Chapter 3 Customizing sendmail Configuration Files

The sendmail program is a mail transport agent that uses a configuration file to provide aliasing and forwarding, automatic routing to network gateways, and flexible configuration. The SunOS 5.x operating system supplies standard configuration files that most sites can use. Chapter 2, Setting Up and Administering Mail Services explains how to set up an electronic mail system using the standard files. This chapter explains how to customize sendmail configuration files if you need to tailor them to fit your site's needs.

• "sendmail Overview"

• "sendmail Features"

• "sendmail Functions"

• "How sendmail Works"

• "sendmail Implementation"

• "Arguments to sendmail"

• "Tuning Configuration Parameters"

• "sendmail Configuration File"

• "How sendmail Interacts With a Name Service"

• "Command-Line Arguments to sendmail"

• "Configuration Options to sendmail"

• "Mailer Flags"

sendmail Overview

The sendmail program can use different types of communications protocols, like TCP/IP and UUCP. It also implements an SMTP server, message queueing, and mailing lists. Name interpretation is controlled by a pattern-matching system that can handle both domain-based naming and improvised conventions.

The sendmail program can accept domain-based naming as well as arbitrary (older) name syntaxes--resolving ambiguities by using heuristics you specify. sendmail can also convert messages between disparate naming schemes. The domain technique separates the issue of physical versus logical naming. See the TCP/IP and Data Communications Administration Guide for a complete description of Internet domain-naming conventions.

You can handle certain special cases by improvised techniques, like providing network names that appear local to hosts on other networks.

sendmail Features

The sendmail program provides the following features:

• It supports UNIX System V mail, UNIX version 7 mail, and Internet mail.

• It is reliable. It is designed to correctly deliver every message. No message should ever be completely lost.

• It uses existing software for delivery whenever possible.

• It can be configured to handle complex environments, including multiple connections to a single network type (like with UUCP or Ethernet). sendmail checks the contents of a name as well as its syntax to determine which mailer to use.

• It uses configuration files to control mail configuration.

• Groups can maintain their own mailing lists. Individuals can specify their own forwarding without modifying the domain-wide alias file (typically located in the domain-wide aliases maintained by NIS or NIS+).

• Each user can specify a custom mailer to process incoming mail, which can provide functions like returning an "I am on vacation" message. See the vacation(1) man page for more information.

Figure 3-1 shows how sendmail interacts with the other programs in the mail system.

Figure 3-1 Interaction of sendmail With Other Mail Programs

The user interacts with a mail-generating and -sending program. When the mail is submitted, the mail-generating program calls sendmail, which routes the message to the correct mailers. Because some of the senders may be network servers and some of the mailers may be network clients, sendmail may be used as an Internet mail gateway.

sendmail Functions

The sendmail program is a message router that calls administrator-defined mailer programs to deliver messages. It collects a message from a program, like mail, edits the header of the message as required by the destination mailer, and calls appropriate mailers to do delivery or queueing for network transmission. When mailing to a file, however, sendmail delivers directly. You can add new mailers at minimum cost.

sendmail Interfaces

The sendmail program communicates with the outside world in three ways:

• Using the conventional argument vector/exit status

• Using pairs of pipes

• Using SMTP over a TCP connection

Argument Vector/Exit Status

The standard way to communicate with a process is by using the argument vector (command name and arguments). The argument vector sends a list of recipients, and the message body is sent on the standard input. If problems occur, anything is printed by the mailer is collected and returned to the sender. After the message is sent, the exit status from the mailer is collected and a diagnostic is printed, if appropriate.

SMTP Over Pipes

You can use the SMTP protocol to run an interactive lock-step interface with the mailer. A subprocess is still created, but no recipient names are passed to the mailer through the argument list. Instead, they are passed one at a time in commands sent to the processes' standard input. Anything appearing on the standard output must be a standard SMTP reply code.

SMTP Over a TCP Connection

This technique is similar to SMTP over pipes, except that it uses a TCP connection. SMTP over a TCP connection is normally used to connect to a sendmail process on another system. This method is exceptionally flexible because the mailer need not reside on the same machine.

How sendmail Works

The sendmail program collects a message from a program like mailx or mailtool, edits the message header as required by the destination mailer, and calls appropriate mailers to deliver mail or to queue the mail for network transmission.

The sendmail program never edits or changes the body of a message. Any changes that it makes to interpret email addresses are made only in the header of the message.

Argument Processing and Address Parsing

When sendmail receives input, it collects recipient names (either from the command line or from the SMTP protocol) and generates two files. One is an envelope that contains the header and a list of recipients. The other file contains the body of the message. The sendmail program expands aliases, including mailing lists, and validates as much as possible of the remote recipient. Then sendmail checks syntax and verifies local recipients. Detailed checking of host names is deferred until delivery. As sendmail verifies local recipients, messages are forwarded to them.

After parsing the recipient lists, sendmail appends each name to both the envelope and the header of the message. When a name is aliased or forwarded, it retains the old name in the list and sets a flag to tell the delivery phase to ignore this recipient. The lists are kept free from duplicates, preventing alias loops and duplicate messages delivered to the same recipient, which can occur if a recipient is in two different alias groups.

Users may receive duplicate copies of the same message when alias lists contain email addresses for the same person using different syntax. The sendmail program cannot always match the email addresses as duplicates of one another.

Message Collection

Once all recipient names are parsed and verified, the message is collected. The message comes in two parts: a message header and a message body. The header and the body are separated by a blank line.

The header is formatted as a series of lines in this form:

field-name: field-value

For example, a sample header might be:

From: John Smith <Smith@colorado.edu>

field-value can be split across lines by starting the subsequent lines with a space or a tab. Some header fields have special internal meaning and have appropriate special processing. Other headers are simply passed through. Some header fields, like time stamps, may be added automatically.

No formatting requirements are imposed on the message body except that they must be lines of text. sendmail stores the header in memory and stores the body of the message in a temporary file. To simplify the program interface, the message is collected, even if no names are valid. If none of the names are valid, the message is returned to the sender with an error.

With DeskSet(TM) Mail Tool, users can transmit binary data. However, it must be encoded by Mail Tool. The sendmail program does not automatically encode binary data. Refer to the mailtool(1) man page for information about how to encode and decode binary data messages.

The message body is completely uninterpreted and untouched, except that lines beginning with a dot have the dot doubled when transmitted over an SMTP channel. The receiver strips this extra dot.

Message Delivery

The send queue is grouped by the receiving host before transmission to implement message batching. An argument list is built as the scan proceeds. Mail being sent to files is detected during the scan of the send list.

After a connection is established, sendmail makes the per-mailer changes to the header and sends the result to the mailer. If any mail is rejected by the mailer, a flag is set to invoke the return-to-sender function after all delivery is complete.

The sendmail program sends the message to the mailer using one of the same interfaces used to submit a message to sendmail (using the conventional UNIX argument vector or return status, communicating over a pair of UNIX pipes, or using SMTP over a TCP connection). Each copy of the message has a customized header.

Error Handling

When mail can't be delivered, the mailer catches and checks the status code, and a suitable error message is given as appropriate. The exit code must conform to a system standard. If a nonstandard exit code is used, sendmail transmits the message, "Services unavailable".

Queueing for Retransmission

If the mailer returns a "temporary failure" exit status, the message is queued. A control file describes the recipients and various other parameters. This control file is formatted as a series of lines, each describing a sender, a recipient, the time of submission, or some other parameter of the message. The header of the message is stored in the control file so that the associated data file in the queue is just the temporary file that was originally collected.

Return to Sender

If errors occur during processing, sendmail returns the message to the sender for retransmission. The letter can be mailed back or written to the dead.letter file in the sender's home directory.

Message Header Editing

Certain editing of the message header occurs automatically. Header lines can be inserted under control of the configuration file. Some lines can be merged; for example, a From: line and a Full-name: line can be merged under certain circumstances.

Configuration File

Almost all configuration information is read at runtime from a text file that includes macro definitions (the value of macros used internally), header declarations (the format of header lines that are specially processed and lines that are added or reformatted), mailer definitions (giving information like the location and characteristics of each mailer), and name-rewriting rules (a limited pattern-matching system used to rewrite names).

sendmail Implementation

You can follow flag arguments with recipient name arguments unless you run sendmail in SMTP mode. In brief, the format of recipient names is:

• Any text in parentheses is thrown away (as a comment).

• Any text in angle brackets (<>) is preferred over any other text. This rule implements the Internet standard that sends names of the following form to the electronic system-name rather than the human username:

  username <login@system-name>

• Double quotation marks (") quote phrases; backslashes (\) quote characters. Backslashes cause otherwise equivalent phrases to compare differently--for example, user and "user" are equivalent, but \user is different from either of them.

You must properly balance and nest parentheses, angle brackets, and double quotation marks. The rewriting rules control the rest of the needed processing.

Mail to Files and Programs

Files and programs are legitimate message recipients. Files provide archival storage of messages, useful for project administration and history. Programs are useful as recipients in a variety of situations, for example, to use mailsort to sort mail or to have the vacation program respond with an informational message when users are away.

Any name passing through the initial parsing algorithm as a local name is scanned for two special cases:

• If the prefix is a vertical bar (|), the rest of the name is processed as a shell command.

• If the user name begins with a slash (/), the name is used as a file name instead of a login name.

Configuration Overview

Primarily the configuration file read at startup controls configuration. Adding mailers or changing the name-rewriting or routing information does not require recompiling. The configuration file encodes macro definitions, header definitions, mailer definitions, name-rewriting rules, and options.

Macros

You can use macros in several ways. Certain macros transmit unstructured textual information into the mail system, like the name that sendmail uses to identify itself in error messages. Other macros are unused internally and you can use them as shorthand in the configuration file.

Header Declarations

Header declarations inform sendmail of the format of known header lines. Knowledge of a few header lines is built into sendmail, like the From: and Date: lines.

Most configured headers are automatically inserted into the outgoing message if they do not exist in the incoming message. Some mailers suppress certain headers.

Mailer Declarations

Mailer declarations specify the internal name of the mailer, some flags associated with the mailer, and an argument vector to be used on the call. This vector is expanded by macro before use.

Name-Rewriting Rules

Name-rewriting rules are the heart of name parsing in sendmail. They are an ordered list of pattern-replacement rules that are applied to each name. For example, rule set 0 determines which mailer to use. sendmail rewrites the message until it is in a form that can be parsed. When a pattern matches the rule is reapplied until it fails.

The configuration file also supports the editing of names into different formats. For example, a name in this form:

ucsfcgl!tef

might be mapped into:

tef@ucsfcgl.UUCP

to conform to the internal syntax. Translations can also be done in the other direction for particular mailers.

Option Setting

You can set several options from the configuration file. These include the path names of various support files, timeouts, default modes, and so forth.

Arguments to sendmail

Arguments to sendmail are listed and described in detail in "Command-Line Arguments to sendmail". Some of the important arguments are described in this section.

Queue Interval

The q flag defines how often sendmail runs the queue. If you run in mode i or b (the default), this time can be relatively long, because it is only relevant when a host that was down restarts. If, however, you run in q mode, the time should be relatively short, as the flag defines the maximum amount of time that a message may sit in the queue. Typical queue time is set to between 15 minutes (q15m) and 1 hour (q1h).

Daemon Mode

If you allow incoming mail over a TCP connection, you should have a daemon running. Set the bd flag in your /etc/rc3.d/S88sendmail file.

You can combine the bd flag and the q flag in one call:

# /usr/lib/sendmail -bd -q30m

Debugging

sendmail has many debug flags, which you set using the d option. Each debug flag has a number and a level, where higher levels mean "print more information." The convention is that you do not need to set levels greater than 9 unless you are debugging that particular piece of code. Table 3-1 shows some examples of debugging flags.

If you have source code, you can refer to the list of debug flags in the code.

Trying a Different Configuration File

You can specify an alternative configuration file by using the C flag; for example, the command

# /usr/lib/sendmail -Ctest.cf

uses the configuration file test.cf instead of the default /etc/mail/sendmail.cf. If you do not define a value for the C flag, it uses the sendmail.cf file in the current directory.

Tuning Configuration Parameters

You can tune several configuration parameters, depending on the requirements of your site. You can set most of these parameters by using an option in the configuration file. For example, the line OT3d sets option T to the value 3d (three days).

Time Values

All time intervals use a syntax of numbers and letters. For example, 10m is 10 minutes, and 2h30m is two and one-half hours.

Table 3-2 lists the time symbols.

Queue Interval

The argument to the q flag specifies how often sendmail runs the queue. It is usually set to between 15 minutes (q15m) and 1 hour (q1h).

Read Timeouts

The Or option in the configuration file sets the read timeout. The default read timeout is Or15m. Although it is technically unacceptable within the published protocols, sendmail might time out when reading the standard input or when reading from a remote SMTP server. If your site has problems with read timeouts, set the read timeout to a larger value, like one hour (Or1h), to reduce the chance of several idle daemons piling up on your system.

Message Timeouts

The OT option in the configuration file sets the message timeout. The default message timeout is three days (OT3d). After a message has been in the queue for the message time-out period, the sender is notified that the message could not be delivered.

You can flush messages that have been hanging for a short period by running the queue with a short message timeout. For example, the command

# /usr/lib/sendmail -oT1d -q

runs the queue and flushes any message that is one day old or older.

Delivery Mode

The Od option in the configuration file sets the delivery mode. The default delivery mode is Odbackground. Delivery modes specify how quickly mail is delivered. Table 3-3shows the legal modes.

There are trade-offs. The interactive mode (i) passes the maximum amount of information to the sender, but it is seldom necessary. The queue mode (q) puts the minimum load on your machine, but means that delivery might be delayed for up to the queue interval. The background mode (b), the default, is a good compromise.

Load Limiting

Central mail machines often can be overloaded. The best solution is to dedicate a more powerful machine to handling mail, but the load almost always expands to consume whatever resources are allocated.

The sendmail program enables you to limit the load. The goal of load limiting is to prevent wasting time during loaded periods by attempting to deliver large messages, messages to many recipients, and messages to sites that have been down for a long time.

Use the Ox and OX options to limit the load caused by sendmail. The default is not to set any load limits if no options are used. Both these configuration options take an argument that is an integer load average. For example, if you specify Ox4 and OX8, then the x load limiting will be used when the load is above four, and the X load limiting will be used when the load is above eight. When the load is above the value specified in the X option, the SMTP server does not accept connections from the network (locally originated mail and other mail like UUCP are not affected). The x option has a more subtle effect, controlling whether messages are queued for later delivery or delivered immediately. The general idea is always to deliver "small" messages immediately and to defer "large" messages for delivery during off-peak periods.

The Oq option specifies the maximum size of a message that is delivered immediately. The "size" of the message includes not only the number of bytes in the message but also the penalty for a large number of recipients and for unsuccessful delivery attempts. The penalty per recipient is option value y, by default set to 1000. The penalty per delivery attempt is the option value z, by default set to 9000. The size limit also depends on the current load, so that more and more messages are queued as the load goes higher. If the load is one above the x threshold, then the limit is halved; if the load is two above the threshold, the limit is divided by three, and so on. Note that this limit also applies to messages being delivered when processing the queue.

Log Level

You can adjust the level of logging for sendmail. Table 3-4shows the levels.

Refer to the system error logging section in System Administration Guide for more information.

File Modes

Certain files can have protection modes that control access. This section describes the modes that you can control from the sendmail.cf file. The modes you use depend on what functionality you want and the level of security you require.

setuid

By default, the sendmail program is executed with the user ID set to 0 (setuid to root) so that it can deliver to programs that might write in a user's home directory. When sendmail is ready to execute a mailer program, sendmail checks to see if the user ID is 0; if so, it resets the user ID and group ID to the values set by the u and g options in the configuration file. The user ID and group ID are both set to 1 (daemon). You can override these values by setting the S flag to the mailer (for mailers that are trusted, and must be called as root). However, mail processing is accounted to root rather than to the user sending the mail.

Temporary File Modes

The OF option sets the mode of all the temporary files that sendmail uses. The default value, 0600, is appropriate for secure mail, and 0644 is more permissive. If you use the more permissive mode, it is not necessary to run sendmail as root at all (even when running the queue). Users will be able to read mail in the queue.

Should My Alias Database Be Writable?

One approach is to provide the alias database (/etc/mail/aliases) with mode 666. If you use this approach, users can modify any list. However, you might want to limit the aliases that a user can change by putting them into a file that the user can edit and referencing this file from /etc/mail/aliases. Such references have the following format:

alias-name::include:/filename

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.

How sendmail Interacts With a Name Service

Mail domain is a concept used by the standard sendmail.cf file to determine whether mail should be delivered directly or through the mail host. Intradomain mail is delivered through direct SMTP connection, while interdomain mail is forwarded to a mail host.

In a secure network, only a few selected hosts are authorized to generate packets targeted to external destinations. Even if a host has the IP address of the remote host external to the mail domain, this does not guarantee that an SMTP connection can be established. The standard sendmail.cf assumes the following:

• The current host is not authorized to send packets directly to a host outside the mail domain.

• The mail host is capable of forwarding the mail to an authorized host that can transmit packets directly to an external host. (In fact, the mail host may itself be an authorized host.)

Given these assumptions, it is the responsibility of the mail host to deliver or forward inter-domain mail.

Setting Up sendmail Requirements for Name Services

sendmail imposes various requirements on name services. This section explains these requirements and how to satisfy them. For more information, refer to the in.named(1M), nis+(1), nisaddent(1M), and nsswitch.conf(4) man pages.

Establishing the Mail Domain Name with a Name Service

The mail domain name must be a suffix of the name service domain. For example, if the domain name of the name service is A.B.C.D, then the mail domain name could be one of the following:

• A.B.C.D

• B.C.D

• C.D

• D

When first established, the mail domain name is often identical to the name service domain. As the network grows larger, the name service domain can be divided into smaller pieces to make the name service more manageable. However, the mail domain often remains undivided to provide consistent aliasing.

The Host Name Space Data

The host table or map in the name service must be set up to support three types of gethostbyname() queries:

• mailhost - Some name service configurations satisfy this requirement automatically.

• Full host name (for example, smith.admin.acme.com) - Many name service configurations satisfy this requirement.

• Short host name (for example, smith) - sendmail must connect to the mail host to forward external mail. To determine if a mail address is within the current mail domain, gethostbyname() is invoked with the full host name. If the entry is found, the address is considered internal.

  NIS, NIS+, and DNS all support gethostbyname() with a short host name as an argument, so this requirement is automatically satisfied.

Two additional rules about the host name space need to be followed to properly establish the sendmail services within a name space.

1. gethostbyname() with full and short host name should yield consistent results. For example, gethostbyname(smith.admin.acme.com) should return the same result as gethostbyname(smith) as long as both functions are called from the mail domain admin.acme.com.

2. For all name service domains under a common mail domain, gethostbyname() with a short host name should yield the same result. For example, given the mail domain smith.admin.acme.com, gethostbyname(smith) should return the same result calling from either domain ebb.admin.acme.com or esg.admin.acme.com. The mail domain name is usually shorter than the name service domain, giving this requirement special implications for various name services.

How to Configure NIS for sendmail

This list includes all the configuration issues that you must resolve before using sendmail when using NIS as your only name service.

mail domain name

If you are setting up NIS as the primary name service, sendmail automatically strips off the first component of the NIS domain name and uses the result as mail domain name. For example, ebs.admin.acme.com becomes admin.acme.com.

mailhost host name

You must have a mailhost entry in the NIS host map.

full host names

The normal NIS setup does not "understand" the full host name. Rather than trying to make NIS understand the full host name, turn off this requirement from the sendmail side by editing the sendmail.cf file and replacing all occurrences of %l with %y. This turns off sendmail's inter-domain mail detection. As long as the target host can be resolved to an IP address, a direct SMTP delivery will be attempted. Make sure that your NIS host map does not contain any host entry that is external to the current mail domain. Otherwise, you will need to further customize the sendmail.cf file.

matching full and short host names

Follow the previous instructions on how to turn off gethostbyname() for a full host name.

multiple NIS domains in one mail domain

All NIS host maps under a common mail domain should have the same set of host entries. For example, the host map in the ebs.admin.acme.com domain should be the same as the host map in the esg.admin.acme.com. Otherwise, one address might work in one NIS domain but fail in the other NIS domain.

How to Configure NIS and DNS for sendmail

This list includes all the configuration issues that you must resolve before using sendmail when using NIS with DNS as your name service.

mail domain name

If you are setting up NIS as the primary name service, sendmail automatically strips the first component of the NIS domain name and uses the result as mail domain name, for example, ebs.admin.acme.com becomes admin.acme.com.

mailhost host name

When the DNS forwarding feature is turned on, queries that NIS cannot resolve are forwarded to DNS, so there is no need for a mailhost entry in the NIS host map.

full host names

Although NIS does not "understand" full host names, DNS does. This requirement is satisfied when you follow the regular procedure for setting up NIS and DNS.

matching full and short host names

For every host entry in the NIS host table, you must have a corresponding host entry in DNS.

multiple NIS domains in one mail domain

All NIS host maps under a common mail domain should have the same set of host entries. For example, the host map in the ebs.admin.acme.com domain should be the same as the host map in the esg.admin.acme.com. Otherwise, one address might work in one NIS domain but fail in the other NIS domain.

How to Configure NIS+ for sendmail

This list includes all the configuration issues that you must resolve before using sendmail when using NIS+ as your only name service.

mail domain name

If you are setting up NIS+ as your primary name service, sendmail can look up the mail domain from the NIS+ sendmailvars table, a two-column NIS+ table with one key column and one value column. To set up your mail domain, you must add one entry to this table. This entry should have the key column set to the literal string maildomain and the value column set to the your mail domain name (for example, admin.acme.com). Although NIS+ allows any string in the sendmailvars table, the suffix rule still applies for the mail system to work correctly. You can use nistbladm to add the maildomail entry to the sendmailvars table. For example:

nistbladm -A key="maildomain" value=<mail domain> sendmailvars.org_dir.<NIS+ domain>

Note that this mail domain is a suffix of the NIS+ domain.

mailhost host name

You must have a mailhost entry in the NIS+ hosts table.

full host names

NIS+ "understands" the full host name. Following the regular NIS+ setup procedure satisfies this requirement.

matching full and short host names

To satisfy this requirement, you can duplicate the entries in the host table, or you can enter all host entries in the user name service domains into a master host table at mail domain level.

multiple NIS domains in one mail domain

To satisfy this requirement, you can duplicate the entries in all the host tables, or you can type all host entries in the user name service domains into a master host table at mail domain level. Because you are merging (logical or physical) multiple host tables into one host table, the same host name cannot be reused in the multiple name service domain sharing a common mail domain.

How to Configure NIS+ and DNS for sendmail

This list includes all the configuration issues that you must resolve before using sendmail when using NIS+ with DNS as your name service.

mail domain name

If you are setting up NIS+ as your primary name service, sendmail can look up the mail domain from the NIS+ sendmailvars table, a two-column NIS+ table with one key column and one value column. To set up your mail domain, you must add one entry to this table. This entry should have the key column set to the literal string maildomain and the value column set to the your mail domain name (for example, admin.acme.com). Although NIS+ allows any string in the sendmailvars table, the suffix rule still applies for the mail system to work correctly. You can use nistbladm to add the maildomail entry to the sendmailvars table. For example:

nistbladm -A key="maildomain" value=<mail domain> sendmailvars.org_dir.<NIS+ domain>

Note that this mail domain is a suffix of the NIS+ domain.

mailhost host name

If your network uses both NIS+ and DNS as the source for the host database, you can put the mailhost entry in either the NIS+ or DNS host table. Make sure that your users list NIS+ and DNS as the source for the host database in the /etc/nsswitch.conf file.

full host names

Both NIS+ and DNS "understand" full host names. Following the regular NIS+ and DNS setup procedures satisfies this requirement.

matching full and short host names

For every host entry in the NIS+ host table, you must have a corresponding host entry in DNS.

multiple NIS domains in one mail domain

To satisfy this requirement, you can duplicate the entries in all the host tables, or you can type all host entries in the user name service domains into a master host table at mail domain level.

Command-Line Arguments to sendmail

You can use command-line arguments when running /usr/lib/sendmail on a command line or type them into the mail startup script, /etc/init.d/sendmail. Table B-1 lists all of these arguments. The following paragraphs document several of the most commonly used arguments.

The sendmail daemon is normally started with the following command:

/usr/lib/sendmail -bd -q1h

Use the b option to select the operation mode that sendmail is running in. In this case, the daemon mode is selected. Other operational modes that you can selecte are initialize the alias database (bi), print the mail queue (bp), or verify the recipients (bv). You can duplicate the action of these arguments with newaliases, mailq, and mconnect.

The second set of arguments indicates that any queued mail should be reprocessed at 1 hour intervals. This can be decreased to 30 minutes by using q30m.

Using this argument, Cfile, will allow testing of a different sendmail configuration file. Other options that are useful when testing or debugging sendmail include d, which will select a debugging level, and v, which selects the verbose mode.

You can use the q argument to limit the jobs that are processed. The following argument selects only those messages to a user named mary, qRmary. This argument also allows limitation by sender, qSname, or by message-id, qInumber.

You can use the o argument to reset a configuration option. For instance, qQ/var/oldmail will run sendmail using /var/oldmail as the queue directory. The configuration options that you can change with this argument are discussed in more depth in the next section.

Configuration Options to sendmail

Table B-2 includes all of the configuration options for sendmail. You can set them using the o flag when starting sendmail or by using the O line in the configuration file.

Use the Afile option to change the location of the alias file, which is normally set to /etc/mail/aliases.

You can reset the hop count using the h# option. The hop count determines the maximum number of hosts a particular message will be routed through before it is sent back to the sender. If a mail message gets into an alias loop, the hop count determines the number of hosts the message will try to go to before the message fails. The default hop count is set to 30, which may be too high for small domains or email domains that do not have many levels.

Two options can help control the system load. The X# option sets the maximum load average value and causes the daemon to refuse any incoming SMTP connections if the load average is above the value designated by #. You can increase the default value of 12, if the mail host can take the load. Using X0 refuses all SMTP connections.

The x# option queues the mail when the load average specified by # is reached instead of refusing it. Make sure that the server has enough disk space to hold all the queued mail before adjusting this value.

Both the options that work with the system load have a delay in response, so that restarting sendmail with new load average values does not immediately remedy all load problems.

Mailer Flags

Table B-3 presents a complete list of the flags you can set in the mailer description. These flags are set in the configuration file.

The m flag allows the mailer to batch a mail message to multiple users if they are all receiving mail on the same host. This can improve response time. It can cause problems if the mail cannot reach one of the users. This will generate an error, which will cause the mail to be resent, and can generate duplicate mail. Remove this flag from the configuration file if potential problems associated with duplicate mail are too great.

The n flag selects to not add a UNIX-style From line on the front of the message. This is already done by /usr/lib/mail.local, so it should not be necessary for the mailer to do this.