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 33) is applied to each IP address independently. The private options are as follows:
Type: boolean
Default: false
When a host specified in hosts or fallback_hosts (see below) turns out to be the local host, or is listed in hosts_treat_as_local, 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).
Type: host list
Default: unset
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.
Type: integer
batch_max (smtp)
Default: 500
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.
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.
Type: time
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. 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.
connect_timeout (smtp)
Default: 5m
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. See also final_timeout.
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, 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 delay_after_cutoff means that there will be many more attempts to deliver to them.
Type: boolean
Default: true
If the hosts or fallback_hosts 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.
Type: boolean
Default: false
If the hosts or fallback_hosts 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.
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 without hosts_override, fallback_hosts specified on the transport is used only if the address does not have its own associated fallback host list. Unlike hosts, a setting of fallback_hosts on an address is not overridden by hosts_override, and neither does hosts_randomize apply to fallback host lists.
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() and mx_domains 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.
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.
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 with MX processing. 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.
Type: string list, expanded
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 hosts which are used if the address being processed does not have any hosts associated with it, or if the hosts_override option is set.
The string is first expanded, before being interpreted as a colon-separated list of host names or IP addresses. 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 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 or A6 records, all the addresses are used.
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), unless hosts_override is set.
Type: host list
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.
Type: host list
Exim will insist on using a TLS session when delivering to any host that
matches this list. See chapter 38 for details of TLS.
hosts_avoid_tls (smtp)
Default: unset
hosts_require_tls (smtp)
Default: unset
Type: boolean
Default: false
If this option is set and the hosts option is also set, any hosts that are attached to the address are ignored, and instead the hosts specified by the hosts option are always used. This option does not apply to fallback_hosts.
Type: integer
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
hosts_max_try 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.
Type: boolean
If this option is set on an smtp 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 fallback_hosts.
hosts_max_try (smtp)
Default: 5
hosts_randomize (smtp)
Default: false
Type: string
Default: unset
This option specifies which interface to bind to when making an outgoing SMTP call. The string must be an IP address, for example:
interface = 192.168.123.123
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.
Type: boolean
Default: true
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 smtp_accept_keepalive option that has the same effect on incoming SMTP connections.
Type: integer
Default: 100
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 remote_max_parallel permits this.
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.
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, any domain name that matches this list is required to have an MX record; an A record is not sufficient.
Type: string
Default: see below
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 getservbyname(). The default value is normally `smtp', but if protocol is set to `lmtp', the default is `lmtp'.
Type: string
If this option is set to `lmtp' instead of `smtp', the default value for the
port 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.
protocol (smtp)
Default: "smtp"
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.
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 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.
Type: string
Default: "smtp"
This option is a synonym for the port option.
Type: integer
Default: 1024
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 size_addition 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.
Alternatively, if the value of size_addition is set negative, it disables the use of the SIZE option altogether.
Type: string, expanded
Default: unset
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 $host and $host_address are set to the name and address of the server during the expansion. See chapter 38 for details of TLS.
Type: string, expanded
Default: unset
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 $host and $host_address are set to the name and address of the server during the expansion. See chapter 38 for details of TLS.
Type: string, expanded
Default: unset
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 $host and $host_address are set to the name and address of the server during the expansion. See chapter 38 for details of TLS.
Type: string, expanded
Default: unset
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 $host and $host_address are set to the name and address of the server during the expansion. See chapter 38 for details of TLS.
Go to the first, previous, next, last section, table of contents.