4.3 m4 Macros by Function

The m4 technique uses a huge number of macros to accomplish the complex task of creating configuration files for all possible circumstances. Many are detailed in the reference section at the end of this chapter. Many others are documented in chapters dedicated to particular subjects. Here, we summarize many of the m4 macros by classification or function. Note that a comprehensive list of all m4 macros is available in Appendix A.

4.3.1 Options

Options can be set, unset, and changed in your mc file with simple define statements. For example, the following line sets the location of the alias file and thus the AliasFile option:

define(`ALIAS_FILE', `nis:-N mail.aliases')

Configuring options with the m4 technique is described in Section 24.4 (with the individual m4 option names listed in Table 24-3 of that section). Options are described in general in Chapter 24. We recommend you leap ahead to that chapter, learn about options that will make your use of sendmail more valuable, then return here.

4.3.2 Define sendmail Macros

Defined sendmail macros can be declared in your mc file. Those that are useful are listed in Table 21-5 of Section 21.7. That section also describes the general technique of defining sendmail macros via m4. To illustrate, for example:

define(`BITNET_RELAY', `host.domain')

causes the value host.domain to be assigned to an internal sendmail macro (currently $B). Non-m4 specific defined macros can be declared with the LOCAL_CONFIG technique (Section 4.3.3.1).

4.3.3 Rules and Rule Sets

Rules are used to rewrite mail addresses and to select delivery agents, among other things. They are organized in rule sets, which can be thought of as subroutines. We deal with rules and rule sets more deeply in Chapter 18 and Chapter 19. Here we only illustrate how the mc configuration method is used to insert custom rules and rule sets in a variety of convenient ways. We list all the mc keywords that affect rules and rule sets in Table 4-2. For completeness, we also list one keyword for adding delivery agents.

To illustrate, consider the following technique for adding a rule to the parse rule set 0:

LOCAL_RULE_0
R$* <@ $=w . $=m> $*        $#local $: $1      @here.ourdomain

Here, we add a rule to the parse rule set 0 that accepts any address with a host part in the class $=w ($=w) that is also in one of the local domains listed in the class $=m ($=m) as a local address.

4.3.3.1 LOCAL_CONFIG mc macro

The LOCAL_CONFIG mc macro allows custom configuration lines to be inserted in the configuration file by using the mc file. The inserted lines are carried literally into the output and appear in the resulting configuration file just before the options. The LOCAL_CONFIG mc macro should be used for sendmail macro, class, and map definitions, but not for rule set declarations. For rule sets, use the LOCAL_RULESETS mc macro (Section 4.3.3.5).

LOCAL_CONFIG
FE/usr/local/mail/visible.users
Khostmap hash /etc/hostmap

In this example the class $=E has additional names read from the file visible.users, and the hostmap database is declared.

If you wrongly include rule sets and rules with this LOCAL_CONFIG mc macro you might see the following warning:

Warning: OperatorChars is being redefined.
      It should only be set before rule set definitions.

4.3.3.2 LOCAL_RULE_0 mc macro

The parse rule set 0 first checks to see if the mail should be delivered locally. It then checks for other addresses, such as uucp and smtp. You can insert custom delivery agent selections of your own in parse rule set 0, after the local delivery selection, but before the uucp, smtp, and the like. To do this, use the LOCAL_RULE_0 mc macro:

LOCAL_RULE_0
# We service lady via an mx record.
R$+ < @ lady.Berkeley.EDU. >         $#uucp $@ lady $: $1

Here, we introduce a new rule to select a delivery agent. The host lady is a UUCP host for which we accept mail via an MX record.

In Section 19.5 we deal with the flow of rules through the parse rule set 0. For now merely note that LOCAL_RULE_0 fits into the flow of rules through the parse rule set 0 like this:

4.3.3.3 LOCAL_RULE_1 and LOCAL_RULE_2 mc macros

Rule sets 1 and 2 are normally empty and not included in the configuration file that is created from your mc file. Rule set 1 processes all sender addresses (Section 19.7.1). Rule set 2 processes all recipient addresses (Section 19.7.2). These two mc macros are used just like LOCAL_RULE_0, as shown earlier, but they introduce rules that would otherwise be omitted, rather than adding rules to an existing rule set.

Note that any modifications made to addresses in LOCAL_RULE_1 and LOCAL_RULE_2 are reflected in the headers of mail messages.

4.3.3.4 LOCAL_RULE_3 mc macro

All addresses are first rewritten by the canonify rule set 3 (Section 19.3). Thus, for complex configuration needs, it is handy to define special rules and add them to the canonify rule set 3. Note that new rules are added to the end of the canonify rule set 3 by way of rule set 96. That is, each final decision in the canonify rule set 3 calls rule set 96 (with $>96) before returning.

The LOCAL_RULE_3 mc macro is most often used to introduce new rules that can be used in canonicalizing the hostnames.

One suggested use for LOCAL_RULE_3 is to convert old UUCP hostnames into domain addresses using the UUCPSMTP mc macro. For example:

LOCAL_RULE_3
UUCPSMTP(decvax,   decvax.dec.com)
UUCPSMTP(research, research.att.com)

This causes the following address transformations:

decvax!user    becomes     user@decvax.dec.com
research!user  becomes     user@research.att.com

Another suggested use for LOCAL_RULE_3 is to introduce a new rule to look up hostnames in a locally customized database:

LOCAL_RULE_3
R$*<@$+>$*       $:$1<@ $(hostmap $2 $) >$3

The declaration and definition of local database maps with the K configuration command (Section 23.2) should appear in the LOCAL_CONFIG section.

4.3.3.5 LOCAL_RULESETS mc macro

Prior to V8.8 sendmail, you had to use the divert mc directive to force your new rule set declarations to be emitted alongside the normal mc-generated rule sets. Beginning with V8.8, that bit of "black magic" has been removed.

The LOCAL_RULESETS mc command causes all the rule sets and rules that follow it to be emitted into your configuration file along with all the rules that are automatically generated. You use it like this:

LOCAL_RULESETS
your new rule sets and rules here

4.3.3.6 SMART_HOST mc macro

Some sites can deliver local mail to the local network but cannot look up hosts on the Internet with DNS. Usually, such sites are connected to the outside world through a firewall, or with UUCP. To ensure delivery of all mail, such sites need to forward all nonlocal mail to a smart (or well-connected) gateway host.

You can enable this behavior by defining SMART_HOST. In a firewall situation, all nonlocal mail should be forwarded to a gateway machine for handling:

define(`SMART_HOST', `gateway.your.domain')

In the case of a site that is only UUCP-connected, all nonlocal mail will need to be forwarded to an Internet-connected host over UUCP:

define(`SMART_HOST', `uucp-dom:supporthost')

Here, Internet mail will be forwarded to the host supporthost using the uucp-dom delivery agent.

For information about other ways to use SMART_HOST, see the file cf/README.

4.3.3.7 LOCAL_NET_CONFIG mc macro

LOCAL_NET_CONFIG is chiefly intended as a place to override settings of the SMART_HOST mc macro (Section 4.3.3.6). To illustrate, consider one possible setup for mail. The idea is to allow hosts on the local network to deliver directly to each other but to have all other mail sent to a "smart host" that forwards that mail offsite. Commonly, such arrangements are used by sites with in-house networks that have access to the outside world only through a UUCP link. For such sites you can use LOCAL_NET_CONFIG:

define(`SMART_HOST', `relay:uucp-gateway')
LOCAL_NET_CONFIG
R $* < @ $+ .$m. > $*     $#smtp $@ $2.$m $: $1 < @ $2.$m > $3

Here, SMART_HOST is defined as relay:uucp-gateway (meaning: send to the host uucp-gateway with the relay delivery agent). The LOCAL_NET_CONFIG then introduces a rule that causes all names that end in your domain name ($m) to be delivered via the smtp delivery agent. Any other addresses fall through and are handled by the SMART_HOST rules.

In Section 19.5 we deal with the flow of rules through the parse rule set 0. For now, merely note that LOCAL_NET_CONFIG fits into the flow of rules through the parse rule set 0 like this: