Table of Contents for

sendmail, 4th Edition

Prior to V8.7, option names that are declared on the command line could be only a single character long:

-oXargument     ← prior to V8.7

The -o switch (lowercase o) is immediately followed (with no intervening space) by the one-letter name of the option (here, X). The one-letter names are case-sensitive (x is not the same as X). Depending on the option selected, an argument might be required. If that argument is present, it must immediately follow the option name with no intervening space. Only one option can be specified for each -o switch.

Under V8 sendmail, a space can appear between the -o and the X, but no space can exist between the X and its argument. This is because V8 sendmail uses getopt(3) to parse its command line.

If an unknown single-character option name is used, sendmail will print and log the following error:

readcf: unknown option name 0x31

Here, the unknown character was a 1, printed in hexadecimal notation.

Beginning with V8.7, option names can be single-character or multicharacter. Single-character options are declared with the -o (lowercase) switch as described earlier. Multicharacter options, which are preferred, are declared with a -O (uppercase) switch:

-OLongName=argument       ← beginning with V8.7
 ↑
 uppercase

Space can optionally exist between the -O and the LongName. In the command line, space cannot exist between the LongName, the =, and the argument unless they are quoted:

-O "LongName = argument"

Only one option can be specified for each -O switch.

The sendmail program ignores case when it considers multicharacter names. Therefore, the following three command lines have the same effect, and none produces an error:

-OQueueDirectory=/var/spool/mqueue
-Oqueuedirectory=/var/spool/mqueue
-OQuEuEdIrEcToRy=/var/spool/mqueue

Multicharacter names are beneficial because they allow option names to have mnemonic recognition. For example, the multicharacter name ForwardPath, which lists the default path for ~/.forward files, is much more recognizable than the single-character name J.

If an unknown multicharacter option name is specified, the following is logged and printed:

readcf: unknown option name bad name here

% /usr/sbin/sendmail -OQueueDirectory=/var/spool/mqueue

% /usr/sbin/sendmail -OQueueDir=/var/spool/mqueue
Option QueueDir used as abbreviation for QueueDirectory

% /usr/sbin/sendmail -OQueue=/var/spool/mqueue
readcf: ambiguous option name Queue (matches QueueFactor and QueueDirectory)

% /usr/sbin/sendmail -OQueDirectory=/var/spool/mqueue
readcf: unknown option name QueDirectory

Some options are intended for use only on the command line and make little or no sense when used in the configuration file. Options that are inappropriate in the configuration file are shown in Table 24-1.

Security considerations normally require that sendmail give up any special privileges for most command-line options specified by the ordinary user. But the ordinary user can specify a few options that allow sendmail to keep its special privilege. Those options are called “safe” and are shown in Table 24-2.

For example, the AliasFile option (location of the aliases file) is unsafe (and is not in Table 24-2). If you were to send mail by specifying a new location with the AliasFile option, sendmail would change its identity from root to an ordinary user (you), thus preventing sendmail from being able to queue its mail:

/var/spool/mqueue: Permission denied

Note that prior to V8.8.4, the DontInitGroups and TryNullMXList options were wrongly set to safe. This is yet another reason to always upgrade to the latest version of sendmail.

The old form for an option command in the sendmail.cf file is:

OXargument      ←  prior to V8.7

Like all configuration commands, the uppercase letter O must begin the line. It is immediately followed (with no intervening space) by another single letter, which selects a specific option. Uppercase letters are distinct from lowercase for single-character option names (that is, X is different from x). Depending on the option selected, an argument might be required. There must be no intervening space between the single-character option name and its argument.

Single-character option names should be considered deprecated in favor of the more modern multicharacter option names.

Beginning with V8.7, option names can be single-character or multicharacter. A space is used to differentiate between single-character and multicharacter (long) names:

O LongName=argument       ←  beginning with V8.7
 ↑
 a space (not a tab)

Whenever the O configuration command is followed by a space (not a tab), everything following that space is taken as the declaration of a multicharacter option. Unlike single-letter option names, multicharacter names are interpreted by sendmail without regard to case. Therefore, the following three examples all produce the same effect:

O QueueDirectory=/var/spool/mqueue
O queuedirectory=/var/spool/mqueue
O QuEuEdIrEcToRy=/var/spool/mqueue

Optional space (not tab) characters can surround the = character:

O QueueDirectory = /var/spool/mqueue
                ↑ ↑
               spaces, not tabs

Multicharacter names in the configuration file ought not be abbreviated or expressed in shorthand:

O QueueDirectory=/var/spool/mqueue     ← good
O QueueDir=/var/spool/mqueue          ← bad, but allowed

Failure to use the full multicharacter name will cause sendmail to print spurious warnings every time it is run. The possible warnings are listed in Multicharacter name shorthand on page 950.

sendmail knows the location of only its configuration file.^[361] Options in the configuration file tell sendmail where all other files and directories are located. The options that specify file locations are summarized in Table 24-6. All file location options are of type string.

File and directory locations should be expressed as full pathnames. Use of relative names will cause the location to become relative to the queue directory or, for some options, cause the name to be interpreted as something other than a file or directory.

Several options combine to determine your site’s policy for managing the sendmail queue (see Chapter 11 on page 394). Among them is one that specifies the location of the queue directory and another that sets the permissions given to files in that directory. The list of many options that affect the queue is shown in Table 24-7.

In addition to knowing the location of the aliases file, some options determine how that file and its associated database files will be used. For example, there is an option that tells sendmail to check the right side of the aliases for validity. The various aliases-related options are shown in Table 24-8.

Several options control the sendmail program’s behavior under high-machine-load conditions. They are intended to reduce the impact of sendmail on machines that provide other services and to help protect sendmail from overburdening a machine. The list of options that determine and help to prevent high-load conditions is shown in Table 24-9.

Connection caching improves the performance of SMTP-transported mail. In processing the queue or delivering to a long list of recipients, keeping a few SMTP connections open (just in case another message is for one of those same sites) will improve the speed of transfers. Caching is of greatest benefit on busy mail hub machines but can benefit any machine that sends a great deal of network mail. Table 24-10 lists the options that determine how connections will be cached.

Note that beginning with V8.13, the ConnectionCacheSize and ConnectionCacheTimeout options now also affect delivery agents that use P=[LPC] for delivery.

The sendmail program offers a few options that will help in locating and solving some mail delivery problems. Table 24-11 lists the available options.

Other means to solve problems are described in Chapter 15 on page 530, which discusses the -d debugging command-line switch, and in Chapter 14 (specifically Log Transactions with -X on page 512), which covers the -X traffic-logging command-line switch.

The sendmail program supports a vast array of options, each of which is described at the end of this chapter. For now, study each one well enough to get a basic feeling for what it does. Then, as you gain experience with sendmail, you’ll know where to look for the particular option that will meet your needs.

Define the aliases file location All versions

The AliasFile option must be declared for sendmail to do aliasing. If you omit this option, sendmail might 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.^[362] For mc configurations, an appropriate default will be defined based on your operating system.

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

Can't open /et/mail/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 option are as follows:

O AliasFile=location              ← configuration file (V8.7 and later)
-OAliasFile=location              ← command line (V8.7 and later)
define(`ALIAS_FILE',`location')   ← mc configuration (V8.7 and later)
OAlocation                        ← configuration file (deprecated)
-oAlocation                       ← command line (deprecated)

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) might cease to work properly.

Note that with the mc technique the only way to eliminate the default alias file declaration is to undefine ALIAS_FILE like this:

undefine(`ALIAS_FILE')

If you need to turn off all aliasing, you must instead turn off alias support at the delivery-agent flag level by removing the F=A flag (F=A on page 767) from all local delivery agents, as, for example:

MODIFY_MAILER_FLAGS(`LOCAL', `-A')
MODIFY_MAILER_FLAGS(`CYRUS', `-A')
MODIFY_MAILER_FLAGS(`CYRUSV2', `-A')

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

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 (MAX... on page 120) as defined in conf.h (the default is 12). The -bi command-line switch will rebuild all alias databases in the order listed in this AliasFile option. Multiple declaration lines can 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 can similarly be specified on the command line with the -O switch. But be aware that any alias files 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 type of each. The type is the same as the types that are available for the K configuration command (The K Configuration Command on page 882). The type 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 type (the nis) database called mail.aliases. The type can include command-line-style 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 database-map switch causes lookups to include a trailing null byte with each key.^[363]

The types that are reasonable to use with this option are shown in Table 24-12. But note that it is generally better to use the service-switch file to select services because it is less confusing.

If a type is not known (that is, if it is completely unknown, rather than one that is not in this shortened table) and if the -d27 command-line switch (-d27.1 on page 556) is specified, sendmail prints:

Unknown alias class bad type here

If the type 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 bad type can't handle aliases

In both cases, the bad type is the offending map type. Both errors cause the AliasFile option’s alias file declaration to be ignored.

Beginning with V8.7 sendmail, the declaration and use of alias files is further complicated^[364] by the introduction of switched-services files (ServiceSwitchFile on page 1088). 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 were 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 can set up a V8.7 switched-service file that can be used for aliases if you wish.

The AliasFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

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 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 two seconds for that entry to appear, then checks again. If the entry is still unavailable, the wait is doubled (up to a maximum wait of 60 seconds). The total time waited (after all the sleeps without success) is the interval specified by this AliasWait 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, 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.

The forms of the AliasWait option are as follows:

O AliasWait=delay                ← configuration file (V8.7 and later)
-OAliasWait=delay                ← command line (V8.7 and later)
define(`confALIAS_WAIT',delay)   ← mc configuration (V8.7 and later)
Oadelay                          ← configuration file (deprecated)
-oadelay                         ← command line (deprecated)

The delay argument is of type time and, if omitted, defaults to five minutes. If the entire AliasWait 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 mc configuration, the default for confALIAS_WAIT is 10 minutes.

The AliasWait option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Allow HELO or EHLO sans host V8.8 and later

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, 13 Dec 2002 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:^[365]

501 5.0.0 HELO requires domain address
501 5.0.0 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 (PICKY_HELO_CHECK on page 133). Also note that the specified hostname must appear to be a correctly formed hostname. If it is not, the following is printed:

501 5.0.0 Invalid domain name

If you favor forcing other sites to obey the RFCs, don’t enable this option. But note that you might 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                         ← configuration file (V8.8 and
later)
-OAllowBogusHELO=bool                         ← command line (V8.8 and later)
define(`confALLOW_BOGUS_HELO', `bool')        ← mc configuration (V8.8 and later)

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).

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

Limit max encryption strength for SASL V8.12 and later

When a client’s site connects to the server, the server can offer authentication by presenting the AUTH keyword, followed by authentication mechanisms supported:

250-host.domain Hello some.domain, pleased to meet you
250-ENHANCEDSTATUSCODES
250-PIPELINING
250-8BITMIME
250-SIZE
250-DSN
250-ETRN
250-AUTH DIGEST-MD5 CRAM-MD5 KERBEROS-V4             ← note this line
250-DELIVERBY
250 HELP

If the connecting site wishes to authenticate itself, it replies with an AUTH command indicating the desired mechanism:

AUTH CRAM-MD5
← authentication challenge here
← authentication reply here
235 Authentication successful.           ← server replies

This interaction automatically establishes an authenticated stream using the CRAM-MD5 method.

If you wish to turn off additional encryption in SASL when STARTTLS is already encrypting the communication, you do so by defining this AuthMaxBits option. When set, this option limits the maximum encryption strength for the security layer in SMTP AUTH. When not set (the default), encryption strength is essentially unlimited. The AuthMaxBits option is used like this:

O AuthMaxBits=limit                     ← configuration file (V8.12 and later)
-OAuthMaxBits=limit                     ← command line (V8.12 and later)
define(`confAUTH_MAX_BITS', `limit')    ← mc configuration (V8.12 and later)

Here, limit is the maximum number of bits in the key length. The existing encryption strength is taken into account when choosing an algorithm for the security layer. For example, if STARTTLS is used and the symmetric cipher is DES, the key length (in bits) will be 168. By setting this option to:

define(`confAUTH_MAX_BITS', `168')

any encryption in SASL will be disabled.

The AuthMaxBits option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

The AUTH mechanisms V8.10 and later

The AuthMechanisms option is used to declare the types of authentication you want to allow to be passed in the AUTH ESMTP extension (see RFC2554). You use this option by listing the mechanisms you wish to set as its value.

O AuthMechanisms=mechanisms                  ← configuration file (V8.10 and
later)
-OAuthMechanisms=mechanisms                  ← configuration file (V8.10 and
later)
define(`confAUTH_MECHANISMS', `mechanisms')  ← mc configuration (V8.10 and later)

When there is more than one preferred mechanism, each is separated from the others by space characters. For example:

define(`confAUTH_MECHANISMS', `CRAM-MD5 KERBEROS_V4')

Before the actual AUTH is generated, sendmail produces an intersection of the mechanisms you want and those supported by the SASL software you have installed. Only those that are specified by this option and those supported by your software are listed by the issued AUTH command:

250-AUTH CRAM-MD5

Here, you wanted both CRAM-MD5 and KERBEROS_V4 offered as mechanisms. But if the SASL software installed on your machine, for example, supports only CRAM-MD5 and DIGEST-MD5, the common or intersecting mechanism will be CRAM-MD5, so that is all that will be advertised.

When more than one mechanism is listed, the other side will negotiate them one at a time, until one succeeds. For example, the interplay of the offered mechanisms and the counters by the other side might look like this:

220 other.domain ESMTP Sendmail 8.12.7/8.12.7; Sat, 18 Dec 1999 09:17:09 −0800 (PST)
EHLO host.your.domain
250-host.your.domain Hello you@host.your.domain [122.45.67.8], pleased to meet you
250-ENHANCEDSTATUSCODES
250-8BITMIME
250-SIZE
250-DSN
250-ONEX
250-ETRN
250-AUTH CRAM-MD5 KERBEROS_V4                   ← we support
250-XUSR
250 HELP
AUTH CRAM-MD5                                   ← they first try this
334← authentication challenge here← authentication reply here
504 5.7.0 Authentication failure                ← that fails
AUTH KERBEROS_V4                                ← so they try this
334← authentication challenge here← authentication reply here
235 2.0.0 OK Authenticated                      ← which succeeds

The following mechanisms are the maximum set of those recognized by the cyrus-sasl-1.5.16 distribution. Not all will be compiled in, so not all will be supported.

The complete list of current mechanisms, and the RFC that describes each, can be found at http://www.iana.org/assignments/sasl-mechanisms/ and http://www.sendmail.org/~ca/email/mel/sasl_info.html.

The AuthMechanisms option is available only if sendmail is compiled with SASL (SASL on page 137) defined.

The AuthMechanisms option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Tune authentication parameters V8.10 and later

AuthOptions provides a list of general tuning parameters that affect authentication. It is declared like this:

O AuthOptions=string                  ← configuration file (V8.10 and later)
-OAuthOptions=string                  ← configuration file (V8.10 and later)
define(`confAUTH_OPTIONS', `string')  ← mc configuration (V8.10 and later)

The argument, of type string, is a list of characters selected from those shown in Table 24-13, where each character sets a particular tuning parameter. If more than one character is listed, each character must be separated from the next by either a comma or a space.

If string is missing, sendmail will issue the following error and skip this option declaration:

Warning: Option: AuthOptions requires parameter(s)

If any letter is specified other than those listed in the table—for example, H—sendmail issues the following warning and skips this option declaration:

Warning: Option: AuthOptions unknown parameter 'H'

Note that macros cannot be used to define the list of characters.

The AuthOptions option is available only if sendmail is compiled with SASL (SASL on page 137) defined as true. For examples of how to use AuthOptions, see The AuthOptions option on page 192.

The AuthOptions option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Cyrus SASL authentication realm V8.13 and later

Prior to V8.13, the authentication realm passed to the Cyrus SASL library was always the value of the $j macro. Beginning with V8.13, the AuthRealm option allows you to specify a different authentication realm:

O AuthRealm=realm                    ← configuration file (V8.13 and later)
-OAuthRealm=realm                    ← command line (V8.13 and later)
define(`confAUTH_REALM',`realm')     ← mc configuration (V8.13 and later)

Here, realm is of type string and specifies the authentication realm to use in place of the $j macro’s value. If realm is missing, the effect is the same as if the entire option was omitted, that is, the value of $j is used.

The AuthRealm option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Auto-rebuild the aliases database Deprecated

Beginning with V8.10 sendmail, it was discovered that auto-rebuilding the aliases database held the potential for a denial-of-service attack. If a user could kill sendmail during a rebuild, the aliases database could be left in an incomplete state, resulting in possible lost and misdirected email. As a consequence, this AutoRebuildAliases option is deprecated. Although it is present in V8.10 and V8.11, you should not use it. This option has been eliminated since V8.12.

Prior to V8.10 sendmail, the need to auto-rebuild the aliases database was determined by comparing the modification time of the aliases source file, as defined by the AliasFile option (AliasFile on page 970), to the modification time of the corresponding aliases.pag and aliases.dir, or aliases.db, database files. If the source file was newer and if this AutoRebuildAliases option was set, sendmail attempted to rebuild the aliases database. If this option was not set, sendmail printed the following warning and used the information in the old database:

Warning: alias database fname out of date

Here, fname is the name of the source file. If you wish to set this to AutoRebuildAliases, despite the risk, be sure that the AliasWait option (AliasWait on page 973) is also declared and given a nonzero time argument. (Note that file locking, to prevent simultaneous rebuilds, is described under the AliasWait option.)

The forms of this AutoRebuildAliases option are as follows:

O AutoRebuildAliases=bool         ← configuration file (V8.7 to V8.11)
-OAutoRebuildAliases=bool         ← command line (V8.7 to V8.11)
define(`confAUTO_REBUILD',bool)   ← mc configuration (V8.7 to V8.11)
ODbool                            ← configuration file (V8.11 and earlier)
-oDbool                           ← command line (V8.11 and earlier)

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

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

The AutoRebuildAliases option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Slow excess bad RCPT To: commands V8.12 and later

One method used to gather addresses for spamming is to misuse the RCPT To: command. To illustrate, consider the following fragment of an SMTP session:

RCPT To:<aa@your.domain>
550 5.1.1 <aa@your.domain>... User unknown
RCPT To:<ab@your.domain>
550 5.1.1 <ab@your.domain>... User unknown
RCPT To:<ac@your.domain>
550 5.1.1 <ac@your.domain>... User unknown
RCPT To:<ad@your.domain>
550 5.1.1 <ad@your.domain>... User unknown
RCPT To:<ae@your.domain>
250 2.1.0 <ae@your.domain>... Recipient ok
RCPT To:<af@your.domain>
550 5.1.1 <af@your.domain>... User unknown

Here, some other site has connected to your sendmail and started sending bad RCPT To: commands for a series of possible usernames. These are alphabetical, but other such abuses might be based on lists of common names. Whenever sendmail replies with a 250, the other site knows that address is good, and adds it to its list of spam addresses.

With V8.12 and later sendmail, it is possible to impose a penalty on sites that send too many bad RCPT To: commands. You do that by defining the BadRcptThrottle, like this:

O BadRcptThrottle=num                   ← configuration file (V8.12 and later)
-OBadRcptThrottle=num                   ← command line (V8.12 and later)
define(`confBAD_RCPT_THROTTLE',`num')   ← mc configuration (V8.12 and later

Here, num is a textual representation of a positive integer. If num is negative, non-numeric, or zero (the default), bad RCPT To: commands are accepted without penalty. If num is positive, only that number of bad RCPT To: commands are allowed in a single SMTP session before a penalty is imposed.

The penalty begins by logging the following warning:

other site: Possible SMTP RCPT flood, throttling.

Thereafter, every RCPT To: command will be received by the local sendmail, which will sleep for one second before replying. The choice of one second is hardcoded in sendmail and cannot be changed.

The BadRcptThrottle option can be used in combination with the MaxRecipientsPerMessage option (MaxRecipientsPerMessage on page 1050) to further limit the number of recipients per message.

The BadRcptThrottle option is safe. Even if it is specified from the command line, sendmail retains its special privileges.

Set unquoted space replacement character All versions

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

John Q Public@wash.dc.gov        ← decidedly not kosher

is viewed by some MUA programs as being composed of three separate addresses: John, Q, and Public@wash.dc.gov. 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\ Public@wash.dc.gov        ← escaped

The BlankSub 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 option as one of the following:

O BlankSub=.
O BlankSub=_

Feeding the address:

John Q Public@wash.dc.gov

through sendmail with the option BlankSub set to a dot yields:

John.Q.Public@wash.dc.gov

The forms of the BlankSub option are as follows:

O BlankSub=char                ← configuration file (V8.7 and later)
-OBlankSub=char                ← command line (V8.7 and later)
define(`confBLANK_SUB',char)   ← mc configuration (V8.7 and later)
OBchar                         ← configuration file (deprecated)
-oBchar                        ← command line (deprecated)

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). The default for the mc technique is the dot (.) character.

Note that old-style addresses are delimited from each other with spaces rather than commas. Such addresses can 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 option (OldStyleHeaders on page 1061).

Also note that this BlankSub option can also be used when tokenized addresses are reassembled (see Pasting Addresses Back Together on page 656).

The BlankSub option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

File containing certificate authority certs V8.11 and later

STARTTLS and stream encryption are discussed in detail in STARTTLS on page 202. Among the items you must provide is a file that contains the certificate of the authority that signed your local server (ServerCertFile on page 1087) and client (ClientCertFile on page 984) certificates. This certificate of authority (CA) contains information (the distinguished name, or DN) that is sent to a connecting or connected-to site. The location of the CA certificate file is specified with this CACertFile option, using a declaration that looks like this:

O CACertFile=path               ← configuration file (V8.11 and later)
-OCACertFile=path               ← command line (V8.11 and later)
define(`confCACERT',`path')     ← mc configuration (V8.11 and later

Here, path is a full path specification of the file containing the CA certificate. The path can contain sendmail macros, and if so, those macros will be expanded (their values used) when the configuration file, or command line, is read:

define(`confCACERT', `${MyCERTPath}/CAcert.pem')

The path must be a full pathname (must begin with a slash) and must also live in a directory that is safe (every component of which is writable only by root or the trusted user specified in the TrustedUser option) and must itself be safe (owned by and writable only by root or the trusted user specified in the TrustedUser option; see TrustedUser on page 1112). If it is not, it will be rejected and the following error logged:

STARTTLS=server: file path unsafe: reason
STARTTLS=client: file path unsafe: reason

But even if all goes well this far, there is still a chance that the SSL software will reject the certificate, and sendmail will log the following:

STARTTLS=server, error: load verify locs dir,  path  failed: num
STARTTLS=client, error: load verify locs dir,  path  failed: num

Here, dir is the directory specified by the CACertPath option (CACertPath on page 982) and path is the file specified by this option. The num is the error number returned by the ssl(8) software.

The CACertFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Directory with certificate authority certs V8.11 and later

STARTTLS and stream encryption are discussed in detail in STARTTLS on page 202. Among the items you must provide is a directory that contains the certificate of the authority for the server (ServerCertFile on page 1087) and client (ClientCertFile on page 984) as well as other certificates of authority you wish to trust. This directory contains both the certificates of authority and hashes of those certificates (more about this soon). The location of the CA certificate directory is specified with this CACertPath option, with declarations that look like this:

O CACertPath=dir                   ← configuration file (V8.12 and later)
-OCACertPath=dir                   ← command line (V8.12 and later)
define(`confCACERT_PATH',`dir')    ← mc configuration (V8.12 and later

Here, dir is a full path specification of the directory containing the CA certificate files and their hashes. The dir can contain sendmail macros, and if so, those macros will be expanded (their values used) when the configuration file, or command line, is read:

define(`confCACERT_PATH', `${MyCERTPath}')

The dir must be a full pathname (must begin with a slash), or the directory will be rejected and the following error logged:

STARTTLS=server: file dir unsafe: reason
STARTTLS=client: file dir unsafe: reason

Here, dir is the directory separately specified by the CACertPath option (CACertPath on page 982) and path is the file specified by this option. The num is the error number returned by the ssl(8) software.

The dir must contain the hashes of each certificate of authority, where each hash is either a file, or a link to the certificate. Symbolic links can be generated with a command such as the following:^[366]

% ln -s cert_file `openssl x509 -noout -hash <    cert_file`.0

The CACertFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Check righthand side of aliases V8.1 and later

Ordinarily, when sendmail rebuilds an aliases database (as defined by the AliasFile option, AliasFile on page 970), 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 (F=A on page 767). It is possible to also have addresses to the right of the colon checked for validity by setting the CheckAliases option to true.

The forms of the CheckAliases option are as follows:

O CheckAliases=bool                ← configuration file (V8.7 and later)
-OCheckAliases=bool                ← command line (V8.7 and later)
define(`confCHECK_ALIASES',True)   ← mc configuration (V8.7 and later)
Onbool                             ← configuration file (deprecated)
-onbool                            ← command line (deprecated)
-on                                ← commandline shorthand (V8.7 and later)

The bool is of type Boolean. If it is absent, the option defaults to true (do check the RHS of aliases). If the entire option declaration is missing, the default is false (don’t check the RHS of aliases). The default for the mc 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 the canonify rule set 3 and then the parse rule set 0 to select a delivery agent. Processing merely needs successfully to select any non-#error delivery agent (see error on page 720). 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 option is further described in Check the Right Side of Aliases on page 479.

The CheckAliases option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Checkpoint the queue V8.1 and later

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 FastSplit option (FastSplit on page 1032) and this CheckpointInterval option can limit that duplication. The CheckpointInterval option tells sendmail to rewrite (checkpoint) its qf file (which contains the list of recipients; see The Queue Control File: qf on page 399) 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 option are as follows:

O CheckpointInterval=num                ← configuration file (V8.7 and later)
-OCheckpointInterval=num                ← command line (V8.7 and later)
define(`confCHECKPOINT_INTERVAL',`num') ← mc configuration (V8.7 and later)
OCnum                                   ← configuration file (deprecated)
-oCnum                                  ← command line (deprecated)

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 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 option is safe. Even if it is specified from the command line, sendmail retains its special privileges. Prior to V8.13, the CheckpointInterval option could have its value raised by anyone using the command line. But beginning with V8.13, only the trusted user, as defined by the TrustedUser option (TrustedUser on page 1112) may raise this value on the command line.

Multiplier for priority increments All versions

This ClassFactor option specifies a multiplying weight (factor) for a message’s precedence when determining a message’s priority. This option interacts with the RecipientFactor option (RecipientFactor on page 1077) and both options are described under that latter option.

The forms of the ClassFactor option are as follows:

O ClassFactor=factor                     ← configuration file (V8.7 and later)
-OClassFactor=factor                     ← command line (V8.7 and later)
define(`confWORK_CLASS_FACTOR',factor)   ← mc configuration (V8.7 and later)
Ozfactor                                 ← configuration file (deprecated)
-ozfactor                                ← command line (deprecated)

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 mc technique is to omit this option.

The ClassFactor option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

File containing the client’s public certificate V8.11 and later

STARTTLS and stream encryption are discussed in detail in STARTTLS on page 202. Among the items you might need to create, or purchase, to set up stream encryption is a certificate for your client side. A client certificate is used by sendmail when it is acting in the role of a sender (dispatching outbound email). It is contained in a file whose location is set with this ClientCertFile option, using declarations that look like this:

O ClientCertFile=path                ← configuration file (V8.11 and later)
-OClientCertFile=path                ← command line (V8.11 and later)
define(`confCLIENT_CERT',`path')     ← mc configuration (V8.11 and later)

Here, path is a full path specification of the file containing the certificate. The path can contain sendmail macros, and if so, those macros will be expanded (their values used) when the configuration file, or command line, is read:

define(`confSERVER_CERT', `${MyCERTPath}/ClntCert.pem')

The path must be a full pathname (must begin with a slash), or the file will be rejected and the following error logged:

STARTTLS: ClientCertFile missing

The path must also live in a directory that is safe (every component of which is writable only by root or the trusted user specified in the TrustedUser option) and must itself be safe (owned by and writable only by root or the trusted user specified in the TrustedUser option; see TrustedUser on page 1112). If it is not, it will be rejected and the following error logged:

STARTTLS=client: file path unsafe: reason

But even if all goes well this far, there is still a chance that the SSL software will reject the certificate, and sendmail will log the following:

STARTTLS=client, error: SSL_CTX_use_certificate_file(path) failed

The ServerCertFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

File with the client certificate’s private key V8.11 and later

STARTTLS and stream encryption are discussed in detail in STARTTLS on page 202. Among the items you might need to set up is a key file that corresponds to a certificate file. The client key is used by sendmail when it acts in the roll of a sender (dispatching outbound email). The key file is contained in a file whose location is set with this ClientKeyFile option, using declarations that look like this:

O ClientKeyFile=path                ← configuration file (V8.11 and later)
-OClientKeyFile=path                ← command line (V8.11 and later)
define(`confCLIENT_KEY',`path')     ← mc configuration (V8.11 and later)

Here, path is a full path specification of the file containing the key. The path can contain sendmail macros, and if so, those macros will be expanded (their values used) when the configuration file, or command line, is read:

define(`confCLIENT_KEY', `${MyCERTPath}/ClntKey.pem')

The path must be a full pathname (must begin with a slash) and must also live in a directory that is safe (every component of which is writable only by root or the trusted user specified in the TrustedUser option) and must itself be safe (owned by and writable only by root or the trusted user specified in the TrustedUser option; see TrustedUser on page 1112). If it is not, it will be rejected and the following error logged:

STARTTLS=client: file path unsafe: reason

Note that the file must not be group- or world-readable.

But even if all goes well this far, there is still a chance that the SSL software will reject the certificate, and sendmail will log the following:

STARTTLS=client, error: SSL_CTX_use_PrivateKey_file(path=) failed

This error means the key doesn’t belong to the certificate, or that the key was encrypted.

The ClientKeyFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Client port option settings V8.10 and later

The sendmail program can run in two connection modes: as a daemon, accepting connections; or as a client, making connections. Each mode can connect to a port to do its work. The options for the daemon port are set by the DaemonPortOptions option (DaemonPortOptions on page 993). The options for the client are set by this ClientPortOptions option.

This ClientPortOptions option sets the options for the outgoing connection. The form for this option is as follows:

O ClientPortOptions=pair,pair,pair                ← configuration file (V8.10 and
later)
-OClientPortOptions=pair,pair,pair                ← command line (V8.10 and later)
define(`confCLIENT_OPTIONS',``pair,pair,pair'')   ← mc configuration (V8.10 through
V8.11)
CLIENT_OPTIONS(``pair,pair,pair'')                ← mc configuration (V8.12 and
later)

The ClientPortOptions option is followed by a comma-separated list of pairs,^[367] in which each pair is of the form:

key=value

The complete list of key and value pairs is can be found under the DaemonPortOptions option (see DaemonPortOptions on page 993). All of those pairs apply to this option, except the Listen key. The flags set by the ClientPortOptions option are saved in the {client_flags} macro (${client_flags} on page 812) and are thereby made available to rule sets.

As of V8.12, you can have multiple ClientPortOptions option declarations, one per Family key type. That is, for example, one for the family of IPv4 addresses, and another for the family of IPv6 addresses.

The ClientPortOptions option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Allow colons in addresses V8.7 and later

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. 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 such as the following cannot be allowed:

host:george@wash.dc.gov

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

O ColonOkInAddr=bool                  ← configuration file (V8.7 and later)
-OColonOkInAddr=bool                  ← command line (V8.7 and later)
define(`confCOLON_OK_IN_ADDR',bool)   ← mc configuration (V8.7 and later)

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

Note that DECnet-style addresses (Handling Specialty Addresses on page 693) legitimately contain double colons (e.g., host::user). DECnet addresses are correctly recognized regardless of how this ColonOkInAddr option is set.

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

SMTP connection cache size V8.1 and later

Without a connection cache, 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 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 option of V8 sendmail specifies that open connections to other hosts should be maintained, and it specifies the maximum number of those connections. The forms of the ConnectionCacheSize option are as follows:

O ConnectionCacheSize=num           ← configuration file (V8.7 and later)
-OConnectionCacheSize=num           ← command line (V8.7 and later)
define(`confMCI_CACHE_SIZE',num)    ← mc configuration (V8.7 and later)
Oknum                               ← configuration file (V8.6 and later)
-oknum                              ← command line (V8.6 and later)

Optional whitespace can precede 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 the mc technique, the default is 2. A value of 4 is the maximum for most machines that forward mail directly over the Internet. Higher values might 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.

Beginning with V8.13, this option affects delivery agents that receive messages using SMTP over the standard input/output (that is, with P=[LPC]).

When caching is enabled with this ConnectionCacheSize option, the ConnectionCacheTimeout option should also be declared to set the connection timeout. The ConnectionCacheSize option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

SMTP connection cache timeout V8.1 and later

Maintaining a cached connection to another host (ConnectionCacheSize on page 987) 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 (or other MTA) that is either waiting for an SMTP QUIT command 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 option. This option tells sendmail how long to wait for another mail message before closing the connection.

The forms of the ConnectionCacheTimeout option are as follows:

O ConnectionCacheTimeout=wait          ← configuration file (V8.7 and later)
-OConnectionCacheTimeout=wait          ← command line (V8.7 and later)
define(`confMCI_CACHE_TIMEOUT',wait)   ← mc configuration (V8.7 and later)
OKwait                                 ← configuration file (V8.6 and later)
-oKwait                                ← command line (V8.6 and later)

Optional whitespace can precede 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 mc configuration technique) is 300 seconds (5 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.

Beginning with V8.13, this option affects delivery agents that receive messages using SMTP over the standard input/output (that is, with P=[LPC]).

This ConnectionCacheTimeout option has an effect only if the ConnectionCacheSize option (ConnectionCacheSize on page 987) is also declared.

The ConnectionCacheTimeout option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Incoming SMTP connection rate V8.8 and later

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 connection and its message. The primary load-limiting mechanisms are the QueueLA (QueueLA on page 1072), RefuseLA (RefuseLA on page 1078), and DelayLA (DelayLA on page 1002) options. However, these options rely on the system load average, which can generally be sluggish and can lag behind events. This ConnectionRateThrottle option, and similar options, exist to help flatten out the actual load until the load average can catch up. The ConnectionRateThrottle option is used like this:

O ConnectionRateThrottle=num                      ← configuration file (V8.8 and
later)
-OConnectionRateThrottle=num                      ← command line (V8.8 and later)
define(`confCONNECTION_RATE_THROTTLE', `num')     ← mc configuration (V8.8 and
later)

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 mc 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 (MaxDaemonChildren on page 1044) affect incoming connections differently. Also see the DelayLA option (DelayLA on page 1002) as a way to delay incoming messages on high load.

The ConnectionRateThrottle option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Window of time in which to measure connection rates V8.13 and later

Under V8.13, two new sendmail macros, called ${client_rate} (${client_rate} on page 814) and ${total_rate} (${total_rate} on page 847), are available to control the number of simultaneous connections allowed. They are used by the corresponding new FEATURE(ratecontrol) (FEATURE(conncontrol) on page 619) and FEATURE(conncontrol) (FEATURE(ratecontrol) on page 638), which perform the same functions via the access database.

This new ConnectionRateWindowSize option sets the size of the window of time that is used to measure these rates. It is declared like this:

O ConnectionRateWindowSize = secs                 ← configuration file (V8.13 and
later)
-O ConnectionRateWindowSize = secs                ← command line (V8.13 and later)
define(`confCONNECTION_RATE_WINDOW_SIZE', `secs') ← mc configuration (V8.13 and
later)

Here, secs is of type time. If this option is omitted, the default for the window of time is 60 seconds. If this option is defined, but the time units are omitted, the default units are seconds.

We recommend you change the default only if you have not already made connection-limiting entries in your access database. If you make those entries first, and then later change this setting, you will silently change the meaning of those access database entries.

The ConnectionRateWindowSize option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Connect only to one specified host V8.10 and later

Sometimes it is necessary to test sendmail without allowing mail to be delivered or relayed offsite. In the ideal test situation, it is preferable that the recipient and sender addresses are not modified in the process. After all, one needs to be sure that all headers will be correct, and that all necessary rule sets will be exercised.

The ConnectOnlyTo option provides just such a service by allowing all mail to be relayed to a single machine, regardless of how the mail is addressed. It is declared like this:

O ConnectOnlyTo=ipaddr                        ← configuration file (V8.10 and
later)
-OConnectOnlyTo=ipaddr                        ← command line (V8.10 and later)
define(`confCONNECT_ONLY_TO',`ipaddr')        ← mc configuration (V8.10 and later)

Here, ipaddr is the IP addresses of the target machine to which all mail will be delivered. It must be given in the form of a dotted quad unless sendmail was compiled with NETINET6 (NET... on page 126) defined, in which case you can specify an IPv6 address.

The ConnectOnlyTo option can be used when testing, and commented out otherwise. The ConnectOnlyTo option should not be confused with the nullclient or msp features, which send all mail to a hostname that can use MX records, and thus is more versatile and does a superior job of forwarding mail to a dedicated mail server.

An easy way to create a target for the ConnectOnlyTo option’s setting that accepts all SMTP mail, but logs and discards each inbound piece, is to add the following to a new and separate mc configuration file (don’t change your main configuration file):

LOCAL_RULESETS
SLocal_check_rcpt
R$*             $#discard

This setup will cause all inbound SMTP mail to be discarded. Logs will include lines that look (in part) like this:

ruleset=check_rcpt, arg1=<recipient>, relay=host [addr], discard

If you set up a host this way, however, understand that you should probably use a setup that is fully separate from the normal one. That way, user outbound email will still work.

The ConnectOnlyTo option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Path to control socket V8.10 and later

Starting with V8.10, the sendmail daemon can accept a few control and status commands via a Unix-based named socket. This interface is primarily intended for use with the tools provided with the commercial version of sendmail, but it can be equally valuable for use with your own home-grown tools. The ControlSocketName option enables this type of controlling interface. It is declared like this:

O ControlSocketName=path                      ← configuration file (V8.10 and
later)
-OControlSocketName=path                      ← command line (V8.10 and later)
define(`confCONTROL_SOCKET_NAME', path)       ← mc configuration (V8.10 and later)

Here, the argument path, of type string, is the full pathname of the Unix named socket. The file named by path need not exist. If it exists, sendmail will remove it and create a new named socket. As a consequence, you should avoid accidently declaring path with an existing file. The file will be silently removed when sendmail starts.

The path needs to be secure. That is, every component of it should be owned by, and writable only by, root or the trusted user specified in the TrustedUser option (TrustedUser on page 1112). Because this interface can be used to shut down the sendmail daemon, the socket requires extra protection. On some operating systems (such as with Solaris and pre-4.4 BSD kernels), it is not enough to make the socket mode 0600. You should also place it in a directory that is root-owned and of mode 0700. On such operating systems, if you put it in a directory that is world-searchable, anyone on the same machine will be able to shut down the daemon.

If the path specification is one where some component does not exist, sendmail will log the following message and not use a controlling socket:

daemon could not open control socket /vqr/spool/mqueue/.control: No such file or
directory

Here, /vqr was mistyped, when /var is what was meant.

An example of code that shows one way to use the controlling socket is in contrib/smcontrol.pl, a perl(1) script that requires version 5 or higher perl to use. It gathers the name of the control socket from the hardcoded file named /etc/mail/sendmail.cf. To run it, you just invoke it with a single argument:

# cd contrib
# ./smcontrol.pl help
Help for smcontrol:
help            This message.
restart         Restart sendmail.
shutdown        Shut down sendmail.
status          Show sendmail status.
memdump         Dump allocated memory list (for debugging only).
End of HELP info

The contrib/smcontrol.pl program is a simple command-line interface to the controlling socket. It should be considered a prototype for developing your own, more sophisticated, tools. Consider, for example, the usefulness of the status output:

# ./smcontrol.pl status
Daemon Status: (process 13480) Accepting connections

Child Process 13560 Status: SMTP server child for 123.45.67.8
Child Process 13579 Status: SMTP server child for 123.45.67.9
Child Process 13584 Status: console socket child

This shows that the daemon is up, and that two sites are connected to yours for the transmission of mail.

The new control socket command mstat has been added beginning with V8.14. This new command causes sendmail to emit stats in a machine-friendly format:

# ./smcontrol.pl mstat
C:1
M:0
L:0
Q:NOTCONFIGURED:−1
D:0/./772127
P:2914 accepting connections
P:19204 SMTP server child for 12.34.56.78
P:19210 console socket child

The ControlSocketName option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Location of Certificate Revocation file V8.13 and later

Beginning with V8.13, sendmail supports use of the certificate revocation lists available with OpenSSL^[368] version 0.9.7 and above. The new CRLFile option allows you to declare the location and name of a certificate revocation list file.

When an inbound connection is received by sendmail, and when the connecting host requests a secure session by giving the STARTTLS command, the local sendmail (by way of the OpenSSL library) uses the information in CRLFile to determine whether the connecting host’s certificate should be accepted or rejected.

The file specified by the CRLFile option is created using the openssl(1) command. After the file has been created, you need to declare its location like this:

O CRLFile=/path/file                    ← configuration file (V8.13 and later)
-OCRLFile=/path/file                    ← command line (V8.13 and later)
define(`confCRL',`/path/file')          ← mc configuration (V8.13 and later)

Here, /path/file is of type string and specifies the full-path location of the certificate revocation list file. By default, the CRLFile option is not declared. But if the file is declared using this CRLFile option, and does not exist or is unreadable or has bad permissions, all STARTTLS commands are disallowed by sendmail. Note that the /path/file argument may contain sendmail macros, and those macros will be expanded as the configuration file is read.

If your version of OpenSSL is too old, the following warning will print when you try to declare the CRLFile option, and the option will be ignored:

Warning: Option: CRLFile requires at least Open SSL 0.9.7

The file referenced by the CRLFile option is created using the openssl(1) command. For example, if you are using your own CA, the following can be used to create a file named /etc/ssl/crl.pem:^[369]

openssl ca -revoke certificate-file ← first revoke the certificate
openssl ca -gencrl -out crl.pem     ← then create the revocation list

If you need DER format in your revocation list file, you can substitute the following line for the second line in the preceding snippet:

openssl crl -in crl.pem -outform der -out crl.der

Note that these examples are an oversimplification for illustrative purposes only. See the OpenSSL documentation for more details.

The CRLFile option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

Options for the daemon V8.1 and later

The sendmail program can run in two connection modes: as a daemon, accepting connections; or as a client, making connections. Each mode can connect to a port to do its work. The options for the client port are set by the ClientPortOptions option (ClientPortOptions on page 986). The options for the daemon are set by this DaemonPortOptions option.

This DaemonPortOptions option is used to customize the daemon’s SMTP service. The form for this option is as follows:

O DaemonPortOptions=pair,pair,pair                  ← configuration file (V8.7 and
later)
-ODaemonPortOptions=pair,pair,pair                  ← command line (V8.7 and
later)
define(`confDAEMON_OPTIONS',``pair,pair,pair'')     ← mc configuration (V8.7 and
later)
DAEMON_OPTIONS(``pair,pair,pair'')                  ← mc configuration (V8.11 and
later)
OOpair,pair,pair                                    ← configuration file
(deprecated)
-oOpair,pair,pair                                   ← command line (deprecated)

The DaemonPortOptions option is set to a comma-separated list of pairs,^[370] where each pair is of the form:

key=value

As of V8.14.1, all keys are case-sensitive.^[371] That is, Children differs from children. Prior to V8.7, an unknown key was silently ignored. With V8.8 and later, an unknown key is still ignored but now causes the following error to be printed:

DaemonPortOptions unknown parameter "key"

Beginning with V8.10, you can declare multiple DaemonPortOptions options, where each causes the single listening daemon to accept connections over multiple sockets.

The list of all currently defined keys is shown in Table 24-14.

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:

O DaemonPortOptions=P=26,A=our-addr  # Only listen for local mail on nonstandard port
26

The DaemonPortOptions option is not safe. If specified from the command line, it can cause sendmail to relinquish its special privileges.

O DaemonPortOptions=Addr=128.32.204.25     # listen to our IP address only

O DaemonPortOptions=Port=587, Name=MSA, M=E, children=4

554 5.3.5 Unknown delivery mode first character here

O DaemonPortOptions=Family=iso