<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>30. The smtp transport</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/ch30.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="ch29.html"><-previous</a><a class="next_page" href="ch31.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPsmtptrans" class="">Chapter 30 - The smtp transport</h2> <p> The <span class="docbook_command">smtp</span> 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="ch32.html" title="32. Retry configuration">32</a>) is applied to each IP address independently. </p> <div class="section"> <h3 id="SECID144" class="">1. Multiple messages on a single connection</h3> <p> The sending of multiple messages over a single TCP/IP connection can arise in two ways: </p> <ul> <li> <p> If a message contains more than <span class="docbook_option">max_rcpt</span> (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 <span class="docbook_command">smtp</span> 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 <span class="docbook_option">remote_max_parallel</span> option. Details are given in section <a href="ch45.html#SECToutSMTPTCP" title="45. SMTP processing">45.1</a>.) </p> </li> <li> <p> 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. </p> </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 <span class="docbook_option">connection_max_messages</span>, no further messages are sent over that connection. </p> </div> <div class="section"> <h3 id="SECID145" class="">2. Use of the $host and $host_address variables</h3> <p> At the start of a run of the <span class="docbook_command">smtp</span> transport, the values of $host and $host_address 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, $host and $host_address are set to the values for that host. These are the values that are in force when the <span class="docbook_option">helo_data</span>, <span class="docbook_option">hosts_try_auth</span>, <span class="docbook_option">interface</span>, <span class="docbook_option">serialize_hosts</span>, and the various TLS options are expanded. </p> </div> <div class="section"> <h3 id="usecippeer" class="">3. Use of $tls_cipher and $tls_peerdn</h3> <p> At the start of a run of the <span class="docbook_command">smtp</span> transport, the values of $tls_cipher and $tls_peerdn 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 <span class="docbook_option">authenticated_sender</span> option is expanded. </p> </div> <div class="section"> <h3 id="SECID146" class="">4. Private options for smtp</h3> <p> The private options of the <span class="docbook_command">smtp</span> transport are as follows: </p> <p> </p> <table> <tr> <td><span class="docbook_option">address_retry_include_sender</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> When an address is delayed because of a 4<span class="docbook_emphasis">xx</span> 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 <span class="docbook_option">address_retry_include_sender</span> false. However, this can lead to problems with servers that regularly issue 4<span class="docbook_emphasis">xx</span> responses to RCPT commands. </p> <p> </p> <table> <tr> <td><span class="docbook_option">allow_localhost</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> When a host specified in <span class="docbook_option">hosts</span> or <span class="docbook_option">fallback_hosts</span> (see below) turns out to be the local host, or is listed in <span class="docbook_option">hosts_treat_as_local</span>, delivery is deferred by default. However, if <span class="docbook_option">allow_localhost</span> 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> <p> </p> <table> <tr> <td><span class="docbook_option">authenticated_sender</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> When Exim has authenticated as a client, or if <span class="docbook_option">authenticated_sender_force</span> 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 $host, $host_address, $tls_cipher, and $tls_peerdn variables are set according to the particular connection. </p> <p> If the SMTP session is not authenticated, the expansion of <span class="docbook_option">authenticated_sender</span> still happens (and can cause the delivery to be deferred if it fails), but no AUTH= item is added to MAIL commands unless <span class="docbook_option">authenticated_sender_force</span> is true. </p> <p> This option allows you to use the <span class="docbook_command">smtp</span> 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> <div class="docbook_literallayout"><pre> authenticated_sender = $local_part </pre></div> <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> <p> </p> <table> <tr> <td><span class="docbook_option">authenticated_sender_force</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set true, the <span class="docbook_option">authenticated_sender</span> option’s value is used for the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as a client. </p> <p> </p> <table> <tr> <td><span class="docbook_option">command_timeout</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">5m</span> </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> <p> </p> <table> <tr> <td><span class="docbook_option">connect_timeout</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">5m</span> </td> </tr> </table> <p> This sets a timeout for the <span class="docbook_function">connect()</span> 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> <p> </p> <table> <tr> <td><span class="docbook_option">connection_max_messages</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">500</span> </td> </tr> </table> <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 <span class="docbook_option">-oB</span> command line option. </p> <p> </p> <table> <tr> <td><span class="docbook_option">data_timeout</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">5m</span> </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 <span class="docbook_option">final_timeout</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">delay_after_cutoff</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </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 <span class="docbook_option">delay_after_cutoff</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 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 <span class="docbook_option">delay_after_cutoff</span> means that there will be many more attempts to deliver to them. </p> <p> </p> <table> <tr> <td><span class="docbook_option">dns_qualify_single</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> If the <span class="docbook_option">hosts</span> or <span class="docbook_option">fallback_hosts</span> option is being used, and the <span class="docbook_option">gethostbyname</span> option is false, the RES_DEFNAMES resolver option is set. See the <span class="docbook_option">qualify_single</span> option in chapter <a href="ch17.html" title="17. The dnslookup router">17</a> for more details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">dns_search_parents</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If the <span class="docbook_option">hosts</span> or <span class="docbook_option">fallback_hosts</span> option is being used, and the <span class="docbook_option">gethostbyname</span> option is false, the RES_DNSRCH resolver option is set. See the <span class="docbook_option">search_parents</span> option in chapter <a href="ch17.html" title="17. The dnslookup router">17</a> for more details. </p> <p> </p> <table> <tr> <td><span class="docbook_option">fallback_hosts</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string list</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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="ch06.html#SECTlistconstruct" title="6. The Exim run time configuration file">6.19</a>. Each individual item in the list is the same as an item in a <span class="docbook_option">route_list</span> setting for the <span class="docbook_command">manualroute</span> router, as described in section <a href="ch20.html#SECTformatonehostitem" title="20. The manualroute router">20.5</a>. </p> <p> Fallback hosts can also be specified on routers, which associate them with the addresses they process. As for the <span class="docbook_option">hosts</span> option without <span class="docbook_option">hosts_override</span>, <span class="docbook_option">fallback_hosts</span> specified on the transport is used only if the address does not have its own associated fallback host list. Unlike <span class="docbook_option">hosts</span>, a setting of <span class="docbook_option">fallback_hosts</span> on an address is not overridden by <span class="docbook_option">hosts_override</span>. However, <span class="docbook_option">hosts_randomize</span> 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 <span class="docbook_option">max_rcpt</span> 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 <span class="docbook_option">gethostbyname</span> option, as for the <span class="docbook_option">hosts</span> option. Fallback hosts apply both to cases when the host list comes with the address and when it is taken from <span class="docbook_option">hosts</span>. This option provides a “use a smart host only if delivery fails” facility. </p> <p> </p> <table> <tr> <td><span class="docbook_option">final_timeout</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">time</span> </td> <td>Default: <span class="docbook_emphasis">10m</span> </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> <p> </p> <table> <tr> <td><span class="docbook_option">gethostbyname</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is true when the <span class="docbook_option">hosts</span> and/or <span class="docbook_option">fallback_hosts</span> options are being used, names are looked up using <span class="docbook_function">gethostbyname()</span> (or <span class="docbook_function">getipnodebyname()</span> 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 <span class="docbook_filename">/etc/hosts</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">gnutls_require_kx</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </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="ch39.html#SECTreqciphgnu" title="39. Encrypted SMTP connections using TLS/SSL">39.5</a>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">gnutls_require_mac</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option controls the MAC algorithms when GnuTLS is used in an Exim client. For details, see section <a href="ch39.html#SECTreqciphgnu" title="39. Encrypted SMTP connections using TLS/SSL">39.5</a>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">gnutls_require_protocols</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option controls the protocols when GnuTLS is used in an Exim client. For details, see section <a href="ch39.html#SECTreqciphgnu" title="39. Encrypted SMTP connections using TLS/SSL">39.5</a>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">gnutls_compat_mode</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> This option controls whether GnuTLS is used in compatibility mode in an Exim server. This reduces security slightly, but improves interworking with older implementations of TLS. </p> <p> </p> <table> <tr> <td><span class="docbook_option">helo_data</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <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> <div class="docbook_literallayout"><pre> $primary_hostname </pre></div> <p> During the expansion, the variables $host and $host_address are set to the identity of the remote host, and the variables $sending_ip_address and $sending_port 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 <span class="docbook_option">helo_data</span> to be obtained by a DNS lookup of the outgoing interface address, you could use this: </p> <div class="docbook_literallayout"><pre> helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ {$primary_hostname}} </pre></div> <p> The use of <span class="docbook_option">helo_data</span> applies both to sending messages and when doing callouts. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> Hosts are associated with an address by a router such as <span class="docbook_command">dnslookup</span>, which finds the hosts by looking up the address domain in the DNS, or by <span class="docbook_command">manualroute</span>, which has lists of hosts in its configuration. However, email addresses can be passed to the <span class="docbook_command">smtp</span> transport by any router, and not all of them can provide an associated list of hosts. </p> <p> The <span class="docbook_option">hosts</span> 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 <span class="docbook_option">hosts</span> are also used, whether or not the address has its own hosts, if <span class="docbook_option">hosts_override</span> 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="ch06.html#SECTlistconstruct" title="6. The Exim run time configuration file">6.19</a>. Each individual item in the list is the same as an item in a <span class="docbook_option">route_list</span> setting for the <span class="docbook_command">manualroute</span> router, as described in section <a href="ch20.html#SECTformatonehostitem" title="20. The manualroute router">20.5</a>. However, note that the <code class="docbook_literal">/MX</code> facility of the <span class="docbook_command">manualroute</span> 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 <span class="docbook_function">gethostbyname()</span> (or <span class="docbook_function">getipnodebyname()</span> when available), depending on the setting of the <span class="docbook_option">gethostbyname</span> 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 <span class="docbook_option">hosts_randomize</span> is set. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_avoid_esmtp</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_option">hosts_avoid_esmtp</span>, 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> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_avoid_pipelining</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_avoid_tls</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> Exim will not try to start a TLS session when delivering to any host that matches this list. See chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_max_try</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">5</span> </td> </tr> </table> <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="ch30.html#SECTvalhosmax" title="30. The smtp transport">30.5</a> describes in detail how the value of this option is used. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_max_try_hardlimit</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">50</span> </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="ch30.html#SECTvalhosmax" title="30. The smtp transport">30.5</a> describes its use and why it exists. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_nopass_tls</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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="ch39.html#SECTmulmessam" title="39. Encrypted SMTP connections using TLS/SSL">39.10</a> for an explanation of when this might be needed. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_override</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set and the <span class="docbook_option">hosts</span> option is also set, any hosts that are attached to the address are ignored, and instead the hosts specified by the <span class="docbook_option">hosts</span> option are always used. This option does not apply to <span class="docbook_option">fallback_hosts</span>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_randomize</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set, and either the list of hosts is taken from the <span class="docbook_option">hosts</span> or the <span class="docbook_option">fallback_hosts</span> 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 <span class="docbook_option">hosts_randomize</span> 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 <code class="docbook_literal">+</code> in the host list. For example: </p> <div class="docbook_literallayout"><pre> hosts = host1:host2:host3:+:host4:host5 </pre></div> <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 <span class="docbook_option">hosts_randomize</span> is not set, a <code class="docbook_literal">+</code> item in the list is ignored. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_require_auth</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_option">hosts_try_auth</span>, and chapter <a href="ch33.html" title="33. SMTP authentication">33</a> for details of authentication. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_require_tls</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <p> Exim will insist on using a TLS session when delivering to any host that matches this list. See chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS. <span class="docbook_emphasis">Note</span>: This option affects outgoing mail only. To insist on TLS for incoming messages, use an appropriate ACL. </p> <p> </p> <table> <tr> <td><span class="docbook_option">hosts_try_auth</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_option">hosts_require_auth</span>, and chapter <a href="ch33.html" title="33. SMTP authentication">33</a> for details of authentication. </p> <p> </p> <table> <tr> <td><span class="docbook_option">interface</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <code class="docbook_literal">eth0</code>. Do not confuse this with the interface address that was used when a message was received, which is in $received_ip_address, formerly known as $interface_address. 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 <span class="docbook_option">interface</span> option the variables $host and $host_address 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> <div class="docbook_literallayout"><pre> interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 </pre></div> <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 <span class="docbook_option">interface</span> is not set, or is ignored, the system’s IP functions choose which interface to use if the host has more than one. </p> <p> </p> <table> <tr> <td><span class="docbook_option">keepalive</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <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> <p> </p> <table> <tr> <td><span class="docbook_option">lmtp_ignore_quota</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">false</span> </td> </tr> </table> <p> If this option is set true when the <span class="docbook_option">protocol</span> option is set to “lmtp”, the string <code class="docbook_literal">IGNOREQUOTA</code> is added to RCPT commands, provided that the LMTP server has advertised support for IGNOREQUOTA in its response to the LHLO command. </p> <p> </p> <table> <tr> <td><span class="docbook_option">max_rcpt</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">100</span> </td> </tr> </table> <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 <span class="docbook_option">remote_max_parallel</span> permits this. </p> <p> </p> <table> <tr> <td><span class="docbook_option">multi_domain</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> When this option is set, the <span class="docbook_command">smtp</span> 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 $domain in an expansion for the transport, because it is set only when there is a single domain involved in a remote delivery. </p> <p> </p> <table> <tr> <td><span class="docbook_option">port</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">see below</span> </td> </tr> </table> <p> This option specifies the TCP/IP port on the server to which Exim connects. <span class="docbook_emphasis">Note:</span> Do not confuse this with the port that was used when a message was received, which is in $received_port, formerly known as $interface_port. 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 <span class="docbook_function">getservbyname()</span>. The default value is normally “smtp”, but if <span class="docbook_option">protocol</span> is set to “lmtp”, the default is “lmtp”. If the expansion fails, or if a port number cannot be found, delivery is deferred. </p> <p> </p> <table> <tr> <td><span class="docbook_option">protocol</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span> </td> <td>Default: <span class="docbook_emphasis">smtp</span> </td> </tr> </table> <p> If this option is set to “lmtp” instead of “smtp”, the default value for the <span class="docbook_option">port</span> 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="ch28.html" title="28. The lmtp transport">28</a>. </p> <p> </p> <table> <tr> <td><span class="docbook_option">retry_include_ip_address</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </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 <span class="docbook_command">smtp</span> transport, set up specially to handle the dialup hosts. </p> <p> </p> <table> <tr> <td><span class="docbook_option">serialize_hosts</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">host list</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_option">serialize_hosts</span> to match the relevant hosts. </p> <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 <span class="docbook_filename">misc</span> and they are kept in the <span class="docbook_filename">spool/db</span> 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> <p> </p> <table> <tr> <td><span class="docbook_option">size_addition</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">integer</span> </td> <td>Default: <span class="docbook_emphasis">1024</span> </td> </tr> </table> <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 <span class="docbook_option">size_addition</span> 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 <span class="docbook_option">size_addition</span> is set negative, it disables the use of the SIZE option altogether. </p> <p> </p> <table> <tr> <td><span class="docbook_option">tls_certificate</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 $host and $host_address are set to the name and address of the server during the expansion. See chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS. </p> <p> <span class="docbook_emphasis">Note</span>: 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> <p> </p> <table> <tr> <td><span class="docbook_option">tls_crl</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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> <p> </p> <table> <tr> <td><span class="docbook_option">tls_privatekey</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 $host and $host_address 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="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS. </p> <p> </p> <table> <tr> <td><span class="docbook_option">tls_require_ciphers</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 $host and $host_address are set to the name and address of the server during the expansion. See chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS; note that this option is used in different ways by OpenSSL and GnuTLS (see sections <a href="ch39.html#SECTreqciphssl" title="39. Encrypted SMTP connections using TLS/SSL">39.4</a> and <a href="ch39.html#SECTreqciphgnu" title="39. Encrypted SMTP connections using TLS/SSL">39.5</a>). For GnuTLS, the order of the ciphers is a preference order. </p> <p> </p> <table> <tr> <td><span class="docbook_option">tls_tempfail_tryclear</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">boolean</span> </td> <td>Default: <span class="docbook_emphasis">true</span> </td> </tr> </table> <p> When the server host is not in <span class="docbook_option">hosts_require_tls</span>, 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<span class="docbook_emphasis">xx</span> 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> <p> </p> <table> <tr> <td><span class="docbook_option">tls_verify_certificates</span></td> <td>Use: <span class="docbook_emphasis">smtp</span> </td> <td>Type: <span class="docbook_emphasis">string</span>†<span class="docbook_emphasis"></span> </td> <td>Default: <span class="docbook_emphasis">unset</span> </td> </tr> </table> <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 <span class="docbook_option">tls_verify_certificates</span> 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 $host and $host_address are set to the name and address of the server during the expansion of this option. See chapter <a href="ch39.html" title="39. Encrypted SMTP connections using TLS/SSL">39</a> for details of TLS. </p> </div> <div class="section"> <h3 id="SECTvalhosmax" class="">5. How the limits for the number of hosts to try are used</h3> <p> There are two options that are concerned with the number of hosts that are tried when an SMTP delivery takes place. They are <span class="docbook_option">hosts_max_try</span> and <span class="docbook_option">hosts_max_try_hardlimit</span>. </p> <p> The <span class="docbook_option">hosts_max_try</span> 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 <span class="docbook_option">hosts_max_try</span> 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 <span class="docbook_option">hosts_max_retry</span> 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 <span class="docbook_option">hosts_max_try</span> 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 <span class="docbook_option">hosts_max_try</span> 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 <span class="docbook_option">hosts_max_try</span> limit has already been reached. </p> <p> The above logic means that <span class="docbook_option">hosts_max_try</span> is not a hard limit, and in particular, Exim normally eventually tries all the IP addresses before timing out an email address. When <span class="docbook_option">hosts_max_try</span> 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 <span class="docbook_option">hosts_max_try_hardlimit</span> 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. </p> </div> </div> <a class="previous_page" href="ch29.html"><-previous</a><a class="next_page" href="ch31.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>