MIME (Multimedia) support in V8 sendmail has been coupled to ESMTP (Extended SMTP) of the new BODY parameter for the MAIL command. The BODY parameter is passed through as is to the delivery agent. Two special parameters are internally recognized by sendmail. They tell sendmail that the message body is either 7bit or 8bitmime. 7bit forces the high bit off. 8bitmime causes sendmail to leave the high bit unchanged. Both override any setting of the SevenBitInput (7) option (see Section 34.8.62, SevenBitInput (7)).

When sendmail connects to another site for incoming mail, it has no way to determine from context whether or not it is dealing with MIME mail. To override any configured assumptions, you may use the -B command-line switch.

-B 7BIT
-B 8BITMIME

Case is unimportant (7BIT and 7bit both work). The 7bit causes the local sendmail to tell the remote sendmail (in ESMTP mode) that the message body should have the high bit stripped from every byte. Conversely, 8bitmime tells the remote sendmail to preserve the high bit of each byte.

The value given to this -B command-line or received via the BODY parameter is stored in the ${bodytype} macro (see Section 31.10.4, ${bodytype}).

The -b switch tells sendmail in what mode to operate. For example, sendmail can "become" a daemon listening for incoming SMTP connections, or it can run in a mode that tells it to simply print the contents of the queue and exit. The form of the -b switch is:

-bmode

If mode is more than a single letter, all but the first letter is silently ignored. If the mode is missing or not one of those allowed, sendmail prints the following error message and exits:

Invalid operation mode bad letter here

If the -b command-line switch is omitted altogether, the default mode becomes -bm (deliver mail and exit).

Beginning with V8.7, sendmail the letter that selected the operating mode is assigned at startup to the ${opMode} macro (see Section 31.10.28, ${opMode}).

In the distant past, mail messages on ARPAnet were sent by using the ftp(1) protocol. Because that protocol was never intended for use with email, many different departures were designed ("patched in") to solve particular problems. That growing anarchy caused Jonathan B. Postel to design the Simple Mail Transfer Protocol (SMTP) in 1982 and to document that protocol in RFC821. Since then, SMTP has replaced FTP as the Internet standard.

In the belief that sufficient time had passed for all sites to have adopted SMTP, the -ba mode was deemed obsolete and removed from the V8.1 sendmail. It turned out that the British Grey Book protocol was based on FTP. To support that protocol, this -ba command-line switch was restored in V8.7 sendmail.

The -ba switch causes each line of a message to be terminated with a carriage-return line-feed pair instead of with a newline. This switch also forces sendmail to guess the sender from the message header, instead of parsing it from the envelope. The -ba switch should never be used outside of a Grey Book setting.

The -bD command line switch is almost exactly the same as the -bd switch. That is, it causes sendmail to run as a daemon, but, unlike the -bd switch, it prevents sendmail from performing a fork(2) and thereby keeps sendmail in the foreground. This allows sendmail to be run from a "wrapper" script to detect whether it died or was killed:

#!/bin/sh
SENDMAIL=/usr/lib/sendmail
UCBMAIL=/usr/ucb/mail

if [ -f $SENDMAIL -a -f $UCBMAIL ]
then
        $SENDMAIL -bD -q1h
        echo ${SENDMAIL}, which should run forever, died \
                | $UCBMAIL -s "Sendmail died" root
fi

Note that the echo line will never be reached as long as sendmail continues to run.

Also note that -bD also prevents detaching from the controlling terminal (just as does the -d99.100 debugging switch; see Section 37.5.193, -d99.100).

The -bd command-line switch causes sendmail to become a daemon, running in the background, listening for and handling incoming SMTP connections. [5]

[5] In its classic invocation, -bd is usually combined with a -q1h.

To become a daemon, sendmail first performs a fork(2). The parent then exits, and the child becomes the daemon by disconnecting itself from its controlling terminal. The -bD command-line switch can be used to prevent the fork(2) and the detachment and allows the sendmail program's behavior to be observed while it runs in daemon mode.

As a daemon, sendmail does a listen(2) on TCP port 25 for incoming SMTP messages. When another site connects to the listening daemon, the daemon performs a fork(2), and the child handles receipt of the incoming mail message.

The -bH command-line switch causes sendmail to clear (purge) all the persistent host-status information that was being saved as a result of the HostStatusDirectory option (see Section 34.8.31). Note that the HostStatusDirectory directory is not itself removed, but all the subdirectories under it are. The purgestat(1) (see Section 36.1.4) command-line command is a synonym for this switch.

The -bh command-line switch is a synonym for the hoststat(1) command-line command. It causes sendmail to print its persistent host status and exit. See Section 36.1.1 for a description of this output.

The -bi command-line switch causes sendmail to rebuild its aliases(5) database, and exit. This switch is described in Section 24.5.1. The name newaliases and the (obsolete) -I command-line switch are synonyms for this mode.

The -bm command-line switch (the default) causes sendmail to run once in the foreground. A list of recipients is taken from the command line (unless the -t command-line switch is used), and the message is read from the standard input and delivered.

This is the mode MUAs use when they invoke sendmail on the user's behalf. The sendmail program processes the recipients first, then the message header, then the message body. Usually, the envelope recipients are those on the command line. But if the -t command-line switch is also used, the recipients are taken from the message header. The envelope sender is more difficult to determine:

• Trusted users, and programs running under the identity of those users, may specify the address of the sender by using either the -f or the -r command-line switch (see Section 36.7.21) when running sendmail. Trusted users are those that are declared with a T configuration command (see Section 22.8.1.1, "Declare trusted users (not V8.1 through V8.6)").

• Otherwise, sendmail tries to use the user identity of the invoking program to determine the sender.

• When generating a mail bounce message, the header sender becomes the name specified by the value of the $n macro (see Section 31.10.26), usually mailer-daemon.

The -bp command-line switch is a synonym for mailq(3). See Section 23.4 for a full description of how to use this command-line switch.

The -bs command-line switch causes sendmail to run one time in the foreground, collect an SMTP message over its standard input and output, deliver the message, and exit.

This mode is intended for use at sites that wish to run sendmail with the inetd(3) daemon. To implement this, place an entry like the following in your inetd.conf(5) file, then restart inetd(3) by killing it with a SIGHUP signal:

smtp   stream  tcp   nowait  root /usr/lib/sendmail sendmail -bs

With this scheme it is important to either use cron(3) to run sendmail periodically to process its queue: [6]

[6] The look of these lines varies depending on the version of UNIX you are running.

0 * * * * /usr/lib/sendmail -q

or run sendmail in the background to process the queue periodically by specifying an interval to -q (see Section 23.6.1):

/usr/lib/sendmail -q1h

There are advantages and disadvantages in using inetd(3) instead of the -bd daemon mode to listen for and process incoming SMTP messages. The advantages are the following:

• At security-conscious sites, sendmail can be hidden behind a tcpd(3) or miscd(3) wrapper that can selectively accept or reject connections. (But see TCPWRAPPERS in Section 18.8.49, TCPWRAPPERS for a way to include this support directly inside sendmail.)

• At hosts that receive few incoming mail messages, this mode avoids the need to run a daemon.

The disadvantages are the following:

• At sites that receive many incoming mail messages, this mode causes a new sendmail process to be started for each connection. Compared to daemon mode, this can adversely affect system performance.

• At highly loaded sites, this mode circumvents the sendmail program options that are intended to avoid overloading the system with too many concurrent sendmail processes.

In general, the inetd(3) approach should be used only on lightly loaded machines that receive few SMTP connections.

The -bs switch is also useful for MUAs that prefer to use SMTP rather than a pipe to transfer a mail message to sendmail. Depending on how it is configured, mh(1) can use this feature.

The bt command-line switch causes sendmail to run in rule-testing mode. This mode is covered in detail in Section 38.1.

The -bv command-line switch causes sendmail to verify the list of recipients. Each recipient in the list of recipients is fully processed up to the point of delivery without actually being delivered. If mail can be successfully delivered to a recipient, sendmail prints a line like one of the following:

name ...deliverable
name ...deliverable: mailer $# value, host $@ value, user $: value

The first form is that of pre-V8 sendmail. The second form began with V8.1 sendmail.

The name is the original recipient address after it has undergone aliasing and rule set rewriting. A local user's name expands to the contents of that user's .forward file. A mailing list expands to many names (and produces many lines of output). The mailer, host, and user correspond to the triple returned by rule set 0 (see Section 29.6). If no $@ is returned, the host part is omitted from this output.

If the recipient cannot be delivered to, sendmail instead prints the following:

name ...reason recipient is undeliverable

The reason can be any of many possible error messages (such as "No such user") that would prevent successful delivery.

The -bv switch also prevents sendmail from collecting any mail message from its standard input unless the -t command-line switch (see Section 36.7.38) is also given.

Prior to V8 sendmail the -bz command-line switch caused sendmail to build (or rebuild) its frozen configuration file (now obsolete). The frozen configuration file was just a simple image of sendmail's variables after it had read and parsed the configuration file. The purpose of the frozen file was to enable sendmail to start up more swiftly than it could when parsing the configuration file from scratch. [7]

[7] In practice, freeze files helped you only on systems with very fast I/O systems relative to their CPU speeds. Although this was true in the day of the VAX 11/750, improvements in processor technology have reversed this tradeoff.

The -bz command-line switch is obsolete. If you use it with V8 sendmail, you will see this error message:

Frozen configurations unsupported

The -C command-line switch tells sendmail where to find its configuration file. The form of the -C switch is:

-C path

Space between the -C and the path is optional. The path specifies the location of the configuration file. That location may be either a relative or a full pathname. If path is missing, the location becomes the file sendmail.cf in the current directory.

The -C command-line switch causes sendmail to internally mark the configuration file as unsafe. An unsafe configuration file prevents all but root from setting certain options and causes sendmail to change its uid and gid to that of the user that ran it. If it is used by someone other than the superuser (and if in other than -bt rule-testing mode), the -oQ switch should also be used to set the location of the queue directory. If that location is not changed, sendmail fails because it cannot chdir(2) into its queue directory.

Prior to V8 the -C command-line switch also prevented sendmail from "thawing" its frozen configuration file.

The -c command-line switch is a synonym for the HoldExpensive (c) option (see Section 34.8.29).

As of V8, this command-line switch has been deprecated and may not be in future versions.

The -d command-line switch causes sendmail to run in debugging mode. This switch is described in gory detail in Section 37.1.

The -E switch is reserved for the Sony NEWS adaptation of sendmail. It is ignored by the Berkeley release of V8 sendmail and produces no errors if used by that version.

The -e command-line switch is a synonym for the ErrorMode (e) option (see Section 34.8.24).

The -e command-line switch is deprecated and may not be in future versions.

The -F command-line switch specifies the full name for the sender, which is used in mail headers and the envelope. The form of the -F switch is:

-Ffullname
-F fullname

Space between the -F and the fullname is optional. If fullname is missing and the -F is the last argument, sendmail prints the following error and exits:

sendmail: option requires an argument - F

If the -F is followed by any other switches, the following switch is taken as the full name.

When specifying the sender's full name, be sure to quote any internal spaces or shell special characters. For example, for the C shell the following would be needed to specify the full name Happy Guy!:

"Happy Guy\!"

In the absence of this switch, sendmail finds the sender's full name in any of several places. These are described in the section discussing the $x macro (see Section 31.10.42, $x).

The -f and -r command-line switches are interchangeable. [8] Either causes sendmail to take the address of the sender from the command line rather than from the envelope or message header. The -f switch is used by UUCP software and by mailing list software. The form of the -f switch is:

[8] The only difference is that the -r command-line switch is deprecated, and there is no guarantee that it will be included in future versions of sendmail.

-faddr
-f addr

Space between the -f and the addr is optional. If addr is missing, sendmail prints the following error message and ignores the -f switch:

sendmail: option requires an argument - f

Multiple -f switches cause sendmail to print the following error message and exit:

More than one "from" person

The behavior of this switch varies depending on the version of sendmail you are running.

Prior to V8 the uid of the user specifying the -f switch must match one of the usernames given in the T configuration command. If they do not match, sendmail silently ignores the option and determines the sender's address in the usual ways.

From V8.1 through V8.6 the T configuration command was eliminated. If the -f or -r switch was used, and if the p (privacy) option was given authwarnings, sendmail included an X-Authentication-Warning: header in the mail message. That header warned that the identity of the sender had changed.

Beginning with V8.7 sendmail, the T was reintroduced, but in a different form (see Section 22.8.1, "Trusted Users"). First sendmail checks to see whether the user specified by the -f is the same as the login name of the user running sendmail, as would be the case for mh(1). If they are the same, sendmail silently accepts the address. If they differ, sendmail looks to see whether the login name of the user running sendmail is in the class $=t. If it is, sendmail silently accepts the address. If not, sendmail checks to see if authwarnings is set for the PrivacyOptions (p) option (see Section 34.8.47, PrivacyOptions (p)). If it is, the following warning is logged and included in the outgoing message:

X-Authentication-Warning: login set sender to new name using -f

A "hop" is the transmittal of a mail message from one machine to another. Many such hops may be required to deliver a message. The number of hops (the hop count) is determined by counting the number of Received: [9] header lines in the header portion of an email message. The maximum number of allowable hops is compiled-in for most versions of sendmail but is set by the MaxHopCount (h) option with V8. When the hop count for a message exceeds the limit set by the MaxHopCount (h) option (see Section 34.8.36, MaxHopCount (h)), the message is bounced. Ordinarily, the count begins at zero. The -h command-line switch is used to specify a minimum hop count. [10] The forms for the -h command-line switch are:

[9] Actually, all headers marked with the H_TRACE flag in conf.c (see Section 35.5.8, "H_TRACE") are counted.

[10] The first edition to this book and the documentation that came with sendmail both wrongly stated that the -h switch set a beginning count.

-hnum
-h num

Space between the -h and num is optional. If num is missing, sendmail prints the following error message and ignores that switch:

sendmail: option requires an argument - h

If num begins with a character other than a digit, the offending text is printed:

Bad hop count (bad text)

The failure above illustrates that the minimum hop count must be positive.

The -h switch was originally used by BerkNet to carry the hop count in the envelope. It currently has no application.

The -I command-line switch is a synonym for the -bi command-line switch and the newaliases name. It is obsolete, but retained for compatibility with the delivermail(1) program (the precursor to sendmail).

The -I switch is deprecated and may not be included in future versions of sendmail.

The -i command-line switch is a synonym for the IgnoreDots (i) option (see Section 34.8.32, IgnoreDots (i)).

The -i switch is deprecated and may not be included in future versions.

The -J switch is reserved for the Sony NEWS adaptation of sendmail. It is ignored by the Berkeley release of V8 sendmail and produces no errors if used by that version.

The -M command-line switch is used to assign a macro a value. Note that prior to V8.8, only single-character macro names could be defined. The -M command-line switch is fully described in Section 31.2.

The -m command-line switch is a synonym for the MeToo (m) option. It is used to set that option to true. The -m command line switch is fully described in Section 34.8.39.

The -N command-line switch causes sendmail to append the DSN NOTIFY command to the ESMTP RCPT command. For example:

RCPT To:<[email protected]> NOTIFY=SUCCESS

Here, sendmail is requesting that the other site return notification of successful delivery. Should the message be successfully delivered by a host that understands DSN, a return message will be sent to the sender. If the other site is running V8.8 sendmail, that return message will look (in part) like this:

Date: Fri, 13 Dec 96 08:11:43 -0800 (PST)
From: Mail Delivery Subsystem <MAILER-DAEMON>
Subject: Return receipt
Message-Id: <[email protected]>
To: <[email protected]>
MIME-Version: 1.0
Content-Type: multipart/report; report-type=delivery-status;
        boundary="PAA09881.834702270/other.site
Auto-Submitted: auto-generated (return-receipt)

This is a MIME-encapsulated message

-PAA09881.834702270/other.site

The original message was received at Fri, 13 Dec 96 08:11:43 -0800 (PST)
from other.site [204.255.152.62]

   --- The following addresses had successful delivery notifications ---
friend (successfully delivered to mailbox)

The -N command-line switch tells the NOTIFY command what to include and thus tunes how notification will be handled. The form of the -N command-line switch looks like this:

-Nnever
-Nkeyword,keyword,...

The first form sets NOTIFY to be NEVER, meaning send no notification. The second form tells NOTIFY to specify notification based on one or more of three possibilities:

success

The success keyword tells sendmail to ask for notification of successful final delivery.

failure

The failure keyword tells sendmail to ask for notification if the message fails to be delivered.

delay

The delay keyword tells sendmail to ask for notification if the message is delayed for any reason.

These keywords can be listed after the -N to set a combination of notification requests. For example,

-Ndelay,success

tells sendmail to ask for notification if the message is successfully delivered or delayed but not to get notification if the message fails.

If an unknown keyword is listed, sendmail prints the following error message and ignores the bad keyword:

Invalid -N argument

If the -N command-line switch is omitted, notification policy is left to the other site. The usual default is failure (and possibly delay). On the local machine, sendmail acts as though both failure and delay were specified.

The -n command-line switch prevents sendmail from changing local recipient addresses with aliases. The -n switch is fully described in Section 24.6.

The -O command-line switch is used to set a multicharacter configuration option from the command line:

-OLongName=value

The -O switch is described in detail in Section 34.1.

The -o command-line switch is used to set a single-character configuration option from the command line.

-oXvalue

The -o switch is described in detail in Section 34.1.

The $r macro holds as its value the protocol that is used in receiving a mail message (usually SMTP or UUCP; see Section 31.10.31, $r). The $s macro holds as its value the name of the sending host (see Section 31.10.33, $s). Some programs, such as UUCP, need to be able to set the values of these macros from the command line. The old way to set them looked like this:

-oMrUUCP -oMslady

Here, the M option sets $r to be UUCP and $s to be lady.

Under V8 sendmail the setting of $r and $s has been simplified. A command-line single switch, -p, can be used to set them both:

-prval:sval

Here, the rval is the value assigned to $r, and the sval is the value assigned to $s. The two are separated by a colon. If the sval is omitted, the colon should also be omitted.

The -q command-line switch causes sendmail to process its queue once or periodically, depending on its arguments. The -q switch is described in detail in Section 23.6.1.

The -R command-line switch tells sendmail to include the DSN RET command with an ESMTP MAIL command:

MAIL From:<[email protected]> RET=full
MAIL From:<[email protected]> RET=hdrs

The RET command tells the receiving site whether or not to include a copy of the original message body in the bounced mail notification. RET=full causes both headers and the message body to be returned. RET=hdrs causes only headers to be returned. The RET= command is binding on the receiving site only if it agrees to handle the DSN extension to ESMTP. In the absence of RET or remote DSN support, the receiving site is free to return the message body if it so desires.

The RET, and hence this -R command-line switch, is useful in two circumstances:

• For users sending email, this should be set to full so that any bounced mail will include the original message body. This helps to reduce the need for users to archive their outgoing mail.

• For mailing-list mailings or other batched broadcast messages, this should be set to hdrs so that only the header portion of the bounced message will be returned.

The form of the -R command line switch looks like this:

-R arg

Space between the -R and its argument is optional. The arg must be present and must be either hdrs (return only headers) or full (return the body too). If it is any other value, the following error is printed and the setting defaults to full:

Invalid -R value

The -R command-line switch may appear only once in the command line. If it appears multiple times, the second and subsequent appearances will result in this error message:

Duplicate -R flag

The -r command-line switch is a synonym for the -f command-line switch. This -r command-line switch is deprecated and may not be included in future versions.

The -s command-line switch tells sendmail to set the SaveFromLine (f) option (see Section 34.8.59) to true. This -s command-line switch is deprecated and may not be in future versions.

The -T command-line switch causes sendmail to set the QueueTimeout (T) option (see Section 34.8.52) to the value specified. This -T command-line switch is deprecated (as is the QueueTimeout (T) option) in favor of the Timeout option of V8.7 sendmail (see Section 34.8.70, Timeout (r)), and may not be in future versions.

The -t command-line switch causes sendmail to gather its list of recipients from the message's header in addition to gathering them from its command line. The -t switch takes no arguments.

When this switch is specified, sendmail gathers recipient names from the To:, Cc:, and Bcc: header lines. It also gathers recipient names from its command line if any were listed there. Duplicates are discarded, and the message is delivered to all that remain.

The -t switch is intended for use by MUAs. It should never be specified when sendmail is run in daemon mode.

The -U command-line switch is used to tell sendmail that this is the very first step in this email message's submission.

As of V8.8, this switch does nothing. When MUAs start to use this switch, it will do things like turning on DNS canonification of the initial addresses. It should always be set by MUAs doing initial submission of a message.

This switch has been instituted as parallel support for the XUSR extension to ESMTP.

The -V command-line switch is used to specify the envelope identifier for the outgoing message. That identifier is called the ENVID and is part of the DSN extension to ESMTP. ENVID and the ${envid} macro are fully discussed in Section 31.10.12, ${envid}.

The form of the -V command-line switch looks like this:

-Venvid
-V envid

Space between the -V and its argument is optional. The envid must be a legal ENVID identifier (see Section 31.10.12). If an illegal character is specified in envid, the following error is printed, and that declaration is ignored:

Invalid syntax in -V flag

The -v command-line switch tells sendmail to run in verbose mode. In that mode, sendmail prints a blow-by-blow description of all the steps it takes in delivering a mail message.

After the sendmail.cf file is parsed and after the command-line arguments have been processed, sendmail checks to see whether it is in verbose mode. If it is, it resets the HoldExpensive (c) option (see Section 34.8.29) to false and sets the DeliveryMode (d) option (see Section 34.8.16) to interactive.

The -v switch is most useful for watching SMTP mail being sent and for producing expanded output when viewing the queue.

The -X command line switch tells sendmail to open the file whose name is the next following argument and to append to that file both sides of all SMTP transactions. The -X command-line switch is described in full in Section 26.4.

V8 sendmail prints an error if an illegal switch is specified (whereas other versions of sendmail silently ignore them). The mailx program supplied with OSF/1 from DEC and AIX from IBM issues an illegal -x switch. To keep sendmail from uselessly complaining under OSF/1 and AIX, that switch is specifically ignored. To get the same behavior with AIX under V8.1 sendmail, look for _osf_ in main.c and uncomment the code necessary to ignore that switch.