See also the Policy controls section above.

Those options that undergo string expansion before use are marked with †.

This option causes Exim to send 8BITMIME in its response to an SMTP EHLO command, and to accept the BODY= parameter on MAIL commands. However, though Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to do anything special with messages received by this route. Consequently, this option is turned off by default.

This option defines the ACL that is run when a non-SMTP message has been read and is on the point of being accepted. See chapter 40 for further details.

This option defines the ACL that is run for individual MIME parts of non-SMTP messages. It operates in exactly the same way as acl_smtp_mime operates for SMTP messages.

This option defines the ACL that is run before Exim starts reading a non-SMTP message. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP AUTH command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP connection is received. See chapter 40 for further details.

This option defines the ACL that is run after an SMTP DATA command has been processed and the message itself has been received, but before the final acknowledgement is sent. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP ETRN command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP EXPN command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP EHLO or HELO command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP MAIL command is received. See chapter 40 for further details.

This option defines the ACL that is run when there is an AUTH parameter on a MAIL command. See chapter 40 for details of ACLs, and chapter 33 for details of authentication.

This option is available when Exim is built with the content-scanning extension. It defines the ACL that is run for each MIME part in a message. See section 41.4 for details.

This option defines the ACL that is run when an SMTP DATA command is received, before the message itself is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP QUIT command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP RCPT command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP STARTTLS command is received. See chapter 40 for further details.

This option defines the ACL that is run when an SMTP VRFY command is received. See chapter 40 for further details.

This option is expanded just once, at the start of Exim’s processing. If the current group or any of the supplementary groups of an Exim caller is in this colon-separated list, the caller has admin privileges. If all your system programmers are in a specific group, for example, you can give them all Exim admin privileges by putting that group in admin_groups. However, this does not permit them to read Exim’s spool files (whose group owner is the Exim gid). To permit this, you have to add individuals to the Exim group.

If this option is set, the RFC 2822 domain literal format is permitted in email addresses. The option is not set by default, because the domain literal format is not normally required these days, and few people know about it. It has, however, been exploited by mail abusers.

Unfortunately, it seems that some DNS black list maintainers are using this format to report black listing to postmasters. If you want to accept messages addressed to your hosts by IP address, you need to set allow_domain_literals true, and also to add @[] to the list of local domains (defined in the named domain list local_domains in the default configuration). This “magic string” matches the domain literal form of all the local host’s IP addresses.

It appears that more and more DNS zone administrators are breaking the rules and putting domain names that look like IP addresses on the right hand side of MX records. Exim follows the rules and rejects this, giving an error message that explains the mis-configuration. However, some other MTAs support this practice, so to avoid “Why can’t Exim do this?” complaints, allow_mx_to_ip exists, in order to enable this heinous activity. It is not recommended, except when you have no other choice.

Lots of discussion is going on about internationalized domain names. One camp is strongly in favour of just using UTF-8 characters, and it seems that at least two other MTAs permit this. This option allows Exim users to experiment if they wish.

If it is set true, Exim’s domain parsing function allows valid UTF-8 multicharacters to appear in domain name components, in addition to letters, digits, and hyphens. However, just setting this option is not enough; if you want to look up these domain names in the DNS, you must also adjust the value of dns_check_names_pattern to match the extended form. A suitable setting is:

dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\
  (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$

Alternatively, you can just disable this feature by setting

dns_check_names_pattern =

That is, set the option to an empty string so that no check is done.

If any server authentication mechanisms are configured, Exim advertises them in response to an EHLO command only if the calling host matches this list. Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands from clients to which it has not advertised the availability of AUTH. The advertising of individual authentication mechanisms can be controlled by the use of the server_advertise_condition generic authenticator option on the individual authenticators. See chapter 33 for further details.

Certain mail clients (for example, Netscape) require the user to provide a name and password for authentication if AUTH is advertised, even though it may not be needed (the host may accept messages from hosts on its local LAN without authentication, for example). The auth_advertise_hosts option can be used to make these clients more friendly by excluding them from the set of hosts to which Exim advertises AUTH.

If you want to advertise the availability of AUTH only when the connection is encrypted using TLS, you can make use of the fact that the value of this option is expanded, with a setting like this:

auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}}

If $tls_cipher is empty, the session is not encrypted, and the result of the expansion is empty, thus matching no hosts. Otherwise, the result of the expansion is *, which matches all hosts.

If this option is set to a time greater than zero, a queue runner will try a new delivery attempt on any frozen message, other than a bounce message, if this much time has passed since it was frozen. This may result in the message being re-frozen if nothing has changed since the last attempt. It is a way of saying “keep on trying, even though there are big problems”.

Note: This is an old option, which predates timeout_frozen_after and ignore_bounce_errors_after. It is retained for compatibility, but it is not thought to be very useful any more, and its use should probably be avoided.

This option is available if Exim is built with the content-scanning extension. It specifies which anti-virus scanner to use. The default value is:

sophie:/var/run/sophie

If the value of av_scanner starts with dollar character, it is expanded before use. See section 41.1 for further details.

This option supplies the name of a command that is run when Exim is called with the -bi option (see chapter 5). The string value is just the command name, it is not a complete command line. If an argument is required, it must come from the -oA command line option.

This option defines a template file containing paragraphs of text to be used for constructing bounce messages. Details of the file’s contents are given in chapter 46. See also warn_message_file.

When this option is set, its contents are included in the default bounce message immediately after “This message was created automatically by mail delivery software.” It is not used if bounce_message_file is set.

This option controls whether the body of an incoming message is included in a bounce message when bounce_return_message is true. The default setting causes the entire message, both header and body, to be returned (subject to the value of bounce_return_size_limit). If this option is false, only the message header is included. In the case of a non-SMTP message containing an error that is detected during reception, only those header lines preceding the point at which the error was detected are returned.

If this option is set false, none of the original message is included in bounce messages generated by Exim. See also bounce_return_size_limit and bounce_return_body.

This option sets a limit in bytes on the size of messages that are returned to senders as part of bounce messages when bounce_return_message is true. The limit should be less than the value of the global message_size_limit and of any message_size_limit settings on transports, to allow for the bounce text that Exim generates. If this option is set to zero there is no limit.

When the body of any message that is to be included in a bounce message is greater than the limit, it is truncated, and a comment pointing this out is added at the top. The actual cutoff may be greater than the value given, owing to the use of buffering for transferring the message in chunks (typically 8K in size). The idea is to save bandwidth on those undeliverable 15-megabyte messages.

This option provides an authenticated sender address that is sent with any bounce messages generated by Exim that are sent over an authenticated SMTP connection. A typical setting might be:

bounce_sender_authentication = mailer-daemon@my.domain.example

which would cause bounce messages to be sent using the SMTP command:

MAIL FROM:<> AUTH=mailer-daemon@my.domain.example

The value of bounce_sender_authentication must always be a complete email address.

This option specifies the expiry time for negative callout cache data for a domain. See section 40.34 for details of callout verification, and section 40.36 for details of the caching.

This option specifies the expiry time for positive callout cache data for a domain. See section 40.34 for details of callout verification, and section 40.36 for details of the caching.

This option specifies the expiry time for negative callout cache data for an address. See section 40.34 for details of callout verification, and section 40.36 for details of the caching.

This option specifies the expiry time for positive callout cache data for an address. See section 40.34 for details of callout verification, and section 40.36 for details of the caching.

This option defines the “random” local part that can be used as part of callout verification. The default value is

$primary_host_name-$tod_epoch-testing

See section 40.35 for details of how this value is used.

See check_spool_space below.

See check_spool_space below.

RFC 2047 defines a way of encoding non-ASCII characters in headers using a system of “encoded words”. The RFC specifies a maximum length for an encoded word; strings to be encoded that exceed this length are supposed to use multiple encoded words. By default, Exim does not recognize encoded words that exceed the maximum length. However, it seems that some software, in violation of the RFC, generates overlong encoded words. If check_rfc2047_length is set false, Exim recognizes encoded words of any length.

See check_spool_space below.

The four check_... options allow for checking of disk resources before a message is accepted.

When any of these options are set, they apply to all incoming messages. If you want to apply different checks to different kinds of message, you can do so by testing the variables $log_inodes, $log_space, $spool_inodes, and $spool_space in an ACL with appropriate additional conditions.

check_spool_space and check_spool_inodes check the spool partition if either value is greater than zero, for example:

check_spool_space = 10M
check_spool_inodes = 100

The spool partition is the one that contains the directory defined by SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit.

check_log_space and check_log_inodes check the partition in which log files are written if either is greater than zero. These should be set only if log_file_path and spool_directory refer to different partitions.

If there is less space or fewer inodes than requested, Exim refuses to accept incoming mail. In the case of SMTP input this is done by giving a 452 temporary error response to the MAIL command. If ESMTP is in use and there was a SIZE parameter on the MAIL command, its value is added to the check_spool_space value, and the check is performed even if check_spool_space is zero, unless no_smtp_check_spool_space is set.

The values for check_spool_space and check_log_space are held as a number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up.

For non-SMTP input and for batched SMTP input, the test is done at start-up; on failure a message is written to stderr and Exim exits with a non-zero code, as it obviously cannot send an error message of any kind.

This option specifies one or more default SMTP ports on which the Exim daemon listens. See chapter 13 for details of how it is used. For backward compatibility, daemon_smtp_port (singular) is a synonym.

This option, along with daemon_startup_sleep, controls the retrying done by the daemon at startup when it cannot immediately bind a listening socket (typically because the socket is already in use): daemon_startup_retries defines the number of retries after the first failure, and daemon_startup_sleep defines the length of time to wait between retries.

See daemon_startup_retries.

When a message is delayed, Exim sends a warning message to the sender at intervals specified by this option. The data is a colon-separated list of times after which to send warning messages. If the value of the option is an empty string or a zero time, no warnings are sent. Up to 10 times may be given. If a message has been on the queue for longer than the last time, the last interval between the times is used to compute subsequent warning times. For example, with

delay_warning = 4h:8h:24h

the first message is sent after 4 hours, the second after 8 hours, and the third one after 24 hours. After that, messages are sent every 16 hours, because that is the interval between the last two times on the list. If you set just one time, it specifies the repeat interval. For example, with:

delay_warning = 6h

messages are repeated every six hours. To stop warnings after a given time, set a very large time at the end of the list. For example:

delay_warning = 2h:12h:99d

The string is expanded at the time a warning message might be sent. If all the deferred addresses have the same domain, it is set in $domain during the expansion. Otherwise $domain is empty. If the result of the expansion is a forced failure, an empty string, or a string matching any of “0”, “no” or “false” (the comparison being done caselessly) then the warning message is not sent. The default is:

delay_warning_condition = ${if or {\
  { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\
  { match{$h_precedence:}{(?i)bulk|list|junk} }\
  { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\
  } {no}{yes}}

This suppresses the sending of warnings for messages that contain List-ID:, List-Post:, or List-Subscribe: headers, or have “bulk”, “list” or “junk” in a Precedence: header, or have “auto-generated” or “auto-replied” in an Auto-Submitted: header.

If this option is set true, Exim drops its root privilege at the start of a delivery process, and runs as the Exim user throughout. This severely restricts the kinds of local delivery that are possible, but is viable in certain types of configuration. There is a discussion about the use of root privilege in chapter 52.

When this option is set, a queue run is abandoned if the system load average becomes greater than the value of the option. The option has no effect on ancient operating systems on which Exim cannot determine the load average. See also queue_only_load and smtp_load_reserve.

Exim’s transports have an option for adding a Delivery-date: header to a message when it is delivered, in exactly the same way as Return-path: is handled. Delivery-date: records the actual time of delivery. Such headers should not be present in incoming messages, and this option causes them to be removed at the time the message is received, to avoid any problems that might occur when a delivered message is subsequently sent on to some other recipient.

If this option is set true, even if the Exim binary has IPv6 support, no IPv6 activities take place. AAAA records are never looked up, and any IPv6 addresses that are listed in local_interfaces, data for the manualroute router, etc. are ignored. If IP literals are enabled, the ipliteral router declines to handle IPv6 literal addresses.

DNS lookups give a “try again” response for the DNS errors “non-authoritative host not found” and “SERVERFAIL”. This can cause Exim to keep trying to deliver a message, or to give repeated temporary errors to incoming mail. Sometimes the effect is caused by a badly set up name server and may persist for a long time. If a domain which exhibits this problem matches anything in dns_again_means_nonexist, it is treated as if it did not exist. This option should be used with care. You can make it apply to reverse lookups by a setting such as this:

dns_again_means_nonexist = *.in-addr.arpa

This option applies to all DNS lookups that Exim does. It also applies when the gethostbyname() or getipnodebyname() functions give temporary errors, since these are most likely to be caused by DNS lookup problems. The dnslookup router has some options of its own for controlling what happens when lookups for MX or SRV records give temporary errors. These more specific options are applied after this global option.

When this option is set to a non-empty string, it causes Exim to check domain names for characters that are not allowed in host names before handing them to the DNS resolver, because some resolvers give temporary errors for names that contain unusual characters. If a domain name contains any unwanted characters, a “not found” result is forced, and the resolver is not called. The check is done by matching the domain name against a regular expression, which is the value of this option. The default pattern is

dns_check_names_pattern = \
  (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$

which permits only letters, digits, slashes, and hyphens in components, but they must start and end with a letter or digit. Hyphens are not, in fact, permitted in host names, but they are found in certain NS records (which can be accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you must modify this pattern, or set the option to an empty string.

This option controls the depth of parental searching for CSA SRV records in the DNS, as described in more detail in section 40.39.

This option controls whether or not an IP address, given as a CSA domain, is reversed and looked up in the reverse DNS, as described in more detail in section 40.39.

When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks for IPv6 address records (AAAA records) as well as IPv4 address records (A records) when trying to find IP addresses for hosts, unless the host’s domain matches this list.

This is a fudge to help with name servers that give big delays or otherwise do not work for the AAAA record type. In due course, when the world’s name servers have all been upgraded, there should be no need for this option.

The options dns_retrans and dns_retry can be used to set the retransmission and retry parameters for DNS lookups. Values of zero (the defaults) leave the system default settings unchanged. The first value is the time between retries, and the second is the number of retries. It isn’t totally clear exactly how these settings affect the total time a DNS lookup may take. I haven’t found any documentation about timeouts on DNS lookups; these parameter values are available in the external resolver interface structure, but nowhere does it seem to describe how they are used or what you might want to set in them.

See dns_retrans above.

This is an obsolete option that is now a no-op. It used to affect the way Exim handled CR and LF characters in incoming messages. What happens now is described in section 44.2.

Exim’s transports have an option for adding an Envelope-to: header to a message when it is delivered, in exactly the same way as Return-path: is handled. Envelope-to: records the original recipient address from the messages’s envelope that caused the delivery to happen. Such headers should not be present in incoming messages, and this option causes them to be removed at the time the message is received, to avoid any problems that might occur when a delivered message is subsequently sent on to some other recipient.

Setting this option causes Exim to send bcc copies of bounce messages that it generates to other addresses. Note: This does not apply to bounce messages coming from elsewhere. The value of the option is a colon-separated list of items. Each item consists of a pattern, terminated by white space, followed by a comma-separated list of email addresses. If a pattern contains spaces, it must be enclosed in double quotes.

Each pattern is processed in the same way as a single item in an address list (see section 10.18). When a pattern matches the recipient of the bounce message, the message is copied to the addresses on the list. The items are scanned in order, and once a matching one is found, no further items are examined. For example:

errors_copy = spqr@mydomain   postmaster@mydomain.example :\
              rqps@mydomain   hostmaster@mydomain.example,\
                              postmaster@mydomain.example

The address list is expanded before use. The expansion variables $local_part and $domain are set from the original recipient of the error message, and if there was any wildcard matching in the pattern, the expansion variables $0, $1, etc. are set in the normal way.

By default, Exim’s bounce and delivery warning messages contain the header line

where qualify-domain is the value of the qualify_domain option. A warning message that is generated by the quota_warn_message option in an appendfile transport may contain its own From: header line that overrides the default.

Experience shows that people reply to bounce messages. If the errors_reply_to option is set, a Reply-To: header is added to bounce and warning messages. For example:

errors_reply_to = postmaster@my.domain.example

The value of the option is not expanded. It must specify a valid RFC 2822 address. However, if a warning message that is generated by the quota_warn_message option in an appendfile transport contain its own Reply-To: header line, the value of the errors_reply_to option is not used.

This option changes the gid under which Exim runs when it gives up root privilege. The default value is compiled into the binary. The value of this option is used only when exim_user is also set. Unless it consists entirely of digits, the string is looked up using getgrnam(), and failure causes a configuration error. See chapter 52 for a discussion of security issues.

This option specifies the path name of the Exim binary, which is used when Exim needs to re-exec itself. The default is set up to point to the file exim in the directory configured at compile time by the BIN_DIRECTORY setting. It is necessary to change exim_path if, exceptionally, Exim is run from some other place. Warning: Do not use a macro to define the value of this option, because you will break those Exim utilities that scan the configuration file to find where the binary is. (They then use the -bP option to extract option settings such as the value of spool_directory.)

This option changes the uid under which Exim runs when it gives up root privilege. The default value is compiled into the binary. Ownership of the run time configuration file and the use of the -C and -D command line options is checked against the values in the binary, not what is set here.

Unless it consists entirely of digits, the string is looked up using getpwnam(), and failure causes a configuration error. If exim_group is not also supplied, the gid is taken from the result of getpwnam() if it is used. See chapter 52 for a discussion of security issues.

This option defines network interfaces that are to be considered local when routing, but which are not used for listening by the daemon. See section 13.8 for details.

According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses are present on the command line when the -t option is used to build an envelope from a message’s To:, Cc: and Bcc: headers, the command line addresses are removed from the recipients list. This is also how Smail behaves. However, other Sendmail documentation (the O’Reilly book) states that command line addresses are added to those obtained from the header lines. When extract_addresses_remove_arguments is true (the default), Exim subtracts argument headers. If it is set false, Exim adds rather than removes argument addresses.

On systems running NIS or other schemes in which user and group information is distributed from a remote system, there can be times when getpwnam() and related functions fail, even when given valid data, because things time out. Unfortunately these failures cannot be distinguished from genuine “not found” errors. If finduser_retries is set greater than zero, Exim will try that many extra times to find a user or a group, waiting for one second between retries.

You should not set this option greater than zero if your user information is in a traditional /etc/passwd file, because it will cause Exim needlessly to search the file multiple times for non-existent users, and also cause delay.

On encountering certain errors, or when configured to do so in a system filter, ACL, or special router, Exim freezes a message. This means that no further delivery attempts take place until an administrator thaws the message, or the auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it to be processed. If freeze_tell is set, Exim generates a warning message whenever it freezes something, unless the message it is freezing is a locally-generated bounce message. (Without this exception there is the possibility of looping.) The warning message is sent to the addresses supplied as the comma-separated value of this option. If several of the message’s addresses cause freezing, only a single message is sent. If the freezing was automatic, the reason(s) for freezing can be found in the message log. If you configure freezing in a filter or ACL, you must arrange for any logging that you require.

Some operating systems, notably HP-UX, use the “gecos” field in the system password file to hold other information in addition to users’ real names. Exim looks up this field for use when it is creating Sender: or From: headers. If either gecos_pattern or gecos_name are unset, the contents of the field are used unchanged, except that, if an ampersand is encountered, it is replaced by the user’s login name with the first character forced to upper case, since this is a convention that is observed on many systems.

When these options are set, gecos_pattern is treated as a regular expression that is to be applied to the field (again with & replaced by the login name), and if it matches, gecos_name is expanded and used as the user’s name.

Numeric variables such as $1, $2, etc. can be used in the expansion to pick up sub-fields that were matched by the pattern. In HP-UX, where the user’s name terminates at the first comma, the following can be used:

gecos_pattern = ([^,]*)
gecos_name = $1

See gecos_name above.