Go to the first, previous, next, last section, table of contents.


The domainlist router

The `domainlist' router compares a list of domain patterns with the domain it is trying to route. When a match is found, the information associated with the pattern can specify several different actions:

The list of patterns can be specified as an option string, or looked up in a file or database, or both; at least one of `route_list', `route_file', `route_query', or `route_queries' must be set. A transport must be set when the routing is completed by this router, that is, when the address is not passed on to subsequent routers, unless `verify_only' is set. Each routing entry can specify its own transport, with the generic `transport' option acting as a default for those that don't.

host_find_failed (domainlist) option

Option: host_find_failed
Type: string
Default: "freeze"

This option controls what happens if a host which `domainlist' tries to look up because an address has been specifically routed to it does not exist. The option can be set to one of


freeze
defer
fail_soft
fail_hard

The default assumes that this state is a serious configuration error. The difference between `fail_soft' and `fail_hard' is that the former causes the address to be passed to the next router, overriding `no_more', while the latter does not, causing the address to fail completely. This option applies only to a definite `does not exist' state; if a host lookup gets a temporary error, delivery is deferred unless the generic `pass_on_timeout' option is set.

modemask (domainlist) option

Option: modemask
Type: "octal
Default: integer" 022

This specifies mode bits which must not be set for the route file. If they are set, the director fails and the message is frozen.

owners (domainlist) option

Option: owners
Type: string-list
Default: unset

This specifies a list of permitted owners for the route file. If it is unset, no check on the ownership is done. If the file is not owned by a user in the list, the router fails and the message is frozen.

owngroups (domainlist) option

Option: owngroups
Type: string-list
Default: unset

This specifies a list of permitted groups for the route file. If it is unset, no check on the file's group is done. If the file's group is not in the list, the router fails and the message is frozen.

qualify_single (domainlist) option

Option: qualify_single
Type: boolean
Default: true

For any domain that is looked up in the DNS, the resolver option that causes it to qualify single-component names with the default domain (RES_DEFNAMES) is set. For example, on a machine called `dictionary.ref.book', looking up the domain `thesaurus' would cause the name `thesaurus.ref.book' to be looked up.

route_file (domainlist) option

Option: route_file
Type: string
Default: unset

If this option is set, `search_type' must be set to one of the single-key lookup types, and `route_query' must not be set. See chapter "File and database lookups" for details of file and database lookups. The domain being routed is used as the key for the lookup, and the resulting data must be a list of routing rules in the form described below. The file name is expanded before use.

route_list (domainlist) option

Option: route_list
Type: "string-list,
Default: semicolon-separated" unset

This string is a list of routing rules, in the form defined below. Note that, unlike most string lists, the items are separated by semicolons. This is so that they may contain colon-separated host lists.

route_queries (domainlist) option

Option: route_queries
Type: string
Default: unset

This option is an alternative to `route_query'; the two options are mutually exclusive. The difference is that `route_queries' contains a colon-separated list of queries, which are tried in order until one succeeds or defers, or all fail. Any colon characters actually required in an individual query must be doubled, in order that they not be treated as query separators.

route_query (domainlist) option

Option: route_query
Type: string
Default: unset

If this option is set, `search_type' must be set to a query-style lookup type, and `route_file' must not be set. See chapter "File and database lookups" for details of file and database lookups. The query is expanded before use, and the expansion variable `$domain' contains the domain being routed. The data returned from the lookup must be a list of routing rules, in the form described below.

search_parents (domainlist) option

Option: search_parents
Type: boolean
Default: false

For any domain that is looked up in the DNS, the resolver option that causes it to search parent domains (RES_DNSRCH) is set if this option is true. This is different from the `qualify_single' option in that it applies to domains containing dots. For example, on a machine in the `fict.book' domain, when looking up `teaparty.wonderland' initially fails, the resolver automatically tries `teaparty.wonderland.fict.book' if this option is set.

search_type (domainlist) option

Option: search_type
Type: string
Default: unset

This option is mandatory when `route_file', `route_query', or `route_queries' is specified. It must be set to one of the supported search types (for example, `lsearch'). See chapter "File and database lookups".

For single-file lookups, the name may be preceded by `partial-', indicating a simple wildcard file lookup that works as follows:

  1. Exim first tries to look up the domain exactly as given.
  2. If that fails, it adds `*.' on the front of the domain, and looks that up.
  3. If that fails, it replaces the first component of the domain with `*' and tries that, and continues chopping off components in this way until either the lookup succeeds, or there are fewer than two non-* components left.

Thus, for example, if you put an entry keyed by `*.austen.fict.film' in your database, that entry will be used for

  1. `austen.fict.film' by rule (b) above, having failed on rule (a). (If you are worried about the resource waste implied by this, you can always add an entry for `austen.fict.film' as well.)
  2. `emma.austen.fict.film' at the first attempt in rule (c), having failed on rules (a) and (b).

A domain such as `jane.fict.film' will fail, having tried 3 lookups: `jane.fict.film', `*.jane.fict.film', `*.fict.film', but it won't waste effort looking up `*.film' because that has only one non-* component. In fact, the minimum number of components can be altered by including a number immediately before the hyphen. For example, `partial4-dbm' specifies a minimum of four non-* components.

Routing rules

Routing rules specified in `route_list' are scanned before `route_file', `route_query' or `route_queries' are used. The contents of `route_list' is a string consisting of a sequence of routing rules, separated by semicolons. If a semicolon is needed in a rule, it can be entered as two semicolons. Empty rules are ignored. The format of each rule is


<domain pattern>  <host-list>  <options>

The following example contains a simple domain pattern and just one rule:


route_list = "dict.ref.book mail-1.ref.book:mail-2.ref.book byname"

The three parts of a rule are separated by white space. Each rule in a `route_list' must start with a single domain pattern, which is the only mandatory item in the rule. The pattern is in the same format as one item in a domain list (see section "Domain lists" in chapter "The Exim configuration file"), that is, it may be wildcarded or a regular expression, or a file or database lookup (with semicolons doubled, because of the use of semicolon as a separator in a `route_list'). The rules in `route_list' are searched in order until one of the patterns matches the domain that is being routed. The host list and options are then used as described below.

If no rule in `route_list' matches the domain, it is used as the key for a lookup of the type specified by `search_type', using `route_file', `route_query', or `route_queries', as appropriate. The data returned from a successful lookup must be a string containing a host list and options, separated by white space. For example, a line in a linearly searched route file might be:


dict.ref.book:  mail-1.ref.book:mail-2.ref.book  byname

Note that there are two different uses of the colon character in this line. The first one is the delimiter of the key in the file, while the second is the normal list delimiter in the host list, which in this example consists of two host names. As both the host list and the options are not compulsory in a rule, the data returned from a lookup can legitimately be an empty string in some circumstances (see Application of routing rules below).

If the domain does not match anything in `route_list' and looking it up using `route_file', `route_query' or `route_queries' also fails, then the router cannot handle the address, and it gets passed on to the next router, unless `no_more' is set.

Host list format

If a host list is present in the rule which matches the domain, it is expanded before use. If the pattern that matched the domain was a lookup item, the data that was looked up is available in the expansion variable `$value'.

The result of the expansion must be a colon-separated list of host names and/or IP addresses. Some string expansion items may contain white space, and if this is the case, the host list must be enclosed in single or double quotes, because otherwise white space terminates it. The numeric expansion variables are available during host list expansion. These are mainly used when the domain is matched against a regular expression domain pattern in a `route_list' string, but `$1' is also set when partial matching is done in a file lookup, and `$0' is always set to the entire domain.

The value of `$domain' is the original domain for the address. This may differ from `$0' if the address has been processed by a previous `domainlist' router which passed on a different routing domain.

If the expansion of the host list is forced to fail (by using the `fail' item in a conditional construction), the router just fails to handle the address, and (unless `no_more' is set) it gets passed on to the next router. If expansion fails for some other reason, the message is frozen, since this is considered to be a configuration error.

Options format

Options can be present only if there is a host list. They are a sequence of words, but in practice no more than two are ever present. One of the words can be the name of one of the configured transports, and this overrides the `transport' option on the router for this particular routing rule only. The other word (if present) specifies how the IP addresses of the hosts in the host list are to be found:

The `qualify_single' and `search_parents' options apply to any DNS lookups that are done. If no IP address for a host can be found, what happens is controlled by the `host_find_failed' option.

Application of routing rules

When a rule has been found that matches the current domain, either by matching one of the rules in `route_list', or by a successful lookup in `route_file' or using `route_query' or `route_queries', the host list and options are used in a number of different ways, depending on which are present and on whether a transport has been specified.

The various different possibilities for configuring the `domainlist' router make it possible to use it for a number of different routing requirements, as shown in the examples in the next section.

Domainlist examples

In some of the examples that follow, the presence of the `remote_smtp' transport, as defined in the default configuration file, is assumed.


Go to the first, previous, next, last section, table of contents.