Table of Contents for

sendmail, 4th Edition

The -E switch can be used with M4= to select your preferred version of m4(1). If, for example, you prefer GNU’s version over the vendor’s version, you can run Build like this:

% ./Build -E M4=/usr/local/gnu/bin/m4
...
Using M4=/usr/local/gnu/bin/m4

The -E switch can be used with MAKE= to select a different version of make(1) than the one that is currently first in your path. If, for example, you prefer your homegrown make(1), you could run Build like this:

% ./Build -E MAKE=/usr/local/newbin/make

The -E switch can be used with DESTDIR= to install sendmail, its symbolic links (such as newaliases), its manual pages, and its support programs (such as praliases) under a whole new directory. One reason for using another directory might be to install sendmail for use by diskless machines. Consider this ordinary install:

% ./Build install
Configuration: pfx=, os=SunOS, rel=5.10, rbase=5, rroot=5.10, arch=sun4, sfx=, variant
=optimized
if [ ! -d /etc/mail ]; then mkdir -p /etc/mail; fi
... etc

Now consider the same install using the DESTDIR= environment variable:

% ./Build -E DESTDIR=/export/sun4 install
Making in ../obj.SunOS.5.10.sun4/sendmail
if [ ! -d /export/sun4/etc/mail ]; then mkdir -p /export/sun4/etc/mail; fi
... etc

Because this prefixing is a part of the Makefile, the DESTDIR environment variable prefixes all the directories defined with the m4 technique (described in DESTDIR= on page 349).

Use an alternative sendmail configuration file editmap command-line switch

If the TrustedUser option (TrustedUser on page 1112) is set in the sendmail configuration file, and if editmap was compiled with HASFCHOWN defined as 1, and if editmap is run by root, the output file will become owned by the user specified in the TrustedUser option. The editmap program finds the TrustedUser option by reading and parsing the sendmail program’s configuration file (normally /etc/mail/sendmail.cf). But if you want editmap to use a different configuration file, you can specify that different file with this -C switch. For example:

# editmap -x -C /etc/mail/sendmail.cf.new hash spamhosts host.spam-site.com

Here, we use editmap to delete the key host.spam-site.com from the database spamhosts. Because editmap was run by root (the # prompt), editmap looks up the TrustedUser option in the alternative configuration file specified by the -C (/etc/mail/sendmail.cf.new). If that option had, for example, a value of bin, editmap would set the owner of the database to bin.

Don’t fold uppercase to lowercase editmap command-line switch

Normally, the key is converted to lowercase before being stored in the database makemap. When the key entries are case-sensitive, the -f switch is used by makemap to prevent conversion to lowercase. This -f command-line switch causes editmap to match that behavior when looking up a key. When the -f is absent, the key specified in the command line is converted to lowercase before it is looked up. If the -f is present, the key is looked up as is.

In general, if the configuration file’s corresponding K command for a database uses the -f, you should also use -f when running editmap on that database file.

Append a null byte to all keys editmap command-line switch

The database files used for aliases always store keys with a null byte appended to each. When you use editmap on such a file, your key will not be found:

% editmap -q hash list-aliases user
editmap: couldn't find key user in map list-aliases

This lookup failed because editmap normally omits a trailing null from a key before looking up its value. When looking up keys in aliases-style databases, you need to use the -N command-line switch to append a null to a key before a lookup:

% editmap -q -N hash list-aliases user

Some database files (other than aliases) also append a null byte to keys. These databases will appear with a corresponding -N in a K configuration file line. In such instances, you must use -N with editmap to match the K line’s -N.

Query for specified key editmap command-line switch

The editmap program must be run with one of three mandatory command-line switches. This -q switch is one of those three.

The -q command-line switch tells editmap to open the database file in read-only mode, and look up and print the value of the key:

% editmap -q dbtype dbfile sought-key

If the dbfile lacks read permission, the following error will print and editmap will exit with an EX_IOERR (EX_IOERR on page 229) exit value:

editmap: error opening type dbtype map dbfile: Permission denied

If the sought-key is found, its value is printed and editmap exits with a zero exit value. If the sought-key is not found, editmap prints the following error and exits with an EX_UNAVAILABLE (EX_UNAVAILABLE on page 230) exit value:

editmap: couldn't find key sought-key in map dbfile

If you get this error when reading aliases-style database files, consider adding the -N command-line switch.

Update the key with a new value editmap command-line switch

The editmap program must be run with one of three mandatory command-line switches. This -u switch is one of those three.

The -u command-line switch tells editmap to open the database file in read/write mode, to look up the key, and to replace that key’s value. If the key is not already in the database, both the key and its value are added to the database:

% editmap -u dbtype dbfile sought-key new-value

If the dbfile lacks read/write permission, the following error will print and editmap will exit with an EX_IOERR (EX_IOERR on page 229) exit value:

editmap: error opening type dbtype map dbfile: Permission denied

If the sought-key is found, its value is replaced with the new-value. If the sought-key is not found, both the key and value are added to the database.

Be careful updating aliases-style database files. If you omit the -N command-line switch with such files, your key will not be found even if it exists, and thus the key and value will wrongly, and silently, update the database. To illustrate, consider this alias:

bob: bob@another.host.domain

If bob moves, you might want to directly edit this aliases-style database to change his address. Here is the correct way to update:

% editmap -N -q hash offsite-aliases bob
bob@another.host.domain
% editmap -N -u hash offsite-aliases bob bob@new.domain
% editmap -N -q hash offsite-aliases bob
bob@new.domain

Here, because offsite-aliases is an aliases-style database, we use the -N command-line switch with all commands. The first and last commands look up (with -q) bob in the database. The second command changes the address for bob.

In the following, we omit the -N from the update command. This is the wrong way to update such a database:

% editmap -N -q hash offsite-aliases bob
bob@another.host.domain
% editmap -u hash offsite-aliases bob bob@new.domain   ← note no -N
% editmap -N -q hash offsite-aliases bob
bob@another.host.domain                                ← note no update
% editmap -q hash offsite-aliases bob
bob@new.domain                                         ← note bogus update

The key bob is in the database, but with a trailing null byte. The update command (the -u) omits the -N and so omits a trailing null byte from the looked-up key. As a result, the key is not found, so the key and value are wrongly added as a new key/value pair to the database. The last two commands illustrate the problem. The first correctly uses the -N and finds that the value was not updated. The second incorrectly omits the -N and finds that another bob (the one without the trailing null byte) got the update.

Delete key from database editmap command-line switch

The editmap program must be run with one of three mandatory command-line switches. This -x switch is one of those three.

The -x command-line switch tells editmap to open the database file in read/write mode, to look up the key, and, if found, to delete the key and its value from the database:

% editmap -x dbtype dbfile sought-key

If the dbfile lacks read/write permission, the following error will print and editmap will exit with an EX_IOERR (EX_IOERR on page 229) exit value.

editmap: error opening type dbtype map dbfile: Permission denied

If the sought-key is found, it and its value are silently deleted from the database. If the sought-key is not found, editmap prints the following error and exits with an EX_UNAVAILABLE (EX_UNAVAILABLE on page 230) exit value:

editmap: couldn't find key sought-key in map dbfile

If you get this error when reading aliases-style database files, consider adding the -N command-line switch.

Don’t advertise 8BITMIME in LMTP mail.local command-line switch

Ordinarily, when mail is delivered using LMTP, the LMTP conversation begins like this:

220 yourhost LMTP ready                 ← mail.local sends
>>> LHLO yourhost.your.domain           ← sendmail sends
250-yourhost                            ← mail.local sends
250-8BITMIME                            ← note
250-ENHANCEDSTATUSCODES
250 PIPELINING

Here, mail.local is telling sendmail (in the fourth line) that it can correctly handle 8-bit MIME (EightBitMode on page 1025) in received messages. If your site is a 7-bit only site, you should not allow mail.local to accept 8-bit MIME messages. You disallow 8-bit MIME by specifying this −7 command-line switch:

FEATURE(`local_lmtp')
define(`LOCAL_MAILER_ARGS', `mail.local −l −7')

Here, the −7 command-line switch causes mail.local to exclude -8BITMIME from the list of features it supports.

220 yourhost LMTP ready                 ← mail.local sends
>>> LHLO yourhost.your.domain           ← sendmail sends
250-yourhost                            ← mail.local sends
250-ENHANCEDSTATUSCODES
250 PIPELINING

Mailbox over quota error is permanent, not temporary mail.local command-line switch

Some errors in local delivery are considered transient. For example, if the mail.local tries to open a user’s mailbox file, and that open fails because the user’s mailbox is already larger than is permitted, delivery will fail. In such a failure, the mail is ordinarily left in the sendmail queue awaiting another try later.

On systems with limited resources, it is sometimes better to take a firm stand and disallow any file that exceeds the user’s quota. You do this with mail.local by adding a -b command-line switch:

FEATURE(`local_lmtp')
define(`LOCAL_MAILER_ARGS', `mail.local -l -b')

See the Unix online manual page concerning quota(1) for information about limiting users’ use of disk resources and about why this error will occur.

Allow old-style -d execution mail.local command-line switch

The original mail.local program was executed like this:

mail.local -d user

Here, mail.local is not running LMTP (the -l command-line switch is absent). Instead, it is running just like the old /bin/mail program. It reads from its standard input and writes to the user’s mailbox.

The modern mail.local program can be run like this:

mail.local user

This invocation has the same effect as the first one earlier. Thus, the use of -d is optional and can be included or omitted with no change in effect.

Select mailbox database type mail.local command-line switch

Beginning with V8.12, the mail.local program uses the same code as sendmail uses to look up user-mailbox information. By default, mail.local uses the pw mailbox database type, which uses the passwd(5) file, to locate the user’s home directory as well as user and group IDs.

Although pw is the only mailbox database type allowed as of V8.12, you can add other mailbox types. For example, if you were to add an LDAP type,^[168] you could then do the following:

FEATURE(`local_lmtp')
define(`LOCAL_MAILER_ARGS', `mail.local -l -D ldap')

See MailboxDatabase on page 1042 for a description of mailbox databases and the MailboxDatabase option.

Specify the envelope sender mail.local command-line switch

The five-character From that begins a line is used to separate one message from another in a user’s mailbox (UnixFromLine with mail files on page 1114). This is a convention used by some but not all MUAs. The From line is generated by mail.local when it delivers the message. Its form looks like this:

From user@host.domain Fri Dec  13 09:10:40 2002

The user is ordinarily determined by getting the login name of the user who ran mail.local with the getlogin(3) routine. If that lookup fails, mail.local gets the name of the user from the passwd(5) file that is associated with the uid of the user that ran mail.local. If that fails, it sets the username to “???.”

This -f command-line switch allows you to override the envelope sender’s user identity. For example:

define(`LOCAL_MAILER_ARGS', `mail.local -f sysmail@our.domain DOL(u)')

Here, we first omit declaration of the FEATURE(local_lmtp), to prevent local LMTP delivery. We then force the envelope sender name, as it appears in the From line of delivered mail, to appear as though it is from the user sysmail, by using this -f command-line switch.

Note that the envelope sender is the address to which failed mail is bounced. It is not the address used for replies.

Also note that when mail.local receives email with LMTP it gathers the actual envelope sender address from the MAIL From: command and places that address in the From line. When that happens, this -f command-line switch is ignored.

Store mail in user’s home directory mail.local command-line switch

Normally, mail.local delivers mail to a file owned by the recipient user in a central directory. That directory is usually /var/mail or /var/spool/mail.

Beginning with V8.12 sendmail, you can tell mail.local to instead deliver mail to a file in each user’s home directory. Simply use the -h command-line switch to specify a filename that will be common across all users’ homes. For example:

-h mbox

Some pop3 servers move a user’s central mail to that user’s home mbox file before transferring it via pop to the user. At such sites, when pop3 is so configured, and when all users read their mail with popd, there is an advantage to delivering directly to each user’s mbox file with mail.local.

Turn on LMTP mode mail.local command-line switch

The preferred way to run mail.local is in LMTP mode. LMTP is described in RFC2033.

Without LMTP (when there are multiple users in the envelope) it is possible for delivery to fail for a single user. When this happens, unexpected problems might occur with the good users. Sometimes they will receive duplicate messages and sometimes they will receive mail after a long and unexplained delay.

At sites that handle a large amount of mail for many users, LMTP mode is highly recommended. Multiple recipients per envelope are gracefully handled with LMTP. Each hands a separate error or success code back to sendmail, so there is never any confusion about what was and was not delivered.

If, despite these advantages, you wish to turn off LMTP mode in mail.local, you can do so by omitting this -l command-line switch:

define(`LOCAL_MAILER_ARGS', `mail.local   DOL(u)')
                                        ↑
                              -l has been omitted

Here, we first omitted the FEATURE(local_lmtp) to prevent the local delivery agent’s flags from being set up for LMTP. We then declare mail.local without the -l to prevent it from speaking LMTP. Finally, we add $u (with the DOL macro) to cause the list of recipients to be passed in the command line.

See Set Up sendmail.cf for mail.local on page 360 for a description of how to install mail.local for use with the preferred LMTP mode.

Specify the envelope sender (deprecated) mail.local command-line switch

The -r command-line switch is a synonym for the -f command-line switch described earlier (-f on page 363). This switch is deprecated and might be removed from future versions of mail.local.

Use submit.cf instead mailstats command-line switch

When you run the MSP form of sendmail (The submit.cf File on page 66) you use two different configuration files, the sendmail.cf file and the submit.cf file. But it is possible to configure sendmail so that it uses a different statistics file with each configuration file. In that case, you can use this -c command-line switch to specify use of the submit.cf file, and its corresponding statistics file:

% mailstats -c       ← use submit.cf to locate the statistics file

If you are not set up to use MSP, use of this switch might yield the following error:

mailstats: /etc/mail/submit.cf: No such file or directory

Specify the configuration file’s location mailstats command-line switch

The mailstats program reads the sendmail program’s configuration file to locate the statistics file. It scans the configuration file looking for a line that begins with one of the following two expressions:

O StatusFile=
OS

The location of the configuration file is defined at compile time with _PATH_SENDMAILCF (_PATH... on page 131). If you wish to use a different configuration file, you can do so by specifying it with this -C command-line switch:

% mailstats -C /etc/mail/sendmail.cf.new

Specify another name for the statistics file mailstats command-line switch

Ordinarily, mailstats gathers the path to, and the name for, its statistics file from the sendmail configuration file. There will be times, however, when you will need to print statistics from information in another statistics file. Consider, for example, the desire to archive statistics files weekly for several years running. In such a scenario, you might run the following command to look at a statistics file from another month:

% mailstats -f /export/mail/archives/statsV3/2007/Dec/stat.25

But be aware that sendmail periodically updates the version of the statistics file. If you use the current version of mailstats to read an older version’s statistics file, you will get an error something like this:

% mailstats -f /etc/sendmail.st
mailstats version (3) incompatible with /etc/sendmail.st version (2)

If you archive statistics files, you should also archive versions of mailstats with which to read them.

Omit the delivery agent names mailstats command-line switch

Ordinarily, when mailstats produces its output, it prints the human-readable names of the delivery agents in its rightmost column:

% mailstats
Statistics from Sat Jan 1 17:30:02 2000
 M   msgsfr  bytes_from   msgsto    bytes_to  msgsrej msgsdis  Mailer
 0        0          0K      246        685K        0       0  prog
...                                                              ↑
                                                                here

If you prefer to omit delivery agent names, you can suppress the last column with this -o command-line switch:

% mailstats -o
Statistics from Sat Jan 1 17:30:02 2000
 M   msgsfr  bytes_from   msgsto    bytes_to  msgsrej msgsdis
 0        0          0K      246        685K        0       0
...                                                             ↑
                                                                gone

Note that this -o switch can be combined with the -p switch (described next) to also suppress printing the M line in that output.

Produce program-friendly output and clear statistics file mailstats command-line switch

Parsing of the mailstats program’s output can be made more program-friendly with the use of the -p command-line switch:

% mailstats -p
938478602 938718475
 0        0          0      247        686        0       0  prog
 3       42         96        2          5        0       0  local
 5      472       1710       10         22        5       0  esmtp
 T      514       1806      259        713        5       0
 C      514        259        5

Here, the first line contains two dates in Unix time(2) format. The first is the date/time the file was created (or zeroed), and the second is the date/time mailstats was run.

The rest of the lines are what you have already seen when mailstats was run without the -p. The M heading and attractive horizontal lines are missing, but the data is the same in both cases.

If the user running the mailstats program has write permission to the statistics file, this -p switch will also cause that file’s contents to become zeroed. If the user running the program lacks write permission to the statistics file, that file’s contents will not be zeroed. Zeroing and not zeroing are silent. You need to run the mailstats program a second time to discover whether the statistics file has been zeroed.

Beginning with V8.12 sendmail, you can use the -P command-line switch (discussed next) to print statistics in program-friendly form, without zeroing the statistics.

Note that the -o switch can be combined with the -p switch to produce program-friendly output that excludes the last, human-readable column:

% mailstats -p -o
938478602 938718475
 0        0          0      247        686        0       0
 3       42         96        2          5        0       0
 5      472       1710       10         22        5       0
 T      514       1806      259        713        5       0
 C      514        259        5

Produce program-friendly output and don’t clear statistics file mailstats command-line switch

Parsing of the mailstats program’s output can be made more program-friendly with the use of the -p command-line switch described earlier. One drawback of using the -p command-line switch is that it both prints and zeros the statistics.

Beginning with V8.12 sendmail, it is possible to print in program-friendly form (as with -p) but not zero the statistics. This is done with the -P command-line switch. This switch is identical in all respects to the -p, but it does not zero the statistics.

Set the cache size for hash and btree makemap command-line switch

The -c switch instructs makemap to set the cache size for hash or btree databases to the number of bytes indicated:

% makemap -c 524288 hash outfile

The default cache size, if this switch is not specified, is 1,048,576 bytes (1k squared). Note that setting the cache size is an art, and that the larger the cache, the better. The minimum cache size is recommended to be no less than 10 pages, or about 40,960 bytes.

Use an alternative sendmail configuration file makemap command-line switch

Ordinarily, makemap will leave the ownership of the created file unchanged. That is, it will behave the same as any nonprivileged Unix program that creates files.

If the TrustedUser option (TrustedUser on page 1112) is set in the sendmail configuration file, and if makemap was compiled with HASFCHOWN defined as 1, and if makemap is run by root, the output file will become owned by the TrustedUser option’s user.

The makemap program finds the TrustedUser option by reading and parsing the sendmail program’s configuration file (normally /etc/mail/sendmail.cf). If you want makemap to use a different configuration file, you can specify that different file with this -C switch, for example:

# makemap -C /etc/mail/sendmail.cf.new hash outfile

Allow duplicate keys in database makemap command-line switch

Ordinarily, makemap will complain if two entries have identical keys and refuse to insert the duplicate. But if it is desirable to allow the same key to appear multiple times in the database, you can use the -d switch to suppress the warnings and allow duplicates to be inserted. But be aware that this switch is allowed only for the btree and hash forms of the db(3) library. Use of this switch with any other form of database will produce the following error:

makemap: Type dbtype does not support -d (allow dups)

See the -r switch for a way to cause duplicates to replace originals.

Define alternative to # as comment character makemap command-line switch

Normally, the makemap program ignores lines of input that begin with the # character, but this can cause problems because some files use a different comment character. The dig(1) program, for example, produces output that uses a semicolon as the comment character:

;; ANSWERS:
host.domain.com   1845    CNAME   domain.com

To satisfy the need to build database-map files from such input, the -D command-line switch was added to the makemap program beginning with V8.13 sendmail. When you run makemap with the -D command-line switch, makemap will ignore lines of input that begin with a semicolon:

% makemap -D\;  file.db < file.txt

Note that, we prefix the semicolon with a backslash to insulate it from interpretation by the shell.

Allow empty data for keys makemap command-line switch

Normally, makemap refuses to allow keys without data. That is, the following infile:

bob     Good User
ted
alice   Gone User

would produce the following error when read by makemap:

makemap: hash: line 2: no RHS for LHS ted

But sometimes it is necessary to initialize or fill databases with new information when the data is not known but where that lack of information is not harmful, or where the data is not required. In support of such needs, makemap allows this -e switch. With it, keys that lack a data portion are allowed to populate the database.

Sometimes it is desirable to populate a database with keys only. For such databases, the key’s presence is the only information of interest. Consider the following K configuration command:

Klocaluser hash -m /etc/mail/localusers

Here, the -m database switch (-m on page 888) tells sendmail to look up the key, but not to fetch any data.

Don’t fold uppercase to lowercase makemap command-line switch

Normally, the key is converted to lowercase before being stored in the database. When the key entries are case-sensitive, the -f switch can be used to prevent conversion to lowercase. When tokens in rule sets are later looked up in the database, you can choose (with the K command, The K Configuration Command on page 882) to leave those tokens as is or convert them to lowercase before the comparison to keys. This switch and the K command should parallel each other.

List database types supported makemap command-line switch

The -l switch tells makemap to print a list of the database types it supports, and then exit. The largest list, and the most types that makemap can support, will look like this:

dbm        ← makemap compiled with NDBM defined
hash       ← makemap compiled with NEWDB defined
btree      ← makemap compiled with NEWDB defined

If in doubt, run makemap with this switch before trying to create a database file.

Append a null byte to all keys makemap command-line switch

The -N switch tells makemap to include a trailing zero byte with each key that it adds to the database. When sendmail looks up a key in the database, it uses a binary comparison. Some databases, such as /etc/aliases under SunOS, append a zero byte to each key. When a trailing zero byte is included with a key, it must also be included with the tokens being looked up, or the lookup will fail. The use of this switch must match the K command (-N on page 889).

Append to, don’t overwrite the file makemap command-line switch

Ordinarily, makemap overwrites any existing map with completely new information. The -o switch causes sendmail to append to a map. The appended information must be all new information (no duplicate keys), unless the -r or the -d switch is also used.

Replace (silently) duplicate keys makemap command-line switch

Ordinarily, it is an error to specify a key that already exists in a database. That is:

john   john@host1
john   john@host2

Here, instead of replacing the first with the second, the second john line produces an error. To allow replacement keys, use the -r switch with makemap. Generally, the -r and -o switches should be combined when updating a database with new information. (See also the editmap program, The editmap Program on page 354.)

Skip security checks makemap command-line switch

Ordinarily, makemap is safety-conscious. It will issue a warning, or abort, if any of the following three circumstances are present.

If makemap is run by root, and if the directory into which the database will be written is writable by anyone other than root, makemap will issue this warning:

WARNING: World writable directory directory

If the database file already exists and is a symbolic link, makemap will print the following error and abort:

makemap: error creating type hash map access: Symbolic links not allowed

Finally, if the database file already exists and is a hard link, makemap will print this error and abort:

makemap: error creating type hash map access: Hard links not allowed

If you wish to override these causes for rejection, you can do so by using this -s switch. But be aware that these warnings and errors are printed for good reasons. Circumventing them might open your machine to security risks.

Specify an alternative to whitespace for a delimiter makemap command-line switch

Normally, makemap expects the key and data portions of its input file to be separated from each other by linear whitespace (space and tab characters). The following is an example of such an input file:

key                 data
 ↓          ↓
lady     relaysite!lady
      ↑
  whitespace

Beginning with V8.12 sendmail, an alternative to whitespace can be specified on the command line. Consider, for example, an input file (named infile) that is delimited with commas:

key,data

To read such an input file with makemap you would run something like the following:

% makemap -t, hash outfile < infile

The delimiting character that follows the -t must be just a single character. If a multicharacter delimiting character is specified, all but the first character will be silently ignored. If the delimiting character has special meaning to the shell (as does a semicolon), be sure to quote or escape it:

-t\;       ← escaped with a backslash
-t ';'     ← quoted

Unmake (dump) the contents of a database makemap command-line switch

The -u switch causes makemap to dump the contents (key and data pairs) of an existing database. The database must exist and be readable for it to be dumped. If you attempt to dump a database for which you lack read access, you will get this message:

% makemap -u hash /etc/mail/privatedata
makemap: error opening type hash map /etc/mail/privatedata: Permission denied

You also must specify a type for the map that matches the type specified when it was made. If you mismatch, you will get an error such as this:

% makemap -u btree /etc/mail/access
makemap: error creating type btree map access: Invalid argument

If all goes well, the contents of the database will be printed to your standard output. Each datum will be separated from its key by a single tab character. Note that the order in which they print will not necessarily match the order in which they appeared in the original source text file.

Watch keys and data being added makemap command-line switch

To watch your keys and data being added to a database, use the -v switch. This switch causes the following line of output to be produced for each key processed:

key=`key', val=`data'

Note that the trailing zero added by the -N switch is not displayed with the -v output. Also note that verbose output is printed to the standard output, whereas error messages are printed to the standard error.

People are sometimes too busy to reply to all the email they get in a prompt fashion, and it is common courtesy to let senders know of the situation. Consider the following .vacation.msg file:

From: Your Full Name <you@your.domain>
Subject: I got your Message
Precedence: bulk
As you know, I often receive over 1,000 messages a week and cannot
reply to each message right away. This automatic reply is just to
reassure you that I receive all messages, and reply to them eventually.

For a plan such as this to work, you should avoid sending this message too often. Consider resetting the default resend interval from a week to a month with the -r command-line switch (-r on page 390).

The vacation program is also useful as a graceful way to retire users while keeping their accounts open for a while. Consider, for example, the following .vacation.msg file:

From: Full Name <user@your.domain>
Subject: I have moved
Precedence: bulk

Thanks for your email. It has been forwarded to my new address at:

       user@a.new.domain

Please update your records to contain this new address.

To complement this message, the user’s ~/.forward file could be set up like this:

user@a.new.domain
|"/usr/ucb/vacation user"

After the account is closed, you can fall back to the less graceful method described for the FEATURE(redirect) (FEATURE(redirect) on page 640).

The ~/.forward file can contain comment lines. Each such line must begin with a # character. For example:

\you
|"/usr/ucb/vacation -m .vacation.msg.weekday you"
#|"/usr/ucb/vacation -m .vacation.msg.weekend you"

Here, the -m command-line switch (-m on page 389) is used to specify different message files to use during the week and on weekends. When the third line is commented out of the ~/.forward file, the weekday message will be sent. By commenting out the second line and uncommenting the third, a different message file will be used.

This is a simplified example of a larger approach that can be quite useful. If you frequently go to conferences, for example, you might need a variety of messages depending on how you can be reached at each conference. Or you might want to maintain a library of messages, each for a different circumstance.

Also handle mail for another name vacation command-line switch

Some users have accounts on other machines under different login names. This can happen when moving from one job to another, for example. At the first job you might be named ellen, and at the next job you might have the login name ewinstin. If your mail is being forwarded to you from your old job, you can use this -a switch to have vacation recognize you under your old login name in addition to your current login name:

|"/usr/ucb/vacation -a ellen ewinstin"

You can add as many other names as you want by adding an -a command-line switch for each. A system administrator, for example, might have a half dozen names under which mail is received:

|"/usr/ucb/vacation -a root -a postmaster -a bin -a sys kate"

Note that vacation does a word match when it looks for each name. That is, only letters and numbers count in a word, so root will not match rootbugs, but will match root+bugs or root@host.

Specify an alternative configuration file vacation command-line switch

Beginning with V8.12 sendmail, the vacation program reads the sendmail program’s configuration file to locate the value of the MailboxDatabase option (MailboxDatabase on page 1042). It scans the configuration file looking for lines that begin with the prefix:

O MailboxDatabase=

If the MailboxDatabase option is undefined, its default value is pw, which means to look up mailbox information in the passwd(5) file form of database. The mailbox database is used to find the home directory, and user and group IDs for the user. The mailbox database is ignored if the -U command-line switch is used.

The location of the configuration file is defined at compile time with _PATH_SENDMAILCF (_PATH... on page 131). If you wish to use a different configuration file, you can do so by specifying it with this -C command-line switch:

% vacation -C /etc/mail/sendmail.cf.new -i

If the configuration file listed with -C doesn’t exist or is unreadable, the entire -C directive is silently ignored. If the MailboxDatabase option is found but specifies an unknown database, the following error is logged or printed and the vacation program exits:

vacation: can't open mailbox database: Service unavailable

Don’t syslog errors vacation command-line switch

Beginning with V8.12 sendmail, vacation logs all its error and warning messages via the syslog(3) facility (Log with syslog on page 513). Warnings are logged at LOG_NOTICE, and errors are logged at LOG_ERR.

The syslog facility reports them like this:

Mar  1 13:30:05 lady vacation[26884]: vacation: can't open mailbox database: Service
unavailable.

If you prefer to have these errors and warnings printed to your screen, you can use this -d command-line switch. It is better used outside your ~/.forward file because otherwise, printed errors will be sent to sendmail where they might be lost. You use the -d command-line switch like this:

% vacation -d bob < /dev/null
vacation: no such user bob.

Here, the administrator is about to set up a ~/.forward file for a user, and tests the vacation command with this -d switch. Because the user is bbob, and not bob, the error is immediately evident. Without the -d, the error would have been logged, and that log message might have been sent to another dedicated logging host.

Use a different database file vacation command-line switch

Sometimes it is desirable for vacation to use a database file different from its default of .vacation.db. Perhaps you want to keep all your vacation files in one directory—say, .vacation. If your message file were there and your database file were there, you might invoke vacation like this:

|"/usr/ucb/vacation -f .vacation/data.db -m .vacation/message you"

The -f command-line switch causes vacation to use a database different from its default. Only one -f can be specified. If you attempt to specify more than one database with multiple -f command-line switches, only the last one listed will be used.

Initialize the database file vacation command-line switch

The -i command-line switch causes vacation to initialize its database. When vacation initializes, it truncates the database (erases any prior information) and stores the notification interval.^[172] If the database file doesn’t exist, the -i command-line switch will cause it to be created. The -I command-line switch is a synonym for the -i command-line switch:

% /usr/ucb/vacation -i

If you wish to use a database file that is different from the default one named .vacation.db, you can do so by including the -f command-line switch described earlier:

% /usr/ucb/vacation -i -f .vacation/data.db

If you use -f when initializing, you must use the same -f expression when you set up your ~/.forward file.

You should initialize the database and give it a custom notification interval, exclusion addresses, and hosts (-x on page 392) before you set up vacation in your ~/.forward file. If a database doesn’t exist, vacation will automatically create an empty one for you with the default notification interval.

If the database file cannot be created or written for some reason, vacation will log the following error:

vacation: .vacation: reason here

Note that the suffix .db or .dbm is omitted because vacation doesn’t know which database type will be used ahead of time.

Reply despite lack of recipient in To: or Cc: header vacation command-line switch

Ordinarily, the vacation program will auto-respond only to messages that contain the recipient’s address in the To: or Cc: header. There will be instances, however (perhaps occurring as a result of aliasing or ~/.forward file translation), when mail will be delivered with an address in one of those headers that is not the recipient’s address. To illustrate, consider the following aliases file (The aliases(5) File’s Location on page 461) entries:

root:     bob
bin:      root
sys:      root
webmaster:     root
hostmaster:    root

Here, the system administrator, bob, receives mail that is also sent to root, bin, sys, webmaster, and hostmaster. Normally, vacation will not respond to mail sent to any of these aliases. If bob wants vacation to respond even if the name bob is not found in the To: or Cc: header, bob can cause it to do so by adding this -j command-line switch to his invocation of vacation in his ~/.forward file:

 |"/usr/ucb/vacation -j bob"

Henceforth, vacation will amend its recipient check^[173] response (when otherwise able) to all messages, no matter to whom each is addressed.

But note, this switch can cause vacation to auto-reply to unexpected addresses, so it is better used in restricted environments. In restricted environments, you will know all possible addresses ahead of time (via the aliases file) and so may safely use the vacation program’s -a switch (-a on page 386).

List the database’s contents vacation command-line switch

Beginning with V8.12 sendmail, you can list the senders contained in the vacation program’s database. Every time you receive a mail message from someone, that individual’s mail address is looked up in the vacation program’s database. If the address if found, and if the date associated with it is zero or if it is newer than the timeout interval, no vacation message is sent. If the address is found, and if the date associated with it is older than the timeout interval, a vacation message is sent and the date for that address’s record is updated to the present. If the address is absent from the database, a vacation message is sent and that address is added to the database and is given the present time.

The -l command-line switch causes vacation to print a list of the sender addresses it has in its database, one address per line, in the following format:

address                         date

The address is the sender address that received the message, or an address preset with the -x command-line switch. The date is when the message was last sent, or, for -x addresses, either a zero (which displays as Wed Dec 31 17:00:00 1969) prior to V8.12.4, or a literal (exclusion) for V8.12.4 and above:

friend@remote.site.com                 Fri Mar  1 15:10:48 2002
buddy@another.com                      Wed Dec 31 17:00:00 1969   ← V8.12.3 and
before
buddy@another.com                      (exclusion)                ← V8.12.4 and
above

The first line shows a sender who recently received a vacation message. The second line shows a sender address that was put in the database with the -x command line.

Note that this -l command-line switch shows only sender information from the database. Other information, such as the timeout interval, is not printed with this switch.

Use a different message file vacation command-line switch

Sometimes it is advantageous to use a message file different from the default internally defined by vacation, which is .vacation.msg. For example, consider the need to maintain a menu of messages to chose from, depending on the situation. In the following example, all the messages are kept in a subdirectory:

|"/usr/ucb/vacation -m .vacation/weekend you"

The -m command-line switch causes vacation to reply using the message file specified in place of the default file. Only one -m can be specified. If you attempt to specify more than one message file with multiple -m command-line switches, only the last one listed will be used.

Redefine envelope sender address vacation command-line switch

There is always a chance that a vacation message will bounce. To prevent that, vacation offers the -z command line switch (-z on page 392), which sets the return address for the message to be the null address:

<>

If you prefer a different return address, you may use the new V8.13 -R vacation command-line switch to define one. For example:

|"/usr/ucb/vacation -R bounces@bounce.example.com  you"

Here, the -R command-line switch causes vacation to mail messages with a return address of bounce+vacation@bounce.yourhost.domain. Such a return address might be appropriate at a site that has a special address for all bounces.

You can also use this switch to have bounces sent to yourself at a plus-address. That way, you can screen such bounces with procmail(1) or slocal(1). Just add a line like the following in your ~/.forward file:

|"/usr/ucb/vacation -R you+bounce@yourhost.domain you"

Change the notification interval vacation command-line switch

By default, vacation will notify any given sender about your status only once each week. If you plan to be gone longer, you can, as a courtesy, notify senders less often. To change this interval you can specify a new one using the -r switch when the database is initialized:

% /usr/ucb/vacation -r 31

The argument to the -r command-line switch is the number of days to wait between notifications. The interval is set, and vacation exits. The new wait interval remains in effect until the next time you set it, or until you clear the database with -i. There is no way to see what the setting currently is, so, if in doubt, reset it to a value you want.

Three special cases exist for the argument to -r. If the argument is not a number, the interval is set to an essentially infinite interval. If the argument is larger than the maximum value of a signed long integer on your system, the vacation program will print a usage message and exit. Finally, if the argument is zero, all interval waits are disabled and every message from a user gets a reply. Needless to say, this latter circumstance should be avoided.

Specify the sender in the command line vacation command-line switch

The vacation program, when run from inside your ~/.forward file, figures out the addresses of the sender by looking at the five-character "From" header (for the envelope sender). But there are other ways to run vacation when the envelope sender address should instead be passed on the command line.

Consider the following delivery agent declaration (The M Configuration Command on page 711) in which arbitrary users can have mail delivered via the vacation program:^[174]

Mvacation, P=/usr/ucb/vacation, A=vacation -s $f $u

Here, the vacation program is run whenever this delivery agent is selected by rule sets. When it is run, the recipient’s address is passed to it in the $u sendmail macro ($u on page 848). The sender’s address is passed to it with the -s command-line switch and the $f sendmail macro ($f on page 824).

This -s command-line switch is useful whenever vacation is run from somewhere other than the command line or your ~/.forward file. If the vacation program is run from inside your ~/.procmail.rc file or from within your ~/.maildelivery file, this -s command-line switch can also be handy.

The sender address must follow the -s. If it is missing, the recipient address will become the sender address and vacation will exit without doing anything. If the sender address is not a valid address, the message mailed by vacation will bounce.

Ignored for compatibility with Sun’s vacation vacation command-line switch

Beginning with V8.12 sendmail, the -t command-line switch is recognized and ignored. This is done to allow compatibility with Sun Microsystems’ version of the vacation program.

Don’t look up the user in the passwd(5) file vacation command-line switch

The vacation program, when run from inside your ~/.forward file, figures out the location of your database file and message file by looking up your username in the passwd(5) file. This method of finding those files will fail, however, if the user’s account has been removed.

Beginning with V8.12 sendmail, you can turn off this lookup of the user identity in the passwd(5) file. But if you do that, you will need to specify the location of the database file and the message file with the corresponding -f and -m command-line switches:

|"/usr/ucb/vacation -U -f /admin/retired/bob.db -m /admin/retired/bob.msg bob"

This method of bypassing the passwd(5) file could be handy in the aliases database as a means of handling retired users:

bob: |"/usr/ucb/vacation -U -f /admin/retired/bob.db -m /admin/retired/bob.msg bob"

The -U suppresses a lookup of bob in the passwd(5) file (which would fail because bob no longer has an account). The -f command-line switch (-f on page 387) tells vacation the path and filename of the database it should use. The -m command-line switch (-f on page 387) tells vacation the path and filename of the message file it should use.

If -U is specified, and if either the -f or -m, or both, are omitted, vacation logs or prints the following error and exits EX_NOINPUT:

vacation: -U requires setting both -f and -m

Exclude a list of addresses vacation command-line switch

Some addresses should not receive replies from vacation. Your boss might be one such case, or perhaps some friends who don’t need to know you’re away. To exclude addresses, just create a file that contains the list of addresses, one address per line. For example:

boss@your.domain
friend@your.domain
another@another.domain

You execute vacation from the command line like this:

% /usr/ucb/vacation -x < list

The -x command-line switch causes vacation to read one address at a time from its standard input and add it to a list of addresses to exclude from replies.

To make things easier, if you specify a domain with an @ at the front, all addresses in that domain will also be excluded:

% echo @your.domain | /usr/ucb/vacation -x

Here, instead of using a file as before, a single domain is echoed through the vacation program. The -x command-line switch causes all addresses in the domain your.domain to be excluded from vacation replies.

Whenever you add addresses to the exclusion list, you can rerun vacation with -x and the new addresses will be added. Initializing the database with -i clears the list, so whenever you initialize, be sure to reload your list with -x. The two switches can be combined, perhaps in a Makefile, to make initializing easier:

vacation:
        /usr/ucb/vacation -i -x < $(HOME)/.vacation.exclude

Set the sender to <> vacation command-line switch

Sometimes it is desirable to have vacation mail resemble bounced email. One way to accomplish this is to use the -z command-line switch. That switch causes the vacation message to appear to come from the special user “<>” instead of from you. At the original sender’s end, the message will likely appear to come from MAILER-DAEMON or something similar:

From MAILER-DAEMON@your.domain  Sat Jan  1 19:56:21 2000

As a side effect, the vacation reply will also have this header added:

X-Authentication-Warning: local.domain:  you set sender to <> using -f

This -z command-line switch is useful if your vacation messages generate significant bounced mail. This could be the case if you get lots of spam email, for example. Using this -z command-line switch will prevent vacation messages to those bad reply addresses from bouncing:

|"/usr/ucb/vacation -z you"