sendmail

sendmailSearch this book
Previous: 31.9 PitfallsChapter 31
Defined Macros
Next: 32. Class Macros
 

31.10 Alphabetized Reference

The sendmail program reserves all lowercase letters, punctuation characters, and digits for its own use. For multicharacter names it reserves all those that begin with an underscore or a lowercase letter. Table 31.7 lists all the macro names that have special internal meaning to sendmail. Included in this list are macros that are used by the m4 configuration technique. [9]

[9] Note that these are the exception to the usual rule in that they are all uppercase letters. In a way this makes sense, because they are being used by the configuration file, not by the internals of the sendmail program.

Table 31.7: Reserved Macros
MacroDescription
$_Section 31.10.1RFC1413-validation & IP source route (V8.1 and above)
$aSection 31.10.2The origin date in RFC822 format
$bSection 31.10.3The current date in RFC822 format
${bodytype}Section 31.10.4The ESMTP BODY parameter
$BSection 31.10.5The BITNET relay
$cSection 31.10.6, $cThe hop count
${client_addr}Section 31.10.7The connecting host's IP address
${client_name}Section 31.10.8The connecting host's canonical name
$CSection 31.10.9The hostname of the DECnet relay (m4 technique)
$dSection 31.10.10The current date in UNIX ctime(3)
$eSection 34.8.65SMTP greeting message (V8.6 and earlier)
${envid}Section 31.10.12The original DSN envelope ID (V8.8 and above)
$ESection 31.10.13X.400 relay (unused) (m4 technique)
$fSection 31.10.14, $fThe sender's address
$FSection 31.10.15FAX relay (m4 technique)
$gSection 31.10.16The sender's address relative to recipient
$hSection 31.10.17, $hHost part of the recipient address
$HSection 31.10.18The mail hub (m4 technique)
$iSection 31.10.19, $iThe queue identifier
$jSection 31.10.20Official canonical name
$kSection 31.10.21UUCP node name (V8.1 and above)
$lSection 34.8.72UNIX From format (V8.6 and earlier)
$LSection 31.10.23Local user relay (m4 technique)
$mSection 31.10.24The DNS domain name (V8.1 and above)
$MSection 31.10.25Who we are masquerading as (m4 technique)
$nSection 31.10.26Error message sender
$oSection 34.8.45Token separation characters (V8.6 and earlier)
${opMode}Section 31.10.28The startup operating mode (V8.7 and above)
$pSection 31.10.29, $pThe sendmail process ID
$qSection 31.10.30Default form of the sender address (V8.6 and earlier)
$rSection 31.10.31The protocol used
$RSection 31.10.32The relay for unqualified names (m4 technique)
$sSection 31.10.33Sender host's name
$SSection 31.10.34The Smart Host (m4 technique)
$tSection 31.10.35Current time in seconds
$uSection 31.10.36, $uRecipient's username
$USection 31.10.37The UUCP name to override $k
$vSection 31.10.38The sendmail program's version
$VSection 31.10.39The UUCP relay (for class $=V) (m4 technique)
$wSection 31.10.40The short name of this host
$WSection 31.10.41The UUCP relay (for class $=W) (m4 technique)
$xSection 31.10.42The full name of the sender
$XSection 31.10.43The UUCP relay (for class $=X) (m4 technique)
$ySection 31.10.44, $yName of the controlling TTY
$YSection 31.10.45The UUCP relay for unclassified hosts
$zSection 31.10.46, $zRecipient's home directory
$ZSection 31.10.47The version of this m4 configuration (m4 technique)

The following pages present a complete reference for each reserved macro. They are presented in alphabetical order for ease of lookup, rather than in the order in which they typically appear in configuration files.

31.10.1 $-

RFC1413-validation and IP source route

(V8.1 and above)

RFC1413, Identification Protocol, describes a method for identifying the user and host that initiate network connections. [10] It relies on the originating host, which must be running the identd(8) daemon.

[10] Bugs in Ultrix and OSF/1 (and maybe others) break the ident protocol. For an explanation, see conf.h.

When the V8 sendmail daemon receives a network connection request (and if Timeout.ident option, see Section 34.8.70.10, "Timeout.ident", is nonzero), it attempts to connect to the originating host's identd service. If the originating host supports identification, sendmail reads the login name of the user who initiated the connection. The sendmail program then appends an @ and the name of the originating host to it. If the name of the originating host is an IP number in square brackets, sendmail attempts to convert the number to a hostname. The final result, in the form user@host, is assigned to $_.

When sendmail is run on the local machine, it sets $_ to be the name of the user that corresponds to the uid of the process that ran sendmail. It gets that name by calling getpwuid(3). If the call fails, the name is set to the string:

Unknown UID: num

Here, num is the uid for which a login name could not be found.

Next, an @ and the name of the local machine are appended to the name, and the result is assigned to $_.

Beginning with V8.7 sendmail, attempts at IP source routing can also be stored in this macro. If sendmail was compiled with IP_SRCROUTE defined, that IP source routing information will be added to $_ after the user and host described above. The format of this additional information is described in Section 18.8.13, IP-SRCROUTE.

The $_ macro is not used by sendmail. Rather, it is offered as a means for the administrator to use authentication information. One possibility would be to include it in the Received: header:

HReceived: $?sfrom $s $.$?_($_) $.by $j ($v/$Z) id $i; $b

Another possibility is to customize checkcompat() in conf.c. One might, for example, wish to reject any mail in which the host part of $_ does not match the contents of $s (see Section 31.10.33). Section 20.2.4, "Verify identd Information" shows an example of how to code this.

31.10.2 $a

The origin date in RFC822 format

(All versions)

The $a macro holds the origin date of a mail message (the date and time that the original message was sent). It holds a date in ARPAnet format, defined in RFC822, section 5.1, and amended by RFC1123, section 5.2.14.

The sendmail program obtains that date in one of the following four ways:

  • When sendmail first begins to run, it presets several date-oriented macros internally to the current date and time. Among those are the macros $t, $d, $b, and $a. This initialization is done after the configuration file is read, so all but $b may be given initial values in that file.

  • Whenever sendmail collects information from the stored header of a message (whether after message collection, during processing of the queue, or when saving to the queue), it sets the value of $a. If a Posted-Date: header exists, the date from that line is used. Otherwise, if a Date: header exists, that date is used. Note that no check is made by sendmail to ensure that the date in $a is indeed in RFC822 format. Of necessity it must trust that the originating program has adhered to that standard.

  • When sendmail notifies the user of an error, it takes the origin date from $b (the current date in RFC822 format, and places that value into $a.

$a is chiefly intended for use in configuration-file header definitions. It may also be used in delivery agent A= equates (argument vectors), although it is of little value in that case.

$a is transient. If defined in the configuration file or in the command line, that definition may be ignored by sendmail. .

31.10.3 $b

The current date in RFC822 format

(All versions)

The $b macro contains the current date in ARPAnet format, as defined in RFC822, section 5.1, and amended by RFC1123, section 5.2.14.

Because $b holds the current date and time, sendmail frequently updates the value in that macro. When sendmail first starts to run, it places the current date and time into $b. Thereafter, each time an SMTP connection is made and each time the queue is processed, the value of the date and time in that macro is updated.

If the system call to time(3) should fail, the value stored in $b becomes Wed Dec 31 15:59:59 1969, [11] and no other indication of an error is given.

[11] The actual time depends on the local time zone.

$b is chiefly intended for use in configuration-file header definitions that require ARPAnet format (such as Received:, see Section 35.10.25, Received:). It may also be used in delivery agent A= equates (argument vectors), although it is of little value in that case.

$b is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.4 ${bodytype}

The ESMTP BODY parameter

(V8.8 and above)

MIME (multimedia) support in V8 sendmail has been coupled to ESMTP (Extended SMTP) of the new BODY parameter for the MAIL command. That parameter tells sendmail whether it is dealing with 7-bit or 8-bit MIME data:

MAIL From: <address> BODY=7BIT
MAIL From: <address> BODY=8BITMIME

The parameter specified for the BODY (7BIT or 8BITMIME) is the value stored in the ${bodytype} macro.

The ${bodytype} macro is intended to be used as part of the delivery agent's A= equate (see Section 30.4.1, A=). It provides a means to pass this information to delivery agent programs as part of their command lines.

${bodytype} is transient. If defined in the configuration file or in the command line, that definition may be ignored by sendmail. Note that the -B command-line switch (see Section 36.7.1, -B) can be used to specify a value to be stored in ${bodytype}, but that value too is transient.

31.10.5 $B

The BITNET relay

(m4 technique)

When configuring with the m4 technique, you can specify a host that will transfer mail between the Internet and BITNET. Mail to BITNET may then be sent by appending the pseudo-domain .BITNET to an address. For example,

user@ucbicsi.BITNET

Here, ucbicsi is a BITNET host.

To allow your configuration file to handle this form of address, you need to declare the name of your BITNET relay using the BITNET_RELAY keyword:

define(`BITNET_RELAY', `relayhost')dnl

This statement causes the rule for BITNET to be included in your configuration file and causes relayhost to be assigned as the value of $B. (See Section 19.4.5, "Relays" for a description of how to include a delivery agent specification with relayhost.)

See also bitdomain FEATURE (see Section 19.6.9, FEATURE(bitdomain)) for a way to convert BITNET addresses to Internet addresses for hosts that have both.

31.10.6 $c

The hop count

(All versions)

The c macro is used to store the number of times a mail message has been forwarded from site to site. It is a count of the number of Received:, Via:, and Mail-From: header lines in a message.

The value in $c is not used by sendmail. Rather, it is made available for use in configuration-file header line definitions. When calculating the hop count for comparison to the MaxHopCount (h) option (see Section 34.8.36, MaxHopCount (h)), sendmail uses internal variables.

$c is transient. If defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.7 ${client-addr}

The connecting host's IP address

(V8.8 and above)

The ${client_addr} macro is assigned its value when a host connects to the running daemon. The value assigned is the IP address of that connecting host and is the same as the IP address stored in the $_ macro, but without the surrounding square brackets and other non-IP information.

The ${client_addr} macro can be useful in the check_rcpt (see Section 29.10.1, "The check_mail Rule Set") and check_mail (see Section 29.10.2, "The check_rcpt Rule Set") rule sets. It can, for example, be used detect whether an external host is trying to send external mail through your outgoing firewall machine.

D{ourdomain}123.45.6
Scheck_mail
R$*                 $: $(dequote "" $&{client_addr} $)
R${ourdomain}.$-    $@ Okay our domain
R$*                 $#error $@ 5.7.1 $: "cannot send out from the outside"

Here, the first rule transfers the value of ${client_addr} into the workspace. The $& prefix (see Section 31.5.3, "Use Value as Is with $&") prevents that macro from wrongly being expanded when the configuration file is read. The second rule compares the domain part of your IP domain (that of your internal network) to the workspace. If they match, the connection is from a host in your internal domain space. If not, an error is generated in response to the SMTP MAIL command.

Note that this rule set rejects all mail coming from outside your network, which may be overkill (depending, of course, on what you want). It is really useful only at sites that have two firewalls, one for incoming traffic and one for outgoing traffic. This rule set might go on the outgoing firewall.

${client_addr} is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail. Note that ${client_addr} is not guaranteed to be available in the check_compat rule set (see Section 29.10.4, "The check_compat Rule Set") or in the check_relay rule set (see Section 29.10.3, "The check_relay Rule Set").

31.10.8 ${client-name}

The connecting host's canonical name

(V8.8 and above)

The ${client_name} macro is assigned its value when a host connects to the running daemon. This macro holds as its value, the canonical hostname of that connecting host, which is the same as the hostname stored in the $_ macro.

The ${client_name} macro is useful in the check_rcpt (see Section 29.10.1) and check_mail (see Section 29.10.2) rule sets. It can, for example, be used to see whether the connecting host is your firewall machine:

D{firewall}fw.our.domain
Scheck_mail
R$*                     $: $(dequote "" $&{client_name} $)
R${firewall}            $@ Okay our firewall machine
R$*                     $#error $@ 5.7.1 $: "can only accept from our firewall"

Here, the first rule transfers the value of ${client_name} into the workspace. The $& prefix (see Section 31.5.3) prevents that macro from wrongly being expanded when the configuration file is read. The second rule compares the name of the firewall to that workspace. If they match, the connecting host was indeed the firewall machine.

${client_name} is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail. Note that ${client_name} is not guaranteed to be available in the check_compat rule set (see Section 29.10.4) or in the check_relay rule set (see Section 29.10.3).

31.10.9 $C

The DECnet relay

(m4 technique)

DECnet addresses are of the form node::user. They can be handled by defining a host that will relay them into your DECnet network. Using the m4 technique, you enable DECnet like this:

define(`DECNET_RELAY', `relay_host')dnl

Mail addressed to node::user will then be forwarded to relay_host, as will any Internet-style addresses that end in the pseudo-domain .DECNET, such as user@domain.DECNET. $C holds the name of the relay_host. (See Section 19.4.5 for a description of how to include a delivery agent specification with relay_host.)

31.10.10 $d

The current date in UNIX ctime(3) format

(All versions)

The $d macro holds the current date and time. $d is given its value at the same time $a is defined. The only difference between the two is that $a contains the date in RFC822 format, whereas $d contains the same date in UNIX ctime(3) format.

The form of a date in ctime(3) format is generally [12]

[12] The format produced by ctime(3) varies depending on the area of the world.

Sun Dec 26 01:03:52 1999\n 

When sendmail stores this form of date into $d, it converts the trailing newline (the \n) into a zero, thus stripping the newline from the date.

31.10.11 $e

The SMTP greeting message

(V8.6 and earlier)

Prior to V8.7 sendmail the $e macro was used to hold the SMTP greeting message. That role has been taken over by the SmtpGreetingMessage option. See Section 34.8.65 for a description of both this $e macro and that new option.

31.10.12 ${envid}

The original DSN envelope ID

(V8.8 and above)

RFC1891 specifies that the keyword ENVID may be given to the MAIL ESMTP command:

MAIL From: <address> ENVID=envelopeID

ENVID is used to propagate a consistent envelope identifier (distinct from the Message-ID: header; see Section 35.10.19, Message-ID:), that will be permanently associated with the message. The envelopeID may contain any ASCII characters between ! and ~, except + and =. Any characters outside that range must be encoded by prefixing an uppercase, two-digit, hexadecimal representation of it with a plus. For example, an envelopeID composed of the letter X followed by a delete character would be encoded like this:

X+7F

When mail is received over an SMTP channel and an ENVID identifier is specified, that identifier is saved as part of the envelope information. The value of the ENVID identifier is saved in and restored from the qf file's Z line (see Section 23.9.17, Z line). For bounced mail, the ENVID identifier is printed with the Original-Envelope-Id: DSN header (see RFC1894) as part of the DSN MIME body. Beginning with V8.8 sendmail, an ENVID identifier can also be assigned to a message with the -V command-line switch (see Section 36.7.40, -V).

When mail is delivered, the value of the envelope's ENVID identifier is saved in the ${envid} macro. That macro is available for use with delivery agents that understand DSN.

${envid} is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.13 $E

X.400 relay

(m4 technique)

The $E macro is reserved for the future use of the m4 technique. It will be used to hold the name of the X.400 relay.

31.10.14 $f

The sender's address

(All versions)

The $f macro is used to hold the address of the sender. That address can be obtained by sendmail from any of a variety of places:

  • During an SMTP conversation the sending host specifies the address of the sender by issuing a MAIL SMTP command.

  • Trusted users are those declared as part of the t class (see Section 32.5.7, $=t). [13] Those users, and programs running under the identity of those users, may specify the address of the sender by using the -f command-line switch when running sendmail.

    [13] Prior to V8.1 this was set with a T configuration command. This feature was eliminated in versions V8.1 through V8.6 and restored in V8.7.

  • In processing a message from the queue, the sender's address is taken from the qf file's S line.

  • In processing bounced mail, the sender becomes the name specified by the value of $n, usually mailer-daemon.

  • In the absence of the above, sendmail tries to use the user identity of the invoking program to determine the sender.

Once sendmail has determined the sender (possibly aliased), it rewrites the address found with rule sets 3, 1, and 4. The rewritten address is then made the value of $f.

$f is intended for use in both configuration-file header commands and delivery agent A= equates. $f differs from $g in that $g undergoes additional processing to produce a true return address. When sendmail queues a mail message and when it processes the queue, the values in $f and $g are identical.

$f is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.15 $F

The FAX relay

(m4 technique)

At many sites, faxes can be sent via email. When the host that dispatches those faxes is not the local host, you need to relay FAX mail to the host that can dispatch faxes. This ability is enabled by defining that relay host with the m4 technique:

define(`FAX_RELAY', `relay_host')dnl

This causes all mail that ends with the pseudo domain .FAX to be forwarded to relay_host. It also assigns the value relay_host to $F. (See Section 19.4.5 for a description of how to include a delivery agent specification with relay_host.)

31.10.16 $g

The sender's address relative to recipient

(All versions)

The $g macro is identical to $f except that it undergoes additional rule-set processing to translate it into a full return address. During delivery the sender's address is processed by rule sets 3, 1, and 4 and then placed into $f. That rewritten address is further processed by 3 and 1 again, then custom rewritten by the rule set specified in the S= equate of the delivery agent. Finally, it is rewritten by rule set 4, and the result is placed into $g.

$g holds the official return address for the sender. As such, it should be used in the From: and Return-Path: header definitions.

The S= equate for each delivery agent must perform all necessary translations to produce a value for $g that is correct. Because the form of a correct return address varies depending on the delivery agent, other rule sets should generally not be used for this translation.

Ordinarily, RFC822 comments (see Section 35.3.4, "Comments in the Header Field") are restored when $g is used in headers. To omit those comments (perhaps for security reasons), you may use the F=c delivery agent flag (see Section 30.8.14, F=c).

$g is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.17 $h

Host part of the recipient address

(All versions)

Rule set 0 (see Section 29.6, "Rule Set 0") is used to resolve the recipient address into a triple: the delivery agent (with $#), the host part of the address (with $@), and the recipient user's name (with $:). The host part, from the $@, is made the value of $h. Once $h's value has been set, it undergoes no further rule-set parsing.

$h is intended for use in the A= equate (see Section 30.4.1) of delivery agent definitions. Normally, it is converted to all lowercase before use, but that conversion can be suppressed with the F=h delivery agent flag (see Section 30.8.23, F=h).

$h is transient. If defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.18 $H

The mail hub

(m4 technique)

The m4 nullclient feature (see Section 19.6.20, FEATURE(nullclient)) causes all mail to be sent to a central hub machine for handling. Part of what it does is to define the m4 macro MAIL_HUB:

define(`MAIL_HUB', `hub')dnl

This also causes $H to be defined as hub. If $H has a value, and if $R (the LOCAL_RELAY, see Section 31.10.32) does not, all local email is forwarded to hub. If $R is defined it takes precedence over $H for some mail. See Section 19.6.41, MAIL-HUB for a description of MAIL_HUB and how it interacts with LOCAL_RELAY.

31.10.19 $i

The queue identifier

(All versions)

Each queued message is identified by a unique identifier (see Section 23.2.1, "The Queue Identifier"). The $i macro contains as its value that identifier. Prior to V8.6 sendmail, $i had a value assigned to it only when a file was first placed into the queue. Beginning with V8.6 sendmail, $i is also given a value when the queue file is processed.

$i is not used by sendmail internally. It should be trusted for use only in the Received: and Message-ID: headers.

31.10.20 $j

Our official canonical name

(All versions)

The j macro is used to hold the fully qualified domain name of the local machine. It must be defined in the configuration file. [14]

[14] Except in V8 sendmail, where $j is automatically defined to be the fully qualified canonical name of the local host. However, it is still possible to redefine $j if necessary, for example, if sendmail cannot figure out your fully qualified canonical name or if your machine has multiple network interfaces and sendmail chooses the name associated with the wrong interface.

A fully qualified domain name is one that begins with the local hostname, which is followed by a dot and all the components of the local domain.

The hostname part is the name of the local machine. That name is defined at boot time in ways that vary with the version of UNIX.

The local domain refers to the DNS domain, not to the NIS domain. If DNS is running, the domain is defined in the /etc/resolv.conf file, for example,

domain wash.dc.gov

At many sites the local hostname is already fully qualified. To tell whether your site uses just the local hostname, run sendmail with a -d0.4 switch:

% /usr/lib/sendmail -d0.4 -bt < /dev/null
... some output here
canonical name: wash            <- not fully qualified
canonical name: wash.dc.gov     <- fully qualified

The j macro is used in two ways by sendmail. Because $j holds the fully qualified domain name, sendmail uses that name to avoid making SMTP connections to itself. It also uses that name in all phases of SMTP conversations that require the local machine's identity. One indication of an improperly formed $j is the following SMTP error:

553 wash.dc.gov.dc.gov host name configuration error

Here, $j was wrongly defined by adding the local domain to a $w that already included that domain:

# Our domain
DDdc.gov
# Our fully qualified name
Dj$w.$D

One way to tell whether $j contains the correct value is to send mail to yourself. Examine the Received: headers. The name of the local host must be fully qualified where it appears in them:

Received: by wash.dc.gov    ...other text here
             -^
             must be a fully qualified domain name

$j is also used: in the Message-Id: header definition; and as the canonical host-name following .IX HELO the HELO or EHLO command.

For all but V8 sendmail, $j must be defined in the configuration file. For V8 it is automatically defined. It must never be defined in the command line. $j must appear at the beginning of the definition of the SmtpGreetingMessage option (formerly $e, see Section 34.8.65). In using SunOS sendmail.mx, $w must also be the fully qualified domain name.

31.10.21 $k

Our UUCP node name

(V8.1 and above)

The UUCP suite of software gets the name of the local host from the uname(2) system call, whereas sendmail gets the name of the local host from the gethostbyname(3) system call. For sendmail to easily handle UUCP addresses, V8 sendmail also makes use of the uname(2) function.

First the host part of the fully qualified name returned by gethostbyname(3) is saved as the first string in the class $=w. Then uname(2) is called. If the call succeeds, the macro $k and the class k are both given the nodename value returned. If the call fails, both are given the same hostname value that was given to the $j. If the system does not have uname(2) available (if HASUNAME was not defined when sendmail was compiled; see Section 18.8.9, HAS...), sendmail simulates it. The sendmail program's internal replacement for uname begins by reading /etc/whoami. If that file does not exist or cannot be read, sendmail scans /usr/include/whoami.h for a line beginning #define sysname. If that fails and if sendmail was compiled with TRUST_POPEN [15] defined (see Section 18.8.51, TRUST-POPEN), sendmail executes the following command and reads its output as the UUCP node name:

[15] TRUST_POPEN is a security risk. Instead of defining it, consider creating an /etc/whoami file and populating it or defining $k directly in your configuration file.

uname -l

If all these fail, $k is set to be the same as $j.

$k is assigned its value when sendmail first begins to run. It can be given a new value either in the configuration file or from the command line. The -d0.22 debugging switch (see Section 37.5.6, -d0.22) can be used to watch uname() fail.

31.10.22 $l (lowercase L)

The From format

(V8.6 and earlier)

Prior to V8.7 sendmail, the l macro was used to define the look of the five character "From " header, and the format of the line was used to separate one message from another in a file of many mail messages. This role has been assumed by the UnixFromLine option. See Section 34.8.72 for a description of both this l macro and that new option.

31.10.23 $L

The Unknown Local User relay

(m4 technique)

A local user is one who evaluates to delivery on the local machine, even after aliasing. By defining LUSER_RELAY:

define(`LUSER_RELAY', `relay_host')dnl

any username that is not found in the passwd(5) file will be forwarded to relay_host. This check is made after aliasing but before processing of the ~/.forward file. The relay_host is assigned to the $L macro. The m4 technique then adds rules to rule set 5 of the configuration file that cause the user to be looked up with the user database class (see the name keyword for that class in Section 33.8.20, user). If the user's name is not found, the message is forwarded to the host defined by $L. (See Section 19.4.5 for a description of how to include a delivery agent specification with relay_host.)

31.10.24 $m

Domain part of hostname

(V8.1 and above)

Under V8 sendmail [16] the $m macro is used to store the domain part of the local host's fully qualified name. A fully qualified name begins with the local hostname followed by a dot and all the components of the local DNS domain.

[16] $m is the NIS domain for pre-V8 versions of Sun sendmail, and $m is the original user address for IDA sendmail.

The value in $m is derived from $w. When V8 sendmail first starts to run, it calls gethostname(3) to get the name of the local machine. If that call fails, it sets that local name to be localhost. Then sendmail calls gethostbyname(3) to find the official name for the local host, which is assigned to $w as that macro's initial value. V8 sendmail then looks for the leftmost dot in $w. If it finds one, everything from the first character following that dot to the end of the name then becomes the value for $m:

host.domain
     -^
     domain part made the value of $m

$m is initialized before the configuration file is read. Consequently, it may be redefined in the configuration file or as a part of the command line.

31.10.25 $M

Whom we are masquerading as

(m4 technique)

When you define MASQUERADE_AS using the m4 configuration technique, you both enable masquerading (see Section 19.6.42, MASQUERADE-AS) and assign that hostname to this $M macro. Note that defining $M will not enable masquerading. You must use the MASQUERADE_AS m4 configuration command to enable this service.

31.10.26 $n

The error message sender

(All versions)

The $n macro contains the name of the person from whom failed mail is returned. Traditionally, that value is the name mailer-daemon.

When delivery fails and notification of that failure is being prepared to be sent to the originating sender, sendmail "fakes up" a header. That header prepends the original header (and any included error messages). The sender of the error mail message (and the sender in the envelope) is taken from $n.

The n macro must contain either a real user's name or a name that resolves to a real user through aliasing. If sendmail cannot resolve $n to a real user, the following message is logged, and the returned error mail message is saved in /usr/tmp/dead.letter (see Section 18.8.34, PATH...):

Can't parse myself!

When an error mail message is sent, $f (see Section 31.10.14) is given the value of $n. Prior to V8.7, $n must be defined in the configuration file. Beginning with V8.7 sendmail, $n is automatically defined as MAILER-DAEMON when sendmail first starts up.

31.10.27 $o

Token separation operators

(V8.6 and earlier)

Prior to V8.7 the $o macro stored as its value a sequence of characters, any one of which could be used to separate the components of an address into tokens (see Section 8.3, "Rule Sets"). That role has been taken over by the V8.7 OperatorChars option (see Section 34.8.45).

For backward compatibility the $o macro is still honored by V8.7 sendmail in pre-version 7 configuration files (see Section 27.5, "The V Configuration Command").

31.10.28 ${opMode}

The startup operating mode

(V8.7 and above)

Beginning with V8.7, the ${opMode} holds as its value the operating mode that sendmail was started with. The operating mode is set with the -b command line switch (see Section 36.7.2, -b). For example, if sendmail were started as a daemon with -bd, the value in ${opMode} would become d.

Once set, ${opMode} retains its initial value as long as sendmail runs. It can be changed only by defining it in the configuration file. Currently, ${opMode} is used only in rule sets by the m4 redirect FEATURE (see Section 19.6.21, FEATURE(redirect)).

31.10.29 $p

The sendmail process id

(All versions)

The p macro contains the process ID of the sendmail that executes the delivery agent. Every process (running program) under UNIX has a unique identification number associated with it (a process ID). Process IDs are necessary to differentiate one incantation of a program from another. The sendmail program fork(2)'s often to perform tasks (like delivery) while performing other tasks (such as listening for incoming SMTP connections). All copies share the name sendmail; each has a unique process ID number.

$p is intended for use in header definitions but may also be used in the A= equate (see Section 30.4.1) of delivery agents.

$p is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.30 $q

The default format of the sender's address

(V8.6 and earlier)

Prior to V8.7 the q macro was used to specify the form that the sender's address would take in header definitions. It was most often used in the From: and Resent-From: header lines.

The definition of $q had to adhere to the standard form of addresses as defined by RFC822. It had to contain just an address or an address and a comment. The traditional definitions of $q were

Dq<$g>        <- as <george@wash.dc.gov>
Dq$g          <- as george@wash.dc.gov

Dq$x <$g>     <- as George Washington <george@wash.dc.gov>
Dq$g ($x)     <- as george@wash.dc.gov (George Washington)

The full name is not always known and so $x can be undefined  - pty). As a consequence, when the full name was included in the q macro definition, it was often wrapped in a conditional test:

Dq$g$?x ($x)$.
Dq$?x$x $.<$g>

Of these the second form was recommended for clients that forward all mail to a central mail-handling machine. If the full name was unknown locally, the header and envelope were identical and bracketed:

From: <user@slave.domain>         <- header
MAIL From: <user@slave.domain>    <- envelope

At the central mail-handling machine, both versions of the From: address were recognized as identical (only if the address was bracketed). As a consequence, the central machine deleted and recreated the From: line and added the full name if known.

Prior to V8.7, $q had to be defined in the configuration file because it was used to define the fields of the Resent-From: and From: headers (see Section 35.10.14, From:). Beginning with V8.7 sendmail, those headers are defined by using the $g and $x macros directly. For example,

H?F?Resent-From: $?x$x <$g>$|$g$.
H?F?From: $?x$x <$g>$|$g$.

To redefine them, you must either edit your configuration file or add new definitions to the LOCAL_CONFIG section of your mc file (see Section 19.6.30, LOCAL-CONFIG):

LOCAL_CONFIG
divert(9)
H?F?From: $?x$x $.<$g>
divert(0)

The divert() statements force the new header definitions to follow the default definitions, thus replacing them.

31.10.31 $r

The protocol used

(All versions)

The $r macro stores the name of the protocol that is used when a mail message is first received. If mail is received via SMTP or ESMTP, $r is set accordingly. Incoming UUCP mail sets $r to "UUCP" (using the -p switch). With V8.7, bounced mail will now assign $r the value "internal."

$r is intended for use in the Received: header definition:

HReceived: $?sfrom $s $.by $j$?r with $r$. id $i

The value in $r is saved to the qf file when the mail message is queued, and it is restored to $r when the queue is later processed.

$r is transient. It may be defined on the command line but should not be defined in the configuration file. Under V8 the -p switch (see Section 36.7.32) is the recommended way to assign a value to $r.

31.10.32 $R

The relay for unqualified names

(m4 technique, deprecated)

Using the m4 configuration technique, the $R macro stores the hostname defined by LOCAL_RELAY (see Section 19.6.31, LOCAL-RELAY). If $H has a value and if $R does not, all local email is forwarded to hub defined for $H. If $R is defined, it takes precedence over $H for some mail. See Section 19.6.41 for a description of MAIL_HUB and how it interacts with LOCAL_RELAY.

31.10.33 $s

The sender host's name

(All versions)

The $s macro contains the name of the sender's machine (host). $s is given the name of the local host as its value when sendmail starts, unless the -p command line switch (see Section 36.7.32) is used, in which case $s is given the value specified by that switch. Thereafter, $s is given a new value by sendmail only if the mail message was received via SMTP. For bounced mail, the $s value is always localhost.

The s macro is intended for use in the Received: header definition:

HReceived: $?sfrom $s $.by $j$?r with $r$. id $i

The phrase from host will be included in this header line if $s has any value. Here, host is the name of the sending machine.

The value in $s is saved to the qf file when the mail message is queued and restored to $s when the queue is later processed.

$s is transient. It may be defined on the command line but should not be defined in the configuration file.

31.10.34 $S

The Smart Host

(m4 technique)

Using the m4 configuration technique the $S macro stores the hostname defined by SMART_HOST (see Section 19.6.47, SMART-HOST). The smart host is the name of the host that can deliver all mail that the local host cannot. $S is most often used with UUCP sites to get DNS mail to the outside world.

31.10.35 $t

The current time in seconds

(All versions)

The $t macro contains the current date and time represented as an integer. The value of $t is set in two places:

  • When sendmail first begins to run, it presets several date-oriented macros internally to the date and time it was run. Among those are the $a, $d, $b, and $t macros. This initialization is done after the configuration file is read.

  • Each time a new envelope is created, the $d, $b, and $t macros are given a default that is the current time.

$t is intended for use in configuration-file header definitions. $t is transient. If it is defined in the configuration file or in the command line, that definition may be ignored by sendmail.

31.10.36 $u

The recipient's username

(All versions)

Rule set 0 (see Section 29.6) is used to resolve the recipient address into a triple: the delivery agent (with $#), the host part of the address (with $@), and the recipient's username (with $:). The recipient's username is then processed by rule set 2 (the generic rule set for all recipient addresses), then by the rule set indicated by the R= equate of the delivery agent (the custom recipient address processing), and finally by rule set 4 (postprocessing for all addresses).

If the delivery agent has the F=A flag set (see Section 30.8.12, F=A), that rewritten recipient's username is looked up in the aliases file and replaced with its alias if one exists. If it is not replaced and if the F=5 flag (see Section 30.8.3, F=5) is set, the address is rewritten by rule set 5 to possibly pick a new delivery agent and repeat this process. [17]

[17] Prior to V8.7 this behavior was all tied to the local delivery agent.

After aliasing, the rewritten recipient's username is then assigned to $u. If the delivery agent's F=w flag (see Section 30.8.43, F=w) is set, [18] the value of $u is then used to look up information about that user with getpwent(3). The user's home directory from pw_dir is made the value of the $z and used to access that user's ~/.forward and dead.letter files.

[18] Prior to V8.7, looking up the user's home directory was tied to the local delivery agent.

For all delivery agents the final value of $u may be used as a component of the delivery agent's A= (see Section 30.4.1) equate. For example,

A=uux - $h!rmail ($u)

Note that $u is special (see Section 30.4.1.3, "$u in A=") in delivery agent A= equates. If it is absent, sendmail speaks SMTP. If it is present and the F=m flag (see Section 30.8.30, F=m) is also pres-nt, the argument containing $u is repeated as many times as there are recipients.

In V8 sendmail, $u is also set to the original recipient (prior to aliasing) while the message headers are first being read. Therefore the original recipient information is available for use in the Received: header line. [19]

[19] In this use, V8's $u is similar to IDA's $m.

$u is transient. If it is defined in the configuration file or in the command line, that definition is ignored by sendmail.

31.10.37 $U

The UUCP name to override $k

(m4 technique)

When configuring with the m4 technique, you can include support for UUCP by using the MAILER(uucp) command (see Section 19.3.2, "MAILER()") in your mc file. With that support, you can override the use of $k (see Section 31.10.21) with a hostname of your choosing when prefixing a string of hosts with the local hostname:

here!lady!sonya!user
-^
insert local host name here

If $U has a value, its value will be inserted. If it lacks a value, $k will be inserted.

$U can be useful when several hosts provide UUCP services. It can be defined in your DOMAIN() file (see Section 19.3.3, "DOMAIN()") as a single name so that all outgoing UUCP mail will appear as though it is from a common host.

31.10.38 $v

The version of sendmail

(All versions)

The v macro contains the current version of the sendmail program, taken from the Version variable that is initialized in version.c of the sendmail source. In general, it is the SCCS revision number of the source. $v is used in defining the SmtpGreetingMessage ($e) option (see Section 34.8.65) and in Received: header lines (see Section 35.10.25).

The value given to $v can vary with the vendor. There is currently no standard for identifying variations on the sendmail program. Clearly, $v may not contain a true picture.

$v is internally defined when sendmail starts up. It may be redefined in the configuration file or as part of the command line.

31.10.39 $V

UUCP relay for class $=V

(m4 technique)

$V holds as its value the name of the host that will handle all UUCP mail for the class $=V. See Section 19.6.46, SITECONFIG for a discussion of UUCP relays in general and how this macro relates to $W, $X, and $Y macros.

31.10.40 $w

The short name of this host

(All versions)

When sendmail first starts to run, it calls gethostname(3) to get the name of the local machine. If that call fails, it sets that local name to be localhost. Then gethostbyname(3) is called to find the official name for the local host. If that call fails, the official name for the local host remains unchanged. The official name for the local host is assigned to $j.

If the V command's version (see Section 27.5) is 5 or higher, V8 sendmail discards the domain and assigns the result to $w (the short name):

here.us.edu
    -^
    from here to end of name discarded

If the version is 4 or less, $w is assigned the fully qualified name (and is identical to $j).

$w is then appended to class $=w (see Section 32.5.8). $=w is used internally by sendmail to screen all MX records that are found in delivering mail over the network. [20] Each such record is compared in a case-insensitive fashion to $=w. If there is a match, that MX record and all additional MX records of lower priority are skipped. This prevents sendmail from mistakenly connecting to itself.

[20] Prior to V8, only $w was checked.

Any of the following errors (or variations on them) indicate that $=w, $w, or $j may contain a faulty value, most likely from a bad configuration file declaration:

553 host config error: mail loops back to myself
553 Local configuration error, host name not recognized as local
553 host host name configuration error

Note that if $w is pulled from the name server and the host is running BIND, and a cache is being downloaded, $w could be periodically unresolved. In this instance, sendmail sleeps and retries the lookup.

$w is defined when sendmail starts up. It may be redefined in the configuration file or as part of the command line.

31.10.41 $W

UUCP relay for class $=W

(m4 technique)

$W holds as its value the name of the host that will handle all UUCP mail for the class $=W. See Section 19.6.46 for a discussion of UUCP relays in general and how this macro relates to $V, $X, and $Y macros.

31.10.42 $x

The full name of the sender

(All versions)

The $x macro holds the full name of the sender. When sendmail processes a mail message for delivery, it rewrites the sender's address using rule sets 3 and 0 so that it can determine whether the sender is local. If the sender is local, rule set 0 provides the sender's login name with the $: operator. Then, if the delivery agent's F=w flag (see Section 30.8.43) is set, [21] sendmail calls getpwent(3) using that login name as the argument. If the login name is known, getpwent(3) returns the sender's full name in its pw_gecos field. The sendmail program then processes that pw_gecos field, throwing away phone numbers and the like and converting the & character where necessary. The result, usually fairly close to the sender's full name, is the value assigned to the x macro.

[21] Prior to V8.7 this behavior was tied to the local delivery agent.

Under certain circumstances, sendmail places a different value in $x:

  • When sendmail first starts to run, it sets the full name to be the value of the NAME environmental variable. The -F command-line switch (see Section 36.7.20, -F) can overwrite that variable. If the operating mode is -q (see Section 23.6.1, "Periodically with -q") or -bd (see Section 36.7.5, -bd), the full name is reset to NULL. When mail is sent, this value is assigned to $x.

  • In processing the headers of a message, if sendmail finds a Full-Name: header (see Section 35.10.15, Full-Name:), it assigns the text of that header to the $x macro.

  • In sending a failed mail message, the login name of the sender is taken from $n, and the full name is set to be

Mail Delivery Subsystem

The $x macro is intended for use in header definitions. If used in the From: header definition, the sender's full name will then also appear in the SMTP envelope mail line.

Note that unusual gecos fields in the password file can cause pre-V8 mail to fail. Consider the following passwd(5) entry:

happy:123:456:Happy Guy ;-),Ext 789,,:/u/happy:/bin/sh

The gecos field here will be parsed by all but V8 sendmail into a value for $x that can yield a faulty header - one with unbalanced parentheses:

From: happy@our.domain (Happy Guy ;-))

V8 sendmail accepts only characters up to the first comma, semicolon, or percent as part of the full name and quotes the result, thus avoiding this problem.

$x is transient. If it is defined in the configuration file or the command line, that definition will be ignored by sendmail.

31.10.43 $X

UUCP relay for class $=X

(m4 technique)

$X holds as its value the name of the host that will handle all UUCP mail for the class $=X. See Section 19.6.46 for a discussion of UUCP relays in general and how this macro relates to $V, $W, and $Y macros.

31.10.44 $y

Name of the controlling tty

(All versions)

The $y macro holds the name of the controlling terminal device, if there is one. The controlling terminal is determined by first calling ttyname(3) with the sendmail program's standard error output as an argument. If ttyname(3) returns the name of a terminal device (such as /dev/ttya), sendmail strips everything up to and including the last / character and stores the result into $y.

$y is intended for use in debugging sendmail problems. It is not used internally by sendmail. In determining whether or not it can write to a user's terminal screen, sendmail calls ttyname(3) separately on its standard input, output, and error output without updating $y.

Note that the device name in $y depends on the implementation of ttyname(3). Under BSD UNIX, all terminals are in /dev, whereas under other versions of UNIX they may be in subdirectories such as /dev/ttys. Also note that $y is only defined if TTYNAME is defined (see Section 18.8.52, TTYNAME) when sendmail is compiled.

$y is transient. If it is defined in the configuration file or the command line, that definition will be ignored by sendmail. Finally, note that $y is set only when mail is being sent and so is of most value in headers.

31.10.45 $Y

UUCP relay for unclassified hosts

(m4 technique)

$Y holds as its value the name of the host that will handle all UUCP mail that was not otherwise handled by class $=V, $=W, or $=X. See Section 19.6.46 for a discussion of UUCP relays in general and how this macro relates to $V, $W, and $X macros.

31.10.46 $z

The recipient's home directory

(All versions)

The $z macro holds the location of the local user's home directory. This macro is given a value only if the delivery agent has the F=w flag set (see Section 30.8.43) [22] and if delivery is to a user (rather than a file or a program). The home directory is taken from the pw_dir field as returned by getpwent(3).

[22] Prior to V8.7 this behavior was tied to the local delivery agent.

The sendmail program uses $z to access a user's ~/.forward file and to save failed mail to a user's dead-letter file.

$z can be passed in the A= equate to a custom written local delivery agent. One reason to do so would be to deliver mail to a user's home directory, rather than to a central spool directory. $z is also very useful with the ForwardPath (J) option (see Section 34.8.27, ForwardPath (J)).

$z is transient. If it is defined in the configuration file or the command line, that definition will be ignored by sendmail.

31.10.47 $Z

Version of the m4 configuration

(m4 technique)

When you are configuring with the m4 technique, the version of the configuration file can be augmented by defining confCF_VERSION in your mc file:

define(`confCF_VERSION', `ver')dnl

This statement causes the value ver to be appended to the default value in $Z. A forward slash character will separate the two. The default value in $Z varies depending on your sendmail version. If your version were V8.8.4, the above m4 definition would yield the following macro definition:

DZ8.8.4/ver

$Z is generally used as part of the SmtpGreetingMessage ($e) option's declaration (see Section 34.8.65):

O SmtpGreetingMessage=$j Sendmail $v/$Z; $b

Note that this version is different from the version declared with the VERSIONID m4 macro (see Section 19.6.50, VERSIONID). Also note that this is the configuration file version, rather than the version of the sendmail program as stored in $v.

Prior to V8 sendmail the configuration file version was stored in $V.


Previous: 31.9 PitfallssendmailNext: 32. Class Macros
31.9 PitfallsBook Index32. Class Macros