cf/README for sendmail 8.12.3

Eric Allman of the Sendmail Consortium

Features

Special features can be requested using the "FEATURE" macro. For example, the .mc line:

FEATURE(`use_cw_file')

tells sendmail that you want to have it read an /etc/mail/local-host-names file to get values for class {w}. A FEATURE may contain up to 9 optional parameters -- for example:

FEATURE(`mailertable', `dbm /usr/lib/mailertable')

The default database map type for the table features can be set with

define(`DATABASE_MAP_TYPE', `dbm')

which would set it to use ndbm databases. The default is the Berkeley DB hash database format. Note that you must still declare a database map type if you specify an argument to a FEATURE. DATABASE_MAP_TYPE is only used if no argument is given for the FEATURE. It must be specified before any feature that uses a map.

Also, features which can take a map definition as an argument can also take the special keyword `LDAP'. If that keyword is used, the map will use the LDAP definition described in the Using LDAP For Aliases, Maps, And Classes section below.

Available features are:

FeatureDescription
use_cw_fileRead the file /etc/mail/local-host-names file to get alternate names for this host. This might be used if you were on a host that MXed for a dynamic set of other hosts. If the set is static, just including the line "Cw<name1> <name2> ..." (where the names are fully qualified domain names) is probably superior. The actual filename can be overridden by redefining confCW_FILE.
use_ct_fileRead the file /etc/mail/trusted-users file to get the names of users that will be ``trusted'', that is, able to set their envelope from address using -f without generating a warning message. The actual filename can be overridden by redefining confCT_FILE.
redirectReject all mail addressed to "address.REDIRECT" with a ``551 User has moved; please try <address>'' message. If this is set, you can alias people who have left to their new address with ".REDIRECT" appended.
nouucpDon't route UUCP addresses. This feature takes one parameter:
`reject': reject addresses which have "!" in the local part unless it originates from a system that is allowed to relay.
`nospecial': don't do anything special with "!".

Warnings:
1. See the notice in the anti-spam section.
2. don't remove "!" from OperatorChars if `reject' is given as parameter.

nocanonifyDon't pass addresses to $[ ... $] for canonification by default, i.e., host/domain names are considered canonical, except for unqualified names, which must not be used in this mode (violation of the standard). It can be changed by setting the DaemonPortOptions modifiers (M=). That is, FEATURE(`nocanonify') will be overridden by setting the 'c' flag. Conversely, if FEATURE(`nocanonify') is not used, it can be emulated by setting the 'C' flag (DaemonPortOptions=Modifiers=C). This would generally only be used by sites that only act as mail gateways or which have user agents that do full canonification themselves. You may also want to use "define(`confBIND_OPTS', `-DNSRCH -DEFNAMES')" to turn off the usual resolver options that do a similar thing.

An exception list for FEATURE(`nocanonify') can be specified with CANONIFY_DOMAIN or CANONIFY_DOMAIN_FILE, i.e., a list of domains which are nevertheless passed to $[ ... $] for canonification. This is useful to turn on canonification for local domains, e.g., use CANONIFY_DOMAIN(`my.domain my') to canonify addresses which end in "my.domain" or "my". Another way to require canonification in the local domain is CANONIFY_DOMAIN(`$=m').

A trailing dot is added to addresses with more than one component in it such that other features which expect a trailing dot (e.g., virtusertable) will still work.

If `canonify_hosts' is specified as parameter, i.e., FEATURE(`nocanonify', `canonify_hosts'), then addresses which have only a hostname, e.g., <user@host>, will be canonified (and hopefully fully qualified), too.

stickyhostThis feature is sometimes used with LOCAL_RELAY, although it can be used for a different effect with MAIL_HUB.

When used without MAIL_HUB, email sent to "user@local.host" are marked as "sticky" -- that is, the local addresses aren't matched against UDB, don't go through ruleset 5, and are not forwarded to the LOCAL_RELAY (if defined).

With MAIL_HUB, mail addressed to "user@local.host" is forwarded to the mail hub, with the envelope address still remaining "user@local.host". Without stickyhost, the envelope would be changed to "user@mail_hub", in order to protect against mailing loops.

mailertableInclude a "mailer table" which can be used to override routing for particular domains (which are not in class {w}, i.e. local host names). The argument of the FEATURE may be the key definition. If none is specified, the definition used is:

hash /etc/mail/mailertable

Keys in this database are fully qualified domain names or partial domains preceded by a dot -- for example, "vangogh.CS.Berkeley.EDU" or ".CS.Berkeley.EDU". As a special case of the latter, "." matches any domain not covered by other keys. Values must be of the form:

mailer:domain

where "mailer" is the internal mailer name, and "domain" is where to send the message. These maps are not reflected into the message header. As a special case, the forms:

local:user

will forward to the indicated user using the local mailer,

local:

will forward to the original user in the e-mail address using the local mailer, and

error:code message error:D.S.N:code message

will give an error message with the indicated SMTP reply code and message, where D.S.N is an RFC 1893 compliant error code.

domaintableInclude a "domain table" which can be used to provide domain name mapping. Use of this should really be limited to your own domains. It may be useful if you change names (e.g., your company changes names from oldname.com to newname.com). The argument of the FEATURE may be the key definition. If none is specified, the definition used is:

hash /etc/mail/domaintable

The key in this table is the domain name; the value is the new (fully qualified) domain. Anything in the domaintable is reflected into headers; that is, this is done in ruleset 3.

bitdomainLook up bitnet hosts in a table to try to turn them into internet addresses. The table can be built using the bitdomain program contributed by John Gardiner Myers. The argument of the FEATURE may be the key definition; if none is specified, the definition used is:

hash /etc/mail/bitdomain

Keys are the bitnet hostname; values are the corresponding internet hostname.

uucpdomainSimilar feature for UUCP hosts. The default map definition is:

hash /etc/mail/uudomain

At the moment there is no automagic tool to build this database.
always_add_domain Include the local host domain even on locally delivered mail. Normally it is not added on unqualified names. However, if you use a shared message store but do not use the same user name space everywhere, you may need the host name on local names. An optional argument specifies another domain to be added than the local.
allmasqueradeIf masquerading is enabled (using MASQUERADE_AS), this feature will cause recipient addresses to also masquerade as being from the masquerade host. Normally they get the local hostname. Although this may be right for ordinary users, it can break local aliases.
For example, if you send to "localalias", the originating sendmail will find that alias and send to all members, but send the message with "To: localalias@masqueradehost". Since that alias likely does not exist, replies will fail.

Use this feature only if you can guarantee that the entire namespace on your masquerade host supersets all the local entries.

limited_masquerade Normally, any hosts listed in class {w} are masqueraded. If this feature is given, only the hosts listed in class {M} (see MASQUERADE_DOMAIN) are masqueraded. This is useful if you have several domains with disjoint namespaces hosted on the same machine.
masquerade_entire_domain If masquerading is enabled (using MASQUERADE_AS) and MASQUERADE_DOMAIN is set, this feature will cause addresses to be rewritten such that the masquerading domains are actually entire domains to be hidden. All hosts within the masquerading domains will be rewritten to the masquerade name (used in MASQUERADE_AS). For example,if you have:

MASQUERADE_AS(`masq.com') MASQUERADE_DOMAIN(`foo.org') MASQUERADE_DOMAIN(`bar.com')

then *foo.org and *bar.com are converted to masq.com. Without this feature, only foo.org and bar.com are masqueraded.

NOTE: only domains within your jurisdiction and current hierarchy should be masqueraded using this.

local_no_masquerade This feature prevents the local mailer from masquerading even if MASQUERADE_AS is used. MASQUERADE_AS will only have effect on addresses of mail going outside the local domain.
genericstable This feature will cause unqualified addresses (i.e., without a domain) and addresses with a domain listed in class {G} to be looked up in a map and turned into another ("generic") form, which can change both the domain name and the user name.

Notice: if you use an MSP (as it is default starting with 8.12), the MTA will only receive qualified addresses from the MSP (as required by the RFCs). Hence you need to add your domain to class {G}.

This feature is similar to the userdb functionality. The same types of addresses as for masquerading are looked up, i.e., only header sender addresses unless the allmasquerade and/or masquerade_envelope features are given. Qualified addresses must have the domain part in class {G}; entries can be added to this class by the macros GENERICS_DOMAIN or GENERICS_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and MASQUERADE_DOMAIN_FILE).

The argument of FEATURE(`genericstable') may be the map definition; the default map definition is:

hash /etc/mail/genericstable

The key for this table is either the full address, the domain (with a leading @; the localpart is passed as first argument) or the unqualified username (tried in the order mentioned); the value is the new user address. If the new user address does not include a domain, it will be qualified in the standard manner, i.e., using $j or the masquerade name. Note that the address being looked up must be fully qualified. For local mail, it is necessary to use FEATURE(`always_add_domain') for the addresses to be qualified. The "+detail" of an address is passed as %1, so entries like

old+*@foo.org	new+%1@example.com
gen+*@foo.org	%1@example.com

and other forms are possible.

generics_entire_domain If the genericstable is enabled and GENERICS_DOMAIN or GENERICS_DOMAIN_FILE is used, this feature will cause addresses to be searched in the map if their domain parts are subdomains of elements in class {G}.
virtusertable A domain-specific form of aliasing, allowing multiple virtual domains to be hosted on one machine. For example, if the virtuser table contained:
info@foo.com	foo-info
info@bar.com	bar-info
joe@bar.com	error:nouser 550 No such user here
jax@bar.com	error:5.7.0:550 Address invalid
@baz.org	jane@example.net

then mail addressed to info@foo.com will be sent to the address foo-info, mail addressed to info@bar.com will be delivered to bar-info, and mail addressed to anyone at baz.org will be sent to jane@example.net, mail to joe@bar.com will be rejected with the specified error message, and mail to jax@bar.com will also have a RFC 1893 compliant error code 5.7.0.

The username from the original address is passed as %1 allowing:

@foo.org	%1@example.com

meaning someone@foo.org will be sent to someone@example.com. Additionally, if the local part consists of "user+detail" then "detail" is passed as %2 and "+detail" is passed as %3 when a match against user+* is attempted, so entries like

old+*@foo.org	new+%2@example.com
gen+*@foo.org	%2@example.com
+*@foo.org	%1%3@example.com
X++@foo.org	Z%3@example.com
@bar.org	%1%3

and other forms are possible.

Note: to preserve "+detail" for a default case (@domain) %1%3 must be used as RHS. There are two wildcards after "+": "+" matches only a non-empty detail, "*" matches also empty details, e.g., user+@foo.org matches +*@foo.org but not ++@foo.org. This can be used to ensure that the parameters %2 and %3 are not empty.

All the host names on the left hand side (foo.com, bar.com, and baz.org) must be in class {w} or class {VirtHost}. The latter can be defined by the macros VIRTUSER_DOMAIN or VIRTUSER_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and MASQUERADE_DOMAIN_FILE). If VIRTUSER_DOMAIN or VIRTUSER_DOMAIN_FILE is used, then the entries of class {VirtHost} are added to class {R}, i.e., relaying is allowed to (and from) those domains. The default map definition is:

hash /etc/mail/virtusertable

A new definition can be specified as the second argument of the FEATURE macro, such as

FEATURE(`virtusertable', `dbm /etc/mail/virtusers')
virtuser_entire_domain If the virtusertable is enabled and VIRTUSER_DOMAIN or VIRTUSER_DOMAIN_FILE is used, this feature will cause addresses to be searched in the map if their domain parts are subdomains of elements in class {VirtHost}.
ldap_routing Implement LDAP-based e-mail recipient routing according to the Internet Draft draft-lachman-laser-ldap-mail-routing-01. This provides a method to re-route addresses with a domain portion in class {LDAPRoute} to either a different mail host or a different address. Hosts can be added to this class using LDAPROUTE_DOMAIN and LDAPROUTE_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and MASQUERADE_DOMAIN_FILE).

See the LDAP Routing section for more information.

nodnsIf you aren't running DNS at your site (for example, you are UUCP-only connected). It's hard to consider this a "feature", but hey, it had to go somewhere. Actually, as of 8.7 this is a no-op -- remove "dns" from the hosts service switch entry instead.
nullclient This is a special case -- it creates a configuration file containing nothing but support for forwarding all mail to a central hub via a local SMTP-based network. The argument is the name of that hub.

The only other feature that should be used in conjunction with this one is FEATURE(`nocanonify'). No mailers should be defined. No aliasing or forwarding is done.

local_lmtp Use an LMTP capable local mailer. The argument to this feature is the pathname of an LMTP capable mailer. By default, mail.local is used. This is expected to be the mail.local which came with the 8.9 distribution which is LMTP capable. The path to mail.local is set by the confEBINDIR m4 variable -- making the default LOCAL_MAILER_PATH /usr/libexec/mail.local.

WARNING: This feature sets LOCAL_MAILER_FLAGS unconditionally, i.e., without respecting any definitions in an OSTYPE setting.

local_procmail Use procmail or another delivery agent as the local mailer. The argument to this feature is the pathname of the delivery agent, which defaults to PROCMAIL_MAILER_PATH. Note that this does not use PROCMAIL_MAILER_FLAGS or PROCMAIL_MAILER_ARGS for the local mailer; tweak LOCAL_MAILER_FLAGS and LOCAL_MAILER_ARGS instead, or specify the appropriate parameters. When procmail is used, the local mailer can make use of the "user+indicator@local.host" syntax; normally the +indicator is just tossed, but by default it is passed as the -a argument to procmail.

This feature can take up to three arguments:

  1. Path to the mailer program
    [/usr/local/bin/procmail]
  2. Argument vector including name of the program
    [procmail -Y -a $h -d $u]
  3. Flags for the mailer
    [SPfhn9]

Empty arguments cause the defaults to be taken.

For example, this allows it to use the maildrop ( http://www.flounder.net/~mrsam/maildrop/) mailer instead by specifying:

FEATURE(`local_procmail', `/usr/local/bin/maildrop', `maildrop -d $u')

or scanmails using:

FEATURE(`local_procmail', `/usr/local/bin/scanmails')

WARNING: This feature sets LOCAL_MAILER_FLAGS unconditionally, i.e., without respecting any definitions in an OSTYPE setting.

bestmx_is_local Accept mail as though locally addressed for any host that lists us as the best possible MX record. This generates additional DNS traffic, but should be OK for low to medium traffic hosts. The argument may be a set of domains, which will limit the feature to only apply to these domains -- this will reduce unnecessary DNS traffic.

This feature is fundamentally incompatible with wildcard MX records. If you have a wildcard MX record that matches your domain, you cannot use this feature.

smrshUse the SendMail Restricted SHell (smrsh) provided with the distribution instead of /bin/sh for mailing to programs. This improves the ability of the local system administrator to control what gets run via e-mail. If an argument is provided it is used as the pathname to smrsh; otherwise, the path defined by confEBINDIR is used for the smrsh binary -- by default, /usr/libexec/smrsh is assumed.
promiscuous_relay By default, the sendmail configuration files do not permit mail relaying (that is, accepting mail from outside your local host (class {w}) and sending it to another host than your local host). This option sets your site to allow mail relaying from any site to any site.

In almost all cases, it is better to control relaying more carefully with the access map, class {R}, or authentication.

Domains can be added to class {R} by the macros RELAY_DOMAIN or RELAY_DOMAIN_FILE (analogously to MASQUERADE_DOMAIN and MASQUERADE_DOMAIN_FILE).

relay_entire_domain By default, only hosts listed as RELAY in the access db will be allowed to relay. This option also allows any host in your domain as defined by class {m}.

Notice: make sure that your domain is not just a top level domain, e.g., com.

This can happen if you give your host a name like example.com instead of host.example.com.

relay_hosts_only By default, names that are listed as RELAY in the access db and class {R} are domain names, not host names. For example, if you specify ``foo.com'', then mail to or from foo.com, abc.foo.com, or a.very.deep.domain.foo.com will all be accepted for relaying. This feature changes the behaviour to lookup individual host names only.
relay_based_on_MX Turns on the ability to allow relaying based on the MX records of the host portion of an incoming recipient; that is, if an MX record for host foo.com points to your site, you will accept and relay mail addressed to foo.com.

See description below for more information before using this feature. Also, see the KNOWNBUGS entry regarding bestmx map lookups.

FEATURE(`relay_based_on_MX') does not necessarily allow routing of these messages which you expect to be allowed, if route address syntax (or %-hack syntax) is used. If this is a problem, add entries to the access-table or use FEATURE(`loose_relay_check').

relay_mail_from Allows relaying if the mail sender is listed as RELAY in the access map. If an optional argument `domain' is given, relaying can be allowed just based on the domain portion of the sender address.

This feature should only be used if absolutely necessary as the sender address can be easily forged.

Use of this feature requires the "From:" tag be prepended to the key in the access map; see the discussion of tags and FEATURE(`relay_mail_from') in the section on Anti-Spam Configuration Control.

relay_local_from Allows relaying if the domain portion of the mail sender is a local host.

This should only be used if absolutely necessary as it opens a window for spammers.

Specifically, they can send mail to your mail server that claims to be from your domain (either directly or via a routed address), and you will go ahead and relay it out to arbitrary hosts on the Internet.
accept_unqualified_senders Normally, MAIL FROM: commands in the SMTP session will be refused if the connection is a network connection and the sender address does not include a domain name. If your setup sends local mail unqualified (i.e., MAIL FROM: <joe>), you will need to use this feature to accept unqualified sender addresses. Setting the DaemonPortOptions modifier 'u' overrides the default behavior, i.e., unqualified addresses are accepted even without this FEATURE. If this FEATURE is not used, the DaemonPortOptions modifier 'f' can be used to enforce fully qualified addresses.
accept_unresolvable_domains Normally, MAIL FROM: commands in the SMTP session will be refused if the host part of the argument to MAIL FROM: cannot be located in the host name service (e.g., an A or MX record in DNS). If you are inside a firewall that has only a limited view of the Internet host name space, this could cause problems. In this case you probably want to use this feature to accept all domains on input, even if they are unresolvable.
access_db Turns on the access database feature. The access db gives you the ability to allow or refuse to accept mail from specified domains for administrative reasons. Moreover, it can control the behavior of sendmail in various situations. By default, the access database specification is:

hash -T<TMPF> /etc/mail/access

See the Anti-Spam Configuration Control section for further important information about this feature.
Notice: "-T<TMPF>" is meant literal, do not replace it by anything.
blacklist_recipients Turns on the ability to block incoming mail for certain recipient usernames, hostnames, or addresses. For example, you can block incoming mail to user nobody, host foo.mydomain.com, or guest@bar.mydomain.com. These specifications are put in the access db as described in the Anti-Spam Configuration Control section later in this document.
delay_checks The rulesets check_mail and check_relay will not be called when a client connects or issues a MAIL command, respectively. Instead, those rulesets will be called by the check_rcpt ruleset; they will be skipped under certain circumstances.

See "Delay all checks" in the Anti-Spam Configuration Control section.

Note: this feature is incompatible to the versions in 8.10 and 8.11.

dnsbl Turns on rejection of hosts found in an DNS based rejection list. If an argument is provided it is used as the domain in which blocked hosts are listed; otherwise it defaults to blackholes.mail-abuse.org. An explanation for an DNS based rejection list can be found at http://mail-abuse.org/rbl/. A second argument can be used to change the default error message. Without that second argument, the error message will be

Mail from IP-ADDRESS refused by blackhole site SERVER

where IP-ADDRESS and SERVER are replaced by the appropriate information. By default, temporary lookup failures are ignored. This behavior can be changed by specifying a third argument, which must be either `t' or a full error message. See the anti-spam configuration control section for an example. The dnsbl feature can be included several times to query different DNS based rejection lists. See also enhdnsbl for an enhanced version.

Note: The default DNS blacklist, blackholes.mail-abuse.org, is a service offered by the Mail Abuse Prevention System (MAPS). As of July 31, 2001, MAPS is a subscription service, so using that network address won't work if you haven't subscribed. Contact MAPS to subscribe (http://mail-abuse.org/).

enhdnsbl Enhanced version of dnsbl (see above). Further arguments (up to 5) can be used to specify specific return values from lookups. Temporary lookup failures are ignored unless a third argument is given, which must be either `t' or a full error message. By default, any successful lookup will generate an error. Otherwise the result of the lookup is compared with the supplied argument(s), and only if a match occurs an error is generated. For example,

FEATURE(`enhdnsbl', `dnsbl.example.com', `', `t', `127.0.0.2.')

will reject the e-mail if the lookup returns the value ``127.0.0.2.'', or generate a 451 response if the lookup temporarily failed. The arguments can contain metasymbols as they are allowed in the LHS of rules. As the example shows, the default values are also used if an empty argument, i.e., `', is specified. This feature requires that sendmail has been compiled with the flag DNSMAP (see sendmail/README).

lookupdotdomain Look up also .domain in the access map. This allows to match only subdomains. It does not work well with FEATURE(`relay_hosts_only'), because most lookups for subdomains are suppressed by the latter feature.
loose_relay_check Normally, if % addressing is used for a recipient, e.g. user%site@othersite, and othersite is in class {R}, the check_rcpt ruleset will strip @othersite and recheck user@site for relaying. This feature changes that behavior.

It should not be needed for most installations.

authinfoProvide a separate map for client side authentication information.
See SMTP AUTHentication for details.
By default, the authinfo database specification is:

hash /etc/mail/authinfo

preserve_luser_host Preserve the name of the recipient host if LUSER_RELAY is used. Without this option, the domain part of the recipient address will be replaced by the host specified as LUSER_RELAY. This feature only works if the hostname is passed to the mailer (see mailer triple in op.me).
Note that in the default configuration the local mailer does not receive the hostname, i.e., the mailer triple has an empty hostname.
preserve_local_plus_detail Preserve the +detail portion of the address when passing address to local delivery agent. Disables alias and .forward +detail stripping (e.g., given user+detail, only that address will be looked up in the alias file; user+* and user will not be looked up). Only use if the local delivery agent in use supports +detail addressing.
compat_check Enable ruleset check_compat to look up pairs of addresses with the Compat: tag -- Compat:sender<@>recipient -- in the access map. Valid values for the RHS include
  • DISCARD: silently discard recipient
  • TEMP: return a temporary error
  • ERROR: return a permanent error
In the last two cases, a 4xy/5xy SMTP reply code should follow the colon.
no_default_msaDon't generate the default MSA daemon, i.e.,

DAEMON_OPTIONS(`Port=587,Name=MSA,M=E')

To define a MSA daemon with other parameters, use this FEATURE and introduce new settings via DAEMON_OPTIONS().
mspDefines config file for Message Submission Program.
See sendmail/SECURITY for details and cf/cf/submit.mc how to use it.

An optional argument can be used to override the default of `[localhost]' to use as host to send all e-mails to.
Note that MX records will be used if the specified hostname is not in square brackets (e.g., [hostname]).
If `MSA' is specified as second argument then port 587 is used to contact the server. Example:

FEATURE(`msp', `', `MSA')

Some more hints about possible changes can be found in the section Message Submission Program.

queuegroup A simple example how to select a queue group based on the full e-mail address or the domain of the recipient. Selection is done via entries in the access map using the tag QGRP:, for example:
QGRP:example.com	main
QGRP:friend@some.org	others
QGRP:my.domain		local

where "main", "others", and "local" are names of queue groups. If an argument is specified, it is used as default queue group.

Note: please read the warning in doc/op/op.me about queue groups and possible queue manipulations.