Table of Contents for

sendmail, 4th Edition

The makemap program, supplied in source form with V8 sendmail, is fully described in The makemap Program on page 370. It is used to create database files and is run, in brief, from the command line like this:

% makemap type file < textfile

The type can be either dbm (which uses the ndbm(3) library routines), hash, or btree (both of which use the db(3) library routines). The file is the location and name (full path or relative name) for the database file to create. For dbm files, the .pag and .dir suffixes are added automatically. For db files, the .db suffix will be added automatically if it is not already included in the name.

The makemap program reads from its standard input. That input is line-oriented and contains the text from which the database files will be created. Lines that begin with a # are interpreted as comments and ignored. Lines that contain no characters (empty lines) are also ignored. Whitespace (spaces or tabs) separates the key on the left from the data on the right. An example of such an input file is the following:

lady     relaysite!lady
my.host  relaysite!lady
bug      bug.localuucp

The second line in this example shows that keys can be multitokened (my.host is three tokens). In reading from existing files, some conversion might be required to massage the input into a usable form. To make a database of the /etc/hosts file (for converting hostnames into IP addresses), for example, a command line such as the following might be required:^[337]

% awk '/^[^#]/ {print $2, $1}' /etc/hosts | makemap ...

Here, awk(1) needs to eliminate comment lines (the /^[^#]/). Otherwise, it will wrongly move them to the second column, where makemap will not recognize them as comments.

The name portion of the K configuration command immediately follows the K. Whitespace between the K and the name is optional:

K name type args
 ↑
 optional whitespace

The name must begin with a letter or digit and can contain only letters, digits, and the underscore character:

K local_hosts      ← good
K $andcents        ← bad

The case of the letters in name does not matter. All names are converted to lowercase before they are stored:

K LOCAL_Hosts
K local_hosts      ← the same

If you begin a name with a bad character, the following error will be printed and that K line will be ignored:

configfile: line num: readcf: config K line: no map name

If a bad character appears in the middle of a name, the part preceding the bad character will be taken as the name, and the part following the bad character will be taken as the type. For example, the name me@home will produce this error:

configfile: line num: readcf: map me: class home  not available

Recall that the type^[338] portion of the K configuration command follows the name:

Kname type args

Note that whitespace between the name and the type can be a joined indented line, which allows commenting and improves readability:

Kname             # Why this name
        type      # Why this type
        args      # and so on

The type declares which sort of database map to use. It must be one of the types listed in Table 23-2.

All of these database-map types are described in Alphabetized Database-Map Types on page 898 at the end of this chapter. If the type is not one of those listed, or if support for the type was not compiled in, the following error is printed and the K command is ignored:

configfile: line num: readcf: map name: class type  not available

The args of the K configuration command follow the symbolic name and type:

Kname type args

The args specify (among other things) the location of the database file or the name of a network database map. The args is like a miniature command line, and its general form looks like this:

switches file_or_map

The switches are letters prefixed with a - character that modify the use of the database. (We’ll discuss them in the next section.) The file_or_map is the location of the database file or the name of a network database map. The file_or_map should exclude the .pag and .dir suffixes for dbm-type files and exclude the .db suffix for hash, or btree-type files.

A database map is opened for reading when the configuration file is processed. If the file cannot be opened (and the -o is omitted, -o on page 889), an appropriate error is printed. The file_or_map should be an absolute pathname of a file (such as /etc/mail/uuhosts) or a literal network database-map name (such as hosts.byname). An nis database-map specification can include a domain:

map@domain

Relative filenames (names that omit a leading /) are interpreted as relative to the queue directory and should never be used.

The database files must live in a safe directory (one whose every component is writable only by root or the user defined by the TrustedUser option, TrustedUser on page 1112). If the file itself is unsafe or its directory is unsafe, one of several errors will be printed or logged, depending on how you run sendmail. (See the description of the DontBlameSendmail option DontBlameSendmail on page 1009 for more information about this safety check.)

Append values for duplicate keys V8.7 and later

Ordinarily, when sendmail builds (rebuilds) an aliases database, it objects to duplicate keys on the left of the colon:

staff:  bill
staff:  leopold        ← this is an error

But sometimes—for example, in automating—such duplicates are necessary. In such instances, the -A switch can be used with the AliasFile (A) option (see AliasFile on page 970) to cause duplicates to be silently appended:

staff:  bill
staff:  leopold
... silently modified by sendmail to internally become
staff:  bill, leopold

Note that this process is further illustrated in Duplicate Entries and Automation on page 477.

The -A database switch is useful only with alias files because those are the only files that sendmail rebuilds on its own. Beginning with V8.10, this switch is also useful with the ph type (ph on page 930).

Append tag on successful match V8.1 and later

When a key is looked up in a database (from inside the $( and $) operators of the RHS of rules) a successfully found key is replaced by its data. If the -a switch is given, the text following that switch, up to the first delimiting whitespace character, is appended to the replacement data. For example:

-a              appends  nothing
-a.             appends  .
-a,MAGICTOKEN   appends  ,MAGICTOKEN

The text to be appended is taken literally. Quotation marks and backslashed characters are included without interpretation, so whitespace cannot be included in that text. Because the rewritten RHS is normalized as an address, special address expressions (such as parentheses) should be avoided. The use of appended text is one of two methods used for recognizing a successful lookup in rules. We’ll discuss the other, $:, in Specify a Default with $: on page 893.

Don’t use if DeliveryMode=defer V8.10 and later

The defer setting of the DeliveryMode option (DeliveryMode on page 1004) is intended for sites that do not have a continuous connection to the Internet (specifically, dial-on-demand sites). For such sites, mail should be placed in the queue without interacting with the Internet (which is likely unavailable). Then, when the Internet connection is made, a normal queue run will deliver the mail.

Some database maps (such as those that look up hosts and possibly those that log messages with syslog) should probably not be used when sendmail is running in defer mode. This -D database switch can also be used with a few database-map types. When it is, it advises those types to not operate when sendmail is in defer mode.

Preserve case V8.1 and later

Ordinarily, sendmail will normalize a key to lowercase before looking it up in a database. If the keys in the database are case-sensitive (“TEX” is considered different from “tex,” for example), the -f database switch should be used to prevent this normalization. Note that if the -f switch is omitted (the default), the database must have been created with all lowercase keys (also the default).

Also note that when the -f switch is used with the regex database-map type, it causes the regular expression match to be made in a case-insensitive manner.

Specify column for key or key name V8.7 and later

Beginning with V8.7, sendmail began to support a flat text-file form of database. The /etc/hosts file is an example of such a flat file, in that it is organized in a line-by-line manner:

123.45.67.89      here.our.domain

When such files are read as databases (with the text type, text on page 941) you need to specify which column contains the key and which contains the value.

For nisplus, netinfo, and ph database maps, the -k switch specifies the name (text) of the desired column.

When the -k switch specifies which column contains the key, its absence defaults to 0 for the text type (which is indexed beginning with 0) and defaults to the name of the first column for the nisplus type. See also -v (-v on page 891) for the returned value’s column, and -z (-z on page 891) for the column delimiter.

Finally, note that for ldap database maps, the -k switch has a different meaning, one that is particular to that type.

Set a timeout for the lookup V8.12 and later

When doing a lookup, the -l switch sets a time limit for how long to wait for a reply:

-l5

Note that the limit is not a general time expression (that is, 15m still evaluates to 15 seconds).

Also note that this -l switch is not available for all database-map types. As of this writing, it is available only with the ldap and ph database-map types.

Suppress replacement on match V8.1 and later

Ordinarily, a successful lookup in a database map causes the key to be replaced by its value. When the intention is to merely verify that the key exists (not to replace it) the -m switch can be used to suppress replacement.

For example, the values that are returned from the hosts.byname NIS database map are not generally useful (they contain multiple hostnames). In looking up a key in this database map (with $( and $); see Use $( and $) in Rules on page 892), the -m switch prevents those multiple names from wrongly replacing the single hostname in the key. Note that the -a switch (-a on page 887) can still be used to append a suffix to a successful lookup. Also, the $:default (Specify a Default with $: on page 893) is still used if the lookup fails.

Append a null byte to all keys V8.1 and later

If a database was created with makemap’s -N switch (-N on page 374) to include the terminating zero byte with each key, this -N switch should be specified with the corresponding K configuration command to force all lookups to also include a zero byte. Note that -N is not needed for the nis type and, if included, is ignored. See also -O in -O on page 889.

Never add a null byte V8.2 and later

If neither -N nor -O is specified, sendmail uses an adaptive algorithm to decide whether to look for the terminating zero byte. The algorithm starts by accepting either possibility. If the first key looked up is found to end with a terminating zero byte, the algorithm will thereafter look only for keys with a terminating zero byte. If the first key that is looked up is found to not end with a terminating zero byte, the algorithm will thereafter look only for keys without a terminating zero byte.

If this -O switch is specified, sendmail never tries a zero byte, which can speed matches. Note that if both -N and -O are specified, sendmail will not produce an error message, and will never try to match at all, thus causing all lookups to appear to fail.

The database map is optional V8.1 and later

Ordinarily, in the case of types that employ disk files, sendmail will complain if a specified file cannot be opened for reading. If the presence of a database file is optional (as it can be on certain machines), the -o switch should be used to tell sendmail that the database is optional. Note that if a database is optional and cannot be opened, all lookups will silently fail for rules that use that database.

Also note that for network-based types of database maps, this -o switch can be used to cause failed initializations to be ignored. If a database map is used during the processing of a message, and if a lookup fails in the absence of a -o switch, the message (or SMTP request) will be rejected with a temporary failure.

Don’t strip quotes from key V8.7 and later

Ordinarily, sendmail strips all the nonescaped quotation marks (those not prefixed with a backslash) from a key before looking it up. For example, the following key:

"Bob "bigboy" Roberts \(esq\)"@bob.com

will have its nonescaped quotation marks removed and end up looking like this:

Bob "bigboy" Roberts (esq)@bob.com

Note that all escaped characters are de-escaped (have the backslash removed) during this process.

When quotation marks and escaped characters need to be preserved in a key before it is looked up, you can use the -q switch with the K configuration command. The -q switch suppresses dequoting and de-escaping.

Space replacement character V8.8 and later

The dequote type (dequote on page 904) refuses to remove quotation marks if doing so will result in an illegal address. For example, internal space characters are illegal in addresses:

"a b"           becomes →      "a b"

The -S switch causes all the quoted space characters to be changed into a character that you specify just before the dequoting process:

Kdequote dequote -S+

Here, we specify that quoted strings will have quoted spaces converted into a plus sign before dequoting. Therefore, the preceding conversion becomes the following:

"a b"           becomes →      a+b

As you will see in the reference sections at the end of this chapter, this -S database switch can be used with a few other types as well.

Suffix to append on temporary failure V8.10 and later

When a resource is temporarily unavailable, it would be handy if sendmail indicated that unavailability when the database lookup fails. Consider NIS, for example. It can time out when a server is down briefly, but a failed lookup of a user’s login name need not cause a permanent failure under such a circumstance. Instead, something should be returned to show that it is only a temporary failure.

The -T database switch was added with V8.10 sendmail to solve this problem. You use it to define a suffix to add to the key for the returned failure value when the problem is temporary. You might use it like this:

Kmailservers nis -T.Defer -o mailservers
...
R $* <@ $+ > $*                 $: $1<@$2>$3 <$(mailservers $2 $: Fail $)>
R $* <@ $+ > $* <$* . Defer>    $# error $@ 4.2.2 $: "450 defer"   ← handle failure
here
R $* <@ $+ > $* <Fail>          $# error $@ 5.7.1 $: "550 reject"  ← handle failure
here
R $* <@ $+ > $* <$+>            $# smtp $@ $4 $: $1 < @ $2 > $3    ← OK, so send it
...

Note that a permanent failure returns the failure alternative indicated by the $: operator (the Fail). But a temporary failure returns the suffix defined by the -T, appended to the original key (the $2) to form $2.Defer.

Note that this definition of temporary failure is different from that defined by the -D database switch. With -D, database lookups are not done at all if the DeliveryMode option (DeliveryMode on page 1004) is set to defer. Also note that this -T database switch affects only the return value. It does not affect the outcome of mail delivery. To affect the outcome on temporary failures, use the -t switch (-t on page 891).

Ignore temporary errors V8.10 and later

Usually it is acceptable for a lookup to fail because of a temporary failure of a system resource. When reading from a network database map (such as the DNS name server) temporary failures (such as server down) generally cause email to be requeued for a later try. However, you might sometimes find it desirable for a database map’s temporary failures to be ignored. In such cases, you can enable this -t database switch. With it set, a temporary error will cause the mail to be delivered.

Note that failure of a key to be found in a database map is not a temporary error. Also note that this switch just determines the outcome of a message. It does not affect the nature of the returned value. To affect the return value on temporary failures, use the -T database switch (-T on page 890).

Specify the value’s column V8.7 and later

The manner in which the key and its value are visually displayed in flat, sequential text files and certain network services, might not be directly suitable for use with database maps. A text-type file—for example, /etc/hosts—might display the key on the right and the value on the left:

123.45.67.89      here.our.domain

For such circumstances, the -v switch can be used with the K command to specify the column or item that will be returned as the value when a key is matched. For example:

Kaddr text -k1 -v0 /etc/hosts

For nisplus, netinfo, user, and other such database maps, the -v switch specifies the name (text) of the value’s column.

This -v switch specifies which column is the value to return. If it is omitted, it defaults to 0 for the text type (which is indexed beginning with 0) to the last named column for the nisplus type, and to the string "members" for the netinfo type. Note that the -v switch has a different meaning for the ph database-map type. See also -k (-k on page 888) for the value’s column and -z (-z on page 891) for the column delimiter.

Specify the column delimiter V8.7 and later

Flat, sequential text files have columns of information delimited from each other with a variety of characters:

123.45.67.89      here.our.domain          ← /etc/hosts uses a whitespace
nobody:*:65534:65534::/:                   ← /etc/passwd uses a colon

The -z switch can be used to specify a delimiter whenever the default delimiter of whitespace is not appropriate. In the case of the /etc/passwd file, a database declaration might look like this:

Kuid text -z: -k2 -v0 /etc/passwd  # map to convert user-id to login name

The default is whitespace for the text type. It is a comma for the netinfo type.

For the ldap type, a -z switch specifies the character to use to separate values when building the resulting string when multiple attribute values are returned.

The $: operator can be used as an alternative to the -a switch (or in conjunction with it). The $: operator, when it stands between the $( and $), specifies a default to use instead of the key, should a lookup fail:

R$- . uucp      $: $(uucp $1 $: $1.uucp $)

Here, the $- part of the LHS is looked up in the uucp database. If it is found, the $( to the $) in the RHS expression is replaced by the data from that database. If it is not found, the $: causes the expression to be replaced with the $- LHS part and a .uucp suffix ($1.uucp).

This version of our rule further simplifies the contents of the database file. With this rule, the database file would contain information such as the following:

lady    lady
sonya   sonya

The -a is still used as before to append a .localuucp to each successful match:

Kuucp hash -a.localuucp /etc/mail/uucp

In the RHS expression, the $: must follow the key or it loses its special meaning:

$(name key $:  default  $)

If the $:default wrongly precedes the key, it is used as the key, lookups fail, and replacements are not as expected. If the $: is present but the default is missing, a failed lookup returns an empty workspace.

For more complex substitutions, V8 sendmail offers use of the $@ operator in the RHS in conjunction with the $( and $) expressions in database maps.^[341] There can be multiple $@-prefixed texts between the key and the $: (if present) or the $), where each of the texts may itself be multiple rule-set expressions:

$(name key $@ text1  $@ text2 and text3 $: default  $)

Each $@text expression is numbered by position (from left to right):

$(name key $@ text1  $@ text2  $: default  $)
               ↑          ↑
1                                2

In this numbering scheme the key is always number 0, even if no $@s are listed.

These numbers correspond to literal % digit expressions in the data portion of a database map. For example:

lady   %0!%1@%2

When a lookup of the key in the RHS of the rule is successful, the returned value is examined for %digit expressions. Each such expression is replaced by its corresponding $@text from the rule. In the case of the preceding database map, %0 would be replaced with lady (the key), %1 with text1, and %2 with text2.

To illustrate, consider the earlier database entry and the following rule:

R$- @ $-.uucp   $: $(uucp $2 $@ $1 $@ mailhost $: $1@$2.uucp $)

If the workspace contains the address joe@lady.uucp, the LHS matches. The RHS rewrites only once because it is prefixed with the $: operator. The expression between the $( and $) causes the second $- from the LHS (the $2, the key) to be looked up in the database whose symbolic name is uucp. Because $2 references lady from the workspace, lady is found and the data (%0!%1@%2) is used to rewrite. The %0 is replaced by lady (the key via $2). The text for the first $@ ($1 or joe) then replaces the %1. Then the second text for the second $@ (mailhost) replaces the %2. Thus, the address joe@lady.uucp is rewritten to become lady!joe@mailhost.

If a host other than lady appeared in the workspace, this RHS would use the $:default part. Thus, the address joe@foo.uucp would become (via the $:$1@$2.uucp) joe@foo.uucp. That is, any address that is not found in the database would remain unchanged.

If there are more $@text expressions in the RHS than there are numbers in the value, the excess $@text parts are ignored. If a %digit in the data references a nonexistent $@text, it is simply removed during the rewrite.

All $@text expressions must lie between the key and the $:default (if present). If any follow the $:, they become part of the default and cease to reference any %digit.

But be aware of a common mistake, which is to confuse a $number rule righthand-side expression with %digit results. For example, you might expect $1 assigned to %1 and $2 assigned to %2 with the following expression, but you would be wrong:

 $(lookup $&{client_addr} $@ $1 $2 $)

Here, $1 and $2 are both assigned to %1. Remember, each $@ corresponds to a single %digit, no matter how many expressions follow the $@. The correct way to code the preceding expression would look like this:

$(lookup $&{client_addr} $@ $1 $@ $2 $)

Here, the intended association is achieved, where $1 is correctly assigned to %1 and $2 is correctly assigned to %2.

The special database-map type called host can be declared to modify name-server lookups with $[ and $]. The special symbolic name and type pair, host and host, is declared with the $( and $) operators like this:

Khost host -a.

The -a switch was discussed earlier in this chapter. Here, it is sufficient to note how it is used in resolving fully qualified domain names with the $[ and $] operators in the RHS of rules. Under V8 sendmail, $[ and $] are a special case of the following database lookup:

$(host lookuphost $)

A successful match will ordinarily append a dot to a successfully resolved hostname.

When a host type is declared with the K command, any suffix of the -a replaces the dot as the character or characters added.^[342] For example:

$[ lookuphost $]     ← found, so rewritten as lookuphost.domain.

Khost host -a
$[ lookuphost $]     ← found, so rewritten as lookuphost.domain

Khost host -a.yes
$[ lookuphost $]     ← found, so rewritten as lookuphost.domain.yes

The first line shows the default action of the $[ and $] operators in the RHS of the rules. If lookuphost can be fully qualified, its fully qualified name becomes the rewritten value of the RHS and has a dot appended. The next two lines show the -a with no suffix (note that with no suffix the -a is optional). In this configuration file, the fully qualified name has nothing (not even a dot) appended. The last two lines show a configuration file with a .yes as the suffix. This time, the fully qualified name has a .yes appended instead of the dot.

FEATUREs that employ on-disk database files all share the common default database-map type hash. But if you wish to change that default to another type, you can do so with the following mc configuration command:

define(`DATABASE_MAP_TYPE', `dbm')

Here, we declare the default to be dbm, thereby causing all such FEATUREs to use ndbm(3) database files. Note that if you declare a default, you must do so before declaring any database FEATUREs.

Many FEATUREs that take arguments require you to declare the database type. For example:

FEATURE(`authinfo', `dbm /etc/security/authinfo')

That is, this DATABASE_MAP_TYPE’s default is used only if no argument is given for the feature.

Perform arithmetic computations V8.10 and later

Beginning with V8.10, sendmail supports arithmetic computations in rule sets via a database-map type called arith. This form of database map is always present for your use, without the need for special compile-time macros. To illustrate one use for arith, consider this mini configuration file:

V10
Kmath arith
SCalculate
R $+ $+ $+      $@ $(math $2 $@ $1 $@ $3 $: EXCEPTION $)

The K configuration command declares that a database map named math will be of the database-map type arith. To use this database map we declare a rule set. We call that rule set Calculate so that rule-set testing will be mnemonically clear.

The rule is the crux of how this math database map is used:

R $+ $+ $+      $@ $(math $2 $@ $1 $@ $3 $: EXCEPTION $)
                          ↑     ↑     ↑
                      operator  lvalue   rvalue

The arith database-type database maps (such as math here) take three arguments. The first, in the position of the key that would otherwise be used for lookups, is the arithmetic operator. The legal operators, as of V8.12, are shown in Table 23-5.

If the arithmetic operator used is not one of those shown in the table (such as an illegal ! operator), the lookup (calculation) fails and the value following the $: operator is returned (the EXCEPTION). If the arithmetic operator is legal (is shown in the table), a calculation is performed and the result returned.

The two values used in the computation are passed following the first and second $@ operators. The lvalue follows the first $@ operator, and the rvalue follows the second. The arithmetic operation specified is performed on the two values and the result is returned.

Computations are always performed using integer calculations, and the values are always interpreted as integer values. A division by 0 always returns a failed lookup (the EXCEPTION). The less-than and equality arithmetic operators return the literal token TRUE or FALSE, indicating the truth of the comparison.

To demonstrate this arith database-map type, you can run sendmail on the mini configuration file listed earlier. If that file were called demo.cf you might test it like this:

% /usr/sbin/sendmail -Cdemo.cf -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
> Calculate 1 + 1
Calculate          input: 1 + 1
Calculate        returns: 2
> Calculate 5 / 0
Calculate          input: 5 / 0
Calculate        returns: EXCEPTION
> Calculate 5 / 2
Calculate          input: 5 / 2
Calculate        returns: 2
> Calculate −1 * 4
Calculate          input: −1 * 4
Calculate        returns: −4
> Calculate 2 = 2
Calculate          input: 2 = 2
Calculate        returns: TRUE
> Calculate 0xff / 2
Calculate          input: 0xff / 2
Calculate        returns: 0

The last three lines show that only decimal integer values can be used. Also note that negative values work properly.

One example of a real use for this type of database map might be a test to see whether the ETRN command should be run if the machine’s load average is too high:

D{OurMaxLoad}20
Scheck_etrn
R $*          $: $(math l $@ $&{load_avg} $@ ${OurMaxLoad} $) $1
R FALSE       $#error $@ 4.7.1 $: "450 The load average is currently too high."

The check_etrn rule set is called by V8.10 and later sendmail each time the remote site sends an ETRN command, and before any reply is sent to the remote site.

The $& prevents the {load_avg} macro (${load_avg} on page 832) from being interpreted too early (when the configuration file was read). Consequently, its current value is compared to the value in the ${OurMaxLoad} macro. If the truncated integer value of the load average is higher than our limit, the request is denied. Note that if ${OurMaxLoad} is undefined, the rule will return a failed lookup, but not the literal token FALSE. Thus, by undefining ${OurMaxLoad} you disable this test.

To fetch a random value using the new r operator (available as of V8.14) you need to provide lower and upper bounds for the random number as the first and second arguments following the operator:

 V10
Kmath arith
SRandomize
R $+ $+      $@ $(math r $@ $1 $@ $2 $)

Here, if the first argument ($1) is numerically less than the second argument ($2), the ASCII representation of a pseudorandom value will be returned that is greater than or equal to the first and less than or equal to the second. If the two values are equal, that equal value is returned. If the first is greater than the second, a literal r is returned to indicate an error. If either, or both, values are non-numeric, the value 0 is returned.

Only a few database switches are useful with the arith database-map type. They are listed in Table 23-6.

Although these switches are allowed, it will take some inventiveness to devise a use for them with this arith database-map type. If you specify a switch that is not listed in the table, it will be silently ignored.

The db(3) form of database V8.1 and later

The term btree stands for “balanced tree.” It is a grow-only form of database. Lookups and insertions are fast, but deletions do not shrink the size of the database file.^[343] A good description of this form of database can be found in The Art of Computer Programming, Vol. 3: Sorting and Searching, by D.E. Knuth. The btree type is available only if sendmail was compiled with NEWDB defined and the Berkeley or Sleepycat db library linked (The Sleepycat DB Library on page 104). In most cases, the hash type (hash on page 908) will perform slightly better.

Quite a few database switches are available with this database-map type. They are listed in Table 23-7.

One use for this btree type might be to look up users for whom permission to send offsite email is denied. The data source file might look like the following, and might live in the file /etc/mail/badusers.db (after makemap was run to create it):

bob    bob
ted    ted
alice  alice

A simple configuration file to test this database can then be created like this:

V10
Kbaduser btree -a.BAD -t /etc/mail/badusers
R $+ < @ $+ > $*                    $: $1< @ $2 > $3 < $(baduser $1 $) >
R $+ < @ $+ > $* < $* . BAD >       $#error $@ 5.1.3 $: "Offsite mailing denied"

Here, the database is declared with the K configuration command. The -a database switch causes .BAD to be appended to any key that is found in the database. The -t switch causes temporary errors to be ignored. A match causes the workspace to carry the extra information that is matched by <$*.BAD >, and which results in an error being reported back to the sender.

The -d38.20 command-line switch (-d38.20 on page 568) can be used to observe this type’s lookups in more detail.

Look up the best MX record for a host V8.7 and later

The bestmx database-map type looks up a hostname as the key and returns the current, single best MX record as the value. Because bestmx is a type, not a database map, you need to declare it with a K configuration command before you can use it:

Kbestmx bestmx

One use for this database-map type might be to see whether a particular host has any usable MX records:^[344]

Kbestmx bestmx
...
R $*< @ $+ > $*                $: $1<@$2>$3 < $(bestmx $2 $: NO $) >
R $*< @ $+ > $* < NO >         $#smtp  $@ $2 $: $1 < @ $2 > $3
R $*< @ $+ > $* < $* >         $: $1<@ $[ $2 $] > $3

In the first rule, we look up the host part of an address (which has already been focused by the canonify rule set 3) with the bestmx database map. The result of the lookup is surrounded with angle brackets and appended to the original address. The second rule looks for the NO caused by an unsuccessful lookup (the $:). The original address is then sent with the smtp delivery agent. If the hostname inside the appended angle braces is not NO, the host part of the original address is canonicalized with the $[ and $] operators.

bestmx is a special internal type that can utilize only a few of the K command switches, as listed in Table 23-8.

The -z switch (special for this bestmx database-map type) allows multiple MX records to be returned, and specifies a column delimiter used to separate one record from another. As long as the column delimiter is not a character that appears in any domain name, it will be used to separate all the MX records returned by the MX lookup. These records will be returned in the new workspace. For example, if the -z switch specified a comma, and if abc.com were looked up, the following might be returned:

mail11 . disney . com . , mail . disney . com .

If the -z switch wrongly specifies a character that can exist in a domain name (such as a dot), the following error will be reported and only one MX record will be returned:

bestmx_map_lookup: MX host mail11.disney.com. includes map delimiter character 0x2E

If too many MX records are returned, the list can be truncated to avoid an overly long workspace. When the list is truncated, some MX records can be lost. This can become a serious problem when this -z switch is used with this database-map type and when FEATURE(relay_based_on_MX) is also declared (FEATURE(relay_based_on_MX) on page 271).

This type can be watched with the -d8 debugging switch (-d8.1 on page 548).

Really ndbm supplied with most versions of Unix V8.1 and later

The dbm database-map type, which is really the ndbm form of database, is the traditional form of Unix database file. Data is stored in one file, keys in another. The data must fit in blocks of fixed sizes, so there is usually a limit on the maximum size (1 kilobyte or so) on any given stored piece of data. The dbm database-map type is available only if sendmail was compiled with NDBM declared (NDBM on page 125).

Many database switches are available with this dbm database-map type. All are listed in Table 23-9.

This is the database-map type used with aliases files, if the hash type is unavailable. This type is also needed on machines that employ NIS because the underlying files for those services are stored in dbm format. Note that because of the implicit limit on the size of a piece of data, you should consider using one of the db(3) hash or btree types instead.

Remove quotation marks V8.6 and later

V8 sendmail can remove quotation marks from around tokens by using the special dequote database-map type. Because dequote is a type, not a database map, you need to declare it with a K configuration command before you can use it:

Kunquote dequote

This declares a database map named unquote of the type dequote. Once a database-map name has been declared, the dequote type can be used in the RHS of rules to remove quotation marks. It is used with $( and $) just like all database-map lookups:

$(unquote tokens $)

Here, arbitrary tokens are looked up in the database map named unquote. That database map is special because it is of the type dequote. Instead of being looked up in an external database file, tokens will just have any surrounding quotation marks removed:

"A.B.C"           becomes   A.B.C
"A"."B"."C"       becomes   A.B.C
"A B"             becomes   "A B"
"A,B"             becomes   "A,B"
"A>B"             becomes   "A>B"

The first example shows that surrounding quotation marks are removed. The second shows that multiple quoted tokens are all dequoted. The last three show that sendmail refuses to dequote any tokens that will form an illegal or ambiguous address when dequoted.

As an aid to understanding this dequoting process, run the following two-line configuration file in rule-testing mode:

V10
Kdequote dequote

You can then use the -bt /map command to try various dequoting possibilities:

> /map dequote "A.B.C"
map_lookup: dequote ("A.B.C") returns A.B.C (0)
> /map dequote "A"."B"."C"
map_lookup: dequote ("A"."B"."C") returns A.B.C (0)
> /map dequote "A B"
map_lookup: dequote ("A B") no match (0)

A few database switches are available to modify the behavior of this dequote database-map type. They are listed in Table 23-10.

Note that beginning with V8.7, specifying the -s switch (and beginning with V8.10, specifying the -S switch) causes the space character to be replaced with another character before dequoting (-S on page 890):

Kdequote dequote -s+           ← V8.7 through V8.9
Kdequote dequote -S+           ← V8.10 and later

When using the mc configuration technique, dequote switches are declared like this:

define(`confDEQUOTE_OPTS', `-S+')

In either case, the last example would have the space converted to a plus sign before the conversion, thus resulting in a legal address. The "A B" example (which failed before) will become the following:

> /map dequote "A B"
map_lookup: dequote ("A B") returns A+B (0)

Also note that beginning with V8.8, specifying the -a switch causes a suffix of your choice to be appended to a successful match:

define(`confDEQUOTE_OPTS', `-a.yes')

In that case, the "A.B.C" example would become the following:

> /map dequote "A.B.C"
map_lookup: dequote ("A.B.C") returns A.B.C.yes (0)

In addition to removing quotes, the dequote type also tokenizes everything that is returned. It does this because quotes are ordinarily used to mask the separation characters that delimit tokens.

No debugging switch is available to watch the actions of the dequote type.

Look up addresses using DNS V8.12 and later

The dns type is an internal database map available to perform DNS lookups. It is declared like this:

Kdnslookup dns -Rlookup-type

The -R switch—which specifies the DNS query to perform—must always be included. Table 23-11 shows the DNS queries that are supported.

If an -R value other than those in Table 23-11 is specified, the following two errors are printed and logged. If the -R switch is omitted, only the second error is printed and logged:

configfile: line num: dns map lookup: wrong type bad -R value
configfile: line num: dns map lookup: missing -R type

To make this dns database-map type more useful, the switches shown in Table 23-12 are also available for your use.

One possible use for this dns database map might be to do a reverse lookup of a connecting host’s address and to defer the message if that address does not resolve.^[345] Consider the following mc configuration, for example:

LOCAL_CONFIG
Krlookup dns -RPTR -a.FOUND -d5s -r2

LOCAL_RULESETS
Local_check_relay
R $*             $: $&{client_addr}
R IPv6: $*       $# OK
R $+.$+.$+.$+    $: $(rlookup $4.$3.$2.$1.in-addr.arpa. $)
R $* . FOUND     $# OK
R $*             $#error $@ 4.1.8 $: "450 cannot resolve " $&{client_addr}

Here, under the LOCAL_CONFIG, we declare a dns-type database called rlookup. The -RPTR specifies that we will be looking up PTR (address) records. The -a.FOUND instructs sendmail to append a literal .FOUND to the value returned by a successful lookup. Finally, the -d5s and -r2 switches prevent the lookup from hanging for too long an interval.

The actual rules are under the LOCAL_RULESETS section of your mc configuration file. We place the rules under the Local_check_relay rule set (Local_check_relay and check_relay on page 252), which is used to screen incoming network connections and accept or reject them based on the hostname, domain, or IP address. The first rule matches everything and simply copies the value of the ${client_addr} macro into the workspace. That macro contains the connecting host’s IP address.

The second rule checks to see whether the IP address is an IPv6 address (the IPv6: prefix) and if so, accepts the address (the $#OK). If the address is a normal dotted-quad, IPv4-style address (such as 123.45.67.8), the third rule finds it in the workspace. An IPv4 address is looked up in the RHS of the third rule using the rlookup database. The key point here is that an address has to look like a hostname, so we reverse it and add a literal .in-addr.arpa. suffix to it. For example:

123.45.67.8     would look up as →    8.67.45.123.in-addr.arpa.

The fourth rule detects the result of the lookup. If the workspace ends in a literal .FOUND, the lookup was successful and the rule set returns a $#OK, which means that the message is acceptable.

The last rule handles any lookup failure (including temporary failures). The envelope sender is rejected with a temporary error, thus causing the sending site to retain the message in its queue. If the IP address can be looked up in the future, no harm is done. Otherwise, the message will eventually bounce.

The value returned by the dns-type database map is always a single item. If a host has multiple MX, A, or AAAA records, a successful lookup will return only one such record. In the case of MX records, the lowest-cost record may not be returned.^[346]

This dns-type database map can be used only if sendmail was built with the NAMED_BIND and DNSMAP compile-time macros defined (which they are by default).

This dns-type database map is used primarily by FEATURE(dnsbl) (FEATURE(dnsbl) on page 261) and FEATURE(enhdnsbl) (FEATURE(enhdnsbl) on page 263). Both of these features use the -RA and -T<TMP> switches. FEATURE(enhdnsbl) also uses the -r5 and -a. switches. Beginning with V8.13, these switches can be overridden for FEATURE(dnsbl) using the DNSBL_MAP_OPT mc configuration macro (FEATURE(dnsbl) on page 261). For FEATURE(enhdnsbl), the timeout for -r can be changed using the EDNSBL_TO mc configuration macro.

LOCAL_CONFIG
Ktxtlookup dns -RTXT -a.FOUND -Bexample.com

LOCAL_CONFIG
Klookup dns -RA -z, -Z2

LOCAL_CONFIG
Klookup dns -RA -z,

hostA . example . com ,  hostB . example . com

A db(3) form of database V8.1 and later

The hash database map type uses a hashing algorithm for storing data. This approach to a database is described in A New Hash Package for UNIX, by Margo Seltzer (Usenix Proceedings, Winter 1991). The hash type is available only if sendmail was compiled with NEWDB defined and the Berkeley or Sleepycat db(3) library linked.

The hash type is the default that is used with most of the features offered by the mc configuration technique (see Table 23-4 on page 896). For example, consider the following:

Kuudomain hash -o /etc/mail/uudomain

Here, a database map named uudomain is declared to be of type hash. The -o says that the database file /etc/mail/uudomain is optional.

Quite a few other database-map switches are available with this type. The complete list is shown in Table 23-13.

The -d38.20 command-line switch (-d38.20 on page 568) can be used to observe this type’s lookups in more detail. See also the btree type (btree on page 901).

MIT network user authentication services V8.7 and later

The hesiod type of database map uses the Hesiod system, a network information system developed as Project Athena. Support of hesiod database maps is available only if you declare HESIOD when compiling sendmail. (See HESIOD on page 115 for a fuller description of the Hesiod system.)

A hesiod database map is declared like this:

Kname hesiod HesiodNameType

The HesiodNameType must be one that is known at your site, such as passwd or service. An unknown HesiodNameType will yield this error when sendmail begins to run:

cannot initialize Hesiod map (hesiod error number)

One example of a lookup might look like this:

Kuid2name hesiod uid
R$-      $: $(uid2name $1 $)

Here, we declare the network database map uid2name using the Hesiod type uid, which converts user-id numbers into login names. If the conversion was successful, we use the login name returned; otherwise, we use the original workspace.

Quite a few database-map switches are available with this type. They are all listed in Table 23-14.

The -d38.20 command-line switch (-d38.20 on page 568) can be used to observe this type’s lookups in more detail.

Internal table to store lookup hostnames V8.1 and later

The host database-map type is a special internal database used by sendmail to help resolve hostnames. It is fully described under the $[ and $] operators in $[ and $]: A Special Case on page 895.

Only a few database-map switches are available with the host type, and they are listed in Table 23-15.

The -D database switch should probably always be used with this type on sites that have dial-on-demand connections to the Internet. It prevents host lookups when the DeliveryMode option (DeliveryMode on page 1004) is set to defer.

Search for an aliases database entry V8.1 and later

The implicit database-map type refers specifically to aliases(5) files only. It causes sendmail to first try to open a db(3) hash-style alias file. If that fails or if NEWDB support was not compiled in, it tries to open an ndbm(3)-style database. If that fails, sendmail reads the aliases(5) source file into its internal symbol table.

When sendmail rebuilds its aliases database (as with newaliases) it looks for the special string literal /yp/ anywhere in the path specified for the aliases source file. If that string literal is found, sendmail uses this implicit type to create both a db(3) hash-style alias file, and an ndbm(3)-style database. It creates both to support NIS compatibility.

Although you can declare and use this type in a configuration file, there is no reason to do so. It is of use only to the internals of sendmail. If implicit fails to open an aliases file, probably because of a faulty AliasFile option (AliasFile on page 970), sendmail will issue the following error if it is running in verbose mode:

WARNING: cannot open alias database bad filename

If the source aliases file exists but no database form exists, sendmail will read that source file into its internal symbol table using the stab type (stab on page 938).

You can experiment with this implicit database-map type using a mini configuration file such as this:

V10
Kxlate implicit -a.Yes -o /etc/mail/aliases
Stest
R$*     $: $(xlate $1 $)

Here, we declare a database map named xlate to be of type implicit. We use it to look up aliases in the file /etc/mail/aliases (which can optionally not exist because of the -o switch). We don’t care whether that file is a db file, a dbm file, or a text file. The implicit type will find the right type and use it. A successful match will append a .Yes suffix to the returned value.

The -d38.20 command-line switch (-d38.20 on page 568) can be used to observe this type’s lookups in db files and dbm files.

The Lightweight Directory Access Protocol V8.8 and later

LDAP stands for Lightweight Directory Access Protocol and provides access to a service based on X.500. Additional information about LDAP is available from:

The ldap database-map type is used to look up items in that directory service. (Prior to V8.10, this was called ldapx to reflect its experimental condition at the time. That prior name still works but is deprecated.) The ldap database-map type is declared like this:

Kname ldap  switches

Lookups via LDAP are defined entirely by the switches specified. To illustrate, consider the following X.500 entry:

cn=Full Name, o=Organization, c=US
sn=Name
uid=yourname
mail=yourname@mailhub.your.domain
objectclass=person
objectclass=deptperson

To look up a login name in this database and have the official email address for that user returned, you might use a declaration such as this:

Kgetname ldap -k"uid=%s" -v"mail" -hldap_host -b"o=Organization, c=US"

Here we use only three switches:

The -k, -h, and -v switches are mandatory.

You can omit selected switches from the K configuration command by defining them with the LDAPDefaultSpec option (LDAPDefaultSpec on page 1039). In general, this option is used to define the -b and -h switch settings. You can, however, use it to define any number of defaults that you wish.

The following rule can be used with the preceding declaration to look up the preferred mail address for a user:

R $* <@ $=w . > $*       $: $(getname $1 $: $1<@$2>$3 $)

Here, we presume that this rule was preceded by a call to the canonify rule set 3 to focus on the host part of the address. If the lookup succeeds, the new (unfocused) address is returned from the mail= line in the database. Otherwise, the original address is returned.

This ldap type has more database switches available for it than most other types. They are all listed in Table 23-16.

Although some of these switches are also used by other database-map types, many of them are unique to this ldap database-map type. In addition to setting switches with the K command, you can also preset selected switches with the LDAPDefaultSpec option (LDAPDefaultSpec on page 1039).

Each successful lookup can cause a line such as the following to be logged via syslog(3) when the LogLevel option (LogLevel on page 1040) is greater than 9:

qid: ldap  key  =>  value

Note that the ldap type can be used only if the LDAPMAP compile-time macro was defined when sendmail was compiled (LDAPMAP on page 119). Also note that the USING_NETSCAPE_LDAP compile-time macro (USING_NETSCAPE_LDAP on page 150) will need to be defined if your ldap libraries are from Netscape or are derived from Netscape’s libraries.

define(`ALIAS_FILE', `ldap:')

ldap -k (&(objectClass=sendmailMTAAliasObject)
        (sendmailMTAAliasGrouping=aliases)
        (|(sendmailMTACluster=${sendmailMTACluster})
        (sendmailMTAHost=$j))
        (sendmailMTAKey=%0))
     -v sendmailMTAAliasValue,
        sendmailMTAAliasSearch:FILTER:sendmailMTAAliasObject,
        sendmailMTAAliasURL:URL:sendmailMTAAliasObject

define(`ALIAS_FILE', `ldap:-k (&objectClass=mg)(mail=%0) -v mmember')

RELAY_DOMAIN_FILE(`@LDAP')

F{X}@ldap:-k (&(objectClass=sendmailMTAClass)
        (sendmailMTAClassName=X)
        (|(sendmailMTACluster=${sendmailMTACluster})
        (sendmailMTAHost=$j)))
     -v sendmailMTAClassValue,
        sendmailMTAClassSearch:FILTER:sendmailMTAclass,
        sendmailMTAClassURL:URL:sendmailMTAClass

-b"o=Organization, c=US"

-d"cn=Directory Manager, o=igloo CA, l=Melbourne, st=Victoria, c=AU"

define(`confLDAP_DEFAULT_SPEC', `-h ldap.example.gov -p 8389')

define(`confLDAP_DEFAULT_SPEC', `-H ldap://ldap.example.gov:8389')

define(`confLDAP_DEFAULT_SPEC', `-H ldaps://ldap.example.gov -b dc=example,dc=gov')

define(`confLDAP_DEFAULT_SPEC', `-H ldapi:///path/to/file -b dc=example,dc=gov')

Must compile with -DUSE_LDAP_INIT to use LDAP URIs (-H) in map name

-h"hostA hostB"

-h"hostA hostB:463"

-h ldaphost                 ← not this
-h ldaphost.your.domain     ← this is preferred

-K -k gid=%2

-k uid=%s

-k (&(objectClass=sendmailMTAClass)(sendmailMTAClassName=ClassName)
   (|(sendmailMTACluster=${sendmailMTACluster})(sendmailMTAHost=$j)))

Method for binding must be [none|simple|krbv4] (not bad word) in map name

cn=Full Name,  o=Organization,   c=US
sn=Name
uid=yourname
mailfrom=youraddress

ou=hardware
ou=software

Deref must be [never|always|search|find] (not badword) in map name

Scope must be [base|one|sub] (not badword) in map name

-V=

user=bob

-voc,ou
-v"oc, ou"

foo:org:bar

oc=foo:ou=org:oc=bar

Too many return attributes in name (max 64)

-v attribute:type:objectclass|objectclass|...

define(`confLDAP_DEFAULT_SPEC', `-H ldaps://ldap.example.com -b dc=example,dc=gov')

LOCAL_CONFIG
Kgetname ldap
-k (&(objectClass=sendmailMTAAliasObject)(sendmailMTAKey=%0))
-v sendmailMTAAliasValue,
   mail:NORMAL:inetOrgPerson,
   uniqueMember:DN:groupOfUniqueNames,
   sendmailMTAAliasSearch:FILTER:sendmailMTAAliasObject,
   sendmailMTAAliasURL:URL:sendmailMTAAliasObject

Kgetname ldap -k"uid=%s" -v"mail" -hhost -b"o=Organization, c=US" -w3

LDAP version specified exceeds max of max in map name

LDAP version specified is lower than min in map name

-zchar

FEATURE(`ldap_routing')

Kldapmh ldap −1 -v mailHost
       -k (&(objectClass=inetLocalMailRecipient)(mailLocalAddress=%0))
Kldapmra ldap −1 -v mailRoutingAddress
       -k (&(objectClass=inetLocalMailRecipient)(mailLocalAddress=%0))

mailLocalAddress: alice@your.domain
mailHost: another.domain
mailRoutingAddress: alice@another.domain

                                                       replaces the declaration
following Kldapmh
                             ↓
 FEATURE(`ldap_routing', `newldapmh', ` newldapmra')
                                         ↑
                                                       replaces the declaration
following Kldapmra

FEATURE(`ldap_routing', `ldap −1 -T<TMPF> -v relayHub
        -k (&(objectClass=inetLocalMailRecipient)(mailLocalAddress=%0))')

Kldapmh ldap −1 -v relayHub
       -k (&(objectClass=inetLocalMailRecipient)(mailLocalAddress=%0))

FEATURE(`ldap_routing', `newldapmh', ` newldapmra',  `bounce')

FEATURE(`ldap_routing', `newldapmh', ` newldapmra',  `bounce', `strip')

dn: uid=alice, o=your.domain, c=US
uid: alice
objectClass: inetLocalMailRecipient
mailLocalAddress: alice@your.domain
mailRoutingAddress: alice@another.domain

FEATURE(`ldap_routing', `newldapmh', ` newldapmra',  `bounce', `detail', `
nodomain',  `tempfail')

LDAPROUTE_DOMAIN(`list of domains')
LDAPROUTE_DOMAIN_FILE(`file')

LDAPROUTE_EQUIVALENT(`list of domains')
LDAPROUTE_EQUIVALENT_FILE(`file')

Store a value into a macro via a rule V8.10 and later

Not only is it possible to use defined macros in rule sets, but as of V8.10 sendmail, it is also possible to place new values into defined macros from inside rule sets. This marvel is accomplished using the macro-type database map. It is an internal type, always available regardless of how sendmail was compiled.

The macro type can be used in three ways. For example:

Kstore_it_in macro
R$*     $: $(store_it_in {MyMacro} $@ $1 $)   ← store new value into macro
R$*     $: $(store_it_in {MyMacro} $@ $)      ← clear macro to empty string
R$*     $: $(store_it_in {MyMacro} $)         ← undefine the macro

The first line declares store_it_in to be the name of a macro database-map type that is used in the rules that follow. Those three rules show three different ways to affect the value stored in the macro {MyMacro}. Note that the macro name must not be prefixed with a $. If it is, its value will be used as the name, instead of its actual name. We cover the use of $& later.

The first rule shows that the value to be stored into the macro is passed as the first $@ argument, the $1. If this value is that of an undefined macro, the stored result is an empty string. Otherwise, the value is stored as is into the {MyMacro} macro. If the value contains macro-like expressions (such as $x), their values are used. If {MyMacro} was previously undefined, it becomes defined.

The second rule shows what happens when the value to be stored is missing (or undefined). A missing value has the effect of clearing the value stored in the {MyMacro} macro to that of an empty string. If {MyMacro} was previously undefined, it becomes defined.

The third rule shows what happens when the argument part (the $@ part) is omitted. The effect is to undefine the {MyMacro} macro.

Regardless of how you update the value in the macro, an empty string is returned. This can cause the original workspace to be lost. If you need to preserve the original workspace (or part of it), consider a variation such as the following:

R$*     $: $(store_it_in {MyMacro} $@ $1 $) $1
                                            ↑
                                    return original workspace

This macro type can also be used as an indirect way to store values into different sendmail macros. To illustrate, consider the following mini configuration file and its use of $&:

V10
Kput macro
D{Target}{LocalTarget}
Stest
R $*    $: $(put $&{Target} $@ $1 $)

Here, the intention is to store the value (the $@ $1) into the macro whose name is stored in {Target}. The D line initializes that name as {LocalTarget}. To witness this indirect method in action run this mini configuration file in rule-testing mode:

% /usr/sbin/sendmail -Cdemo.cf -bt
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
> test foo in local target
test               input: foo in local target
test             returns:
> ${LocalTarget}
foo in local target
> .D{Target}{NewTarget}
> test foo in new target
test               input: foo in new target
test             returns:
> ${NewTarget}
foo in new target

This sort of indirection can be useful in rules that might, for example, cause one relay host to be selected under high load and another under low load. Another use might be to reject certain outside mail during business hours, but accept it after business hours.

No database-map switches are useful with this type.

NeXT, Darwin, and Mac OS X NetInfo V8.7 and later

NetInfo is NeXT’s implementation of a network-based information service. It has also been adopted by the Darwin and Mac OS X operating systems. The netinfo type expects a database-map declaration to be of the following form:

Kname netinfo  database-map

The database-map name defaults to /aliases.

The netinfo type uses only a handful of database switches, as shown in Table 23-18.

The -v property returns defaults to members. The -z column delimiter defaults to a comma.

Support of netinfo database maps is available only if you declare NETINFO when compiling sendmail (NETINFO on page 127).

Sun’s Network Information Services (NIS) V8.1 and later

Sun Microsystems offers a network information service called NIS. It provides the ability to look up various kinds of information in network databases. The nis type allows you to access that network information by way of rules in rule sets. You declare an nis database-map type like this:

Kname nis nismap

Here, name is the identifier that you will later use in rule sets. The nismap is any NIS database map that defaults to mail.aliases. Lookups will occur in the default NIS domain. If you wish to specify some other domain, you can append an @ character and the domain name to the nismap:

Kname nis nismap @ domain

To illustrate, consider the need to look up the name of the central mail server for your department. If such a database map were called mailservers, you could use the following configuration file line to look up your domain in that database map:

Kmailservers nis -o mailservers
...
R $* <@ $+ > $*          $: $1<@$2>$3 <$(mailservers $2 $)>
R $* <@ $+ > $* <$+>     $#smtp $@ $4 $: $1 < @ $2 > $3
...

Here, we look up the host part of an address ($2) in the mailservers NIS database map. The -o makes the existence of the database map optional. If the host part is found, it is rewritten to be the name of the mail server for that host. In the last rule, we forward the original address to that server.

Without the -o, the nonexistence of a database map will cause this error to be logged:

Cannot bind to map name in domain  domain:  reason here

If NIS is not running or if sendmail cannot bind to the domain specified for the default domain, the following error is logged:

421 4.3.5 NIS map name specified, but NIS not running

Only a few database switches are available with this nis database-map type. They can be found in Table 23-19.

The nis database-map type is available only if sendmail is compiled with NIS defined (NIS on page 128).

Sun’s newer version of NIS V8.7 and later

Sun Microsystems’ NIS+ is a complete redo of its earlier NIS system. The nisplus type allows you to look up information using NIS+. The form of that type declaration looks like this:

Kname nisplus  nismap.domain

Here, the nismap is an NIS+ database-map name, such as mail_aliases.^[349] If the domain or .domain is missing, the nisplus default domain is used. If the entire nismap.domain is missing, the default becomes mail_aliases.org_dir. The domain org_dir contains all the systemwide administration tables.

Any lookup failures that can be retried will automatically be retried up to five times, with a sleep(3) of 2 seconds between each try. If the map.domain doesn’t exist in the local NIS+ system, no error is reported.

Only a modest number of database switches are available for this type. They are listed in Table 23-20.

You can use the -k switch to specify a key column to look up. Under nisplus, columns are named, so the -k must be followed by a valid name. You can also use the -v switch to specify the value’s column, and a name. If the -v is omitted, the last column becomes the default.

IRIX nsd database maps V8.10 and later

The nsd database-map type implements an interface to the Unified Name Service supplied under IRIX 6.5 and later. That service is a translation layer between any program and a wide range of services (ranging from NIS to LDAP). You declare an nsd database-map type like this:

Kname nsd  switches  nsdmap

The name is the symbolic name you will later use in the RHS of rule sets. The nsdmap is a full path into the nsd(8) daemons’ name space (such as /ns/engr.sgi.com/passwd.byname).

This nsd database-map type supports only a few switches. They are listed in Table 23-21.

This nsd type was contributed by Bob Mende of SGI Inc.

Provide a never-found service V8.7 and later

The null database-map type is an internal service that always returns a failed lookup.

Normally, the null type is used only internally. It can, however, be useful when used to replace another database-map type so that it can force failure without causing an error. Consider, for example, a tiny configuration file that does not need the use of the aliases facilities. One way to declare aliases would be like this:

O AliasFile=null:

This tells sendmail to use the null type for looking up aliases. Therefore, no aliases will ever be found.

None of the K command switches can be used with the null database-map type. If you try to use any, they will be silently ignored. No debugging switch is available to watch this null database-map type.

CCSO Nameserver (ph) lookups V8.10 and later

Prior to V8.10 sendmail, redirecting email with a ph server required running the phquery program. Beginning with V8.10 sendmail, a database-map type called ph has been added that allows sendmail to perform direct ph queries. You declare it like this:

Kname ph  switches

The complete list of switches for this database-map type is shown in Table 23-22.

This ph database map was contributed by Mark Roth of the University of Illinois at Urbana-Champaign. For additional information see:

-h phserver.your.domain

-h "phserver.your.domain phserver2.your.domain"

ph_map_parseargs: -h flag is required

Run an external program to look up the key V8.7 and later

The program type allows you to perform lookups via arbitrary external programs. The form for the declaration of this database-map type looks like this:

Kname program  /path  arg1 arg2 ...

The /path must be the full pathname to the program. Relative paths will not work, and attempts to use them will log the following error and cause the lookup to fail:

NOQUEUE: SYSERR(user): relative name: cannot exec: No such file or directory

The program is run as the user and group specified by the DefaultUser option (DefaultUser on page 1000) unless the RunAsUser option (RunAsUser on page 1083) is declared, in which case it will run as the user and group declared by that latter option.

The arguments to the program always have the key to be looked up added as a final argument:

Kname program  /path  arg1 arg2 ...
                                     ↑
                                key added here

This is the only way the key can be passed to the program. The key will specifically not be piped to the program’s standard input.

The value (result of the lookup) is read from the program’s standard output. Only the first MAXLINE-1 characters are read (where MAXLINE is defined in conf.h, currently as 2048). The read result is processed like an address and placed into the workspace (unless the -m switch is used with the K command).

To illustrate, consider the need to look up a user’s preferred address in an external relational database:

Kilook program /usr/sbin/ingres_lookup -d users.database

This program has been custom-written to accept the key as its final argument. To prevent spurious errors, it exits with a zero value regardless of whether the key is found. Any system errors cause it to exit with a value selected from those defined in <sysexits.h > (those recognized by sendmail). Error messages are printed to the standard error output, and the found value (if there was one) is printed to the standard output.

In general, it is better to use one of the database formats known to sendmail than to attempt to look up keys via external programs. The process of fork(2)ing and exec(2)ing the program can become expensive if it is done often, slowing down the handling of mail.

This type of database map employs only a small set of switches. They are listed in Table 23-23.

Use regular expressions V8.9 and later

The regex type allows you to parse tokens in the workspace using POSIX regular expressions. For information on how to use regular expressions, see the online manuals ed(1) and regexp(1). A regex database-map type is declared like this:

Kname regex expression

The name is the symbolic name you will use to reference this database map from inside the RHS of rule sets. The expression is the literal text that composes your regular expression. Here is a simple example:

Knumberedname regex   ^[0-9]+<@(aol|msn).com.?>

The intention here is for this regular expression to match any address that has an all-numeric user part (the part before the <@) and a domain part that is either aol.com or (the | character) msn.com. To make rules that use this type easier to write, you can add a -a switch to the declaration:

Knumberedname regex -a.FOUND ^[0-9]+<@(aol|msn).com.?>

Here the -a database switch causes .FOUND to be appended to any successful match.

Note that because of the way we have declared this database map, nothing but the suffix will be returned on a successful match. To get the original key returned you need to also use the -m database switch (-m on page 888).

This regex type can use a number of switches to good advantage. The complete list is shown in Table 23-24.

Note that some additional explanation for a few of these switches is provided in the sections that follow. Also, for an actual example of the regex type, see the file cf/cf/knecht.mc, which demonstrates a way to deal with one type of spam email.

Kmatch regex -b -aLOCAL @localhost

configfile: line num: field (2) out of range, only 1 substring in pattern

Kmatch regex -s2,3 -d+|+ -a.FOUND (\<a\>|\<b\>)@(\<bob\>|\<ted\>).
(\<com\>|\<org\>)

> test a@bob.com
test               input: a @ bob . com
test             returns: bob+|+com . FOUND

Kmatch regex -s2,3 -m -d+|+ -a.FOUND (\<a\>|\<b\>)@(\<bob\>|\<ted\>)
.(\<com\>|\<org\>)

> test a@bob.com
test               input: a @ bob . com
test             returns: a @ bob . com . FOUND

Kmatch regex -m -n -a.FOUND (\<a\>|\<b\>)@(\<bob\>|\<ted\>).(\<com\>|\<org\>)

> test a@bob.com
test               input: a @ bob . com
test             returns: a @ bob . com
> test x@y.net
test               input: x @ y . net
test             returns: x @ y . net . FOUND

V10
Kmatch regex -s (\<bob\>|\<ted\>)
Stest
R $*       $@ $(match $1 $)

% /usr/sbin/sendmail -bt -Cdemo.cf
ADDRESS TEST MODE (ruleset 3 NOT automatically invoked)
Enter <ruleset> <address>
> test bob
test               input: bob
test             returns: bob $| bob
> test alice
test               input: alice
test             returns: alice

Kmatch regex -s -a.FOUND (bob|ted)

> test bob
test               input: bob
test             returns: bob $| bob . FOUND

Kmatch regex -s2 -a.FOUND (\<a\>|\<b\>)@(\<bob\>|\<ted\>)

> test a@bob
test               input: a @ bob
test             returns: bob . FOUND

Kmatch regex -s2,3 -a.FOUND (\<a\>|\<b\>)@(\<bob\>|\<ted\>).(\<com\>|\<org\>)

> test a@bob.com
test               input: a @ bob . com
test             returns: bob $| com . FOUND

Search a series of database maps V8.7 and later

The sequence type allows you to declare a single name that will be used to search a series of databases. It is declared like this:

Kname sequence  map1  map2 ...

Here, a key (in a later rule set) will be looked up first in the database map named map1, and if not found there, it will be looked up in the database map named map2. The type of each of the listed database maps should logically relate but need not be the same. Consider, for example, a rule’s RHS, where a lookup will match if the workspace contains either a user’s login name or the name of a host, with the hostname taking precedence:

Khosts host  -a<+> /etc/hosts
Kpasswd user -a<-> /etc/passwd
Kboth sequence hosts passwd

R$-     $: $(both $1 $)

Here, we say that the database map named both is of type sequence. Any single token in the LHS will be looked up first in the database map named hosts, and if it is found there the hostname will be returned with a <+> appended. If it is not found in the hosts database map, it will be next looked up in the passwd database map. If it is found there, the original workspace will be returned with a <-> appended. If the workspace is not found in either database map, the lookup fails and the workspace remains unchanged.

If any database map in the series of database maps declared with the K command does not exist, as for example:

Kboth sequence hosts passwd badname

the following error is logged and printed, and that database map is ignored:

Sequence map both: unknown member map  badname

If the number of database maps that are sequenced exceeds the maximum allowed (MAXMAPSTACK in conf.h, currently 12), the following error is printed and the overflow of database maps is ignored:

Sequence map name: too many member maps ( max  max)

None of the K command switches can be used with the sequence type. If you try to use any, they will be wrongly interpreted as database-map names.

Perform lookups over a socket V8.13 and later

Beginning with V8.13 sendmail, a new database-map type called socket is available for your use.^[352] You declare a socket database-map type like this:

Kname socket type:port@host

Here, name is the identifier that you will later use in rule sets. The type:port@host is declared in the same fashion as a Milter is declared using the X configuration command (The X Configuration Command on page 1173). For example:

Ktrustedip socket inet:8020@db5.example.gov

Here, lookups can be made in rule sets using the database map named trustedip. The sendmail program will make an IPv4 connection (the inet) to port 8020 on the host db5.example.gov. Once the connection has been made, lookups are performed using a simple dialog that looks like this:

sendmail sends:    database_map_name key
sendmail receives:   status datum

Note that neither the request sent nor the reply received may end in a carriage-return/linefeed pair, a carriage return, or a line feed. Also note that the two parts of each dialog are separated by a single space character.

Both the request and the reply begin and end with characters that denote their length and termination. The length is an ASCII representation of the number of characters sent or received, stated as a prefix and a colon. Both the request and the reply are terminated by a comma. But note that the length prefix must not include the comma in its length computation. For example:

sendmail sends:    17:trustedip 1.2.3.4,
sendmail receives:  14:OK VERYTRUSTED,

The sendmail program sends the database-map name declared earlier using a K configuration command. In our example, that would be the database map named trustedip. That name is followed by a single space and then the key to look up in the database. Again, the entire request is prefixed with the length and a colon and terminated with a comma (and excludes any terminating newline or carriage-return characters).

The connected-to host replies with one of the keywords shown in Table 23-25. Each must be completely uppercase. Each keyword is followed by a single space, then information appropriate to the keyword (the keyword OK, for example, would be followed by the sought datum). The entire reply is prefixed with a length and a colon and terminated with a comma.

To illustrate, consider the need to look up the name of the central mail server for your department. If such a database map were called mailservers, you could use the following configuration file line to look up your domain in that database map:

Kmailservers socket -o inet:8020@db4.example.gov
...
R $* <@ $+ > $*          $: $1<@$2>$3 <$(mailservers $2 $)>
R $* <@ $+ > $* <$+>     $#smtp $@ $4 $: $1 < @ $2 > $3
...

Here, we look up the host part of an address ($2) in the mailservers database on the host db4.example.gov. The -o makes the existence of the database map optional. If the host part is found, it is rewritten to be the name of the mail server for that host. Finally, in the last rule, we forward the original address to that server.

Note that only a few database switches (shown in Table 23-26) are available with this socket database-map type.

Note that the socket database-map type is available only if sendmail is compiled with the SOCKETMAP compile-time macro (SOCKETMAP on page 145) defined when you build sendmail (which is normally not done by default).

For examples of how to use this new socket database-map type, see the files contrib/socketmapServer.pl and contrib/socketmapClient.pl.

Internally load aliases into the symbol table V8.10 and later

The stab database-map type is used internally by sendmail to load the raw aliases(5) file into its internal symbol table.^[353] This is a fallback position that is taken if no database form of aliasing is found.

The stab type should never be used in configuration files.

Build sequences based on service switch V8.7 and later

The switch database-map type is used internally by sendmail to create sequence types of database maps based on external service-switch files. The lines inside a service-switch file look like this:

service     methodA methodB

as, for example:

aliases   files nis

This line tells sendmail to search for its aliases in files first, and then using NIS.

To illustrate the switch type, consider the need to look up aliases inside rule sets in the same way that sendmail looks up its own aliases. To do this, you would declare a switch database map. For example:

Kali switch aliases

This causes sendmail to search for the service named aliases in the service-switch file. In this example it finds such a line, so for each how that follows the aliases in that line, sendmail creates a new database map with the name ali followed by a dot and the how:^[354]

aliases   files    becomes →    ali.files
aliases   nis      becomes →    ali.nis

These named database maps are then sequenced for you. Recall that sequence database maps are declared like this:

Kname sequence  map1  map2,...

The name given to the sequence is ali. In our example, the following sequence is automatically created for you from your original switch declaration:

Kali sequence ali.files ali.nis

In rule sets, when you look up aliases with the ali database map:

R...        $( ali $1 $)
                ↑
          the sequence named ali

you will use the sequence named ali that was automatically built for you from a combination of your original switch definition and your service-switch file’s aliases line. That is, you declare a switch, but you use a sequence.

Log information using syslog(3) via rule sets V8.10 and later

The syslog database-map type allows you to log messages directly from inside rule sets. If you are unfamiliar with syslog, see Log with syslog on page 513 for a general discussion of syslog-style logging.

The syslog type is declared like this:

Kname syslog switches

The name is the database-map name you will use in rule sets. The switches are selected from those shown in Table 23-27.

In rule sets, the syslog type is used, for example, like this:

R $*    $: $(name what to log $)

The information in the position of the key is logged as is via the syslog facility. An empty workspace is returned as a result of logging. That is, for the syslog type, the $( and $) expressions evaluate to an empty string.

Any use of defined macros in the message should use the $& prefix so that the current value is logged. For example, the following might be used to log the load average:

Kdolog syslog
R $*    $: $(dolog The cutoff was caused by a load average of $&{load_average}. $)

If you need to have a sendmail macro or positional macro literally logged as is, just prefix it with an extra $ character. For example, the following shows the macro and logs its value:

R $*    $: $(dolog Failure detected with $$1=$1 $)

Don’t use quotation marks to surround macro references. Quotation marks cause the macro’s internal binary value to print, instead of its defined value. For example, the following will log $1=^U1:

R $*    $: $(dolog $$1="$1" $)         ← wrong

If macros are not included inside quotation marks, you can use quotation marks for clarity. They will be stripped from the output:

R $*    $: $(dolog "Aborting the use of ETRN because of high load" $)

In general, this syslog type of database map will be used in conjunction with other database maps that can make decisions about behavior, such as arith (arith on page 898). You should avoid the temptation to overlog because rule sets can be parsed every time mail is sent or received, and if you place a logging rule in the wrong place, you risk flooding your site’s syslog facility with extraneous messages.

Kname syslog -LLOG_CRIT

Kname syslog -LCRIT

syslog_map_parseargs: Unknown priority LOG_MAIL

Look up in flat text files V8.7 and later

The text database-map type allows you to look up keys in flat text files. This technique is vastly less efficient than looking up keys in real databases, but it can serve as a way to test rules before implementing them in database form.

For the text database map, columns for the key and value are measured as an index. That is, the first column is number 0. To illustrate, consider the following mini configuration file that can be used to check spelling:

Kspell text /usr/dict/words
Spell
R$-      $: $(spell $1 $: not in dictionary $)

The /usr/dict/words file contains only a single column of words. This rule shows that the key is (by default) the first column (index 0). And the value is (by default) also the first column (index 0).

For more sophisticated applications you can specify the key’s column (with the -k switch), the value’s column (with the -v switch), and the column delimiter (with the -z switch). To illustrate, consider the need to look up a user-id in the /etc/passwd file and to return the login name of the user to whom it belongs:

Kgetuid text -k2 -v0 -z: /etc/passwd
R$-      $: $(getuid $1 $)

The lines of a password file look like this:

ftp:*:1092:255:File Transfer Protocol Program:/u/ftp:/bin/sh

The third column (where the columns are separated by colons) is the uid field. The first is the login name. Note that the -k and -v switches show these fields as indexes, where the first is 0 and the third is 2.

Note that if a file cannot be opened because it is unsafe (DontBlameSendmail on page 1009), the following warning will be logged and printed:

text map "name": unsafe map file filename

This message will not be printed if the -o switch is specified with the database-map declaration.

Only a handful of database switches are available with this text type. The are listed in Table 23-28.

The -d38.20 debugging command-line switch (-d38.20 on page 568) is available to watch this text type.

Look up in the User Database V8.7 and later

The User Database is a special database file that you create for use by sendmail. It causes sender and recipient addresses to be rewritten under control of an external database. Ordinarily, any local address is first looked up in the aliases database. If it is not found there, that user’s ~/.forward is next examined. If the User Database is enabled, the address is looked up in that database after aliasing and before forwarding, but only if the selected delivery agent has the F=@ flag set (F=@ on page 766).

In the sections that follow, we describe the use of this database in detail, but first we will note a few important points.

Although we illustrate here that a lookup can be done using a database file, a remote lookup can also be done via a User Database server, or via a network service. Those forms of lookup are described in UserDatabaseSpec on page 1116.

You can also look up addresses in the User Database with rule sets using this userdb database-map type. To do so, you declare it like this:

Kname userdb  switches  field

Here, the name is the name you will use in later rule sets. The field is either a literal maildrop or mailname (see Create the User Database on page 944). The possible switches are shown in Table 23-29.