sendmail, 4th Edition

Chapter 16. Configuration File Overview

The sendmail configuration file (usually called sendmail.cf, but for MSP submission, called submit.cf) provides all the central information that controls the sendmail program’s behavior. Among the key pieces of information provided are the following:

The location of all the other files that sendmail needs to access and the location of all the directories in which sendmail needs to create and remove files.
The definitions that sendmail uses in rewriting addresses. Some of those definitions can come from files, which are also specified.
The mail header lines that sendmail should modify, pass through, and/or augment.
The rules and sets of rules that sendmail uses for transforming mail addresses (and aliases for those addresses) into usable information, such as which delivery agent to use and the correct form of the address to use with that delivery agent.
The external programs through which sendmail should filter messages to detect and eliminate spam and viruses.

The location of the sendmail.cf (and submit.cf) file is compiled into sendmail. Beginning with V8.10, sendmail expects to find its configuration file in the /etc/mail directory. Prior to V8.10, the configuration file was usually found in either the /etc, the /usr/lib, or the /etc/mail directory. (See _PATH... on page 131 for a description of how to change the default.) We recommend that the standard /etc/mail location be used unless you have a compelling reason to do otherwise. A nonstandard location can, for example, make operating system upgrades difficult.

The configuration file is read and parsed by sendmail every time it starts up. Because sendmail is run every time electronic mail is sent, its configuration file is designed to be easy for sendmail to parse rather than easy for humans to read.

Overall Syntax

The sendmail.cf file is line-oriented, with one configuration command per line. Each configuration command consists of a single letter^[233] that must begin a line. Each letter is followed by other information as required by the purpose of the particular command.

In addition to commands, the configuration file can also have lines that begin with a # to form a comment line, or with a tab or space character to form a continuation line. A list of all legal characters that can begin a line in the configuration file is shown in Table 16-1.

Table 16-1. sendmail.cf configuration commands

Command	§	Version	Description
`#`	Comments on page 579	All	A comment line, ignored.
`space`	Continuation Lines on page 580	All	Continue the previous line.
`tab`	Continuation Lines on page 580	All	Continue the previous line.
`C`	Class Configuration Commands on page 854	All	Define a class macro.
`D`	Configuration-File Definitions on page 787	All	Define a sendmail macro.
`E`	The E Configuration Command on page 156	V8.7 and above	Environment for agents.
`F`	Class Configuration Commands on page 854	All	Define a class macro from a file or a pipe.
`H`	Overview on page 1120	All	Define a header.
`K`	The K Configuration Command on page 882	V8.1 and above	Create a keyed map entry.
`L`		Obsolete	Extended load average.
`M`	The M Configuration Command on page 711	All	Define a mail delivery agent.
`O`	Configuration File Options on page 952	All	Define an option.
`P`	Precedence on page 1148	All	Define delivery priorities.
`Q`	The Q Configuration Command on page 409	V8.12 and above	Declare queue groups.
`R`	The R Configuration Command on page 649	All	Define a transformation rule.
`S`	The S Configuration Command on page 683	All	Declare a rule-set start.
`T`	Declare trusted users (ignored V8.1 through V8.6) on page 174	All	Declare trusted users (ignored V8.1-V8.6).
`V`	The V Configuration Command on page 580	V8.1 and above	Version of configuration file.
`X`	The X Configuration Command on page 1173	V8.12 and above	Define a mail filter for use.

Most configuration commands are so complex that each requires a chapter or two of its own. A few, however, are simple. In this chapter, we will describe the simple ones: comments, continuation lines, and the V (version) command.

Comments

Comments provide you with the documentation necessary to maintain the configuration file. Because comments slow down sendmail by only a negligible amount, and only at startup, it is better to overcomment than to undercomment.

Blank lines and lines that begin with a # character are considered comments and are ignored. A blank line is one that contains no characters at all (except for its terminating newline). Indentation characters (spaces and tabs) are invisible and can turn an apparently blank line into an empty-looking line, which is not ignored:

# text            ← a comment
tabtext            ← a continuation line
            ← a blank line
tab            ← an "empty-looking line"

Except for two special cases, pre-V8 comments occupy the entire line. The two special cases are the R and S configuration commands. The R command is composed of three tab-separated fields, the third field being a comment that does not require a leading # character:

Rlhs      rhs       comment

The pre-V8.7 S command looks only for a number following it and ignores everything else, so it can also be followed by a comment:

S3 this is a comment

Prior to V8, no other commands allow comments to follow on the same line:

CWlocalhost mailhost  # This won't work prior to V8

V8 Comments

Beginning with V8 sendmail, all lines of configuration files of version levels 3 and above (The V Configuration Command on page 580) can have optional trailing comments. That is, all text from the first # character to the end of the line is ignored. Any whitespace (space or tab characters) leading up to the # is also ignored:

CWlocalhost mailhost  # This is a comment
                    ↑
                    from here to end of line ignored

To include a # character in a line under V8 sendmail, precede it with a backslash:

DM16\#megs

Note that you do not need to escape the # in the $# operator. The $ has a higher precedence, and $# is interpreted correctly.

Continuation Lines

A line that begins with either a tab or a space character is considered a continuation of the preceding line. Internally, such continuation lines are joined to the preceding line, and the newline character of that preceding line is retained. Thus, for example:

DZzoos
       lions and bears
↑
line begins with a tab character

is internally joined by sendmail to form:

DZzoos\n       lions and bears
       ↑
       newline and tab retained

Both the newline (\n) and the tab are retained. When such a joined line is later used (as in a header), the joined line is split at the newline and prints as two separate lines again.

The V Configuration Command

The V configuration command was added to V8 sendmail to prevent old versions of configuration files from breaking when used with V8 sendmail. The syntax for the V configuration command looks like this:

Vlevel                  ← V8.1 through V8.5
Vlevel/vendor           ← V8.6 and above

We describe the level and vendor parts in the next two sections.

The V Configuration Command’s Level Part

The level is a positive integer. If level is higher than the maximum allowed for the current version, sendmail prints the following warning and accepts the value:

Warning: .cf version level (lev) exceeds sendmail version ver functionality
(max)

If level is less than 0 or if the V configuration command is omitted, the default level is 0.

The effects of the various version levels are relatively minor. As sendmail continues to develop, they might become more pronounced. Currently, the version levels are as follows:

0: The check for a valid shell in /etc/shells is ignored (The /etc/shells File on page 180).
0 through 1: MX records are looked up with the RES_DEFNAMES and RES_DNSRCH cleared. The high bit is always stripped from the body of every mail message.
2 and above: The sendmail program automatically adds a -a. to the "host host" database map ($[ and $]: A Special Case on page 895) declaration, if that database map isn’t declared in the configuration file. RES_DEFNAMES and RES_DNSRCH are not turned off as they were for older versions. Rule set 5 (The localaddr Rule Set 5 on page 700) behavior is enabled.
0 through 2: Set the UseErrorsTo option (UseErrorsTo on page 1115) to true automatically.
2 and above: Automatically set the $w sendmail macro ($w on page 850) to be the short name instead of the fully qualified local hostname ($j, $j on page 830, still contains the fully qualified name and $m, $m on page 833, the local domain).
3 and above: You can use the V8 form of comments.
0 through 5: For V8.7 and above sendmail, level 5 or lower causes the F=5Aw:|/@ flags (Delivery Agent F= Flags on page 759) to automatically be set for the local delivery agent (The local delivery agent on page 726) and the F=o flag (F=o on page 777) to automatically be set for the prog (The prog delivery agent on page 727) and *file* (*file* and *include* on page 725) delivery agents.
0 through 5: Looking up MX records with HasWildcardMX listed with the ResolverOptions option (ResolverOptions on page 1080) causes RES_QUERY to be used in place of RES_SEARCH. Defaults the ColonOkInAddr option (ColonOkInAddr on page 986) to false.
0 through 6: Set the SmtpGreetingMessage option (SmtpGreetingMessage on page 1093) with the value of $e ($e on page 823) if $e has a value. Set the OperatorChars option (OperatorChars on page 1062) with the value of $o ($o on page 839) if $o has a value.
7: The version shipped with V8.8 sendmail. Added that a version 6 or less causes the F=q flag (F=q on page 778) for the local (The local delivery agent on page 726) prog (The prog delivery agent on page 727) and *file* (*file* and *include* on page 725) delivery agents to be automatically set.
8: The version shipped with V8.9 sendmail. Added the first antispam rule sets to the configuration file.
9: Beginning with V8.10 sendmail, a version of 9 or higher causes the parenthetical comment in rules to be retained (Rules Are Treated Like Addresses on page 651).
10: The version shipped with V8.12 sendmail. Added the FEATURE(authinfo) (FEATURE(authinfo) on page 616). Added -T<TMPF> for access database (Create the access Database on page 278) temporary lookup errors, and delivery agents no longer need numbered rule sets (R= on page 751 and S= on page 753). Added support for queue groups (The Q Configuration Command on page 409).

The V Configuration Command’s Vendor Part

Beginning with V8.6 sendmail, the level for the version command can be followed by the identity of the vendor. The form of that declaration looks like this:

Vlevel/vendor           ← V8.6 and above

The / must immediately follow the level with no intervening space. There can be arbitrary space between the / and the vendor. The string that is the vendor specification is case-insensitive and can be any one of the following:

Sendmail: This is the commercial version of sendmail sold by Sendmail, Inc.
Berkeley: This is a configuration file based on the BSD distribution and is the one you get when you build and install from the source. As of V8.14, this declaration does nothing. If you use this configuration file with another vendor’s version of sendmail, the Berkeley tells the other version that you are using a configuration file based on the open source.
Sun: This is a configuration file intended for use with Sun’s release of sendmail. If it is declared and if you are running Sun’s sendmail, Sun-specific enhancements become available to you. If you are not running Sun’s sendmail, an error is printed.
HP, IBM, DEC, etc.: Beginning with V8.12, other vendors, such as IBM, now add their own vendor designation to the V configuration command.

If any unrecognized string appears in the vendor part, or if the vendor name is absent but the slash is present, sendmail will print the following error and ignore that vendor declaration:

file.cf: line num: invalid V line vendor code: "bad or missing vendor name here"

Note that vendors other than those shown might have customized their sendmail too, so this might not be a complete list.^[234]

Pitfalls

Avoid accidentally creating an empty-looking line (one that contains only invisible space and tab characters) in the sendmail.cf file when you really intend to create a blank line (one that contains only the newline character). The empty-looking line is joined by sendmail to the line above it and is likely to cause mysterious problems that are difficult to debug. One way to find such lines is to run a command such as the following, where there is a single space between the ^ and the dot:
```
% grep '^ .*$' /etc/mail/sendmail.cf
```
Beginning with V8 sendmail, it is a mistake to edit your configuration file directly because that file is generated from m4 source. The correct way to change your configuration file is to edit the m4 source and generate a new configuration file from that source (see Configure with m4 on page 587).
Avoid the temptation to devise tools that parse the sendmail configuration file. Future versions of sendmail might dramatically change the internals of the configuration file and might obsolete your work.
The listening daemon and the submission msp sendmail use two different configuration files (e.g., sendmail.cf and submit.cf ). Unless you specify a specific configuration file with -C (-C on page 238), the -Am and -Ac switches (-A on page 231) determine which of the two configuration files is used.

^[233]^* A quick bit of trivia: initially, there was almost nothing in the configuration file except R rules (and there was only one rule set). Eric recalls adding M and O fairly quickly. Commands such as K and V came quite late.

^[234]^* Vendors that enhance their sendmail are strongly encouraged to use a new vendor code.

Previous Chapter

II. Configuration Reference

Next Chapter

17. Configure sendmail.cf with m4

Table of Contents for sendmail, 4th Edition