Exim can be configured to look up data in files or databases in a number of different circumstances. This chapter discusses some of the common features of the data lookup facilities; particular cases are covered in more detail in subsequent chapters.
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:
`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.
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, then `*' is looked up.
There has been some confusion over the way `lsearch' lookups work. The fact that the file is searched linearly does not make this kind of search any different from the other single-key lookup types. Its implementation is just one of several `black boxes' which, given a key, yield a data value. Thus the keys in the file 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'.
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 possible to request partial matching. In this case, information in the file that has a key starting with `*.' matches any domain that ends with the components that follow the fullstop. For example, if a key in a DBM file is
*.dates.fict.book
then this matches the keys `2001.dates.fict.book' and `1984.dates.fict.book' when partial matching is requested. It also matches the key `dates.fict.book', if that key does not itself appear in the file.
Partial matching is requested by adding the string `partial-' to the front of the name of a search type, for example, `partial-dbm'. The key is first looked up verbatim; if that fails, then `*.' is added to the start of the 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 key, one-by-one, and `*.' added on the front, until there are fewer than two non-* components left.
In fact, the minimum number of non-* components 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 key. 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 `*@', then the search for a default that that causes happens after all partial lookups have failed. If `partial0' is specified, adding `*' to the search type has no effect, because the `*' key is already included in the sequence of partial lookups.
Exim caches the most recent lookup result on a per-file basis for single-key lookup types, and keeps the relevant files open. For query-style lookups, a single 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.
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 include files and libraries needed to compile Exim with LDAP support can be obtained from
`http://www.umich.edu/~dirsvcs/ldap/index.html'
An LDAP query takes the form of a URL as defined in the Internet Draft `draft-ietf-asid-ldapv3-url-04.txt'. For example, in the configuration of an `aliasfile' director one might have these settings:
search_type = ldap
query = "ldap:///o=University%20of%20Cambridge,c=UK\
?mailbox?sub?(cn=$local_part)"
The `ldap' lookup type generates an error if more than one value is obtained from the lookup, but `ldapm' permits this case, and if multiple values are returned, they are separated by newline characters.
Go to the first, previous, next, last section, table of contents.