Section 10.5. sendmail.cf Configuration Language

Every time sendmail starts up, it reads sendmail.cf. For this reason, the syntax of the sendmail.cf commands is designed to be easy for sendmail to parsenot necessarily easy for humans to read. As a consequence, sendmail commands are very terse, even by Unix standards.

The configuration command is not separated from its variable or value by any spaces. This "run together" format makes the commands hard to read. Figure 10-2 illustrates the format of a command. In the figure, a define macro command assigns the value wrotethebook.com to the macro D.

Figure 10-2. A sendmail.cf configuration command

Starting with version 8 of sendmail, variable names are no longer restricted to a single character. Long variable names, enclosed in braces, are now acceptable. For example, the define macro shown in Figure 10-2 could be written:

D{Domain}wrotethebook.com

Long variable names are easier to read and provide for more choices than the limited set provided by single character names. However, the old-fashioned, short variable names are still common. This terse syntax can be very hard to decipher, but it helps to remember that the first character on the line is always the command. From this single character you can determine what the command is and therefore its structure. Table 10-1 lists the sendmail.cf commands and their syntax.

Table 10-1. sendmail configuration commands
Command	Syntax	Function
Version Level	Vlevel[/vendor]	Specify version level.
Define Macro	Dxvalue	Set macro x to value.
Define Class	Ccword1[ word2] ...	Set class c to word1 word2 ....
Define Class	Fcfile	Load class c from file.
Set Option	Ooption=value	Set option to value.
Trusted Users	Tuser1[ user2 ...]	Trusted users are user1 user2 ....
Set Precedence	Pname=number	Set name to precedence number.
Define Mailer	Mname, {field=value}	Define mailer name.
Define Header	H[?mflag?]name:format	Set header format.
Set Ruleset	Sn	Start ruleset number n.
Define Rule	Rlhs rhs comment	Rewrite lhs patterns to rhs format.
Key File	Kname type [argument]	Define database name.

The following sections describe each configuration command in more detail.

10.5.1 The Version Level Command

The version level command is an optional command not found in all sendmail.cf files. You don't add a V command to the sendmail.cf file or change one if it is already there. The V command is inserted into the configuration file when it is first built from m4 macros or by the vendor.

The level number on the V command line indicates the version level of the configuration syntax. V1 is the oldest configuration syntax and V9 is the version supported by sendmail 8.11.3. Every level in between adds some feature extensions. The vendor part of the V command identifies if any vendor-specific syntax is supported. The default vendor value for the sendmail distribution is Berkeley.

The V command tells the sendmail executable the level of syntax and commands required to support this configuration. If the sendmail program cannot support the requested commands and syntax, it displays the following error message:

# /usr/lib/sendmail -Ctest.cf 

Warning: .cf version level (9) exceeds sendmail version 8.9.3+Sun functionality (8): 

Operation not permitted

This error message indicates that this sendmail program supports level 8 configuration files with Sun syntax extensions.^[9] The example was produced on a Solaris 8 system running the sendmail program that came with the operating system. In the example we attempted to read a configuration file that was created by the m4 macros that came with sendmail 8.11.3. The syntax and functions needed by the configuration file are not available in the sendmail program. To use this configuration file, we would have to compile a newer version of the sendmail program. See Appendix E for an example of compiling sendmail.

^[9] See Table 10-4 for Sun-specific syntax.

You will never change the values on a V command. You might, however, need to customize some D commands.

10.5.2 The Define Macro Command

The define macro command (D) defines a macro and stores a value in it. Once the macro is defined, it is used to provide the stored value to other sendmail.cf commands and directly to sendmail itself. This allows sendmail configurations to be shared by many systems simply by modifying a few system-specific macros.

A macro name can be any single ASCII character or a word enclosed in curly braces. Use long names for user-created macros. sendmail's own internal macros use most of the available letters and special characters as names. Additionally, a large number of long macro names are already defined. This does not mean that you won't be called upon to name a macro, but it does mean you will have to be careful that your name doesn't conflict with a name that has already been used. Internal macros are sometimes defined in the sendmail.cf file. Appendix E provides a complete list of sendmail's internal macros. Refer to that list when creating a user-defined macro to avoid conflicting with an internal macro. To retrieve the value stored in a macro, reference it as $x, where x is the macro name. Macros are expanded when the sendmail.cf file is read. A special syntax, $&x, is used to expand macros when they are referenced. The $&x syntax is only used with certain internal macros that change at runtime.

The code below defines the macros {our-host}, M, and Q. After this code executes, ${our-host} returns crab, $M returns wrotethebook.com, and $Q returns crab.wrotethebook.com. This sample code defines Q as containing the value of {our-host} (which is ${our-host}), plus a literal dot, plus the value of M ($M).

D{our-host}crab 

DMwrotethebook.com

DQ${our-host}.$M

If you customize your sendmail.cf file, it will probably be necessary to modify some macro definitions. The macros that usually require modification define site-specific information, such as hostnames and domain names.

10.5.2.1 Conditionals

A macro definition can contain a conditional. Here's a conditional:

 DX$g$?x ($x)$.

The D is the define macro command; X is the macro being defined; and $g says to use the value stored in macro g. But what does $?x ($x)$. mean? The construct $?x is a conditional. It tests whether macro x has a value set. If the macro has been set, the text following the conditional is interpreted. The $. construct ends the conditional.

Given this, the assignment of macro X is interpreted as follows: X is assigned the value of g; and if x is set, X is also assigned a literal blank, a literal left parenthesis, the value of x, and a literal right parenthesis.

So if g contains chunt@wrotethebook.com and x contains Craig Hunt, X will contain:

 chunt@wrotethebook.com (Craig Hunt)

The conditional can be used with an "else" construct, which is $|. The full syntax of the conditional is:

 $?x text1 $| text2 $.

This is interpreted as:

if ($?) x is set;
use text1;
else ($|);
use text2;
end if ($.).

10.5.3 Defining Classes

Two commands, C and F, define sendmail classes. A class is similar to an array of values. Classes are used for anything with multiple values that are handled in the same way, such as multiple names for the local host or a list of uucp hostnames. Classes allow sendmail to compare against a list of values instead of against a single value. Special pattern matching symbols are used with classes. The $= symbol matches any value in a class, and the $~ symbol matches any value not in a class. (More on pattern matching later.)

Like macros, classes can have single-character names or long names enclosed in curly braces. User-created classes use long names that do not conflict with sendmail's internal names. (See Appendix E for a complete list of the names that sendmail uses for its internal class values.) Class values can be defined on a single line, on multiple lines, or loaded from a file. For example, class w is used to define all of the hostnames by which the local host is known. To assign class w the values goober and pea, you can enter the values on a single line:

Cwgoober pea

Or you can enter the values on multiple lines:

Cwgoober

Cwpea

You can also use the F command to load the class values from a file. The F command reads a file and stores the words found there in a class variable. For example, to define class w and assign it all of the strings found in /etc/mail/local-host-names, use:^[10]

^[10] sendmail 8.11 uses /etc/mail/local-host-names to load class w. Earlier versions of sendmail used /etc/sendmail.cw. Only the name has changed; the file still contains a list of hostnames.

 Fw/etc/mail/local-host-names

You may need to modify a few class definitions when creating your sendmail.cf file. Frequently information relating to uucp, to alias hostnames, and to special domains for mail routing is defined in class statements. If your system has a uucp connection as well as a TCP/IP connection, pay particular attention to the class definitions. But in any case, check the class definitions carefully and make sure they apply to your configuration.

Here we grep the Linux sample configuration file for lines beginning with C or F:

% grep '^[CF]' generic-linux.cf 

Cwlocalhost 

Fw/etc/mail/local-host-names

CP.	

CO @ % !

C..

C[[

FR-o /etc/mail/relay-domains

C{E}root

CPREDIRECT

This grep shows that generic-linux.cf defines classes w, P, O, ., [, R, and E. w contains the host's alias hostnames. Notice that values are stored in w with both a C command and an F command. Unlike a D command, which overwrites the value stored in a macro, the commands that store values in class arrays are additive. The C command and the F command at the start of this listing add values to class w. Another example of the additive nature of C commands is class P. P holds pseudo-domains used for mail routing. The first C command affecting class P stores a dot in the array. The last command in the list adds REDIRECT to class P.

Class O stores operators that cannot be part of a valid username. The classes . (dot) and [ are primarily of interest because they show that variable names do not have to be alphabetic characters and that sometimes arrays have only one value. E lists the usernames that should always be associated with the local host's fully qualified domain name, even if simplified email addresses are being used for all other users. (More on simplified addresses later.) Notice that even a single character class name, in this case E, can be enclosed in curly braces.

Remember that your system will be different. These same class names may be assigned other values on your system, and are only presented here as an example. Carefully read the comments in your sendmail.cf file for guidance as to how classes and macros are used in your configuration.

Many class names are reserved for internal sendmail use. All internal classes defined in sendmail version 8.11 are shown in Appendix E. Only class w, which defines all of the hostnames the system will accept as its own, is commonly modified by system administrators who directly configure the sendmail.cf file.

10.5.4 Setting Options

The option (O) command is used to define the sendmail environment. Use the O command to set values appropriate for your installation. The value assigned to an option is a string, an integer, a Boolean, or a time interval, as appropriate for the individual option. All options define values used directly by sendmail.

There are no user-created options. The meaning of each sendmail option is defined within sendmail itself. Appendix E lists the meaning and use of each option, and there are plenty of them.

A few sample options from the generic-linux.cf file are shown below. The AliasFile option defines the name of the sendmail aliases file as /etc/mail/aliases. If you want to put the aliases file elsewhere, change this option. The TempFileMode option defines the default file mode as 0600 for temporary files created by sendmail in /var/spool/mqueue. The Timeout.queuereturn option sets the timeout interval for undeliverable mail, here set to five days (5d). These options show the kind of general configuration parameters set by the option command.

# location of alias file 

O AliasFile=/etc/mail/aliases 

# temporary file mode 

O TempFileMode=0600 

# default timeout interval

O Timeout.queuereturn=5d

The syntax of the option command shown in this example and in Appendix E was introduced in sendmail version 8.7.5. Prior to that, the option command used a syntax more like the other sendmail commands. The old syntax is: Oovalue, where O is the command, o is the single character option name, and value is the value assigned to the option. The options shown in the previous discussion, if written in the old syntax, would be:

# location of alias file 

OA/etc/aliases 

# temporary file mode 

OF0600 

# default timeout interval OT5d

If your configuration uses the old option format, it is dangerously out of date and should be upgraded. See Appendix E for information on downloading, compiling, and installing the latest version of sendmail.

Most of the options defined in the sendmail.cf file that comes with your system don't require modification. People change options settings because they want to change the sendmail environment, not because they have to. The options in your configuration file are almost certainly correct for your system.

10.5.5 Defining Trusted Users

The T command defines a list of users who are trusted to override the sender address using the mailer -f flag.^[11] Normally the trusted users are defined as root, uucp, and daemon. Trusted users can be specified as a list of usernames on a single command line or on multiple command lines. The users must be valid usernames from the /etc/passwd file.

^[11] Mailer flags are listed in Appendix E.

The most commonly defined trusted users are:

Troot 

Tdaemon

Tuucp

Do not modify this list. Additional trusted users increase the possibility of security problems.

10.5.6 Defining Mail Precedence

Precedence is one of the factors used by sendmail to assign priority to messages entering its queue. The P command defines the message precedence values available to sendmail users. The higher the precedence number, the greater the precedence of the message. The default precedence of a message is 0. Negative precedence numbers indicate especially low-priority mail. Error messages are not generated for mail with a negative precedence number, making low priorities attractive for mass mailings. Some commonly used precedence values are:

Pfirst-class=0 

Pspecial-delivery=100 

Plist=-30 

Pbulk=-60

Pjunk=-100

To specify a desired precedence, add a Precedence header to your outbound message. Use the text name from the P command in the Precedence header to set the specific precedence of the message. Given the precedence definitions shown above, a user who wanted to avoid receiving error messages for a large mailing could select a message precedence of -60 by including the following header line in the mail:

 Precedence: bulk

The five precedence values shown are probably more than you'll ever need.

10.5.7 Defining Mail Headers

The H command defines the format of header lines that sendmail inserts into messages. The format of the header command is the H command, optional header flags enclosed in question marks, a header name, a colon, and a header template. The header template is a combination of literals and macros that are included in the header line. Macros in the header template are expanded before the header is inserted in a message. The same conditional syntax used in macro definitions can be used in header templates, and it functions in exactly the same way: it allows you to test whether a macro is set and to use another value if it is not set.

The header template field can contain the $>name syntax that is used in rewrite rules. When used in a header template, the $>name syntax allows you to call the ruleset identified by name to process an incoming header. This can be useful for filtering headers in order to reduce spam email. We discuss rulesets, rewrite rules, the $>name syntax, and how these things are used later in this chapter.

The header flags often arouse more questions than they merit. The function of the flags is very simple. The header flags control whether or not the header is inserted into mail bound for a specific mailer. If no flags are specified, the header is used for all mailers. If a flag is specified, the header is used only for a mailer that has the same flag set in the mailer's definition. (Mailer flags are listed in Appendix E.) Header flags control only header insertion. If a header is received in the input, it is passed to the output regardless of the flag settings.

Some sample header definitions from the generic-linux.cf sample file are:

H?P?Return-Path: <$g>

HReceived: $?sfrom $s $.$?_($?s$|from $.$_)

H?D?Resent-Date: $a

H?D?Date: $a

H?F?Resent-From: $?x$x <$g>$|$g$.

H?F?From: $?x$x <$g>$|$g$.

H?x?Full-Name: $x

H?M?Resent-Message-Id: <$t.$i@$j>

H?M?Message-Id: <$t.$i@$j>

The headers provided in your system's sendmail.cf are sufficient for most installations. It's unlikely you'll ever need to change them.

10.5.8 Defining Mailers

The M commands define the mail delivery programs used by sendmail. The syntax of the command is:

 Mname, {field=value}

name is an arbitrary name used internally by sendmail to refer to this mailer. The name doesn't matter as long as it is used consistently within the sendmail.cf file to refer to this mailer. For example, the mailer used to deliver SMTP mail within the local domain might be called smtp on one system and ether on another system. The function of both mailers is the same; only the names are different.

There are a few exceptions to this freedom of choice. The mailer that delivers local mail to users on the same machine must be called local, and a mailer named local must be defined in the sendmail.cf file. Three other special mailer names are:

prog: Delivers mail to programs.
*file*: Sends mail to files.
*include*: Directs mail to :include: lists.

Of these, only the prog mailer is defined in the sendmail.cf file. The other two are defined internally by sendmail.

Despite the fact that the mailer name can be anything you want, it is usually the same on most systems because the mailers in the sendmail.cf file are built by standard m4 macros. In the linux.mc configuration created earlier, the MAILER(local) macro created the prog and local mailers, and the MAILER(smtp) macro created the smtp, esmtp, smtp8, dsmtp, and relay mailers. Every system you work with will probably have this same set of mailer names.

The mailer name is followed by a comma-separated list of field=value pairs that define the characteristics of the mailer. Table 10-2 shows the single-character field identifiers and the contents of the value field associated with each of them. Most mailers don't require all of these fields.

Table 10-2. Mailer definition fields
Field	Meaning	Contents	Example
P	Path	Path of the mailer	P=/bin/mail
F	Flags	sendmail flags for this mailer	F=lsDFMe
S	Sender	Rulesets for sender addresses	S=10
R	Recipient	Rulesets for recipient addresses	R=20
A	Argv	The mailer's argument vector	A=sh -c $u
E	Eol	End-of-line string for the mailer	E=\r\n
M	Maxsize	Maximum message length	M=100000
L	Linelimit	Maximum line length	L=990
D	Directory	prog mailer's execution directory	D=$z:/
U	Userid	User and group ID used to run mailer	U=uucp:wheel
N	Nice	nice value used to run mailer	N=10
C	Charset	Content-type for 8-bit MIME characters	C=iso8859-1
T	Type	Type information for MIME errors	T=dns/rfc822/smtp

The Path (P) fields contain either the path to the mail delivery program or the literal string [IPC]. Mailer definitions that specify P=[IPC] use sendmail to deliver mail via SMTP.^[12] The path to a mail delivery program varies from system to system depending on where the systems store the programs. Make sure you know where the programs are stored before you modify the Path field. If you use a sendmail.cf file from another computer, make sure that the mailer paths are valid for your system. If you use m4 to build the configuration, the path will be correct.

^[12] [TCP] and [IPC] are used interchangeably, both in the P field and in the A field.

The Flags (F) field contains the sendmail flags used for this mailer. These are the mailer flags referenced earlier in this chapter under "Defining Mail Headers," but mailer flags do more than just control header insertion. There are a large number of flags. Appendix E describes all of them and their functions.

The Sender (S) and the Recipient (R) fields identify the rulesets used to rewrite the sender and recipient addresses for this mailer. Each ruleset is identified by its number. We'll discuss rulesets more later in this chapter, and we will refer to the S and R values when troubleshooting the sendmail configuration.

The Argv (A) field defines the argument vector passed to the mailer. It contains, among other things, macro expansions that provide the recipient username (which is $u),^[13] the recipient hostname ($h), and the sender's From address ($f). These macros are expanded before the argument vector is passed to the mailer.

^[13] In the prog mailer definition, $u actually passes a program name in the argument vector.

The End-of-line (E) field defines the characters used to mark the end of a line. A carriage return and a line feed (CRLF) is the default for SMTP mailers.

Maxsize (M) defines, in bytes, the longest message that this mailer will handle. This field is used most frequently in definitions of UUCP mailers.

Linelimit (L) defines, in bytes, the maximum length of a line that can be contained in a message handled by this mailer. This mailer field was introduced in sendmail V8. Previous versions of sendmail limited lines to 80 characters because this was the limit for SMTP mail before MIME mail was introduced.

The Directory (D) field specifies the working directory for the prog mailer. More than one directory can be specified for the directory field by separating the directory paths with colons. The example in Table 10-2 tells prog to use the recipient's home directory, which is the value returned by the internal macro $z. If that directory is not available, it should use the root (/) directory.

The Userid (U) field is used to specify the default user and the group ID used to execute the mailer. The example U=uucp:wheel says that the mailer should be run under the user ID uucp and the group ID wheel. If no value is specified for the Userid field, the value defined by the DefaultUser option is used.

Use Nice (N) to change the nice value for the execution of the mailer. This allows you to change the scheduling priority of the mailer. This is rarely used. If you're interested, see the nice manpage for appropriate values.

The last two fields are used only for MIME mail. Charset (C) defines the character set used in the Content-type header when an 8-bit message is converted to MIME. If Charset is not defined, the value defined in the DefaultCharSet option is used. If that option is not defined, unknown-8bit is used as the default value.

The Type (T) field defines the type information used in MIME error messages. MIME-type information defines the mailer transfer agent type, the mail address type, and the error code type. The default is dns/rfc822/smtp.

10.5.8.1 Some common mailer definitions

The following mailer definitions are from generic-linux.cf:

Mlocal,   P=/usr/bin/procmail, F=lsDFMAw5:/|@qSPfhn9,

          S=EnvFromL/HdrFromL, R=EnvToL/HdrToL, T=DNS/RFC822/X-Unix,

          A=procmail -Y -a $h -d $u

Mprog,    P=/bin/sh, F=lsDFMoqeu9, S=EnvFromL/HdrFromL,

          R=EnvToL/HdrToL, D=$z:/, T=X-Unix/X-Unix/X-Unix,

          A=sh -c $u

Msmtp,    P=[IPC], F=mDFMuX, S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP,

          E=\r\n, L=990, T=DNS/RFC822/SMTP, A=TCP $h

Mesmtp,   P=[IPC], F=mDFMuXa, S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP,

          E=\r\n, L=990, T=DNS/RFC822/SMTP, A=TCP $h

Msmtp8,   P=[IPC], F=mDFMuX8, S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP,

          E=\r\n, L=990, T=DNS/RFC822/SMTP, A=TCP $h

Mdsmtp,   P=[IPC], F=mDFMuXa%, S=EnvFromSMTP/HdrFromSMTP, R=EnvToSMTP,

          E=\r\n, L=990, T=DNS/RFC822/SMTP, A=TCP $h

Mrelay,   P=[IPC], F=mDFMuXa8, S=EnvFromSMTP/HdrFromSMTP, R=MasqSMTP,

          E=\r\n, L=2040, T=DNS/RFC822/SMTP,A=TCP $h

This example contains the following mailer definitions:

A definition for local mail delivery, always called local. This definition is required by sendmail.
A definition for delivering mail to programs, always called prog. This definition is found in most configurations.
A definition for TCP/IP mail delivery, here called smtp.
A definition for an Extended SMTP mailer, here called esmtp.
A definition for an SMTP mailer that handles unencoded 8-bit data, here called smtp8.
A definition for on-demand SMTP, here called dsmtp.
A definition for a mailer that relays TCP/IP mail through an external mail relay host, here called relay.

A close examination of the fields in one of these mailer entries, for example the entry for the smtp mailer, shows the following:

Msmtp: A mailer, arbitrarily named smtp, is being defined.
P=[IPC]: The path to the program used for this mailer is [IPC], which means delivery of this mail is handled internally by sendmail.
F=mDFMuX: The sendmail flags for this mailer say that this mailer can send to multiple recipients at once; that Date, From, and Message-Id headers are needed; that uppercase should be preserved in hostnames and usernames; and that lines beginning with a dot have an extra dot prepended. Refer to Appendix E for more details.
S =EnvFromSMTP/HdrFromSMTP: The sender address in the mail "envelope" is processed through ruleset EnvFromSMTP, and the sender address in the message is processed through ruleset HdrFromSMTP. More on this later.
R= EnvToSMTP: All recipient addresses are processed through ruleset EnvToSMTP.
E=\r\n: Lines are terminated with a carriage return and a line feed.
L=990: This mailer will handle lines up to 990 bytes long.
T=DNS/RFC822/SMTP: The MIME-type information for this mailer says that DNS is used for hostnames, RFC 822 email addresses are used, and SMTP error codes are used.
A=TCP $h: The meaning of each option in an argument vector is exactly as defined on the manpage for the command; see the local mailer as an example. In the case of the smtp mailer, however, the argument refers to an internal sendmail process designed to deliver SMTP mail over a TCP connection. The macro $h is expanded to provide the recipient host ($h) address.

Despite this long discussion, don't worry about mailer definitions. The configuration file that is built by m4 for your operating system contains the correct mailer definitions to run sendmail in a TCP/IP network environment. You shouldn't need to modify any mailer definitions.