.\" @(#)$Id: Alias.guide,v 4.1 90/04/28 22:40:58 syd Exp $
.\"
.\"  A guide to the ELM alias system and so on.
.\"  format with:
.\"      tbl Alias.guide | troff -mn > Alias.format'
.\"
.\"  (C) Copyright 1986, 1987 Dave Taylor
.\"  (C) Copyright 1988, 1989, 1990 USENET Community Trust
.\"  Elm is now in the public trust. Bug reports, comments, suggestions, flames
.\"  etc. should go to:
.\"	Syd Weinstein		elm@DSI.COM (dsinc!elm)
.\"
.\"  $Log:	Alias.guide,v $
.\" Revision 4.1  90/04/28  22:40:58  syd
.\" checkin of Elm 2.3 as of Release PL0
.\" 
.\"  
.tm Have we been run through "tbl" first?? I hope so!
.po 1i
.ds h0
.ds h1
.ds h2
.ds f0
.ds f1
.ds f2
.nr Hy 1
.nr Pt 1
.nr Pi 0
.lg 0
.nf
.na
.rs
.za
.sp |3.0i
.ce 99
.ps 20
.ss 18
.vs 12
\f3The Elm Alias System Users Guide\f1
.sp 4
.ps 12
.ss 14
.vs 14
\f2What aliases are and how to use them
in the \f3Elm\fP mail system\f1
.sp 2
Dave Taylor
.sp 
Hewlett-Packard Laboratories
1501 Page Mill Road
Palo Alto CA
94304
.sp 3
email:  taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
.sp 3
>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
.sp
Syd Weinstein
Datacomp Systems, Inc.
3837 Byron Road
Huntingdon Valley, PA 19006-2320
.sp
email: elm\s-1@\s+1DSI.COM  or  dsinc\s-1!\s+1elm
.sp 2
\s18\f3\(co\f1\s12 Copyright 1986, 1987 by Dave Taylor
\s18\f3\(co\f1\s12 Copyright 1988, 1989, 1990 by The USENET Community Trust
.ps 10
.ss 12
.vs 12
.fi
.ad
.bp 1
.sv 5v
.ps 14
.ss 12
.vs 16
\f3The Elm Alias System Users Guide\f1
.ds h0 "Alias Users Guide
.ds h1
.ds h2 "Version 2.3
.ds f0 "May 1, 1990
.ds f1
.ds f2 "Page %
.sp
.ps 10
.ss 12
.vs 12
(Version 2.3)
.sp 2
Dave Taylor
.sp
Hewlett-Packard Laboratories
1501 Page Mill Road
Palo Alto CA
94304
.sp 
email: taylor\s-1@\s+1hplabs.HP.COM  or  hplabs\s-1!\s+1taylor
.sp 2
>>> Elm is now in the public trust. Bug reports, comments, etc. to: <<<
.sp
Syd Weinstein
Datacomp Systems, Inc.
3837 Byron Road
Huntingdon Valley, PA 19006-2320
.sp
email: elm\s-1@\s+1DSI.COM  or  dsinc\s-1!\s+1elm
.sp 2
May 1, 1990
.ce 0
.sp 3
.pg
This document is intended as a supplement to the \f2Elm Users Guide\f1
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 (okay, so maybe it's not \f2that\f1 exciting!)
.sp
.pg
This document is broken up into the following sections;
user aliases,
group aliases,
system aliases,
editing and installing new aliases,
the host routing database,
the domain routing database,
general warnings and other chitchat.
.sp
.hn 1 User Aliases

The most simple type of aliases in the \f3Elm\f1 system are individual
user aliases.  These are made up of three parts;
.nf
	\f2aliasname list\f1  =  \f2username\f1  =  \f2address\f1 \s-2\u1\d\s0
.fn
1. Notice that the alias separator has moved from being a colon 
character (`:') to the equals sign (`=').
This is due to the requirements of the X.400 addressing scheme.
.ef
.fi
Where the \f2aliasname list\f1 is either a single aliasname\s-2\u2\d\s0
.fn
2. aliasnames can be any combination of letters, numbers, dashes (`-'),
periods (`.'), or underscores (`_').  Letter case is not significant.
That is `FRED' and `Fred' are identical.
.ef
or a list of aliasnames separated by commas.  Aliasnames are case insensitive and will be
converted to all lower case by the alias system.
.pg
\f2Username\f1 is used to indicate the full `real name' of the user.  
For example, if you had an alias for `taylor' to get to me, the 
\f2username\f1 field would contain `Dave Taylor' or 
perhaps `Dave Taylor at HP'
or some other permutation.  \f3Elm\f1
uses this information to add the users full name to the addresses of 
outbound mail to get more readable addresses.  
.pg
\f2Address\f1 is either the users full electronic mail address or, if
the machine routing database is installed, 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 \(em I could have his address
specified as simply `ken@hp-sdd' (or alternatively `hp-sdd!ken' since
the two are functionally equivalent).
.sp
.pg 0
Let's get on to some examples, shall we?
.sp
Consider this excerpt from my own \f2.elm/aliases.text\f1 file;

.nf
.ft CW
.zf
.in .5i
.ta \w'frank,minjarez 'u \w'frank,minjarez = Frank Minjarez 'u
# Mail aliases for Dave Taylor
# Friends from UCSD
addie	= Addie Silva	= addie@hp-sdd.SDD.HP.COM
frank,minjarez	= Frank Minjarez	= Minjarez.Verify@dockmaster.arpa
pizzini	= Ken Pizzini	= hplabs!ucbvax!ucdavis!pai!ken
.ft 1

.in 0
.fi
Note that the alias for Frank Minjarez has two \f2aliasnames\f1 associated
with it,
.ft CW
.zf
frank\f1 and
.ft CW
.zf
minjarez\f1.
Also notice that the first and second aliases
use the ARPA Internet style naming convention of \f2user@machine\f1 
whereas the third uses the UUCP notation of \f2machine!user\f1.
.pg
For the most part, the notational format is transparent within the
alias file \(em the only time it \f2does\f1 make a difference 
is if you have to specify more than the machine that the user is
receiving mail on (as in the third example above).  
.pg
Suffice to say that if you must specify any sort of uucp route
that you should use the uucp notation as much as possible to ensure
that the system expands the correct machine name.  Similarly, if
you're bouncing mail through different ARPA Internet sites (to
get to a foreign system, as in the example below) you should use the
notation that system expects:

.ft CW
.zf
.ti .5i
	listserv%byuadmin.BITNET@rugters.edu
.ft 1
.sp
.hn 1 Group Aliases

After the confusion of user aliases, group aliases are even more 
fun!  For the most part the notation is very similar;

	\f2aliasname list\f1   =   \f2groupname\f1   =   \f2list of people\f1

Where \f2aliasname list\f1 and \f2groupname\f1 are exactly equivalent
to the corresponding fields in user aliases.
.pg
The interesting part is the \f2list of people\f1 field; this
field is actually in the same notation as the aliasname list,
so it's really quite easy to create.
It's best to illustrate by example:

.ft CW
.zf
.nf
.in .5i
friends, mypals = The Gang of Six = joe, larry, mary, joanna,
\h'\w'friends, mypals = The Gang of Six = 'u'nancy, michael
.ft 1

.in 0
.fi
(Notice that you can continue onto as many lines as you'd like so
long as each additional line start with either a \s8SPACE\s10 or a \s8TAB\s10
character)
.pg
The major limitation with group aliases is that each of the
people in the list must be a \f2previously defined alias\f1
or a valid mail address on the current machine.
.pg
What does this mean?  That the following excerpt from an alias file:

.in .5i
.ft CW
.zf
.nf
.ta \w'hawaii 'u \w'hawaii = The Hawaiian Twins 'u
hawaii	= The Hawaiian Twins	= joe@cs.rit.edu, maoa
maoa	= Maoa Lichtenski Jr	= maoa@Hawaii.cs.uh.edu
.ft 1

.in 0
.fi
will fail for two reasons \(em not only does the group \f2list of people\f1
contain a complex address, but it also contains an aliasname that is 
defined \f2further on\f1 in
the \f2.elm/aliases.text\f1 file.
.pg
The correct way to have the previous aliases in the file are to have them 
organized like:

.ft CW
.zf
.in .5i
.ta \w'hawaii 'u \w'hawaii = The Hawaiian Twins 'u
.nf
joe	= Joe Lichtenski	= joe@cs.rit.edu
maoa	= Maoa Lichtenski Jr	= maoa@Hawaii.cs.uh.edu
hawaii	= The Hawaiian Twins	= joe, maoa
.ft 1

.in 0
.fi
which will then work correctly.
.sp
Fortunately, while this seems fairly picky, when you run \f2newalias\f1
to install the new aliases, you'll get relevant and meaningful
error messages to help you fix your aliases up correctly.
.sp
.hn 1 System Aliases

System aliases are functionally equivalent to the individual \f3Elm\f1 
alias lists each \f3Elm\f1 user has (both user aliases and group aliases) 
but are \f2read only\f1 for everyone but the \f3Elm\f1 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 \f2system_hash_file\f1 and \f2system_data_file\f1 files (see the
\f2Elm Configuration Guide\f1 for more details on these variables).
.pg
Simply create the system alias file in the specified directory
as you would a normal alias file, and install it the same way (see the
following section for more details on that).  
.pg
Voila!!
.sp
.hn 1 Editing and Installing New Aliases

To install new aliases, you need merely to create, or modify,
the file \f2.elm/aliases.text\f1 until you're
satisfied with it and it meets the requirements discussed above.
You can then try to install it with the command;

	$ \f3newalias\f1

which will either report back the number of aliases installed 
or any errors encountered trying to parse and store the
given alias list.
.pg
Note that blank lines are no problem and that comments are not only
allowed but actually encouraged, and must have `\f3#\f1' as the first
character of each comment line.
.sp
Finally, if you find that you're hitting the ``Too many aliases'' error, 
then you'll need to reconfigure the entire \f3Elm\f1 system (again,
see \f2The Elm Configuration Guide\f1).
.sp
.hn 1 The Hostname Routing Database

Floating about on the various networks is a rather nifty program by
a number of people, including Peter Honeyman and Steve Bellovin, 
called \f2pathalias\f1.  What this software does is 
take the Usenet articles in the group ``comp.mail.maps'' and change
them into a file of the form;

	\f2hostname\f1    <tab>    \f2address\f1

which then must be sorted alphabetically and stored in the file
pointed to by \f2pathfile\f1 for \f3Elm\f1 (and other 
programs) to use.
.pg
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;

	\f2hostname\f1<tab>\f2machine-address\f1

where \f2hostname\f1 is a limited identifier (no special characters) 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.  This file must be sorted alphabetically
for Elm to use it properly.
.pg
By way of example, here are a few entries from my own file;

.ft CW
.zf
.in .5i
.TS
l l.
HPL	%s@hplabs
PARC	%s%%Xerox.PA.COM@hplabs
amc-hq	%s%%AMC-HQ.ARPA@hplabs
imsss	%s%%IMSSS%%AI.STANFORD.EDU@hplabs
infopro	hplabs!infopro!%s
interleaf	sun!interleaf!%s
.TE
.ft 1

.in 0
As you can see, the addresses can get pretty complicated.  In fact
it's due purely to the complexity of addresses that this file 
is so useful.
.sp
.ne 5
Some brief examples:

.in .5i
.ft CW
.zf
.nf
$ \f3elm joe@HPL\f1
.ft CW
.zf
To: joe@hplabs
$ \f3elm michelle@imsss\f1
.ft CW
.zf
To: michelle%IMSSS%AI.STANFORD.EDU@hplabs
$ \f3elm fiedler@infopro\f1
.ft CW
.zf
To: hplabs!infopro!fiedler
.ft 1
.fi

.in 0
If you'd like further information on the \f2pathalias\f1 program, try
keeping track of the entries in the netnews group \f2comp.sources.unix\f1 \(em
it's posted about once a year or so...
.sp
.hn 1 The Domain Routing Database

Another interesting feature of the 
\f3Elm\f1 system is the shorthand domain routing database.  
This is the same database (in the same strange format) as used by
the publically available \f2uumail\f1 program.
.pg
In a nutshell, the file contains information of the form;

.in .5i
\f2domain,   path-to-gateway,  rewrite-template\f1
.in 0

The \f2domain\f1 field must begin with a leading `.' and
is usually ordered in the same way as the standard
domain entries (that is, ``\s8.HP.COM\s10'' not ``\s8.COM.HP\s10'').
.pg
\f2Path-to-gateway\f1 is routing information on how to get
to the particular gateway that this domain expects, and
always is a machine/host name (to be found in the pathalias
database, see the previous section) preceded by a `>' 
character.
.pg
\f2Rewrite-template\f1 is the most interesting of the
three, and is akin to a printf string for C.  The 
changes are that instead of `%s' `%d' and so on, the
actual ``percent'' values represent various parts of 
the address, namely;

.in .5i
.TS
c l.
\f3Symbol	Represents\f1
%U	The username in the To: address
%N	The remote machine name
%D	%N + domain information 
%R	path to %N from pathalias
%P	\f2path-to-gateway\f1 entry
%%	The `%' character
.TE
.in 0

with this very un-intuitive setup, let's look at a few entries 
from the domains database and then see how they work:

.nf
.ft CW
.zf
.in .5i
\&.EUR.UUCP, , , %R!%U
\&.ATT.COM, >att, , %P!%D!%U
\&.HP.COM, , , %R!%U
\&.UUCP, , , %R!%U
\&.COM, >hplabs, , %P!%U@%D
\&.CSNET, >hplabs, , %P!18:12:00%%D@CSNET-RELAY.ARPA
\&.EDU, >hplabs, , %P!%U@%D
.ft 1
.fi
.in 0

(Note the presence of a third field that is always null.
This is for compatibility with the \f2uumail\f1 program.
Also notice that there is a space after each and every comma,
even if that field has an entry.)
.pg
To see how it all works, let's suppose that we want to send a message
to `jad@cs.purdue.edu'.  This would break down into the following fields:

.nf
.in .5i
%U = \f2jad\f1
%N = \f2cs\f1
%D = \f2cs.purdue.edu\f1
.in 0
	  
.fi
When the \f3Elm\f1 program matches the \f2.edu\f1  entry

.nf
.in .5i
.ft CW
.zf
\&.EDU, >hplabs, , %P!%U@%D
.ft 1
.in 0

.fi
the other field instantiated would be:

.nf
.in .5i
%P = \f2path to hplabs\f1
template = \f2%P!%U@%D\f1
.in 0
.fi

If, say, our path to \f2hplabs\f1 was \f2hpcnoe!hplabs\f1, then
the fully expanded address would be:

.nf
.ft CW
.zf
.in .5i
hpcnoe!hplabs!jad@cs.purdue.edu
.ft 1
.in 0
.fi

\f1and so on.  
.sp
What does this mean to the average user?  It means that you can
for the most part send mail to people on different networks by
simply using their full address, including any domain information, 
so that mail to addresses like ``Jack@AI.MIT.EDU'' will work, 
a message to ``SueAnn@BBN.MAILNET'' will work and so on!
.sp
.hn 1 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 my existing \f2Berkeley Mail\f1
aliases and the lower-level \f2sendmail\f1 alias system??''  Well,
rest assured that if you \f2really\f1 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 \f3Elm\f1.
.pg
And for those ex-\f2Berkeley Mail\f1 fans, you can translate your 
aliases into the format that \f3Elm\f1 wants by running them
through the \f2awk\f1 script listed in the appendix.
.pg
Finally, if you have any problems or questions, try looking in 
the \f2newalias\f1 manual entry, or dropping me a line at the
``usual'' email address.
.bp
.ce 99
\f3Appendix One
An AWK Script for Translating Aliases from 
a \f2Berkeley Mail\fP ``.mailrc'' File to an \f2Elm\fP ``.elm/aliases.text'' 
File\f1
.ce 0
.sp 
.nf

.ta .5i
.ft CW
.zf
BEGIN { print "# Elm .elm/aliases.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) 
	      group = sprintf("%s%s%s", group, sep, $i);
	    else
	      group = $i;
	    }
	    print $2 " = group alias = " group;
	  }
	}

.ft 1
.fi
Note: this script is contained in the release under the name ``mailrc.awk''
in the utilities directory ``utils''.
