Add Debugging for Detail

In rule-testing mode the -d rule-testing command can be used to turn debugging output on and off. Prior to V8.7 sendmail the -d could be specified only on the command line. Beginning with V8.7 sendmail, the -d may also be specified in rule-testing mode. We illustrate the latter technique here.

Debugging output can reveal in great detail how individual rules are being handled. A debugging category and level of , for example, causes sendmail to print the LHS of each rule as it is tried. To illustrate, consider the following (highly simplified) configuration-file rule set:

S0 R@ $#local $:$n handle <> form R$*<@$+>$* $#$M $@$R $:$1<@$2>$3 user@some.where R$+ $#local $:$1 local names

Normal output that is produced when a rule-set number and address are entered at the > prompt looks like this:

> 0 george rewrite: ruleset 0 input: george rewrite: ruleset 0 returns: $# local $: george

But if we turn on debugging using the -d rule-testing command:

> -d21.12

the output that is produced when the same rule-set number and address are entered is more verbose than it was before:

> 0 george rewrite: ruleset 0 input: george ---trying rule: @ --- rule fails ---trying rule: $* < @ $+ > $* --- rule fails ---trying rule: $+ ---rule matches: $# local $: $1 rewritten as: $# local $: george rewrite: ruleset 0 returns: $# local $: george

Observe that the first rule in rule set 0 (the lone @) does not match george in the workspace. Therefore that rule fails and is skipped. Then the more complicated rule ($*<@$+>$*) is tried, and it too fails. Finally, the $+ operator in the last rule matches george, and the workspace is rewritten.

Note that the extra output that is produced by -d can potentially run to many lines. To capture the output for later examination, consider running sendmail in rule-testing mode from within a script(1), emacs(1), or similar session.

Higher levels of debugging are also available for examining rules and rule sets. The level -d21.15 shows $digit operators on the RHS being substituted with values from the LHS. The level -d21.35 causes each comparison, token versus token, to be printed.

To turn off the extra debugging output, just reuse the -d rule-testing command and specify a level of zero:

> -d21.0

A -d with no category or level behaves the same as the -d command-line switch (see "The Syntax of -d"). It sets a default of -99.1.

Trick

In debugging large configuration files, the output that is produced by the -d21.15 switch can become too huge to examine conveniently. A good alternative (when modifying or adding rules) is to temporarily insert a fake subroutine call before and after individual rules to see what they do:

R$* $:$>TEST $1 fake subroutine call Rlhs rhs new rule R$* $:$>TEST $1 fake subroutine call

With the fake wrapper around the new rule (the name TEST is arbitrary), ordinary rule testing with -bt now shows how the address is rewritten by that rule:

rewrite: ruleset 3 input: ... rewrite: ruleset TEST input: ... rewrite: ruleset TEST returns: ... new rule acted here rewrite: ruleset TEST input: ... rewrite: ruleset TEST returns: ... rewrite: ruleset 3 returns: ... >

If you use this technique, remember, of course, to remove the fake subroutine calls before putting that configuration file into use.