Sendmail Operation Guide

K: key file declaration

Special maps can be defined using the line:

Kmapname mapclass arguments

The mapname is the handle by which this map is referenced in the rewriting rules. The mapclass is the name of a type of map; these are compiled in to sendmail(1M). The arguments are interpreted depending on the class; typically, there would be a single argument naming the file containing the map.

Maps are referenced using the syntax:

$( map key $@ arguments $: default $)

Either or both of the arguments or default portion may be omitted. The $@ arguments may appear more than once. The indicated key and arguments are passed to the appropriate mapping function. If it returns a value, it replaces the input. If it does not return a value and the default is specified, the default replaces the input. Otherwise, the input is unchanged.

The arguments are passed to the map for arbitrary use. Most map classes can interpolate these arguments into their values using the syntax %n (where n is a digit) to indicate the corresponding argument. Argument %0 indicates the database key. For example, the rule

R$- ! $+ $: $(uucp $1 $@ $2 $: %1 @ %0 . UUCP $)

looks up the UUCP name in a (user defined) UUCP map; if not found, it turns it into .UUCP form. The database might contain records like:

decvax %1@%0.DEC.COM
research %1@%0.ATT.COM

Note that default clauses never do this mapping.

The built in map with both name and class host is the host name canonicalization lookup. Thus, the syntax:

   $(host hostname$)
is equivalent to:
   $[hostname$]
There are many defined classes:

dbm
Database lookups using the ndbm(3bsd) library. sendmail must be compiled with NDBM defined.

btree
Database lookups using the btree interface to the Berkeley DB library. sendmail must be compiled with NEWDB defined.

hash
Database lookups using the hash interface to the Berkeley DB library. sendmail must be compiled with NEWDB defined.

nis
NIS lookups. sendmail must be compiled with NIS defined.

nisplus
NIS+ lookups. sendmail must be compiled with NISPLUS defined. The argument is the name of the table to use for lookups, and the -k and -v flags may be used to set the key and value columns respectively.

hesiod
Hesiod lookups. sendmail must be compiled with HESIOD defined.

ldap
LDAP X500 directory lookups. sendmail must be compiled with LDAPMAP defined. The map supports most of the standard arguments and most of the command line arguments of the ldapsearch(1ldap) program. Note that, by default, if a single query matches multiple values, only the first value will be returned unless the -z (value separator) map flag is set. Also, the -1 map flag will treat a multiple value return as if there were no matches. (For details of the UnixWare implementation of LDAP, refer to Configuring and administering LDAP.)

netinfo
NeXT NetInfo lookups. sendmail must be compiled with NETINFO defined.

text
Text file lookups. The format of the text file is defined by the -k (key field number), -v (value field number), and -z (field delimiter) flags.

ph
PH query map. Contributed and supported by Mark Roth, roth@uiuc.edu. For more information, consult the web site http://www-wsg.cso.uiuc.edu/sendmail/sendmail-phmap/.

nsd
nsd map for IRIX 6.5 and later. Contributed and supported by Bob Mende of SGI, mende@sgi.com.

stab
Internal symbol table lookups. Used internally for aliasing.

implicit
Really should be called ``alias''; this is used to get the default lookups for alias files, and is the default if no class is specified for alias files.

user
Looks up users using getpwnam(3C). The -v flag can be used to specify the name of the field to return (although this is normally used only to check the existence of a user).

host
Canonifies host domain names. Given a host name it calls the name server to find the canonical name for that host.

sequence
The arguments on the K line are a list of maps; the resulting map searches the argument maps in order until it finds a match for the indicated key. For example:
Kmap1 ...
Kmap2 ...
Kseqmap sequence map1 map2
With this key definition, a lookup against seqmap first does a lookup in map1. If that is found, it returns immediately. Otherwise, the same key is used for map2.

syslog
the key is logged via syslogd(8). The lookup returns the empty string.

switch
Much like the sequence map except that the order of maps is determined by the service switch. The argument is the name of the service to be looked up; the values from the service switch are appended to the map name to create new map names. For example, consider the key definition:
Kali switch aliases
together with the service switch entry:
aliases     nis files
This causes a query against the map ali to search maps named ali.nis and ali.files in that order.

dequote
Strip double quotes (") from a name. It does not strip backslashes, and will not strip quotes if the resulting string would contain unscannable syntax (that is, basic errors like unbalanced angle brackets; more sophisticated errors such as unknown hosts are not checked). The intent is for use when trying to accept mail from systems such as DECnet that routinely quote odd syntax such as:
49ers::ubell
A typical usage is probably something like:
Kdequote dequote

...

R$- $: $(dequote $1 $) R$- $+ $: $>3 $1 $2

Care must be taken to prevent unexpected results. For example:
"|someprogram < input > output"
will have quotes stripped, but the result is probably not what you had in mind. Fortunately these cases are rare.

regex
The map definition on the K line contains a regular expression. Any key input is compared to that expression using the POSIX regular expressions routines regcomp, regerr, and regexec. Refer to the documentation for those routines for more information about the regular expression matching. No rewriting of the key is done if the m flag is used. Without it, the key is discarded or if -s if used, it is substituted by the substring matches, delimited by $| or the string specified with the the -d flag. The flags available for the map are:

-n not
-f case sensitive
-b basic regular expressions (default is extended)
-s substring match
-d set the delimiter used for -s
-a append string to key
-m match only, do not replace/discard value
-D perform no lookup in deferred delivery mode
The -s flag can include an optional parameter which can be used to select the substrings in the result of the lookup. For example, -s1,3,4


program
The arguments on the K line are the pathname to a program and any initial parameters to be passed. When the map is called, the key is added to the initial parameters and the program is invoked as the default user/group id. The first line of standard output is returned as the value of the lookup. This has many potential security problems, and has terrible performance; it should be used only when absolutely necessary.

macro
Set or clear a macro value. To set a macro, pass the value as the first argument in the map lookup. To clear a macro, do not pass an argument in the map lookup. The map always returns the empty string. Example of typical usage include:
   Kstorage macro
   

...

# set macro ${MyMacro} to the ruleset match R$+ $: $(storage {MyMacro} $@ $1 $) $1 # set macro ${MyMacro} to an empty string R$* $: $(storage {MyMacro} $@ $) $1 # clear macro ${MyMacro} R$- $: $(storage {MyMacro} $) $1


arith
Perform simple arithmetic operations. The operation is given as key, currently +, -, *, /, l (for less than), and = are supported. The two operands are given as arguments. The lookup returns the result of the computation (that is, TRUE or FALSE) for comparisons, integer values otherwise. All options which are possible for maps are ignored. A simple example is:
   Kcomp arith
   

...

Scheck_etrn R$* $: $(comp l $@ $&{load_avg} $@ 7 $) $1 RFALSE $# error ...

Most of these accept as arguments the same optional flags and a filename (or a mapname for NIS; the filename is the root of the database path, so that .db or some other extension appropriate for the database type will be added to get the actual database name). Known flags are:

-o
Indicates that this map is optional; that is, if it cannot be opened, no error is produced, and sendmail will behave as if the map existed but was empty.

-N, -O
If neither -N nor -O are specified, then sendmail uses an adaptive algorithm to decide whether or not to look for null bytes on the end of keys. It starts by trying both; if it finds any key with a null byte it never tries again without a null byte and vice versa. If -N is specified, it never tries without a null byte and if -O is specified, it never tries with a null byte. Setting one of these can speed matches but they are never necessary. If both -N and -O are specified, sendmail will never try any matches at all. That is, everything will appear to fail.

-ax
Append the string x on successful matches. For example, the default host map appends a dot on successful matches.

-D
Perform no lookup in deferred delivery mode.

-f
Do not fold upper to lower case before looking up the key.

-m
Match only (without replacing the value). If you only care about the existence of a key and not the value (as you might when searching the NIS map hosts.byname for example), this flag prevents the map from substituting the value. However, The -a argument is still appended on a match, and the default is still taken if the match fails.

-kkeycol
The key column name (for NIS+) or number (for text lookups). For LDAP maps, this is an LDAP filter string in which %s is replaced with the literal contents of the lookup key and %0 is replaced with the LDAP escaped contents of the lookup key according to RFC2254.

-vvalcol
The value column name (for NIS+) or number (for text lookups). For LDAP maps, this is the name of one or more attributes to be returned; multiple attributes can be separated by commas. If not specified, all attributes found in the match will be returned.

-zdelim
The column delimiter (for text lookups). It can be a single character or one of the special strings \n or \t to indicate newline or tab respectively. If omitted entirely, the column separator is any sequence of white space. For LDAP maps this is the separator character to combine multiple values into a single return string. If not set, the LDAP lookup will only return the first match found.

-t
Normally, when a map attempts to do a lookup and the server fails (for example, sendmail couldn't contact any name server; this is not the same as an entry not being found in the map), the message being processed is queued for future processing. The -t flag turns off this behavior, letting the temporary failure (server down) act as though it were a permanent failure (entry not found). It is particularly useful for DNS lookups, where someone else's misconfigured name server can cause problems on your machine. However, care must be taken to ensure that you don't bounce mail that would be resolved correctly if you tried again. A common strategy is to forward such mail to another, possibly better connected, mail server.

-D
Perform no lookup in deferred delivery mode. This flag is set by default for the host map.

-Sspacesub
The character to use to replace space characters after a successful map lookup (especially useful for regex and syslog maps).

-sspacesub
For the dequote map only, the character to use to replace space characters after a successful dequote.

-Llevel
For the syslog map only, it specifies the level to use for the syslog call. Note that this identifier is set as early as possible. However, sendmail may be used if problems arise before the command line arguments are processed.

-A
When rebuilding an alias file, the -A flag causes duplicate entries in the text version to be merged. For example, two entries:
   list:	user1, user2
   list:	user3
would be treated as though it were the single entry
   list:	user1, user2, user3
in the presence of the -A flag.

The following additional flags are present in the ldap map only:


-R
Do not auto chase referrals. sendmail must be compiled with -DLDAP_REFERRALS to use this flag.

-n
Retrieve attribute names only.

-rderef
Set the alias dereference option to one of never, always, search, or find.

-sscope
Set search scope to one of base, one (one level), or sub (subtree).

-hhost
LDAP server hostname.

-bbase
LDAP search base.

-pport
LDAP service port.

-ltimelimit
Time limit for LDAP queries.

-Zsizelimit
Size (number of matches) limit for LDAP queries.

-ddistinguished_name
The distinguished name to use to login to the LDAP server.

-Mmethod
The method to authenticate to the LDAP server. Should be one of LDAP_AUTH_NONE, LDAP_AUTH_SIMPLE , or LDAP_AUTH_KRBV4.

-Ppasswordfile
The file containing the secret key for the LDAP_AUTH_SIMPLE authentication method or the name of the Kerberos ticket file for LDAP_AUTH_KRBV4.

-1
Force LDAP searches to only succeed if a single match is found. If multiple values are found, the search is treated as if no match was found.
The dbm(3bsd) map appends the strings ``.pag'' and ``.dir'' to the given filename; the hash and btree maps append ``.db''. For example, the map specification

Kuucp dbm -o -N /usr/lib/uucpmap

specifies an optional map named uucp of class dbm; it always has null bytes at the end of every string, and the data is located in /usr/lib/uucpmap.{dir,pag}.

The program makemap(1M) can be used to build any of the three database-oriented maps. It takes the following flags:


-f
Do not fold upper to lower case in the map.

-d
Allow duplicate keys in the map.

-N
Include null bytes in keys.

-o
Append to an existing (old) file.

-r
Allow replacement of existing keys; normally, re-inserting an existing key is an error.

-v
Print what is happening.
The sendmail daemon does not have to be restarted to read the new maps as long as you change them in place; file locking is used so that the maps will not be read while they are being updated.

New classes can be added in the routine setupmaps in file conf.c.


© 2000 The Santa Cruz Operation, Inc. All rights reserved.