[Appendix E] E.3 m4 sendmail Macros

E.3 m4 sendmail Macros

The sendmail distribution comes with several sample configuration files. Chapter 10 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 useable sendmail.cf files as output. The prototype files are located in the sendmail/cf/cf directory of the sendmail distribution. All of the m4 macro configuration files end with the .mc file name extension. The .mc files can be composed of the following m4 macros: [1]

[1] The macro commands are listed in the order they would occur in the configuration file.

VERSIONID: Defines the version number of the .mc source file. RCS or SCCS version numbers are commonly used. This command is optional.
OSTYPE: Points to the m4 source file that contains the operating system-specific information for this configuration. This is required.
DOMAIN: Points to the m4 source file that contains configuration information specific to this domain. This is optional.
FEATURE: Points to an m4 source file that defines an optional sendmail feature. This is not required for m4 to process the .mc source file, but many configurations have multiple FEATURE entries.
HACKS: Points to an m4 source file that contains site-specific configuration information. This is a temporary configuration used to fix a temporary problem. The use of HACKS is discouraged.
SITECONFIG: Points to a source file that contains m4 SITE commands that define the UUCP sites connected to this host. The format of the command is: SITECONFIG( file , local-hostname , class ) , which reads the UUCP hostnames from file into class .
define: Defines a local value. Most "defines" are done in the m4 source files that are called by the .mc file, not in the .mc file itself. It can define a value for a sendmail.cf macro, option, or other command.
MAILER: Points to an m4 source file that contains the configuration commands that define a sendmail mailer. A least one MAILER command must appear in the configuration file. Generally more than one MAILER command is used.
LOCAL_RULE_n: Heads a section of code to be added to ruleset n , where n is 0, 1, 2, or 3. The code that follows the LOCAL_RULE_n command is composed of standard sendmail.cf rewrite rules. [2] The LOCAL_RULE_ n command is rarely used.

[2] The one exception to this is the UUCPSMTP macro that can be used in the local rule. See the New sendmail Configuration Files document that come with the sendmail V8 distribution if you have questions about UUCP configuration.
LOCAL_CONFIG: Heads a section of code to be added to the sendmail.cf file after the local information section and before the rewrite rules. The section of code contains standard sendmail.cf configuration commands. This macro is rarely used.

Most of the macros in the .mc file point to other m4 source files. The macro names OSTYPE, DOMAIN, FEATURE, MAILER, HACKS, and SITECONFIG are all names of subdirectories within the sendmail/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 feature directory and process the m4 source code found there. The real meat of the sendmail configuration is contained in the source files pointed to by the OSTYPE, DOMAIN, FEATURE, and MAILER commands.

The macro commands HACK, SITECONFIG, LOCAL_RULE_ n , and LOCAL_CONFIG are rarely used in a macro configuration file. To simplify this appendix, we do not mention them again. [3] Likewise, for the sake of simplicity we avoid discussing UUCP configuration and concentrate on SMTP. Still, m4 configuration can appear to be enormously complex. Please remember that this appendix is a reference, and as such lists as many of the m4 macros as possible. Most of these you will never need to use. Refer to Chapter 10 for a realistic example of how m4 is used to build a sendmail.cf file.

[3] To see examples of some of these commands, look at the ucbvax.mc sample file that comes with the sendmail V8 distribution.

In the following section we provide 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. Chapter 10 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, we have organized the commands according to the files they are most likely to appear in, which is similar to the organization found in the documentation that comes with 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.

E.3.1 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.

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 equal 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', 'peanut.nuts.com')

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

Djpeanut.nuts.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.

confMAILER_NAME: Default is MAILER-DAEMON. The sender name used on error messages. [$n]
confDOMAIN_NAME: The full hostname. [$j]
confCF_VERSION: The configuration file's version number. [$Z]
confFROM_HEADER: Default is $?x$x <$g>$|$g$. . The From: header format.
confRECEIVED_HEADER: Default is $?sfrom $s $.$?_($?s$|from $.$_) $.by $j ($v/$Z)$?r with $r$. id $i$?u for $u$.; $b . The Received: header format.
confCW_FILE: Default is /etc/sendmail.cw . The file of local host aliases. [$=w]
confCT_FILE: Default is /etc/sendmail.ct . The file of trusted usernames. [$=t]
confTRUSTED_USERS: Trusted users name to add to root , uucp , and daemon .
confSMTP_MAILER: Default is esmtp. The mailer used for SMTP connections; must be smtp, smtp8, or esmtp.
confUUCP_MAILER: Default is uucp-old. The default UUCP mailer.
confLOCAL_MAILER: Default is local. The mailer used for local connections.
confRELAY_MAILER: Default is relay. The default mailer name for relaying.
confSEVEN_BIT_INPUT: Default is False. Force input to seven bits. [SevenBitInput]
confEIGHT_BIT_HANDLING: Default is pass8. Defines how 8-bit data is handled. [EightBitMode]
confALIAS_WAIT: Default is 10m. The amount of time to wait for alias file rebuild. [AliasWait]
confMIN_FREE_BLOCKS: Default is 100. The minimum number of free blocks on the queue filesystem that must be available to accept SMTP mail. [MinFreeBlocks]
confMAX_MESSAGE_SIZE: Default is infinite. The maximum message size. [MaxMessageSize]
confBLANK_SUB: The character used to replace unquoted blank characters in email addresses. [BlankSub]
confCON_EXPENSIVE: Default is False. Tells system to hold mail bound for mailers that have the e flag set until the next queue run. [HoldExpensive]
confCHECKPOINT_INTERVAL: Default is 10. Tells system to checkpoint the queue files after this number of queued items are processed. [CheckpointInterval]
confDELIVERY_MODE: Default is background. Sets the default delivery mode. [DeliveryMode]
confAUTO_REBUILD: Default is False. Automatically rebuilds alias file. [AutoRebuildAliases]
confERROR_MODE: Default is print. Defines how errors are handled. [ErrorMode]
confERROR_MESSAGE: Points to a file containing a message that is prepended to error messages. [ErrorHeader]
confSAVE_FROM_LINES: Tells system not to discard UNIX From: lines. They are discarded if this is not set. [SaveFromLine]
confTEMP_FILE_MODE: Default is 0600. File mode for temporary files. [TempFileMode]
confMATCH_GECOS: Tells system to match the email username to the GECOS field. This match is not done if this is not set. [MatchGECOS]
confMAX_HOP: Default is 25. The counter used to determine mail loops. [MaxHopCount]
confIGNORE_DOTS: Default is False. Tells system to ignore dots in incoming messages. [IgnoreDots]
confBIND_OPTS: Default is undefined. Sets options for DNS resolver. [ResolverOptions]
confMIME_FORMAT_ERRORS*: Default is True. Tells system to send MIME-encapsulated error messages. [SendMimeErrors]
confFORWARD_PATH: Default is $z/.forward.$w:$z/.forward . Places to search for .forward files. [ForwardPath]
confMCI_CACHE_SIZE: Default is 2. The number of open connections that can be cached. [ConnectionCacheSize]
confMCI_CACHE_TIMEOUT: Default is 5m. The amount of time inactive open connections are held in the cache. [ConnectionCacheTimeout]
confHOST_STATUS_DIRECTORY: Directory in which host status is saved. [HostStatusDirectory]
confUSE_ERRORS_TO*: Default is False. Delivers errors using the Errors-To: header. [UserErrorsTo]
confLOG_LEVEL: Default is 9. Level of detail for the logfile. [LogLevel]
confME_TOO: Default is False. Sends a copy to the sender. [MeToo]
confCHECK_ALIASES: Default is False. Looks up every alias during alias file build. [CheckAliases]
confOLD_STYLE_HEADERS*: Default is True. Treats headers without special chars as old style. [OldStyleHeaders]
confDAEMON_OPTIONS: SMTP daemon options. [DaemonPortOptions]
confPRIVACY_FLAGS: Default is authwarnings. These flags restrict the use of some mail commands. [PrivacyOptions]
confCOPY_ERRORS_TO: Address to receive copies of error messages. [PostmasterCopy]
confQUEUE_FACTOR: Default is 600000. Used to calculate when a loaded system should queue mail instead of attempting delivery. [QueueFactor]
confDONT_PRUNE_ROUTES: Default is False. Don't prune route-addresses to the minimum possible. [DontPruneRoutes]
confSAFE_QUEUE: Create a queue file, then attempt delivery. This is not done unless this paramter is specified. [SuperSafe]
confTO_INITIAL: Default is 5m. Maximum time to wait for the initial connect response. [Timeout.initial]
confTO_CONNECT: Default is 0. Maximum time to wait for a connect to complete. [Timeout.connect]
confTO_ICONNECT: Maximum time to wait for the very first connect attempt to a host. [Timeout.iconnect]
confTO_HELO: Default is 5m. Maximum time to wait for a HELO or EHLO response. [Timeout.helo]
confTO_MAIL: Default is 10m. Maximum time to wait for a MAIL command response. [Timeout.mail]
confTO_RCPT: Default is 1h. Maximum time to wait for a RCPT command response. [Timeout.rcpt]
confTO_DATAINIT: Default is 5m. Maximum time to wait for a DATA command response. [Timeout.datainit]
confTO_DATABLOCK: Default is 1h. Maximum time to wait for a block during DATA phase. [Timeout.datablock]
confTO_DATAFINAL: Default is 1h. Maximum time to wait for a response to the terminating ".". [Timeout.datafinal]
confTO_RSET: Default is 5m. Maximum time to wait for a RSET command response. [Timeout.rset]
confTO_QUIT: Default is 2m. Maximum time to wait for a QUIT command response. [Timeout.quit]
confTO_MISC: Default is 2m. Maximum time to wait for other SMTP command responses. [Timeout.misc]
confTO_COMMAND: Default is 1h. Maximum time to wait for a command to be issued. [Timeout.command]
confTO_IDENT: Default is 30s. Maximum time to wait for an IDENT query response. [Timeout.ident]
confTO_FILEOPEN: Default is 60s. Maximum time to wait for a file open. [Timeout.fileopen]
confTO_QUEUERETURN: Default is 5d. Time until a message is returned from the queue as undeliverable. [Timeout.queuereturn]
confTO_QUEUERETURN_NORMAL: "Undeliverable" timeout for normal priority messages. [Timeout.queuereturn.normal]
confTO_QUEUERETURN_URGENT: "Undeliverable" timeout for urgent priority messages. [Timeout.queuereturn.urgent]
confTO_QUEUERETURN_NONURGENT: "Undeliverable" timeout for low priority messages. [Timeout.queuereturn.non-urgent]
confTO_QUEUEWARN: Default is 4h. Time until a "still queued" warning is sent about a message. [Timeout.queuewarn]
confTO_QUEUEWARN_NORMAL: Time until a "still queued" warning is sent for normal priority messages. [Timeout.queuewarn.normal]
confTO_QUEUEWARN_URGENT: Time until a "still queued" warning is sent for urgent priority messages. [Timeout.queuewarn.urgent]
confTO_QUEUEWARN_NONURGENT: Time until a "still queued" warning is sent for low priority messages. [Timeout.queuewarn.non-urgent]
confTO_HOSTSTATUS: Default is 30m. Timer for stale host status information. [Timeout.hoststatus]
confTIME_ZONE: Default is USE_SYSTEM. Sets time zone from the system (USE_SYSTEM) or the TZ variable (USE_TZ). [TimeZoneSpec]
confDEF_USER_ID: Default is 1:1. Default user ID and group ID. [DefaultUser]
confUSERDB_SPEC: Path of the user database file. [UserDatabaseSpec]
confFALLBACK_MX: Backup MX host. [FallbackMXhost]
confTRY_NULL_MX_LIST: Default is False. Instructs system to connect to the remote host directly if the MX point to the local host. [TryNullMXList]
confQUEUE_LA: Default is 8. Sends mail directly to the queue when this load average is reached. [QueueLA]
confREFUSE_LA: Default is 12. Refuses incoming SMTP connections at this load average. [RefuseLA]
confMAX_DAEMON_CHILDREN: If set, refuses connection when this number of children is reached. [MaxDaemonChildren]
confCONNECTION_RATE_THROTTLE: Maximum number of connections permitted per second, if set. [ConnectionRateThrottle]
confWORK_RECIPIENT_FACTOR: Default is 30000. Factor used to lower the priority of a job for each additional recipient. [RecipientFactor]
confSEPARATE_PROC: Default is False. Delivers messages with separate processes. [ForkEachJob]
confWORK_CLASS_FACTOR: Default is 1800. The factor used to favor a high-priority job. [ClassFactor]
confWORK_TIME_FACTOR: Default is 90000. Factor used to lower the priority of a job for each delivery attempt. [RetryFactor]
confQUEUE_SORT_ORDER: Default is Priority. Sorts queue by Priority or Host order. [QueueSortOrder]
confMIN_QUEUE_AGE: Default is 0. Minimum time a job must be queued. [MinQueueAge]
confDEF_CHAR_SET: Default is unknown-8bit. Default character set for unlabeled 8-bit MIME data. [DefaultCharSet]
confSERVICE_SWITCH_FILE: Default is /etc/service.switch . The path to the service switch file. [ServiceSwitchFile]
confHOSTS_FILE: Default is /etc/hosts . The path to the hostnames file. [HostsFile]
confDIAL_DELAY: Default is 0s. Amount of time to delay before retrying a "dial on demand" connection. 0s means "don't retry". [DialDelay]
confNO_RCPT_ACTION: Default is none . Handling for mail with no recipient headers: do nothing ( none ); add To: header ( add-to ); add Apparently-To: header ( add-apparently-to ); add a Bcc: header ( add-bcc ); add "To: undisclosed-recipients" header ( add-to-undisclosed ). [NoRecipientAction]
confSAFE_FILE_ENV: Default is undefined. chroot() to this directory before writing files. [SafeFileEnvironment]
confCOLON_OK_IN_ADDR: Default is True. Treats colons as regular characters in addresses. [ColonOkInAddr]
confMAX_QUEUE_RUN_SIZE: Default is 0. Limits the number of entries processed in a queue run. 0 means no limit. [MaxQueueRunSize]
confDONT_EXPAND_CNAMES: Default is False. If true, don't convert nicknames to canonical names. False means "do convert." [DontExpandCnames]
confFROM_LINE: Default is From $g $d. The format of the UNIX From: line. [UnixFromLine]
confOPERATORS: Default is .:%@!^/[]+. Address operator characters. [OperatorChars]
confSMTP_LOGIN_MSG: Default is $j sendmail $v/$Z; $b . The SMTP greeting message. [SmtpGreetingMessage]
confDONT_INIT_GROUPS: Default is False. If true, disable the initgroups(3) routine. False means "use the initgroups(3) routine. [DontInitGroups]
confUNSAFE_GROUP_WRITES: Default is False. If true, don't reference programs or file from group-writable :include: and .forward files. [UnsafeGroupWrites]
confDOUBLE_BOUNCE_ADDRESS: Default is postmaster . When errors occur sending an error message, send the second error message to this address. [DoubleBounceAddress]
confRUN_AS_USER: Default is undefined. Run as this user to read and deliver mail. [RunAsUser]
confSINGLE_THREAD_DELIVERY: Default is False. Force single threaded mail deliver when set with HostStatusDirectory. [SingleThreadDelivery]

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

E.3.2 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, dbm /usr/lib/mailertable)

generates the code for accessing the mailertable and defines that table as being a dbm database located in the file /usr/lib/mailertable .

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

Table E.3: sendmail V8 Features
Name	Purpose
use_cw_file	Load $=w from /etc/sendmail.cw .
use_ct_file	Load $=t from /etc/sendmail.ct .
redirect	Support the .REDIRECT pseudo-domain.
nouucp	Don't include UUCP address processing.
nocanonify	Don't convert names with $[ ... $] syntax.
stickyhost	Treat "user" different than "user@local.host".[4]
mailertable	Mail routing using a mailer table.
domaintable	Domain name mapping using a domain table.
bitdomain	Use a table to map bitnet hosts to Internet addresses.
uucpdomain	Use a table to map UUCP hosts to Internet addresses.
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.
genericstable	Use a table to rewrite local addresses.
virtusertable	Maps virtual domain names to real mail addresses.
nodns	Don't include DNS support.
nullclient	Forwarding all mail to a central server.
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.

[4] 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 Chapter 10 for descriptions of host aliases ( $=w ) and trusted users ( $=t ).

The .REDIRECT pseudo-domain code returns an error message to the sender telling them 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 almond.nuts.com . 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 to the ed account on almond , the following error is returned to the sender:

551 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, which is rarely used, disables the $[ name ]$ syntax that converts nicknames and IP addresses; see Table 10-7. 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. They are: stickyhost, 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/ filename , where filename matches the name of the feature. For example: mailertable defaults to the definition hash -o /etc/mailertable . The database features are:

mailertable

Maps host and domain names to specific mailer:host pairs. [5] If the host or domain name in the recipient addresses matches a key field in the mailertable database, it returns the mailer and host for that address. The format of mailertable entries is:

[5] See Chapter 10 for a description of the mailer, host, and user triple returned by ruleset 0.

domain-name mailer : host

where domain-name is either a full hostname (host plus domain) or a domain name. If a domain name is used it must start with a dot (.), and it will match every host in the specified domain.

domaintable

Converts an old domain name to a new domain name. The old name is the key and the new name is the value returned for the key.

bitdomain

Converts a Bitnet hostname to an Internet hostname. The Bitnet name is the key and the Internet hostname is the value returned. The bitdomain program that comes with sendmail V8 can be used to build this database.

uucpdomain

Converts a UUCP name to an Internet hostname. The key is the UUCP host name and the value returned is the Internet hostname.

generictable

Converts a sender email address. The key to the database is either a username or a full email address (username and hostname). The value returned by the database is always a full email address. If the value specified in the database is not a full address, genericstable appends the value from $j to the value to force it to be a full address. genericstable converts the same address as those processed for masquerading and the features that affect masquerading affect the genericstable conversion in exactly the same way. See Chapter 10 for an example of using the genericstable and see the "DOMAIN" section later in this appendix for information on masquerading. Note that if you use the genericstable and you don't use masquerading, you can still get the functionality of the MASQUERADE_DOMAIN and the MASQUERADE_DOMAIN_FILE by using GENERICS_DOMAIN and GENERICS_DOMAIN_FILE. These commands have the same function and are used in the same way as their masquerade counterparts, which are described in the following section.

virtusertable

Aliases incoming email addresses. Essentially, this is an extended alias database for aliasing addresses that are not local to this host. The key to the database is a full email address or a domain name. The value returned by the database is the recipient address to which the mail is delivered. If a domain name is used as a key, it must begin with an at-sign (@). Mail addressed to any user in the specified domain is sent to the recipient defined by the virtusertable database. Any host name used as a key in the virtusertable database must also be defined in class w.

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 remainder of this section describes the purpose and structure of the OSTYPE, DOMAIN, and MAILER source files.

E.3.3 OSTYPE

The source file for the OSTYPE macro defines operating system-specific parameters. Many operating systems are pre-defined. 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 13.7 lists the define parameters most frequently associated with the OSTYPE source file and the function of each parameter. The default value assigned to each parameter is shown enclosed in square brackets after its functional description, if the parameter has a default value.

Table E.4: OSTYPE Defines
Parameter	Function
ALIAS_FILE	Name of the alias file. [ /etc/aliases ]
HELP_FILE	Name of the help file. [ /usr/lib/sendmail.hf ]
QUEUE_DIR	Directory containing queue files. [ /var/spool/mqueue ]
STATUS_FILE	Name of the status file. [ /etc/sendmail.st ]
LOCAL_MAILER_PATH	The local mail delivery program. [ /bin/mail ]
LOCAL_MAILER_FLAGS	Local mailer flags added to "lsDFM". [ rmn ]
LOCAL_MAILER_ARGS	Arguments for local mail delivery. [ mail -d $u ]
LOCAL_MAILER_MAX	Maximum size of local mail.
LOCAL_MAILER_CHARSET	Character set for local 8-bit MIME mail.
LOCAL_SHELL_PATH	Shell used to deliver piped email. [ /bin/sh ]
LOCAL_SHELL_FLAGS	Flags added to lsDFM for the shell mailer. [ eu ]
LOCAL_SHELL_ARGS	Arguments for the "prog" mail. [ sh -c $u ]
LOCAL_SHELL_DIR	Directory which the shell should run. [ $z:/ ]
USENET_MAILER_PATH	Program used for news. [ /usr/lib/news/inews ]
USENET_MAILER_FLAGS	Usenet mailer flags. [ rlsDFMmn ]
USENET_MAILER_ARGS	Arguments for the usenet mailer. [ -m -h -n ]
USENET_MAILER_MAX	Maximum size of usenet mail messages. [100000]
SMTP_MAILER_FLAGS	Flags added to "mDFMUX" for all SMTP mailers.
SMTP_MAILER_MAX	Maximum size of messages for all SMTP mailers.
SMTP_MAILER_ARGS	smtp mailer arguments. [ IPC $h ]
ESMTP_MAILER_ARGS	esmtp mailer arguments. [ IPC $h ]
SMTP8_MAILER_ARGS	smtp8 mailer arguments. [ IPC $h ]
RELAY_MAILER_ARGS	relay mailer arguments. [ IPC $h ]
SMTP_MAILER_CHARSET	Character set for SMTP 8-bit MIME mail.
UUCP_MAILER_PATH	Path to the UUCP mail program. [ /usr/bin/uux ]
UUCP_MAILER_FLAGS	Flags added to "DFMhuU" for the UUCP mailer.
UUCP_MAILER_ARGS	UUCP mailer arguments.
	[ uux - -r -z -a$g -gC $h!rmail ($u) ]
UUCP_MAILER_MAX	Maximum size for UUCP messages. [100000]
UUCP_MAILER_CHARSET	Character set for UUCP 8-bit MIME mail.
FAX_MAILER_PATH	Path to the FAX program. [ /usr/local/lib/fax/mailfax ]
FAX_MAILER_ARGS	FAX mailer arguments. [ mailfax $u $h $f ]
FAX_MAILER_MAX	Maximum size of a FAX. [100000]
POP_MAILER_PATH	Path of the POP mailer. [ /usr/lib/mh/spop ]
POP_MAILER_FLAGS	Flags added to "lsDFM" for the POP mailer. [ Penu ]
POP_MAILER_ARGS	POP mailer arguments. [ pop $u ]
PROCMAIL_MAILER_PATH	Path to the procmail program. [ /usr/local/bin/procmail ]
PROCMAIL_MAILER_FLAGS	Flags added to "DFMmn" for the Procmail mailer. [ Shu ]
PROCMAIL_MAILER_ARGS	Procmail mailer arguments. [ procmail -m $h $f $u ]
PROCMAIL_MAILER_MAX	Maximum size message for the Procmail mailer.
MAIL11_MAILER_PATH	Path to the mail11 mailer. [ /usr/etc/mail11 ]
MAIL11_MAILER_FLAGS	Flags for the mail11 mailer. [ nsFx ]
MAIL11_MAILER_ARGS	mail11 mailer arguments. [ mail11 $g $x $h $u ]
PH_MAILER_PATH	Path to the phquery program. [ /usr/local/etc/phquery ]
PH_MAILER_FLAGS	Flags for the phquery mailer. [ ehmu ]
PH_MAILER_ARGS	phquery mailer arguments. [ phquery -- $u ]
CYRUS_MAILER_FLAGS	Flags added to "lsDFMnP" for the cyrus mailer. [ A5@ ]
CYRUS_MAILER_PATH	Path to the cyrus mailer. [ /usr/cyrus/bin/deliver ]
CYRUS_MAILER_ARGS	cyrus mailer arguments. [ deliver -e -m $h -- $u ]
CYRUS_MAILER_MAX	Maximum size message for the cyrus mailer.
CYRUS_MAILER_USER	User and group used to the cyrus mailer. [ cyrus:mail ]
CYRUS_BB_MAILER_FLAGS	Flags added to "lsDFMnP" for the cyrusbb mailer.
CYRUS_BB_MAILER_ARGS	cyrusbb mailer arguments. [ deliver -e -m $u ]

Despite the long list of parameters in Table 13.7 most OSTYPE macros are very short. The largest OSTYPE file in the sendmail V8 distribution contains only eight define s. 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 systems 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 than the default.

E.3.4 DOMAIN

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

Table 13.8 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 Defines
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[6]
LOCAL_RELAY	Sever 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

[6] 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 BITNET_RELAY and the SMART_HOST relay are defined, the BITNET_RELAY is used for outgoing BITNET mail even though the SMART_HOST relay is defined as handling "all" outgoing mail. If you define both LOCAL_RELAY and MAIL_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 MAIL_HUB handles all local addresses.

In addition to the defines shown in Table 13.8 there are 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 Chapter 10 . The macros are:

LOCAL_USER(usernames ): Defines local usernames that should not be relayed even if LOCAL_RELAY or MAIL_HUB are defined. This command is the same as adding usernames to class L in the sendmail.cf file.
MASQUERADE_AS(host.domain ): Converts the host portion of the sender address on outgoing mail to the domain name defined by host.domain . Sender addresses that have no hostname or that have a hostname found in the w class are converted. This has the same as effect as defining host.domain for the M macro in the sendmail.cf file. See examples of MASQUERADE_AS and macro M in Chapter 10 .
MASQUERADE_DOMAIN(otherhost.domain ): Converts the host portion of the sender address on outgoing mail to the domain name defined by the MASQUERADE_AS command, if the host portion of the sender address matches otherhost.domain . This command must be used in conjunction with MASQUERADE_AS. Its effect is the same as adding hostnames to class M in the sendmail.cf file. See Chapter 10 .
MASQUERADE_DOMAIN_FILE(filename ): Loads otherhost.domain hostnames from the file identified by filename . This can be used in place of multiple MASQUERADE_DOMAIN commands. Its effect is the same as loading class M from a file by using the FM filename command in the sendmail.cf file.
EXPOSED_USER(username ): Disables masquerading when the user portion of the sender address matches username . Some usernames, such as root, occur on many systems and are therefore not unique across a domain. For those usernames, converting the host portion of the address makes it impossible to sort out where the message really came from and makes replies impossible. This command prevents the MASQUERADE_AS command from having an effect on the sender addresses for specific users. This is the same as setting the values in class E in the sendmail.cf file.

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

FEATURE(masquerade_envelope): Causes envelop addresses to be masqueraded in the same way that sender addresses are masqueraded. See Chapter 10 for an example of this command.
FEATURE(allmasquerade): Causes recipient addresses to be masqueraded in the same way that sender addresses are masqueraded. Thus, if the host portion of the recipient address matches the requirements of the MASQUERADE_AS command, it is converted. Don't use this feature unless you are positive that every alias known to the local system is also known to the mail server that handles mail for the masquerade domain.
FEATURE(limited_masquerade): Limits masquerading to those hosts defined in class M. The hosts defined in class w are not masqueraded.
FEATURE(masquerade_entire_domain): Causes MASQUERADE_DOMAIN to be interpreted as referring to all hosts with an entire domain. If this feature is not used, only an address that exactly matches the value defined by MASQUERADE_DOMAIN is converted. If this feature is used, all addresses that end with the value defined by MASQUERADE_DOMAIN are converted. For example, assume that the options MASQUERADE_AS(nuts.com) and MASQUERADE_DOMAIN(sales.nuts.com) are defined. If FEATURE (masquerade_entire_domain) is set, every hostname in the sales.nuts.com domain is converted to nuts.com on outgoing email. Otherwise only the hostname sales.nuts.com is converted.

See the "FEATURE" section earlier in this chapter for more information on the available features.

E.3.5 MAILER

It is possible that you will need to customize a file location in an OSTYPE file or that you will need to 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 13.9 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.

Table E.6: MAILER Values
Name	Function
local	The local and prog mailers
smtp	All SMTP mailers: smtp, esmtp, smtp8, and relay
uucp	All UUCP mailers: uucp-old (uucp) and uucp-new (suucp)
usenet	Usenet news support
fax	Fax support using FlexFAX software
pop	Post Office Protocol (POP) support
procmail	An interface for procmail
mail11	The DECnet mail11 mailer
phquery	The phquery program for CSO phone book
cyrus	The cyrus and cyrusbb mailers

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 MAILER(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 envelop.

The other mailers are rarely used:

usenet: Modifies the sendmail rewrite rules to send local mail that contains ".usenet" in the username to the program inews. Instead of this mailer, choose a user mail agent that supports Usenet news. Don't hack sendmail to handle it.
fax: This is still experimental in sendmail V8, though built-in fax support could be useful when it is ready.
pop: On most systems, POP support is provided separately by the popd daemon, and the MAILER(pop) command is not used.
procmail: Only provides an interface to procmail for use in the mailertable. The sendmail V8 distribution does not provide procmail. Even when procmail is used as the local mailer, as it is in Slackware Linux, the MAILER(procmail) command is not required.
mail11: Only used on DECNET mail networks that use the mail11 mailer.
phquery: Provides a name lookup program for the CSO phone book (ph) directory service. User directory services are usually configured in the user mail agent, not in sendmail.
cyrus: This is a local mail delivery program with a mailbox architecture. cyrus and cyrusbb mailers are not widely 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 and excerpts from a sendmail.cf file. The bulk of information about sendmail.cf is found in Chapter 10 .