 |
NOTE |
Refer to sendmail by Bryan Costales with Eric Allman and Neil Rickert for a comprehensive discussion of the Sendmail facility.
This chapter provides a detailed description of Sendmail configuration. It also provides information on the configuration file.
The information in this chapter is taken from the Sendmail Installation and Operation Guide by Eric Allman. You can find this document a www.sendmail.org.
NOTE Refer to sendmail by Bryan Costales with Eric Allman and Neil Rickert for a comprehensive discussion of the Sendmail facility.
Sendmail implements a general-purpose internetwork mail routing facility under the UNIX operating system. It is not tied to a particular transport protocol - its function may be likened to a crossbar switch, relaying messages from one domain into another. In the process, it can do a limited amount of message header editing to put a message into a format that is appropriate for the receiving domain. All of this is done under the control of a configuration file.
Because of the requirements of flexibility for Sendmail, its configuration file can seem somewhat unapproachable. However, there are only a few basic configurations for most sites for which standard configuration files have been supplied. Most other configurations can be built by adjusting existing configuration files incrementally.
Sendmail is based on the following:
RFC822 (Internet Mail Format Protocol)
RFC821 (Simple Mail Transport Protocol)
RFC1123 (Internet Host Requirements)
RFC1425 (SMTP Service Extensions)
However, since Sendmail is designed to work in a wider world, in many cases it can be configured to exceed these protocols. These cases are described in this appendix.
Although you can run Sendmail without monitoring it, it has a number of features that may be used to monitor or adjust the operation under unusual circumstances. These features are described in this appendix.
The system log is supported by the syslogd(8) program. All messages from Sendmail are logged under the LOG_MAIL facility.
Each line in the system log consists of a timestamp, the name of the machine that generated it (for logging from several machines over the local area network), the word sendmail:, and a message. Most messages are a sequence of name=value pairs.
The two most common lines are logged when a message is processed. The first line logs the receipt of a message; there will be exactly one of these for each message. Some fields may be omitted if they do not contain interesting information. The fields are described as follows:
There is also one line logged for each delivery attempt. Therefore, there can be several for each message if delivery is deferred or if there are multiple recipients. The fields are described as follows:
Note that not all fields are present in all messages (for example, the relay is not listed for local delieveries).
If you have syslogd(8) or an equivalent installed, you will be able to do logging. There is a large amount of information that can be logged. The log is arranged as a succession of levels. At the lowest level only extremely strange situations are logged. At the highest level, even the most mundane and uninteresting events are recorded for posterity. As a convention, log levels under ten are considered useful; log levels above 64 are usually for debugging purposes. Levels from 11-64 are reserved for verbose information that some sites might want.
A complete description of the log levels is given in section called "Log Levels."
You can ask Sendmail to log a dump of the open files and the connection cache by sending it a SIGUSR1 signal. The results are logged at LOG_DEBUG priority.
Sometimes a host cannot handle a message immediately. For example, it may be down or overloaded, causing it to refuse connections. The sending host is then expected to save this message in its mail queue and attempt to deliver it later.
The mail queue should be processed transparently. However, you may have to manually intervene at times. For example, if a major host is down for a period of time the queue may become clogged. Although Sendmail ought to recover gracefully when the host comes up, you may find performance unacceptably bad in the meantime.
The contents of the queue can be printed using the mailq command (or by specifying the -bp flag to Sendmail). This command will produce a listing of the queue IDs, the size of the message, the date the message entered the queue, and the sender and recipients.
Sendmail should run the queue automatically at intervals. The algorithm is to read and sort the queue, and then to attempt to process all jobs in order. When it attempts to run the job, Sendmail first checks to see if the job is locked. If so, it ignores the job.
There is no attempt to insure that only one queue processor exists at any time, since there is no guarantee that a job cannot take forever to process(however, Sendmail does include heuristics to try to abort jobs that are taking absurd amounts of time; technically, this violates RFC 821 but is blessed by RFC 1123). The locking algorithm makes it impossible for one job to freeze the queue. However, an uncooperative recipient host or a program recipient that never returns can accumulate many processes in your system. Unfortunately, there is no way to resolve this without violating the protocol.
In some cases, a major host's going down for a couple of days may create a prohibitively large queue. This will cause Sendmail to spend an inordinate amount of time sorting the queue. This situation can be fixed by moving the queue to a temporary place and creating a new queue. The old queue can be run later when the offending host returns to service.
To do this, it is acceptable to move the entire queue directory:
cd /usr/spool
mv mqueue omqueue; mkdir mqueue; chmod 700 mqueue
You should then kill the existing daemon (since it will still be processing in the old queue directory) and create a new daemon.
To run the old mail queue, run the following command:
/usr/lib/sendmail -oQ/usr/spool/omqueue -q
The -oQ flag specifies an alternate queue directory and the -q flag runs every job in the queue. If you want to observe, you can use the -v flag to watch what is going on.
When the queue is finally emptied, you can remove the directory:
rmdir /usr/spool/omqueue
The service switch controls the implementation of certain system services such as host and user name lookup. However, service switches are not completely integrated. For example, despite the fact that the host entry may look in NIS, on DYNIX/ptx systems, this will not happen because the system implementation of gethostbyname(3) does not understand this request.
The alias database exists in two forms. One is a text form, maintained in the file /usr/lib/aliases. The aliases are of the following form:
name: name1, name2, ...
Only local names may be aliased; for example:
eric@prep.ai.MIT.EDU: eric@CS.Berkeley.EDU
will not have the desired effect. Aliases may be continued by starting any continuation line with a space or a tab. Blank lines and lines beginning with a pound, or sharp, sign (#) are comments.
The second form is processed by the dbm(3) (or db(3)) library. This form is in the files /usr/lib/aliases.dir and /usr/lib/aliases.pag. This is the form that Sendmail actually uses to resolve aliases. This technique is used to improve performance.
NOTE dbm restricts a single alias to about 1000 bytes of information. You can get longer aliases by ``chaining''; that is, by making the last name in the alias a dummy name that is a continuation alias. This problem has been noted in the aliases(4) man page.
The control of the search order is set by the service switch. Essentially, the entry
OAswitch:aliases
is always added as the first alias entry. Also, the first alias file name without a class (for example, without nis: on the front) will be used as the name of the file for a files entry in the aliases switch. For example, if the configuration file contains
OA/etc/aliases
and the service switch contains
aliases nis files nisplus
then aliases will be searched in the NIS database, next in /etc/aliases, and finally in the NIS+ database.
You can also use NIS-based alias files. For example, the specification:
OA/etc/aliases
OAnis:mail.aliases@my.nis.domain
will first search the /etc/aliases file and then the map named mail.aliases in my.nis.domain.
CAUTION If you build your own NIS-based alias files, be sure to provide the -l flag to makedbm(8) to map uppercase letters in the keys to lowercase. Otherwise, aliases with uppercase letters in their names will not match incoming addresses.
Additional flags can be added after the colon exactly like a K line, for example:
OAnis:-N mail.aliases@my.nis.domain
will search the appropriate NIS map and always include null bytes in the key.
The DB or DBM version of the database may be rebuilt explicitly by executing the command newaliases. This is equivalent to giving Sendmail the -bi flag:
/usr/lib/sendmail -bi
If the RebuildAliases (old D) option is specified in the configuration, Sendmail will rebuild the alias database automatically if possible when it is out of date. Auto-rebuild can be dangerous on heavily loaded machines with large alias files. If it takes more than the rebuild timeout (option AliasWait, old a, which is normally five minutes) to rebuild the database, several processes may start the rebuild process simultaneously.
If you have specified multiple aliases databases, the -bi flag rebuilds all of the database types that it understands (for example, it can rebuild DBM databases but not NIS databases).
A number of problems can occur with the alias database. They all result from a Sendmail process accessing the DBM version while it is only partially built. This can happen under two circumstances: one process accesses the database while another process is rebuilding it, or the process rebuilding the database dies (through being killed or a system crash) before completing the rebuild.
Sendmail has two techniques to try to relieve these problems. First, it ignores interrupts while rebuilding the database; this prevents someone from aborting the process and leaving a partially rebuilt database. Second, at the end of the rebuild it adds an alias of the form:
@: @
(which is not normally legal). Before Sendmail will access the database, it checks to insure that this entry exists.
If an error occurs on sending to a certain address, for example x, Sendmail will look for an alias of the form owner-x to receive the errors. This is typically useful for a mailing list where the submitter of the list has no control over the maintenance of the list itself; in this case the list maintainer would be the owner of the list. For example:
unix-wizards: eric@ucbarpa, wnj@monet, nosuchuser, sam@matisse owner-unix-wizards: eric@ucbarpa unix-wizards-request: eric@ucbarpa
would cause eric@ucbarpa to get the error that will occur when someone sends to unix-wizards. This error occurs because nosuchuser is included in the list.
List owners also cause the envelope sender address to be modified. The contents of the owner alias are used if they point to a single user. Otherwise the name of the alias itself is used. For this reason, and to obey Internet conventions, the owner- address normally points at the -request address. This convention causes messages to go out with the typical Internet convention of using list-request as the return address.
If you have a version of Sendmail with the user information database compiled in, and you have specified one or more databases using the U option, the databases will be searched for a user:maildrop entry. If found, the mail will be sent to the specified address.
As an alternative to the alias database, any user may put a file with the name .forward in his or her home directory. If this file exists, Sendmail redirects mail for that user to the list of addresses listed in the .forward file. For example, if the home directory for user mckusick has a .forward file with contents:
mckusick@ernie kirk@calder
then any mail arriving for mckusick will be redirected to the specified accounts.
Actually, the configuration file defines a sequence of filenames to check. By default, this is the user's .forward file, but it can be defined to be more general by using the J option. If you change this, you will have to inform your user base of the change.
Several header lines have special interpretations defined by the configuration file. Others have interpretations built into Sendmail that cannot be changed without changing the code. These built-ins are described here.
If errors occur anywhere during processing, this header will cause error messages to go to the listed addresses rather than to the sender. This is intended for mailing lists.
The Errors-To: header was created when UUCP did not understand the distinction between an envelope and a header. This was a hack to provide what should now be passed as the envelope sender address. It should go away. It is only used if the UseErrorsTo option is set.
The Errors-To: header has been officially deprecated and will cease to exist in a future release.
RFC 822 requires at least one recipient field (To:, Cc:, or Bcc: line) in every message. If a message comes in with no recipients listed in the message, Sendmail will adjust the header based on the NoRecipientAction option. Therefore, Sendmail may add an Apparently-To: header line for any recipient it is aware of. This header is not used as a standard recipient line to warn any recipient that the list is not complete.
The Apparently-To: header is non-standard and has been deprecated.
The Precedence: header can be used as a crude control of message priority. It adjusts the sort order in the queue and can be configured to change the message timeout values.
Sendmail supports the IDENT protocol as defined in RFC 1413. Although this enhances identification of the author of an E-mail message by doing a call back to the originating system to include the owner of a particular TCP connection in the audit trail, it is in no sense perfect. A determined forger can easily spoof the IDENT protocol. The following description is excerpted from RFC 1413:
The information returned by this protocol is at most as trustworthy as the host providing it OR the organization operating the host. For example, a PC in an open lab has few if any controls on it to prevent a user from having this protocol return any identifier the user wants. Likewise, if the host has been compromised, the information returned may be completely erroneous and misleading.
The Identification Protocol is not intended as an authorization or access control protocol. At best, it provides some additional auditing information with respect to TCP connections. At worst, it can provide misleading, incorrect, or maliciously false information.
The use of the information returned by this protocol for other than auditing is strongly discouraged. Specifically, using Identification Protocol information to make access control decisions - either as the primary method (i.e., no other checks) or as an adjunct to other methods may result in a weakening of normal host security.
An Identification server may reveal information about users, entities, objects or processes which might normally be considered private. An Identification server provides service which is a rough analog of the CallerID services provided by some phone companies and many of the same privacy considerations and arguments that apply to the CallerID service apply to Identification. If you would not run a finger server because of privacy considerations, you may not want to run this protocol.
In some cases our system may not work properly with IDENT support because of a problem in the TCP/IP implementation. You may see symptoms in which the SMTP connection for some hosts immediately closes. If this is true or if you do not want to use IDENT, you should set the IDENT timeout to zero. This action will disable the IDENT protocol.
The complete list of arguments to Sendmail is described in detail in the section called "Command Line Flags." Some important arguments are described here.
The amount of time between forking a process to run through the queue is defined by the -q flag. If you run in delivery mode i or b this can be relatively large, since it will only be relevant when a host that was down comes back up. If you run in q mode it should be relatively short, since it defines the maximum amount of time that a message may sit in the queue.
RFC 1123 section 5.3.1.1 says that this value should be at least 30 minutes (although that might not make sense if you use "queue-only" mode).
If you allow incoming mail over an IPC connection, you should have a daemon running. This should be set by your /etc/rc file using the -bd flag. The -bd flag and the -q flag may be combined in one call:
/usr/lib/sendmail -bd -q30m
As an alternative approach, you can invoke Sendmail from inetd(8) (use the -bsflag to ask Sendmail to speak SMTP on its standard input and output). This alternative allows you to wrap Sendmail in a TCP wrapper program, but it may be a bit slower since the configuration file has to be reread on every message that comes in. If you do this, you will still need to have Sendmail running to flush the queue:
/usr/lib/sendmail -q30m
In some cases you may find that the queue has gotten clogged. You can force a queue run using the -q flag (with no value). It is entertaining to use the -v flag (verbose) when this is done to watch what happens:
/usr/lib/sendmail -q -v
You can also limit the jobs to those with a particular queue identifier, sender, or recipient using one of the queue modifiers. For example, -qRberkeley restricts the queue run to jobs that have the string "berkeley" somewhere in one of the recipient addresses. Similarly, -qSstring limits the run to particular senders and -qIstring limits it to particular identifiers.
Many debug flags have been built into Sendmail. Each debug flag has a number and a level, where a higher level means, "print out more information". The convention is that levels greater than nine are "absurd"; that is, they print out so much information that you would not normally want to see them except for debugging that particular piece of code.
Debug flags are set using the -d option; the syntax is:
where spaces are for reading ease only. For example:
For a complete list of the available debug flags you will have to look at the code (they are too dynamic to keep this documentation up to date).
Options can be overridden using the -o or the -O command line flag. For example,
/usr/lib/sendmail -oT2m
sets the T (timeout) option to two minutes for this run only. The equivalent line using the long option name is
/usr/lib/sendmail -OQueueTimeout=2m
Some options have security implications. Sendmail allows you to set these but relinquishes its setuid root permissions thereafter.
An alternative configuration file can be specified using the -C flag; for example,
/usr/lib/sendmail -Ctest.cf -oQ/tmp/mqueue
uses the configuration file test.cf instead of the default /usr/lib/sendmail.cf. If the -C flag has no value, it defaults to sendmail.cf in the current directory.
Sendmail gives up its setuid root permissions when you use this flag. Therefore, it is common to use a publicly writable directory (such as /tmp) as the spool directory (QueueDirectory or Q option) while you are testing.
Many SMTP implementations do not fully implement the protocol. For example, some personal computer-based SMTPs do not understand continuation lines in reply codes. These can be very hard to trace. If you suspect such a problem, you can set traffic logging by using the -X flag, as shown in the following example:
/usr/lib/sendmail -X/tmp/traffic -bd
This logs all traffic in the file /tmp/traffic.
This logs a lot of data very quickly and should never be used during normal operations. After starting up such a daemon, force the errant implementation to send a message to your host. All message traffic in and out of Sendmail, including the incoming SMTP traffic, will be logged in this file.
When you build a configuration table, you can do some testing by using the test mode of Sendmail. For example, you can invoke Sendmail as
sendmail -bt -Ctest.cf
which will read the configuration file test.cf and enter test mode. In this mode, you enter lines in the form:
rwset address
where rwset is the rewriting set that you want to use and address is an address to apply the set to. Test mode shows you the steps it takes as it proceeds, finally showing you the address that it ends up with. You may use a comma separated list of rwsets for sequential application of rules to an input. For example,
3,1,21,4 monet:bollard
first applies rule set 3 to the input monet:bollard. Rule set 1 is then applied to the output of rule set 3, followed similarly by rule sets 21 and 4.
If you need more detail, you can also use the -d21 flag to turn on more debugging. For example,
sendmail -bt -d21.99
turns on an incredible amount of information. A single word address is probably going to print out several pages worth of information.
Be warned that internally, Sendmail applies rule set 3 to all of the addresses. In test mode you will have to do that manually. For example, older versions allowd you to use
0 bruce@broadcast.sony.com
This version of Sendmail requires that you use
3,0 bruce@broadcast.song.com
As of version 8.7, some other syntaxes are available in the test mode:
.D x value defines macro x to have the indicated value. This is useful when debugging rules that use the $&x syntax.
.C c value adds the indicated value to class c.
.S rule set dumps the contents of the indicated rule set.
-d debug-spec is equivalent to the command-line flag.
Several configuration parameters can be changed, 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 default appropriately 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 before 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 that you most likely will want to adjust. Read the section entitle "The Configuration File" for more information.
All time intervals are set using a scaled syntax. For example, 10m represents ten minutes, whereas 2h30m represents two-and-a-half hours.
The following list describes the full scale syntax:
The argument to the -q flag specifies how often a subdaemon runs the queue. This is typically set to between fifteen minutes and one hour. RFC 1123 section 5.3.1.1 recommends that this be at least 30 minutes.
Timeouts all have option names Timeout.suboption. The recognized suboptions, their default values, and the minimum values allowed by RFC 1123 section 5.3.2 are as follows:
For compatibility with old configuration files, if no suboption is specified, all of the timeouts marked with * are set to the indicated value.
Many of the RFC 1123 minimum values may be too short. Sendmail was designed to the RFC 822 protocols, which did not specify read timeouts. Hence, Sendmail does not guarantee to reply to messages promptly. In particular, an RCPT command specifying a mailing list will expand and verify the entire list; a large list on a slow system may take more than five minutes. A one-hour timeout is best; since this failure is rare, a long timeout is not onerous and may ultimately help to reduce the network load and duplicated messages. For example, the line
O Timeout.command=25m 0 Timeout.datablock=3h
sets the server SMTP command timeout to 25 minutes and the input data block timeout to three hours.
After sitting in the queue for a few days, a message times out. This insures that at least the sender is aware of the inability to send a message. The timeout is typically set to five days. Sometimes it is convenient to also send a warning message if the message is in the queue longer than a few hours (assuming that you normally have good connectivity; if your messages normally took several hours to send you would not want to do this because it would not be an unusual event). These timeouts are set by using the Timeout.queuereturn and Timeout.queuewarn options in the configuration file (previously both were by using the T option.
Since this option is global, and since you cannot know 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 to 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 value
OT5d/4h
causes E-mail 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.
By setting the ForkEachJob (Y) option, Sendmail forks before each individual message while running the queue. This prevents Sendmail from consuming large amounts of memory, so it may be useful in memory-poor environments. However, if the ForkEachJob option is not set, Sendmail keeps track of hosts that are down during a queue run. This can improve performance dramatically.
If the ForkEachJob option is set, Sendmail cannot use connection caching.
Every message is assigned a priority when it is first instantiated, consisting of the message size (in bytes) offset by the message class 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 factor is also included in 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 3000 (for the recipient factor) and 1800 (for the class factor). The initial priority is:
pri = msgsize - (class x ClassFactor) + (nrcpt x RecipientFactor)
(Remember that 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 Z option defaults to 90000.
Sendmail can be asked to queue (but not deliver) mail if the system load
average gets too high with 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 exceeds the priority of the message - that is, the message is queued if: 
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 (including incoming UUCP mail) is still accepted.
Sendmail can operate in a number of delivery modes. These modes specify how quickly mail will be delivered. The DeliveryMode (d) configuration option specifies the delivery modes. Legal modes are as follows:
There are tradeoffs. Mode i gives the sender the quickest feedback, but it may slow down some mailers and is hardly ever necessary. Mode q puts the minimum load on your machine, but delivery may be delayed. Mode b is probably a good compromise. However, this mode can cause a large number of processes if you have a mailer that takes a long time to deliver a message. Mode d is identical to mode q except that it also prevents all of the early map lookups from working. It is intended for dial on demand sites in which DNS lookups might be monetarily expensive. Some simple error messages (for example, host unknown during the SMTP protocol) will be delayed by 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 cannot be used by the SMTP server.
The level of logging can be set for Sendmail. The default using a standard configuration table is level 9. The levels are as follows:
Additionally, values above 64 are reserved for extremely verbose debugging output. No normal site would ever set these.
Many files can have a number of modes. The modes depend on what functionality you want and the level of security you require.
Sendmail can safely be made to set the user ID (setuid) to root. At the point where it is about to exec(2) a mailer, it checks to see if the userid is zero. If so, it resets the user ID and group ID to a default (set by the u and g options). (This reset can be overridden by setting the S flag to the mailer for mailers that are trusted and must be called as root. However, doing so will cause mail processing to be accounted (using sa) to root rather than to the user sending the mail.)
If you do not make Sendmail set the user ID (setuid) to root, it will still run, but you will lose a lot of functionality and privacy, since you will have to make the queue directory word readable. You can also make Sendmail set the user ID (setuid) to some pseudo-user (for example, create a user called sendmail and make Sendmail set the user ID (setuid) to that), which will fix the privacy problems but not the functionality issues. Also, this is not a guarantee of security. For example, root occasionally sends mail, and the daemon often runs as root.
Berkeley has the alias database (usr/lib/aliases*) mode 644. While this is not as flexible as if the database were mode 666, it avoids potential security problems with a globally writable database.
The database that Sendmail actually used is represented by the two files aliases.dir and aliases.pag (both in /usr/lib) (or aliases.db if you are running with the new Berkeley database primitives). The mode on these files should match the mode on /usr/lib/aliases. If aliases is writable and the DBM files (aliases.dir and aliases.pag) are not, users will be unable to reflect their desired changes through to the actual database. However, if aliases is read-only and the DBM files are writable, a slightly sophisticated user can arrange to steal mail anyway.
If your DBM files are not writable by the world or you do not have auto-rebuild enabled (with the AutoRebuildAliases option), then you must be careful to reconstruct the alias database each time you change the text version with the newaliases utility. If this step is ignored or forgotten, any intended changes will also be ignored or forgotten.
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 NOOP command. It is not an error if this fails. Instead, the connection is closed and reopened.
Two parameters, ConnectionCacheSize (k) and ConnectionCacheTimeout (K), 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 ConnectionCacheSize (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.
The hosts service entry in your service switch file controls the host address lookups. Sendmail will consult the /etc/service.switch file. Sendmail only uses two entries: hosts and aliases.
However, some systems will do DNS lookups regardless of the setting of the service switch entry. In particular, the gethostbyname(3) system routine 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 name server configured at all, 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 indicate a temporary failure and will queue the mail for later processing. Otherwise, it ignores the name server data.
The same techniques can be 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 also allows you to tweak name-server options. The command line takes a series of flags as documented in resolver(3). 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 by default turn DNSRCH, DEFNAMES, and RECURSE flags on and all others off. Note the use of the initial "True" - this is for compatibility with previous versions of Sendmail, but is not otherwise necessary.
Version level 1 configurations 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 do not want to do automatic name extensions, do not call $[ ... $].
The search rules for $[ ... $] are somewhat unusual. If the name (that is, the " ... ") has at least one dot, it always tries the unmodified name first. If that fails, it tries the reduced search path, and last 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 "uts.CS" to match the site 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, you will have to recompile with -DNAMED_BIND=0 and remove -lresolv from the list of libraries to be searched when linking.
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 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 configuration 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 in the user's home directory is searched. A site could also search by sender, 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.
On systems that have the statfs(2) system call, 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 E-mail when that mail would be processed without difficulty.
To avoid overflowing your system with a large message, the MaxMessageSize option can be set to indicate an absolute limit on the size of any one message. This will be advertised in the ESMTP dialogue and checked while messages are collected.
The PrivacyOptions (p) option allows you to set certain "privacy" flags. Actually, many of them do not give you any extra privacy; rather, they just insist 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.
Normally, Sendmail deletes the (envelope) sender from any list expansions. For example, if matt sends a list that contains matt as one of the members, he will not get a copy of the message. If the -m (me too) command line flag is set, or if the MeToo (m) option is set in the configuration file, this behavior is suppressed. Some sites like to run the SMTP daemon with -m.
This section describes the configuration file in detail.
One point that should be made clear immediately: the syntax of the configuration file is designed to be reasonably easy to parse, since this is done every time Sendmail starts up, rather than easy for a human being to read or write. On the "future project" list is a configuration-file compiler.
The configuration file is organized as a series of lines, each of which begins with a single character defining the semantics for the rest of the line. Lines beginning with a space or a tab are continuation lines (although the semantics are not well defined in many places). Blank lines and lines beginning with a sharp symbol (#) are comments.
Rewriting tools form the core of address parsing. These are an ordered production system. Sendmail scans through the set of rewriting rules looking for a match on the left hand side (LHS) of the rule. When a rule matches, the address is replaced by the right hand side (RHS) of the rule.
There are several sets of rewriting rules. Some of the rewriting sets are used internally and must have specific semantics. Other rewriting sets do not have specifically assigned semantics and may be referenced by the mailer definitions or by other rewriting sets.
The S command has the following form:
Sn
This command sets the current rule set being collected to n. If you begin a rule set more than once, it deletes the old definition.
The R command has the following form:
Rlhs rhs comments
The fields must be separated by at least one tab character, and there may be embedded spaces in the fields. The lhs field is a pattern that is applied to the input. If it matches, the input is rewritten to the rhs field. Comments are ignored.
Macro expansions of the form $x are performed when the configuration file is read. Expansions of the form $&x are performed at runtime by using a somewhat less general algorithm. This form is only for referencing internally defined macros, such as $h, which are changed at runtime.
The left-hand side of rewriting rules contains a pattern. Normal words are simply matched directly. Metasyntax is introduced, using a dollar ($) sign. The metasymbols are as follows:
If any of these match, they are assigned to the symbol $n for replacement on the right-hand side, where n is the index in the LHS. For example, if the LHS:
$-:$+
UCBARPA:eric
the rule will match, and the values passed to the RHS will be
$1 UCBARPA $2 eric
Additionally, the LHS can include $@ to match zero tokens. This not bound to a $N on the RHS, and is normally only used when it stands alone in order to match the null input.
When the left-hand side of a rewriting rule matches, the input is deleted and replaced by the right-hand side. Tokens are copied directly from the RHS unless they begin with a dollar sign. Metasymbols are as follows:
The $n syntax substitutes the corresponding value from a $+, $-, $*, $=, or $~ match on the LHS. It may be used anywhere.
A hostname enclosed between $[ and $] is looked up using the gethostent(3) routines and replaced by the canonical name. For example, $[csam$] might become lblcsam.arpa and $[[128.32.130.2]$] would become vangogh.CSBerkeley.EDU. Sendmail recognizes its numeric IP address without calling the name server and replaces it with its canonical name.
The $( ... $) syntax is a more general form of lookup. It uses a named map instead of an implicit map. If no lookup is found, the indicated default is inserted. If no default is specified, and no lookup matches, the value is left unchanged.
The $>n syntax causes the remainder of the line to be substituted as usual and then passed as the argument to rule set n. The final value of rule set n then becomes the substitution for this rule.
The $# syntax should only be used in rule set zero or a subroutine of rule set zero. It causes evaluation of the rule set to terminate immediately and signals to Sendmail that the address has completely resolved. The complete syntax is as follows:
$#mailer $@host $: user
This specifies the (mailer, host, user) 3-tuple necessary to direct the mailer. If the mailer is local, the host part may be omitted. The mailer must be a single word, but the host and user may be multi-part. If the mailer is the built-in IPC mailer, the host may be a colon-separated list of hosts that are searched in order for the first working address (exactly like MX records). The user is later rewritten by the mailer-specific envelope rewriting set and assigned to the $u macro. As a special case, if the value to $# is "local" and the first character of the $: value is @, the @ is stripped off and a flag is set in the address descriptor that causes Sendmail not to do rule set 5 processing.
Normally, a rule that matches is retried. That is, the rule loops until it fails. A RHS may also be preceded by a $2 or a $: to change this behavior. A $@ prefix causes the rule set to return with the remainder of the RHS as the value. A $: prefix causes the rule to terminate immediately, but the rule set to continue. This can be used to avoid continued application of a rule. The prefix is stripped before continuing.
The $@ and $: prefixes may precede a $> spec, as in the following example:
R$+ $: $>7 $1
matches anything, passes that to rule set 7, and continues; the $: is necessary to avoid an infinite loop.
Substitution occurs in the order described. That is, parameters from the LHS are substituted, hostnames are made canonical, subroutines are called, and finally $#, $@, and $: are processed.
There are five rewriting sets that have specific semantics. Four of these are related as depicted by Figure D-1.
Rule set 3 should turn the address into canonical form. This form should have the basic syntax:
local-part@host-domain-spec
Rule set 3 is applied by Sendmail before doing anything with any address.
If no @ sign is specified, then the host-domain-spec may be appended (Box D in Figure D-1) from the sender address (if the C flag is set in the mailer definition corresponding to the sending mailer).
Figure D-1. Rewriting set semantics.
The following information applies to Figure D-1 .
Rule set 0 is applied after rule set 3 to addresses that are actually going to actually specify recipients. It must resolve to a (mailer, host, user) tuple. The mailer must be defined in the mailer definitions from the configuration file. The host is defined into the $h macro for use in the argv expansion of the specified mailer.
Rule sets 1 and 2 are applied to all sender and recipient address respectively. They are applied before any specification in the mailer definition. They must never resolve.
Rule set 4 is applied to all addresses in the message. It is typically used to translate internal to external form.
Some special processing occurs if the rule set 0 resolves to an IPC mailer (that is, a mailer that has [IPC] listed as the path in the M configuration line. The host name passed after $@ has MX expansion performed. This looks up the name in DNS to find alternate delivery sites.
The host name can also be provided as a dotted quad in square brackets, for example, [123.32.148.78]. This causes direct conversion of the numeric value to a TCP/IP host address
The host name passed in after the $@ may also be a colon-separated list of hosts. Each is separately MX expanded and the results are concatenated to make (essentially one long MX list. The intent here is to create fake MX records that are not published in DNS for private internal networks.
As a final special case, the host name can be passed in as a text string in square brackets, for example, [ucbvax.berkeley.edu]. This form avoids the MX mapping.
NOTE This is intended only for situations where you have a network firewall - so that your MX record points to a gateway machine. This machine could then do direct delivery to machines within your local domain. Use of this feature directly violates RFC 1123 section 5.3.5. It should not be used lightly.
Macros are named with a single character. These may be selected from the entire ASCII set, but user-defined macros should be selected from the set of uppercase letters only. Lowercase letters and special symbols are used internally.
Macro definitions have the following syntax:
Dx val
x is the name of the macro, and val is the value it should have. Macros can be interpolated in most places using the escape sequence $x, where x is the name of the macro to be interpolated. This interpolation is done when the configuration file is read, except in M lines. The special construct $&x can be used in R lines to get deferred interpolation.
Conditionals can be specified using the following syntax:
$?x test1 $| test2 $
This interpolates test1 if the macro $x is set, and test2 otherwise. The else ($|) clause may be omitted.
Lowercase macro names are reserved to have special semantics that are used to pass information in or out of Sendmail, and special characters are reserved to provide conditionals. Uppercase names (that is, $A through $Z) are specifically reserved for configuration file authors.
The following macros are defined and/or used internally by Sendmail for interpolation into argvs for mailers or for other contexts. The ones marked * are information passed into Sendmail. The ones marked ** are information passed both in and out of Sendmail, and the unmarked macros are passed out of Sendmail but are not otherwise used internally. These macros are the following:
Eric Allman <eric@CS.Berkeley.EDU> eric@CS.Berkeley.EDU (Eric Allman)
Sendmail properly quotes names that have special characters if the first form is used.
There are three types of dates that can be used. The $a and $b macros are in RFC 822 format. $a is the time as extracted from the Date: line of the message (if there was one), and $b is the current date and time (used for postmarks). If no Date: line is found in the incoming message, $a is set to the current time also. The $d macro is equivalent to the $b macro in UNIX ( ctime) format.
The macros $w, $j, and $m are set to the identity of this host. Sendmail tries to find the fully qualified name of the host if at all possible. It does this by calling gethostname(2) to get the current host name and then passing that to gethostbyanme(3), which is supposed to return the canonical version of the host name. If this operation is successful, $j is set to the fully qualified name and $m is set to the domain part of the name (everything after the first dot). The $w macro is set to the first word (everything before the first dot) if you have a level-5 or higher configuration file. Otherwise, it is set to the same value as $j. If the canonification is not successful, it is imperative that the configuration file set $j to the fully qualified domain name.
The $f macro is the ID of the sender as originally determined; when mailing to a specific host the $g macro is set to the address of the sender relative to the recipient. For example, if (using "eric" above) eric sends to bollard@matisse.CS.Berkeley.EDU from the machine vangogh.CS.Berkeley.EDU, the $f macro will be eric, and the $g macro will be eric@vangogh.CS.Berekely.EDU.
The $x macro is set to the full name of the sender. This can be determined in several ways. It can be passed as a flag to Sendmail. The second choice is the value of the Full-name: line in the header if it exists, and the third choice is the comment field of a From: line. If all of these fail, and if the message is being originated locally, the full name is looked up in the /etc/passwd file.
When sending, the $h, $u, and $z macros are set to the host, user, and home directory (if local) of the recipient. The first two are set from the $@ and $: part of the rewriting rules, respectively.
The $p and $t macros are used to create unique strings (for example, for the message-Id: field). The $i macro is set to the queue ID on this host; if put into the timestamp line, it can be extremely useful for tracking messages. The $v macro is set to be the version number of Sendmail. This is normally put in timestamps and has proved extremely useful for debugging.
The $c field is set to the hop count; that is, the number of times this message has been processed. This can be determined by the -h flag on the command line or by counting the timestamps in the message.
The $r and $s fields are set to the protocol used to communicate with Sendmail and the sending host name.
The $_ is set to a validated sender's host name. If the sender is running an RFC 1413-compliant IDENT server, it will include the user name on that host.
Classes of phrases may be defined to match on the left-hand side of rewriting rules, where a phrase is a sequence of characters that do not contain space characters. For example, a class of all local names for a site might be created so that attempts to send to oneself can be eliminated. These local names can either be defined directly in the configuration file or read in from another file. Classes may be given names from the set of uppercase letters. Lowercase letters and special characters are reserved for system use.
The C and F classes have the following syntax:
Cc phrase1 phrase2
Fc file
The C form defines the class c to match any of the named phrases. You can split the named phrases among multiple lines. For example, the C form:
CHmonet ucbmonet
is equivalent to
CHmonet
CHucbmonet
The F form reads the elements of the class c from the named file.
Elements of classes can be accessed in rules using $= or $~. The $~ (match entries not in class) only matches a single word. Multiword entries in the class are ignored in this context.
The class $=w is set to be the set of all names by which this host is known. This can be used to match local host names.
The class $=k is set to be the same as $k, that is, the UUCP node name.
The class $=m is set to the set of domains by which this host is known, initially by just $m.
The class $=t is set to the set of trusted users by the T configuration line. To read trusted users from a file, use Ft/file/user.
The class $=n can be set to the set of MIME body types that can never be 8 to 7-bit encoded. It defaults to multipart/signed. Message types message/* and multipart/* are never encoded directly. Multipart messages are always handled recursively. The handling of message/* messages are controlled by class $=s. The class $=e contains the Content-Transfer-Encodings that can be 8 to 7-bit encoded. it is predefined to contain 7bit, 8bit, and binary. The class $=s contains the set of subtypes of messages that can be treated recursively. By default it contains only rfc822. Other message/* types cannot be 8 to 7-bit encoded. If a message containing 8-bit data is sent to a 7-bit host and that message cannot be encoded into 7 bits, it will be stripped to 7 bits.
Sendmail can be compiled to allow a scanf(3) string on the F line. This lets you do simplistic parsing of text files. For example, to read all the user names in your systems's /etc/passwd file into a class, use
FL/etc/passwd %[^:]
which reads every line up to the first colon.
The M line defines programs and interfaces to mailers and has the following format:
Mname, {field=value}*
name is the name of the mailer (used internally only). The field=name pairs define attributes of the mailer. The following list defines the fields:
Only the first character of the field name is checked.
The following flags may be set in the mailer description. Any other flags may be used freely to conditionally assign headers to messages destined for particular mailers. Flags marked with * are not interpreted by the Sendmail binary; these are used to correlate the flags portion of the H line. Flags marked with ** apply to the mailers for the sender address rather than the usual recipient mailers.
From: usera@hosta To: userb@hostb, userc
to be automatically rewritten as:
From: usera@hosta To: userb@hostb, userc@hosta
However, it does not work reliably.
Configuration files before level 7 assume the A, w, 5, :, |, /, and @ options on the mailer named local.
This mailer with the special name error can be used to generate a user error. The (optional) host field is an exit status to be returned, and the user field is a message to be printed. the exit status may be numeric or one of the values USAGE, NOUSER, NOHOST, UNAVAILABLE, SOFTWARE, TEMPFAIL, PROTOCOL, or CONFIG to return the corresponding EX_ exit code. For example, the entry:
$#error $@ NOHOST $: Host unknown in this domain
on the RHS of a rule will cause the specified error to be generated and the Host unknown exit status to be returned if the LHS matches. This mailer is only functional in rule set 0 or 5.
The mailer named local must be defined in every configuration file. This is used to deliver local mail, and is treated specially in several ways. Additionally, three other mailers named prog, *file*, and *include* may be defined to tune the delivery of messages to programs, file, and :include: lists respectively. They default to:
Mprog, P=/bin/sh, F=lsD, A=sh c $u M*file*, P=/dev/null, F=lsDFMPEu, A=FILE M*include*, P=/dev/null, F=su, A=INCLUDE
The Sender and Recipient rewriting sets may be either a simple rule set ID or two IDs separated by a slash. If so, the first rewriting set is applied to envelope addresses, and the second is applied to headers.
The Directory is actually a colon-separated path of directories to try. For example, the definition D=$z:/ first tries to execute in the recipient's home directory. If that is not available, it tries to execute in the root of the filesystem. This should be used only on the prog mailer, since some shells (such as csh) refuse to execute if they cannot read the home directory. Since the queue directory is not normally readable by normal users, csh scripts as recipients can fail.
The Userid specifies the default user and group ID, overriding the DefaultUser option. If the S mailer flag is also specified, this is the user and group to run as in all circumstances. The Userid may be given as user:group to set both the user and group ID. Either may be an integer or a symbolic name to be looked up in the passwd and group files respectively. If only a symbolic user name is specified, the group ID in the passwd file for that user is used as the group ID.
The Charset field is used when converting a message to MIME; this is the character set used in the Content-Type: header. If this is not set, the DefaultCharset option is used, and if that is not set, the value unknown-8bit is used.
NOTE This field applies to the sender's mailer, not the recipient's mailer. For example, if the envelope sender address lists an address on the local network and the recipient is on an external network, the character set will be set from the Charset= field for the local network mailer, not that of the external network mailer.
The Type= field sets the type information used in MIME error messages. It is three values separated by slashes: the MTA-type (that is, the description of how hosts are named), the address type (the description of e-mail addresses), and the diagnostic type (the description of error diagnostic codes). Each of these must be a registered value or begin with X-. The default is dns/rfc822/smtp.
The H line defines the format of the header lines that Sendmail inserts into the message and has the following syntax:
H[?mflags?]hname: htemplate
Continuation lines in this appendix are reflected directly into the outgoing message. The htemplate is macro-expanded before insertion into the message. If the mflags (surrounded by question marks) are specified, at least one of the specified flags must be stated in the mailer definition for the header to be automatically output. An input header is reflected to the output regardless of these flags.
Some headers have special semantics that are described below.
A number of global options can be set from a configuration file. These options are represented by full words, although some are also represented as single characters for back compatibility. The syntax of this line is as follows:
O option=value
This sets option option to be value. Note that there must be a space between the letter O and the name of the option. An older version is:
Oo value
Here, option o is a single character. Depending on the option, value may be a string, an integer, a boolean (with legal values t, T, F, or F with TRUE as the default), or a time interval.
The supported options (with the old, one character names in brackets) are as follows:
Port - Name/number of listening port (defaults toSMPT)
Addr - Address mask (defaults to INADDR_ANY)
Family - Address family (defaults to INET)
Listen - Size of listen queue (defaults to 10)
SndBufSize - Size of TCP send buffer
RcvBufSize - Size of TCP receive buffer
The Address mask may be a numeric address in dot notation or a network name.
i - Deliver interactively (synchronously)
b - Deliver in background (asynchronously)
q - Just queue the message (deliver during queue run)
Defaults to b if no option is specified, i if it is specified but given no argument (that is, Od is equivalent to Odi). The -v command line flag sets this to i.
<@known1,@known2,@known3:user@unknown>
Sendmail will strip off the @known1,@known2 in order to make the route as direct as possible. However, if the R option is set, this will be disabled, and the mail will be sent to the first address in the route, even if later addresses are known. This may be useful if you are caught behind a firewall.
s - Reject undeclared 8-bit data (strict)
m - Convert undeclared 8-bit data to MIME (mime)
p - Pass undeclared 8-bit data (pass)
In all cases, properly declared 8BITMIME data will be converted to 7BIT as needed.
p - Print error messages (default)
q - No messages, just give exit status
m - Mail back errors
w - Write back errors (mail if user not logged in)
e - Mail back errors and give zero exit status always
public - Allows open access.
needmailhelo - Insists on HELO or EHLO command before MAIL.
needexpnhelo - Insists on HELO or EHLO command before EXPN.
noexpn - Disallows EXPN entirely.
needvrfyhelo - Insists on HELO or EHLO command before VRFY.
novrfy - Disallows VRFY entirely.
restrictmailq - Restricts mailq command.
restrictqrun - Restricts -q command line flag.
noreceipts - Ignores Return-Receipt-To: header.
goaway - Disallows all SMTP status queries.
authwarnings - Puts X-Authentication-Warning: headers in messages.
The goaway pseudo-flag sets all flags except restrictmailq and restrictqrun. If mailq is restricted, only people in the same group as the queue directory can print the queue. If queue runs are restricted, only root and the owner of the queue directory can run the queue. Authentication Warnings add warnings about various conditions that may indicate attempts to spoof the E-mail system, such as using a non-standard queue directory.
Note that before Version 8.7, this option indicated that the name server be responding in order to accept addresses. This has been replaced by checking to responding in order to accept addresses. This has been replaced by checkin to see if the "dns" method is listed in the service switch entry for the "hosts"service.
All but command apply to client SMTP. For back compatibility, a timeout with no keywords= part will set all of the longer values.
All but those that are marked with an asterisk (*) apply to client SMTP. If the message is submitted by 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.