File: spec_19.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (816 lines) | stat: -rw-r--r-- 22,985 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 19. The smtp transport</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_18.html">previous</A>, <A HREF="spec_20.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC541" HREF="spec_toc.html#TOC541">19. The smtp transport</A></H1>
<P>
<A NAME="IDX1291"></A>
<A NAME="IDX1292"></A>
<A NAME="IDX1293"></A>
<A NAME="IDX1294"></A>
The <EM>smtp</EM> transport delivers messages over TCP/IP connections using the SMTP
protocol. The list of hosts to try can either be taken from the address that is
being processed, or specified explicitly for the transport. Timeout and retry
processing (see chapter 33) is applied to each IP address
independently. The private options are as follows:

</P>
<P>
<A NAME="IDX1295"></A>

</P>
<P>

<P>
<A NAME="IDX1296"></A>


<H3><A NAME="SEC542" HREF="spec_toc.html#TOC542">allow_localhost (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1297"></A>
When a host specified in <EM>hosts</EM> or <EM>fallback_hosts</EM> (see below) turns out to
be the local host, or is listed in <EM>hosts_treat_as_local</EM>, Exim freezes the
message by default. However, if <EM>allow_localhost</EM> is set, it 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 SMTP port).

</P>

<P>
<A NAME="IDX1298"></A>
<A NAME="IDX1299"></A>


<H3><A NAME="SEC543" HREF="spec_toc.html#TOC543">authenticate_hosts (smtp)</A></H3>

<P>
Type: host list<BR>
Default: unset

</P>
<P>
This option is available only when Exim is built to contain support for at
least one of the SMTP authentication mechanisms. It provides a list of servers
to which, provided they announce authentication support, Exim will attempt to
authenticate as a client when it connects. See chapter 35 for
details.

</P>
<P>
<A NAME="IDX1300"></A>
<A NAME="IDX1301"></A>
<A NAME="IDX1302"></A>
<font color=green>
<A NAME="IDX1303"></A>


<H3><A NAME="SEC544" HREF="spec_toc.html#TOC544">batch_max (smtp)</A></H3>

<P>
Type: integer<BR>
Default: 500

</P>
<P>
</font>
This controls the maximum number of separate message deliveries that can take
place over a single TCP/IP connection. If the value is zero, there is no limit.

</P>
<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 create yet another process. Each time this happens, a
sequence counter is incremented, and if it ever gets to the (non-zero)
<EM>batch_max</EM> value, no further messages are sent on the same TCP/IP connection.

</P>
<P>
For testing purposes, this value can be overridden by the -<EM>oB</EM> command line
option.

</P>
<P>
<A NAME="IDX1304"></A>


<H3><A NAME="SEC545" HREF="spec_toc.html#TOC545">command_timeout (smtp)</A></H3>

<P>
Type: time<BR>
Default: 5m

</P>
<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>
<font color=green>
<A NAME="IDX1305"></A>


<H3><A NAME="SEC546" HREF="spec_toc.html#TOC546">connect_timeout (smtp)</A></H3>

<P>
Type: time<BR>
Default: 5m

</P>
<P>
This sets a timeout for the <EM>connect()</EM> 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.
</font>

</P>
<P>
<A NAME="IDX1306"></A>


<H3><A NAME="SEC547" HREF="spec_toc.html#TOC547">data_timeout (smtp)</A></H3>

<P>
Type: time<BR>
Default: 5m

</P>
<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 <EM>final_timeout</EM>.

</P>
<P>
<A NAME="IDX1307"></A>


<H3><A NAME="SEC548" HREF="spec_toc.html#TOC548">delay_after_cutoff (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<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 <EM>delay_after_cutoff</EM> 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
<EM>delay_after_cutoff</EM> means that there will be many more attempts to deliver
to them.

</P>
<P>
<A NAME="IDX1308"></A>


<H3><A NAME="SEC549" HREF="spec_toc.html#TOC549">dns_qualify_single (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<P>
If the <EM>hosts</EM> or <EM>fallback_hosts</EM> option is being used and names are being
looked up in the DNS, the option to cause the resolver to qualify
single-component names with the local domain is set.

</P>
<P>
<A NAME="IDX1309"></A>


<H3><A NAME="SEC550" HREF="spec_toc.html#TOC550">dns_search_parents (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1310"></A>
If the <EM>hosts</EM> or <EM>fallback_hosts</EM> option is being used and names are being
looked up in the DNS, the resolver option to enable the searching of
parent domains is set. Many resolvers default this option to be on, but its use
in resolving mail addresses has caused problems in cases where wildcard MX
records exist, so the default was changed to false in Exim version 1.80.

</P>
<P>
<A NAME="IDX1311"></A>


<H3><A NAME="SEC551" HREF="spec_toc.html#TOC551">fallback_hosts (smtp)</A></H3>

<P>
Type: string list<BR>
Default: unset

</P>
<P>
<A NAME="IDX1312"></A>
<A NAME="IDX1313"></A>
String expansion is not applied to this option. The argument must be a
colon-separated list of host names or IP addresses. Fallback hosts can also be
specified on routers and directors which then associate them with the addresses
they process;
<font color=green>
as for the <EM>hosts</EM> option without <EM>hosts_override</EM>, <EM>fallback_hosts</EM>
specified on the transport is used only if the address does not have its own
associated fallback host list. Unlike <EM>hosts</EM>, a setting of <EM>fallback_hosts</EM>
on an address is not overridden by <EM>hosts_override</EM>, and neither does
<EM>hosts_randomize</EM> apply to fallback host lists.
</font>

</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 <EM>max_rcpt</EM> 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
<EM>gethostbyname()</EM> and <EM>mx_domains</EM> options, as for the <EM>hosts</EM> option.
Fallback hosts apply both to cases when the host list comes with the address
and when it is taken from <EM>hosts</EM>. This option provides a `use a smart host
only if delivery fails' facility.

</P>
<P>
<A NAME="IDX1314"></A>


<H3><A NAME="SEC552" HREF="spec_toc.html#TOC552">final_timeout (smtp)</A></H3>

<P>
Type: time<BR>
Default: 10m

</P>
<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>
<A NAME="IDX1315"></A>


<H3><A NAME="SEC553" HREF="spec_toc.html#TOC553">gethostbyname (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true when the <EM>hosts</EM> and/or <EM>fallback_hosts</EM> options are
being used, names are looked up using <EM>gethostbyname()</EM> instead of using the
DNS
with MX processing.
Of course, <EM>gethostbyname()</EM> may in fact use the DNS to look up A (but not MX)
records, but it may also consult other sources of information such as
<EM>/etc/hosts</EM>.

</P>
<P>
<A NAME="IDX1316"></A>


<H3><A NAME="SEC554" HREF="spec_toc.html#TOC554">hosts (smtp)</A></H3>

<P>
Type: string list, expanded<BR>
Default: unset

</P>
<P>
Hosts are associated with an address by a router such as <EM>lookuphost</EM>, which
finds the hosts by looking up the address domain in the DNS. However, addresses
can be passed to the <EM>smtp</EM> transport by any router or director, not all of
which provide an associated host list. This option specifies a list of
hosts which are used if the address being processed does not have any hosts
associated with it, or if the <EM>hosts_override</EM> option is set.

</P>
<P>
The string is first expanded, before being interpreted as a colon-separated
list of host names or IP addresses.
<font color=green>
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 in the DNS (using MX processing) or using
<EM>gethostbyname()</EM>, depending on the setting of the <EM>gethostbyname</EM> option. When
Exim is compiled with IPv6 support, if a host that is looked up in the DNS has
both A and AAAA or A6 records, all the addresses are used.
</font>

</P>
<P>
This option is typically used in association with a <EM>smartuser</EM> director that
wants to direct messages to a particular host or hosts. The given hosts are
tried in order, subject to their retry status. This option is ignored when the
address has been routed by a router that supplies a host list (for example,
<EM>lookuphost</EM>),
unless <EM>hosts_override</EM> is set.

</P>
<P>
<font color=green>
<A NAME="IDX1317"></A>


<H3><A NAME="SEC555" HREF="spec_toc.html#TOC555">hosts_avoid_tls (smtp)</A></H3>

<P>
Type: host list<BR>
Default: unset

</P>
<P>
<A NAME="IDX1318"></A>
Exim will not try to start a TLS session when delivering to any host that
matches this list. See chapter 38 for details of TLS.

</P>
<P>
<A NAME="IDX1319"></A>


<H3><A NAME="SEC556" HREF="spec_toc.html#TOC556">hosts_require_tls (smtp)</A></H3>

<P>
Type: host list<BR>
Default: unset

</P>
<P>
<A NAME="IDX1320"></A>
Exim will insist on using a TLS session when delivering to any host that
matches this list. See chapter 38 for details of TLS.
</font>

</P>
<P>
<A NAME="IDX1321"></A>


<H3><A NAME="SEC557" HREF="spec_toc.html#TOC557">hosts_override (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is set and the <EM>hosts</EM> option is also set, any hosts that
are attached to the address are ignored, and instead the hosts specified by the
<EM>hosts</EM> option are always used.
<font color=green>
This option does not apply to <EM>fallback_hosts</EM>.
</font>

</P>
<P>
<font color=green>
<A NAME="IDX1322"></A>


<H3><A NAME="SEC558" HREF="spec_toc.html#TOC558">hosts_max_try (smtp)</A></H3>

<P>
Type: integer<BR>
Default: 5

</P>
<P>
<A NAME="IDX1323"></A>
<A NAME="IDX1324"></A>
This option limits the number of IP addresses that will be tried for any one
delivery. Some large domains have very many MX records, each of which may refer
to several IP addresses. Trying every single one of 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. The value of
<EM>hosts_max_try</EM> is the maximum number of IP addresses that will actually be
tried; any that are skipped because their retry times have not arrived do not
count.

</P>
<P>
<A NAME="IDX1325"></A>


<H3><A NAME="SEC559" HREF="spec_toc.html#TOC559">hosts_randomize (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1326"></A>
<A NAME="IDX1327"></A>
If this option is set on an <EM>smtp</EM> transport that uses its hosts list, the
order of items in the list is randomized each time it is used. This does not
apply to <EM>fallback_hosts</EM>.
</font>

</P>

<P>
<A NAME="IDX1328"></A>
<A NAME="IDX1329"></A>
<A NAME="IDX1330"></A>


<H3><A NAME="SEC560" HREF="spec_toc.html#TOC560">interface (smtp)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
This option specifies which interface to bind to when making an outgoing SMTP
call. The string must be an IP address, for example:

<PRE>
interface = 192.168.123.123
</PRE>

<P>
If <EM>interface</EM> is not set, the system's IP functions choose which interface to
use if there is more than one. In an IPv6 system, the type of interface
specified must be of the same kind as the address to which the call is being
made. If not, it is ignored.

</P>
<P>
<A NAME="IDX1331"></A>


<H3><A NAME="SEC561" HREF="spec_toc.html#TOC561">keepalive (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<P>
This option controls the setting of SO_KEEPALIVE on outgoing socket
connections. This causes the kernel periodically to send some OOB (out-of-band)
data on idle connections. The option is provided for symmetry with the global
<EM>smtp_accept_keepalive</EM>
option that has the same effect on incoming SMTP connections.

</P>
<P>
<A NAME="IDX1332"></A>


<H3><A NAME="SEC562" HREF="spec_toc.html#TOC562">max_rcpt (smtp)</A></H3>

<P>
Type: integer<BR>
Default: 100

</P>
<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 <EM>remote_max_parallel</EM>
permits this.

</P>
<P>
<A NAME="IDX1333"></A>


<H3><A NAME="SEC563" HREF="spec_toc.html#TOC563">multi_domain (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<P>
When this option is set, the <EM>smtp</EM> 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 $<EM>domain</EM> in an
expansion for the transport, because it is set only when there is a single
domain involved in a remote delivery.

</P>
<P>
<A NAME="IDX1334"></A>


<H3><A NAME="SEC564" HREF="spec_toc.html#TOC564">mx_domains (smtp)</A></H3>

<P>
Type: domain list<BR>
Default: unset

</P>
<P>
If the <EM>hosts</EM> or <EM>fallback_hosts</EM> options are being used and names are being
looked up in the DNS, that is, the <EM>gethostbyname</EM> option is <EM>not</EM> set,
any domain name that matches this list is required to have an MX record; an
A record is not sufficient.

</P>
<P>
<A NAME="IDX1335"></A>


<H3><A NAME="SEC565" HREF="spec_toc.html#TOC565">port (smtp)</A></H3>

<P>
Type: string<BR>
Default: see below

</P>
<P>
<A NAME="IDX1336"></A>
<A NAME="IDX1337"></A>
<font color=green>
This option specifies the TCP/IP port on the server to which Exim connects. If
it begins with a digit it is taken as a port number; otherwise it is looked up
using <EM>getservbyname()</EM>. The default value is normally `smtp', but if
<EM>protocol</EM> is set to `lmtp', the default is `lmtp'.
</font>

</P>
<P>
<font color=green>
<A NAME="IDX1338"></A>


<H3><A NAME="SEC566" HREF="spec_toc.html#TOC566">protocol (smtp)</A></H3>

<P>
Type: string<BR>
Default: "smtp"

</P>
<P>
<A NAME="IDX1339"></A>
If this option is set to `lmtp' instead of `smtp', the default value for the
<EM>port</EM> 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 17.
</font>

</P>
<P>
<A NAME="IDX1340"></A>


<H3><A NAME="SEC567" HREF="spec_toc.html#TOC567">retry_include_ip_address (smtp)</A></H3>

<P>
Type: boolean<BR>
Default: true

</P>
<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 <EM>smtp</EM> transport, set up specially to handle the dialup hosts.

</P>
<P>
<A NAME="IDX1341"></A>


<H3><A NAME="SEC568" HREF="spec_toc.html#TOC568">serialize_hosts (smtp)</A></H3>

<P>
Type: host list<BR>
Default: unset

</P>
<P>
<A NAME="IDX1342"></A>
<A NAME="IDX1343"></A>
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
<EM>serialize_hosts</EM> 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, and 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>
However, if you set up any serialization, you should also arrange to delete the
hints database whenever your system reboots. The names of the files all start
with <EM>serialize-&#60;<EM>transport name</EM>&#62;</EM> and they are kept in the <EM>spool/db</EM>
directory. There may be one or two files per serialized transport, depending on
the type of DBM in use.

</P>
<P>
<A NAME="IDX1344"></A>


<H3><A NAME="SEC569" HREF="spec_toc.html#TOC569">service (smtp)</A></H3>

<P>
Type: string<BR>
Default: "smtp"

</P>
<P>
This option is a synonym for the <EM>port</EM> option.

</P>
<P>
<A NAME="IDX1345"></A>


<H3><A NAME="SEC570" HREF="spec_toc.html#TOC570">size_addition (smtp)</A></H3>

<P>
Type: integer<BR>
Default: 1024

</P>
<P>
<A NAME="IDX1346"></A>
<A NAME="IDX1347"></A>
<A NAME="IDX1348"></A>
<A NAME="IDX1349"></A>
<A NAME="IDX1350"></A>
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 <EM>size_addition</EM> 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 <EM>size_addition</EM> is set negative, it disables
the use of the SIZE option altogether.

</P>

<P>
<font color=green>

</P>
<P>
<A NAME="IDX1351"></A>


<H3><A NAME="SEC571" HREF="spec_toc.html#TOC571">tls_certificate (smtp)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
<A NAME="IDX1352"></A>
The value of this option is expanded, and must then be the absolute path to a
file which contains the client's certificate, for use when sending a message
over an encrypted connection. The values of $<EM>host</EM> and $<EM>host_address</EM> are
set to the name and address of the server during the expansion. See chapter
38 for details of TLS.

</P>
<P>
<A NAME="IDX1353"></A>


<H3><A NAME="SEC572" HREF="spec_toc.html#TOC572">tls_privatekey (smtp)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
The value of this option is expanded, and must then be the absolute path to
a file which contains the client's private key, for use when sending a message
over an encrypted connection. The values of $<EM>host</EM> and $<EM>host_address</EM> are
set to the name and address of the server during the expansion. See chapter
38 for details of TLS.

</P>
<P>
<A NAME="IDX1354"></A>


<H3><A NAME="SEC573" HREF="spec_toc.html#TOC573">tls_verify_certificates (smtp)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
The value of this option is expanded, and must then be the absolute path to a
file or a directory containing permitted server certificates, for use when
setting up an encrypted connection. The values of $<EM>host</EM> and
$<EM>host_address</EM> are set to the name and address of the server during the
expansion. See chapter 38 for details of TLS.

</P>
<P>
<A NAME="IDX1355"></A>


<H3><A NAME="SEC574" HREF="spec_toc.html#TOC574">tls_verify_ciphers (smtp)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
The value of this option is expanded, and must then be a list of permitted
ciphers, for use when setting up an encrypted connection. The values of
$<EM>host</EM> and $<EM>host_address</EM> are set to the name and address of the server
during the expansion. See chapter 38 for details of TLS.
</font>

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_18.html">previous</A>, <A HREF="spec_20.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>