Exim can be configured to look up data in files or databases in a number of different circumstances (see "Use of data lookups" below). Two different styles of data lookup are implemented:
The code for each lookup type is in a separate source file which is compiled and included in the binary of Exim only if the corresponding compile-time option is set. The default settings in `src/EDITME' are:
LOOKUP_DBM=yes LOOKUP_LSEARCH=yes
which means that only linear searching and DBM lookups are included by default.
The following single-key lookup types are implemented:
baduser: :fail:Empty lines and lines beginning with # are ignored, even if they occur in the middle of an item. This is the traditional textual format of alias files.
`http://www.pobox.com/~djb/cdb.html'The cdb distribution is not needed in order to build Exim with cdb support, as the code for reading cdb files is included directly in Exim itself. However, no means of building or testing cdb files is provided with Exim because these are available within the cdb distribution.
There has been some confusion about the way `lsearch' lookups work, in particular in domain and host lists. An item in one of these lists may be a plain file name, or a file name preceded by a search type, and these behave differently. For a plain file name, for example
local_domains = /etc/local-mail-domains
each line of the file is treated as if it appeared as an item in the list, and negated items, wild cards, and regular expressions may be present. However, if an item is specified as an `lsearch' lookup, for example
local_domains = lsearch;/etc/local-mail-domains
then negated items, wild cards, and regular expressions may not be used, because `lsearch' is an indexed lookup method which, when given a key (the domain in the above example), yields a data value that corresponds to that key. The fact that the file is searched linearly does not make this kind of search any different from the other single-key lookup types, and an `lsearch' file can always be directly converted into one of the other types without change of function. Thus the keys in `lsearch'ed files are literal strings and are not interpreted in any way.
The following query-style lookup types are implemented:
There are three different types of configuration item in which data lookups can be specified:
In a string expansion, all the parameters of the lookup are specified explicitly, while for the other types there is always one implicit key involved. For example, the `local_domains' option contains a list of local domains; when it is being searched there is some domain name that is an implicit key.
This is not a problem for single-key lookups; the relevant file name is specified, and the key is implicit. For example, the list of local domains could be given as
local_domains = dbm;/local/domain/list
However, for query-style lookups the entire query has to be specified, and to do this, some means of including the implicit key is required. The special expansion variable `$key' is provided for this purpose. NIS+ could be used to look up local domains by a setting such as
local_domains = nisplus;[domain=$key],domains.org_dir
In cases where drivers can be configured to do lookups, there are always three alternative configuration options: `file' is used for single-key lookups, using an implicit key, and `query' or `queries' is specified for query-style lookups. In these cases the query is an expanded string, and the implicit key that would be used for `file' is always available as one of the normal expansion variables. The difference between `query' and `queries' is that in the latter case the string is treated as a colon-separated list of queries that are tried in order until one succeeds.
Lookup functions can return temporary error codes if the lookup cannot be completed. (For example, a NIS or LDAP database might be unavailable.) When this occurs in a transport, director, or router, delivery of the message is deferred, as for any other temporary error. In other circumstances Exim may assume the lookup has failed, or may give up altogether. It is not advisable to use a lookup that might defer for critical options such as (to give an extreme example) `local_domains'.
In this context, a `default value' is a value specified by the administrator that is to be used if a lookup fails.
If `*' is added to a single-key lookup type (for example, `lsearch*'), then if the initial lookup fails, the key `*' is looked up in the file to provide a default value. See also the section on partial matching below.
Alternatively, if `*@' is added to a single-key lookup type (for example `dbm*@') then, if the initial lookup fails and the key contains an @ character, a second lookup is done with everything before the last @ replaced by *. This makes it possible to provide per-domain defaults in alias files that include the domains in the keys. If the second lookup fails (or doesn't take place because there is no @ in the key), then `*' is looked up.
The normal operation of a single-key lookup is to search the file for an exact
match with the given key. However, in a number of situations where domains are
being looked up, it is useful to be able to do partial matching. In this case,
information in the file that has a key starting with `*.' is matched by any
domain that ends with the components that follow the full stop. For example, if
a key in a DBM file is
then when partial matching is enabled this is matched by (amongst others)
`2001.dates.fict.book' and `1984.dates.fict.book'. It is also matched by
`dates.fict.book', if that does not appear as a separate key in the file.
Partial matching is implemented by doing a series of separate lookups using
keys constructed by modifying the original subject key. This means that it can
be used with any of the single-key lookup types, provided that the special
partial-matching keys beginning with `*.' are included in the data file. Keys
in the file that do not begin with `*.' are matched only by unmodified
subject keys when partial matching is in use.
Partial matching is requested by adding the string `partial-' to the front of
the name of a single-key lookup type, for example, `partial-dbm'. When this is
done, the subject key is first looked up unmodified; if that fails, then `*.'
is added at the start of the subject key, and it is looked up again. If that
fails, then further lookups are tried with dot-separated components removed
from the start of the subject key, one-by-one, and `*.' added on the front of
what remains.
A minimum number of two non-* components is required. This can be adjusted by
including a number before the hyphen in the search type. For example,
`partial3-lsearch' specifies a minimum of three non-* components in the
modified keys. Omitting the number is equivalent to `partial2-'. If the subject
key is `2250.dates.fict.book' then the following keys are looked up when the
minimum number of non-* components is two:
As soon as one key in the sequence is successfully looked up, the lookup
finishes. If `partial0-' is used, the original key gets shortened right down to
the null string, and the final lookup is for `*' on its own.
If the search type ends in `*' or `*@' (see section
"Default values in single-key lookups" above), then the search for an ultimate default
*.dates.fict.book
2250.dates.fict.book
*.2250.dates.fict.book
*.dates.fict.book
*.fict.book
The use of `*' in lookup partial matching differs from its use as a wildcard in domain lists and the like. Partial matching works only in terms of dot-separated components; a key such as `*fict.book' in a database file is useless, because the asterisk in a partial matching subject key is always followed by a dot.
Exim caches the most recent lookup result on a per-file basis for single-key lookup types, and keeps the relevant files open. In some types of configuration this can lead to many files being kept open for messages with many recipients. To avoid hitting the operating system limit on the number of simultaneously open files, Exim closes the least recently used file when it needs to open more files than its own internal limit, which can be changed via the `lookup_open_max' option. For query-style lookups, a single data cache per lookup type is kept. The files are closed and the caches flushed at strategic points during delivery -- for example, after all directing and routing is complete.
When data from an incoming message is included in a query-style lookup, there is the possibility of special characters in the data messing up the syntax of the query. For example, a NIS+ query that contains
[name=$local_part]
will be broken if the local part happens to contain a closing square bracket. For NIS+, data can be enclosed in double quotes like this:
[name="$local_part"]
but this still leaves the problem of a double quote in the data. The rule for NIS+ is that double quotes must be doubled. Other lookup types have different rules, and to cope with the differing requirements, an expansion operator of the following form is provided:
${quote_<lookup-type>:<string>}
For example, the safest way to write the NIS+ query is
[name="${quote_nisplus:$local_part}"]
See chapter "String expansions" for full coverage of string expansions. The quote operator can be used for all lookup types, but has no effect for single-key lookups, since no quoting is ever needed in their key strings.
NIS+ queries consist of a NIS+ indexed name followed by an optional colon and field name. If this is given, the result of a successful query is the contents of the named field; otherwise the result consists of a concatenation of field-name=field-value pairs, separated by spaces. Empty values and values containing spaces are quoted. For example, the query
[name=mg1456],passwd.org_dir
might return the string
name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" home=/home/mg1456 shell=/bin/bash shadow=""
(split over two lines here to fit on the page), whereas
[name=mg1456],passwd.org_dir:gcos
would just return
Martin Guerre
with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry for the given indexed key. The effect of the `quote_nisplus' expansion operator is to double any quote characters within the text.
The original LDAP implementation came from the University of Michigan; this has become `Open LDAP'. Another implementation comes from Netscape, and Solaris 7 contains inbuilt LDAP support. Unfortunately, though these are all compatible at the lookup function level, their error handling is different. For this reason it is necessary to set a compile-time variable when building Exim with LDAP, to indicate which LDAP library is in use. One of the following should appear in your `Local/Makefile':
LDAP_LIB_TYPE=UMICHIGAN LDAP_LIB_TYPE=NETSCAPE LDAP_LIB_TYPE=SOLARIS7
If LDAP_LIB_TYPE is not set, Exim uses a heuristic to guess which of the University of Michigan or Netscape libraries is in use. It cannot distinguish the Solaris 7 library.
An LDAP query takes the form of a URL as defined in RFC 2255. For example, in the configuration of an `aliasfile' director one might have these settings:
search_type = ldap
query = "ldap:///cn=$local_part,o=University%20of%20Cambridge,\
c=UK?mailbox?base?"
Two levels of quoting are required in LDAP queries, the first for LDAP and the second because the LDAP query is represented as a URL. The `quote_ldap' expansion operator implements the following rules:
The example above does not specify an LDAP server. A server can be specified in a query by starting it with
ldap://<hostname>:<port>/...
If the port (and preceding colon) are omitted, the standard LDAP port (389) is used. When, however, no server is specified in a query, a list of default servers is taken from the `ldap_default_servers' configuration option. This supplies a colon-separated list of servers which are tried in turn until one successfully handles a query, or there is a serious error. Successful handling either returns the requested data, or indicates that it does not exist. Serious errors are syntactical, or multiple values when only a single value is expected. Errors which cause the next server to be tried are connection failures, bind failures, and timeouts.
For each server name in the list, a port number can be given. The standard way of specifing a host and port is to use a colon separator (RFC 1738). Because `ldap_default_servers' is a colon-separated list, such colons have to be doubled. For example
ldap_default_servers = ldap1.example.com::145:ldap2.example.com
If `ldap_default_servers' is unset, then a URL with no server name is passed to the LDAP library with no server name, and the library's default (normally the local host) is used.
The LDP URL syntax provides no way of passing authentication and other control information to the server. To make this possible, the URL in an LDAP query may be preceded by any number of `<name>=<value>' settings, separated by spaces. If a value contains spaces it must be enclosed in double quotes, and when double quotes are used, backslash is interpreted in the usual way inside them. The following names are recognized:
USER set the DN, for authenticating the LDAP bind PASS set the password, likewise SIZE set the limit for the number of entries returned TIME set the maximum waiting time for a query
The values may be given in any order. Here is an example of an LDAP query in an Exim lookup which uses some of these values. This is a single line, folded for ease of reading:
${lookup ldap
{user="cn=manager,o=University of Cambridge,c=UK" pass=secret
ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
{$value}fail}
The encoding of spaces as %20 is a URL thing which should not be done for any of the auxiliary data.
If an LDAP lookup finds an entry with no attributes, it behaves as if the entry did not exist. The `ldap' lookup type generates an error if more than one entry matches the search filter, whereas `ldapm' permits this case. It is possible for multiple values, separated by newlines, to be returned for both `ldap' and `ldapm', but in the former case you know that whatever values are returned all came from a single entry in the directory.
If any MYSQL lookups are used, the `mysql_servers' option must be set to a colon-separated list of slash-separated host, database, user, password, tuples, for example:
mysql_servers = "localhost/users/root/secret:\
otherhost/users/root/othersecret"
For each query, these are tried in order until a connection and a query succeeds. No database need be supplied -- if it is absent, it must be given in the queries. A host may be specified as <name>:<port> but because this is a colon-separated list, the colon has to be doubled. Queries are SQL statements, so an example might be
${lookup mysql{select mailbox from users where id='ph10'}{$value}fail}
If the result of the query contains more than one field, the data for each field in the row is returned, preceded by its name, so the result of
${lookup mysql{select home,name from users where id='ph10'}{$value}}
might be
home=/home/ph10 name="Philip Hazel"
Values containing spaces and empty values are double quoted, with embedded quotes escaped by backslash.
If the result of the query contains just one field, the value is passed back verbatim, without a field name, for example:
Philip Hazel
If the result of the query yields more than one row, it is all concatenated, with a newline between the data for each row.
The `quote_mysql' expansion operator converts newline, tab, carriage return, and backspace to \n, \t, \r, and \b respectively, and the characters '"\%_ are all escaped with backslashes.
Go to the first, previous, next, last section, table of contents.