.set drivernamemax "64"
.macro copyyear
-2021
+2022
.endmacro
. /////////////////////////////////////////////////////////////////////////////
.itable none 0 0 2 $1 left $2 left
.endmacro
+
+. --- A macro for a "tainted" marker, done as a one-element table
+.macro tmark
+.itable none 0 0 1 10pt left
+.row &'Tainted'&
+.endtable
+.endmacro
+. --- A macro for a tainted variable, adding a taint-marker
+. --- and including the .vitem and .vindex
+.macro tvar
+.vitem $1
+.vindex $1
+.tmark
+.endmacro
+
. --- A macro that generates .row, but puts &I; at the start of the first
. --- argument, thus indenting it. Assume a minimum of two arguments, and
. --- allow up to four arguments, which is as many as we'll ever need.
If the &%domains%& option is set, the domain of the address must be in the set
of domains that it defines.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
A match verifies the variable &$domain$& (which carries tainted data)
and assigns an untainted value to the &$domain_data$& variable.
Such an untainted value is often needed in the transport.
debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that
no spaces are allowed in the debug setting. The available debugging categories
are:
-.display
-&`acl `& ACL interpretation
-&`auth `& authenticators
-&`deliver `& general delivery logic
-&`dns `& DNS lookups (see also resolver)
-&`dnsbl `& DNS black list (aka RBL) code
-&`exec `& arguments for &[execv()]& calls
-&`expand `& detailed debugging for string expansions
-&`filter `& filter handling
-&`hints_lookup `& hints data lookups
-&`host_lookup `& all types of name-to-IP address handling
-&`ident `& ident lookup
-&`interface `& lists of local interfaces
-&`lists `& matching things in lists
-&`load `& system load checks
-&`local_scan `& can be used by &[local_scan()]& (see chapter &&&
- &<<CHAPlocalscan>>&)
-&`lookup `& general lookup code and all lookups
-&`memory `& memory handling
-&`noutf8 `& modifier: avoid UTF-8 line-drawing
-&`pid `& modifier: add pid to debug output lines
-&`process_info `& setting info for the process log
-&`queue_run `& queue runs
-&`receive `& general message reception logic
-&`resolver `& turn on the DNS resolver's debugging output
-&`retry `& retry handling
-&`rewrite `& address rewriting
-&`route `& address routing
-&`timestamp `& modifier: add timestamp to debug output lines
-&`tls `& TLS logic
-&`transport `& transports
-&`uid `& changes of uid/gid and looking up uid/gid
-&`verify `& address verification logic
-&`all `& almost all of the above (see below), and also &%-v%&
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow acl "ACL interpretation"
+.irow auth "authenticators"
+.irow deliver "general delivery logic"
+.irow dns "DNS lookups (see also resolver)"
+.irow dnsbl "DNS black list (aka RBL) code"
+.irow exec "arguments for &[execv()]& calls"
+.irow expand "detailed debugging for string expansions"
+.irow filter "filter handling"
+.irow hints_lookup "hints data lookups"
+.irow host_lookup "all types of name-to-IP address handling"
+.irow ident "ident lookup"
+.irow interface "lists of local interfaces"
+.irow lists "matching things in lists"
+.irow load "system load checks"
+.irow local_scan "can be used by &[local_scan()]& (see chapter &&&
+ &<<CHAPlocalscan>>&)"
+.irow lookup "general lookup code and all lookups"
+.irow memory "memory handling"
+.irow noutf8 "modifier: avoid UTF-8 line-drawing"
+.irow pid "modifier: add pid to debug output lines"
+.irow process_info "setting info for the process log"
+.irow queue_run "queue runs"
+.irow receive "general message reception logic"
+.irow resolver "turn on the DNS resolver's debugging output"
+.irow retry "retry handling"
+.irow rewrite "address rewriting""
+.irow route "address routing"
+.irow timestamp "modifier: add timestamp to debug output lines"
+.irow tls "TLS logic"
+.irow transport "transports"
+.irow uid "changes of uid/gid and looking up uid/gid"
+.irow verify "address verification logic"
+.irow all "almost all of the above (see below), and also &%-v%&"
+.endtable
The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it
for &`-all`&. The reason for this is that &`+all`& is something that people
tend to use when generating debug output for Exim maintainers. If &`+memory`&
When the lookup succeeds, the result of the expansion is a list of domains (and
possibly other types of item that are allowed in domain lists).
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a lookup expansion""
The result of the expansion is not tainted.
In the second example, the lookup is a single item in a domain list. It causes
The file string may not be tainted.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a single-key lookup"
All single-key lookups support the option &"ret=key"&.
If this is given and the lookup
(either underlying implementation or cached value)
returns data, the result is replaced with a non-tainted
version of the lookup key.
-.cindex "tainted data" "de-tainting"
.next
.cindex "query-style lookup" "definition of"
The &'query-style'& type accepts a generalized database query. No particular
spaces. If a value contains spaces it must be enclosed in double quotes, and
when double quotes are used, backslash is interpreted in the usual way inside
them. The following names are recognized:
-.display
-&`DEREFERENCE`& set the dereferencing parameter
-&`NETTIME `& set a timeout for a network operation
-&`USER `& set the DN, for authenticating the LDAP bind
-&`PASS `& set the password, likewise
-&`REFERRALS `& set the referrals parameter
-&`SERVERS `& set alternate server list for this query only
-&`SIZE `& set the limit for the number of entries returned
-&`TIME `& set the maximum waiting time for a query
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow DEREFERENCE "set the dereferencing parameter"
+.irow NETTIME "set a timeout for a network operation"
+.irow USER "set the DN, for authenticating the LDAP bind"
+.irow PASS "set the password, likewise"
+.irow REFERRALS "set the referrals parameter"
+.irow SERVERS "set alternate server list for this query only"
+.irow SIZE "set the limit for the number of entries returned"
+.irow TIME "set the maximum waiting time for a query"
+.endtable
The value of the DEREFERENCE parameter must be one of the words &"never"&,
&"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter
must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP
&$domain_data$& variable and can be referred to in other router options or
other statements in the same ACL.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using ACL domains condition"
The value will be untainted.
&*Note*&: If the data result of the lookup (as opposed to the key)
&%domains%& option on a router, the value is preserved in the &$domain_data$&
variable and can be referred to in other options.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router domains option"
The value will be untainted.
.next
a shell, you must explicitly code it.
The command name may not be tainted, but the remaining arguments can be.
+&*Note*&: if tainted arguments are used, they are supplied by a
+potential attacker;
+a careful assessment for security vulnerabilities should be done.
+
If the option &'preexpand'& is used,
.wen
the command and its arguments are first expanded as one string. The result is
-.vitem &*${substr{*&<&'string1'&>&*}{*&<&'string2'&>&*}{*&<&'string3'&>&*}}*&
+.vitem &*${substr{*&<&'start'&>&*}{*&<&'len'&>&*}{*&<&'subject'&>&*}}*&
.cindex "&%substr%& expansion item"
.cindex "substring extraction"
.cindex "expansion" "substring extraction"
The three strings are expanded; the first two must yield numbers. Call them
<&'n'&> and <&'m'&>. If you are using fixed values for these numbers, that is,
-if <&'string1'&> and <&'string2'&> do not change when they are expanded, you
+if <&'start'&> and <&'len'&> do not change when they are expanded, you
can use the simpler operator notation that avoids some of the braces:
.code
-${substr_<n>_<m>:<string>}
+${substr_<n>_<m>:<subject>}
.endd
The second number is optional (in both notations).
If it is absent in the simpler format, the preceding underscore must also be
.cindex "expansion" "numeric comparison"
There are a number of symbolic operators for doing numeric comparisons. They
are:
-.display
-&`= `& equal
-&`== `& equal
-&`> `& greater
-&`>= `& greater or equal
-&`< `& less
-&`<= `& less or equal
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow "= " "equal"
+.irow "== " "equal"
+.irow "> " "greater"
+.irow ">= " "greater or equal"
+.irow "< " "less"
+.irow "<= " "less or equal"
+.endtable
For example:
.code
${if >{$message_size}{10M} ...
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.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using an inlist expansion condition"
It will have the same taint status as the list; expansions such as
.code
${if inlist {$h_mycode:} {0 : 1 : 42} {$value}}
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.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using a match_local_part expansion condition"
It will have the same taint status as the list; expansions such as
.code
${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}}
This section contains an alphabetical list of all the expansion variables. Some
of them are available only when Exim is compiled with specific options such as
support for TLS or the content scanning extension.
+.new
+.cindex "tainted data"
+Variables marked as &'tainted'& are likely to carry data supplied by
+a potential attacker.
+Variables without such marking may also, depending on how their
+values are created.
+Such variables should not be further expanded,
+used as filenames
+or used as command-line arguments for external commands.
+.wen
.vlist
.vitem "&$0$&, &$1$&, etc"
precedes the expansion of the string. For example, the commands available in
Exim filter files include an &%if%& command with its own regular expression
matching condition.
+.new
+If the subject string was tainted then any captured substring will also be.
+.wen
.vitem "&$acl_arg1$&, &$acl_arg2$&, etc"
Within an acl condition, expansion condition or expansion item
the ACL's as well.
-.vitem &$authenticated_sender$&
+.tvar &$authenticated_sender$&
.cindex "sender" "authenticated"
.cindex "authentication" "sender"
.cindex "AUTH" "on MAIL command"
-.vindex "&$authenticated_sender$&"
When acting as a server, Exim takes note of the AUTH= parameter on an incoming
SMTP MAIL command if it believes the sender is sufficiently trusted, as
described in section &<<SECTauthparamail>>&. Unless the data is the string
possible to distinguish between &"did not try to authenticate"&
(&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to
&"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$&
-is empty and &$authentication_failed$& is set to &"1"&). Failure includes any
-negative response to an AUTH command, including (for example) an attempt to use
-an undefined mechanism.
+is empty and &$authentication_failed$& is set to &"1"&).
+Failure includes cancellation of a authentication attempt,
+and any negative response to an AUTH command,
+(including, for example, an attempt to use an undefined mechanism).
.vitem &$av_failed$&
.cindex "content scanning" "AV scanner failure"
looked up, the contents of any associated TXT record, and the value from the
main A record. See section &<<SECID204>>& for more details.
-.vitem &$domain$&
-.vindex "&$domain$&"
+.tvar &$domain$&
When an address is being routed, or delivered on its own, this variable
contains the domain. Uppercase letters in the domain are converted into lower
case for &$domain$&.
This value may be overridden by the &%exim_version%& main config option.
.vitem &$header_$&<&'name'&>
+.tmark
This is not strictly an expansion variable. It is expansion syntax for
inserting the message header line with the given name. Note that the name must
be terminated by colon or white space, because it may contain a wide variety of
deny hosts = net-lsearch;/some/file
message = $host_data
.endd
+
.vitem &$host_lookup_deferred$&
.cindex "host name" "lookup, failure of"
.vindex "&$host_lookup_deferred$&"
is an integer. For example, if the load average is 0.21, the value of the
variable is 210. The value is recomputed every time the variable is referenced.
-.vitem &$local_part$&
-.vindex "&$local_part$&"
+.tvar &$local_part$&
When an address is being routed, or delivered on its own, this
variable contains the local part. When a number of addresses are being
delivered together (for example, multiple RCPT commands in an SMTP
of seconds since the message was received. It does not change during a single
delivery attempt.
-.vitem &$message_body$&
+.tvar &$message_body$&
.cindex "body of message" "expansion variable"
.cindex "message body" "in expansion"
.cindex "binary zero" "in message body"
-.vindex "&$message_body$&"
.oindex "&%message_body_visible%&"
This variable contains the initial portion of a message's body while it is
being delivered, and is intended mainly for use in filter files. The maximum
this can be disabled by setting &%message_body_newlines%& to be true. Binary
zeros are always converted into spaces.
-.vitem &$message_body_end$&
+.tvar &$message_body_end$&
.cindex "body of message" "expansion variable"
.cindex "message body" "in expansion"
-.vindex "&$message_body_end$&"
This variable contains the final portion of a message's
body while it is being delivered. The format and maximum size are as for
&$message_body$&.
line; it is the local id that Exim assigns to the message, for example:
&`1BXTIK-0001yO-VA`&.
-.vitem &$message_headers$&
-.vindex &$message_headers$&
+.tvar &$message_headers$&
This variable contains a concatenation of all the header lines when a message
is being processed, except for lines added by routers or transports. The header
lines are separated by newline characters. Their contents are decoded in the
same way as a header line that is inserted by &%bheader%&.
-.vitem &$message_headers_raw$&
-.vindex &$message_headers_raw$&
+.tvar &$message_headers_raw$&
This variable is like &$message_headers$& except that no processing of the
contents of header lines is done.
These variables are counters that can be incremented by means
of the &%add%& command in filter files.
-.vitem &$original_domain$&
+.tvar &$original_domain$&
.vindex "&$domain$&"
-.vindex "&$original_domain$&"
When a top-level address is being processed for delivery, this contains the
same value as &$domain$&. However, if a &"child"& address (for example,
generated by an alias, forward, or filter file) is being processed, this
filter, it is set up with an artificial &"parent"& address. This has the local
part &'system-filter'& and the default qualify domain.
-.vitem &$original_local_part$&
+.tvar &$original_local_part$&
.vindex "&$local_part$&"
-.vindex "&$original_local_part$&"
When a top-level address is being processed for delivery, this contains the
same value as &$local_part$&, unless a prefix or suffix was removed from the
local part, because &$original_local_part$& always contains the full local
For messages received by SMTP over TCP/IP, this is normally the uid of the Exim
user.
-.vitem &$parent_domain$&
-.vindex "&$parent_domain$&"
+.tvar &$parent_domain$&
This variable is similar to &$original_domain$& (see
above), except that it refers to the immediately preceding parent address.
-.vitem &$parent_local_part$&
-.vindex "&$parent_local_part$&"
+.tvar &$parent_local_part$&
This variable is similar to &$original_local_part$&
(see above), except that it refers to the immediately preceding parent address.
(described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
It cannot be used in general expansion strings, and provokes an &"unknown
variable"& error if encountered.
+.new
+&*Note*&: This value permits data supplied by a potential attacker to
+be used in the command for a &(pipe)& transport.
+Such configurations should be carefully assessed for security vulnerbilities.
+.wen
.vitem &$primary_hostname$&
.vindex "&$primary_hostname$&"
is available in the DATA ACL, the non-SMTP ACL, and while routing and
delivering.
-.vitem &$received_for$&
-.vindex "&$received_for$&"
+.tvar &$received_for$&
If there is only a single recipient address in an incoming message, this
variable contains that address when the &'Received:'& header line is being
built. The value is copied after recipient rewriting has happened, but before
The main use of this variable is expected to be to distinguish between
rejections of MAIL and rejections of RCPT.
-.vitem &$recipients$&
-.vindex "&$recipients$&"
+.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
When a &%regex%& or &%mime_regex%& ACL condition succeeds,
these variables contain the
captured substrings identified by the regular expression.
+.new
+If the subject string was tainted then so will any captured substring.
+.wen
-.vitem &$reply_address$&
-.vindex "&$reply_address$&"
+.tvar &$reply_address$&
When a message is being processed, this variable contains the contents of the
&'Reply-To:'& header line if one exists and it is not empty, or otherwise the
contents of the &'From:'& header line. Apart from the removal of leading
happens, &$self_hostname$& is set to the name of the local host that the
original router encountered. In other circumstances its contents are null.
-.vitem &$sender_address$&
-.vindex "&$sender_address$&"
+.tvar &$sender_address$&
When a message is being processed, this variable contains the sender's address
that was received in the message's envelope. The case of letters in the address
is retained, in both the local part and the domain. For bounce messages, the
after the end of the current ACL statement. If you want to preserve it for
longer, you can save it in an ACL variable.
-.vitem &$sender_address_domain$&
-.vindex "&$sender_address_domain$&"
+.tvar &$sender_address_domain$&
The domain portion of &$sender_address$&.
-.vitem &$sender_address_local_part$&
-.vindex "&$sender_address_local_part$&"
+.tvar &$sender_address_local_part$&
The local part portion of &$sender_address$&.
.vitem &$sender_data$&
.cindex "DNS" "DNSSEC"
done using DNS information the resolver library stated was authenticated data.
-.vitem &$sender_helo_name$&
-.vindex "&$sender_helo_name$&"
+.tvar &$sender_helo_name$&
When a message is received from a remote host that has issued a HELO or EHLO
command, the argument of that command is placed in this variable. It is also
set if HELO or EHLO is used when a message is received using SMTP locally via
is known to currently ignore EDNS0, documented in CAVEATS of asr_run(3).
-.vitem &$sender_host_name$&
-.vindex "&$sender_host_name$&"
+.tvar &$sender_host_name$&
When a message is received from a remote host, this variable contains the
host's name as obtained by looking up its IP address. For messages received by
other means, this variable is empty.
&$smtp_active_hostname$& is saved with any message that is received, so its
value can be consulted during routing and delivery.
-.vitem &$smtp_command$&
-.vindex "&$smtp_command$&"
+.tvar &$smtp_command$&
During the processing of an incoming SMTP command, this variable contains the
entire command. This makes it possible to distinguish between HELO and EHLO in
the HELO ACL, and also to distinguish between commands such as these:
rewriting, whereas the values in &$local_part$& and &$domain$& are taken from
the address after SMTP-time rewriting.
-.vitem &$smtp_command_argument$&
+.tvar &$smtp_command_argument$&
.cindex "SMTP" "command, argument for"
-.vindex "&$smtp_command_argument$&"
While an ACL is running to check an SMTP command, this variable contains the
argument, that is, the text that follows the command name, with leading white
space removed. Following the introduction of &$smtp_command$&, this variable is
Observability for TLS session resumption. See &<<SECTresumption>>& for details.
-.vitem &$tls_in_sni$&
-.vindex "&$tls_in_sni$&"
+.tvar &$tls_in_sni$&
.vindex "&$tls_sni$&"
.cindex "TLS" "Server Name Indication"
.cindex "TLS" SNI
.row &%log_timezone%& "add timezone to log lines"
.row &%message_logs%& "create per-message logs"
.row &%preserve_message_logs%& "after message completion"
+.row &%panic_coredump%& "request coredump on fatal errors"
.row &%process_log_path%& "for SIGUSR1 and &'exiwhat'&"
.row &%slow_lookup_log%& "control logging of slow DNS lookups"
.row &%syslog_duplication%& "controls duplicate log lines on syslog"
.row &%gnutls_compat_mode%& "use GnuTLS compatibility mode"
.row &%gnutls_allow_auto_pkcs11%& "allow GnuTLS to autoload PKCS11 modules"
.row &%hosts_require_alpn%& "mandatory ALPN"
+.row &%hosts_require_helo%& "mandatory HELO/EHLO"
.row &%openssl_options%& "adjust OpenSSL compatibility options"
.row &%tls_advertise_hosts%& "advertise TLS to these hosts"
.row &%tls_alpn%& "acceptable protocol names"
.code
hosts_connection_nolog = :
.endd
-If the &%smtp_connection%& log selector is not set, this option has no effect.
+.new
+The hosts affected by this option also do not log "no MAIL in SMTP connection"
+lines, as may commonly be produced by a monitoring system.
+.wen
.option hosts_require_alpn main "host list&!!" unset
managed by this option, and should be done separately.
+.option hosts_require_helo main "host list&!!" *
+.cindex "HELO/EHLO" requiring
+Exim will require an accepted HELO or EHLO command from a host matching
+this list, before accepting a MAIL command.
+
+
.option hosts_proxy main "host list&!!" unset
.cindex proxy "proxy protocol"
This option enables use of Proxy Protocol proxies for incoming
The option is available only if Exim has been built with Oracle support.
+.new
+.option panic_coredump main boolean false
+This option is rarely needed but can help for some debugging investigations.
+If set, when an internal error is detected by Exim which is sufficient
+to terminate the process
+(all such are logged in the paniclog)
+then a coredump is requested.
+
+Note that most systems require additional administrative configuration
+to permit write a core file for a setuid program, which is Exim's
+common installed configuration.
+.wen
+
.option percent_hack_domains main "domain list&!!" unset
.cindex "&""percent hack""&"
.cindex "source routing" "in email address"
.option pipelining_connect_advertise_hosts main "host list&!!" *
.cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
-.cindex "ESMTP extensions" PIPE_CONNECT
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+.cindex "pipelining" PIPECONNECT
+.cindex "ESMTP extensions" PIPECONNECT
+If Exim is built without the DISABLE_PIPE_CONNECT build option
this option controls which hosts the facility is advertised to
and from which pipeline early-connection (before MAIL) SMTP
commands are acceptable.
See also the &%hosts_pipe_connect%& smtp transport option.
-The SMTP service extension keyword advertised is &"PIPE_CONNECT"&.
+The SMTP service extension keyword advertised is &"PIPECONNECT"&;
+it permits the client to pipeline
+TCP connection and hello command (inclear phase),
+or TLS-establishment and hello command (encrypted phase),
+on later connections to the same host.
.option prdr_enable main boolean false
next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&.
-.option queue_fast_ramp main boolean false
+.option queue_fast_ramp main boolean true
.cindex "queue runner" "two phase"
.cindex "queue" "double scanning"
If set to true, two-phase queue runs, initiated using &%-qq%& on the
for the remaining recipients at a later time.
-.option remote_max_parallel main integer 2
+.option remote_max_parallel main integer 4
.cindex "delivery" "parallelism for remote"
This option controls parallel delivery of one message to a number of remote
hosts. If the value is less than 2, parallel delivery is disabled, and Exim
holding password data (such as NIS) are supported. If the local part is a local
user,
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using router check_local_user option"
&$local_part_data$& is set to an untainted version of the local part and
&$home$& is set from the password data. The latter can be tested in other
preconditions that are evaluated after this one (the order of evaluation is
The expansion variables &$host$& and &$host_address$& are available when the
transport is a remote one. They contain the name and IP address of the host to
which the message is being sent. For example:
+. used to have $sender_address in this cmdline, but it's tainted
.code
transport_filter = /some/directory/transport-filter.pl \
- $host $host_address $sender_address $pipe_addresses
+ $host $host_address $pipe_addresses
.endd
Two problems arise if you want to use more complicated expansion items to
checking is done in "belowhome" mode.
.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using appendfile create_file option"
If "belowhome" checking is used, the file or directory path
becomes de-tainted.
the &%environment%& option can be used to add additional variables to this
environment. The environment for the &(pipe)& transport is not subject
to the &%add_environment%& and &%keep_environment%& main config options.
+.new
+&*Note*&: Using enviroment variables loses track of tainted data.
+Writers of &(pipe)& transport commands should be wary of data supplied
+by potential attackers.
+.wen
.display
&`DOMAIN `& the domain of the address
&`HOME `& the home directory, if set
Exim, and each argument is separately expanded, as described in section
&<<SECThowcommandrun>>& above.
+.new
+.cindex "tainted data"
+No part of the resulting command may be tainted.
+.wen
+
.option environment pipe string&!! unset
.cindex "&(pipe)& transport" "environment for command"
.cindex "Cyrus"
The next example shows a transport and a router for a system where local
deliveries are handled by the Cyrus IMAP server.
+. Used to have R: local_part_suffix = .* + T: -m $local_part_suffix_v
+. but that suffix is tainted so cannot be used in a command arg
+. Really, you'd want to use a lookup for acceptable suffixes to do real detainting
.code
# transport
local_delivery_cyrus:
driver = pipe
command = /usr/cyrus/bin/deliver \
- -m ${substr_1:$local_part_suffix} -- $local_part
+ -- $local_part_data
user = cyrus
group = mail
return_output
local_user_cyrus:
driver = accept
check_local_user
- local_part_suffix = .*
transport = local_delivery_cyrus
.endd
Note the unsetting of &%message_prefix%& and &%message_suffix%&, and the use of
The use of &%helo_data%& applies both to sending messages and when doing
callouts.
+.new
+.option host_name_extract smtp "string list&!!" "see below"
+.cindex "load balancer" "hosts behind"
+.cindex TLS resumption
+Some mail-accepting sites
+(notably Microsoft)
+operate many servers behind a network load-balancer. When this is done,
+with separated TLS session caches, TLS session resuption becomes problematic.
+It will only succeed when the same server happens to be selected by the
+load-balancer, matching the session stored in the client's cache.
+
+Exim can pull out a server name, if there is one, from the response to the
+client's SMTP EHLO command.
+The default value of this option:
+.code
+ ${if and { {match {$host} {.outlook.com\$}} \
+ {match {$item} {\N^250-([\w.]+)\s\N}} \
+ } {$1}}
+.endd
+suffices for one known case.
+During the expansion of this option the &$item$& variable will have the
+server's EHLO response.
+The result of the option expansion is included in the key used to store and
+retrieve the TLS session, for session resumption.
+
+Operators of high-load sites may wish to evaluate their logs for indications
+of other destination sites operating load-balancers, and develop a suitable
+expression for this option.
+The smtp:ehlo event and the &$tls_out_resumption$& variable
+will be useful for such work.
+.wen
+
.option hosts smtp "string list&!!" unset
Hosts are associated with an address by a router such as &(dnslookup)&, which
finds the hosts by looking up the address domain in the DNS, or by
.option hosts_pipe_connect smtp "host list&!!" unset
.cindex "pipelining" "early connection"
-.cindex "pipelining" PIPE_CONNECT
+.cindex "pipelining" PIPECONNECT
If Exim is built with the SUPPORT_PIPE_CONNECT build option
this option controls which to hosts the facility watched for
and recorded, and used for subsequent connections.
See the &%dnssec_request_domains%& router and transport options.
See section &<<SECDANE>>&.
-.option hosts_require_helo smtp "host list&!!" *
-.cindex "HELO/EHLO" requiring
-Exim will require an accepted HELO or EHLO command from a host matching
-this list, before accepting a MAIL command.
-
.option hosts_require_ocsp smtp "host list&!!" unset
.cindex "TLS" "requiring for certain servers"
Exim will request, and check for a valid Certificate Status being given, on a
by default called &'debuglog'&.
.new
+Logging set up by the control will be maintained across spool residency.
+
Options are a slash-separated list.
If an option takes an argument, the option name and argument are separated by
an equals character.
(which is the most common usage), because it prevents a DNS failure from
blocking mail. However, you can change this behaviour by putting one of the
following special items in the list:
-.display
-&`+include_unknown `& behave as if the item is on the list
-&`+exclude_unknown `& behave as if the item is not on the list (default)
-&`+defer_unknown `& give a temporary error
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow "+include_unknown" "behave as if the item is on the list"
+.irow "+exclude_unknown" "behave as if the item is not on the list (default)"
+.irow "+defer_unknown " "give a temporary error"
+.endtable
.cindex "&`+include_unknown`&"
.cindex "&`+exclude_unknown`&"
.cindex "&`+defer_unknown`&"
just used the address 127.0.0.1 on the right hand side of each record, but the
RBL+ list and some other lists use a number of values with different meanings.
The values used on the RBL+ list are:
-.display
-127.1.0.1 RBL
-127.1.0.2 DUL
-127.1.0.3 DUL and RBL
-127.1.0.4 RSS
-127.1.0.5 RSS and RBL
-127.1.0.6 RSS and DUL
-127.1.0.7 RSS and DUL and RBL
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow 127.1.0.1 "RBL"
+.irow 127.1.0.2 "DUL"
+.irow 127.1.0.3 "DUL and RBL"
+.irow 127.1.0.4 "RSS"
+.irow 127.1.0.5 "RSS and RBL"
+.irow 127.1.0.6 "RSS and DUL"
+.irow 127.1.0.7 "RSS and DUL and RBL"
+.endtable
Section &<<SECTaddmatcon>>& below describes how you can distinguish between
different values. Some DNS lists may return more than one address record;
see section &<<SECThanmuldnsrec>>& for details of how they are checked.
It uses a hints database to record a timestamp against a key.
host. The syntax of the condition is:
.display
-&`seen =`& <&'time interval'&> &`/`& <&'options'&>
+&`seen =`& <&'optional flag'&><&'time interval'&> &`/`& <&'options'&>
.endd
For example,
.endd
in a RCPT ACL will implement simple greylisting.
-The parameters for the condition
-are an interval followed, slash-separated, by a list of options.
+The parameters for the condition are
+a possible minus sign,
+then an interval,
+then, slash-separated, a list of options.
The interval is taken as an offset before the current time,
and used for the test.
If the interval is preceded by a minus sign then the condition returns
If a &%write%& option is given then
a record create or update is always done.
An update is done if the test is for &"since"&.
+If none of those hold and there was no existing record,
+a record is created.
Creates and updates are marked with the current time.
clients when the SMTP PIPELINING extension is in use. The flushing can be
disabled by using a &%control%& modifier to set &%no_callout_flush%&.
+.new
+.cindex "tainted data" "de-tainting"
+.cindex "de-tainting" "using receipient verify"
+A recipient callout which gets a 2&'xx'& code
+will assign untainted values to the
+&$domain_data$& and &$local_part_data$& variables,
+corresponding to the domain and local parts of the recipient address.
+.wen
+
.vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*&
This function checks for a match in a domain list. Domains are always
matched caselessly. The return value is one of the following:
-.display
-&`OK `& match succeeded
-&`FAIL `& match failed
-&`DEFER `& match deferred
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &`OK`& "match succeeded"
+.irow &`FAIL`& "match failed"
+.irow &`DEFER`& "match deferred"
+.endtable
DEFER is usually caused by some kind of lookup defer, such as the
inability to contact a database.
&"syslog"&. This means that an empty item in &%log_file_path%& can be used to
mean &"use the path specified at build time"&. If no such item exists, log
files are written in the &_log_& subdirectory of the spool directory. This is
-equivalent to the setting:
+equivalent to the configuration file setting:
.code
log_file_path = $spool_directory/log/%slog
.endd
A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames
are in use &-- see section &<<SECTdatlogfil>>& below.
-Here are some examples of possible settings:
+Here are some examples of possible Makefile settings:
.display
&`LOG_FILE_PATH=syslog `& syslog only
&`LOG_FILE_PATH=:syslog `& syslog and default path
successful, unsuccessful, and delayed delivery. These lines can readily be
picked out by the distinctive two-character flags that immediately follow the
timestamp. The flags are:
-.display
-&`<=`& message arrival
-&`(=`& message fakereject
-&`=>`& normal message delivery
-&`->`& additional address in same delivery
-&`>>`& cutthrough message delivery
-&`*>`& delivery suppressed by &%-N%&
-&`**`& delivery failed; address bounced
-&`==`& delivery deferred; temporary problem
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &%<=%& "message arrival"
+.irow &%(=%& "message fakereject"
+.irow &%=>%& "normal message delivery"
+.irow &%->%& "additional address in same delivery"
+.irow &%>>%& "cutthrough message delivery"
+.irow &%*>%& "delivery suppressed by &%-N%&"
+.irow &%**%& "delivery failed; address bounced"
+.irow &%==%& "delivery deferred; temporary problem"
+.endtable
.section "Logging message reception" "SECID251"
.endd
The list of optional log items is in the following table, with the default
selection marked by asterisks:
-.display
-&` 8bitmime `& received 8BITMIME status
-&`*acl_warn_skipped `& skipped &%warn%& statement in ACL
-&` address_rewrite `& address rewriting
-&` all_parents `& all parents in => lines
-&` arguments `& command line arguments
-&`*connection_reject `& connection rejections
-&`*delay_delivery `& immediate delivery delayed
-&` deliver_time `& time taken to attempt delivery
-&` delivery_size `& add &`S=`&&'nnn'& to => lines
-&`*dkim `& DKIM verified domain on <= lines
-&` dkim_verbose `& separate full DKIM verification result line, per signature
-&`*dnslist_defer `& defers of DNS list (aka RBL) lookups
-&` dnssec `& DNSSEC secured lookups
-&`*etrn `& ETRN commands
-&`*host_lookup_failed `& as it says
-&` ident_timeout `& timeout for ident connection
-&` incoming_interface `& local interface on <= and => lines
-&` incoming_port `& remote port on <= lines
-&`*lost_incoming_connection `& as it says (includes timeouts)
-&` millisec `& millisecond timestamps and RT,QT,DT,D times
-&`*msg_id `& on <= lines, Message-ID: header value
-&` msg_id_created `& on <= lines, Message-ID: header value when one had to be added
-&` outgoing_interface `& local interface on => lines
-&` outgoing_port `& add remote port to => lines
-&`*queue_run `& start and end queue runs
-&` queue_time `& time on queue for one recipient
-&`*queue_time_exclusive `& exclude recieve time from QT times
-&` queue_time_overall `& time on queue for whole message
-&` pid `& Exim process id
-&` pipelining `& PIPELINING use, on <= and => lines
-&` proxy `& proxy address on <= and => lines
-&` receive_time `& time taken to receive message
-&` received_recipients `& recipients on <= lines
-&` received_sender `& sender on <= lines
-&`*rejected_header `& header contents on reject log
-&`*retry_defer `& &"retry time not reached"&
-&` return_path_on_delivery `& put return path on => and ** lines
-&` sender_on_delivery `& add sender to => lines
-&`*sender_verify_fail `& sender verification failures
-&`*size_reject `& rejection because too big
-&`*skip_delivery `& delivery skipped in a queue run
-&`*smtp_confirmation `& SMTP confirmation on => lines
-&` smtp_connection `& incoming SMTP connections
-&` smtp_incomplete_transaction`& incomplete SMTP transactions
-&` smtp_mailauth `& AUTH argument to MAIL commands
-&` smtp_no_mail `& session with no MAIL commands
-&` smtp_protocol_error `& SMTP protocol errors
-&` smtp_syntax_error `& SMTP syntax errors
-&` subject `& contents of &'Subject:'& on <= lines
-&`*tls_certificate_verified `& certificate verification status
-&`*tls_cipher `& TLS cipher suite on <= and => lines
-&` tls_peerdn `& TLS peer DN on <= and => lines
-&` tls_resumption `& append * to cipher field
-&` tls_sni `& TLS SNI on <= lines
-&` unknown_in_list `& DNS lookup failed in list match
-
-&` all `& all of the above
-.endd
+.itable none 0 0 3 1pt left 10pt center 1pt left
+.irow &`8bitmime`& "received 8BITMIME status"
+.irow &`acl_warn_skipped`& * "skipped &%warn%& statement in ACL"
+.irow &`address_rewrite`& "address rewriting"
+.irow &`all_parents`& "all parents in => lines"
+.irow &`arguments`& "command line arguments"
+.irow &`connection_reject`& * "connection rejections"
+.irow &`delay_delivery`& * "immediate delivery delayed"
+.irow &`deliver_time`& "time taken to attempt delivery"
+.irow &`delivery_size`& "add &`S=`&&'nnn'& to => lines"
+.irow &`dkim`& * "DKIM verified domain on <= lines"
+.irow &`dkim_verbose`& "separate full DKIM verification result line, per signature"
+.irow &`dnslist_defer`& * "defers of DNS list (aka RBL) lookups"
+.irow &`dnssec`& "DNSSEC secured lookups"
+.irow &`etrn`& * "ETRN commands"
+.irow &`host_lookup_failed`& * "as it says"
+.irow &`ident_timeout`& "timeout for ident connection"
+.irow &`incoming_interface`& "local interface on <= and => lines"
+.irow &`incoming_port`& "remote port on <= lines"
+.irow &`lost_incoming_connection`& * "as it says (includes timeouts)"
+.irow &`millisec`& "millisecond timestamps and RT,QT,DT,D times"
+.irow &`msg_id`& * "on <= lines, Message-ID: header value"
+.irow &`msg_id_created`& "on <= lines, Message-ID: header value when one had to be added"
+.irow &`outgoing_interface`& "local interface on => lines"
+.irow &`outgoing_port`& "add remote port to => lines"
+.irow &`queue_run`& * "start and end queue runs"
+.irow &`queue_time`& "time on queue for one recipient"
+.irow &`queue_time_exclusive`& "exclude recieve time from QT times"
+.irow &`queue_time_overall`& "time on queue for whole message"
+.irow &`pid`& "Exim process id"
+.irow &`pipelining`& "PIPELINING use, on <= and => lines"
+.irow &`proxy`& "proxy address on <= and => lines"
+.irow &`receive_time`& "time taken to receive message"
+.irow &`received_recipients`& "recipients on <= lines"
+.irow &`received_sender`& "sender on <= lines"
+.irow &`rejected_header`& * "header contents on reject log"
+.irow &`retry_defer`& * "&<quote>&retry time not reached&</quote>&"
+.irow &`return_path_on_delivery`& "put return path on => and ** lines"
+.irow &`sender_on_delivery`& "add sender to => lines"
+.irow &`sender_verify_fail`& * "sender verification failures"
+.irow &`size_reject`& * "rejection because too big"
+.irow &`skip_delivery`& * "delivery skipped in a queue run"
+.irow &`smtp_confirmation`& * "SMTP confirmation on => lines"
+.irow &`smtp_connection`& "incoming SMTP connections"
+.irow &`smtp_incomplete_transaction`& "incomplete SMTP transactions"
+.irow &`smtp_mailauth`& "AUTH argument to MAIL commands"
+.irow &`smtp_no_mail`& "session with no MAIL commands"
+.irow &`smtp_protocol_error`& "SMTP protocol errors"
+.irow &`smtp_syntax_error`& "SMTP syntax errors"
+.irow &`subject`& "contents of &'Subject:'& on <= lines"
+.irow &`tls_certificate_verified`& * "certificate verification status"
+.irow &`tls_cipher`& * "TLS cipher suite on <= and => lines"
+.irow &`tls_peerdn`& "TLS peer DN on <= and => lines"
+.irow &`tls_resumption`& "append * to cipher field"
+.irow &`tls_sni`& "TLS SNI on <= lines"
+.irow &`unknown_in_list`& "DNS lookup failed in list match"
+.irow &`all`& "&*all of the above*&"
+.endtable
See also the &%slow_lookup_log%& main configuration option,
section &<<SECID99>>&
the field has a minus appended.
.cindex "pipelining" "early connection"
-If Exim is built with the SUPPORT_PIPE_CONNECT build option
+If Exim is built without the DISABLE_PIPE_CONNECT build option
accept "L" fields have a period appended if the feature was
offered but not used, or an asterisk appended if used.
Delivery "L" fields have an asterisk appended if used.
system configuration options that configure exactly how &'exiwhat'& works. If
it doesn't seem to be working for you, check the following compile-time
options:
-.display
-&`EXIWHAT_PS_CMD `& the command for running &'ps'&
-&`EXIWHAT_PS_ARG `& the argument for &'ps'&
-&`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output
-&`EXIWHAT_KILL_ARG `& the argument for the &'kill'& command
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &`EXIWHAT_PS_CMD`& "the command for running &'ps'&"
+.irow &`EXIWHAT_PS_ARG`& "the argument for &'ps'&"
+.irow &`EXIWHAT_EGREP_ARG`& "the argument for &'egrep'& to select from &'ps'& output"
+.irow &`EXIWHAT_KILL_ARG`& "the argument for the &'kill'& command"
+.endtable
An example of typical output from &'exiwhat'& is
.code
164 daemon: -q1h, listening on port 25
&'exim_dumpdb'& program,
.new
taking as arguments the spool and database names.
-An option &'-z'& may be given to regest times in UTC;
+An option &'-z'& may be given to request times in UTC;
otherwise times are in the local timezone.
+An option &'-k'& may be given to dump only the record keys.
.wen
For example, to dump the retry database:
.code
right-hand side. These strings describe recommended action based
on the DMARC check. To understand what the policy recommendations
mean, refer to the DMARC website above. Valid strings are:
-.display
-&'accept '& The DMARC check passed and the library recommends accepting the email.
-&'reject '& The DMARC check failed and the library recommends rejecting the email.
-&'quarantine '& The DMARC check failed and the library recommends keeping it for further inspection.
-&'none '& The DMARC check passed and the library recommends no specific action, neutral.
-&'norecord '& No policy section in the DMARC record for this RFC5322.From field
-&'nofrom '& Unable to determine the domain of the sender.
-&'temperror '& Library error or dns error.
-&'off '& The DMARC check was disabled for this email.
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &'accept'& "The DMARC check passed and the library recommends accepting the email"
+.irow &'reject'& "The DMARC check failed and the library recommends rejecting the email"
+.irow &'quarantine'& "The DMARC check failed and the library recommends keeping it for further inspection"
+.irow &'none'& "The DMARC check passed and the library recommends no specific action, neutral"
+.irow &'norecord'& "No policy section in the DMARC record for this RFC5322.From field"
+.irow &'nofrom'& "Unable to determine the domain of the sender"
+.irow &'temperror'& "Library error or dns error"
+.irow &'off'& "The DMARC check was disabled for this email"
+.endtable
You can prefix each string with an exclamation mark to invert its
meaning, for example "!accept" will match all results but
"accept". The string list is evaluated left-to-right in a
The following expansion variables are usable
(&"internal"& and &"external"& here refer to the interfaces
of the proxy):
-.display
-&'proxy_external_address '& IP of host being proxied or IP of remote interface of proxy
-&'proxy_external_port '& Port of host being proxied or Port on remote interface of proxy
-&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy
-&'proxy_local_port '& Port of proxy server inbound or Port on local interface of proxy
-&'proxy_session '& boolean: SMTP connection via proxy
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow $proxy_external_address "IP of host being proxied or IP of remote interface of proxy"
+.irow $proxy_external_port "Port of host being proxied or Port on remote interface of proxy"
+.irow $proxy_local_address "IP of proxy server inbound or IP of local interface of proxy"
+.irow $proxy_local_port "Port of proxy server inbound or Port on local interface of proxy"
+.irow $proxy_session "boolean: SMTP connection via proxy"
+.endtable
If &$proxy_session$& is set but &$proxy_external_address$& is empty
there was a protocol error.
The variables &$sender_host_address$& and &$sender_host_port$&
Options are a string <name>=<value>.
The list of options is in the following table:
-.display
-&'auth '& authentication method
-&'name '& authentication username
-&'pass '& authentication password
-&'port '& tcp port
-&'tmo '& connection timeout
-&'pri '& priority
-&'weight '& selection bias
-.endd
+.itable none 0 0 2 1pt left 1pt left
+.irow &'auth'& "authentication method"
+.irow &'name'& "authentication username"
+.irow &'pass'& "authentication password"
+.irow &'port'& "tcp port"
+.irow &'tmo'& "connection timeout"
+.irow &'pri'& "priority"
+.irow &'weight'& "selection bias"
+.endtable
More details on each of these options follows:
but could be used for any message.
If a value is appended it may be:
-.display
-&`1 `& mandatory downconversion
-&`0 `& no downconversion
-&`-1 `& if SMTPUTF8 not supported by destination host
-.endd
+.itable none 0 0 2 1pt right 1pt left
+.irow &`1`& "mandatory downconversion"
+.irow &`0`& "no downconversion"
+.irow &`-1`& "if SMTPUTF8 not supported by destination host"
+.endtable
If no value is given, 1 is used.
If mua_wrapper is set, the utf8_downconvert control
.new
The current list of events is:
-.display
-&`dane:fail after transport `& per connection
-&`msg:complete after main `& per message
-&`msg:defer after transport `& per message per delivery try
-&`msg:delivery after transport `& per recipient
-&`msg:rcpt:host:defer after transport `& per recipient per host
-&`msg:rcpt:defer after transport `& per recipient
-&`msg:host:defer after transport `& per host per delivery try; host errors
-&`msg:fail:delivery after transport `& per recipient
-&`msg:fail:internal after main `& per recipient
-&`tcp:connect before transport `& per connection
-&`tcp:close after transport `& per connection
-&`tls:cert before both `& per certificate in verification chain
-&`tls:fail:connect after main `& per connection
-&`smtp:connect after transport `& per connection
-&`smtp:ehlo after transport `& per connection
-.endd
+.itable all 0 0 4 1pt left 1pt center 1pt center 1pt left
+.irow dane:fail after transport "per connection"
+.irow msg:complete after main "per message"
+.irow msg:defer after transport "per message per delivery try"
+.irow msg:delivery after transport "per recipient"
+.irow msg:rcpt:host:defer after transport "per recipient per host"
+.irow msg:rcpt:defer after transport "per recipient"
+.irow msg:host:defer after transport "per host per delivery try; host errors"
+.irow msg:fail:delivery after transport "per recipient"
+.irow msg:fail:internal after main "per recipient"
+.irow tcp:connect before transport "per connection"
+.irow tcp:close after transport "per connection"
+.irow tls:cert before both "per certificate in verification chain"
+.irow tls:fail:connect after main "per connection"
+.irow smtp:connect after transport "per connection"
+.irow smtp:ehlo after transport "per connection"
+.endtable
.wen
New event types may be added in future.
An additional variable, &$event_data$&, is filled with information varying
with the event type:
-.display
-&`dane:fail `& failure reason
-&`msg:defer `& error string
-&`msg:delivery `& smtp confirmation message
-&`msg:fail:internal `& failure reason
-&`msg:fail:delivery `& smtp error message
-&`msg:host:defer `& error string
-&`msg:rcpt:host:defer `& error string
-&`msg:rcpt:defer `& error string
-&`tls:cert `& verification chain depth
-&`tls:fail:connect `& error string
-&`smtp:connect `& smtp banner
-&`smtp:ehlo `& smtp ehlo response
-.endd
+.itable all 0 0 2 1pt left 1pt left
+.irow dane:fail "failure reason"
+.irow msg:defer "error string"
+.irow msg:delivery "smtp confirmation message"
+.irow msg:fail:internal "failure reason"
+.irow msg:fail:delivery "smtp error message"
+.irow msg:host:defer "error string"
+.irow msg:rcpt:host:defer "error string"
+.irow msg:rcpt:defer "error string"
+.irow tls:cert "verification chain depth"
+.irow tls:fail:connect "error string"
+.irow smtp:connect "smtp banner"
+.irow smtp:ehlo "smtp ehlo response"
+.endtable
The :defer events populate one extra variable: &$event_defer_errno$&.
-For complex operations an ACL expansion can be used in &%event_action%&
+For complex operations an ACL expansion can be used in &%event_action%&,
however due to the multiple contexts that Exim operates in during
the course of its processing:
.ilist
The expansion of the event_action option should normally
return an empty string. Should it return anything else the
following will be forced:
-.display
-&`tcp:connect `& do not connect
-&`tls:cert `& refuse verification
-&`smtp:connect `& close connection
-.endd
+.itable all 0 0 2 1pt left 1pt left
+.irow tcp:connect "do not connect"
+.irow tls:cert "refuse verification"
+.irow smtp:connect "close connection"
+.endtable
All other message types ignore the result string, and
no other use is made of it.
git://git.exim.org / exim.git / blobdiff