-decvax %1@%0.DEC.COM
-research %1@%0.ATT.COM
-.)b
-.pp
-The built in map with both name and class
-.q host
-is the host name canonicalization lookup.
-Thus,
-the syntax:
-.(b
-$(host \fIhostname\fP$)
-.)b
-is equivalent to:
-.(b
-$[\fIhostname\fP$]
-.)b
-.pp
-There are four predefined database lookup classes:
-.q dbm ,
-.q btree ,
-.q hash ,
-and
-.q nis .
-The first requires that sendmail be compiled with the
-.b ndbm
-library;
-the second two require the
-.b db
-library,
-and the third requires that sendmail be compiled with NIS support.
-All four accept as arguments the some optional flags
-and a filename (or a mapname for NIS).
-Known flags are:
-.ip "\-o"
-Indicates that this map is optional \*- that is,
-if it cannot be opened,
-no error is produced,
-and sendmail will behave as if the map existed but was empty.
-.ip "\-N"
-Normally sendmail does not include the trailing null byte
-on a string as part of the key.
-If this flag is indicated,
-it will be included.
-This is for compatibility with some methods of building the maps.
-.ip "\-a\fIx\fP"
-Append the character
-.i x
-on successful matches.
-For example, the default
-.i host
-map appends a dot on successful matches.
-.ip "\-d\fIdomain\fP"
-Use the indicated
-.i domain
-instead of the default domain.
-Used only for NIS maps.
-.ip "\-f"
-Fold upper to lower case before looking up the key.
-.ip "\-m"
-Match only (without replacing the value).
-If you only care about the existence of a key and not the value
-(as you might when searching the NIS map
-.q hosts.byname
-for example),
-this flag prevents the map from substituting the value.
-However,
-The \-a argument is still appended on a match,
-and the default is still taken if the match fails.
-.pp
-The
-.i dbm
-map appends the strings
-.q \&.pag
-and
-.q \&.dir
-to the given filename;
-the two
-.i db -based
-maps do not.
-.pp
-The program
-.i makemap (8)
-can be used to build any of the three database-oriented maps.
-It takes the following flags:
-.ip \-f
-Fold upper to lower case in the map.
-.ip \-N
-Include null bytes in keys.
-.ip \-o
-Append to an existing (old) file.
-.ip \-r
-Allow replacement of existing keys;
-normally, re-inserting an existing key is an error.
-.ip \-v
-Print what is happening.
-.pp
-There are also two builtin maps that are,
-strictly speaking,
-not database lookups.
-.pp
-The
-.q host
-map does host domain canonification;
-given a host name it calls the name server
-to find the canonical name for that host.
-.pp
-The
-.q dequote
-map strips double quotes (") from a name.
-It does not strip backslashes.
-It will not strip quotes if the resulting string
-would contain unscannable syntax
-(that is, basic errors like unbalanced angle brackets;
-more sophisticated errors such as unknown hosts are not checked).
-The intent is for use when trying to accept mail from systems such as
-DECnet
-that routinely quote odd syntax such as
-.(b
-"49ers::ubell"
-.)b
-A typical usage is probably something like:
-.(b
-Kdequote dequote
-
-\&...
-
-R$\- $: $(dequote $1 $)
-R$\- $+ $: $>3 $1 $2
-.)b
-Care must be taken to prevent unexpected results;
-for example,
-.(b
-"|someprogram < input > output"
-.)b
-will have quotes stripped,
-but the result is probably not what you had in mind.
-Fortunately these cases are rare.
-.pp
-New classes can be added in the routine
-.b setupmaps
-in file
-.b conf.c .
-.sh 2 "Building a Configuration File From Scratch"
-.pp
-Building a configuration table from scratch is an extremely difficult job.
-Fortunately,
-it is almost never necessary to do so;
-nearly every situation that may come up
-may be resolved by changing an existing table.
-In any case,
-it is critical that you understand what it is that you are trying to do
-and come up with a philosophy for the configuration table.
-This section is intended to explain what the real purpose
-of a configuration table is
-and to give you some ideas
-for what your philosophy might be.
-.pp
-.b "Do not even consider"
-writing your own configuration file
-without carefully studying
-RFC 821, 822, and 1123.
-You should also read RFC 976
-if you are doing UUCP exchange.
-.sh 3 "What you are trying to do"
-.pp
-The configuration table has three major purposes.
-The first and simplest
-is to set up the environment for
-.i sendmail .
-This involves setting the options,
-defining a few critical macros,
-etc.
-Since these are described in other places,
-we will not go into more detail here.
-.pp
-The second purpose is to rewrite addresses in the message.
-This should typically be done in two phases.
-The first phase maps addresses in any format
-into a canonical form.
-This should be done in ruleset three.
-The second phase maps this canonical form
-into the syntax appropriate for the receiving mailer.
-.i Sendmail
-does this in three subphases.
-Rulesets one and two
-are applied to all sender and recipient addresses respectively.
-After this,
-you may specify per-mailer rulesets
-for both sender and recipient addresses;
-this allows mailer-specific customization.
-Finally,
-ruleset four is applied to do any default conversion
-to external form.
-.pp
-The third purpose
-is to map addresses into the actual set of instructions
-necessary to get the message delivered.
-Ruleset zero must resolve to the internal form,
-which is in turn used as a pointer to a mailer descriptor.
-The mailer descriptor describes the interface requirements
-of the mailer.
-.sh 3 "Philosophy"
-.pp
-The particular philosophy you choose will depend heavily
-on the size and structure of your organization.
-I will present a few possible philosophies here.
-There are as many philosophies as there are config designers;
-feel free to develop your own.
-.pp
-One general point applies to all of these philosophies:
-it is almost always a mistake
-to try to do full host route resolution.
-For example,
-if you are on a UUCP-only site
-and you are trying to get names of the form
-.q user@host
-to the Internet,
-it does not pay to route them to
-.q xyzvax!decvax!ucbvax!c70!user@host
-since you then depend on several links not under your control,
-some of which are likely to misparse it anyway.
-The best approach to this problem
-is to simply forward the message for
-.q user@host
-to
-.q xyzvax
-and let xyzvax
-worry about it from there.
-In summary,
-just get the message closer to the destination,
-rather than determining the full path.
-.sh 4 "Large site, many hosts \*- minimum information"
-.pp
-Berkeley is an example of a large site,
-i.e., more than two or three hosts
-and multiple mail connections.
-We have decided that the only reasonable philosophy
-in our environment
-is to designate one host as the guru for our site.
-It must be able to resolve any piece of mail it receives.
-The other sites should have the minimum amount of information
-they can get away with.
-In addition,
-any information they do have
-should be hints rather than solid information.
-.pp
-For example,
-a typical site on our local ether network is
-.q monet
-(actually
-.q monet.CS.Berkeley.EDU ).
-When monet receives mail for delivery,
-it checks whether it knows
-that the destination host is directly reachable;
-if so, mail is sent to that host.
-If it receives mail for any unknown host,
-it just passes it directly to
-.q ucbvax.CS.Berkeley.EDU ,
-our master host.
-Ucbvax may determine that the host name is illegal
-and reject the message,
-or may be able to do delivery.
-However, it is important to note that when a new mail connection is added,
-the only host that
-.i must
-have its tables updated
-is ucbvax;
-the others
-.i may
-be updated if convenient,
-but this is not critical.
-.pp
-This picture is slightly muddied
-due to network connections that are not actually located
-on ucbvax.
-For example,
-some UUCP connections are currently on
-.q ucbarpa.
-However,
-monet
-.i "does not"
-know about this;
-the information is hidden totally between ucbvax and ucbarpa.
-Mail going from monet to a UUCP host
-is transferred via the ethernet
-from monet to ucbvax,
-then via the ethernet from ucbvax to ucbarpa,
-and then is submitted to UUCP.
-Although this involves some extra hops,
-we feel this is an acceptable tradeoff.
-.pp
-An interesting point is that it would be possible
-to update monet
-to send appropriate UUCP mail directly to ucbarpa
-if the load got too high;
-if monet failed to note a host as connected to ucbarpa
-it would go via ucbvax as before,
-and if monet incorrectly sent a message to ucbarpa
-it would still be sent by ucbarpa
-to ucbvax as before.
-The only problem that can occur is loops,
-for example,
-if ucbarpa thought that ucbvax had the UUCP connection
-and vice versa.
-For this reason,
-updates should
-.i always
-happen to the master host first.
-.pp
-This philosophy results as much from the need
-to have a single source for the configuration files
-(typically built using
-.i m4 \|(1)
-or some similar tool)
-as any logical need.
-Maintaining more than three separate tables by hand
-is essentially an impossible job.
-.sh 4 "Small site \*- complete information"
-.pp
-A small site
-(two or three hosts and few external connections)
-may find it more reasonable to have complete information
-at each host.
-This would require that each host
-know exactly where each network connection is,
-possibly including the names of each host on that network.
-As long as the site remains small
-and the the configuration remains relatively static,
-the update problem will probably not be too great.
-.sh 4 "Single host"
-.pp
-This is in some sense the trivial case.
-The only major issue is trying to insure that you don't
-have to know too much about your environment.
-For example,
-if you have a UUCP connection
-you might find it useful to know about the names of hosts
-connected directly to you,
-but this is really not necessary
-since this may be determined from the syntax.
-.sh 4 "A completely different philosophy"
-.pp
-This is adapted from Bruce Lilly.
-Any errors in interpretation are mine.
-.pp
-Do minimal changes in ruleset 3:
-fix some common but unambiguous errors (e.g. trailing dot on domains) and
-hide bang paths foo!bar into bar@foo.UUCP.
-The resulting "canonical" form is any valid RFC822/RFC1123/RFC976 address.
-.pp
-Ruleset 0 does the bulk of the work.
-It removes the trailing "@.UUCP" that hides bang paths,
-strips anything not needed to resolve,
-e.g. the phrase from phrase <route-addr> and from named groups,
-rejects unparseable addresses using $#error,
-and finally
-resolves to a mailer/host/user triple.
-Ruleset 0 is rather lengthy
-as it has to handle 3 basic address forms:
-RFC976 bang paths,
-RFC1123 %-hacks
-(including vanilla RFC822 local-part@domain),
-and RFC822 source routes.
-It's also complicated by having to handle named lists.
-.pp
-The header rewriting rulesets 1 and 2
-remove the trailing "@.UUCP" that hides bang paths.
-Ruleset 2 also strips the $# mailer $@ host (for test mode).
-.pp
-Ruleset 4 does absolutely nothing.
-.pp
-The per-mailer rewriting rulesets conform the envelope and
-header addresses to the requirements of the specific
-mailer.
-.pp
-Lots of rulesets-as-subroutines are used.
-.pp
-As a result, header addresses are subject to minimal munging
-(per RFC1123), and the general plan is per RFC822 sect. 3.4.10.
-.sh 3 "Relevant issues"
-.pp
-The canonical form you use
-should almost certainly be as specified in
-the Internet protocols
-RFC819 and RFC822.
-Copies of these RFC's are included on the
-.i sendmail
-tape
-as
-.i doc/rfc819.lpr
-and
-.i doc/rfc822.lpr .
-.pp
-RFC822
-describes the format of the mail message itself.
-.i Sendmail
-follows this RFC closely,
-to the extent that many of the standards described in this document
-can not be changed without changing the code.
-In particular,
-the following characters have special interpretations:
-.(b
-< > ( ) " \e
-.)b
-Any attempt to use these characters for other than their RFC822
-purpose in addresses is probably doomed to disaster.
-.pp
-RFC819
-describes the specifics of the domain-based addressing.
-This is touched on in RFC822 as well.
-Essentially each host is given a name
-which is a right-to-left dot qualified pseudo-path
-from a distinguished root.
-The elements of the path need not be physical hosts;
-the domain is logical rather than physical.
-For example,
-at Berkeley
-one legal host might be
-.q a.CC.Berkeley.EDU ;
-reading from right to left,
-.q EDU
-is a top level domain
-comprising educational institutions,
-.q Berkeley
-is a logical domain name,
-.q CC
-represents the Computer Center,
-(in this case a strictly logical entity),
-and
-.q a
-is a host in the Computer Center.
-.pp
-Beware when reading RFC819
-that there are a number of errors in it.
-.sh 3 "How to proceed"
-.pp
-Once you have decided on a philosophy,
-it is worth examining the available configuration tables
-to decide if any of them are close enough
-to steal major parts of.
-Even under the worst of conditions,
-there is a fair amount of boiler plate that can be collected safely.
-.pp
-The next step is to build ruleset three.
-This will be the hardest part of the job.
-Beware of doing too much to the address in this ruleset,
-since anything you do will reflect through
-to the message.
-In particular,
-stripping of local domains is best deferred,
-since this can leave you with addresses with no domain spec at all.
-Since
-.i sendmail
-likes to append the sending domain to addresses with no domain,
-this can change the semantics of addresses.
-Also try to avoid
-fully qualifying domains in this ruleset.
-Although technically legal,
-this can lead to unpleasantly and unnecessarily long addresses
-reflected into messages.
-The Berkeley configuration files
-define ruleset nine
-to qualify domain names and strip local domains.
-This is called from ruleset zero
-to get all addresses into a cleaner form.
-.pp
-Once you have ruleset three finished,
-the other rulesets should be relatively trivial.
-If you need hints,
-examine the supplied configuration tables.
-.sh 3 "Testing the rewriting rules \*- the \-bt flag"
-.pp
-When you build a configuration table,
-you can do a certain amount of testing
-using the
-.q "test mode"
-of
-.i sendmail .
-For example,
-you could invoke
-.i sendmail
-as:
-.(b
-sendmail \-bt \-Ctest.cf
-.)b
-which would read the configuration file
-.q test.cf
-and enter test mode.
-In this mode,
-you enter lines of the form:
-.(b
-rwset address
-.)b
-where
-.i rwset
-is the rewriting set you want to use
-and
-.i address
-is an address to apply the set to.
-Test mode shows you the steps it takes
-as it proceeds,
-finally showing you the address it ends up with.
-You may use a comma separated list of rwsets
-for sequential application of rules to an input.
-For example:
-.(b
-3,1,21,4 monet:bollard
-.)b
-first applies ruleset three to the input
-.q monet:bollard.
-Ruleset one is then applied to the output of ruleset three,
-followed similarly by rulesets twenty-one and four.
-.pp
-If you need more detail,
-you can also use the
-.q \-d21
-flag to turn on more debugging.
-For example,
-.(b
-sendmail \-bt \-d21.99