. Update the Copyright year (only) when changing content.
. /////////////////////////////////////////////////////////////////////////////
-.set previousversion "4.95"
+.set previousversion "4.96"
.include ./local_params
.set ACL "access control lists (ACLs)"
. /////////////////////////////////////////////////////////////////////////////
-. This chunk of literal XML implements index entries of the form "x, see y" and
-. "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
+. These implement index entries of the form "x, see y" and "x, see also y".
+. However, the DocBook DTD doesn't allow <indexterm> entries
. at the top level, so we have to put the .chapter directive first.
-
-. These do not turn up in the HTML output, unfortunately. The PDF does get them.
. /////////////////////////////////////////////////////////////////////////////
.chapter "Introduction" "CHID1"
-.literal xml
-<indexterm role="variable">
- <primary>$1, $2, etc.</primary>
- <see><emphasis>numerical variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>address</primary>
- <secondary>rewriting</secondary>
- <see><emphasis>rewriting</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>Bounce Address Tag Validation</primary>
- <see><emphasis>BATV</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>Client SMTP Authorization</primary>
- <see><emphasis>CSA</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>CR character</primary>
- <see><emphasis>carriage return</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>CRL</primary>
- <see><emphasis>certificate revocation list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>delivery</primary>
- <secondary>failure report</secondary>
- <see><emphasis>bounce message</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>dialup</primary>
- <see><emphasis>intermittently connected hosts</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>exiscan</primary>
- <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>failover</primary>
- <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>fallover</primary>
- <see><emphasis>fallback</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>filter</primary>
- <secondary>Sieve</secondary>
- <see><emphasis>Sieve filter</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>ident</primary>
- <see><emphasis>RFC 1413</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>LF character</primary>
- <see><emphasis>linefeed</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>maximum</primary>
- <seealso><emphasis>limit</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
- <primary>monitor</primary>
- <see><emphasis>Exim monitor</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>no_<emphasis>xxx</emphasis></primary>
- <see>entry for xxx</see>
-</indexterm>
-<indexterm role="concept">
- <primary>NUL</primary>
- <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>passwd file</primary>
- <see><emphasis>/etc/passwd</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>process id</primary>
- <see><emphasis>pid</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>RBL</primary>
- <see><emphasis>DNS list</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>redirection</primary>
- <see><emphasis>address redirection</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>return path</primary>
- <seealso><emphasis>envelope sender</emphasis></seealso>
-</indexterm>
-<indexterm role="concept">
- <primary>scanning</primary>
- <see><emphasis>content scanning</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>SSL</primary>
- <see><emphasis>TLS</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>string</primary>
- <secondary>expansion</secondary>
- <see><emphasis>expansion</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>top bit</primary>
- <see><emphasis>8-bit characters</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>variables</primary>
- <see><emphasis>expansion, variables</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>zero, binary</primary>
- <see><emphasis>binary zero</emphasis></see>
-</indexterm>
-<indexterm role="concept">
- <primary>headers</primary>
- <see><emphasis>header lines</emphasis></see>
+.macro seeother
+.literal xml
+<indexterm role="$2">
+ <primary>$3</primary>
+.arg 5
+ <secondary>$5</secondary>
+.endarg
+ <$1><emphasis>$4</emphasis></$1>
</indexterm>
-
.literal off
+.endmacro
+
+. NB: for the 4-arg variant the ordering is awkward
+.macro see
+.seeother see "$1" "$2" "$3" "$4"
+.endmacro
+.macro seealso
+.seeother seealso "$1" "$2" "$3" "$4"
+.endmacro
+
+.see variable "<emphasis>$1</emphasis>, <emphasis>$2</emphasis>, etc." "numerical variables"
+.see concept address rewriting rewriting
+.see concept "Bounce Address Tag Validation" BATV
+.see concept "Client SMTP Authorization" CSA
+.see concept "CR character" "carriage return"
+.see concept CRL "certificate revocation list"
+.seealso concept de-tainting "tainted data"
+.see concept delivery "bounce message" "failure report"
+.see concept dialup "intermittently connected hosts"
+.see concept exiscan "content scanning"
+.see concept fallover fallback
+.see concept filter "Sieve filter" Sieve
+.see concept headers "header lines"
+.see concept ident "RFC 1413"
+.see concept "LF character" "linefeed"
+.seealso concept maximum limit
+.see concept monitor "Exim monitor"
+.see concept "no_<emphasis>xxx</emphasis>" "entry for xxx"
+.see concept NUL "binary zero"
+.see concept "passwd file" "/etc/passwd"
+.see concept "process id" pid
+.see concept RBL "DNS list"
+.see concept redirection "address redirection"
+.see concept "return path" "envelope sender"
+.see concept scanning "content scanning"
+.see concept SSL TLS
+.see concept string expansion expansion
+.see concept "top bit" "8-bit characters"
+.see concept variables "expansion, variables"
+.see concept "zero, binary" "binary zero"
. /////////////////////////////////////////////////////////////////////////////
order in which they are tested. The individual configuration options are
described in more detail in chapter &<<CHAProutergeneric>>&.
-.ilist
+.olist
.cindex affix "router precondition"
The &%local_part_prefix%& and &%local_part_suffix%& options can specify that
the local parts handled by the router may or must have certain prefixes and/or
.cindex "delivery" "in detail"
When a message is to be delivered, the sequence of events is as follows:
-.ilist
+.olist
If a system-wide filter file is specified, the message is passed to it. The
filter may add recipients to the message, replace the recipients, discard the
message, cause a new message to be generated, or cause the message delivery to
-.section "Temporary delivery failure" "SECID20"
+.subsection "Temporary delivery failure" SECID20
.cindex "delivery" "temporary failure"
There are many reasons why a message may not be immediately deliverable to a
particular address. Failure to connect to a remote machine (because it, or the
-.section "Permanent delivery failure" "SECID21"
+.subsection "Permanent delivery failure" SECID21
.cindex "delivery" "permanent failure"
.cindex "bounce message" "when generated"
When a message cannot be delivered to some or all of its intended recipients, a
-.section "Failures to deliver bounce messages" "SECID22"
+.subsection "Failures to deliver bounce messages" SECID22
.cindex "bounce message" "failure to deliver"
If a bounce message (either locally generated or received from a remote host)
itself suffers a permanent delivery failure, the message is left in the queue,
To complicate things further, there are several very different versions of the
Berkeley DB package. Version 1.85 was stable for a very long time, releases
2.&'x'& and 3.&'x'& were current for a while,
-.new
but the latest versions when Exim last revamped support were numbered 5.&'x'&.
Maintenance of some of the earlier releases has ceased,
and Exim no longer supports versions before 3.&'x'&.
-.wen
All versions of Berkeley DB could be obtained from
&url(http://www.sleepycat.com/), which is now a redirect to their new owner's
page with far newer versions listed.
.endd
Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An
error is diagnosed if you set more than one of these.
-.new
You can set USE_NDBM if needed to override an operating system default.
-.wen
At the lowest level, the build-time configuration sets none of these options,
thereby assuming an interface of type (1). However, some operating system
DBMLIB = -ltdb
DBMLIB = -lgdbm -lgdbm_compat
.endd
-.new
The last of those was for a Linux having GDBM provide emulated NDBM facilities.
-.wen
Settings like that will work if the DBM library is installed in the standard
place. Sometimes it is not, and the library's header file may also not be in
the default path. You may need to set INCLUDE to specify where the header
Because macros in the config file are often used for secrets, those are only
available to admin users.
+.new
+The word &"set"& at the start of a line, followed by a single space,
+is recognised specially as defining a value for a variable.
+The syntax is otherwise the same as the ACL modifier &"set ="&.
+.wen
+
.vitem &%-bem%&&~<&'filename'&>
.oindex "&%-bem%&"
.cindex "testing" "string expansion"
debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that
no spaces are allowed in the debug setting. The available debugging categories
are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
.irow acl "ACL interpretation"
.irow auth "authenticators"
.irow deliver "general delivery logic"
domains = lsearch;/some/file
.endd
The first uses a string expansion, the result of which must be a domain list.
-.new
The key for an expansion-style lookup must be given explicitly.
-.wen
No strings have been specified for a successful or a failing lookup; the
defaults in this case are the looked-up data and an empty string, respectively.
The expansion takes place before the string is processed as a list, and the
Any data that follows the keys is not relevant when checking that the domain
matches the list item.
-.new
The key for a list-style lookup is implicit, from the lookup context, if
the lookup is a single-key type (see below).
For query-style lookup types the key must be given explicitly.
-.wen
It is possible, though no doubt confusing, to use both kinds of lookup at once.
Consider a file containing lines like this:
key value is assumed by Exim for query-style lookups. You can use whichever
Exim variables you need to construct the database query.
.cindex "tainted data" "quoting for lookups"
-.new
If tainted data is used in the query then it should be quuted by
using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
appropriate for the lookup.
-.wen
.endlist
The code for each lookup type is in a separate source file that is included in
${lookup dnsdb{>:,; soa=a.b.example.com}}
.endd
-.section "Dnsdb lookup modifiers" "SECTdnsdb_mod"
+.subsection "Dnsdb lookup modifiers" SECTdnsdb_mod
.cindex "dnsdb modifiers"
.cindex "modifiers" "dnsdb"
.cindex "options" "dnsdb"
value of the set of returned DNS records.
-.section "Pseudo dnsdb record types" "SECID66"
+.subsection "Pseudo dnsdb record types" SECID66
.cindex "MX record" "in &(dnsdb)& lookup"
By default, both the preference value and the host name are returned for
each MX record, separated by a space. If you want only host names, you can use
.endd
-.section "Multiple dnsdb lookups" "SECID67"
+.subsection "Multiple dnsdb lookups" SECID67
In the previous sections, &(dnsdb)& lookups for a single domain are described.
However, you can specify a list of domains or IP addresses in a single
&(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as
First we explain how LDAP queries are coded.
-.section "Format of LDAP queries" "SECTforldaque"
+.subsection "Format of LDAP queries" SECTforldaque
.cindex "LDAP" "query format"
An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
the configuration of a &(redirect)& router one might have this setting:
&_exim.conf_&.
-.section "LDAP quoting" "SECID68"
+.subsection "LDAP quoting" SECID68
.cindex "LDAP" "quoting"
Two levels of quoting are required in LDAP queries, the first for LDAP itself
and the second because the LDAP query is represented as a URL. Furthermore,
authentication below.
-.section "LDAP connections" "SECID69"
+.subsection "LDAP connections" SECID69
.cindex "LDAP" "connections"
The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
is in use, via a Unix domain socket. The example given above does not specify
-.section "LDAP authentication and control information" "SECID70"
+.subsection "LDAP authentication and control information" SECID70
.cindex "LDAP" "authentication"
The LDAP URL syntax provides no way of passing authentication and other control
information to the server. To make this possible, the URL in an LDAP query may
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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* 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"
-.section "Format of data returned by LDAP" "SECID71"
+.subsection "Format of data returned by LDAP" SECID71
.cindex "LDAP" "returned data formats"
The &(ldapdn)& lookup type returns the Distinguished Name from a single entry
as a sequence of values, for example
with a newline between the data for each row.
-.section "More about MySQL, PostgreSQL, Oracle, InterBase, and Redis" "SECID72"
+.subsection "More about MySQL, PostgreSQL, Oracle, InterBase, and Redis" SECID72
.cindex "MySQL" "lookup type"
.cindex "PostgreSQL lookup type"
.cindex "lookup" "MySQL"
The &%quote_redis%& expansion operator
escapes whitespace and backslash characters with a backslash.
-.section "Specifying the server in the query" "SECTspeserque"
+.subsection "Specifying the server in the query" SECTspeserque
For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and InterBase),
it is possible to specify a list of servers with an individual query. This is
done by appending a comma-separated option to the query type:
&*Note*&: server specifications in list-style lookups are still problematic.
-.section "Special MySQL features" "SECID73"
+.subsection "Special MySQL features" SECID73
For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%&
causes a connection to the server on the local host by means of a Unix domain
socket. An alternate socket can be specified in parentheses.
is zero because no rows are affected.
-.section "Special PostgreSQL features" "SECID74"
+.subsection "Special PostgreSQL features" SECID74
PostgreSQL lookups can also use Unix domain socket connections to the database.
This is usually faster and costs less CPU time than a TCP/IP connection.
However it can be used only if the mail server runs on the same machine as the
update, or delete command), the result of the lookup is the number of rows
affected.
-.section "More about SQLite" "SECTsqlite"
+.subsection "More about SQLite" SECTsqlite
.cindex "lookup" "SQLite"
.cindex "sqlite lookup type"
SQLite is different to the other SQL lookups because a filename is required in
to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%&
option.
-.section "More about Redis" "SECTredis"
+.subsection "More about Redis" SECTredis
.cindex "lookup" "Redis"
.cindex "redis lookup type"
Redis is a non-SQL database. Commands are simple get and set.
+.section "Results of list checking" SECTlistresults
+The primary result of doing a list check is a truth value.
+In some contexts additional information is stored
+about the list element that matched:
+.vlist
+.vitem hosts
+A &%hosts%& ACL condition
+will store a result in the &$host_data$& variable.
+.vitem local_parts
+A &%local_parts%& router option or &%local_parts%& ACL condition
+will store a result in the &$local_part_data$& variable.
+.vitem domains
+A &%domains%& router option or &%domains%& ACL condition
+will store a result in the &$domain_data$& variable.
+.vitem senders
+A &%senders%& router option or &%senders%& ACL condition
+will store a result in the &$sender_data$& variable.
+.vitem recipients
+A &%recipients%& ACL condition
+will store a result in the &$recipient_data$& variable.
+.endlist
+
+The detail of the additional information depends on the
+type of match and is given below as the &*value*& information.
+
+
+
+
.section "Expansion of lists" "SECTlistexpand"
.cindex "expansion" "of lists"
Each list is expanded as a single string before it is used.
-.section "Negated items in lists" "SECID76"
+.subsection "Negated items in lists" SECID76
.cindex "list" "negation"
.cindex "negation" "in lists"
Items in a list may be positive or negative. Negative items are indicated by a
-.section "File names in lists" "SECTfilnamlis"
+.subsection "File names in lists" SECTfilnamlis
.cindex "list" "filename in"
If an item in a domain, host, address, or local part list is an absolute
filename (beginning with a slash character), each line of the file is read and
-.section "An lsearch file is not an out-of-line list" "SECID77"
+.subsection "An lsearch file is not an out-of-line list" SECID77
As will be described in the sections that follow, lookups can be used in lists
to provide indexed methods of checking list membership. There has been some
confusion about the way &(lsearch)& lookups work in lists. Because
-.section "Results of list checking" SECTlistresults
-The primary result of doing a list check is a truth value.
-In some contexts additional information is stored
-about the list element that matched:
-.vlist
-.vitem hosts
-A &%hosts%& ACL condition
-will store a result in the &$host_data$& variable.
-.vitem local_parts
-A &%local_parts%& router option or &%local_parts%& ACL condition
-will store a result in the &$local_part_data$& variable.
-.vitem domains
-A &%domains%& router option or &%domains%& ACL condition
-will store a result in the &$domain_data$& variable.
-.vitem senders
-A &%senders%& router option or &%senders%& ACL condition
-will store a result in the &$sender_data$& variable.
-.vitem recipients
-A &%recipients%& ACL condition
-will store a result in the &$recipient_data$& variable.
-.endlist
-
-The detail of the additional information depends on the
-type of match and is given below as the &*value*& information.
-
-
-
-
-.section "Named lists" "SECTnamedlists"
+.subsection "Named lists" SECTnamedlists
.cindex "named lists"
.cindex "list" "named"
A list of domains, hosts, email addresses, or local parts can be given a name
-.section "Named lists compared with macros" "SECID78"
+.subsection "Named lists compared with macros" SECID78
.cindex "list" "named compared with macro"
.cindex "macro" "compared with named list"
At first sight, named lists might seem to be no different from macros in the
.endd
-.section "Named list caching" "SECID79"
+.subsection "Named list caching" SECID79
.cindex "list" "caching of named"
.cindex "caching" "named lists"
While processing a message, Exim caches the result of checking a named list if
involved, to ensure that the right value is being used as the key.
-.section "Special host list patterns" "SECID80"
+.subsection "Special host list patterns" SECID80
.cindex "empty item in hosts list"
.cindex "host list" "empty string in"
If a host list item is the empty string, it matches only when no remote host is
-.section "Host list patterns that match by IP address" "SECThoslispatip"
+.subsection "Host list patterns that match by IP address" SECThoslispatip
.cindex "host list" "matching IP addresses"
If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
the incoming address actually appears in the IPv6 host as
-.section "Host list patterns for single-key lookups by host address" &&&
- "SECThoslispatsikey"
+.subsection "Host list patterns for single-key lookups by host address" &&&
+ SECThoslispatsikey
.cindex "host list" "lookup of IP address"
When a host is to be identified by a single-key lookup of its complete IP
address, the pattern takes this form:
-.section "Host list patterns that match by host name" "SECThoslispatnam"
+.subsection "Host list patterns that match by host name" SECThoslispatnam
.cindex "host" "lookup failures"
.cindex "unknown host name"
.cindex "host list" "matching host name"
-.section "Behaviour when an IP address or name cannot be found" "SECTbehipnot"
+.subsection "Behaviour when an IP address or name cannot be found" SECTbehipnot
.cindex "host" "lookup failures, permanent"
While processing a host list, Exim may need to look up an IP address from a
name (see section &<<SECThoslispatip>>&), or it may need to look up a host name
list. The effect of each one lasts until the next, or until the end of the
list.
-.section "Mixing wildcarded host names and addresses in host lists" &&&
- "SECTmixwilhos"
+.subsection "Mixing wildcarded host names and addresses in host lists" &&&
+ SECTmixwilhos
.cindex "host list" "mixing names and addresses in"
This section explains the host/ip processing logic with the same concepts
.endlist
-.section "Temporary DNS errors when looking up host information" &&&
- "SECTtemdnserr"
+.subsection "Temporary DNS errors when looking up host information" &&&
+ SECTtemdnserr
.cindex "host" "lookup failures, temporary"
.cindex "&`+include_defer`&"
.cindex "&`+ignore_defer`&"
-.section "Host list patterns for single-key lookups by host name" &&&
- "SECThoslispatnamsk"
+.subsection "Host list patterns for single-key lookups by host name" &&&
+ SECThoslispatnamsk
.cindex "unknown host name"
.cindex "host list" "matching host name"
If a pattern is of the form
-.section "Host list patterns for query-style lookups" "SECID81"
+.subsection "Host list patterns for query-style lookups" SECID81
If a pattern is of the form
.display
<&'query-style-search-type'&>;<&'query'&>
-.section "Case of letters in address lists" "SECTcasletadd"
+.subsection "Case of letters in address lists" SECTcasletadd
.cindex "case of local parts"
.cindex "address list" "case forcing"
.cindex "case forcing in address lists"
database lookups, and the use of expansion operators such as &%sg%&, &%substr%&
and &%nhash%&.
+.new
+When reading lines from the standard input,
+macros can be defined and ACL variables can be set.
+For example:
+.code
+MY_MACRO = foo
+set acl_m_myvar = bar
+.endd
+Such macros and variables can then be used in later input lines.
+.wen
+
Exim gives up its root privilege when it is called with the &%-be%& option, and
instead runs under the uid and gid it was called with, to prevent users from
using &%-be%& for reading files to which they do not have access.
.cindex "expansion" "running a command"
.cindex "&%run%& expansion item"
This item runs an external command, as a subprocess.
-.new
One option is supported after the word &'run'&, comma-separated.
If the option &'preexpand'& is not used,
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
split apart into individual arguments by spaces, and then the command is run
as above.
around the command arguments. A possible guard against this is to wrap the
variable in the &%sg%& operator to change any quote marks to some other
character.
-.new
Neither the command nor any argument may be tainted.
-.wen
The standard input for the command exists, but is empty. The standard output
and standard error are set to the same file descriptor.
Since this operation is expected to
be mostly used for looking up masked addresses in files, the
-.new
normal
-.wen
result for an IPv6
address uses dots to separate components instead of colons, because colon
terminates a key string in lsearch files. So, for example,
.code
3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
.endd
-.new
If the optional form &*mask_n*& is used, IPv6 address result are instead
returned in normailsed form, using colons and with zero-compression.
-.wen
Letters in IPv6 addresses are always output in lower case.
.cindex "expansion" "numeric comparison"
There are a number of symbolic operators for doing numeric comparisons. They
are:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
.irow "= " "equal"
.irow "== " "equal"
.irow "> " "greater"
${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
.endd
-.new
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"
.endd
can be used for de-tainting.
Any previous &$value$& is restored after the if.
-.wen
.vitem &*isip&~{*&<&'string'&>&*}*& &&&
have their local parts matched casefully. Domains are always matched
caselessly.
-.new
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"
.endd
can be used for de-tainting.
Any previous &$value$& is restored after the if.
-.wen
Note that <&'string2'&> is not itself subject to string expansion, unless
Exim was built with the EXPAND_LISTMATCH_RHS option.
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.
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
(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$&"
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
.tvar &$reply_address$&
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
At this point, all of the "ike" values should be considered obsolete;
they are still in Exim to avoid breaking unusual configurations, but are
candidates for removal the next time we have backwards-incompatible changes.
-.new
Two of them in particular (&`ike1`& and &`ike22`&) are called out by RFC 8247
as MUST NOT use for IPSEC, and two more (&`ike23`& and &`ike24`&) as
SHOULD NOT.
are used, warnings will be logged in the paniclog, and if any are used then
warnings will be logged in the mainlog.
All four will be removed in a future Exim release.
-.wen
The TLS protocol does not negotiate an acceptable size for this; clients tend
to hard-drop connections if what is offered by the server is unacceptable,
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
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
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
See also the &%pipelining_connect_advertise_hosts%& main option.
Note:
-.new
When the facility is used, if the transport &%interface%& option is unset
the &%helo_data%& option
-.wen
will be expanded before the &$sending_ip_address$& variable
is filled in.
A check is made for the use of that variable, without the
.vindex "&$sender_address$&"
At the start of an ACL for MAIL, the sender address may have been rewritten
-by a special SMTP-time rewrite rule (see section &<<SECTrewriteS>>&), but no
+by a special SMTP-time rewrite rule (see section &<<SSECTrewriteS>>&), but no
ordinary rewrite rules have yet been applied. If, however, the sender address
is verified in the ACL, it is rewritten before verification, and remains
rewritten thereafter. The subsequent value of &$sender_address$& is the
-.section "Rewriting flags" "SECID153"
+.subsection "Rewriting flags" "SSECID153"
There are three different kinds of flag that may appear on rewriting rules:
.ilist
-.section "Flags specifying which headers and envelope addresses to rewrite" &&&
- "SECID154"
-.cindex "rewriting" "flags"
+.subsection "Flags specifying which headers and envelope addresses to rewrite" &&&
+ "SSECID154"
+.cindex rewriting flags
If none of the following flag letters, nor the &"S"& flag (see section
-&<<SECTrewriteS>>&) are present, a main rewriting rule applies to all headers
+&<<SSECTrewriteS>>&) are present, a main rewriting rule applies to all headers
and to both the sender and recipient fields of the envelope, whereas a
transport-time rewriting rule just applies to all headers. Otherwise, the
rewriting rule is skipped unless the relevant addresses are being processed.
restrict this to special known cases in your own domains.
-.section "The SMTP-time rewriting flag" "SECTrewriteS"
-.cindex "SMTP" "rewriting malformed addresses"
-.cindex "RCPT" "rewriting argument of"
-.cindex "MAIL" "rewriting argument of"
+.subsection "The SMTP-time rewriting flag" SSECTrewriteS
+.cindex SMTP "rewriting malformed addresses"
+.cindex RCPT "rewriting argument of"
+.cindex MAIL "rewriting argument of"
The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at
SMTP time, as soon as an address is received in a MAIL or RCPT command, and
before any other processing; even before syntax checking. The pattern is
original address in the MAIL or RCPT command.
-.section "Flags controlling the rewriting process" "SECID155"
+.subsection "Flags controlling the rewriting process" SSECID155
There are four flags which control the way the rewriting process works. These
take effect only when a rule is invoked, that is, when the address is of the
correct type (matches the flags) and matches the pattern:
.cindex "ESMTP extensions" AUTH
Very briefly, the way SMTP authentication works is as follows:
-.ilist
+.olist
The server advertises a number of authentication &'mechanisms'& in response to
the client's EHLO command.
.next
Successful authentication sets up information used by the
&%authresults%& expansion item.
-
+.new
+.cindex authentication "failure event"
+If an authenticator is run and does not succeed,
+an event (see &<<CHAPevents>>&) of type "auth:fail" is raised.
+While the event is being processed the variables
+&$sender_host_authenticated$& (with the authenticator name)
+and &$authenticated_fail_id$& (as set by the suthenticator &%server_set_id%& option)
+will be valid.
+See <<CHAPevents>> for details on events.
+.wen
.section "Testing server authentication" "SECID169"
(again depending on the &%tls_cipher%& log selector).
-.section "Requesting and verifying client certificates" "SECID183"
+.subsection "Requesting and verifying client certificates" SECID183
.cindex "certificate" "verification of client"
.cindex "TLS" "client certificate verification"
If you want an Exim server to request a certificate when negotiating a TLS
-.section "Caching of static client configuration items" "SECTclientTLScache"
+.subsection "Caching of static client configuration items" SECTclientTLScache
.cindex certificate caching
.cindex privatekey caching
.cindex crl caching
only point of caution. The &$tls_out_sni$& variable will be set to this string
for the lifetime of the client connection (including during authentication).
-.new
If DANE validated the connection attempt then the value of the &%tls_sni%& option
is forced to the name of the destination host, after any MX- or CNAME-following.
-.wen
Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string
received from a client.
&url(https://www.ssllabs.com/).
-.section "Certificate chains" "SECID186"
+.subsection "Certificate chains" SECID186
A file named by &%tls_certificate%& may contain more than one
certificate. This is useful in the case where the certificate that is being
sent is validated by an intermediate certificate which the other end does
-.section "Self-signed certificates" "SECID187"
+.subsection "Self-signed certificates" SECID187
.cindex "certificate" "self-signed"
You can create a self-signed certificate using the &'req'& command provided
with OpenSSL, like this:
testing as possible at RCPT time.
-.section "The non-SMTP ACLs" "SECID190"
+.subsection "The non-SMTP ACLs" SECID190
.cindex "non-SMTP messages" "ACLs for"
The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they
apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not
temporary error for these kinds of message.
-.section "The SMTP connect ACL" "SECID191"
+.subsection "The SMTP connect ACL" SECID191
.cindex "SMTP" "connection, ACL for"
.oindex &%smtp_banner%&
The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP
the message override the banner message that is otherwise specified by the
&%smtp_banner%& option.
-.new
For tls-on-connect connections, the ACL is run after the TLS connection
is accepted (however, &%host_reject_connection%& is tested before).
-.wen
-.section "The EHLO/HELO ACL" "SECID192"
+.subsection "The EHLO/HELO ACL" SECID192
.cindex "EHLO" "ACL for"
.cindex "HELO" "ACL for"
The ACL test specified by &%acl_smtp_helo%& happens when the client issues an
an EHLO response.
-.section "The DATA ACLs" "SECID193"
+.subsection "The DATA ACLs" SECID193
.cindex "DATA" "ACLs for"
Two ACLs are associated with the DATA command, because it is two-stage
command, with two responses being sent to the client.
the &%acl_smtp_dkim%&
and the &%acl_smtp_mime%& ACLs.
-.section "The SMTP DKIM ACL" "SECTDKIMACL"
+.subsection "The SMTP DKIM ACL" SECTDKIMACL
The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support
enabled (which is the default).
For details on the operation of DKIM, see section &<<SECDKIM>>&.
-.section "The SMTP MIME ACL" "SECID194"
+.subsection "The SMTP MIME ACL" SECID194
The &%acl_smtp_mime%& option is available only when Exim is compiled with the
content-scanning extension. For details, see chapter &<<CHAPexiscan>>&.
This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&.
-.section "The SMTP PRDR ACL" "SECTPRDRACL"
+.subsection "The SMTP PRDR ACL" SECTPRDRACL
.cindex "PRDR" "ACL for"
.oindex "&%prdr_enable%&"
The &%acl_smtp_data_prdr%& ACL is available only when Exim is compiled
If the ACL is not defined, processing completes as if
the feature was not requested by the client.
-.section "The QUIT ACL" "SECTQUITACL"
+.subsection "The QUIT ACL" SECTQUITACL
.cindex "QUIT, ACL for"
The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL
does not affect the response code to QUIT, which is always 221. Thus, the ACL
connection is closed. In these special cases, the QUIT ACL does not run.
-.section "The not-QUIT ACL" "SECTNOTQUITACL"
+.subsection "The not-QUIT ACL" SECTNOTQUITACL
.vindex &$acl_smtp_notquit$&
The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when
an SMTP session ends without sending QUIT. However, when Exim itself is in bad
with &`-d`&, with the output going to a new logfile in the usual logs directory,
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.
Several options are supported:
-.wen
.display
tag=<&'suffix'&> The filename can be adjusted with thise option.
The argument, which may access any variables already defined,
.cindex "domain" "ACL checking"
.cindex "&ACL;" "testing a recipient domain"
.vindex "&$domain_data$&"
-This condition is relevant only after a RCPT command. It checks that the domain
+This condition is relevant only in a RCPT ACL. It checks that the domain
of the recipient address is in the domain list. If percent-hack processing is
enabled, it is done before this test is done. If the check succeeds with a
lookup, the result of the lookup is placed in &$domain_data$& until the next
.cindex "local part" "ACL checking"
.cindex "&ACL;" "testing a local part"
.vindex "&$local_part_data$&"
-This condition is relevant only after a RCPT command. It checks that the local
+This condition is relevant only in a RCPT ACL. It checks that the local
part of the recipient address is in the list. If percent-hack processing is
enabled, it is done before this test. If the check succeeds with a lookup, the
result of the lookup is placed in &$local_part_data$&, which remains set until
.cindex "&%recipients%& ACL condition"
.cindex "recipient" "ACL checking"
.cindex "&ACL;" "testing a recipient"
-This condition is relevant only after a RCPT command. It checks the entire
+This condition is relevant only in a RCPT ACL. It checks the entire
recipient address against a list of recipients.
.vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&>
non-SMTP ACLs. It causes the incoming message to be scanned for a match with
any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&.
-.new
.vitem &*seen&~=&~*&<&'parameters'&>
-.cindex "&%sseen%& ACL condition"
+.cindex "&%seen%& ACL condition"
This condition can be used to test if a situation has been previously met,
for example for greylisting.
Details are given in section &<<SECTseen>>&.
-.wen
.vitem &*sender_domains&~=&~*&<&'domain&~list'&>
.cindex "&%sender_domains%& ACL condition"
(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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 25* left 75* 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"
-.section "Specifying the IP address for a DNS list lookup" "SECID201"
+.subsection "Specifying the IP address for a DNS list lookup" SECID201
.cindex "DNS list" "keyed by explicit IP address"
By default, the IP address that is used in a DNS list lookup is the IP address
of the calling host. However, you can specify another IP address by listing it
-.section "DNS lists keyed on domain names" "SECID202"
+.subsection "DNS lists keyed on domain names" SECID202
.cindex "DNS list" "keyed by domain name"
There are some lists that are keyed on domain names rather than inverted IP
addresses (see, e.g., the &'domain based zones'& link at
-.section "Multiple explicit keys for a DNS list" "SECTmulkeyfor"
+.subsection "Multiple explicit keys for a DNS list" SECTmulkeyfor
.cindex "DNS list" "multiple keys for"
The syntax described above for looking up explicitly-defined values (either
names or IP addresses) in a DNS blacklist is a simplification. After the domain
-.section "Data returned by DNS lists" "SECID203"
+.subsection "Data returned by DNS lists" SECID203
.cindex "DNS list" "data returned from"
DNS lists are constructed using address records in the DNS. The original RBL
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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* left
.irow 127.1.0.1 "RBL"
.irow 127.1.0.2 "DUL"
.irow 127.1.0.3 "DUL and RBL"
returned values outside the 127/8 region.
-.section "Variables set from DNS lists" "SECID204"
+.subsection "Variables set from DNS lists" SECID204
.cindex "expansion" "variables, set from DNS list"
.cindex "DNS list" "variables set from"
.vindex "&$dnslist_domain$&"
-.section "Additional matching conditions for DNS lists" "SECTaddmatcon"
+.subsection "Additional matching conditions for DNS lists" SECTaddmatcon
.cindex "DNS list" "matching specific returned data"
You can add an equals sign and an IP address after a &%dnslists%& domain name
in order to restrict its action to DNS records with a matching right hand side.
-.section "Negated DNS matching conditions" "SECID205"
+.subsection "Negated DNS matching conditions" SECID205
You can supply a negative list of IP addresses as part of a &%dnslists%&
condition. Whereas
.code
-.section "Handling multiple DNS records from a DNS list" "SECThanmuldnsrec"
+.subsection "Handling multiple DNS records from a DNS list" SECThanmuldnsrec
A DNS lookup for a &%dnslists%& condition may return more than one DNS record,
thereby providing more than one IP address. When an item in a &%dnslists%& list
is followed by &`=`& or &`&&`& and a list of IP addresses, in order to restrict
-.section "Detailed information from merged DNS lists" "SECTmordetinf"
+.subsection "Detailed information from merged DNS lists" SECTmordetinf
.cindex "DNS list" "information from merged"
When the facility for restricting the matching IP values in a DNS list is used,
the text from the TXT record that is set in &$dnslist_text$& may not reflect
-.section "DNS lists and IPv6" "SECTmorednslistslast"
+.subsection "DNS lists and IPv6" SECTmorednslistslast
.cindex "IPv6" "DNS black lists"
.cindex "DNS list" "IPv6 usage"
If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it
.endd
-.new
.section "Previously seen user and hosts" "SECTseen"
-.cindex "&%sseen%& ACL condition"
+.cindex "&%een%& ACL condition"
.cindex greylisting
The &%seen%& ACL condition can be used to test whether a
situation has been previously met.
Note that &"seen"& should be added to the list of hints databases
for maintenance if this ACL condition is used.
-.wen
.section "Rate limiting incoming messages" "SECTratelimiting"
the &%count=%& option.
-.section "Ratelimit options for what is being measured" "ratoptmea"
+.subsection "Ratelimit options for what is being measured" ratoptmea
.cindex "rate limiting" "per_* options"
The &%per_conn%& option limits the client's connection rate. It is not
normally used in the &%acl_not_smtp%&, &%acl_not_smtp_mime%&, or
The &%unique=%& option is described in section &<<ratoptuniq>>& below.
-.section "Ratelimit update modes" "ratoptupd"
+.subsection "Ratelimit update modes" ratoptupd
.cindex "rate limiting" "reading data without updating"
You can specify one of three options with the &%ratelimit%& condition to
control when its database is updated. This section describes the &%readonly%&
next section) so you must specify the &%readonly%& option explicitly.
-.section "Ratelimit options for handling fast clients" "ratoptfast"
+.subsection "Ratelimit options for handling fast clients" ratoptfast
.cindex "rate limiting" "strict and leaky modes"
If a client's average rate is greater than the maximum, the rate limiting
engine can react in two possible ways, depending on the presence of the
.endd
-.section "Limiting the rate of different events" "ratoptuniq"
+.subsection "Limiting the rate of different events" ratoptuniq
.cindex "rate limiting" "counting unique events"
The &%ratelimit%& &%unique=%& option controls a mechanism for counting the
rate of different events. For example, the &%per_addr%& option uses this
as intended.
-.section "Using rate limiting" "useratlim"
+.subsection "Using rate limiting" useratlim
Exim's other ACL facilities are used to define what counter-measures are taken
when the rate limit is exceeded. This might be anything from logging a warning
(for example, while measuring existing sending rates in order to define
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"
+.cindex "de-tainting" "using recipient 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
-.section "Additional parameters for callouts" "CALLaddparcall"
+.subsection "Additional parameters for callouts" CALLaddparcall
.cindex "callout" "additional parameters for"
The &%callout%& option can be followed by an equals sign and a number of
optional parameters, separated by commas. For example:
-.section "Callout caching" "SECTcallvercache"
+.subsection "Callout caching" SECTcallvercache
.cindex "hints database" "callout cache"
.cindex "callout" "cache, description of"
.cindex "caching" "callout"
.vitem &*header_line&~*header_last*&
A pointer to the last of the header lines.
-.new
.vitem &*const&~uschar&~*headers_charset*&
The value of the &%headers_charset%& configuration option.
-.wen
.vitem &*BOOL&~host_checking*&
This variable is TRUE during a host checking session that is initiated by the
.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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 15* left 85* left
.irow &`OK`& "match succeeded"
.irow &`FAIL`& "match failed"
.irow &`DEFER`& "match deferred"
-.section "Resent- header lines" "SECID220"
+.section "Header lines"
+.subsection "Resent- header lines" SECID220
.chindex Resent-
RFC 2822 makes provision for sets of header lines starting with the string
&`Resent-`& to be added to a message when it is resent by the original
-.section "The Auto-Submitted: header line" "SECID221"
+.subsection Auto-Submitted: SECID221
Whenever Exim generates an autoreply, a bounce, or a delay warning message, it
includes the header line:
.code
Auto-Submitted: auto-replied
.endd
-.section "The Bcc: header line" "SECID222"
+.subsection Bcc: SECID222
.cindex "&'Bcc:'& header line"
If Exim is called with the &%-t%& option, to take recipient addresses from a
message's header, it removes any &'Bcc:'& header line that may exist (after
existing &'Bcc:'& is not removed.
-.section "The Date: header line" "SECID223"
+.subsection Date: SECID223
.cindex Date:
If a locally-generated or submission-mode message has no &'Date:'& header line,
Exim adds one, using the current date and time, unless the
&%suppress_local_fixups%& control has been specified.
-.section "The Delivery-date: header line" "SECID224"
+.subsection Delivery-date: SECID224
.cindex "&'Delivery-date:'& header line"
.oindex "&%delivery_date_remove%&"
&'Delivery-date:'& header lines are not part of the standard RFC 2822 header
messages.
-.section "The Envelope-to: header line" "SECID225"
+.subsection Envelope-to: SECID225
.chindex Envelope-to:
.oindex "&%envelope_to_remove%&"
&'Envelope-to:'& header lines are not part of the standard RFC 2822 header set.
messages.
-.section "The From: header line" "SECTthefrohea"
+.subsection From: SECTthefrohea
.chindex From:
.cindex "Sendmail compatibility" "&""From""& line"
.cindex "message" "submission"
name as described in section &<<SECTconstr>>&.
-.section "The Message-ID: header line" "SECID226"
+.subsection Message-ID: SECID226
.chindex Message-ID:
.cindex "message" "submission"
.oindex "&%message_id_header_text%&"
&%message_id_header_domain%& options.
-.section "The Received: header line" "SECID227"
+.subsection Received: SECID227
.chindex Received:
A &'Received:'& header line is added at the start of every message. The
contents are defined by the &%received_header_text%& configuration option, and
-H spool file is written) the earliest time at which delivery could start.
-.section "The References: header line" "SECID228"
+.subsection References: SECID228
.chindex References:
Messages created by the &(autoreply)& transport include a &'References:'&
header line. This is constructed according to the rules that are described in
-.section "The Return-path: header line" "SECID229"
+.subsection Return-path: SECID229
.chindex Return-path:
.oindex "&%return_path_remove%&"
&'Return-path:'& header lines are defined as something an MTA may insert when
-.section "The Sender: header line" "SECTthesenhea"
+.subsection Sender: SECTthesenhea
.cindex "&'Sender:'& header line"
.cindex "message" "submission"
.chindex Sender:
-.section "Errors in outgoing SMTP" "SECToutSMTPerr"
+.subsection "Errors in outgoing SMTP" SECToutSMTPerr
.cindex "error" "in outgoing SMTP"
.cindex "SMTP" "errors in outgoing"
.cindex "host" "error"
Exim can be configured to verify addresses in incoming SMTP commands as they
are received. See chapter &<<CHAPACL>>& for details. It can also be configured
to rewrite addresses at this time &-- before any syntax checking is done. See
-section &<<SECTrewriteS>>&.
+section &<<SSECTrewriteS>>&.
Exim can also be configured to limit the rate at which a client host submits
MAIL and RCPT commands in a single SMTP session. See the
-.section "Unrecognized SMTP commands" "SECID234"
+.subsection "Unrecognized SMTP commands" SECID234
.cindex "SMTP" "unrecognized commands"
If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP
commands during a single SMTP connection, it drops the connection after sending
circumstances, a number of non-SMTP lines are sent first.
-.section "Syntax and protocol errors in SMTP commands" "SECID235"
+.subsection "Syntax and protocol errors in SMTP commands" SECID235
.cindex "SMTP" "syntax errors"
.cindex "SMTP" "protocol errors"
A syntax error is detected if an SMTP command is recognized, but there is
-.section "Use of non-mail SMTP commands" "SECID236"
+.subsection "Use of non-mail SMTP commands" SECID236
.cindex "SMTP" "non-mail commands"
The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and
DATA. Exim counts such commands, and drops the connection if there are too
-.section "The VRFY and EXPN commands" "SECID237"
+.subsection "The VRFY and EXPN commands" SECID237
When Exim receives a VRFY or EXPN command on a TCP/IP connection, it
runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as
appropriate) in order to decide whether the command should be accepted or not.
than a verification (the &%-bv%& option). If an unqualified local part is given
as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections
of VRFY and EXPN commands are logged on the main and reject logs, and
-VRFY verification failures are logged on the main log for consistency with
+VRFY verification failures are logged in the main log for consistency with
RCPT failures.
-.section "The ETRN command" "SECTETRN"
+.subsection "The ETRN command" SECTETRN
.cindex "ETRN" "processing"
.cindex "ESMTP extensions" ETRN
RFC 1985 describes an ESMTP command called ETRN that is designed to
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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
.irow &%<=%& "message arrival"
.irow &%(=%& "message fakereject"
.irow &%=>%& "normal message delivery"
.endd
The list of optional log items is in the following table, with the default
selection marked by asterisks:
-.itable none 0 0 3 1pt left 10pt center 1pt left
+.itable none 0 0 3 2.8in left 10pt center 3in left
.irow &`8bitmime`& "received 8BITMIME status"
.irow &`acl_warn_skipped`& * "skipped &%warn%& statement in ACL"
.irow &`address_rewrite`& "address rewriting"
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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 30* left 70* 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"
.endlist
There is one more option, &%-h%&, which outputs a list of options.
-.new
At least one selection option, or either the &*-c*& or &*-h*& option, must be given.
-.wen
.cindex "&'exim_dumpdb'&"
The entire contents of a database are written to the standard output by the
&'exim_dumpdb'& program,
-.new
taking as arguments the spool and database names.
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
exim_dumpdb /var/spool/exim retry
sequence of digit pairs for year, month, day, hour, and minute. Colons can be
used as optional separators.
-.new
Both displayed and input times are in the local timezone by default.
If an option &'-z'& is used on the command line, displayed times
are in UTC.
-.wen
start of the epoch. The second number is a count of the number of messages
warning of delayed delivery that have been sent to the sender.
-.new
There follow a number of lines starting with a hyphen.
These contain variables, can appear in any
order, and are omitted when not relevant.
The following word specifies a variable,
and the remainder of the item depends on the variable.
-.wen
.vlist
.vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
senders).
-.section "Signing outgoing messages" "SECDKIMSIGN"
-.cindex "DKIM" "signing"
+.subsection "Signing outgoing messages" SECDKIMSIGN
+.cindex DKIM signing
For signing to be usable you must have published a DKIM record in DNS.
Note that RFC 8301 (which does not cover EC keys) says:
After expansion, this can be a list.
Each element in turn,
lowercased,
+.vindex "&$dkim_domain$&"
is put into the &%$dkim_domain%& expansion variable
while expanding the remaining signing options.
If it is empty after expansion, DKIM signing is not done,
This sets the key selector string.
After expansion, which can use &$dkim_domain$&, this can be a list.
Each element in turn is put in the expansion
+.vindex "&$dkim_selector$&"
variable &%$dkim_selector%& which may be used in the &%dkim_private_key%&
option along with &%$dkim_domain%&.
If the option is empty after expansion, DKIM signing is not done for this domain,
RFC 6376 lists these tags as RECOMMENDED.
-.section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY"
-.cindex "DKIM" "verification"
+.subsection "Verifying DKIM signatures in incoming mail" SECDKIMVFY
+.cindex DKIM verification
Verification of DKIM signatures in SMTP incoming email is done for all
messages for which an ACL control &%dkim_disable_verify%& has not been set.
-.section "SRS (Sender Rewriting Scheme)" SECTSRS
+.subsection "SRS (Sender Rewriting Scheme)" SECTSRS
.cindex SRS "sender rewriting scheme"
SRS can be used to modify sender addresses when forwarding so that
encoded.
The second argument should be given as the envelope sender address before this
encoding operation.
+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.
.endlist
that headers will be in /usr/local/include, and that the libraries
are in /usr/local/lib.
-. subsection
+.subsection Configuration SSECDMARCCONFIG
+.cindex DMARC configuration
There are three main-configuration options:
.cindex DMARC "configuration options"
the dsn_from option, and <> is used for the
envelope from.
-. I wish we had subsections...
-
+.subsection Controls SSECDMARCCONTROLS
.cindex DMARC controls
+
By default, the DMARC processing will run for any remote,
non-authenticated user. It makes sense to only verify DMARC
status of messages coming from remote, untrusted sources. You can
There are no options to either control. Both must appear before
the DATA acl.
-. subsection
+.subsection ACL SSECDMARCACL
+.cindex DMARC "ACL condition"
DMARC checks cam be run on incoming SMTP messages by using the
&"dmarc_status"& ACL condition in the DATA ACL. You are required to
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:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 20* left 80* 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"
is any error, including no DMARC record.
.endlist
-. subsection
+.subsection Logging SSECDMARCLOGGING
+.cindex DMARC logging
By default, Exim's DMARC configuration is intended to be
non-intrusive and conservative. To facilitate this, Exim will not
enable sending DMARC forensic reports
.endlist
-. subsection
+.subsection Example SSECDMARCEXAMPLE
+.cindex DMARC example
Example usage:
.code
The following expansion variables are usable
(&"internal"& and &"external"& here refer to the interfaces
of the proxy):
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 30* left 70* 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"
Options are a string <name>=<value>.
The list of options is in the following table:
-.itable none 0 0 2 1pt left 1pt left
+.itable none 0 0 2 10* left 90* left
.irow &'auth'& "authentication method"
.irow &'name'& "authentication username"
.irow &'pass'& "authentication password"
but could be used for any message.
If a value is appended it may be:
-.itable none 0 0 2 1pt right 1pt left
+.itable none 0 0 2 5* right 95* left
.irow &`1`& "mandatory downconversion"
.irow &`0`& "no downconversion"
.irow &`-1`& "if SMTPUTF8 not supported by destination host"
The name is placed in the variable &$event_name$& and the event action
expansion must check this, as it will be called for every possible event type.
-.new
The current list of events is:
-.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"
+.itable all 0 0 4 25* left 10* center 15* center 50* left
+.row auth:fail after main "per driver per authentication attempt"
+.row dane:fail after transport "per connection"
+.row msg:complete after main "per message"
+.row msg:defer after transport "per message per delivery try"
+.row msg:delivery after transport "per recipient"
+.row msg:rcpt:host:defer after transport "per recipient per host"
+.row msg:rcpt:defer after transport "per recipient"
+.row msg:host:defer after transport "per host per delivery try; host errors"
+.row msg:fail:delivery after transport "per recipient"
+.row msg:fail:internal after main "per recipient"
+.row tcp:connect before transport "per connection"
+.row tcp:close after transport "per connection"
+.row tls:cert before both "per certificate in verification chain"
+.row tls:fail:connect after main "per connection"
+.row smtp:connect after transport "per connection"
+.row smtp:ehlo after transport "per connection"
.endtable
-.wen
New event types may be added in future.
The event name is a colon-separated list, defining the type of
An additional variable, &$event_data$&, is filled with information varying
with the event type:
-.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"
+.itable all 0 0 2 20* left 80* left
+.row auth:fail "smtp response"
+.row dane:fail "failure reason"
+.row msg:defer "error string"
+.row msg:delivery "smtp confirmation message"
+.row msg:fail:internal "failure reason"
+.row msg:fail:delivery "smtp error message"
+.row msg:host:defer "error string"
+.row msg:rcpt:host:defer "error string"
+.row msg:rcpt:defer "error string"
+.row tls:cert "verification chain depth"
+.row tls:fail:connect "error string"
+.row smtp:connect "smtp banner"
+.row smtp:ehlo "smtp ehlo response"
.endtable
The :defer events populate one extra variable: &$event_defer_errno$&.
The expansion of the event_action option should normally
return an empty string. Should it return anything else the
following will be forced:
-.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"
+.itable all 0 0 2 20* left 80* left
+.row tcp:connect "do not connect"
+.row tls:cert "refuse verification"
+.row 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