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.
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 pass fail
The default assumes that this state is a serious configuration error. The difference between `pass' and `fail' 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.
In earlier versions of Exim fail_soft and fail_hard were used instead of pass and fail. They will remain as synonyms for some time.
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.
Type: boolean
Default: false
If this option is set, the order of the items in a host list in a routing rule is randomized each time it is used. This can be used to do crude load sharing. However, there is a complication when a message has more than one address that is routed by the same rule. Without randomization, each such address ends up with an identical host list, and so they are all eligible for batching and sending in a single SMTP transaction. When the host order is randomized, the addresses won't all end up with the same host list, and so they will not be batched in the same way.
If there are only two hosts in the list, this probably doesn't matter too much, because, on average, 50% of addresses will have them one way round, and 50% the other, so you just get two SMTP calls instead of one, however many addresses there are. With more than two hosts, however, the number of permutations increases very rapidly, leading to very many more SMTP calls being made. The way to solve this problem is to put a single, dummy host in the routing rule, and route the addresses to a special smtp transport, which has hosts, hosts_randomize, and hosts_override set. Now all the addresses can be batched up and sent to the transport together.
Type: octal integer
Default: 022
This specifies mode bits which must not be set for the route file. If they are set, delivery is deferred and the message is frozen.
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, delivery is deferred and the message is frozen.
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, delivery is deferred and the message is frozen.
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.
Type: string, expanded
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 6 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 routing rule, in the form described below. The file name is expanded before use.
Type: string list, semicolon-separated
Default: 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. The list is not expanded as a whole, but host lists within it are expanded during processing.
Type: string, expanded
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.
Type: string, expanded
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 6 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 routing rule, in the form described below.
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.
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 6.
For single-file lookups, the name may be preceded by `partial-', indicating a simple wildcard file lookup that works as follows:
Thus, for example, if you put an entry keyed by `*.austen.fict.film' in your database, that entry will be used for
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 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 7.12), 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, the router declines to handle the address, and it gets passed on to the next router, unless no_more is set.
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 declines 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 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.
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.
In some of the examples that follow, the presence of the remote_smtp transport, as defined in the default configuration file, is assumed.
uucp_bitnet:
driver = domainlist
route_list = *.uucp uugateway.fict.book; \
*.bitnet bngateway.ref.book
The two rules match domains ending in .uucp and .bitnet respectively, and
because no options or transport are specified in either case, the name of the
appropriate gateway domain is taken from the host list and passed to
subsequent routers for further routing. So, for example, mail addressed to
user@faraway.uucp is routed by applying subsequent routers to the domain
uugateway.fict.book to determine where to send it.
If there are two hosts servicing one of these domains and they are not
connected to a single domain name (by MX records for example), you may want to
quote two names in the host list portion of a rule. In this case, you have to
specify one of the byxxx options, to get the names looked up by
domainlist, since it can pass on only a single domain name to other routers.
A transport must also be provided:
uucp:
driver = domainlist
transport = remote_smtp
route_list = \
*.uucp uugate1.fict.book:uugate2.fict.book byname
In this case, no further routers are called.
route_append: driver = domainlist transport = batchsmtp_appendfile route_list = gated.domainthough often a pattern is used to pick up more than one domain. If there are several domains or groups of domains with different transport requirements, different transports can be listed in the routing information:
route_append:
driver = domainlist
route_list = \
*.gated.domain1 $domain batch_appendfile; \
*.gated.domain2 \
${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \
batch_pipe
The first of these just passes the domain in the $host variable, which
doesn't achieve much (since it is also in $domain) but the second does a
file lookup to find a value to pass, causing the router to decline to handle the
address if the lookup fails.
# Transport
uucp:
driver = pipe
user = nobody
command = /usr/local/bin/uux -r - \
${substr_-5:$host}!rmail ${local_part}
return_fail_output = true
# Router uucphost: transport = uucp driver = domainlist route_file = /usr/local/exim/uucphosts search_type = lsearchThe file /usr/local/exim/uucphosts contains entries like
darksite.ethereal.ru: darksite.UUCPIt can be set up more simply without adding and removing `.UUCP' but this way makes clear the distinction between the domain name darksite.ethereal.ru and the UUCP host name darksite.
through_firewall: driver = domainlist transport = remote_smtp route_file = /internal/host/routes search_type = lsearchFor a small number of cases, the routing could be inline, using the route_list option, but for a larger number a file lookup would be easier to manage, and the file containing the internal routing might contain lines like this:
dict.ref.book: mail-1.ref.book:mail-2.ref.book bynameThe DNS would be set up with an MX record for dict.ref.book pointing to the mail hub, which would then then forward mail for dict.ref.book to one of the two specified machines, looking up their addresses using gethostbyname(). If the domain names are in fact the names of the machines to which the mail is to be sent by the mail hub, the configuration can be quite simple. For example,
hub_route: driver = domainlist transport = remote_smtp route_list = *.rhodes.tvs $domain bynameThis configuration routes domains that match `*.rhodes.tvs' by calling gethostbyname() on the domain that matched. A similar approach can be taken if the host name can be obtained from the domain name by simple manipulation that the expansion facilities can handle.
smart_route: driver = domainlist transport = remote_smtp route_list = * smarthost.ref.book bydns_awhich causes all messages containing remote addresses to be sent to the single host smarthost.ref.book, whose address (in this example) is obtained from its DNS address record. If a colon-separated list of smart hosts is given, they are tried in order. A router like this should be the last one in the configuration file, since it will route any domain whatsoever.
Go to the first, previous, next, last section, table of contents.