sendmail Configuration File

This section describes the configuration file in detail, including hints for writing your own file.

The syntax of the configuration file is reasonably easy to parse, as parsing can be done every time sendmail starts. Unfortunately, this syntax sacrifices readability.

sendmail uses single letters for several different functions:

• Command-line flags

• Configuration options

• Queue-file line types

• Configuration-file line types

• Mailer field names

• Mailer flags

• Macro names

• Class names

The following sections provide an overview of the configuration file and details of its semantics. Appendix A, sendmail Configuration File a copy of the default main.cf file.

Purpose of the sendmail Configuration File

The sendmail configuration file has three parts:

• Definitions of symbols, classes, options, and parameters

• Definitions of mailers and delivery programs

• Rule sets that determine the rules for rewriting addresses

You define symbols, classes, options, and parameters to set up the environment for sendmail, setting the options and defining a few critical macros.

You define your mailers and delivery programs so that sendmail uses the correct protocols and interacts with the correct delivery programs.

You define rewriting rules, grouped into rule sets, to transform addresses from one form to another. In general, each rule in a rule set is applied to a particular address. An address might be rewritten several times within a rule set.

Table 3-5 lists the seven standard rule sets, applied in the order shown in.

Rule set 0 must resolve to the internal form, which is in turn used as a pointer to a mailer descriptor. The mailer descriptor describes the interface requirements of the mailer.

Rewriting names in the message is typically done in two phases. The first phase uses rule set 3 to map names in any format into a local-address@host-domain form. The second phase converts map names to the canonical form into the syntax appropriate for the receiving mailer. sendmail rewrites names in three subphases. Rule sets 1 and 2 are applied to all sender and recipient names respectively. Mailer-specific rule sets are specified during mailer definition. Finally, rule set 4 is applied to do any conversion to external form.

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

< > ( ) " \

Use the RFC 822 special characters < > ( ) " \ only for their designated purposes. Information between parentheses, (), is reserved for comments or personal names. Information between angle brackets, <>, is reserved for local-address@host-domain addresses.

sendmail Configuration File Syntax

The configuration file is organized as a series of lines, each of which begins with a single character defining the semantics for the rest of the line. Lines beginning with a space or a tab are continuation lines (although the semantics are not well defined in many places). Blank lines and lines beginning with a pound sign (#) are ignored.

D and L-Define Macro

Macros are named with a single character. Although a macro can be defined with any character from the complete ASCII set, use only uppercase letters for macros that you define. However, do not use characters like M, R, L, G, and V that are already used by sendmail. Lowercase letters and special symbols are used internally.

You can define macros in two ways:

• Use D to assign the value directly specified.

• Use L to assignsx the value looked up in the sendmailvars database (either the NIS+ sendmailvars table or /etc/mail/sendmailvars file). The L command is classified as a Sun uncommitted interface.

The syntax for D macro definitions is:

DXval

where X is a letter defining the macro and val is the value it should have. No spaces are allowed. You can insert macros in most places using the escape sequence $X.

Here are examples of D macro definitions from the configuration file:

DRmailhost
Dmeng.acme.com

The variable R is set to contain the value mailhost and the internal variable m is set to contain the value eng.acme.com.

The m macro defines the mail domain. If it is not defined, the name service domain name is used with the first component stripped. For example, ecd.east.acme.com becomes east.acme.com. An even more flexible way to define the mail domain name is to use an L macro definition, as shown in the following example.

The syntax for an L macro definition is:

LXsearch-key

where X is the name of the macro and search-key is looked up in the sendmailvars database. The value found in the entry located by the search key is assigned to X.

Here is an example of an internal L macro definition from the configuration file:

Lmmaildomain

The variable m is set to the value found in the sendmailvars database using maildomain as the search key. If the entry in the sendmailvars database appears as follows:

maildomain        eng.acme.com

the value of m becomes eng.acme.com.

sendmail uses the sendmailvars entry in the /etc/nsswitch.conf file to determine the order in which to search the name space and /etc/mail/sendmailvars file.

C, F, and G-Define Classes

You can define classes of words to match the left-hand side of address-rewriting rules. For example, you might create a class of all local names for this site so that you can eliminate attempts to send mail to yourself.

You can give classes names from the set of uppercase letters. Lowercase letters and special characters are reserved for system use.

You can define classes in three ways:

• Use C to assign the values directly specified.

• Use F to read in the values from another file or from another command.

• Use G to assign the values looked up in the sendmailvars database (either the NIS+ sendmailvars table or /etc/mail/sendmailvars file). The G command is classified as a Sun uncommitted interface.

Table 3-6 shows the syntaxes of the different forms of class definition.

The first form simply assigns the named words to match the class X. This example assigns the names monet and ucbmonet to class H:

CHmonet ucbmonet

The second form reads words from the file into the class X, for example, FC /.rhosts. The pattern argument to the FC class is used with scanf to read from the file; otherwise, the first word from each line is used.

The third form executes the given command and reads the elements of the class from standard output of the command. For example:

FC | awk '{print $2}' /etc/hosts

The fourth form reads the elements of the class from the entry in the sendmailvars database pointed to by the search key. For example:

GVuucp-list

gets the definition of class V from the uucp-list entry in the sendmailvars database.

If the entry in the sendmailvars database appears as follows:

uucp-list        sunmoon hugo comic

the value of V becomes sunmoon hugo comic.

sendmail uses the sendmailvars entry in the /etc/nsswitch.conf file to determine the order in which to search the name space and /etc/mail/sendmailvars file.

You could split class definitions among multiple lines. For example, the following:

CHmonet ucbmonet

is equivalent to:

CHmonet
CHucbmonet 

O-Set Option

You can set several options (not to be confused with mailer flags or command-line arguments) from a configuration file. Options are also represented by single characters. The syntax of this line is:

Oc value

This sets option c to value. Depending on the option, value may be a string, an integer, a Boolean (with legal values t, T, f, or F--the default is "true''), or a time interval. See "Configuration Options to sendmail" for the list of options.

P-Precedence Definitions

You can define values for the Precedence: field using the P control line. The syntax of this field is:

Pname=num

When the name is found in a Precedence: field, the message class is set to num. Higher numbers mean higher precedence. Numbers less than zero have the special property that error messages are not returned. The default precedence is 0 (zero). For example:

Pfirst-class=0
Pspecial-delivery=100
Pjunk=-100

T-Define Trusted Users

This configuration line has been deleted. It will be accepted but will be ignored.

H-Define Header

The H line defines the format of the header lines. The syntax of this line is:

H[c ?c mflagsc ?]c hnamec :c htemplate

Continuation lines in this specification are inserted directly into the outgoing message. The htemplate is macro-expanded before it is inserted into the message. If the expansion is empty, the header line is not included. If the mflags (surrounded by question marks) are specified, at least one of the specified flags must be stated in the mailer definition before this header can be automatically output. If one of these headers is in the input, it is directed to the output regardless of these flags.

R and S-Rewriting Rules

Address parsing is done according to the rewriting rules, a simple pattern-matching and replacement system. sendmail scans the set of rewriting rules looking for a match on the left-hand side (LHS) of the rule. When a rule matches, the name is replaced by the right-hand side (RHS) of the rule.

There are several sets of rewriting rules. Some of the rewriting sets are used internally and must have specific semantics. Other rewriting sets do not have specifically assigned semantics and can be referenced by the mailer definitions or by other rewriting sets.

For example:

Sn

sets the current rule set being collected to n. If you begin a rule set more than once, the new definition overwrites the old definition.

R is used to define a rule in the rule set. The syntax of the R line is:

Rlhs		rhs	comments

The lhs is a pattern that is applied to the input. If it matches, the input is rewritten to the rhs. The comments are ignored.

Here is an example of how a rule definition might look:

# handle "from:<>" special caseR<>			$@@				turn into magic token

The fields must be separated by at least one tab character; you can use embedded spaces in the fields.

M-Define Mailer

Programs and interfaces to mailers are defined on this line. The format is:

Mc name, c
{c field=value}*

where name is the name of the mailer (used in error messages) and the field=value pairs define attributes of the mailer. Table 3-7 shows the fields.

V-Define Configuration File Version

The new version of sendmail (version 8) includes a new configuration option which defines the version of the sendmail.cf file. This will allow older configuration files to be used with Version 8 sendmail. You can set the version level to values between 0 and 5. You can also define the vendor. Either Berkeley or Sun are valid vendor options. If the V option is not defined in the configuration file the default setting is V1/Sun. If a version level is specified but no vendor is defined, then Berkeley is the used as the default vendor setting. Table 3-8 lists some of the valid options.

If Sun is defined as the vendor, then only V0 and V1 may be used to define the level.

Address-Rewriting Rules

This section describes the details of rewriting rules and mailer descriptions.

Special Macros, Conditionals

Special macros are referenced with the construct $x, where x is the name of the macro to be matched (LHS) or inserted (RHS). Lowercase letters are reserved for special semantics, and some special characters are reserved to provide conditionals.

The macros shown in Table 3-9 must be defined to transmit information into sendmail.

In the SunOS 4.x releases, $w is the fully qualified hostname. In the Solaris 2.6 release, $w is the short version of the hostname.

For example:

De$j Sendmail $v ready at $b
DnMAILER-DAEMON
DlFrom $g $d
Do.:%@!^=/
Dq$g$?x ($x)$.
Dj$H.$D

You should not need to change any of these macros except under unusual circumstances. For example, you might want to change the first line, which defines the banner for security. You might want to change the last two lines to make several hosts look like one host.

An acceptable alternative for the $q macro is:

$?x$x $.<$g>

This entry corresponds to the following two formats:

doe@acme.com (John Doe)
John Doe <doe@acme.com>

Some macros are defined by sendmail for use in mailer arguments or for other contexts.Table 3-10 shows these macros.

You can use three types of dates. The $a and $b macros are in ARPANET format; $a is the time as extracted from the Date: line of the message (if there was one), and $b is the current date and time (used for postmarks). If no Date: line is found in the incoming message, $a is also set to the current time. The $d macro is equivalent to the $a macro in UNIX (ctime) format.

The $f macro is the ID of the sender as originally determined; for a message mailed to a specific host, the $g macro is set to the name of the sender relative to the recipient. For example, suppose the sender eric sends a message to bollard@matisse from the machine ucbarpa. The value of $f will be eric and the value of $g will be eric@ucbarpa.

The $x macro is set to the full name of the sender, which can be determined in several ways. It can be passed as a flag to sendmail (from the value of the Full-name: line in the header or use the comment field of a From: line). If the name can't be determined from the Full-name: or From: lines, and if the message is being originated locally, the full name is looked up in the /etc/passwd file. It can also be read from the name environment variable.

When a message is sent, the $h, $u, and $z macros are set to the host, user, and home directory (if local) of the recipient. The first two macros are set from the $@ and $: part of the rewriting rules respectively.

The $p and $t macros are used to create unique strings (for example, for the Message-Id: field). The $i macro is set to the queue ID on this host; if put into the time stamp line, it can be useful for tracking messages. The $v macro is set to be the version number of sendmail; this is normally put in time stamps and is extremely useful for debugging. It can, however, be a security risk if a publicized bug with the current version can be exploited. The $w macro is set to the primary name of this host, as given by gethostname() and gethostbyname(). The $c field is set to the "hop count"; that is, the number of times this message has been processed, which can be determined by counting the time stamps in the message.

The $r and $s fields are set to the protocol used to communicate with sendmail and the sending host name.

You can specify conditionals by using the syntax:

$?x text1 $| text2 $

This example inserts text1 if the macro $x is set, and text2 otherwise. The else (c $|) clause can be omitted.

Special Classes

The class $=w is the set of all names by which this host is known. It can be used to delete local host names. The class $=m is set to the domain name.

Left-Hand Side of Address-Rewriting Rules

The left-hand side of rewriting rules contains a pattern. Normal words are matched directly. Dollar signs introduce "metasymbols," which match items other than simple words, like macros or classes. Table 3-11 shows the metasymbols.

If any of the patterns match, it is assigned to the symbol $n for replacement on the right-hand side, where n is the index in the LHS. For example, the LHS rules can be applied to this input:

$-:$+

JUPITER:eric

The rule will match, and the values passed to the RHS will be:

$1	JUPITER

$2	eric

Solaris-Specific Rules

Several special rules have been added to work with the name space. These rules are not generic to sendmail, so can only be used on systems running the Solaris software.

The special form $%y matches any host name in the hosts information in the name space. Either local or remote hosts can be matched using this rule. It does a most-to-least multitoken match, so it can handle fully qualified host names as well as a short local host name.

The $%x form matches MX records through DNS. This will succeed even if the A-record does not exist in the DNS database.

The $%l matches any fully qualified host in the local domain. If NIS or local files are being used, this means that the host name in the name space must include the local domain name or DNS forwarding has to be turned on. The NIS+ name space will qualify the host name appropriately, without any changes.

To use $%l in a NIS environment in which DNS forwarding cannot be set up and the name space cannot be changed to use fully qualified host names, add the following line into the configuration file:

DAhosts.byname

and replace all occurrences of %l with %A. You can use any non-conflicting letter in place of the A. This will turn off the need to look up fully qualified names, as long as the target host can be resolved to an IP address and it is a single token name. All resolved addresses are assumed to be local, so make sure that the name space does not contain any single-token host entries that are external to the mail domain.

Right-Hand Side of Address Rewriting Rules

When the left-hand side of a rewriting rule matches, the input is replaced by the right-hand side. Tokens are copied directly from the right-hand side, unless they begin with a dollar sign, in which case they are treated as macros and expanded.

Table 3-12 shows the metasymbols for more complicated substitutions.

The $n (n being a digit) syntax substitutes the corresponding value from a $+, $-, $*, or $~x match on the LHS. It may be used anywhere.

The $>n syntax substitutes the remainder of the line as usual and then passes it to rule set n. The final value of rule set n then becomes the substitution for this rule (like a procedure or function call).

Only use the $# syntax in rule set 0. Evaluation of the rule set stops immediately, and signals are sent to sendmail that the name has completely resolved. The complete syntax is:

$#mailer$@host$:user

This specifies the {mailer, host, user} triple necessary to direct the mailer. More processing may then take place, depending on the mailer. For example, local names are aliased.

A right-hand side may also be preceded by a $@ or a $: to control evaluation. A $@ prefix returns the remainder of the right-hand side as the value. A $: prefix terminates the rule immediately, but the rule set continues. Thus it can be used to limit a rule to one application. Neither prefix affects the result of the right-hand side expansion.

The $@ and $: prefixes can precede a $> spec. For example:

R$+	$:$>7$1

matches anything, passes that to rule set 7, and continues; the $: is necessary to avoid an infinite loop. The $[host]$ syntax replaces the host name with the "official" or primary host name, the one listed first in the hosts.byname NIS map, or /etc/hosts if not running NIS. It is used to eliminate nicknames for hosts. The ${x name $} syntax replaces the string by the result of the nis_map_name indicated in macro $x.

The rule below can be added to ruleset 0 to forward mail to the mail host from a system (like a router) that might not be able to route mail itself:

R$*<@$*.$m>		$#ether $@mailhost $:$1<@$2.$m>

Semantics of Rewriting Rule Sets

Five rewriting sets have specific semantics, as shown in Figure 3-2.

Figure 3-2 Rewriting Set Semantics

Rule set 3 is applied by sendmail before sendmail handles any name. Rule set 3 should turn the name into a form, with the basic syntax:

local-part@host-domain-spec

If no @ is specified, then the host-domain-spec may be appended from the sender name (if the C flag is set in the mailer definition corresponding to the sending mailer).

Rule set 0 is applied after rule set 3 to names that will actually specify recipients. It must resolve to a mailer, host, user triple. The mailer must be defined in the mailer definitions from the configuration file. The host is defined into the $h macro for use in the argument expansion of the specified mailer; the user is defined into $u.

Rule set 1 is applied to all From: recipient names, and rule set 2 is applied to all To: and Cc: lines. Then the rule sets specified in the mailer definition line (and R=) are applied. This process is done many times for one message, depending on how many mailers the message is routed to by rule set 0.

Rule set 4 is applied last to all names in the message. It is typically used to translate internal to external form.

error Mailer

You can use the mailer with the special name error in rule set 0 to generate a user error message. The user field is a message to be printed. For example, the entry:

$#error$:Host unknown in this domain

on the RHS of a rule generates the specified error if the LHS matches.

Semantics of Mailer Descriptions

Each mailer has an internal name. It can be arbitrary, except that the names local and prog must be defined first and second respectively. Rule set 0 resolves names to this mailer name (and a host and user name).

Give the path name of the mailer in the P field. If this mailer will be accessed by way of a TCP connection, use the string [TCP] instead.

Define the mailer flags in the F field. Specify an f or r flag to pass the name of the sender as an f or r flag respectively. To conform mailers that give errors under some circumstances, these flags are passed only if they were passed to sendmail. In some cases, you might be able to specify f$g in the argv template. If the mailer must be called as root, and sendmail is running setuid to root, use the S flag; it will not reset the user ID before calling the mailer. If this mailer is local (that is, will perform final delivery rather than another network hop), use the flag. Quoted characters (backslashes and double quotation marks) can be stripped from names if the s flag is specified; if it is not specified, they are passed through. If the mailer is capable of sending to more than one user on the same host in a single transaction, use the m flag. 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," and sendmail defers connection until a queue run. Note that the c configuration option must also be set.

The C flag is a useful case. It applies to the mailer from which the message is sent, rather than the mailer where the message is received. If set, the domain specification of the sender (that is, the @host.domain part) is saved and appended to any names in the message that do not already contain a domain specification. For example, a message in this form:

From: eric@jupiter
To: joe@saturn, sam

is modified to:

From: eric@jupiter
To: joe@saturn, sam@ganymede

if and only if the C flag is defined in the mailer corresponding to eric@jupiter.

The S and R fields in the mailer description are per-mailer rewriting sets to be applied to sender and recipient names respectively. These are applied after the sending domain is appended and the general rewriting sets (number 1 or 2) are applied, but before the output rewrite (rule set 4) is applied. A typical use is to append the current domain to names that do not already have a domain. For example, a header in this form:

From: eric@host

might be changed to:

From: eric@host.colorado.edu

or:

From: saturn!eric

depending on the domain into which it is being shipped. These sets can also be used to do special-purpose output rewriting in cooperation with rule set 4.

Table 3-13 includes additional flags that you might use in the configuration file.

For example, the specification:

Mlocal, P=/bin/mail, F=flsSDFMmnP, S=10, R=20, A=mail -d $u
Mprog,  P=/bin/sh,   F=lsDFMeuP,  S=10, R=20, A=sh -c $u

specifies a mailer for local delivery and a mailer for Ethernet delivery. The first is called local, is located in the file /bin/mail, takes an F flag, does local delivery, strips quotes from names, and delivers mail to multiple users at once. It applies rule set 10 to sender names in the message and applies rule set 20 to recipient names. The argument vector to send to a message is the word mail, the word d, and words containing the name of the receiving user. If you are inserting an r flag is inserted, place it between the words mail and d.

The second mailer is called ether. It is connected through TCP and can handle multiple users at once. It defers connections and appends any domain from the sender name to any receiver name without a domain; it processes sender names by rule set 11 and recipient names by rule set 21. Messages passed through this mailer have a 100,000-byte limit.

Building a Configuration File

Building a configuration file "from scratch" is a complex task. Fortunately, it is almost never necessary; you can accommodate almost every situation by changing an existing file. In any case, it is critical that you understand what you are trying to do and come up with a policy statement for the delivery of mail. This section explains the purpose of a configuration file and gives you some ideas about policies.

Domains and Policies

RFC 1006 describes domain-based naming. RFC 822 touches on this issue 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 are organizational entities, not physical networks.

RFC 822 and RFC 976 specify how to parse certain sorts of addresses. You can configure sendmail to follow or ignore these rules.

How to Proceed

After you have established a policy, examine the available configuration files to decide if you can use major parts of any of them. Even under the worst of conditions, there is a fair amount of boilerplate information that can be collected safely.

The next step is to build rule set 3, which specifies a rule set for your individual mailers. Building rule set 3 is the hardest part of the job. Here are some guidelines:

• Beware of doing too much to the name in this rule set, as anything you do will be reflected in the message.

• Do not strip local domains in this rule set. Doing so can leave you with names that have no domain specifications at all. sendmail appends the sending domain to names with no domain, which can change the semantics of names.

• Do not provide fully qualified domains in this rule set. Although technically correct, fully qualified domain names can lead to unnecessarily long names reflected in messages. The SunOS configuration files define rule set 9 to qualify domain names and strip local domains. Rule set 9 is called from rule set 0 to get all names into a cleaner form.

After you have rule set 3 finished, the other rule sets should be relatively simple. Examine the supplied configuration files for hints.

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

which would read the configuration file test.cf and enter test mode. For example:

ADDRESS TEST MODE
Enter <ruleset> <name>
>

In this mode, you enter lines in this form:

ADDRESS TEST MODE
Enter <ruleset> <name>
> rwset  name

where rwset is the rewriting set you want to use and name is a name to which to apply the set. Test mode shows you the steps it takes as it proceeds and shows you the final name. You can use a comma-separated list of rwsets for sequential application of rules to an input. For example:

ADDRESS TEST MODE
Enter <ruleset> <name>
> 3,1,21,4 jupiter:smith

First apply rule set 3 to the input monet:bollard. Rule set 1 is then applied to the output of rule set 3, followed similarly by rule sets 21 and 24.

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

% sendmail -bt -d21.99

turns on a large amount of information; a single-word name might result in several pages worth of information.