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

During replacement of either a map value or default the string %n (where n is a digit) is replaced by the corresponding argument. Argument zero is always 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

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(3) library. Sendmail must be compiled with NDBM defined.
btree
Database lookups using the btree interface to the Berkeley db(3) library. Sendmail must be compiled with NEWDB defined.
hash
Database lookups using the hash interface to the Berkeley db(3) 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.
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(3). 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, if the key definition is:
Kmap1 ...
Kmap2 ...
Kseqmap sequence map1 map2
then 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.

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 or -O are specified, 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 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).
-vvalcol
The value column name (for NIS+) or number (for text lookups).
-zdelim
The column delimiter (for text lookups). It can be a single character or one of the special strings \en or \et to indicate newline or tab respectively. If omitted entirely, the column separator is any sequence of whitespace.
"-sspacesub
For the dequote map only, the character to use to replace space characters after a successful dequote.

The dbm map appends the strings .pag and .dir to the given filename; the two db-based 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(8) 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.
-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 won't be read while they are being updated.[20]

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


[Contents] [Previous] [Next]


Questions or problems regarding this web site should be directed to Steve Gielda.
Copyright 1999 www.cotse.com.  All rights reserved.
Last modified: Friday April 02, 1999.