sendmail

sendmailSearch this book
Previous: 34.7 PitfallsChapter 34
Options
Next: 35. Headers
 

34.8 Alphabetized Reference

In the following sections we present all the options that are currently available for V8 sendmail. They are in alphanumeric order sorted by the multicharacter name. The multicharacter name appears at the left of each major section header. If an old single-character name exists, it is displayed parenthetically to the right of the multicharacter name. In a few cases, multicharacter names have replaced macros. In those instances the macro is displayed nonparenthetically.

34.8.1 AliasFile (A)

Define the aliases file location

(All versions)

The AliasFile (A) option must be declared for sendmail to do aliasing. If you omit this option, sendmail may silently assume that you do not want to do aliasing at all. There is no default compiled into sendmail for the location of the aliases file. [4] For V8 m4 configurations an appropriate default will be defined based on your operating system.

[4] Beginning with V8.7, a switched-services file (see Section 34.8.61) may cause aliases to be found in NIS or other services and may completely ignore alias files altogether.

If you specify a file that doesn't exist (such as /et/aliases if you really meant /etc/aliases) or one that is unreadable, sendmail complains, for example with

Can't open /et/aliases

This is a nonfatal error. The sendmail program prints it and continues to run but assumes that it shouldn't do aliasing.

The forms of the AliasFile (A) option are as follows:

OAlocation                        <- configuration file (old form)
-oAlocation                       <- command line (old form)
O AliasFile=location              <- configuration file (beginning with V8.7)
-OAliasFile=location              <- command line (beginning with V8.7)
define(`ALIAS_FILE',`location')   <- V8 m4 configuration

The location is an argument of type string and can be an absolute or a relative pathname. A relative path (such as ../aliases) can be used for testing but should never be used in the production version of your sendmail.cf file. To do so opens a security hole. Such a path is interpreted by sendmail as relative to the queue directory.

This option can be used to change the name of the aliases file (a possible consideration for security). If you change the location or name of the aliases file, be aware that other programs (such as emacs and Sun's nis services) may cease to work properly.

Note that with the m4 technique the only way to eliminate the default alias file declaration (and thus to eliminate all aliases support) is to undefine ALIAS_FILE like this:

undefine(`ALIAS_FILE')

The sendmail program also allows you to use several alias databases simultaneously. They are listed with the AliasFile (A) option as, for example, like this:

O AliasFile=/etc/aliases/users,/etc/aliases/maillists

In this case, sendmail will look up an alias first in the database /etc/aliases/users. If it is not found, sendmail will then look in /etc/aliases/maillists. The number of simultaneous alias files is limited to MAXALIASDB (see Section 18.8.19, MAX...) as defined in conf.h (by default 12). The -bi command-line switch will rebuild all alias databases in the order listed in this AliasFile (A) option. Multiple declarations lines may appear in the file, each adding an alias database to the list:

O AliasFile=/etc/aliases/users     # aliases local users first
O AliasFile=/etc/aliases/maillists # then mailing lists
O AliasFile=/etc/aliases/retired   # then retired accounts

Duplicates are not detected. Therefore the following causes /etc/aliases to be searched and rebuilt twice each time:

O AliasFile=/etc/aliases
O AliasFile=/etc/aliases

Multiple alias files may similarly be specified on the command line with the -o switch. But be aware that any alias files that are declared in the command line cause all the configuration file alias declarations to be ignored.

In addition to the name of alias databases, sendmail also allows you to specify the class of each. The class is the same as the classes that are available for the K configuration command (see Section 33.3, "The K Configuration Command"). The class prefixes the name, and the two are separated by a colon:

O AliasFile=nis:mail.aliases

This example tells sendmail to look up aliases in the nis class (the nis) database called mail.aliases. The class can include switches that mean the same thing as those allowed for the K configuration command.

For example:

O AliasFile=nis:-N mail.aliases

Here, the -N class switch causes lookups to include a trailing null byte with each key. [5]

[5] Also see Section 24.4.4, "Duplicate Entries and Automation", which illustrates the -A option switch for appending keys.

Under V8.6 sendmail the reasonable classes are hash, btree, dbm, nis, and udb. Under V8.7 sendmail this list can also include nisplus for Sun's nisplus and hesiod for Hesiod support. (See Section 33.3.2, "The class" and Section 33.3.4, "The switches".) But note that it is generally better to use the service-switch file to select services because it is less confusing.

If a class is not a known one and if the -d27 command-line switch (see Section 37.5.88, -d27.1) is specified, sendmail prints

Unknown alias class badclass

If the class is one that cannot support aliasing (as defined by MCF_ALIASOK in conf.c) and if the -d27 command-line switch is specified, sendmail prints:

setalias: map class badclass can't handle aliases

In both cases the badclass is the offending class. Both errors cause the AliasFile (A) option's alias file declaration to be ignored.

Beginning with V8.7 sendmail, the declaration and use of alias files is further complicated [6] by the introduction of switched-services files (see Section 34.8.61). If the file defined by the ServiceSwitchFile option exists, and if it defines the type and location of alias information, each alias definition is used just as if it was included in the configuration file (although the syntax differs). On Solaris, Ultrix, and OSF systems, switched-service files are supplied by the operating system. With these you should beware the silent introduction of unexpected alias services. On other operating systems you may set up a V8.7 switched-service file that can be used for aliases if you wish.

[6] Or simplified, depending on whom you talk to.

The AliasFile (A) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.2 AliasWait (a)

Wait for aliases file rebuild

(All versions)

Whenever sendmail rebuilds the aliases database, it first clears the old database. It then rebuilds the database and, when done, adds the special entry @:@. Before sendmail attempts to use the database, it first looks in that database for the special entry @:@ that should be present. This curious entry is employed because it is one that is always illegal in an aliases file. If sendmail doesn't find that entry (whether because a user ran newaliases or because another invocation of sendmail is currently rebuilding it), it waits 2 seconds for that entry to appear, then checks again. If the entry is still unavailable, the wait is doubled (up to maximum wait of 60 seconds). The total time waited (after all the sleeps without success) is the interval specified by this AliasWait (a) option.

When the @:@ appears, sendmail checks to see whether the database still needs to be rebuilt and rebuilds it if it does. If the special entry @:@ does not appear after the specified time and if the AutoRebuildAliases (D) option (see Section 34.8.4) is set, sendmail assumes that some other process died while that other process was rebuilding the database. This assumption paves the way for sendmail to go ahead and rebuild the database. Note that if AutoRebuildAliases (D) option is not set, sendmail uses the old information.

The forms of the AliasWait (a) option are as follows:

Oadelay                          <- configuration file (old style)
-oadelay                         <- command line (old style)
O AliasWait=delay                <- configuration file (beginning with V8.7)
-OAliasWait=delay                <- command line (beginning with V8.7)
define(`confALIAS_WAIT',delay)   <- V8 m4 configuration

The delay argument is of type time and, if omitted, defaults to 5 minutes. If the entire AliasWait (a) option is omitted or if delay is zero or non-numeric, the database is not automatically rebuilt. If the unit of time desired is omitted, the delay defaults to minutes. If you use the V8 m4 configuration, the default for confALIAS_WAIT is 10 minutes.

The AliasWait (a) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.3 AllowBogusHELO

Allow no host with HELO or EHLO

(V8.8 and above)

Prior to V8.7, sendmail would accept without complaint an SMTP HELO command (or an EHLO) that omitted the hostname:

220-oldsite.uofa.edu  Sendmail 8.6.13/8.6.13 ready at Fri, 31 Dec 1996 08:11:44 -0700
220 ESMTP spoken here
HELO
250 oldsite.uofa.edu Hello here.ufa.edu [123.45.67.89], pleased to meet you

RFC1123, section 5.2.5, specifies that all HELO and EHLO commands must be followed by a fully qualified hostname.

HELO here.uofa.edu
EHLO here.uofa.edu

Beginning with V8.7, omitting the hostname results in one of the following errors:

501 helo requires domain address
501 ehlo requires domain address

Note that there is no check to see that the hostname is actually that of the connecting host unless PICKY_HELO_CHECK is declared when sendmail is compiled(see Section 18.8.35, PICKY...). Also note that the hostname that is specified must appear to be a correctly formed hostname. If it is not, the following is printed:

501 Invalid domain name

If you favor forcing other sites to obey the RFCs, don't enable this option. But note that you may need to enable it if your site accepts connections from other sites that don't obey the protocols.

The AllowBogusHELO option is used like this:

O AllowBogusHELO=bool            <- V8.8 and above

The bool is of type Boolean. If it is absent, the option defaults to true (do allow the hostname to be omitted). If the entire option declaration is missing, the default is false (require the hostname to be present). Note that there is no m4 shorthand for declaring this option.

The AllowBogusHELO option safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.4 AutoRebuildAliases (D)

Auto-rebuild the aliases database

(All versions)

The need to rebuild the aliases database is determined by comparing the modification time of the aliases source file, as defined by the AliasFile (A) option (see Section 34.8.1), to the modification time of the corresponding aliases.pag and aliases.dir, or aliases.db, database files. If the source file is newer and if this AutoRebuild-Aliases (D) option is set, sendmail attempts to rebuild the aliases database. If this option is not set, sendmail prints the following warning and uses the information in the old database:

Warning: alias database fname out of date

Here, fname is the name of the source file. If you set this AutoRebuildAliases (D) option, be sure that the AliasWait (a) option (see Section 34.8.2) is also declared and given a nonzero time argument. (File locking, to prevent simultaneous rebuilds, is described under the AliasWait (a) option.)

The forms of this AutoRebuildAliases (D) option are as follows:

ODbool                            <- configuration file (old style)
-oDbool                           <- command line (old style)
O AutoRebuildAliases=bool         <- configuration file (beginning with V8.7)
-OAutoRebuildAliases=bool         <- command line (beginning with V8.7)
define(`confAUTO_REBUILD',bool)   <- V8 m4 configuration

With no argument, AutoRebuildAliases (D) is set to true (the aliases database is automatically rebuilt). If the entire AutoRebuildAliases (D) option is missing, it defaults to false (no automatic rebuilds).

IDA sendmail uses fcntl(3) to prevent simultaneous rebuilds. Old versions of sendmail used flock(3). V8 sendmail uses either fcntl(3) or flock(3), depending on how it was compiled.

The AutoRebuildAliases (D) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.5 BlankSub (B)

Set unquoted space replacement

(All versions)

Some mailer programs have difficulty handling addresses that contain spaces. Such addresses are both illegal under RFC821 and RFC822 and subject to gross misinterpretation. For example, the address

John Q [email protected]

is viewed by some MUA programs as being composed of three separate addresses: John, Q, and [email protected]. To prevent this misinterpretation, such MUAs usually either quote the user portion or escape each space with a backslash:

"John Q Public"@wash.dc.gov <- quoted
John\ Q\ [email protected] <- escaped

The BlankSub (B) option is intended to handle an address that contains internal spaces, and is neither quoted nor escaped. For sendmail a space is any character defined by the C language library routine isspace(3).

Most sites use a . (dot or period) or an _ (underscore) character to replace unquoted space characters. That is, they declare the BlankSub (B) option as one of the following:

OB.
OB_

Feeding the address

John Q [email protected]

through sendmail with the option OB. set yields

[email protected]

The forms of the BlankSub (B) option are as follows:

OBchar                         <- configuration file (old style)
-oBchar                        <- command line (old style)
O BlankSub=char                <- configuration file (beginning with V8.7)
-OBlankSub=char                <- command line (beginning with V8.7)
define(`confBLANK_SUB',char)   <- V8 m4 configuration

The argument char is of type character and is a single character. The default, if this option is omitted or if the char argument is omitted, is that an unquoted space character is replaced with a space character (which does nothing to correct the problem at all). The default for the m4 technique is the dot (.) character.

Note that old-style addresses are delimited from each other with spaces rather than commas. Such addresses may be wrongly joined into a single address if the char is other than a space. Acceptance of such old-style addresses is determined by the setting of the OldStyleHeaders (o) option (see Section 34.8.44).

Also note that this BlankSub (B) option may also be used when tokenized addresses are reassembled (see Section 28.2.3, "Pasting Addresses Back Together").

The BlankSub (B) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.6 CheckAliases (n)

Check right-hand side of aliases

(V8.1 and above)

Ordinarily, when sendmail rebuilds an aliases database (as defined by the AliasFile (A) option, see Section 34.8.1), it checks only the addresses to the left of the colon to make sure they all resolve to a delivery agent that has the F=A flag set (see Section 30.8.12, F=A). It is possible to also have addresses to the right of the colon checked for validity by setting option CheckAliases (n) option to true.

The forms of the CheckAliases (n) option are as follows:

Onbool                             <- configuration file (old style)
-onbool                            <- command line (oldstyle)
-on                                <- command line shorthand
O CheckAliases=bool                <- configuration file (beginning with V8.7)
-OCheckAliases=bool                <- command line (beginning with V8.7)
define(`confCHECK_ALIASES',True)   <- V8 m4 configuration

The bool is of type Boolean. If it is absent, the option defaults to true (do check the right-hand side of aliases). If the entire option declaration is missing, the default is false (don't check the right-hand side of aliases). The default for the m4 configuration technique is false.

Addresses to the right of the colon are checked only to be sure they are good addresses. Each is processed by rule set 3 and then rule set 0 to select a delivery agent. Processing merely needs to successfully select any non-#error delivery agent (see Section 30.5.2, "The error Delivery Agent"). The sendmail program prints and logs the following warning and skips any address that fails to select a valid delivery agent:

address... bad address

If the address selects an #error delivery agent, the error text for that error is printed instead:

address... user address required

The CheckAliases (n) option is further described in Section 24.5.2, "Check the Right Side of Aliases". This option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.7 CheckpointInterval (C)

Checkpoint the queue

(V8.1 and above)

When a single email message is sent to many recipients (those on a mailing list, for example), a single sendmail process handles all the recipients. Should that sendmail process die or be killed halfway through processing, there is no record that the first half was delivered. As a result, when the queue is later reprocessed, the recipients in that first half will receive the message a second time.

The CheckpointInterval (C) option can limit the duplication. It tells sendmail to rewrite (checkpoint) its qf file (which contains the list of recipients; see Section 23.2.5, "The Queue Control File: qf") after each group of a specified number of recipients has been delivered. Recipients who have already received mail are deleted from the list, and that list is rewritten to the qf file. The forms of the CheckpointInterval (C) option are as follows:

OCnum                                   <- configuration file (old style)
-oCnum                                  <- command line (old style)
O CheckpointInterval=num                <- configuration file (beginning with V8.7)
-OCheckpointInterval=num                <- command line (beginning with V8.7)
define(`confCHECKPOINT_INTERVAL','num') <- V8 m4 configuration

The num argument is of type numeric and specifies the number of recipients in each group. If num is entirely missing, is non-numeric, or is zero, this feature is disabled. If the entire CheckpointInterval (C) option is missing, the default is 10. There is a small performance penalty that increases as num approaches 1. A good starting value is 4, meaning that at most four people will get duplicate deliveries. Note that the F=M flag on local delivery will try as many recipients as possible before checkpointing, even if that number is greater than the value of this CheckpointInterval option. The CheckpointInterval (C) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.8 ClassFactor (z)

Multiplier for priority increments

(All versions)

The ClassFactor (z) option specifies a multiplying weight (factor) for a message's precedence when determining a message's priority. This option interacts with the RecipientFactor (y) option (see Section 34.8.53), and both options are described under that latter option.

The forms of the ClassFactor (z) option are as follows:

Ozfactor                                 <- configuration file (old form)
-ozfactor                                <- command line (old form)
O ClassFactor=factor                     <- configuration file (beginning with V8.7)
-OClassFactor=factor                     <- command line (beginning with V8.7)
define(`confWORK_CLASS_FACTOR',factor)   <- V8 m4 configuration

The argument factor is of type numeric. If that argument is missing, the default value is zero. If the entire option is missing, the default value is 1800. The default for the m4 technique is to omit this option.

The ClassFactor (z) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.9 ColonOkInAddr

Allow colons in addresses

(8.7 and above)

One possible form of an address is called "list syntax" and looks like this:

group: list;

Here, group is the name of a mailing list, and list is a list of zero or more addresses to which the message should be delivered (see Section 17.1.2.1, "A rule to handle List:;"). To understand this kind of address, sendmail needs to view the prefix and colon as a comment and the trailing semicolon as a comment. This is similar to treating everything outside an angle-bracketed address as a comment:

group:  list  ;
group: <list> ;

For such addresses to be recognizable, it is necessary to prohibit the use of other addresses that contain colons, unless those colons appear inside a part of the address that is surrounded by angle brackets. That is, to use list syntax, addresses like the following cannot be allowed:

host:[email protected]

To handle this situation, V8.7 sendmail has introduced the ColonOkInAddr option. It is used like this:

O ColonOkInAddr=bool                  <- configuration file
-OColonOkInAddr=bool                  <- command line
define(`confCOLON_OK_IN_ADDR',bool)   <- m4 configuration

The argument bool is of type Boolean. If it is absent, this option is true (colons are okay, so list syntax is not recognized). If this option is entirely omitted or if bool is false, colons are not okay, so list syntax is recognized. Note that for version 5 or earlier configuration files (see Section 27.5, "The V Configuration Command" for a description of the V configuration command), this option is automatically set to true. Also note that for m4 configurations this option is absent (false) by default.

Note that DECnet style addresses (see Section 29.4.4, "Handling Specialty Addresses") legitimately contain double colons (e.g., host::user). DECnet addresses are correctly recognized no matter how this ColonOkInAddr option is set.

The ColonOkInAddr option is safe. If it is specified from the command line, sendmail will not relinquish its root privilege.

34.8.10 ConnectionCacheSize (k)

Multiple-SMTP connections

(V8.1 and above)

Usually, sendmail uses a single autonomous SMTP session to transmit one email message to another host. It connects to the other host, transmits the message, and closes the connection. Although this approach is sufficient for most mail, there are times when sending multiple messages during a single connection is preferable. This is called caching connections.

When sendmail caches a connection, it connects to the other host and transmits the mail message as usual. But instead of closing the connection, it keeps the connection open so that it can transmit additional mail messages without the additional overhead of opening and closing the connection each time. The ConnectionCacheSize (k) option of V8 sendmail specifies that open connections to other hosts should be maintained and the maximum number of those connections. The forms of the ConnectionCacheSize (k) option are as follows:

Oknum                               <- configuration file (V8.6)
-oknum                              <- command line (V8.6)
O ConnectionCacheSize=num           <- configuration file (beginning with V8.7)
-OConnectionCacheSize=num           <- command line (beginning with V8.7)
define(`confMCI_CACHE_SIZE',num)    <- V8 m4 configuration

There may be optional whitespace preceding the num. The num is an integer that specifies the maximum number of simultaneous connections to keep open. If num is zero, this caching feature is turned off. A value of 1 is good for workstations that forward all mail to a central mail server and is the default that is used if this option is entirely missing. When configuring with V8's m4 technique, the default is 2. A value of 4 is the maximum for most machines that forward mail directly over the Internet. Higher values require that you increase the number of open files allowed per process at the system level.

Caching is of greatest benefit in processing the queue. V8 sendmail automatically adapts to conditions to avoid caching connections for each invocation of sendmail. Maintenance of an open connection can delay return to the user's program, for example, and too many open connections to a common target host can create a high load on that host.

When caching is enabled with this ConnectionCacheSize (k) option, the ConnectionCacheTimeout (K) option should also be declared to set the connection timeout. The ConnectionCacheSize (k) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.11 ConnectionCacheTimeout (K)

Multiple-SMTP time-outs

(V8.1 and above)

Maintaining a cached connection to another host (see Section 34.8.10) imposes a penalty on both the local host and the other host. Each connection means that the other host is running a forked sendmail process that is doing nothing but waiting for an SMTP QUIT message to close the connection or for more mail to arrive. The local host has open sockets that consume system resources.

To limit the impact on other hosts, V8 sendmail offers the ConnectionCacheTimeout (K) option. This option tells sendmail how long to wait for another mail message before closing the connection.

The forms of the ConnectionCacheTimeout (K) option are as follows:

OKwait                                 <- configuration file (V8.6)
-oKwait                                <- command line (V8.6)
O ConnectionCacheTimeout=wait          <- configuration file (beginning with V8.7)
-OConnectionCacheTimeout=wait          <- command line (beginning with V8.7)
define(`confMCI_CACHE_TIMEOUT',wait)   <- V8 m4 configuration

There may be optional whitespace preceding the wait. The wait is of type time and specifies the period to wait before timing out a cached connection. If this option is entirely missing, the default (for both the configuration file and the m4 configuration technique) is 300 seconds (five minutes). When specifying the wait, be sure to include a trailing s character. If you don't, the number that you specify is interpreted by default as a number of minutes. The wait should never be longer than five minutes. A value of 0 essentially turns off caching.

This ConnectionCacheTimeout (K) option has an effect only if the ConnectionCacheSize (k) option (see Section 34.8.10) is also declared. The ConnectionCacheTimeout (K) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.12 ConnectionRateThrottle

Incoming SMTP connection rate

(V8.8 and above)

Whenever an outside site connects to sendmail's SMTP port, sendmail fork(2)s a copy of itself. That copy (the child) processes the incoming message. Beginning with V8.8, sendmail keeps track of how many child processes it has spawned to handle incoming connections. The MaxDaemonChildren (see Section 34.8.35) option can be used to reject connections when the number of children has exceeded a specified threshold.

A different approach is to slow down acceptance of, rather than to reject, new connections when the number of children becomes too high. This allows the QueueLA (x) option (see Section 34.8.50) and the RefuseLA (X) option (see Section 34.8.54) to operate properly even if many incoming connections arrive simultaneously. You slow incoming connections with the ConnectionRateThrottle option:

O ConnectionRateThrottle=num                      <- V8.8 and above
define(`confCONNECTION_RATE_THROTTLE', num)       <- V8 m4 technique

The num is of type numeric. If it is present and greater than zero, connections are slowed when more than that number of connections arrive within one second. If num is less than or equal to zero, or absent, no threshold is enforced. If the entire option is missing, the default becomes zero. The default for the m4 technique is to omit this option.

To illustrate how the slowdown operates, consider a situation in which num is set to 3, and 12 connections come in simultaneously. The first three connections are handled immediately. The next three are handled after one second. The three after that are handled after two seconds, and so on. The twelfth connection would be handled after a delay of three seconds.

Note that this option and the MaxDaemonChildren option (see Section 34.8.35) affect incoming connections differently.

The ConnectionRateThrottle option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.13 DaemonPortOptions (O)

Options for the daemon

(V8.1 and above)

The DaemonPortOptions (O) option is used to customize the daemon's SMTP service. The form for this option is as follows:

OOpair,pair,pair                                <- configuration file (old form)
-oOpair,pair,pair                               <- command line (old form)
O DaemonPortOptions=pair,pair,pair              <- configuration file (beginning with V8.7)

-ODaemonPortOptions=pair,pair,pair              <- command line (beginning with V8.7)
define(`confDAEMON_OPTIONS',`pair,pair,pair')   <- V8 m4 configuration

The DaemonPortOptions (O) is followed by a comma-separated list of pairs, in which each pair is of the form:

key=value

Only six keys are available, and prior to V8.7 they were case-sensitive. Prior to V8.7 an unknown key was silently ignored. Now an unknown key not only is ignored but also causes following error to be printed:

DaemonPortOptions unknown parameter "key"

The list of all currently defined keys is shown in Table 34.12.

Table 34.12: DaemonPortOptions Option Keywords
KeyMeaning
AddrSection 34.8.13.1, "DaemonPortOptions=Addr"

The network to accept connection from

FamilySection 34.8.13.2, "DaemonPortOptions=Family"

The type network we are connected to

ListenSection 34.8.13.3, "DaemonPortOptions=Listen"

The size of the listen(2) queue

PortSection 34.8.13.4, "DaemonPortOptions=Port"

The port number on which sendmail should listen

ReceiveSizeSection 34.8.13.5, "DaemonPortOptions=ReceiveSize"

The size of the TCP/IP receive buffer

SendSizeSection 34.8.13.6, "DaemonPortOptions=SendSize"

The size of the TCP/IP send buffer

Only the first character in each key is recognized, so a succinct declaration such as the following can be used to change the port used by the daemon:

OOP=26,A=our-net    # Only listen for local mail                 <- old form
O DaemonPortOptions=P=26,A=our-net  # Only listen for local mail <- beginning with V8.7

The O option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.13.1 DaemonPortOptions=Addr

The Addr key is used to specify the network to use. The value is the name [7] or IP address of one of your network interfaces:

[7] Names did not work prior to V8.8 sendmail.

O DaemonPortOptions=Addr=128.32.204.25     # listen to our internal network only

If the Addr pair is omitted, the default network becomes INADDR_ANY, which allows connections from any network.

34.8.13.2 DaemonPortOptions=Family

The Family key is used to specify the network family. The legal possible values are inet for AF_INET, iso for AF_ISO, ns for AF_NS, and x.25 for AF_CCITT.

O DaemonPortOptions=Family=iso

Note that only inet and iso are currently supported. The default is inet. Also note that inet requires NETINET to be defined, and iso requires NETISO to be defined when sendmail is being compiled (see Section 18.8.26, NET...).

34.8.13.3 DaemonPortOptions=Listen

When sendmail begins to run in daemon mode, it executes a listen(2) system call as part of monitoring its SMTP port for incoming mail. The second argument to listen(2) defines the maximum length to which the incoming queue of pending connections may grow. If a connection request arrives with the queue full, the client will receive an error that indicates ECONNREFUSED. This Listen key is used to change the size of the incoming queue from its default of 10. If Listen is less than or equal to zero, listen(2) will silently set its own default. But note that some kernels may have built-in defaults of their own, so setting Listen may have no effect at all.

34.8.13.4 DaemonPortOptions=Port

The Port key is used to specify the service port on which the daemon should listen. This is normally the port called smtp, as defined in the /etc/services file. The value may be either a services string (such as smtp) or a number (such as 25). This key is useful inside domains that are protected by a firewall. By specifying a non-standard port, the firewall can communicate in a more secure manner with the internal network while still accepting mail on the normal port from the outside world:

O DaemonPortOptions=Port=26

If this pair is missing, the port defaults to smtp.

34.8.13.5 DaemonPortOptions=ReceiveSize

The ReceiveSize key is used to specify the size of the TCP/IP receive buffer. The value is a size in bytes. This should not be set unless you are having performance problems. Slow links (such as 9.6K SL/IP lines) might profit from a setting of 256, for example:

O DaemonPortOptions=ReceiveSize=256

The default value is set by the system (see setsockopt(2)).

34.8.13.6 DaemonPortOptions=SendSize

The SendSize key is used to specify the size of the TCP/IP send buffer. The value is a size in bytes. This should not be set unless you are having performance problems. Slow links (such as 9.6K SL/IP lines) might profit from a setting of 256, for example:

O DaemonPortOptions=SendSize=256

The default value is set by the system (see setsockopt(2)).

34.8.14 DefaultCharSet

Content-Type: character set

(V8.7 and above)

When a mail message is converted from 8 to 7 bits (see the EightBitMode (8) option in Section 34.8.22), it is important that the result look like a MIME message. V8.7 sendmail first outputs the following header if one is not already present:

MIME-Version: 1.0

After that, V8.7 sendmail looks for a Content-Type: header (see Section 35.10.9, Content-Type:). If none is found, the following is inserted, where charset is the value declared for this option:

Content-Type: text/plain; charset=charset

The forms of the DefaultCharSet option are as follows:

O DefaultCharSet=charset                  <- configuration file
-ODefaultCharSet=charset                  <- command line
define(`confDEF_CHAR_SET',charset)        <- m4 configuration

If DefaultCharSet is undefined, charset defaults to the string "unknown-8bit." The default for the m4 technique is to omit this option.

Note that if the C= equate (Section 30.4.2, C=) is present for the sender's delivery agent, that character set supersedes the DefaultCharSet.

The DefaultCharSet option is safe. If specified from the command line, sendmail will not relinquish its root privilege.

34.8.15 DefaultUser (g)(u)

Default delivery agent identity

(All versions)

The sendmail program can be run as an suid root process (that is, with the permissions of the root, no matter who runs it) or as an ordinary process, run by an ordinary (nonprivileged) user (that is, with root privilege only if it is run by root). When sendmail is run so that it has root privilege, it must give up that privilege under certain circumstances to remain secure. [8] When it can't set its identity to that of a real user, sendmail sets its gid to that specified by the g option and its uid to that specified by the u option. For version 8.7 and above, the DefaultUser option sets both the user and group identities. [9]

[8] V8 is more security conscious and presumes that it is still root even if it has given up that privilege.

[9] In essence, the g and u options have been deprecated in favor of a single DefaultUser option, which sets both.

When sendmail is running with root privilege and when the F=S delivery agent flag (see Section 30.8.40, F=S) is not specified, sendmail changes its owner and group identity to that of an ordinary user in the following circumstances:

1.

If the mail message is forwarded because of a user's ~/.forward file and if delivery is via a delivery agent that has the F=o flag set (see Section 30.8.33, F=o), then sendmail changes its owner and group identity to that of the user whose ~/.forward file was read.

2.

Otherwise, if the mail message is being delivered through an aliases(5) file's :include: mailing list expansion and if delivery is via a delivery agent that has the F=o flag set (see Section 30.8.33) or to a file, then sendmail changes its owner and group identity to that of the owner of the file that was specified by the :include: line.

3.

Otherwise, if the sender of the mail message is local and if delivery is via a delivery agent that does not have the F=o flag set (see Section 30.8.33) or to a file, then sendmail changes its owner and group identity to that of the sender. If the sender is root, sendmail changes its owner and group identity to that specified by the DefaultUser option.

4.

Otherwise, sendmail changes its owner and group identity to that specified by the DefaultUser option.

These user and group defaults are ignored if the delivery agent's F= equate includes the S flag (run as another specified user). These user and group defaults are also ignored for any delivery agent that specifies the U= equate (see Section 30.4.13, U=), which customizes user and group identities at the individual delivery agent level, but only if the F=o equate is not specified.

The forms of the DefaultUser (u) (g) option are as follows:

Ouuid                               <- user, configuration file (old form)
-ouuid                              <- user, command line (old form)
Oggid                               <- group, configuration file (old form)
-oggid                              <- group, command line (old form)
Ouuid:gid                           <- both, configuration file (beginning with V8.7)
-ouuid:gid                          <- both, command line (beginning with V8.7)
O DefaultUser=uid:gid               <- both, configuration file (beginning with V8.7)
-ODefaultUser=uid:gid               <- both, command line (beginning with V8.7)
define(`confDEF_USER_ID',uid)       <- user, V8 m4 configuration
define(`confDEF_GROUP_ID',gid)      <- group, V8 m4 configuration (obsolete as of V8.7)
define(`confDEF_USER_ID',uid:gid)   <- both, V8 m4 configuration

The arguments uid and gid are of type numeric. Beginning with V8 sendmail, user or group names can also be text (for example, nobody). Beginning with V8.7 sendmail, the user definition with DefaultUser or u can specify both user and group. For example,

O DefaultUser=daemon:nogroup

There may be arbitrary whitespace between the user (daemon), the colon, [10] and the group (nogroup). If the group is missing, the value that is assigned to it varies depending on the nature of the uid specification. If the uid is a name, the group becomes the default group of that user as defined in the passwd(5) file. If the uid is numeric, the value in the group is not changed. For example, consider this passwd(5) file entry, where the group 12 corresponds to the group name bumgroup:

[10] The character between the user and group notations can be a colon, a period, or a forward slash. The colon is recommended.

bogus:*:10:12::/:

Then all the following are equivalent:

O DefaultUser=bogus
O DefaultUser=bogus:12
O DefaultUser=bogus:bumgroup

Og12[lbbcb] taken together
Ou10[ltbcb]

But the following combination causes the group to reset to 12:

Og77
Oubogus

Under pre-8.7 sendmail a missing argument causes the value 0 to be used for the respective user or group identities. If an entire u or g option is missing, the default value becomes 1 (usually daemon). Under V8.7 sendmail the default is -1. In NFS-mounted environments, safe values for these options are one less than those of the user nobody and the group nogroup.

For maximum security, you should create a special pseudo-user and assign that pseudo-user to this option. (See Section 22.8.3.1, "The DefaultUser option" for a more detailed description of this approach.)

The g, u, and DefaultUser options are not safe. If specified from the command line, they may cause sendmail to relinquish its root privilege.

34.8.16 DeliveryMode (d)

Set delivery mode

(All versions)

There are four modes that sendmail can use for delivering mail. Three have always been a part of sendmail: background, interactive, and queue-only. One is new to V8.7 sendmail: deferred.

The mode is selected with the DeliveryMode (d) option:

Odmode                             <- configuration file (old form)
-odmode                            <- command line (old form)
O DeliveryMode=mode                <- configuration file (beginning with V8.7)
-ODeliveryMode=mode                <- command line (beginning with V8.7)
define(`confDELIVERY_MODE',mode)   <- V8 m4 configuration

The mode argument is of type character. It is case sensitive (must be lowercase) and is selected from one of the keywords shown in Table 34.13. Only the first letter of each is recognized, but we recommend full words for improved clarity.

Table 34.13: DeliveryMode Option Keywords
KeywordDescription
backgroundSection 34.8.16.1, "DeliveryMode=background"

Background (asynchronous) delivery

deferredSection 34.8.16.2, "DeliveryMode=deferred"

Deferred (held as is) delivery (beginning with V8.7)

interactiveSection 34.8.16.3, "DeliveryMode=interactive"

Interactive (synchronous) delivery

queueonlySection 34.8.16.4, "DeliveryMode=queueonly"

Queued (held but processed) delivery

If the mode argument is missing, this option defaults to the i or interactive mode. If the entire DeliveryMode (d) option is missing, V8 sendmail then defaults to background mode, but old sendmail behaves unpredictably; consequently, this option should be considered mandatory. The default for a V8 m4 configuration is also background.

If the mode character is other than one of the first lowercase letters shown in Table 34.13 sendmail will print and log the following error and will immediately exit with an exit value of EX_USAGE as defined in <sysexits.h>:

Unknown delivery mode char

Queue-only and deferred modes are only available if QUEUE was defined when sendmail was compiled (see Section 18.8.37, QUEUE). If QUEUE was not defined and one of these two modes is selected, sendmail will print and log the following:

need QUEUE to set -odqueue or -oddefer

The DeliveryMode (d) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.16.1 DeliveryMode=background

Background mode - intended primarily [11] for use in the configuration file - allows sendmail to run asynchronously. This means that once sendmail has gathered the entire message and verified that the recipient is deliverable, it will fork(3) a copy of itself and exit. The copy, running in the background (asynchronously), will then handle the delivery. From the user's point of view, this mode allows the mail interface program to act as though it sent the message nearly instantaneously.

[11] A sending program (MUA) might need to use background mode on the command line (db) if the message is urgent and if the default in sendmail's configuration file is to queue all messages (with q mode).

34.8.16.2 DeliveryMode=deferred

Deferred mode - for use in either the command line or the configuration file - is much like queue-only mode except that all database lookups, including DNS, are deferred until the actual queue run. Deferred mode (new with V8.7) is preferred for dial-on-demand sites (typically, modem-based SL/IP or PPP connections). As in queue-only mode, all mail is queued for later delivery, but with deferred mode, code inside sendmail that would ordinarily interact with DNS is suppressed. This prevents the modem from being dialed and connections from being established every time mail is queued.

34.8.16.3 DeliveryMode=interactive

Interactive mode - intended for use from the command line - causes sendmail to run synchronously. This mode is useful primarily for debugging mail problems. Instead of going into the background with fork(3), it runs in the foreground (synchronously). In this mode, error messages are printed back to the controlling terminal rather than being mailed to the user as bounced mail. The -v command-line switch (see Section 36.7.41) automatically sets the mode to interactive.

34.8.16.4 DeliveryMode=queueonly

Queue-only mode - for use in either the command line or the configuration file - causes sendmail to synchronously queue mail. Queue-only mode is useful at sites that have huge amounts of UUCP mail or Usenet news batch feeds or when delivering to low priority addresses such as mailing lists. Queuing has the beneficial effect of serializing delivery through queue runs, and it reduces the load on a machine that many parallel backgrounded sendmail processes can cause. Queue-only mode is typically supplied as a command-line option to sendmail by the uuxqt(8) program. When queue-only mode is selected, all mail is queued for delivery, and none is actually delivered. A separate run of sendmail with its -q command-line switch (see Section 23.6.1, "Periodically with -q") is needed to actually process the queue. Note that addresses can still be looked up with DNS as a part of the queueing process. Consequently, queue-only mode is probably not suitable for dial-on-demand sites.

34.8.17 DialDelay

Connect failure retry time

(V8.7 and above)

Many Internet providers allow small sites (such as home machines) to dial up when there is a demand for network traffic to flow. Such connections are usually of short duration and use the PPP or SL/IP protocols. A problem can arise when this dial-up-on-demand is instigated by sendmail. [12] The process of negotiating a dial-up connection can take so long that sendmail will have its attempt to connect(2) fail. (See also the connect keyword for the Timeout option in Section 34.8.70.2). To remedy this situation, V8.7 sendmail offers the DialDelay option. It is declared like this:

[12] Or by any other network-oriented program, such as FTP or Mosaic.

O DialDelay=delay              <- configuration file
-ODialDelay=delay              <- command line
define(`confDIAL_DELAY',delay) <- m4 configuration

The argument delay is of type time. If this option is entirely omitted or if delay is omitted, the default is then zero and no delay is enabled. The default for the m4 configuration technique is also zero. If the unit of time is omitted from the time declaration, the default is seconds.

If delay is nonzero and sendmail has its initial connect(2) fail, it will sleep(3) for delay seconds and then try to connect(2) again. Note that sendmail tries a second time only once, so the delay should be large enough to accommodate your anticipated worst-case delay. On the other hand, care should be taken to avoid excessively long delays that can make sendmail appear to hang. No check is made by sendmail for absurdly large values given to delay.

The DialDelay option is safe. If it is specified from the command line, sendmail will not relinquish its root privilege.

34.8.18 DontExpandCnames

Prevent CNAME expansion

(V8.7 and above)

Ordinarily, the $[ and $] operators (see Section 28.6.6, "Canonicalize Hostname: $[ and $]") cause the enclosed hostname to be looked up with DNS and replaced with the canonical name for that host. The canonical name is the A DNS record. For example, consider these DNS records:

here.us.edu.    IN     A     123.45.67.89
ftp.us.edu.     IN     CNAME here.us.edu.

If the address ftp.us.edu is fed to the $[ and $] operators in the RHS of a rule:

R...      $[ $1 $]

then the rewritten result of passing ftp.us.edu as $1 will be the A record name here.us.edu. This behavior is correct under RFC822 and RFC1123, but the IETF is currently moving toward a change.

Sometimes it is important for the CNAME to appear in email headers as the canonical name. One example might be that of an FTP service moving from one machine to another during a transition phase. In that case, outgoing mail should appear to be from ftp.us.edu, because the records will change after the move, and we want to maintain the ability to reply to such mail.

here.us.edu.    IN     A     123.45.67.89     <- retired and gone
ftp.us.edu.     IN     CNAME there.us.edu.
there.us.edu.   IN     A     123.45.67.90

Another possibility might be that of a mobile host (a workstation that plugs into different networks and thus has different A records over time):

mobile.us.edu.    IN     CNAME monday.dc.gov.
monday.dc.gov.    IN     A     12.34.56.78
tuesday.foo.com.  IN     A     23.45.67.89

Whenever this workstation is plugged in, its CNAME record is changed to point to the A record of the day: monday.dc.gov on Monday and tuesday.foo.com on Tuesday. But no matter what its A record happens to be, outgoing mail should look as though it came from mobile.us.edu.

The DontExpandCnames option causes sendmail to accept CNAME records as canonical. It is intended for use on sending hosts with special CNAME needs and should not be enabled without good reason. It is declared like this:

O DontExpandCnames=bool			  <- configuration file (V8.7)
-ODontExpandCnames=bool			  <- command line (V8.7)
define(`confDONT_EXPAND_CNAMES',bool)	  <- V8 m4 configuration

The argument bool is of type Boolean. If bool is missing, the default is true (use the CNAME). If the entire DontExpandCnames option is missing, the default is false (convert CNAMEs to A records).

The DontExpandCnames option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.19 DontInitGroups

Don't use initgroups(3)

(V8.7 and above)

Just before executing any delivery agent (including the *include* delivery agent) and just before opening a ~/.forward file, sendmail sets its group and user identities as appropriate. To illustrate, consider the U= equate (see Section 30.4.13). If the fax delivery agent has the U= equate set like this:

U=fax:fax

its A= program will be executed by the user fax who is in the group fax. In addition, sendmail calls the initgroups(3) system call to expand the list of groups to which the user belongs. In the case of fax, it may also belong to the groups faxadm and faxusers. The total result is that fax can execute, read, and write any files that have the appropriate group permissions set for any of the groups fax, faxadm, and faxusers.

This versatility, however, has a price. As group files get huge or as nis, nisplus, or hesiod services become slow (probably because they are also large), the initgroups(3) call can start to adversely affect sendmail's performance.

When performance is a concern, the DontInitGroups option can be used to disable initgroups(3):

O DontInitGroups=bool    <- configuration file
-ODontInitGroups=bool    <- command line
define(`confDONT_INIT_GROUPS',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If it is missing, the default value is true  - don't call initgroups(3). If the entire option is missing, the default value is false  - do call initgroups(3). See Section 18.8.31, NO-GROUP-SET for a discussion of how NO_GROUP_SET determines whether or not this option also affects the getgrgid(3) system call.

The DontInitGroups option is not safe as of V8.8.4. Even if it is specified from the command line, may cause sendmail to relinquish its root privilege.

34.8.20 DontPruneRoutes (R)

Don't prune route addresses

(V8.1 and above)

One form of address is called a route address, because it specifies a route (sequence of hosts) through which the message should be delivered. For example:

@hostA,@hostB:user@hostC

This address specifies that the message should first go to hostA, then from hostA to hostB, and finally from hostB to hostC for delivery to user. [13]

[13] Also see how route addresses are handled in rules in Section 29.4.3, "Handling Routing Addresses" and the F=d delivery agent flag in Section 30.8.16, F=d).

RFC1123, in Section 5.3.3, specifies that delivery agents should always try to eliminate source routing when they are able. V8 sendmail takes an address like the above and checks to see whether it can connect to hostC directly. If it can, it rewrites the address like this:

user@hostC

This is called "pruning route addresses." There may be times when such pruning is inappropriate. Internal networks, for example, may be set up to encourage manual specification of a route through a high-speed network. If left to its own, sendmail always tosses the route and tries to connect directly.

The DontPruneRoutes (R) option causes sendmail to never prune route addresses. The forms of this option are as follows:

ORbool                                          <- configuration file (old form)
-oRbool                                         <- command line (old form)
O DontPruneRoutes=bool                          <- configuration file (beginning with V8.7)
-ODontPruneRoutes=bool                          <- command line (beginning with V8.7)
define(`confDONT_PRUNE_ROUTES',`bool')          <- V8 m4 configuration

The argument bool is of type Boolean. If it is missing, the default value is true (nothing special is done with route addresses). If the entire R option is missing, the default becomes false (route addresses are pruned). With the V8 m4 configuration technique the default is false.

The DontPruneRoutes (R) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.21 DoubleBounceAddress

Errors when sending errors

(V8.8 and above)

Ordinarily, when sendmail sends error notification mail, it expects that error notification to be successfully delivered. Upon occasion, error mail itself will bounce or fail too. This is called a "double-bounce" situation. Prior to V8.8, sendmail would notify postmaster if error notification failed. But this might not be the best solution in all cases. Consider, for example, a site that has a sitewide postmaster and several departmental postmasters. In such situations, double-bounce mail should probably go to the sitewide postmaster.

Beginning with V8.8 sendmail, the DoubleBounceAddress option can be used to define who gets double-bounce mail:

O DoubleBounceAddress=addr                      <- configuration file (beginning with V8.8)
-ODoubleBounceAddress=addr                      <- command line (beginning with V8.8)
define(`confDOUBLE_BOUNCE_ADDRESS',`addr')      <- V8 m4 configuration

Here, addr is of type string and is a comma-separated list of one or more email addresses. If addr is missing, the following error is printed and the option is ignored:

readcf: option DoubleBounceAddress: value required

If the entire option is missing, the default becomes postmaster. If sendmail is unable to send double-bounce mail to addr, it logs the following error:

cannot parse addr

The DoubleBounceAddress option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.22 EightBitMode (8)

How to convert MIME input

(V8.7 and above)

The data portion of an email message is transmitted during the DATA phase of an SMTP transaction. Prior to V8.6 the data were presumed to be 7-bit. That is, the high (8th) bit of every byte of the message could be cleared (reset or made zero) with no change in the meaning of that data. With the advent of ESMTP and MIME, it became possible for sendmail to receive data for which the preservation of the 8th bit is important.

There are two kinds of 8-bit data. Data that arrive with the high bit set and for which no notification was given are called "unlabeled" 8-bit data. Data for which notification was given (using 8BITMIME in the ESMTP session or with the -B8BITMIME command-line switch, see Section 36.7.1, -B, or with a MIME-Version: header in the message, see Section 35.10.21, MIME-Version:) are called "labeled."

The EightBitMode (8) option tells sendmail how to treat incoming unlabeled 8-bit data. The forms of this option are as follows:

O8key                                  <- configuration file (V8,6)
-o8key                                 <- command line (V8,6)
O EightBitMode=key                     <- configuration file (beginning with V8.7)
-OEightBitMode=key                     <- command line (beginning with V8.7)
define(`confEIGHT_BIT_HANDLING',key)   <- m4 configuration

The key is mandatory and must be selected from one of those shown in Table 34.14. If the key is missing or if key is not one of those listed, sendmail will print the following error and ignore the option:

Unknown 8-bit mode char

Only the first character of the key is recognized, but we still recommend that the full word be used for clarity.

Table 34.14: EightBitMode Option Characters
KeyMeaning
mimifySection 34.8.22.1, "EightBitMode=mimefy"

Do any necessary conversion of 8BITMIME to 7-bit

passSection 34.8.22.2, "EightBitMode=pass"

Pass unlabeled 8-bit input through as is

strictSection 34.8.22.3, "EightBitMode=strict"

Reject unlabeled 8-bit input

If the entire EightBitMode (8) option is missing, the default becomes p (pass 8-bit and convert MIME). If you configure with V8's m4 technique, the default is also p.

Depending on the key selected and the nature of incoming mail, any of several error messages may be generated:

Eight bit data not allowed
Cannot send 8-bit data to 7-bit destination
host does not support 8BITMIME

Conversion from 8 to 7 bit is complex. First, sendmail looks for a MIME Content-Type: header. If the header is found, sendmail looks for and, if found, uses a MIME boundary definition to delimit conversion. [14] If more than 1/4 of a section has the high bit set after reading at least 4 kilobytes of data, sendmail presumes base64 encoding [15] and inserts the following MIME header into the data stream:

[14] A boundary is used only for multipart messages.

[15] Also see the $=q class (Section 32.5.5, $=q) for a way to require quoted-printable encoding.

Content-Transfer-Encoding: base64

Base64 encoding converts 8-bit data into a stream of 6-bit bytes that contain universally readable text. Base64 is described in RFC1521.

If less than 1/4 of the data that were scanned have the high bit set or if the type in the Content-Type: header is listed in $=q (Section 32.5.5), the data are converted from 8 to 7 bit by using Quoted-Printable encoding, and the following MIME header is inserted into the stream:

Content-Transfer-Encoding: quoted-printable

Under Quoted-Printable encoding, ASCII control characters (in the range 0x00 through 0x20), the tab character, the "=" character, and all characters with the high bit set are converted. First an "=" character is output, then the character is converted to an ASCII representation of its hexadecimal value, and that value is output. For example,

0xb9      -> becomes   =B9

Under this scheme, the = character is considered binary and is encoded as =3D. If the F=3 flag (see Section 30.8.2, F=3) is set for a selected delivery agent, the characters

! " # $ @ \ [ ] ^ ` { | } ~

are also converted. If F=3 is not set, those characters are output as is.

Lines longer than 72 characters (bytes) are broken with the insertion of an "=" character and the E= end-of-line characters defined for the current delivery agent. Any lines that end in a whitespace character have that character converted to quoted-printable even if the line is under 72 characters. Quoted-printable is described in RFC1521. Where m (mimefy) may not be appropriate for a given delivery agent, the F=8 flag (see Section 30.8.5, F=8) can be specified to force p (pass8bit) behavior.

The EightBitMode (8) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.22.1 EightBitMode=mimefy

Convert unlabeled 8-bit input to 8BITMIME, and do any necessary conversion of 8BITMIME to 7-bit. When running as a daemon receiving mail via SMTP, advertise the 8BITMIME ESMTP keyword as valid. This key specifies that your site will be a full-time MIME installation. Note that compiling with MIME8TO1=1 (see Section 18.8.22, MIME8TO7) causes ESMTP to always advertise 8BITMIME.

34.8.22.2 EightBitMode=pass

Pass unlabeled 8-bit input through as is. Convert labeled 8BITMIME input to 7-bit as required by any delivery agent with the F=7 flag set (see Section 30.8.4, F=7) or any SMTP server that does not advertise 8BITMIME.

34.8.22.3 EightBitMode=strict

Reject unlabeled 8-bit input. Convert 8BITMIME to 7-bit as required by any delivery agent with the F=7 flag set (see Section 30.8.4) or any SMTP server that does not advertise 8BITMIME.

34.8.23 ErrorHeader (E)

Set error message header

(V8 and above)

When a notification of a mail error is sent to the sender, the details of the error are taken from the text saved in the xf file (see Section 23.2.7, "The Transcript File: xf"). The ErrorHeader (E) option, available only with V8 sendmail, allows you to prepend custom text ahead of that error text.

Custom error text is useful for sites that wish to offer help as part of the error message. For example, one common kind of error message is notification of an unknown user:

--- Transcript of session follows ---
550 [email protected]... User unknown
   --- Unsent message follows ---

Here, the user smith is one that is unknown. A useful error help message for your site to produce might be

Common problems:
        User unknown: the user or login name is wrong.
        Host unknown: you mistyped the host part of the address.
   --- Transcript of session follows ---
550 [email protected]... User unknown
   --- Unsent message follows ---

The forms for the ErrorHeader (E) option are as follows:

OEtext                               <- configuration file (V8.6)
-oEtext                              <- command line (V8.6)
O ErrorHeader=text                   <- configuration file (beginning with V8.7)
-OErrorHeader=text                   <- command line (beginning with V8.7)
define(`confERROR_MESSAGE',`text')   <- V8 m4 configuration

The argument text is mandatory. If it is missing, this option is ignored. The text is either the actual error text that is printed or the name of a file containing that text. If text begins with the / character, it is taken as the absolute pathname of the file (a relative name is not possible). If the specified file cannot be opened for reading, this option is silently ignored.

Macros may be used in the error text, and they are expanded as they are printed. For example, the text might contain

For help with $u, try "finger $u"

which might produce this error message:

For help with [email protected], try "finger [email protected]"
   --- Transcript of session follows ---
550 [email protected]... User unknown
   --- Unsent message follows ---

The ErrorHeader (E) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.24 ErrorMode (e)

Specify mode of error handling

(All versions)

The sendmail program is flexible in its handling of delivery errors. By selecting from five possible modes with the ErrorMode (e) option, you can tailor notification of delivery errors to suit many needs.

This option is intended primarily for use from the command line. If included in the configuration file, it should be given only the p argument, for print mode (the default).

The forms of the ErrorMode (e) option are as follows:

Oemode                          <- configuration file (old form)
-oemode                         <- command line (old form)
-emode                          <- command-line shorthand (not recommended)
O ErrorMode=mode                <- configuration file (beginning with V8.7)
-OErrorMode=mode                <- command line (beginning with V8.7)
define(`confERROR_MODE',mode)   <- V8 m4 configuration

The type of mode is character. If mode is missing, the default value is p (for print normally). Under older versions of sendmail, if this ErrorMode (e) option is entirely missing, the default value for mode is the C language character constant '\0'. Under V8 sendmail, the default value in this case is p.

The possible characters for the mode argument are listed in Table 34.15.

Table 34.15: ErrorMode Option Modes
ModeMeaning
eSection 34.8.24.1, "ErrorMode=e"

Like m, but always exit with a zero exit status

mSection 34.8.24.2, "ErrorMode=m"

Mail error notification to the sender no matter what

pSection 34.8.24.3, "ErrorMode=p"

Print error messages (the default)

qSection 34.8.24.4, "ErrorMode=q"

Remain silent about all delivery errors

wSection 34.8.24.5, "ErrorMode=w"

Write errors to the sender's terminal screen

Note that the error-handling mode is automatically set to m (for mail errors) in two special circumstances. First, if a mailing list is being processed and if an owner is found for that list (see Section 25.3, "Defining a Mailing List Owner"), the mode is set to m to force mail notification to that owner. Second, if SMTP delivery is to multiple recipients, the mode is set to m to force mail notification to the sender. This latter assumes that multiple recipients qualify as a mailing list.

Also note that V8 sendmail sets the error-handling mode to q (for quiet) when sendmail is given the -bv (address verification) command line switch. This prevents spurious error messages from being mailed to root in testing addresses.

The ErrorMode (e) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.24.1 ErrorMode=e

Like m, but always exit with a zero exit status. This mode is intended for use from the command line. This e mode is used by the rmail(8) program when it invokes sendmail. On some systems, if sendmail exits with a nonzero value (fails), the uuxqt(8) program sends its own error message. This results in two error messages being sent, whereas only one should ever be sent. Worse still, the error message from uuxqt may contain a bad address, one that may itself bounce.

34.8.24.2 ErrorMode=m

Mail error notification to the sender no matter what. This mode tries to find the most rational way to return mail. All aliasing is disabled to prevent loops. Nothing is ever saved to ~/dead.letter. This mode is intended for use from the command line. The m mode is appropriate for mail generated by an application that arises from a login but for which no human is present to monitor messages. One example might be a data-acquisition system that is manually logged in but is then left to fend for itself. Similarly, when the user news sends articles by mail, error messages should not be placed in ~news/dead.letter, where they may be overlooked; rather, this mode should be used so that errors are placed in a mail spool file where they can be periodically monitored.

34.8.24.3 ErrorMode=p

Print error messages (the default). The sendmail program simply tries to save a copy of the failed mail in ~/dead.letter and prints an error message to its standard output. If the sender is remote, it sends notification of the problem back to that sender via email. If ~/dead.letter is not writable, a copy is saved to /usr/tmp/dead.letter. Note that this default path was hard-coded into pre-V8 versions of sendmail as a string constant. The only way to change it was by editing savemail.c. But beginning with V8 sendmail, the path component is defined by the _PATH_VARTMP definition, and that can be tuned in your Makefile (see Section 18.8.34, PATH...). The default for _PATH_VARTMP is /usr/tmp/. The file named dead.letter is hard-coded in all versions of sendmail.

34.8.24.4 ErrorMode=q

Quiet; remain silent about all delivery errors. If the sender is local, this mode assumes that the program or person that ran sendmail will give notification of the error. Mail is not sent, and ~/dead.letter is not saved. Error information is provided only in the sendmail program's exit(2) status (see Section 36.5, "sendmail's exit() Status"). This mode is intended for use from the command line. One possible use might be exploding a junk-mail mailing list with a program that could correctly interpret the exit status.

34.8.24.5 ErrorMode=w

Write errors to the sender's terminal screen if logged in (similar to write(1)); otherwise, send mail to that user. First tries to write to stdout. If that fails, it reverts to mail notification. This mode is intended for use from the command line. The reason for this mode has been lost to history, [16] and it should be considered obsolete.

[16] According to Eric Allman, "Dubious, someone bugged me for it; I forget why."

34.8.25 FallbackMXhost (V)

Fallback MX host

(V8.4 and above)

At sites with poor (connect on demand, or unreliable) network connections, SMTP connections may often fail. In such situations it may not be desirable for each workstation to queue the mail locally for a later attempt. Under V8 sendmail it is possible to specify a fallback host to which the mail should instead be forwarded. One such host might be a central mail hub machine.

The FallbackMXhost (V) option specifies the name of a mail exchanger machine (MX record) of last resort. It is given an artificially low priority (high preference number) so that sendmail tries to connect to it only if all other connection attempts for the target host have failed.

Note that this fallback MX host is used only for connection failures. It is not used if the name server lookup failed. It is available only for the [IPC] delivery agent (see Section 30.4.1.2, "$h and other arguments in A=[IPC]"). Note that MX lookups are available only if sendmail is compiled with NAMED_BIND defined (see Section 18.8.23, NAMED-BIND).

The forms of the FallbackMXhost (V) option are as follows:

OVhost                             <- configuration file (V8.6)
-oVhost                            <- command line (V8.6)
O FallbackMXhost=host              <- configuration file (beginning with V8.7)
-OFallbackMXhost=host              <- command line (beginning with V8.7)
define(`confFALLBACK_MX',`host')   <- V8 m4 configuration

Here, host is of type string and is the fully qualified domain name of the fallback host. If host or the entire option is missing, no fallback MX record is used. The effect of this option can be seen by using the /mx rule-testing command (see Section 38.5.2, "Look Up MX Records with /mx").

The FallbackMXhost (V) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.26 ForkEachJob (Y)

Process queue files individually

(All versions)

On machines with a small amount of memory (such as 3B1s and old Sun 3s) it is best to limit the size of running processes. One way to do this is to have the sendmail program fork(2) a copy of itself to handle each individual queued message. The ForkEachJob (Y) option can be used to allow those fork(2)'s.

The forms of the ForkEachJob (Y) option are as follows:

OYbool                             <- configuration file (old style)
-oYbool                            <- command line (old style)
O ForkEachJob=bool                 <- configuration file (beginning with V8.7)
-OForkEachJob=bool                 <- command line (beginning with V8.7)
define(`confSEPARATE_PROC',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If bool is missing, the default is true (fork). The default for the V8 m4 technique is true. If the entire ForkEachJob (Y) option is missing, the default is false (don't fork).

If option ForkEachJob (Y) is set (true), there is a fork(2) to start processing of the queue, then another fork(2) to process each message in the queue. If option ForkEachJob (Y) is not set (false), only the initial fork(2) takes place, greatly improving the efficiency of a queue run. For example, a single process (as with ForkEachJob (Y) false) retains information about down hosts and so does not waste time trying to connect again for subsequent mail to the same host during the current queue run. For all modern machines the ForkEachJob (Y) option should be false.

The ForkEachJob (Y) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.27 ForwardPath (J)

Set ~/.forward search path

(V8 and above)

When mail is being delivered to a local user, sendmail attempts to open and read a file in the user's home directory called .forward. If that file exists and is readable, the aliases in that file replace the local username for delivery.

Under V8 sendmail the ForwardPath (J) option is used to define alternative locations for the user's ~/.forward file.

The forms of the ForwardPath (J) option are as follows:

OJpath                            <- configuration file (V8.6)
-oJpath                           <- command line (V8.6)
O ForwardPath=path                <- configuration file (beginning with V8.7)

-OForwardPath=path                <- command line (beginning with V8.7)
define(`confFORWARD_PATH',path)   <- V8 m4 configuration

The path is a colon-separated list of files. An attempt is made to open and read each in turn, from left to right, until one is successfully read:

OJ/var/forward/$u:$z/.forward

Macros may, and should, be used in the path file locations. In the above example, sendmail first looks in the file /var/forward/$u (where the macro $u contains the user's login name; see Section 31.10.36, $u). If that file can't be opened for reading, sendmail tries reading $z/.forward (where the $z macro contains the user's home directory; see Section 31.10.46, $z). Other macros of interest are $w (the local hostname; see Section 31.10.40, $w), $x (the user's full name; see Section 31.10.14, $f), $r (the sending protocol; see Section 31.10.31, $r), and $s (the sending host; see Section 31.10.33, $s). The recommended declaration is to use the name of the sending host thus:

OJ$z/.forward.$w:$z/.forward

If the path or the entire option is omitted, the default is $z/.forward. Therefore omitting the ForwardPath (J) option causes V8 sendmail to emulate older versions by looking only in the ~/.forward file for user forwarding information.

Beginning with V8.7 sendmail, the F=w delivery agent flag (see Section 30.8.43, F=w) must be set for the recipient's delivery agent, or all forwarding is skipped. Previously, this was tied to the delivery agent named local.

The ForwardPath (J) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.28 HelpFile (H)

Specify location of the help file

(All versions)

The sendmail program implements the SMTP (and ESMTP) HELP command by looking up help messages in a text file. Beginning with V8.7 sendmail, help messages for the -bt rule-testing mode are also looked up in that file. The location and name of that text file are specified by using the HelpFile (H) option. If the name is the C language value NULL or if sendmail cannot open that file for reading, sendmail issues the following message and continues:

502 HELP not implemented

The help file is composed of lines of text, separated by tab characters into two fields per line. The leftmost field is an item for which help is offered. The rightmost field (the rest of the line) is the help text to be printed. A few lines in a typical help file might look like this:

.ps 8
rset   RSET
rset          Resets the system.
quit   QUIT
quit          Exit sendmail (SMTP).
verb   VERB
verb          Go into verbose mode.  This sends 0xy responses that are
verb          not RFC821 standard (but should be). They are recognized
verb          by humans and other sendmail implementations.
vrfy   VRFY <recipient>
vrfy          Verify an address.  If you want to see what it aliases
vrfy          to, use EXPN instead.

For an SMTP request of help vrfy, sendmail might produce

214-VRFY <recipient>
214-     Verify an address.  If you want to see what it aliases
214-     to, use EXPN instead.
214 End of HELP info

The forms of the HelpFile (H) option are as follows:

OHfile                       <- configuration file (old form)
-oHfile                      <- command line (old form)
O HelpFile=file              <- configuration file (beginning with V8.7)
-OHelpFile=file              <- command line (beginning with V8.7)
define(`HELP_FILE',`file')   <- V8 m4 configuration

The argument file is of type string and may be a full or relative pathname. Relative names are always relative to the queue directory. If file is omitted, then the name of the help file defaults to sendmail.hf. If the entire H option is omitted, the name of the help file becomes the C language value NULL. The Simple Mail Transfer Protocol (SMTP) is described in RFC821, and Extended SMTP (ESMTP) is described in RFC1869.

The HelpFile (H) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.29 HoldExpensive (c)

Queue for expensive mailers

(All versions)

An expensive mailer is a delivery agent that contains an e flag in its F= equate (see Section 30.8.18, F=e). Typically, such delivery agents are associated with slow network connections such as SL/IP or with costly networks such as those with high per connect or connection startup rates. Whatever the reason, the HoldExpensive (c) option allows you to queue all such mail for later delivery rather than connecting on demand. (Queuing is described in Chapter 23.)

Note that this option affects only the initial delivery attempt, not later attempts when the queue is processed. Essentially, all this option does is to defer delivery until the next time the queue is processed.

The forms of the HoldExpensive (c) option are as follows:

Ocbool                             <- configuration file (old form)
-ocbool                            <- command line (old form)
-c                                 <- command-line shorthand (not recommended)
O HoldExpensive=bool               <- configuration file (beginning with V8.7)
-OHoldExpensive=bool               <- command line (beginning with V8.7)
define(`confCON_EXPENSIVE',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If the bool argument is missing, the default is true (expensive mail is queued). If the entire HoldExpensive (c) option is missing, the default value is false (expensive mail is delivered immediately).

The -v (verbose) command-line switch automatically sets the HoldExpensive (c) option to false. The HoldExpensive (c) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.30 HostsFile

Specify alternate /etc/hosts file

(V8.7 and above)

When canonifying a host's name, sendmail will use the method described under the ServiceSwitchFile option (see Section 34.8.61). When that method is files, sendmail parses the /etc/hosts file to find the canonical name. If a different file should be used on your system, you can specify it with this HostsFile option:

O HostsFile=path               <- configuration file (beginning with V8.7)
-OHostsFile=path               <- command line (beginning with V8.7)
define(`confHOSTS_FILE',path)  <- V8 m4 configuration

Here, path is of type string. If path is missing, the name of the /etc/hosts file becomes an empty string. If the entire option is missing, the default is the value that was given to _PATH_HOSTS when sendmail was compiled (see Section 18.8.34). If the path cannot be opened for reading (for any reason at all), host canonification by this method is silently skipped.

One example of a use for the HostsFile option would be to use a switched-service file to cause all host lookups to use DNS first, then files:

hosts:    dns files

In that case you would use a special file to hold information about internal hosts that are not known to DNS. Such a file might look like this:

123.45.67.89	secret.internal.host.domain

This special file would be defined with the HostsFile option.

The HostsFile option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.31 HostStatusDirectory

Location of persistent host status

(V8.8 and above)

The process of delivering network mail requires that sendmail fork(2) so that the child process can handle the queue. Then, if the ForkEachJob (Y) option (see Section 34.8.26) is true, each job in the queue has to fork(2) again so that each child-of-a-child can perform each task. Internally, sendmail maintains tables of status information about network hosts (such as whether the host is up or down or refusing connections). A problem can arise when multiple queue-processing children are running. Because they are separate processes, their separate children lack access to the common pool of host information that is stored internally by each parent. [17]

[17] Also status information from previous queue runs is lost.

One solution is to store host status information externally so that all children can access it. Inspired by KJS sendmail, V8.8 has introduced the HostStatusDirectory option. This option both tells sendmail that it should save host status information externally and defines where that information will be stored on disk.

The form for the HostStatusDirectory option looks like this:

O HostStatusDirectory=path                     <- V8.8 and above
define(`confHOST_STATUS_DIRECTORY', `path')    <- V8 m4 technique

Here, path is of type string and, if present, specifies the base directory under which host status will be stored. This may be a full or relative path specification. If it is a relative path, it is interpreted as relative to the queue directory. If path is omitted or if the entire option is omitted, the default is that no persistent host information will be saved. If path does not exist or if it exists and is not a directory, sendmail will then print the following error and will store no persistent host information:

Cannot use HostStatusDirectory = path: reason here

The form of the information stored and the way files and directories under this base directory are named are detailed in Appendix Appendix B, Host Status File Internals. Note that the status information in this directory can be printed with the hoststat(1) command (see Section 36.1.1, "hoststat (V8.8 and Above)"). Also note that the HostStatusDirectory option will not work if the ConnectionCacheSize option (see Section 34.8.10) is set to zero:

Warning: HostStatusDirectory disabled with ConnectionCacheSize = 0

Note that on machines that send out a great deal of mail, you should probably compare performance with and without this option enabled and base your decision to use it on the result. Also note that this option is required if you wish to also use the SingleThreadDelivery option (see Section 34.8.64).

Avoid using a directory that is on a tmpfs file system (prior to Sun Solaris 2.5), because file locking is not supported. Avoid using a directory that is on an nfs file system, because record locking is unreliable and single-threaded and can add extra RPC traffic.

The HostStatusDirectory option is not safe. If it is specified from the command line, it may cause sendmail to give up its root privilege.

34.8.32 IgnoreDots (i)

Ignore leading dots in messages

(All versions)

There are two ways that sendmail can detect the end of a mail message: by noting an end-of-file (EOF) condition or by finding a line composed of a single dot. According to the SMTP and ESMTP protocols (RFC821), the end of the mail data is indicated by sending a line containing only a period. The IgnoreDots (i) option tells sendmail to treat any line that contains only a single period as ordinary text, not as an end-of-file indicator.

This option is used from the command line to prevent sendmail from wrongly thinking that a message is complete when collecting the message from its standard input. This differs from the correct behavior when sendmail is reading from an SMTP connection. Over SMTP a lone dot must signal the end of the message.

This option is intended for use from the command line. This option should be used in the configuration file only for sites that have no SMTP network connections. But V8 sendmail has built-in protection. If this option is specified in the configuration file, it is automatically forced false for all SMTP connections.

The forms of the i option are as follows:

Oibool                           <- configuration file (old form)
-oibool                          <- command line (old form)
-i                               <- command-line
shorthand (deprecated)
O IgnoreDots=bool                <- configuration file (beginning with V8.7)
-OIgnoreDots=bool                <- command line (beginning with V8.7)
define(`confIGNORE_DOTS',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If bool is missing, the default value is true (ignore leading dots). If the IgnoreDots (i) option is entirely omitted, the default is false (recognize leading dots as special).

The IgnoreDots (i) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.33 LogLevel (L)

Set (increase) logging level

(All versions)

The sendmail program is able to log a wide variety of information about what it is doing. There is no default file for recording information. Instead, sendmail sends all such information via the UNIX syslog(3) mechanism. The disposition of messages by syslog is determined by information in the file /etc/syslog.conf (see Section 26.1.2, "Tuning syslog.conf"). One common scheme places noncritical messages /var/log/syslog but routes important messages to /dev/console or /var/adm/messages.

The meaningful values for the logging level, and their syslog priorities, are outlined below. [18] Higher logging levels include the lower logging levels. For example, logging level 2 also causes level 1 messages to be logged.

[18] Note that the pre-V8 organization differs and is not covered in this book.

0

Minimal logging. See Section 34.8.33.1, "What is logged at LogLevel=0" for examples of what is logged at this setting.

1

Serious system failures and security problems logged at LOG_CRIT or LOG_ALERT.

2

Communication failures, (e.g., lost connections or protocol failures) logged at LOG_CRIT.

3

Malformed addresses logged at LOG_NOTICE. Transient forward/include errors logged at LOG_ERROR. Connect timeouts logged at LOG_NOTICE.

4

Malformed qf filenames and minor errors logged at LOG_NOTICE. Out of date alias databases logged at LOG_INFO. Connection rejections (via libwrap.a or one of the check_ rule sets) logged at LOG_NOTICE.

5

A record of each message received logged at LOG_INFO. Envelope cloning logged at LOG_INFO.

6

SMTP VRFY attempts and messages returned to the original sender logged at LOG_INFO. The ETRN and EXPN ESMTP commands logged at LOG_INFO.

7

Delivery failures, excluding mail deferred because of the lack of a resource, logged at LOG_INFO.

8

Successful deliveries logged at LOG_INFO. Alias database rebuilds logged at LOG_NOTICE.

9

Mail deferred because of a lack of a resource logged at LOG_INFO.

10

Each key as looked up in a database, and the result of each lookup, logged at LOG_INFO.

11

All nis errors logged at LOG_INFO. The end of processing (job deletion) logged at LOG_INFO.

12

SMTP connects logged at LOG_INFO.

13

Log bad user shells, world-writable files, and other questionable situations.

14

Connection refusals logged at LOG_INFO.

15

All incoming and outgoing SMTP commands and their arguments logged at LOG_INFO.

16-98

Debugging information. You'll need the source to understand this logging. You can grep(1) LogLevel in all the .c files to find interesting things to look for. These are logged at LOG_DEBUG.

The forms of the LogLevel (L) option are as follows:

OLlev                         <- configuration file (old form)
-oLlev                        <- command line (old form)
O LogLevel=lev                <- configuration file (beginning with V8.7)
-OLogLevel=lev                <- command line (beginning with V8.7)
define(`confLOG_LEVEL',lev)   <- V8 m4 configuration

The type for lev is numeric and defaults to 0. For the m4 technique the default is 9. Negative values are equivalent to a logging level of 0.

Logging is effective only if sendmail is compiled with LOG defined in conf.h (see Section 18.8.16, LOG). The -d0.1 debugging switch (see Section 37.5.1, -d0.1) can be used to see if LOG was defined for your system.

The LogLevel (L) option is safe. Even if it is specified from the command line, sendmail retained its root privilege. For security reasons the logging level of V8.6 and above sendmail can be increased from the command line but not decreased. [19]

[19] V8.7.3 sendmail was released with the LogLevel (L) option set as not safe.

34.8.33.1 What is logged at LogLevel=0

Because of their severe nature, some errors and problems are logged even though the LogLevel (L) option is set to zero. Specifically, problems with $j and $=w that are checked if sendmail was compiled with XDEBUG defined:

daemon process doesn't have $j in $=w; see syslog
daemon process $j lost dot; see syslog

Failure to find your unqualified hostname or qualified domain:

My unqualified host name (my host name) unknown
unable to qualify my own domain name (my host name) - using short name

If the daemon was invoked without a full pathname:

daemon invoked without full pathname; kill -1 won't work

Normal startup of the daemon:

starting daemon (version): how

File descriptor failure if sendmail was compiled with XDEBUG defined:

subroutine: fd number not open

Possible attacks based on a newline in a string:

POSSIBLE ATTACK from address: newline in string "string here"

Also the states dumped as a result of a SIGUSR1 (see Section 26.3.3, "SIGUSR1 Dump States") are logged, and the output caused by the -d91.100 switch (see Section 37.5.192, -d91.100).

34.8.34 MatchGECOS (G)

Match recipient in gecos field

(V8.1 and above)

The gecos field is the portion of a passwd(5) file line that contains a user's full name. Typical passwd file lines are illustrated below with the gecos field of each highlighted in bold type:

george:Vnn9x34sEVbCN:101:29:George Washington:/usr/george:/bin/csh
bcx:/a88.97eGSx1l:102:5:Bill Xavier,,,:/usr/bcx:/bin/csh
tim:Fss9UdQl55cde:103:45:& Plenty (Jr):/usr/tim:/bin/csh

When sendmail attempts to deliver through a delivery agent that has the F=w flag set (see Section 30.8.43) it looks up the recipient's name in the passwd file so it can locate the user's home directory. That lookup tries to match the login name, the leftmost field in the passwd file. If sendmail has been compiled with MATCHGECOS defined (see Section 18.8.18, MATCHGECOS) and this MatchGECOS (G) option is true, sendmail also tries to match the recipient name to the gecos field. [20]

[20] Note that IDA sendmail can be configured to match addresses in the gecos field, but the algorithm it uses differs from that described here.

First, sendmail converts any underscore characters in the address into spaces and, if the BlankSub (B) option is set (see Section 34.8.5), any characters that match that space substitution character into spaces. This makes the recipient name look like a normal full name.

Second, sendmail normalizes each gecos entry by throwing away everything following and including the first comma, semicolon, and percent characters. It also converts the & to the login name wherever one is found. If any of the characters

< >( ) ' .

are inside the name, the whole gecos name is quoted; otherwise, it's unquoted.

After each gecos name is normalized, it is compared in a case-insensitive manner to the recipient. If they match, the passwd entry for that user is used.

This feature allows users to receive mail addressed to their full name as given in the gecos field of the passwd file. The usual form is to replace spaces in the full name with dots or underscores:

George_Washington
Bill.Xavier
"Tim_Plenty_(Jr)"

Full names in gecos fields that contain characters with special meaning to sendmail, like the last one above, must be quoted when used as addresses.

You should not enable this option if your site lets users edit their own gecos fields with the chfn(1) program. At best, they can change their name in a way that can cause mail to start failing. Worse, they can change their name to match another user's and begin to capture that other user's mail. Even if the gecos field is secure, you should avoid this option if your passwd file is large. The sendmail program performs a sequential read of the passwd file, which could be very slow.

The forms of the MatchGECOS (G) option are as follows:

OGbool                           <- configuration file (old form)
-oGbool                          <- command line (old form)
O MatchGECOS=bool                <- configuration file (beginning with V8.7)
-OMatchGECOS=bool                <- command line (beginning with V8.7)
define(`confMATCH_GECOS',bool)   <- V8 m4 configuration

The MatchGECOS (G) option is not safe. If it is specified from the command line, it may cause sendmail to give up its root privilege.

34.8.35 MaxDaemonChildren

Maximum forked children

(V8.8 and above)

The sendmail program fork(3)'s often. It forks to process each incoming connection, and it forks to process its queue.

You can limit the number of forked children that sendmail produces by defining the MaxDaemonChildren option:

O MaxDaemonChildren=num                  <- configuration file (beginning with V8.7)
-OMaxDaemonChildren=num                  <- command line (beginning with V8.7)
define(`confMAX_DAEMON_CHILDREN', `num')   <- V8 m4 technique

The num is of type numeric and specifies the maximum number of forked children that are allowed to exist at any one time. If num is less than or equal to zero, if it is missing, or if this entire option is missing, no limit is imposed. If num is greater than zero, connections that cause more than that number of forked children to be created will be rejected. While rejecting more connections, sendmail will change its process title to read

rejecting connections: maximum children: num

If num is greater than zero, sendmail will also limit the number of forked children it creates to handle queue runs.

Note the MaxDaemonChildren option should not be set in the configuration file. If the daemon handling incoming mail has this option set, a denial-of-service attack can easily be launched against your machine. Beginning with V8.8, the ConnectionRateThrottle option (see Section 34.8.12) can be used to slow rapid incoming connections and can be used with the incoming daemon.

The MaxDaemonChildren option is appropriate for use in certain queue-processing situations. For example, consider a special queue that exclusively holds mail for a popular host (say, /var/spool/bigqueue). To handle the outgoing mail, you could run sendmail in queue-processing mode like this:

/usr/lib/sendmail -q5m -OMaxDaemonChildren=2 -OQueueDirectory=/var/spool/bigqueue

Here, the queue is processed once every five minutes. If the number of children were not limited and if the queue were large or the destination host slow, too many parallel invocations of sendmail would be spawned, thus causing excessive connections to the destination host. By limiting the number of children with the MaxDaemonChildren option, you allow a small, polite amount of parallelism.

The MaxDaemonChildren option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.36 MaxHopCount (h)

Set maximum hop count

(All version)

A hop is the transmittal of a mail message from one machine to another. [21] Many hops may be required to deliver a message. The number of hops is determined by counting the Received: and Via: lines [22] in the header of an email message.

[21] The IP transport protocol also has the concept of hops. A message going from one machine to another has only one mail hop but may have many IP hops.

[22] Actually, only the headers that are marked with an H_TRACE flag (see Section 35.5.8, "H_TRACE") are counted.

The MaxHopCount (h) option tells sendmail the maximum number of times a message can be forwarded. When sendmail receives a message via email, it calculates the hop count. If that count is above the maximum allowed, it bounces the message back to the sender with the error

sendmail: too many hops (17 max)

In this case, 17 is the maximum. Detecting too many hops is useful in stopping mail loops - messages being forwarded back and forth between two machines.

The forms of the MaxHopCount (h) option are as follows:

Ohhops                       <- configuration file (old form)
-ohhops                      <- command line (old form)
O MaxHopCount=hops           <- configuration file (beginning with V8.7)
-OMaxHopCount=hops           <- command line (beginning with V8.7)
define(`confMAX_HOP',hops)   <- V8 m4 configuration

The hops argument is of type numeric. If hops is missing, the value becomes zero and causes all mail to fail with the error:

sendmail: too many hops (0 max)

If the entire MaxHopCount (h) option is missing, hops defaults to 25. A good value is 15 or more. This allows mail to follow a fairly long route through many machines (as it could with UUCP) but still catches and bounces mail caught in a loop between two machines.

In pre-V8 sendmail there was no h option for setting the maximum number of hops. Instead, the number of hops could be limited only by the compile-time definition of MAXHOP in conf.h. The default definition varied between 15 for IDA sendmail and 30 for V5 and earlier SunOS sendmail.

The MaxHopCount (h) option should not be confused with the -h command-line switch (see Section 36.7.22, -h). The MaxHopCount (h) option specifies the maximum number of hops allowed, whereas the -h command-line switch presets the (beginning) hop count for a given email message.

The MaxHopCount (h) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.37 MaxMessageSize

Maximum incoming ESMTP message size

(V8.7 and above)

The SIZE keyword to the ESMTP MAIL command tells V8 sendmail how big an incoming message is in bytes. If the SIZE keyword is not specified, sendmail assumes that the incoming message is zero bytes in size. V8 sendmail can reject a message at this point if it is larger than a definable maximum message size:

Message size exceeds fixed maximum message size (max)

Here, max is the maximum acceptable size in bytes. Ordinarily, there no maximum. If you want to define one, you may do so with the MaxMessageSize (b) option:

Obminblocks/maxsize                      <- configuration file (beginning with V8.1)
-obminblocks/maxsize                     <- command line (beginning with V8.1)
O MaxMessageSize=maxsize                 <- configuration file (beginning with V8.7)
-OMaxMessageSize=maxsize                 <- command line (beginning with V8.7)
define(`confMAX_MESSAGE_SIZE',maxsize)   <- V8 m4 configuration

If maxsize is omitted or if this entire option is omitted, the default is 0 (for unlimited message sizes). For the m4 configuration the default is 0 (unlimited). Note that the b option can also set the minimum blocks free (see Section 34.8.40).

This limit on message size is enforced during the SMTP dialogue. Later, after a delivery agent has been selected, further limitations can be imposed by using the M= delivery agent equate (see Section 30.4.7, M=).

The MaxMessageSize (b) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.38 MaxQueueRunSize

Maximum queue messages processed

(V8.7 and above)

Ordinarily (beginning with V8.6 sendmail), there is no limit to the number of queued messages that can be processed during a single queue run. If there are more messages than sendmail has allocated memory for, sendmail will calmly allocate more memory. (Previously, there was a fixed limit imposed at compile time.)

Some systems process so much mail that a single queue run can become unmanageably large - so huge, in fact, that system resources are strained to the limit with an adverse effect on system performance. If your site suffers from this problem, beginning with V8.7 you can set an upper limit on the number of queued messages to be processed by using the MaxQueueRunSize option:

O MaxQueueRunSize=limit                     <- configuration file (beginning with V8.7)
-OMaxQueueRunSize=limit                     <- command line (beginning with V8.7)
define(`confMAX_QUEUE_RUN_SIZE',limit)      <- m4 configuration

Here, limit is of type numeric and defines the upper limit on how many queued messages can be processed during a single queue run. If limit is less than or equal to zero, if it is missing, or if the entire option is missing, no limit is imposed. The default is to impose no limit.

If MaxQueueRunSize is defined and if that limit is reached while processing the queue, sendmail will log the following message at LOG_ALERT:

WorkList for queuedir maxed out at limit

Processing of the queue is described in Section 23.5, "How the Queue Is Processed". That process can be watched with the -d41 debugging switch (see Section 37.5.144, -d41.1).

The MaxQueueRunSize option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.39 MeToo (m)

Send to me too

(All versions)

When you send mail to a mailing list that includes your name as a part of that list, sendmail normally excludes you from that mailing. There are two good reasons for that behavior:

  • Since you sent the mail, it is assumed that you already have a copy of the letter. Most mailing programs have options that allow you to automatically retain copies of your outgoing mail. The BSD Mail program, for example, has the outfolder option.

  • When mail passes through a site that is acting as an exploder for an outside mailing list, mail loops could be caused by sending a copy of the message back to the original sender.

The MeToo (m) option overrides this behavior, but it is usually best to keep it turned off. If individual users want to be included in mailings to lists that they belong to, they can set this behavior from their mail-sending programs. BSD Mail, for example, allows you to set metoo in your ~/.mailrc file. This use of metoo simply causes Mail to invoke sendmail with the -om switch, thereby setting the MeToo (m) option.

The forms of the MeToo (m) option are as follows:

Ombool                      <- configuration file (old form)
-ombool                     <- command line (old form)
-m                          <- command-line shorthand
O MeToo=bool                <- configuration file (beginning with V8.7)
-OMeToo=bool                <- command line (beginning with V8.7)
define(`confME_TOO',bool)   <- V8 m4 configuration

The optional argument bool, when missing, defaults to true (include the sender). If this option is entirely missing, it defaults to false (exclude the sender).

The MeToo (m) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.40 MinFreeBlocks (b)

Define minimum free disk blocks

(V8.1 and above)

The SIZE keyword to the ESMTP MAIL command tells V8 sendmail how big an incoming message is in bytes. If the SIZE keyword is not specified, sendmail assumes that the incoming message is zero bytes in size. In either case it calls the subroutine enoughspace() in conf.c to see whether enough space is available in the queue to accept the message. Unless sendmail is told otherwise, it assumes it can use 100% of the disk space in the queue. If SIZE bytes will overfill the queue disk, sendmail prints the following error and rejects the mail message:

Insufficient disk space; try again later

Note that the SIZE keyword (if received) is just an estimate that allows oversized mail to be rejected early in the ESMTP dialogue. V8 sendmail still properly diagnoses out-of-space conditions when it actually reads the message.

If using 100% of the disk space is unacceptable, you can use the MinFreeBlocks (b) option to reserve space for other kinds of files:

Obminblocks/maxsize                             <- configuration file (beginning with V8.6)
-obminblocks/maxsize                            <- command line (beginning with V8.6)
O MinFreeBlocks=minblocks                       <- configuration file (beginning with V8.7)
-OMinFreeBlocks=minblocks                       <- command line (beginning with V8.7)
define(`confMIN_FREE_BLOCKS',minblocks)         <- V8 m4 configuration

Here, minblocks is of type numeric and is the number of disk blocks you wish to reserve. If minblocks is missing or negative or if the entire option is omitted, no blocks are reserved. For the V8.6 form of the b option a slash is required to separate minblocks from maxsize (maxsize is described under the MaxMessageSize option, Section 34.8.37). The default when configuring with the V8 m4 method is 100.

Note that minblocks are reserved only for the ESMTP SIZE keyword to the MAIL command. No check is made for any other kind of queuing to reserve space. Consequently, you should reserve a sufficient number of blocks to satisfy your normal queuing needs.

The MinFreeBlocks (b) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.41 MinQueueAge

Skip queue file if too young

(V8.7 and above)

Ordinarily, all messages in the queue are processed whenever sendmail is run in queue-processing mode. No distinction is made between recently queued messages and messages that have been in the queue for a long time (other than by priority which simply orders the processing).

Some sites may prefer to process the queue often, say, once every five minutes. This ensures that all important mail will be delivered promptly but can exact a price in degraded performance. Every time the queue is processed, sendmail tries to deliver every mail message the queue contains, but at many sites there can be many queued messages that should not be retried every five minutes. One way to handle this problem is to set the MinQueueAge option. If it is set to 1h (one hour), every queued message is forced to remain in the queue for a minimum of one hour, even if the queue is processed more frequently:

O MinQueueAge=wait			<- configuration file (beginning with V8.7)
-OMinQueueAge=wait			<- command line (beginning with V8.7)
define(`confMIN_QUEUE_AGE',`wait')		<- V8 m4 configuration

The argument wait is of type time. If wait is less than or equal to zero or if it is missing, this feature is disabled. If the units in the time expression are omitted, the default is minutes. There is no default for the m4 method.

Note that the decision of whether to process or not is not based on the time the message was placed into the queue. It is instead based on the time the message was last processed from the queue. This time is stored in the K line of the qf file (see Section 23.9.8, K line). This minimum is enforced only if the number of times delivery has been attempted is greater than zero (see the qf file's N line, Section 23.9.10, N line). This ensures that the first delivery attempt will be made immediately.

The MinQueueAge option is safe. If specified from the command line, sendmail will not relinquish its root privilege.

34.8.42 MustQuoteChars

Quote nonaddress characters

(V8.8 and above)

All addresses are composed of address information and nonaddress information. The two most common forms of addresses look like this:

address (non-address)
non-address <address>

Usually, the nonaddress information is a user's full name or something similar. RFC822 requires that certain characters be quoted if they appear in the nonaddress part of an address:

@ , ; : \ ( ) [ ] . \'

Nonaddress information inside parentheses is already quoted by those parentheses. Other nonaddress that contains any of these characters needs to be quoted with full quotation marks. To illustrate, consider this address:

From: Bob@home <[email protected]>

Because the nonaddress part Bob@home contains an @ character, sendmail is required to quote the entire phrase, thus forming

From: "Bob@home" <[email protected]>

This quoting is automatic and cannot be turned off for the first nine characters:

@ , ; : \ ( ) [ ] . \'
                  -^ -^
		the last two are optional (but are required by RFC822)

The last two characters are optional (but required by RFC822). All 11 characters are the default for the MustQuoteChars option. If you wish to add characters to the mandatory list of characters that will be quoted, you may do so with the MustQuoteChars option:

O MustQuoteChars=more            <- V8.8 and above
-OMustQuoteChars=more            <- V8.8 and above

Here, more is of type string and is the list of additional characters that you wish to see quoted in the nonaddress part of addresses. The more characters replace the optional characters and append to the mandatory characters. If more is missing, the optional characters are dropped. There is no m4 shorthand for setting this option.

The MustQuoteChars option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.43 NoRecipientAction

Handle no recipients in header

(V8.7 and above)

The header portion of a mail message must contain at least one recipient header. Problems can arise when an MUA produces a recipientless message or when the only recipients are listed in a Bcc: header line. In the past, sendmail inserted an Apparently-To: header (see Section 35.10.2, Apparently-To:) into any message that lacked header recipients. The addresses in the Apparently-To: were gleaned from the envelope.

Beginning with V8.7 sendmail, it is possible to chose how recipientless headers will be handled. This is done with the NoRecipientAction option, which is used like this:

O NoRecipientAction=what              <- configuration file (beginning with V8.7)
-ONoRecipientAction=what              <- command line (beginning with V8.7)
define(`confNO_RCPT_ACTION',what)     <- m4 configuration

The argument what is of type string and must be selected from those shown in Table 34.16. If the what is omitted or if it is other than one of the possibilities shown, the following error is printed, and the option is ignored:

Invalid NoRecipientAction: badwhat

If the entire option is omitted, the default becomes none. The default for the m4 technique is to omit this option.

The what is case-insensitive, meaning that none and nOnE are both identical.

Table 34.16: NoRecipientAction Option Keywords
WhatMeaning
add-apparently-toSection 34.8.43.1, "NoRecipientAction=add-apparently-to"

Add an Apparently-To: header

add-bccSection 34.8.43.2, "NoRecipientAction=add-bcc"

Add an empty Bcc: header

add-toSection 34.8.43.3, "NoRecipientAction=add-to"

Add a To: header

add-to-undisclosedSection 34.8.43.4, "NoRecipientAction=add-to-undisclosed"

Add To: undisclosed-recipients:;

noneSection 34.8.43.5, "NoRecipientAction=none"

Pass the message unchanged

The NoRecipientAction option is safe. If it is specified from the command line, sendmail will not relinquish its root privilege.

34.8.43.1 NoRecipientAction=add-apparently-to

Add an Apparently-To: header. That is, act like pre-V8.7 sendmail. But note that this choice has been deprecated and should not be used.

34.8.43.2 NoRecipientAction=add-bcc

Add an empty Bcc: header. This makes the header portion of the mail message legal under RFC822 but implies that all recipients originally appeared in Bcc: header lines. But be aware that old versions of sendmail will strip all Bcc: headers, so the next site may add an Apparently-To: header and wrongly expose the address.

34.8.43.3 NoRecipientAction=add-to

Add a To: header and fill it out with all the recipients from the envelope. This may be misleading because it can give a false picture of the intended recipients. It can also cause Bcc: header addresses to be mistakenly revealed. This choice may be appropriate in the command line when sendmail is run from an MUA that routinely omits recipient headers.

34.8.43.4 NoRecipientAction=add-to-undisclosed

Add a To: header, but list in it only the address of an empty, but descriptive, mailing list:

To: undisclosed-recipients:;

This is the recommended setting for use in configuration files.

34.8.43.5 NoRecipientAction=none

Pass the message unchanged. Currently, this is technically illegal because RFC822 requires at least one recipient header in every mail message. This choice may be appropriate for naive sites that kick all mail to a smart host for processing. Note that the IETF is considering making this legal.

34.8.44 OldStyleHeaders (o)

Allow spaces in recipient lists

(All versions)

In pre-RFC821 days, lists of recipients were commonly space-delimited; that is,

hans christian andersen

was considered a list of three mail recipients, rather than a single, three-part name. Currently, individual recipient names must be delimited with commas, and internal spaces must be quoted. That is,

hans,christian,andersen<- three recipients
"hans christian andersen"<- a single three-part name
hans christian andersen<- illegal

Since some users and some old programs still delimit recipient lists with spaces, the OldStyleHeaders (o) option can be used to tell sendmail to internally convert those spaces to commas.

The forms of the OldStyleHeaders (o) option are as follows:

Oobool                                 <- configuration file (old form)
-oobool                                <- command line (old form)
O OldStyleHeaders=bool                 <- configuration file (beginning with V8.7)
-OOldStyleHeaders=bool                 <- command line (beginning with V8.7)
define(`confOLD_STYLE_HEADERS',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If that argument is missing, the default value is true, and unquoted spaces in an address are converted to commas. The default when configuring with the m4 technique is true. If the entire OldStyleHeaders (o) option is missing, it defaults to false, and unquoted spaces are converted to the character defined by the BlankSub (B) option (see Section 34.8.5).

The sendmail program is somewhat adaptive about commas. When first examining a list of addresses, it looks to see whether one of the following four characters appears in that list:

, ; < (

If it finds any of these characters in an address list, it turns off the OldStyleHeaders (o) option for the remainder of the list. You always want to enable this option in your configuration file. The only exception might be the unusual situation in which all addresses are normally comma-separated but some legal addresses contain spaces.

Note that comma delimiting allows spaces around recipient names for clarity. That is, both of the following are equivalent:

hans,christian,andersen
hans, christian, andersen

The OldStyleHeaders (o) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.45 OperatorChars or $o

Set token separation operators

(V8.7 and above)

The OperatorChars option stores as its value a sequence of characters, any one of which can be used to separate the components of an address into tokens (see Section 8.3, "Rule Sets"). Prior to V8.7 the $o macro fulfilled this role. Beginning with V8.7, the OperatorChars option has taken over:

Do.:%@!^=/[]                          <- prior to V8.7
O OperatorChars=.:%@!^=/[]            <- beginning with V8.7

The list of separation operators declared with this option is joined by sendmail to an internal list of hard-coded separation operators:

()<>,;\"\r\n

The combined list is used in tokenizing the workspace for rule-set processing. The order in which the characters appear in the OperatorChars option declaration is arbitrary. The space and tab characters need not be included in that list because they are always used to separate tokens.

Care should be taken in eliminating any given character from this list. Before doing so, the entire configuration file should be examined in detail to be sure that no rule requires that character. The use of the individual characters in addresses is beyond the scope of this book. The book !%@:: A Directory of Electronic Mail Addressing and Networks, by Donnalyn Frey and Rick Adams (O'Reilly & Associates, 1993), contains the many forms of addressing in great detail.

The OperatorChars option is used like this:

O OperatorChars=text               <- beginning with V8.7
define(`confOPERATORS',`text')     <- V8 m4 technique

The text is of type string. If it is missing and if the configuration file version is less than 7, sendmail tries to use the value of the $o macro. If that macro is also undefined, a default of ".:@[]" is used. If text is longer than 39 characters, it is truncated to 39 characters. In using the V8 m4 technique, a default of ".:%@!^/[]+" is used.

The OperatorChars option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.46 PostmasterCopy (P)

Extra copies of postmaster mail

(All versions)

RFC822, entitled Standard for the Format of ARPA Internet Text Messages, requires that all sites be set up so that mail addressed to the special name Postmaster [23] always be successfully delivered. This requirement ensures that notification of mail problems can always be sent and successfully delivered to the offending site. [24] At most sites the name Postmaster is an alias to a real person's name in the aliases file. Mail to Postmaster should never be ignored.

[23] The name Postmaster is case-insensitive. That is, POSTMASTER, Postmaster, postmaster, and even PoStMaStEr are all equivalent.

[24] Note that adoption of RFC1648, entitled Postmaster Convention for X.400 Operations, has extended this concept to include hosts addressed as [email protected] that are really X.400 sites masquerading as Internet sites.

Ordinarily, notification of locally bounced mail and other mail problems is sent back (bounced) to the sender of the message. The local person in the role of Postmaster does not get a copy of local failed mail.

The PostmasterCopy (P) option tells sendmail to send a copy of all failed mail to another person, often Postmaster. Under V8 and SunOS that copy contains only the failed message's header. Under other versions of sendmail that copy includes both the header and the body.

The forms of the PostmasterCopy (P) option are as follows:

OPuser                              <- configuration file (old form)
-oPuser                             <- command line (old form)
O PostmasterCopy=user               <- configuration file (beginning with V8.7)
-OPostmasterCopy=user               <- command line (beginning with V8.7)
define(`confCOPY_ERRORS_TO',user)   <- V8 m4 configuration

The argument user is of type string. If the argument is missing or if the PostmasterCopy (P) option is entirely missing, no extra copy is sent. The default for the m4 configuration technique to not send an extra copy.

While debugging a new sendmail.cf file, it is wise to define the PostmasterCopy (P) option so that you receive a copy of all failed mail. Once the configuration file is stable, either the PostmasterCopy (P) option may be removed or the name may be replaced with an alias to a program. Such a program could filter the copies of error mail so that only serious problems would be seen.

Macros used in the user argument will be correctly expanded before use. For example,

DHmailhost                                <- old form
OPPostmaster@$H                           <- old form

D{NOTIFYHOST}mailhost                     <- beginning with V8.7
O PostmasterCopy=Postmaster@${NOTIFYHOST} <- beginning with V8.7

The PostmasterCopy (P) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.47 PrivacyOptions (p)

Increase privacy of the daemon

(V8.1 and above)

The PrivacyOptions (p) option is used primarily as a way to force other sites to adhere to SMTP conventions, but can also be used to improve security.

The forms of the PrivacyOptions (p) option are as follows:

Opwhat,...                               <- configuration file (old mode)
-opwhat,...                              <- command line (old mode)
O PrivacyOptions=what,...                <- configuration file (beginning with V8.7)
-OPrivacyOptions=what,...                <- command line (beginning with V8.7)
define(`confPRIVACY_FLAGS',`what,...')   <- V8 m4 configuration

Multiple what arguments may be listed and must be separated from one another by commas (there may be arbitrary spaces around the commas), for example,

Op authwarnings, needmailhelo
O PrivacyOptions=authwarnings, needmailhelo

If this option is entirely omitted or if no what arguments are listed, the option defaults to public. The default for the m4 configuration technique is authwarnings. The possible what arguments are listed in Table 34.17.

Table 34.17: PrivacyOptions Option Keywords
KeywordMeaning
authwarningsSection 34.8.47.1, ""PrivacyOptions=authwarnings"

Enable X-Authentication-Warning: headers

goawaySection 34.8.47.2, ""PrivacyOptions=goaway"

Much checking for privacy and security

needexpnheloSection 34.8.47.3, "PrivacyOptions=needexpnhelo"

Require HELO before EXPN

needmailheloSection 34.8.47.4, "PrivacyOptions=needmailhelo"

Require HELO before MAIL

needvrfyheloSection 34.8.47.5, "PrivacyOptions=needvrfyhelo"

Require HELO before VRFY

noexpnSection 34.8.47.6, ""PrivacyOptions=noexpn"

Disallow all SMTP EXPN commands

noreceiptsSection 34.8.47.7, ""PrivacyOptions=noreceipts"

Prevent return receipts

novrfySection 34.8.47.8, ""PrivacyOptions=novrfy"

Disallow all SMTP VRFY commands

publicSection 34.8.47.9, "PrivacyOptions=public"

No extra checking for privacy or security

restrictmailqSection 34.8.47.10, ""PrivacyOptions=restrictmailq"

Restrict who may run mailq(1)

restrictqrunSection 34.8.47.11, ""PrivacyOptions=restrictqrun"

Restrict who processes the queue

If what is not one of the keywords listed in the table, sendmail prints the following message and ignores the unknown word:

readcf: Op line: unknown_word unrecognized

Note that sendmail checks for nonroot use of the -C (see Section 36.7.15, -C) and -oQ (see Section 34.8.48) command line switches and dangerous uses of the -f (see Section 36.7.21, -f and -r) command line switch when the command line is read but does not issue warnings until after the configuration file is read. That way, the configuration file determines how X-Authentication-Warning: headers will be issued.

The PrivacyOptions (p) option is safe. If specified from the command line, it does not cause sendmail to relinquish its root privilege. Because it is really a mask, specifications in the configuration file or on the command line can only make it more restrictive.

34.8.47.1 "PrivacyOptions=authwarnings

Setting authwarnings causes sendmail to insert special headers into the mail message that advise the recipient of reasons to suspect that the message may not be authentic. The general form of this special header is shown at the end of this paragraph. The possible reasons are listed in Chapter 35, Headers (see Section 35.10.35, X-Authentication-Warning:).

X-Authentication-Warning: ourhost: reason

34.8.47.2 "PrivacyOptions=goaway

A shorthand way to set all of authwarnings, noexpn, novrfy, needmailhelo, needexpnhelo, and needvrfyhelo.

34.8.47.3 PrivacyOptions=needexpnhelo

The SMTP EXPN command causes sendmail to "expand" a local address and print the result. If the address is an alias, it shows all the addresses that result from the alias expansion. If the address is local, it shows the result of aliasing through a user's ~/.forward file. If needexpnhelo is specified, sendmail requires that the requesting site first introduce itself with an SMTP HELO or ELHO command. If the requesting site has not done so, sendmail responds with the following message rather than providing the requested expansion information:

503 I demand that you introduce yourself first

34.8.47.4 PrivacyOptions=needmailhelo

The SMTP protocol specifies that the sending site should issue the HELO or ELHO command to identify itself before specifying the name of the sender with the MAIL command. By listing needmailhelo with the PrivacyOptions (p) option, you cause the following error to be returned to the sending site in this situation:

503 Polite people say HELO first

If needmailhelo is not specified but authwarnings is specified, then the following header is added to the message describing the problem:

X-Authentication-Warning: ourself: Host they didn't use HELO protocol

34.8.47.5 PrivacyOptions=needvrfyhelo

The SMTP VRFY command causes sendmail to verify that an address is that of a local user or local alias. Unlike EXPN above, VRFY does not cause mailing list contents, the result of aliasing, or the contents of ~/.forward files to be displayed. If needvrfyhelo is specified, sendmail requires that the requesting site first introduce itself with an SMTP HELO or ELHO command. If the requesting site has not done so, sendmail responds with the same message as for needexpnhelo above, rather than providing the requested verification information.

34.8.47.6 "PrivacyOptions=noexpn

Setting noexpn causes sendmail to disallow all SMTP EXPN commands. In place of information, sendmail sends the following reply to the requesting host:

502 That's none of your business            <- prior to V8.7
502 Sorry, we do not allow this operation   <- beginning with V8.7

Setting noexpn also causes sendmail to reject all SMTP VERB commands:

502 Verbose unavailable

Other sendmail programs may send VERB if the delivery agent making the connection has the F=I flag set (see Section 30.8.25, F=I (uppercase i)).

34.8.47.7 "PrivacyOptions=noreceipts

Setting noreceipts causes pre-V8.7 sendmail to silently skip the processing of all Return-Receipt-To: headers (see Section 35.10.29, Return-Receipt-To:). Beginning with V8.7 sendmail, notification of successful delivery is governed by the NOTIFY keyword (see RFC1891) to the ESMTP RCPT command:

RCPT TO: <address> NOTIFY=SUCCESS

Setting noreceipts causes V8.7 sendmail to silently skip all such requests for notification of successful delivery.

34.8.47.8 "PrivacyOptions=novrfy

Setting novrfy causes sendmail to disallow all SMTP VRFY commands. In place of verification, sendmail sends the following reply to the requesting host:

252 Who's to say?                                                  <- V8.6
252 Cannot VRFY user; try RCPT to attempt delivery (or try finger) <- V8.7

34.8.47.9 PrivacyOptions=public

The default for the non-m4 version of the PrivacyOptions (p) option is public. This means that there is no extra checking for valid SMTP syntax and no checking for the security matters.

34.8.47.10 "PrivacyOptions=restrictmailq

Ordinarily, anyone may examine the mail queue's contents by using the mailq(1) command (see Section 23.4, "Printing the Queue"). To restrict who may examine the queue's contents, specify restrictmailq. If restricted, sendmail allows only users who are in the same group as the group ownership of the queue directory to examine the contents. This allows the queue directory to be fully protected with mode 0700 yet for selected users to still be able to see its contents.

34.8.47.11 "PrivacyOptions=restrictqrun

Ordinarily, anyone may process the queue with the -q switch (see Section 23.6.1). To limit queue processing to root and the owner of the queue directory, specify restrictqrun. If queue processing is restricted, any nonprivileged user who attempts to process the queue will get this message:

You do not have permission to process the queue

34.8.48 QueueDirectory (Q)

Location of queue directory

(All versions)

Mail messages that have not yet been delivered are stored in the sendmail program's queue directory. The location of that directory is defined by the QueueDirectory (Q) option. That location may be a relative pathname (for testing) or an absolute pathname. If the specified location does not exist, sendmail prints something like the following:

cannot chdir(/var/spool/mqueue): No such file or directory

If the location exists but is not a directory, sendmail prints something like the following:

cannot chdir(/var/spool/mqueue): Not a directory

In both cases, sendmail also logs an error message via syslog(8) if the logging level of the LogLevel (L) option (see Section 34.8.33) permits. In both cases, sendmail aborts immediately.

The forms of the QueueDirectory (Q) option are as follows:

OQpath                       <- configuration file (old form)
-oQpath                      <- command line (old form)
O QueueDirectory=path        <- configuration file (beginning with V8.7)
-OQueueDirectory=path        <- command line (beginning with V8.7)
define(`QUEUE_DIR',`path')   <- V8 m4 configuration

The path argument is of type string. If it is missing, the value for path defaults to "mqueue". Relative names for the queue are always relative to the directory in which sendmail was invoked. If the entire QueueDirectory (Q) option is missing, the value for path defaults to the C language value of NULL, and sendmail complains with

cannot chdir((null)): Bad file number

The default in configuring with the m4 technique varies depending on your operating system.

The QueueDirectory (Q) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.49 QueueFactor (q)

Factor for high-load queuing

(All versions)

When the load average on a machine (the average number of processes in the run queue over the last minute) becomes too high, sendmail can compensate by queuing all mail, rather than delivering it. The QueueFactor (q) option is used in combination with the QueueLA (x) option (see Section 34.8.50) to calculate the point at which sendmail stops delivering. If the current load average is greater than or equal to the value given to the QueueLA (x) option, then the following formula is evaluated:

msgpri > q / (la - x + 1)

Here, q is the value set by this option, la is the current load average, and x is the cutoff load specified by the QueueLA (x) option. If the value yielded by this calculation is less than or equal to the priority of the current mail message (msgpri above), the message is queued rather than delivered. Priorities are initialized with the P sendmail.cf command (see Section 35.8, "Precedence") and tuned with the RecipientFactor (y) and ClassFactor (z) options (see Section 34.8.53). As the load average (la) grows, the value to the right of the > becomes smaller, increasing the chance that msgpri will exceed that threshold (so that the mail will be queued). Beginning with V8.7 sendmail, this relation can be tuned with the help of the -d3.30 debugging switch (see Section 37.5.18, -d3.30).

The forms of QueueFactor (q) option are as follows:

Oqfact                            <- configuration file (old form)
-oqfact                           <- command line (old form)
O QueueFactor=fact                <- configuration file (beginning with V8.7)
-OQueueFactor=fact                <- command line (beginning with V8.7)
define(`confQUEUE_FACTOR',fact)   <- V8 m4 configuration

The argument fact is of type numeric. It may be positive, negative, or zero. If fact is missing, the value defaults to zero. If the entire QueueFactor (q) option is missing, the default value given to fact is 600000 (six hundred thousand). The default for the m4 technique is to omit this option.

Note that the load average is effective only if your sendmail binary was compiled with load-average support (see Section 18.8.14, LA-TYPE). Use the -d3.1 debugging switch (Section 37.5.14, -d3.1) to discover whether your binary includes that support.

The QueueFactor (q) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.50 QueueLA (x)

On high load, queue only

(All versions)

The QueueLA (x) option specifies the load above which sendmail queues messages rather than delivering them. The QueueLA (x) and QueueFactor (q) options interact to determine this cutoff; they are both covered under the QueueFactor (q) option (Section 34.8.49).

The forms of the QueueLA (x) option are as follows:

Oxload                        <- configuration file (old form)
-oxload                       <- command line (old form)
O QueueLA=load                <- configuration file (beginning with V8.7)
-OQueueLA=load                <- command line (beginning with V8.7)
define(`confQUEUE_LA',load)   <- V8 m4 configuration

The optional argument load, of type numeric, defaults to zero if it is missing. If the entire QueueLA (x) option is missing, the default value given to load is eight. The default for the m4 technique is to omit this option. On newer, faster machines a higher setting may be more appropriate.

This QueueLA (x) option is effective only if your sendmail binary was compiled with load-average support (see Section 18.8.14). You can use the -d3.1 debugging switch (Section 37.5.14) to discover whether your binary includes the necessary support.

The QueueLA (x) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.51 QueueSortOrder

How to pre-sort the queue

(V8.7 and above)

Prior to V8.7 sendmail, mail messages in the queue were sorted by priority when the queue was processed. Under V8.7 an enhanced sort can be implemented with the QueueSortOrder option:

O QueueSortOrder=how                  <- configuration file (beginning with V8.7)
-OQueueSortOrder=how                  <- command line (beginning with V8.7)
define(`confQUEUE_SORT_ORDER',how)    <- V8 m4 configuration

The argument how is of type character. [25] It can be a P or p (for priority), which causes sendmail to emulate its old (sort by priority) behavior. It can be an H or h (for host), which causes sendmail to perform a new enhanced sort. Beginning with V8.8 sendmail, it can be T or t (for time), which sorts by submission time. If any other character is specified or if how is omitted, the following message is printed and the option is skipped:

[25] Of course, we recommend using full words for clarity.

Invalid queue sort order "badchar"

If this option is entirely omitted, the default is to sort by priority. The default in configuring with the V8 m4 technique is also priority.

The QueueSortOrder option is safe. If specified from the command line, sendmail will not relinquish its root privilege.

34.8.51.1 QueueSortOrder=host

If what is host, the messages in the queue are first sorted by recipient host, lock status, and priority. If any message for a host is locked (currently being delivered) all the messages for that host are also marked as locked. Then the queue is sorted again, this time by lock status (unlocked first), recipient host, and priority. Delivery attempts after this sort tend to group SMTP connections to the same host together sequentially.

Be careful in sorting by host. If you have a large backlog of low-priority (batch) mail on a low-speed link to some host (for example news), you might end up delaying higher-priority mail intended for other hosts. The host sort is recommended for high-speed links but is less desirable on low-speed links.

34.8.51.2 QueueSortOrder=priority

The method to order a queue run that has been used by sendmail for many years is a simple sort of the message priorities. A message's priority is found in the qf file's P line (see Section 23.9.11, P line). The sort is one of cost. That is, low (less positive) priorities are sorted ahead of high (more positive) values.

34.8.51.3 QueueSortOrder=time (V8.8 and above)

Beginning with V8.8, sendmail recognizes the time keyword, which causes it to sort based on submission time. This setting is not intended for use in the configuration file. Instead, it should be used only from the command line and in combination with the -qR command-line switch (see Section 23.6.2.3, "Process by identifier/recipient/sender: -q[ISR]").

If you wrongly set time in the configuration file, large jobs and old jobs will be sorted in with small and new jobs. This can delay important mail. Also note that there is no guarantee that mail will be delivered in submission order unless the DeliveryMode option (see Section 34.8.16) is set to queue or defer.

34.8.52 QueueTimeout (T)

Limit life of a message in the queue

(deprecated

When mail cannot be delivered promptly, it is left in the queue. At intervals specified by sendmail's -q command-line switch, redelivery of that queued mail is attempted. The maximum time a mail message can remain in the queue before being bounced as undeliverable is defined by the T option. (Note that the QueueTimeout (T) option has been deprecated in favor of the Timeout option of V8.7 sendmail.)

The forms of the QueueTimeout (T) option are as follows:

OTqtime                               <- configuration file (old form)
-oTqtime                              <- command line (old form)
O QueueTimeout=qtime                  <- configuration file (deprecated)
define(`confMESSAGE_TIMEOUT',qtime)   <- V8 m4 configuration

The argument qtime is of type time. If this argument is missing or if the entire QueueTimeout (T) option is missing, the value given to qtime is zero, and no mail is ever queued. [26] The qtime is generally specified as a number of days, 5d for example. (Incidentally, RFC1123 recommends five days as a minimum.)

[26] That is, each message is instantly bounced if it cannot be delivered on the first try.

All queued mail is timed out on the basis of its creation time compared to the timeout period specified by the QueueTimeout (T) option. Each queued message has its creation time stored in its qf file's T line (see Section 23.9.15, T line). When sendmail is run (either as a daemon or by hand) to process the queue, it gets its timeout period from the value of the QueueTimeout (T) option. As the queue is processed, each message's creation time is checked to see whether it has timed out on the basis of the current value of the QueueTimeout (T) option. Since the configuration file is read only once (when sendmail first starts), the timeout period cannot be subsequently changed. There are only two ways to lengthen the timeout period: first, by modifying the configuration file's QueueTimeout (T) option (which prior to V8 could involve creating a freeze file) and killing and restarting sendmail; second, by running sendmail by hand with the -q command-line switch (see Section 23.6.1) and setting a new timeout using the -oTtimeout command-line switch.

Since the creation time is stored in a queued file's qf file, messages can theoretically be rejuvenated (made to appear young again) by simply modifying that entry. The details of the qf queue file are presented in Section 23.9, "The qf File Internals".

Under V8 sendmail the sender can be notified when a message is delayed. This feature is enabled by the inclusion of a second argument following the qtime argument in the QueueTimeout (T) option declaration:

OTqtime/notify                     <- configuration file (V8.6)
-oTqtime/notify                    <- command line (V8.6)
O QueueTimeout=qtime/notify        <- configuration file (V8.7; deprecated)

If the second argument is present, it must be separated from the first by a /. The notify specifies the amount of time sendmail should wait, after the message is first queued, before sending notification to the sender that it was delayed. If notify is missing or longer than qtime, no warning messages are sent. If notify is longer than qtime, no notification is ever sent.

Note that this is a crude method compared to the one described under the Timeout option in Section 34.8.70. Beginning with V8.7 sendmail and using the queuereturn and queuewarn keywords of that option, the qtime and notify values above can be tuned on the basis of individual mail message priorities.

The QueueTimeout (T) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.53 RecipientFactor (y)

Penalize large recipient lists

(All versions)

Not all messages need to be treated equally. When sendmail processes the messages in its queue, it sorts them by priority. [27] The priority that is given to a message is calculated once, when it is first created, and adjusted (incremented or decremented) each time it is processed in the queue. Mail with the lowest priority number is handled first. The formula for the initial calculation is

[27] See the QueueSortOrder option, Section 34.8.51, for alternative ways to sort.

priority = nbytes - (class * z) + (recipients * y)

The items in this calculation are as follows:

priority

Priority of the message when it was first created.

nbytes

Number of bytes in the total message, including the header and body of the message.

class

Value given to a message by the Precedence: line in the header of the message. The string following the Precedence: is usually either first-class, special-delivery, junk, bulk, or list. That string is converted to a numeric value determined by the P command (see Section 35.8) in the sendmail.cf file.

z

Value given the ClassFactor (z) option (see Section 34.8.8) and a weighting factor to adjust the relative importance of the class.

recipients

Number of recipients to whom the message is addressed. This number is counted after all alias expansion.

y

Value given this RecipientFactor (y) option and weighting factor to adjust the relative importance of the number of recipients.

The forms of the RecipientFactor (y) option are as follows:

Oyfactor                                     <- configuration file (old form)
-oyfactor                                    <- command line (old form)
O RecipientFactor=factor                     <- configuration file (beginning with V8.7)
-ORecipientFactor=factor                     <- command line (beginning with V8.7)
define(`confWORK_RECIPIENT_FACTOR',factor)   <- V8 m4 configuration

The argument factor is of type numeric. If that argument is missing, the default value is zero. If the entire RecipientFactor (y) option is missing, the default value is 30000 (thirty thousand). The default for the m4 technique is to omit this option.

The RecipientFactor (y) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.54 RefuseLA (X)

Refuse connections on high load

(All versions)

When the load average on a machine (the average number of jobs in the run queue over the last minute) becomes too high, sendmail can compensate by refusing to accept SMTP connections. Some experts consider this a more serious problem than the queuing caused by the QueueLA (x) option (see Section 34.8.50), so prior to the introduction of V8.7 sendmail, they generally recommended that the load specified for this RefuseLA (X) option should be higher. [28] Under V8.7 the two options have been decoupled, and you can now tune them according to your personal philosophy.

[28] Others take the opposite stand. Paul Vixie, for one, believes that the RefuseLA option should be lower than the QueueLA option so that you stop accepting mail before you stop processing it.

The forms of the RefuseLA (X) option are as follows:

OXload                         <- configuration file (old form)
-oXload                        <- command line (old form)
O RefuseLA=load                <- configuration file (beginning with V8.7)
-ORefuseLA=load                <- command line (beginning with V8.7)
define(`confREFUSE_LA',load)   <- V8 m4 configuration

The argument load is of type numeric. If load is missing, the value becomes zero, causing all SMTP connections to be refused. If the entire RefuseLA (X) option is missing, the value for the load cutoff defaults to 12. The default for the m4 technique is to omit this option.

This RefuseLA (X) option is effective only if your sendmail binary was compiled with load-average support included (see Section 18.8.14). You can use the -d3.1 debugging switch (see Section 37.5.14) to discover whether your binary includes the necessary support.

The RefuseLA (X) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.55 ResolverOptions (I)

Tune DNS lookups

(All versions)

The ResolverOptions (I) allows you to tune the way DNS lookups are performed:

OIbool                              <- configuration file (old form)
-oIbool                             <- command line (old form)
-oI"arg ..."                        <- command line (V8.6)
OIarg ...                           <- configuration file (V8.6)
O ResolverOptions="arg ..."         <- configuration file (V8.7)
-OResolverOptions="arg ..."         <- command line (V8.7)
define(`confBIND_OPTS',`arg ...')   <- V8 m4 configuration

The arg is one or more arguments that allow you to tune the behavior of the name server. The arg arguments are identical to the flags listed in resolver(3), but you omit the RES_ prefix. For example, RES_DNSRCH is expressed DNSRCH. A flag may be preceded by a plus or a minus to enable or disable the corresponding name server option. If no pluses or minuses appear, the name server option is enabled just as though a plus was present. Consider the following:

OI+AAONLY -DNSRCH
O ResolverOptions=+AAONLY -DNSRCH

These turn on the AAONLY name server option (Authoritative Answers Only) and turn off the DNSRCH name server option (search the domain path). If the ResolverOptions (I) option is entirely omitted, the default is for the DNSRCH, DEFNAMES, and RECURSE name server options to be enabled and all others to be disabled. Thus, for example, DNSRCH is always enabled unless you specifically turn it off.

Beginning with V8.7 sendmail, the special string HasWildcardMX can be listed along with the other resolver options:

O ResolverOptions=+AAONLY -DNSRCH HasWildcardMX

This string causes MX lookups to be done with RES_QUERY set (provided that the level of the configuration is 6 or above; see Section 27.5); otherwise, those lookups are done with RES_SEARCH. It also inhibits MX lookups when getting the canonical name of the local host. It should always be used if you have a wildcard MX record that matches your local domain.

Note that omitting the ResolverOptions (I) option does not disable DNS lookups. To disable DNS under V8.6 sendmail, you must compile a version of sendmail with NAMED_BIND support omitted (see Section 18.8.23). Beginning with V8.7 sendmail, you can disable use of DNS via your service-switch file (see Section 34.8.61).

Under V8 sendmail, any Boolean argument following the ResolverOptions (I) is silently ignored. Therefore an initial True may be included for compatibility with previous versions of sendmail. Note that under V8 sendmail, a False produces an error and cannot be used to disable this option.

OITrue

Version 1 configuration files (see Section 27.5) cause sendmail to disable DNSRCH and DEFNAMES when doing delivery lookups but leave them on at all other times. Version 2 and above configuration files cause sendmail to use the resolver options defined by the ResolverOptions (I) option, except that it always enables DNSRCH when doing lookups with the $[ and $] operators. Starting with Version 8, sendmail defers the decision of whether or not to use DNS lookups to the ServiceSwitchFile option (see Section 34.8.61). DNS is now only considered canonical if the dns service is listed for hosts in the ServiceSwitchFile.

Finally, note that an attempt to use this option with a version of sendmail that does not support DNS lookups (see Section 18.8.23) will result in this error message:

name server (I option) specified but BIND not compiled in

The ResolverOptions (I) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.56 RetryFactor (Z)

Increment per job priority

(All versions)

When sendmail processes the messages in its queue, it sorts them by priority and handles those with the lowest (least positive) priority first.

The priority of a message is calculated once, using the RecipientFactor (y) (see Section 34.8.53) and ClassFactor (z) (see Section 34.8.8) options, when the message is first created, and it is adjusted, using this RetryFactor (Z) option, each time the message is processed in the queue.

Each time a message from the queue fails to be delivered and needs to be requeued, its priority is adjusted. That adjustment is made by adding the value of this RetryFactor (Z) option.

The forms of the RetryFactor (Z) option are as follows:

OZinc                                <- configuration file (old form)
-oZinc                               <- command line (old form)
O RetryFactor=inc                    <- configuration file (beginning with V8.7)

-ORetryFactor=inc                    <- command line (beginning with V8.7)
define(`confWORK_TIME_FACTOR',inc)   <- V8 m4 configuration

The argument inc is of type numeric. If inc is missing, the default value is zero. If the entire RetryFactor (Z) option is missing, the value for inc defaults to 90000 (ninety thousand). The default for the m4 technique is to omit this option. The increment is performed by adding the value of inc to the previously stored message priority each time that message is queued.

The RetryFactor (Z) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.57 RunAsUser

Run as non-root (on a firewall)

(V8.8 and above)

On firewalls, for reasons of additional security, it is often desirable to run sendmail as a user other than root. Beginning with V8.8 sendmail, you can accomplish this by using the RunAsUser option:

O RunAsUser=user:group                       <- V8.8 and above
-ORunAsUser=user:group                       <- V8.8 and above
define(`confRUN_AS_USER', `user:group')       <- V8 m4 technique

Here, user is either the uid number of the identity you want sendmail to run under or a symbolic name for that identity. If a symbolic name is specified and if that name cannot be looked up in the passwd(5) file, sendmail prints the following error:

readcf: option RunAsUser: unknown user bad symbolic name here

If the symbolic name is found in the passwd(5) file, the uid and gid that sendmail will run under are set from that file.

The :, if it is present, [29] signals to sendmail that you also intend to specify a group identity.

[29] It can also be a . or a / character.

The group is either the numeric gid that you want sendmail to run as or a symbolic name for a group. If it is a symbolic name, that name is looked up in the group(5) file. If it is not found in that file, the following error is printed:

readcf: option RunAsUser: unknown group bad group name here

If the symbolic name is in that file, sendmail will run under the gid found there.

The sendmail program assumes the identity specified just after the configuration file is read for all but the daemon mode. As a daemon, sendmail remains root to listen for incoming SMTP connections. Each time it receives a connection, it validates that connection (see Section 22.4.1, "Accept/Reject Connections via libwrap.a" and Section 29.10.3, "The check_relay Rule Set"), then fork(2)'s. The child then processes the incoming message. Immediately after the fork, the child assumes the identity specified by this RunAsUser option.

Note that running as non-root can lead to problems, especially on machines that do more than simply relay mail between networks. As non-root, sendmail may not be able to read some :include: files, will certainly not be able to read protected ~/.forward files, and won't be able to save messages to the queue, all unless permissions are relaxed to allow the non-root user such access. This option is intended to be used on a firewall machine. It should definitely not be used on nonfirewall machines.

The RunAsUser option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.58 SafeFileEnvironment

Directory for safe file writes

(V8.7 and above)

For security it is desirable to control the manner and circumstances under which messages are delivered to files. Beginning with V8.7 sendmail you can enhance the security of writing to files with the SafeFileEnvironment option. It is used like this:

O SafeFileEnvironment=path              <- configuration file (beginning with V8.7)
-OSafeFileEnvironment=path              <- command line (beginning with V8.7)
define(`confSAFE_FILE_ENV',path)        <- m4 configuration (beginning with V8.7)

The path is of type string and, if present, must be the full path name of a directory. The default, if either path or the entire option is missing, is NULL, causing this feature to be ignored.

When preparing to save a message to a file, sendmail first obtains the permissions of that file, if the file exists, and saves them (see Section 24.2.2, "Delivery to Files"). The sendmail program uses lstat(2) to obtain those permissions if it was compiled with HASLSTAT defined (see Section 18.8.9, HAS...). Otherwise, it uses stat(2).

Ordinarily, sendmail does a chroot(2) to the / directory just before it opens the file for writing. If the path is non-NULL and nonempty, sendmail then precedes that chroot(2) with a:

chroot(path)

If the chroot(2) fails, sendmail prints the following error and bounces the mail message:

mailfile: Cannot chroot(path)

If the name of the file begins with path, that prefix is stripped after the chroot(2) and before the fopen(3).

For example, consider the need to safely store all mail archive files on the mail hub in a directory called /archives. You would first create this configuration declaration:

O SafeFileEnvironment=/archives

Then every file archive notation in the aliases database should be changed to reference this base directory: [30]

[30] This is not strictly necessary. Both /archives/admin/log and /admin/log will work equally well. The former, however, is preferred for clarity.

adminlist:   :include:/usr/local/maillists/admin.list,
             /archives/admin/log

For safety, sendmail will henceforth chroot(2) into the /archives directory before delivering to any files. Note that this SafeFileEnvironment option affects all writes to files, so a user's ~/.forward entry (such as the following) will become relative to /archives and so may fail depending on your specific setup:

/u/bill/tmp/incoming     <- written as /archives/u/bill/tmp/incoming

The SafeFileEnvironment option also causes sendmail to verify that the file that is being written to is a plain file. If it is anything else, sendmail prints the following error and bounces the messages:

/dev/tty... Can't create output: Error 0

Here, an attempt to dump the message to /dev/tty failed because sendmail discovered it was a device rather than an ordinary file. But note that beginning with V8.8, it is legal to write to the special device named /dev/null.

The SafeFileEnvironment option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.59 SaveFromLine (f)

Save UNIX-style From lines

(All versions)

Many UNIX MUAs, as well as some transmittal systems like UUCP, require that a mail-message header begin with a line that begins with the five-character sequence "From ". All other header lines must adhere to the RFC822 standard and be delimited with a colon:

From [email protected] Fri Jul 26 12:35:25 1991
Return-Path: <[email protected]>
Date: Fri, 26 Jul 91 12:35:15 PDT
From: [email protected] (John Q Public)

If you don't set the SaveFromLine (f) option, the first line in the above example is stripped out by sendmail. The SaveFromLine (f) option prevents this, because it tells sendmail to keep header lines that begin with the five characters "From ". But note that it also causes this header to no longer be recognized as a header.

The forms of the SaveFromLine (f) option are as follows:

Ofbool                               <- configuration file (old form)
-ofbool                              <- command line (old form)
-s                                   <- command-line shorthand (not recommended)
O SaveFromLine=bool                  <- configuration file (beginning with V8.7)
-OSaveFromLine=bool                  <- command line (beginning with V8.7)
define(`confSAVE_FROM_LINES',bool)   <- V8 m4 configuration

The optional argument bool is of type Boolean. If bool is missing, this option becomes true (the "From " line is saved). If the entire option is missing, it defaults to false (neither save the "From " line nor recognize it as a header).

The SaveFromLine (f) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.60 SendMimeErrors (j)

Return MIME format errors

(V6.57 and above)

MIME (Multipurpose Internet Mail Extensions) is documented in RFC1341, with addition details in RFC1344, RFC1426, RFC1428, RFC1437, RFC1521, RFC1522, RFC1523, RFC1556, RFC1563, RFC1641, RFC1740, RFC1741, and RFC1767. MIME is a method of incorporating non-ASCII text (such as images and sounds) in mail messages.

When sendmail composes an error notification of failed (bounced) mail, this SendMimeErrors (j) option tells sendmail to include MIME format headers in that error notification. MIME format is required for DSN notification to work (the two go hand in hand). This option affects only returned (bounced) mail.

If the SendMimeErrors (j) option is true and if sendmail is composing a returned mail message, the following two headers are added to the header portion of that message:

MIME-Version: 1.0
Content-Type: multipart/report; report-type=delivery-status;
        boundary=magic

The version (1.0) of the MIME-Version: header (see Section 35.10.21) is hard-coded into V8 sendmail, so it cannot be changed. The Content-Type: is instead multipart/mixed if sendmail was compiled without DSN support (see Section 18.8.5, DSN). The magic of Content-Type: is a string that is used to separate the various parts of the message body. The string is formed from the queue ID, the time, and the hostname. For example:

Content-Type: multipart/report; report-type=delivery-status; 
        boundary=AA26662.9306241634/hostname

Then sendmail prefixes the body of the returned message (if there is one), a line of notification, and this boundary:

This is a MIME-encapsulated message

-AA26662.9306241634/hostname
           <- message body begins here

Newer MUAs are aware of MIME and can send and receive MIME messages. Such MUAs understand MIME-Version: header in a mail message. Older (non-MIME aware) MUAs ignore that header.

Unless you bounce mail to a site that cannot handle MIME, you should always set this SendMimeErrors (j) option to true.

The forms of the SendMimeErrors (j) option are as follows:

Ojbool                                  <- configuration file (V8.6)
-ojbool                                 <- command line (V8.6)
O SendMimeErrors=bool                   <- configuration file (V8.7)
-OSendMimeErrors=bool                   <- command line (V8.7)
define(`confMIME_FORMAT_ERRORS',bool)   <- V8 m4 configuration

The optional argument bool is of type Boolean. If bool is missing, this option becomes true (errors are sent in MIME format). If the entire option is missing it defaults to false (errors are sent just as they were before this option was introduced).

The SendMimeErrors (j) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.61 ServiceSwitchFile

Specify file for switched services

(V8.7 and above)

Some implementations of UNIX recognize that system information can be found in a variety of places. On Solaris, for example, hostnames can be obtained from the /etc/hosts file, from nis, from nisplus, or from DNS. Solaris allows the system administrator to choose the order in which these services are searched with a "service-switch" file. Other systems, such as Ultrix and DEC OSF/1, have a similar concept, but some (such as SunOS) use built-in rules that cannot be changed without the source code.

V8.7 sendmail uses a system-service switch if one is available. Otherwise, sendmail uses the service switch defined by this ServiceSwitchFile option.

The form for redefining the switched-services file is as follows:

O ServiceSwitchFile=path                 <- configuration file (beginning with V8.7)
-OServiceSwitchFile=path                 <- command line (beginning with V8.7)
define(`confSERVICE_SWITCH_FILE',path)   <- V8 m4 configuration

If this option is defined on an operating system that does offer a service-switch (such as Solaris, DEC OSF/1 or Ultrix), it is ignored. Otherwise, path is used as the full pathname of the file that is to be used as the service-switch. If path is omitted, the default is NULL. If the entire option is omitted, the default is /etc/service.switch. The default for the m4 technique is to omit this option.

The form of each line in that file is

service  how how

Here, service is either hosts (which states how host names are looked up) aliases (which states how aliases are looked up), or passwd (which states how passwd(5) information is looked up). For each of these services, there may be one or more how methods (not all of which make sense with all services). The service and the hows must be separated from each other by whitespace. The possible methods (values for each how) are files (the information is in a file or database, such as /etc/hosts), netinfo (for information on NeXT machines), nis (the information is in an nis map), nisplus (the information is in an nisplus map), dns (the host information is looked up with DNS), or hesiod (the information is listed with a Hesiod service). [31]

[31] Currently, the list is limited to those shown. Future versions of sendmail may offer others.

For example, consider the contents of the following /etc/service.switch file:

aliases nis
passwd nis files
hosts dns

Here, sendmail will look up aliases in the nis map mail.aliases. Password information, such as local user login names and full name information from the gecos field, will first be looked up in the nis map passwd.byname. If not found there, they will then be looked up in the file /etc/passwd. The last line tells sendmail to look up A and MX records for hosts using the DNS services.

The hosts line can also determine how MX records are treated (see Section 21.2.3, "Look Up Addresses for Delivery"). If "dns" does not appear in that line, sendmail disables lookups of MX records. If sendmail is configured to look up hosts with nis first, then DNS, it will do the MX lookup in DNS before the nis lookup.

For Solaris, hosts is looked up with the nsswitch.conf(4) service. For DEC OSF/1 and Ultrix, hosts is looked up with the svc.conf(5) service. For all others the file defined by the ServiceSwitchFile is examined for a line that begins with the word hosts. If that line is missing or if the file doesn't exist, "dns" is returned by default. But if NAMED_BIND was not defined (see Section 18.8.23) when sendmail was compiled, the default returned is "nis" for Solaris and SunOS, and on other systems it is "files."

Note that on systems such as SunOS, a version of gethostbyname(3) is still called that ignores the sendmail programs service-switch file. On such systems you may need to download the source, recompile, and install a version that works correctly.

The ServiceSwitchFile option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.62 SevenBitInput (7)

Force 7-bit input

(V8.1 and above)

By default, V8 sendmail leaves as is all bytes of every mail message it reads. This differs from other releases of sendmail that always clear (zero) the high (most-significant) bit. To make V8 sendmail behave like older versions and always clear the high bit on input, the SevenBitInput (7) option is available:

O7bool                               <- configuration file (V8.6)
-o7bool                              <- command line (V8.6)
O SevenBitInput=bool                 <- configuration file (V8.7 and above)
-OSevenBitInput=bool                 <- command line (V8.7 and above)
define(`confSEVEN_BIT_INPUT',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If bool is missing, the default value is true (clear the 8th bit). If this option is omitted entirely, the default is false (the 8th bit is unmodified). If you configure with V8's m4 technique, the default for confSEVEN_BIT_INPUT is false.

Note that this option is temporarily set to false for a single message if the ESMTP BODY=8BITMIME parameter is given and is set to true if the BODY=7BIT parameter is given.

Also note that the SevenBitInput (7) option affects input only. The F=7 delivery agent flag (see Section 30.8.4) can be used to set 7-bit output on an individual delivery agent basis.

The SevenBitInput (7) option is safe. If specified from the command line, sendmail will not relinquish its root privilege.

34.8.63 SingleLineFromHeader

Strip newlines from From: headers

(V8.8 and above)

Lotus Notes' SMTP mail gateway can generate From: headers that contain newlines and that contain the address on the second line:

From: Full Name
        <address>

Although this is legal per RFC822, many MUAs mishandle such headers and are unable to find the address. If your site suffers from this problem, you may define the SingleLineFromHeader option:

O SingleLineFromHeader=bool                  <- configuration file (V8.8)
-OSingleLineFromHeader=bool                  <- command line (V8.8)

The bool is of type Boolean. If it is true, sendmail will convert all newlines found in a From: header into space characters. If it is false, sendmail will leave all From: headers as is.

The SingleLineFromHeader option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.64 SingleThreadDelivery

Set single threaded delivery

(V8.8 and above)

Ordinarily, when sendmail processes the queue, it pays relatively little attention to other sendmail processes that may be processing the same queue at the same time. It locks a single qf file during delivery so that no other sendmail will attempt delivery of that message at the same time, but that is all. In sending many messages to a single other host, it is possible for multiple, parallel sendmail processes to try to deliver different messages from that queue to that single host all at once.

When accidental parallelism is not desirable, as in just processing the queue, you may wish to set up sendmail to be single-threaded. This ensures that only a single sendmail will ever be delivering to a given host at a given time. Single-threaded delivery is enabled with the SingleThreadDelivery option:

O SingleThreadDelivery=bool                       <- V8.8 and above
-OSingleThreadDelivery=bool                       <- V8.8 and above
define(`confSINGLE_THREAD_DELIVERY',bool)         <- V8 m4 technique

The argument bool is of type Boolean. If it is missing, the default value is true (deliver single-threaded). If the entire SingleThreadDelivery option is missing, the default becomes false (deliver in parallel). There is no m4 shorthand for enabling this option.

Note that the SingleThreadDelivery option will work only if the HostStatusDirectory option is also declared (see Section 34.8.31). If it is not, sendmail will print the following error and reset the SingleThreadDelivery option to false:

Warning: HostStatusDirectory required for SingleThreadDelivery

Also note that the SingleThreadDelivery option should probably never be set in the configuration file. To see why, consider an ongoing queue run to a host that is receiving many messages. If interactive user mail arrives during that run, the sendmail process executed by the user's MUA may find that it cannot send the message because it is single-threaded and the other sendmail has that host locked. In that case the user's message will be queued and will wait in the queue until the next queue is run. Even if your site is on the Internet, one large message to a slow site can cause interactive mail for that site to be wrongly queued.

The appropriate use for the SingleThreadDelivery option is on the command line when processing the queue. In daemon mode, for example, these startup commands may be appropriate:

/usr/lib/sendmail -bd
/usr/lib/sendmail -OSingleThreadDelivery -q30m

Note that two sendmail programs are started: one to act as a daemon and the other to periodically process the queue. Don't combine them when using the SingleThreadDelivery option, because incoming (relayed) mail can wrongly affect outgoing mail.

The SingleThreadDelivery option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.65 SmtpGreetingMessage or $e

The SMTP greeting message

(All versions)

When sendmail accepts an incoming SMTP connection it sends a greeting message to the other host. This message identifies the local machine and is the first thing it sends to say it is ready.

Prior to V8.7 sendmail, this message was declared with the $e macro. Beginning with V8.7 sendmail, it is declared with the SmtpGreetingMessage option. In both cases the message must begin with the fully qualified name of the local host. Usually, that name is stored in $j. The minimal definition for both is

De$j                           <- V8.6 and earlier
O SmtpGreetingMessage=$j       <- beginning with V8.7

Additional information may follow the local hostname. Any additional information must be separated from the hostname by at least one space:

De$j additional information
    -^
    at least one space

Traditionally, that additional information is the name of the listening program (in our case, always sendmail), the version of that program, and a statement that the program is ready. For example:

De$j Sendmail $v ready at $b                      <- V8.6 and earlier
O SmtpGreetingMessage=$j Sendmail $v ready at $b  <- beginning with V8.7

Note that it is not uncommon to see imaginative (and legal) variations in the additional information:

De$j Sun's sendmail.mx is set to go (at $b), let 'er rip!

Under versions V8.6 and earlier there was no default for this greeting message. You had to define $e in every configuration file. Beginning with V8.7, sendmail now checks to see whether the SmtpGreetingMessage option was defined and uses that value if it was. Otherwise, it checks to see whether the level of the configuration file is 6 or less. If it is and if the $e macro was defined it uses that value. Otherwise, it uses the following default:

$j Sendmail $v ready at $b

The forms for the $e and SmtpGreetingMessage are as follows:

Demessage                                      <- V8.6 and earlier
O SmtpGreetingMessage=message                  <- configuration file (beginning with V8.7)
-OSmtpGreetingMessage=message                  <- command line (beginning with V8.7)
define(`confSMTP_LOGIN_MSG',message)           <- V8 m4 technique

The message is of type string and must be present. It must contain, at minimum, the fully qualified name of the local host.

Note that in V8.1 through V8.6, sendmail always added the extra line

ESMTP spoken here

to its initial greeting message. Beginning with V8.7, sendmail instead inserts the word "ESMTP" into the greeting message itself just after the fully qualified hostname.

The SmtpGreetingMessage option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.66 StatusFile (S)

Specify statistics file

(All versions)

At busy and complex mail sites, many different delivery agents are active. For example, one kind of mail might be routed over the Internet using the TCP delivery agent, while another might be routed via the UUCP suite of programs, and yet another might be routed over a DS3 link to a group of research machines. In such circumstances, it is useful to gather statistical information about the total use to date of each delivery agent.

The StatusFile (S) option tells sendmail the name of the file into which it should save those statistics. This option does not cause statistics to be gathered. It merely specifies the name of the file where they may be saved. When sendmail runs, it checks for the existence of such a file. If the file exists, it opens and updates the statistics in the file. If the file doesn't exist, sendmail quietly ignores statistics. The statistics can be viewed by using the mailstats(8) [32] program (see Section 26.2.1, "The sendmail.st File").

[32] If you install V8 sendmail over an existing sendmail installation, you need to also install the V8 mailstats program.

The forms of the StatusFile (S) option are as follows:

OSpath                         <- configuration file (old form)
-oSpath                        <- command line (old form)
O StatusFile=path              <- configuration file (beginning with V8.7)
-OStatusFile=path              <- command line (beginning with V8.7)
define(`STATUS_FILE',`path')   <- V8 m4 configuration

The optional argument path is of type string. It may be a relative or a full pathname. The default value for path is sendmail.st. Relative names are always relative to the queue directory. If the entire option is missing, the value for path becomes the C language value NULL. The default in configuring with the V8 m4 technique varies depending on your operating system.

The S option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.67 SuperSafe (s)

Queue everything just in case

(All versions)

At times, such as when calling /bin/mail to deliver local mail, sendmail holds an entire message internally while waiting for that delivery to complete. Clearly, this runs the risk that the message will be lost if the system crashes at the wrong time.

As a safeguard against such rare catastrophes, the SuperSafe (s) option can be used to force sendmail to queue every message. The queued copy is left in place until sendmail is sure that delivery was successful. We recommend that this option always be declared as true.

The forms of the SuperSafe (s) option are as follows:

Osbool                          <- configuration file (old form)
-osbool                         <- command line (old form)
O SuperSafe=bool                <- configuration file (beginning with V8.7)
-OSuperSafe=bool                <- command line (beginning with V8.7)
define(`confSAFE_QUEUE',bool)   <- V8 m4 configuration

The argument bool is of type Boolean. If it is missing, the default value is true (everything is queued). The default for the V8 m4 configuration technique is also true. If the entire SuperSafe (s) option is missing, the default becomes false (no special queuing behavior).

The SuperSafe (s) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.68 TempFileMode (F)

Permissions for temporary files

(All versions)

The TempFileMode (F) option tells sendmail what mode (file permissions) to give its temporary files and its freeze file. [33] Because the files in the queue contain private email, this option is usually set to the least permissive level, 0600. On dedicated mail servers (hub machines), where logins are restricted to mail managers, you may wish to relax permissions for easier problem solving.

[33] V8 sendmail no longer supports freeze files.

The forms of the TempFileMode (F) option are as follows:

OFmode                              <- configuration file (old mode)
-oFmode                             <- command line (old mode)
O TempFileMode=mode                 <- configuration file (beginning with V8.7)
-OTempFileMode=mode                 <- command line (beginning with V8.7)
define(`confTEMP_FILE_MODE',mode)   <- V8 m4 configuration

The mode is of type octal. If this option is entirely missing, the default permissions are 0644. Beware of omitting just the mode argument - if you do, the permissions become 0000, and sendmail may not be able to read or write its own files.

The TempFileMode (F) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.69 TimeZoneSpec (t)

Set time zone

(All versions)

Under System V UNIX, processes must look for the local time zone in the environment variable TZ. Because sendmail is often run as an SUID root program, it cannot (and should not) trust its environment variables. Consequently, on System V machines it is necessary to use the TimeZoneSpec (t) option to give sendmail the correct time zone information.

The forms for the TimeZoneSpec (t) option are as follows:

Otzone                           <- configuration file (old mode)
-otzone                          <- command line (old mode)
O TimeZoneSpec=zone              <- configuration file (beginning with V8.7)
-OTimeZoneSpec=zone              <- command line (beginning with V8.7)
define(`confTIME_ZONE',`zone')   <- V8 m4 configuration

Here, the zone is of type string and is usually three arguments in one: [34] the local abbreviation for standard time, the number of hours the local time differs from GMT, and the local abbreviation for daylight savings time. For example, on the west coast of the United States, you might declare

[34] This is actually a convention that is not used by all versions of UNIX. Consult your online documentation to find the correct form for your system.

OtPST8PDT                             <- pre-V8.7 form
O TimeZoneSpec=PST8PDT                <- beginning with V8.7

For pre-V8 sendmail on System V, if the zone argument is omitted or if this entire option is omitted, the default is the value compiled into your C language library (often the east coast of the United States, EST5EDT). For BSD the default is NULL.

Beginning with V8 sendmail, if the entire TimeZoneSpec (t) option is missing, the default is to unset the TZ environmental variable (use the system default). If zone is missing, the default is to import the TZ variable from the environment. If zone is present, time zone is set to that specified.

The system default varies depending on the operating system. For BSD UNIX it is the value returned by the gettimeofday(3) call. For SysV UNIX it is whatever was compiled into the C library (usually New Jersey time).

For the m4 declaration, zone should be either a literal USE_SYSTEM, which causes the entire option to be omitted, or a literal USE_TZ, which causes the option to be declared but the zone to be omitted (thus importing the TZ variable from the calling environment). Otherwise, a time zone declaration is as described above:

define(`confTIME_ZONE',`USE_SYSTEM')  <- use system default
#O TimeZoneSpec=                      <- the same 

define(`confTIME_ZONE',`USE_TZ')      <- use environment TZ
O TimeZoneSpec=                       <- the same 

define(`confTIME_ZONE',`EST5EDT')     <- use EST5EDT
O TimeZoneSpec=EST5EDT                <- the same

The TimeZoneSpec (t) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.70 Timeout (r)

Set timeouts

(All versions)

Many events can take a long time to complete - so long, in fact, that they can cause sendmail to appear to hang if they don't time out. For example, when reading commands or data from a remote SMTP connection, the other side can be so slow that it becomes necessary for the local sendmail to time out and break the connection. Similarly, when reading from its standard input, sendmail may find that the program feeding it information is taking so long that a timeout becomes necessary.

The V8 version of the sendmail program has introduced defaults for the amount of time it waits under various circumstances. The forms of the Timeout (r) option are as follows:

Ortime                                          <- configuration file (old form)
-ortime                                         <- command line (old form)
Orkeyword=value,...                             <- configuration file (V8.1)
-orkeyword=value,...                            <- command line (V8.1)
O Timeout=keyword=value,...                     <- configuration file (V8.7 and above)
-OTimeout=keyword=value,...                     <- command line (V8.7 and above)
define(`confREAD_TIMEOUT',`keyword=value,...')  <- V8 m4 configuration (not V8.7 up)

Prior to V8 sendmail, only a single time could be specified, which set the timeout for all SMTP transactions. Beginning with V8 sendmail, a list of keyword and value pairs can be specified that individually set a wide assortment of timeouts. The recognized keyword words are listed in Table 34.18. The default and minimum value for each in described in the individual section.

Table 34.18: Timeout Option Keywords
KeywordMeaning
commandSection 34.8.70.1

Wait for the next command

connectSection 34.8.70.2

Wait for connect(2) to return

datablockSection 34.8.70.3

Wait for each DATA block read

datafinalSection 34.8.70.4

Wait for acknowledgment of final dot

datainitSection 34.8.70.5

Wait for DATA acknowledgment

fileopenSection 34.8.70.6

Wait an NFS file to open (V8.7 and above)

heloSection 34.8.70.7

Wait for HELO or EHLO

hoststatusSection 34.8.70.8

Duration of host status (V8.8 and above)

iconnectSection 34.8.70.9

Wait for first connect(2) (V8.8 and above)

identSection 34.8.70.10

Wait for RFC1413 identification protocol

initialSection 34.8.70.11

Wait for initial greeting message

mailSection 34.8.70.12

Wait for MAIL acknowledgment

miscSection 34.8.70.13

Wait for other SMTP commands

queuereturnSection 34.8.70.14

Bounce if still undelivered (V8.7 and above)

queuewarnSection 34.8.70.15

Warn if still undelivered (V8.7 and above)

quitSection 34.8.70.16

Wait for QUIT acknowledgment

rcptSection 34.8.70.17

Wait for RCPT acknowledgment

rsetSection 34.8.70.18

Wait for RSET acknowledgment

The minimums are not enforced but are rather the minimums recommended by RFC1123, section 5.3.2. [35] The value is of type time. The default, if a unit character is omitted, is minutes. For the queuewarn and queuereturn keywords, however, the defaults are hours and days, respectively. Note that some of the default values may seem overly long. This is intentional because some events can legitimately take a very long time. Consider, for example, a misconfigured DNS server. If you time out too soon, your performance will actually decrease because the timeouts will cause retransmits.

[35] Note that the defaults are intentionally higher than the recommended minimums. Setting timeouts too low can cause mail to fail unnecessarily.

For the V8.7 and above m4 technique, each keyword is declared with its corresponding confTO_ expression. For example, the keyword initial is declared like this:

define(`confTO_INITIAL',`5m')                  <- V8 m4 configuration

The particular confTO_ expression and its corresponding default value are listed with each keyword.

For compatibility with old configuration files, if no keyword= is specified, timeouts for the mail, rcpt, datainit, datablock, datafinal, and command keywords are set to the indicated value:

Or2h              <- set them to two hours

An example of the r option with keyword= pairs looks like this:

Orrcpt=25m,datablock=3h

With the new V8.7 form of the Timeout option, individual timeouts can be listed more attractively like this:

O Timeout.rcpt      = 25m
O Timeout.datablock =  3h

For the above two examples the timeout for acknowledgment of the SMTP RCPT command (list a recipient) is 25 minutes and the timeout for acknowledgment of receipt of each line of the mail message is three hours; all the others that are not specified assume the default values.

The Timeout (r) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.70.1 Timeout.command

When local sendmail is running as an SMTP server, it acknowledges any SMTP command sent to it by the other host and then waits for the next command. The amount of time the local sendmail waits for each command is defined with the command keyword. The default is one hour, and the minimum is specified as five minutes. The m4 technique should use confTO_COMMAND for which not default is defined. If a command is not received in time, the local sendmail believes that the connection has hung and shuts it down.

34.8.70.2 Timeout.connect

When sendmail attempts to establish a network connection to another host, it uses the connect(2) system call. If the connection is going to fail, that system call will time out after an amount time that varies with the operating system. With Linux, for example, the timeout is 90 minutes, whereas for other versions of UNIX it is typically 5 minutes.

When the amount of time to wait for a connection to fail is of concern, you may override the system value with the connect keyword to the Timeout option: [36]

[36] Note that you can decrease the system defined timeout, but you cannot increase it.

O Timeout.connect=3m		         <- V8.8 and above
define(`confTO_CONNECT', 3m)	         <- V8 m4 technique

The default, if no timeout is specified, is to use the system imposed timeout. No default is defined for the m4 technique.

Note that if the connect(2) call times out, delivery will be deferred until the next queue run. If you wish the connect(2) to be tried again (as you might for a dial-on-demand machine), you should investigate the DialDelay option (see Section 34.8.17).

34.8.70.3 Timeout.datablock

The local sendmail then buffers the mail message and sends it to the receiving site one line at a time. The amount of time that the receiving sendmail waits for a read to complete is set with the datablock keyword. [37] The default value is one hour, and the specified minimum is three minutes. The m4 technique should use confTO_DATABLOCK, which has no default.

[37] The timeout for writes by the sending sendmail are timed out on the basis of the number of recipients.

34.8.70.4 Timeout.datafinal

After the entire mail message has been transmitted, the local sendmail sends a lone dot to say that it is done, then waits for the receiving sendmail to acknowledge acceptance of that dot:

250 Mail accepted

The amount of time that the local sendmail waits for acknowledgment that the mail message was received is set with the datafinal keyword. The default value is one hour, and the specified minimum is 10 minutes. The m4 technique should use confTO_DATAFINAL, which has no default. If the value is shorter than the time actually needed for the receiving site to deliver the message, the local sendmail times out before seeing the "Mail accepted" message when, in fact, the mail was accepted. This can lead to the local sendmail wrongly attempting to deliver the message later for a second time.

34.8.70.5 Timeout.datainit

After all the recipients have been specified, the local sendmail declares that it is ready to send the mail message itself. It issues the SMTP DATA command to the other site:

DATA

The local sendmail then waits for acknowledgment, which looks like this:

354 Enter mail, end with "." on a line by itself

The amount of time that the local sendmail waits for acknowledgment of its DATA command is set with the datainit keyword. The default value is five minutes, and the specified minimum is two minutes. The m4 technique should use confTO_DATAINIT, which has no default.

34.8.70.6 Timeout.fileopen

If a directory is remotely mounted and the server is down or not responding, an attempt to open a file in that directory can hang. Beginning with V8.7, the fileopen keyword sets the amount of time to wait for a remote open to complete. [38] The default is zero seconds, which sets no limit. The m4 technique should use confTO_FILEOPEN, which has no default.

[38] Note that this works only if the file system is mounted with the intr mount option.

34.8.70.7 Timeout.helo

After the greeting, the local sendmail sends a HELO (or EHLO to get ESMTP) message to identify itself. That message looks something like this:

HELO here.us.edu

The other site then replies with acknowledgment of the local HELO or EHLO:

250 there.dc.gov  Hello here.us.edu, pleased to meet you

The amount of time the local sendmail waits for the other site to acknowledge the local HELO or EHLO is set with the helo keyword. The default value is five minutes. There is no specified minimum, but we recommend no less than five minutes (because some sites use DNS to validate the hostname). The m4 technique should use confTO_HELO, which has no default.

34.8.70.8 Timeout.hoststatus

When processing the queue, sendmail saves the connection status of each host to which it connects and each host to which it fails to connect. It does this because an unsuccessful host should not be tried again during the same queue run. This makes sense when you consider that failures tend to remain failures for a while.

At sites that process huge queues, on the other hand, such behavior may not be appropriate. If it takes hours (rather than minutes) to process the queue, the likelihood increases that a previously failed connection may succeed. For such sites, V8.8 sendmail has introduced the Timeout.hoststatus option:

O Timeout.hoststatus=interval                  	<- V8.8 and above
-OTimeout.hoststatus=interval			<- V8.8 and above
define(`confTO_HOSTSTATUS', interval)		<- V8 m4 techniqueue

Here, interval is of type time. If interval is present, it specifies the length of time information about a host will be considered valid. If a queue run finishes faster than this interval, it has no effect. But when queue runs take longer than this interval, a previously down host will be given a second try if it appears in the queue again.

If interval is missing, it is interpreted as zero, and no host information is ever saved. If the entire option is missing, the default is 30 minutes. The m4 technique should use confTO_HOSTSTATUS, which has no default.

34.8.70.9 Timeout.iconnect

When sendmail attempts to establish a network connection to another host, it uses the connect(2) system call. If the connection is going to fail, that system call will time out after an amount of time that varies with the operating system. You can override the system timeout with the connect keyword (see Section 34.8.70.2) to the Timeout option.

When outgoing mail is first processed, mail to responsive hosts should precede mail to sluggish hosts. To understand why, consider that all mail is processed serially during each queue run. If a sluggish host precedes all the other hosts in the queue, those other hosts will not even be tried until the sluggish host finishes or times out. With this in mind, the very first time sendmail attempts to deliver a message, it should enforce a shorter connect(2) timeout than it should for latter attempts.

Beginning with V8.8 sendmail, you can set an initial connect(2) timeout with the iconnect keyword to the Timeout option:

O Timeout.iconnect=10s              <- time out first connection
O Timeout.connect=3m                <- time out all others

define(`confTO_ICONNECT', `10s')    <- v8 m4 technique

The default, if no Timeout.iconnect is specified or if the entire Timeout.iconnect option is omitted, is to time out the first connection the same as the timeout for all connections. The m4 technique should use confTO_ICONNECT, for which there is no default. The N line in the qf file (see Section 23.9.10) determines whether this is the first attempt or not. If the value in that line is zero, this is the first delivery attempt.

34.8.70.10 Timeout.ident

The sendmail daemon queries every outside connecting host with the RFC1413 identification protocol to record the identity of the user at the other end who made the connection and to verify the true name of the remote connecting host. The default timeout is to wait 30 seconds for a response. The ident keyword is used to change this timeout. If your site accepts mail from PCs running SMTP software, you may need to disable this feature. Some PCs get stuck when queried with the RFC1413 identification protocol. If the timeout is zero, the ident protocol is disabled. The m4 technique should use confTO_IDENT, for which there is no default.

34.8.70.11 Timeout.initial

The amount of time to wait for the initial greeting message. This message is printed by the remote site when it first makes its connection. The greeting message always starts with 220 and looks something like this:

220 there.dc.gov Sendmail 8.1/3x ready at ...

The default for the greeting wait and the recommended minimum are both five minutes. [39] The m4 technique should use confTO_INITIAL, for which there is no default.

[39] Because DNS name resolution can time out and retry and can actually take up to five minutes!

34.8.70.12 Timeout.mail

The local sendmail next sends the address of the sender (the envelope sender address) with an SMTP MAIL command:

MAIL From:<[email protected]>

The local sendmail then waits for acknowledgment, which looks like this:

250 <[email protected]>... Sender ok

The amount of time that the local sendmail waits for acknowledgment of its MAIL command is set with the mail keyword. The default value is 10 minutes, and the specified minimum is five minutes. The m4 technique should use confTO_MAIL, for which there is no default.

34.8.70.13 Timeout.misc

During the course of mail transfer, the local sendmail may issue short miscellaneous commands. Examples are NOOP (which stands for no operation) and VERB (which tells the other side to enter verbose mode). The time that the local sendmail waits for acknowledgment of these miscellaneous commands is defined with the misc keyword. The default is two minutes, and no minimum is specified. The m4 technique should use confTO_MISC, for which there is no default.

34.8.70.14 Timeout.queuereturn

That this keyword determines a mail message's lifetime in the queue. Beginning with V8.7, this queuereturn keyword is used to set the amount of time a message must wait in the queue before it is bounced as nondeliverable. Either it can be expressed as an interval of time:

O Timeout.queuereturn=5d
O Timeout.queuereturn.*=5d          <- the same
define(`confTO_QUEUERETURN',`5d')   <- V8 m4 technique

or it can be tuned on the basis of any of three possible levels of priority that a mail message may have. That is, both of the above set all three levels to five days, whereas the following tunes each level to three, five, and six days, respectively:

O Timeout.queuereturn.urgent=3d
O Timeout.queuereturn.normal=5d
O Timeout.queuereturn.non-urgent=6d
define(`confTO_QUEUERETURN_URGENT',`3d')       <- V8 m4 technique
define(`confTO_QUEUERETURN_NORMAL',`5d')       <- V8 m4 technique
define(`confTO_QUEUERETURN_NONURGENT',`6d')    <- V8 m4 technique

The default for the m4 configuration technique is to bounce all messages that remain in the queue for more than four days.

The keywords urgent, normal, and non-urgent correspond to the Precedence: header from the mail message. When the numeric equivalent of the Precedence: header as translated from the P line of the configuration file (see Section 35.8) is negative, the message is classified as nonurgent. When it is greater than zero, the message is classified as urgent. Otherwise, it is normal.

In addition to a message's precedence, a new Priority: header is available (see Section 35.10.24, Priority:) to specify the message priority and thereby bypass the value obtained from the Precedence: header.

Priority: urgent
Priority: normal
Priority: non-urgent

There is currently no way to specify a Priority: header's value from the sendmail command line.

34.8.70.15 Timeout.queuewarn

When a message is queued, sendmail sends a message to the sender explaining that the original message could not be delivered right away and that sendmail will keep trying. Beginning with V8.7, this queuewarn keyword is used to set the amount of time a message must wait in the queue before that explanation is mailed. Either it can be expressed as an interval of time:

O Timeout.queuewarn=4d
O Timeout.queuewarn.*=4d          <- the same
define(`confTO_QUEUEWARN',`4d')   <- V8 m4 technique

or it can be tuned on the basis of any of three possible levels of priority a mail message may have. That is, both of the above set all three levels to four days, whereas the following tunes each level to one, two, and four days, respectively:

O Timeout.queuewarn.urgent=1d
O Timeout.queuewarn.normal=2d
O Timeout.queuewarn.non-urgent=4d
define(`confTO_QUEUEWARN_URGENT',`1d')       <- V8 m4 technique
define(`confTO_QUEUEWARN_NORMAL',`2d')       <- V8 m4 technique
define(`confTO_QUEUEWARN_NONURGENT',`4d')    <- V8 m4 technique

The defaults for the m4 configuration technique are to send a warning for normal mail after four hours, for urgent mail after one hour, and for nonurgent mail after twelve hours.

The keywords urgent, normal, and non-urgent correspond to the Precedence: header from the mail message. When the numeric equivalent of the Precedence: header as translated from the P line of the configuration file (see Section 35.8) is negative, the message is classified as nonurgent. When it is greater than zero, the message is classified as urgent. Otherwise, it is normal.

In addition to a message's precedence, a new Priority: header is available (see Section 35.10.24) to specify the message priority and thereby bypass the value obtained from the Precedence: header:

Priority: urgent
Priority: normal
Priority: non-urgent

There is currently no way to specify a Priority: header's value from the sendmail command line.

34.8.70.16 Timeout.quit

When the local sendmail is finished and wishes to break the connection, it sends the SMTP QUIT command.

QUIT

The other side acknowledges, and the connection is terminated:

221 there.dc.gov delivering mail

The time the local sendmail waits for acknowledgment of the QUIT command is defined with the quit keyword. The default is two minutes, and no minimum is specified. The m4 technique should use confTO_QUIT, for which there is no default.

34.8.70.17 Timeout.rcpt

Next, the local sendmail issues one RCPT command to specify each envelope recipient. One such RCPT line might look like this:

RCPT To:<[email protected]>

The local sendmail then waits for acknowledgment, which looks like this:

250 <[email protected]>... Recipient ok

The amount of time that the local sendmail waits for acknowledgment of each RCPT command is set with the rcpt keyword. The default value is one hour, [40] and the specified minimum is five minutes. The m4 technique should use confTO_RCPT, for which there is no default.

[40] This timeout should be generously long because a recipient may be the name of a mailing list and the other side may take a long time to expand all the names in that list before replying.

34.8.70.18 Timeout.rset

If connection caching is enabled (see option k), the local sendmail sends an SMTP RSET command to reset the other side. The time the local sendmail waits for acknowledgment of the RSET command is defined with the rset keyword. The default is five minutes, and no minimum is specified. The m4 technique should use confTO_RSET, for which there is no default.

34.8.71 TryNullMXList (w)

Use A if no best MX record

(V8.1 and above)

RFC974 says that when mail is being sent from a host that is an MX record for the receiving host, all MX records of a preference equal to or greater than the sending host must be discarded. In some circumstances this can leave no usable MX records. In this absence, V8 sendmail bases its action on the setting of its TryNullMXList (w) option.

The forms of the TryNullMXList (w) option are as follows:

Owbool                                <- configuration file (V8.6)
-owbool                               <- command line (V8.6)
O TryNullMXList=bool                  <- configuration file (beginning with V8.7)
-OTryNullMXList=bool                  <- command line (beginning with V8.7)
define(`confTRY_NULL_MX_LIST',bool)   <- V8 m4 configuration

The bool is of type Boolean. If it is false, sendmail bounces the mail message with the following error message:

MX list for otherhost points back to thishost

If it is true, sendmail looks to see whether the receiving host has an A record. If it does, V8 sendmail tries to deliver the mail message directly to that host's A record address. If the host doesn't have an A record, sendmail bounces the message. See Section 21.3.7, "Ambiguous MX Records" in Chapter 21, DNS and sendmail, for a full discussion of why one setting may be preferable over the other. The default with the V8 m4 configuration technique is false.

The TryNullMXList (w) option is not safe as of V8.8.4. If it is specified from the command line, may cause sendmail to relinquish its root privilege.

34.8.72 UnixFromLine or $l

Define the From format

(All versions)

The UnixFromLine option replaces the pre-V8.7 $l macro. It has two functions:

  • It defines the look of the five character "From " header line needed by UUCP software.

  • It defines the format of the line that is used to separate one message from another in a file of many mail messages.

The forms of the UnixFromLine option and $l macro are as follows:

Dlformat                           <- configuration file (V8.6 and earlier)
O UnixFromLine=format              <- configuration file (beginning with V8.7)
-OUnixFromLine=format              <- command line (beginning with V8.7)
define(`confFROM_LINE',`format')   <- V8 m4 configuration

The format is of type string. Under versions V8.6 and earlier there was no default for format. So the $l macro always had to be defined. Beginning with V8.7, sendmail first checks to see if the UnixFromLine option was defined and uses that value if it was. Otherwise, it checks to see whether the level of the configuration file is 6 or less. If it is and if the $l macro was defined, it uses that value. Otherwise, it uses the default

From $g  $d

The UnixFromLine option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.72.1 UnixFromLine in UUCP software

UUCP software requires all messages to begin with a header line that looks like

From sender  date remote from <host>

The sendmail program prepends such a line to a mail message's headers if the F=U flag (see Section 30.8.42, F=U) is set for the delivery agent. [41] Prior to V8.7, if the local machine supports UUCP, the l macro must be supplied with "From ", sender, and date:

[41] Prior to V8.7 this behavior was supported only if UGLYUUCP was defined in conf.h when sendmail was compiled.

DlFrom $g $d

The rest of the information is supplied by sendmail.

34.8.72.2 UnixFromLine with mail files

Under UNIX, in a file of many mail messages such as a user's mailbox, lines that begin with the five characters "From " are used to separate one message from another. This is a convention that is not shared by all MUAs. The sendmail program appends mail messages to files under only two circumstances: when saving failed mail to the user's dead-letter file and when delivering to a local address that begins with the / character. In appending messages to files, it uses the UnixFromLine ($l) option to define the form of the message separator lines.

For sites that use the Rand MUA (and that do not also use UUCP) the UnixFromLine ($l) option can be defined to be four CTRL-A characters:

Dl^A^A^A^A
O UnixFromLine=^A^A^A^A

34.8.73 UnsafeGroupWrites

Check unsafe group permissions

(V8.8 and above)

In processing a ~/.forward file or a :include: file, a question arises when group or world write permission is enabled. Should sendmail trust the addresses found in such files? Clearly the answer is "no" when world write permission is enabled. But what of group write permission?

Beginning with V8.8 sendmail, the decision of whether or not to trust group write permission is left to the UnsafeGroupWrites option:

O UnsafeGroupWrites=bool                 <- configuration file (beginning with V8.8)
-OUnsafeGroupWrites=bool                 <- command line (beginning with V8.8)
define(`confUNSAFE_GROUP_WRITES',bool)   <- V8 m4 configuration

The optional argument bool, when missing, defaults to true (check for unsafe group write permission). If this option is entirely missing, it defaults to false (don't check for unsafe group write permission).

With this option set to true, a ~/.forward file or a :include: file with group or world writability will result in one of these four errors being logged:

filename: group writable forward file, marked unsafe
filename: world writable forward file, marked unsafe
filename: group writable include file, marked unsafe
filename: world writable include file, marked unsafe

Any address in the file that is a file or a program will result in a bounce and this message:

Address address is unsafe for mailing to programs
Address address is unsafe for mailing to files

The UnsafeGroupWrites option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.74 UseErrorsTo (l)

Use Errors-To: for errors

(V8.1 and above)

Ordinarily, V8 sendmail sends notification of failed mail to the envelope sender. It specifically does not send notification to the addresses listed in the Errors-To: header. It does this because the Errors-To: header violates RFC1123. For additional information about the Errors-To: header, see Section 35.10.13, Errors-To:.

The UseErrorsTo (l) option is available to prevent older versions of software from failing. When set, it allows error notification to be sent to the address listed in the Errors-To: header in addition to that sent to the envelope sender.

The forms of the UseErrorsTo (l) option are as follows:

Olbool                             <- configuration file (old form)
-olbool                            <- command line (old form)
O UseErrorsTo=bool                 <- configuration file (beginning with V8.7)
-OUseErrorsTo=bool                 <- command line (beginning with V8.7)
define(`confUSE_ERRORS_TO',bool)   <- V8 m4 configuration

The optional argument bool, when missing, defaults to true (errors are sent to the Errors-To: header). If this option is entirely missing, it defaults to false (the Errors-To: header is ignored).

The UseErrorsTo (l) option is safe. Even if it is specified from the command line, sendmail retains its root privilege.

34.8.75 UserDatabaseSpec (U)

Specify user database

(V8.1 and above)

V8 sendmail, if compiled with USERDB defined (see Section 18.8.54, USERDB), can use a special, internally understood database called the User Database. Addresses that are defined in the User Database can be looked up and modified after aliasing and before processing of the user's ~/.forward file.

The workings of this database are described in Section 33.5, "The User Database". The UserDatabaseSpec (U) option defines the name and location of the file containing this User Database information.

The forms of the UserDatabaseSpec (U) option are as follows:

OUpath,...                             <- configuration file (V8.6)
-oUpath,...                            <- command line (V8.6)
O UserDatabaseSpec=path,...            <- configuration file (V8.7)

-OUserDatabaseSpec=path,...            <- command line (V8.7)
define(`confUSERDB_SPEC',`path,...')   <- V8 m4 configuration

The argument path,... is of type string and is a comma- or space-separated list of elements. Those elements can be database pathnames or other information as described below. If path,... is missing or if the entire option is missing, the user database is not used. Otherwise, the user database is used, and each database is accessed in turn, leftmost to rightmost, in the list of paths. There is no default for the V8 m4 technique.

The elements of path,... can either be pathnames of files or other methods of lookup depending on the first character of each:

/

A lead slash causes the element to be interpreted as a pathname; for example, /etc/userdb.

@

A leading @ causes a copy of the message for each user to be forwarded to a specified host. The assumption is that the other host is in a better position to perform user database lookups. Such a declaration looks like @dbhost.our.domain. Note that this form of declaration must be last in the list that constitutes path,... because it always succeeds.

h

Beginning with V8.7, a leading h or H causes sendmail to perform a case-insensitive comparison of the path to the string "hesiod." If they match, user database inquiries are looked up via Hesiod services.

For example, the following declares two user databases. The first that is used up will be /etc/userdb. If the entry is not found in that database, it will be forwarded to the host mail.here.us for handling there:

O UserDatabaseSpec=/etc/userdb,@mail.here.us

Any leading character other than those shown above causes an error message to be printed and that particular path,... element to be ignored.

Unknown UDB spec badpath

Note that future releases of sendmail may include additional subfields for each path. These will look like :opt=value. Consequently, the path that you specify should not include the colon character.

If UDB_DEFAULT_SPEC is defined in Makefile when sendmail is compiled (see Section 18.8.53, UDB-DEFAULT-SPEC), that value becomes the default if the UserDatabaseSpec (U) option is missing. If UDB_DEFAULT_SPEC is undefined, the default becomes NULL and no User Database lookups are performed.

The UserDatabaseSpec (U) option is not safe. If specified from the command line, it may cause sendmail to relinquish its root privilege.

34.8.76 Verbose

Run in verbose mode

(v)

The sendmail program offers a verbose mode of operation. In this "blow-by-blow" mode a description of all the sendmail program's actions is printed to the standard output. This mode is valuable in running sendmail interactively but useless in running in daemon mode. Consequently, you should never set this option in the sendmail.cf file. Instead, you should set it from the command line using the -v command-line switch.

After the sendmail.cf file is parsed and the command-line arguments have been processed, sendmail checks to see whether it is in verbose mode. If it is, it sets the HoldExpensive (c) option (don't connect to expensive mailers; see Section 34.8.29) to false and sets the DeliveryMode (d) option (see Section 34.8.16) to interactive.

The forms of the Verbose (v) option are as follows:

Ovbool            <- configuration file (old form)
-ovbool           <- command line (old form)
-v                <- command-line shorthand
O Verbose=bool    <- configuration file (beginning with V8.7)
-OVerbose=bool    <- command line (beginning with V8.7)

The argument bool is of type Boolean. If it is missing, the default value is true (be verbose). If the entire option is missing, the default value is false (be quiet).

The Verbose (v) option is safe. When it is specified from the command line, sendmail retains its root privilege. Note that the Verbose (v) option should never be set in the configuration file.

34.8.77 (M)

Define a macro

(Obsolete as of V8.7)

The M option is used to set or change a defined macro's value. Although this option is allowed in the sendmail.cf file, it is exclusively intended for use from the command line. Macros that are defined in the command line will not override the values of those same macros defined in the configuration file.

The forms of the M option are as follows:

OMXvalue    <- configuration file
-oMXvalue   <- command line (old obsolete form)
-MXvalue    <- command line (beginning with V8.7)
DXvalue     <- both are equivalent of this in the configuration and m4 files

In all four cases the argument value is of type string. The value is assigned to the macro named X. Pre-V8.7 macro names are always a single character. Multicharacter macro names that are available with V8.7 are described in Chapter 31, Defined Macros.

One example of the usefulness of this option concerns the rmail(8) program. Suppose a machine is used for networked mail. Ordinarily, the r macro is given the value "smtp" to signify that mail is received over the network. But for UUCP mail the r macro should be given the value "UUCP." One way to effect such a change is to arrange for rmail(8) to invoke sendmail with a command-line argument of

-oMrUUCP

In this command line, the -o switch tells sendmail to define a macro (the M) whose name is r to have the text UUCP as its new value. [42] This new value overrides whatever value r may have been given in the configuration file. The M option should be approached with caution. If you later upgrade your sendmail program and install a new configuration file, you may find that the names of macros aren't what you expect. Previous command-line assumptions about macro names may suddenly break.

[42] Under V8 sendmail the $s and $r macros should be assigned values with -p command-line switch (see Section 36.7.32, -p in Chapter 36). Also note that -oM has been deprecated in favor of the new -M switch.

The M option is safe only in assigning values to the r and s macros. For all other macros it is unsafe and, if specified from the command line, may cause sendmail to relinquish its root privilege. Pre-V8 SunOS sendmail was an exception in that it considered this option safe for all macros. Note that the M option should never be used in the configuration file.


Previous: 34.7 PitfallssendmailNext: 35. Headers
34.7 PitfallsBook Index35. Headers