m4 sendmail Macros

The sendmail distribution comes with several sample configuration files. "sendmail " provides an example of how the tcpproto.mc file is modified to produce a configuration file suitable for a Linux system. The prototype files are m4 macro configuration files that produce usable sendmail.cf files as output. The prototype files are located in the sendmail/cf/cf directory of the sendmail distribution. Use those prototypes as examples of reasonable sendmail configurations.

All of the sendmail configuration files are composed of the following m4 macros: [164]

[164]By convention, m4 macros are shown in uppercase, and built-in m4 commands are shown in lowercase.

The built-in m4 commands shown above -- those listed in lowercase characters -- are divided between those that control the flow of output and those that set macro values. The two commands that control the flow of output are dnl and divert. Text following the dnl command is not sent to the output file. Thus it is used at the beginning of a line on a comment. The divert(-1) command sends output to the "bit-bucket" and marks the start of a block of comments. The divert(0) command directs output to standard m4 processing. In addition to -1 and , the divert command accepts nine other numeric arguments: the values 1 to 9. These other values are used in the m4 macro source code to direct data to various parts of the sendmail.cf file. You will not use these values in your own configuration. Instead you will use other commands to direct data to specific parts of the sendmail.cf file.

The commands LOCAL_CONFIG, LOCAL_USER, LOCAL_RULESETS, AILER_DEFINITION, LOCAL_NET_CONFIG, and LOCAL_RULE allow you to send data to various parts of the sendmail.cf file without using the various divert values directly. Commands such as LOCAL_CONFIG and MAILER_DEFINITION mark the start of raw sendmail.cf code that should be included in some part of the output file. These commands make it possible for you to customize the sendmail.cf file in any possible way.

The built-in m4 commands define and undefine set macro values. define sets a variable to a value and undefine resets it to its default value. More configuration parameters can be controlled through the define command than through any other, and, correspondingly, more of this appendix is dedicated to define parameters than to anything else.

Almost half of the m4 macros act like the define command and simply set a parameter to a value. MASQUERADE_AS, ASQUERADE_DOMAIN, RELAY_DOMAIN, and VIRTUSER_DOMAIN_FILE are all examples of commands used to set variables.

The TRUST_AUTH_MECH macro is a good example of a macro that complements a define. As you'll see in , "define" of this appendix, the parameter confAUTH_MECHANISMS can be used to define the trusted authentication mechanisms your server advertises to other servers. The TRUST_AUTH_MECH macro is the inverse of this. It identifies the mechanism that your server accepts from other servers. The same list of keywords used to configure the confAUTH_MECHANISMS parameter in , "define" can be used to configure TRUST_AUTH_MECHANISMS.

The macro names OSTYPE, DOMAIN, FEATURE, MAILER, HACK, and SITECONFIG are all names of subdirectories within the cf directory. The value passed to each of these macros is the name of a file within the specified directory. For example, the command FEATURE(nouucp) tells m4 to load the file nouucp.m4 from the ostype directory and process the m4 source code found there. The m4 source files pointed to by the OSTYPE, DOMAIN, FEATURE, and MAILER commands are built primarily from define and FEATURE commands.

Two of the macros that are also directory names, SITECONFIG and HACK, are rarely used. SITECONFIG points to a source file that contains SITE macros that define the UUCP sites connected to the local host. You create the file containing the SITE macros yourself and then invoke it with the SITECONFIG command. These commands, along with UUCPSMTP, are obsolete and maintained only for backward compatibility.

The HACK macro points to an m4 source file that contains a temporary site-specific fix to a sendmail problem. You create the file in the hack directory and then use the HACK command to add that file to the configuration. The use of hacks is discouraged and is generally unnecessary.

The following section provides additional information about the OSTYPE, DOMAIN, FEATURE, and MAILER macros and details of the various commands used to build the m4 source files they call. "sendmail " provides an example of building a custom DOMAIN macro source file. The source files can contain any of the macros we have already mentioned as well as the additional ones documented below. The macro configuration (mc) file also can contain any of the commands documented below. In fact, pretty much any macro can appear in any file.

To bring some order out of this chaos, the commands are organized according to the files they are most likely to appear in, which is similar to the organization found in the documentation that comes with the sendmail distribution. Just remember, actual implementation files may have a different organization. We start by examining the define macros and the FEATURE macros that are the primary building blocks of all the other files.

define

The syntax of the define macro is: 

define(`parameter' `value')

where parameter is the keyword name of a sendmail configuration parameter and value is the value assigned to that configuration parameter. The parameter and the value are normally enclosed in single quotes to prevent inappropriate macro expansion. These are not balanced quotes. The opening quote is a grave sign (`), and the closing quote is an apostrophe (').

Many of the configuration parameters that can be set using the define command are shown below. Most of the parameters correspond to sendmail options, macros, or classes. The name of the option, macro, or class set by the parameter is listed in the parameter description enclosed in square brackets ([]). Macro names begin with a dollar sign ($j), class names begin with a dollar sign and an equals sign ($=w), and options are shown with long option names (SingleThreadDelivery). To find out more about these parameters, see the descriptions of the macros, options, and classes they represent that are provided later in this appendix.

Because many define parameters are equivalent to options, macros, and classes, the command: 

define(`confDOMAIN_NAME', `rodent.wrotethetutorial.com')

placed in an m4 source file has the same effect as: 

Djrodent.wrotethetutorial.com

placed directly in the sendmail.cf file. If you compile and install a new version of sendmail, build your configuration with m4 and set values for macros, classes, and options with the m4 define macro.

The list of define parameters is quite long. However, because most of the parameters default to a reasonable value, they do not have to be explicitly set in the m4 source file. The default value of each parameter is shown in the listing -- unless there is no default.

define macros are the most common macros in the m4 source files. The next most commonly used macro is the FEATURE macro.

FEATURE

The FEATURE macro processes m4 source code from the cf/feature directory. Source files in that directory define optional sendmail features that you may wish to include in your configuration. The syntax of the FEATURE macro is: 

FEATURE(name, [argument])

The FEATURE source file can be called with or without an optional argument. If an argument is passed to the source file, the argument is used by the source file to generate code for the sendmail.cf file. For example: 

FEATURE(`mailertable', `hash /etc/mail/mailertable')

generates the code for accessing the mailertable and defines that table as being a hash database located in the file /etc/mail/mailertable.

There are several features available in sendmail V8. They are all listed in Table E-3. The table provides the name of each feature and its purpose.

Table E-3. sendmail features

Name Purpose
use_cw_file Load $=w from /etc/mail/local-host-names.
use_ct_file Load $=t from /etc/mail/trusted-users.
relay_based_on_MX Relay mail for any site whose MX points to this server.
relay_entire_domain Relay mail for any host in your domain.
relay_hosts_only Only relay mail for hosts listed in the access database.
relay_local_from Relay mail if the source is a local host.
relay_mail_from Relay mail if the sender is listed as RELAY in the access database.
promiscuous_relay Relay mail from any site to any site.
rbl The obsolete Realtime Blackhole List feature has been replaced by dnsbl.
dnsbl Reject mail from hosts listed in a DNS-based rejection list. Replaces rbl.
blacklist_recipients Filter incoming mail based on values set in the access database.
delay_checks Delay the check_mail and check_relay rulesets until check_rcpt is called.
loose_relay_check Disable validity checks for addresses that use the % hack.
redirect Support the .REDIRECT pseudo-domain.
no_default_msa Allow the default configuration of the Message Submission Agent to be overridden by the DAEMON_OPTIONS macro.
nouucp Don't include UUCP address processing.
nocanonify Don't convert names with $[name$] syntax.
stickyhost Treat "user" differently than "user@local.host".[166]
mailertable Mail routing using a mailer table.
domaintable Domain name mapping using a domain table.
access_db Relay control using the access database.
bitdomain Use a table to map bitnet hosts to Internet addresses.
uucpdomain Use a table to map UUCP hosts to Internet addresses.
accept_unqualified_senders Allow network mail from addresses that do not include a valid hostname.
accept_unresolvable_domains Accept mail from hosts that are unknown to DNS.
always_add_domain Add the local hostname to all locally delivered mail.
allmasquerade Also masquerade recipient addresses.
limited_masquerade Only masquerade hosts listed in $=M.
masquerade_entire_domain Masquerade all hosts within the masquerading domains.
masquerade_envelope Also masquerade envelope addresses. The default is to masquerade only header addresses.
genericstable Use a table to rewrite local addresses.
generics_entire_domain Map domain names identified in class G through the genericstable.
virtusertable Map virtual domain names to real mail addresses.
virtuser_entire_domain Map domain names through the virtusertable.
ldap_routing Enable LDAP-based email routing.
nodns Don't include DNS support.
nullclient Forward all mail to a central server.
local_lmtp Use mail.local with LMTP support.
local_procmail Use procmail as the local mailer.
bestmx_is_local Accept mail as local when it is addressed to a host that lists us as its MX server.
smrsh Use smrsh as the prog mailer.
[166] See the discussion of "stickyhost" in the "DOMAIN" section later in this appendix.

The use_cw_file and the use_ct_file features are equivalent to Fw/etc/sendmail.cw and Fw/etc/sendmail.ct commands in the sendmail.cf file. See "sendmail " for descriptions of host aliases ($=w) and trusted users ($=t).

The .REDIRECT pseudo-domain code returns an error message to the sender telling the sender to try a new address for the recipient. This is used to handle mail for people who no longer read mail at your site but who are still getting mail sent to a very old address. Enable this feature with the FEATURE(redirect) command and then add aliases for each obsolete mailing address in the form: 

old-address new-address.REDIRECT

For example, assume that Edward Winslow is no longer a valid user of crab.wrotethetutorial.com. Therefore, his old username, ed, should no longer accept mail. His new mailing address is WinslowE@industry.com. We enter the following alias in the /etc/aliases file: 

ed WinslowE@industry.com.REDIRECT

Now when mail is sent to the ed account on crab, the following error is returned to the sender: 

User not local; please try <WinslowE@industry.com>

Several of the FEATURE macros actually remove features from the sendmail.cf file instead of adding them. nouucp removes the code to handle UUCP addresses for systems that do not have access to UUCP networks, and nodns removes the code for DNS lookups for systems that do not have access to DNS. nocanonify disables the $[name]$ syntax that converts nicknames and IP addresses to canonical names. Finally, the nullclient feature strips everything out of the configuration except for the ability to forward mail to a single mail server via a local SMTP link. The name of the mail server is provided as the argument on the nullclient command line. For example, FEATURE(nullclient, ms.big.com) forwards all mail to ms.big.com without any local mail processing.

Several features relate to mail relaying and masquerading. Examples include stickyhost, relay_based_on_MX, allmasquerade, limited_masquerade, and masquerade_entire_domain. All of these features are covered in the "DOMAIN" section later in this appendix.

Several of the features define databases that are used to perform special address processing. All of these features accept an optional argument that defines the database. (See the sample mailertable command at the beginning of this section for an example of defining the database with the optional argument.) If the optional argument is not provided, the database description always defaults to hash -o /etc/mail/filename, where filename matches the name of the feature. For example, mailertable defaults to the definition hash -o /etc/mail/mailertable. The database features are:

Some features are important in the fight against spam because they help you control what mail your server will deliver or forward on for delivery. These are accept_unqualified_senders, accept_unresolvable_domains, access_db, blacklist_recipients, and dnsbl. The access database lists email sources and how mail from these sources should be treated. The dnsbl uses a special DNS database to reject mail from specific sources. The blacklist_recipients feature extends the access_db and dnsbl controls to email destinations as well as email sources. Two of the features, accept_unqualified_senders and accept_unresolvable_domains, weaken relay controls by allowing relaying for hosts or domains that cannot be found via DNS. Use care when adjusting these controls.

Two of the remaining FEATURE commands relate to domains. The always_add_domain macro makes sendmail add the local hostname to all locally delivered mail, even to those pieces of mail that would normally have just a username as an address. The bestmx_is_local feature accepts mail addressed to a host that lists the local host as its preferred MX server as if the mail was local mail. If this feature is not used, mail bound for a remote host is sent directly to the remote host even if its MX record lists the local host as its preferred MX server. The bestmx_is_local feature should not be used if you use a wildcard MX record for your domain.

The last two features are used to select optional programs for the local and the prog mailers. local_procmail selects procmail as the local mailer. Provide the path to procmail as the argument in the FEATURE command. The smrsh feature selects the sendmail Restricted SHell (smrsh) as the prog mailer. smrsh provides improved security over /bin/sh, which is normally used as the prog mailer. Provide the path to smrsh as the argument in the FEATURE command.

The FEATURE commands discussed in this section and the define macros discussed previously are used to build the m4 source files. The following sections describe the purpose and structure of the OSTYPE, DOMAIN, and MAILER source files.

OSTYPE

The source file for the OSTYPE macro defines operating system-specific parameters. Many operating systems are predefined. Look in the sendmail/cf/ostype directory for a full listing of the systems that are already defined.

OSTYPE source files are mostly composed of define macros. Table E-4 lists the define parameters most frequently associated with the OSTYPE source file and the function of each parameter. If a default value is assigned to a parameter, it is shown enclosed in square brackets after the functional description.

Despite the long list of parameters in Table E-4, most OSTYPE macros are very short. There are a few reasons for this. First, many of the parameters in the table are redundant. They define the same things for different mailers, and no operating system uses all of the mailers. Second, the default values are often correct. A define only needs to be made if the operating system requires a value different from the default.

DOMAIN

The DOMAIN source file defines configuration parameters that are related to the local domain. "sendmail " provides an example of a DOMAIN file built for the imaginary wrotethetutorial.com domain.

Table E-5 shows some define macros that commonly appear in DOMAIN files. (See the syntax of the define macro earlier.) This table lists the parameters and the function of each parameter. All of these parameters are used to define mail relay hosts. The value provided for each parameter is either a hostname, i.e., the name of a mail relay server, or a mailer:hostname pair where the mailer is the internal name of a local sendmail mailer and the hostname is the name of the remote mail relay server. If only a hostname is used, the mailer defaults to relay, which is the name of the SMTP relay mailer. If no values are provided for these parameters, the BITNET, DECNET, and FAX pseudo-domains are not used, and the local host must be able to handle its own UUCP and "local" mail.

Table E-5. Mail relay define macros

Parameter Function
UUCP_RELAY Server for UUCP-addressed email
BITNET_RELAY Server for BITNET-addressed email
DECNET_RELAY Server for DECNET-addressed email
FAX_RELAY Server for mail to the .FAX pseudo-domain[167]
LOCAL_RELAY Server for unqualified names
LUSER_RELAY Server for apparently local names that really aren't local
MAIL_HUB Server for all incoming mail
SMART_HOST Server for all outgoing mail
[167] The "fax" mailer overrides this value.

The precedence of the relays defined by these parameters is from the most specific to the least specific. If both the UUCP_RELAY and the SMART_HOST relay are defined, the UUCP_RELAY is used for outgoing UUCP mail even though the SMART_HOST relay is defined as handling "all" outgoing mail. If you define both LOCAL_RELAY and AIL_HUB, you must also use the FEATURE(stickyhost) command to get the expected behavior.

When the stickyhost feature is specified, LOCAL_RELAY handles all local addresses that do not have a host part, and MAIL_HUB handles all local addresses that do have a host part. If stickyhost is not specified and both relays are defined, the LOCAL_RELAY is ignored and AIL_HUB handles all local addresses.

In addition to the defines shown in Table E-5, there is a group of macros that relate to masquerading and relaying that also appear in the DOMAIN source file. Some of these are used in the examples in "sendmail ". The macros are:

There are several features that affect relaying and masquerading. We have already discussed FEATURE(stickyhost). Others are:

Some features define how the server handles mail if it is the mail relay server. These features, which are mentioned in the "FEATURE" section earlier in this appendix, are:

Inbound mail can also be filtered to reduce the impact of spammers. Two macros are available for this purpose:

The DOMAIN source file is also used for features and macros that directly relate to DNS. These features are:

The DNS macros are:

The macros and features described in this section are not limited to the DOMAIN source file. They can appear in any m4 source file, and, in fact, are often found in the macro control file. However, they are most naturally associated with the DOMAIN file as indicated by the documentation in the cf/cf/README file.

MAILER

It is possible that you will need to customize a file location in an OSTYPE file or that define domain-specific information in a DOMAIN file, but unless you develop your own mail delivery program you will not need to create a MAILER source file. Instead, you will need to invoke one or more existing files in your macro configuration file.

The available MAILER files are listed in Table E-6. This table lists each MAILER value and its function. These are invoked using the MAILER(value) command in the macro configuration (mc) file, where value is one of the mailer names from the table.

Your macro configuration file should have a MAILER(local) and a MAILER(smtp) entry. This gives you the local and prog mailers required by sendmail, the smtp mailer for standard SMTP mail, the esmtp mailer for Extended SMTP, the smtp8 mailer for 8-bit MIME mail, and the relay mailer for the various mail relay servers mentioned in the "DOMAIN" section of this appendix. Selecting local and smtp provides everything you need for a standard TCP/IP installation.

Of all the remaining mailers, only uucp is widely used. uucp provides UUCP mail support for systems directly connected to UUCP networks. The uucp-old mailer supports standard UUCP mail, and the uucp-new mailer is used for remote sites that can handle multiple recipients in one transfer. The system needs the mailer that is correct for the capabilities of the remote site. Use class U to define the hostnames of systems that need the old mailer, and class Y for the names of remote systems that can work with the new mailer. Specify AILER(uucp) after the MAILER(smtp) entry if your system has both TCP/IP and UUCP connections. Ordering the MAILER statements in this way adds two more mailers to the two standard UUCP mailers: the uucp-dom mailer to support standard domain names, and the uucp-uudom mailer to support standard domain names with a standard UUCP envelope.

The other mailers are rarely used:

This concludes our discussion of m4 macros. The output of all of the files and commands that go into the m4 processor is a sendmail.cf file. The remainder of this appendix provides additional details about the sendmail.cf configuration. The bulk of information about sendmail.cf is found in "sendmail ".