The argument to the -q flag specifies how often to process the mail queue. When the sendmail daemon is started with the /etc/init.d/mail script, the queue interval is set to 15 minutes.

If sendmail runs in delivery mode b, messages are written to the queue only when they cannot be delivered (for example, when a recipient host is down). Therefore, the need to process the queue is limited and the queue interval value may be set quite high. The value is relevant only when a host that was down comes back up.

If sendmail runs in delivery mode q, the queue interval should be set to a low value, as it defines the longest time that a message sits in the local queue before being processed.

sendmail can time out when reading the standard input or when reading from a remote SMTP server. Technically, a timeout is not acceptable within the published protocols. However, setting the read timeout option to a high value (such as an hour) reduces the chance that a large number of idle daemons will pile up on a system. The read timeout option is r.

sendmail causes a queued message to time out after a specified time period. This feature ensures that the sender knows the message cannot be delivered. This default message timeout value is one week (seven days). The value is set with the T option.

The queue records the time of submission, rather than the time remaining until timeout. This approach enables sendmail to flush messages that have been hanging for a short period by running the queue with a short message timeout. The following example illustrates how to process the queue and flush any message that is one day old:

/usr/lib/sendmail -oT1d -q 

The rewriting rules are the core of address parsing. These rules form an ordered production system. During parsing, sendmail scans the set of rewriting rules, looking for a match on the left-hand side (ls) of the rule. When a rule matches, the address is replaced by the right-hand side (rhs) of the rule.

The rewriting rules are grouped into sets of one or more rules. Each set has an integer identifier called a rule set number. Each rule set acts like a subroutine: When the set is called, each rule is scanned in sequence until all rules have been scanned or until the rule set returns to the caller.

Some rule sets are used internally and have specific semantics. Others do not have specifically assigned semantics and can be referenced by mailer definitions or by other rule sets.

Each rule set begins with an S command, with the syntax

Sn

where n is the rule set identifier, an integer between 0 and 99. If the same rule set identifier is used more than once in a configuration file, the last definition is the one used.

Each line within the rule set begins with an R command and defines a rewrite rule. R commands have the syntax

Rlhs rhs [comments]

where the following conditions exist:

The D command names a macro and defines its content. A macro name is a single ASCII character. sendmail defines several internal macros of its own. To avoid conflicts, use uppercase letters for all user-defined macros. Lowercase letters and special characters are reserved for system use. (A list of sendmail's internally defined macros appears under the topic “Special Macros and Conditionals”.)

The Define Macro command takes one of the following forms:

DxValue
Dx|shell_command [arguments]

where x is the name of the macro. The first form defines the macro to contain Value. The second form defines the macro as the first line seen on stdout of the specified shell command. The vertical bar must immediately follow the macro identifier; no white space is permitted. The remainder of the line is interpreted as arguments to the shell command.

Macros can be interpolated in most places by means of the escape sequence $x.

---

Caution: sendmail does not honor comments on macro definition lines. For example, the following line defines the D macro as “foo.com # my domain name”:

---

DDfoo.com # my domain name

The C command defines classes of words to match on the left-hand side of rewriting rules, where a “word” is a sequence of characters. A class name is a single uppercase letter. A class might define a site's local names and be used to eliminate attempts to send to oneself. Classes can be defined either directly in the configuration file or by being read in from a pipe or other file. The sequence cannot contain characters used as “operators” in addresses. (Operators are defined with the $o macro.)

The C command takes one of the following forms:

CX word1 [word2 ...]
CX $x [$y ...]

where X is the class name. The first form defines the class to match any of the named words. The second form reads the elements of the class from the expansion of the listed macros. The macros to be expanded must be leftmost in each token. Only one macro can be expanded per token. Any remainder in a token following a macro expansion is added as a separate token.

The F command defines a file from which to read the elements of a class, and takes either of the following forms:

FX file [format]
FX|shell_command [arguments]

The first form reads the elements of the class from the named file. If an optional format argument is present, it is passed as the control string to an sscanf() call and applied to each input line read from the named file, thus:

sscanf(const char *line, const char *format, char *new-element);

There must be no white space to the left of the filename.

The second form reads the elements of the class from stdout of the specified shell command. The entire contents of the line are taken to be a shell command followed by its arguments.

It is permissible to split class definitions across multiple lines. For example, these two forms are equivalent:

CHmonet picasso

and

CHmonet
CHpicasso

It is also permissible to define a class using both C and F commands. For example, the following commands define class H containing monet, picasso, the expansion of the $w macro, and all strings from the file /var/tmp/foofile appearing before the first number symbol (#) on each line:

CHmonet picasso $w
FH/var/tmp/foofile %[^#]

---

Caution: sendmail does not honor comments that are not respected on class definition lines. For example, the following command defines the D class as containing “foo.com,” “bar.com,” “#,” “my,” “local,” and “domains”:

---

CD foo.com bar.com # my local domains 

The M command defines programs and interfaces to mailers. The format is as follows:

Mname, {field=value}*

where name is the name of the mailer (used internally only) and the field=value pairs define attributes of the mailer. The asterisk (*) indicates that the preceding bracketed structure may be repeated 0 or more times. That is, there may be multiple field=value pairs. The following list defines valid field names:

Only the first character of the field name is checked.

The H command defines the format of header lines that sendmail inserts into a message. The command format is as follows:

H[?mflags?]hname: htemplate 

Continuation lines for an H command line appear in the outgoing message. sendmail macro-expands the htemplate before inserting it into the message. If mflags (which must be surrounded by question marks) appear in the command line, at least one of the specified flags must also appear in the mailer definition or the header will not appear in the message. However, if a header appears in the input message, the header also appears in the output, regardless of these flags.

Some headers have special semantics, which are described in “The Semantics”.

Several sendmail options can be set by a command line in the configuration file. Each option is identified by a single character.

The format of the O command line is as follows:

Oo value

The command sets option o to value. Depending on the option, value is a string; an integer; a Boolean (with legal values “t,” “T,” “f,” or “F” and a default of TRUE); or a time interval.

The K command is a new command available in IRIX sendmail. This command defines (K)eyed databases that are accessible by means of the lookup operators. See “Define Keyed Files—The K Command” for a complete description of the K command.

Trusted users are permitted to override the sender address by using the -f flag. Typically, trusted users are limited to root, uucp, and network. On some systems it may be convenient to include other users. For example, there may be a separate uucp login for each host. Note, though, that the concept of trusted users in sendmail bears no relation to Trusted IRIX/B, or to the concept of trusted (secure) operating systems in general.

The format of the T command is as follows:

Tuser1 user2...

A configuration file can contain multiple T lines.

The P command defines values for the Precedence field. The format of the command line is as follows:

Pname=num

When sendmail matches the value in a message's Precedence field with the name in a P command line, sendmail sets the message's class to num. A higher number indicates a higher precedence. Negative numbers indicate that error messages will not be returned to the sender. The default precedence is zero. For example, a list of precedences might be

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

The K command defines a symbolic name for accessing a database. The format of the command line is as follows:

Kname type file

The name value is the name used to specify the database in a lookup command. The type defines the type of database file, which can be one of the following:

The file value specifies the filename of the database to be searched.

Macros are interpolated by means of the construct $x, where x is the name of the macro to be interpolated. Special macros are named with lowercase letters; they either have special semantics or pass information into or out of sendmail. Some special characters are also reserved, and are used to provide conditionals and other functions.

The following syntax specifies a conditional:

$?x text1 $| text2 $.

This example interpolates text1 if the macro $x is set, and text2 otherwise.

The “else” ($|) clause can be omitted.

The following macros must be defined if information is to be transmitted into sendmail:

The $o macro consists of a list of characters that are treated as tokens themselves and serve to separate tokens during parsing. For example, if @ were in the $o macro, then the input string “a@b” would scan as three tokens: a, @, and b.

Here are several examples of these macro definitions:

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

An acceptable alternative format for the $q macro is "$?x$x $.<$g>" . This syntax corresponds to the following two formats:

jd@company.com (John Doe)
John Doe <jd@company.com>

Some macros are defined by sendmail for interpolation into arguments passed to mailers or for other contexts. These macros are:

Macros $a, $b, and $d specify three dates that can be used. The $a and $b macros are in RFC 822 format. $a is the time extracted from the “Date:” line of the message; $b is the current date and time (used for postmarks). If no “Date:” line appears in the incoming message, $a is also set to the current time. The $d macro is equivalent to the $a macro in UNIX format (as described on the ctime(3C) reference page).

The $c macro is set to the “hop count,” the number of times this message has been processed. It can be determined by the -h flag on the command line or by counting the time stamps in the message.

The $f macro is the ID of the sender as originally determined; when a message is sent to a specific host, the $g macro is set to the address of the sender relative to the recipient. For example, if jd sends to buddy@USomewhere.edu from the machine company.com, the $f macro will be jd and the $g macro will be jd@company.com.

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 are set from the $@ and $: part of the rewriting rules, respectively. The $i macro is set to the queue ID on this host; when included in the time-stamp line, it can be extremely useful for tracking messages.

The $p and $t macros are used to create unique strings (for example, for the Message-Id field). The $r and $s macros are set to the protocol used to communicate with sendmail and the name of the sending host; these macros are not supported in the current version.

The $v macro is set to be the version number of sendmail, which normally appears in time stamps and is extremely useful for debugging. The $w macro is set to the name of this host, if it can be determined.

The $x macro is set to the full name of the sender, derived from one of these sources (in this order):

The w class is the set of all names this host is known by, and can be used to match local hostnames.

The left-hand side of a rewriting rule contains a pattern. Words are simply matched directly. A dollar sign introduces the following meta-syntax:

If a match occurs, it is assigned to the symbol $n for replacement on the right-hand side, where n is the index in the lhs. For example, if the lhs

$-@$+

is applied to the input

jd@company.com

the rule will match, and the values passed to the rhs will be

When the left-hand side of a rewriting rule matches, the input is deleted and replaced by the right-hand side. Right-hand-side tokens are inserted exactly as they appear unless they begin with a dollar sign. The meta-syntax is:

An entire rhs may also be prefixed by a $@ or a $: to control evaluation.

The $@ prefix causes the rule set to return with the remainder of the rhs as the value. The $: prefix causes the rule to terminate immediately, but the rule set to continue; this can be used to avoid continued application of a rule. The prefix is stripped before continuing.

The $@ and $: prefixes may precede a $> specification. For example,

R$+     $:$>7$1

matches anything, passes that to rule set 7, and continues; the $: is necessary to avoid an infinite loop.

Substitution occurs in the order described: Parameters from the lhs are substituted, host names are canonicalized, “subroutines” are called, and finally $#, $@, and $: are processed.

There are five rewriting rule sets that have specific semantics. Figure B-1 shows the relationship among these rule sets.

Figure B-1. Semantics of Rewriting Rule Sets

Rule set 3 should turn the address into canonical form. This form should have the following basic syntax:

local-part@host-domain-spec

If no “at” (@) sign is specified, then the host-domain-spec can be appended from the sender address (if the C flag is set in the mailer definition corresponding to the sending mailer). sendmail applies rule set 3 before doing anything with any address.

Next, rule set 0 is applied to an address that actually specifies recipients. The address 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 argv expansion of the specified mailer.

Rule sets 1 and 2 are applied to all sender and recipient addresses, respectively. They are applied before any specification in the mailer definition. They must never resolve.

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

The mailer with the special name “error” can be used to generate a user error. The (optional) host field is a numeric exit status to be returned, and the user field is a message to be printed. For example, the following entry on the rhs of a rule causes the specified error to be generated if the lhs match:

$#error$:Host unknown in this domain

This mailer is functional only in rule set 0.

As part of building or modifying a configuration file, you should test the new file. sendmail provides a number of built-in tools to assist in this task. The subsections that follow discuss tools and techniques for debugging the rewrite rules.

Using the -C command-line flag causes sendmail to read an alternate configuration file. This feature is helpful during debugging because it permits modifications and testing on a separate copy of the configuration file from the one currently in use. This precaution eliminates the chance that a buggy configuration file will be used by an instance of sendmail that is trying to deliver real mail. This flag also provides a convenient way to test any number of configuration files without fussy and potentially confusing renames. See “Using a Different Configuration File” and “Command-Line Flags” for more information.

Invoking sendmail with the -bt flag causes it to run in “test mode.” For example, the following command invokes sendmail in test mode and causes it to read configuration file test.cf:

/usr/lib/sendmail -bt -Ctest.cf 

In this mode, sendmail processes lines of the form

rwsets address

where rwsets is the list of rewriting sets to use and address is an address to which you apply the sets. In test mode, sendmail shows the steps it takes as it proceeds, finally showing the final address.

A comma-separated list of rule sets causes sequential application of rules to an input. For example, the following command first applies rule set 3 to the value monet@giverny. Rule set 1 is applied to the output of rule set 3, followed similarly by rule sets 21 and 4:

3,1,21,4 monet@giverny

---

Note: Some versions of sendmail, including those provided with all versions of IRIX prior to IRIX 4.0, automatically apply rule set 3 to input before applying the requested rule set sequence. Versions of sendmail in IRIX 4.0 and later do not apply rule set 3; rule set 3 must be specifically requested.

---

The input and output of each rule set is displayed. For example, input of

3,0 foo@bar

might result in output that looks like this:

rewrite: ruleset 3 input: foo @ bar
rewrite: ruleset 3 returns: foo < @ bar >
rewrite: ruleset 0 input: foo < @ bar > 
rewrite: ruleset 30 input: foo < @ bar . com > 
rewrite: ruleset 30 returns: foo < @ bar . com > 
rewrite: ruleset 0 returns: 
$# forgn $@ bar . com $: foo < @ bar . com > 

This output indicates that, given the address foo@bar, rule set 0 will select the forgn mailer and direct it to connect to host bar.com, which will be told to send the mail on to foo@bar.com. Furthermore, rule set 0 “called” rule set 30 at one point while processing the address.

The -d21 debugging flag causes sendmail to display detailed information about the rewrite process. This flag is most useful when used with the test mode described in the preceding subsection. The most useful setting of this flag is -d21.12, which shows all rewrite steps. Higher levels of the -d21 flag are rarely needed and create enormous amounts of output.

The standard /usr/lib/sendmail.cf file supplied with IRIX includes a special “debugging” rewrite rule. This rule is defined as follows:

# insert this handy debugging line wherever you have problems
#R$*                            $:$>99$1

Note that rule set 99 is an empty rule set that does nothing. Placing one or more (uncommented) copies of this rule anywhere within a rule set forces sendmail to display an intermediate rewrite result without using the -d21 flag. The following test mode output illustrates the use of the debugging rewrite rule:

rewrite: ruleset 3 input: foo @ bar
rewrite: ruleset 3 returns: foo < @ bar > 
rewrite: ruleset 0 input: foo < @ bar > 
rewrite: ruleset 99 input: foo < @ bar . com > 
rewrite: ruleset 99 returns: foo < @ bar . com > 
rewrite: ruleset 99 input: foo < @ barcom > 
rewrite: ruleset 99 returns: foo < @ barcom > 
rewrite: ruleset 0 returns: 
$# ether $@ barcom $: foo < @ barcom >

Note that somewhere between the first and second appearance of the debugging rewrite rule in rule set 0, the host name was mangled from bar.com to barcom.

To add an outgoing mailer to a mail system, you must define the characteristics of the mailer. Each mailer must have an internal name. This name can be arbitrary, except that the names “local” and “prog” must be defined.

The pathname of the mailer must be given in the P field. If this mailer is accessed by means of an IPC connection (socket), use the string “[IPC]” instead.

The F field defines the mailer flags. Specify an f or r flag to pass the name of the sender as an -f or -r flag respectively. These flags are passed only if they were passed to sendmail, so that mailers that give errors under some circumstances can be placated. If the mailer is not picky, just specify “-f $g” in the argv template. If the mailer must be called as root, use the S flag; this flag will not reset the user ID before calling the mailer. (sendmail must be running setuid to root for this technique to work.)

If this mailer is local (that is, it will perform final delivery rather than another network hop), use the l flag. Quote characters (backslashes and quotation marks) can be stripped from addresses if the s flag is specified; if it is not, 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, the argv template containing $u will be repeated for each unique user on a given host. The e flag marks the mailer as being expensive, causing sendmail to defer connection until a queue run. (For this technique to be effective, you must use the c configuration option.)

An unusual case is the C flag: it applies to the mailer the message is received from, rather than the mailer being sent to. If this flag is set, the domain specification of the sender (that is, the @host.domain part) is saved and is appended to any addresses in the message that do not already contain a domain specification. For example, if the C flag is defined in the mailer corresponding to jd@company.com, a message of the form

From: jd@company.com
To: buddy@USomewhere.edu, jane

will be modified to

From: jd@company.com
To: buddy@USomewhere.edu, jane@company.com

Other flags are described in “Mailer Flags”.

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

For example, depending on the domain it is being shipped into, a header of the form “From: jd” might be changed to “From: jd@company.com” or “From: company!jd.”

These sets can also be used to do special-purpose output rewriting with rule set 4.

The E field defines the string to use as an end-of-line indication. A string containing only a newline is the default. The usual backslash escapes (\r, \n, \f, \b) can be used.

Finally, an argv template is given as the E field. It can have embedded spaces. If there is no argv with a $u macro in it, sendmail will speak SMTP to the mailer. If the pathname for this mailer is “[IPC],” the argv should be

IPC $h [ port ]

where port is the port number to connect to. This number is optional.

For example, the following specification specifies a mailer to do local delivery and a mailer for Ethernet delivery:

Mlocal, P=/bin/mail, F=EDFMlsmhu, S=10, R=20, A=mail -s -d $u 
Mether, P=[IPC], F=mDFMhuXC, S=11, R=21, M=1000000, E=\r\n, \
       A=IPC $h 

The first mailer is called “local” and is located in the file /bin/mail. It has the following characteristics:

Rule set 10 is to be applied to sender addresses in the message and rule set 20 is to be applied to recipient addresses. The argv to send to a message is the word mail, the word -s, the word -d, and words containing the name of the receiving user.

The second mailer is called “ether” and is connected with an IPC connection. It has the following characteristics:

Sender addresses are processed by rule set 11; recipient addresses, by rule set 21. There is a 1,000,000-byte limit on messages passed through this mailer. The EOL string for this mailer is "\r\n" and the argument passed to the mailer is the name of the recipient host.