-while they are being updated.\**
-.(f
-\**That is, don't create new maps and then use
-.i mv (1)
-to move them into place.
-I consider this a shortfall (a.k.a. bug) in
-.i sendmail
-which should be fixed in a future release.
-.)f
-.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 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
-.)b
-turns on an incredible amount of information;
-a single word address
-is probably going to print out several pages worth of information.
-.pp
-You should be warned that internally,
-.i sendmail
-applies ruleset 3 to all addresses.
-In this version of
-.i sendmail ,
-you will have to do that manually.
-For example, older versions allowed you to use
-.(b
-0 bruce@broadcast.sony.com
-.)b
-This version requires that you use:
-.(b
-3,0 bruce@broadcast.sony.com
-.)b
-.sh 3 "Building mailer descriptions"
-.pp
-To add an outgoing mailer to your mail system,
-you will have to define the characteristics of the mailer.
-.pp
-Each mailer must have an internal name.
-This can be arbitrary,
-except that the names
-.q local
-and
-.q prog
-must be defined.
-.pp
-The pathname of the mailer must be given in the P field.
-If this mailer should be accessed via an IPC connection,
-use the string
-.q [IPC]
-instead.
-.pp
-The F field defines the mailer flags.
-You should specify an
-.q f
-or
-.q r
-flag to pass the name of the sender as a
-.b \-f
-or
-.b \-r
-flag respectively.
-These flags are only passed if they were passed to
-.i sendmail ,
-so that mailers that give errors under some circumstances
-can be placated.
-If the mailer is not picky
-you can just specify
-.q "\-f $g"
-in the argv template.
-If the mailer must be called as
-.b root
-the
-.q S
-flag should be given;
-this will not reset the userid
-before calling the mailer\**.
-.(f
-\**\c
-.i Sendmail
-must be running setuid to root
-for this to work.
-.)f
-If this mailer is local
-(i.e., will perform final delivery
-rather than another network hop)
-the
-.q l
-flag should be given.
-Quote characters
-(backslashes and " marks)
-can be stripped from addresses if the
-.q s
-flag is specified;
-if this is not given
-they are passed through.
-If the mailer is capable of sending to more than one user
-on the same host
-in a single transaction
-the
-.q m
-flag should be stated.
-If this flag is on,
-then the argv template containing
-.b $u
-will be repeated for each unique user
-on a given host.
-The
-.q e
-flag will mark the mailer as being
-.q expensive,
-which will cause
-.i sendmail
-to defer connection
-until a queue run\**.
-.(f
-\**The
-.q c
-configuration option must be given
-for this to be effective.
-.)f
-.pp
-An unusual case is the
-.q C
-flag.
-This flag applies to the mailer that the message is received from,
-rather than the mailer being sent to;
-if set,
-the domain spec of the sender
-(i.e., the
-.q @host.domain
-part)
-is saved
-and is appended to any addresses in the message
-that do not already contain a domain spec.
-For example,
-a message of the form:
-.(b
-From: eric@vangogh.CS.Berkeley.EDU
-To: wnj@monet.CS.Berkeley.EDU, mckusick
-.)b
-will be modified to:
-.(b
-From: eric@vangogh.CS.Berkeley.EDU
-To: wnj@monet.CS.Berkeley.EDU, mckusick@vangogh.CS.Berkeley.EDU
-.)b
-.i "if and only if"
-the
-.q C
-flag is defined in the mailer resolved to
-by running
-.q eric@vangogh.CS.Berkeley.EDU
-through rulesets 3 and 0.
-.pp
-Other flags are described
-in Appendix C.
-.pp
-The S and R fields in the mailer description
-are per-mailer rewriting sets
-to be applied to sender and recipient addresses
-respectively.
-These are applied after the sending domain is appended
-and the general rewriting sets
-(numbers one and two)
-are applied,
-but before the output rewrite
-(ruleset four)
-is applied.
-A typical use is to append the current domain
-to addresses that do not already have a domain.
-For example,
-a header of the form:
-.(b
-From: eric
-.)b
-might be changed to be:
-.(b
-From: eric@vangogh.CS.Berkeley.EDU
-.)b
-or
-.(b
-From: ucbvax!eric
-.)b
-depending on the domain it is being shipped into.
-These sets can also be used
-to do special purpose output rewriting
-in cooperation with ruleset four.
-.pp
-The S and R fields
-can be specified as two numbers separated by a slash
-(e.g.,
-.q "S=10/11" ),
-meaning that all envelope addresses will be processed through ruleset 10
-and all header addresses will be processed through ruleset 11.
-With only one number specified,
-both envelope and header rewriting sets are set to the indicated ruleset.
-.pp
-The E field defines the string to use
-as an end-of-line indication.
-A string containing only newline is the default.
-The usual backslash escapes
-(\er, \en, \ef, \eb)
-may be used.
-.pp
-Finally,
-an argv template is given as the A field.
-It may have embedded spaces.
-If there is no argv with a
-.b $u
-macro in it,
-.i sendmail
-will speak SMTP
-to the mailer.
-If the pathname for this mailer is
-.q [IPC],
-the argv should be
-.(b
-IPC $h [ \fIport\fP ]
-.)b
-where
-.i port
-is the optional port number
-to connect to.
projects / unix-history / blobdiff