. 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"
. /////////////////////////////////////////////////////////////////////////////
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"
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
.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.
${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$&
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
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.
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"
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"
.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"
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
.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
.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'&>"
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,
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
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 smtp:connect after transport "per connection"
.irow 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
git://git.exim.org / exim.git / blobdiff