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.