Mail Administration Guide

Address-Rewriting Rules

This section describes the details of rewriting rules and mailer descriptions.

Special Macros, Conditionals

Special macros are referenced with the construct $x, where x is the name of the macro to be matched (LHS) or inserted (RHS). Lowercase letters are reserved for special semantics, and some special characters are reserved to provide conditionals.

The macros shown in Table 3-9 must be defined to transmit information into sendmail.

Table 3-9 Required sendmail Macros


Macro	Description
`$a`	Origination date in ARPANET format
`$b`	Current date in ARPANET format
`$c`	Hop count
`$d`	Date in UNIX (`ctime()`) format
`$e`	Printed out when SMTP starts
`$f`	Sender from name
`$g`	Sender name relative to the recipient
`$h`	Recipient host
`$i`	Queue ID
`$j`	The official domain name for this site; should be the first word of the `$e` macro; `$j` should be in domain name format
`$k`	The UUCP node name (from `uname`)
`$l`	The format of the UNIX `From` line
`$m`	The domain part of the `gethostname` return value
`$n`	The name of the daemon (for error messages)
`$o`	List of characters that are considered tokens
`$p`	`sendmail`'s process ID
`$q`	Default format of the sender address. Specifies how a sender should appear in a message when it is created.
`$r`	Protocol used
`$s`	Sender's host name
`$t`	Numeric representation of the current time
`$u`	Recipient user
`$v`	Version number of `sendmail`
`$w`	Host name of this site
`$x`	Full name of the sender
`$z`	Home directory of the recipient
`$-`	Sender address

Note -

In the SunOS 4.x releases, $w is the fully qualified hostname. In the Solaris 2.6 release, $w is the short version of the hostname.

For example:

De$j Sendmail $v ready at $b
DnMAILER-DAEMON
DlFrom $g $d
Do.:%@!^=/
Dq$g$?x ($x)$.
Dj$H.$D

You should not need to change any of these macros except under unusual circumstances. For example, you might want to change the first line, which defines the banner for security. You might want to change the last two lines to make several hosts look like one host.

An acceptable alternative for the $q macro is:

$?x$x $.<$g>

This entry corresponds to the following two formats:

doe@acme.com (John Doe)
John Doe <doe@acme.com>

Some macros are defined by sendmail for use in mailer arguments or for other contexts.Table 3-10 shows these macros.

Table 3-10 Additional sendmail Macro Definitions


Macro	Description
`$m`	Domain name
`$p`	`sendmail` process ID

You can use three types of dates. The $a and $b macros are in ARPANET format; $a is the time as extracted from the Date: line of the message (if there was one), and $b is the current date and time (used for postmarks). If no Date: line is found in the incoming message, $a is also set to the current time. The $d macro is equivalent to the $a macro in UNIX (ctime) format.

The $f macro is the ID of the sender as originally determined; for a message mailed to a specific host, the $g macro is set to the name of the sender relative to the recipient. For example, suppose the sender eric sends a message to bollard@matisse from the machine ucbarpa. The value of $f will be eric and the value of $g will be eric@ucbarpa.

The $x macro is set to the full name of the sender, which can be determined in several ways. It can be passed as a flag to sendmail (from the value of the Full-name: line in the header or use the comment field of a From: line). If the name can't be determined from the Full-name: or From: lines, and if the message is being originated locally, the full name is looked up in the /etc/passwd file. It can also be read from the name environment variable.

When a message is sent, the $h, $u, and $z macros are set to the host, user, and home directory (if local) of the recipient. The first two macros are set from the $@ and $: part of the rewriting rules respectively.

The $p and $t macros are used to create unique strings (for example, for the Message-Id: field). The $i macro is set to the queue ID on this host; if put into the time stamp line, it can be useful for tracking messages. The $v macro is set to be the version number of sendmail; this is normally put in time stamps and is extremely useful for debugging. It can, however, be a security risk if a publicized bug with the current version can be exploited. The $w macro is set to the primary name of this host, as given by gethostname() and gethostbyname(). The $c field is set to the "hop count"; that is, the number of times this message has been processed, which can be determined by counting the time stamps in the message.

The $r and $s fields are set to the protocol used to communicate with sendmail and the sending host name.

You can specify conditionals by using the syntax:

$?x text1 $| text2 $

This example inserts text1 if the macro $x is set, and text2 otherwise. The else (c $|) clause can be omitted.

Special Classes

The class $=w is the set of all names by which this host is known. It can be used to delete local host names. The class $=m is set to the domain name.

Left-Hand Side of Address-Rewriting Rules

The left-hand side of rewriting rules contains a pattern. Normal words are matched directly. Dollar signs introduce "metasymbols," which match items other than simple words, like macros or classes. Table 3-11 shows the metasymbols.

Table 3-11 sendmail Left-Hand Side Metasymbols


Symbol	Matches
`$*`	Zero or more tokens
`$+`	One or more tokens
`$-`	Exactly one token
`$=x`	Any string in class `x`
`$~x`	Any token not in class `x`
`$x`	Macro `x`

If any of the patterns match, it is assigned to the symbol $n for replacement on the right-hand side, where n is the index in the LHS. For example, the LHS rules can be applied to this input:

$-:$+

JUPITER:eric

The rule will match, and the values passed to the RHS will be:

$1	JUPITER

$2	eric

Solaris-Specific Rules

Several special rules have been added to work with the name space. These rules are not generic to sendmail, so can only be used on systems running the Solaris software.

The special form $%y matches any host name in the hosts information in the name space. Either local or remote hosts can be matched using this rule. It does a most-to-least multitoken match, so it can handle fully qualified host names as well as a short local host name.

The $%x form matches MX records through DNS. This will succeed even if the A-record does not exist in the DNS database.

The $%l matches any fully qualified host in the local domain. If NIS or local files are being used, this means that the host name in the name space must include the local domain name or DNS forwarding has to be turned on. The NIS+ name space will qualify the host name appropriately, without any changes.

To use $%l in a NIS environment in which DNS forwarding cannot be set up and the name space cannot be changed to use fully qualified host names, add the following line into the configuration file:

DAhosts.byname

and replace all occurrences of %l with %A. You can use any non-conflicting letter in place of the A. This will turn off the need to look up fully qualified names, as long as the target host can be resolved to an IP address and it is a single token name. All resolved addresses are assumed to be local, so make sure that the name space does not contain any single-token host entries that are external to the mail domain.

Right-Hand Side of Address Rewriting Rules

When the left-hand side of a rewriting rule matches, the input is replaced by the right-hand side. Tokens are copied directly from the right-hand side, unless they begin with a dollar sign, in which case they are treated as macros and expanded.

Table 3-12 shows the metasymbols for more complicated substitutions.

Table 3-12 sendmail Right-Hand Side Metasymbols


Symbol	Description
`$x`	Expands macro `x`
`$n`	Substitutes indefinite token `n` from LHS; `n` is a digit
`$>n`	Calls rule set `n; n` is a digit
`$#mailer`	Resolves to `mailer`
`$@host`	Specifies `host`
`$:user`	Specifies `user`
`$[host$]`	Maps to primary host name
`${x name$}`	Maps name through NIS map or NIS+ table `$x`; if the map name begins with `rev`, `sendmail` will reverse the aliases.

The $n (n being a digit) syntax substitutes the corresponding value from a $+, $-, $*, or $~x match on the LHS. It may be used anywhere.

The $>n syntax substitutes the remainder of the line as usual and then passes it to rule set n. The final value of rule set n then becomes the substitution for this rule (like a procedure or function call).

Only use the $# syntax in rule set 0. Evaluation of the rule set stops immediately, and signals are sent to sendmail that the name has completely resolved. The complete syntax is:

$#mailer$@host$:user

This specifies the {mailer, host, user} triple necessary to direct the mailer. More processing may then take place, depending on the mailer. For example, local names are aliased.

A right-hand side may also be preceded by a $@ or a $: to control evaluation. A $@ prefix returns the remainder of the right-hand side as the value. A $: prefix terminates the rule immediately, but the rule set continues. Thus it can be used to limit a rule to one application. Neither prefix affects the result of the right-hand side expansion.

The $@ and $: prefixes can precede a $> spec. For example:

R$+	$:$>7$1

matches anything, passes that to rule set 7, and continues; the $: is necessary to avoid an infinite loop. The $[host]$ syntax replaces the host name with the "official" or primary host name, the one listed first in the hosts.byname NIS map, or /etc/hosts if not running NIS. It is used to eliminate nicknames for hosts. The ${x name $} syntax replaces the string by the result of the nis_map_name indicated in macro $x.

The rule below can be added to ruleset 0 to forward mail to the mail host from a system (like a router) that might not be able to route mail itself:

R$*<@$*.$m>		$#ether $@mailhost $:$1<@$2.$m>

Semantics of Rewriting Rule Sets

Five rewriting sets have specific semantics, as shown in Figure 3-2.

Figure 3-2 Rewriting Set Semantics

Rule set 3 is applied by sendmail before sendmail handles any name. Rule set 3 should turn the name into a form, with the basic syntax:

local-part@host-domain-spec

If no @ is specified, then the host-domain-spec may be appended from the sender name (if the C flag is set in the mailer definition corresponding to the sending mailer).

Rule set 0 is applied after rule set 3 to names that will actually specify recipients. It must resolve to a mailer, host, user triple. The mailer must be defined in the mailer definitions from the configuration file. The host is defined into the $h macro for use in the argument expansion of the specified mailer; the user is defined into $u.

Rule set 1 is applied to all From: recipient names, and rule set 2 is applied to all To: and Cc: lines. Then the rule sets specified in the mailer definition line (and R=) are applied. This process is done many times for one message, depending on how many mailers the message is routed to by rule set 0.

Rule set 4 is applied last to all names in the message. It is typically used to translate internal to external form.

`error` Mailer

You can use the mailer with the special name error in rule set 0 to generate a user error message. The user field is a message to be printed. For example, the entry:

$#error$:Host unknown in this domain

on the RHS of a rule generates the specified error if the LHS matches.

Semantics of Mailer Descriptions

Each mailer has an internal name. It can be arbitrary, except that the names local and prog must be defined first and second respectively. Rule set 0 resolves names to this mailer name (and a host and user name).

Give the path name of the mailer in the P field. If this mailer will be accessed by way of a TCP connection, use the string [TCP] instead.

Define the mailer flags in the F field. Specify an f or r flag to pass the name of the sender as an f or r flag respectively. To conform mailers that give errors under some circumstances, these flags are passed only if they were passed to sendmail. In some cases, you might be able to specify f$g in the argv template. If the mailer must be called as root, and sendmail is running setuid to root, use the S flag; it will not reset the user ID before calling the mailer. If this mailer is local (that is, will perform final delivery rather than another network hop), use the flag. Quoted characters (backslashes and double quotation marks) can be stripped from names if the s flag is specified; if it is not specified, they are passed through. If the mailer is capable of sending to more than one user on the same host in a single transaction, use the m flag. If this flag is on, then the argv template containing $u is repeated for each unique user on a given host. The e flag marks the mailer as being "expensive," and sendmail defers connection until a queue run. Note that the c configuration option must also be set.

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

From: eric@jupiter
To: joe@saturn, sam

is modified to:

From: eric@jupiter
To: joe@saturn, sam@ganymede

if and only if the C flag is defined in the mailer corresponding to eric@jupiter.

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

From: eric@host

might be changed to:

From: eric@host.colorado.edu

or:

From: saturn!eric

depending on the domain into which it is being shipped. These sets can also be used to do special-purpose output rewriting in cooperation with rule set 4.

Table 3-13 includes additional flags that you might use in the configuration file.

Table 3-13 Additional Flags for the Mailer Description


Field Name	Use
`E`	Defines the string to use as an end-of-line indication. A string containing `return` and `newline` is the default (if using TCP; otherwise just a `newline` indicates end-of-line. You can use the `print` backslash escapes (`/r`, `/n` `/f`, `/b`).
`A`	Specifies an argument vector template. It may have embedded spaces. The template is macro-expanded before being passed to the mailer. Useful macros include `$h`, the host name resolved by rule set 0, and `$u`, the user name (or names) resolved. If there is no argument with a `$u` macro in it, `sendmail` uses SMTP to communicate with the mailer. If the path name for this mailer is TCP, use the argument vector: `TCP $h [` `port` `],` where `port` is the optional port number to connect to.
`L`	Specifies the maximum length of the `$u` macro passed to the mailer. To make UUCP mail more efficient, you can use the `L` field with the `m` flag to send mail to multiple recipients with one call to the mailer, while avoiding mailer limitations on argument length. `$u` always expands to at least one recipient even if that recipient exceeds the `L=` limit.

For example, the specification:

Mlocal, P=/bin/mail, F=flsSDFMmnP, S=10, R=20, A=mail -d $u
Mprog,  P=/bin/sh,   F=lsDFMeuP,  S=10, R=20, A=sh -c $u

specifies a mailer for local delivery and a mailer for Ethernet delivery. The first is called local, is located in the file /bin/mail, takes an F flag, does local delivery, strips quotes from names, and delivers mail to multiple users at once. It applies rule set 10 to sender names in the message and applies rule set 20 to recipient names. The argument vector to send to a message is the word mail, the word d, and words containing the name of the receiving user. If you are inserting an r flag is inserted, place it between the words mail and d.

The second mailer is called ether. It is connected through TCP and can handle multiple users at once. It defers connections and appends any domain from the sender name to any receiver name without a domain; it processes sender names by rule set 11 and recipient names by rule set 21. Messages passed through this mailer have a 100,000-byte limit.