TUNING

There are a number of configuration parameters you may want to change, depending on the requirements of your site. Most of these are set using an option in the configuration file. For example, the line O Timeout.queuereturn=5d sets option Timeout.queuereturn to the value 5d (five days).

Most of these options have appropriate defaults for most sites. However, sites having very high mail loads may find they need to tune them as appropriate for their mail load. In particular, sites experiencing a large number of small messages, many of which are delivered to many recipients, may find that they need to adjust the parameters dealing with queue priorities.

All versions of sendmail prior to 8.7 had single character option names. As of 8.7, options have long (multi-character names). Although old short names are still accepted, most new options do not have short equivalents.

This section only describes the options you are most likely to want to tweak; read section

Timeouts

All time intervals are set using a scaled syntax. For example, 10m represents ten minutes, whereas 2h30m represents two and a half hours. The full set of scales is:


s seconds
m minutes
h hours
d days
w weeks

Queue interval

The argument to the -q flag specifies how often a sub-daemon will run the queue. This is typically set to between fifteen minutes and one hour. If not set, or set to zero, the queue will not be run automatically. RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes. Should you need to terminate the queue jobs currently active then a SIGTERM to the parent of the process (or processes) will cleanly stop the jobs.

Read timeouts

Timeouts all have option names Timeout.suboption. Most of these control SMTP operations. The recognized suboptions, their default values, and the minimum values allowed by RFC 2821 section 4.5.3.2 (or RFC 1123 section 5.3.2) are:

connect
The time to wait for an SMTP connection to open (the connect(2) system call) [0, unspecified]. If zero, uses the kernel default. In no case can this option extend the timeout longer than the kernel provides, but it can shorten it. This is to get around kernels that provide an absurdly long connection timeout (90 minutes in one case).
iconnect
The same as connect, except it applies only to the initial attempt to connect to a host for a given message [0, unspecified]. The concept is that this should be very short (a few seconds); hosts that are well connected and responsive will thus be serviced immediately. Hosts that are slow will not hold up other deliveries in the initial delivery attempt.
aconnect
[0, unspecified] The overall timeout waiting for all connection for a single delivery attempt to succeed. If 0, no overall limit is applied. This can be used to restrict the total amount of time trying to connect to a long list of host that could accept an e-mail for the recipient. This timeout does not apply to FallbackMXhost, i.e., if the time is exhausted, the FallbackMXhost is tried next.
initial
The wait for the initial 220 greeting message [5m, 5m].
helo
The wait for a reply from a HELO or EHLO command [5m, unspecified]. This may require a host name lookup, so five minutes is probably a reasonable minimum.
mail*
The wait for a reply from a MAIL command [10m, 5m].
rcpt*
The wait for a reply from a RCPT command [1h, 5m]. This should be long because it could be pointing at a list that takes a long time to expand (see below).
datainit*
The wait for a reply from a DATA command [5m, 2m].
datablock*
The wait for reading a data block (that is, the body of the message). [1h, 3m]. This should be long because it also applies to programs piping input to sendmail which have no guarantee of promptness.
datafinal*
The wait for a reply from the dot terminating a message. [1h, 10m]. If this is shorter than the time actually needed for the receiver to deliver the message, duplicates will be generated. This is discussed in RFC 1047.
rset
The wait for a reply from a RSET command [5m, unspecified].
quit
The wait for a reply from a QUIT command [2m, unspecified].
misc
The wait for a reply from miscellaneous (but short) commands such as NOOP (no-operation) and VERB (go into verbose mode). [2m, unspecified].
command*
In server SMTP, the time to wait for another command. [1h, 5m].
ident
The timeout waiting for a reply to an IDENT query [5s[15], unspecified].
lhlo
The wait for a reply to an LMTP LHLO command [2m, unspecified].
auth
The timeout for a reply in an SMTP AUTH dialogue [10m, unspecified].
starttls
The timeout for a reply to an SMTP STARTTLS command and the TLS handshake [1h, unspecified].
fileopen
The timeout for opening .forward and :include: files [60s, none].
control
The timeout for a complete control socket transaction to complete [2m, none].
hoststatus
How long status information about a host (e.g., host down) will be cached before it is considered stale [30m, unspecified].
resolver.retrans
The resolver's retransmission time interval (in seconds) [varies]. Sets both Timeout.resolver.retrans.first and Timeout.resolver.retrans.normal.
resolver.retrans.first
The resolver's retransmission time interval (in seconds) for the first attempt to deliver a message [varies].
resolver.retrans.normal
The resolver's retransmission time interval (in seconds) for all resolver lookups except the first delivery attempt [varies].
resolver.retry
The number of times to retransmit a resolver query. Sets both Timeout.resolver.retry.first and Timeout.resolver.retry.normal [varies].
resolver.retry.first
The number of times to retransmit a resolver query for the first attempt to deliver a message [varies].
resolver.retry.normal
The number of times to retransmit a resolver query for all resolver lookups except the first delivery attempt [varies].

For compatibility with old configuration files, if no suboption is specified, all the timeouts marked with (*) are set to the indicated value. All but those marked with () apply to client SMTP.

For example, the lines:

O Timeout.command=25m
O Timeout.datablock=3h
sets the server SMTP command timeout to 25 minutes and the input data block timeout to three hours.

Message timeouts

After sitting in the queue for a few days, an undeliverable message will time out. This is to insure that at least the sender is aware of the inability to send a message. The timeout is typically set to five days. It is sometimes considered convenient to also send a warning message if the message is in the queue longer than a few hours (assuming you normally have good connectivity; if your messages normally took several hours to send you wouldn't want to do this because it wouldn't be an unusual event). These timeouts are set using the Timeout.queuereturn and Timeout.queuewarn options in the configuration file (previously both were set using the T option).

If the message is submitted using the NOTIFY SMTP extension, warning messages will only be sent if NOTIFY=DELAY is specified. The queuereturn and queuewarn timeouts can be further qualified with a tag based on the Precedence: field in the message; they must be one of urgent (indicating a positive non-zero precedence) normal (indicating a zero precedence), or non-urgent (indicating negative precedences). For example, setting Timeout.queuewarn.urgent=1h sets the warning timeout for urgent messages only to one hour. The default if no precedence is indicated is to set the timeout for all precedences. The value "now" can be used for -O Timeout.queuereturn to return entries immediately during a queue run, e.g., to bounce messages independent of their time in the queue.

Since these options are global, and since you cannot know a priori how long another host outside your domain will be down, a five day timeout is recommended. This allows a recipient to fix the problem even if it occurs at the beginning of a long weekend. RFC 1123 section 5.3.1.1 says that this parameter should be ``at least 4-5 days''.

The Timeout.queuewarn value can be piggybacked on the T option by indicating a time after which a warning message should be sent; the two timeouts are separated by a slash. For example, the line

OT5d/4h
causes email to fail after five days, but a warning message will be sent after four hours. This should be large enough that the message will have been tried several times.

Forking During Queue Runs

By setting the ForkEachJob ( Y) option, sendmail will fork before each individual message while running the queue. This option was used with earlier releases to prevent sendmail from consuming large amounts of memory. It should no longer be necessary with sendmail 8.12. If the ForkEachJob option is not set, sendmail will keep track of hosts that are down during a queue run, which can improve performance dramatically.

If the ForkEachJob option is set, sendmail cannot use connection caching.

Queue Priorities

Every message is assigned a priority when it is first instantiated, consisting of the message size (in bytes) offset by the message class (which is determined from the Precedence: header) times the work class factor and the number of recipients times the work recipient factor. The priority is used to order the queue. Higher numbers for the priority mean that the message will be processed later when running the queue.

The message size is included so that large messages are penalized relative to small messages. The message class allows users to send high priority messages by including a Precedence: field in their message; the value of this field is looked up in the P lines of the configuration file. Since the number of recipients affects the amount of load a message presents to the system, this is also included into the priority.

The recipient and class factors can be set in the configuration file using the RecipientFactor ( y) and ClassFactor ( z) options respectively. They default to 30000 (for the recipient factor) and 1800 (for the class factor). The initial priority is:

pri = msgsize - (class times bold ClassFactor) + (nrcpt times bold RecipientFactor)
(Remember, higher values for this parameter actually mean that the job will be treated with lower priority.)

The priority of a job can also be adjusted each time it is processed (that is, each time an attempt is made to deliver it) using the work time factor, set by the RetryFactor ( Z) option. This is added to the priority, so it normally decreases the precedence of the job, on the grounds that jobs that have failed many times will tend to fail again in the future. The RetryFactor option defaults to 90000.

Load Limiting

Sendmail can be asked to queue (but not deliver) mail if the system load average gets too high using the QueueLA ( x) option. When the load average exceeds the value of the QueueLA option, the delivery mode is set to q (queue only) if the QueueFactor ( q) option divided by the difference in the current load average and the QueueLA option plus one is less than the priority of the message -- that is, the message is queued iff:

pri > { bold QueueFactor } over { LA - { bold QueueLA } + 1 }
The QueueFactor option defaults to 600000, so each point of load average is worth 600000 priority points (as described above).

For drastic cases, the RefuseLA ( X) option defines a load average at which sendmail will refuse to accept network connections. Locally generated mail, i.e., mail which is not submitted via SMTP (including incoming UUCP mail), is still accepted. Notice that the MSP submits mail to the MTA via SMTP, and hence mail will be queued in the client queue in such a case. Therefore it is necessary to run the client mail queue periodically.

Delivery Mode

There are a number of delivery modes that sendmail can operate in, set by the DeliveryMode ( d) configuration option. These modes specify how quickly mail will be delivered. Legal modes are:


i deliver interactively (synchronously)
b deliver in background (asynchronously)
q queue only (don't deliver)
d defer delivery attempts (don't deliver)
There are tradeoffs. Mode i gives the sender the quickest feedback, but may slow down some mailers and is hardly ever necessary. Mode b delivers promptly but can cause large numbers of processes if you have a mailer that takes a long time to deliver a message. Mode q minimizes the load on your machine, but means that delivery may be delayed for up to the queue interval. Mode d is identical to mode q except that it also prevents lookups in maps including the -D flag from working during the initial queue phase; it is intended for ``dial on demand'' sites where DNS lookups might cost real money. Some simple error messages (e.g., host unknown during the SMTP protocol) will be delayed using this mode. Mode b is the usual default.

If you run in mode q (queue only), d (defer), or b (deliver in background) sendmail will not expand aliases and follow .forward files upon initial receipt of the mail. This speeds up the response to RCPT commands. Mode i should not be used by the SMTP server.

Log Level

The level of logging can be set for sendmail. The default using a standard configuration table is level 9. The levels are as follows:

0
Minimal logging.
1
Serious system failures and potential security problems.
2
Lost communications (network problems) and protocol failures.
3
Other serious failures, malformed addresses, transient forward/include errors, connection timeouts.
4
Minor failures, out of date alias databases, connection rejections via check_ rulesets.
5
Message collection statistics.
6
Creation of error messages, VRFY and EXPN commands.
7
Delivery failures (host or user unknown, etc.).
8
Successful deliveries and alias database rebuilds.
9
Messages being deferred (due to a host being down, etc.).
10
Database expansion (alias, forward, and userdb lookups) and authentication information.
11
NIS errors and end of job processing.
12
Logs all SMTP connections.
13
Log bad user shells, files with improper permissions, and other questionable situations.
14
Logs refused connections.
15
Log all incoming and outgoing SMTP commands.
20
Logs attempts to run locked queue files. These are not errors, but can be useful to note if your queue appears to be clogged.
30
Lost locks (only if using lockf instead of flock).

Additionally, values above 64 are reserved for extremely verbose debugging output. No normal site would ever set these.

File Modes

The modes used for files depend on what functionality you want and the level of security you require. In many cases sendmail does careful checking of the modes of files and directories to avoid accidental compromise; if you want to make it possible to have group-writable support files you may need to use the DontBlameSendmail option to turn off some of these checks.

To suid or not to suid?

Sendmail is no longer installed set-user-ID to root. sendmail/SECURITY explains how to configure and install sendmail without set-user-ID to root but set-group-ID which is the default configuration starting with 8.12.

The daemon usually runs as root, unless other measures are taken. At the point where sendmail is about to exec(2) a mailer, it checks to see if the userid is zero (root); if so, it resets the userid and groupid to a default (set by the U= equate in the mailer line; if that is not set, the DefaultUser option is used). This can be overridden by setting the S flag to the mailer for mailers that are trusted and must be called as root. However, this will cause mail processing to be accounted (using sa(8)) to root rather than to the user sending the mail.

A middle ground is to set the RunAsUser option. This causes sendmail to become the indicated user as soon as it has done the startup that requires root privileges (primarily, opening the SMTP socket). If you use RunAsUser, the queue directory (normally /var/spool/mqueue) should be owned by that user, and all files and databases (including user .forward files, alias files, :include: files, and external databases) must be readable by that user. Also, since sendmail will not be able to change it's uid, delivery to programs or files will be marked as unsafe, e.g., undeliverable, in .forward, aliases, and :include: files. Administrators can override this by setting the DontBlameSendmail option to the setting NonRootSafeAddr. RunAsUser is probably best suited for firewall configurations that don't have regular user logins.

Turning off security checks

Sendmail is very particular about the modes of files that it reads or writes. For example, by default it will refuse to read most files that are group writable on the grounds that they might have been tampered with by someone other than the owner; it will even refuse to read files in group writable directories.

If you are quite sure that your configuration is safe and you want sendmail to avoid these security checks, you can turn off certain checks using the DontBlameSendmail option. This option takes one or more names that disable checks. In the descriptions that follow, unsafe directory means a directory that is writable by anyone other than the owner. The values are:

Safe
No special handling.
AssumeSafeChown
Assume that the chown system call is restricted to root. Since some versions of UNIX permit regular users to give away their files to other users on some filesystems, sendmail often cannot assume that a given file was created by the owner, particularly when it is in a writable directory. You can set this flag if you know that file giveaway is restricted on your system.
ClassFileInUnsafeDirPath
When reading class files (using the F line in the configuration file), allow files that are in unsafe directories.
DontWarnForwardFileInUnsafeDirPath
Prevent logging of unsafe directory path warnings for non-existent forward files.
ErrorHeaderInUnsafeDirPath
Allow the file named in the ErrorHeader option to be in an unsafe directory.
FileDeliveryToHardLink
Allow delivery to files that are hard links.
FileDeliveryToSymLink
Allow delivery to files that are symbolic links.
ForwardFileInGroupWritableDirPath
Allow .forward files in group writable directories.
ForwardFileInUnsafeDirPath
Allow .forward files in unsafe directories.
ForwardFileInUnsafeDirPathSafe
Allow a .forward file that is in an unsafe directory to include references to program and files.
GroupReadableKeyFile
Accept a group-readable key file for STARTTLS.
GroupReadableSASLDBFile
Accept a group-readable Cyrus SASL password file.
GroupWritableAliasFile
Allow group-writable alias files.
GroupWritableDirPathSafe
Change the definition of unsafe directory to consider group-writable directories to be safe. World-writable directories are always unsafe.
GroupWritableForwardFile
Allow group writable .forward files.
GroupWritableForwardFileSafe
Accept group-writable .forward files as safe for program and file delivery.
GroupWritableIncludeFile
Allow group wriable :include: files.
GroupWritableIncludeFileSafe
Accept group-writable :include: files as safe for program and file delivery.
GroupWritableSASLDBFile
Accept a group-writable Cyrus SASL password file.
HelpFileInUnsafeDirPath
Allow the file named in the HelpFile option to be in an unsafe directory.
IncludeFileInGroupWritableDirPath
Allow :include: files in group writable directories.
IncludeFileInUnsafeDirPath
Allow :include: files in unsafe directories.
IncludeFileInUnsafeDirPathSafe
Allow a :include: file that is in an unsafe directory to include references to program and files.
InsufficientEntropy
Try to use STARTTLS even if the PRNG for OpenSSL is not properly seeded despite the security problems.
LinkedAliasFileInWritableDir
Allow an alias file that is a link in a writable directory.
LinkedClassFileInWritableDir
Allow class files that are links in writable directories.
LinkedForwardFileInWritableDir
Allow .forward files that are links in writable directories.
LinkedIncludeFileInWritableDir
Allow :include: files that are links in writable directories.
LinkedMapInWritableDir
Allow map files that are links in writable directories.
LinkedServiceSwitchFileInWritableDir
Allow the service switch file to be a link even if the directory is writable.
MapInUnsafeDirPath
Allow maps (e.g., hash, btree, and dbm files) in unsafe directories.
NonRootSafeAddr
Do not mark file and program deliveries as unsafe if sendmail is not running with root privileges.
RunProgramInUnsafeDirPath
Run programs that are in writable directories without logging a warning.
RunWritableProgram
Run programs that are group- or world-writable without logging a warning.
TrustStickyBit
Allow group or world writable directories if the sticky bit is set on the directory. Do not set this on systems which do not honor the sticky bit on directories.
WorldWritableAliasFile
Accept world-writable alias files.
WorldWritableForwardfile
Allow world writable .forward files.
WorldWritableIncludefile
Allow world wriable :include: files.
WriteMapToHardLink
Allow writes to maps that are hard links.
WriteMapToSymLink
Allow writes to maps that are symbolic links.
WriteStatsToHardLink
Allow the status file to be a hard link.
WriteStatsToSymLink
Allow the status file to be a symbolic link.

Connection Caching

When processing the queue, sendmail will try to keep the last few open connections open to avoid startup and shutdown costs. This only applies to IPC connections.

When trying to open a connection the cache is first searched. If an open connection is found, it is probed to see if it is still active by sending a RSET command. It is not an error if this fails; instead, the connection is closed and reopened.

Two parameters control the connection cache. The ConnectionCacheSize ( k) option defines the number of simultaneous open connections that will be permitted. If it is set to zero, connections will be closed as quickly as possible. The default is one. This should be set as appropriate for your system size; it will limit the amount of system resources that sendmail will use during queue runs. Never set this higher than 4.

The ConnectionCacheTimeout ( K) option specifies the maximum time that any cached connection will be permitted to idle. When the idle time exceeds this value the connection is closed. This number should be small (under ten minutes) to prevent you from grabbing too many resources from other hosts. The default is five minutes.

Name Server Access

Control of host address lookups is set by the hosts service entry in your service switch file. If you are on a system that has built-in service switch support (e.g., Ultrix, Solaris, or DEC OSF/1) then your system is probably configured properly already. Otherwise, sendmail will consult the file /etc/mail/service.switch, which should be created. Sendmail only uses two entries: hosts and aliases, although system routines may use other services (notably the passwd service for user name lookups by getpwname).

However, some systems (such as SunOS 4.X) will do DNS lookups regardless of the setting of the service switch entry. In particular, the system routine gethostbyname(3) is used to look up host names, and many vendor versions try some combination of DNS, NIS, and file lookup in /etc/hosts without consulting a service switch. Sendmail makes no attempt to work around this problem, and the DNS lookup will be done anyway. If you do not have a nameserver configured at all, such as at a UUCP-only site, sendmail will get a connection refused message when it tries to connect to the name server. If the hosts switch entry has the service dns listed somewhere in the list, sendmail will interpret this to mean a temporary failure and will queue the mail for later processing; otherwise, it ignores the name server data.

The same technique is used to decide whether to do MX lookups. If you want MX support, you must have dns listed as a service in the hosts switch entry.

The ResolverOptions ( I) option allows you to tweak name server options. The command line takes a series of flags as documented in resolver(3) (with the leading RES_ deleted). Each can be preceded by an optional `+' or `-'. For example, the line

O ResolverOptions=+AAONLY -DNSRCH
turns on the AAONLY (accept authoritative answers only) and turns off the DNSRCH (search the domain path) options. Most resolver libraries default DNSRCH, DEFNAMES, and RECURSE flags on and all others off. If NETINET6 is enabled, most libraries default to USE_INET6 as well. You can also include HasWildcardMX to specify that there is a wildcard MX record matching your domain; this turns off MX matching when canonifying names, which can lead to inappropriate canonifications. Use WorkAroundBrokenAAAA when faced with a a broken nameservers that returns SERVFAIL (a temporary failure) on T_AAAA (IPv6) lookups during hostname canonification.

Version level 1 configurations (see the section about Configuration Version Level) turn DNSRCH and DEFNAMES off when doing delivery lookups, but leave them on everywhere else. Version 8 of sendmail ignores them when doing canonification lookups (that is, when using $[ ... $]), and always does the search. If you don't want to do automatic name extension, don't call $[ ... $].

The search rules for $[ ... $] are somewhat different than usual. If the name being looked up has at least one dot, it always tries the unmodified name first. If that fails, it tries the reduced search path, and lastly tries the unmodified name (but only for names without a dot, since names with a dot have already been tried). This allows names such as ``utc.CS'' to match the site in Czechoslovakia rather than the site in your local Computer Science department. It also prefers A and CNAME records over MX records -- that is, if it finds an MX record it makes note of it, but keeps looking. This way, if you have a wildcard MX record matching your domain, it will not assume that all names match.

To completely turn off all name server access on systems without service switch support (such as SunOS 4.X) you will have to recompile with -DNAMED_BIND=0 and remove -lresolv from the list of libraries to be searched when linking.

Moving the Per-User Forward Files

Some sites mount each user's home directory from a local disk on their workstation, so that local access is fast. However, the result is that .forward file lookups from a central mail server are slow. In some cases, mail can even be delivered on machines inappropriately because of a file server being down. The performance can be especially bad if you run the automounter.

The ForwardPath ( J) option allows you to set a path of forward files. For example, the config file line

O ForwardPath=/var/forward/$u:$z/.forward.$w
would first look for a file with the same name as the user's login in /var/forward; if that is not found (or is inaccessible) the file ``.forward. machinename'' in the user's home directory is searched. A truly perverse site could also search by sender by using $r, $s, or $f.

If you create a directory such as /var/forward, it should be mode 1777 (that is, the sticky bit should be set). Users should create the files mode 644. Note that you must use the ForwardFileInUnsafeDirPath and ForwardFileInUnsafeDirPathSafe flags with the DontBlameSendmail option to allow forward files in a world writable directory. This might also be used as a denial of service attack (users could create forward files for other users); a better approach might be to create /var/forward mode 755 and create empty files for each user, owned by that user, mode 644. If you do this, you don't have to set the DontBlameSendmail options indicated above.

Free Space

On systems that have one of the system calls in the statfs(2) family (including statvfs and ustat), you can specify a minimum number of free blocks on the queue filesystem using the MinFreeBlocks ( b) option. If there are fewer than the indicated number of blocks free on the filesystem on which the queue is mounted the SMTP server will reject mail with the 452 error code. This invites the SMTP client to try again later.

Beware of setting this option too high; it can cause rejection of email when that mail would be processed without difficulty.

Maximum Message Size

To avoid overflowing your system with a large message, the MaxMessageSize option can be set to set an absolute limit on the size of any one message. This will be advertised in the ESMTP dialogue and checked during message collection.

Privacy Flags

The PrivacyOptions ( p) option allows you to set certain ``privacy'' flags. Actually, many of them don't give you any extra privacy, rather just insisting that client SMTP servers use the HELO command before using certain commands or adding extra headers to indicate possible spoof attempts.

The option takes a series of flag names; the final privacy is the inclusive or of those flags. For example:

O PrivacyOptions=needmailhelo, noexpn
insists that the HELO or EHLO command be used before a MAIL command is accepted and disables the EXPN command.

The flags are detailed in section

Send to Me Too

Beginning with version 8.10, sendmail includes by default the (envelope) sender in any list expansions. For example, if matt sends to a list that contains matt as one of the members he will get a copy of the message. If the MeToo option is set to FALSE (in the configuration file or via the command line), this behavior is changed, i.e., the (envelope) sender is excluded in list expansions.


[Contents] [Previous] [Next]
This document was translated by troff2html v0.21 on October 10, 2001.


Claus Aßmann Please send comments to: <ca at sendmail.org>