19.1 The S Configuration Command | sendmail, 4th Edition

The S configuration command declares the start of a rule set. It is perhaps the simplest of all configuration commands and looks like this:

 S  ident

The S , like all configuration commands, must begin the line. The ident identifies the rule set. There can be whitespace between the S and the ident . If the ident is missing, sendmail prints the following error message and skips that particular rule-set declaration:

  configfile  : line  num  : invalid ruleset name: ""

Prior to V8.7 sendmail the ident could only be numeric. Beginning with V8.7 sendmail the ident can be numeric or alphanumeric . We cover the old form first, then the new.

19.1.1 Rule-Set Numbers

Prior to V8.7 sendmail , rule sets could be identified only by numbers. When a rule set is declared with an integer, that integer is taken to be the numeric identity of the rule set:

 S  #

Here, # is an integer such as 23. If the # is greater than 100 ^[1] (the maximum number of numbered rule sets allowed), or is negative, sendmail prints and logs the following error:

^[1] This limit is defined as one-half of MAXRWSETS, which is defined as 200 in sendmail/conf.h .

  configfile  : line  number  : bad ruleset # (  maximum  max)

and each rule following that bad rule-set declaration will produce the following error:

  configfile  : line  number  :  missing valid ruleset for "R  rule shown here"

19.1.2 Rule-Set Names

Beginning with V8.7 sendmail , rule sets can be declared with numbers (as in the previous section) or with more meaningful names. The form for a rule-set name declaration looks like this:

 S  name

The name can contain only ASCII alphanumeric characters and the underscore character. Any bad character causes that character and the characters following it to be silently ignored:

 My_rule   good  My rule   bad, name is "My"

Case is recognized; that is, Myrule and MYRULE are different names. You can use any name that begins with an uppercase letter. Names that begin with a lowercase letter or an underscore character are reserved for internal use by sendmail .

There can be, at most, MAXRWSETS/2 named rule sets (MAX...). Each rule set that is declared beyond that amount causes sendmail to print the following error and ignore that rule-set declaration:

  name  : too many named rulesets ( #  max)

When you declare a rule-set name, sendmail associates a number with it. That number is selected by counting down from MAXRWSETS. That is, the first name is given the number MAXRWSETS-1, the second is given the number MAXRWSETS-2, and so on. Named rule sets can be used anywhere that numbered rule sets can be used.

19.1.3 Associate Number with Name

When associating a named rule set with a number of importance, you can create that association when the name is declared. The form of such a combined declaration looks like this:

 S  name=num

Here, the rule set named name is declared. Instead of allowing sendmail to associate a number with it, you create the association yourself by following the name with an = character and then an integer num . Arbitrary whitespace can surround the = character. If the integer is missing or nonnumeric, sendmail prints the following error and skips that rule-set declaration:

  configfile  : line  num  : bad ruleset definition "  bad  "  (number required after `=')

Different names should not share the same number:

 Sfoo=1 Sfee=1

If they do, the second declaration will produce the following warning:

 WARNING: Ruleset fee=1 has multiple definitions

The same name cannot be given a different number. Consider the following example:

 SMyrule=1 SMyrule=2

This causes sendmail to print the following error and skip the second declaration:

  configfile  : line  num  : Myrule: ruleset changed value (old 1, new 2)

Named rule sets have numbers associated with them when they first appear. If you use a named rule set in an S= equate for a delivery agent and then later attempt to assign it a value, you will get an error such as the previous example:

 Mprog, P=sh, ...., S=  Myrule  , ... ... S  Myrule  =2

The solution is either to move the rule-set declaration (and its rules) so that they reside above the delivery agent declaration or to declare a numeric association in the delivery agent declaration instead of in the rule-set declaration:

 Mprog, P=sh, ...., S=  Myrule=2  , ... ... S  Myrule

You could also place just the S line above the delivery agent declaration and the rules, without the =2 , below it:

 S  Myrule=2  Mprog, P=sh, ...., S=  Myrule  , ... ... S  Myrule

In general, we recommend that you assign numbers to named rule sets only if there is a genuine need.

19.1.4 Macros in Rule-Set Names

Macros can be used in any or all of a part of a rule-set declaration. They can be used to declare a name:

 D{NAME}myname S${NAME}

or to declare a number:

 D{NUMBER}12 S${NUMBER}

or both a name and a number:

 D{NAME}myname D{NUMBER}12 S${NAME}=${NUMBER}

or even the whole thing:

 D{SET}myset=12 S${SET}

You can use single- and multicharacter sendmail macros in any combination. Macros can be used in any rule-set declaration, including subroutine calls inside rules:

 R $* < $=w > $*       $@ $>${NAME}

But they cannot be used in the S= or the R= of delivery agents :

 Mprog, P=sh, ..., S=$X, R=$X, ...    neither of these will work

Macros can be used in the command line to modify a configuration file when sendmail is run. Consider the desire to call one rule set when running as a daemon and another when processing the queue. You might declare such rules like this:

 R $*            $: $&A R daemon        $@ $>Daemon_ruleset R queue         $@ $>Queue_ruleset R $*            $@ $>UndefinedA_ruleset

The two different runs might look like this:

 #  /usr/sbin/sendmail -MAdaemon -bd  #  /usr/sbin/sendmail -MAqueue -q30m

The first defines the $A sendmail macro to have the value daemon and results in this subroutine call:

 R daemon        $@ $>Daemon_ruleset

The second defines the $A sendmail macro to have the value queue and results in this different subroutine call:

 R queue         $@ $>Queue_ruleset

Note that any different or missing command-line setting for $A will result in the fallback subroutine call:

 R $*            $@ $>UndefinedA_ruleset

Also note that you can also define multicharacter macros from the command line. But to protect such multicharacter names from being interpreted by the shell, you should quote them:

 #  /usr/sbin/sendmail -M"{RunMode}"daemon -bd  #  /usr/sbin/sendmail -M"{RunMode}"queue -q30m

Also note that defining macros from the command line can result in sendmail giving up special privileges.

19.1.5 Rule Sets and Lists of Rules

All rules ( R lines) that follow a rule-set declaration are added to and become part of that rule set:

 S0 R...   rules added to rule set 0  SMyset R...   rules added to rule set Myset  S1 R...   rules added to rule set 1

Rule sets need not be declared in any particular order. Any order that clarifies the intention of the configuration file as a whole is acceptable. If a rule set appears more than once in a configuration file, V8 sendmail will print a warning:

 WARNING: Ruleset  name  redefined   prior to V8.8  WARNING: Ruleset  name  has multiple definitions   V8.8 and above

and append the new rules to the old:

 S0 R...   rules added to rule set 0  S2 R...   rules added to rule set 2  S0   warning issued  R...   rules appended to earlier rule set 0

Note that the warning is given in all cases prior to V8.8, but beginning with V8.8, it is issued only in -bt rule-testing mode (Section 8.1) or if the -d37.1 debugging switch (-d37.1) is set.

Other configuration commands can be interspersed among rule definitions without affecting the rule set to which the rules are added:

 S0 R...   rules added to rule set 0  DUuucphost.our.domain R...   rules added to rule set 0

Prior to V8.10, any rules that appeared before the first S command were added to rule set 0 by default. With V8.10 and above, sendmail rejects any rules that are not preceded with a valid rule set definition.

19.1.6 Odds and Ends

Arbitrary text that follows a rule-set declaration is ignored unless it appears to be part of the declaration:

 S11 100 more rule sets   rule set 11  S11100 more rule sets   rule set 11100 is illegal  SMyset 100 more rule sets   rule set Myset

Although the first and last of these examples work, we recommend that you use the # commenting mechanism instead (available with version 3 and higher configuration files):

 S11 #100 more rule sets   rule set 11  S11#100 more rule sets   rule set 11  SMyset #100 more rule sets   rule set Myset

A rule-set declaration that has no rules associated with it acts like a do-nothing subroutine (one that returns its workspace unaltered):

 Stest1   rule set test1 without rules does nothing  Stest2 R $*     $@   rule set test2 also returns the workspace unaltered

19.1.7 Rule Sets and m4

When building a configuration file using the m4 technique (Section 4.1), sendmail reserves certain rule-set numbers and names for its own use. Using the m4 technique, you can add rules to those rule sets, but you cannot replace those rule sets with your own. A few m4 keywords are available to make adding rules easier. They affect rule sets 0 through 3 (now called parse through canonify ) directly, and other rule sets indirectly (see Table 4-2 in Section 4.3.3).

The configuration file created with the m4 technique uses quite a few rule sets beyond the base group . To avoid name collisions, we recommend you begin all your own named rules with a leading capital letter.