The first part of the run time configuration file contains three types of item:
Macro definitions: These lines start with an upper case letter. See section 6.4 for details of macro processing.
Named list definitions: These lines start with one of the words ``domainlist'', ``hostlist'', ``addresslist'', or ``localpartlist''. Their use is described in section 10.5.
Main configuration settings: Each setting occupies one line of the file (including possible continuations). If any setting is preceded by the word ``hide'', the -bP option displays its value to admin users only (see section 6.5).
This chapter lists all the main configuration options, along with their types and default values, in alphabetical order.
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 an SMTP AUTH command is received. See chapter 37 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 37 for further details.
This option defines the ACL that is run when an SMTP ETRN command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP EXPN command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP RCPT command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP VRFY command is received. See chapter 37 for further details.
If the current group or any of the supplementary groups of the 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.
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, though it is always prepared to accept it.
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 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 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''. See also timeout_frozen_after and ignore_bounce_errors_after.
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 40. 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.
If this option is set false, the original message is not included in bounce messages generated by Exim. See also return_size_limit.
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.
See check_spool_space below.
See check_spool_space below.
See check_spool_space below.
The four check_... options allow for checking of disc resources before a message is accepted: 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 which contains the directory defined by SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit.
check_log_space and check_log_
Concepts
A B C D E F G H I J K L M N O P Q R S T U V W X
$header_
Many strings in Exim's run time configuration are expanded before use. Some of
them are expanded every time they are used; others are expanded only once.
When a string is being expanded it is copied verbatim from left to right except
when a dollar or backslash character is encountered. A dollar specifies the
start of a portion of the string which is interpreted and replaced as described
below in section 11.4 onwards. Backslash is used as an escape
character, as described in the following section.
An uninterpreted dollar can be included in an expanded string by putting a
backslash in front of it. A backslash can be used to prevent any special
character being treated specially in an expansion, including itself. If the
string appears in quotes in the configuration file, two backslashes are
required because the quotes themselves cause interpretation of backslashes when
the string is read in (see section 6.12).
A portion of the string can specified as non-expandable by placing it between
two occurrences of \N. This is particularly useful for protecting regular
expressions, which often contain backslashes and dollar signs. For example:
$value [2] [3]
*@
+caseful
+defer_unknown
+exclude_unknown
+include_unknown [2]
/dev/null
8-bit characters [2] [3]
8BITMIME
@ in a domain list
@ in a host list
@[] in a domain list
@[] in a host list
@mx_any
@mx_primary
@mx_secondary
A
abandoning mail [2]
accept router
ACL: condition processing
ACL: conditions, definition of
ACL: description
ACL: format
ACL: indirect
ACL: modifier processing
ACL: modifiers, definition of
ACL: nested
ACL: options for specifying
ACL: relay control
ACL: setting up for SMTP commands
ACL: specifying
ACL: unset
ACL: verbs, definition of
ACL: verifying header syntax
ACL: verifying HELO/EHLO
ACL: verifying host reverse lookup
ACL: verifying recipient
ACL: verifying sender [2]
adding drivers
additional groups [2]
address list: case forcing
address list: empty item
address list: in a rewriting pattern
address list: patterns
address rewriting
address: constructed
address: copying routing [2]
address: duplicated
address: qualification
address: rewriting [2]
address: sender
address: source-routed
address: testing [2]
address: verification
admin user [2] [3] [4] [5] [6] [7] [8]
admin user, definition of
alias file: backslash in
alias file: broken
alias file: building [2]
alias file: exception to default
alias file: in a redirect router
alias file: one-time expansion
alias file: ownership
alias file: per-domain default
alias for host
alternate configuration file
``and'' expansion condition
angle brackets, excess
appendfile transport
appending to a file
architecture type
asterisk after IP address
Athena
AUTH: ACL for
AUTH: advertising
AUTH: advertising when encrypted
AUTH: argument
AUTH: configuration [2]
AUTH: how it works
AUTH: in plaintext authenticator
AUTH: logging
AUTH: on bounce message
AUTH: on MAIL
11. String expansions
11.1. Literal text in expanded strings
deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
On encountering the first \N, the expander copies subsequent characters without interpretation until it reaches the next \N or the end of the string.
A backslash followed by one of the letters ``n'', ``r'', or ``t'' in an expanded string is recognized as an escape sequence for the character newline, carriage return, or tab, respectively. A backslash followed by up to three octal digits is recognized as an octal encoding for a single character, and a backslash followed by ``x'' and up to two hexadecimal digits is a hexadecimal encoding.
These escape sequences are also recognized in quoted strings when they are read in. Their interpretation in expansions as well is useful for unquoted strings, and for other cases such as looked-up strings that are then expanded.
The first part of the run time configuration file contains three types of item:
Macro definitions: These lines start with an upper case letter. See section 6.4 for details of macro processing.
Named list definitions: These lines start with one of the words ``domainlist'', ``hostlist'', ``addresslist'', or ``localpartlist''. Their use is described in section 10.5.
Main configuration settings: Each setting occupies one line of the file (with possible continuations). If any setting is preceded by the word ``hide'', the -bP command line option displays its value to admin users only. See section 6.6 for a description of the syntax of these option settings.
This chapter specifies all the main configuration options, along with their types and default values. For ease of finding a particular option, they appear in alphabetical order in section 13.22 below. However, because there are now so many options, they are first listed briefly in functional groups, as an aid to finding the name of the option you are looking for.
| bi_command | to run for -bi command line option |
| keep_malformed | for broken files - should not happen |
| localhost_number | for unique message ids in clusters |
| message_logs | keep per-message logs |
| message_body_visible | how much to show in $message_body |
| print_topbitchars | top-bit characters are printing |
| split_spool_directory | use multiple directories |
| timezone | force time zone |
| exim_group | override compiled-in value |
| exim_path | override compiled-in value |
| exim_user | override compiled-in value |
| primary_hostname | default from uname() |
| spool_directory | override compiled-in value |
| admin_groups | groups that are Exim admin users |
| deliver_drop_privilege | drop root for delivery processes |
| local_from_check | insert Sender: if necessary |
| local_from_prefix | for testing From: for local sender |
| local_from_suffix | for testing From: for local sender |
| never_users | do not run deliveries as these |
| prod_requires_admin | forced delivery requires admin user |
| queue_list_requires_admin | queue listing requires admin user |
| trusted_groups | groups that are trusted |
| trusted_users | users that are trusted |
| log_file_path | override compiled-in value |
| log_selector | set/unset optional logging |
| log_timezone | add timezone to log lines |
| preserve_message_logs | in another directory |
| syslog_facility | set syslog ``facility'' field |
| syslog_processname | set syslog ``ident'' field |
| syslog_timestamp | timestamp syslog lines |
| auto_thaw | sets time for retrying frozen messages |
| freeze_tell | send message when freezing |
| move_frozen_messages | to another directory |
| timeout_frozen_after | keep frozen messages only so long |
| ldap_default_servers | used if no server in query |
| ldap_version | set protocol version |
| lookup_open_max | lookup files held open |
| mysql_servers | as it says |
| oracle_servers | as it says |
| pgsql_servers | as it says |
| message_id_header_domain | used to build Message-ID: header |
| message_id_header_text | ditto |
| perl_at_start | always start the interpreter |
| perl_startup | code to obey when starting Perl |
| daemon_smtp_port | default port |
| local_interfaces | on which to listen, with optional ports |
| pid_file_path | override compiled-in value |
| check_log_inodes | before accepting a message |
| check_log_space | before accepting a message |
| check_spool_inodes | before accepting a message |
| check_spool_space | before accepting a message |
| deliver_queue_load_max | no queue deliveries if load high |
| smtp_load_reserve | SMTP from reserved hosts if load high |
| queue_only_load | queue incoming if load high |
| acl_not_smtp | set ACL for non-SMTP messages |
| acl_smtp_auth | set ACL for AUTH |
| acl_smtp_connect | set ACL for connection |
| acl_smtp_data | set ACL for DATA |
| acl_smtp_etrn | set ACL for ETRN |
| acl_smtp_expn | set ACL for EXPN |
| acl_smtp_helo | set ACL for EHLO or HELO |
| acl_smtp_mail | set ACL for MAIL |
| acl_smtp_rcpt | set ACL for RCPT |
| acl_smtp_starttls | set ACL for STARTTLS |
| acl_smtp_vrfy | set ACL for VRFY |
| header_maxsize | total size of message header |
| header_line_maxsize | individual header line limit |
| helo_verify_hosts | HELO checked for these hosts |
| host_lookup | host name looked up for these hosts |
| host_reject_connection | reject connection from these hosts |
| hosts_treat_as_local | useful in some cluster configurations |
| local_scan_timeout | timeout for local_scan() |
| message_size_limit | for all messages |
| percent_hack_domains | recognize %-hack for these domains |
| callout_domain_negative_expire | timeout for negative domain cache item |
| callout_domain_positive_expire | timeout for positive domain cache item |
| callout_negative_expire | timeout for negative address cache item |
| callout_positive_expire | timeout for positive address cache item |
| callout_random_local_part | string to use for ``random'' testing |
| tls_advertise_hosts | advertise TLS to these hosts |
| tls_certificate | location of server certificate |
| tls_dhparam | DH parameters for server |
| tls_privatekey | location of server private key |
| tls_try_verify_hosts | try to verify client certificate |
| tle_verify_certificates | expected client certificates |
| tls_verify_hosts | insist on client certificate verify |
| finduser_retries | useful in NIS environments |
| gecos_name | used when creating Sender: |
| gecos_pattern | ditto |
| max_username_length | for systems that truncate |
| unknown_login | used when no login name found |
| unknown_username | ditto |
| uucp_from_pattern | for recognizing ``From '' lines |
| uucp_from_sender | ditto |
| header_maxsize | total size of message header |
| header_line_maxsize | individual header line limit |
| percent_hack_domains | recognize %-hack for these domains |
| receive_timeout | for non-SMTP messages |
| received_header_text | expanded to make Received: |
| received_headers_max | for mail loop detection |
| recipient_unqualified_hosts | may send unqualified recipients |
| recipients_max | limit per message |
| recipients_max_reject | permantely reject excess |
| rfc1413_hosts | make ident calls to these hosts |
| rfc1413_query_timeout | zero disables ident calls |
| sender_unqualified_hosts | may send unqualified senders |
| smtp_accept_keepalive | some TCP/IP magic |
| smtp_accept_max | simultaneous incoming connections |
| smtp_accept_max_nommail | non-mail commands |
| smtp_accept_max_nonmail_hosts | hosts to which the limit applies |
| smtp_accept_max_per_connection | messages per connection |
| smtp_accept_max_per_host | connections from one host |
| smtp_accept_queue | queue mail if more connections |
| smtp_accept_queue_per_connection | queue if more messages per connection |
| smtp_accept_reserve | only reserve hosts if more connections |
| smtp_banner | text for welcome banner |
| smtp_check_spool_space | from SIZE on MAIL command |
| smtp_connect_backlog | passed to TCP/IP stack |
| smtp_enforce_sync | of SMTP command/responses |
| smtp_etrn_command | what to run for ETRN |
| smtp_etrn_serialize | only one at once |
| smtp_load_reserve | only reserve hosts if this load |
| smtp_max_unknown_commands | before dropping connection |
| smtp_ratelimit_hosts | apply ratelimiting to these hosts |
| smtp_ratelimit_mail | ratelimit for MAIL commands |
| smtp_ratelimit_rcpt | ratelimit for RCPT commands |
| smtp_receive_timeout | per command or data line |
| smtp_reserve_hosts | these are the reserve hosts |
| smtp_return_error_details | give detail on rejections |
| accept_8bitmime | advertise 8BITMIME |
| auth_advertise_hosts | advertise AUTH to these hosts |
| ignore_fromline_hosts | allow ``From '' from these hosts |
| ignore_fromline_local | allow ``From '' from local SMTP |
| pipelining_advertise_hosts | advertise pipelining to these hosts |
| tls_advertise_hosts | advertise TLS to these hosts |
| allow_domain_literals | recognize domain literal syntax |
| allow_mx_to_ip | allow MX to point to IP address |
| allow_utf8_domains | in addresses |
| delivery_date_remove | from incoming messages |
| drop_cr | from local incoming messages |
| envelope_to_remote | from incoming messages |
| extract_addresses_remove_arguments | affects -t processing |
| qualify_domain | default for senders |
| qualify_recipient | default for recipients |
| return_path_remove | from incoming messages |
| strip_excess_angle_brackets | in addresses |
| strip_trailing_dot | at end of addresses |
| untrusted_set_sender | untrusted can set envelope sender |
| system_filter | locate system filter |
| system_filter_directory_transport | transport for delivery to a directory |
| system_filter_file_transport | transport for delivery to a file |
| system_filter_group | group for filter running |
| system_filter_pipe_transport | transport for delivery to a pipe |
| system_filter_reply_transport | transport for autoreply delivery |
| system_filter_user | user for filter running |
| dns_again_means_nonexist | for broken domains |
| dns_check_names_pattern | pre-DNS syntax check |
| dns_ipv4_lookup | only v4 lookup for these domains |
| dns_retrans | parameter for resolver |
| dns_retry | parameter for resolver |
| hold_domains | hold delivery for these domains |
| local_interfaces | for routing checks |
| queue_domains | no immediate delivery for these |
| queue_only | no immediate delivery at all |
| queue_only_file | no immediate deliveryif file exists |
| queue_only_load | no immediate delivery if load is high |
| queue_run_in_order | order of arrival |
| queue_run_max | of simultaneous queue runners |
| queue_smtp_domains | no immediate SMTP delivery for these |
| remote_max_parallel | parallel SMTP delivery per message |
| remote_sort_domains | order of remote deliveries |
| retry_data_expire | timeout for retry data |
| retry_interval_max | safety net for retry rules |
| bounce_message_file | content of bounce |
| bounce_message_text | content of bounce |
| bounce_return_message | include original message in bounce |
| bounce_sender_authentication | send authenticated sender with bounce |
| errors_copy | copy bounce messages |
| errors_reply_to | Reply-to: in bounces |
| delay_warning | time schedule |
| delay_warning_condition | condition for warning messages |
| ignore_bounce_errors_after | discard undeliverable bounces |
| return_size_limit | limit on returned message |
| warn_message_file | content of warning message |
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 is on the point
of being accepted. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP connection is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP AUTH command is received. See chapter 37 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 37 for further details.
This option defines the ACL that is run when an SMTP ETRN command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP EXPN command is
received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP EHLO or HELO
command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP MAIL command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP RCPT command is
received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP STARTTLS command is received. See chapter 37 for further details.
This option defines the ACL that is run when an SMTP VRFY command is received. See chapter 37 for further details.
If the current group or any of the supplementary groups of the 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 32 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 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''. See also timeout_frozen_after and ignore_bounce_errors_after.
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 40. 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.
If this option is set false, the original message is not included in bounce messages generated by Exim. See also return_size_limit.
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 37.14 for details of callout verification, and section 37.16 for details of the caching.
This option specifies the expiry time for positive callout cache data for a domain. See section 37.14 for details of callout verification, and section 37.16 for details of the caching.
This option specifies the expiry time for negative callout cache data for an address. See section 37.14 for details of callout verification, and section 37.16 for details of the caching.
This option specifies the expiry time for positive callout cache data for an address. See section 37.14 for details of callout verification, and section 37.16 for details of the caching.
See check_spool_space below.
See check_spool_space below.
See check_spool_space below.
The four check_... options allow for checking of disk resources before a message is accepted: 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 which 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.
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 the default SMTP port on which the Exim daemon listens. It can either be given as a number, or as a service name. It can be overridden by giving an explicit port number on an IP address in the local_interfaces option, or by using -oX on the command line. If this option is not set, the service name ``smtp'' is used.
When a message is delayed, Exim sends a warning message to the sender at intervals specified by this option. If it is set to a zero, no warnings are sent. The data is a colon-separated list of times after which to send warning messages. 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 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 match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}}
which suppresses the sending of warnings about messages that have ``bulk'', ``list'' or ``junk'' in a Precedence: 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 47.
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.
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.
When this option is set to a non-empty string, it causes Exim to check domain names for illegal characters before handing them to the DNS resolver, because some resolvers give temporary errors for malformed names. If a domain name contains any illegal 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, and hyphens in components, but they may not start or end with a hyphen. If you set allow_utf8_domains, you must modify this pattern, or set the option to an empty string.
When Exim is compiled with IPv6 support, it looks for IPv6 address records (AAAA and, if configured, A6) as well as IPv4 address 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 new IPv6 record types. If Exim is handed an IPv6 address record as a result of an MX lookup, it always recognizes it, and may as a result make an outgoing IPv6 connection. All this option does is to make Exim look only for IPv4-style A records when it needs to find an IP address for a host name. 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.
Setting drop_cr true affects non-SMTP messages that are submitted locally. It causes every carriage return character that immediately precedes a linefeed to be discarded. Other carriage returns are treated as data. This action can be requested for individual messages by means of the -dropcr command line option.
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.13). 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.
Exim's bounce and delivery warning messages contain the header line
From: Mail Delivery System <Mailer-Daemon@<qsdomain>>
where <qsdomain> is the value of qualify_domain_sender. Experience shows that a large number of 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.
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 47 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 47 for a discussion of security issues.
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.
On encountering certain errors, or when configured to do so in a system filter, Exim freezes a message. This means that no further delivery attempts take place until an administrator (or the auto_thaw feature) thaws the message. If freeze_tell is set, Exim generates a warning message whenever it freezes something, unless the message it is freezing is a 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. The reason(s) for freezing can be found in the message log.
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.
This option controls the overall maximum size of a message's header section. The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for that is 1M. Messages with larger header sections are rejected.
This option limits the length of any individual header line in a message, after all the continuations have been joined together. Messages with individual header lines that are longer than the limit are rejected. The default value of zero means ``no limit''.
Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and gives an error response for invalid data. Unfortunately, there are some SMTP clients that send syntactic junk. They can be accommodated by setting this option. Note that this is a syntax check only. See helo_verify_hosts if you want to do semantic checking. See also helo_allow_chars for a way of extending the permitted character set.
This option can be set to a string of rogue characters that are permitted in all EHLO and HELO names in addition to the standard letters, digits, hyphens, and dots. If you really must allow underscores, you can set
helo_allow_chars = _
Note that the value is one string, not a list.
If the domain given by a client in a HELO or EHLO command matches this list, a reverse lookup is done in order to establish the host's true name. The default forces a lookup if the client host gives the server's name or any of its IP addresses (in brackets), something that broken clients have been seen to do.
The RFCs mandate that a server must not reject a message because it doesn't like the HELO or EHLO command. By default, Exim just checks the syntax of these commands (see helo_accept_junk_hosts and helo_allow_chars above). However, some sites like to be stricter. If the calling host matches helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO command either:
is an IP literal matching the calling address of the host (the RFCs specifically allow this), or
matches the host name that Exim obtains by doing a reverse lookup of the calling host address, or
when looked up using gethostbyname() (or getipnodebyname() when available) yields the calling host address.
However, the EHLO or HELO command is not rejected if any of the checks fail. Processing continues, but the result of the check is remembered, and can be detected later in an ACL by the verify = helo condition. If you want verification failure to cause rejection of EHLO or HELO, use helo_verify_hosts instead.
For hosts that match this option, Exim checks the host name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If the check fails, the HELO or EHLO command is rejected with a 550 error, and entries are written to the main and reject logs. If a MAIL command is received before EHLO or HELO, it is rejected with a 503 error.
This option allows mail for particular domains to be held on the queue manually. The option is overridden if a message delivery is forced with the -M, -qf, -Rf or -Sf options, and also while testing or verifying addresses using -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing or delivery for that address is done, and it is deferred every time the message is looked at.
This option is intended as a temporary operational measure for delaying the delivery of mail while some problem is being sorted out, or some new configuration tested. If you just want to delay the processing of some domains until a queue run occurs, you should use queue_domains or queue_smtp_domains, not hold_domains.
A setting of hold_domains does not override Exim's code for removing messages from the queue if they have been there longer than the longest retry time in any retry rule. If you want to hold messages for longer than the normal retry times, insert a dummy retry rule with a long retry time.
Exim does not look up the name of a calling host from its IP address unless it is required to compare against some host list, or the host matches helo_try_verify_hosts or helo_verify_hosts, or the host matches this option (which normally contains IP addresses rather than host names). The default configuration file contains
host_lookup = *
which causes a lookup to happen for all hosts. If the expense of these lookups is felt to be too great, the setting can be changed or removed.
After a successful reverse lookup, Exim does a forward lookup on the name it has obtained, to verify that it yields the IP address that it started with. If this check fails, Exim behaves as if the name lookup failed.
After any kind of failure, the host name (in $sender_host_name) remains unset, and $host_lookup_failed is set to the string ``1''. See also helo_lookup_domains and verify = reverse_host_lookup in ACLs.
If this option is set, incoming SMTP calls from the hosts listed are rejected as soon as the connection is made. The ACL specified by acl_smtp_connect can also reject incoming connections immediately. The ability to give an immediate rejection is provided for use in unusual cases. Many hosts will just try again, sometimes without much delay. Normally, it is better to use an ACL to reject incoming messages at a later stage, such as after RCPT commands. See chapter 37.
If this option is set, any host names that match the domain list are treated as if they were the local host when Exim is scanning host lists obtained from MX records. This option also applies when Exim is matching the special items @mx_any, @mx_primary, and @mx_secondary in a domain list (see section 10.7), and when checking the hosts option in the smtp transport for the local host (see the allow_localhost option in that transport).
This option affects the processing of bounce messages that cannot be delivered. After an initial failure, such messages are frozen, because there is no sender to whom they can be returned. When a frozen bounce message has been on the queue for more than the given time, it is unfrozen at the next queue run, and a further delivery is attempted. If delivery fails again, the bounce message is discarded. This makes it possible to keep failed bounce messages around for a shorter time than the normal maximum retry time for frozen messages. For example,
ignore_bounce_errors_after = 12h
retries failed bounce message deliveries after 12 hours, discarding any further failures. If the value of this option is set to a zero time period, bounce failures are discarded immediately. Setting a very long time (as in the default value) has the effect of disabling this option. For ways of automatically dealing with other kinds of frozen message, see auto_thaw and timeout_frozen_after.
Some broken SMTP clients insist on sending a UUCP-like ``From'' line before the headers of a message. By default this is treated as the start of the message's body, which means that any following headers are not recognized as such. Exim can be made to ignore it by setting ignore_fromline_hosts to match those hosts that insist on sending it. If the sender is actually a local process rather than a remote host, and is using -bs to inject the messages, ignore_fromline_local must be set to achieve this effect.
See ignore_fromline_hosts above.
This option specifies the length of time to keep messages whose spool files have been corrupted in some way. This should, of course, never happen. At the next attempt to deliver such a message, it gets removed. The incident is logged.
This option provides a list of LDAP servers which are tried in turn when an
LDAP query does not contain a server. See section 9.11 for details
of LDAP queries. This option is available only when Exim has been built with
LDAP support.
This option can be used to force Exim to set a specific protocol version for LDAP. If it option is unset, it is shown by the -bP command line option as -1. When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP headers; otherwise it is 2. This option is available only when Exim has been built with LDAP support.
When a message is submitted locally (that is, not over a TCP/IP connection) by an untrusted user, Exim removes any existing Sender: header line, and checks that the From: header line matches the login of the calling user. You can use local_from_prefix and local_from_suffix to permit affixes on the local part. If the From: header line does not match, Exim adds a Sender: header with an address constructed from the calling user's login and the default qualify domain.
If local_from_check is set false, the From: header check is disabled, and no Sender: header is ever added. If, in addition, you want to retain Sender: header lines supplied by untrusted users, you must also set local_sender_retain to be true.
These options affect only the header lines in the message. The envelope sender is still forced to be the login id at the qualify domain unless untrusted_set_sender permits the user to supply an envelope sender. Section 43.12 has more details about Sender: processing.
When Exim checks the From: header line of locally submitted messages for matching the login id (see local_from_check above), it can be configured to ignore certain prefixes and suffixes in the local part of the address. This is done by setting local_from_prefix and/or local_from_suffix to appropriate lists, in the same form as the local_part_prefix and local_part_suffix router options (see chapter 14). For example, if
local_from_prefix = *-
is set, a From: line containing
From: anything-user@your.domain.example
will not cause a Sender: header to be added if user@your.domain.example matches the actual sender address that is constructed from the login name and qualify domain.
See local_from_prefix above.
The string must contain a list of IP addresses, in dotted-quad format for IPv4 addresses, or in colon-separated format for IPv6 addresses. It is usually easier to change the list separator character instead of doubling all the colons in IPv6 addresses. For example:
local_interfaces = <; 127.0.0.1 ; \ 192.168.23.65 ; \ ::1 ; \ 3ffe:ffff:836f::fe86:a061
IPv6 addresses have ``scopes'', and a host with multiple interfaces can, in principle, have the same link-local addresses on different interfaces. Thus, they need to be distinguished, and a convention of using a percent sign followed by something (often the interface name) has been adopted in some cases, leading to addresses like this:
3ffe:2101:12:1:a00:20ff:fe86:a061%eth0
To accommodate this usage, a percent sign followed by an arbitrary string is allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to convert a textual IPv6 address for actual use. This function recognizes the percent convention in operating systems that support it, and it processes the address appropriately.
Unfortunately, some older libraries have problems with getaddrinfo(). If
IPV6_USE_INET_PTON=yes
is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim uses inet_pton() to convert a textual IPv6 address for actual use, instead of getaddrinfo(). (Before version 4.14, it always used this function.) Of course, this means that the additional functionality of getaddrinfo() - recognizing scoped addresses - is lost.
A port number can be specified along with each IP address. Two different formats are recognized:
The port is added onto the address with a dot separator, for example,
local_interfaces = <; 192.168.23.65.1234 ; \ 3ffe:ffff:836f::fe86:a061.1234
The IP address is enclosed in square brackets, and the port is added with a colon separator, for example,
local_interfaces = <; [192.168.23.65]:1234 ; \ [3ffe:ffff:836f::fe86:a061]:1234
The list of IP addresses in local_interfaces is used for two different purposes:
When a daemon is started to listen for incoming SMTP calls, it listens only on the interfaces and ports identified here. For interfaces listed without a port, the value of daemon_smtp_port is used, unless overridden by the -oX option. Exim can be made to listen on more than one port by listing the same interface with different port numbers, for example:
local_interfaces = 192.168.34.67.25 : 192.168.34.67.26
The address 0.0.0.0 means ``any interface'' in most IPv4 stacks, and ::0 is the
IPv6 equivalent. So, to specify listening on multiple ports on any interface,
you can use settings such as:
local_interfaces = <; 0.0.0.0.25 ; 0.0.0.0.26 ; \
::0.25 ; ::0.26
When a message is received over TCP/IP, the interface and port that were used are set in $interface_address and $interface_port. When the daemon is started, an error occurs if it is unable to bind a listening socket to any listed interface.
Only the IP addresses listed here are taken as the local host's IP addresses when routing mail and checking for mail loops. In this case, the port values are not used.
If local_interfaces is unset, the daemon issues a generic listen() that accepts incoming calls to any interface. The same port is used in all cases. In addition, Exim gets a complete list of available interfaces from the operating system, and treats them all as local when routing mail. On most systems, the default action is what is wanted. However, some systems set up large numbers of virtual interfaces in order to provide many different virtual web servers. In these cases local_interfaces can be used to restrict SMTP traffic to one or two interfaces only. See also hosts_treat_as_local.
This timeout applies to the local_scan() function (see chapter 38). Zero means ``no timeout''. If the timeout is exceeded, the incoming message is rejected with a temporary error if it is an SMTP message. For a non-SMTP message, the message is dropped and Exim ends with a non-zero code. The incident is logged on the main and reject logs.
When a message is submitted locally (that is, not over a TCP/IP connection) by an untrusted user, Exim removes any existing Sender: header line. If you do not want this to happen, you must set local_sender_retain, and you must also set local_from_check to be false (Exim will complain if you do not). Section 43.12 has more details about Sender: processing.
Exim's message ids are normally unique only within the local host. If uniqueness among a set of hosts is required, each host must set a different value for the localhost_number option. The string is expanded immediately after reading the configuration file (so that a number can be computed from the host name, for example) and the result of the expansion must be a number in the range 0-16 (or 0-10 on operating systems with case-insensitive file systems). This is available in subsequent string expansions via the variable $localhost_number. When localhost_number is set, the final two characters of the message id, instead of just being a fractional part of the time, are computed from the time and the local host number as described in section 3.3.
This option sets the path which is used to determine the names of Exim's log files, or indicates that logging is to be to syslog, or both. It is expanded when Exim is entered, so it can, for example, contain a reference to the host name. If no specific path is set for the log files at compile or run time, they are written in a sub-directory called log in Exim's spool directory. Chapter 44 contains further details about Exim's logging, and section 44.1 describes how the contents of log_file_path are used. If this string is fixed at your installation (contains no expansion variables) it is recommended that you do not set this option in the configuration file, but instead supply the path using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for logging errors detected early on - in particular, failure to read the configuration file.
This option can be used to reduce or increase the number of things that Exim writes to its log files. Its argument is made up of names preceded by plus or minus characters. For example:
log_selector = +arguments -retry_defer
A list of possible names and what they control is given in the chapter on
logging, in section 44.15.
By default, the timestamps on log lines are in local time without the timezone. This means that if your timezone changes twice a year, the timestamps in log lines are ambiguous for an hour when the clocks go back. One way of avoiding this problem is to set the timezone to UTC. An alternative is to set log_timezone true. This turns on the addition of the timezone offset to timestamps in log lines. Turning on this option can add quite a lot to the size of log files because each line is extended by 6 characters. Note that the $tod_log variable contains the log timestamp without the zone, but there is another variable called $tod_zone that contains just the timezone offset.
This option limits the number of simultaneously open files for single-key lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally keeps these files open during routing, because often the same file is required several times. If the limit is reached, Exim closes the least recently used file. Note that if you are using the ndbm library, it actually opens two files for each logical DBM database, though it still counts as one for the purposes of lookup_open_max. If you are getting ``too many open files'' errors with NDBM, you need to reduce the value of lookup_open_max.
Some operating systems are broken in that they truncate long arguments to getpwnam() to eight characters, instead of returning ``no such user''. If this option is set greater than zero, any attempt to call getpwnam() with an argument that is longer behaves as if getpwnam() failed.
This option specifies how much of a message's body is to be included in the
$message_body and $message_body_end expansion variables.
If this option is set, the string is expanded and used as the right hand side (domain) of the Message-ID: header that Exim creates if an incoming message does not have one. Otherwise, the primary host name is used. Only letters, digits, dot and hyphen are accepted; any other characters are replaced by hyphens. If the expansion is forced to fail, or if the result is an empty string, the option is ignored.
If this variable is set, the string is expanded and used to augment the text of the Message-id: header that Exim creates if an incoming message does not have one. The text of this header is required by RFC 2822 to take the form of an address. By default, Exim uses its internal message id as the local part, and the primary host name as the domain. If this option is set, it is expanded, and provided the expansion is not forced to fail, and does not yield an empty string, the result is inserted into the header immediately before the @, separated from the internal message id by a dot. Any characters that are illegal in an address are automatically converted into hyphens. This means that variables such as $tod_log can be used, because the spaces and colons will become hyphens.
If this option is turned off, per-message log files are not created in the msglog spool sub-directory. This reduces the amount of disk I/O required by Exim, by reducing the number of files involved in handling a message from a minimum of four (header spool file, body spool file, delivery journal, and per-message log) to three. The other major I/O activity is Exim's main log, which is not affected by this option.
This option limits the maximum size of message that Exim will process. The value is expanded for each incoming connection so, for example, it can be made to depend on the IP address of the remote host for messages arriving via TCP/IP. Note: This limit cannot be made to depend on a message's sender or any other properties of an individual message, because it has to be advertised in the server's response to EHLO. String expansion failure causes a temporary error. A value of zero means no limit, but its use is not recommended. See also return_size_limit.
Incoming SMTP messages are failed with a 552 error if the limit is exceeded; locally-generated messages either get a stderr message or a delivery failure message to the sender, depending on the -oe setting. Rejection of an oversized message is logged in both the main and the reject logs. See also the generic transport option message_size_limit, which limits the size of message that an individual transport can process.
This option, which is available only if Exim has been built with the setting
SUPPORT_MOVE_FROZEN_MESSAGES=yes
in Local/Makefile, causes frozen messages and their message logs to be moved from the input and msglog directories on the spool to Finput and Fmsglog, respectively. There is currently no support in Exim or the standard utilities for handling such moved messages, and they do not show up in lists generated by -bp or by the Exim monitor.
This option provides a list of MySQL servers and associated connection data, to be used in conjunction with mysql lookups (see section 9.17). The option is available only if Exim has been built with MySQL support.
Local mail deliveries are normally run in processes that are setuid to the recipient, and remote deliveries are normally run under Exim's own uid and gid. It is usually desirable to prevent any deliveries from running as root, as a safety precaution. If a message is to be delivered as one of the users on the never_users list, an error occurs, and delivery is deferred. A common example is
never_users = root:daemon:bin
This option overrides the pipe_as_creator option of the pipe transport driver.
This option provides a list of Oracle servers and associated connection data, to be used in conjunction with oracle lookups (see section 9.17). The option is available only if Exim has been built with Oracle support.
The ``percent hack'' is the convention whereby a local part containing a percent sign is re-interpreted as a new email address, with the percent replaced by @. This is sometimes called ``source routing'', though that term is also applied to RFC 2822 addresses that begin with an @ character. If this option is set, Exim implements the percent facility for those domains listed, but no others. This happens before an incoming SMTP address is tested against an ACL.
Warning: The ``percent hack'' has often been abused by people who are trying to get round relaying restrictions. For this reason, it is best avoided if at all possible. Unfortunately, a number of less security-conscious MTAs implement it unconditionally. If you are running Exim on a gateway host, and routing mail through to internal MTAs without processing the local parts, it is a good idea to reject recipient addresses with percent characters in their local parts. Exim's default configuration does this.
This option is available only when Exim is built with an embedded Perl interpreter. See chapter 12 for details of its use.
This option is available only when Exim is built with an embedded Perl interpreter. See chapter 12 for details of its use.
This option provides a list of PostgreSQL servers and associated connection data, to be used in conjunction with pgsql lookups (see section 9.17). The option is available only if Exim has been built with PostgreSQL support.
This option sets the name of the file to which the Exim daemon writes its process id. The string is expanded, so it can contain, for example, references to the host name:
pid_file_path = /var/log/$primary_hostname/exim.pid
If no path is set, the pid is written to the file exim-daemon.pid in Exim's spool directory. The value set b
Access Control Lists (ACLs) are defined in a separate section of the run time configuration file, headed by ``begin acl''. Each ACL definition starts with a name, terminated by a colon. Here is a complete ACL section which contains just one very small ACL:
begin acl small_acl: accept hosts = one.host.only
You can have as many lists as you like in the ACL section, and the order in which they appear does not matter. The lists are self-terminating.
The majority of ACLs are used to control Exim's behaviour when it receives certain SMTP commands. This applies both to incoming TCP/IP connections, and when a local process submits a message over a pipe (using the -bs option). The most common use is for controlling which recipients are accepted in incoming messages. In addition, you can also define an ACL that is used to check local non-SMTP messages. The default configuration file contains an example of a realistic ACL for checking RCPT commands. This is discussed in chapter 7.
The -bh command line option provides a way of testing your ACL configuration locally by running a fake SMTP session with which you interact. The host relay-test.mail-abuse.org provides a service for checking your relaying configuration (see section 37.20 for more details).
In order to cause an ACL to be used, you have to name it in one of the relevant options in the main part of the configuration. These options are:
| acl_not_smtp | ACL for non-SMTP messages |
| acl_smtp_auth | ACL for AUTH |
| acl_smtp_connect | ACL for start of SMTP connection |
| acl_smtp_data | ACL after DATA |
| acl_smtp_etrn | ACL for ETRN |
| acl_smtp_expn | ACL for EXPN |
| acl_smtp_helo | ACL for HELO or EHLO |
| acl_smtp_mail | ACL for MAIL |
| acl_smtp_rcpt | ACL for RCPT |
| acl_smtp_starttls | ACL for STARTTLS |
| acl_smtp_vrfy | ACL for VRFY |
For example, if you set
acl_smtp_rcpt = small_acl
the little ACL defined above is used whenever Exim receives a RCPT command in an SMTP dialogue. The majority of policy tests on incoming messages can be done when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to give up on the recipient address contained in the RCPT command, whereas rejection at other times may cause the client MTA to keep on trying to deliver the message. It is therefore recommended that you do as much testing as possible at RCPT time.
However, you cannot test the contents of the message, for example, to verify addresses in the headers, at RCPT time. Such tests have to appear in the ACL that is run after the message has been received, before the final response to the DATA command is sent. This is the ACL specified by acl_smtp_data. At this time, it is no longer possible to reject individual recipients. An error response should reject the entire message. Unfortunately, it is known that some MTAs do not treat hard (5xx) errors correctly at this point - they keep the message on their queues and try again later, but that is their problem, though it does waste some of your resources.
The ACL test specified by acl_smtp_connect happens after the test specified by host_reject_connection (which is now an anomaly) and any TCP Wrappers testing (if configured).
The non-SMTP ACL applies to all non-interactive incoming messages, that is, it applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not really SMTP.) This ACL is run just before the local_scan() function. Any kind of rejection is treated as permanent, because there is no way of sending a temporary error for these kinds of message. Many of the ACL conditions (for example, host tests, and tests on the state of the SMTP connection such as encryption and authentication) are not relevant and are forbidden in this ACL.
The result of running an ACL is either ``accept'' or ``deny'', or, if some test cannot be completed (for example, if a database is down), ``defer''. These results cause 2xx, 5xx, and 4xx return codes, respectively, to be used in the SMTP dialogue. A fourth return, ``error'', occurs when there is an error such as invalid syntax in the ACL. This also causes a 4xx return code.
The ACLs that are relevant to message reception may also return ``discard''. This has the effect of ``accept'', but causes either the entire message or an individual recipient address to be discarded. In other words, it is a blackholing facility. Use it with great care.
If the ACL for MAIL returns ``discard'', all recipients are discarded, and no ACL is run for subsequent RCPT commands. The effect of ``discard'' in a RCPT ACL is to discard just the one address. If there are no recipients left when the message's data is received, the DATA ACL is not run. A ``discard'' return from the DATA or the non-SMTP ACL discards all the remaining recipients.
The local_scan() function is always run, even if there are no remaining recipients; it may create new recipients.
The default actions when any of the acl_smtp_xxx options are unset are not all the same.
For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo, acl_smtp_mail, and acl_smtp_starttls, the default action is ``accept''.
For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy), the default action is ``deny''. This means that acl_smtp_rcpt must be defined in order to receive any messages over an SMTP connection. For an example, see the ACL in the default configuration file.
When an ACL for MAIL, RCPT, or DATA is being run, the variables that contain information about the host and the message's sender (for example, $sender_host_address and $sender_address) are set, and can be used in ACL statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part are set from the argument address.
The $message_size variable is set to the value of the SIZE parameter on the MAIL command at MAIL and RCPT time, or -1 if that parameter was not given. Its value is updated to the true message size by the time the ACL after DATA is run.
The $rcpt_count variable increases by one for each RCPT command received. The $recipients_count variable increases by one each time a RCPT command is accepted, so while an ACL for RCPT is being processed, it contains the number of previously accepted recipients. At DATA time, $rcpt_count contains the total number of RCPT commands, and $recipients_count contains the total number of accepted recipients.
When an ACL for AUTH, ETRN, EXPN, STARTTLS, or VRFY is being run, the remainder of the SMTP command line is placed in $smtp_command_argument. This can be tested using a condition condition. For example, here is an ACL for use with AUTH, which insists that either the session is encrypted, or the CRAM-MD5 authentication method is used. In other words, it does not permit authentication methods that use cleartext passwords on unencrypted connections.
acl_check_auth: accept encryptedExim 4.20 Specification chapter 38 Previous Next Contents (Exim 4.20 Specification)
38. Adding a local scan function to Exim
In these days of email worms, viruses, and ever-increasing spam, some sites want to apply a lot of checking to messages before accepting them. You can do a certain amount through string expansions and the condition condition in the ACL that runs after the SMTP DATA command or the ACL for non-SMTP messages (see chapter 37), but this has its limitations. To allow for more general checking that can be customized to a site's own requirements, there is the possibility of linking Exim with a private message scanning function, written in C. If you want to run code that is written in something other than C, you can of course use a little C stub to call it.
The local scan function is run for every incoming message. It can therefore be used to control non-SMTP messages from local processes as well as messages arriving via SMTP.
Exim applies a timeout to calls of the local scan function, and there is an option called local_scan_timeout for setting it. The default is 5 minutes. Zero means ``no timeout''. Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS before calling the local scan function, so that the most common types of crash are caught. If the timeout is exceeded or one of those signals is caught, the incoming message is rejected with a temporary error if it is an SMTP message. For a non-SMTP message, the message is dropped and Exim ends with a non-zero code. The incident is logged on the main and reject logs.
38.1. Building Exim to use a local scan function
To make use of the local scan function feature, you must tell Exim where your function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/Makefile. A recommended place to put it is in the Local directory, so you might set
LOCAL_SCAN_SOURCE=Local/local_scan.cfor example. The function must be called local_scan(). It is called by Exim after it has received a message, when the success return code is about to be sent. This is after all the ACLs have been run. The return code from your function controls whether the message is actually accepted or not. There is a commented template function (that just accepts the message) in the file src/local_scan.c.
If you want to make use of Exim's run time configuration file to set options for your local_scan() function, you must also set
LOCAL_SCAN_HAS_OPTIONS=yesin Local/Makefile (see section 38.3 below).
38.2. API for local_scan()
You must include this line near the start of your code:
#include "local_scan.h"This header file defines a number of variables and other values, and the prototype for the function itself. Exim is coded to use unsigned char values almost exclusively, and one of the things this header defines is a shorthand for unsigned char called uschar. It also contains the following macro definitions, to simplify casting character strings and pointers to character strings:
#define CS (char *) #define CCS (const char *) #define CSS (char **) #define US (unsigned char *) #define CUS (const unsigned char *) #define USS (unsigned char **)The function prototype for local_scan() is:
extern int local_scan(int fd, uschar **return_text);The arguments are as follows:
fd is a file descriptor for the file that contains the body of the message (the -D file). The file is open for reading and writing, but updating it is not recommended. Warning: You must not close this file descriptor.
The descriptor is positioned at character 19 of the file, which is the first character of the body itself, because the first 19 characters are the message id followed by -D and a newline. If you rewind the file, you should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the data, just in case this changes in some future version.
return_text is an address which you can use to return a pointer to a text string at the end of the function. The value it points to on entry is NULL.
The function must return an int value which is one of the following macros:
LOCAL_SCAN_ACCEPT
The message is accepted. If you pass back a string of text, it is saved with the message, and made available in the variable $local_scan_data. No newlines are permitted (if there are any, they are turned into spaces) and the maximum length of text is 1000 characters.
LOCAL_SCAN_ACCEPT_FREEZE
This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is queued without immediate delivery, and is frozen.
LOCAL_SCAN_ACCEPT_QUEUE
This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is queued without immediate delivery.
LOCAL_SCAN_REJECT
The message is rejected; the returned text is used as an error message which is passed back to the sender and which is also logged. Newlines are permitted - they cause a multiline response for SMTP rejections, but are converted to \n in log lines. If no message is given, ``Administrative prohibition'' is used.
LOCAL_SCAN_TEMPREJECT
The message is temporarily rejected; the returned text is used as an error message as for LOCAL_SCAN_REJECT. If no message is given, ``Temporary local problem'' is used.
LOCAL_SCAN_REJECT_NOLOGHDR
This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected message is not written to the reject log. It has the effect of unsetting the rejected_header log selector for just this rejection. If rejected_header is already unset (see the discussion of the log_selection option in section 44.15), this code is the same as LOCAL_SCAN_REJECT.
LOCAL_SCAN_TEMPREJECT_NOLOGHDR
This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT.
If the message is not being received by interactive SMTP, rejections are reported by writing to stderr or by sending an email, as configured by the -oe command line options.
It is possible to have option settings in the main configuration file that set values in static variables in the local_scan() module. If you want to do this, you must have the line
LOCAL_SCAN_HAS_OPTIONS=yes
in your Local/Makefile when you build Exim. (This line is in OS/Makefile-Default, commented out). Then, in the local_scan() source file, you must define static variables to hold the option values, and a table to define them.
The table must be a vector called local_scan_options, of type optionlist. Each entry is a triplet, consisting of a name, an option type, and a pointer to the variable that holds the value. The entries must appear in alphabetical order. Following local_scan_options you must also define a variable called local_scan_options_count that contains the number of entries in the table. Here is a short example, showing two kinds of option:
static int my_integer_option = 42;
static uschar *my_string_option = US"a default string";
optionlist local_scan_options[] = {
{ "my_integer", opt_int, &my_integer_option },
{ "my_string", opt_stringptr, &my_string_option }
};
int local_scan_options_count =
sizeof(local_scan_options)/sizeof(optionlist);
The values of the variables can now be changed from Exim's runtime configuration file by including a local scan section as in this example:
begin local_scan my_integer = 99 my_string = some string of text...
The available types of option data are as follows:
opt_bool
This specifies a boolean (true/false) option. The address should point to a variable of type BOOL, which will be set to TRUE or FALSE, which are macros that are defined as ``1'' and ``0'', respectively. If you want to detect whether such a variable has been set at all, you can initialize it to TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than two values.)
opt_fixed
This specifies a fixed point number, such as is used for load averages. The address should point to a variable of type int. The value is stored multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414.
opt_int
This specifies an integer; the address should point to a variable of type int. The value may be specified in any of the integer formats accepted by Exim.
opt_mkint
This is the same as opt_int, except that when such a value is output in a -bP listing, if it is an exact number of kilobytes or megabytes, it is printed with the suffix K or M.
opt_octint
This also specifies an integer, but the value is always interpeted as an octal integer, whether or not it starts with the digit zero, and it is always output in octal.
opt_stringptr
This specifies a string value; the address must be a pointer to a variable that points to a string (for example, of type uschar *).
opt_time
This specifies a time interval value. The address must point to a variable of type int. The value that is placed there is a number of seconds.
If the -bP command line option is followed by local_scan, Exim prints out the values of all the local_scan() options.
The header local_scan.h gives you access to a number of C variables.
These are the only ones that are guaranteed to be maintained from release to
release. Note, however, that you can obtain the value of any Exim variable by
calling expand_string(). The exported variables are as follows:
unsigned int debug_selector
This variable is set to zero when no debugging is taking place. Otherwise, it is a bitmap of debugging selectors. Two bits are identified for use in local_scan(); they are defined as macros:
The D_v bit is set when -v was present on the command line. This is a testing option that is not privileged - any caller may set it. All the other selector bits can be set only by admin users.
The D_local_scan bit is provided for use by local_scan(); it is set by the +local_scan debug selector. It is not included in the default set of debugging bits.
Thus, to write to the debugging output only when +local_scan has been selected, you should use code like this:
if ((debug_selector & D_local_scan) != 0)
debug_printf("xxx", ...);
uschar *expand_string_message
After a failing call to expand_string() (returned value NULL), the variable expand_string_message contains the error message, zero-terminated.
header_line *header_list
A pointer to a chain of header lines. The header_line structure is discussed below.
header_line *header_last
A pointer to the last of the header lines.
BOOL host_checking
This variable is TRUE during a host checking session that is initiated by the -bh command line option.
uschar *interface_address
The IP address of the interface that received the message, as a string. This is NULL for locally submitted messages.
int interface_port
The port on which this message was received.
uschar *message_id
This variable contains the message id for the incoming message as a zero-terminated string.
uschar *received_protocol
The name of the protocol by which the message was received.
int recipients_count
The number of accepted recipients.
recipient_item *recipients_list
The list of accepted recipients, held in a vector of length recipients_count. The recipient_item structure is discussed below. You can add additional recipients by calling receive_add_recipient() (see below). You can delete recipients by removing them from the vector and adusting the value in recipients_count. In particular, by setting recipients_count to zero you remove all recipients. If you then return the value LOCAL_SCAN_ACCEPT, the message is accepted, but immediately blackholed. To replace the recipients, set recipients_count to zero and then call receive_add_recipient() as often as needed.
uschar *sender_address
The envelope sender address. For bounce messages this is the empty string.
uschar *sender_host_address
The IP address of the sending host, as a string. This is NULL for locally-submitted messages.
uschar *sender_host_authenticated
The name of the authentication mechanism that was used, or NULL if the message was not received over an authenticated SMTP connection.
uschar *sender_host_name
The name of the sending host, if known.
int sender_host_port
The port on the sending host.
int store_pool
The contents of this variable control which pool of memory is used for new requests. See section 38.8 for details.
The header_line structure contains the members listed below. You can add additional header lines by calling the header_add() function (see below). You can cause header lines to be ignored (deleted) by setting their type to *.
struct header_line *next
A pointer to the next header line, or NULL for the last line.
int type
A code identifying certain headers that Exim recognizes. The codes are printing characters, and are documented in chapter 48 of this manual. Notice in particular that any header line whose type is * is not transmitted with the message. This flagging is used for header lines that have been rewritten, or are to be removed (for example, Envelope-sender: header lines.) Effectively, * means ``deleted''.
int slen
The number of characters in the header line, including the terminating and any internal newlines.
uschar *text
A pointer to the text of the header. It always ends with a newline, followed by a zero byte. Internal newlines are preserved.
The recipient_item structure contains these members:
uschar *address
This is a pointer to the recipient address as it was received.
int pno
This is used in later Exim processing when top level addresses are created by the one_time option. It is not relevant at the time local_scan() is run and must always contain -1 at this stage.
uschar *errors_to
If this value is not NULL, bounce messages caused by failing to deliver to the recipient are sent to the address it contains. In other words, it overrides the envelope sender for this one recipient. (Compare the errors_to generic router option.) If a local_scan() function sets an errors_to field to an unqualified address, Exim qualifies it using the domain from qualify_recipient. When local_scan() is called, the errors_to field is NULL for all recipients.
The header local_scan.h gives you access to a number of Exim functions.
These are the only ones that are guaranteed to be maintained from release to
release:
pid_t child_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, BOOL make_leader)
This function creates a child process that runs the command specified by argv. The environment for the process is specified by envp, which can be NULL if no environment variables are to be passed. A new umask is supplied for the process in newumask.
Pipes to the standard input and output of the new process are set up and returned to the caller via the infdptr and outfdptr arguments. The standard error is cloned to the standard output. If there are any file descriptors ``in the way'' in the new process, they are closed. If the final argument is TRUE, the new process is made into a process group leader.
Th