[Previous Section] [Back to Table of Contents] [Next Section]

IRIX Advanced Site and Server Administration Guide

Appendix D
IRIX sendmail Reference

The sendmail system implements a general purpose internetwork mail-routing facility under the UNIX operating system. It is not tied to any one transport protocol; its function is like a crossbar switch, relaying messages from one domain into another. In the process, it can also do a limited amount of message header editing to put the message into a format that is appropriate for the receiving domain. All sendmail operations are done under the control of a configuration file.

To provide customized services to each site, sendmail uses a configuration file that provides a high degree of flexibility. The unfortunate result is that the configuration file can seem complex and unapproachable. However, most sites fit one of a few basic configurations. The standard configuration file supplied with IRIX is designed to work in these configurations with a minimum number of site-specific modifications.

This appendix is organized into the following sections:


sendmail's implementation features aliasing, forwarding, automatic routing to network gateways, and flexible configuration.

In a simple network, each node has an address, and resources can be identified with a host-resource pair. For example, a mail system can refer to users with a host­user-name pair. Host names and numbers must be administered by a central authority, but user names can be assigned locally to each host.

In an internetwork, multiple networks with different characteristics and management must communicate. In particular, the syntax and semantics of resource identification change. You can handle certain simple cases by using improvised techniques, such as providing network names that appear local to hosts on other networks. However, the general case is extremely complex. For example, some networks require point-to-point routing, which simplifies the database update problem, because only adjacent hosts are entered into the system tables; others use end-to-end addressing. Some networks use a left-associative syntax; others use a right-associative syntax, causing ambiguity in mixed addresses.

Internetwork standards seek to eliminate these problems. Initially, these standards proposed expanding the address pairs to address triples, consisting of {network, host, resource}. Network numbers must be universally agreed upon; hosts can be assigned locally on each network. The user-level presentation was quickly expanded to address domains, composed of a local resource identification and a hierarchical domain specification with a common static root, as defined in RFC 1034. The domain technique separates the issue of physical versus logical addressing. For example, an address of the form "jane@iris1.company.com" describes only the logical organization of the address space.

sendmail bridges the gap between the world of totally isolated networks that know nothing of each other and the clean, tightly coupled world of unique network numbers. sendmail can accept old arbitrary address syntaxes, resolving ambiguities by using heuristics specified by the network administrator, as well as domain-based addressing. sendmail helps guide the conversion of message formats between disparate networks. In short, sendmail is designed to assist a graceful transition to consistent internetwork addressing schemes.

Design Goals

The design goals for sendmail included the following:

    Message delivery should be reliable, guaranteeing that every message is correctly delivered or at least brought to the attention of a human for correct disposal; no message should ever be completely lost.

    Existing software should be used to do actual message delivery whenever possible.

    sendmail should be easy to expand to fairly complex environments.

    Configuration should not be compiled into the code.

    sendmail should let various groups maintain their own mailing lists, and let individuals specify their own forwarding, without modifying the system alias file.

    Each user should be able to specify which mailer to execute to process mail being delivered for him. This feature allows users with specialized mailers that use a different format to build their environments without changing the system, and facilitates specialized functions (such as returning an "I am on vacation" message).

    To minimize network traffic, addresses should be batched to a single host where possible, without assistance from the user.

System Organization

The original design goals for sendmail motivated the architecture illustrated in Figure D-1.



Figure D-1 : sendmail System Structure

sendmail neither interfaces with the user nor does actual mail delivery. Rather, it collects a message generated by a user agent program such as Berkeley Mail, edits the message as required by the destination network, and calls appropriate mailers to do mail delivery or queueing for network transmission. The exception is mail sent to a file; in this case, sendmail delivers the mail directly.

This discipline allows the insertion of new mailers at minimum cost.

Because some of the senders may be network servers and some of the mailers may be network clients, sendmail can be used as an internetwork mail gateway.

sendmail Communications

sendmail communicates with the outside world to receive and send mail in any of three ways:

How sendmail Works

To send a message, the sender program issues a request to sendmail by using one of the methods described in the preceding subsection. sendmail operates in two distinct phases. First, it collects and stores the message. Second, it sees that the message is delivered. If errors occur during the second phase, sendmail returns to the sender either a status code or a new message describing the error.

Argument Processing and Address Parsing

When sendmail is called, initial processing includes reading sendmail.cf, scanning arguments and processing option specifications. Next, sendmail collects recipient addresses, either from the command line or from the SMTP RCPT command, and creates a list of recipients. This step includes expanding alias and mailing lists. sendmail also tries to validate addresses by checking syntax and verifying local addresses. However, detailed checking of host names and addresses occurs during the delivery phase.

As local addresses are verified, sendmail performs any system aliasing or per-user forwarding (described in "Per-User Forwarding"). sendmail appends each address to the recipient list after parsing. When a name is aliased or forwarded, the old name is retained in the list and a flag is set that tells the delivery phase to ignore this recipient. This list is kept free from duplicates to prevent alias loops and duplicate messages to the same recipient, which might occur if a person is a member of two groups.

Message Collection

After initial processing,sendmail collects the message. The message should begin with a header; no other formatting requirements are imposed on the message except that it must be composed of text lines. (That is, sendmail does not accept binary data.) The message header is parsed and stored in memory; the message body (the text lines of the actual message) is saved in a temporary file.

To simplify the program interface, the message is collected even if no addresses are valid. In this case, the message is returned with an error.

Message Delivery

For each unique mailer and host in the recipient list, sendmail calls the appropriate mailer. Each mailer invocation sends to all users receiving the message on one host. Mailers that accept only one recipient at a time are handled properly.

The message is sent to the mailer by means of one of the same three interfaces used to submit a message to sendmail. Each copy of the message is prepended by a customized header. The mailer status code is caught and checked, and an error message given as appropriate. If the exit code does not conform to a system standard, sendmail sends a generic message ("Service unavailable").

Queueing for Retransmission

If the mailer returns a status indicating that it might be able to handle the mail later, sendmail queues the mail and tries again later.

Return to Sender

If errors occur during processing, sendmail returns the message to the sender for retransmission. The message can be mailed back or written in the file dead.letter in the sender's home directory. (Obviously, if the site giving the error is not the originating site, the only reasonable option is to return the message to the sender. There are many error disposition options, but they only affect the error message. The "return to sender" function always operates in one of these two ways.)

Message Header Editing

Some editing of the message header occurs automatically under the control of the configuration file. Header lines may be inserted and addresses rewritten to conform to the requirements of the receiving domain.

See "The Configuration File" for more information on the configuration file.

Usage and Implementation

This section provides a more in-depth discussion of several topics discussed at the operational level in the preceding section.


sendmail command arguments include both flags and addresses. Flags appear first and set various processing options. Address arguments are valid unless sendmail is running in SMTP mode, and follow the address syntax in RFC 822 for Internet address formats:

    Anything in parentheses is ignored (treated as a comment).

    Anything in angle brackets (< >) is preferred over anything else. This rule implements the Internet standard of choosing bracketed over nonbracketed addresses in cases like the following:

    user name <machine-address >

    In this example the electronic "machine-address" will be the recipient of the message rather than the human "user name."

    Double quotation marks (") are used to quote a phrase; a backslash (\) is used to quote a character. Backslashes are more powerful: They cause otherwise equivalent phrases to compare differently. For example, user and "user" are equivalent, but \user is different from either of the first two forms.

Parentheses, angle brackets, and double quotation marks must be properly balanced and nested. The rewriting rules control the rest of the parsing, except that some special processing occurs after local names are rewritten. This processing is described in the next subsection.

Message Redirection

sendmail uses three facilities to redirect mail: aliasing, forwarding, and inclusion. Aliasing applies system-wide. Forwarding allows each user to redirect incoming mail sent to his account. Inclusion directs sendmail to read a file for a list of addresses, and is normally used in conjunction with aliasing.


Aliasing maps names to address lists, using a system-wide file. This file is indexed to speed access. Only names that parse as local are allowed as aliases; this restriction guarantees a unique key (since there are no nicknames for the local host). You can suppress aliasing by prepending a backslash to the address. See "The Alias Database" for more information.


If aliasing determines that a name is local and valid, the recipient's home directory is checked for the existence of a .forward file. If one exists, the message is not sent to the user, but rather to the list of users identified in the .forward file. The file may contain only one address; in this case, the feature implements network mail forwarding. See "Per-User Forwarding" for more information.


Inclusion is specified in RFC 733 syntax:

:include: pathname

An address of this form reads the file specified by pathname and sends the message to all users listed in that file. RFC 822, which defines Internet addressing, does not define inclusion; therefore it should not appear in any message address field. Silicon Graphics does not support direct use of this feature, but uses it as a subset of aliasing. For example, an alias of the following form allows a project to maintain a mailing list without involving the system administration, even if the alias file is protected:

project: :include:/usr/project/userlist

When you change the contents of an :include: list, you do not have to rebuild the indexed alias database. (You will, however, have to rebuild the indexed alias database if the pathname changes.)

Mail to Files and Programs

A message can be sent to a file or program residing on the local host if the file or program name is the result of an alias lookup or is obtained from a user's .forward file.

Files provide archival storage of messages and are useful for project administration and history. Programs are useful recipients in a variety of situations. The vacation(1) program, which automatically responds to messages while you are on vacation, is an example of a recipient program.

If the initial parsing algorithm determines that an address is local (that is, that the address is not valid for another mailer), the address is scanned for two special cases:

In general, file-type recipients must be writable by everyone. However, if sendmail is running as root and the file has setuid or setgid bits set, then the message will be written to the file.

Message Collection

After all recipient addresses are parsed and verified, the message is collected. The message comes in two parts, a message header and a message body, separated by a blank line, as defined by RFC 822.

The header is formatted as a series of lines of the form

field-name: field-value

Field-value can be split across lines if each subsequent line starts with a space or a tab. Some header fields have special internal meaning and appropriate special processing. Other headers simply pass through. Header fields such as time stamps may be added automatically.

The body is a series of text lines that is completely uninterpreted and un-touched, except that an extra dot is added to any line beginning with a dot when transmitted over an SMTP channel. (The extra dot is stripped by the receiver.)

The message is then placed in the mail queue. The mail queue resides in the directory /var/spool/mqueue and consists of two queue files for each message. The queue control file describes the list of recipients built during initial address parsing, as well as other parameters. This control file is a series of tagged lines with each line describing a sender, a recipient, or some other salient parameter of the message. The queue control file also contains the complete message header. Associated with each control file is an unstructured queue data file that contains the complete body of the message.

Message Delivery

After the message has been collected and placed in the mail queue, sendmail attempts to deliver it. To implement message batching, prior to transmission, the list of recipients is ordered by receiving host. Under control of the configuration file, sendmail selects the appropriate mailer to use for connecting to each receiving host in turn.

After a connection is established, sendmail makes the per-mailer changes to the header and sends the result to the mailer. If any mail is rejected by the mailer, a flag is set to invoke the return-to-sender function after all delivery completes.

The interface to the mailer uses one of the techniques described in "sendmail Communications".

Each recipient address to which the message is sent is marked so that sendmail can safely rescan the list. Mail to files and programs is detected during the scan of the recipient list.

After the message has been delivered to all recipients (or errors reported for all recipients to whom the message could not be delivered), the message is removed from the mail queue.

Queueing for Retransmission

If the mailer returns a "temporary failure" exit status, the message is left in the mail queue for attempted delivery at a later time.


Almost all configuration information is read at run time from an ASCII file named /usr/lib/sendmail.cf. This file encodes options, header declarations, mailer declarations, trusted user declarations, message precedences, address-rewriting rules, macro definitions, and class definitions.

To eliminate the need to read the configuration file each time sendmail is called, thus improving performance, sendmail can save a copy of its data space after the configuration file has been parsed. This technique creates what is known as a "frozen" configuration file. Subsequent calls to sendmail can use this frozen configuration directly, greatly reducing startup time.

The subsections that follow briefly describe the information in the configuration file. For a full description of the syntax and semantics of the configuration file, see "The Configuration File".


The options that can be set from the configuration file include the pathnames of various support files, timeouts, default modes, and so forth.

See the description of the Set Option command in "The Syntax" and "Configuration Options" for further details.

Header Declarations

Header declarations tell sendmail the format of known header lines.

Built into sendmail is the knowledge of a few header lines, such as the "From:" and "Date" lines. Most configured headers are automatically inserted in the outgoing message if they don't exist in the incoming message. See the description of the Define Header command in "The Syntax" for details.

Mailer Declarations

Mailer declarations tell sendmail what mailers are available. The definition specifies the internal name of the mailer, the pathname of the program to call, some flags associated with the mailer, associated and separate sender and recipient address-rewriting rules, and an argument vector to be used on the call. See the description of the Define Header command in "The Syntax" for details.

Trusted User Declarations

Trusted user declarations tell sendmail the names of users who are allowed to override the sender-address setting in messages. This should not be confused with anything having to do with Trusted IRIX/B, which is a B1-level trusted (secure) operating system. See the description of the Define Trusted Users command in "The Syntax".

Message Precedence

Message precedence is set by the configuration file and is used by sendmail to determine the message priority adjustment associated with various possible contents of the "Precedence:" header field. See the description of the Define Precedence command in "The Syntax" for details.

Address Rewriting Rules

The heart of address parsing in sendmail consists of the address-rewriting rule sets. Each rule set is an ordered list of pattern-replacement rules. Rule sets perform the two main functions of rewriting address strings and selecting the appropriate mailer for the message.

The mechanism for textual rewriting of address strings enables sendmail to edit addresses into different formats. For example, consider an address of the following form:


This address might be rewritten as follows to conform to the domain syntax:


With appropriate rule sets, translations can also be made in the other direction.

The special rule set 0 selects the correct mailer to handle a message based upon the recipient's address. For example, consider the following address:


This address is parsed into a (mailer, host, user) triple:

{ether, big.company.com, johndoe@big.company.com}

The triple selects the mailer to use to deliver the message, the name of the host to deliver the message to next, and the address of the recipient.

sendmail uses different rule sets to rewrite sender and recipient addresses. Each mailer can have specific sender and recipient address-rewriting rules associated with it. Using these rules, sendmail can function as an internetwork mail router. See "The Syntax" for information.


sendmail uses macros in three ways:

See the description of the Define Macros command in "The Syntax" for information.


Used in the address-rewriting rules, classes define sets of textual information against which to test patterns to determine whether they are members. For example, a class might contains all known names for the local host. The address-rewriting rules might use this class to test the recipient hostname, determining if it is actually just another name for the local host. See the description of the Define Classes command in "The Syntax" for more detail.

Basic Installation

Installing sendmail is a two-step process:

    Install the sendmail files into the appropriate places with the proper permissions.

    This installation happens automatically when you install IRIX.

    Modify the /usr/lib/sendmail.cf configuration file, the file that sendmail reads when it starts up.

    The configuration file describes mailers, tells sendmail how to parse addresses and rewrite message headers, and sets various sendmail options. The standard configuration file shipped with IRIX supports a wide variety of mail configurations and should require only minimal modification.

Note: The supplied /usr/lib/sendmail.cf file does not work "out of the box." Some modifications are required before sendmail will work. The next section describes typical modifications.

See "Customizing the sendmail.cf File" for instructions on tailoring sendmail to your specific mail environment.

Normal Operations

This sections describes how sendmail operates under normal conditions.

Starting and Stopping the sendmail Daemon

Under rare circumstances, a user may need to stop or start the sendmail daemon manually. For example, to implement changes to the configuration file, you must stop all running sendmail processes, "refreeze" the configuration file, and restart the sendmail daemon before the new configuration will take effect. To simplify the task of starting and stopping sendmail, IRIX provides a shell script called /etc/init.d/mail.

This script takes a single argument, either "start" or "stop," which starts or stops the sendmail daemon respectively. You must be superuser (root) to use this script.

When /etc/init.d/mail is called with the "start" argument, it verifies the existence and permissions of various required components of the mail environment. If a required component such as the /var/spool/mqueue directory is missing, the script creates it. For more complex components such as /usr/lib/aliases, the script exits with a message.

When the /etc/init.d/mail script is called with the "stop" argument, it kills all running sendmail processes with a SIGTERM signal.

Note: System startup includes an automatic call to the /etc/init.d/mail script with the start argument. If system startup runs in "verbose" mode (that is, /etc/chkconfig verbose on), the following message appears, verifying that sendmail has been started: Mailerdaemons:sendmail For more information, examine the /etc/init.d/mail script.

Freezing the Configuration File

A "frozen" configuration file (sendmail.fc) is an image of sendmail's data space upon reading in the configuration file. After the sendmail.fc file is created, it is used in place of /usr/lib/sendmail.cf. This process improves startup speed. The regular configuration file is effectively ignored once a frozen configuration file exists.

The following command creates a "frozen" configuration file; the -bz option is required:

/usr/lib/sendmail -bz 

Note: If /usr/lib/sendmail.fc exists, changes to /usr/lib/sendmail.cf are not honored until you rebuild /usr/lib/sendmail.fc. A common mistake is forgetting to re-freeze the configuration after making modifications to /usr/lib/sendmail.cf.sendmail ignores the newly modified /usr/lib/sendmail.cf and continues to use the old frozen configuration. (However, if a /usr/lib/sendmail.fc file exists when sendmail is restarted by means of the /etc/init.d/mail script, a new frozen configuration is created automatically.)

The frozen configuration file is ignored if sendmailis started with a -C flag or if sendmail detects that /usr/lib/sendmail.fc is out of date.

Caution: sendmail's heuristics for detecting that the frozen configuration is out of date are not strong and should not be trusted.

Error Logging

The syslogd(1M) program supports the error log. A large amount of information can be logged. The log is structured in a succession of levels. The lowest level includes only extremely strange or serious situations. The highest level includes even the most mundane and uninteresting events. As a convention, log levels above ten are considered useful only for debugging purposes. For a complete description of log levels, see "Log Level".

The Mail Queue

The mail queue contains messages that could not be delivered immediately. The messages are stored in various queue files that exist under the /var/spool/mqueue directory. Normally, a sendmail subdaemon processes the messages in this queue periodically, attempting to deliver each message. (The /etc/init.d/mail script starts the sendmail daemon so that it will fork a subdaemon every 15 minutes to process the mail queue.)

Each time sendmail processes the queue, it reads and sorts the queue, and then attempts to run all jobs in order. When sendmail attempts to run a job, it first checks to see if the job is locked. If the job is locked, sendmail ignores the job.

On occasion, you may need to process the queue manually. For example, if a major host is down for a period of time, the queue may become clogged. Although sendmail ought to recover gracefully once the host comes up, performance may be unacceptably bad in the interim.

Printing the Queue

You can print the contents of the queue using the mailq command or by specifying the -bp flag to sendmail. The printout includes a listing of the queue IDs, the size of each message, the date the message entered the queue, and the sender and recipients.

Forcing the Queue

The -q flag (with no value) forces sendmail to process the queue. It is sometimes useful to use the -v flag (verbose) also when running the queue manually, as follows:

/usr/lib/sendmail -q -v 

In verbose mode,sendmail displays the SMTP chatter with other hosts as well as messages indicating any delivery errors and final message disposition.

Because of the locking algorithm, it is impossible for one job to freeze the queue. However, an uncooperative recipient host or a program recipient that never returns can consume many system resources. Unfortunately, there is no way to resolve this without violating the SMTP protocol used by sendmail.

In some cases, if a major host goes down for a couple of days, a prohibitively large queue may be created. As a result, sendmail's will spend an inordinate amount of time sorting the queue. You can remedy this situation by moving the queue to a temporary location and creating a new queue. The old queue can be run later when the offending host returns to service.

Use the following commands to move the entire queue directory:

cd /var/spool 
mv mqueue omqueue 
mkdir mqueue 
chmod 755 mqueue 

Then kill the existing sendmail daemon (because it will still be processing in the old queue directory) and create a new daemon:

/etc/init.d/mail stop 
/etc/init.d/mail start 

To run the old mail queue, use the following command:

/usr/lib/sendmail -oQ/var/spool/omqueue -q 

The -oQ flag specifies an alternate queue directory and the -q flag says to run every job in the queue once and then return. Use the -v (verbose) flag to watch what is going on. It may be necessary to run the old mail queue a number of times before all of the messages can be delivered.

When the queue is finally emptied, the directory can be removed:

rmdir /var/spool/omqueue 

The Queue Files

All queue file names take this form:


Where AA99999 is the ID for this file and x is a file type. Valid types include the following:


The data file. The message body (excluding the header) is kept in this file.


This file is created when an ID is being created. It is a separate file to ensure that no mail can ever be destroyed because of a race condition. The file should exist for no more than a few milliseconds at any given time.


The queue control file. This file contains the information necessary to process the job.


A temporary file. This is an image of the qf file when it is being rebuilt. It should be renamed to a qf file very quickly.


A transcript file, existing during the life of a session showing everything that happens during that session.

The qf file is structured as a series of lines each beginning with a code letter. The codes and lines are as follows:


The controlling user. This line defines the name of the controlling user for security purposes. If the message was forwarded, the line is set to the user name of the original message recipient. There can be no more than one of these lines in a qf file.


The name of the data file. There must only be one of these lines in a qf file.


An error address. If any such lines exist, they contain the addresses that should receive error messages.


A header definition. There may be any number of these lines in a qf file. The order is important, as the header lines appear in the final message in the order in which they appear in the qf file. These lines use the same syntax as header definitions in the configuration file.


A message. This line is printed by the mailq command and is generally used to store status information. It can contain any text.


The current message priority. This line is used to order the queue. Higher numbers mean lower priorities. The priority changes as the message sits in the queue. The initial priority depends on the message class and the size of the message.


A recipient address. This line will normally be completely aliased, but is actually re-aliased when the job is processed. There will be one line for each recipient in a qf file.


The sender address. There must only be one of these lines.


The job creation time. This is the time (in seconds since January 1, 1970) that the job was entered into the queue. This value is used to compute when to timeout the job.

The following example is a queue control file for a message sent from jd@iris.company.com to bossman@company.com and buddy@company.com:

S<jd@iris.company.com> R<bossman@company.com> R<buddy@company.com>
Hdate: Fri, 29 Mar 91 23:21:00 GMT 
HFrom: jd (John Doe)
Hfull-name: John Doe
Hsubject: This is an example message
Hmessage-id: <8209232249.AA13557@IRIS.COMPANY.COM>
Hreceived: by IRIS.COMPANY.COM (5.65+bind 1.5+ida/900410.SGI)for
bossman@company.com id AA13557; Fri, 29 Mar 91 23:21:00 GMT
HTo: bossman@company.com, buddy

The lines in the example provide the following information:

The Alias Database

The alias database is an ndbm(3B) database. The text form of the database is maintained in the file /usr/lib/aliases. The alias are of this form:

name: name1 [, name2, ...]

For example, the following command delivers mail addressed to jd to johndoe@company.com:


Caution: Only the local part of addresses may be aliased. For example, the following command is wrong and will not have the desired effect: jd@big.university.edu:jd@company.com.sendmail consults the alias database only after deciding that the message (as originally addressed) should be delivered locally, and after it has rewritten the address to contain only the local part.

Alias continuation lines must start with a space or a tab. Blank lines and lines beginning with the number sign (#) are treated as comments.

If you are running NIS, sendmail can use the contents of the NIS alias database with the local /usr/lib/aliases database by adding the following special alias to the /usr/lib/aliases file:


This special alias tells sendmail to consult the NIS alias database if the alias cannot be found in the local alias database. (Notice that local alias therefore supersede NIS alias.)

Building the Alias Database

At startup sendmail automatically uses the ndbm (3B) routines to process the /usr/lib/aliases file into the files /usr/lib/aliases.dir and /usr/lib/aliases.pag. Using these files to resolve alias is a technique that improves performance.

To rebuild the DBM version of the database without restarting sendmail, execute this command


Executing this command is equivalent to giving sendmail the -bi flag:

/usr/lib/sendmail -bi 

When building the DBM version of the database, sendmail checks the left­hand side of each entry to make sure that it is a local address. sendmail issues a warning for each entry in /usr/lib/aliases with a non-local left­hand side. Such entries are not entered into the DBM version of the database.

If the NIS alias database is used with the local usr/lib/aliases database, the special "+:+" alias is entered into the DBM version of the database. If sendmail cannot find an alias in the DBM version of the database, it looks for the special "+:+" alias. If it finds the special alias, sendmail then queries the NIS alias database. This permits the global NIS alias database to change without having to rebuild the local alias database. However, the left-hand sides of the NIS alias are not checked by sendmail to ensure that they contain only local addresses.

If the configuration or the command line specifies the D option, sendmail will automatically try to rebuild the alias database when it is out of date.

sendmail rebuilds the alias database if either of the following conditions exists:

Auto-rebuild can be dangerous on heavily loaded machines with large alias files. If it takes more than five minutes to rebuild the database, there is a chance that several processes will start the rebuild process simultaneously.

Testing the Alias Database

You can test the alias database as described in "Verify Mode".

Potential Problems

Problems can occur with the alias database, especially if a sendmail process accesses the DBM version before it is completely rebuilt. Two circumstances can cause this problem:

sendmail has two techniques to try to relieve these problems. First, to avoid the problem of a partially rebuilt database, sendmail ignores interrupts while rebuilding the database. Second, at the end of the rebuild it adds an alias of the following form (which is not normally legal):

@: @

Before sendmail accesses the database, it ensures that this entry exists. For this action to occur requires the -a option in the configuration file. Be sure to specify this unless you run delivermail in parallel with sendmail.

If the @ : @ entry does not exist, sendmail waits for it to appear. After the specified waiting period elapses, sendmail will force a rebuild itself. For this action to occur, the configuration file must include the D option. If the D option is not specified, a warning message is generated and sendmail continues.

Another alias problem can arise for systems incorporating the NIS alias database in /usr/lib/aliases through the use of the "+:+" alias. If the NIS alias server goes down or is otherwise nonresponsive to NIS queries, sendmail will not see the alias normally obtained from the NIS server. This situation may result in mail's being returned, marked "User unknown."

List Owners

If an error occurs when mail is sent to a certain address (x, for example), sendmail looks for an alias of the following form to receive the error:


This scheme is typically useful for a mailing list where a user mailing to 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, the following would cause jd@1company.com to get the error that occurs when someone sends mail to unix-hackers and sendmail finds the phony user nosuchuser on the list.

unix-hackers: jd@company1.com, ed@big.university.edu, nosuchuser,   jane@company2.com
owner-unix-hackers: jd@company1.com

Per-User Forwarding

As an alternative to the alias database, a user can put a file with the name .forward in his home directory. If the .forward file exists, sendmail redirects mail for that user to the list of recipients in the file. The recipients are separated by commas or newlines. For example, if the home directory for user jane has a .forward file with the following contents, any mail arriving for jane is redirected to the specified accounts:


The .forward file also allows the user to redirect mail to files or programs. A .forward file with the following contents will redirect any incoming messages to jd@company.com, append a copy of the message to the file /var/tmp/mail.log, and pipe a copy of the message to stdin of the /usr/bin/mymailer program:


In general, file-type recipients must be writable by everyone. However, if sendmail is running as root and the file has setuid or setgid bits set, then the message will be written to the file.

Users can redirect mail to themselves in addition to sending it to other recipients. This is particularly useful if the users want to continue to receive mail in their own mailboxes while passing copies of each incoming message to some alternative destination. For example, say that the home directory for user john contains a .forward file with the following contents:

\john, |/usr/sbin/vacation 

sendmail will behave as follows:

Special Header Lines

The configuration file defines special interpretations for several header lines. In others cases, sendmail defines special interpretations. This section describes these special header lines.


When this header appears in a message, a return-receipt message is sent to the specified addresses when the message is successfully delivered to a mailer with the l flag (for "local delivery") set in the mailer descriptor. The header is added by the program that presents the mail interface to the sender. For example, mail_bsd(1) is one such program.


If errors occur at any time during processing, this header directs error messages to the listed addresses rather than to the sender. The header is automatically added by sendmail when it expands a mailing list. The address of the list owner is inserted into the header. For more information, see the "List Owners" topic contained in "The Alias Database".


If a message arrives with no recipients listed in a "To:," "Cc:," or "Bcc:" line, sendmail will add an "Apparently-To" header line for any recipients it knows. The appearance of an "Apparently-To" header instead of a standard recipient line notifies recipients that the list is not complete.

At least one recipient line is required under RFC 822.

sendmail Command-Line Flags

You can include one or more flags on the command line to tailor a sendmail session. This section describes some of the more frequently used flags. For a complete description of command-line flags, see "Flags, Options, and Files".

Changing the Values of Configuration Options

The -o flag overrides an option in the configuration file. The override is for the current session only. In the following example, the T (timeout) option becomes two minutes for this session only:

/usr/lib/sendmail -oT2m 

For a complete discussion of configuration options, see "Flags, Options, and Files".

Delivery Mode

One configuration option frequently overridden on the command line is the d option, which specifies the sendmail delivery mode. The delivery mode determines how quickly mail is delivered:


deliver interactively (synchronously)


deliver in background (asynchronously)


queue only (don't deliver)

There are trade-offs. Mode i passes the maximum amount of information to the sender, but is rarely necessary.

Mode q puts the minimum load on your system, but if you use it, delivery may be delayed for up to the queue interval.

Mode b is probably a good compromise. However, in this mode, sendmail may initiate a large number of processes if you have a mailer that takes a long time to deliver a message.

Queue Mode

The -q flag causes sendmail to process the mail queue at regular intervals. The syntax is as follows, where time defines the interval between instances of queue processing:

-q [time]

Time is expressed in number of minutes: 15m sets the interval to 15 minutes. If time is omitted, sendmail processes the queue once and returns. The -q flag is often used in conjunction with daemon mode, described in the next subsection.

See "Timeouts and Intervals" for a discussion of time interval specifications and formats.

Daemon Mode

To process incoming mail over sockets, a daemon must be running. The -bd flag causes sendmail to run in daemon mode. The -bd and -q flags can be combined in one call, as in the following example:

/usr/lib/sendmail -bd -q30m

This command causes sendmail to run in daemon mode and to fork a subdaemon for queue processing every half hour.

The script for starting sendmail that is provided with IRIX includes the following command line:

/usr/lib/sendmail -bd -q15m

Verify Mode

Using the -bv flag directs sendmail to validate addresses, aliases, and mailing lists. In this mode sendmail performs verification only. It does not try to collect or deliver a message. sendmail expands all aliases, suppresses duplicates, and displays the expanded list of names. For each name, sendmail indicates if it knows how to deliver a message to that destination.

Test Mode

The -bt flag places sendmail in test mode so that it describes how the current configuration rewrites addresses. Test mode is extremely useful for debugging modifications to the /usr/lib/sendmail.cf configuration file. For more information, see the "Test Mode" topic contained in "Relevant Issues".

Debugging Flags

Several debugging flags are built into sendmail. Each flag includes a number and a level. The number identifies the debugging flag. The level, which defaults to 1, dictates how much information prints. A low level causes minimal information to print; a high level causes more comprehensive information to print. By convention, levels greater than 9 are "absurd," so much information prints that it is of limited value. Debugging flags use the following syntax:

-d debug-list

A debug list includes the flag number and the flag level, as shown in the following examples.

Many debugging flags are of little use to the average sendmail user. Some are occasionally useful for helping to track down obscure problems. "Flags, Options, and Files" includes a complete list of debugging flags.

Using a Different Configuration File

The -C flag directs sendmail to use an alternate configuration file. For example, the following line directs sendmail to use the test.cf file instead of the default /usr/lib/sendmail.cf file:

/usr/lib/sendmail -Ctest.cf 

If the -C flag appears without a file name, sendmail uses the file sendmail.cf in the current directory. Thus, the -C flag directs sendmail to ignore any /usr/lib/sendmail.fc ( "frozen") file that may be present.


A number of configuration parameters are available for fine-tuning sendmail to the requirements of a specific site. Options in the configuration file set these parameters. For example, the string "T3d" sets the T (timeout) option to "3d" (three days).

Most options have default values that are appropriate for many sites. However, sites having very high mail loads may need to tune these parameters to fit the mail load. In particular, sites with a large volume of small messages that are delivered to multiple recipients may need to adjust the parameters for queue priorities.

The rest of this section describes the configuration parameters for the following tuning areas:

Timeouts and Intervals

Time intervals use the following abbreviations:











For example, 10m represents 10 minutes, and 2h30m represents two hours and 30 minutes.

Queue Interval

The argument to the -q flag specifies how often to process the mail queue. When the sendmail daemon is started with the /etc/init.d/mail script, the queue interval is set to 15 minutes.

If sendmail runs in delivery mode b, messages are written to the queue only when they cannot be delivered (for example, when a recipient host is down). Therefore, the need to process the queue is limited and the queue interval value may be set quite high. The value is relevant only when a host that was down comes back up.

If sendmail runs in delivery mode q, the queue interval should be set to a low value, as it defines the longest time that a message sits in the local queue before being processed.

Read Timeouts

sendmail can time out when reading the standard input or when reading from a remote SMTP server. Technically, a timeout is not acceptable within the published protocols. However, setting the read timeout option to a high value (such as an hour) reduces the chance that a large number of idle daemons will pile up on a system. The read timeout option is r.

Message Timeouts

sendmail causes a queued message to time out after a specified time period. This feature ensures that the sender knows the message cannot be delivered. This default message timeout value is one week (seven days). The value is set with the T option.

The queue records the time of submission, rather than the time remaining until timeout. This approach enables sendmail to flush messages that have been hanging for a short period by running the queue with a short message timeout. The following example illustrates how to process the queue and flush any message that is one day old:

/usr/lib/sendmail -oT1d -q 

Forking During Queue Runs

Setting the Y option causes sendmail to fork before each individual message when processing the queue. This technique prevents sendmail from consuming large amounts of memory, and may be useful in memory-poor environments. However, if the Y option is not set, sendmail keeps track of hosts that are down during a queue run, which can improve performance dramatically.

Queue Priorities

sendmail assigns a priority to every message when it is first instantiated. sendmail uses the priority and the message creation time (in seconds since January 1, 1970) to order the queue. The message with the lowest priority number is processed first. The algorithm that derives a message's priority uses the following information:

message size (in bytes)

Small messages receive lower priorities than large messages, increasing the efficiency of the queue.

message class

If the user includes a "Precedence:" field and value in a message, sendmail uses the value to select the message class from the configuration file. (Typical values might be "first-class" or "special-delivery.")

class work factor

This factor is set in the configuration file with the z option; its default value is 1800.

number of recipients

The number of recipients affects the load a message presents to the system. A message with a single recipient has a lower priority than one with a long recipient list.

recipient work factor

This factor is set in the configuration file with the y option; its default value is 1000.

The priority algorithm is as follows:

priority=message_size-(message_class * z)+(num_recipients * y)

After assigning message priorities, sendmail orders the queue by using the following formula:

ordering = priority + creation_time

A message's priority can change each time an attempt is made to deliver it. The "work time factor" (set with the Z option) is a value that increments the priority, on the assumption that a message that has failed many times will tend to fail in the future.

Load Limiting

sendmail can queue (and not attempt to deliver) mail if the system load average exceeds a specified maximum. The x option defines this maximum limit. When the load average exceeds the maximum, sendmail tests each message's priority by using the following algorithm, where q is the value associated with the q option, and x is the value associated with the x option:

q / (load_average - x + 1)

In IRIX sendmail, the algorithm is modified slightly. The number of child processes forked by the sendmail daemon is added to the load average. Thus, a host with a load average of 1 but with six forked sendmail processes has an effective load average of 7.

After the final load average is calculated, sendmail compares it to the message priority for each message. If the priority is greater, sendmail sets the delivery mode to q (queue only).

The default value for the q option is 10000; each point of load average is worth 10000 priority points. The X option defines the load average at which sendmail refuses to accept network connections. Locally generated mail (including incoming UUCP mail) is still accepted.

Log Level

sendmail provides a comprehensive error- and event-logging capability. The L (log level) option in the configuration file determines the level of detail written to the log. The default value for the log level is 1; valid levels are as follows:


no logging


major problems only


message collections and failed deliveries


successful deliveries


messages being deferred (because a host is down, for example)


normal message queue-ups


unusual but benign incidents, such as trying to process a locked queue file


log internal queue ID to external message ID mappings; useful for tracing a message as it travels among several hosts


several messages of interest when debugging


verbose information regarding the queue

The Configuration File

This section begins with an overview of the configuration file, describes its semantics in detail, and includes hints on writing a customized version. Admittedly, the file's syntax is not easy to read or write. A more important design criterion is that the syntax be easy to parse, because it must be parsed each time sendmail starts up.

The Syntax

The configuration file is a series of lines, each of which begins with a character that defines the semantics for the rest of the line. A line beginning with a space or a tab is a continuation line (although the semantics are not well defined in many places). A blank line or a line beginning with the number symbol (#) is a comment.

Rewriting Rules - the S and R Commands

The rewriting rules are the core of address parsing. These rules form an ordered production system. During parsing, sendmail scans the set of rewriting rules, looking for a match on the left-hand side (ls) of the rule. When a rule matches, the address is replaced by the right-hand side (rhs) of the rule.

The rewriting rules are grouped into sets of one or more rules. Each set has an integer identifier called a rulesetnumber. Each rule set acts like a subroutine: When the set is called, each rule is scanned in sequence until all rules have been scanned or until the rule set returns to the caller.

Some rule sets are used internally and have specific semantics. Others do not have specifically assigned semantics and can be referenced by mailer definitions or by other rule sets.

Each rule set begins with an S command, with the syntax


where n is the rule set identifier, an integer between 0 and 99. If the same rule set identifier is used more than once in a configuration file, the last definition is the one used.

Each line within the rule set begins with an R command and defines a rewrite rule. R commands have the syntax

Rlhs rhs [comments]

where the following conditions exist:

Define Macro­the D Command

The D command names a macro and defines its content. A macro name is a single ASCII character. Because sendmail defines several internal macros, care must be taken to avoid using their identifiers. If an identifier is re-used, it effectively redefines the macro. To avoid conflicts, the convention is that the name for any user-defined macro is an uppercase letter. Lowercase letters and special characters are reserved for system use. (A list of sendmail's internally defined macros appears under the topic "Special Macros and Conditionals" in "The Semantics".

The Define Macro command takes one of the following forms:

Dx|shell_command [arguments]

where x is the name of the macro. The first form defines the macro to contain Value. The second form defines the macro as the first line seen on stdout of the specified shell command. The vertical bar must immediately follow the macro identifier; no white space is permitted. The remainder of the line is interpreted as arguments to the shell command.

Macros can be interpolated in most places by means of the escape sequence $x.

Caution: sendmail does not honor comments on macro definition lines. For example, the following line defines the D macro as "foo.com # my domain name": DDfoo.com#mydomainname

Define Classes­the C and F Commands

The C command defines classes of words to match on the left-hand side of rewriting rules, where a "word" is a sequence of characters. A class name is a single uppercase letter. A class might define a site's local names and be used to eliminate attempts to send to oneself. Classes can be defined either directly in the configuration file or by being read in from a pipe or other file. The sequence cannot contain characters used as "operators" in addresses. (Operators are defined with the $o macro.)

The C command takes one of the following forms:

CX word1 [word2 ...]CX $x [$y ...]

where X is the class name. The first form defines the class to match any of the named words. The second form reads the elements of the class from the expansion of the listed macros. The macros to be expanded must be leftmost in each token. Only one macro can be expanded per token. Any remainder in a token following a macro expansion will be added as a separate token.

The F command defines a file from which to read the elements of a class, and takes either of the following forms:

FX file [format]FX|shell_command [arguments]

The first form reads the elements of the class from the named file. If an optional format argument is present, it is passed as the control string to an sscanf(3S) call and applied to each input line read from the named file, thus:

sscanf(const char *line, const char *format, char *new-element);

There must be no white space to the left of the file name.

The second form reads the elements of the class from stdout of the specified shell command. The entire contents of the line are taken to be a shell command followed by its arguments.

It is permissible to split class definitions across multiple lines. For example, the two forms:

CHmonet picasso



are equivalent.

It is also permissible to define a class using both C and F commands. For example the following commands define class H containing monet,picasso, the expansion of the $w macro, and all strings from the file /var/tmp/foofile appearing before the first number symbol (#) on each line:

CHmonet picasso $w
FH/var/tmp/foofile %[^#]

Caution: sendmail does not honor comments are not respected on class definition lines. For example, the following command defines the D class as containing "foo.com," "bar.com," "#," "my," "local," and "domains": CDfoo.combar.com#mylocaldomains

Define Mailer­the M Command

The M command defines programs and interfaces to mailers. The format is as follows:

Mname, {field=value}*

where name is the name of the mailer (used internally only) and the field=value pairs define attributes of the mailer. The asterisk (*) indicates that the preceding bracketed structure may be repeated 0 or more times. That is, there may be multiple field=value pairs. The following list defines valid field names:


The pathname of the mailer


Special flags for this mailer; see "Flags, Options, and Files" for a list of special flags.


A rewriting set for sender addresses.


A rewriting set for recipient addresses.


An argument vector to pass to this mailer.


The end-of-line string for this mailer.


The maximum message length to this mailer.

Only the first character of the field name is checked.

Define Header­the H Command

The H command defines the format of header lines that sendmail inserts into a message. The command format is as follows:

H[?mflags?]hname: htemplate 

Continuation lines for an H command line appear in the outgoing message. sendmail macro-expands the htemplate before inserting it into the message. If mflags (which must be surrounded by question marks) appear in the command line, at least one of the specified flags must also appear in the mailer definition or the header will not appear in the message. However, if a header appears in the input message, the header also appears in the output, regardless of these flags.

Some headers have special semantics, which are described in "The Semantics".

Set Option­the O Command

Several sendmail options can be set by a command line in the configuration file. Each option is identified by a single character.

The format of the O command line is as follows:

Oo value

The command sets option o to value. Depending on the option, value is a string, an integer, a Boolean (with legal values "t ," "T," "f," or "F" and a default of TRUE), or a time interval.

The K option is a new option available in IRIX sendmail. This option defines (K)eyed databases that are accessible by means of the IDA lookup operators. See "Configuration Options" for a complete description of the K option, as well as a list of all configuration options.

Define Trusted Users­the T Command

Trusted users are permitted to override the sender address by using the -f flag. Typically, trusted users are limited to root, uucp, and network. On some systems it may be convenient to include other users. For example, there may be a separate uucp login for each host. Note, though, that the concept of trusted users in sendmail bears no relation to Trusted IRIX/B, or to the concept of trusted (secure) operating systems in general.

The format of the T command is as follows:

Tuser1 user2...

A configuration file can contain multiple T lines.

Define Precedence­the P Command

The P command defines values for the "Precedence:" field. The format of the command line is as follows:


When sendmail matches the value in a message's "Precedence: " field with the name in a P command line, sendmail sets the message's class to num. A higher number indicates a higher precedence. Numbers less than zero indicate that error messages will not be returned to the sender. The default precedence is zero. For example, a list of precedences might be:


The Semantics

This section describes the semantics of the configuration file, including special macros, conditionals, special classes, and the "error" mailer.

Special Macros and Conditionals

Macros are interpolated by means of the construct $x, where x is the name of the macro to be interpolated. Special macros are named with lowercase letters; they either have special semantics or pass information into or out of sendmail. Some special characters are also reserved, and are used to provide conditionals and other functions.

The following syntax specifies a conditional:

$?x text1 $| text2 $.

This example interpolates text1 if the macro $x is set, and text2 otherwise.

The "else" ($|) clause can be omitted.

The following macros mustbe defined if information is to be transmitted into sendmail:


SMTP entry message, which prints out when STMP starts up


"official" domain name for this site; must be the first word of the $e macro


format of the UNIX "from" line; usually a constant


name of the daemon (for error messages); usually a constant


set of token operators in addresses


default format of sender address

The $o macro consists of a list of characters that are treated as tokens themselves and serve to separate tokens during parsing. For example, if @ were in the $o macro, then the input string "a@b" would scan as three tokens: a, @, and b.

Here are several examples of these macro definitions:

De$j Sendmail $v/$Z ready at $b
DlFrom $g  $d
Dq$g$?x ($x)$.

An acceptable alternative format for the $q macro is "$?x$x $.<$g>" . This syntax corresponds to the following two formats:

jd@company.com (John Doe)
John Doe <jd@company.com>

Some macros are defined by sendmail for interpolation into argv's for mailers or for other contexts. These macros are:


origination date in RFC 822 format


current date in RFC 822 format


hop count


date in UNIX (ctime) format


sender ("From") address


sender address relative to the recipient


recipient host


queue ID


pid for sendmail


protocol used


sender's host name


a numeric representation of the current time


recipient user


version number of sendmail


host name of this site


full name of the sender


home directory of the recipient

Macros $a, $b, and $d specify three dates that can be used. The $a and $b macros are in RFC 822 format. $a is the time extracted from the "Date:" line of the message; $b is the current date and time (used for postmarks). If no "Date:" line appears in the incoming message, $a is also set to the current time. The $d macro is equivalent to the $a macro in UNIX (ctime) format.

The $c macro is set to the "hop count," the number of times this message has been processed. It can be determined by the -h flag on the command line or by counting the time stamps in the message.

The $f macro is the ID of the sender as originally determined; when a message is sent to a specific host, the $g macro is set to the address of the sender relativetotherecipient. For example, if jd sends to buddy@USomewhere.edu from the machine company.com, the $f macro will be jd and the $g macro will be jd@company.com.

When a message is sent, 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 $i macro is set to the queue ID on this host; when included in the time-stamp line, it can be extremely useful for tracking messages.

The $p and $t macros are used to create unique strings (for example, for the "Message-Id:" field). The $r and $s macros are set to the protocol used to communicate with sendmail and the name of the sending host; these macros are not supported in the current version.

The $v macro is set to be the version number of sendmail, which normally appears in time stamps and is extremely useful for debugging. The $w macro is set to the name of this host, if it can be determined.

The $x macro is set to the full name of the sender, derived from one of these sources (in this order):

Special Classes

The w class is set to be the set of all names this host is known by, and can be used to match local host names.

The Left-Hand Side

The left-hand side of rewriting rules contains a pattern. Words are simply matched directly. A dollar sign introduces the following meta-syntax:


Match zero or more tokens.


Match one or more tokens.


Match exactly one token.


Match any token in class x.


Match any token not in class x.

If a match occurs, it is 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:


is applied to the input:


the rule will match, and the values passed to the rhs will be:





The Right-Hand Side

When the left-hand side of a rewriting rule matches, the input is deleted and replaced by the right-hand side. Right-hand-side tokens are inserted exactly as they appear unless they begin with a dollar sign. The meta-syntax is:


Substitute indefinite token n from lhs; substitute the corresponding value from a $+, $-, $*, $=, or $~ match on the lhs; can be used anywhere.


Canonicalize hostname; a host name enclosed between $[ and $] is looked up by the gethostbyname(3N) routines and replaced by the canonical name. For example, $[frodo$] might become frodo.fantasy.com and $[[]$] would become sgi.com. In the event that gethostbyname(3N) encounters an error, hostname will be returned unchanged.


This is an extended version of the preceding construct, and provides a way to determine whether the canonicalization was successful. Using this syntax, the default is returned if the canonicalization step fails. For example, $[frodo$:FAIL$] would become FAIL if gethostbyname(3N) fails to canonicalize frodo.

$(x key$@arg$:default$)

Look up key in DBM or NIS database x. This is the IDA database lookup syntax; x corresponds to a database previously declared using the K option (described in "Configuration Options") and key is the string that should be searched for in the database. The arg and default arguments are optional. The default is returned if the key was not found in the database. If neither the default nor a matching key is found, the whole expression expands to the value of key. However, if a result is found, it is used as the format string of a sprintf(3S) expression, with the arg as extra argument. Thus, database values with "%s" strings embedded in them can be useful when rewriting expressions. These values could typically be used with the pathalias program to expand routes without leaving sendmail.

${x query$:default$}

Look up query in DNS database x. This is the DNS database lookup syntax. The various values of x are internally defined and correspond to various DNS databases. The default argument is optional and will be returned in the event that query cannot be found in the specified database.

The values for x are:

@ Return MX record for query.

. As above, but use domain search rules.

: Return MR record for query.

? Return MB record for query.

c Expand query to its canonical name following MX records.

C As above, but use domain search rules.

h Like ${c but for A records.

H As above, but use domain search rules.

When domain search rules are requested, sendmail sets the RES_DNSRCH flag when calling the resolver. See the resolver(3N) man page for further information.


Call rule set n; 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 becomes the substitution for this construct.

Multiple calls can be embedded on the rhs. For example, $>32$>33$1 would make the substitution for $1 and pass the result to rule set 33. The result from rule set 33 would then be passed as the input to rule set 32. Finally, the entire construct would be replaced with the result from rule set 32.

Only embedded rule set calls in the form outlined above are supported. Rule sets calls cannot be arbitrarily placed within the rhs.


Resolve to mailer; the $# syntax should be used only in rule set 0. The syntax causes evaluation of the rule set to terminate immediately and signals sendmail that the address has completely resolved. This process specifies the {mailer, host, user} triple necessary to direct the mailer. If the mailer is local, the host part may be omitted. The mailer and host must be a single word, but the user may be a multi-part value.

An entire rhs may also be prefixed by a $@ or a $: to control evaluation.

The $@ prefix causes the rule set to return with the remainder of the rhs as the value. The $: 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 $> specification. For 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: Parameters from the lhs are substituted, host names are canonicalized, "subroutines" are called, and finally $#, $@, and $: are processed.

Semantics of Rewriting Rule Sets

There are five rewriting rule sets that have specific semantics. Figure D-2 shows the relationship among these rule sets.


Figure D-2 : Semantics of Rewriting Rule Sets

Rule set 3 should turn the address into canonical form. This form should have the following basic syntax:


If no "at" (@) sign is specified, then the host-domain-spec can be appended from the sender address (if the C flag is set in the mailer definition corresponding to the sending mailer). sendmail applies rule set 3 before doing anything with any address.

Next, rule set 0 is applied to an address that actually specifies recipients. The address must resolve to a {mailer,host,user} triple. 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 addresses, 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 from internal to external form.

The "error" Mailer

The mailer with the special name "error" can be used to generate a user error. The (optional) host field is a numeric exit status to be returned, and the user field is a message to be printed. For example, the following entry on the rhs of a rule causes the specified error to be generated if the lhs match:

$#error$:Host unknown in this domain

This mailer is functional only in rule set 0.

Relevant Issues

This section discusses testing and debugging the rewrite rules and building mailer definitions.

Testing and Debugging the Rewrite Rules

As part of building or modifying a configuration file, you should test the new file. sendmail provides a number of built-in tools to assist in this task. The subsections that follow discuss tools and techniques for debugging the rewrite rules.

Using Alternative Configuration Files

Using the -C command-line flag causes sendmail to read an alternate configuration file. This feature is helpful during debugging because it permits modifications and testing on a separate copy of the configuration file from the one currently in use. This precaution eliminates the chance that a buggy configuration file will be used by an instance of sendmail that is trying to deliver real mail. This flag also provides a convenient way to test any number of configuration files without fussy and potentially confusing renames. See "Using a Different Configuration File" and "Command-Line Flags" for more information.

Test Mode

Invoking sendmail with the -bt flag causes it to run in "test mode." For example, the following command invokes sendmail in test mode and causes it to read configuration file test.cf:

/usr/lib/sendmail -bt -Ctest.cf 

In this mode, sendmail processes lines of the form:

rwsets address 

where rwsets is the list of rewriting sets to use and address is an address to which to apply the sets. In test mode, sendmail shows the steps it takes as it proceeds, finally showing the final address.

A comma-separated list of rule sets causes sequential application of rules to an input. For example, the following command first applies rule set 3 to the value monet@giverny. Rule set 1 is applied to the output of rule set 3, followed similarly by rule sets 21 and 4:

3,1,21,4 monet@giverny

Note: Some versions of sendmail, including those provided with all versions of IRIX prior to IRIX 4.0, automatically apply rule set 3 to input before applying the requested rule set sequence. Versions of sendmail in IRIX 4.0 and later do not apply rule set 3; rule set 3 must be specifically requested.

The input and output of each rule set is displayed. For example, input of:

3,0 foo@bar

might result in output that looks like this:

rewrite: ruleset 3 input: foo @ bar
rewrite: ruleset 3 returns: foo < @ bar >
rewrite: ruleset 0 input: foo < @ bar > 
rewrite: ruleset 30 input: foo < @ bar . com > 
rewrite: ruleset 30 returns: foo < @ bar . com > 
rewrite: ruleset 0 returns: 
$# forgn $@ bar . com $: foo < @ bar . com > 

This output indicates that, given the address foo@bar, rule set 0 will select the forgn mailer and direct it to connect to host bar.com, which will be told to send the mail on to foo@bar.com. Furthermore, rule set 0 "called" rule set 30 at one point while processing the address.

The -d21 Debugging Flag

The -d21 debugging flag causes sendmail to display detailed information about the rewrite process. This flag is most useful when used with the test mode described in the preceding subsection. The most useful setting of this flag is -d21.12, which shows all rewrite steps. Higher levels of the -d21 flag are rarely needed and create enormous amounts of output.

The Debugging Rewrite Rule

The standard /usr/lib/sendmail.cf file supplied with IRIX includes a special "debugging" rewrite rule. This rule is defined as follows:

# insert this handy debugging line wherever you have  # problems
#R$*                            $:$>99$1

Note that rule set 99 is an empty rule set that does nothing. Placing one or more (uncommented) copies of this rule anywhere within a rule set forces sendmail to display an intermediate rewrite result without using the -d21 flag. The following test mode output illustrates the use of the debugging rewrite rule:

rewrite: ruleset 3 input: foo @ bar
rewrite: ruleset 3 returns: foo < @ bar > 
rewrite: ruleset 0 input: foo < @ bar > 
rewrite: ruleset 99 input: foo < @ bar . com > 
rewrite: ruleset 99 returns: foo < @ bar . com > 
rewrite: ruleset 99 input: foo < @ barcom > 
rewrite: ruleset 99 returns: foo < @ barcom > 
rewrite: ruleset 0 returns: 
$# ether $@ barcom $: foo < @ barcom >

Note that somewhere between the first and second appearance of the debugging rewrite rule in rule set 0, the host name was mangled from




Building Mailer Definitions

To add an outgoing mailer to a mail system, you must define the characteristics of the mailer. Each mailer must have an internal name. This name can be arbitrary, except that the names "local" and "prog" must be defined.

The pathname of the mailer must be given in the P field. If this mailer should be accessed by means of an IPC connection (socket), use the string "[IPC]" instead.

The F field defines the mailer flags. Specify an f or r flag to pass the name of the sender as an -f or -r flag respectively. These flags are passed only if they were passed to sendmail, so that mailers that give errors under some circumstances can be placated. If the mailer is not picky, just specify "-f $g" in the argv template. If the mailer must be called as root, use the S flag; this flag will not reset the userid before calling the mailer. (sendmail must be running setuid to root for this technique to work.)

If this mailer is local (that is, it will perform final delivery rather than another network hop), use the l flag. Quote characters (backslashes and quotation marks) can be stripped from addresses if the s flag is specified; if it is not, they are passed through. If the mailer is capable of sending to more than one user on the same host in a single transaction, use the m flag. If this flag is on, the argv template containing $u will be repeated for each unique user on a given host. The e flag will mark the mailer as being expensive, causing sendmail to defer connection until a queue run. (For this technique to be effective, you must use the c configuration option.)

An unusual case is the C flag: It applies to the mailer the message is received from, rather than the mailer being sent to. If this flag is set, the domain specification of the sender (that is, the @host.domain part) is saved and is appended to any addresses in the message that do not already contain a domain specification. For example, a message of the form:

From: jd@company.com
To: buddy@USomewhere.edu, jane

will be modified to:

From: jd@company.com
To: buddy@USomewhere.edu, jane@company.com

if the C flag is defined in the mailer corresponding to jd@company.com.

Other flags are described in "Mailer Flags".

The S and R fields in the mailer description are per-mailer rewriting sets to be applied to sender and recipient addresses, respectively. These sets are applied after the sending domain is appended and the general rewriting sets (sets 1 and 2) are applied, but before the output rewrite (rule set 4) is applied. A typical usage is to append the current domain to addresses that do not already have a domain.

For example, a header of the form:

From: jd

might be changed to:

From: jd@company.com


From: company!jd

depending on the domain it is being shipped into.

These sets can also be used to do special-purpose output rewriting with rule set 4.

The E field defines the string to use as an end-of-line indication. A string containing only a newline is the default. The usual backslash escapes (\r, \n, \f, \b) can be used.

Finally, an argv template is given as the E field. It can have embedded spaces. If there is no argv with a $u macro in it, sendmail will speak SMTP to the mailer. If the pathname for this mailer is "[IPC]," the argv should be

IPC $h [ port ]

where port is the port number to connect to. This number is optional.

For example, the following specification specifies a mailer to do local delivery and a mailer for Ethernet delivery:

Mlocal, P=/bin/mail, F=EDFMlsmhu, S=10, R=20, A=mail -s -d $u 
Mether, P=[IPC], F=mDFMhuXC, S=11, R=21, M=1000000, E=\r\n, \
       A=IPC $h 

The first mailer is called "local" and is located in the file /bin/mail. It has the following characteristics:

Rule set 10 is to be applied to sender addresses in the message and rule set 20 is to be applied to recipient addresses. The argv to send to a message will be the word mail, the word -s , the word -d and words containing the name of the receiving user.

The second mailer is called "ether" and is connected with an IPC connection. It has the following characteristics:

Sender addresses are processed by rule set 11; recipient addresses, by rule set 21. There is a 1,000,000-byte limit on messages passed through this mailer. The EOL string for this mailer is "\r\n" and the argument passed to the mailer is the name of the recipient host.

Flags, Options, and Files

This section contains information on the following topics:

Command-Line Flags

Flags must precede addresses. The flags are:


Set operation mode to x. Operation modes are:


Run in ARPANET mode.


Run as a daemon.


Initialize the alias database.


Deliver mail in the usual way (default).


Print the mail queue.


Speak SMTP on input side.


Run in test mode.


Just verify addresses, don't collect or deliver.


Freeze the configuration file.

The special processing for the ARPANET includes reading the "From:" and "Sender:" lines from the header to find the sender, printing ARPANET-style messages (preceded by three-digit reply codes for compatibility with the FTP protocol) and ending lines of error messages with <CRLF>.


Use a different configuration file. sendmail runs as the invoking user (rather than root) when this flag is specified.


Set debugging flag (or range of flags) to the specified level. (The default is 1.) See "Debugging Flags".


Set the full name of the sender to name.

-f name

Set the name of the "From" person (the sender of the mail). This flag is ignored unless the user appears in the list of "trusted" users, or the person the user is trying to become is himself.

-h cnt

Set the "hop count" to cnt. The hop count is incremented every time the mail is processed. When it reaches a limit, the mail is returned with an error message, the victim of an aliasing loop.


Don't do aliasing.

-ox value

Set configuration option x to the specified value. These options are described in section "Configuration Options".


Process the queued mail. If the time is given, sendmail will run through the queue at the specified interval to deliver queued mail; otherwise, it only runs once. See "Queue Mode".

-r name

An alternative and obsolete form of -f.


Read the header for "To:", "Cc:", and "Bcc:" lines, and send the message to everyone listed in those lists. The "Bcc:" line is deleted before sending. Any addresses in the argument vector are deleted from the send list.


Go into verbose mode: Alias expansions are announced, and so on.

Configuration Options

You can set the following options by using the -o flag on the command line or the O line in the configuration file. Many of these options cannot be specified unless the invoking user is trusted.


Use the named file as the alias file. If no file is specified, use alias in the current directory.


If set, wait up to N minutes for an "@:@" entry to exist in the alias database before starting up. If the entry does not appear in N minutes, rebuild the database (if the D option is also set) or issue a warning.


Set the blank substitution character to c. Unquoted spaces in addresses are replaced by this character.


If an outgoing mailer is marked as being expensive, don't connect immediately. This option requires queueing.


Deliver in mode x. Legal modes are:


Deliver interactively (synchronously).


Deliver in background (asynchronously).


Just queue the message (deliver during queue run).


Rebuild the alias database if necessary and possible. If this option is not set, sendmail will never rebuild the alias database unless you explicitly request it to do so (by using sendmail-bi).


Handle errors by using mode x. The values for x are:

p Print error messages (default).

q Print no messages; just give exit status.

m Mail back errors.

w Write back errors (mail the errors if user not logged in).

e Mail back errors and always give zero exit status.


Set the UNIX file mode to use when creating queue files and "frozen configuration" files.


Save UNIX-style "From" lines at the front of headers. Normally these lines are assumed to be redundant and are discarded.


Set the default gid for running mailers to n.


Specify the help file for SMTP.


Insist that the BIND name server be running to resolve host names and MX records. Treat ECONNREFUSED errors from the resolver as temporary failures. In general, you should set this option only if you are running the name server. Set this option if the /etc/hosts file does not include all known hosts or if you are using the MX (mail forwarding) feature of the BIND name server. The name server is still consulted even if this option is not set, but sendmail resorts to reading /etc/hosts if the name server is not available.


Do not interpret dots on a line by themselves as a message terminator.


Define the internal keyed database x and associate it with the external database file;x is a single character database name. If the percent sign (%) is present, file is the name of an NIS database. If the percent signr is absent, file is the name of a ndbm(3B) database. After a keyed database is defined, you can use it to look up arbitrary strings in the right-hand side of rewriting rules, by using the IDA lookup operator $($). The /usr/lib/aliases file is automatically available if you are using the "@" database and should not be declared with the K option.


Set the log level to n.

Mx value

Set the macro x to value. This option can be used only from the command line.


Send to "me" (the sender) even if the sender is in an alias expansion.


Set the name of the home (local) network. If the name of a connecting host (determined by a call to gethostbyaddr(3N)) is unqualified (contains no dots), a single dot and netname will be appended to sendmail's idea of the name of the connecting host.

Later, the argument of the SMTP "HELO" command from the connecting host will be checked against the name of the connecting host as determined above. If they do not match, "Received:" lines are augmented by the connecting host name that sendmail has generated so that messages can be traced accurately.


Validate the right-hand side when building the alias database.


Assume that the headers may be in an old format, in which spaces delimit names. This option actually turns on an adaptive algorithm: If any recipient address contains a comma, parenthesis, or angle bracket, it will be assumed that commas already exist. If this flag is not on, only commas delimit names. Headers are always put out with commas between the names.


Add "postmaster" address addr to the "Cc:" list of all error messages.


Use dir as the queue directory.


Use factor as the multiplier in the function to decide when to queue messages rather than attempting to send them. This value is divided by the difference between the current load average and the load average limit (x option) to determine the maximum message priority that will be sent. This value defaults to 10000.


Cause a timeout on reads after time interval.


Log statistics in the named file.


Be super-safe when running; that is, always instantiate the queue file, even if attempting immediate delivery. sendmail always instantiates the queue file before returning control to the client under any circumstances.


Set the queue timeout to time. After this interval, messages that have not been successfully sent are returned to the sender.


Set the default userid for mailers to n. Mailers without the S flag in the mailer definition run as this user.


Run in verbose mode.


Use LA as the system load average limit when deciding whether to queue messages rather than attempting to send them.


When the system load average exceeds LA, refuse incoming SMTP connections.


This factor is multiplied by the number of recipients and added to the priority. Therefore, this value penalizes messages with large numbers of recipients.


Deliver each job that is run from the queue in a separate process. Use this option if you are short of memory, since the default tends to consume considerable amounts of memory while the queue is being processed.


This factor is multiplied by the message class (determined by the "Precedence:" field in the user header and the precedence declaration lines in the configuration file) and subtracted from the priority. Therefore, messages with a higher class will be favored.


This factor is added to the priority every time a message is processed. Therefore, this value penalizes messages that are processed frequently.

Mailer Flags

The following flags can be set in the F field of a mailer definition in the sendmail.cf file:


Don't wait for SMTP responses.


If mail is received from a mailer with this flag set, any addresses in the header that do not have an "at" sign (@) after being rewritten by rule set 3 have the "@domain" clause from the sender appended. This flag allows mail with headers of the form:
From: usera@hosta
To: userb@hostb, userc
to be rewritten automatically as:
From: usera@hosta
To: userb@hostb, userc@hosta

This mailer wants a "Date:" header line.


Escape any lines beginning with "From" in the message with a ">" sign.


This mailer is expensive to connect to; usually, avoid connecting. Any necessary connection occurs during a queue run.


The mailer wants a "From:" header line.


The mailer wants a -ffrom flag, but only if this is a network forwarding operation. (That is, the mailer will give an error if the executing user does not have special permissions).


Uppercase should be preserved in host names for this mailer.


This mailer will be speaking SMTP to another sendmail and can use special protocol features. This option is not required; if it is omitted, the transmission still operates successfully, although perhaps not as efficiently as possible.


Limit the line lengths as specified in RFC 821.


This mailer is local; final delivery will be performed.


This mailer wants a "Message-Id:" header line.


This mailer can send to multiple users on the same host in one transaction. When a $u macro occurs in the argv part of the mailer definition, that field will be repeated as necessary for all qualifying users.


Do not insert a UNIX-style "From" line on the front of the message.


This mailer wants a "Return-Path:" line.


Use the return-path in the SMTP "MAIL FROM:" command rather than just the return address; although this usage is required in RFC 821, many hosts do not process return paths properly.


Same as f, but sends an -r flag.


Don't reset the userid before calling the mailer. Used in a secure environment where sendmail runs as root, this option could avoid forged addresses. This flag is suppressed if given from an "unsafe" environment (such as a user's mail.cf file).


Strip quotation characters from the address before calling the mailer.


This mailer wants UNIX-style "From" lines with the UUCP-style "remote from <host>" on the end.


Preserve uppercase characters in user names for this mailer.


Make all addresses UUCP !-relative to recipient/sender nodes. Addresses of the form recipient_host!foo!bar are rewritten as foo!bar. Addresses of the form mumble!grumble are rewritten as sender_host!mumble!grumble.


This mailer wants to use the hidden-dot algorithm as specified in RFC 821; basically, any line beginning with a dot will have an extra dot prepended (to be stripped at the other end). This action ensures that a line containing a dot will not terminate the message prematurely.


This mailer wants a "Full-Name:" header line.

Support Files

This section provides a summary of the support files that sendmail creates or generates.


The sendmail program.


The configuration file in textual form.


A link to /usr/lib/sendmail; causes the alias database to be rebuilt. Running this program is equivalent to giving sendmail the -bi flag.


The configuration file represented as a memory image (the "frozen configuration").


The SMTP help file.


A statistics file; need not be present.


A text file that contains the names of all known "dead" hosts (hosts that no longer exist or cannot receive mail for some reason).


The textual version of the alias file.


The alias file in ndbm(3B) format.


The directory in which the mail queue and temporary files reside.


Control (queue) files for messages.


Data files.


Temporary versions of the qf files, used during queue-file rebuild.


A file used when a unique ID is created.


A transcript of the current session.


Prints a listing of the mail queue; using this file is equivalent to using the -bp flag to sendmail.


Shell script for starting and stopping the sendmail daemon.


Program that sendmail uses as the "local" mailer.

Debugging Flags

The following list includes all known debugging flags. Flags that are especially useful are marked with an asterisk (*).


Force daemon to run in foreground.


Show known names for local host.


Print configuration file.


Have printav() print addresses of elements.


Show mail "From" address for locally generated mail.


Print exit status and envelope flags.


Print arguments to tick() calls.


Print arguments to setevent() and clrevent() calls.


Print event queue on tick() call.


Indicate call to savemail() or returntosender() error processing.


Trace states in savemail() state machine.


Print information on envelope assigned to queue file.


Print selected queue-file name.


Print intermediate queue-file name selections.


Print various information about resolver calls.


Show results from gethostbyaddr() call.


Print message delivery information.


Indicate call to openmailer().


Display remotename() input and output.


sendall() - print addresses being sent to


sendall() - print each address in loop looking for failure.


sendall() - print who gets the error.


Indicate commaize() calls.


Indicate port or socket number used by getrequests().


Indicate when getrequests() forks or returns.


Set DEBUG socket option in getrequests().


Indicate host, address, and socket being connected to in makeconnection().


Set DEBUG socket option in makeconnection().


Show SMTP chatter.


Suspend sendmail after reading each SMTP reply.


Display parseaddr() input and output.


Show rewrite rule-set subroutine calls/returns and input/output, and display run-time macro expansions.


Indicate rewrite subroutine call from inside rewrite rule.


Display rewrite results.


Indicate rule failures.


Indicate rule matches and display address-rewrite steps.


Show rewrite substitutions.


Display elements in pattern and subject.


Display prescan() processing.


Display more prescan() processing.


Display even more prescan() processing.


Show "To" list designations.


Show recipient designations/duplicate suppression.


Show recipient password-match processing.


Print alias and forward transformations and errors.


Print detailed aliaslookup() information.


Indicate End Of Headers when collecting a message.


Print arguments to eatfrom() calls.


Indicate when adding an "Apparently-To" header to the message.


Indicate call to chompheader() and header to be processed.


Display collected header.


Display crackaddr() input/output.


Display macro definitions.


Display macro expansions.


Show symbol table processing.


Show symbol table hash function result.


Display options as set.


Show rewrite class loading.


Indicate queueing of messages and display queue contents.


Display queue control file contents.


Display information about message-controlling user.


Indicate orderq() failure to open control file.


Indicate setsender() calls.


Indicate dropenvelope() calls.


Don't remove transcript files (qxAAXXXXX files).


Indicate call to disconnect(); print I/O file descriptors.


Don't do disconnect.


Print information about alias database accesses.


Print information about MX record lookups.

[Previous Section] [Back to Table of Contents] [Next Section]

Send feedback to Technical Publications.

Copyright © 1997, Silicon Graphics, Inc. All Rights Reserved. Trademark Information