The K
configuration command is used to associate a
symbolic name with a database file. The symbolic name
will later be used in the RHS of rules.
The form of the K
command looks like this:
Kname class args
The name
is the symbolic name. The class
is the kind
of database to use (see Section 33.3.2, "The class").
The args
specifies the location and properties of the database file
(see Section 33.3.3, "The args").
We describe each in turn.
The name
portion of the K
configuration command immediately
follows the K
. Whitespace between the K
and the
name
is optional.
Kname class args
optional whitespace
The name must begin with a letter or digit and may contain only letters, digits, and the underscore character. For example:
K local_hosts good K $andCents bad
If you begin a name
with a bad character, the following error
will be printed and that K
line will be ignored:
configfile: linenum
: 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 class
. For
example, the name
me@home
will produce this error:
configfile: linenum
: readcf: map me: class home not available
The case of the letters in name
does not matter.
All names are converted to lowercase before they are stored.
Recall that the class
portion of the K
configuration
command follows the name
:
Kname class args
Note that whitespace between the name
and the class
may be a joined indented line, which allows commenting and improves
readability:
Kname
# Why this nameclass
# Why this classargs
# and so on
The class
is the database type. It must be
one of the classes listed in
Table 33.3.
Class | Version | Description | |
---|---|---|---|
btree | Section 33.8.1 | V8.1 and above | Berkeley's db form of database |
bestmx | Section 33.8.2, bestmx | V8.7 and above | Look up the best MX record for a host |
dbm | Section 33.8.3 | V8.1 and above | Really ndbm supplied with most versions of UNIX |
dequote | Section 33.8.4, dequote | V8.1 and above | A pseudo map for removing quotation marks |
hash | Section 33.8.5, hash | V8.1 and above | Berkeley's db form of database |
hesiod | Section 33.8.6 | V8.7 and above | MIT network user authentication services |
host | Section 33.4.3, "$[ and $]: A Special Case" | V8.1 and above | Internal table to store and look up hostnames |
implicit | Section 33.8.8, implicit | V8.1 and above | Search for an aliases database file |
ldapx | Section 33.8.9 | V8.8 and above | The Lightweight Directory Access Protocol |
netinfo | Section 33.8.10 | V8.7 and above | NeXT Computers network information services |
nis | Section 33.8.11 | V8.1 and above | Sun's Network Information Services (NIS) |
nisplus | Section 33.8.12 | V8.7 and above | Sun's newer Network Information Services (NIS+) |
null | Section 33.8.13, null | V8.7 and above | Provide a never found service |
program | Section 33.8.14, program | V8.7 and above | Run an external program to look up the key |
sequence | Section 33.8.15, sequence | V8.7 and above | Search a series of maps |
stab | Section 33.8.16, stab | V8.1 and above | Internally load aliases into the symbol table |
switch | Section 33.8.17, switch | V8.7 and above | Internal hook to auto-build sequences |
text | Section 33.8.18, text | V8.7 and above | Look up in flat text files |
userdb | Section 33.8.19, userdb | V8.7 and above | Look up in the User Database |
user | Section 33.8.20, user | V8.7 and above | Look up local passwd information |
All of these classes are described in Section 33.8, "Alphabetized Reference" at the end
of this chapter. If the class
is not one of those listed,
or if support for the class
was not compiled in, the following error
is printed and the K
command is ignored:
configfile: linenum
: readcf: map mehome: class badclass not available
The case of the class
is ignored by sendmail. That is,
hash
, Hash
, and HASH
are all the same.
The args
of the K
configuration command follow symbolic name and class type:
Kname class args
The args
specify
(among other things) the location of the database file or the name
of a network 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
map. The file_or_map
should exclude the .pag and .dir
suffixes for dbm class files and exclude
the .db suffix for hash or btree class files.
A database or map is opened for reading when the configuration
file is processed. If the file
cannot be opened (and
the -o
is omitted; see Section 33.3.4.8, "-o the database file is optional (V8.1 and above)"), an appropriate error
is printed. The file_or_map
should be an absolute pathname
of a file (such as /etc/uuhosts)
or a literal network map name (such as hosts.byname).
An nis
map specification can include a domain:
map@domain
Relative filenames (names that omit a leading /
) are interpreted
as relative to the current directory of the process that invoked
sendmail and should never be used.
The switches
must follow the class
and precede
the file_or_map
:
Kname class switches file_or_map
If any switches
follow file_or_map
,
they are silently ignored.
[3]
All switches
begin with a -
character and
are listed in
Table 33.4.
[3] This is true as of version 8.8.4. Future versions may change the semantics of the
K
line such that switches may follow.
If a switch other than those listed is specified, that switch is silently ignored.
Not all switches work with all classes. Some classes use many switches; others use none. The switches that are used by each class are shown in Table 33.5.
Class | Switches |
---|---|
btree | -A -a -f -m -N -O -o -q |
bestmx | -a -q |
dbm | -A -a -f -m -N -O -o -q |
dequote | -a -s |
hash | -A -a -f -m -N -O -o -q |
hesiod | -a -m -o -q |
host | -a -m -q |
implicit | -q |
ldapx | -a -f -m -N -O -o -q |
netinfo | -a -k -m -q -v |
nisplus | -a -f -k -m -o -q -v -z |
nis | -a -f -m -o -q |
null | |
program | -a -m -o -q |
sequence | |
stab | -q |
switch | -q |
text | -a -f -k -m -o -q -v -z |
userdb | -a -f -m -q |
user | -a -m -q -v |
Some classes of databases use special switches that are not available to the broad class of databases. Others redefine the meaning of some switches. These special switches are shown in Table 33.6. Future versions of sendmail may be changed in such a way that it may be possible to have only one list.
Switch | Class or Vendor | Description |
---|---|---|
-b | ldapx | Base from which to begin the search |
-d | Sun | Use domain wide information (see Section 38.16, "K Command's -d switch") |
-h | ldapx | Host that serves this network database |
-l | ldapx | Time limit to timeout connection |
-n | ldapx | Retrieve attribute names only, not values |
-p | ldapx | Port to use when connecting to host |
-R | ldapx | Don't auto chase referrals |
-s | ldapx | Search scope of "base," "one," or "sub" |
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, in automating for example, such duplicates are necessary.
In such instances, the -A
switch can be used with the
AliasFile
(A
) option (see Section 34.8.1, AliasFile (A))
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 Section 24.4.4, "Duplicate Entries and Automation".
The -A
database switch is useful only with alias files, because
those are the only files that sendmail rebuilds on its own.
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 Section 33.4.1, "Specify a Default with $:".
Ordinarily, sendmail will normalize a key to lowercase
before looking it up in the database. If the keys in the database
are case-sensitive ("TEX" is considered different from "tex," for example),
the -f
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).
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
class;
see Section 33.8.18), you need to specify which column is the
key and which is the value.
For nisplus
and netinfo
maps, the -k
switch specifies the
name (text) of the desired column.
When the -k
switch specifies which column is the key, its absence
defaults to 0 for the text
class and to
the name of the zeroth column for the nisplus
class.
Note that the numbered columns are indexed beginning with 0 for the first
and 1 for the second. See also -v
(see Section 33.3.4.11)
for the value's column (text
and nisplus
only)
and -z
(see Section 33.3.4.12) for the column delimiter
(text
only).
Ordinarily, a successful lookup in a database or map causes the
key to be replaced by its value. When the intention is to merely verify
that the key exists (not replace it), the -m
switch
can be used to suppress replacement.
For example, the values that are returned from the hosts.byname
NIS map are not generally useful (they contain multiple hostnames).
In looking up a key in this map (with $(
and $)
;
see Section 33.4), the -m
switch prevents
those multiple names from wrongly replacing the single hostname
in the key. Note that the -a
(see Section 33.3.4.2)
can still be used to append a suffix to a successful lookup.
Also, the $:
default
(see Section 33.4.1)
is still used if the lookup fails.
If a database was created with makemap's -N
switch
(see Section 33.2.1.3) to include
the terminating zero byte with each key, this K
configuration
command -N
switch may be specified to force all lookups to
also include a zero byte. Note that -N
is not needed for the
nis
class and, if included, is ignored. See also -O
below.
If neither -N
nor -O
is specified,
sendmail uses an adaptive algorithm to decide
whether or not to look for the terminating zero byte.
The algorithm starts by accepting either. If the first key looked up
is found to end with a terminating zero byte, the algorithm
will thereafter look only for keys with terminating zero bytes.
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
terminating zero bytes.
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 never try to match at all,
thus causing all lookups to appear to fail.
Ordinarily, sendmail will complain if a database file cannot
be opened for reading. If the presence of a database file is optional
(as it may 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.
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 to end up 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.
The dequote
class (see Section 33.8.4) 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 before dequoting. Therefore, the above conversion becomes the following:
"a b" becomes a+b
The -s
switch is only of use with the dequote
class.
Note that the lpadx
class
uses the -s
switch differently (see Table 33.6
in Section 33.3.4, "The switches").
The manner in which the key and its value are visually displayed
in flat, sequential, text files and certain network services, may not
be directly suitable for use in maps.
A text
class file, for example /etc/hosts,
may 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
and netinfo
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
class and to
the last named column for the nisplus
class.
Note that text columns are indexed beginning with 0 for the first
and 1 for the second. See also -k
(see Section 33.3.4.4)
for the key's column and -z
(see Section 33.3.4.12) for
the column delimiter.
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 uid to login name
The default is whitespace for the text
class. It is
a comma for the netinfo
class.