Exim 4.10 Specification chapter 19

Previous Next Contents (Exim 4.10 Specification)

# 19. The manualroute router

The manualroute router is so-called because it provides a way of manually routing an address according to its domain. It is mainly used when you want to route addresses to remote hosts according to your own rules, bypassing the normal DNS routing that looks up MX records. However, manualroute can also route to local transports, a facility that may be useful if you want to save messages for dial-in hosts in local files.

The manualroute router compares a list of domain patterns with the domain it is trying to route. If there is no match, the router declines. Each pattern has associated with it a list of hosts and some other optional data, which may include a transport. The combination of a pattern and its data is called a ``routing rule''. For patterns that do not have an associated transport, the generic `transport` option must specify a transport, unless the router is being used purely for verification (see `verify_only`).

In the case of verification, matching the domain pattern is sufficient for the router to accept the address. When actually routing an address for delivery, an address that matches a domain pattern is queued for the associated transport. If the transport is not a local one, a host list must be associated with the pattern; IP addresses are looked up for the hosts, and these are passed to the transport along with the mail address. For local transports, a host list is optional. If it is present, it is passed in `$host` as a single text string.

The list of routing rules can be provided as an inline string in `route_list`, or the data can be obtained by looking up the domain in a file or database by setting `route_data`. Only one of these settings may appear in any one instance of manualroute. The format of routing rules is described below, following the list of private options.

## 19.1. Private options for manualroute

The private options for the manualroute router are as follows:

### host_find_failed

Type: string
Default: freeze

This option controls what happens when manualroute tries to find an IP address for a host, and the host does not exist. The option can be set to one of

      decline
      defer
      fail
      freeze
      pass

The default assumes that this state is a serious configuration error. The difference between ``pass'' and ``decline'' is that the former forces the address to be passed to the next router (or the router defined by `pass_router`), overriding `no_more`, whereas the latter passes the address to the next router only if `more` is true.

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.

### hosts_randomize

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 by the router, the addresses won't all end up with the same host list, and so they will not be batched in the same way.

This may be desirable if you want a number of different delivery processes to be used. However, if you do want all addresses that route to the same hosts to be batched together, but still want to use the hosts in a random order, you should not set `hosts_randomize` on this router. Instead, arrange to use a special smtp transport, and set `hosts_randomize` on the transport.

### route_data

Type: string, expanded
Default: unset

If this option is set, it must expand to yield the data part of a routing rule. Typically, the expansion string includes a lookup based on the domain. For example:

      route_data = ${lookup{$domain}dbm{/etc/routes/}}

If the expansion is forced to fail, or the result is an empty string, the router declines. Other kinds of expansion failure cause delivery to be deferred.

### route_list

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.

### same_domain_copy_routing

Type: boolean
Default: false

Addresses with the same domain are normally routed by the manualroute router to the same list of hosts. However, this cannot be presumed, because the router options and pre-conditions may refer to the local part of the address. By default, therefore, Exim routes each address in a message independently. DNS servers run caches, so repeated DNS lookups are not normally expensive, and in any case, personal messages rarely have more than a few recipients.

If you are running mailing lists with large numbers of subscribers at the same domain, and you are using a manualroute router which is independent of the local part, you can set `same_domain_copy_routing` to bypass repeated DNS lookups for identical domains in one message. In this case, when manualroute routes an address to a remote transport, any other unrouted addresses in the message that have the same domain are automatically given the same routing without processing them independently. However, this is only done if `headers_add` and `headers_remove` are unset.

## 19.2. Routing rules in route_list

The value 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 two rules, each with a simple domain pattern and no options:

      route_list = \
        dict.ref.example  mail-1.ref.example:mail-2.ref.example ; \
        thes.ref.example  mail-3.ref.example:mail-4.ref.example

The three parts of a rule are separated by white space. The pattern and host list can be enclosed in quotes if necessary, and if they are, the usual quoting rules apply. 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 10.6), 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 there is no match, the router declines. When `route_list` is set, `route_data` must not be set.

## 19.3. Routing rules in route_data

The use of `route_list` is convenient when there are only a small number of routing rules. For larger numbers, it is easier to use a file or database to hold the routing information, and use the `route_data` option instead. Most commonly, the value of `route_data` is a string that contains an expansion lookup. For example, suppose we place two routing rules in a file like this:

      dict.ref.example:  mail-1.ref.example:mail-2.ref.example
      thes.ref.example:  mail-3.ref.example:mail-4.ref.example

This data can be accessed by setting

      route_data = ${lookup{$domain}lsearch{/the/file/name}}

Failure of the lookup results in an empty string, causing the router to decline. However, you do not have to use a lookup in `route_data`. The only requirement is that the result of expanding the string is a single host list, possibly followed by options, separated by white space. The host list can be enclosed in quotes if necessary.

## 19.4. Host list format

A host list, whether obtained via `route_data` or `route_list`, is always separately expanded before use. If the expansion fails, the router declines. The result of the expansion must be a colon-separated list of host names and/or IP addresses. IP addresses in host lists are not enclosed in brackets.

If the host list was obtained from a `route_list` item, the following variables are set during the expansion of the host list:

- If the domain was matched against a regular expression, the numeric variables `$1`, `$2`, etc. may be set.

- `$0` is always set to the entire domain.

- `$1` is also set when partial matching is done in a file lookup.

- If the pattern that matched the domain was a lookup item, the data that was looked up is available in the expansion variable `$value`.

## 19.5. Options format

Options are a sequence of words, but in practice no more than two are ever present. One of the words can be the name of a transport, 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 named in the host list are to be found when routing to a remote transport:

- `byname`: use gethostbyname() (or getipnodebyname() when available). This is the default way of finding host addresses if no options are given.

- `bydns`: look up address records for the host(s) in the DNS; fail if there are none.

If no IP address for a host can be found, what happens is controlled by the `host_find_failed` option.

When an address is routed to a local transport, IP addresses are not looked up. The host list is passed to the transport in the `$host` variable.

## 19.6. Manualroute examples

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

- The manualroute router can be used to forward all external mail to a smart host. If you have set up, in the main part of the configuration, a named domain list that contains your local domains, for example,

        domainlist local_domains = my.domain.example

  you can arrange for all other domains to be routed to a smart host by making your first router something like this:

        smart_route:
          driver = manualroute
          domains = !+local_domains
          transport = remote_smtp
          route_list = * smarthost.ref.example

  This causes all non-local addresses to be sent to the single host smarthost.ref.example. If a colon-separated list of smart hosts is given, they are tried in order (but you can use `hosts_randomize` to vary the order each time). Another way of configuring the same thing is this:

        smart_route:
          driver = manualroute
          transport = remote_smtp
          route_list = !+local_domains  smarthost.ref.example

  There is no difference in behaviour between these two routers as they stand. However, they behave differently if `no_more` is added to them. In the first example, the router is skipped if the domain does not match the `domains` pre-condition; the following router is always tried. If the router runs, it always matches the domain and so can never decline. Therefore, `no_more` would have no effect. In the second case, the router is never skipped; it always runs. However, if it doesn't match the domain, it declines. In this case `no_more` would prevent subsequent routers from running.

- A mail hub is a host which receives mail for a number of domains via MX records in the DNS and delivers it via its own private routing mechanism. Often the final destinations are behind a firewall, with the mail hub being the one machine that can connect to machines both inside and outside the firewall. The manualroute router is usually used on a mail hub to route incoming messages to the correct hosts. For a small number of domains, the routing can be inline, using the `route_list` option, but for a larger number a file or database lookup is easier to manage.

  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 = manualroute
          transport = remote_smtp
          route_list = *.rhodes.tvs.example  $domain

  This configuration routes domains that match `*.rhodes.tvs.example` to hosts whose names are the same as the mail domains. A similar approach can be taken if the host name can be obtained from the domain name by a string manipulation that the expansion facilities can handle. Otherwise, a lookup based on the domain can be used to find the host:

        through_firewall:
          driver = manualroute
          transport = remote_smtp
          route_data = ${lookup {$domain} cdb {/internal/host/routes}}

  The result of the lookup must be the name or IP address of the host (or hosts) to which the address is to be routed. If the lookup fails, the route data is empty, causing the router to decline. The address then passes to the next router.

- You can use manualroute to deliver messages to pipes or files in batched SMTP format for onward transportation by some other means. This is one way of storing mail for a dial-up host when it is not connected. The route list entry can be as simple as a single domain name in a configuration like this:

        save_in_file:
          driver = manualroute
          transport = batchsmtp_appendfile
          route_list = saved.domain.example

  though 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:

        save_in_file:
          driver = manualroute
          route_list = \
            *.saved.domain1.example  $domain  batch_appendfile; \
            *.saved.domain2.example  \
              ${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.

- Routing mail directly to UUCP software is a specific case of the use of manualroute in a gateway to another mail environment. This is an example of one way it can be done:

        # 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 = manualroute
          route_data = \
            ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}}

  The file /usr/local/exim/uucphosts contains entries like

        darksite.ethereal.example:           darksite.UUCP

  It can be set up more simply without adding and removing ``.UUCP'' but this way makes clear the distinction between the domain name darksite.ethereal.example and the UUCP host name darksite.

Previous Next Contents (Exim 4.10 Specification)