<!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: 30. The smtp transport</title>
<meta name="description" content="Specification of the Exim Mail Transfer Agent: 30. The smtp transport">
<meta name="keywords" content="Specification of the Exim Mail Transfer Agent: 30. The smtp transport">
<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-smtp-transport"></a>
<a name="SEC242"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="spec_29.html#SEC241" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC243" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="spec_29.html#SEC235" 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_31.html#SEC248" 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"> 30. The smtp transport </h1>
<p>The <code>smtp</code> transport delivers messages over TCP/IP connections using the SMTP
or LMTP protocol. The list of hosts to try can either be taken from the address
that is being processed (having been set up by the router), or specified
explicitly for the transport. Timeout and retry processing (see chapter
<a href="spec_32.html#SEC260">Retry configuration</a>) is applied to each IP address independently.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC243">30.1 Multiple messages on a single connection</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC244">30.2 Use of the $host and $host_address variables</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC245">30.3 Use of $tls_cipher and $tls_peerdn</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC246">30.4 Private options for smtp</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC247">30.5 How the limits for the number of hosts to try are used</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Multiple-messages-on-a-single-connection"></a>
<a name="SEC243"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC242" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC244" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC242" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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"> 30.1 Multiple messages on a single connection </h2>
<p>The sending of multiple messages over a single TCP/IP connection can arise in
two ways:
</p>
<ul class="toc">
<li>
If a message contains more than <code>max_rcpt</code> (see below) addresses that are
routed to the same host, more than one copy of the message has to be sent to
that host. In this situation, multiple copies may be sent in a single run of
the <code>smtp</code> transport over a single TCP/IP connection. (What Exim actually
does when it has too many addresses to send in one message also depends on the
value of the global <code>remote_max_parallel</code> option. Details are given in
section <a href="spec_45.html#SEC406">Outgoing SMTP and LMTP over TCP/IP</a>.)
</li><li>
<a name="IDX2258"></a>
When a message has been successfully delivered over a TCP/IP connection, Exim
looks in its hints database to see if there are any other messages awaiting a
connection to the same host. If there are, a new delivery process is started
for one of them, and the current TCP/IP connection is passed on to it. The new
process may in turn send multiple copies and possibly create yet another
process.
</li></ul>
<p>For each copy sent over the same TCP/IP connection, a sequence counter is
incremented, and if it ever gets to the value of <code>connection_max_messages</code>,
no further messages are sent over that connection.
</p>
<hr size="6">
<a name="Use-of-the-_0024host-and-_0024host_005faddress-variables"></a>
<a name="SEC244"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC243" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC245" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC242" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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"> 30.2 Use of the $host and $host_address variables </h2>
<p>At the start of a run of the <code>smtp</code> transport, the values of <code>$host</code> and
<code>$host_address</code> are the name and IP address of the first host on the host list
passed by the router. However, when the transport is about to connect to a
specific host, and while it is connected to that host, <code>$host</code> and
<code>$host_address</code> are set to the values for that host. These are the values
that are in force when the <code>helo_data</code>, <code>hosts_try_auth</code>, <code>interface</code>,
<code>serialize_hosts</code>, and the various TLS options are expanded.
</p>
<hr size="6">
<a name="Use-of-_0024tls_005fcipher-and-_0024tls_005fpeerdn"></a>
<a name="SEC245"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC244" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC246" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC242" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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"> 30.3 Use of $tls_cipher and $tls_peerdn </h2>
<p>At the start of a run of the <code>smtp</code> transport, the values of <code>$tls_cipher</code>
and <code>$tls_peerdn</code> are the values that were set when the message was received.
These are the values that are used for options that are expanded before any
SMTP connections are made. Just before each connection is made, these two
variables are emptied. If TLS is subsequently started, they are set to the
appropriate values for the outgoing connection, and these are the values that
are in force when any authenticators are run and when the
<code>authenticated_sender</code> option is expanded.
</p>
<hr size="6">
<a name="Private-options-for-smtp"></a>
<a name="SEC246"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC245" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC247" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC242" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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"> 30.4 Private options for smtp </h2>
<p>The private options of the <code>smtp</code> transport are as follows:
</p>
<a name="IDX2259"></a>
<table>
<tr><td>
<p><code>address_retry_include_sender</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<a name="IDX2260"></a>
<p>When an address is delayed because of a 4<em>xx</em> response to a RCPT command, it
is the combination of sender and recipient that is delayed in subsequent queue
runs until the retry time is reached. You can delay the recipient without
reference to the sender (which is what earlier versions of Exim did), by
setting <code>address_retry_include_sender</code> false. However, this can lead to
problems with servers that regularly issue 4<em>xx</em> responses to RCPT commands.
</p>
<a name="IDX2261"></a>
<table>
<tr><td>
<p><code>allow_localhost</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<a name="IDX2262"></a>
<a name="IDX2263"></a>
<p>When a host specified in <code>hosts</code> or <code>fallback_hosts</code> (see below) turns out
to be the local host, or is listed in <code>hosts_treat_as_local</code>, delivery is
deferred by default. However, if <code>allow_localhost</code> is set, Exim goes on to do
the delivery anyway. This should be used only in special cases when the
configuration ensures that no looping will result (for example, a differently
configured Exim is listening on the port to which the message is sent).
</p>
<a name="IDX2264"></a>
<table>
<tr><td>
<p><code>authenticated_sender</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2265"></a>
<p>When Exim has authenticated as a client, or if <code>authenticated_sender_force</code>
is true, this option sets a value for the AUTH= item on outgoing MAIL commands,
overriding any existing authenticated sender value. If the string expansion is
forced to fail, the option is ignored. Other expansion failures cause delivery
to be deferred. If the result of expansion is an empty string, that is also
ignored.
</p>
<p>The expansion happens after the outgoing connection has been made and TLS
started, if required. This means that the <code>$host</code>, <code>$host_address</code>,
<code>$tls_cipher</code>, and <code>$tls_peerdn</code> variables are set according to the
particular connection.
</p>
<p>If the SMTP session is not authenticated, the expansion of
<code>authenticated_sender</code> still happens (and can cause the delivery to be
deferred if it fails), but no AUTH= item is added to MAIL commands
unless <code>authenticated_sender_force</code> is true.
</p>
<p>This option allows you to use the <code>smtp</code> transport in LMTP mode to
deliver mail to Cyrus IMAP and provide the proper local part as the
"authenticated sender", via a setting such as:
</p>
<table><tr><td> </td><td><pre class="example">authenticated_sender = $local_part
</pre></td></tr></table>
<p>This removes the need for IMAP subfolders to be assigned special ACLs to
allow direct delivery to those subfolders.
</p>
<p>Because of expected uses such as that just described for Cyrus (when no
domain is involved), there is no checking on the syntax of the provided
value.
</p>
<a name="IDX2266"></a>
<table>
<tr><td>
<p><code>authenticated_sender_force</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<p>If this option is set true, the <code>authenticated_sender</code> option's value
is used for the AUTH= item on outgoing MAIL commands, even if Exim has not
authenticated as a client.
</p>
<a name="IDX2267"></a>
<table>
<tr><td>
<p><code>command_timeout</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>time</em></p></td><td><p> Default: <em>5m</em>
</p></td></tr>
</table>
<p>This sets a timeout for receiving a response to an SMTP command that has been
sent out. It is also used when waiting for the initial banner line from the
remote host. Its value must not be zero.
</p>
<a name="IDX2268"></a>
<table>
<tr><td>
<p><code>connect_timeout</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>time</em></p></td><td><p> Default: <em>5m</em>
</p></td></tr>
</table>
<p>This sets a timeout for the <code>connect()</code> function, which sets up a TCP/IP call
to a remote host. A setting of zero allows the system timeout (typically
several minutes) to act. To have any effect, the value of this option must be
less than the system timeout. However, it has been observed that on some
systems there is no system timeout, which is why the default value for this
option is 5 minutes, a value recommended by RFC 1123.
</p>
<a name="IDX2269"></a>
<table>
<tr><td>
<p><code>connection_max_messages</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>integer</em></p></td><td><p> Default: <em>500</em>
</p></td></tr>
</table>
<a name="IDX2270"></a>
<a name="IDX2271"></a>
<a name="IDX2272"></a>
<p>This controls the maximum number of separate message deliveries that are sent
over a single TCP/IP connection. If the value is zero, there is no limit.
For testing purposes, this value can be overridden by the <code>-oB</code> command line
option.
</p>
<a name="IDX2273"></a>
<table>
<tr><td>
<p><code>data_timeout</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>time</em></p></td><td><p> Default: <em>5m</em>
</p></td></tr>
</table>
<p>This sets a timeout for the transmission of each block in the data portion of
the message. As a result, the overall timeout for a message depends on the size
of the message. Its value must not be zero. See also <code>final_timeout</code>.
</p>
<a name="IDX2274"></a>
<table>
<tr><td>
<p><code>delay_after_cutoff</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<p>This option controls what happens when all remote IP addresses for a given
domain have been inaccessible for so long that they have passed their retry
cutoff times.
</p>
<p>In the default state, if the next retry time has not been reached for any of
them, the address is bounced without trying any deliveries. In other words,
Exim delays retrying an IP address after the final cutoff time until a new
retry time is reached, and can therefore bounce an address without ever trying
a delivery, when machines have been down for a long time. Some people are
unhappy at this prospect, so...
</p>
<p>If <code>delay_after_cutoff</code> 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
none, of if they all fail, the address is bounced. In other words, it does not
delay when a new message arrives, but immediately tries those expired IP
addresses that haven't been tried since the message arrived. If there is a
continuous stream of messages for the dead hosts, unsetting
<code>delay_after_cutoff</code> means that there will be many more attempts to deliver
to them.
</p>
<a name="IDX2275"></a>
<table>
<tr><td>
<p><code>dns_qualify_single</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<p>If the <code>hosts</code> or <code>fallback_hosts</code> option is being used,
and the <code>gethostbyname</code> option is false,
the RES_DEFNAMES resolver option is set. See the <code>qualify_single</code> option
in chapter <a href="spec_17.html#SEC188">The dnslookup router</a> for more details.
</p>
<a name="IDX2276"></a>
<table>
<tr><td>
<p><code>dns_search_parents</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<p>If the <code>hosts</code> or <code>fallback_hosts</code> option is being used, and the
<code>gethostbyname</code> option is false, the RES_DNSRCH resolver option is set.
See the <code>search_parents</code> option in chapter <a href="spec_17.html#SEC188">The dnslookup router</a> for more
details.
</p>
<a name="IDX2277"></a>
<table>
<tr><td>
<p><code>fallback_hosts</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string list</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2278"></a>
<p>String expansion is not applied to this option. The argument must be a
colon-separated list of host names or IP addresses, optionally also including
port numbers, though the separator can be changed, as described in section
<a href="spec_6.html#SEC75">List construction</a>. Each individual item in the list is the same as an
item in a <code>route_list</code> setting for the <code>manualroute</code> router, as described
in section <a href="spec_20.html#SEC199">Format of one host item</a>.
</p>
<p>Fallback hosts can also be specified on routers, which associate them with the
addresses they process. As for the <code>hosts</code> option without <code>hosts_override</code>,
<code>fallback_hosts</code> specified on the transport is used only if the address does
not have its own associated fallback host list. Unlike <code>hosts</code>, a setting of
<code>fallback_hosts</code> on an address is not overridden by <code>hosts_override</code>.
However, <code>hosts_randomize</code> does apply to fallback host lists.
</p>
<p>If Exim is unable to deliver to any of the hosts for a particular address, and
the errors are not permanent rejections, the address is put on a separate
transport queue with its host list replaced by the fallback hosts, unless the
address was routed via MX records and the current host was in the original MX
list. In that situation, the fallback host list is not used.
</p>
<p>Once normal deliveries are complete, the fallback queue is delivered by
re-running the same transports with the new host lists. If several failing
addresses have the same fallback hosts (and <code>max_rcpt</code> permits it), a single
copy of the message is sent.
</p>
<p>The resolution of the host names on the fallback list is controlled by the
<code>gethostbyname</code> option, as for the <code>hosts</code> option. Fallback hosts apply
both to cases when the host list comes with the address and when it is taken
from <code>hosts</code>. This option provides a "use a smart host only if delivery
fails" facility.
</p>
<a name="IDX2279"></a>
<table>
<tr><td>
<p><code>final_timeout</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>time</em></p></td><td><p> Default: <em>10m</em>
</p></td></tr>
</table>
<p>This is the timeout that applies while waiting for the response to the final
line containing just "." that terminates a message. Its value must not be
zero.
</p>
<a name="IDX2280"></a>
<table>
<tr><td>
<p><code>gethostbyname</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<p>If this option is true when the <code>hosts</code> and/or <code>fallback_hosts</code> options are
being used, names are looked up using <code>gethostbyname()</code>
(or <code>getipnodebyname()</code> when available)
instead of using the DNS. Of course, that function may in fact use the DNS, but
it may also consult other sources of information such as ‘<tt>/etc/hosts</tt>’.
</p>
<a name="IDX2281"></a>
<table>
<tr><td>
<p><code>gnutls_require_kx</code></p></td><td><p> Use: <em>main</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>This option controls the key exchange mechanisms when GnuTLS is used in an Exim
client. For details, see section <a href="spec_39.html#SEC299">Requiring specific ciphers or other parameters in GnuTLS</a>.
</p>
<a name="IDX2282"></a>
<table>
<tr><td>
<p><code>gnutls_require_mac</code></p></td><td><p> Use: <em>main</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>This option controls the MAC algorithms when GnuTLS is used in an Exim
client. For details, see section <a href="spec_39.html#SEC299">Requiring specific ciphers or other parameters in GnuTLS</a>.
</p>
<a name="IDX2283"></a>
<table>
<tr><td>
<p><code>gnutls_require_protocols</code></p></td><td><p> Use: <em>main</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>This option controls the protocols when GnuTLS is used in an Exim
client. For details, see section <a href="spec_39.html#SEC299">Requiring specific ciphers or other parameters in GnuTLS</a>.
</p>
<a name="IDX2284"></a>
<table>
<tr><td>
<p><code>helo_data</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>see below</em>
</p></td></tr>
</table>
<a name="IDX2285"></a>
<a name="IDX2286"></a>
<a name="IDX2287"></a>
<p>The value of this option is expanded after a connection to a another host has
been set up. The result is used as the argument for the EHLO, HELO, or LHLO
command that starts the outgoing SMTP or LMTP session. The default value of the
option is:
</p>
<table><tr><td> </td><td><pre class="example">$primary_hostname
</pre></td></tr></table>
<p>During the expansion, the variables <code>$host</code> and <code>$host_address</code> are set to
the identity of the remote host, and the variables <code>$sending_ip_address</code> and
<code>$sending_port</code> are set to the local IP address and port number that are being
used. These variables can be used to generate different values for different
servers or different local IP addresses. For example, if you want the string
that is used for <code>helo_data</code> to be obtained by a DNS lookup of the outgoing
interface address, you could use this:
</p>
<table><tr><td> </td><td><pre class="example">helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\
{$primary_hostname}}
</pre></td></tr></table>
<p>The use of <code>helo_data</code> applies both to sending messages and when doing
callouts.
</p>
<a name="IDX2288"></a>
<table>
<tr><td>
<p><code>hosts</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<p>Hosts are associated with an address by a router such as <code>dnslookup</code>, which
finds the hosts by looking up the address domain in the DNS, or by
<code>manualroute</code>, which has lists of hosts in its configuration. However,
email addresses can be passed to the <code>smtp</code> transport by any router, and not
all of them can provide an associated list of hosts.
</p>
<p>The <code>hosts</code> option specifies a list of hosts to be used if the address being
processed does not have any hosts associated with it. The hosts specified by
<code>hosts</code> are also used, whether or not the address has its own hosts, if
<code>hosts_override</code> is set.
</p>
<p>The string is first expanded, before being interpreted as a colon-separated
list of host names or IP addresses, possibly including port numbers. The
separator may be changed to something other than colon, as described in section
<a href="spec_6.html#SEC75">List construction</a>. Each individual item in the list is the same as an
item in a <code>route_list</code> setting for the <code>manualroute</code> router, as described
in section <a href="spec_20.html#SEC199">Format of one host item</a>. However, note that the ‘<samp>/MX</samp>’ facility
of the <code>manualroute</code> router is not available here.
</p>
<p>If the expansion fails, delivery is deferred. Unless the failure was caused by
the inability to complete a lookup, the error is logged to the panic log as
well as the main log. Host names are looked up either by searching directly for
address records in the DNS or by calling <code>gethostbyname()</code> (or
<code>getipnodebyname()</code> when available), depending on the setting of the
<code>gethostbyname</code> option. When Exim is compiled with IPv6 support, if a host
that is looked up in the DNS has both IPv4 and IPv6 addresses, both types of
address are used.
</p>
<p>During delivery, the hosts are tried in order, subject to their retry status,
unless <code>hosts_randomize</code> is set.
</p>
<a name="IDX2289"></a>
<table>
<tr><td>
<p><code>hosts_avoid_esmtp</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2290"></a>
<a name="IDX2291"></a>
<a name="IDX2292"></a>
<a name="IDX2293"></a>
<p>This option is for use with broken hosts that announce ESMTP facilities (for
example, PIPELINING) and then fail to implement them properly. When a host
matches <code>hosts_avoid_esmtp</code>, Exim sends HELO rather than EHLO at the
start of the SMTP session. This means that it cannot use any of the ESMTP
facilities such as AUTH, PIPELINING, SIZE, and STARTTLS.
</p>
<a name="IDX2294"></a>
<table>
<tr><td>
<p><code>hosts_avoid_pipelining</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2295"></a>
<p>Exim will not use the SMTP PIPELINING extension when delivering to any host
that matches this list, even if the server host advertises PIPELINING support.
</p>
<a name="IDX2296"></a>
<table>
<tr><td>
<p><code>hosts_avoid_tls</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2297"></a>
<p>Exim will not try to start a TLS session when delivering to any host that
matches this list. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for details of TLS.
</p>
<a name="IDX2298"></a>
<table>
<tr><td>
<p><code>hosts_max_try</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>integer</em></p></td><td><p> Default: <em>5</em>
</p></td></tr>
</table>
<a name="IDX2299"></a>
<a name="IDX2300"></a>
<a name="IDX2301"></a>
<a name="IDX2302"></a>
<p>This option limits the number of IP addresses that are tried for any one
delivery in cases where there are temporary delivery errors. Section
<a href="#SEC247">How the limits for the number of hosts to try are used</a> describes in detail how the value of this option is used.
</p>
<a name="IDX2303"></a>
<table>
<tr><td>
<p><code>hosts_max_try_hardlimit</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>integer</em></p></td><td><p> Default: <em>50</em>
</p></td></tr>
</table>
<p>This is an additional check on the maximum number of IP addresses that Exim
tries for any one delivery. Section <a href="#SEC247">How the limits for the number of hosts to try are used</a> describes its use and
why it exists.
</p>
<a name="IDX2304"></a>
<table>
<tr><td>
<p><code>hosts_nopass_tls</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2305"></a>
<a name="IDX2306"></a>
<a name="IDX2307"></a>
<p>For any host that matches this list, a connection on which a TLS session has
been started will not be passed to a new delivery process for sending another
message on the same connection. See section <a href="spec_39.html#SEC304">Multiple messages on the same encrypted TCP/IP connection</a> for an
explanation of when this might be needed.
</p>
<a name="IDX2308"></a>
<table>
<tr><td>
<p><code>hosts_override</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<p>If this option is set and the <code>hosts</code> option is also set, any hosts that are
attached to the address are ignored, and instead the hosts specified by the
<code>hosts</code> option are always used. This option does not apply to
<code>fallback_hosts</code>.
</p>
<a name="IDX2309"></a>
<table>
<tr><td>
<p><code>hosts_randomize</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<a name="IDX2310"></a>
<a name="IDX2311"></a>
<a name="IDX2312"></a>
<p>If this option is set, and either the list of hosts is taken from the
<code>hosts</code> or the <code>fallback_hosts</code> option, or the hosts supplied by the router
were not obtained from MX records (this includes fallback hosts from the
router), and were not randomized by the router, the order of trying the hosts
is randomized each time the transport runs. Randomizing the order of a host
list can be used to do crude load sharing.
</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">hosts = 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.
</p>
<a name="IDX2313"></a>
<table>
<tr><td>
<p><code>hosts_require_auth</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2314"></a>
<p>This option provides a list of servers for which authentication must succeed
before Exim will try to transfer a message. If authentication fails for
servers which are not in this list, Exim tries to send unauthenticated. If
authentication fails for one of these servers, delivery is deferred. This
temporary error is detectable in the retry rules, so it can be turned into a
hard failure if required. See also <code>hosts_try_auth</code>, and chapter
<a href="spec_33.html#SEC272">SMTP authentication</a> for details of authentication.
</p>
<a name="IDX2315"></a>
<table>
<tr><td>
<p><code>hosts_require_tls</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2316"></a>
<p>Exim will insist on using a TLS session when delivering to any host that
matches this list. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for details of TLS.
<strong>Note</strong>: This option affects outgoing mail only. To insist on TLS for
incoming messages, use an appropriate ACL.
</p>
<a name="IDX2317"></a>
<table>
<tr><td>
<p><code>hosts_try_auth</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2318"></a>
<p>This option provides a list of servers to which, provided they announce
authentication support, Exim will attempt to authenticate as a client when it
connects. If authentication fails, Exim will try to transfer the message
unauthenticated. See also <code>hosts_require_auth</code>, and chapter
<a href="spec_33.html#SEC272">SMTP authentication</a> for details of authentication.
</p>
<a name="IDX2319"></a>
<table>
<tr><td>
<p><code>interface</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2320"></a>
<a name="IDX2321"></a>
<a name="IDX2322"></a>
<a name="IDX2323"></a>
<p>This option specifies which interface to bind to when making an outgoing SMTP
call. The value is an IP address, not an interface name such as
‘<samp>eth0</samp>’. Do not confuse this with the interface address that was used when a
message was received, which is in <code>$received_ip_address</code>, formerly known as
<code>$interface_address</code>. The name was changed to minimize confusion with the
outgoing interface address. There is no variable that contains an outgoing
interface address because, unless it is set by this option, its value is
unknown.
</p>
<p>During the expansion of the <code>interface</code> option the variables <code>$host</code> and
<code>$host_address</code> refer to the host to which a connection is about to be made
during the expansion of the string. Forced expansion failure, or an empty
string result causes the option to be ignored. Otherwise, after expansion, the
string must be a list of IP addresses, colon-separated by default, but the
separator can be changed in the usual way. For example:
</p>
<table><tr><td> </td><td><pre class="example">interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061
</pre></td></tr></table>
<p>The first interface of the correct type (IPv4 or IPv6) is used for the outgoing
connection. If none of them are the correct type, the option is ignored. If
<code>interface</code> is not set, or is ignored, the system's IP functions choose which
interface to use if the host has more than one.
</p>
<a name="IDX2324"></a>
<table>
<tr><td>
<p><code>keepalive</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<a name="IDX2325"></a>
<p>This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket
connections. When set, it causes the kernel to probe idle connections
periodically, by sending packets with "old" sequence numbers. The other end
of the connection should send a acknowledgment if the connection is still okay
or a reset if the connection has been aborted. The reason for doing this is
that it has the beneficial effect of freeing up certain types of connection
that can get stuck when the remote host is disconnected without tidying up the
TCP/IP call properly. The keepalive mechanism takes several hours to detect
unreachable hosts.
</p>
<a name="IDX2326"></a>
<table>
<tr><td>
<p><code>lmtp_ignore_quota</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>false</em>
</p></td></tr>
</table>
<a name="IDX2327"></a>
<p>If this option is set true when the <code>protocol</code> option is set to "lmtp", the
string ‘<samp>IGNOREQUOTA</samp>’ is added to RCPT commands, provided that the LMTP server
has advertised support for IGNOREQUOTA in its response to the LHLO command.
</p>
<a name="IDX2328"></a>
<table>
<tr><td>
<p><code>max_rcpt</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>integer</em></p></td><td><p> Default: <em>100</em>
</p></td></tr>
</table>
<a name="IDX2329"></a>
<p>This option limits the number of RCPT commands that are sent in a single
SMTP message transaction. Each set of addresses is treated independently, and
so can cause parallel connections to the same host if <code>remote_max_parallel</code>
permits this.
</p>
<a name="IDX2330"></a>
<table>
<tr><td>
<p><code>multi_domain</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<a name="IDX2331"></a>
<p>When this option is set, the <code>smtp</code> transport can handle a number of
addresses containing a mixture of different domains provided they all resolve
to the same list of hosts. Turning the option off restricts the transport to
handling only one domain at a time. This is useful if you want to use
<code>$domain</code> in an expansion for the transport, because it is set only when there
is a single domain involved in a remote delivery.
</p>
<a name="IDX2332"></a>
<table>
<tr><td>
<p><code>port</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>see below</em>
</p></td></tr>
</table>
<a name="IDX2333"></a>
<a name="IDX2334"></a>
<p>This option specifies the TCP/IP port on the server to which Exim connects.
<strong>Note:</strong> Do not confuse this with the port that was used when a message was
received, which is in <code>$received_port</code>, formerly known as <code>$interface_port</code>.
The name was changed to minimize confusion with the outgoing port. There is no
variable that contains an outgoing port.
</p>
<p>If the value of this option begins with a digit it is taken as a port number;
otherwise it is looked up using <code>getservbyname()</code>. The default value is
normally "smtp", but if <code>protocol</code> is set to "lmtp", the default is
"lmtp". If the expansion fails, or if a port number cannot be found, delivery
is deferred.
</p>
<a name="IDX2335"></a>
<table>
<tr><td>
<p><code>protocol</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em></p></td><td><p> Default: <em>smtp</em>
</p></td></tr>
</table>
<a name="IDX2336"></a>
<p>If this option is set to "lmtp" instead of "smtp", the default value for
the <code>port</code> option changes to "lmtp", and the transport operates the LMTP
protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local
deliveries into closed message stores. Exim also has support for running LMTP
over a pipe to a local process - see chapter <a href="spec_28.html#SEC234">The lmtp transport</a>.
</p>
<a name="IDX2337"></a>
<table>
<tr><td>
<p><code>retry_include_ip_address</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<p>Exim normally includes both the host name and the IP address in the key it
constructs for indexing retry data after a temporary delivery failure. This
means that when one of several IP addresses for a host is failing, it gets
tried periodically (controlled by the retry rules), but use of the other IP
addresses is not affected.
</p>
<p>However, in some dialup environments hosts are assigned a different IP address
each time they connect. In this situation the use of the IP address as part of
the retry key leads to undesirable behaviour. Setting this option false causes
Exim to use only the host name. This should normally be done on a separate
instance of the <code>smtp</code> transport, set up specially to handle the dialup
hosts.
</p>
<a name="IDX2338"></a>
<table>
<tr><td>
<p><code>serialize_hosts</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>host list</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2339"></a>
<a name="IDX2340"></a>
<p>Because Exim operates in a distributed manner, if several messages for the same
host arrive at around the same time, more than one simultaneous connection to
the remote host can occur. This is not usually a problem except when there is a
slow link between the hosts. In that situation it may be helpful to restrict
Exim to one connection at a time. This can be done by setting
<code>serialize_hosts</code> to match the relevant hosts.
</p>
<a name="IDX2341"></a>
<p>Exim implements serialization by means of a hints database in which a record is
written whenever a process connects to one of the restricted hosts. The record
is deleted when the connection is completed. Obviously there is scope for
records to get left lying around if there is a system or program crash. To
guard against this, Exim ignores any records that are more than six hours old.
</p>
<p>If you set up this kind of serialization, you should also arrange to delete the
relevant hints database whenever your system reboots. The names of the files
start with ‘<tt>misc</tt>’ and they are kept in the ‘<tt>spool/db</tt>’ directory. There
may be one or two files, depending on the type of DBM in use. The same files
are used for ETRN serialization.
</p>
<a name="IDX2342"></a>
<table>
<tr><td>
<p><code>size_addition</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>integer</em></p></td><td><p> Default: <em>1024</em>
</p></td></tr>
</table>
<a name="IDX2343"></a>
<a name="IDX2344"></a>
<a name="IDX2345"></a>
<a name="IDX2346"></a>
<a name="IDX2347"></a>
<p>If a remote SMTP server indicates that it supports the SIZE option of the
MAIL command, Exim uses this to pass over the message size at the start of
an SMTP transaction. It adds the value of <code>size_addition</code> to the value it
sends, to allow for headers and other text that may be added during delivery by
configuration options or in a transport filter. It may be necessary to increase
this if a lot of text is added to messages.
</p>
<p>Alternatively, if the value of <code>size_addition</code> is set negative, it disables
the use of the SIZE option altogether.
</p>
<a name="IDX2348"></a>
<table>
<tr><td>
<p><code>tls_certificate</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2349"></a>
<a name="IDX2350"></a>
<a name="IDX2351"></a>
<a name="IDX2352"></a>
<p>The value of this option must be the absolute path to a file which contains the
client's certificate, for possible use when sending a message over an encrypted
connection. The values of <code>$host</code> and <code>$host_address</code> are set to the name and
address of the server during the expansion. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for
details of TLS.
</p>
<p><strong>Note</strong>: This option must be set if you want Exim to be able to use a TLS
certificate when sending messages as a client. The global option of the same
name specifies the certificate for Exim as a server; it is not automatically
assumed that the same certificate should be used when Exim is operating as a
client.
</p>
<a name="IDX2353"></a>
<table>
<tr><td>
<p><code>tls_crl</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2354"></a>
<a name="IDX2355"></a>
<p>This option specifies a certificate revocation list. The expanded value must
be the name of a file that contains a CRL in PEM format.
</p>
<a name="IDX2356"></a>
<table>
<tr><td>
<p><code>tls_privatekey</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2357"></a>
<a name="IDX2358"></a>
<a name="IDX2359"></a>
<p>The value of this option must be the absolute path to a file which contains the
client's private key. This is used when sending a message over an encrypted
connection using a client certificate. The values of <code>$host</code> and
<code>$host_address</code> are set to the name and address of the server during the
expansion. If this option is unset, or the expansion is forced to fail, or the
result is an empty string, the private key is assumed to be in the same file as
the certificate. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for details of TLS.
</p>
<a name="IDX2360"></a>
<table>
<tr><td>
<p><code>tls_require_ciphers</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2361"></a>
<a name="IDX2362"></a>
<a name="IDX2363"></a>
<a name="IDX2364"></a>
<p>The value of this option must be a list of permitted cipher suites, for use
when setting up an outgoing encrypted connection. (There is a global option of
the same name for controlling incoming connections.) The values of <code>$host</code> and
<code>$host_address</code> are set to the name and address of the server during the
expansion. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for details of TLS; note that this option
is used in different ways by OpenSSL and GnuTLS (see sections
<a href="spec_39.html#SEC298">Requiring specific ciphers in OpenSSL</a> and <a href="spec_39.html#SEC299">Requiring specific ciphers or other parameters in GnuTLS</a>). For GnuTLS, the order of the
ciphers is a preference order.
</p>
<a name="IDX2365"></a>
<table>
<tr><td>
<p><code>tls_tempfail_tryclear</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>boolean</em></p></td><td><p> Default: <em>true</em>
</p></td></tr>
</table>
<a name="IDX2366"></a>
<p>When the server host is not in <code>hosts_require_tls</code>, and there is a problem in
setting up a TLS session, this option determines whether or not Exim should try
to deliver the message unencrypted. If it is set false, delivery to the
current host is deferred; if there are other hosts, they are tried. If this
option is set true, Exim attempts to deliver unencrypted after a 4<em>xx</em>
response to STARTTLS. Also, if STARTTLS is accepted, but the subsequent
TLS negotiation fails, Exim closes the current connection (because it is in an
unknown state), opens a new one to the same host, and then tries the delivery
in clear.
</p>
<a name="IDX2367"></a>
<table>
<tr><td>
<p><code>tls_verify_certificates</code></p></td><td><p> Use: <em>smtp</em></p></td><td><p> Type: <em>string</em>*<em></em></p></td><td><p> Default: <em>unset</em>
</p></td></tr>
</table>
<a name="IDX2368"></a>
<a name="IDX2369"></a>
<a name="IDX2370"></a>
<a name="IDX2371"></a>
<p>The value of this option must be the absolute path to a file containing
permitted server certificates, for use when setting up an encrypted connection.
Alternatively, if you are using OpenSSL, you can set
<code>tls_verify_certificates</code> to the name of a directory containing certificate
files. This does not work with GnuTLS; the option must be set to the name of a
single file if you are using GnuTLS. The values of <code>$host</code> and
<code>$host_address</code> are set to the name and address of the server during the
expansion of this option. See chapter <a href="spec_39.html#SEC294">Encrypted SMTP connections using TLS/SSL</a> for details of TLS.
</p>
<hr size="6">
<a name="How-the-limits-for-the-number-of-hosts-to-try-are-used"></a>
<a name="SEC247"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC246" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC242" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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"> 30.5 How the limits for the number of hosts to try are used </h2>
<p>There are two options that are concerned with the number of hosts that are
tried when an SMTP delivery takes place. They are <code>hosts_max_try</code> and
<code>hosts_max_try_hardlimit</code>.
</p>
<p>The <code>hosts_max_try</code> option limits the number of hosts that are tried
for a single delivery. However, despite the term "host" in its name, the
option actually applies to each IP address independently. In other words, a
multihomed host is treated as several independent hosts, just as it is for
retrying.
</p>
<p>Many of the larger ISPs have multiple MX records which often point to
multihomed hosts. As a result, a list of a dozen or more IP addresses may be
created as a result of routing one of these domains.
</p>
<p>Trying every single IP address on such a long list does not seem sensible; if
several at the top of the list fail, it is reasonable to assume there is some
problem that is likely to affect all of them. Roughly speaking, the value of
<code>hosts_max_try</code> is the maximum number that are tried before deferring the
delivery. However, the logic cannot be quite that simple.
</p>
<p>Firstly, IP addresses that are skipped because their retry times have not
arrived do not count, and in addition, addresses that are past their retry
limits are also not counted, even when they are tried. This means that when
some IP addresses are past their retry limits, more than the value of
<code>hosts_max_retry</code> may be tried. The reason for this behaviour is to ensure
that all IP addresses are considered before timing out an email address (but
see below for an exception).
</p>
<p>Secondly, when the <code>hosts_max_try</code> limit is reached, Exim looks down the host
list to see if there is a subsequent host with a different (higher valued) MX.
If there is, that host is considered next, and the current IP address is used
but not counted. This behaviour helps in the case of a domain with a retry rule
that hardly ever delays any hosts, as is now explained:
</p>
<p>Consider the case of a long list of hosts with one MX value, and a few with a
higher MX value. If <code>hosts_max_try</code> is small (the default is 5) only a few
hosts at the top of the list are tried at first. With the default retry rule,
which specifies increasing retry times, the higher MX hosts are eventually
tried when those at the top of the list are skipped because they have not
reached their retry times.
</p>
<p>However, it is common practice to put a fixed short retry time on domains for
large ISPs, on the grounds that their servers are rarely down for very long.
Unfortunately, these are exactly the domains that tend to resolve to long lists
of hosts. The short retry time means that the lowest MX hosts are tried every
time. The attempts may be in a different order because of random sorting, but
without the special MX check, the higher MX hosts would never be tried until
all the lower MX hosts had timed out (which might be several days), because
there are always some lower MX hosts that have reached their retry times. With
the special check, Exim considers at least one IP address from each MX value at
every delivery attempt, even if the <code>hosts_max_try</code> limit has already been
reached.
</p>
<p>The above logic means that <code>hosts_max_try</code> is not a hard limit, and in
particular, Exim normally eventually tries all the IP addresses before timing
out an email address. When <code>hosts_max_try</code> was implemented, this seemed a
reasonable thing to do. Recently, however, some lunatic DNS configurations have
been set up with hundreds of IP addresses for some domains. It can
take a very long time indeed for an address to time out in these cases.
</p>
<p>The <code>hosts_max_try_hardlimit</code> option was added to help with this problem.
Exim never tries more than this number of IP addresses; if it hits this limit
and they are all timed out, the email address is bounced, even though not all
possible IP addresses have been tried.
<a name="IDX2372"></a>
<a name="IDX2373"></a>
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC242" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="spec_31.html#SEC248" 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
>
133
