<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><style xmlns="" type="text/css">
div.added { background-color: #ffff99; }
div.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
div.changed { background-color: #99ff99; }
div.off { }
span.added { background-color: #ffff99; }
span.deleted { text-decoration: line-through;
background-color: #FF7F7F; }
span.changed { background-color: #99ff99; }
span.off { }
pre.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] pre.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div.literallayout {
background-color: #E8E8D0;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
div[class=changed] div.literallayout {
background-color: #99ff99;
padding-left: 0.5cm;
padding-top: 5px;
padding-bottom: 5px;
}
</style><title>32. Retry configuration</title><meta name="generator" content="DocBook XSL Stylesheets V1.72.0" /><link rel="start" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="up" href="index.html" title="Specification of the Exim Mail Transfer Agent" /><link rel="prev" href="ch31.html" title="31. Address rewriting" /><link rel="next" href="ch33.html" title="33. SMTP authentication" /></head><body><div class="navheader">
<table width="100%" summary="Navigation header"><tr><td width="20%" align="left"><a accesskey="p" href="ch31.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch33.html">Next</a></td></tr></table></div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a href="index.html#toc0260" id="CHAPretry">32. Retry configuration</a></h2></div>
</div>
</div>
<p>
<a id="IIDretconf1" class="indexterm"></a>
<a id="IIDregconf2" class="indexterm"></a>
The “<span class="quote">retry</span>” section of the runtime configuration file contains a list of
retry rules that control how often Exim tries to deliver messages that cannot
be delivered at the first attempt. If there are no retry rules (the section is
empty or not present), there are no retries. In this situation, temporary
errors are treated as permanent. The default configuration contains a single,
general-purpose retry rule (see section <a href="ch07.html#SECID57" title="7.5 Default retry rule">7.5</a>). The <span><strong class="option">-brt</strong></span> command
line option can be used to test which retry rule will be used for a given
address, domain and error.
</p>
<p>
The most common cause of retries is temporary failure to deliver to a remote
host because the host is down, or inaccessible because of a network problem.
Exim’s retry processing in this case is applied on a per-host (strictly, per IP
address) basis, not on a per-message basis. Thus, if one message has recently
been delayed, delivery of a new message to the same host is not immediately
tried, but waits for the host’s retry time to arrive. If the <span><strong class="option">retry_defer</strong></span>
log selector is set, the message
<a id="id610927" class="indexterm"></a>
“<span class="quote">retry time not reached</span>” is written to the main log whenever a delivery is
skipped for this reason. Section <a href="ch45.html#SECToutSMTPerr" title="45.2 Errors in outgoing SMTP">45.2</a> contains more details of
the handling of errors during remote deliveries.
</p>
<p>
Retry processing applies to routing as well as to delivering, except as covered
in the next paragraph. The retry rules do not distinguish between these
actions. It is not possible, for example, to specify different behaviour for
failures to route the domain <span class="emphasis"><em>snark.fict.example</em></span> and failures to deliver to
the host <span class="emphasis"><em>snark.fict.example</em></span>. I didn’t think anyone would ever need this
added complication, so did not implement it. However, although they share the
same retry rule, the actual retry times for routing and transporting a given
domain are maintained independently.
</p>
<p>
When a delivery is not part of a queue run (typically an immediate delivery on
receipt of a message), the routers are always run, and local deliveries are
always attempted, even if retry times are set for them. This makes for better
behaviour if one particular message is causing problems (for example, causing
quota overflow, or provoking an error in a filter file). If such a delivery
suffers a temporary failure, the retry data is updated as normal, and
subsequent delivery attempts from queue runs occur only when the retry time for
the local address is reached.
</p>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0261" id="SECID157">32.1 Changing retry rules</a></h3></div>
</div>
</div>
<p>
If you change the retry rules in your configuration, you should consider
whether or not to delete the retry data that is stored in Exim’s spool area in
files with names like <em class="filename">db/retry</em>. Deleting any of Exim’s hints files is
always safe; that is why they are called “<span class="quote">hints</span>”.
</p>
<p>
The hints retry data contains suggested retry times based on the previous
rules. In the case of a long-running problem with a remote host, it might
record the fact that the host has timed out. If your new rules increase the
timeout time for such a host, you should definitely remove the old retry data
and let Exim recreate it, based on the new rules. Otherwise Exim might bounce
messages that it should now be retaining.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0262" id="SECID158">32.2 Format of retry rules</a></h3></div>
</div>
</div>
<p>
<a id="id611025" class="indexterm"></a>
Each retry rule occupies one line and consists of three or four parts,
separated by white space: a pattern, an error name, an optional list of sender
addresses, and a list of retry parameters. The pattern and sender lists must be
enclosed in double quotes if they contain white space. The rules are searched
in order until one is found where the pattern, error name, and sender list (if
present) match the failing host or address, the error that occurred, and the
message’s sender, respectively.
</p>
<p>
The pattern is any single item that may appear in an address list (see section
<a href="ch10.html#SECTaddresslist" title="10.19 Address lists">10.19</a>). It is in fact processed as a one-item address list,
which means that it is expanded before being tested against the address that
has been delayed. A negated address list item is permitted. Address
list processing treats a plain domain name as if it were preceded by “<span class="quote">*@</span>”,
which makes it possible for many retry rules to start with just a domain. For
example,
</p>
<pre class="literallayout">lookingglass.fict.example * F,24h,30m;
</pre><p>
provides a rule for any address in the <span class="emphasis"><em>lookingglass.fict.example</em></span> domain,
whereas
</p>
<pre class="literallayout">alice@lookingglass.fict.example * F,24h,30m;
</pre><p>
applies only to temporary failures involving the local part <span><strong class="option">alice</strong></span>.
In practice, almost all rules start with a domain name pattern without a local
part.
</p>
<p>
<a id="id611096" class="indexterm"></a>
<span class="bold"><strong>Warning</strong></span>: If you use a regular expression in a routing rule pattern, it
must match a complete address, not just a domain, because that is how regular
expressions work in address lists.
</p>
<div class="literallayout">
<code class="literal">^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2</code> <span><strong class="option">Wrong</strong></span><br />
<code class="literal">^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2</code> <span><strong class="option">Right</strong></span><br />
</div>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0263" id="SECID159">32.3 Choosing which retry rule to use for address errors</a></h3></div>
</div>
</div>
<p>
When Exim is looking for a retry rule after a routing attempt has failed (for
example, after a DNS timeout), each line in the retry configuration is tested
against the complete address only if <span><strong class="option">retry_use_local_part</strong></span> is set for the
router. Otherwise, only the domain is used, except when matching against a
regular expression, when the local part of the address is replaced with “<span class="quote">*</span>”.
A domain on its own can match a domain pattern, or a pattern that starts with
“<span class="quote">*@</span>”. By default, <span><strong class="option">retry_use_local_part</strong></span> is true for routers where
<span><strong class="option">check_local_user</strong></span> is true, and false for other routers.
</p>
<p>
Similarly, when Exim is looking for a retry rule after a local delivery has
failed (for example, after a mailbox full error), each line in the retry
configuration is tested against the complete address only if
<span><strong class="option">retry_use_local_part</strong></span> is set for the transport (it defaults true for all
local transports).
</p>
<p>
<a id="id611202" class="indexterm"></a>
However, when Exim is looking for a retry rule after a remote delivery attempt
suffers an address error (a 4<span class="emphasis"><em>xx</em></span> SMTP response for a recipient address), the
whole address is always used as the key when searching the retry rules. The
rule that is found is used to create a retry time for the combination of the
failing address and the message’s sender. It is the combination of sender and
recipient that is delayed in subsequent queue runs until its retry time is
reached. You can delay the recipient without regard to the sender by setting
<span><strong class="option">address_retry_include_sender</strong></span> false in the <span><strong class="command">smtp</strong></span> transport but this can
lead to problems with servers that regularly issue 4<span class="emphasis"><em>xx</em></span> responses to RCPT
commands.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0264" id="SECID160">32.4 Choosing which retry rule to use for host and message errors</a></h3></div>
</div>
</div>
<p>
For a temporary error that is not related to an individual address (for
example, a connection timeout), each line in the retry configuration is checked
twice. First, the name of the remote host is used as a domain name (preceded by
“<span class="quote">*@</span>” when matching a regular expression). If this does not match the line,
the domain from the email address is tried in a similar fashion. For example,
suppose the MX records for <span class="emphasis"><em>a.b.c.example</em></span> are
</p>
<pre class="literallayout">a.b.c.example MX 5 x.y.z.example
MX 6 p.q.r.example
MX 7 m.n.o.example
</pre><p>
and the retry rules are
</p>
<pre class="literallayout">p.q.r.example * F,24h,30m;
a.b.c.example * F,4d,45m;
</pre><p>
and a delivery to the host <span class="emphasis"><em>x.y.z.example</em></span> suffers a connection failure. The
first rule matches neither the host nor the domain, so Exim looks at the second
rule. This does not match the host, but it does match the domain, so it is used
to calculate the retry time for the host <span class="emphasis"><em>x.y.z.example</em></span>. Meanwhile, Exim
tries to deliver to <span class="emphasis"><em>p.q.r.example</em></span>. If this also suffers a host error, the
first retry rule is used, because it matches the host.
</p>
<p>
In other words, temporary failures to deliver to host <span class="emphasis"><em>p.q.r.example</em></span> use the
first rule to determine retry times, but for all the other hosts for the domain
<span class="emphasis"><em>a.b.c.example</em></span>, the second rule is used. The second rule is also used if
routing to <span class="emphasis"><em>a.b.c.example</em></span> suffers a temporary failure.
</p>
<p>
<span class="bold"><strong>Note</strong></span>: The host name is used when matching the patterns, not its IP address.
However, if a message is routed directly to an IP address without the use of a
host name, for example, if a <span><strong class="command">manualroute</strong></span> router contains a setting such as:
</p>
<pre class="literallayout">route_list = *.a.example 192.168.34.23
</pre><p>
then the “<span class="quote">host name</span>” that is used when searching for a retry rule is the
textual form of the IP address.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0265" id="SECID161">32.5 Retry rules for specific errors</a></h3></div>
</div>
</div>
<p>
<a id="id611386" class="indexterm"></a>
The second field in a retry rule is the name of a particular error, or an
asterisk, which matches any error. The errors that can be tested for are:
</p>
<div class="variablelist">
<dl><dt><span class="term"><span><strong class="option">auth_failed</strong></span></span></dt><dd><p>
Authentication failed when trying to send to a host in the
<span><strong class="option">hosts_require_auth</strong></span> list in an <span><strong class="command">smtp</strong></span> transport.
</p>
</dd><dt><span class="term"><span><strong class="option">data_4xx</strong></span></span></dt><dd><p>
A 4<span class="emphasis"><em>xx</em></span> error was received for an outgoing DATA command, either immediately
after the command, or after sending the message’s data.
</p>
</dd><dt><span class="term"><span><strong class="option">mail_4xx</strong></span></span></dt><dd><p>
A 4<span class="emphasis"><em>xx</em></span> error was received for an outgoing MAIL command.
</p>
</dd><dt><span class="term"><span><strong class="option">rcpt_4xx</strong></span></span></dt><dd><p>
A 4<span class="emphasis"><em>xx</em></span> error was received for an outgoing RCPT command.
</p>
</dd></dl></div>
<p>
For the three 4<span class="emphasis"><em>xx</em></span> errors, either the first or both of the x’s can be given
as specific digits, for example: <code class="literal">mail_45x</code> or <code class="literal">rcpt_436</code>. For example, to
recognize 452 errors given to RCPT commands for addresses in a certain domain,
and have retries every ten minutes with a one-hour timeout, you could set up a
retry rule of this form:
</p>
<pre class="literallayout">the.domain.name rcpt_452 F,1h,10m
</pre><p>
These errors apply to both outgoing SMTP (the <span><strong class="command">smtp</strong></span> transport) and outgoing
LMTP (either the <span><strong class="command">lmtp</strong></span> transport, or the <span><strong class="command">smtp</strong></span> transport in LMTP mode).
</p>
<div class="variablelist">
<dl><dt><span class="term"><span><strong class="option">lost_connection</strong></span></span></dt><dd><p>
A server unexpectedly closed the SMTP connection. There may, of course,
legitimate reasons for this (host died, network died), but if it repeats a lot
for the same host, it indicates something odd.
</p>
</dd><dt><span class="term"><span><strong class="option">refused_MX</strong></span></span></dt><dd><p>
A connection to a host obtained from an MX record was refused.
</p>
</dd><dt><span class="term"><span><strong class="option">refused_A</strong></span></span></dt><dd><p>
A connection to a host not obtained from an MX record was refused.
</p>
</dd><dt><span class="term"><span><strong class="option">refused</strong></span></span></dt><dd><p>
A connection was refused.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout_connect_MX</strong></span></span></dt><dd><p>
A connection attempt to a host obtained from an MX record timed out.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout_connect_A</strong></span></span></dt><dd><p>
A connection attempt to a host not obtained from an MX record timed out.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout_connect</strong></span></span></dt><dd><p>
A connection attempt timed out.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout_MX</strong></span></span></dt><dd><p>
There was a timeout while connecting or during an SMTP session with a host
obtained from an MX record.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout_A</strong></span></span></dt><dd><p>
There was a timeout while connecting or during an SMTP session with a host not
obtained from an MX record.
</p>
</dd><dt><span class="term"><span><strong class="option">timeout</strong></span></span></dt><dd><p>
There was a timeout while connecting or during an SMTP session.
</p>
</dd><dt><span class="term"><span><strong class="option">tls_required</strong></span></span></dt><dd><p>
The server was required to use TLS (it matched <span><strong class="option">hosts_require_tls</strong></span> in the
<span><strong class="command">smtp</strong></span> transport), but either did not offer TLS, or it responded with 4<span class="emphasis"><em>xx</em></span>
to STARTTLS, or there was a problem setting up the TLS connection.
</p>
</dd><dt><span class="term"><span><strong class="option">quota</strong></span></span></dt><dd><p>
A mailbox quota was exceeded in a local delivery by the <span><strong class="command">appendfile</strong></span>
transport.
</p>
</dd><dt><span class="term"><span><strong class="option">quota_</strong></span><<span class="emphasis"><em>time</em></span>></span></dt><dd><p>
<a id="id612031" class="indexterm"></a>
<a id="id612046" class="indexterm"></a>
A mailbox quota was exceeded in a local delivery by the <span><strong class="command">appendfile</strong></span>
transport, and the mailbox has not been accessed for <<span class="emphasis"><em>time</em></span>>. For example,
<span class="emphasis"><em>quota_4d</em></span> applies to a quota error when the mailbox has not been accessed
for four days.
</p>
</dd></dl></div>
<p>
<a id="id612082" class="indexterm"></a>
The idea of <span><strong class="option">quota_</strong></span><<span class="emphasis"><em>time</em></span>> is to make it possible to have shorter
timeouts when the mailbox is full and is not being read by its owner. Ideally,
it should be based on the last time that the user accessed the mailbox.
However, it is not always possible to determine this. Exim uses the following
heuristic rules:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
If the mailbox is a single file, the time of last access (the “<span class="quote">atime</span>”) is
used. As no new messages are being delivered (because the mailbox is over
quota), Exim does not access the file, so this is the time of last user access.
</p>
</li><li><p>
<a id="id612125" class="indexterm"></a>
For a maildir delivery, the time of last modification of the <em class="filename">new</em>
subdirectory is used. As the mailbox is over quota, no new files are created in
the <em class="filename">new</em> subdirectory, because no new messages are being delivered. Any
change to the <em class="filename">new</em> subdirectory is therefore assumed to be the result of an
MUA moving a new message to the <em class="filename">cur</em> directory when it is first read. The
time that is used is therefore the last time that the user read a new message.
</p>
</li><li><p>
For other kinds of multi-file mailbox, the time of last access cannot be
obtained, so a retry rule that uses this type of error field is never matched.
</p>
</li></ul></div>
<p>
The quota errors apply both to system-enforced quotas and to Exim’s own quota
mechanism in the <span><strong class="command">appendfile</strong></span> transport. The <span class="emphasis"><em>quota</em></span> error also applies
when a local delivery is deferred because a partition is full (the ENOSPC
error).
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0266" id="SECID162">32.6 Retry rules for specified senders</a></h3></div>
</div>
</div>
<p>
<a id="id612212" class="indexterm"></a>
You can specify retry rules that apply only when the failing message has a
specific sender. In particular, this can be used to define retry rules that
apply only to bounce messages. The third item in a retry rule can be of this
form:
</p>
<div class="literallayout">
<code class="literal">senders=</code><<span class="emphasis"><em>address list</em></span>><br />
</div>
<p>
The retry timings themselves are then the fourth item. For example:
</p>
<pre class="literallayout">* rcpt_4xx senders=: F,1h,30m
</pre><p>
matches recipient 4<span class="emphasis"><em>xx</em></span> errors for bounce messages sent to any address at any
host. If the address list contains white space, it must be enclosed in quotes.
For example:
</p>
<pre class="literallayout">a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5
</pre><p>
<span class="bold"><strong>Warning</strong></span>: This facility can be unhelpful if it is used for host errors
(which do not depend on the recipient). The reason is that the sender is used
only to match the retry rule. Once the rule has been found for a host error,
its contents are used to set a retry time for the host, and this will apply to
all messages, not just those with specific senders.
</p>
<p>
When testing retry rules using <span><strong class="option">-brt</strong></span>, you can supply a sender using the
<span><strong class="option">-f</strong></span> command line option, like this:
</p>
<pre class="literallayout">exim -f "" -brt user@dom.ain
</pre><p>
If you do not set <span><strong class="option">-f</strong></span> with <span><strong class="option">-brt</strong></span>, a retry rule that contains a senders
list is never matched.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0267" id="SECID163">32.7 Retry parameters</a></h3></div>
</div>
</div>
<p>
<a id="id612338" class="indexterm"></a>
The third (or fourth, if a senders list is present) field in a retry rule is a
sequence of retry parameter sets, separated by semicolons. Each set consists of
</p>
<div class="literallayout">
<<span class="emphasis"><em>letter</em></span>>,<<span class="emphasis"><em>cutoff time</em></span>>,<<span class="emphasis"><em>arguments</em></span>><br />
</div>
<p>
The letter identifies the algorithm for computing a new retry time; the cutoff
time is the time beyond which this algorithm no longer applies, and the
arguments vary the algorithm’s action. The cutoff time is measured from the
time that the first failure for the domain (combined with the local part if
relevant) was detected, not from the time the message was received.
</p>
<p>
<a id="id612384" class="indexterm"></a>
<a id="id612398" class="indexterm"></a>
<a id="id612413" class="indexterm"></a>
<a id="id612427" class="indexterm"></a>
The available algorithms are:
</p>
<div class="itemizedlist">
<ul type="disc"><li><p>
<span class="emphasis"><em>F</em></span>: retry at fixed intervals. There is a single time parameter specifying
the interval.
</p>
</li><li><p>
<span class="emphasis"><em>G</em></span>: retry at geometrically increasing intervals. The first argument
specifies a starting value for the interval, and the second a multiplier, which
is used to increase the size of the interval at each retry.
</p>
</li><li><p>
<span class="emphasis"><em>H</em></span>: retry at randomized intervals. The arguments are as for <span class="emphasis"><em>G</em></span>. For each
retry, the previous interval is multiplied by the factor in order to get a
maximum for the next interval. The minimum interval is the first argument of
the parameter, and an actual interval is chosen randomly between them. Such a
rule has been found to be helpful in cluster configurations when all the
members of the cluster restart at once, and may therefore synchronize their
queue processing times.
</p>
</li></ul></div>
<p>
When computing the next retry time, the algorithm definitions are scanned in
order until one whose cutoff time has not yet passed is reached. This is then
used to compute a new retry time that is later than the current time. In the
case of fixed interval retries, this simply means adding the interval to the
current time. For geometrically increasing intervals, retry intervals are
computed from the rule’s parameters until one that is greater than the previous
interval is found. The main configuration variable
<a id="id612494" class="indexterm"></a>
<a id="id612508" class="indexterm"></a>
<a id="id612523" class="indexterm"></a>
<span><strong class="option">retry_interval_max</strong></span> limits the maximum interval between retries. It
cannot be set greater than <code class="literal">24h</code>, which is its default value.
</p>
<p>
A single remote domain may have a number of hosts associated with it, and each
host may have more than one IP address. Retry algorithms are selected on the
basis of the domain name, but are applied to each IP address independently. If,
for example, a host has two IP addresses and one is unusable, Exim will
generate retry times for it and will not try to use it until its next retry
time comes. Thus the good IP address is likely to be tried first most of the
time.
</p>
<p>
<a id="id612561" class="indexterm"></a>
Retry times are hints rather than promises. Exim does not make any attempt to
run deliveries exactly at the computed times. Instead, a queue runner process
starts delivery processes for delayed messages periodically, and these attempt
new deliveries only for those addresses that have passed their next retry time.
If a new message arrives for a deferred address, an immediate delivery attempt
occurs only if the address has passed its retry time. In the absence of new
messages, the minimum time between retries is the interval between queue runner
processes. There is not much point in setting retry times of five minutes if
your queue runners happen only once an hour, unless there are a significant
number of incoming messages (which might be the case on a system that is
sending everything to a smart host, for example).
</p>
<p>
The data in the retry hints database can be inspected by using the
<span class="emphasis"><em>exim_dumpdb</em></span> or <span class="emphasis"><em>exim_fixdb</em></span> utility programs (see chapter
<a href="ch50.html" title="50. Exim utilities">50</a>). The latter utility can also be used to change the data. The
<span class="emphasis"><em>exinext</em></span> utility script can be used to find out what the next retry times
are for the hosts associated with a particular mail domain, and also for local
deliveries that have been deferred.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0268" id="SECID164">32.8 Retry rule examples</a></h3></div>
</div>
</div>
<p>
Here are some example retry rules:
</p>
<pre class="literallayout">alice@wonderland.fict.example quota_5d F,7d,3h
wonderland.fict.example quota_5d
wonderland.fict.example * F,1h,15m; G,2d,1h,2;
lookingglass.fict.example * F,24h,30m;
* refused_A F,2h,20m;
* * F,2h,15m; G,16h,1h,1.5; F,5d,8h
</pre><p>
The first rule sets up special handling for mail to
<span class="emphasis"><em>alice@wonderland.fict.example</em></span> when there is an over-quota error and the
mailbox has not been read for at least 5 days. Retries continue every three
hours for 7 days. The second rule handles over-quota errors for all other local
parts at <span class="emphasis"><em>wonderland.fict.example</em></span>; the absence of a local part has the same
effect as supplying “<span class="quote">*@</span>”. As no retry algorithms are supplied, messages that
fail are bounced immediately if the mailbox has not been read for at least 5
days.
</p>
<p>
The third rule handles all other errors at <span class="emphasis"><em>wonderland.fict.example</em></span>; retries
happen every 15 minutes for an hour, then with geometrically increasing
intervals until two days have passed since a delivery first failed. After the
first hour there is a delay of one hour, then two hours, then four hours, and
so on (this is a rather extreme example).
</p>
<p>
The fourth rule controls retries for the domain <span class="emphasis"><em>lookingglass.fict.example</em></span>.
They happen every 30 minutes for 24 hours only. The remaining two rules handle
all other domains, with special action for connection refusal from hosts that
were not obtained from an MX record.
</p>
<p>
The final rule in a retry configuration should always have asterisks in the
first two fields so as to provide a general catch-all for any addresses that do
not have their own special handling. This example tries every 15 minutes for 2
hours, then with intervals starting at one hour and increasing by a factor of
1.5 up to 16 hours, then every 8 hours up to 5 days.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0269" id="SECID165">32.9 Timeout of retry data</a></h3></div>
</div>
</div>
<p>
<a id="id612694" class="indexterm"></a>
<a id="id612708" class="indexterm"></a>
<a id="id612720" class="indexterm"></a>
<a id="id612734" class="indexterm"></a>
Exim timestamps the data that it writes to its retry hints database. When it
consults the data during a delivery it ignores any that is older than the value
set in <span><strong class="option">retry_data_expire</strong></span> (default 7 days). If, for example, a host hasn’t
been tried for 7 days, Exim will try to deliver to it immediately a message
arrives, and if that fails, it will calculate a retry time as if it were
failing for the first time.
</p>
<p>
This improves the behaviour for messages routed to rarely-used hosts such as MX
backups. If such a host was down at one time, and happens to be down again when
Exim tries a month later, using the old retry data would imply that it had been
down all the time, which is not a justified assumption.
</p>
<p>
If a host really is permanently dead, this behaviour causes a burst of retries
every now and again, but only if messages routed to it are rare. If there is a
message at least once every 7 days the retry data never expires.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0270" id="SECID166">32.10 Long-term failures</a></h3></div>
</div>
</div>
<p>
<a id="id612785" class="indexterm"></a>
<a id="id612796" class="indexterm"></a>
Special processing happens when an email address has been failing for so long
that the cutoff time for the last algorithm is reached. For example, using the
default retry rule:
</p>
<pre class="literallayout">* * F,2h,15m; G,16h,1h,1.5; F,4d,6h
</pre><p>
the cutoff time is four days. Reaching the retry cutoff is independent of how
long any specific message has been failing; it is the length of continuous
failure for the recipient address that counts.
</p>
<p>
When the cutoff time is reached for a local delivery, or for all the IP
addresses associated with a remote delivery, a subsequent delivery failure
causes Exim to give up on the address, and a bounce message is generated.
In order to cater for new messages that use the failing address, a next retry
time is still computed from the final algorithm, and is used as follows:
</p>
<p>
For local deliveries, one delivery attempt is always made for any subsequent
messages. If this delivery fails, the address fails immediately. The
post-cutoff retry time is not used.
</p>
<p>
If the delivery is remote, there are two possibilities, controlled by the
<a id="id612849" class="indexterm"></a>
<span><strong class="option">delay_after_cutoff</strong></span> option of the <span><strong class="command">smtp</strong></span> transport. The option is true by
default. Until the post-cutoff retry time for one of the IP addresses is
reached, the failing email address is bounced immediately, without a delivery
attempt taking place. After that time, one new delivery attempt is made to
those IP addresses that are past their retry times, and if that still fails,
the address is bounced and new retry times are computed.
</p>
<p>
In other words, when all the hosts for a given email address have been failing
for a long time, Exim bounces rather then defers until one of the hosts’ retry
times is reached. Then it tries once, and bounces if that attempt fails. This
behaviour ensures that few resources are wasted in repeatedly trying to deliver
to a broken destination, but if the host does recover, Exim will eventually
notice.
</p>
<p>
If <span><strong class="option">delay_after_cutoff</strong></span> is set false, Exim behaves differently. If all IP
addresses are past their final cutoff time, Exim tries to deliver to those IP
addresses that have not been tried since the message arrived. If there are
no suitable IP addresses, or if they all fail, the address is bounced. In other
words, it does not delay when a new message arrives, but tries the expired
addresses immediately, unless they have been tried since the message arrived.
If there is a continuous stream of messages for the failing domains, setting
<span><strong class="option">delay_after_cutoff</strong></span> false means that there will be many more attempts to
deliver to permanently failing IP addresses than when <span><strong class="option">delay_after_cutoff</strong></span> is
true.
</p>
</div>
<div class="section" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 xmlns="" class="title"><a xmlns="http://www.w3.org/1999/xhtml" href="index.html#toc0271" id="SECID167">32.11 Deliveries that work intermittently</a></h3></div>
</div>
</div>
<p>
<a id="id612913" class="indexterm"></a>
Some additional logic is needed to cope with cases where a host is
intermittently available, or when a message has some attribute that prevents
its delivery when others to the same address get through. In this situation,
because some messages are successfully delivered, the “<span class="quote">retry clock</span>” for the
host or address keeps getting reset by the successful deliveries, and so
failing messages remain on the queue for ever because the cutoff time is never
reached.
</p>
<p>
Two exceptional actions are applied to prevent this happening. The first
applies to errors that are related to a message rather than a remote host.
Section <a href="ch45.html#SECToutSMTPerr" title="45.2 Errors in outgoing SMTP">45.2</a> has a discussion of the different kinds of error;
examples of message-related errors are 4<span class="emphasis"><em>xx</em></span> responses to MAIL or DATA
commands, and quota failures. For this type of error, if a message’s arrival
time is earlier than the “<span class="quote">first failed</span>” time for the error, the earlier time
is used when scanning the retry rules to decide when to try next and when to
time out the address.
</p>
<p>
The exceptional second action applies in all cases. If a message has been on
the queue for longer than the cutoff time of any applicable retry rule for a
given address, a delivery is attempted for that address, even if it is not yet
time, and if this delivery fails, the address is timed out. A new retry time is
not computed in this case, so that other messages for the same address are
considered immediately.
<a id="id612975" class="indexterm"></a>
<a id="id612986" class="indexterm"></a>
</p>
</div>
</div>
<div class="navfooter">
<table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch31.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch33.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div>
</body></html>
