 |
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.
aliases files hosts dns nis files
The default file is /etc/service.switch.
All options can be specified on the command line using the -O or -o flag, but most will cause Sendmail to relinquish its setuid permissions. The options that will not cause this are MinFreeBlocks [b], DeliveryMode [d], ErrorMode [e], IgnoreDots [i], LogLevel [L], MeToo [m], OldStyleHeaders [o], PrivacyOptions [p], Timeouts [r], SuperSafe [s], Verbose [v], CheckpointInterval [C], and SevenBitInput [7]. Also, M (define macro) when defining the r or s macros, is also considered "safe".
Values for the Precedence: field may be defined using the P control line. This field has the following syntax:
Pname=num
When the name is found in a Precedence: field, the message class is set to num. Higher numbers mean higher precedence. Numbers less than zero have the special property that if an error occurs during process, the body of the message will not be returned. This is expected to be used for bulk mail such as through mailing lists. The default precedence is zero. For example, our list of precedences is as follows:
Pfirst-class=0 Pspecial-delivery=100 Plist= 30 Pbulk= 60 Pjunk= 100
People writing mailing list exploders are encouraged to use Precedence: list. Older versions of Sendmail (which discarded all error returns for negative precedences) did not recognize this name, giving it a default precedence of zero. This allows list maintainers to see error returns on both old and new versions of Sendmail.
To provide compatibility with old configuration files, the V line has been added to define some very basic semantics of the configuration file. These are not intended to be long-term supports. Rather, they describe compatibility features that will probably be removed in future releases.
NOTE These version levels have noting to do with the version number on the files. For example, as of this writing version 8 configuration files (specifically 8.67) used version level 6 configurations.
Old configuration files are defined as version-level one. Version level two files make the following changes:
Host name canonification ($[ ... $]) appends a dot if the name is recognized. This process gives the configuration file a way of finding out if anything matched. (Actually, this process just initializes the host map with the -a flag. You can reset it to anything you prefer by declaring the map explicitly.
Default host name extension is consistent throughout processing; version-level-one configurations turn off domain extension (that is, adding the local domain name) during certain points in processing. Version-level-two configurations are expected to include a trailing dot to indicate that the name is already canonical.
Local names that are not aliases are passed through a newly distinguished rule set 5; this behavior can be used to append a local relay. This behavior can be prevented by resolving the local name with an initial @. That is, something that resolves to a local mailer and a user name of vikki will be passed through rule set 5, but a user name of @vikki will have the @ stripped, will not be passed through rule set 5, but will otherwise be treated the same as the prior example. The expectation is that this might be used to implement a policy where mail sent to vikki was handled by a central hub, but mail sent to vikki@localhost was delivered directly.
Version-level-three files allow # initiated comments on all lines. Exceptions are backslash-escaped # marks and the $# syntax.
Version-level-four configurations are completely equivalent to level three for historical reasons.
Version-level-five configuration files change the default definition of $w to be just the first component of the host name.
Version-level-six configuration files change many of the local processing options (such as aliasing and matching the beginning of the address for | characters) to be mailer flags. This action allows fine-grained control over the special local processing. Level-six configuration files may also use long option names. The ColonOkInAddr option (to allow colons in the local part of addresses) defaults to on for lower-numbered configuration files. The configuration file requires some additional intelligence to properly handle the RFC 822 group construct.
The V line may have an optional /vendor to indicate that this configuration file uses modifications specific to a particular vendor. You can use /Berkeley to emphasize that this configuration file used the Berkeley dialect of Sendmail.
Special maps can be defined using the following line:
Kmapname mapclass arguments
The mapname is the handle by which this map is referenced in the rewriting rules. The mapclass is the name of a type of map; these are compiled in to Sendmail. The arguments are interpreted depending on the class; typically, there would be a single argument naming the file containing the map.
Maps are referenced by the following syntax:
$( map key $@ arguments $: default $)
where either or both of the arguments or default portion may be omitted. The arguments may appear more than once. The indicated key and arguments are passed to the appropriate mapping function. If it returns a value, it replaces the input. If that does not return a value and the default is specified, the default replaces the input. Otherwise, the input is unchanged.
During the replacement of either a map value or default, the string %n (where n is a digit) is replaces by the corresponding argument. Argument zero is always the database key. For example, the rule
R$-!$+ $: $(uucp $1 $@ $2$: %1@ %0. UUCP $)
looks up the UUCP name in a (user defined) UUCP map. If not found, it turns it into .UUCP form. The database might contain records like:
decvax %1@%0.DEC.COM research %1@%0.ATT.COM
The built-in map with both name and class host is the host name canonicalization lookup. Therefore, the following syntax:
$(host hostname$)
is equivalent to:
$[hostname$]
The predefined database lookup classes are defined below:
Kmap1 ...
Kmap2 ... Kseqmap sequence map1 map2
then a lookup against seqmap first does a lookup in map1. If that is found, it returns immediately. Otherwise, the same key is used for map2.
Kali switch aliases
together with the service switch entry:
aliases nis files
This causes a query against the map ali to search maps named ali.nis and ali.files in that order.
``49ers::ubell''A typical usage is probably something like:
Kdequote dequote
...
R$- $:$(dequote $1 $)
R$- $+ $: $>3 $1 $2
Care must be taken to prevent unexpected results; for example, ''\someprogram<input>outputwill have quotes stripped, but the result is probably not what you had in mind. Fortunately, these cases are rare.
Most of these classes accept as arguments the same optional flags and a filename (or a mapname for NIS; the filename is the root of the database path, so that .db or some other extension appropriate for the database type will be added to get the actual database name). Known flags are as follows:
The dbm map appends the strings .pag and .dir to the given filename. The two db-based maps append .db. For example, the following map specification:
Kuucp dbm -o -N /usr/lib/uucpmap
specifies an optional map named uucp of class dbm. It always has null bytes at the end of every string. The data is located in /usr/lib/uucpmap.[dir,pag].
The makemap(8) program can be used to build any of the three database-oriented maps. It takes the following flags:
The Sendmail daemon does not have to be restarted to read the new maps as long as you change them in place. File locking is used so that the maps will not be read while they are being updated.
New classes can be added in the setupmaps routine in the conf.c file.
If you have a version of Sendmail with the user database package compiled in, the handling of sender and recipient addresses is modified.
The location of this database is controlled with the UserDatabaseSpec option.
The database has a sorted (BTree-based) structure. User records are stored with the following key:
user-name:field-name
The sorted database format ensures that user records are clustered together. Meta-information is always stored with a leading colon.
Field names define both the syntax and semantics of the value. Defined fields include the following:
As of this writing, only a few of these fields are actually being used by Sendmail. They are maildrop and mailname. A finger program that uses the other fields is planned.
When the rewriting rules submit an address to the local mailer, the user name is passed through the alias file. If no alias is found (or if the alias points back to the same address), the name (with :maildrop appended) is then used as a key in the user database. If no match occurs (or if the maildrop points at the same address), forwarding is tried.
If the first token of the user name returned by rule set 0 is an @ sign, the user database lookup is skipped. The user database should act as a set of defaults for a cluster; mail sent to a specific machine should ignore these defaults.
When mail is sent, the name of the sending user is looked up in the database. If that user has a mailname record, the value of that record is used as his or her outgoing name. For example, consider the following record:
eric:mailname Eric.Allman@CS.Berkeley.EDU
This would cause my outgoing mail to be sent as Eric.Allman.
If a maildrop is found for the user, but no corresponding mailname record exists, the record :default:mailname is consulted. If present, this is the name of a host to overrider the local host. For example, in our case we would set it to CS.Berkeley.EDU. The effect is that all the users known in the database have their outgoing mail stamped as user@CS.Berkeley.EDU, but people not listed in the database use the local host name.
The user database is built from a text file using the makemap utility (in the distribution in the makemap subdirectory). The text file is a series of lines corresponding to userdb records. Each line has a key and a value separated by white space. The key is always in the format described above, for example,
eric:maildrop
This file is normally installed in a system directory; for example, it might be called /etc/userdb. To make the database version of the map, run the following program:
makemap btree /etc/userdb.db < /etc/userdb
Then create a configuration file that uses this. For example, using the V8 M4 configuration, include the following line in your .mc file;
define(`confUSERDB_SPEC', /etc/userdb.db)
Some configuration changes can be made by recompiling Sendmail. This section describes what changes can be made and what has to be modified to make them. In most cases any change should be unnecessary unless you are porting Sendmail to a new environment.
These parameters describe the compilation environment, not site policy, and should normally be defined in src/Makefile.
There are also several compilation flags to indicate the environment such as _AIX3 and _SCO_unix_. See the READ_ME file for the latest information on these flags.
Parameters and compilation options are defined in conf.h. Most of these need not normally be tweaked; common parameters are all in sendmail.cf. However, the sizes of certain primitive vectors, etc., are included in this file. The numbers following the parameters are their default value.
NOTE This document is not the best source of information for compilation flags in conf.h. Refer to src/READ_ME or src/conf.h.
A number of other compilation options exist. These specify whether or not specific code should be compiled in. Ones marked with * are 0/1 valued.
The following options are normally turned on in per-operating-system clauses in conf.h.
system call including <sys/statvfs.h>), SFS_STATVFS (use the two-argument statfs(2) system call including <sys/statvfs.h>), or SFS_NONE.
There are several built-in ways of computing the load average. Sendmail tries to auto-configure them based on imperfect guesses. You can select one by using the cc option -DLA_TYPE=type, where type is:
If type LA_INT, LA_SHORT or LA_FLOAT is specified, you may also need to specify _PATH_UNIX (the path to your system binary) and LA_AVENRUN (the name of the variable containing the load average in the kernel - usually _avenrun or avenrun).
The following changes can be made in conf.c.
Not all header semantics are defined in the configuration file. Header lines that should only be included by certain mailers (as well as other more obscure semantics) must be specified in the HdrInfo table in conf.c. This table contains the header name (which should be in lower case) and a set of header control flags (described below). The flags are as follows:
Consider the following sample HdrInfo specification:
struct hdrinfo HdrInfo[] =
{
/* originator fields, most to least significant */
"resent-sender", H_FROM,
"resent-from", H_FROM,
"sender", H_FROM,
"from", H_FROM,
"full-name", H_ACHECK,
``error-to'', H_FROM|ERRORSTO,
/* destination fields */
"to", H_RCPT,
"resent-to", H_RCPT,
"cc", H_RCPT,
"bcc", H_RCPT|H_STRIPVAL
/* message identification and control */
"message", H_EOH,
"text", H_EOH,
/* trace fields */
"received", H_TRACE|H_FORCE,
/* miscellaneous fields */
``content-transfer-encoding'', H_CTE.
``content-type''. H_CTYPE,
NULL, 0,
};
This structure indicates that the To:, Resent-To:, and Cc: fields all specify recipient addresses. Any Full-Name: field will be deleted unless the required mailer flag (indicated in the configuration file) is specified. The Message: and Text: fields will terminate the header. These are used by random dissenters around the network world. The Received: field will always be added, and can be used to trace messages.
There are a number of important points here. First, header fields are not added automatically just because they are in the HdrInfo structure; they must be specified in the configuration file in order to be added to the message. Any header fields mentioned in the configuration file but not mentioned in the HdrInfo structure have default processing performed; that is, they are added unless they were in the message already. Second, the HdrInfo structure only specifies cliched processing; that is, certain headers are processed specially by ad hoc code regardless of the status specified in HdrInfo. For example, the Sender: and From: fields are always scanned on ARPANET mail to determine the sender; this is used to perform the "return to sender" function. The From: and Full-Name: fields are used to determine the full name of the sender if possible; this is stored in the macro $x and used in a number of ways.
If it is necessary to restrict mail through a relay, the checkcompat routine can be modified. This routine is called for every recipient address. It returns an exit status indicating the status of the message. The status EX_OK accepts the address, EX_TEMPFAIL queues the message for a later try, and other values (commonly EX_UNAVAILABLE) reject the message. It is up to checkcompat to print an error message (using usrerr) if the message is rejected. For example, checkcompat could read as follows:
int
checkcompat(to, e)
register ADDRESS *to;
register ENVELOPE *e;
{
register STAB *s;
s = stab("private", ST_MAILER, ST_FIND);
if (s != NULL && e >e_from.q_mailer != LocalMailer &&
to->q_mailer == s->s_mailer)
{ usrerr("No private net mail allowed through this machine");
return (EX_UNAVAILABLE);
} if (MsgSize > 50000 && bitnset(M_LOCALMAILER, to->q_mailer))
{ usrerr("Message too large for non-local delivery");
e->e_flags|=EF_NORETURN;
return (EX_UNAVAILABLE);
} return (EX_OK);
}
This would reject messages greater than 50000 bytes unless they were local. The EF_NORETURN flag can be set in e->e_flags to suppress the return of the actual body of the message in the error return. The actual use of this routine is highly dependent on the implementation, and use should be limited.
The getla routine should return an approximation of the current system load average as an integer. There are four versions included on compilation flags as described above.
The new key maps can be added by creating a class initialization function and a lookup function. These are then added to the setupmaps routine.
The initialization function is called as
xxx _map_init(MAP *map, char *mapname, char *args)
The map is an internal data structure. The mapname is the name of the map (used for error messages). The args is a pointer to the rest of the configuration file line. Flags and filenames can be extracted from this line. The initialization function must return TRUE if it successfully opened the map, FALSE otherwise.
The lookup function is called as
xxx _map_lookup(MAP *map, char buf[], int bufsize, char **av,int *statp)
The map defines the map internally. The buf and bufsize parameters have the input key. This may be (and often is) used destructively. The av is a list of arguments passed in from the rewrite line. The lookup function should return a pointer to the new value. If the map lookup fails, *statp should be set to an exit status code. In particular, it should be set to EX_TEMPFAIL if recovery is to be attempted by the higher level code.
The shouldqueue routine is called to decide if a message should be queued or processed immediately. Typically, this compares the message priority with the current load average. The default definition is as follows:
bool
shouldqueue(pri, ctime)
long pri;
time_t ctime;
{
if (CurrentLA < QueueLA)
return (FALSE);
return (pri > (QueueFactor / (CurrentLA -- QueueLA + 1)));
}
If the current load average (global variable CurrentLA, which is set before this function is called) is less than the low threshold load average (option x, variable QueueLA), shouldqueuereturns FALSE immediately (that is, it should not queue). If the current load average exceeds the high threshold load average (option X, variable RefuseLA), shouldqueuereturns TRUE immediately. Otherwise, it computes the function based on the message priority, the queue factor (option q, global variable QueueFactor), and the current and threshold load averages.
An implementation wishing to take the actual age of the message into account can also use the ctime parameter, which is the time that the message was first submitted to Sendmail. Note that the pri parameter is already weighted by the number of times the message has been tried (although this tends to lower the priority of the message with time). The expectation is that the ctime would be used as an "escape clause" to ensure that messages are eventually processed.
The refuseconnections function returns TRUE if incoming SMTP connections should be refused. The current implementation is based exclusively on the current load average and the refuse load average option (option X, global variable RefuseLA):
bool
refuseconnections()
{
return (CurrentLA >= RefuseLA);
}
A cleverer implementation could look at more system resources.
The getla routine returns the current load average (as a rounded integer). The distribution includes several possible implementations.
The file src/daemon.c contains a number of routines that are dependent on the local networking environment. The version supplied assumes that you have BSD style sockets.
In previous releases, it was recommended that you modify the routine maphostname if you wanted to generalize $[ ...$] lookups. Now it is recommended that you create a new keyed map instead.
The following sections summarize the changes since the last commonly available version of Sendmail (5.67).
Instead of being closed immediately, SMTP connections are cached for possible future use. The advent of MX records made this effective for mailing lists. In addition, substantial performance improvements can be expected for queue processing.
If two hosts with different names in a single message happen to have the same set of MX hosts, they can be sent in the same transaction. Version 8 notices this possibility and tries to batch the messages.
A number of changes have been made to make Sendmail "conditionally compliant" (that is, Sendmail satisfies all of the "MUST" clauses and most but not all of the "SHOULD" clauses in RFC 1123).
The major areas of change are (numbers are RFC 1123 section numbers):
The areas in which Sendmail is not "unconditionally compliant" are as follows:
Version 8 includes both sending and receiving support for Extended SMTP (ESMTP) as defined by RFC 1425 (basic) and RFC 1427 (SIZE), and limited support for RFC 1425 (BODY).
Previous versions of Sendmail used the 0200 bit for quoting. This version avoids that use. However, for compatibility with RFC 822, you can set option 7 to get 7-bit stripping.
Individual mailers can still produce 7-bit output using the 7 mailer flag.
The user database is still an experimental attempt to provide unified large-site name support. Future versions may show significant modification.
The BIND support, particularly for MX records, had a number of annoying features that have been removed in this release. In particular, these more tightly bind the name server to Sendmail, so that the name server resolution rules are incorporated directly into Sendmail.
Generalized keyed files is an idea taken directly from IDA Sendmail (albeit with a completely different implementation). They can be useful on large sites.
Version 8 also understands YP.
Classes can now be multiple words as in the following example:
CShofmann.CS.Berkeley.EDU
In this example, you can match the entire string hofman.CS.Berkeley.EDU using the single construct $=S.
The $&x construct has been adopted from IDA.
The IDENT protocol as defined in RFC 1413 is supported.
A number of small bugs dealing with such things as backslash-escaped quotes inside of comments have been fixed.
Since the From: line is passed in separately from the envelope sender, these have both been made visible. The $g macro is set to the envelope sender during processing of mailer argument vectors and the header sender during processing of headers.
You can also specify separate per-mailer envelope and header processing. The SenderRWSet and RecipientRWset arguments for mailers can be specified as envelope/header to give different rewritings for envelope versus header addresses.
When an alias has an associated owner-list name, that alias is used to change the envelope sender address. This will cause downstream errors to be returned to that owner.
The fixed size limit on header lines has been eliminated.
The -B flag has been added to pass in body type information.
The -p flag has been added to pass in protocol information.
The -X flag has been added to allow logging of all protocol in and out of Sendmail for debugging.
The -q flag can limit a queue run to specific recipients, senders, or queue IDs using -qRsubstring, -qSsubstring, or -qIsubstring respectively.
The K line has been added to declare database maps.
The V line has been added to declare the configuration version level.
The M line has a D= field that lets you change into a temporary directory while that mailer is running.
Several new options have been added, many to support new features, others to allow tuning that was previously available only by recompiling. They are described earlier in the section entitled "H - Define Header" and are briefly described in the following list:
eight bit data handling mode.
The r (read timeout), I (use BIND), and T (queue timeout) options have been extended to pass in more information.
The following new mailer flags have been added:
All options can be specified by using long names, and some new options can only be specified with long names.
The following macros are pre-defined:
Version 8 allows $@ on the Left-Hand Side of an R line to match zero tokens. This is used to match the null input.
Version 8 allows up to 100 rule sets instead of 30. It is recommended that rule sets 0-9 be reserved for Sendmail's dedicated use in future releases.
The total number of MX records that can be used has been raised to 20.
The number of queued messages that can be handled at one time has been raised from 600 to 1000.
Version 8 has changed the default parameters for tuning queue costs to make the number of recipients more important than the size of the message (for small messages). This is reasonable if you are connected with reasonably fast links.
Previously, the "Full Name <email address>" syntax would generate incorrect protocol output if Full Name had special characters such as a dot. This version puts quotes around such names.
Several names have been built in to the $@ portion of the $#error mailer.
Previous versions of Sendmail treated VRFY and EXPN the same. In this version, VRFY does not expand aliases or follow .forward files. EXPN still does.
As an optimization, if you run with your default delivery mode being queue-only or deliver-in-background, the RCPT command will also not chase aliases and .forward files. It will chase them when it processes the queue.
When an address resolves to a mailer that has [IPC] as its Path, the $@ part (host name) can be a colon-separated list of hosts instead of a single host name. This asks Sendmail to search the list for the first entry that is available exactly as though it were an MX record. The intent is to route internal traffic through internal networks with out publishing an MX record to the net. MX expansion is still done on individual terms.
The implementation has been merged with maps. Among other things, this supports NIS-based aliases.
A number of internal changes have been made to enhance portability.
Several fixes have been made to increase the paranoia factor.
Sendmail writes a /etc/sendmail.pid file with the current process ID of the SMTP daemon.
Two people using the same program in their .forward file are considered different so that duplicate elimination does not delete one of them.
The mailstats program prints mailer names and gets the location of the sendmail.st file from /usr/lib/sendmail.cf.
Many minor bugs have been fixed, such as handling of backslashes inside End of File (EOF) quotes.
A hook (rule set 5) has been added to allow rewriting of local addresses after aliasing.
Arguments must be presented with flags before addresses. The flags are explained in the following list:
m - Delivers mail (default).
s - Speaks SMTP on input side.
a* - "Arpanet" mode (get envelope sender information from header)
d - Runs as a daemon.
t - Runs in test mode.
v - Verifies addresses, do not collect or deliver.
i - Initializes the alias database.
p - Prints the mail queue.
The e, i, m, and v options may be specified as primitive flags. Also, the f option may be specified as the -s flag.
This appendix describes the format of the queue files. These files live in the directory defined by the Q option in the sendmail.cf file, usually /var/spool/mqueue or /usr/spool/mqueue.
All queue files have the name xfAAA99999 where AAA99999 is the ID for this message and the x is a type. The first letter of the ID encodes the hour of the day that the message was received by the system (with A being the hour between midnight and 1:00 AM). all files with the same ID collectively define on message.
The types are described in the following list:
The qf file is structured as a series of lines - each beginning with a code letter. The lines are as follows:
As an example, the following is a queue file that is sent to eric@mammoth.Berkeley.EDU and bostic@okeefe.CS.Berkeley.EDU:
P835771
T404261372
Seric Ceric:sendmail@vangogh.CS.Berkeley.EDU
Reric@mammoth.Berkeley.EDU
Rbostic@okeeffe.CS.Berkeley.EDU
H?P?return-path: <owner-sendmail@vangogh.CS.Berkeley.EDU>
Hreceived: by vangogh.CS.Berkeley.EDU (5.108/2.7) id AAA06703;
Fri, 17 Jul 92 00:28:55 -0700
Hreceived: from mail.CS.Berkeley.EDU by vangogh.CS.Berkeley.EDU (5.108/2.7)
id AAA06698; Fri, 17 Jul 92 00:28:54 -0700
Hreceived: from [128.32.31.21] by mail.CS.Berkeley.EDU (5.96/2.5)
id AA22777; Fri, 17 Jul 92 03:29:14 -0400
Hreceived: by foo.bar.baz.de (5.57/Ultrix3.0-C)
id AA22757; Fri, 17 Jul 92 09:31:25 GMT
H?F?from: eric@foo.bar.baz.de (Eric Allman)
H?x?full-name: Eric Allman
Hmessage-id: <9207170931.AA22757@foo.bar.baz.de>
HTo: sendmail@vangogh.CS.Berkeley.EDU
Hsubject: this is an example message
This shows the name of the data file, the person who sent the message, the submission time (in seconds since January 1, 1970), the message priority, the message class, the recipients, and the headers for the message.
This is a summary of the support files that Sendmail creates or generates.