38.6.1 Syntax

The > prompt expects rule sets and addresses to be specified like this:

> ident,ident,ident... address

Each ident is a rule-set name or number. When there is more than one rule set, they must be separated from each other by commas (with no spaces between them).

For numbered rule sets, the number must be in the range of 0 through the highest number allowed. A number that is too large causes sendmail to print the following two errors:

bad ruleset number (max max)
Undefined ruleset number

A rule set whose number is below the maximum but that was never defined will act as though it was defined but lacks rules.

Named rule sets must exist in the symbol table. If the name specified was never defined, the following error is printed:

Undefined ruleset ident

If any rule set number in the comma-separated list of rule sets is omitted (e.g., ident,,ident), sendmail interprets the second comma as part of the second identifier, thus producing this error:

Undefined ruleset ,identifier

The address is everything following the first whitespace (space and tab characters) to the end of the line. If whitespace characters appear anywhere in the list of rule sets, the rule sets to the right of the whitespace are interpreted as part of the address.

38.6.2 The Address

Each address that is specified is processed by sendmail in the same way that mail addresses are processed when actual mail is being sent. Each is parsed and normalized so that everything but the actual address is thrown away. Each is then tokenized and placed into the workspace for rule-set processing. To illustrate, observe the following rule-testing session:

ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
> 0 bill (Bill Bix)
rewrite: ruleset  0   input: bill
rewrite: ruleset  0 returns: $# local $: bill
> 0 Bill Bix <bill>
rewrite: ruleset  0   input: Bill Bix < bill >
rewrite: ruleset  0 returns: $# local $: Bill Bix < bill >
> 3,0 Bill Bix <bill>
rewrite: ruleset  3   input: Bill Bix < bill >
rewrite: ruleset  3 returns: bill
rewrite: ruleset  0   input: bill
rewrite: ruleset  0 returns: $# local $: bill
>

The first test illustrates that sendmail strips RFC822-style comments from addresses before tokenizing them. This results in the (Bill Bix) being thrown away so that rule set 0 sees only the address bill.

The second test illustrates that sendmail does not internally recognize addresses in angle brackets. Instead, rule set 3 throws away everything but the address in angle brackets, as shown in the third test.

Note that in many actual configuration files, rule set 3 also focuses on the host part of the address. For this reason, you should always begin with rule set 3 unless you are tuning a particular rule for which you know the precise input required.

38.6.3 Rule 3 Always Called First with -bt

When sendmail starts to run in rule-testing mode, its appearance and initial behavior vary from vendor to vendor and from version to version. When rule-testing mode begins, sendmail always prints an introductory banner. Pre-V8 sendmail printed the following banner:

ADDRESS TEST MODE
Enter <ruleset> <address>
>

It is important to note that (unless a banner says otherwise) sendmail always calls rule set 3 first. That is, even if you try to test rule set 0, you always first see the effects of rule set 3.

Beginning with V8 sendmail, rule set 3 is no longer automatically called. To ensure that there is no confusion, V8 sendmail prints this banner:

ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
>

Note that in all versions the last line (the >) is a prompt. At this prompt, you can specify a rule set and an address or, beginning with V8.7, any of the commands shown in Section 38.1, "Overview".

38.6.4 The Output

Each line of output that is produced when rule testing begins with an indication of the rule set number being processed:

rewrite: ruleset  3   input: Bill Bix < bill >

The word input precedes each address that is about to be processed by a rule set:

rewrite: ruleset  3   input: Bill Bix < bill >

The word returns precedes each address that is the result of rewriting by a rule set:

rewrite: ruleset  3 returns: bill

When rule sets call other rule sets as subroutines, those calls are shown in the output with input and returns pairs. In the following, rule set 11 is called as a subroutine rule set from inside rule set 3:

rewrite: ruleset  3   input: Bill Bix < bill >
rewrite: ruleset  11  input: bill
rewrite: ruleset  11 returns: bill
rewrite: ruleset  3  returns: bill

The output can also contain rule set operators:

rewrite: ruleset  0 returns: $# local $: bill

In this output, the operators are printed as they would appear in the configuration file. The $# selects a delivery agent, and the $: specifies the user. Under old versions of sendmail those operators are printed in the output as control characters:

rewrite: ruleset  0 returns: ^V local ^X bill

The correspondence between control characters in the output and sendmail configuration file operators is given in Table 38.2.