 THE CARE AND FEEDING OF DBM DATABASES FOR THE IDA PACKAGE.

 The power of the IDA package derives mainly from its use of DBM databases 
which can be looked up during the processing of mail.

 The DBM databases are set up to map a KEY into a VALUE.  In our descriptions 
below we shall always presume that the source for building the database is 
organized in the format:

VALUE    KEY [KEY] ...

This is usually the most convenient format.  However the output of the 
pathalias program has a different format.  Notice that sendmail always 
converts the key to lower case before doing a database lookup.

 The dbm command is sufficiently versatile to be able to handle either of 
these source formats. 

 We start with an overview of the various tables.

=============================================================================

 MAILERTABLE:  This is probably the first table you will wish to define.  By 
    default, mail directed to one of the PSEUDONYMs is processed by the 
    LOCAL mailer, mail addressed to 'user@host.UUCP' is sent out by the UUCP 
    mailer (but only if 'host' is a UUCP neighbor), mail to 
    'user@full.domain.name' is sent out with the TCP mailer.  There is no 
    default provision for handling mail to .BITNET hosts, to UUCP hosts which 
    are not neighbors, etc.

    The MAILERTABLE allows this default processing to be changed for specific 
    domains or classes of domains.

    The KEY in each entry is a domain name, or a partial domain name 
    (beginning with a dot).  The VALUE is a MAILER/DOMAIN pair, in any of the 
    formats 'MAILER,domain'  or 'MAILER:domain' or 'MAILER!domain'.  The 
    choice of the separator (',' or ':' or '!') affects how the name address 
    is processed after mailer selection.

    Example 1.  I have a UUCP neighbor 'denali'.  But this host is also on 
    the network, and has in Internet mail name of 'math.niu.edu'.  Since it 
    is more efficient to use the network, I can insert the entry:

TCP,math.niu.edu        denali.UUCP

    in my MAILERTABLE.  That way mail addressed via UUCP can actually be 
    delivered via TCP.

    MAILERTABLE can also be used to deliver BITNET mail.  I can install the 
    entry

TCP,UICVM.UIC.EDU       .BITNET

    in the table.  Then any mail which matches the .BITNET - that is, any 
    mail to a 'host.BITNET' destination is forwarded to the nearby BITNET 
    gateway, UICVM.UIC.EDU.

    uunet.uu.net is an Internet host.  Thus by default mail to there is 
    processed by the TCP mailer.  But with the entry

TCP-U,uunet.uu.net      uunet.uu.net

    mail will be transmitted with the TCP-U mailer.  This is still a TCP 
    mailer, but it is designed to provide UUCP format addresses.  This may
    be appropriate for uunet which is a major UUCP forwarder.  However
    uunet.uu.net is a well run host, and can recognize a variety of
    formats, so the regular TCP mailer is also a good choice.

    The various mailers which can be selected by MAILERTABLE entries include 
    the TCP mailer, the UUCP mailer, the TCP-U mailer just mentioned, the 
    TCP-A mailer which uses strict RFC822 source routes, the UUCP-A mailer 
    which uses UUCP transport but formats addresses in Internet style.  The 
    local mailer could also be selected.

    In selecting a mailer, the mailer pair may be separated by any of ',' or 
    ':' or '!'.  There significance is in the way the address is modified.  
    If ',' is used, the recipient address is sent to the mailer unchanged.  
    If a '!' is used, the recipient host is first removed from the recipient 
    address before forwarding via the mailer.  The '!' is appropriate for the 
    UUCP and LOCAL mailers which expect the recipient host to have been 
    removed.  The use of ':' is somewhere between these two.  The recipient 
    host is removed, but only if there are additional hosts in a mailing 
    path.

    It is also possible to specify the MAILER-domain pair as just a ':'.  
    This has the special meaning of forcing mailer selection to fail.  Such 
    entries are useful in conjunction with PATHTABLE, discussed next.

 *********** IMPORTANT NOTE ****************

    It is important that host names in the MAILER:HOST pair be the OFFICIAL
    host name.  Thus,

TCP,math.niu.edu	denali.UUCP

    is correct.

TCP,math		denali.UUCP

    is incorrect, even if 'niu.edu' is my local domain.  Likewise, when I
    use the UUCP-A mailer to send Internet format mail via UUCP to our
    Geology department, the record

UUCP-A!earth		geol.niu.edu

    is correct.  However

UUCP-A!earth.UUCP	geol.niu.edu

    would be incorrect.  This is because 'earth' is the official name of this
    UUCP host, whereas 'earth.UUCP' is not the host name, but an internet-like
    mailname sometimes used for the host.

    NOTES ON ADVANCED FEATURES OF MAILERTABLE.

    When you use a MAILERTABLE entry with a key beginning with '.', the
    mailer/host pair can contain a '%s'.  The %s is replaced by that part
    of the matching host name which precedes the key.  Thus an entry

Dmail,%s	.dnet

    would result in mail to  XYZZY.dnet being sent by the Dmail (Decnet)
    mailer to decnet node XYZZY, which is the string to replace the %s.
    Likewise you might use an entry like:

ACSNET,%s.oz	.oz

    to route all mail to *.oz hosts via the ACSNET mailer, while retaining
    the full original domain name for the receiving host.

    SELECTING THE ERROR MAILER.

    If the mailer/host pair in a MAILERTABLE entry does not contain any
    of the tokens ':' or ',' or '!', the ERROR mailer will be invoked.
    This could be used for handling special error situations.  For example
    I could use the entry:

"ANNEX1: Terminal server does not handle mail"		annex1.niu.edu

    Note that since the message is quoted, it is parsed as a single token,
    so the ':' will not be recognized.  Mail to 'user@annex1.niu.edu' will
    resolve to the error mailer as:
	$#ERROR $:"ANNEX1: Terminal server does not handle mail"
    (Of course this only affects mail for annex1 passing through this host,
    since it would be silly to have an MX record where mail is not accepted.)

    Or you might create a mailertable entry:

"User mail privileges suspended"	mailsuspend

    and then in your aliases file you might have an alias

smith: "smith doesn't read mail.  His mailbox overfloweth"@mailsuspend

    to deal with a user whose mail habits are causing you headaches.

=============================================================================

 PATHTABLE

    This table is useful for rerouting mail.  Usually it is constructed from 
    the UUCP map, using the pathalias command.

    The PATHTABLE is searched when the first attempt at selecting a mailer 
    has failed.  Thus I can have an entry:
 VALUE                          KEY
seismo!%s@uunet.uu.net          seismo

    Suppose then that I have mail for 'user@seismo.UUCP'.  Since 'seismo' is 
    not a UUCP neighbor, the first attempt at finding a mailer fails.  Then a 
    PATHTABLE lookup is performed.  The domain name 'seismo' is used to 
    lookup the table, and 'user' is sprintf-ed through the value, to yield an 
    address 'seismo!user@uunet.uu.net'.  Note that 'user' could actually be a 
    long bang path in this.  Note also that UUCP addresses are special for 
    PATHTABLE, in that the '.UUCP' is not part of the key.  The special 
    treatment derives from the history of the pathalias command for preparing 
    UUCP maps.  

    However the PATHTABLE is not restricted to UUCP mail.  I could use an 
    entry

%s@UICVM.UIC.EDU        .BITNET

    as an alternate way of routing BITNET mail via UICVM.  Since the key 
    begins with a '.', the original domain is not removed.  Thus 
    'user@host.BITNET' is converted into something like 
    'user@host.BITNET@UICVM.UIC.EDU' except that the internal reformatting 
    associated with PATHTABLE lookups will convert this to the RFC822 source 
    route '@UICVM.UIC.EDU:user@host.BITNET'. 

 *********** IMPORTANT NOTE ****************

    It is essential that PATHTABLE entries, other than simple UUCP node names,
    use the fully qualified names, since - except for the addition of '.UUCP'
    to uucp hosts, the addresses coming from PATHTABLE are not subject to
    later qualification.

    For entries generated from the UUCP maps with the pathalias command, this
    will not be a problem, for they are already in the correct format.  But
    if you manually add extra entries you must see that they too (except for
    simple UUCP names) are fully qualified.

  VALUE			KEY
uunet.uu.net!seismo%s	seismo

	or

seismo%s@uunet.uu.net	seismo

    is alright, because uunet.uu.net is fully qualified.

uxc!uunet%s		uunet.uu.net

    is alright, since uxc is a simple UUCP name.  But if I want to use
    TCP to send mail to my UUCP neighbor 'denali', I must use

%s@math.niu.edu		denali

	not

%s@math			denali

    since 'math' is not fully qualified.

    FORCING PATHTABLE LOOKUPS.

    If you use a MAILERTABLE, you can force a PATHTABLE lookup for a
    particular host with the MAILERTABLE entry:

:	host.name

    This is mostly useful for dealing with special routing problems.  If
    for example, our VM system had a problem with its ethernet card, I
    could use the mailertable entry

:	VM.CSO.NIU.EDU

    to force a PATHTABLE lookup, and then I could use the pathtable entry:

%s@NIUCS.BITNET		VM.CSO.NIU.EDU

    to temporarily reroute its mail via a BITNET link.

=============================================================================

 DOMAINTABLE

    This table is used to fully qualify domain names.  

    The domain qualification process uses both the name server and the domain 
    table.  Thus if I send mail to 'person@niucs1' the name server lookup 
    first attempts to append my default domain (from /etc/resolv.conf) of 
    'niu.edu' forming the domain 'niucs1.niu.edu'.  Since there is a CNAME 
    record in the domain database mapping this to the canonical name of 
    'mp.cs.niu.edu', that becomes the fully qualified domain name used.  
    Similarly, if I try sending mail to 'person@math' the domain is 
    tentatively qualified with 'niu.edu', and since 'math.niu.edu' is a valid 
    name known to the name server this becomes the fully qualified name.

    If, however, I send mail to 'person@chem' this procedure fails.  The name 
    'chem.niu.edu' does have records in the domain database.  But the records 
    are only MX records, and the lowest preference is to this host.  Since 
    MX records of preference >= that of the local host must be discarded, it 
    looks to the name server lookup as if 'chem.niu.edu' is an invalid name.  
    This the name is not properly qualified.

    The solution is a DOMAINTABLE entry

chem.niu.edu       chem

    This entry maps the key 'chem' into its fully qualified version, so that 
    the correct fully qualified name is still found.  Actually I prefer to 
    use a table entry of

chem.niu.edu       chem  chem.niu.edu

    Here the key 'chem.niu.edu' is useful if sendmail wants to be sure that 
    'chem.niu.edu' is a valid fully qualified name.  As mentioned above, the 
    name server lookup will not validate the domain, so a DOMAINTABLE lookup 
    must be used.

    Mail coming into my machine from the 'chem.niu.edu' machine arrives via 
    UUCP.  In fact 'chem.niu.edu' has a UUCP name of 'socrates'.  The sender 
    address on this mail will be in the form 'socrate!person'.  Because I 
    used BANGIMPLIESUUCP in my setup, the domain is converted to 
    'socrate.UUCP'.  I use the DOMAINTABLE entries:

chem.niu.edu       socrate.UUCP socrates.UUCP socrate socrates

    Thus the address 'socrate.UUCP' is automatically converted to its 
    Internet equivalent of 'chem.niu.edu' before it leaves sendmail.
    Note that I include both 'socrate.UUCP' and 'socrates.UUCP' as keys.  The 
    actual machine name is 'socrates' but much UUCP software truncates names 
    to 7 characters.  For safety I use both versions.  I also include 
    'socrate' and 'socrates' without the '.UUCP' so that if I ever stop using 
    BANGIMPLIESUUCP correct qualification will still occur.

    As a general rule, you should only have entries in DOMAINTABLE for direct 
    UUCP connections, and for local machines (machines within your domain).  
    There may be special local circumstances which would cause you to add a 
    few additional entries.  You do not need to qualify every domain in the 
    world. 

=============================================================================

 UUCPXTABLE

    This table is used to convert full domain names into UUCP names.  For 
    example I use an entry

socrates      chem.niu.edu

    This is used to convert the name 'chem.niu.edu' into the corresponding 
    UUCP name of 'socrates'.  The idea is that the host should always be 
    known as 'chem.niu.edu' when Internet format addresses are preferred, 
    such as with the TCP mailer.  But when UUCP format addresses are 
    preferred, as with the UUCP mailer, it is better to use the UUCP name.

    As a general guide, whenever there is a DOMAINTABLE entry to convert your 
    UUCP neighbor's name into a full domain name, there should be a 
    corresponding UUCPXTABLE entry so that the UUCP name is still used with 
    the UUCP mailer. 

=============================================================================

 DECNETXTABLE

    This is used for DECNET mail.  Its use is somewhat analogous to the use 
    of UUCPXTABLE for UUCP mail.  See Sendmail.mc for more information.

=============================================================================

 GENERICFROM

    This table only effects addresses on the 'From:' header line.  If, for 
    example, I had an entry:

Neil-Rickert@cs.niu.edu      rickert

    then mail sent out by 'rickert' would have its 'From:' line read as 
    'From: Neil-Rickert@cs.niu.edu'.

    Note that the program 'xalparse' allows a single source file 'xaliases' to 
    be used to build both the ALIASES and the GENERICFROM databases.

=============================================================================

 NOTES ON MX-GATEWAYING.

 A number of hosts do not have direct Internet connections, but use Internet
style addresses, and have mail reach them with the aid of an MX domain
record and a forwarding gateway machine.  These notes give some approaches to
using this setup.

 If you are not Internet connected, but use UUCP to forward mail to an MX
gatewaying machine, try using UUCP-A as the RELAY_MAILER.  Beyond setting
up the relaying mailer and host there is little for you to do, for most of
the setup must be handled on the gateway machine.

 The rest of these notes apply to the gateway machine.

 There are two problems to consider.  We must forward received mail to the
machine for which we gateway.  And we must send mail from that machine onto
the network.  We consider the problems separately.

 Handling incoming mail from Internet:

	Firstly you will want to ensure that there is an MX record in
	the domain database, making your host the lowest preference mail
	exchanger for the host.  As an example, my host (mp.cs.niu.edu)
	provides MX gatewaying for the domain 'art.niu.edu'.

	Next decide which mailer to use for the domain.  In the case of
	'art.niu.edu', they are able to handle Internet addresses, so I
	use the UUCP-A mailer which uses UUCP transport, but Internet
	style addresses.  The connecting machine is 'laotzu.art.niu.edu' and
	has a UUCP name of 'laotzu'.  I use the following entry in my
	mailer table:

UUCP-A!laotzu	art.niu.edu

	This causes mail to be forwarded via the UUCP-A mailer.  If there were
	an MX record for addresses *.art.niu.edu I would also include an
	entry

UUCP-A,laotzu	.art.niu.edu

	which would forward all such mail (addressed to 'host.art.niu.edu')
	for 'laotzu' to handle.

	If the domain does not understand Internet style addresses, you should
	use the UUCP mailer, instead of the UUCP-A mailer.  In this case it is
	also a good idea to include a UUCPXTABLE entry

laotzu	art.niu.edu

	The has the effect of translating the Internet name into a UUCP name,
	so that the domain (art.niu.edu) does not even need to deal with
	Internet format addresses on incoming mail.  In fact if you have such
	a UUCPXTABLE entry you don't need a MAILERTABLE entry, for the
	UUCPXTABLE entry will already select the UUCP mailer for you.

	Another approach is to handle the forwarding purely with PATHTABLE.  If
	there is a PATHTABLE entry with KEY = 'art.niu.edu' and
	VALUE = 'laotzu!%s', mail to this domain should be handled correctly.
	This works because, since your host has the lowest MX preference, the
	first attempt to find a mailer fails and the PATHTABLE is consulted.
	This approach is particularly attractive if you do MX forwarding for
	many domains.  The advantage is that those domains can manage their
	own PATHTABLE entries by submitting UUCP MAPS to the UUCP MAP project
	(uucpmap@rutgers.edu).  Of course this assumes you keep up to date
	maps and run pathalias regularly to build your PATHTABLE.

 Handling outgoing mail to the Internet:

	This depends on how the domain handles its own addresses.  It
	will need to be set up to use a relay mailer and relay all
	Internet format mail to your host.  The best solution is for the
	host to format its outgoing addresses in Internet style.  In that
	case you need do nothing.  For example, in the case of 'art.niu.edu',
	the machine currently is a Sun work station.  It uses the 'smartuucp'
	mailer as its relay mailer, but the mailer definition has been altered
	to remove the 'U' flag so that pure Internet style addresses are used.
	This works partly because I use the version of 'rmail' in 'ida/aux'
	for my rmail, and run it suid to root.  This version of 'rmail' does
	not get confused when given internet style addresses.

	If, however, 'laotzu' was unable to handle Internet style addresses
	at all for its own domain name, I would include a DOMAINTABLE entry

art.niu.edu	laotzu.UUCP	laotzu

	Then incoming mail from laotzu would automatically have its address
	converted (by DOMAINTABLE) to Internet format before sending it out
	to Internet.


  ----
  Neil Rickert <rickert@cs.niu.edu>
