

The smtp transport

The `smtp' 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 "Retry configuration") is applied to each IP address independently. The private options are as follows:

allow_localhost (smtp) option

Option: allow_localhost
Type: boolean
Default: false

When a host specified in `hosts' or `fallback_hosts' (see below) turns out to be the local host, Exim freezes the message by default. However, if `allow_localhost' 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).

batch_max (smtp) option

Option: batch_max
Type: integer
Default: 0

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.

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) `batch_max' value, no further messages are sent on the same TCP/IP connection.

For testing purposes, this value can be overridden by the `-oB' command line option.

command_timeout (smtp) option

Option: command_timeout
Type: time
Default: 5m

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.

connect_timeout (smtp) option

Option: connect_timeout
Type: time
Default: 0s

This sets a timeout for the `connect()' 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.

data_timeout (smtp) option

Option: data_timeout
Type: time
Default: 5m

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.

delay_after_cutoff (smtp) option

Option: delay_after_cutoff
Type: boolean
Default: true

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.

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...

If `delay_after_cutoff' is set false, Exim behaves differently. If all IP addresses are past their final cutoff time, then 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 addresses that haven't been tried since the message arrived. If there is a continuous stream of messages for the dead hosts, unsetting `delay_after_cutoff' means that there will be many more attempts to deliver to them.

dns_qualify_single (smtp) option

Option: dns_qualify_single
Type: boolean
Default: true

If the `hosts' or `fallback_hosts' option is being used and names are being looked up in the DNS, then the option to cause the resolver to qualify single-component names with the local domain is set.

dns_search_parents (smtp) option

Option: dns_search_parents
Type: boolean
Default: false

If the `hosts' or `fallback_hosts' option is being used and names are being looked up in the DNS, then 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.

fallback_hosts (smtp) option

Option: fallback_hosts
Type: string-list
Default: unset

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; as for the `hosts' option, `fallback_hosts' specified on the transport is used only if the address does not have its own associated fallback host list.

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.

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 `max_rcpt' permits it), a single copy of the message is sent.

The resolution of the host names on the fallback list is controlled by the `gethostbyname()', `mx_domains' and `mx_domains_except' options, as for the `hosts' option. Fallback hosts apply both to cases when the host list comes with the address and when it is taken from `hosts'. This option provides a `use a smart host only if delivery fails' facility.

final_timeout (smtp) option

Option: final_timeout
Type: time
Default: 10m

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.

gethostbyname (smtp) option

Option: gethostbyname
Type: boolean
Default: false

If this option is true when the `hosts' and/or `fallback_hosts' options are being used, names are looked up using `gethostbyname()' instead of using the DNS. Of course, `gethostbyname()' 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 `/etc/hosts'.

hosts (smtp) option

Option: hosts
Type: string-list
Default: unset

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

The string is first expanded, before being interpreted as a colon-separated host list. The names are looked up either in the DNS or using `gethostbyname()', depending on the setting of the `gethostbyname' option. When Exim is compiled with IPv6 support, if a host that is looked up in the DNS has both A and AAAA records, all the addresses are used. See `README.IPV6' for general information about IPv6 support.

This option is typically used in association with a `smartuser' 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, `lookuphost').

interface (smtp) option

Option: interface
Type: string
Default: unset

This option specifies which interface to use when making an SMTP call. The string must be an IP address, for example:

interface =

If `interface' 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.

max_rcpt (smtp) option

Option: max_rcpt
Type: integer
Default: 100

This option limits the number of RCPT TO 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 `remote_max_parallel' permits this.

multi_domain (smtp) option

Option: multi_domain
Type: boolean
Default: true

When this option is set, the `smtp' 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.

mx_domains (smtp) option

Option: mx_domains
Type: domain-list
Default: unset

If the `hosts' or `fallback_hosts' options are being used and names are being looked up in the DNS, that is, the `gethostbyname' option is not set, then if the host name is in this list and not in `mx_domains_except', it is required to have an MX record.

mx_domains_except (smtp) option

Option: mx_domains_except
Type: domain-list
Default: unset

See `mx_domains' above. Note that this does not operate alone, nor prevent MX records being looked up. You should set the `gethostbyname' option if you want the domains in `hosts' or `fallback_hosts' to be looked up without MX processing.

non_mx_domains (smtp) option

Option: non_mx_domains
Type: domain-list
Default: unset

This is an obsolete synonym for the `mx_domains_except' option.

retry_include_ip_address (smtp) option

Option: retry_include_ip_address
Type: boolean
Default: true

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.

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

serialize_hosts (smtp) option

Option: serialize_hosts
Type: host-list
Default: unset

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 `serialize_hosts' or `serialize_nets' to match the relevant hosts.

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.

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 `serialize-<transport name>' and they are kept in the `spool/db' directory. There may be one or two files per serialized transport, depending on the type of DBM in use.

serialize_nets (smtp) option

Option: serialize_nets
Type: net-list
Default: unset

See `serialize_hosts' above.

service (smtp) option

Option: service
Type: string
Default: "smtp"

This option specifies the TCP/IP port that is used to send the message. If it begins with a digit it is taken as a port number; otherwise it is looked up using `getservbyname()'.

size_addition (smtp) option

Option: size_addition
Type: integer
Default: 1024

If a remote SMTP server indicates that it supports the SIZE option of the MAIL FROM command, Exim uses this to pass over the message size at the start of an SMTP transaction. It adds the value of `size_addition' to the value it sends, to allow for headers or 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.

Alternatively, if the value of `size_addition' is set negative, it disables the use of the SIZE option altogether.
