<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 10 2009 by texi2html 1.78 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Specification of the Exim Mail Transfer Agent: 20. The manualroute router</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 20. The manualroute router">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 20. The manualroute router">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.78">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="The-manualroute-router"></a>
<a name="SEC194"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_19.html#SEC193" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC195" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_19.html#SEC193" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 20. The manualroute router </h1>
<p>The <code>manualroute</code> 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, <code>manualroute</code> 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.
</p>
<p>The <code>manualroute</code> 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 <code>transport</code> option must specify a transport, unless the router is
being used purely for verification (see <code>verify_only</code>).
</p>
<a name="IDX1817"></a>
<p>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 <code>$host</code> as a single
text string.
</p>
<p>The list of routing rules can be provided as an inline string in
<code>route_list</code>, or the data can be obtained by looking up the domain in a file
or database by setting <code>route_data</code>. Only one of these settings may appear in
any one instance of <code>manualroute</code>. The format of routing rules is described
below, following the list of private options.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC195">20.1 Private options for manualroute</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC196">20.2 Routing rules in route_list</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC197">20.3 Routing rules in route_data</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC198">20.4 Format of the list of hosts</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC199">20.5 Format of one host item</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC200">20.6 How the list of hosts is used</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC201">20.7 How the options are used</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC202">20.8 Manualroute examples</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Private-options-for-manualroute"></a>
<a name="SEC195"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC194" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC196" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.1 Private options for manualroute </h2>
<p>The private options for the <code>manualroute</code> router are as follows:
</p>
<a name="IDX1818"></a>
<table>
<tr><td>
<p><code>host_all_ignored</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>defer</em>
</p></td></tr>
</table>
<p>See <code>host_find_failed</code>.
</p>
<a name="IDX1819"></a>
<table>
<tr><td>
<p><code>host_find_failed</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>freeze</em>
</p></td></tr>
</table>
<p>This option controls what happens when <code>manualroute</code> tries to find an IP
address for a host, and the host does not exist. The option can be set to one
of the following values:
</p>
<table><tr><td> </td><td><pre class="example">decline
defer
fail
freeze
ignore
pass
</pre></td></tr></table>
<p>The default ("freeze") 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
<code>pass_router</code>),
<a name="IDX1820"></a>
overriding <code>no_more</code>, whereas the latter passes the address to the next
router only if <code>more</code> is true.
</p>
<p>The value "ignore" causes Exim to completely ignore a host whose IP address
cannot be found. If all the hosts in the list are ignored, the behaviour is
controlled by the <code>host_all_ignored</code> option. This takes the same values
as <code>host_find_failed</code>, except that it cannot be set to "ignore".
</p>
<p>The <code>host_find_failed</code> option applies only to a definite "does not exist"
state; if a host lookup gets a temporary error, delivery is deferred unless the
generic <code>pass_on_timeout</code> option is set.
</p>
<a name="IDX1821"></a>
<table>
<tr><td>
<p><code>hosts_randomize</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<a name="IDX1822"></a>
<a name="IDX1823"></a>
<p>If this option is set, the order of the items in a host list in a routing rule
is randomized each time the list is used, unless an option in the routing rule
overrides (see below). Randomizing the order of a host list can be used to do
crude load sharing. However, if more than one mail address is routed by the
same router to the same host list, the host lists are considered to be the same
(even though they may be randomized into different orders) for the purpose of
deciding whether to batch the deliveries into a single SMTP transaction.
</p>
<p>When <code>hosts_randomize</code> is true, a host list may be split
into groups whose order is separately randomized. This makes it possible to
set up MX-like behaviour. The boundaries between groups are indicated by an
item that is just ‘<samp>+</samp>’ in the host list. For example:
</p>
<table><tr><td> </td><td><pre class="example">route_list = * host1:host2:host3:+:host4:host5
</pre></td></tr></table>
<p>The order of the first three hosts and the order of the last two hosts is
randomized for each use, but the first three always end up before the last two.
If <code>hosts_randomize</code> is not set, a ‘<samp>+</samp>’ item in the list is ignored. If a
randomized host list is passed to an <code>smtp</code> transport that also has
<code>hosts_randomize set</code>, the list is not re-randomized.
</p>
<a name="IDX1824"></a>
<table>
<tr><td>
<p><code>route_data</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>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:
</p>
<table><tr><td> </td><td><pre class="example">route_data = ${lookup{$domain}dbm{/etc/routes}}
</pre></td></tr></table>
<p>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.
</p>
<a name="IDX1825"></a>
<table>
<tr><td>
<p><code>route_list</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>string list</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>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.
</p>
<a name="IDX1826"></a>
<table>
<tr><td>
<p><code>same_domain_copy_routing</code></p></td><td><p> Use: <em>manualroute</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<a name="IDX1827"></a>
<p>Addresses with the same domain are normally routed by the <code>manualroute</code>
router to the same list of hosts. However, this cannot be presumed, because the
router options and preconditions 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.
</p>
<p>If you are running mailing lists with large numbers of subscribers at the same
domain, and you are using a <code>manualroute</code> router which is independent of the
local part, you can set <code>same_domain_copy_routing</code> to bypass repeated DNS
lookups for identical domains in one message. In this case, when
<code>manualroute</code> 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 <code>headers_add</code> and <code>headers_remove</code> are unset.
</p>
<hr size="6">
<a name="Routing-rules-in-route_005flist"></a>
<a name="SEC196"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC195" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC197" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.2 Routing rules in route_list </h2>
<p>The value of <code>route_list</code> 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. Alternatively, the list separator can be changed as
described (for colon-separated lists) in section <a href="spec_6.html#SEC75">List construction</a>.
Empty rules are ignored. The format of each rule is
</p>
<table><tr><td> </td><td><pre class="display"><domain pattern> <list of hosts> <options>
</pre></td></tr></table>
<p>The following example contains two rules, each with a simple domain pattern and
no options:
</p>
<table><tr><td> </td><td><pre class="example">route_list = \
dict.ref.example mail-1.ref.example:mail-2.ref.example ; \
thes.ref.example mail-3.ref.example:mail-4.ref.example
</pre></td></tr></table>
<p>The three parts of a rule are separated by white space. The pattern and the
list of hosts can be enclosed in quotes if necessary, and if they are, the
usual quoting rules apply. Each rule in a <code>route_list</code> 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
<a href="spec_10.html#SEC123">Domain lists</a>),
except that it may not be the name of an interpolated 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 <code>route_list</code>).
</p>
<p>The rules in <code>route_list</code> are searched in order until one of the patterns
matches the domain that is being routed. The list of hosts and then options are
then used as described below. If there is no match, the router declines. When
<code>route_list</code> is set, <code>route_data</code> must not be set.
</p>
<hr size="6">
<a name="Routing-rules-in-route_005fdata"></a>
<a name="SEC197"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC196" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC198" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.3 Routing rules in route_data </h2>
<p>The use of <code>route_list</code> 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 <code>route_data</code> option instead.
The value of <code>route_data</code> is a list of hosts, followed by (optional) options.
Most commonly, <code>route_data</code> is set as a string that contains an
expansion lookup. For example, suppose we place two routing rules in a file
like this:
</p>
<table><tr><td> </td><td><pre class="example">dict.ref.example: mail-1.ref.example:mail-2.ref.example
thes.ref.example: mail-3.ref.example:mail-4.ref.example
</pre></td></tr></table>
<p>This data can be accessed by setting
</p>
<table><tr><td> </td><td><pre class="example">route_data = ${lookup{$domain}lsearch{/the/file/name}}
</pre></td></tr></table>
<p>Failure of the lookup results in an empty string, causing the router to
decline. However, you do not have to use a lookup in <code>route_data</code>. The only
requirement is that the result of expanding the string is a list of hosts,
possibly followed by options, separated by white space. The list of hosts must
be enclosed in quotes if it contains white space.
</p>
<hr size="6">
<a name="Format-of-the-list-of-hosts"></a>
<a name="SEC198"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC197" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC199" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.4 Format of the list of hosts </h2>
<p>A list of hosts, whether obtained via <code>route_data</code> or <code>route_list</code>, 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 names
and/or IP addresses, optionally also including ports. The format of each item
in the list is described in the next section. The list separator can be changed
as described in section <a href="spec_6.html#SEC75">List construction</a>.
</p>
<p>If the list of hosts was obtained from a <code>route_list</code> item, the following
variables are set during its expansion:
</p>
<ul class="toc">
<li>
<a name="IDX1828"></a>
If the domain was matched against a regular expression, the numeric variables
<code>$1</code>, <code>$2</code>, etc. may be set. For example:
<table><tr><td> </td><td><pre class="example">route_list = ^domain(\d+) host-$1.text.example
</pre></td></tr></table>
</li><li>
<code>$0</code> is always set to the entire domain.
</li><li>
<code>$1</code> is also set when partial matching is done in a file lookup.
</li><li>
<a name="IDX1829"></a>
If the pattern that matched the domain was a lookup item, the data that was
looked up is available in the expansion variable <code>$value</code>. For example:
<table><tr><td> </td><td><pre class="example">route_list = lsearch;;/some/file.routes $value
</pre></td></tr></table>
</li></ul>
<p>Note the doubling of the semicolon in the pattern that is necessary because
semicolon is the default route list separator.
</p>
<hr size="6">
<a name="Format-of-one-host-item"></a>
<a name="SEC199"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC198" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC200" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.5 Format of one host item </h2>
<p>Each item in the list of hosts is either a host name or an IP address,
optionally with an attached port number. When no port is given, an IP address
is not enclosed in brackets. When a port is specified, it overrides the port
specification on the transport. The port is separated from the name or address
by a colon. This leads to some complications:
</p>
<ul class="toc">
<li>
Because colon is the default separator for the list of hosts, either
the colon that specifies a port must be doubled, or the list separator must
be changed. The following two examples have the same effect:
<table><tr><td> </td><td><pre class="example">route_list = * "host1.tld::1225 : host2.tld::1226"
route_list = * "<+ host1.tld:1225 + host2.tld:1226"
</pre></td></tr></table>
</li><li>
When IPv6 addresses are involved, it gets worse, because they contain
colons of their own. To make this case easier, it is permitted to
enclose an IP address (either v4 or v6) in square brackets if a port
number follows. For example:
<table><tr><td> </td><td><pre class="example">route_list = * "</ [10.1.1.1]:1225 / [::1]:1226"
</pre></td></tr></table>
</li></ul>
<hr size="6">
<a name="How-the-list-of-hosts-is-used"></a>
<a name="SEC200"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC199" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC201" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.6 How the list of hosts is used </h2>
<p>When an address is routed to an <code>smtp</code> transport by <code>manualroute</code>, each of
the hosts is tried, in the order specified, when carrying out the SMTP
delivery. However, the order can be changed by setting the <code>hosts_randomize</code>
option, either on the router (see section <a href="#SEC195">Private options for manualroute</a> above), or on the
transport.
</p>
<p>Hosts may be listed by name or by IP address. An unadorned name in the list of
hosts is interpreted as a host name. A name that is followed by ‘<samp>/MX</samp>’ is
interpreted as an indirection to a sublist of hosts obtained by looking up MX
records in the DNS. For example:
</p>
<table><tr><td> </td><td><pre class="example">route_list = * x.y.z:p.q.r/MX:e.f.g
</pre></td></tr></table>
<p>If this feature is used with a port specifier, the port must come last. For
example:
</p>
<table><tr><td> </td><td><pre class="example">route_list = * dom1.tld/mx::1225
</pre></td></tr></table>
<p>If the <code>hosts_randomize</code> option is set, the order of the items in the list is
randomized before any lookups are done. Exim then scans the list; for any name
that is not followed by ‘<samp>/MX</samp>’ it looks up an IP address. If this turns out to
be an interface on the local host and the item is not the first in the list,
Exim discards it and any subsequent items. If it is the first item, what
happens is controlled by the
<a name="IDX1830"></a>
<code>self</code> option of the router.
</p>
<p>A name on the list that is followed by ‘<samp>/MX</samp>’ is replaced with the list of
hosts obtained by looking up MX records for the name. This is always a DNS
lookup; the <code>bydns</code> and <code>byname</code> options (see section <a href="#SEC201">How the options are used</a>
below) are not relevant here. The order of these hosts is determined by the
preference values in the MX records, according to the usual rules. Because
randomizing happens before the MX lookup, it does not affect the order that is
defined by MX preferences.
</p>
<p>If the local host is present in the sublist obtained from MX records, but is
not the most preferred host in that list, it and any equally or less
preferred hosts are removed before the sublist is inserted into the main list.
</p>
<p>If the local host is the most preferred host in the MX list, what happens
depends on where in the original list of hosts the ‘<samp>/MX</samp>’ item appears. If it
is not the first item (that is, there are previous hosts in the main list),
Exim discards this name and any subsequent items in the main list.
</p>
<p>If the MX item is first in the list of hosts, and the local host is the
most preferred host, what happens is controlled by the <code>self</code> option of the
router.
</p>
<p>DNS failures when lookup up the MX records are treated in the same way as DNS
failures when looking up IP addresses: <code>pass_on_timeout</code> and
<code>host_find_failed</code> are used when relevant.
</p>
<p>The generic <code>ignore_target_hosts</code> option applies to all hosts in the list,
whether obtained from an MX lookup or not.
</p>
<hr size="6">
<a name="How-the-options-are-used"></a>
<a name="SEC201"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC200" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC202" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.7 How the options are used </h2>
<p>The options are a sequence of words; in practice no more than three are ever
present. One of the words can be the name of a transport; this overrides the
<code>transport</code> option on the router for this particular routing rule only. The
other words (if present) control randomization of the list of hosts on a
per-rule basis, and how the IP addresses of the hosts are to be found when
routing to a remote transport. These options are as follows:
</p>
<ul class="toc">
<li>
<code>randomize</code>: randomize the order of the hosts in this list, overriding the
setting of <code>hosts_randomize</code> for this routing rule only.
</li><li>
<code>no_randomize</code>: do not randomize the order of the hosts in this list,
overriding the setting of <code>hosts_randomize</code> for this routing rule only.
</li><li>
<code>byname</code>: use <code>getipnodebyname()</code> (<code>gethostbyname()</code> on older systems) to
find IP addresses. This function may ultimately cause a DNS lookup, but it may
also look in ‘<tt>/etc/hosts</tt>’ or other sources of information.
</li><li>
<code>bydns</code>: look up address records for the hosts directly in the DNS; fail if
no address records are found. If there is a temporary DNS error (such as a
timeout), delivery is deferred.
</li></ul>
<p>For example:
</p>
<table><tr><td> </td><td><pre class="example">route_list = domain1 host1:host2:host3 randomize bydns;\
domain2 host4:host5
</pre></td></tr></table>
<p>If neither <code>byname</code> nor <code>bydns</code> is given, Exim behaves as follows: First, a
DNS lookup is done. If this yields anything other than HOST_NOT_FOUND, that
result is used. Otherwise, Exim goes on to try a call to <code>getipnodebyname()</code>
or <code>gethostbyname()</code>, and the result of the lookup is the result of that
call.
</p>
<p><strong>Warning</strong>: It has been discovered that on some systems, if a DNS lookup
called via <code>getipnodebyname()</code> times out, HOST_NOT_FOUND is returned
instead of TRY_AGAIN. That is why the default action is to try a DNS
lookup first. Only if that gives a definite "no such host" is the local
function called.
</p>
<p>If no IP address for a host can be found, what happens is controlled by the
<code>host_find_failed</code> option.
</p>
<a name="IDX1831"></a>
<p>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 <code>$host</code> variable.
</p>
<hr size="6">
<a name="Manualroute-examples"></a>
<a name="SEC202"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC201" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC194" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 20.8 Manualroute examples </h2>
<p>In some of the examples that follow, the presence of the <code>remote_smtp</code>
transport, as defined in the default configuration file, is assumed:
</p>
<ul class="toc">
<li>
<a name="IDX1832"></a>
The <code>manualroute</code> router can be used to forward all external mail to a
<em>smart host</em>. If you have set up, in the main part of the configuration, a
named domain list that contains your local domains, for example:
<table><tr><td> </td><td><pre class="example">domainlist local_domains = my.domain.example
</pre></td></tr></table>
<p>You can arrange for all other domains to be routed to a smart host by making
your first router something like this:
</p>
<table><tr><td> </td><td><pre class="example">smart_route:
driver = manualroute
domains = !+local_domains
transport = remote_smtp
route_list = * smarthost.ref.example
</pre></td></tr></table>
<p>This causes all non-local addresses to be sent to the single host
<em>smarthost.ref.example</em>. If a colon-separated list of smart hosts is given,
they are tried in order
(but you can use <code>hosts_randomize</code> to vary the order each time).
Another way of configuring the same thing is this:
</p>
<table><tr><td> </td><td><pre class="example">smart_route:
driver = manualroute
transport = remote_smtp
route_list = !+local_domains smarthost.ref.example
</pre></td></tr></table>
<p>There is no difference in behaviour between these two routers as they stand.
However, they behave differently if <code>no_more</code> is added to them. In the first
example, the router is skipped if the domain does not match the <code>domains</code>
precondition; the following router is always tried. If the router runs, it
always matches the domain and so can never decline. Therefore, <code>no_more</code>
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
<code>no_more</code> would prevent subsequent routers from running.
</p>
</li><li>
<a name="IDX1833"></a>
A <em>mail hub</em> 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
<code>manualroute</code> 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 <code>route_list</code> option, but for a larger number a file or database
lookup is easier to manage.
<p>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:
</p>
<table><tr><td> </td><td><pre class="example">hub_route:
driver = manualroute
transport = remote_smtp
route_list = *.rhodes.tvs.example $domain
</pre></td></tr></table>
<p>This configuration routes domains that match ‘<samp>*.rhodes.tvs.example</samp>’ 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:
</p>
<table><tr><td> </td><td><pre class="example">through_firewall:
driver = manualroute
transport = remote_smtp
route_data = ${lookup {$domain} cdb {/internal/host/routes}}
</pre></td></tr></table>
<p>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.
</p>
</li><li>
<a name="IDX1834"></a>
<a name="IDX1835"></a>
You can use <code>manualroute</code> 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:
<table><tr><td> </td><td><pre class="example">save_in_file:
driver = manualroute
transport = batchsmtp_appendfile
route_list = saved.domain.example
</pre></td></tr></table>
<p>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:
</p>
<table><tr><td> </td><td><pre class="example">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
</pre></td></tr></table>
<a name="IDX1836"></a>
<a name="IDX1837"></a>
<p>The first of these just passes the domain in the <code>$host</code> variable, which
doesn't achieve much (since it is also in <code>$domain</code>), 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.
</p>
</li><li>
<a name="IDX1838"></a>
Routing mail directly to UUCP software is a specific case of the use of
<code>manualroute</code> in a gateway to another mail environment. This is an example of
one way it can be done:
<table><tr><td> </td><td><pre class="example"># 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}}
</pre></td></tr></table>
<p>The file ‘<tt>/usr/local/exim/uucphosts</tt>’ contains entries like
</p>
<table><tr><td> </td><td><pre class="example">darksite.ethereal.example: darksite.UUCP
</pre></td></tr></table>
<p>It can be set up more simply without adding and removing ".UUCP" but this way
makes clear the distinction between the domain name
<em>darksite.ethereal.example</em> and the UUCP host name <em>darksite</em>.
</p></li></ul>
<a name="IDX1839"></a>
<a name="IDX1840"></a>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC194" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_21.html#SEC203" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[<a href="spec_55.html#SEC493" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="spec_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>September, 10 2009</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78</i></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a4080654d049ad31b216b761b9173c1f
>
files
>
122
