. --- table with four columns. For cases when the option name is given with
. --- a space, so that it can be split, a fifth argument is used for the
. --- index entry.
+. --- Also one for multiple option def headings be grouped in a single
+. --- table (but without the split capability).
+
+.macro otable
+.itable all 0 0 4 8* left 6* center 6* center 6* right
+.endmacro
+
+.macro orow
+.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
+.endmacro
.macro option
.arg 5
.arg -5
.oindex "&%$1%&"
.endarg
-.itable all 0 0 4 8* left 6* center 6* center 6* right
-.row "&%$1%&" "Use: &'$2'&" "Type: &'$3'&" "Default: &'$4'&"
+.otable
+.orow "$1" "$2" "$3" "$4"
+.endtable
+.endmacro
+
+.macro options
+.eacharg
+.oindex "&%$+1%&"
+.endeach 4
+.otable
+.eacharg
+.orow "$+1" "$+2" "$+3" "$+4"
+.endeach 4
.endtable
.endmacro
The following Exim mailing lists exist:
.table2 140pt
-.row &'exim-announce@exim.org'& "Moderated, low volume announcements list"
-.row &'exim-users@exim.org'& "General discussion list"
-.row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc."
-.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS"
+.row &'exim-announce@lists.exim.org'& "Moderated, low volume announcements list"
+.row &'exim-users@lists.exim.org'& "General discussion list"
+.row &'exim-users-de@lists.exim.org'& "General discussion list in German language"
+.row &'exim-dev@lists.exim.org'& "Discussion of bugs, enhancements, etc."
+.row &'exim-cvs@lists.exim.org'& "Automated commit messages from the VCS"
.endtable
You can subscribe to these lists, change your existing subscriptions, and view
.cindex "Darwin"
.cindex "Cygwin"
.cindex "exim_msgdate"
-Every message handled by Exim is given a &'message id'& which is sixteen
+Every message handled by Exim is given a &'message id'& which is 23
characters long. It is divided into three parts, separated by hyphens, for
-example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits,
+example &`16VDhn-000000001bo-D342`&. Each part is a sequence of letters and digits,
normally encoding numbers in base 62. However, in the Darwin operating
system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
(avoiding the use of lower case letters) is used instead, because the message
contains the number of seconds since the start of the epoch (the normal Unix
way of representing the date and time of day).
.next
-After the first hyphen, the next six characters are the id of the process that
-received the message.
+After the first hyphen, the next
+.new
+eleven
+.wen
+characters are the id of the process that received the message.
.next
-There are two different possibilities for the final two characters:
+.new
+There are two different possibilities for the final four characters:
.olist
.oindex "&%localhost_number%&"
If &%localhost_number%& is not set, this value is the fractional part of the
-time of reception, normally in units of 1/2000 of a second, but for systems
+time of reception, normally in units of
+microseconds.
+but for systems
that must use base 36 instead of base 62 (because of case-insensitive file
-systems), the units are 1/1000 of a second.
+systems), the units are
+2 us.
.next
-If &%localhost_number%& is set, it is multiplied by 200 (100) and added to
-the fractional part of the time, which in this case is in units of 1/200
-(1/100) of a second.
+If &%localhost_number%& is set, it is multiplied by
+500000 (250000) and added to
+the fractional part of the time, which in this case is in units of 2 us (4 us).
.endlist
+.wen
.endlist
After a message has been received, Exim waits for the clock to tick at the
This option requests Exim to give up trying to deliver the listed messages,
including any that are frozen. However, if any of the messages are active,
their status is not altered. For non-bounce messages, a delivery error message
-is sent to the sender, containing the text &"cancelled by administrator"&.
+is sent to the sender.
Bounce messages are just discarded. This option can be used only by an admin
user.
The &'query-style'& type accepts a generalized database query. No particular
key value is assumed by Exim for query-style lookups. You can use whichever
Exim variables you need to construct the database query.
+
+For the string-expansion kind of lookups, the query is given in the first
+bracketed argument of the &${lookup ...}$& expansion.
+For the list-argument kind of lookup the quury is given by the remainder of the
+list item after the first semicolon.
+
.cindex "tainted data" "quoting for lookups"
If tainted data is used in the query then it should be quuted by
using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
in a database file is useless, because the asterisk in a partial matching
subject key is always followed by a dot.
+When the lookup is done from a string-expansion,
+the variables &$1$& and &$2$& contain the wild and non-wild parts of the key
+during the expansion of the replacement text.
+They return to their previous values at the end of the lookup item.
+
.code
${quote_<lookup-type>:<string>}
.endd
-For example, the safest way to write the NIS+ query is
+For example, the way to write the NIS+ query is
.code
[name="${quote_nisplus:$local_part}"]
.endd
+.cindex "tainted data" "in lookups"
+.new
+&*All*& tainted data used in a query-style lookup must be quoted
+using a mechanism appropriate for the lookup type.
+.wen
See chapter &<<CHAPexpand>>& for full coverage of string expansions. The quote
operator can be used for all lookup types, but has no effect for single-key
lookups, since no quoting is ever needed in their key strings.
After expansion, <&'string'&> is interpreted as a list, colon-separated by
default, but the separator can be changed in the usual way (&<<SECTlistsepchange>>&).
For each item
-in this list, its value is place in &$item$&, and then the condition is
+in this list, its value is placed in &$item$&, and then the condition is
evaluated.
.new
Any modification of &$value$& by this evaluation is discarded.
sending the request. Values are &"yes"& (the default) or &"no"&
(preferred, eg. by some webservers).
+.next
+&*sni*&
+Controls the use of Server Name Identification on the connection.
+Any nonempty value will be the SNI sent; TLS will be forced.
+
.next
&*tls*&
Controls the use of TLS on the connection.
This item inserts &"raw"& header lines. It is described with the &%header%&
expansion item in section &<<SECTexpansionitems>>& above.
-.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
+.vitem "&*${run<&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
{*&<&'string2'&>&*}}*&"
.cindex "expansion" "running a command"
.cindex "&%run%& expansion item"
This item runs an external command, as a subprocess.
-One option is supported after the word &'run'&, comma-separated.
+One option is supported after the word &'run'&, comma-separated
+and without whitespace.
If the option &'preexpand'& is not used,
the command string is split into individual arguments by spaces
.code
${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}}
.endd
+Note that &$value$& will not persist beyond the reception of a single message.
.vindex "&$runrc$&"
The return code from the command is put in the variable &$runrc$&, and this
.endlist
Note that negation of &*forany*& means that the condition must be false for all
items for the overall condition to succeed, and negation of &*forall*& means
-that the condition must be false for at least one item. In this example, the
-list separator is changed to a comma:
+that the condition must be false for at least one item.
+
+Example:
.code
-${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}}
+${if forany{$recipients_list}{match{$item}{^user3@}}{yes}{no}}
.endd
The value of &$item$& is saved and restored while &%forany%& or &%forall%& is
being processed, to enable these expansion items to be nested.
Consult section &<<SECThoslispatip>>& for further details of these patterns.
+The variable &$value$& will be set for a successful match and can be
+used in the success clause of an &%if%& expansion item using the condition.
+Any previous &$value$& is restored after the if.
+
.vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
.cindex "domain list" "in expansion condition"
.cindex "address list" "in expansion condition"
rejections of MAIL and rejections of RCPT.
.tvar &$recipients$&
-This variable contains a list of envelope recipients for a message. A comma and
-a space separate the addresses in the replacement text. However, the variable
-is not generally available, to prevent exposure of Bcc recipients in
-unprivileged users' filter files. You can use &$recipients$& only in these
+.new
+.tvar &$recipients_list$&
+These variables both contain the envelope recipients for a message.
+
+The first uses a comma and a space separate the addresses in the replacement text.
+&*Note*&: an address can legitimately contain a comma;
+this variable is not intended for further processing.
+
+The second is a proper Exim list; colon-separated.
+.wen
+
+However, the variables
+are not generally available, to prevent exposure of Bcc recipients in
+unprivileged users' filter files. You can use either of them only in these
cases:
.olist
.cindex "router" "name"
.cindex "name" "of router"
.vindex "&$router_name$&"
-During the running of a router this variable contains its name.
+During the running of a router, or a transport called,
+this variable contains the router name.
.vitem &$runrc$&
.cindex "return code" "from &%run%& expansion"
single connection is being processed. When a child process terminates, the
daemon decrements its copy of the variable.
+.vitem &$smtp_notquit_reason$&
+.vindex "&$smtp_notquit_reason$&"
+When the not-QUIT ACL is running, this variable is set to a string
+that indicates the reason for the termination of the SMTP connection.
+
.vitem "&$sn0$& &-- &$sn9$&"
These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators
that were current at the end of the system filter file. This allows a system
See section &<<CALLaddparcall>>& for details of how this value is used.
-.option check_log_inodes main integer 100
-See &%check_spool_space%& below.
-
-
-.option check_log_space main integer 10M
+.options check_log_inodes main integer 100 &&&
+ check_log_space main integer 10M
See &%check_spool_space%& below.
.oindex "&%check_rfc2047_length%&"
set false, Exim recognizes encoded words of any length.
-.option check_spool_inodes main integer 100
-See &%check_spool_space%& below.
-
-
-.option check_spool_space main integer 10M
+.options check_spool_inodes main integer 100 &&&
+ check_spool_space main integer 10M
.cindex "checking disk space"
.cindex "disk space, checking"
.cindex "spool directory" "checking space"
listens. See chapter &<<CHAPinterfaces>>& for details of how it is used. For
backward compatibility, &%daemon_smtp_port%& (singular) is a synonym.
-.option daemon_startup_retries main integer 9
+.options daemon_startup_retries main integer 9 &&&
+ daemon_startup_sleep main time 30s
.cindex "daemon startup, retrying"
-This option, along with &%daemon_startup_sleep%&, controls the retrying done by
+These options control 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.
-.option daemon_startup_sleep main time 30s
-See &%daemon_startup_retries%&.
-
.option delay_warning main "time list" 24h
.cindex "warning of delay"
.cindex "delay warning, specifying"
.option freeze_tell main "string list, comma separated" unset
.cindex "freezing messages" "sending a message when freezing"
+.cindex "frozen messages" "sending a message when freezing"
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
logging that you require.
-.option gecos_name main string&!! unset
+.options gecos_name main string&!! unset &&&
+ gecos_pattern main string unset
.cindex "HP-UX"
.cindex "&""gecos""& field, parsing"
Some operating systems, notably HP-UX, use the &"gecos"& field in the system
gecos_name = $1
.endd
-.option gecos_pattern main string unset
-See &%gecos_name%& above.
-
.option gnutls_compat_mode main boolean unset
This option controls whether GnuTLS is used in compatibility mode in an Exim
&%timeout_frozen_after%&.
-.option ignore_fromline_hosts main "host list&!!" unset
+.options ignore_fromline_hosts main "host list&!!" unset &&&
+ ignore_fromline_local main boolean false
.cindex "&""From""& line"
.cindex "UUCP" "&""From""& line"
Some broken SMTP clients insist on sending a UUCP-like &"From&~"& line before
&%ignore_fromline_local%& must be set to achieve this effect.
-.option ignore_fromline_local main boolean false
-See &%ignore_fromline_hosts%& above.
.option keep_environment main "string list" unset
.cindex "environment" "values from"
-.option local_from_prefix main string unset
+.options local_from_prefix main string unset &&&
+ local_from_suffix main string unset
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
qualify domain.
-.option local_from_suffix main string unset
-See &%local_from_prefix%& above.
-
-
.option local_interfaces main "string list" "see below"
This option controls which network interfaces are used by the daemon for
listening; they are also used to identify the local host when routing. Chapter
local parts. Exim's default configuration does this.
-.option perl_at_start main boolean false
-.cindex "Perl"
-This option is available only when Exim is built with an embedded Perl
-interpreter. See chapter &<<CHAPperl>>& for details of its use.
-
-
-.option perl_startup main string unset
+.options perl_at_start main boolean false &&&
+ perl_startup main string unset
.cindex "Perl"
-This option is available only when Exim is built with an embedded Perl
-interpreter. See chapter &<<CHAPperl>>& for details of its use.
+These options are available only when Exim is built with an embedded Perl
+interpreter. See chapter &<<CHAPperl>>& for details of their use.
.option perl_taintmode main boolean false
.cindex "Perl"
&%queue_only_load%&, and &%smtp_accept_queue%&.
-.option queue_only_file main string unset
+.option queue_only_file main "string list" unset
.cindex "queueing incoming messages"
.cindex "message" "queueing by file existence"
This option can be set to a colon-separated list of absolute path names, each
-.option smtp_ratelimit_hosts main "host list&!!" unset
+.options smtp_ratelimit_hosts main "host list&!!" unset &&&
+ smtp_ratelimit_mail main string unset &&&
+ smtp_ratelimit_rcpt main string unset
.cindex "SMTP" "rate limiting"
.cindex "limit" "rate of message arrival"
.cindex "RCPT" "rate limiting"
delays to RCPT commands when more than four occur in a single message.
-.option smtp_ratelimit_mail main string unset
-See &%smtp_ratelimit_hosts%& above.
-
-
-.option smtp_ratelimit_rcpt main string unset
-See &%smtp_ratelimit_hosts%& above.
-
.option smtp_receive_timeout main time&!! 5m
.cindex "timeout" "for SMTP input"
.cindex ALPN "set acceptable names for server"
If this option is set,
the TLS library supports ALPN,
-and the client offers either more than
+and the client offers either more than one
ALPN name or a name which does not match the list,
the TLS connection is declined.
.cindex "router" "restricting to specific domains"
.vindex "&$domain_data$&"
If this option is set, the router is skipped unless the current domain matches
-the list. If the match is achieved by means of a file lookup, the data that the
-lookup returned for the domain is placed in &$domain_data$& for use in string
+the list.
+The data returned by the list check
+is placed in &$domain_data$& for use in string
expansions of the driver's private options and in the transport.
See section &<<SECTrouprecon>>& for
a list of the order in which preconditions are evaluated.
+A complex example, using a file like:
+.code
+alice@dom1
+bill@dom1
+maggie@dom1
+.endd
+and checking both domain and local_part
+.code
+domains = ${domain:${lookup {$local_part@$domain} lseach,ret=key {/path/to/accountsfile}}}
+local_parts = ${local_part:${lookup {$local_part@$domain} lseach,ret=key {/path/to/accountsfile}}}
+.endd
+
.option driver routers string unset
local_parts = dbm;/usr/local/specials/$domain_data
.endd
.vindex "&$local_part_data$&"
-If the match is achieved by a lookup, the data that the lookup returned
+the data returned by the list check
for the local part is placed in the variable &$local_part_data$& for use in
expansions of the router's private options or in the transport.
You might use this option, for
transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
.endd
This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and
-&(/bin/cmd2)& otherwise. If double quotes had been used, they would have been
+&(/bin/cmd2)& otherwise.
+
+Option strings in general have any fully-surrounding double quote wrapping
+removed early in parsing (see &<<SECTstrings>>&).
+Then, for this option, quotes protect against whitespace being
+regarded as a separator while splitting into the command argument vector.
+Either double or single quotes can be used here;
+the former interprets backlash-quoted charachters
+and the latter does not.
+
+If double quotes had been used in this example, they would have been
stripped by Exim when it read the option's value. When the value is used, if
the single quotes were missing, the line would be split into two items,
&`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when
while verifying the server certificate,
checks will be included on the host name
(note that this will generally be the result of a DNS MX lookup)
-versus Subject and Subject-Alternate-Name fields. Wildcard names are permitted
+versus the Subject-Alternate-Name (or, if none, Subject-Name) fields.
+Wildcard names are permitted,
limited to being the initial component of a 3-or-more component FQDN.
There is no equivalent checking on client certificates.
(see &<<CHAPTLS>>&).
If an authenticator of this type is configured it is
-run before any SMTP-level communication is done,
+run immediately after a TLS connection being negotiated
+(due to either STARTTLS or TLS-on-connect)
and can authenticate the connection.
-If it does, SMTP authentication is not offered.
+If it does, SMTP authentication is not subsequently offered.
A maximum of one authenticator of this type may be present.
The value &"system"& results in no caching under GnuTLS.
The macro _HAVE_TLS_CA_CACHE will be defined if the suffix for "system"
-is acceptable in configurations for the Exim executavble.
+is acceptable in configurations for the Exim executable.
Caching of the system Certificate Authorities bundle can
-save siginificant time and processing on every TLS connection
+save significant time and processing on every TLS connection
accepted by Exim.
The value &"system"& results in no caching under GnuTLS.
The macro _HAVE_TLS_CA_CACHE will be defined if the suffix for "system"
-is acceptable in configurations for the Exim executavble.
+is acceptable in configurations for the Exim executable.
Caching of the system Certificate Authorities bundle can
-save siginificant time and processing on every TLS connection
+save significant time and processing on every TLS connection
initiated by Exim.
The text in a &%message%& modifier is literal; any quotes are taken as
literals, but because the string is expanded, backslash escapes are processed
-anyway. If the message contains newlines, this gives rise to a multi-line SMTP
+anyway.
+If the message contains newlines, this gives rise to a multi-line SMTP
response.
+A long message line will also be split into multi-line SMTP responses,
+on word boundaries if possible.
.vindex "&$acl_verify_message$&"
While the text is being expanded, the &$acl_verify_message$& variable
.vitem &*control&~=&~fakedefer/*&<&'message'&>
.cindex "fake defer"
.cindex "defer, fake"
+.cindex fakedefer
This control works in exactly the same way as &%fakereject%& (described below)
except that it causes an SMTP 450 response after the message data instead of a
550 response. You must take care when using &%fakedefer%& because it causes the
.vitem &*control&~=&~fakereject/*&<&'message'&>
.cindex "fake rejection"
.cindex "rejection, fake"
+.cindex fakereject
This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
words, only when an SMTP message is being received. If Exim accepts the
message, instead the final 250 response, a 550 rejection message is sent.
DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
More than one header can be removed at the same time by using a colon separated
-list of header names. The header matching is case insensitive. Wildcards are
-not permitted, nor is list expansion performed, so you cannot use hostlists to
+list of header specifiers.
+.new
+If a specifier does not start with a circumflex (^)
+then it is treated as a header name.
+The header name matching is case insensitive.
+If it does, then it is treated as a (front-anchored)
+regular expression applied to the whole header.
+
+&*Note*&: The colon terminating a header name will need to be doubled
+if used in an RE, and there can legitimately be whitepace before it.
+
+Example:
+.code
+remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N
+.endd
+.wen
+
+List expansion is not performed, so you cannot use hostlists to
create a list of headers, however both connection and message variable expansion
are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example:
.code
warn message = Remove internal headers
remove_header = $acl_c_ihdrs
.endd
-Header names for removal are accumulated during the MAIL, RCPT, and predata ACLs.
+Header specifiers for removal are accumulated during the MAIL, RCPT, and predata ACLs.
Matching header lines are removed from the message before processing the DATA and MIME ACLs.
If multiple header lines match, all are removed.
There is no harm in attempting to remove the same header twice nor in removing
-a non-existent header. Further header lines to be removed may be accumulated
-during the DATA and MIME ACLs, after which they are removed from the message,
-if present. In the case of non-SMTP messages, headers to be removed are
-accumulated during the non-SMTP ACLs, and are removed from the message after
+a non-existent header. Further header specifiers for removal may be accumulated
+during the DATA and MIME ACLs, after which matching headers are removed
+if present. In the case of non-SMTP messages, remove specifiers are
+accumulated during the non-SMTP ACLs, and are acted on after
all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
ACL, there really is no effect because there is no logging of what headers
would have been removed.
.display
&`A `& authenticator name (and optional id and sender)
&`C `& SMTP confirmation on delivery
+&`Ci `& connection identifier
&` `& command list for &"no mail in SMTP session"&
&`CV `& certificate verification status
&`D `& duration of &"no mail in SMTP session"&
.section "Reducing or increasing what is logged" "SECTlogselector"
.cindex "log" "selectors"
By setting the &%log_selector%& global option, you can disable some of Exim's
-default logging, or you can request additional logging. The value of
+default logging to the main log, or you can request additional logging. The value of
&%log_selector%& is made up of names preceded by plus or minus characters. For
example:
.code
.irow &`address_rewrite`& "address rewriting"
.irow &`all_parents`& "all parents in => lines"
.irow &`arguments`& "command line arguments"
+.irow &`connection_id`& "connection identifier"
.irow &`connection_reject`& * "connection rejections"
.irow &`delay_delivery`& * "immediate delivery delayed"
.irow &`deliver_time`& "time taken to attempt delivery"
only way to log such cases is to interpose a script such as &_util/logargs.sh_&
between the caller and Exim.
.next
+.cindex "log" "connection identifier"
+.new
+&%connection_identifier%&: An identifier for the accepted connection is added to
+connection start and end lines and to message accept lines.
+The identifier is tagged by Ci=.
+The value is PID-based, so will reset on reboot and will wrap.
+.wen
+.next
.cindex "log" "connection rejections"
&%connection_reject%&: A log entry is written whenever an incoming SMTP
connection is rejected, for whatever reason.
.next
Limiting the concurrency of specific transports (when &%max_parallel%& is set
in a transport)
+.next
+Recording EHLO-time facilities advertised by hosts
.endlist
.endlist
-In addition, two ACL conditions are provided:
+In addition, two ACL conditions are provided, usable only in a DKIM ACL:
.vlist
.vitem &%dkim_signers%&
If this value is empty the the expansion result will be empty.
The third argument should be the recipient domain of the message when
it arrived at this system.
+All arguments are expanded before use.
+
+The result of the expansion is the replacement envelope-from (return path)
+to be used.
.endlist
.cindex SRS decoding
To decode an address use this expansion condition:
.vlist
.vitem &*inbound_srs&~{*&<&'local&~part'&>&*}{*&<&'secret'&>&*}*&
-The first argument should be the recipient local prt as is was received.
+The first argument should be the recipient local part as it was received.
The second argument is the site secret.
+Both arguments are expanded before use.
If the messages is not for an SRS-encoded recipient the condition will
-return false. If it is, the condition will return true and the variable
+return false.
+If it is, the condition will return true and the variable
&$srs_recipient$& will be set to the decoded (original) value.
+
+.new
+If the second argument is empty then the condition returns true if
+the first argument is in valid SRS formet, else false.
+The variable &$srs_recipient$& is not set for this case.
+.wen
.endlist
Example usage:
git://git.exim.org / exim.git / blobdiff