Now you've got a working sendmail, but like the Wizard of Oz's Scarecrow, it's brainless. The sendmail.cf file provides sendmail with its brains, and because it's so important, we're going to cover it in fairly excruciating detail. Don't worry if you don't understand everything in this section the first time through. It will make more sense upon rereading, and after you've had a chance to play with some configuration files of your own.

sendmail's power lies in its flexibility, which comes from its configuration file, sendmail.cf. sendmail.cf statements comprise a cryptic programming language that at first glance doesn't inspire much confidence (but C language code probably didn't either the first time you saw it). However, learning the sendmail.cf language isn't that hard, and you won't have to learn the nitty-gritty details unless you plan to write a sendmail.cf from scratch—a bad idea at best. You do need to learn enough to understand and adapt the V8 sendmail configuration file templates to your site's needs.

General Form of the Configuration File

Each line of the configuration file begins with a single command character that tells the function and syntax of that line. Lines beginning with a # are comments, and blank lines are ignored. Lines beginning with a space or tab are a continuation of the previous line, although you should usually avoid continuations.

Table 41.1 shows the command characters and their functions. It is split into three parts corresponding to the three main functions of a configuration file, which are covered later in "A Functional Description of the Configuration File."

Table 41.1. sendmail.cf command characters.

A Functional Description of the Configuration File

A configuration file does three things. First, it sets the environment for sendmail by telling it what options you want set and the locations of the files and databases it uses.

Second, it defines the characteristics of the mailers (delivery agents or MTAs) that sendmail uses after it decides where to route a letter. All configuration files must define local and program mailers to handle delivery to users on the local host; most also define one or more SMTP mailers; and sites that must handle UUCP mail define UUCP mailers.

Third, the configuration file specifies rulesets that rewrite sender and recipient addresses and select mailers. All rulesets are user-defined, but some have special meaning to sendmail. Ruleset 0, for instance, is used to select a mailer. Rulesets 0, 1, 2, 3, and 4 all have special meaning to sendmail and are processed in a particular order (see "The S and R Operators—Rulesets and Rewriting Rules") later in this chapter.

In the following sections we'll cover the operators in more detail, in the order in which they appear in Table 41.1.

The D Operator—Macros

Macros are like shell variables. Once you define a macro's value you can refer to it later in the configuration file and its value will be substituted for the macro. For instance, a configuration file might have many lines that mention our hypothetical mail hub, mailer.gonzo.gov. Rather than typing that name over and over, you can define a macro R (for relay mailer):

When sendmail encounters a $R in sendmail.cf, it substitutes the string mailer.gonzo.gov.

Macro names are always a single character. Quite a few macros are defined by sendmail and shouldn't be redefined except to work around broken software1. sendmail uses lower-case letters for its predefined macros. Uppercase letters may be used freely. V8 sendmail's predefined macros are fully documented in section 5.1.2 of the SIOG.

The C and F Operators—Classes

Classes are similar to macros but are used for different purposes in rewriting rules (see below, "The S and R operators—rulesets and rewriting rules"). As with macros, classes are named by a single character. Lowercase letters are reserved to sendmail, and uppercase letters for user-defined classes. A class contains one or more words. For instance, you could define a class H containing all the hosts in the local domain:

For convenience, large classes may be continued on subsequent lines. The following definition of the class H is exactly the same as the previous one:

You can also define a class by reading its words from a file:

If the file /usr/local/lib/localhosts contains the words larry, moe, and curly, one per line, this definition is equivalent to the previous two.

Why use macros and classes? The best reason is that they centralize information in the configuration file. In the example above, if you decide to change the name of the mail hub from mailer.gonzo.gov to mailhub.gonzo.gov, you only have to change the definition of the $R macro remedyand the configuration file will work as before. If the name mailer.gonzo.gov is scattered throughout the file, you might forget to change it in some places. Also, if important information is centralized, you can comment it extensively in a single place. Because configuration files tend to be obscure at best, a liberal dose of comments is a good antidote to that sinking feeling you get when, six months later, you wonder why you made a change.

The H Operator—Header Definitions

You probably won't want to change the header definitions given in the V8 sendmail configuration files because they already follow accepted standards. Here are some sample headers:

Note that header definitions can use macros, which are expanded, when inserted into a letter. For instance, the $x macro used in the Full-Name: header definition above expands to the full name of the sender.

The optional ?mailerflag? construct tells sendmail to insert a header only if the chosen mailer has that mailer flag set. (See "The M Operator—Mailer Definitions" later in this chapter.)

Suppose that the definition of your local mailer has a flag Q, and sendmail selects that mailer to deliver a letter. If your configuration file contains a header definition like the following one, sendmail will insert that header into letters delivered through the local mailer, substituting the value of the macro $F:

Why would you use the ?mailerflag? feature? Different protocols may require different mail headers. Since they also need different mailers, you can define appropriate mailer flags for each in the mailer definition, and use the ?mailerflag? construct in the header definition to tell sendmail whether to insert the header.

The O Operator—Setting Options

sendmail has many options that change its operation or tell it the location of files it uses. Most of them may be given either on the command line or in the configuration file. For instance, the location of the aliases file may be specified in either place. To specify the aliases file on the command line, you use the -o option:

To do the same thing in the configuration file, you include a line like this:

Either use is equivalent, but options such as the location of the aliases file rarely change and most people set them in sendmail.cf. The V8 sendmail options are fully described in section 5.1.6 of the SIOG.

The P Operator—Mail Precedence

Users can include mail headers indicating the relative importance of their mail, and sendmail can use those headers to decide the priority of competing letters. Precedences for V8 sendmail are given as:

If a user who runs a large mailing list includes the header Precedence: bulk in his letters, sendmail gives it a lower priority than a letter with the header Precedence: first-class.

The V Operator—sendmail.cf Version Levels

As V8 sendmail evolves its author adds new features. The V operator lets V8 sendmail know what features it should expect to find in your configuration file. Older versions of sendmail don't understand this command. Section 5.1.8 of the SIOG explains the different configuration file version levels in detail.

The K Operator—Key Files

sendmail has always used keyed databases, for instance, the aliases databases. Given the key postmaster, sendmail looks up the data associated with that key and returns the names of the accounts to which the postmaster's mail should be delivered. V8 sendmail extends this concept to arbitrary databases, including NIS maps (Sun's Network Information Service, formerly known as Yellow Pages or YP). The K operator tells sendmail the location of the database, its class, and how to access it. V8 sendmail supports the following classes of user-defined databases: dbm, btree, hash, and NIS. Depending on which of these databases you use, you must compile sendmail with different options. See section 5.1.9 of the SIOG for the lowdown on key files.

The M Operator—Mailer Definitions

Mailers are either MTAs or final delivery agents. Recall that the aliases file allows you to send mail to a login name (which might be aliased to a remote user), a program, or a file. A special mailer may be defined for each purpose. And even though the SMTP MTA is built-in, it must have a mailer definition to tailor sendmail's SMTP operations.

Mailer definitions are important because all recipient addresses must resolve to a mailer in ruleset 0. Resolving to a mailer is just another name for sendmail's main function, mail routing. For instance, resolving to the local mailer routes the letter to a local user via the final delivery agent defined in that mailer (usually /bin/mail), and resolving to the SMTP mailer routes the letter to another host via sendmail's built-in SMTP transport, as defined in the SMTP mailer. A concrete example of a mailer definition will make this clearer. Since sendmail requires a local mailer definition, let's look at that:

All mailer definitions begin with the M operator and the name of the mailer, in this case local. Other fields follow, separated by commas. Each field consists of a field name and its value, separated by an equals sign (=). The allowable fields are explained in section 5.1.4 of the SIOG.

In the local mailer definition above, the P= equivalence gives the pathname of the program to run to deliver the mail, /bin/mail. The F= field gives the sendmail flags for the local mailer. (See also "The H Operator—Defining Headers" earlier in the chapter.) These flags are not passed to the command mentioned in the P= field but are used by sendmail to modify its operation depending on the mailer it chooses. For instance, sendmail usually drops its super-user status before invoking mailers, but you can use the S mailer flag to tell sendmail to retain it for certain mailers.

The S= and R= fields specify rulesets for sendmail to use in rewriting sender and recipient addresses. Since you can give different R= and S= flags for each mailer you define, you can rewrite addresses differently for each mailer. For instance, if one of your UUCP neighbors runs obsolete software that doesn't understand domain addressing, you might declare a special mailer just for that site and write mailer-specific rulesets to convert addresses into a form its mailer could understand.

The S= and R= fields can also specify different rulesets to rewrite the envelope and header addresses. (See "Header and Envelope Addresses".) A specification like S=21/31 tells sendmail to use ruleset 21 to rewrite sender envelope addresses and ruleset 31 to rewrite sender header addresses. This comes in handy for mailers that require addresses to be presented differently in the envelope and the headers.

The A= field gives the argument vector (command line) for the program that will be run, in this case /bin/mail. In this example, sendmail runs the command as mail -d $u, expanding the $u macro to the name of the user to which the mail should be delivered, for instance:

This is exactly the same command that you could type to your shell at a command prompt.

There are many other mailer flags you may want to use to tune mailers, for instance to limit the maximum message size on a per-mailer basis. These flags are all documented in section 5.1.4 of the SIOG.

The S and R Operators—Rulesets and Rewriting Rules

A configuration file is composed of a series of rulesets, which are somewhat like subroutines in a program. Rulesets are used to detect bad addresses, to rewrite addresses into forms that remote mailers can understand, and to route mail to one of sendmail's internal mailers. (See the previous section, "The M Operator—Mailer Definitions".)

sendmail passes addresses to rulesets according to a built-in order. Rulesets may also call other rulesets not in the built-in order. The built-in order varies depending on whether the address being handled is a sender or receiver address, and what mailer has been chosen to deliver the letter.

Rulesets are announced by the S command, which is followed by a number to identify the ruleset. sendmail collects subsequent R (rule) lines until it finds another S operator, or the end of the configuration file. The following example defines ruleset 11:

This ruleset doesn't do much that is useful. The important thing to note is that sendmail collects ruleset number 11, composed of a single rule.

sendmail's Built-In Ruleset Processing Rules

sendmail uses a three-track approach to processing addresses, one to choose a delivery agent, another to process sender addresses, and one for receiver addresses.

All addresses are first sent through ruleset 3 for preprocessing into a canonical form that makes them easy for other rulesets to handle. Regardless of the complexity of the address, ruleset 3's job is to decide the next host to which a letter should be sent. Ruleset 3 tries to locate that host in the address and mark it within angle brackets. In the simplest case, an address like joe@gonzo.gov becomes joe<@gonzo.gov>.

Ruleset 0 then determines the correct delivery agent (mailer) to use for each recipient. For instance, a letter from betty@whizzer.com to joe@gonzo.gov (an Internet site) and pinhead!zippy (an old-style UUCP site) will require two different mailers: an SMTP mailer for gonzo.gov and an old-style UUCP mailer for pinhead. Mailer selection determines later processing of sender and recipient addresses because the rulesets given in the S= and R= mailer flags vary from mailer to mailer.

Addresses sent through ruleset 0 must resolve to a mailer. This means that when an address matches the lhs, the rhs gives a triple2 of mailer, user, host. The following line shows the syntax for a rule that resolves to a mailer:

The mailer is the name of one of the mailers you've defined in an M command, for instance smtp. The host and user are usually positional macros taken from the lhs match. (See "The Righthand Side (rhs) of Rules," later in the chapter.)

After sendmail selects a mailer in ruleset 0, it processes sender addresses through ruleset 1 (often empty), and then sends them to the ruleset given in the S= flag for that mailer.

Similarly, it sends recipient addresses through ruleset 2 (also often empty), and then to the ruleset mentioned in the R= mailer flag.

Finally, sendmail post-processes all addresses in ruleset 4, which among other things removes the angle brackets inserted by ruleset 3.

Why do mailers have different S= and R= flags? Consider the example above of the letter sent to joe@gonzo.gov and pinhead!zippy. If betty@whizzer.com sends the mail, her address must appear in a different form to each recipient. For Joe, it should be a domain address, betty@whizzer.com. For Zippy, since whizzer.com expects old-style UUCP addresses (and assuming it has a UUCP link to pinhead and whizzer.com's UUCP hostname is whizzer), the return address should be whizzer!betty. Joe's address must also be rewritten for the pinhead UUCP mailer, and Joe's copy must include an address for Zippy that his mailer can handle.

Processing Rules Within Rulesets

sendmail passes an address to a ruleset, and then processes it through each rule line by line. If the lhs of a rule matches the address, it is rewritten by the rhs. If it doesn't match, sendmail continues to the next rule until it reaches the end of the ruleset3. At the end of the ruleset, sendmail returns the rewritten address to the calling ruleset or to the next ruleset in its built-in execution sequence.

If an address matches the lhs and is rewritten by the rhs, the rule is tried again—an implicit loop (but see the $@ and $: modifiers below for exceptions).

As shown in Table 41.1, each rewriting rule is introduced by the R command and has three fields, the lefthand side (lhs, or matching side), the righthand side (rhs, or rewriting side) and an optional comment, each of which must be separated by tab characters:

Parsing—Turning Addresses into Tokens

sendmail parses addresses and the lhs of rules into tokens and then matches the address and the lhs, token by token. The macro $o contains the characters that sendmail uses to separate an address into tokens. It's often defined like this:

All of the characters in $o are both token separators and tokens. sendmail takes an address such as rae@rainbow.org and breaks it into tokens according to the characters in the o macro, like this:

sendmail also parses the lhs of rewriting rules into tokens so they can be compared one by one with the input address to see if they match. For instance, the lhs $-@rainbow.org gets parsed as:

(Don't worry about the $- just yet. It's a pattern-matching operator similar to shell wild cards that matches any single token, and is covered below in "The Lefthand Side (lhs) of Rules.") Now we can put the two together to show how sendmail decides whether an address matches the lhs of a rule:

In this case, each token from the address matches a constant string (e.g., rainbow) or a pattern-matching operator ($-), so the address matches and sendmail would use the rhs to rewrite the address.

Consider the effect (usually bad!) of changing the value of $o. As shown above, sendmail breaks the address rae@rainbow.org into five tokens. However, if the @ character were not in $o, the address would be parsed quite differently, into only three tokens:

You can see that changing $o has a drastic effect on sendmail's address parsing, and you should leave it alone until you really know what you're doing. Even then you probably won't want to change it since the V8 sendmail configuration files already have it correctly defined for standard RFC 822 and RFC 976 address interpretation.

The Lefthand Side (lhs) of Rules

The lhs is a pattern against which sendmail matches the input address. The lhs may contain ordinary text or any of the pattern-matching operators shown in Table 41.2:

Table 41.2. lhs pattern-matching operators.

The values of macros and classes are matched in the lhs with the operators shown in Table 41.3:

Table 41.3. lhs macro and class matching operators.

The pattern-matching operators and macro- and class-matching operators are necessary because most rules must match many different input addresses. For instance, a rule might need to match all addresses that end with gonzo.gov and begin with one or more of anything.

The Righthand Side (rhs) of Rules

The rhs of a rewriting rule tells sendmail how to rewrite an address that matches the lhs. The rhs may include text, macros, and positional references to matches in the lhs. When a pattern-matching operator from Table 41.2 matches the input, sendmail assigns it to a numeric macro $n, corresponding to the position it matches in the lhs. For instance, suppose the address joe@pc1.gonzo.gov is passed to the following rule:

In this example, joe matches $+ (one or more of anything), so sendmail assigns the string joe to $1. The @ in the address matches the @ in the lhs, but constant strings are not assigned to positional macros. The tokens in the string pc1.gonzo.gov match the second $+ and are assigned to $2. The address is rewritten as $1<@$2>, or joe<@pc1.gonzo.gov>.

$: and $@—Altering a Ruleset's Evaluation

Consider the following rule:

After rewriting an address in the rhs, sendmail tries to match the rewritten address with the lhs of the current rule. Since $* matches zero or more of anything, what prevents sendmail from going into an infinite loop on this rule? After all, no matter how the rhs rewrites the address, it will always match $*.

The $: preface to the rhs comes to the rescue; it tells sendmail to evaluate the rule only once.

There are also times when you want a ruleset to terminate immediately and return the address to the calling ruleset or the next ruleset in sendmail's built-in sequence. Prefacing a rule's rhs with $@ causes sendmail to exit the ruleset immediately after rewriting the address in the rhs.

$>—Calling Another Ruleset

A ruleset can pass an address to another ruleset by using the $> preface to the rhs. Consider the following rule:

The lhs $* matches zero or more of anything, so sendmail always does the rhs. As we saw in the previous section, the $: prevents the rule from being evaluated more than once. The $>66 $1 calls ruleset 66 with $1 as its input address. Since the $1 matches whatever was in the lhs, this rule simply passes the entirety of the current input address to ruleset 66. Whatever ruleset 66 returns is passed to the next rule in the ruleset.

Testing Rules and Rulesets—the -bt, -d and -C Options

Debugging a sendmail.cf can be a tricky business. Fortunately, sendmail provides several ways to test rulesets before you install them.

The -bt option tells sendmail to enter its rule-testing mode:

The > prompt means sendmail is waiting for you to enter one or more ruleset numbers, separated by commas, and an address. Try your login name with rulesets 3 and 0. The result should look something like this:

The output shows how sendmail processes the input address joe in each ruleset. Each line of output is identified with the number of the ruleset processing it, the input address, and the address that the ruleset returns. The > is a second prompt indicating that sendmail is waiting for another line of input. When you're done testing, just type Ctrl+D.

Indentation and blank lines better show the flow of processing in this example:

The rulesets called were 3 and 0, in that order. Ruleset 3 was processed and returned the value joe, and then sendmail called ruleset 0. Ruleset 0 called ruleset 3 again, and then ruleset 6, an example of how a ruleset can call another one by using $>. Neither ruleset 3 nor ruleset 6 rewrote the input address. Finally, ruleset 0 resolved to a mailer, as it must.

Often you need more detail than -bt provides—usually just before you tear out a large handful of hair because you don't understand why an address doesn't match the lhs of a rule. You may remain hirsute because sendmail has verbose debugging built-in to most of its code.

You use the -d option to turn on sendmail's verbose debugging. This option is followed by a numeric code that tells which section of debugging code to turn on, and at what level. The following example shows how to run sendmail in one of its debugging modes and the output it produces:

The -d21.12 in the example above tells sendmail to turn on level 12 debugging in section 21 of its code. The same command with the option -d21.36 gives more verbose output (debug level 36 instead of 12).

The -d option is not limited to use with sendmail's address testing mode (-bt); you can also use it to see how sendmail processes rulesets while sending a letter, as the following example shows:

Unfortunately, the SIOG doesn't tell you which numbers correspond to which sections of code. Instead, the author suggests that it's a lot of work to keep such documentation current (which it is), and that you should look at the code itself to discover the correct debugging formulas.

The function tTd() is the one to look for. For example, suppose you wanted to turn on debugging in sendmail's address-parsing code. The source file parseaddr.c contains most of this code, and the following command finds the allowable debugging levels:

The egrep output shows that debugging specifications like -d20.1, -d24.4, and -d22.11 (and others) will make sense to sendmail.

If perusing thousands of lines of C code doesn't appeal to you, the guide sendmail documents the debugging flags for sendmail version 8.6.9.

The -C option allows you to test new configuration files before you install them, which is always a good idea. If you want to test a different file, use -C/path/to/the/file. This can be combined with the -bt and -d flags. For instance, a common invocation for testing new configuration files is:

WARNING: For security, sendmail drops its super-user permissions when you use the -C option. Final testing of configuration files should be done as the super-user to ensure that your testing is compatible with sendmail's normal operating mode.

Conclusion

Now you know a lot about the sendmail.cf language as well as some useful debugging techniques. However, configuration files will be easier to grasp when you look at some real ones. The section below shows you how to create one from the m4 templates included with V8 sendmail.

Creating a sendmail.cf

In this section, we'll develop a sendmail.cf for a Solaris 2.3 system, using the templates supplied with V8 sendmail. However, because every site is different, even if you're developing a sendmail.cf for another Solaris 2.3 system, yours will probably differ from the one below.

Previous versions of sendmail included complete, sample configuration files to adapt for your site. By contrast, the V8 sendmail configuration files are supplied as m4 templates that you use like building blocks to create a custom configuration file. This is a big advantage for most people. In previous versions, if your site did not want UUCP support, you had to pick through hundreds of lines of a configuration file and remove it line by line. In this version, you simply insert the statement FEATURE(nouucp) into your configuration file template and you are done.

M4 is a programming language that reads a file of macro definitions and commands and creates an output file from it. As a trivial example, suppose you create a document and find yourself repeatedly typing the phrase sendmail Installation and Operation Guide. To avoid the extra typing, you could define a macro siog and enter that instead:

Running m4 on the file test.m4 converts all occurrences of siog to sendmail Installation and Operation Guide. This example only hints at m4's capabilities. The V8 sendmail.cf templates make full use of them.

The sendmail.cf templates and m4 support files are in the cf directory you created earlier when you unpacked V8 sendmail:

Please note the file README. If you don't read it, you have little hope of making a working configuration file.

The cf subdirectory is the main one of interest. It contains m4 templates for configuration files used at the University of California at Berkeley (UCB). You should look at them all; one of them may be very close to what you need, and all of them provide good examples for you to adapt to your own site.

The other subdirectories contain m4 support files, the building blocks that are included based on the template you define in the cf subdirectory. You probably won't have to change any of these, although you may need to create site-specific files in the domain and siteconfig subdirectories.

The cf subdirectory contains the following configuration file templates:

The template tcpproto.mc is intended for a generic Internet site without UUCP connections. We'll use that as a starting point to develop our own. Since we don't want to modify the original file, we'll make a copy called test.mc and modify that. Although we won't show this in the examples below, it's a good idea to use a version control system like SCCS or RCS, or some other version control system to track changes you make to your configuration file template.

Stripped of its comments (a notice), blank lines, and an m4 directive, test.mc looks like this:

This doesn't look like much, but m4 expands it to almost 600 lines. We'll look at this template line-by-line to show what it does.

The line include('../m4/cf.m4') must come first in all configuration file templates, immediately after any comments. It contains the macro definitions that m4 uses to build your configuration file, and if you don't include it here, nothing else will work.

The VERSIONID() macro provides a place to put version information for the edification of humans—sendmail ignores it. If you use RCS or SCCS, you can include their version information here. For instance, for RCS you can include the $Id$ keyword:

and the RCS co (check-out) command expands this to:

The FEATURE() macro is used to specify which features you want (or don't want). The line FEATURE(nouucp) in this configuration file template removes UUCP support from the resulting configuration file. Other features are documented in the README file mentioned above. Some features of particular interest are redirect, which provides a clever way to notify senders when someone leaves your site; and nullclient, which creates a bare-bones configuration file that knows just enough to forward mail to a relay. (See the template nullclient.mc for an example of its use.)

The next two lines are MAILER() macros to specify the mailers included in this sendmail.cf. The MAILER() macro takes a single argument, the name of the mailer when m4 expands the MAILER() macro into one or more ruleset definitions, rules to select them in ruleset 0, and the rulesets given in the R= and S= flags. Selecting the smtp mailer actually causes three SMTP mailers to be included. The V8 templates also provide mailer definitions for UUCP mailers, a FAX mailer, and a POP (Post Office Protocol) mailer. See the README file for details.

This is almost enough of a specification to create a working sendmail.cf for an SMTP-only site, but you'll want to tune it a little first with additional macros.

The OSTYPE() macro also takes a single argument, the name of a file in ../ostype. This file should contain definitions particular to your operating system, for instance, the location of the aliases file. A wide variety of operating system definitions are included with the V8 configuration files:

Since we're developing a configuration file for a Solaris 2.3 system, we'll look at that file:

This is pretty straightforward—the file gives the location of sendmail's auxiliary files on that system and specifies local mailer flags appropriate for the Solaris version of /bin/mail. We'll include an OSTYPE() macro just after the VERSIONID() macro, dropping the .m4 filename extension.

The other things you may define in an OSTYPE file are documented in the README.

You may also want to create a domain file and use the DOMAIN() macro to collect site-wide definitions such as your site's UUCP or BITNET relay hosts. You should only put things in this file that are true for all the hosts in your domain. If you only have a single host, you may want to forego creating a domain file and keep this information in your m4 template.

The DOMAIN() macro takes a single argument, the name of a file in ../domain. For instance, DOMAIN(gonzo) would cause m4 to look for a file named ../domain/gonzo.m4. (Note that the .m4 extension is not included in the macro argument.)

WARNING: If you copy one of the UCB templates that includes a DOMAIN() macro, make sure you change that line to use your own domain file, or delete it.

A common feature to include in a domain file is the MASQUERADE_AS() macro, which causes all hosts using that sendmail.cf to masquerade as your mail hub. For example, if the Solaris 2.3 host we're building this configuration file for is one of many, all named sunX.gonzo.gov, the following line would cause all their outbound mail to be addressed as login@gonzo.gov, regardless of which workstation sent it:

This line could also be included in the m4 template if you don't want to create a domain file. Now the template looks like this, with the lines we've added or changed in boldface type:

To create the working sendmail.cf, run m4 on the template:

This creates a 600 line configuration file, which should be tested thoroughly before you install it. We will do just that in the next section, "Testing sendmail and sendmail.cf."

But first, considering that building a sendmail.cf file from the V8 macros is so easy, you may be wondering why I went on at such length about the guts of it. After all, if including an SMTP mailer is as easy as typing MAILER(smtp), why bother to learn the grungy details? The first answer is that someday you'll probably need them; something will go wrong and you'll have to figure out exactly why your sendmail isn't working the way it should. You can't do that unless you understand the details. A second answer is that you can't properly test your sendmail.cf unless you know what's going on under the simplified m4 gloss. Finally, although the V8 configuration file templates are easy to work with compared to those included with previous versions of sendmail, they're still not exactly on a par with plugging in a new toaster and shoving in a couple of slices of rye. If sendmail were a toaster, instead of a single lever it would have hundreds of complicated knobs and dials, a thick instruction manual, and despite your best efforts, would periodically burst into flames.

Testing sendmail and sendmail.cf

Before installing a new or modified sendmail.cf you must test it thoroughly. Even small, apparently innocuous changes can lead to disaster, and as mentioned in the introduction to this chapter, people get really irate when you mess up the mail system.

The first step in testing is to create a list of addresses that you know should work at your site. For instance, at gonzo.gov, an Internet site without UUCP connections, they know that the following addresses must work:

If gonzo.gov has a UUCP link, those addresses must also be tested. Other addresses to consider include the various kinds of aliases (e.g., postmaster, a :include: list, an alias that mails to a file and one that mails to a program), nonlocal addresses, source-routed addresses, and so on. If you want to be thorough, you can create a test address for each legal address format in RFC822.

Now that you've got your list of test addresses, you can use the -C and -bt options to see what happens. At a minimum you'll want to run the addresses through rulesets 3 and 0 to make sure they are routed to the correct mailer. An easy way to do this is to create a file containing the ruleset invocations and test addresses, and run sendmail on that. For instance, if the file addr.test contains the following lines:

you can test your configuration file test.cf by typing:

You may also want to follow one or more addresses through the complete rewriting process. For instance, if an address resolves to the smtp mailer and that mailer specifies R=21, you can test recipient address rewriting with 3,2,21,4 test_address.

If the sendmail.cf appears to work correctly so far, it's time to move on to sending some real letters. You can do so with a command like this:

The -v option tells sendmail to be verbose so you can see what's happening. Depending on whether the delivery is local or remote, you may see something as simple as joe... Sent, or an entire SMTP dialogue.

The -oQ/tmp tells sendmail to use /tmp as its queue directory. This is necessary because sendmail drops its super-user permissions when run with the -C option and can't write queue files into the normal mail queue directory. Because you are using the -C and -oQ options, sendmail also includes the following warning headers in the letter to help alert the recipient of possible mail forgery:

sendmail also inserts the header Apparently-to: joe because although you specified a recipient on the command line, there was none in the body of the letter. In this case the letter's body was taken from the empty file /dev/null, so there was no To: header. If you do your testing as the super-user, you can skip the -oQ argument, and sendmail won't insert the warning headers. You can avoid the Apparently-to: header by creating a file like this:

and using it as input instead of /dev/null.

The recipient should be you so you can inspect the headers of the letter for correctness. In particular, return address lines must include an FQDN for SMTP mail. That is, a header like From: joe@gonzo is incorrect since it doesn't include the domain part of the name, but a header like From: joe@gonzo.gov is fine.

You should repeat this testing for the same variety of addresses you used in the first tests. You may have to create special aliases that point to you for some of the testing.

The amount of testing you do depends on the complexity of your site and the amount of experience you have, but a beginning system administrator should test things very thoroughly, even for apparently simple installations. Remember the flaming toaster.

Installing sendmail and Friends

Once you're satisfied that your sendmail and sendmail.cf work, you must decide where to install them. The most popular approach is to put sendmail and its other files in the same place that your vendor puts its distributed sendmail files. The advantage of this approach is conformity; if someone else familiar with your operating system tries to diagnose a mail problem, he will know where to look.

However, some people prefer to install local programs separately from vendor programs, for several good reasons. First, operating system upgrades are usually easier when local modifications are clearly segregated from vendor programs. Second, some vendors, notably Sun Microsystems, release operating system patches that bundle together everything including the kitchen sink. If you naively install such a patch, you may inadvertently overwrite your V8 sendmail with your vendor's version, and it probably won't understand your V8 sendmail.cf.

Therefore, you may want to install sendmail in a subdirectory of /usr/local, the traditional directory for local enhancements to the vendor's operating system. The locations of sendmail's auxiliary files are given in sendmail.cf, so you can either leave them in the vendor's usual locations or install them in /usr/local and modify the sendmail.cf to match. If you want to change the compiled-in location of the configuration file, redefine the C preprocessor macro _PATH_SENDMAILCF in src/Makefile and recompile sendmail. For example, add the definition:

to the CFLAGS macro in the Makefile.

Once you've decided where the files should go, look at the Makefile you used to compile sendmail and see if it agrees. The easiest way is to use make's -n option to see what would have happened. The results look like this for the V8 distribution's Makefile.Solaris:

If this isn't what you want, modify the Makefile as necessary.

Note that the sendmail manual pages use the 4.4BSD mandoc macros, which your system probably doesn't have. You can ftp the mandoc macros from the host ftp.uu.net, in the directory /systems/unix/bsd-sources/share/tmac.

If your system doesn't have the /usr/ucb/install program, you can copy the new files instead, and use chown, chgrp and chmod to set the correct owner, group, and mode. However, if you're installing on top of your vendor's files, it's a good idea to first copy or rename them in case you ever need them again.

After you install sendmail and its auxiliary files, rebuild the aliases database by running sendmail -bi. You'll also need to kill and restart your sendmail daemon. If your vendor's system uses a frozen configuration file (sendmail.fc), remove it; V8 sendmail doesn't use one.

Modifying sendmail's Boot-Time Startup

In its SMTP server role, sendmail starts when the system boots and runs continuously. If you install it in a non-standard location like /usr/local, you'll have to modify your system's startup scripts. Even if you install it in the standard location, you should ensure that the default system startup is correct for V8 sendmail.

When SVR4 UNIX systems boot, they run a series of short shell scripts in the directories /etc/rcX.d, where the X corresponds to the system run level. For instance, shell scripts that bring the system to run level 2 are found in /etc/rc2.d.

However, SVR4 systems have many run levels and some software subsystems should be started in each of them. Therefore, the shell scripts in /etc/rcX.d are located in /etc/init.d and linked to the files in the /etc/rcX.d directories. The /etc/init.d directory is therefore the best place to look for your sendmail startup script.

The following example shows how to find how sendmail starts on a Solaris 2.3 system. Other SVR4 systems are similar:

In this case the grep output shows that the vendor starts sendmail with a script named sendmail because each line of the grep output is prefixed with that filename. Examine the script sendmail to see if any changes are necessary. This script expects sendmail to be located in /usr/lib. If you install V8 sendmail somewhere else, you'll have to modify the script to match, changing paths like /usr/lib/sendmail to /usr/local/lib/sendmail. If the command-line flags in the script aren't what you want, change those too.

Summary