Building a configuration file from scratch

Building a configuration file from scratch is an extremely difficult job. Fortunately, it is almost never necessary to do so; nearly every situation that may come up can be resolved by changing an existing configuration file. In any case, it is critical that you understand what you are trying to do and come up with a design plan for the configuration file. This section is intended to explain the real purpose of a configuration file and to give you some ideas as to what your design plan might be.

Do not even consider writing your own configuration file without carefully studying RFC 821, RFC 822, and RFC 1123. You should also read RFC 976 if you are doing UUCP exchange.

Purpose of the configuration file

The configuration file has three major purposes. The first and simplest is to set up the environment for sendmail. This involves setting the options, defining a few critical macros, and so on. Because these are described in other sections, we will not go into more detail here.

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.

The sendmail program performs this second phase in the following three subphases: Rulesets one and two are applied to all sender and recipient addresses, respectively. After this, you can 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.

The third purpose of the configuration file 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. This describes the interface requirements of the mailer.

Relevant issues

The canonical form you use should almost certainly be as specified in the Internet standards documents RFC 819 and RFC 822. These RFCs can be ftp'd from ftp.ds.internic.net.

RFC 822 describes the format of the mail message itself. The sendmail program follows this RFC closely, to the extent that many of the standards described in this document cannot be changed without changing the code. In particular, the following characters have special interpretations:

< > ( ) " \

Any attempt to use these characters for other than their RFC 822 purpose in addresses is probably doomed to disaster.

RFC 819 describes the specifics of the domain-based addressing. This is touched on in RFC 822 as well. Essentially, each host is given a name that 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, atOcelot, one legal host might be a.CC.Ocelot.EDU; reading from right to left, EDU is a top level domain comprising educational institutions, Ocelot is a logical domain name, CC represents the Computer Center, (in this case a strictly logical entity), and ``a'' is a host in the Computer Center.

Beware when reading RFC 819 that there are a number of errors in it.

How to proceed

Once you have decided on a design plan for the new configuration file, it is worth examining existing configuration files to decide whether any of them are close enough for you to use major parts of them as a basis for your own configuration file. Even under the worst of conditions, there should be a large amount of material you can use.

The next step is to build ruleset three. This is the hardest part of the job. Beware of doing too much to the address in this ruleset, because anything you do reflects through to the message. In particular, stripping of local domains is best deferred, as this can leave you with addresses with no domain specifications at all. Because 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 Ocelot 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.

Once you have ruleset three finished, the other rulesets should be relatively trivial. If you need hints, examine the supplied configuration files.

Testing the rewriting rules: the -bt flag

When you build a configuration file, you can do a certain amount of testing using the ``test mode'' of sendmail. For example, you could invoke sendmail as:

sendmail -bt -Ctest.cf

This reads the configuration file test.cf and enters test mode. In this mode, you enter lines of the form:

rwset address

Here rwset is the rewriting set you want to use and address is an address to which to apply the set. Test mode shows you the steps it takes as it proceeds, finally showing you the address with which it ends up. You may use a comma-separated list of rwsets for sequential application of rules to an input. For example:

3,1,21,4 monet:bollard

The first applies ruleset three to the input ``monet:bollard.'' Ruleset one is then applied to the output of ruleset three, followed similarly by rulesets 21 and 4.

If you need more detail, you can also use the -d21 flag to turn on more debugging. For example:

sendmail -bt -d21.99

This turns on a huge amount of information. A single-word address probably prints out several pages of information.

You should be warned that internally, sendmail applies ruleset 3 to all addresses. In this version of sendmail, you will have to do that manually. For example, older versions allowed you to use

0 bruce@broadcast.sony.com

This version requires that you use:

3,0 bruce@broadcast.sony.com

Building mailer descriptions

To add an outgoing mailer to your mail system, you must define the characteristics of the mailer.

Each mailer must have an internal name. This can be arbitrary, except that the names ``local'' and ``prog'' must be defined.

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 ``[IPC]'' instead.

The ``F'' field defines the mailer flags. You should specify an ``f'' or ``r'' flag to pass the name of the sender as a -f or -r flag, respectively. These flags are only passed if they were passed to sendmail, so that mailers that give errors under some circumstances can be placated. If the mailer does not produce many errors, you can just specify ``-f $g'' in the argv template. If the mailer must be called as root, the S flag should be given. This does not reset the user ID before calling the mailer. (sendmail must be running setuid to root for this to work.) If this mailer is local (that is, it performs final delivery rather than another network hop), the l flag should be given. Quote characters (backslashes and " marks) can be stripped from addresses if the 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 m flag should be stated. If this flag is on, then the argv template containing $u is repeated for each unique user on a given host. The e flag marks the mailer as being expensive, which causes sendmail to defer connection until a queue run. (The ``c'' configuration option must be given for this to be effective.)

An unusual case is the 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 specification of the sender (that is, the @host.domain part) is saved and is appended to any addresses in the message that do not already contain a domain specification. For example:

   From: eric@vango.CS.Berkeley.EDU
   To: wnj@monet.CS.Berkeley.EDU, mckusick

   From: eric@vango.CS.Berkeley.EDU
   To: wnj@monet.CS.Berkeley.EDU, mckusick@monet.CS.Berkeley.EDU

Other mailer flags are described in the section ``M--define mailer''.

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:

   From: eric

   From: eric@vango.CS.Berkeley.EDU

   From: ucbvax!eric

The ``S'' and ``R'' fields can be specified as two numbers separated by a slash (for example, ``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.

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 (\r, \n, \f, \b) may be used.

Finally, an argv template is given as the ``A'' field. It may have embedded spaces. If there is no argv with a $u macro in it, sendmail speaks SMTP to the mailer. If the pathname for this mailer is [IPC], the argv should be:

IPC $h [ port ]

Here port is the optional port number to connect to.

For example:

Mlocal, P=/usr/bin/lmail, F=lsDFMmnPS S=10, R=20, A=lmail $u
Mether, P=[IPC], F=meC, S=11, R=21, A=IPC $h, M=100000, E=\r\n

These specifications specify a mailer to do local delivery and a mailer for Ethernet delivery. The first is called ``local''; it is located in the file /usr/bin/lmail, does local delivery, quotes should be stripped from addresses, and multiple users can be delivered at once; ruleset 10 should be applied to sender addresses in the message, and ruleset 20 should be applied to recipient addresses. The argv to send to a message is the word ``lmail,'' and words containing the name of the receiving user(s).

The second mailer is called ``ether''; it should be connected to via an IPC connection; it can handle multiple users at once; connections should be deferred; and any domain from the sender address should be appended to any receiver name without a domain. Sender addresses should be processed by ruleset 11 and recipient addresses by ruleset 21. There is a 100,000-byte limit on messages passed through this mailer.