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$)

   $[hostname$]

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.

ldapx

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

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.

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.

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

-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 a filter string passed to the printf(3S) function with a %s where the string to be mapped is inserted.

-vvalcol

The value column name (for NIS+) or number (for text lookups). For LDAP maps, this is the name of the attribute to 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 whitespace.

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

-sspacesub

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

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.

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