Path: seismo!harvard!talcott!panda!sources-request From: sources-request@panda.UUCP Newsgroups: mod.sources Subject: Msg docs preformatted (part 1 of 2) Message-ID: <1526@panda.UUCP> Date: 15 Mar 86 15:12:46 GMT Sender: jpn@panda.UUCP Lines: 1096 Approved: jpn@panda.UUCP Mod.sources: Volume 4, Issue 35 If your site has the "mm" macro package, then you don't need this, the formatted documentation for the Msg mail system. #! /bin/sh # This is a shell archive, meaning: # 1. Remove everything above the #! /bin/sh line. # 2. Save the resulting text in a file. # 3. Execute the file with /bin/sh (not csh) to create the files: # Alias.fmtd # Config.fmtd # This archive created: Sat Mar 15 10:06:15 1986 export PATH; PATH=/bin:$PATH echo shar: extracting "'Alias.fmtd'" '(13394 characters)' if test -f 'Alias.fmtd' then echo shar: will not over-write existing file "'Alias.fmtd'" else cat << \SHAR_EOF > 'Alias.fmtd' A Users Guide to the MSG Alias System (C) Copyright 1986, by Dave Taylor March 15, 1986 This document is intended as a supplement to the Msg Users Guide and is only of interest to those users desiring more knowledge about how aliases work and how to create strange and exciting aliases for their systems (alright, so it's not that exciting!) This document is broken up into the following sections; user aliases, group aliases, system aliases, editing and installing new aliases, the machine routing database, and general warnings and other chitchat. 1. User Aliases The most simple sort of aliases in the Msg system are individual user aliases. These are made up of three parts; : :
Where the alias list is either a single aliasname* or a list of aliasnames separated by commas. Username is currently a comment field, and is used to indicate the full "real name" that the alias is for. For example, if you had an alias for "dat" to get to me, the username field would contain "Dave Taylor" or perhaps "Dave Taylor, HP" or some other permutation of that. In a future release of the mailer, the alias system will know about this field and include it in outgoing messages AND as a supple- ment to the usual list of aliasnames. Address is either the users full electronic mail address or, if the machine routing database is installed, __________ * Please see the appendix for a full definition of what exactly an aliasname consists of. Page 1 the minimum address needed to specify the destination. For example, say our routing database contained information on how to get to machine "hp-sdd" and I wanted to have an address for my friend Ken there - I could have his address specified as simply "ken@hp-sdd" (or alternatively "hp- sdd!ken" since the two are functionally equivalent). Let's get on to some examples, shall we? Consider this excerpt from my own .alias_text file; wunder,walt : Walt Underwood : wunder@hpcea laubach : Mark Laubach : laubach@hpcea mary : Mary Hsia-Coron : hsia@hpindla decot : Dave Decot : decot@hpda jeff : Jeff Wu : hpcnoe!j_wu dave : Dave Barrett : hpcnof!d_barrett Note that the alias for Walt Underwood has two aliasnames associated with it, "wunder" and "walt". Also notice that the first four aliases use the ARPA style naming convention (user@machine) but the last two use the UUCP style conven- tion (machine!user). In this context it is independent. The only time when it does make a difference which notation you use is if you have to specify more than the machine that the user is receiving mail on. That is, say we have a friend who receives mail at a machine called "twinkie" and our best connection is through Georgia Tech...Then our alias for them could be; buddy : Our friend : gatech!twinkie!buddy or buddy2 : Our friend : gatech!buddy@twinkie but not; buddy : Our friend : buddy@twinkie@gatech (however, buddy%twinkie@gatech will also work, but that's far too bizarre a notation to be recommended!!) (besides there's no guarantee that "gatech" will like it, nor the "buddy2" alias above!) Anyway, suffice to say that if you must specify any sort of route that you should use the uucp notation as much as possible to ensure that the Msg system expands the Page 2 correct machine name. 2. Group Aliases After the confusion of user aliases, group aliases are even more fun! For the most part the notation is very simi- lar; : : Where aliasname list and groupname are exactly equivalent to the corresponding fields in user aliases. The interesting part is the list of people field! This field is actually in the same notation as the aliasname list, so it's not quite as strange as I've lead you to believe. It's best to illustrate by example; friends, mypals, gang : The Gang of Six : joe, larry, mary, joanna, nancy, michael (Notice that you can continue onto as many lines as you'd like so long as each additional line start with either a SPACE or a TAB character) The significant limitation with group aliases is that each of the people in the list must be a previously defined aliasname in either the existing alias file or the system alias file or a valid destination on the current machine. What does this mean? This means that the following excerpt from an alias file; hawaii : The Hawaiian Twins : joe@RIT-CS.ARPA, maoa maoa : Maoa Lichtenski Jr : maoa@Hawaii.cs.uh.ARPA will fail for two reasons - not only does the group list of people contain a complex address, but it also contains an aliasname that is defined later in the .alias_text file! ** BEWARE!!! ** The correct way to have the previous alias in the file is to have it like; joe : Joe Lichtenski : joe@RIT-CS maoa : Maoa Lichtenski Jr : maoa@Hawaii hawaii : The Hawaiian Twins : joe, maoa which will then work correctly. Page 3 This isn't too hard now, is it? Fortunately, while this seems pretty tough, if you run the newalias command to install your new aliases, it will give you nice meaningful error messages that will help you fix the list up correctly! 3. System Aliases System aliases are functionally equivalent to the indi- vidual Msg alias lists each Msg user has (both user aliases and group aliases) but are "read only" for everyone but the Msg administrator. The format of the file is identical to the users file, and the only difference is that this file is expected to be located in the directory that contains the "system_hash_file" and "system_data_file" files (see the Msg Configuration Guide for more details on these variables). Simply create a .alias_text file in the specific direc- tory as you would a normal file, and install it the same way (see the following section for more details on that). Voila!! 4. Editing and Installing New Aliases To install new aliases, you need merely to create, or modify, your .alias_text file in your home directory until you're satisfied with it and it meets the requirements stated above. You can then try to install it with the com- mand; $ newalias which will either report back the number of aliases installed into the system or will report errors indicative of the changes that the program expects before it can accept the alias list. Note that blank lines are no problem and that comments are not only allowed but actually encouraged, and must have # as the first character of each comment line. Finally, if you find that you're hitting the "Too many aliases" error, then you'll need to reconfigure the entire Msg system (again, see the Msg Configuration Guide espe- cially the discussion on "MAX_UALIASES" and "MAX_SALIASES" Page 4 therein). 5. The Hostname Routing Database Floating about on the various networks is a rather nifty program by a number of people, including Peter Honey- man and Steve Bellovin, called "pathalias". What this incredibly handy program does is take the strange postings in groups like "mod.map" and massage them into a file of the form;
which is then sorted alphabetically and stored in the file pointed to by "pathfile" (guess where to look for more information!) for Msg to use. If you don't have the program, or don't want to use it, you can simulate this file by listing machines in the same format. The exact format expected is; where hostname is a limited identifier (no special charac- ters) and machine-address MUST contain the sequence "%s" (and consequently any other percent signs that appear in the address must be paired) so that the call in the program "sprintf(buffer, machine-address, username)" will generate a valid return address. By way of example, here are a few entries from my own file; HPL hplabs!%s PARC hplabs!%s@Xerox.PA.COM amc-hq hplabs!%s@AMC-HQ.ARPA imsss hplabs!%s%%IMSSS@SU-AI.ARPA infopro hpfcla!ihnp4!astrovax!infopro!%s interleaf hpfcdc!hpda!sun!interleaf!%s jpl-vax hplabs!%s@jpl-vax As you can see, the addresses can get pretty complicated!! In fact it's due purely to the complication that a database file of this sort can be so wonderful!! If you'd like further information on the pathalias program, try keeping track of the entries in "mod.sources" - it's posted about once a year or so... Page 5 6. Other Stuff not Covered Yet Probably the biggest question you have in your mind right now is "But how the heck does this relate to the 'ole mailx aliases and the snazzo sendmail alias system??" Well, rest assured, sendmail fans, that if you REALLY want to have your aliases down in the transport you can. No problem. All you'll need to do is to turn off the address validation routine in Msg by defining the "NOCHECK_VALIDNAME" defini- tion (I'm not even going to bother to tell you where to look for this one!!). For those mailx fanatics out there, you can translate your aliases into the format that Msg wants by running them through the awk script listed in Appendix Two. Finally, if you have any problems or questions, try looking in the newalias manual entry, or dropping me a line at the "usual" email address (ask your administrator!). Page 6 Appendix One A BNF of the Alias File Grammar In this listing, items in <> brackets are non-terminals, items in {} are optional, and items in bold face are termi- nals. ::= { } ::= | | ::= .. any sequence of characters starting with '#' .. ::= .. an empty line .. ::= | ::= : { : } {}
::= : { : } {} ::= { , } ::= { } ::= .. anything other than ":" ..
::= | | | ::= { , } { } ::= .. any valid mailbox name on the system .. ::= ( @ | ) ::= .. any legal host machine name .. ::= ! ::= ( | ) ::= ! { } Page 7 ::= % { } @ ::= .. any characters other than space, tab, return, or colon .. ::= .. space, tab or newline followed by space or tab .. Page 8 Appendix Two An AWK Script for Translating Aliases from a ".mailrc" Format to a Msg Format ------------------------------------------------------------------- BEGIN { print "# MSG alias_text file, from a .mailrc file..." print "" } next_line == 1 { next_line = 0; group = "" for (i = 1; i <= NF; i++) { if (i == NF && $i == "\\") sep = "" else sep = ", " if ($i == "\\") { group = sprintf("%s,", group) next_line = 1; } else if (length(group) > 0) group = sprintf("%s%s%s", group, sep, $i); else group = $i; } print "\t" group } $1 ~ /[Aa]lias|[Gg]roup/ { if ( NF == 3) print $2 " : user alias : " $3; else { group = "" for (i = 3; i <= NF; i++) { if (i == NF && $i == "\\") sep = "" else sep = ", " if ($i == "\\") { group = sprintf("%s,", group) next_line = 1; } else if (length(group) > 0) Page 9 group = sprintf("%s%s%s", group, sep, $i); else group = $i; } print $2 " : group alias : " group; } } ------------------------------------------------------------------- Note: this script is contained in the release under the name "mailrc.awk" in the utilities directory "utils". Page 10 SHAR_EOF if test 13394 -ne "`wc -c < 'Alias.fmtd'`" then echo shar: error transmitting "'Alias.fmtd'" '(should have been 13394 characters)' fi fi echo shar: extracting "'Config.fmtd'" '(11466 characters)' if test -f 'Config.fmtd' then echo shar: will not over-write existing file "'Config.fmtd'" else cat << \SHAR_EOF > 'Config.fmtd' Configuration Guide to the MSG Mail System (C) Copyright 1986, by Dave Taylor February 28, 1986 This document is intended as a supplement to the Msg Users Guide and is only of interest to sites having the source code to the msg system. Virtually all of the installation dependent definitions are contained in the file 'hdrs/sysdefs.h', as detailed below; ------------------------------------------------------------- #define USE_EMBEDDED_ADDRESSES #define FIND_DELTA 10 /* for binary searches in path database */ #define MAX_HEADERS 500 /* max number of messages in one file! */ #define MAX_SALIASES 503 /* number of system aliases allowed */ #define MAX_UALIASES 251 /* number of user aliases allowed */ #define MAX_IN_WEEDLIST 50 /* max headers to weed out */ #define MAX_HOPS 35 /* max hops in return addr to E)veryone */ #define MAX_ATTEMPTS 6 /* #times to attempt lock file creation */ #define REMOVE_AT_LAST /* see leavembox.c */ #define DEFAULT_BATCH_SUBJECT "no subject (file transmission)" #define NOCHECK_VALIDNAME /* see validname.c */ #define NOTES_HEADER "/***** " #define NOTES_FOOTER "/* ---------- */" #ifdef BSD # define system_hash_file "/usr/spool/mail/.alias_hash" # define system_data_file "/usr/spool/mail/.alias_data" #else # define system_hash_file "/usr/mail/.alias_hash" # define system_data_file "/usr/mail/.alias_data" #endif Page 1 #define pathfile "/usr/lib/nmail.paths" #define Lsys "/usr/lib/uucp/L.sys" #define DEBUG "Msg.debug.info" #define temp_file "/tmp/snd." #define temp_mbox "/tmp/mbox." #define temp_print "/tmp/print." #define mailtime_file ".last_read_mail" #ifdef BSD # define default_editor "/usr/ucb/vi" # define mailhome "/usr/spool/mail/" #else # define default_editor "/usr/bin/vi" # define mailhome "/usr/mail/" #endif #define sendmail "/usr/lib/sendmail" #define sendmailflags "-oi" #define mailer "/bin/rmail" #define mailx "/usr/bin/mailx" #define helphome "/usr/local/lib/" #define helpfile "main.help" #define msgrcfile "/.msgrc" #define mailheaders ".msgheaders" #define unedited_mail "emergency.mbox" #define newalias "newalias 1>&2 > /dev/null" #define remove "/bin/rm -f" /* how to remove a file */ #define cat "/bin/cat" /* how to display files */ ------------------------------------------------------------- USE_EMBEDDED_ADDRESSES This controls the mailers response to messages that contain "Reply-To:" or "From:" lines that actually contain a return address. If it's defined, the mailer will attempt to use the address specified (overriding the return address built from the path that the mail took). It will look the address up in the pathalias database (see the documentation on the alias system) for incomplete paths, but it is still recommended that this be left undefined. Page 2 This will, of course, make the mailer not be a standard 'RFC-822' mailer, since the mail system is defined to use the reply-to if included rather than the return address, but, at least for addresses on the ARPA net, it ain't going to work a lot of the time! FIND_DELTA This is the delta that the binary search of the pathalias database will use to determine when it's slicing up a single line, rather than a multitude of lines. Ideally, this should be set to 1 byte less than the shor- test line in the file...the default is 10 bytes. MAX_HEADERS The maximum number of messages allowed in a single mailbox. MAX_SALIASES The number of system aliases allowed. (It is recommended that this be a prime number to improve the performance of the hashing func- tion (it's a complicated proof!)) MAX_UALIASES The number of user aliases allowed. (should be a prime number - see the comment above) MAX_IN_WEEDLIST The maximum number of headers that can be specified in the weedout list of the .msgrc file. A suggested alternative approach if this number is too small is to specify ini- tial substrings in the file rather than increasing the number. For example, say you want to weedout the headers "Latitude:" and "Latitudinal-Coords:", you could simply specify "Latitud" and match them both! Furthermore you could also specify headers like "X-" and remove all the user defined headers! MAX_HOPS When replying to a G)roup, this is the max- imum number of hops that a message can have taken. This is used to try to optimize the return address (remove cyclic loops and so on) and regular use should show that the default of 35 is plenty more than you'll ever need! MAX_ATTEMPTS When reading in the default mailbox (/usr/mail/$username) the mailer creates a file called "/usr/mail/$username.lock" to ensure that no mail is added to the file Page 3 while it's being either read, or replaced (ie written to). Occasionally, this lock file will already be in place since someone is currently sending you mail. If this occurs, the mailer will wait a few seconds and try to create the lock file again. This parameter defines the number of tries the mailer should take before giving up. REMOVE_AT_LAST When it does decide to give up after trying to create the lock file, (see MAX_ATTEMPTS, above) this will define how to act. If it's defined, the mailer will attempt to remove the lock file after the MAX_ATTEMPTS timeout. On the other hand, if it's not defined (the recommended state) it'll simply quit the mailer, telling the user to try again in a few minutes. DEFAULT_BATCH_SUBJECT What the subject should be on messages that are from redirected input but don't have a subject specified... NOCHECK_VALIDNAME This disables the checking of validnames on the existing machine. On machines that run a system such as sendmail and use the sendmail alias feature, this should be defined. On other systems this should be left as the default (not defined) to avoid users generating "dead.letter" files... NOTES_HEADER This defines the first "word" of the line that a notes file entry would contain. NOTES_FOOTER This defines the footer line (in it's entirety). system_hash_file This is the file that contains the hashed version of the system aliases. It is also used in the newalias command. (note that it is defined differently if you're running on a Berkeley system) system_data_file This is the other file the newalias command installs in the system alias area. (Note this is defined differently if you're runnnig a bsd system) pathfile This defines the location of the alias datafile. This file is in the format that pathalias generates, that is; Page 4 machine address For further information, please see the Msg Alias System documentation. Lsys This defines where the system L.sys file is kept. This is used for the mailer to quickly know what machines the current machine can talk to directly (to avoid trying to search the pathalias database to route mail to these machines). DEBUG The name of the file to put in the users home directory if they choose to use the "-d" debug option. temp_file Temporary file for sending outbound messages. Place to keep copy of incoming mailbox to avoid collisions with newer mail. temp_print File to use when creating a printout of a message. mailtime_file File to compare date to to determine if a given message is New since the last time the mail was read or not. default_editor If no editor is specified in the users .msgrc file, this is which editor to use. ENSURE IT IS A VALID EDITOR ON THIS MACHINE!! (Not that the default home for "vi" is different on BSD machines) mailhome Where all the incoming mailboxes are, and also where the 'lock' files have to be put for the mailer to know not to add new mail while we're reading/writing the mailfile. (note that mail is kept in a different direc- tory on Berkeley systems) sendmail Defines where sendmail is (if you have it on your system). sendmailflags Defines the flags to hand to sendmail if and when the program chooses to use it. mailer If you don't have sendmail, this is the mailer that'll be used. Page 5 mailx If all else fails, this mailer can be used in a rather dumb way. helphome Where the help file is kept (soon to be help files!) helpfile The name of the main helpfile (kept in "hel- phome"). msgrcfile The name of the automatic control file (currently ".msgrc") mailheaders The name of the optional file that users may have that will be included in the headers of each outbound message. unedited_mail In the strange case when the mailer suddenly finds all the directories it uses shut off (like /usr/mail and /tmp) then it'll put the current mailbox into this file in the users home directory. newalias How to install new aliases.. remove How to remove a file. cat How to display a file to stdout. Page 6 SHAR_EOF if test 11466 -ne "`wc -c < 'Config.fmtd'`" then echo shar: error transmitting "'Config.fmtd'" '(should have been 11466 characters)' fi fi exit 0 # End of shell archive