Relevant Issues

Relevant Issues

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

Testing and Debugging the Rewrite Rules

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

Using Alternative Configuration Files

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

Test Mode

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

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

In this mode, sendmail processes lines of the form

rwsets address

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

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

3,1,21,4 monet@giverny

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

3,0 foo@bar

might result in output that looks like this:

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

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

The -d21 Debugging Flag

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

The Debugging Rewrite Rule

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

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

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

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

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

Building Mailer Definitions

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

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

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

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

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

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

will be modified to

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

Other flags are described in "Mailer Flags".

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

For example, depending on the domain it is being shipped into, a header of the form "From: jd" might be changed to "From: jd@company.com" or "From: company!jd."

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

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

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

IPC $h [ port ]

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

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

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

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

It escapes lines beginning with "From" in the message with a ">" sign.
It expects "Date:", "From:", and "Message-Id:" header lines.
It does local delivery.
It strips quotation marks from addresses.
It sends to multiple users at once.
It expects uppercase to be preserved in both host and user names.

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

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

It handles multiple users at the same time.
It expects "Date:", "From:", and "Message-Id:" header lines.
It expects uppercase to be preserved in both host and user names.
It uses the hidden-dot algorithm of RFC 821.
It rewrites addresses so that any domain from the sender address is appended to any receiver name without a domain.

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