[exim-cvs] Add Exim 4.95

Página superior

Responder a este mensaje
Autor: Exim Git Commits Mailing List
Fecha:  
A: exim-cvs
Asunto: [exim-cvs] Add Exim 4.95
Gitweb: https://git.exim.org/exim-website.git/commitdiff/c0bf2de3bfbdb15b88d13fc54a129227b9339b81
Commit:     c0bf2de3bfbdb15b88d13fc54a129227b9339b81
Parent:     08a974ef87a0f5e457d7cce49e4a1f486f644c0c
Author:     Heiko Schlittermann (HS12-RIPE) <hs@???>
AuthorDate: Tue Sep 28 11:25:38 2021 +0200
Committer:  Heiko Schlittermann (HS12-RIPE) <hs@???>
CommitDate: Tue Sep 28 11:25:47 2021 +0200


    Add Exim 4.95
---
 docbook/4.95/filter.xml |  2015 ++
 docbook/4.95/spec.xml   | 76968 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 78983 insertions(+)


diff --git a/docbook/4.95/filter.xml b/docbook/4.95/filter.xml
new file mode 100644
index 0000000..8026679
--- /dev/null
+++ b/docbook/4.95/filter.xml
@@ -0,0 +1,2015 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+
+<?sdop
+  foot_right_recto="&chaptertitle;"
+  foot_right_verso="&chaptertitle;"
+  table_warn_overflow="overprint"
+  toc_chapter_blanks="yes,yes"
+  toc_title="Exim's interfaces to mail filtering"
+?>
+<book>
+<bookinfo>
+<title>Exim's interfaces to mail filtering</title>
+<titleabbrev>Exim filtering</titleabbrev>
+<date>
+28 Sep 2021
+</date>
+<author><firstname>Philip</firstname><surname>Hazel</surname></author>
+<authorinitials>PH</authorinitials>
+<revhistory><revision>
+<revnumber>4.95</revnumber>
+<date>28 Sep 2021</date>
+  <authorinitials>PH</authorinitials>
+</revision></revhistory>
+<copyright><year>
+2018
+           </year><holder>The Exim Maintainers</holder></copyright>
+</bookinfo>
+<chapter id="CHAPforandfilt">
+<title>Forwarding and filtering in Exim</title>
+<para>
+This document describes the user interfaces to Exim&#x2019;s in-built mail filtering
+facilities, and is copyright &copy; The Exim Maintainers 2018. It
+corresponds to Exim version 4.95.
+</para>
+<section id="SEC00">
+<title>Introduction</title>
+<para>
+Most Unix mail transfer agents (programs that deliver mail) permit individual
+users to specify automatic forwarding of their mail, usually by placing a list
+of forwarding addresses in a file called <filename>.forward</filename> in their home
+directories. Exim extends this facility by allowing the forwarding instructions
+to be a set of rules rather than just a list of addresses, in effect providing
+<quote><filename>.forward</filename> with conditions</quote>. Operating the set of rules is called
+<emphasis>filtering</emphasis>, and the file that contains them is called a <emphasis>filter file</emphasis>.
+</para>
+<para>
+Exim supports two different kinds of filter file. An <emphasis>Exim filter</emphasis> contains
+instructions in a format that is unique to Exim. A <emphasis>Sieve filter</emphasis> contains
+instructions in the Sieve format that is defined by RFC 3028. As this is a
+standard format, Sieve filter files may already be familiar to some users.
+Sieve files should also be portable between different environments. However,
+the Exim filtering facility contains more features (such as variable
+expansion), and better integration with the host environment (such as the use
+of external processes and pipes).
+</para>
+<para>
+The choice of which kind of filter to use can be left to the end-user, provided
+that the system administrator has configured Exim appropriately for both kinds
+of filter. However, if interoperability is important, Sieve is the only
+choice.
+</para>
+<para>
+The ability to use filtering or traditional forwarding has to be enabled by the
+system administrator, and some of the individual facilities can be separately
+enabled or disabled. A local document should be provided to describe exactly
+what has been enabled. In the absence of this, consult your system
+administrator.
+</para>
+<para>
+This document describes how to use a filter file and the format of its
+contents. It is intended for use by end-users. Both Sieve filters and Exim
+filters are covered. However, for Sieve filters, only issues that relate to the
+Exim implementation are discussed, since Sieve itself is described elsewhere.
+</para>
+<para>
+The contents of traditional <filename>.forward</filename> files are not described here. They
+normally contain just a list of addresses, file names, or pipe commands,
+separated by commas or newlines, but other types of item are also available.
+The full details can be found in the chapter on the <command>redirect</command> router in the
+Exim specification, which also describes how the system administrator can set
+up and control the use of filtering.
+</para>
+</section>
+<section id="SEC01">
+<title>Filter operation</title>
+<para>
+It is important to realize that, in Exim, no deliveries are actually made while
+a filter or traditional <filename>.forward</filename> file is being processed. Running a filter
+or processing a traditional <filename>.forward</filename> file sets up future delivery
+operations, but does not carry them out.
+</para>
+<para>
+The result of filter or <filename>.forward</filename> file processing is a list of destinations
+to which a message should be delivered. The deliveries themselves take place
+later, along with all other deliveries for the message. This means that it is
+not possible to test for successful deliveries while filtering. It also means
+that any duplicate addresses that are generated are dropped, because Exim never
+delivers the same message to the same address more than once.
+</para>
+</section>
+<section id="SECTtesting">
+<title>Testing a new filter file</title>
+<para>
+Filter files, especially the more complicated ones, should always be tested, as
+it is easy to make mistakes. Exim provides a facility for preliminary testing
+of a filter file before installing it. This tests the syntax of the file and
+its basic operation, and can also be used with traditional <filename>.forward</filename> files.
+</para>
+<para>
+Because a filter can do tests on the content of messages, a test message is
+required. Suppose you have a new filter file called <filename>myfilter</filename> and a test
+message in a file called <filename>test-message</filename>. Assuming that Exim is installed with
+the conventional path name <filename>/usr/sbin/sendmail</filename> (some operating systems use
+<filename>/usr/lib/sendmail</filename>), the following command can be used:
+</para>
+<literallayout class="monospaced">
+/usr/sbin/sendmail -bf myfilter &lt;test-message
+</literallayout>
+<para>
+The <option>-bf</option> option tells Exim that the following item on the command line is
+the name of a filter file that is to be tested. There is also a <option>-bF</option> option,
+which is similar, but which is used for testing system filter files, as opposed
+to user filter files, and which is therefore of use only to the system
+administrator.
+</para>
+<para>
+The test message is supplied on the standard input. If there are no
+message-dependent tests in the filter, an empty file (<filename>/dev/null</filename>) can be
+used. A supplied message must start with header lines or the <quote>From&nbsp;</quote> message
+separator line that is found in many multi-message folder files. Note that
+blank lines at the start terminate the header lines. A warning is given if no
+header lines are read.
+</para>
+<para>
+The result of running this command, provided no errors are detected in the
+filter file, is a list of the actions that Exim would try to take if presented
+with the message for real. For example, for an Exim filter, the output
+</para>
+<literallayout class="monospaced">
+Deliver message to: gulliver@???
+Save message to: /home/lemuel/mail/archive
+</literallayout>
+<para>
+means that one copy of the message would be sent to
+<emphasis>gulliver@???</emphasis>, and another would be added to the file
+<filename>/home/lemuel/mail/archive</filename>, if all went well.
+</para>
+<para>
+The actions themselves are not attempted while testing a filter file in this
+way; there is no check, for example, that any forwarding addresses are valid.
+For an Exim filter, if you want to know why a particular action is being taken,
+add the <option>-v</option> option to the command. This causes Exim to output the results of
+any conditional tests and to indent its output according to the depth of
+nesting of <command>if</command> commands. Further additional output from a filter test can be
+generated by the <command>testprint</command> command, which is described below.
+</para>
+<para>
+When Exim is outputting a list of the actions it would take, if any text
+strings are included in the output, non-printing characters therein are
+converted to escape sequences. In particular, if any text string contains a
+newline character, this is shown as <quote>\n</quote> in the testing output.
+</para>
+<para>
+When testing a filter in this way, Exim makes up an <quote>envelope</quote> for the
+message. The recipient is by default the user running the command, and so is
+the sender, but the command can be run with the <option>-f</option> option to supply a
+different sender. For example,
+</para>
+<literallayout class="monospaced">
+/usr/sbin/sendmail -bf myfilter \
+   -f islington@??? &lt;test-message
+</literallayout>
+<para>
+Alternatively, if the <option>-f</option> option is not used, but the first line of the
+supplied message is a <quote>From&nbsp;</quote> separator from a message folder file (not the
+same thing as a <emphasis>From:</emphasis> header line), the sender is taken from there. If
+<option>-f</option> is present, the contents of any <quote>From&nbsp;</quote> line are ignored.
+</para>
+<para>
+The <quote>return path</quote> is the same as the envelope sender, unless the message
+contains a <emphasis>Return-path:</emphasis> header, in which case it is taken from there. You
+need not worry about any of this unless you want to test out features of a
+filter file that rely on the sender address or the return path.
+</para>
+<para>
+It is possible to change the envelope recipient by specifying further options.
+The <option>-bfd</option> option changes the domain of the recipient address, while the
+<option>-bfl</option> option changes the <quote>local part</quote>, that is, the part before the @
+sign. An adviser could make use of these to test someone else&#x2019;s filter file.
+</para>
+<para>
+The <option>-bfp</option> and <option>-bfs</option> options specify the prefix or suffix for the local
+part. These are relevant only when support for multiple personal mailboxes is
+implemented; see the description in section <xref linkend="SECTmbox"/> below.
+</para>
+</section>
+<section id="SEC02">
+<title>Installing a filter file</title>
+<para>
+A filter file is normally installed under the name <filename>.forward</filename> in your home
+directory &ndash; it is distinguished from a conventional <filename>.forward</filename> file by its
+first line (described below). However, the file name is configurable, and some
+system administrators may choose to use some different name or location for
+filter files.
+</para>
+</section>
+<section id="SEC03">
+<title>Testing an installed filter file</title>
+<para>
+Testing a filter file before installation cannot find every potential problem;
+for example, it does not actually run commands to which messages are piped.
+Some <quote>live</quote> tests should therefore also be done once a filter is installed.
+</para>
+<para>
+If at all possible, test your filter file by sending messages from some other
+account. If you send a message to yourself from the filtered account, and
+delivery fails, the error message will be sent back to the same account, which
+may cause another delivery failure. It won&#x2019;t cause an infinite sequence of such
+messages, because delivery failure messages do not themselves generate further
+messages. However, it does mean that the failure won&#x2019;t be returned to you, and
+also that the postmaster will have to investigate the stuck message.
+</para>
+<para>
+If you have to test an Exim filter from the same account, a sensible precaution
+is to include the line
+</para>
+<literallayout class="monospaced">
+if error_message then finish endif
+</literallayout>
+<para>
+as the first filter command, at least while testing. This causes filtering to
+be abandoned for a delivery failure message, and since no destinations are
+generated, the message goes on to be delivered to the original address. Unless
+there is a good reason for not doing so, it is recommended that the above test
+be left in all Exim filter files. (This does not apply to Sieve files.)
+</para>
+</section>
+<section id="SEC04">
+<title>Details of filtering commands</title>
+<para>
+The filtering commands for Sieve and Exim filters are completely different in
+syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
+chapter we describe how it is integrated into Exim. The subsequent chapter
+covers Exim filtering commands in detail.
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPsievefilter">
+<title>Sieve filter files</title>
+<para>
+The code for Sieve filtering in Exim was contributed by Michael Haardt, and
+most of the content of this chapter is taken from the notes he provided. Since
+Sieve is an extensible language, it is important to understand <quote>Sieve</quote> in
+this context as <quote>the specific implementation of Sieve for Exim</quote>.
+</para>
+<para>
+This chapter does not contain a description of Sieve, since that can be found
+in RFC 3028, which should be read in conjunction with these notes.
+</para>
+<para>
+The Exim Sieve implementation offers the core as defined by RFC 3028,
+comparison tests, the subaddress parameter, the <emphasis role="bold">copy</emphasis>, <emphasis role="bold">envelope</emphasis>,
+<emphasis role="bold">fileinto</emphasis>, <emphasis role="bold">notify</emphasis>, and <emphasis role="bold">vacation</emphasis> extensions, but not the <emphasis role="bold">reject</emphasis>
+extension. Exim does not support message delivery notifications (MDNs), so
+adding it just to the Sieve filter (as required for <emphasis role="bold">reject</emphasis>) makes little
+sense.
+</para>
+<para>
+In order for Sieve to work properly in Exim, the system administrator needs to
+make some adjustments to the Exim configuration. These are described in the
+chapter on the <command>redirect</command> router in the full Exim specification.
+</para>
+<section id="SEC05">
+<title>Recognition of Sieve filters</title>
+<para>
+A filter file is interpreted as a Sieve filter if its first line is
+</para>
+<literallayout class="monospaced">
+# Sieve filter
+</literallayout>
+<para>
+This is what distinguishes it from a conventional <filename>.forward</filename> file or an Exim
+filter file.
+</para>
+</section>
+<section id="SEC06">
+<title>Saving to specified folders</title>
+<para>
+If the system administrator has set things up as suggested in the Exim
+specification, and you use <command>keep</command> or <command>fileinto</command> to save a mail into a
+folder, absolute files are stored where specified, relative files are stored
+relative to <varname>$home</varname>, and <filename>inbox</filename> goes to the standard mailbox location.
+</para>
+</section>
+<section id="SEC07">
+<title>Strings containing header names</title>
+<para>
+RFC 3028 does not specify what happens if a string denoting a header field does
+not contain a valid header name, for example, it contains a colon. This
+implementation generates an error instead of ignoring the header field in order
+to ease script debugging, which fits in with the common picture of Sieve.
+</para>
+</section>
+<section id="SEC08">
+<title>Exists test with empty list of headers</title>
+<para>
+The <emphasis role="bold">exists</emphasis> test succeeds only if all the specified headers exist. RFC 3028
+does not explicitly specify what happens on an empty list of headers. This
+implementation evaluates that condition as true, interpreting the RFC in a
+strict sense.
+</para>
+</section>
+<section id="SEC09">
+<title>Header test with invalid MIME encoding in header</title>
+<para>
+Some MUAs process invalid base64 encoded data, generating junk. Others ignore
+junk after seeing an equal sign in base64 encoded data. RFC 2047 does not
+specify how to react in this case, other than stating that a client must not
+forbid to process a message for that reason. RFC 2045 specifies that invalid
+data should be ignored (apparently looking at end of line characters). It also
+specifies that invalid data may lead to rejecting messages containing them (and
+there it appears to talk about true encoding violations), which is a clear
+contradiction to ignoring them.
+</para>
+<para>
+RFC 3028 does not specify how to process incorrect MIME words. This
+implementation treats them literally, as it does if the word is correct but its
+character set cannot be converted to UTF-8.
+</para>
+</section>
+<section id="SEC10">
+<title>Address test for multiple addresses per header</title>
+<para>
+A header may contain multiple addresses. RFC 3028 does not explicitly specify
+how to deal with them, but since the address test checks if anything matches
+anything else, matching one address suffices to satisfy the condition. That
+makes it impossible to test if a header contains a certain set of addresses and
+no more, but it is more logical than letting the test fail if the header
+contains an additional address besides the one the test checks for.
+</para>
+</section>
+<section id="SEC11">
+<title>Semantics of keep</title>
+<para>
+The <command>keep</command> command is equivalent to
+</para>
+<literallayout class="monospaced">
+fileinto "inbox";
+</literallayout>
+<para>
+It saves the message and resets the implicit keep flag. It does not set the
+implicit keep flag; there is no command to set it once it has been reset.
+</para>
+</section>
+<section id="SEC12">
+<title>Semantics of fileinto</title>
+<para>
+RFC 3028 does not specify whether <command>fileinto</command> should try to create a mail
+folder if it does not exist. This implementation allows the sysadmin to
+configure that aspect using the <command>appendfile</command> transport options
+<option>create_directory</option>, <option>create_file</option>, and <option>file_must_exist</option>. See the
+<command>appendfile</command> transport in the Exim specification for details.
+</para>
+</section>
+<section id="SEC13">
+<title>Semantics of redirect</title>
+<para>
+Sieve scripts are supposed to be interoperable between servers, so this
+implementation does not allow mail to be redirected to unqualified addresses,
+because the domain would depend on the system being used. On systems with
+virtual mail domains, the default domain is probably not what the user expects
+it to be.
+</para>
+</section>
+<section id="SEC14">
+<title>String arguments</title>
+<para>
+There has been confusion if the string arguments to <command>require</command> are to be
+matched case-sensitively or not. This implementation matches them with the
+match type <command>:is</command> (default, see section 2.7.1 of the RFC) and the comparator
+<command>i;ascii-casemap</command> (default, see section 2.7.3 of the RFC). The RFC defines
+the command defaults clearly, so any different implementations violate RFC
+3028. The same is valid for comparator names, also specified as strings.
+</para>
+</section>
+<section id="SEC15">
+<title>Number units</title>
+<para>
+There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte.
+The mistake is obvious, because RFC 3028 specifies G to denote 2^30
+(which is gibi, not tebi), and that is what this implementation uses as
+the scaling factor for the suffix G.
+</para>
+</section>
+<section id="SEC16">
+<title>RFC compliance</title>
+<para>
+Exim requires the first line of a Sieve filter to be
+</para>
+<literallayout class="monospaced">
+# Sieve filter
+</literallayout>
+<para>
+Of course the RFC does not specify that line. Do not expect examples to work
+without adding it, though.
+</para>
+<para>
+RFC 3028 requires the use of CRLF to terminate a line. The rationale was that
+CRLF is universally used in network protocols to mark the end of the line. This
+implementation does not embed Sieve in a network protocol, but uses Sieve
+scripts as part of the Exim MTA. Since all parts of Exim use LF as the newline
+character, this implementation does, too, by default, though the system
+administrator may choose (at Exim compile time) to use CRLF instead.
+</para>
+<para>
+Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so this
+implementation repeats this violation to stay consistent with Exim. This is in
+preparation for UTF-8 data.
+</para>
+<para>
+Sieve scripts cannot contain NUL characters in strings, but mail headers could
+contain MIME encoded NUL characters, which could never be matched by Sieve
+scripts using exact comparisons. For that reason, this implementation extends
+the Sieve quoted string syntax with \0 to describe a NUL character, violating
+\0 being the same as 0 in RFC 3028. Even without using \0, the following tests
+are all true in this implementation. Implementations that use C-style strings
+will only evaluate the first test as true.
+</para>
+<literallayout class="monospaced">
+Subject: =?iso-8859-1?q?abc=00def
+
+header :contains "Subject" ["abc"]
+header :contains "Subject" ["def"]
+header :matches "Subject" ["abc?def"]
+</literallayout>
+<para>
+Note that by considering Sieve to be an MUA, RFC 2047 can be interpreted in a
+way that NUL characters truncating strings is allowed for Sieve
+implementations, although not recommended. It is further allowed to use encoded
+NUL characters in headers, but that&#x2019;s not recommended either. The above example
+shows why.
+</para>
+<para>
+RFC 3028 states that if an implementation fails to convert a character set to
+UTF-8, two strings cannot be equal if one contains octets greater than 127.
+Assuming that all unknown character sets are one-byte character sets with the
+lower 128 octets being US-ASCII is not sound, so this implementation violates
+RFC 3028 and treats such MIME words literally. That way at least something
+could be matched.
+</para>
+<para>
+The folder specified by <command>fileinto</command> must not contain the character sequence
+<quote>..</quote> to avoid security problems. RFC 3028 does not specify the syntax of
+folders apart from <command>keep</command> being equivalent to
+</para>
+<literallayout class="monospaced">
+fileinto "INBOX";
+</literallayout>
+<para>
+This implementation uses <filename>inbox</filename> instead.
+</para>
+<para>
+Sieve script errors currently cause messages to be silently filed into
+<filename>inbox</filename>.  RFC 3028 requires that the user is notified of that condition.
+This may be implemented in the future by adding a header line to mails that
+are filed into <filename>inbox</filename> due to an error in the filter.
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPeximfilter">
+<title>Exim filter files</title>
+<para>
+This chapter contains a full description of the contents of Exim filter files.
+</para>
+<section id="SEC17">
+<title>Format of Exim filter files</title>
+<para>
+Apart from leading white space, the first text in an Exim filter file must be
+</para>
+<literallayout class="monospaced">
+# Exim filter
+</literallayout>
+<para>
+This is what distinguishes it from a conventional <filename>.forward</filename> file or a Sieve
+filter file. If the file does not have this initial line (or the equivalent for
+a Sieve filter), it is treated as a conventional <filename>.forward</filename> file, both when
+delivering mail and when using the <option>-bf</option> testing mechanism. The white space
+in the line is optional, and any capitalization may be used. Further text on
+the same line is treated as a comment. For example, you could have
+</para>
+<literallayout class="monospaced">
+#   Exim filter   &lt;&lt;== do not edit or remove this line!
+</literallayout>
+<para>
+The remainder of the file is a sequence of filtering commands, which consist of
+keywords and data values. For example, in the command
+</para>
+<literallayout class="monospaced">
+deliver gulliver@???
+</literallayout>
+<para>
+the keyword is <literal>deliver</literal> and the data value is
+<literal>gulliver@???</literal>. White space or line breaks separate the
+components of a command, except in the case of conditions for the <command>if</command>
+command, where round brackets (parentheses) also act as separators. Complete
+commands are separated from each other by white space or line breaks; there are
+no special terminators. Thus, several commands may appear on one line, or one
+command may be spread over a number of lines.
+</para>
+<para>
+If the character # follows a separator anywhere in a command, everything from
+# up to the next newline is ignored. This provides a way of including comments
+in a filter file.
+</para>
+</section>
+<section id="SEC18">
+<title>Data values in filter commands</title>
+<para>
+There are two ways in which a data value can be input:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the text contains no white space, it can be typed verbatim. However, if it
+is part of a condition, it must also be free of round brackets (parentheses),
+as these are used for grouping in conditions.
+</para>
+</listitem>
+<listitem>
+<para>
+Otherwise, text must be enclosed in double quotation marks. In this case, the
+character \ (backslash) is treated as an <quote>escape character</quote> within the
+string, causing the following character or characters to be treated specially:
+</para>
+<literallayout>
+<literal>\n</literal>   is replaced by a newline
+<literal>\r</literal>   is replaced by a carriage return
+<literal>\t</literal>   is replaced by a tab
+</literallayout>
+</listitem>
+</itemizedlist>
+<para>
+Backslash followed by up to three octal digits is replaced by the character
+specified by those digits, and <literal>\x</literal> followed by up to two hexadecimal digits
+is treated similarly. Backslash followed by any other character is replaced by
+the second character, so that in particular, <literal>\"</literal> becomes <literal>"</literal> and <literal>\\</literal>
+becomes <literal>\</literal>. A data item enclosed in double quotes can be continued onto the
+next line by ending the first line with a backslash. Any leading white space at
+the start of the continuation line is ignored.
+</para>
+<para>
+In addition to the escape character processing that occurs when strings are
+enclosed in quotes, most data values are also subject to <emphasis>string expansion</emphasis>
+(as described in the next section), in which case the characters <literal>$</literal> and
+<literal>\</literal> are also significant. This means that if a single backslash is actually
+required in such a string, and the string is also quoted, <literal>\\\\</literal> has to be
+entered.
+</para>
+<para>
+The maximum permitted length of a data string, before expansion, is 1024
+characters.
+</para>
+</section>
+<section id="SECTfilterstringexpansion">
+<title>String expansion</title>
+<para>
+Most data values are expanded before use. Expansion consists of replacing
+substrings beginning with <literal>$</literal> with other text. The full expansion facilities
+available in Exim are extensive. If you want to know everything that Exim can
+do with strings, you should consult the chapter on string expansion in the Exim
+documentation.
+</para>
+<para>
+In filter files, by far the most common use of string expansion is the
+substitution of the contents of a variable. For example, the substring
+</para>
+<literallayout class="monospaced">
+$reply_address
+</literallayout>
+<para>
+is replaced by the address to which replies to the message should be sent. If
+such a variable name is followed by a letter or digit or underscore, it must be
+enclosed in curly brackets (braces), for example,
+</para>
+<literallayout class="monospaced">
+${reply_address}
+</literallayout>
+<para>
+If a <literal>$</literal> character is actually required in an expanded string, it must be
+escaped with a backslash, and because backslash is also an escape character in
+quoted input strings, it must be doubled in that case. The following two
+examples illustrate two different ways of testing for a <literal>$</literal> character in a
+message:
+</para>
+<literallayout class="monospaced">
+if $message_body contains \$ then ...
+if $message_body contains "\\$" then ...
+</literallayout>
+<para>
+You can prevent part of a string from being expanded by enclosing it between
+two occurrences of <literal>\N</literal>. For example,
+</para>
+<literallayout class="monospaced">
+if $message_body contains \N$$$$\N then ...
+</literallayout>
+<para>
+tests for a run of four dollar characters.
+</para>
+</section>
+<section id="SEC19">
+<title>Some useful general variables</title>
+<para>
+A complete list of the available variables is given in the Exim documentation.
+This shortened list contains the ones that are most likely to be useful in
+personal filter files:
+</para>
+<para>
+<varname>$body_linecount</varname>: The number of lines in the body of the message.
+</para>
+<para>
+<varname>$body_zerocount</varname>: The number of binary zero characters in the body of the
+message.
+</para>
+<para>
+<varname>$home</varname>: In conventional configurations, this variable normally contains the
+user&#x2019;s home directory. The system administrator can, however, change this.
+</para>
+<para>
+<varname>$local_part</varname>: The part of the email address that precedes the @ sign &ndash;
+normally the user&#x2019;s login name. If support for multiple personal mailboxes is
+enabled (see section <xref linkend="SECTmbox"/> below) and a prefix or suffix for the local
+part was recognized, it is removed from the string in this variable.
+</para>
+<para>
+<varname>$local_part_prefix</varname>: If support for multiple personal mailboxes is enabled
+(see section <xref linkend="SECTmbox"/> below), and a local part prefix was recognized,
+this variable contains the prefix. Otherwise it contains an empty string.
+</para>
+<para>
+<varname>$local_part_suffix</varname>: If support for multiple personal mailboxes is enabled
+(see section <xref linkend="SECTmbox"/> below), and a local part suffix was recognized,
+this variable contains the suffix. Otherwise it contains an empty string.
+</para>
+<para>
+<varname>$message_body</varname>: The initial portion of the body of the message. By default,
+up to 500 characters are read into this variable, but the system administrator
+can configure this to some other value. Newlines in the body are converted into
+single spaces.
+</para>
+<para>
+<varname>$message_body_end</varname>: The final portion of the body of the message, formatted
+and limited in the same way as <varname>$message_body</varname>.
+</para>
+<para>
+<varname>$message_body_size</varname>: The size of the body of the message, in bytes.
+</para>
+<para>
+<varname>$message_exim_id</varname>: The message&#x2019;s local identification string, which is unique
+for each message handled by a single host.
+</para>
+<para>
+<varname>$message_headers</varname>: The header lines of the message, concatenated into a
+single string, with newline characters between them.
+</para>
+<para>
+<varname>$message_size</varname>: The size of the entire message, in bytes.
+</para>
+<para>
+<varname>$original_local_part</varname>: When an address that arrived with the message is
+being processed, this contains the same value as the variable <varname>$local_part</varname>.
+However, if an address generated by an alias, forward, or filter file is being
+processed, this variable contains the local part of the original address.
+</para>
+<para>
+<varname>$reply_address</varname>: The contents of the <emphasis>Reply-to:</emphasis> header, if the message
+has one; otherwise the contents of the <emphasis>From:</emphasis> header. It is the address to
+which normal replies to the message should be sent.
+</para>
+<para>
+<varname>$return_path</varname>: The return path &ndash; that is, the sender field that will be
+transmitted as part of the message&#x2019;s envelope if the message is sent to another
+host. This is the address to which delivery errors are sent. In many cases,
+this variable has the same value as <varname>$sender_address</varname>, but if, for example,
+an incoming message to a mailing list has been expanded, <varname>$return_path</varname> may
+have been changed to contain the address of the list maintainer.
+</para>
+<para>
+<varname>$sender_address</varname>: The sender address that was received in the envelope of
+the message. This is not necessarily the same as the contents of the <emphasis>From:</emphasis>
+or <emphasis>Sender:</emphasis> header lines. For delivery error messages (<quote>bounce messages</quote>)
+there is no sender address, and this variable is empty.
+</para>
+<para>
+<varname>$tod_full</varname>: A full version of the time and date, for example: Wed, 18 Oct
+1995 09:51:40 +0100. The timezone is always given as a numerical offset from
+GMT.
+</para>
+<para>
+<varname>$tod_log</varname>: The time and date in the format used for writing Exim&#x2019;s log files,
+without the timezone, for example: 1995-10-12 15:32:29.
+</para>
+<para>
+<varname>$tod_zone</varname>: The local timezone offset, for example: +0100.
+</para>
+</section>
+<section id="SECTheadervariables">
+<title>Header variables</title>
+<para>
+There is a special set of expansion variables containing the header lines of
+the message being processed. These variables have names beginning with
+<varname>$header_</varname> followed by the name of the header line, terminated by a colon.
+For example,
+</para>
+<literallayout class="monospaced">
+$header_from:
+$header_subject:
+</literallayout>
+<para>
+The whole item, including the terminating colon, is replaced by the contents of
+the message header line. If there is more than one header line with the same
+name, their contents are concatenated. For header lines whose data consists of
+a list of addresses (for example, <emphasis>From:</emphasis> and <emphasis>To:</emphasis>), a comma and newline
+is inserted between each set of data. For all other header lines, just a
+newline is used.
+</para>
+<para>
+Leading and trailing white space is removed from header line data, and if there
+are any MIME <quote>words</quote> that are encoded as defined by RFC 2047 (because they
+contain non-ASCII characters), they are decoded and translated, if possible, to
+a local character set. Translation is attempted only on operating systems that
+have the <function>iconv()</function> function. This makes the header line look the same as it
+would when displayed by an MUA. The default character set is ISO-8859-1, but
+this can be changed by means of the <command>headers</command> command (see below).
+</para>
+<para>
+If you want to see the actual characters that make up a header line, you can
+specify <varname>$rheader_</varname> instead of <varname>$header_</varname>. This inserts the <quote>raw</quote>
+header line, unmodified.
+</para>
+<para>
+There is also an intermediate form, requested by <varname>$bheader_</varname>, which removes
+leading and trailing space and decodes MIME <quote>words</quote>, but does not do any
+character translation. If an attempt to decode what looks superficially like a
+MIME <quote>word</quote> fails, the raw string is returned. If decoding produces a binary
+zero character, it is replaced by a question mark.
+</para>
+<para>
+The capitalization of the name following <varname>$header_</varname> is not significant.
+Because any printing character except colon may appear in the name of a
+message&#x2019;s header (this is a requirement of RFC 2822, the document that
+describes the format of a mail message) curly brackets must <emphasis>not</emphasis> be used in
+this case, as they will be taken as part of the header name. Two shortcuts are
+allowed in naming header variables:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The initiating <varname>$header_</varname>, <varname>$rheader_</varname>, or <varname>$bheader_</varname> can be
+abbreviated to <varname>$h_</varname>, <varname>$rh_</varname>, or <varname>$bh_</varname>, respectively.
+</para>
+</listitem>
+<listitem>
+<para>
+The terminating colon can be omitted if the next character is white space. The
+white space character is retained in the expanded string. However, this is not
+recommended, because it makes it easy to forget the colon when it really is
+needed.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+If the message does not contain a header of the given name, an empty string is
+substituted. Thus it is important to spell the names of headers correctly. Do
+not use <varname>$header_Reply_to</varname> when you really mean <varname>$header_Reply-to</varname>.
+</para>
+</section>
+<section id="SEC20">
+<title>User variables</title>
+<para>
+There are ten user variables with names <varname>$n0</varname> &ndash; <varname>$n9</varname> that can be
+incremented by the <command>add</command> command (see section <xref linkend="SECTadd"/>). These can be
+used for <quote>scoring</quote> messages in various ways. If Exim is configured to run a
+<quote>system filter</quote> on every message, the values left in these variables are
+copied into the variables <varname>$sn0</varname> &ndash; <varname>$sn9</varname> at the end of the system filter,
+thus making them available to users&#x2019; filter files. How these values are used is
+entirely up to the individual installation.
+</para>
+</section>
+<section id="SEC21">
+<title>Current directory</title>
+<para>
+The contents of your filter file should not make any assumptions about the
+current directory. It is best to use absolute paths for file names; you can
+normally make use of the <varname>$home</varname> variable to refer to your home directory. The
+<command>save</command> command automatically inserts <varname>$home</varname> at the start of non-absolute
+paths.
+</para>
+</section>
+<section id="SECTsigdel">
+<title>Significant deliveries</title>
+<para>
+When in the course of delivery a message is processed by a filter file, what
+happens next, that is, after the filter file has been processed, depends on
+whether or not the filter sets up any <emphasis>significant deliveries</emphasis>. If at least
+one significant delivery is set up, the filter is considered to have handled
+the entire delivery arrangements for the current address, and no further
+processing of the address takes place. If, however, no significant deliveries
+are set up, Exim continues processing the current address as if there were no
+filter file, and typically sets up a delivery of a copy of the message into a
+local mailbox. In particular, this happens in the special case of a filter file
+containing only comments.
+</para>
+<para>
+The delivery commands <command>deliver</command>, <command>save</command>, and <command>pipe</command> are by default
+significant. However, if such a command is preceded by the word <quote>unseen</quote>, its
+delivery is not considered to be significant. In contrast, other commands such
+as <command>mail</command> and <command>vacation</command> do not set up significant deliveries unless
+preceded by the word <quote>seen</quote>. The following example commands set up
+significant deliveries:
+</para>
+<literallayout class="monospaced">
+deliver jack@???
+pipe $home/bin/mymailscript
+seen mail subject "message discarded"
+seen finish
+</literallayout>
+<para>
+The following example commands do not set up significant deliveries:
+</para>
+<literallayout class="monospaced">
+unseen deliver jack@???
+unseen pipe $home/bin/mymailscript
+mail subject "message discarded"
+finish
+</literallayout>
+</section>
+<section id="SEC222">
+<title>Filter commands</title>
+<para>
+The filter commands that are described in subsequent sections are listed
+below, with the section in which they are described in brackets:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="100pt" align="left"/>
+<colspec colwidth="300pt" align="left"/>
+<tbody>
+<row>
+<entry><command>add</command></entry>
+<entry>&nbsp;&nbsp;increment a user variable (section <xref linkend="SECTadd"/>)</entry>
+</row>
+<row>
+<entry><command>deliver</command></entry>
+<entry>&nbsp;&nbsp;deliver to an email address (section <xref linkend="SECTdeliver"/>)</entry>
+</row>
+<row>
+<entry><command>fail</command></entry>
+<entry>&nbsp;&nbsp;force delivery failure (sysadmin use) (section <xref linkend="SECTfail"/>)</entry>
+</row>
+<row>
+<entry><command>finish</command></entry>
+<entry>&nbsp;&nbsp;end processing (section <xref linkend="SECTfinish"/>)</entry>
+</row>
+<row>
+<entry><command>freeze</command></entry>
+<entry>&nbsp;&nbsp;freeze message (sysadmin use) (section <xref linkend="SECTfreeze"/>)</entry>
+</row>
+<row>
+<entry><command>headers</command></entry>
+<entry>&nbsp;&nbsp;set the header character set (section <xref linkend="SECTheaders"/>)</entry>
+</row>
+<row>
+<entry><command>if</command></entry>
+<entry>&nbsp;&nbsp;test condition(s) (section <xref linkend="SECTif"/>)</entry>
+</row>
+<row>
+<entry><command>logfile</command></entry>
+<entry>&nbsp;&nbsp;define log file (section <xref linkend="SECTlog"/>)</entry>
+</row>
+<row>
+<entry><command>logwrite</command></entry>
+<entry>&nbsp;&nbsp;write to log file (section <xref linkend="SECTlog"/>)</entry>
+</row>
+<row>
+<entry><command>mail</command></entry>
+<entry>&nbsp;&nbsp;send a reply message (section <xref linkend="SECTmail"/>)</entry>
+</row>
+<row>
+<entry><command>pipe</command></entry>
+<entry>&nbsp;&nbsp;pipe to a command (section <xref linkend="SECTpipe"/>)</entry>
+</row>
+<row>
+<entry><command>save</command></entry>
+<entry>&nbsp;&nbsp;save to a file (section <xref linkend="SECTsave"/>)</entry>
+</row>
+<row>
+<entry><command>testprint</command></entry>
+<entry>&nbsp;&nbsp;print while testing (section <xref linkend="SECTtestprint"/>)</entry>
+</row>
+<row>
+<entry><command>vacation</command></entry>
+<entry>&nbsp;&nbsp;tailored form of <command>mail</command> (section <xref linkend="SECTmail"/>)</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+The <command>headers</command> command has additional parameters that can be used only in a
+system filter. The <command>fail</command> and <command>freeze</command> commands are available only when
+Exim&#x2019;s filtering facilities are being used as a system filter, and are
+therefore usable only by the system administrator and not by ordinary users.
+They are mentioned only briefly in this document; for more information, see the
+main Exim specification.
+</para>
+</section>
+<section id="SECTadd">
+<title>The add command</title>
+<literallayout>
+<literal>     add </literal>&lt;<emphasis>number</emphasis>&gt;<literal> to </literal>&lt;<emphasis>user variable</emphasis>&gt;
+<literal>e.g. add 2 to n3</literal>
+</literallayout>
+<para>
+There are 10 user variables of this type, with names <varname>$n0</varname> &ndash; <varname>$n9</varname>. Their
+values can be obtained by the normal expansion syntax (for example <varname>$n3</varname>) in
+other commands. At the start of filtering, these variables all contain zero.
+Both arguments of the <command>add</command> command are expanded before use, making it
+possible to add variables to each other. Subtraction can be obtained by adding
+negative numbers.
+</para>
+</section>
+<section id="SECTdeliver">
+<title>The deliver command</title>
+<literallayout>
+<literal>     deliver</literal> &lt;<emphasis>mail address</emphasis>&gt;
+<literal>e.g. deliver "Dr Livingstone &lt;David@???&gt;"</literal>
+</literallayout>
+<para>
+This command provides a forwarding operation. The delivery that it sets up is
+significant unless the command is preceded by <quote>unseen</quote> (see section
+<xref linkend="SECTsigdel"/>). The message is sent on to the given address, exactly as
+happens if the address had appeared in a traditional <filename>.forward</filename> file. If you
+want to deliver the message to a number of different addresses, you can use
+more than one <command>deliver</command> command (each one may have only one address).
+However, duplicate addresses are discarded.
+</para>
+<para>
+To deliver a copy of the message to your normal mailbox, your login name can be
+given as the address. Once an address has been processed by the filtering
+mechanism, an identical generated address will not be so processed again, so
+doing this does not cause a loop.
+</para>
+<para>
+However, if you have a mail alias, you should <emphasis>not</emphasis> refer to it here. For
+example, if the mail address <emphasis>L.Gulliver</emphasis> is aliased to <emphasis>lg303</emphasis> then all
+references in Gulliver&#x2019;s <filename>.forward</filename> file should be to <emphasis>lg303</emphasis>. A reference
+to the alias will not work for messages that are addressed to that alias,
+since, like <filename>.forward</filename> file processing, aliasing is performed only once on an
+address, in order to avoid looping.
+</para>
+<para>
+Following the new address, an optional second address, preceded by
+<quote>errors_to</quote> may appear. This changes the address to which delivery errors on
+the forwarded message will be sent. Instead of going to the message&#x2019;s original
+sender, they go to this new address. For ordinary users, the only value that is
+permitted for this address is the user whose filter file is being processed.
+For example, the user <emphasis>lg303</emphasis> whose mailbox is in the domain
+<emphasis>lilliput.example</emphasis> could have a filter file that contains
+</para>
+<literallayout class="monospaced">
+deliver jon@??? errors_to lg303@???
+</literallayout>
+<para>
+Clearly, using this feature makes sense only in situations where not all
+messages are being forwarded. In particular, bounce messages must not be
+forwarded in this way, as this is likely to create a mail loop if something
+goes wrong.
+</para>
+</section>
+<section id="SECTsave">
+<title>The save command</title>
+<literallayout>
+<literal>     save </literal>&lt;<emphasis>file name</emphasis>&gt;
+<literal>e.g. save $home/mail/bookfolder</literal>
+</literallayout>
+<para>
+This command specifies that a copy of the message is to be appended to the
+given file (that is, the file is to be used as a mail folder). The delivery
+that <command>save</command> sets up is significant unless the command is preceded by
+<quote>unseen</quote> (see section <xref linkend="SECTsigdel"/>).
+</para>
+<para>
+More than one <command>save</command> command may be obeyed; each one causes a copy of the
+message to be written to its argument file, provided they are different
+(duplicate <command>save</command> commands are ignored).
+</para>
+<para>
+If the file name does not start with a / character, the contents of the
+<varname>$home</varname> variable are prepended, unless it is empty, or the system
+administrator has disabled this feature. In conventional configurations, this
+variable is normally set in a user filter to the user&#x2019;s home directory, but the
+system administrator may set it to some other path. In some configurations,
+<varname>$home</varname> may be unset, or prepending may be disabled, in which case a
+non-absolute path name may be generated. Such configurations convert this to an
+absolute path when the delivery takes place. In a system filter, <varname>$home</varname> is
+never set.
+</para>
+<para>
+The user must of course have permission to write to the file, and the writing
+of the file takes place in a process that is running as the user, under the
+user&#x2019;s primary group. Any secondary groups to which the user may belong are not
+normally taken into account, though the system administrator can configure Exim
+to set them up. In addition, the ability to use this command at all is
+controlled by the system administrator &ndash; it may be forbidden on some systems.
+</para>
+<para>
+An optional mode value may be given after the file name. The value for the mode
+is interpreted as an octal number, even if it does not begin with a zero. For
+example:
+</para>
+<literallayout class="monospaced">
+save /some/folder 640
+</literallayout>
+<para>
+This makes it possible for users to override the system-wide mode setting for
+file deliveries, which is normally 600. If an existing file does not have the
+correct mode, it is changed.
+</para>
+<para>
+An alternative form of delivery may be enabled on your system, in which each
+message is delivered into a new file in a given directory. If this is the case,
+this functionality can be requested by giving the directory name terminated by
+a slash after the <command>save</command> command, for example
+</para>
+<literallayout class="monospaced">
+save separated/messages/
+</literallayout>
+<para>
+There are several different formats for such deliveries; check with your system
+administrator or local documentation to find out which (if any) are available
+on your system. If this functionality is not enabled, the use of a path name
+ending in a slash causes an error.
+</para>
+</section>
+<section id="SECTpipe">
+<title>The pipe command</title>
+<literallayout>
+<literal>     pipe </literal>&lt;<emphasis>command</emphasis>&gt;
+<literal>e.g. pipe "$home/bin/countmail $sender_address"</literal>
+</literallayout>
+<para>
+This command specifies that the message is to be delivered to the specified
+command using a pipe. The delivery that it sets up is significant unless the
+command is preceded by <quote>unseen</quote> (see section <xref linkend="SECTsigdel"/>). Remember,
+however, that no deliveries are done while the filter is being processed. All
+deliveries happen later on. Therefore, the result of running the pipe is not
+available to the filter.
+</para>
+<para>
+When the deliveries are done, a separate process is run, and a copy of the
+message is passed on its standard input. The process runs as the user, under
+the user&#x2019;s primary group. Any secondary groups to which the user may belong are
+not normally taken into account, though the system administrator can configure
+Exim to set them up. More than one <command>pipe</command> command may appear; each one causes
+a copy of the message to be written to its argument pipe, provided they are
+different (duplicate <command>pipe</command> commands are ignored).
+</para>
+<para>
+When the time comes to transport the message, the command supplied to <command>pipe</command>
+is split up by Exim into a command name and a number of arguments. These are
+delimited by white space except for arguments enclosed in double quotes, in
+which case backslash is interpreted as an escape, or in single quotes, in which
+case no escaping is recognized. Note that as the whole command is normally
+supplied in double quotes, a second level of quoting is required for internal
+double quotes. For example:
+</para>
+<literallayout class="monospaced">
+pipe "$home/myscript \"size is $message_size\""
+</literallayout>
+<para>
+String expansion is performed on the separate components after the line has
+been split up, and the command is then run directly by Exim; it is not run
+under a shell. Therefore, substitution cannot change the number of arguments,
+nor can quotes, backslashes or other shell metacharacters in variables cause
+confusion.
+</para>
+<para>
+Documentation for some programs that are normally run via this kind of pipe
+often suggest that the command should start with
+</para>
+<literallayout class="monospaced">
+IFS=" "
+</literallayout>
+<para>
+This is a shell command, and should <emphasis>not</emphasis> be present in Exim filter files,
+since it does not normally run the command under a shell.
+</para>
+<para>
+However, there is an option that the administrator can set to cause a shell to
+be used. In this case, the entire command is expanded as a single string and
+passed to the shell for interpretation. It is recommended that this be avoided
+if at all possible, since it can lead to problems when inserted variables
+contain shell metacharacters.
+</para>
+<para>
+The default PATH set up for the command is determined by the system
+administrator, usually containing at least <filename>/bin</filename> and <filename>/usr/bin</filename> so that
+common commands are available without having to specify an absolute file name.
+However, it is possible for the system administrator to restrict the pipe
+facility so that the command name must not contain any / characters, and must
+be found in one of the directories in the configured PATH. It is also possible
+for the system administrator to lock out the use of the <command>pipe</command> command
+altogether.
+</para>
+<para>
+When the command is run, a number of environment variables are set up. The
+complete list for pipe deliveries may be found in the Exim reference manual.
+Those that may be useful for pipe deliveries from user filter files are:
+</para>
+<literallayout>
+<literal>DOMAIN            </literal>   the domain of the address
+<literal>HOME              </literal>   your home directory
+<literal>LOCAL_PART        </literal>   see below
+<literal>LOCAL_PART_PREFIX </literal>   see below
+<literal>LOCAL_PART_SUFFIX </literal>   see below
+<literal>LOGNAME           </literal>   your login name
+<literal>MESSAGE_ID        </literal>   the unique id of the message
+<literal>PATH              </literal>   the command search path
+<literal>RECIPIENT         </literal>   the complete recipient address
+<literal>SENDER            </literal>   the sender of the message
+<literal>SHELL             </literal>   <literal>/bin/sh</literal>
+<literal>USER              </literal>   see below
+</literallayout>
+<para>
+LOCAL_PART, LOGNAME, and USER are all set to the same value, namely, your login
+id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may be set if Exim is configured to
+recognize prefixes or suffixes in the local parts of addresses. For example, a
+message addressed to <emphasis>pat-suf2@???</emphasis> may cause the filter for user
+<emphasis>pat</emphasis> to be run. If this sets up a pipe delivery, LOCAL_PART_SUFFIX is
+<literal>-suf2</literal> when the pipe command runs. The system administrator has to configure
+Exim specially for this feature to be available.
+</para>
+<para>
+If you run a command that is a shell script, be very careful in your use of
+data from the incoming message in the commands in your script. RFC 2822 is very
+generous in the characters that are permitted to appear in mail addresses, and
+in particular, an address may begin with a vertical bar or a slash. For this
+reason you should always use quotes round any arguments that involve data from
+the message, like this:
+</para>
+<literallayout class="monospaced">
+/some/command '$SENDER'
+</literallayout>
+<para>
+so that inserted shell meta-characters do not cause unwanted effects.
+</para>
+<para>
+Remember that, as was explained earlier, the pipe command is not run at the
+time the filter file is interpreted. The filter just defines what deliveries
+are required for one particular addressee of a message. The deliveries
+themselves happen later, once Exim has decided everything that needs to be done
+for the message.
+</para>
+<para>
+A consequence of this is that you cannot inspect the return code from the pipe
+command from within the filter. Nevertheless, the code returned by the command
+is important, because Exim uses it to decide whether the delivery has succeeded
+or failed.
+</para>
+<para>
+The command should return a zero completion code if all has gone well. Most
+non-zero codes are treated by Exim as indicating a failure of the pipe. This is
+treated as a delivery failure, causing the message to be returned to its
+sender. However, there are some completion codes that are treated as temporary
+errors. The message remains on Exim&#x2019;s spool disk, and the delivery is tried
+again later, though it will ultimately time out if the delivery failures go on
+too long. The completion codes to which this applies can be specified by the
+system administrator; the default values are 73 and 75.
+</para>
+<para>
+The pipe command should not normally write anything to its standard output or
+standard error file descriptors. If it does, whatever is written is normally
+returned to the sender of the message as a delivery error, though this action
+can be varied by the system administrator.
+</para>
+</section>
+<section id="SECTmail">
+<title>Mail commands</title>
+<para>
+There are two commands that cause the creation of a new mail message, neither
+of which count as a significant delivery unless the command is preceded by the
+word <quote>seen</quote> (see section <xref linkend="SECTsigdel"/>). This is a powerful facility, but
+it should be used with care, because of the danger of creating infinite
+sequences of messages. The system administrator can forbid the use of these
+commands altogether.
+</para>
+<para>
+To help prevent runaway message sequences, these commands have no effect when
+the incoming message is a bounce (delivery error) message, and messages sent by
+this means are treated as if they were reporting delivery errors. Thus, they
+should never themselves cause a bounce message to be returned. The basic
+mail-sending command is
+</para>
+<literallayout>
+<literal>mail [to </literal>&lt;<emphasis>address-list</emphasis>&gt;<literal>]</literal>
+<literal>     [cc </literal>&lt;<emphasis>address-list</emphasis>&gt;<literal>]</literal>
+<literal>     [bcc </literal>&lt;<emphasis>address-list</emphasis>&gt;<literal>]</literal>
+<literal>     [from </literal>&lt;<emphasis>address</emphasis>&gt;<literal>]</literal>
+<literal>     [reply_to </literal>&lt;<emphasis>address</emphasis>&gt;<literal>]</literal>
+<literal>     [subject </literal>&lt;<emphasis>text</emphasis>&gt;<literal>]</literal>
+<literal>     [extra_headers </literal>&lt;<emphasis>text</emphasis>&gt;<literal>]</literal>
+<literal>     [text </literal>&lt;<emphasis>text</emphasis>&gt;<literal>]</literal>
+<literal>     [[expand] file </literal>&lt;<emphasis>filename</emphasis>&gt;<literal>]</literal>
+<literal>     [return message]</literal>
+<literal>     [log </literal>&lt;<emphasis>log file name</emphasis>&gt;<literal>]</literal>
+<literal>     [once </literal>&lt;<emphasis>note file name</emphasis>&gt;<literal>]</literal>
+<literal>     [once_repeat </literal>&lt;<emphasis>time interval</emphasis>&gt;<literal>]</literal>
+<literal>e.g. mail text "Your message about $h_subject: has been received"</literal>
+</literallayout>
+<para>
+Each &lt;<emphasis>address-list</emphasis>&gt; can contain a number of addresses, separated by commas,
+in the format of a <emphasis>To:</emphasis> or <emphasis>Cc:</emphasis> header line. In fact, the text you supply
+here is copied exactly into the appropriate header line. It may contain
+additional information as well as email addresses. For example:
+</para>
+<literallayout class="monospaced">
+mail to "Julius Caesar &lt;jc@???&gt;, \
+         &lt;ma@???&gt; (Mark A.)"
+</literallayout>
+<para>
+Similarly, the texts supplied for <option>from</option> and <option>reply_to</option> are copied into
+their respective header lines.
+</para>
+<para>
+As a convenience for use in one common case, there is also a command called
+<command>vacation</command>. It behaves in the same way as <command>mail</command>, except that the defaults
+for the <option>subject</option>, <option>file</option>, <option>log</option>, <option>once</option>, and <option>once_repeat</option> options
+are
+</para>
+<literallayout class="monospaced">
+subject "On vacation"
+expand file .vacation.msg
+log  .vacation.log
+once .vacation
+once_repeat 7d
+</literallayout>
+<para>
+respectively. These are the same file names and repeat period used by the
+traditional Unix <command>vacation</command> command. The defaults can be overridden by
+explicit settings, but if a file name is given its contents are expanded only
+if explicitly requested.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: The <command>vacation</command> command should always be used conditionally,
+subject to at least the <command>personal</command> condition (see section <xref linkend="SECTpersonal"/>
+below) so as not to send automatic replies to non-personal messages from
+mailing lists or elsewhere. Sending an automatic response to a mailing list or
+a mailing list manager is an Internet Sin.
+</para>
+<para>
+For both commands, the key/value argument pairs can appear in any order. At
+least one of <option>text</option> or <option>file</option> must appear (except with <command>vacation</command>, where
+there is a default for <option>file</option>); if both are present, the text string appears
+first in the message. If <option>expand</option> precedes <option>file</option>, each line of the file is
+subject to string expansion before it is included in the message.
+</para>
+<para>
+Several lines of text can be supplied to <option>text</option> by including the escape
+sequence <quote>\n</quote> in the string wherever a newline is required. If the command is
+output during filter file testing, newlines in the text are shown as <quote>\n</quote>.
+</para>
+<para>
+Note that the keyword for creating a <emphasis>Reply-To:</emphasis> header is <option>reply_to</option>,
+because Exim keywords may contain underscores, but not hyphens. If the <option>from</option>
+keyword is present and the given address does not match the user who owns the
+forward file, Exim normally adds a <emphasis>Sender:</emphasis> header to the message, though it
+can be configured not to do this.
+</para>
+<para>
+The <option>extra_headers</option> keyword allows you to add custom header lines to the
+message. The text supplied must be one or more syntactically valid RFC 2822
+header lines. You can use <quote>\n</quote> within quoted text to specify newlines between
+headers, and also to define continued header lines. For example:
+</para>
+<literallayout class="monospaced">
+extra_headers "h1: first\nh2: second\n continued\nh3: third"
+</literallayout>
+<para>
+No newline should appear at the end of the final header line.
+</para>
+<para>
+If no <option>to</option> argument appears, the message is sent to the address in the
+<varname>$reply_address</varname> variable (see section <xref linkend="SECTfilterstringexpansion"/> above).
+An <emphasis>In-Reply-To:</emphasis> header is automatically included in the created message,
+giving a reference to the message identification of the incoming message.
+</para>
+<para>
+If <option>return message</option> is specified, the incoming message that caused the filter
+file to be run is added to the end of the message, subject to a maximum size
+limitation.
+</para>
+<para>
+If a log file is specified, a line is added to it for each message sent.
+</para>
+<para>
+If a <option>once</option> file is specified, it is used to hold a database for remembering
+who has received a message, and no more than one message is ever sent to any
+particular address, unless <option>once_repeat</option> is set. This specifies a time
+interval after which another copy of the message is sent. The interval is
+specified as a sequence of numbers, each followed by the initial letter of one
+of <quote>seconds</quote>, <quote>minutes</quote>, <quote>hours</quote>, <quote>days</quote>, or <quote>weeks</quote>. For example,
+</para>
+<literallayout class="monospaced">
+once_repeat 5d4h
+</literallayout>
+<para>
+causes a new message to be sent if at least 5 days and 4 hours have elapsed
+since the last one was sent. There must be no white space in a time interval.
+</para>
+<para>
+Commonly, the file name specified for <option>once</option> is used as the base name for
+direct-access (DBM) file operations. There are a number of different DBM
+libraries in existence. Some operating systems provide one as a default, but
+even in this case a different one may have been used when building Exim. With
+some DBM libraries, specifying <option>once</option> results in two files being created,
+with the suffixes <filename>.dir</filename> and <filename>.pag</filename> being added to the given name. With
+some others a single file with the suffix <filename>.db</filename> is used, or the name is used
+unchanged.
+</para>
+<para>
+Using a DBM file for implementing the <option>once</option> feature means that the file
+grows as large as necessary. This is not usually a problem, but some system
+administrators want to put a limit on it. The facility can be configured not to
+use a DBM file, but instead, to use a regular file with a maximum size. The
+data in such a file is searched sequentially, and if the file fills up, the
+oldest entry is deleted to make way for a new one. This means that some
+correspondents may receive a second copy of the message after an unpredictable
+interval. Consult your local information to see if your system is configured
+this way.
+</para>
+<para>
+More than one <command>mail</command> or <command>vacation</command> command may be obeyed in a single filter
+run; they are all honoured, even when they are to the same recipient.
+</para>
+</section>
+<section id="SECTlog">
+<title>Logging commands</title>
+<para>
+A log can be kept of actions taken by a filter file. This facility is normally
+available in conventional configurations, but there are some situations where
+it might not be. Also, the system administrator may choose to disable it. Check
+your local information if in doubt.
+</para>
+<para>
+Logging takes place while the filter file is being interpreted. It does not
+queue up for later like the delivery commands. The reason for this is so that a
+log file need be opened only once for several write operations. There are two
+commands, neither of which constitutes a significant delivery. The first
+defines a file to which logging output is subsequently written:
+</para>
+<literallayout>
+<literal>     logfile </literal>&lt;<emphasis>file name</emphasis>&gt;
+<literal>e.g. logfile $home/filter.log</literal>
+</literallayout>
+<para>
+The file name must be fully qualified. You can use <varname>$home</varname>, as in this
+example, to refer to your home directory. The file name may optionally be
+followed by a mode for the file, which is used if the file has to be created.
+For example,
+</para>
+<literallayout class="monospaced">
+logfile $home/filter.log 0644
+</literallayout>
+<para>
+The number is interpreted as octal, even if it does not begin with a zero.
+The default for the mode is 600. It is suggested that the <command>logfile</command> command
+normally appear as the first command in a filter file. Once a log file has
+been obeyed, the <command>logwrite</command> command can be used to write to it:
+</para>
+<literallayout>
+<literal>     logwrite "</literal>&lt;<emphasis>some text string</emphasis>&gt;<literal>"</literal>
+<literal>e.g. logwrite "$tod_log $message_id processed"</literal>
+</literallayout>
+<para>
+It is possible to have more than one <command>logfile</command> command, to specify writing to
+different log files in different circumstances.
+A previously opened log is closed on a subsequent <command>logfile</command> command.
+Writing takes place at the end
+of the file, and a newline character is added to the end of each string if
+there isn&#x2019;t one already there. Newlines can be put in the middle of the string
+by using the <quote>\n</quote> escape sequence. Lines from simultaneous deliveries may get
+interleaved in the file, as there is no interlocking, so you should plan your
+logging with this in mind. However, data should not get lost.
+</para>
+</section>
+<section id="SECTfinish">
+<title>The finish command</title>
+<para>
+The command <command>finish</command>, which has no arguments, causes Exim to stop
+interpreting the filter file. This is not a significant action unless preceded
+by <quote>seen</quote>. A filter file containing only <quote>seen finish</quote> is a black hole.
+</para>
+</section>
+<section id="SECTtestprint">
+<title>The testprint command</title>
+<para>
+It is sometimes helpful to be able to print out the values of variables when
+testing filter files. The command
+</para>
+<literallayout>
+<literal>     testprint </literal>&lt;<emphasis>text</emphasis>&gt;
+<literal>e.g. testprint "home=$home reply_address=$reply_address"</literal>
+</literallayout>
+<para>
+does nothing when mail is being delivered. However, when the filtering code is
+being tested by means of the <option>-bf</option> option (see section <xref linkend="SECTtesting"/>
+above), the value of the string is written to the standard output.
+</para>
+</section>
+<section id="SECTfail">
+<title>The fail command</title>
+<para>
+When Exim&#x2019;s filtering facilities are being used as a system filter, the
+<command>fail</command> command is available, to force delivery failure. Because this command
+is normally usable only by the system administrator, and not enabled for use by
+ordinary users, it is described in more detail in the main Exim specification
+rather than in this document.
+</para>
+</section>
+<section id="SECTfreeze">
+<title>The freeze command</title>
+<para>
+When Exim&#x2019;s filtering facilities are being used as a system filter, the
+<command>freeze</command> command is available, to freeze a message on the queue. Because this
+command is normally usable only by the system administrator, and not enabled
+for use by ordinary users, it is described in more detail in the main Exim
+specification rather than in this document.
+</para>
+</section>
+<section id="SECTheaders">
+<title>The headers command</title>
+<para>
+The <command>headers</command> command can be used to change the target character set that is
+used when translating the contents of encoded header lines for insertion by the
+<varname>$header_</varname> mechanism (see section <xref linkend="SECTheadervariables"/> above). The
+default can be set in the Exim configuration; if not specified, ISO-8859-1 is
+used. The only currently supported format for the <command>headers</command> command in user
+filters is as in this example:
+</para>
+<literallayout class="monospaced">
+headers charset "UTF-8"
+</literallayout>
+<para>
+That is, <command>headers</command> is followed by the word <quote>charset</quote> and then the name of a
+character set. This particular example would be useful if you wanted to compare
+the contents of a header to a UTF-8 string.
+</para>
+<para>
+In system filter files, the <command>headers</command> command can be used to add or remove
+header lines from the message. These features are described in the main Exim
+specification.
+</para>
+</section>
+<section id="SECTif">
+<title>Obeying commands conditionally</title>
+<para>
+Most of the power of filtering comes from the ability to test conditions and
+obey different commands depending on the outcome. The <command>if</command> command is used to
+specify conditional execution, and its general form is
+</para>
+<literallayout>
+<literal>if    </literal>&lt;<emphasis>condition</emphasis>&gt;
+<literal>then  </literal>&lt;<emphasis>commands</emphasis>&gt;
+<literal>elif  </literal>&lt;<emphasis>condition</emphasis>&gt;
+<literal>then  </literal>&lt;<emphasis>commands</emphasis>&gt;
+<literal>else  </literal>&lt;<emphasis>commands</emphasis>&gt;
+<literal>endif</literal>
+</literallayout>
+<para>
+There may be any number of <command>elif</command> and <command>then</command> sections (including none) and
+the <command>else</command> section is also optional. Any number of commands, including nested
+<command>if</command> commands, may appear in any of the &lt;<emphasis>commands</emphasis>&gt; sections.
+</para>
+<para>
+Conditions can be combined by using the words <command>and</command> and <command>or</command>, and round
+brackets (parentheses) can be used to specify how several conditions are to
+combine. Without brackets, <command>and</command> is more binding than <command>or</command>. For example:
+</para>
+<literallayout class="monospaced">
+if
+$h_subject: contains "Make money" or
+$h_precedence: is "junk" or
+($h_sender: matches ^\\d{8}@ and not personal) or
+$message_body contains "this is not spam"
+then
+seen finish
+endif
+</literallayout>
+<para>
+A condition can be preceded by <command>not</command> to negate it, and there are also some
+negative forms of condition that are more English-like.
+</para>
+</section>
+<section id="SEC23">
+<title>String testing conditions</title>
+<para>
+There are a number of conditions that operate on text strings, using the words
+<quote>begins</quote>, <quote>ends</quote>, <quote>is</quote>, <quote>contains</quote> and <quote>matches</quote>. If you want to
+apply the same test to more than one header line, you can easily concatenate
+them into a single string for testing, as in this example:
+</para>
+<literallayout class="monospaced">
+if "$h_to:, $h_cc:" contains me@??? then ...
+</literallayout>
+<para>
+If a string-testing condition name is written in lower case, the testing
+of letters is done without regard to case; if it is written in upper case
+(for example, <quote>CONTAINS</quote>), the case of letters is taken into account.
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> begins </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> does not begin </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>e.g. $header_from: begins "Friend@"</literal>
+</literallayout>
+<para>
+A <quote>begins</quote> test checks for the presence of the second string at the start of
+the first, both strings having been expanded.
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> ends </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> does not end </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>e.g. $header_from: ends "public.com.example"</literal>
+</literallayout>
+<para>
+An <quote>ends</quote> test checks for the presence of the second string at the end of
+the first, both strings having been expanded.
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> is </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> is not </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>e.g. $local_part_suffix is "-foo"</literal>
+</literallayout>
+<para>
+An <quote>is</quote> test does an exact match between the strings, having first expanded
+both strings.
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> contains </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> does not contain </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>e.g. $header_subject: contains "evolution"</literal>
+</literallayout>
+<para>
+A <quote>contains</quote> test does a partial string match, having expanded both strings.
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> matches </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>text1</emphasis>&gt;<literal> does not match </literal>&lt;<emphasis>text2</emphasis>&gt;
+<literal>e.g. $sender_address matches "(bill|john)@"</literal>
+</literallayout>
+<para>
+For a <quote>matches</quote> test, after expansion of both strings, the second one is
+interpreted as a regular expression. Exim uses the PCRE regular expression
+library, which provides regular expressions that are compatible with Perl.
+</para>
+<para>
+The match succeeds if the regular expression matches any part of the first
+string. If you want a regular expression to match only at the start or end of
+the subject string, you must encode that requirement explicitly, using the
+<literal>^</literal> or <literal>$</literal> metacharacters. The above example, which is not so constrained,
+matches all these addresses:
+</para>
+<literallayout class="monospaced">
+bill@???
+john@???
+spoonbill@???
+littlejohn@???
+</literallayout>
+<para>
+To match only the first two, you could use this:
+</para>
+<literallayout class="monospaced">
+if $sender_address matches "^(bill|john)@" then ...
+</literallayout>
+<para>
+Care must be taken if you need a backslash in a regular expression, because
+backslashes are interpreted as escape characters both by the string expansion
+code and by Exim&#x2019;s normal processing of strings in quotes. For example, if you
+want to test the sender address for a domain ending in <emphasis>.com</emphasis> the regular
+expression is
+</para>
+<literallayout class="monospaced">
+\.com$
+</literallayout>
+<para>
+The backslash and dollar sign in that expression have to be escaped when used
+in a filter command, as otherwise they would be interpreted by the expansion
+code. Thus, what you actually write is
+</para>
+<literallayout class="monospaced">
+if $sender_address matches \\.com\$
+</literallayout>
+<para>
+An alternative way of handling this is to make use of the <literal>\N</literal> expansion
+flag for suppressing expansion:
+</para>
+<literallayout class="monospaced">
+if $sender_address matches \N\.com$\N
+</literallayout>
+<para>
+Everything between the two occurrences of <literal>\N</literal> is copied without change by
+the string expander (and in fact you do not need the final one, because it is
+at the end of the string). If the regular expression is given in quotes
+(mandatory only if it contains white space) you have to write either
+</para>
+<literallayout class="monospaced">
+if $sender_address matches "\\\\.com\\$"
+</literallayout>
+<para>
+or
+</para>
+<literallayout class="monospaced">
+if $sender_address matches "\\N\\.com$\\N"
+</literallayout>
+<para>
+If the regular expression contains bracketed sub-expressions, numeric
+variable substitutions such as <varname>$1</varname> can be used in the subsequent actions
+after a successful match. If the match fails, the values of the numeric
+variables remain unchanged. Previous values are not restored after <command>endif</command>.
+In other words, only one set of values is ever available. If the condition
+contains several sub-conditions connected by <command>and</command> or <command>or</command>, it is the
+strings extracted from the last successful match that are available in
+subsequent actions. Numeric variables from any one sub-condition are also
+available for use in subsequent sub-conditions, because string expansion of a
+condition occurs just before it is tested.
+</para>
+</section>
+<section id="SEC24">
+<title>Numeric testing conditions</title>
+<para>
+The following conditions are available for performing numerical tests:
+</para>
+<literallayout>
+<literal>     </literal>&lt;<emphasis>number1</emphasis>&gt;<literal> is above </literal>&lt;<emphasis>number2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>number1</emphasis>&gt;<literal> is not above </literal>&lt;<emphasis>number2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>number1</emphasis>&gt;<literal> is below </literal>&lt;<emphasis>number2</emphasis>&gt;
+<literal>     </literal>&lt;<emphasis>number1</emphasis>&gt;<literal> is not below </literal>&lt;<emphasis>number2</emphasis>&gt;
+<literal>e.g. $message_size is not above 10k</literal>
+</literallayout>
+<para>
+The &lt;<emphasis>number</emphasis>&gt; arguments must expand to strings of digits, optionally
+followed by one of the letters K or M (upper case or lower case) which cause
+multiplication by 1024 and 1024x1024 respectively.
+</para>
+</section>
+<section id="SEC25">
+<title>Testing for significant deliveries</title>
+<para>
+You can use the <command>delivered</command> condition to test whether or not any previously
+obeyed filter commands have set up a significant delivery. For example:
+</para>
+<literallayout class="monospaced">
+if not delivered then save mail/anomalous endif
+</literallayout>
+<para>
+<quote>Delivered</quote> is perhaps a poor choice of name for this condition, because the
+message has not actually been delivered; rather, a delivery has been set up for
+later processing.
+</para>
+</section>
+<section id="SEC26">
+<title>Testing for error messages</title>
+<para>
+The condition <command>error_message</command> is true if the incoming message is a bounce
+(mail delivery error) message. Putting the command
+</para>
+<literallayout class="monospaced">
+if error_message then finish endif
+</literallayout>
+<para>
+at the head of your filter file is a useful insurance against things going
+wrong in such a way that you cannot receive delivery error reports. <emphasis role="bold">Note</emphasis>:
+<command>error_message</command> is a condition, not an expansion variable, and therefore is
+not preceded by <literal>$</literal>.
+</para>
+</section>
+<section id="SEC27">
+<title>Testing a list of addresses</title>
+<para>
+There is a facility for looping through a list of addresses and applying a
+condition to each of them. It takes the form
+</para>
+<literallayout>
+<literal>foranyaddress </literal>&lt;<emphasis>string</emphasis>&gt;<literal> (</literal>&lt;<emphasis>condition</emphasis>&gt;<literal>)</literal>
+</literallayout>
+<para>
+where &lt;<emphasis>string</emphasis>&gt; is interpreted as a list of RFC 2822 addresses, as in a
+typical header line, and &lt;<emphasis>condition</emphasis>&gt; is any valid filter condition or
+combination of conditions. The <quote>group</quote> syntax that is defined for certain
+header lines that contain addresses is supported.
+</para>
+<para>
+The parentheses surrounding the condition are mandatory, to delimit it from
+possible further sub-conditions of the enclosing <command>if</command> command. Within the
+condition, the expansion variable <varname>$thisaddress</varname> is set to the non-comment
+portion of each of the addresses in the string in turn. For example, if the
+string is
+</para>
+<literallayout class="monospaced">
+B.Simpson &lt;bart@???&gt;, lisa@??? (his sister)
+</literallayout>
+<para>
+then <varname>$thisaddress</varname> would take on the values <literal>bart@???</literal> and
+<literal>lisa@???</literal> in turn.
+</para>
+<para>
+If there are no valid addresses in the list, the whole condition is false. If
+the internal condition is true for any one address, the overall condition is
+true and the loop ends. If the internal condition is false for all addresses in
+the list, the overall condition is false. This example tests for the presence
+of an eight-digit local part in any address in a <emphasis>To:</emphasis> header:
+</para>
+<literallayout class="monospaced">
+if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ...
+</literallayout>
+<para>
+When the overall condition is true, the value of <varname>$thisaddress</varname> in the
+commands that follow <command>then</command> is the last value it took on inside the loop. At
+the end of the <command>if</command> command, the value of <varname>$thisaddress</varname> is reset to what it
+was before. It is best to avoid the use of multiple occurrences of
+<command>foranyaddress</command>, nested or otherwise, in a single <command>if</command> command, if the
+value of <varname>$thisaddress</varname> is to be used afterwards, because it isn&#x2019;t always
+clear what the value will be. Nested <command>if</command> commands should be used instead.
+</para>
+<para>
+Header lines can be joined together if a check is to be applied to more than
+one of them. For example:
+</para>
+<literallayout class="monospaced">
+if foranyaddress $h_to:,$h_cc: ....
+</literallayout>
+<para>
+This scans through the addresses in both the <emphasis>To:</emphasis> and the <emphasis>Cc:</emphasis> headers.
+</para>
+</section>
+<section id="SECTpersonal">
+<title>Testing for personal mail</title>
+<para>
+A common requirement is to distinguish between incoming personal mail and mail
+from a mailing list, or from a robot or other automatic process (for example, a
+bounce message). In particular, this test is normally required for <quote>vacation
+messages</quote>.
+</para>
+<para>
+The <command>personal</command> condition checks that the message is not a bounce message and
+that the current user&#x2019;s email address appears in the <emphasis>To:</emphasis> header. It also
+checks that the sender is not the current user or one of a number of common
+daemons, and that there are no header lines starting <emphasis>List-</emphasis> in the message.
+Finally, it checks the content of the <emphasis>Precedence:</emphasis> header line, if there is
+one.
+</para>
+<para>
+You should always use the <command>personal</command> condition when generating automatic
+responses. This example shows the use of <command>personal</command> in a filter file that is
+sending out vacation messages:
+</para>
+<literallayout class="monospaced">
+if personal then
+mail to $reply_address
+subject "I am on holiday"
+file $home/vacation/message
+once $home/vacation/once
+once_repeat 10d
+endif
+</literallayout>
+<para>
+It is tempting, when writing commands like the above, to quote the original
+subject in the reply. For example:
+</para>
+<literallayout class="monospaced">
+subject "Re: $h_subject:"
+</literallayout>
+<para>
+There is a danger in doing this, however. It may allow a third party to
+subscribe you to an opt-in mailing list, provided that the list accepts bounce
+messages as subscription confirmations. (Messages sent from filters are always
+sent as bounce messages.) Well-managed lists require a non-bounce message to
+confirm a subscription, so the danger is relatively small.
+</para>
+<para>
+If prefixes or suffixes are in use for local parts &ndash; something which depends
+on the configuration of Exim (see section <xref linkend="SECTmbox"/> below) &ndash; the tests
+for the current user are done with the full address (including the prefix and
+suffix, if any) as well as with the prefix and suffix removed. If the system is
+configured to rewrite local parts of mail addresses, for example, to rewrite
+<literal>dag46</literal> as <literal>Dirk.Gently</literal>, the rewritten form of the address is also used in
+the tests.
+</para>
+</section>
+<section id="SEC28">
+<title>Alias addresses for the personal condition</title>
+<para>
+It is quite common for people who have mail accounts on a number of different
+systems to forward all their mail to one system, and in this case a check for
+personal mail should test all their various mail addresses. To allow for this,
+the <command>personal</command> condition keyword can be followed by
+</para>
+<literallayout>
+<literal>alias </literal>&lt;<emphasis>address</emphasis>&gt;
+</literallayout>
+<para>
+any number of times, for example:
+</para>
+<literallayout class="monospaced">
+if personal alias smith@???
+            alias jones@???
+then ...
+</literallayout>
+<para>
+The alias addresses are treated as alternatives to the current user&#x2019;s email
+address when testing the contents of header lines.
+</para>
+</section>
+<section id="SEC29">
+<title>Details of the personal condition</title>
+<para>
+The basic <command>personal</command> test is roughly equivalent to the following:
+</para>
+<literallayout class="monospaced">
+not error_message and
+$message_headers does not contain "\nList-Id:" and
+$message_headers does not contain "\nList-Help:" and
+$message_headers does not contain "\nList-Subscribe:" and
+$message_headers does not contain "\nList-Unsubscribe:" and
+$message_headers does not contain "\nList-Post:" and
+$message_headers does not contain "\nList-Owner:" and
+$message_headers does not contain "\nList-Archive:" and
+(
+"${if def:h_auto-submitted:{present}{absent}}" is "absent" or
+$header_auto-submitted: is "no"
+) and
+$header_precedence: does not contain "bulk" and
+$header_precedence: does not contain "list" and
+$header_precedence: does not contain "junk" and
+foranyaddress $header_to:
+( $thisaddress contains "$local_part$domain" ) and
+not foranyaddress $header_from:
+(
+$thisaddress contains "$local_part@$domain" or
+$thisaddress contains "server@" or
+$thisaddress contains "daemon@" or
+$thisaddress contains "root@" or
+$thisaddress contains "listserv@" or
+$thisaddress contains "majordomo@" or
+$thisaddress contains "-request@" or
+$thisaddress matches  "^owner-[^@]+@"
+)
+</literallayout>
+<para>
+The variable <varname>$local_part</varname> contains the local part of the mail address of
+the user whose filter file is being run &ndash; it is normally your login id. The
+<varname>$domain</varname> variable contains the mail domain. As explained above, if aliases
+or rewriting are defined, or if prefixes or suffixes are in use, the tests for
+the current user are also done with alternative addresses.
+</para>
+</section>
+<section id="SEC30">
+<title>Testing delivery status</title>
+<para>
+There are two conditions that are intended mainly for use in system filter
+files, but which are available in users&#x2019; filter files as well. The condition
+<command>first_delivery</command> is true if this is the first process that is attempting to
+deliver the message, and false otherwise. This indicator is not reset until the
+first delivery process successfully terminates; if there is a crash or a power
+failure (for example), the next delivery attempt is also a <quote>first delivery</quote>.
+</para>
+<para>
+In a user filter file <command>first_delivery</command> will be false if there was previously
+an error in the filter, or if a delivery for the user failed owing to, for
+example, a quota error, or if forwarding to a remote address was deferred for
+some reason.
+</para>
+<para>
+The condition <command>manually_thawed</command> is true if the message was <quote>frozen</quote> for
+some reason, and was subsequently released by the system administrator. It is
+unlikely to be of use in users&#x2019; filter files.
+</para>
+</section>
+<section id="SECTmbox">
+<title>Multiple personal mailboxes</title>
+<titleabbrev>SEC31</titleabbrev>
+<para>
+The system administrator can configure Exim so that users can set up variants
+on their email addresses and handle them separately. Consult your system
+administrator or local documentation to see if this facility is enabled on your
+system, and if so, what the details are.
+</para>
+<para>
+The facility involves the use of a prefix or a suffix on an email address. For
+example, all mail addressed to <emphasis>lg303-</emphasis>&lt;<emphasis>something</emphasis>&gt; would be the property
+of user <emphasis>lg303</emphasis>, who could determine how it was to be handled, depending on
+the value of &lt;<emphasis>something</emphasis>&gt;.
+</para>
+<para>
+There are two possible ways in which this can be set up. The first possibility
+is the use of multiple <filename>.forward</filename> files. In this case, mail to <emphasis>lg303-foo</emphasis>,
+for example, is handled by looking for a file called <filename>.forward-foo</filename> in
+<emphasis>lg303</emphasis>&#x2019;s home directory. If such a file does not exist, delivery fails
+and the message is returned to its sender.
+</para>
+<para>
+The alternative approach is to pass all messages through a single <filename>.forward</filename>
+file, which must be a filter file so that it can distinguish between the
+different cases by referencing the variables <varname>$local_part_prefix</varname> or
+<varname>$local_part_suffix</varname>, as in the final example in section <xref linkend="SECTex"/> below.
+</para>
+<para>
+It is possible to configure Exim to support both schemes at once. In this case,
+a specific <filename>.forward-foo</filename> file is first sought; if it is not found, the basic
+<filename>.forward</filename> file is used.
+</para>
+<para>
+The <command>personal</command> test (see section <xref linkend="SECTpersonal"/>) includes prefixes and
+suffixes in its checking.
+</para>
+</section>
+<section id="SEC43">
+<title>Ignoring delivery errors</title>
+<para>
+As was explained above, filtering just sets up addresses for delivery &ndash; no
+deliveries are actually done while a filter file is active. If any of the
+generated addresses subsequently suffers a delivery failure, an error message
+is generated in the normal way. However, if a filter command that sets up a
+delivery is preceded by the word <quote>noerror</quote>, errors for that delivery,
+and any deliveries consequent on it (that is, from alias, forwarding, or
+filter files it invokes) are ignored.
+</para>
+</section>
+<section id="SECTex">
+<title>Examples of Exim filter commands</title>
+<para>
+Simple forwarding:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+deliver baggins@???
+</literallayout>
+<para>
+Vacation handling using traditional means, assuming that the <filename>.vacation.msg</filename>
+and other files have been set up in your home directory:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+unseen pipe "/usr/ucb/vacation \"$local_part\""
+</literallayout>
+<para>
+Vacation handling inside Exim, having first created a file called
+<filename>.vacation.msg</filename> in your home directory:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+if personal then vacation endif
+</literallayout>
+<para>
+File some messages by subject:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+if $header_subject: contains "empire" or
+$header_subject: contains "foundation"
+then
+save $home/mail/f+e
+endif
+</literallayout>
+<para>
+Save all non-urgent messages by weekday:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+if $header_subject: does not contain "urgent" and
+$tod_full matches "^(...),"
+then
+save $home/mail/$1
+endif
+</literallayout>
+<para>
+Throw away all mail from one site, except from postmaster:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+if $reply_address contains "@spam.site.example" and
+$reply_address does not contain "postmaster@"
+then
+seen finish
+endif
+</literallayout>
+<para>
+Handle multiple personal mailboxes:
+</para>
+<literallayout class="monospaced">
+# Exim filter
+if $local_part_suffix is "-foo"
+then
+save $home/mail/foo
+elif $local_part_suffix is "-bar"
+then
+save $home/mail/bar
+endif
+</literallayout>
+</section>
+</chapter>
+
+</book>
diff --git a/docbook/4.95/spec.xml b/docbook/4.95/spec.xml
new file mode 100644
index 0000000..a9976c8
--- /dev/null
+++ b/docbook/4.95/spec.xml
@@ -0,0 +1,76968 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+
+<?sdop
+  foot_right_recto="&chaptertitle; (&chapternumber;)"
+  foot_right_verso="&chaptertitle; (&chapternumber;)"
+  toc_chapter_blanks="yes,yes"
+  table_warn_overflow="overprint"
+?>
+<book>
+<bookinfo>
+<title>Specification of the Exim Mail Transfer Agent</title>
+<titleabbrev>The Exim MTA</titleabbrev>
+<date>
+28 Sep 2021
+</date>
+<author><firstname>Exim</firstname><surname>Maintainers</surname></author>
+<authorinitials>EM</authorinitials>
+<revhistory><revision>
+<revnumber>4.95</revnumber>
+<date>28 Sep 2021</date>
+  <authorinitials>EM</authorinitials>
+</revision></revhistory>
+<copyright><year>
+2021
+           </year><holder>The Exim Maintainers</holder></copyright>
+</bookinfo>
+<chapter id="CHID1">
+<title>Introduction</title>
+
+<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>de-tainting</primary>
+  <see><emphasis>tainting, de-tainting</emphasis></see>
+</indexterm>
+<indexterm role="concept">
+  <primary>detainting</primary>
+  <see><emphasis>tainting, de-tainting</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>
+</indexterm>
+
+<para>
+Exim is a mail transfer agent (MTA) for hosts that are running Unix or
+Unix-like operating systems. It was designed on the assumption that it would be
+run on hosts that are permanently connected to the Internet. However, it can be
+used on intermittently connected hosts with suitable configuration adjustments.
+</para>
+<para>
+Configuration files currently exist for the following operating systems: AIX,
+BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd,
+GNU/Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD,
+OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4,
+Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and UnixWare.
+Some of these operating systems are no longer current and cannot easily be
+tested, so the configuration files may no longer work in practice.
+</para>
+<para>
+There are also configuration files for compiling Exim in the Cygwin environment
+that can be installed on systems running Windows. However, this document does
+not contain any information about running Exim in the Cygwin environment.
+</para>
+<para>
+The terms and conditions for the use and distribution of Exim are contained in
+the file <filename>NOTICE</filename>. Exim is distributed under the terms of the GNU General
+Public Licence, a copy of which may be found in the file <filename>LICENCE</filename>.
+</para>
+<para>
+The use, supply, or promotion of Exim for the purpose of sending bulk,
+unsolicited electronic mail is incompatible with the basic aims of Exim,
+which revolve around the free provision of a service that enhances the quality
+of personal communications. The author of Exim regards indiscriminate
+mass-mailing as an antisocial, irresponsible abuse of the Internet.
+</para>
+<para>
+Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the
+experience of running and working on the Smail 3 code, I could never have
+contemplated starting to write a new MTA. Many of the ideas and user interfaces
+were originally taken from Smail 3, though the actual code of Exim is entirely
+new, and has developed far beyond the initial concept.
+</para>
+<para>
+Many people, both in Cambridge and around the world, have contributed to the
+development and the testing of Exim, and to porting it to various operating
+systems. I am grateful to them all. The distribution now contains a file called
+<filename>ACKNOWLEDGMENTS</filename>, in which I have started recording the names of
+contributors.
+</para>
+<section id="SECID1">
+<title>Exim documentation</title>
+<para revisionflag="changed">
+<indexterm role="concept">
+<primary>documentation</primary>
+</indexterm>
+This edition of the Exim specification applies to version 4.95 of Exim.
+Substantive changes from the 4.94 edition are marked in some
+renditions of this document; this paragraph is so marked if the rendition is
+capable of showing a change indicator.
+</para>
+<para>
+This document is very much a reference manual; it is not a tutorial. The reader
+is expected to have some familiarity with the SMTP mail transfer protocol and
+with general Unix system administration. Although there are some discussions
+and examples in places, the information is mostly organized in a way that makes
+it easy to look up, rather than in a natural order for sequential reading.
+Furthermore, this manual aims to cover every aspect of Exim in detail, including
+a number of rarely-used, special-purpose features that are unlikely to be of
+very wide interest.
+</para>
+<para>
+<indexterm role="concept">
+<primary>books about Exim</primary>
+</indexterm>
+An <quote>easier</quote> discussion of Exim which provides more in-depth explanatory,
+introductory, and tutorial material can be found in a book entitled <emphasis>The Exim
+SMTP Mail Server</emphasis> (second edition, 2007), published by UIT Cambridge
+(<emphasis role="bold"><ulink url="https://www.uit.co.uk/exim-book/">https://www.uit.co.uk/exim-book/</ulink></emphasis>).
+</para>
+<para>
+The book also contains a chapter that gives a general introduction to SMTP and
+Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date
+with the latest release of Exim. (Note that the earlier book about Exim,
+published by O&#x2019;Reilly, covers Exim 3, and many things have changed in Exim 4.)
+</para>
+<para>
+<indexterm role="concept">
+<primary>Debian</primary>
+<secondary>information sources</secondary>
+</indexterm>
+If you are using a Debian distribution of Exim, you will find information about
+Debian-specific features in the file
+<filename>/usr/share/doc/exim4-base/README.Debian</filename>.
+The command <command>man update-exim.conf</command> is another source of Debian-specific
+information.
+</para>
+<para>
+<indexterm role="concept">
+<primary><filename>doc/NewStuff</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>doc/ChangeLog</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>change log</primary>
+</indexterm>
+As Exim develops, there may be features in newer versions that have not
+yet made it into this document, which is updated only when the most significant
+digit of the fractional part of the version number changes. Specifications of
+new features that are not yet in this manual are placed in the file
+<filename>doc/NewStuff</filename> in the Exim distribution.
+</para>
+<para>
+Some features may be classified as <quote>experimental</quote>. These may change
+incompatibly while they are developing, or even be withdrawn. For this reason,
+they are not documented in this manual. Information about experimental features
+can be found in the file <filename>doc/experimental.txt</filename>.
+</para>
+<para>
+All changes to Exim (whether new features, bug fixes, or other kinds of
+change) are noted briefly in the file called <filename>doc/ChangeLog</filename>.
+</para>
+<para>
+<indexterm role="concept">
+<primary><filename>doc/spec.txt</filename></primary>
+</indexterm>
+This specification itself is available as an ASCII file in <filename>doc/spec.txt</filename> so
+that it can easily be searched with a text editor. Other files in the <filename>doc</filename>
+directory are:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="100pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry><filename>OptionLists.txt</filename></entry>
+<entry>list of all options in alphabetical order</entry>
+</row>
+<row>
+<entry><filename>dbm.discuss.txt</filename></entry>
+<entry>discussion about DBM libraries</entry>
+</row>
+<row>
+<entry><filename>exim.8</filename></entry>
+<entry>a man page of Exim&#x2019;s command line options</entry>
+</row>
+<row>
+<entry><filename>experimental.txt</filename></entry>
+<entry>documentation of experimental features</entry>
+</row>
+<row>
+<entry><filename>filter.txt</filename></entry>
+<entry>specification of the filter language</entry>
+</row>
+<row>
+<entry><filename>Exim3.upgrade</filename></entry>
+<entry>upgrade notes from release 2 to release 3</entry>
+</row>
+<row>
+<entry><filename>Exim4.upgrade</filename></entry>
+<entry>upgrade notes from release 3 to release 4</entry>
+</row>
+<row>
+<entry><filename>openssl.txt</filename></entry>
+<entry>installing a current OpenSSL release</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+The main specification and the specification of the filtering language are also
+available in other formats (HTML, PostScript, PDF, and Texinfo). Section
+<xref linkend="SECTavail"/> below tells you how to get hold of these.
+</para>
+</section>
+<section id="SECID2">
+<title>FTP site and websites</title>
+<para>
+<indexterm role="concept">
+<primary>website</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>FTP site</primary>
+</indexterm>
+The primary site for Exim source distributions is the <option>exim.org</option> FTP site,
+available over HTTPS, HTTP and FTP.  These services, and the <option>exim.org</option>
+website, are hosted at the University of Cambridge.
+</para>
+<para>
+<indexterm role="concept">
+<primary>wiki</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>FAQ</primary>
+</indexterm>
+As well as Exim distribution tar files, the Exim website contains a number of
+differently formatted versions of the documentation. A recent addition to the
+online information is the Exim wiki (<emphasis role="bold"><ulink url="https://wiki.exim.org">https://wiki.exim.org</ulink></emphasis>),
+which contains what used to be a separate FAQ, as well as various other
+examples, tips, and know-how that have been contributed by Exim users.
+The wiki site should always redirect to the correct place, which is currently
+provided by GitHub, and is open to editing by anyone with a GitHub account.
+</para>
+<para>
+<indexterm role="concept">
+<primary>Bugzilla</primary>
+</indexterm>
+An Exim Bugzilla exists at <emphasis role="bold"><ulink url="https://bugs.exim.org">https://bugs.exim.org</ulink></emphasis>. You can use
+this to report bugs, and also to add items to the wish list. Please search
+first to check that you are not duplicating a previous entry.
+Please do not ask for configuration help in the bug-tracker.
+</para>
+</section>
+<section id="SECID3">
+<title>Mailing lists</title>
+<para>
+<indexterm role="concept">
+<primary>mailing lists</primary>
+<secondary>for Exim users</secondary>
+</indexterm>
+The following Exim mailing lists exist:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="140pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry><emphasis>exim-announce@???</emphasis></entry>
+<entry>Moderated, low volume announcements list</entry>
+</row>
+<row>
+<entry><emphasis>exim-users@???</emphasis></entry>
+<entry>General discussion list</entry>
+</row>
+<row>
+<entry><emphasis>exim-dev@???</emphasis></entry>
+<entry>Discussion of bugs, enhancements, etc.</entry>
+</row>
+<row>
+<entry><emphasis>exim-cvs@???</emphasis></entry>
+<entry>Automated commit messages from the VCS</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+You can subscribe to these lists, change your existing subscriptions, and view
+or search the archives via the mailing lists link on the Exim home page.
+<indexterm role="concept">
+<primary>Debian</primary>
+<secondary>mailing list for</secondary>
+</indexterm>
+If you are using a Debian distribution of Exim, you may wish to subscribe to
+the Debian-specific mailing list <emphasis>pkg-exim4-users@???</emphasis>
+via this web page:
+</para>
+<literallayout>
+<emphasis role="bold"><ulink url="https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users">https://alioth-lists.debian.net/cgi-bin/mailman/listinfo/pkg-exim4-users</ulink></emphasis>
+</literallayout>
+<para>
+Please ask Debian-specific questions on that list and not on the general Exim
+lists.
+</para>
+</section>
+<section id="SECID5">
+<title>Bug reports</title>
+<para>
+<indexterm role="concept">
+<primary>bug reports</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>reporting bugs</primary>
+</indexterm>
+Reports of obvious bugs can be emailed to <emphasis>bugs@???</emphasis> or reported
+via the Bugzilla (<emphasis role="bold"><ulink url="https://bugs.exim.org">https://bugs.exim.org</ulink></emphasis>). However, if you are unsure
+whether some behaviour is a bug or not, the best thing to do is to post a
+message to the <emphasis>exim-dev</emphasis> mailing list and have it discussed.
+</para>
+</section>
+<section id="SECTavail">
+<title>Where to find the Exim distribution</title>
+<para>
+<indexterm role="concept">
+<primary>FTP site</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>HTTPS download site</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>distribution</primary>
+<secondary>FTP site</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>distribution</primary>
+<secondary>https site</secondary>
+</indexterm>
+The master distribution site for the Exim distribution is
+</para>
+<literallayout>
+<emphasis role="bold"><ulink url="https://downloads.exim.org/">https://downloads.exim.org/</ulink></emphasis>
+</literallayout>
+<para>
+The service is available over HTTPS, HTTP and FTP.
+We encourage people to migrate to HTTPS.
+</para>
+<para>
+The content served at <emphasis role="bold"><ulink url="https://downloads.exim.org/">https://downloads.exim.org/</ulink></emphasis> is identical to the
+content served at <emphasis role="bold"><ulink url="https://ftp.exim.org/pub/exim">https://ftp.exim.org/pub/exim</ulink></emphasis> and
+<emphasis role="bold"><ulink url="ftp://ftp.exim.org/pub/exim">ftp://ftp.exim.org/pub/exim</ulink></emphasis>.
+</para>
+<para>
+If accessing via a hostname containing <emphasis>ftp</emphasis>, then the file references that
+follow are relative to the <filename>exim</filename> directories at these sites.
+If accessing via the hostname <emphasis>downloads</emphasis> then the subdirectories described
+here are top-level directories.
+</para>
+<para>
+There are now quite a number of independent mirror sites around
+the world. Those that I know about are listed in the file called <filename>Mirrors</filename>.
+</para>
+<para>
+Within the top exim directory there are subdirectories called <filename>exim3</filename> (for
+previous Exim 3 distributions), <filename>exim4</filename> (for the latest Exim 4
+distributions), and <filename>Testing</filename> for testing versions. In the <filename>exim4</filename>
+subdirectory, the current release can always be found in files called
+</para>
+<literallayout>
+<filename>exim-n.nn.tar.xz</filename>
+<filename>exim-n.nn.tar.gz</filename>
+<filename>exim-n.nn.tar.bz2</filename>
+</literallayout>
+<para>
+where <emphasis>n.nn</emphasis> is the highest such version number in the directory. The three
+files contain identical data; the only difference is the type of compression.
+The <filename>.xz</filename> file is usually the smallest, while the <filename>.gz</filename> file is the
+most portable to old systems.
+</para>
+<para>
+<indexterm role="concept">
+<primary>distribution</primary>
+<secondary>signing details</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>distribution</primary>
+<secondary>public key</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>public key for signed distribution</primary>
+</indexterm>
+The distributions will be PGP signed by an individual key of the Release
+Coordinator.  This key will have a uid containing an email address in the
+<emphasis>exim.org</emphasis> domain and will have signatures from other people, including
+other Exim maintainers.  We expect that the key will be in the "strong set" of
+PGP keys.  There should be a trust path to that key from the Exim Maintainer&#x2019;s
+PGP keys, a version of which can be found in the release directory in the file
+<filename>Exim-Maintainers-Keyring.asc</filename>.  All keys used will be available in public keyserver pools,
+such as <emphasis>pool.sks-keyservers.net</emphasis>.
+</para>
+<para>
+At the time of the last update, releases were being made by Jeremy Harris and signed
+with key <emphasis>0xBCE58C8CE41F32DF</emphasis>.  Other recent keys used for signing are those
+of Heiko Schlittermann, <emphasis>0x26101B62F69376CE</emphasis>,
+and of Phil Pennock, <emphasis>0x4D1E900E14C1CC04</emphasis>.
+</para>
+<para>
+The signatures for the tar bundles are in:
+</para>
+<literallayout>
+<filename>exim-n.nn.tar.xz.asc</filename>
+<filename>exim-n.nn.tar.gz.asc</filename>
+<filename>exim-n.nn.tar.bz2.asc</filename>
+</literallayout>
+<para>
+For each released version, the log of changes is made available in a
+separate file in the directory <filename>ChangeLogs</filename> so that it is possible to
+find out what has changed without having to download the entire distribution.
+</para>
+<para>
+<indexterm role="concept">
+<primary>documentation</primary>
+<secondary>available formats</secondary>
+</indexterm>
+The main distribution contains ASCII versions of this specification and other
+documentation; other formats of the documents are available in separate files
+inside the <filename>exim4</filename> directory of the FTP site:
+</para>
+<literallayout>
+<filename>exim-html-n.nn.tar.gz</filename>
+<filename>exim-pdf-n.nn.tar.gz</filename>
+<filename>exim-postscript-n.nn.tar.gz</filename>
+<filename>exim-texinfo-n.nn.tar.gz</filename>
+</literallayout>
+<para>
+These tar files contain only the <filename>doc</filename> directory, not the complete
+distribution, and are also available in <filename>.bz2</filename> and <filename>.xz</filename> forms.
+</para>
+</section>
+<section id="SECID6">
+<title>Limitations</title>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>limitations of Exim</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>bang paths</primary>
+<secondary>not handled by Exim</secondary>
+</indexterm>
+Exim is designed for use as an Internet MTA, and therefore handles addresses in
+RFC 2822 domain format only. It cannot handle UUCP <quote>bang paths</quote>, though
+simple two-component bang paths can be converted by a straightforward rewriting
+configuration. This restriction does not prevent Exim from being interfaced to
+UUCP as a transport mechanism, provided that domain addresses are used.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>domainless addresses</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>address</primary>
+<secondary>without domain</secondary>
+</indexterm>
+Exim insists that every address it handles has a domain attached. For incoming
+local messages, domainless addresses are automatically qualified with a
+configured domain value. Configuration options specify from which remote
+systems unqualified addresses are acceptable. These are then qualified on
+arrival.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>transport</primary>
+<secondary>external</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>external transports</primary>
+</indexterm>
+The only external transport mechanisms that are currently implemented are SMTP
+and LMTP over a TCP/IP network (including support for IPv6). However, a pipe
+transport is available, and there are facilities for writing messages to files
+and pipes, optionally in <emphasis>batched SMTP</emphasis> format; these facilities can be used
+to send messages to other transport mechanisms such as UUCP, provided they can
+handle domain-style addresses. Batched SMTP input is also catered for.
+</para>
+</listitem>
+<listitem>
+<para>
+Exim is not designed for storing mail for dial-in hosts. When the volumes of
+such mail are large, it is better to get the messages <quote>delivered</quote> into files
+(that is, off Exim&#x2019;s queue) and subsequently passed on to the dial-in hosts by
+other means.
+</para>
+</listitem>
+<listitem>
+<para>
+Although Exim does have basic facilities for scanning incoming messages, these
+are not comprehensive enough to do full virus or spam scanning. Such operations
+are best carried out using additional specialized software packages. If you
+compile Exim with the content-scanning extension, straightforward interfaces to
+a number of common scanners are provided.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECID7">
+<title>Runtime configuration</title>
+<para>
+Exim&#x2019;s runtime configuration is held in a single text file that is divided
+into a number of sections. The entries in this file consist of keywords and
+values, in the style of Smail 3 configuration files. A default configuration
+file which is suitable for simple online installations is provided in the
+distribution, and is described in chapter <xref linkend="CHAPdefconfil"/> below.
+</para>
+</section>
+<section id="SECID8">
+<title>Calling interface</title>
+<para>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary>command line interface</secondary>
+</indexterm>
+Like many MTAs, Exim has adopted the Sendmail command line interface so that it
+can be a straight replacement for <filename>/usr/lib/sendmail</filename> or
+<filename>/usr/sbin/sendmail</filename> when sending mail, but you do not need to know anything
+about Sendmail in order to run Exim. For actions other than sending messages,
+Sendmail-compatible options also exist, but those that produce output (for
+example, <option>-bp</option>, which lists the messages in the queue) do so in Exim&#x2019;s own
+format. There are also some additional options that are compatible with Smail
+3, and some further options that are new to Exim. Chapter <xref linkend="CHAPcommandline"/>
+documents all Exim&#x2019;s command line options. This information is automatically
+made into the man page that forms part of the Exim distribution.
+</para>
+<para>
+Control of messages in the queue can be done via certain privileged command
+line options. There is also an optional monitor program called <emphasis>eximon</emphasis>,
+which displays current information in an X window, and which contains a menu
+interface to Exim&#x2019;s command line administration options.
+</para>
+</section>
+<section id="SECID9">
+<title>Terminology</title>
+<para>
+<indexterm role="concept">
+<primary>terminology definitions</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>body of message</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The <emphasis>body</emphasis> of a message is the actual data that the sender wants to transmit.
+It is the last part of a message and is separated from the <emphasis>header</emphasis> (see
+below) by a blank line.
+</para>
+<para>
+<indexterm role="concept">
+<primary>bounce message</primary>
+<secondary>definition of</secondary>
+</indexterm>
+When a message cannot be delivered, it is normally returned to the sender in a
+delivery failure message or a <quote>non-delivery report</quote> (NDR). The term
+<emphasis>bounce</emphasis> is commonly used for this action, and the error reports are often
+called <emphasis>bounce messages</emphasis>. This is a convenient shorthand for <quote>delivery
+failure error report</quote>. Such messages have an empty sender address in the
+message&#x2019;s <emphasis>envelope</emphasis> (see below) to ensure that they cannot themselves give
+rise to further bounce messages.
+</para>
+<para>
+The term <emphasis>default</emphasis> appears frequently in this manual. It is used to qualify a
+value which is used in the absence of any setting in the configuration. It may
+also qualify an action which is taken unless a configuration setting specifies
+otherwise.
+</para>
+<para>
+The term <emphasis>defer</emphasis> is used when the delivery of a message to a specific
+destination cannot immediately take place for some reason (a remote host may be
+down, or a user&#x2019;s local mailbox may be full). Such deliveries are <emphasis>deferred</emphasis>
+until a later time.
+</para>
+<para>
+The word <emphasis>domain</emphasis> is sometimes used to mean all but the first component of a
+host&#x2019;s name. It is <emphasis>not</emphasis> used in that sense here, where it normally refers to
+the part of an email address following the @ sign.
+</para>
+<para>
+<indexterm role="concept">
+<primary>envelope, definition of</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>definition of</secondary>
+</indexterm>
+A message in transit has an associated <emphasis>envelope</emphasis>, as well as a header and a
+body. The envelope contains a sender address (to which bounce messages should
+be delivered), and any number of recipient addresses. References to the
+sender or the recipients of a message usually mean the addresses in the
+envelope. An MTA uses these addresses for delivery, and for returning bounce
+messages, not the addresses that appear in the header lines.
+</para>
+<para>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>header, definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>header section</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The <emphasis>header</emphasis> of a message is the first part of a message&#x2019;s text, consisting
+of a number of lines, each of which has a name such as <emphasis>From:</emphasis>, <emphasis>To:</emphasis>,
+<emphasis>Subject:</emphasis>, etc. Long header lines can be split over several text lines by
+indenting the continuations. The header is separated from the body by a blank
+line.
+</para>
+<para>
+<indexterm role="concept">
+<primary>local part</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The term <emphasis>local part</emphasis>, which is taken from RFC 2822, is used to refer to the
+part of an email address that precedes the @ sign. The part that follows the
+@ sign is called the <emphasis>domain</emphasis> or <emphasis>mail domain</emphasis>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>local delivery</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>remote delivery, definition of</primary>
+</indexterm>
+The terms <emphasis>local delivery</emphasis> and <emphasis>remote delivery</emphasis> are used to distinguish
+delivery to a file or a pipe on the local host from delivery by SMTP over
+TCP/IP to another host. As far as Exim is concerned, all hosts other than the
+host it is running on are <emphasis>remote</emphasis>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>return path</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<emphasis>Return path</emphasis> is another name that is used for the sender address in a
+message&#x2019;s envelope.
+</para>
+<para>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The term <emphasis>queue</emphasis> is used to refer to the set of messages awaiting delivery
+because this term is in widespread use in the context of MTAs. However, in
+Exim&#x2019;s case, the reality is more like a pool than a queue, because there is
+normally no ordering of waiting messages.
+</para>
+<para>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The term <emphasis>queue runner</emphasis> is used to describe a process that scans the queue
+and attempts to deliver those messages whose retry times have come. This term
+is used by other MTAs and also relates to the command <option>runq</option>, but in Exim
+the waiting messages are normally processed in an unpredictable order.
+</para>
+<para>
+<indexterm role="concept">
+<primary>spool directory</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The term <emphasis>spool directory</emphasis> is used for a directory in which Exim keeps the
+messages in its queue &ndash; that is, those that it is in the process of
+delivering. This should not be confused with the directory in which local
+mailboxes are stored, which is called a <quote>spool directory</quote> by some people. In
+the Exim documentation, <quote>spool</quote> is always used in the first sense.
+</para>
+</section>
+</chapter>
+
+<chapter id="CHID2">
+<title>Incorporated code</title>
+<para>
+<indexterm role="concept">
+<primary>incorporated code</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>library</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>PCRE</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>OpenDMARC</primary>
+</indexterm>
+A number of pieces of external code are included in the Exim distribution.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Regular expressions are supported in the main Exim program and in the
+Exim monitor using the freely-distributable PCRE library, copyright
+&copy; University of Cambridge. The source to PCRE is no longer shipped with
+Exim, so you will need to use the version of PCRE shipped with your system,
+or obtain and install the full version of the library from
+<emphasis role="bold"><ulink url="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre">ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre</ulink></emphasis>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>cdb</primary>
+<secondary>acknowledgment</secondary>
+</indexterm>
+Support for the cdb (Constant DataBase) lookup method is provided by code
+contributed by Nigel Metheringham of (at the time he contributed it) Planet
+Online Ltd. The implementation is completely contained within the code of Exim.
+It does not link against an external cdb library. The code contains the
+following statements:
+</para>
+<blockquote>
+<para>
+Copyright &copy; 1998 Nigel Metheringham, Planet Online Ltd
+</para>
+<para>
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2 of the License, or (at your option) any later
+version.
+This code implements Dan Bernstein&#x2019;s Constant DataBase (cdb) spec. Information,
+the spec and sample code for cdb can be obtained from
+<emphasis role="bold"><ulink url="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</ulink></emphasis>. This implementation borrows
+some code from Dan Bernstein&#x2019;s implementation (which has no license
+restrictions applied to it).
+</para>
+</blockquote>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>SPA authentication</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Samba project</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Microsoft Secure Password Authentication</primary>
+</indexterm>
+Client support for Microsoft&#x2019;s <emphasis>Secure Password Authentication</emphasis> is provided
+by code contributed by Marc Prud&#x2019;hommeaux. Server support was contributed by
+Tom Kistner. This includes code taken from the Samba project, which is released
+under the Gnu GPL.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Cyrus</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>pwcheck</emphasis> daemon</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>pwauthd</emphasis> daemon</primary>
+</indexterm>
+Support for calling the Cyrus <emphasis>pwcheck</emphasis> and <emphasis>saslauthd</emphasis> daemons is provided
+by code taken from the Cyrus-SASL library and adapted by Alexander S.
+Sabourenkov. The permission notice appears below, in accordance with the
+conditions expressed therein.
+</para>
+<blockquote>
+<para>
+Copyright &copy; 2001 Carnegie Mellon University.  All rights reserved.
+</para>
+<para>
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+</para>
+</listitem>
+<listitem>
+<para>
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in
+the documentation and/or other materials provided with the
+distribution.
+</para>
+</listitem>
+<listitem>
+<para>
+The name <quote>Carnegie Mellon University</quote> must not be used to
+endorse or promote products derived from this software without
+prior written permission. For permission or any other legal
+details, please contact
+</para>
+<literallayout>
+              Office of Technology Transfer
+              Carnegie Mellon University
+              5000 Forbes Avenue
+              Pittsburgh, PA  15213-3890
+              (412) 268-4387, fax: (412) 268-7395
+              tech-transfer@???
+</literallayout>
+</listitem>
+<listitem>
+<para>
+Redistributions of any form whatsoever must retain the following
+acknowledgment:
+</para>
+<para>
+<quote>This product includes software developed by Computing Services
+at Carnegie Mellon University (<emphasis role="bold"><ulink url="https://www.cmu.edu/computing/">https://www.cmu.edu/computing/</ulink></emphasis>.</quote>
+</para>
+<para>
+CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO
+THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE
+FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
+AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING
+OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+</para>
+</listitem>
+</orderedlist>
+</blockquote>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Exim monitor</primary>
+<secondary>acknowledgment</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>X-windows</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Athena</primary>
+</indexterm>
+The Exim Monitor program, which is an X-Window application, includes
+modified versions of the Athena StripChart and TextPop widgets.
+This code is copyright by DEC and MIT, and their permission notice appears
+below, in accordance with the conditions expressed therein.
+</para>
+<blockquote>
+<para>
+Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
+and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
+</para>
+<para>
+All Rights Reserved
+</para>
+<para>
+Permission to use, copy, modify, and distribute this software and its
+documentation for any purpose and without fee is hereby granted,
+provided that the above copyright notice appear in all copies and that
+both that copyright notice and this permission notice appear in
+supporting documentation, and that the names of Digital or MIT not be
+used in advertising or publicity pertaining to distribution of the
+software without specific, written prior permission.
+</para>
+<para>
+DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
+ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
+DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
+ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
+SOFTWARE.
+</para>
+</blockquote>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>opendmarc</primary>
+<secondary>acknowledgment</secondary>
+</indexterm>
+The DMARC implementation uses the OpenDMARC library which is Copyrighted by
+The Trusted Domain Project. Portions of Exim source which use OpenDMARC
+derived code are indicated in the respective source files. The full OpenDMARC
+license is provided in the LICENSE.opendmarc file contained in the distributed
+source code.
+</para>
+</listitem>
+<listitem>
+<para>
+Many people have contributed code fragments, some large, some small, that were
+not covered by any specific license requirements. It is assumed that the
+contributors are happy to see their code incorporated into Exim under the GPL.
+</para>
+</listitem>
+</itemizedlist>
+</chapter>
+
+<chapter id="CHID11">
+<title>How Exim receives and delivers mail</title>
+<titleabbrev>Receiving and delivering mail</titleabbrev>
+<section id="SECID10">
+<title>Overall philosophy</title>
+<para>
+<indexterm role="concept">
+<primary>design philosophy</primary>
+</indexterm>
+Exim is designed to work efficiently on systems that are permanently connected
+to the Internet and are handling a general mix of mail. In such circumstances,
+most messages can be delivered immediately. Consequently, Exim does not
+maintain independent queues of messages for specific domains or hosts, though
+it does try to send several messages in a single SMTP connection after a host
+has been down, and it also maintains per-host retry information.
+</para>
+</section>
+<section id="SECID11">
+<title>Policy control</title>
+<para>
+<indexterm role="concept">
+<primary>policy control</primary>
+<secondary>overview</secondary>
+</indexterm>
+Policy controls are now an important feature of MTAs that are connected to the
+Internet. Perhaps their most important job is to stop MTAs from being abused as
+<quote>open relays</quote> by misguided individuals who send out vast amounts of
+unsolicited junk and want to disguise its source. Exim provides flexible
+facilities for specifying policy controls on incoming mail:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>access control lists (ACLs)</primary>
+<secondary>introduction</secondary>
+</indexterm>
+Exim 4 (unlike previous versions of Exim) implements policy controls on
+incoming mail by means of <emphasis>Access Control Lists</emphasis> (ACLs). Each list is a
+series of statements that may either grant or deny access. ACLs can be used at
+several places in the SMTP dialogue while receiving a message from a remote
+host. However, the most common places are after each RCPT command, and at the
+very end of the message. The sysadmin can specify conditions for accepting or
+rejecting individual recipients or the entire message, respectively, at these
+two points (see chapter <xref linkend="CHAPACL"/>). Denial of access results in an SMTP
+error code.
+</para>
+</listitem>
+<listitem>
+<para>
+An ACL is also available for locally generated, non-SMTP messages. In this
+case, the only available actions are to accept or deny the entire message.
+</para>
+</listitem>
+<listitem>
+<para>
+When Exim is compiled with the content-scanning extension, facilities are
+provided in the ACL mechanism for passing the message to external virus and/or
+spam scanning software. The result of such a scan is passed back to the ACL,
+which can then use it to decide what to do with the message.
+</para>
+</listitem>
+<listitem>
+<para>
+When a message has been received, either from a remote host or from the local
+host, but before the final acknowledgment has been sent, a locally supplied C
+function called <function>local_scan()</function> can be run to inspect the message and decide
+whether to accept it or not (see chapter <xref linkend="CHAPlocalscan"/>). If the message
+is accepted, the list of recipients can be modified by the function.
+</para>
+</listitem>
+<listitem>
+<para>
+Using the <function>local_scan()</function> mechanism is another way of calling external scanner
+software. The <option>SA-Exim</option> add-on package works this way. It does not require
+Exim to be compiled with the content-scanning extension.
+</para>
+</listitem>
+<listitem>
+<para>
+After a message has been accepted, a further checking mechanism is available in
+the form of the <emphasis>system filter</emphasis> (see chapter <xref linkend="CHAPsystemfilter"/>). This
+runs at the start of every delivery process.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECID12">
+<title>User filters</title>
+<para>
+<indexterm role="concept">
+<primary>filter</primary>
+<secondary>introduction</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+</indexterm>
+In a conventional Exim configuration, users are able to run private filters by
+setting up appropriate <filename>.forward</filename> files in their home directories. See
+chapter <xref linkend="CHAPredirect"/> (about the <command>redirect</command> router) for the
+configuration needed to support this, and the separate document entitled
+<emphasis>Exim&#x2019;s interfaces to mail filtering</emphasis> for user details. Two different kinds
+of filtering are available:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Sieve filters are written in the standard filtering language that is defined
+by RFC 3028.
+</para>
+</listitem>
+<listitem>
+<para>
+Exim filters are written in a syntax that is unique to Exim, but which is more
+powerful than Sieve, which it pre-dates.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+User filters are run as part of the routing process, described below.
+</para>
+</section>
+<section id="SECTmessiden">
+<title>Message identification</title>
+<para>
+<indexterm role="concept">
+<primary>message ids</primary>
+<secondary>details of format</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>of message id</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>id of message</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>base62</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>base36</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Darwin</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Cygwin</primary>
+</indexterm>
+Every message handled by Exim is given a <emphasis>message id</emphasis> which is sixteen
+characters long. It is divided into three parts, separated by hyphens, for
+example <literal>16VDhn-0001bo-D3</literal>. Each part is a sequence of letters and digits,
+normally encoding numbers in base 62. However, in the Darwin operating
+system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
+(avoiding the use of lower case letters) is used instead, because the message
+id is used to construct filenames, and the names of files in those systems are
+not always case-sensitive.
+</para>
+<para>
+<indexterm role="concept">
+<primary>pid (process id)</primary>
+<secondary>re-use of</secondary>
+</indexterm>
+The detail of the contents of the message id have changed as Exim has evolved.
+Earlier versions relied on the operating system not re-using a process id (pid)
+within one second. On modern operating systems, this assumption can no longer
+be made, so the algorithm had to be changed. To retain backward compatibility,
+the format of the message id was retained, which is why the following rules are
+somewhat eccentric:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The first six characters of the message id are the time at which the message
+started to be received, to a granularity of one second. That is, this field
+contains the number of seconds since the start of the epoch (the normal Unix
+way of representing the date and time of day).
+</para>
+</listitem>
+<listitem>
+<para>
+After the first hyphen, the next six characters are the id of the process that
+received the message.
+</para>
+</listitem>
+<listitem>
+<para>
+There are two different possibilities for the final two characters:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>localhost_number</option></primary>
+</indexterm>
+If <option>localhost_number</option> is not set, this value is the fractional part of the
+time of reception, normally in units of 1/2000 of a second, but for systems
+that must use base 36 instead of base 62 (because of case-insensitive file
+systems), the units are 1/1000 of a second.
+</para>
+</listitem>
+<listitem>
+<para>
+If <option>localhost_number</option> is set, it is multiplied by 200 (100) and added to
+the fractional part of the time, which in this case is in units of 1/200
+(1/100) of a second.
+</para>
+</listitem>
+</orderedlist>
+</listitem>
+</itemizedlist>
+<para>
+After a message has been received, Exim waits for the clock to tick at the
+appropriate resolution before proceeding, so that if another message is
+received by the same process, or by another process with the same (re-used)
+pid, it is guaranteed that the time will be different. In most cases, the clock
+will already have ticked while the message was being received.
+</para>
+</section>
+<section id="SECID13">
+<title>Receiving mail</title>
+<para>
+<indexterm role="concept">
+<primary>receiving mail</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>reception</secondary>
+</indexterm>
+The only way Exim can receive mail from another host is using SMTP over
+TCP/IP, in which case the sender and recipient addresses are transferred using
+SMTP commands. However, from a locally running process (such as a user&#x2019;s MUA),
+there are several possibilities:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the process runs Exim with the <option>-bm</option> option, the message is read
+non-interactively (usually via a pipe), with the recipients taken from the
+command line, or from the body of the message if <option>-t</option> is also used.
+</para>
+</listitem>
+<listitem>
+<para>
+If the process runs Exim with the <option>-bS</option> option, the message is also read
+non-interactively, but in this case the recipients are listed at the start of
+the message in a series of SMTP RCPT commands, terminated by a DATA
+command. This is called <quote>batch SMTP</quote> format,
+but it isn&#x2019;t really SMTP. The SMTP commands are just another way of passing
+envelope addresses in a non-interactive submission.
+</para>
+</listitem>
+<listitem>
+<para>
+If the process runs Exim with the <option>-bs</option> option, the message is read
+interactively, using the SMTP protocol. A two-way pipe is normally used for
+passing data between the local process and the Exim process.
+This is <quote>real</quote> SMTP and is handled in the same way as SMTP over TCP/IP. For
+example, the ACLs for SMTP commands are used for this form of submission.
+</para>
+</listitem>
+<listitem>
+<para>
+A local process may also make a TCP/IP call to the host&#x2019;s loopback address
+(127.0.0.1) or any other of its IP addresses. When receiving messages, Exim
+does not treat the loopback address specially. It treats all such connections
+in the same way as connections from other hosts.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<indexterm role="concept">
+<primary>message sender, constructed by Exim</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>constructed by Exim</secondary>
+</indexterm>
+In the three cases that do not involve TCP/IP, the sender address is
+constructed from the login name of the user that called Exim and a default
+qualification domain (which can be set by the <option>qualify_domain</option> configuration
+option). For local or batch SMTP, a sender address that is passed using the
+SMTP MAIL command is ignored. However, the system administrator may allow
+certain users (<quote>trusted users</quote>) to specify a different sender addresses
+unconditionally, or all users to specify certain forms of different sender
+address. The <option>-f</option> option or the SMTP MAIL command is used to specify these
+different addresses. See section <xref linkend="SECTtrustedadmin"/> for details of trusted
+users, and the <option>untrusted_set_sender</option> option for a way of allowing untrusted
+users to change sender addresses.
+</para>
+<para>
+Messages received by either of the non-interactive mechanisms are subject to
+checking by the non-SMTP ACL if one is defined. Messages received using SMTP
+(either over TCP/IP or interacting with a local process) can be checked by a
+number of ACLs that operate at different times during the SMTP session. Either
+individual recipients or the entire message can be rejected if local policy
+requirements are not met. The <function>local_scan()</function> function (see chapter
+<xref linkend="CHAPlocalscan"/>) is run for all incoming messages.
+</para>
+<para>
+Exim can be configured not to start a delivery process when a message is
+received; this can be unconditional, or depend on the number of incoming SMTP
+connections or the system load. In these situations, new messages wait on the
+queue until a queue runner process picks them up. However, in standard
+configurations under normal conditions, delivery is started as soon as a
+message is received.
+</para>
+</section>
+<section id="SECID14">
+<title>Handling an incoming message</title>
+<para>
+<indexterm role="concept">
+<primary>spool directory</primary>
+<secondary>files that hold a message</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>how a message is held</secondary>
+</indexterm>
+When Exim accepts a message, it writes two files in its spool directory. The
+first contains the envelope information, the current status of the message, and
+the header lines, and the second contains the body of the message. The names of
+the two spool files consist of the message id, followed by <literal>-H</literal> for the
+file containing the envelope and header, and <literal>-D</literal> for the data file.
+</para>
+<para>
+<indexterm role="concept">
+<primary>spool directory</primary>
+<secondary><filename>input</filename> sub-directory</secondary>
+</indexterm>
+By default, all these message files are held in a single directory called
+<filename>input</filename> inside the general Exim spool directory. Some operating systems do
+not perform very well if the number of files in a directory gets large; to
+improve performance in such cases, the <option>split_spool_directory</option> option can be
+used. This causes Exim to split up the input files into 62 sub-directories
+whose names are single letters or digits. When this is done, the queue is
+processed one sub-directory at a time instead of all at once, which can improve
+overall performance even when there are not enough files in each directory to
+affect file system performance.
+</para>
+<para>
+The envelope information consists of the address of the message&#x2019;s sender and
+the addresses of the recipients. This information is entirely separate from
+any addresses contained in the header lines. The status of the message includes
+a list of recipients who have already received the message. The format of the
+first spool file is described in chapter <xref linkend="CHAPspool"/>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>rewriting</primary>
+<secondary>addresses</secondary>
+</indexterm>
+Address rewriting that is specified in the rewrite section of the configuration
+(see chapter <xref linkend="CHAPrewrite"/>) is done once and for all on incoming addresses,
+both in the header lines and the envelope, at the time the message is accepted.
+If during the course of delivery additional addresses are generated (for
+example, via aliasing), these new addresses are rewritten as soon as they are
+generated. At the time a message is actually delivered (transported) further
+rewriting can take place; because this is a transport option, it can be
+different for different forms of delivery. It is also possible to specify the
+addition or removal of certain header lines at the time the message is
+delivered (see chapters <xref linkend="CHAProutergeneric"/> and
+<xref linkend="CHAPtransportgeneric"/>).
+</para>
+</section>
+<section id="SECID15">
+<title>Life of a message</title>
+<para>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>life of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>frozen</secondary>
+</indexterm>
+A message remains in the spool directory until it is completely delivered to
+its recipients or to an error address, or until it is deleted by an
+administrator or by the user who originally created it. In cases when delivery
+cannot proceed &ndash; for example when a message can neither be delivered to its
+recipients nor returned to its sender, the message is marked <quote>frozen</quote> on the
+spool, and no more deliveries are attempted.
+</para>
+<para>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>thawing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>thawing frozen</secondary>
+</indexterm>
+An administrator can <quote>thaw</quote> such messages when the problem has been
+corrected, and can also freeze individual messages by hand if necessary. In
+addition, an administrator can force a delivery error, causing a bounce message
+to be sent.
+</para>
+<para>
+<indexterm role="option">
+<primary><option>timeout_frozen_after</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>ignore_bounce_errors_after</option></primary>
+</indexterm>
+There are options called <option>ignore_bounce_errors_after</option> and
+<option>timeout_frozen_after</option>, which discard frozen messages after a certain time.
+The first applies only to frozen bounces, the second to all frozen messages.
+</para>
+<para>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>log file for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>log</primary>
+<secondary>file for each message</secondary>
+</indexterm>
+While Exim is working on a message, it writes information about each delivery
+attempt to its main log file. This includes successful, unsuccessful, and
+delayed deliveries for each recipient (see chapter <xref linkend="CHAPlog"/>). The log
+lines are also written to a separate <emphasis>message log</emphasis> file for each message.
+These logs are solely for the benefit of the administrator and are normally
+deleted along with the spool files when processing of a message is complete.
+The use of individual message logs can be disabled by setting
+<option>no_message_logs</option>; this might give an improvement in performance on very busy
+systems.
+</para>
+<para>
+<indexterm role="concept">
+<primary>journal file</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>journal</secondary>
+</indexterm>
+All the information Exim itself needs to set up a delivery is kept in the first
+spool file, along with the header lines. When a successful delivery occurs, the
+address is immediately written at the end of a journal file, whose name is the
+message id followed by <literal>-J</literal>. At the end of a delivery run, if there are some
+addresses left to be tried again later, the first spool file (the <literal>-H</literal> file)
+is updated to indicate which these are, and the journal file is then deleted.
+Updating the spool file is done by writing a new file and renaming it, to
+minimize the possibility of data loss.
+</para>
+<para>
+Should the system or Exim crash after a successful delivery but before
+the spool file has been updated, the journal is left lying around. The next
+time Exim attempts to deliver the message, it reads the journal file and
+updates the spool file before proceeding. This minimizes the chances of double
+deliveries caused by crashes.
+</para>
+</section>
+<section id="SECTprocaddress">
+<title>Processing an address for delivery</title>
+<para>
+<indexterm role="concept">
+<primary>drivers</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>router</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>transport</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The main delivery processing elements of Exim are called <emphasis>routers</emphasis> and
+<emphasis>transports</emphasis>, and collectively these are known as <emphasis>drivers</emphasis>. Code for a
+number of them is provided in the source distribution, and compile-time options
+specify which ones are included in the binary. Runtime options specify which
+ones are actually used for delivering messages.
+</para>
+<para>
+<indexterm role="concept">
+<primary>drivers</primary>
+<secondary>instance definition</secondary>
+</indexterm>
+Each driver that is specified in the runtime configuration is an <emphasis>instance</emphasis>
+of that particular driver type. Multiple instances are allowed; for example,
+you can set up several different <command>smtp</command> transports, each with different
+option values that might specify different ports or different timeouts. Each
+instance has its own identifying name. In what follows we will normally use the
+instance name when discussing one particular instance (that is, one specific
+configuration of the driver), and the generic driver name when discussing
+the driver&#x2019;s features in general.
+</para>
+<para>
+A <emphasis>router</emphasis> is a driver that operates on an address, either determining how
+its delivery should happen, by assigning it to a specific transport, or
+converting the address into one or more new addresses (for example, via an
+alias file). A router may also explicitly choose to fail an address, causing it
+to be bounced.
+</para>
+<para>
+A <emphasis>transport</emphasis> is a driver that transmits a copy of the message from Exim&#x2019;s
+spool to some destination. There are two kinds of transport: for a <emphasis>local</emphasis>
+transport, the destination is a file or a pipe on the local host, whereas for a
+<emphasis>remote</emphasis> transport the destination is some other host. A message is passed
+to a specific transport as a result of successful routing. If a message has
+several recipients, it may be passed to a number of different transports.
+</para>
+<para>
+<indexterm role="concept">
+<primary>preconditions</primary>
+<secondary>definition of</secondary>
+</indexterm>
+An address is processed by passing it to each configured router instance in
+turn, subject to certain preconditions, until a router accepts the address or
+specifies that it should be bounced. We will describe this process in more
+detail shortly. First, as a simple example, we consider how each recipient
+address in a message is processed in a small configuration of three routers.
+</para>
+<para>
+To make this a more concrete example, it is described in terms of some actual
+routers, but remember, this is only an example. You can configure Exim&#x2019;s
+routers in many different ways, and there may be any number of routers in a
+configuration.
+</para>
+<para>
+The first router that is specified in a configuration is often one that handles
+addresses in domains that are not recognized specifically by the local host.
+Typically these are addresses for arbitrary domains on the Internet. A precondition
+is set up which looks for the special domains known to the host (for example,
+its own domain name), and the router is run for addresses that do <emphasis>not</emphasis>
+match. Typically, this is a router that looks up domains in the DNS in order to
+find the hosts to which this address routes. If it succeeds, the address is
+assigned to a suitable SMTP transport; if it does not succeed, the router is
+configured to fail the address.
+</para>
+<para>
+The second router is reached only when the domain is recognized as one that
+<quote>belongs</quote> to the local host. This router does redirection &ndash; also known as
+aliasing and forwarding. When it generates one or more new addresses from the
+original, each of them is routed independently from the start. Otherwise, the
+router may cause an address to fail, or it may simply decline to handle the
+address, in which case the address is passed to the next router.
+</para>
+<para>
+The final router in many configurations is one that checks to see if the
+address belongs to a local mailbox. The precondition may involve a check to
+see if the local part is the name of a login account, or it may look up the
+local part in a file or a database. If its preconditions are not met, or if
+the router declines, we have reached the end of the routers. When this happens,
+the address is bounced.
+</para>
+</section>
+<section id="SECID16">
+<title>Processing an address for verification</title>
+<para>
+<indexterm role="concept">
+<primary>router</primary>
+<secondary>for verification</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>verifying address</primary>
+<secondary>overview</secondary>
+</indexterm>
+As well as being used to decide how to deliver to an address, Exim&#x2019;s routers
+are also used for <emphasis>address verification</emphasis>. Verification can be requested as
+one of the checks to be performed in an ACL for incoming messages, on both
+sender and recipient addresses, and it can be tested using the <option>-bv</option> and
+<option>-bvs</option> command line options.
+</para>
+<para>
+When an address is being verified, the routers are run in <quote>verify mode</quote>. This
+does not affect the way the routers work, but it is a state that can be
+detected. By this means, a router can be skipped or made to behave differently
+when verifying. A common example is a configuration in which the first router
+sends all messages to a message-scanning program unless they have been
+previously scanned. Thus, the first router accepts all addresses without any
+checking, making it useless for verifying. Normally, the <option>no_verify</option> option
+would be set for such a router, causing it to be skipped in verify mode.
+</para>
+</section>
+<section id="SECTrunindrou">
+<title>Running an individual router</title>
+<para>
+<indexterm role="concept">
+<primary>router</primary>
+<secondary>running details</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>preconditions</primary>
+<secondary>checking</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>router</primary>
+<secondary>result of running</secondary>
+</indexterm>
+As explained in the example above, a number of preconditions are checked before
+running a router. If any are not met, the router is skipped, and the address is
+passed to the next router. When all the preconditions on a router <emphasis>are</emphasis> met,
+the router is run. What happens next depends on the outcome, which is one of
+the following:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<emphasis>accept</emphasis>: The router accepts the address, and either assigns it to a
+transport or generates one or more <quote>child</quote> addresses. Processing the
+original address ceases
+<indexterm role="option">
+<primary><option>unseen</option></primary>
+</indexterm>
+unless the <option>unseen</option> option is set on the router. This option
+can be used to set up multiple deliveries with different routing (for example,
+for keeping archive copies of messages). When <option>unseen</option> is set, the address is
+passed to the next router. Normally, however, an <emphasis>accept</emphasis> return marks the
+end of routing.
+</para>
+<para>
+Any child addresses generated by the router are processed independently,
+starting with the first router by default. It is possible to change this by
+setting the <option>redirect_router</option> option to specify which router to start at for
+child addresses. Unlike <option>pass_router</option> (see below) the router specified by
+<option>redirect_router</option> may be anywhere in the router configuration.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>pass</emphasis>: The router recognizes the address, but cannot handle it itself. It
+requests that the address be passed to another router. By default, the address
+is passed to the next router, but this can be changed by setting the
+<option>pass_router</option> option. However, (unlike <option>redirect_router</option>) the named router
+must be below the current router (to avoid loops).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>decline</emphasis>: The router declines to accept the address because it does not
+recognize it at all. By default, the address is passed to the next router, but
+this can be prevented by setting the <option>no_more</option> option. When <option>no_more</option> is
+set, all the remaining routers are skipped. In effect, <option>no_more</option> converts
+<emphasis>decline</emphasis> into <emphasis>fail</emphasis>.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>fail</emphasis>: The router determines that the address should fail, and queues it for
+the generation of a bounce message. There is no further processing of the
+original address unless <option>unseen</option> is set on the router.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>defer</emphasis>: The router cannot handle the address at the present time. (A
+database may be offline, or a DNS lookup may have timed out.) No further
+processing of the address happens in this delivery attempt. It is tried again
+next time the message is considered for delivery.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>error</emphasis>: There is some error in the router (for example, a syntax error in
+its configuration). The action is as for defer.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+If an address reaches the end of the routers without having been accepted by
+any of them, it is bounced as unrouteable. The default error message in this
+situation is <quote>unrouteable address</quote>, but you can set your own message by
+making use of the <option>cannot_route_message</option> option. This can be set for any
+router; the value from the last router that <quote>saw</quote> the address is used.
+</para>
+<para>
+Sometimes while routing you want to fail a delivery when some conditions are
+met but others are not, instead of passing the address on for further routing.
+You can do this by having a second router that explicitly fails the delivery
+when the relevant conditions are met. The <command>redirect</command> router has a <quote>fail</quote>
+facility for this purpose.
+</para>
+</section>
+<section id="SECID17">
+<title>Duplicate addresses</title>
+<para>
+<indexterm role="concept">
+<primary>case of local parts</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>address duplicate, discarding</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>duplicate addresses</primary>
+</indexterm>
+Once routing is complete, Exim scans the addresses that are assigned to local
+and remote transports and discards any duplicates that it finds. During this
+check, local parts are treated case-sensitively. This happens only when
+actually delivering a message; when testing routers with <option>-bt</option>, all the
+routed addresses are shown.
+</para>
+</section>
+<section id="SECTrouprecon">
+<title>Router preconditions</title>
+<para>
+<indexterm role="concept">
+<primary>router</primary>
+<secondary>preconditions, order of processing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>preconditions</primary>
+<secondary>order of processing</secondary>
+</indexterm>
+The preconditions that are tested for each router are listed below, in the
+order in which they are tested. The individual configuration options are
+described in more detail in chapter <xref linkend="CHAProutergeneric"/>.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>affix</primary>
+<secondary>router precondition</secondary>
+</indexterm>
+The <option>local_part_prefix</option> and <option>local_part_suffix</option> options can specify that
+the local parts handled by the router may or must have certain prefixes and/or
+suffixes. If a mandatory affix (prefix or suffix) is not present, the router is
+skipped. These conditions are tested first. When an affix is present, it is
+removed from the local part before further processing, including the evaluation
+of any other conditions.
+</para>
+</listitem>
+<listitem>
+<para>
+Routers can be designated for use only when not verifying an address, that is,
+only when routing it for delivery (or testing its delivery routing). If the
+<option>verify</option> option is set false, the router is skipped when Exim is verifying an
+address.
+Setting the <option>verify</option> option actually sets two options, <option>verify_sender</option> and
+<option>verify_recipient</option>, which independently control the use of the router for
+sender and recipient verification. You can set these options directly if
+you want a router to be used for only one type of verification.
+Note that cutthrough delivery is classed as a recipient verification for this purpose.
+</para>
+</listitem>
+<listitem>
+<para>
+If the <option>address_test</option> option is set false, the router is skipped when Exim is
+run with the <option>-bt</option> option to test an address routing. This can be helpful
+when the first router sends all new messages to a scanner of some sort; it
+makes it possible to use <option>-bt</option> to test subsequent delivery routing without
+having to simulate the effect of the scanner.
+</para>
+</listitem>
+<listitem>
+<para>
+Routers can be designated for use only when verifying an address, as
+opposed to routing it for delivery. The <option>verify_only</option> option controls this.
+Again, cutthrough delivery counts as a verification.
+</para>
+</listitem>
+<listitem>
+<para>
+Individual routers can be explicitly skipped when running the routers to
+check an address given in the SMTP EXPN command (see the <option>expn</option> option).
+</para>
+</listitem>
+<listitem>
+<para>
+If the <option>domains</option> option is set, the domain of the address must be in the set
+of domains that it defines.
+</para>
+<para revisionflag="changed">
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+A match verifies the variable <varname>$domain</varname> (which carries tainted data)
+and assigns an untainted value to the <varname>$domain_data</varname> variable.
+Such an untainted value is often needed in the transport.
+For specifics of the matching operation and the resulting untainted value,
+refer to section <xref linkend="SECTdomainlist"/>.
+</para>
+<para revisionflag="changed">
+When an untainted value is wanted, use this option
+rather than the generic <option>condition</option> option.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$local_part_prefix</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$local_part_prefix_v</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$local_part</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$local_part_suffix</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$local_part_suffix_v</varname></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>affix</primary>
+<secondary>router precondition</secondary>
+</indexterm>
+If the <option>local_parts</option> option is set, the local part of the address must be in
+the set of local parts that it defines.
+</para>
+<para revisionflag="changed">
+A match verifies the variable <varname>$local_part</varname> (which carries tainted data)
+and assigns an untainted value to the <varname>$local_part_data</varname> variable.
+Such an untainted value is often needed in the transport.
+For specifics of the matching operation and the resulting untainted value,
+refer to section <xref linkend="SECTlocparlis"/>.
+</para>
+<para revisionflag="changed">
+When an untainted value is wanted, use this option
+rather than the generic <option>condition</option> option.
+</para>
+<para>
+If <option>local_part_prefix</option> or
+<option>local_part_suffix</option> is in use, the prefix or suffix is removed from the local
+part before this check. If you want to do precondition tests on local parts
+that include affixes, you can do so by using a <option>condition</option> option (see below)
+that uses the variables <varname>$local_part</varname>, <varname>$local_part_prefix</varname>,
+<varname>$local_part_prefix_v</varname>, <varname>$local_part_suffix</varname>
+and <varname>$local_part_suffix_v</varname> as necessary.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$local_user_uid</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$local_user_gid</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$home</varname></primary>
+</indexterm>
+If the <option>check_local_user</option> option is set, the local part must be the name of
+an account on the local host. If this check succeeds, the uid and gid of the
+local user are placed in <varname>$local_user_uid</varname> and <varname>$local_user_gid</varname> and the
+user&#x2019;s home directory is placed in <varname>$home</varname>; these values can be used in the
+remaining preconditions.
+</para>
+</listitem>
+<listitem>
+<para>
+If the <option>router_home_directory</option> option is set, it is expanded at this point,
+because it overrides the value of <varname>$home</varname>. If this expansion were left till
+later, the value of <varname>$home</varname> as set by <option>check_local_user</option> would be used in
+subsequent tests. Having two different values of <varname>$home</varname> in the same router
+could lead to confusion.
+</para>
+</listitem>
+<listitem>
+<para>
+If the <option>senders</option> option is set, the envelope sender address must be in the
+set of addresses that it defines.
+</para>
+</listitem>
+<listitem>
+<para>
+If the <option>require_files</option> option is set, the existence or non-existence of
+specified files is tested.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>customizing</primary>
+<secondary>precondition</secondary>
+</indexterm>
+If the <option>condition</option> option is set, it is evaluated and tested. This option
+uses an expanded string to allow you to set up your own custom preconditions.
+Expanded strings are described in chapter <xref linkend="CHAPexpand"/>.
+</para>
+<para revisionflag="changed">
+Note that while using
+this option for address matching technically works,
+it does not set any de-tainted values.
+Such values are often needed, either for router-specific options or
+for transport options.
+Using the <option>domains</option> and <option>local_parts</option> options is usually the most
+convenient way to obtain them.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Note that <option>require_files</option> comes near the end of the list, so you cannot use
+it to check for the existence of a file in which to lookup up a domain, local
+part, or sender. However, as these options are all expanded, you can use the
+<option>exists</option> expansion condition to make such tests within each condition. The
+<option>require_files</option> option is intended for checking files that the router may be
+going to use internally, or which are needed by a specific transport (for
+example, <filename>.procmailrc</filename>).
+</para>
+</section>
+<section id="SECID18">
+<title>Delivery in detail</title>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>in detail</secondary>
+</indexterm>
+When a message is to be delivered, the sequence of events is as follows:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+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
+fail. The format of the system filter file is the same as for Exim user filter
+files, described in the separate document entitled <emphasis>Exim&#x2019;s interfaces to mail
+filtering</emphasis>.
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+<secondary>not available for system filter</secondary>
+</indexterm>
+(<emphasis role="bold">Note</emphasis>: Sieve cannot be used for system filter files.)
+</para>
+<para>
+Some additional features are available in system filters &ndash; see chapter
+<xref linkend="CHAPsystemfilter"/> for details. Note that a message is passed to the system
+filter only once per delivery attempt, however many recipients it has. However,
+if there are several delivery attempts because one or more addresses could not
+be immediately delivered, the system filter is run each time. The filter
+condition <option>first_delivery</option> can be used to detect the first run of the system
+filter.
+</para>
+</listitem>
+<listitem>
+<para>
+Each recipient address is offered to each configured router, in turn, subject to
+its preconditions, until one is able to handle it. If no router can handle the
+address, that is, if they all decline, the address is failed. Because routers
+can be targeted at particular domains, several locally handled domains can be
+processed entirely independently of each other.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>routing</primary>
+<secondary>loops in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>loop</primary>
+<secondary>while routing</secondary>
+</indexterm>
+A router that accepts an address may assign it to a local or a remote
+transport. However, the transport is not run at this time. Instead, the address
+is placed on a list for the particular transport, which will be run later.
+Alternatively, the router may generate one or more new addresses (typically
+from alias, forward, or filter files). New addresses are fed back into this
+process from the top, but in order to avoid loops, a router ignores any address
+which has an identically-named ancestor that was processed by itself.
+</para>
+</listitem>
+<listitem>
+<para>
+When all the routing has been done, addresses that have been successfully
+handled are passed to their assigned transports. When local transports are
+doing real local deliveries, they handle only one address at a time, but if a
+local transport is being used as a pseudo-remote transport (for example, to
+collect batched SMTP messages for transmission by some other means) multiple
+addresses can be handled. Remote transports can always handle more than one
+address at a time, but can be configured not to do so, or to restrict multiple
+addresses to the same domain.
+</para>
+</listitem>
+<listitem>
+<para>
+Each local delivery to a file or a pipe runs in a separate process under a
+non-privileged uid, and these deliveries are run one at a time. Remote
+deliveries also run in separate processes, normally under a uid that is private
+to Exim (<quote>the Exim user</quote>), but in this case, several remote deliveries can be
+run in parallel. The maximum number of simultaneous remote deliveries for any
+one message is set by the <option>remote_max_parallel</option> option.
+The order in which deliveries are done is not defined, except that all local
+deliveries happen before any remote deliveries.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>queue runner</primary>
+</indexterm>
+When it encounters a local delivery during a queue run, Exim checks its retry
+database to see if there has been a previous temporary delivery failure for the
+address before running the local transport. If there was a previous failure,
+Exim does not attempt a new delivery until the retry time for the address is
+reached. However, this happens only for delivery attempts that are part of a
+queue run. Local deliveries are always attempted when delivery immediately
+follows message reception, even if retry times are set for them. This makes for
+better behaviour if one particular message is causing problems (for example,
+causing quota overflow, or provoking an error in a filter file).
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>retry in remote transports</secondary>
+</indexterm>
+Remote transports do their own retry handling, since an address may be
+deliverable to one of a number of hosts, each of which may have a different
+retry time. If there have been previous temporary failures and no host has
+reached its retry time, no delivery is attempted, whether in a queue run or
+not. See chapter <xref linkend="CHAPretry"/> for details of retry strategies.
+</para>
+</listitem>
+<listitem>
+<para>
+If there were any permanent errors, a bounce message is returned to an
+appropriate address (the sender in the common case), with details of the error
+for each failing address. Exim can be configured to send copies of bounce
+messages to other addresses.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>deferral</secondary>
+</indexterm>
+If one or more addresses suffered a temporary failure, the message is left on
+the queue, to be tried again later. Delivery of these addresses is said to be
+<emphasis>deferred</emphasis>.
+</para>
+</listitem>
+<listitem>
+<para>
+When all the recipient addresses have either been delivered or bounced,
+handling of the message is complete. The spool files and message log are
+deleted, though the message log can optionally be preserved if required.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECID19">
+<title>Retry mechanism</title>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>retry mechanism</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>retry</primary>
+<secondary>description of mechanism</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+</indexterm>
+Exim&#x2019;s mechanism for retrying messages that fail to get delivered at the first
+attempt is the queue runner process. You must either run an Exim daemon that
+uses the <option>-q</option> option with a time interval to start queue runners at regular
+intervals or use some other means (such as <emphasis>cron</emphasis>) to start them. If you do
+not arrange for queue runners to be run, messages that fail temporarily at the
+first attempt will remain in your queue forever. A queue runner process works
+its way through the queue, one message at a time, trying each delivery that has
+passed its retry time.
+You can run several queue runners at once.
+</para>
+<para>
+Exim uses a set of configured rules to determine when next to retry the failing
+address (see chapter <xref linkend="CHAPretry"/>). These rules also specify when Exim
+should give up trying to deliver to the address, at which point it generates a
+bounce message. If no retry rules are set for a particular host, address, and
+error combination, no retries are attempted, and temporary errors are treated
+as permanent.
+</para>
+</section>
+<section id="SECID20">
+<title>Temporary delivery failure</title>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>temporary failure</secondary>
+</indexterm>
+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
+connection to it, is down) is one of the most common. Temporary failures may be
+detected during routing as well as during the transport stage of delivery.
+Local deliveries may be delayed if NFS files are unavailable, or if a mailbox
+is on a file system where the user is over quota. Exim can be configured to
+impose its own quotas on local mailboxes; where system quotas are set they will
+also apply.
+</para>
+<para>
+If a host is unreachable for a period of time, a number of messages may be
+waiting for it by the time it recovers, and sending them in a single SMTP
+connection is clearly beneficial. Whenever a delivery to a remote host is
+deferred,
+<indexterm role="concept">
+<primary>hints database</primary>
+<secondary>deferred deliveries</secondary>
+</indexterm>
+Exim makes a note in its hints database, and whenever a successful
+SMTP delivery has happened, it looks to see if any other messages are waiting
+for the same host. If any are found, they are sent over the same SMTP
+connection, subject to a configuration limit as to the maximum number in any
+one connection.
+</para>
+</section>
+<section id="SECID21">
+<title>Permanent delivery failure</title>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>permanent failure</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>bounce message</primary>
+<secondary>when generated</secondary>
+</indexterm>
+When a message cannot be delivered to some or all of its intended recipients, a
+bounce message is generated. Temporary delivery failures turn into permanent
+errors when their timeout expires. All the addresses that fail in a given
+delivery attempt are listed in a single message. If the original message has
+many recipients, it is possible for some addresses to fail in one delivery
+attempt and others to fail subsequently, giving rise to more than one bounce
+message. The wording of bounce messages can be customized by the administrator.
+See chapter <xref linkend="CHAPemsgcust"/> for details.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>X-Failed-Recipients:</emphasis> header line</primary>
+</indexterm>
+Bounce messages contain an <emphasis>X-Failed-Recipients:</emphasis> header line that lists the
+failed addresses, for the benefit of programs that try to analyse such messages
+automatically.
+</para>
+<para>
+<indexterm role="concept">
+<primary>bounce message</primary>
+<secondary>recipient of</secondary>
+</indexterm>
+A bounce message is normally sent to the sender of the original message, as
+obtained from the message&#x2019;s envelope. For incoming SMTP messages, this is the
+address given in the MAIL command. However, when an address is expanded via a
+forward or alias file, an alternative address can be specified for delivery
+failures of the generated addresses. For a mailing list expansion (see section
+<xref linkend="SECTmailinglists"/>) it is common to direct bounce messages to the manager
+of the list.
+</para>
+</section>
+<section id="SECID22">
+<title>Failures to deliver bounce messages</title>
+<para>
+<indexterm role="concept">
+<primary>bounce message</primary>
+<secondary>failure to deliver</secondary>
+</indexterm>
+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,
+but it is frozen, awaiting the attention of an administrator. There are options
+that can be used to make Exim discard such failed messages, or to keep them
+for only a short time (see <option>timeout_frozen_after</option> and
+<option>ignore_bounce_errors_after</option>).
+</para>
+</section>
+</chapter>
+
+<chapter id="CHID3">
+<title>Building and installing Exim</title>
+<para>
+<indexterm role="concept" id="IIDbuex" class="startofrange">
+<primary>building Exim</primary>
+</indexterm>
+</para>
+<section id="SECID23">
+<title>Unpacking</title>
+<para>
+Exim is distributed as a gzipped or bzipped tar file which, when unpacked,
+creates a directory with the name of the current release (for example,
+<filename>exim-4.95</filename>) into which the following files are placed:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="140pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>ACKNOWLEDGMENTS</filename></entry>
+<entry>contains some acknowledgments</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>CHANGES</filename></entry>
+<entry>contains a reference to where changes are documented</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>LICENCE</filename></entry>
+<entry>the GNU General Public Licence</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>Makefile</filename></entry>
+<entry>top-level make file</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>NOTICE</filename></entry>
+<entry>conditions for the use of Exim</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>README</filename></entry>
+<entry>list of files, directories and simple build instructions</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+Other files whose names begin with <filename>README</filename> may also be present. The
+following subdirectories are created:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="140pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>Local</filename></entry>
+<entry>an empty directory for local configuration files</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>OS</filename></entry>
+<entry>OS-specific files</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>doc</filename></entry>
+<entry>documentation files</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>exim_monitor</filename></entry>
+<entry>source files for the Exim monitor</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>scripts</filename></entry>
+<entry>scripts used in the build process</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>src</filename></entry>
+<entry>remaining source files</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<filename>util</filename></entry>
+<entry>independent utilities</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+The main utility programs are contained in the <filename>src</filename> directory and are built
+with the Exim binary. The <filename>util</filename> directory contains a few optional scripts
+that may be useful to some sites.
+</para>
+</section>
+<section id="SECID24">
+<title>Multiple machine architectures and operating systems</title>
+<para>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>multiple OS/architectures</secondary>
+</indexterm>
+The building process for Exim is arranged to make it easy to build binaries for
+a number of different architectures and operating systems from the same set of
+source files. Compilation does not take place in the <filename>src</filename> directory.
+Instead, a <emphasis>build directory</emphasis> is created for each architecture and operating
+system.
+<indexterm role="concept">
+<primary>symbolic link</primary>
+<secondary>to build directory</secondary>
+</indexterm>
+Symbolic links to the sources are installed in this directory, which is where
+the actual building takes place. In most cases, Exim can discover the machine
+architecture and operating system for itself, but the defaults can be
+overridden if necessary.
+<indexterm role="concept">
+<primary>compiler</primary>
+<secondary>requirements</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>compiler</primary>
+<secondary>version</secondary>
+</indexterm>
+A C99-capable compiler will be required for the build.
+</para>
+</section>
+<section id="SECTpcre">
+<title>PCRE library</title>
+<para>
+<indexterm role="concept">
+<primary>PCRE library</primary>
+</indexterm>
+Exim no longer has an embedded PCRE library as the vast majority of
+modern systems include PCRE as a system library, although you may need to
+install the PCRE package or the PCRE development package for your operating
+system. If your system has a normal PCRE installation the Exim build
+process will need no further configuration. If the library or the
+headers are in an unusual location you will need to either set the PCRE_LIBS
+and INCLUDE directives appropriately,
+or set PCRE_CONFIG=yes to use the installed <command>pcre-config</command> command.
+If your operating system has no
+PCRE support then you will need to obtain and build the current PCRE
+from <emphasis role="bold"><ulink url="ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/">ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/</ulink></emphasis>.
+More information on PCRE is available at <emphasis role="bold"><ulink url="https://www.pcre.org/">https://www.pcre.org/</ulink></emphasis>.
+</para>
+</section>
+<section id="SECTdb">
+<title>DBM libraries</title>
+<para>
+<indexterm role="concept">
+<primary>DBM libraries</primary>
+<secondary>discussion of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>hints database</primary>
+<secondary>DBM files used for</secondary>
+</indexterm>
+Even if you do not use any DBM files in your configuration, Exim still needs a
+DBM library in order to operate, because it uses indexed files for its hints
+databases. Unfortunately, there are a number of DBM libraries in existence, and
+different operating systems often have different ones installed.
+</para>
+<para>
+<indexterm role="concept">
+<primary>Solaris</primary>
+<secondary>DBM library for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>IRIX, DBM library for</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>BSD, DBM library for</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Linux, DBM library for</primary>
+</indexterm>
+If you are using Solaris, IRIX, one of the modern BSD systems, or a modern
+Linux distribution, the DBM configuration should happen automatically, and you
+may be able to ignore this section. Otherwise, you may have to learn more than
+you would like about DBM libraries from what follows.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>ndbm</emphasis> DBM library</primary>
+</indexterm>
+Licensed versions of Unix normally contain a library of DBM functions operating
+via the <emphasis>ndbm</emphasis> interface, and this is what Exim expects by default. Free
+versions of Unix seem to vary in what they contain as standard. In particular,
+some early versions of Linux have no default DBM library, and different
+distributors have chosen to bundle different libraries with their packaged
+versions. However, the more recent releases seem to have standardized on the
+Berkeley DB library.
+</para>
+<para>
+Different DBM libraries have different conventions for naming the files they
+use. When a program opens a file called <filename>dbmfile</filename>, there are several
+possibilities:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+A traditional <emphasis>ndbm</emphasis> implementation, such as that supplied as part of
+Solaris, operates on two files called <filename>dbmfile.dir</filename> and <filename>dbmfile.pag</filename>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><emphasis>gdbm</emphasis> DBM library</primary>
+</indexterm>
+The GNU library, <emphasis>gdbm</emphasis>, operates on a single file. If used via its <emphasis>ndbm</emphasis>
+compatibility interface it makes two different hard links to it with names
+<filename>dbmfile.dir</filename> and <filename>dbmfile.pag</filename>, but if used via its native interface, the
+filename is used unmodified.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Berkeley DB library</primary>
+</indexterm>
+The Berkeley DB package, if called via its <emphasis>ndbm</emphasis> compatibility interface,
+operates on a single file called <filename>dbmfile.db</filename>, but otherwise looks to the
+programmer exactly the same as the traditional <emphasis>ndbm</emphasis> implementation.
+</para>
+</listitem>
+<listitem>
+<para>
+If the Berkeley package is used in its native mode, it operates on a single
+file called <filename>dbmfile</filename>; the programmer&#x2019;s interface is somewhat different to
+the traditional <emphasis>ndbm</emphasis> interface.
+</para>
+</listitem>
+<listitem>
+<para>
+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.<emphasis>x</emphasis> and 3.<emphasis>x</emphasis> were current for a while, but the latest versions when Exim last revamped support were numbered 4.<emphasis>x</emphasis>.
+Maintenance of some of the earlier releases has ceased. All versions of
+Berkeley DB could be obtained from
+<emphasis role="bold"><ulink url="http://www.sleepycat.com/">http://www.sleepycat.com/</ulink></emphasis>, which is now a redirect to their new owner&#x2019;s
+page with far newer versions listed.
+It is probably wise to plan to move your storage configurations away from
+Berkeley DB format, as today there are smaller and simpler alternatives more
+suited to Exim&#x2019;s usage model.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><emphasis>tdb</emphasis> DBM library</primary>
+</indexterm>
+Yet another DBM library, called <emphasis>tdb</emphasis>, is available from
+<emphasis role="bold"><ulink url="https://sourceforge.net/projects/tdb/files/">https://sourceforge.net/projects/tdb/files/</ulink></emphasis>. It has its own interface, and also
+operates on a single file.
+</para>
+</listitem>
+</orderedlist>
+<para>
+<indexterm role="concept">
+<primary>USE_DB</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>DBM libraries</primary>
+<secondary>configuration for building</secondary>
+</indexterm>
+Exim and its utilities can be compiled to use any of these interfaces. In order
+to use any version of the Berkeley DB package in native mode, you must set
+USE_DB in an appropriate configuration file (typically
+<filename>Local/Makefile</filename>). For example:
+</para>
+<literallayout class="monospaced">
+USE_DB=yes
+</literallayout>
+<para>
+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.
+</para>
+<para>
+At the lowest level, the build-time configuration sets none of these options,
+thereby assuming an interface of type (1). However, some operating system
+configuration files (for example, those for the BSD operating systems and
+Linux) assume type (4) by setting USE_DB as their default, and the
+configuration files for Cygwin set USE_GDBM. Anything you set in
+<filename>Local/Makefile</filename>, however, overrides these system defaults.
+</para>
+<para>
+As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be
+necessary to set DBMLIB, to cause inclusion of the appropriate library, as
+in one of these lines:
+</para>
+<literallayout class="monospaced">
+DBMLIB = -ldb
+DBMLIB = -ltdb
+</literallayout>
+<para>
+Settings like that will work if the DBM library is installed in the standard
+place. Sometimes it is not, and the library&#x2019;s header file may also not be in
+the default path. You may need to set INCLUDE to specify where the header
+file is, and to specify the path to the library more fully in DBMLIB, as in
+this example:
+</para>
+<literallayout class="monospaced">
+INCLUDE=-I/usr/local/include/db-4.1
+DBMLIB=/usr/local/lib/db-4.1/libdb.a
+</literallayout>
+<para>
+There is further detailed discussion about the various DBM libraries in the
+file <filename>doc/dbm.discuss.txt</filename> in the Exim distribution.
+</para>
+</section>
+<section id="SECID25">
+<title>Pre-building configuration</title>
+<para>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>pre-building configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration for building Exim</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>Local/Makefile</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>src/EDITME</filename></primary>
+</indexterm>
+Before building Exim, a local configuration file that specifies options
+independent of any operating system has to be created with the name
+<filename>Local/Makefile</filename>. A template for this file is supplied as the file
+<filename>src/EDITME</filename>, and it contains full descriptions of all the option settings
+therein. These descriptions are therefore not repeated here. If you are
+building Exim for the first time, the simplest thing to do is to copy
+<filename>src/EDITME</filename> to <filename>Local/Makefile</filename>, then read it and edit it appropriately.
+</para>
+<para>
+There are three settings that you must supply, because Exim will not build
+without them. They are the location of the runtime configuration file
+(CONFIGURE_FILE), the directory in which Exim binaries will be installed
+(BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and
+maybe EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be
+a colon-separated list of filenames; Exim uses the first of them that exists.
+</para>
+<para>
+There are a few other parameters that can be specified either at build time or
+at runtime, to enable the same binary to be used on a number of different
+machines. However, if the locations of Exim&#x2019;s spool directory and log file
+directory (if not within the spool directory) are fixed, it is recommended that
+you specify them in <filename>Local/Makefile</filename> instead of at runtime, so that errors
+detected early in Exim&#x2019;s execution (such as a malformed configuration file) can
+be logged.
+</para>
+<para>
+<indexterm role="concept">
+<primary>content scanning</primary>
+<secondary>specifying at build time</secondary>
+</indexterm>
+Exim&#x2019;s interfaces for calling virus and spam scanning software directly from
+access control lists are not compiled by default. If you want to include these
+facilities, you need to set
+</para>
+<literallayout class="monospaced">
+WITH_CONTENT_SCAN=yes
+</literallayout>
+<para>
+in your <filename>Local/Makefile</filename>. For details of the facilities themselves, see
+chapter <xref linkend="CHAPexiscan"/>.
+</para>
+<para>
+<indexterm role="concept">
+<primary><filename>Local/eximon.conf</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>exim_monitor/EDITME</filename></primary>
+</indexterm>
+If you are going to build the Exim monitor, a similar configuration process is
+required. The file <filename>exim_monitor/EDITME</filename> must be edited appropriately for
+your installation and saved under the name <filename>Local/eximon.conf</filename>. If you are
+happy with the default settings described in <filename>exim_monitor/EDITME</filename>,
+<filename>Local/eximon.conf</filename> can be empty, but it must exist.
+</para>
+<para>
+This is all the configuration that is needed in straightforward cases for known
+operating systems. However, the building process is set up so that it is easy
+to override options that are set by default or by operating-system-specific
+configuration files, for example, to change the C compiler, which
+defaults to <option>gcc</option>. See section <xref linkend="SECToverride"/> below for details of how to
+do this.
+</para>
+</section>
+<section id="SECID26">
+<title>Support for iconv()</title>
+<para>
+<indexterm role="concept">
+<primary><function>iconv()</function> support</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>RFC 2047</primary>
+</indexterm>
+The contents of header lines in messages may be encoded according to the rules
+described RFC 2047. This makes it possible to transmit characters that are not
+in the ASCII character set, and to label them as being in a particular
+character set. When Exim is inspecting header lines by means of the <option>$h_</option>
+mechanism, it decodes them, and translates them into a specified character set
+(default is set at build time). The translation is possible only if the operating system
+supports the <function>iconv()</function> function.
+</para>
+<para>
+However, some of the operating systems that supply <function>iconv()</function> do not support
+very many conversions. The GNU <option>libiconv</option> library (available from
+<emphasis role="bold"><ulink url="https://www.gnu.org/software/libiconv/">https://www.gnu.org/software/libiconv/</ulink></emphasis>) can be installed on such
+systems to remedy this deficiency, as well as on systems that do not supply
+<function>iconv()</function> at all. After installing <option>libiconv</option>, you should add
+</para>
+<literallayout class="monospaced">
+HAVE_ICONV=yes
+</literallayout>
+<para>
+to your <filename>Local/Makefile</filename> and rebuild Exim.
+</para>
+</section>
+<section id="SECTinctlsssl">
+<title>Including TLS/SSL encryption support</title>
+<para>
+<indexterm role="concept">
+<primary>TLS</primary>
+<secondary>including support for TLS</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>encryption</primary>
+<secondary>including support for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>OpenSSL</primary>
+<secondary>building Exim with</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>GnuTLS</primary>
+<secondary>building Exim with</secondary>
+</indexterm>
+Exim is usually built to support encrypted SMTP connections, using the STARTTLS
+command as per RFC 2487. It can also support clients that expect to
+start a TLS session immediately on connection to a non-standard port (see the
+<option>tls_on_connect_ports</option> runtime option and the <option>-tls-on-connect</option> command
+line option).
+</para>
+<para>
+If you want to build Exim with TLS support, you must first install either the
+OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for
+implementing SSL.
+</para>
+<para>
+If you do not want TLS support you should set
+</para>
+<literallayout class="monospaced">
+DISABLE_TLS=yes
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>.
+</para>
+<para>
+If OpenSSL is installed, you should set
+</para>
+<literallayout class="monospaced">
+USE_OPENSL=yes
+TLS_LIBS=-lssl -lcrypto
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>. You may also need to specify the locations of the
+OpenSSL library and include files. For example:
+</para>
+<literallayout class="monospaced">
+USE_OPENSSL=yes
+TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
+TLS_INCLUDE=-I/usr/local/openssl/include/
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>pkg-config</primary>
+<secondary>OpenSSL</secondary>
+</indexterm>
+If you have <emphasis>pkg-config</emphasis> available, then instead you can just use:
+</para>
+<literallayout class="monospaced">
+USE_OPENSSL=yes
+USE_OPENSSL_PC=openssl
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>USE_GNUTLS</primary>
+</indexterm>
+If GnuTLS is installed, you should set
+</para>
+<literallayout class="monospaced">
+USE_GNUTLS=yes
+TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>, and again you may need to specify the locations of the
+library and include files. For example:
+</para>
+<literallayout class="monospaced">
+USE_GNUTLS=yes
+TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
+TLS_INCLUDE=-I/usr/gnu/include
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>pkg-config</primary>
+<secondary>GnuTLS</secondary>
+</indexterm>
+If you have <emphasis>pkg-config</emphasis> available, then instead you can just use:
+</para>
+<literallayout class="monospaced">
+USE_GNUTLS=yes
+USE_GNUTLS_PC=gnutls
+</literallayout>
+<para>
+You do not need to set TLS_INCLUDE if the relevant directory is already
+specified in INCLUDE. Details of how to configure Exim to make use of TLS are
+given in chapter <xref linkend="CHAPTLS"/>.
+</para>
+</section>
+<section id="SECID27">
+<title>Use of tcpwrappers</title>
+<para>
+<indexterm role="concept">
+<primary>tcpwrappers, building Exim to support</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>USE_TCP_WRAPPERS</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>TCP_WRAPPERS_DAEMON_NAME</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>tcp_wrappers_daemon_name</primary>
+</indexterm>
+Exim can be linked with the <emphasis>tcpwrappers</emphasis> library in order to check incoming
+SMTP calls using the <emphasis>tcpwrappers</emphasis> control files. This may be a convenient
+alternative to Exim&#x2019;s own checking facilities for installations that are
+already making use of <emphasis>tcpwrappers</emphasis> for other purposes. To do this, you
+should set USE_TCP_WRAPPERS in <filename>Local/Makefile</filename>, arrange for the file
+<filename>tcpd.h</filename> to be available at compile time, and also ensure that the library
+<filename>libwrap.a</filename> is available at link time, typically by including <option>-lwrap</option> in
+EXTRALIBS_EXIM. For example, if <emphasis>tcpwrappers</emphasis> is installed in <filename>/usr/local</filename>,
+you might have
+</para>
+<literallayout class="monospaced">
+USE_TCP_WRAPPERS=yes
+CFLAGS=-O -I/usr/local/include
+EXTRALIBS_EXIM=-L/usr/local/lib -lwrap
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>. The daemon name to use in the <emphasis>tcpwrappers</emphasis> control
+files is <quote>exim</quote>. For example, the line
+</para>
+<literallayout class="monospaced">
+exim : LOCAL  192.168.1.  .friendly.domain.example
+</literallayout>
+<para>
+in your <filename>/etc/hosts.allow</filename> file allows connections from the local host, from
+the subnet 192.168.1.0/24, and from all hosts in <emphasis>friendly.domain.example</emphasis>.
+All other connections are denied. The daemon name used by <emphasis>tcpwrappers</emphasis>
+can be changed at build time by setting TCP_WRAPPERS_DAEMON_NAME in
+<filename>Local/Makefile</filename>, or by setting tcp_wrappers_daemon_name in the
+configure file. Consult the <emphasis>tcpwrappers</emphasis> documentation for
+further details.
+</para>
+</section>
+<section id="SECID28">
+<title>Including support for IPv6</title>
+<para>
+<indexterm role="concept">
+<primary>IPv6</primary>
+<secondary>including support for</secondary>
+</indexterm>
+Exim contains code for use on systems that have IPv6 support. Setting
+<literal>HAVE_IPV6=YES</literal> in <filename>Local/Makefile</filename> causes the IPv6 code to be included;
+it may also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems
+where the IPv6 support is not fully integrated into the normal include and
+library files.
+</para>
+<para>
+Two different types of DNS record for handling IPv6 addresses have been
+defined. AAAA records (analogous to A records for IPv4) are in use, and are
+currently seen as the mainstream. Another record type called A6 was proposed
+as better than AAAA because it had more flexibility. However, it was felt to be
+over-complex, and its status was reduced to <quote>experimental</quote>.
+Exim used to
+have a compile option for including A6 record support but this has now been
+withdrawn.
+</para>
+</section>
+<section id="SECTdynamicmodules">
+<title>Dynamically loaded lookup module support</title>
+<para>
+<indexterm role="concept">
+<primary>lookup modules</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>dynamic modules</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>.so building</primary>
+</indexterm>
+On some platforms, Exim supports not compiling all lookup types directly into
+the main binary, instead putting some into external modules which can be loaded
+on demand.
+This permits packagers to build Exim with support for lookups with extensive
+library dependencies without requiring all users to install all of those
+dependencies.
+Most, but not all, lookup types can be built this way.
+</para>
+<para>
+Set <literal>LOOKUP_MODULE_DIR</literal> to the directory into which the modules will be
+installed; Exim will only load modules from that directory, as a security
+measure.  You will need to set <literal>CFLAGS_DYNAMIC</literal> if not already defined
+for your OS; see <filename>OS/Makefile-Linux</filename> for an example.
+Some other requirements for adjusting <literal>EXTRALIBS</literal> may also be necessary,
+see <filename>src/EDITME</filename> for details.
+</para>
+<para>
+Then, for each module to be loaded dynamically, define the relevant
+<literal>LOOKUP_</literal>&lt;<emphasis>lookup_type</emphasis>&gt; flags to have the value "2" instead of "yes".
+For example, this will build in lsearch but load sqlite and mysql support
+on demand:
+</para>
+<literallayout class="monospaced">
+LOOKUP_LSEARCH=yes
+LOOKUP_SQLITE=2
+LOOKUP_MYSQL=2
+</literallayout>
+</section>
+<section id="SECID29">
+<title>The building process</title>
+<para>
+<indexterm role="concept">
+<primary>build directory</primary>
+</indexterm>
+Once <filename>Local/Makefile</filename> (and <filename>Local/eximon.conf</filename>, if required) have been
+created, run <emphasis>make</emphasis> at the top level. It determines the architecture and
+operating system types, and creates a build directory if one does not exist.
+For example, on a Sun system running Solaris 8, the directory
+<filename>build-SunOS5-5.8-sparc</filename> is created.
+<indexterm role="concept">
+<primary>symbolic link</primary>
+<secondary>to source files</secondary>
+</indexterm>
+Symbolic links to relevant source files are installed in the build directory.
+</para>
+<para>
+If this is the first time <emphasis>make</emphasis> has been run, it calls a script that builds
+a make file inside the build directory, using the configuration files from the
+<filename>Local</filename> directory. The new make file is then passed to another instance of
+<emphasis>make</emphasis>. This does the real work, building a number of utility scripts, and
+then compiling and linking the binaries for the Exim monitor (if configured), a
+number of utility programs, and finally Exim itself. The command <literal>make
+makefile</literal> can be used to force a rebuild of the make file in the build
+directory, should this ever be necessary.
+</para>
+<para>
+If you have problems building Exim, check for any comments there may be in the
+<filename>README</filename> file concerning your operating system, and also take a look at the
+FAQ, where some common problems are covered.
+</para>
+</section>
+<section id="SECID283">
+<title>Output from <quote>make</quote></title>
+<para>
+The output produced by the <emphasis>make</emphasis> process for compile lines is often very
+unreadable, because these lines can be very long. For this reason, the normal
+output is suppressed by default, and instead output similar to that which
+appears when compiling the 2.6 Linux kernel is generated: just a short line for
+each module that is being compiled or linked. However, it is still possible to
+get the full output, by calling <emphasis>make</emphasis> like this:
+</para>
+<literallayout class="monospaced">
+FULLECHO='' make -e
+</literallayout>
+<para>
+The value of FULLECHO defaults to <quote>@</quote>, the flag character that suppresses
+command reflection in <emphasis>make</emphasis>. When you ask for the full output, it is
+given in addition to the short output.
+</para>
+</section>
+<section id="SECToverride">
+<title>Overriding build-time options for Exim</title>
+<para>
+<indexterm role="concept">
+<primary>build-time options, overriding</primary>
+</indexterm>
+The main make file that is created at the beginning of the building process
+consists of the concatenation of a number of files which set configuration
+values, followed by a fixed set of <emphasis>make</emphasis> instructions. If a value is set
+more than once, the last setting overrides any previous ones. This provides a
+convenient way of overriding defaults. The files that are concatenated are, in
+order:
+</para>
+<literallayout>
+<filename>OS/Makefile-Default</filename>
+<filename>OS/Makefile-</filename>&lt;<emphasis>ostype</emphasis>&gt;
+<filename>Local/Makefile</filename>
+<filename>Local/Makefile-</filename>&lt;<emphasis>ostype</emphasis>&gt;
+<filename>Local/Makefile-</filename>&lt;<emphasis>archtype</emphasis>&gt;
+<filename>Local/Makefile-</filename>&lt;<emphasis>ostype</emphasis>&gt;-&lt;<emphasis>archtype</emphasis>&gt;
+<filename>OS/Makefile-Base</filename>
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary><filename>Local/Makefile</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>operating system type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>architecture type</secondary>
+</indexterm>
+where &lt;<emphasis>ostype</emphasis>&gt; is the operating system type and &lt;<emphasis>archtype</emphasis>&gt; is the
+architecture type. <filename>Local/Makefile</filename> is required to exist, and the building
+process fails if it is absent. The other three <filename>Local</filename> files are optional,
+and are often not needed.
+</para>
+<para>
+The values used for &lt;<emphasis>ostype</emphasis>&gt; and &lt;<emphasis>archtype</emphasis>&gt; are obtained from scripts
+called <filename>scripts/os-type</filename> and <filename>scripts/arch-type</filename> respectively. If either of
+the environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their
+values are used, thereby providing a means of forcing particular settings.
+Otherwise, the scripts try to get values from the <option>uname</option> command. If this
+fails, the shell variables OSTYPE and ARCHTYPE are inspected. A number
+of <emphasis>ad hoc</emphasis> transformations are then applied, to produce the standard names
+that Exim expects. You can run these scripts directly from the shell in order
+to find out what values are being used on your system.
+</para>
+<para>
+<filename>OS/Makefile-Default</filename> contains comments about the variables that are set
+therein. Some (but not all) are mentioned below. If there is something that
+needs changing, review the contents of this file and the contents of the make
+file for your operating system (<filename>OS/Makefile-&lt;ostype&gt;</filename>) to see what the
+default values are.
+</para>
+<para>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>overriding default settings</secondary>
+</indexterm>
+If you need to change any of the values that are set in <filename>OS/Makefile-Default</filename>
+or in <filename>OS/Makefile-&lt;ostype&gt;</filename>, or to add any new definitions, you do not
+need to change the original files. Instead, you should make the changes by
+putting the new values in an appropriate <filename>Local</filename> file. For example,
+<indexterm role="concept">
+<primary>Tru64-Unix build-time settings</primary>
+</indexterm>
+when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX,
+formerly DEC-OSF1) operating system, it is necessary to specify that the C
+compiler is called <emphasis>cc</emphasis> rather than <emphasis>gcc</emphasis>. Also, the compiler must be
+called with the option <option>-std1</option>, to make it recognize some of the features of
+Standard C that Exim uses. (Most other compilers recognize Standard C by
+default.) To do this, you should create a file called <filename>Local/Makefile-OSF1</filename>
+containing the lines
+</para>
+<literallayout class="monospaced">
+CC=cc
+CFLAGS=-std1
+</literallayout>
+<para>
+If you are compiling for just one operating system, it may be easier to put
+these lines directly into <filename>Local/Makefile</filename>.
+</para>
+<para>
+Keeping all your local configuration settings separate from the distributed
+files makes it easy to transfer them to new versions of Exim simply by copying
+the contents of the <filename>Local</filename> directory.
+</para>
+<para>
+<indexterm role="concept">
+<primary>NIS lookup type</primary>
+<secondary>including support for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>NIS+ lookup type</primary>
+<secondary>including support for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>including support for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>inclusion in binary</secondary>
+</indexterm>
+Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file
+lookup, but not all systems have these components installed, so the default is
+not to include the relevant code in the binary. All the different kinds of file
+and database lookup that Exim supports are implemented as separate code modules
+which are included only if the relevant compile-time options are set. In the
+case of LDAP, NIS, and NIS+, the settings for <filename>Local/Makefile</filename> are:
+</para>
+<literallayout class="monospaced">
+LOOKUP_LDAP=yes
+LOOKUP_NIS=yes
+LOOKUP_NISPLUS=yes
+</literallayout>
+<para>
+and similar settings apply to the other lookup types. They are all listed in
+<filename>src/EDITME</filename>. In many cases the relevant include files and interface
+libraries need to be installed before compiling Exim.
+<indexterm role="concept">
+<primary>cdb</primary>
+<secondary>including support for</secondary>
+</indexterm>
+However, there are some optional lookup types (such as cdb) for which
+the code is entirely contained within Exim, and no external include
+files or libraries are required. When a lookup type is not included in the
+binary, attempts to configure Exim to use it cause runtime configuration
+errors.
+</para>
+<para>
+<indexterm role="concept">
+<primary>pkg-config</primary>
+<secondary>lookups</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>pkg-config</primary>
+<secondary>authenticators</secondary>
+</indexterm>
+Many systems now use a tool called <emphasis>pkg-config</emphasis> to encapsulate information
+about how to compile against a library; Exim has some initial support for
+being able to use pkg-config for lookups and authenticators.  For any given
+makefile variable which starts <literal>LOOKUP_</literal> or <literal>AUTH_</literal>, you can add a new
+variable with the <literal>_PC</literal> suffix in the name and assign as the value the
+name of the package to be queried.  The results of querying via the
+<emphasis>pkg-config</emphasis> command will be added to the appropriate Makefile variables
+with <literal>+=</literal> directives, so your version of <emphasis>make</emphasis> will need to support that
+syntax.  For instance:
+</para>
+<literallayout class="monospaced">
+LOOKUP_SQLITE=yes
+LOOKUP_SQLITE_PC=sqlite3
+AUTH_GSASL=yes
+AUTH_GSASL_PC=libgsasl
+AUTH_HEIMDAL_GSSAPI=yes
+AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>Perl</primary>
+<secondary>including support for</secondary>
+</indexterm>
+Exim can be linked with an embedded Perl interpreter, allowing Perl
+subroutines to be called during string expansion. To enable this facility,
+</para>
+<literallayout class="monospaced">
+EXIM_PERL=perl.o
+</literallayout>
+<para>
+must be defined in <filename>Local/Makefile</filename>. Details of this facility are given in
+chapter <xref linkend="CHAPperl"/>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>X11 libraries, location of</primary>
+</indexterm>
+The location of the X11 libraries is something that varies a lot between
+operating systems, and there may be different versions of X11 to cope
+with. Exim itself makes no use of X11, but if you are compiling the Exim
+monitor, the X11 libraries must be available.
+The following three variables are set in <filename>OS/Makefile-Default</filename>:
+</para>
+<literallayout class="monospaced">
+X11=/usr/X11R6
+XINCLUDE=-I$(X11)/include
+XLFLAGS=-L$(X11)/lib
+</literallayout>
+<para>
+These are overridden in some of the operating-system configuration files. For
+example, in <filename>OS/Makefile-SunOS5</filename> there is
+</para>
+<literallayout class="monospaced">
+X11=/usr/openwin
+XINCLUDE=-I$(X11)/include
+XLFLAGS=-L$(X11)/lib -R$(X11)/lib
+</literallayout>
+<para>
+If you need to override the default setting for your operating system, place a
+definition of all three of these variables into your
+<filename>Local/Makefile-&lt;ostype&gt;</filename> file.
+</para>
+<para>
+<indexterm role="concept">
+<primary>EXTRALIBS</primary>
+</indexterm>
+If you need to add any extra libraries to the link steps, these can be put in a
+variable called EXTRALIBS, which appears in all the link commands, but by
+default is not defined. In contrast, EXTRALIBS_EXIM is used only on the
+command for linking the main Exim binary, and not for any associated utilities.
+</para>
+<para>
+<indexterm role="concept">
+<primary>DBM libraries</primary>
+<secondary>configuration for building</secondary>
+</indexterm>
+There is also DBMLIB, which appears in the link commands for binaries that
+use DBM functions (see also section <xref linkend="SECTdb"/>). Finally, there is
+EXTRALIBS_EXIMON, which appears only in the link step for the Exim monitor
+binary, and which can be used, for example, to include additional X11
+libraries.
+</para>
+<para>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>editing</secondary>
+</indexterm>
+The make file copes with rebuilding Exim correctly if any of the configuration
+files are edited. However, if an optional configuration file is deleted, it is
+necessary to touch the associated non-optional file (that is,
+<filename>Local/Makefile</filename> or <filename>Local/eximon.conf</filename>) before rebuilding.
+</para>
+</section>
+<section id="SECID30">
+<title>OS-specific header files</title>
+<para>
+<indexterm role="concept">
+<primary><filename>os.h</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>building Exim</primary>
+<secondary>OS-specific C header files</secondary>
+</indexterm>
+The <filename>OS</filename> directory contains a number of files with names of the form
+<filename>os.h-&lt;ostype&gt;</filename>. These are system-specific C header files that should not
+normally need to be changed. There is a list of macro settings that are
+recognized in the file <filename>OS/os.configuring</filename>, which should be consulted if you
+are porting Exim to a new operating system.
+</para>
+</section>
+<section id="SECID31">
+<title>Overriding build-time options for the monitor</title>
+<para>
+<indexterm role="concept">
+<primary>building Eximon</primary>
+</indexterm>
+A similar process is used for overriding things when building the Exim monitor,
+where the files that are involved are
+</para>
+<literallayout>
+<filename>OS/eximon.conf-Default</filename>
+<filename>OS/eximon.conf-</filename>&lt;<emphasis>ostype</emphasis>&gt;
+<filename>Local/eximon.conf</filename>
+<filename>Local/eximon.conf-</filename>&lt;<emphasis>ostype</emphasis>&gt;
+<filename>Local/eximon.conf-</filename>&lt;<emphasis>archtype</emphasis>&gt;
+<filename>Local/eximon.conf-</filename>&lt;<emphasis>ostype</emphasis>&gt;-&lt;<emphasis>archtype</emphasis>&gt;
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary><filename>Local/eximon.conf</filename></primary>
+</indexterm>
+As with Exim itself, the final three files need not exist, and in this case the
+<filename>OS/eximon.conf-&lt;ostype&gt;</filename> file is also optional. The default values in
+<filename>OS/eximon.conf-Default</filename> can be overridden dynamically by setting environment
+variables of the same name, preceded by EXIMON_. For example, setting
+EXIMON_LOG_DEPTH in the environment overrides the value of
+LOG_DEPTH at runtime.
+<indexterm role="concept" startref="IIDbuex" class="endofrange"/>
+</para>
+</section>
+<section id="SECID32">
+<title>Installing Exim binaries and scripts</title>
+<para>
+<indexterm role="concept">
+<primary>installing Exim</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>BIN_DIRECTORY</primary>
+</indexterm>
+The command <literal>make install</literal> runs the <command>exim_install</command> script with no
+arguments. The script copies binaries and utility scripts into the directory
+whose name is specified by the BIN_DIRECTORY setting in <filename>Local/Makefile</filename>.
+<indexterm role="concept">
+<primary>setuid</primary>
+<secondary>installing Exim with</secondary>
+</indexterm>
+The install script copies files only if they are newer than the files they are
+going to replace. The Exim binary is required to be owned by root and have the
+<emphasis>setuid</emphasis> bit set, for normal configurations. Therefore, you must run <literal>make
+install</literal> as root so that it can set up the Exim binary in this way. However, in
+some special situations (for example, if a host is doing no local deliveries)
+it may be possible to run Exim without making the binary setuid root (see
+chapter <xref linkend="CHAPsecurity"/> for details).
+</para>
+<para>
+<indexterm role="concept">
+<primary>CONFIGURE_FILE</primary>
+</indexterm>
+Exim&#x2019;s runtime configuration file is named by the CONFIGURE_FILE setting
+in <filename>Local/Makefile</filename>. If this names a single file, and the file does not
+exist, the default configuration file <filename>src/configure.default</filename> is copied there
+by the installation script. If a runtime configuration file already exists, it
+is left alone. If CONFIGURE_FILE is a colon-separated list, naming several
+alternative files, no default is installed.
+</para>
+<para>
+<indexterm role="concept">
+<primary>system aliases file</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>/etc/aliases</filename></primary>
+</indexterm>
+One change is made to the default configuration file when it is installed: the
+default configuration contains a router that references a system aliases file.
+The path to this file is set to the value specified by
+SYSTEM_ALIASES_FILE in <filename>Local/Makefile</filename> (<filename>/etc/aliases</filename> by default).
+If the system aliases file does not exist, the installation script creates it,
+and outputs a comment to the user.
+</para>
+<para>
+The created file contains no aliases, but it does contain comments about the
+aliases a site should normally have. Mail aliases have traditionally been
+kept in <filename>/etc/aliases</filename>. However, some operating systems are now using
+<filename>/etc/mail/aliases</filename>. You should check if yours is one of these, and change
+Exim&#x2019;s configuration if necessary.
+</para>
+<para>
+The default configuration uses the local host&#x2019;s name as the only local domain,
+and is set up to do local deliveries into the shared directory <filename>/var/mail</filename>,
+running as the local user. System aliases and <filename>.forward</filename> files in users&#x2019; home
+directories are supported, but no NIS or NIS+ support is configured. Domains
+other than the name of the local host are routed using the DNS, with delivery
+over SMTP.
+</para>
+<para>
+It is possible to install Exim for special purposes (such as building a binary
+distribution) in a private part of the file system. You can do this by a
+command such as
+</para>
+<literallayout class="monospaced">
+make DESTDIR=/some/directory/ install
+</literallayout>
+<para>
+This has the effect of pre-pending the specified directory to all the file
+paths, except the name of the system aliases file that appears in the default
+configuration. (If a default alias file is created, its name <emphasis>is</emphasis> modified.)
+For backwards compatibility, ROOT is used if DESTDIR is not set,
+but this usage is deprecated.
+</para>
+<para>
+<indexterm role="concept">
+<primary>installing Exim</primary>
+<secondary>what is not installed</secondary>
+</indexterm>
+Running <emphasis>make install</emphasis> does not copy the Exim 4 conversion script
+<emphasis>convert4r4</emphasis>. You will probably run this only once if you are
+upgrading from Exim 3. None of the documentation files in the <filename>doc</filename>
+directory are copied, except for the info files when you have set
+INFO_DIRECTORY, as described in section <xref linkend="SECTinsinfdoc"/> below.
+</para>
+<para>
+For the utility programs, old versions are renamed by adding the suffix <filename>.O</filename>
+to their names. The Exim binary itself, however, is handled differently. It is
+installed under a name that includes the version number and the compile number,
+for example, <filename>exim-4.95-1</filename>. The script then arranges for a symbolic link
+called <filename>exim</filename> to point to the binary. If you are updating a previous version
+of Exim, the script takes care to ensure that the name <filename>exim</filename> is never absent
+from the directory (as seen by other processes).
+</para>
+<para>
+<indexterm role="concept">
+<primary>installing Exim</primary>
+<secondary>testing the script</secondary>
+</indexterm>
+If you want to see what the <emphasis>make install</emphasis> will do before running it for
+real, you can pass the <option>-n</option> option to the installation script by this
+command:
+</para>
+<literallayout class="monospaced">
+make INSTALL_ARG=-n install
+</literallayout>
+<para>
+The contents of the variable INSTALL_ARG are passed to the installation
+script. You do not need to be root to run this test. Alternatively, you can run
+the installation script directly, but this must be from within the build
+directory. For example, from the top-level Exim directory you could use this
+command:
+</para>
+<literallayout class="monospaced">
+(cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n)
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>installing Exim</primary>
+<secondary>install script options</secondary>
+</indexterm>
+There are two other options that can be supplied to the installation script.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<option>-no_chown</option> bypasses the call to change the owner of the installed binary
+to root, and the call to make it a setuid binary.
+</para>
+</listitem>
+<listitem>
+<para>
+<option>-no_symlink</option> bypasses the setting up of the symbolic link <filename>exim</filename> to the
+installed binary.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+INSTALL_ARG can be used to pass these options to the script. For example:
+</para>
+<literallayout class="monospaced">
+make INSTALL_ARG=-no_symlink install
+</literallayout>
+<para>
+The installation script can also be given arguments specifying which files are
+to be copied. For example, to install just the Exim binary, and nothing else,
+without creating the symbolic link, you could use:
+</para>
+<literallayout class="monospaced">
+make INSTALL_ARG='-no_symlink exim' install
+</literallayout>
+</section>
+<section id="SECTinsinfdoc">
+<title>Installing info documentation</title>
+<para>
+<indexterm role="concept">
+<primary>installing Exim</primary>
+<secondary><emphasis>info</emphasis> documentation</secondary>
+</indexterm>
+Not all systems use the GNU <emphasis>info</emphasis> system for documentation, and for this
+reason, the Texinfo source of Exim&#x2019;s documentation is not included in the main
+distribution. Instead it is available separately from the FTP site (see section
+<xref linkend="SECTavail"/>).
+</para>
+<para>
+If you have defined INFO_DIRECTORY in <filename>Local/Makefile</filename> and the Texinfo
+source of the documentation is found in the source tree, running <literal>make
+install</literal> automatically builds the info files and installs them.
+</para>
+</section>
+<section id="SECID33">
+<title>Setting up the spool directory</title>
+<para>
+<indexterm role="concept">
+<primary>spool directory</primary>
+<secondary>creating</secondary>
+</indexterm>
+When it starts up, Exim tries to create its spool directory if it does not
+exist. The Exim uid and gid are used for the owner and group of the spool
+directory. Sub-directories are automatically created in the spool directory as
+necessary.
+</para>
+</section>
+<section id="SECID34">
+<title>Testing</title>
+<para>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>installation</secondary>
+</indexterm>
+Having installed Exim, you can check that the runtime configuration file is
+syntactically valid by running the following command, which assumes that the
+Exim binary directory is within your PATH environment variable:
+</para>
+<literallayout class="monospaced">
+exim -bV
+</literallayout>
+<para>
+If there are any errors in the configuration file, Exim outputs error messages.
+Otherwise it outputs the version number and build date,
+the DBM library that is being used, and information about which drivers and
+other optional code modules are included in the binary.
+Some simple routing tests can be done by using the address testing option. For
+example,
+</para>
+<literallayout>
+<literal>exim -bt</literal> &lt;<emphasis>local username</emphasis>&gt;
+</literallayout>
+<para>
+should verify that it recognizes a local mailbox, and
+</para>
+<literallayout>
+<literal>exim -bt</literal> &lt;<emphasis>remote address</emphasis>&gt;
+</literallayout>
+<para>
+a remote one. Then try getting it to deliver mail, both locally and remotely.
+This can be done by passing messages directly to Exim, without going through a
+user agent. For example:
+</para>
+<literallayout class="monospaced">
+exim -v postmaster@???
+From: user@???
+To: postmaster@???
+Subject: Testing Exim
+
+This is a test message.
+^D
+</literallayout>
+<para>
+The <option>-v</option> option causes Exim to output some verification of what it is doing.
+In this case you should see copies of three log lines, one for the message&#x2019;s
+arrival, one for its delivery, and one containing <quote>Completed</quote>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>problems with</secondary>
+</indexterm>
+If you encounter problems, look at Exim&#x2019;s log files (<emphasis>mainlog</emphasis> and
+<emphasis>paniclog</emphasis>) to see if there is any relevant information there. Another source
+of information is running Exim with debugging turned on, by specifying the
+<option>-d</option> option. If a message is stuck on Exim&#x2019;s spool, you can force a delivery
+with debugging turned on by a command of the form
+</para>
+<literallayout>
+<literal>exim -d -M</literal> &lt;<emphasis>exim-message-id</emphasis>&gt;
+</literallayout>
+<para>
+You must be root or an <quote>admin user</quote> in order to do this. The <option>-d</option> option
+produces rather a lot of output, but you can cut this down to specific areas.
+For example, if you use <option>-d-all+route</option> only the debugging information
+relevant to routing is included. (See the <option>-d</option> option in chapter
+<xref linkend="CHAPcommandline"/> for more details.)
+</para>
+<para>
+<indexterm role="concept">
+<primary><quote>sticky</quote> bit</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lock files</primary>
+</indexterm>
+One specific problem that has shown up on some sites is the inability to do
+local deliveries into a shared mailbox directory, because it does not have the
+<quote>sticky bit</quote> set on it. By default, Exim tries to create a lock file before
+writing to a mailbox file, and if it cannot create the lock file, the delivery
+is deferred. You can get round this either by setting the <quote>sticky bit</quote> on the
+directory, or by setting a specific group for local deliveries and allowing
+that group to create files in the directory (see the comments above the
+<command>local_delivery</command> transport in the default configuration file). Another
+approach is to configure Exim not to use lock files, but just to rely on
+<function>fcntl()</function> locking instead. However, you should do this only if all user
+agents also use <function>fcntl()</function> locking. For further discussion of locking issues,
+see chapter <xref linkend="CHAPappendfile"/>.
+</para>
+<para>
+One thing that cannot be tested on a system that is already running an MTA is
+the receipt of incoming SMTP mail on the standard SMTP port. However, the
+<option>-oX</option> option can be used to run an Exim daemon that listens on some other
+port, or <emphasis>inetd</emphasis> can be used to do this. The <option>-bh</option> option and the
+<emphasis>exim_checkaccess</emphasis> utility can be used to check out policy controls on
+incoming SMTP mail.
+</para>
+<para>
+Testing a new version on a system that is already running Exim can most easily
+be done by building a binary with a different CONFIGURE_FILE setting. From
+within the runtime configuration, all other file and directory names
+that Exim uses can be altered, in order to keep it entirely clear of the
+production version.
+</para>
+</section>
+<section id="SECID35">
+<title>Replacing another MTA with Exim</title>
+<para>
+<indexterm role="concept">
+<primary>replacing another MTA</primary>
+</indexterm>
+Building and installing Exim for the first time does not of itself put it in
+general use. The name by which the system&#x2019;s MTA is called by mail user agents
+is either <filename>/usr/sbin/sendmail</filename>, or <filename>/usr/lib/sendmail</filename> (depending on the
+operating system), and it is necessary to make this name point to the <emphasis>exim</emphasis>
+binary in order to get the user agents to pass messages to Exim. This is
+normally done by renaming any existing file and making <filename>/usr/sbin/sendmail</filename>
+or <filename>/usr/lib/sendmail</filename>
+<indexterm role="concept">
+<primary>symbolic link</primary>
+<secondary>to <emphasis>exim</emphasis> binary</secondary>
+</indexterm>
+a symbolic link to the <emphasis>exim</emphasis> binary. It is a good idea to remove any setuid
+privilege and executable status from the old MTA. It is then necessary to stop
+and restart the mailer daemon, if one is running.
+</para>
+<para>
+<indexterm role="concept">
+<primary>FreeBSD, MTA indirection</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>/etc/mail/mailer.conf</filename></primary>
+</indexterm>
+Some operating systems have introduced alternative ways of switching MTAs. For
+example, if you are running FreeBSD, you need to edit the file
+<filename>/etc/mail/mailer.conf</filename> instead of setting up a symbolic link as just
+described. A typical example of the contents of this file for running Exim is
+as follows:
+</para>
+<literallayout class="monospaced">
+sendmail            /usr/exim/bin/exim
+send-mail           /usr/exim/bin/exim
+mailq               /usr/exim/bin/exim -bp
+newaliases          /usr/bin/true
+</literallayout>
+<para>
+Once you have set up the symbolic link, or edited <filename>/etc/mail/mailer.conf</filename>,
+your Exim installation is <quote>live</quote>. Check it by sending a message from your
+favourite user agent.
+</para>
+<para>
+You should consider what to tell your users about the change of MTA. Exim may
+have different capabilities to what was previously running, and there are
+various operational differences such as the text of messages produced by
+command line options and in bounce messages. If you allow your users to make
+use of Exim&#x2019;s filtering capabilities, you should make the document entitled
+<emphasis>Exim&#x2019;s interface to mail filtering</emphasis> available to them.
+</para>
+</section>
+<section id="SECID36">
+<title>Upgrading Exim</title>
+<para>
+<indexterm role="concept">
+<primary>upgrading Exim</primary>
+</indexterm>
+If you are already running Exim on your host, building and installing a new
+version automatically makes it available to MUAs, or any other programs that
+call the MTA directly. However, if you are running an Exim daemon, you do need
+<indexterm role="concept">
+<primary>restart</primary>
+<secondary>on HUP signal</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>signal</primary>
+<secondary>HUP, to restart</secondary>
+</indexterm>
+to send it a HUP signal, to make it re-execute itself, and thereby pick up the
+new binary. You do not need to stop processing mail in order to install a new
+version of Exim. The install script does not modify an existing runtime
+configuration file.
+</para>
+</section>
+<section id="SECID37">
+<title>Stopping the Exim daemon on Solaris</title>
+<para>
+<indexterm role="concept">
+<primary>Solaris</primary>
+<secondary>stopping Exim on</secondary>
+</indexterm>
+The standard command for stopping the mailer daemon on Solaris is
+</para>
+<literallayout class="monospaced">
+/etc/init.d/sendmail stop
+</literallayout>
+<para>
+If <filename>/usr/lib/sendmail</filename> has been turned into a symbolic link, this script
+fails to stop Exim because it uses the command <emphasis>ps -e</emphasis> and greps the output
+for the text <quote>sendmail</quote>; this is not present because the actual program name
+(that is, <quote>exim</quote>) is given by the <emphasis>ps</emphasis> command with these options. A
+solution is to replace the line that finds the process id with something like
+</para>
+<literallayout class="monospaced">
+pid=`cat /var/spool/exim/exim-daemon.pid`
+</literallayout>
+<para>
+to obtain the daemon&#x2019;s pid directly from the file that Exim saves it in.
+</para>
+<para>
+Note, however, that stopping the daemon does not <quote>stop Exim</quote>. Messages can
+still be received from local processes, and if automatic delivery is configured
+(the normal case), deliveries will still occur.
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPcommandline">
+<title>The Exim command line</title>
+<para>
+<indexterm role="concept" id="IIDclo1" class="startofrange">
+<primary>command line</primary>
+<secondary>options</secondary>
+</indexterm>
+<indexterm role="concept" id="IIDclo2" class="startofrange">
+<primary>options</primary>
+<secondary>command line</secondary>
+</indexterm>
+Exim&#x2019;s command line takes the standard Unix form of a sequence of options,
+each starting with a hyphen character, followed by a number of arguments. The
+options are compatible with the main options of Sendmail, and there are also
+some additional options, some of which are compatible with Smail 3. Certain
+combinations of options do not make sense, and provoke an error if used.
+The form of the arguments depends on which options are set.
+</para>
+<section id="SECID38">
+<title>Setting options by program name</title>
+<para>
+<indexterm role="concept">
+<primary><emphasis>mailq</emphasis></primary>
+</indexterm>
+If Exim is called under the name <emphasis>mailq</emphasis>, it behaves as if the option <option>-bp</option>
+were present before any other options.
+The <option>-bp</option> option requests a listing of the contents of the mail queue on the
+standard output.
+This feature is for compatibility with some systems that contain a command of
+that name in one of the standard libraries, symbolically linked to
+<filename>/usr/sbin/sendmail</filename> or <filename>/usr/lib/sendmail</filename>.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>rsmtp</emphasis></primary>
+</indexterm>
+If Exim is called under the name <emphasis>rsmtp</emphasis> it behaves as if the option <option>-bS</option>
+were present before any other options, for compatibility with Smail. The
+<option>-bS</option> option is used for reading in a number of messages in batched SMTP
+format.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>rmail</emphasis></primary>
+</indexterm>
+If Exim is called under the name <emphasis>rmail</emphasis> it behaves as if the <option>-i</option> and
+<option>-oee</option> options were present before any other options, for compatibility with
+Smail. The name <emphasis>rmail</emphasis> is used as an interface by some UUCP systems.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>runq</emphasis></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+</indexterm>
+If Exim is called under the name <emphasis>runq</emphasis> it behaves as if the option <option>-q</option>
+were present before any other options, for compatibility with Smail. The <option>-q</option>
+option causes a single queue runner process to be started.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>newaliases</emphasis></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>alias file</primary>
+<secondary>building</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary>calling Exim as <emphasis>newaliases</emphasis></secondary>
+</indexterm>
+If Exim is called under the name <emphasis>newaliases</emphasis> it behaves as if the option
+<option>-bi</option> were present before any other options, for compatibility with Sendmail.
+This option is used for rebuilding Sendmail&#x2019;s alias file. Exim does not have
+the concept of a single alias file, but can be configured to run a given
+command if called with the <option>-bi</option> option.
+</para>
+</section>
+<section id="SECTtrustedadmin">
+<title>Trusted and admin users</title>
+<para>
+Some Exim options are available only to <emphasis>trusted users</emphasis> and others are
+available only to <emphasis>admin users</emphasis>. In the description below, the phrases <quote>Exim
+user</quote> and <quote>Exim group</quote> mean the user and group defined by EXIM_USER and
+EXIM_GROUP in <filename>Local/Makefile</filename> or set by the <option>exim_user</option> and
+<option>exim_group</option> options. These do not necessarily have to use the name <quote>exim</quote>.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>trusted users</primary>
+<secondary>definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>user</primary>
+<secondary>trusted definition of</secondary>
+</indexterm>
+The trusted users are root, the Exim user, any user listed in the
+<option>trusted_users</option> configuration option, and any user whose current group or any
+supplementary group is one of those listed in the <option>trusted_groups</option>
+configuration option. Note that the Exim group is not automatically trusted.
+</para>
+<para>
+<indexterm role="concept">
+<primary><quote>From</quote> line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope from</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope sender</primary>
+</indexterm>
+Trusted users are always permitted to use the <option>-f</option> option or a leading
+<quote>From&nbsp;</quote> line to specify the envelope sender of a message that is passed to
+Exim through the local interface (see the <option>-bm</option> and <option>-f</option> options below).
+See the <option>untrusted_set_sender</option> option for a way of permitting non-trusted
+users to set envelope senders.
+</para>
+<para>
+<indexterm role="concept">
+<primary><emphasis>From:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>From:</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>Sender:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>Sender:</secondary>
+</indexterm>
+For a trusted user, there is never any check on the contents of the <emphasis>From:</emphasis>
+header line, and a <emphasis>Sender:</emphasis> line is never added. Furthermore, any existing
+<emphasis>Sender:</emphasis> line in incoming local (non-TCP/IP) messages is not removed.
+</para>
+<para>
+Trusted users may also specify a host name, host address, interface address,
+protocol name, ident value, and authentication data when submitting a message
+locally. Thus, they are able to insert messages into Exim&#x2019;s queue locally that
+have the characteristics of messages received from a remote host. Untrusted
+users may in some circumstances use <option>-f</option>, but can never set the other values
+that are available to trusted users.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>user</primary>
+<secondary>admin definition of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>admin user</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The admin users are root, the Exim user, and any user that is a member of the
+Exim group or of any group listed in the <option>admin_groups</option> configuration option.
+The current group does not have to be one of these groups.
+</para>
+<para>
+Admin users are permitted to list the queue, and to carry out certain
+operations on messages, for example, to force delivery failures. It is also
+necessary to be an admin user in order to see the full information provided by
+the Exim monitor, and full debugging output.
+</para>
+<para>
+By default, the use of the <option>-M</option>, <option>-q</option>, <option>-R</option>, and <option>-S</option> options to cause
+Exim to attempt delivery of messages on its queue is restricted to admin users.
+However, this restriction can be relaxed by setting the <option>prod_requires_admin</option>
+option false (that is, specifying <option>no_prod_requires_admin</option>).
+</para>
+<para>
+Similarly, the use of the <option>-bp</option> option to list all the messages in the queue
+is restricted to admin users unless <option>queue_list_requires_admin</option> is set
+false.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<emphasis role="bold">Warning</emphasis>: If you configure your system so that admin users are able to
+edit Exim&#x2019;s configuration file, you are giving those users an easy way of
+getting root. There is further discussion of this issue at the start of chapter
+<xref linkend="CHAPconf"/>.
+</para>
+</section>
+<section id="SECID39">
+<title>Command line options</title>
+<para>
+Exim&#x2019;s command line options are described in alphabetical order below. If none
+of the options that specifies a specific action (such as starting the daemon or
+a queue runner, or testing an address, or receiving a message in a specific
+format, or listing the queue) are present, and there is at least one argument
+on the command line, <option>-bm</option> (accept a local message on the standard input,
+with the arguments specifying the recipients) is assumed. Otherwise, Exim
+outputs a brief message about itself and exits.
+</para>
+<!-- === Start of command line options === -->
+<variablelist>
+<varlistentry>
+<term><option>--</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary>--</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>command line; terminating</secondary>
+</indexterm>
+This is a pseudo-option whose only purpose is to terminate the options and
+therefore to cause subsequent command line items to be treated as arguments
+rather than options, even if they begin with hyphens.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>--help</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>--help</option></primary>
+</indexterm>
+This option causes Exim to output a few sentences stating what it is.
+The same output is generated if the Exim binary is called with no options and
+no arguments.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>--version</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>--version</option></primary>
+</indexterm>
+This option is an alias for <option>-bV</option> and causes version information to be
+displayed.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Ac</option></term>
+<term><option>-Am</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Ac</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>-Am</option></primary>
+</indexterm>
+These options are used by Sendmail for selecting configuration files and are
+ignored by Exim.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-B</option>&lt;<emphasis>type</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-B</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>8-bit characters</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary>8-bit characters</secondary>
+</indexterm>
+This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit
+clean; it ignores this option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bd</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bd</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>listener</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+</indexterm>
+This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually
+the <option>-bd</option> option is combined with the <option>-q</option>&lt;<emphasis>time</emphasis>&gt; option, to specify
+that the daemon should also initiate periodic queue runs.
+</para>
+<para>
+The <option>-bd</option> option can be used only by an admin user. If either of the <option>-d</option>
+(debugging) or <option>-v</option> (verifying) options are set, the daemon does not
+disconnect from the controlling terminal. When running this way, it can be
+stopped by pressing ctrl-C.
+</para>
+<para>
+By default, Exim listens for incoming connections to the standard SMTP port on
+all the host&#x2019;s running interfaces. However, it is possible to listen on other
+ports, on multiple ports, and only on specific interfaces. Chapter
+<xref linkend="CHAPinterfaces"/> contains a description of the options that control this.
+</para>
+<para>
+When a listening daemon
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>process id (pid)</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>pid (process id)</primary>
+<secondary>of daemon</secondary>
+</indexterm>
+is started without the use of <option>-oX</option> (that is, without overriding the normal
+configuration), it writes its process id to a file called <filename>exim-daemon.pid</filename>
+in Exim&#x2019;s spool directory. This location can be overridden by setting
+PID_FILE_PATH in <filename>Local/Makefile</filename>. The file is written while Exim is still
+running as root.
+</para>
+<para>
+When <option>-oX</option> is used on the command line to start a listening daemon, the
+process id is not written to the normal pid file path. However, <option>-oP</option> can be
+used to specify a path on the command line if a pid file is required.
+</para>
+<para>
+The SIGHUP signal
+<indexterm role="concept">
+<primary>SIGHUP</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>restart</primary>
+<secondary>on HUP signal</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>signal</primary>
+<secondary>HUP, to restart</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>restarting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>signal</primary>
+<secondary>to reload configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>reload configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>reload</primary>
+<secondary>configuration</secondary>
+</indexterm>
+can be used to cause the daemon to re-execute itself. This should be done
+whenever Exim&#x2019;s configuration file, or any file that is incorporated into it by
+means of the <option>.include</option> facility, is changed, and also whenever a new version
+of Exim is installed. It is not necessary to do this when other files that are
+referenced from the configuration (for example, alias files) are changed,
+because these are reread each time they are used.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bdf</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bdf</option></primary>
+</indexterm>
+This option has the same effect as <option>-bd</option> except that it never disconnects
+from the controlling terminal, even when no debugging is specified.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-be</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-be</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>string expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>testing</secondary>
+</indexterm>
+Run Exim in expansion testing mode. Exim discards its root privilege, to
+prevent ordinary users from using this mode to read otherwise inaccessible
+files. If no arguments are given, Exim runs interactively, prompting for lines
+of data. Otherwise, it processes each argument in turn.
+</para>
+<para>
+If Exim was built with USE_READLINE=yes in <filename>Local/Makefile</filename>, it tries
+to load the <option>libreadline</option> library dynamically whenever the <option>-be</option> option is
+used without command line arguments. If successful, it uses the <function>readline()</function>
+function, which provides extensive line-editing facilities, for reading the
+test data. A line history is supported.
+</para>
+<para>
+Long expansion expressions can be split over several lines by using backslash
+continuations. As in Exim&#x2019;s runtime configuration, white space at the start of
+continuation lines is ignored. Each argument or data line is passed through the
+string expansion mechanism, and the result is output. Variable values from the
+configuration file (for example, <varname>$qualify_domain</varname>) are available, but no
+message-specific values (such as <varname>$message_exim_id</varname>) are set, because no message
+is being processed (but see <option>-bem</option> and <option>-Mset</option>).
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: If you use this mechanism to test lookups, and you change the data
+files or databases you are using, you must exit and restart Exim before trying
+the same lookup again. Otherwise, because each Exim process caches the results
+of lookups, you will just get the same result as before.
+</para>
+<para>
+Macro processing is done on lines before string-expansion: new macros can be
+defined and macros will be expanded.
+Because macros in the config file are often used for secrets, those are only
+available to admin users.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bem</option>&nbsp;&lt;<emphasis>filename</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bem</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>string expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>testing</secondary>
+</indexterm>
+This option operates like <option>-be</option> except that it must be followed by the name
+of a file. For example:
+</para>
+<literallayout class="monospaced">
+exim -bem /tmp/testmessage
+</literallayout>
+<para>
+The file is read as a message (as if receiving a locally-submitted non-SMTP
+message) before any of the test expansions are done. Thus, message-specific
+variables such as <varname>$message_size</varname> and <varname>$header_from:</varname> are available. However,
+no <emphasis>Received:</emphasis> header is added to the message. If the <option>-t</option> option is set,
+recipients are read from the headers in the normal way, and are shown in the
+<varname>$recipients</varname> variable. Note that recipients cannot be given on the command
+line, because further arguments are taken as strings to expand (just like
+<option>-be</option>).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bF</option>&nbsp;&lt;<emphasis>filename</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bF</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>system filter</primary>
+<secondary>testing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>system filter</secondary>
+</indexterm>
+This option is the same as <option>-bf</option> except that it assumes that the filter being
+tested is a system filter. The additional commands that are available only in
+system filters are recognized.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bf</option>&nbsp;&lt;<emphasis>filename</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bf</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>filter</primary>
+<secondary>testing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>filter file</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>forward file</primary>
+<secondary>testing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>forward file</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+<secondary>testing</secondary>
+</indexterm>
+This option runs Exim in user filter testing mode; the file is the filter file
+to be tested, and a test message must be supplied on the standard input. If
+there are no message-dependent tests in the filter, an empty file can be
+supplied.
+</para>
+<para>
+If you want to test a system filter file, use <option>-bF</option> instead of <option>-bf</option>. You
+can use both <option>-bF</option> and <option>-bf</option> on the same command, in order to test a system
+filter and a user filter in the same run. For example:
+</para>
+<literallayout class="monospaced">
+exim -bF /system/filter -bf /user/filter &lt;/test/message
+</literallayout>
+<para>
+This is helpful when the system filter adds header lines or sets filter
+variables that are used by the user filter.
+</para>
+<para>
+If the test filter file does not begin with one of the special lines
+</para>
+<literallayout class="monospaced">
+# Exim filter
+# Sieve filter
+</literallayout>
+<para>
+it is taken to be a normal <filename>.forward</filename> file, and is tested for validity under
+that interpretation. See sections <xref linkend="SECTitenonfilred"/> to
+<xref linkend="SECTspecitredli"/> for a description of the possible contents of non-filter
+redirection lists.
+</para>
+<para>
+The result of an Exim command that uses <option>-bf</option>, provided no errors are
+detected, is a list of the actions that Exim would try to take if presented
+with the message for real. More details of filter testing are given in the
+separate document entitled <emphasis>Exim&#x2019;s interfaces to mail filtering</emphasis>.
+</para>
+<para>
+When testing a filter file,
+<indexterm role="concept">
+<primary><quote>From</quote> line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope from</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope sender</primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>-f</option></primary>
+<secondary>for filter testing</secondary>
+</indexterm>
+the envelope sender can be set by the <option>-f</option> option,
+or by a <quote>From&nbsp;</quote> line at the start of the test message. Various parameters
+that would normally be taken from the envelope recipient address of the message
+can be set by means of additional command line options (see the next four
+options).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bfd</option>&nbsp;&lt;<emphasis>domain</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bfd</option></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$qualify_domain</varname></primary>
+</indexterm>
+This sets the domain of the recipient address when a filter file is being
+tested by means of the <option>-bf</option> option. The default is the value of
+<varname>$qualify_domain</varname>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bfl</option>&nbsp;&lt;<emphasis>local&nbsp;part</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bfl</option></primary>
+</indexterm>
+This sets the local part of the recipient address when a filter file is being
+tested by means of the <option>-bf</option> option. The default is the username of the
+process that calls Exim. A local part should be specified with any prefix or
+suffix stripped, because that is how it appears to the filter when a message is
+actually being delivered.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bfp</option>&nbsp;&lt;<emphasis>prefix</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bfp</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>affix</primary>
+<secondary>filter testing</secondary>
+</indexterm>
+This sets the prefix of the local part of the recipient address when a filter
+file is being tested by means of the <option>-bf</option> option. The default is an empty
+prefix.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bfs</option>&nbsp;&lt;<emphasis>suffix</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bfs</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>affix</primary>
+<secondary>filter testing</secondary>
+</indexterm>
+This sets the suffix of the local part of the recipient address when a filter
+file is being tested by means of the <option>-bf</option> option. The default is an empty
+suffix.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bh</option>&nbsp;&lt;<emphasis>IP&nbsp;address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bh</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>incoming SMTP</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>testing incoming</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>relay control</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>relaying</primary>
+<secondary>testing configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>policy control</primary>
+<secondary>testing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary><option>-bh</option> option</secondary>
+</indexterm>
+This option runs a fake SMTP session as if from the given IP address, using the
+standard input and output. The IP address may include a port number at the end,
+after a full stop. For example:
+</para>
+<literallayout class="monospaced">
+exim -bh 10.9.8.7.1234
+exim -bh fe80::a00:20ff:fe86:a061.5678
+</literallayout>
+<para>
+When an IPv6 address is given, it is converted into canonical form. In the case
+of the second example above, the value of <varname>$sender_host_address</varname> after
+conversion to the canonical form is
+<literal>fe80:0000:0000:0a00:20ff:fe86:a061.5678</literal>.
+</para>
+<para>
+Comments as to what is going on are written to the standard error file. These
+include lines beginning with <quote>LOG</quote> for anything that would have been logged.
+This facility is provided for testing configuration options for incoming
+messages, to make sure they implement the required policy. For example, you can
+test your relay controls using <option>-bh</option>.
+</para>
+<para>
+<emphasis role="bold">Warning 1</emphasis>:
+<indexterm role="concept">
+<primary>RFC 1413</primary>
+</indexterm>
+You can test features of the configuration that rely on ident (RFC 1413)
+information by using the <option>-oMt</option> option. However, Exim cannot actually perform
+an ident callout when testing using <option>-bh</option> because there is no incoming SMTP
+connection.
+</para>
+<para>
+<emphasis role="bold">Warning 2</emphasis>: Address verification callouts (see section <xref linkend="SECTcallver"/>)
+are also skipped when testing using <option>-bh</option>. If you want these callouts to
+occur, use <option>-bhc</option> instead.
+</para>
+<para>
+Messages supplied during the testing session are discarded, and nothing is
+written to any of the real log files. There may be pauses when DNS (and other)
+lookups are taking place, and of course these may time out. The <option>-oMi</option> option
+can be used to specify a specific IP interface and port if this is important,
+and <option>-oMaa</option> and <option>-oMai</option> can be used to set parameters as if the SMTP
+session were authenticated.
+</para>
+<para>
+The <emphasis>exim_checkaccess</emphasis> utility is a <quote>packaged</quote> version of <option>-bh</option> whose
+output just states whether a given recipient address from a given host is
+acceptable or not. See section <xref linkend="SECTcheckaccess"/>.
+</para>
+<para>
+Features such as authentication and encryption, where the client input is not
+plain text, cannot easily be tested with <option>-bh</option>. Instead, you should use a
+specialized SMTP test program such as
+<emphasis role="bold"><ulink url="https://www.jetmore.org/john/code/swaks/">swaks</ulink></emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bhc</option>&nbsp;&lt;<emphasis>IP&nbsp;address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bhc</option></primary>
+</indexterm>
+This option operates in the same way as <option>-bh</option>, except that address
+verification callouts are performed if required. This includes consulting and
+updating the callout cache database.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bi</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bi</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>alias file</primary>
+<secondary>building</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>building alias file</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-bi</option> option</secondary>
+</indexterm>
+Sendmail interprets the <option>-bi</option> option as a request to rebuild its alias file.
+Exim does not have the concept of a single alias file, and so it cannot mimic
+this behaviour. However, calls to <filename>/usr/lib/sendmail</filename> with the <option>-bi</option> option
+tend to appear in various scripts such as NIS make files, so the option must be
+recognized.
+</para>
+<para>
+If <option>-bi</option> is encountered, the command specified by the <option>bi_command</option>
+configuration option is run, under the uid and gid of the caller of Exim. If
+the <option>-oA</option> option is used, its value is passed to the command as an argument.
+The command set by <option>bi_command</option> may not contain arguments. The command can
+use the <emphasis>exim_dbmbuild</emphasis> utility, or some other means, to rebuild alias files
+if this is required. If the <option>bi_command</option> option is not set, calling Exim with
+<option>-bi</option> is a no-op.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bI:help</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bI:help</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>querying exim information</primary>
+</indexterm>
+We shall provide various options starting <literal>-bI:</literal> for querying Exim for
+information.  The output of many of these will be intended for machine
+consumption.  This one is not.  The <option>-bI:help</option> option asks Exim for a
+synopsis of supported options beginning <literal>-bI:</literal>.  Use of any of these
+options shall cause Exim to exit after producing the requested output.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bI:dscp</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bI:dscp</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>DSCP</primary>
+<secondary>values</secondary>
+</indexterm>
+This option causes Exim to emit an alphabetically sorted list of all
+recognised DSCP names.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bI:sieve</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bI:sieve</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+<secondary>capabilities</secondary>
+</indexterm>
+This option causes Exim to emit an alphabetically sorted list of all supported
+Sieve protocol extensions on stdout, one per line.  This is anticipated to be
+useful for ManageSieve (RFC 5804) implementations, in providing that protocol&#x2019;s
+<literal>SIEVE</literal> capability response line.  As the precise list may depend upon
+compile-time build options, which this option will adapt to, this is the only
+way to guarantee a correct response.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bm</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bm</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>local message reception</primary>
+</indexterm>
+This option runs an Exim receiving process that accepts an incoming,
+locally-generated message on the standard input. The recipients are given as the
+command arguments (except when <option>-t</option> is also present &ndash; see below). Each
+argument can be a comma-separated list of RFC 2822 addresses. This is the
+default option for selecting the overall action of an Exim call; it is assumed
+if no other conflicting option is present.
+</para>
+<para>
+If any addresses in the message are unqualified (have no domain), they are
+qualified by the values of the <option>qualify_domain</option> or <option>qualify_recipient</option>
+options, as appropriate. The <option>-bnq</option> option (see below) provides a way of
+suppressing this for special cases.
+</para>
+<para>
+Policy checks on the contents of local messages can be enforced by means of
+the non-SMTP ACL. See chapter <xref linkend="CHAPACL"/> for details.
+</para>
+<para>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-bm</option></secondary>
+</indexterm>
+The return code is zero if the message is successfully accepted. Otherwise, the
+action is controlled by the <option>-oe</option><emphasis>x</emphasis> option setting &ndash; see below.
+</para>
+<para>
+The format
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>format</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>message</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><quote>From</quote> line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>UUCP</primary>
+<secondary><quote>From</quote> line</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><quote>From</quote> line</secondary>
+</indexterm>
+of the message must be as defined in RFC 2822, except that, for
+compatibility with Sendmail and Smail, a line in one of the forms
+</para>
+<literallayout class="monospaced">
+From sender Fri Jan  5 12:55 GMT 1997
+From sender Fri, 5 Jan 97 12:55:01
+</literallayout>
+<para>
+(with the weekday optional, and possibly with additional text after the date)
+is permitted to appear at the start of the message. There appears to be no
+authoritative specification of the format of this line. Exim recognizes it by
+matching against the regular expression defined by the <option>uucp_from_pattern</option>
+option, which can be changed if necessary.
+</para>
+<para>
+<indexterm role="option">
+<primary><option>-f</option></primary>
+<secondary>overriding <quote>From</quote> line</secondary>
+</indexterm>
+The specified sender is treated as if it were given as the argument to the
+<option>-f</option> option, but if a <option>-f</option> option is also present, its argument is used in
+preference to the address taken from the message. The caller of Exim must be a
+trusted user for the sender of a message to be set in this way.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bmalware</option>&nbsp;&lt;<emphasis>filename</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bmalware</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>,</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>malware scan test</primary>
+</indexterm>
+This debugging option causes Exim to scan the given file or directory
+(depending on the used scanner interface),
+using the malware scanning framework.  The option of <option>av_scanner</option> influences
+this option, so if <option>av_scanner</option>&#x2019;s value is dependent upon an expansion then
+the expansion should have defaults which apply to this invocation.  ACLs are
+not invoked, so if <option>av_scanner</option> references an ACL variable then that variable
+will never be populated and <option>-bmalware</option> will fail.
+</para>
+<para>
+Exim will have changed working directory before resolving the filename, so
+using fully qualified pathnames is advisable.  Exim will be running as the Exim
+user when it tries to open the file, rather than as the invoking user.
+This option requires admin privileges.
+</para>
+<para>
+The <option>-bmalware</option> option will not be extended to be more generally useful,
+there are better tools for file-scanning.  This option exists to help
+administrators verify their Exim and AV scanner configuration.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bnq</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bnq</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>address qualification, suppressing</primary>
+</indexterm>
+By default, Exim automatically qualifies unqualified addresses (those
+without domains) that appear in messages that are submitted locally (that
+is, not over TCP/IP). This qualification applies both to addresses in
+envelopes, and addresses in header lines. Sender addresses are qualified using
+<option>qualify_domain</option>, and recipient addresses using <option>qualify_recipient</option> (which
+defaults to the value of <option>qualify_domain</option>).
+</para>
+<para>
+Sometimes, qualification is not wanted. For example, if <option>-bS</option> (batch SMTP) is
+being used to re-submit messages that originally came from remote hosts after
+content scanning, you probably do not want to qualify unqualified addresses in
+header lines. (Such lines will be present only if you have not enabled a header
+syntax check in the appropriate ACL.)
+</para>
+<para>
+The <option>-bnq</option> option suppresses all qualification of unqualified addresses in
+messages that originate on the local host. When this is used, unqualified
+addresses in the envelope provoke errors (causing message rejection) and
+unqualified addresses in header lines are left alone.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bP</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bP</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration options</primary>
+<secondary>extracting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>configuration &ndash; extracting</secondary>
+</indexterm>
+If this option is given with no arguments, it causes the values of all Exim&#x2019;s
+main configuration options to be written to the standard output. The values
+of one or more specific options can be requested by giving their names as
+arguments, for example:
+</para>
+<literallayout class="monospaced">
+exim -bP qualify_domain hold_domains
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>hiding configuration option values</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration options</primary>
+<secondary>hiding value of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>hiding value of</secondary>
+</indexterm>
+However, any option setting that is preceded by the word <quote>hide</quote> in the
+configuration file is not shown in full, except to an admin user. For other
+users, the output is as in this example:
+</para>
+<literallayout class="monospaced">
+mysql_servers = &lt;value not displayable&gt;
+</literallayout>
+<para>
+If <option>config</option> is given as an argument, the config is
+output, as it was parsed, any include file resolved, any comment removed.
+</para>
+<para>
+If <option>config_file</option> is given as an argument, the name of the runtime
+configuration file is output. (<option>configure_file</option> works too, for
+backward compatibility.)
+If a list of configuration files was supplied, the value that is output here
+is the name of the file that was actually used.
+</para>
+<para>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>hiding name of</secondary>
+</indexterm>
+If the <option>-n</option> flag is given, then for most modes of <option>-bP</option> operation the
+name will not be output.
+</para>
+<para>
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>process id (pid)</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>pid (process id)</primary>
+<secondary>of daemon</secondary>
+</indexterm>
+If <option>log_file_path</option> or <option>pid_file_path</option> are given, the names of the
+directories where log files and daemon pid files are written are output,
+respectively. If these values are unset, log files are written in a
+sub-directory of the spool directory called <option>log</option>, and the pid file is
+written directly into the spool directory.
+</para>
+<para>
+If <option>-bP</option> is followed by a name preceded by <literal>+</literal>, for example,
+</para>
+<literallayout class="monospaced">
+exim -bP +local_domains
+</literallayout>
+<para>
+it searches for a matching named list of any type (domain, host, address, or
+local part) and outputs what it finds.
+</para>
+<para>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>router &ndash; extracting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>transport &ndash; extracting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>authenticator &ndash; extracting</secondary>
+</indexterm>
+If one of the words <option>router</option>, <option>transport</option>, or <option>authenticator</option> is given,
+followed by the name of an appropriate driver instance, the option settings for
+that driver are output. For example:
+</para>
+<literallayout class="monospaced">
+exim -bP transport local_delivery
+</literallayout>
+<para>
+The generic driver options are output first, followed by the driver&#x2019;s private
+options. A list of the names of drivers of a particular type can be obtained by
+using one of the words <option>router_list</option>, <option>transport_list</option>, or
+<option>authenticator_list</option>, and a complete list of all drivers with their option
+settings can be obtained by using <option>routers</option>, <option>transports</option>, or
+<option>authenticators</option>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>environment</primary>
+</indexterm>
+If <option>environment</option> is given as an argument, the set of environment
+variables is output, line by line. Using the <option>-n</option> flag suppresses the value of the
+variables.
+</para>
+<para>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>macro &ndash; extracting</secondary>
+</indexterm>
+If invoked by an admin user, then <option>macro</option>, <option>macro_list</option> and <option>macros</option>
+are available, similarly to the drivers.  Because macros are sometimes used
+for storing passwords, this option is restricted.
+The output format is one item per line.
+For the "-bP macro &lt;name&gt;" form, if no such macro is found
+the exit status will be nonzero.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bp</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bp</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>listing messages in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>listing</primary>
+<secondary>messages in the queue</secondary>
+</indexterm>
+This option requests a listing of the contents of the mail queue on the
+standard output. If the <option>-bp</option> option is followed by a list of message ids,
+just those messages are listed. By default, this option can be used only by an
+admin user. However, the <option>queue_list_requires_admin</option> option can be set false
+to allow any user to see the queue.
+</para>
+<para>
+Each message in the queue is displayed as in the following example:
+</para>
+<literallayout class="monospaced">
+25m  2.9K 0t5C6f-0000c8-00 &lt;alice@???&gt;
+          red.king@???
+          &lt;other addresses&gt;
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>size in queue listing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>size</primary>
+<secondary>of message</secondary>
+</indexterm>
+The first line contains the length of time the message has been in the queue
+(in this case 25 minutes), the size of the message (2.9K), the unique local
+identifier for the message, and the message sender, as contained in the
+envelope. For bounce messages, the sender address is empty, and appears as
+<quote>&lt;&gt;</quote>. If the message was submitted locally by an untrusted user who overrode
+the default sender address, the user&#x2019;s login name is shown in parentheses
+before the sender address.
+</para>
+<para>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>in queue listing</secondary>
+</indexterm>
+If the message is frozen (attempts to deliver it are suspended) then the text
+<quote>*** frozen ***</quote> is displayed at the end of this line.
+</para>
+<para>
+The recipients of the message (taken from the envelope, not the headers) are
+displayed on subsequent lines. Those addresses to which the message has already
+been delivered are marked with the letter D. If an original address gets
+expanded into several addresses via an alias or forward file, the original is
+displayed with a D only when deliveries for all of its child addresses are
+complete.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpa</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpa</option></primary>
+</indexterm>
+This option operates like <option>-bp</option>, but in addition it shows delivered addresses
+that were generated from the original top level address(es) in each message by
+alias or forwarding operations. These addresses are flagged with <quote>+D</quote> instead
+of just <quote>D</quote>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpc</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpc</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>count of messages on</secondary>
+</indexterm>
+This option counts the number of messages in the queue, and writes the total
+to the standard output. It is restricted to admin users, unless
+<option>queue_list_requires_admin</option> is set false.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpr</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpr</option></primary>
+</indexterm>
+This option operates like <option>-bp</option>, but the output is not sorted into
+chronological order of message arrival. This can speed it up when there are
+lots of messages in the queue, and is particularly useful if the output is
+going to be post-processed in a way that doesn&#x2019;t need the sorting.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpra</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpra</option></primary>
+</indexterm>
+This option is a combination of <option>-bpr</option> and <option>-bpa</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpru</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpru</option></primary>
+</indexterm>
+This option is a combination of <option>-bpr</option> and <option>-bpu</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bpu</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bpu</option></primary>
+</indexterm>
+This option operates like <option>-bp</option> but shows only undelivered top-level
+addresses for each message displayed. Addresses generated by aliasing or
+forwarding are not shown, unless the message was deferred after processing by a
+router with the <option>one_time</option> option set.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-brt</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-brt</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>retry configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>retry</primary>
+<secondary>configuration testing</secondary>
+</indexterm>
+This option is for testing retry rules, and it must be followed by up to three
+arguments. It causes Exim to look for a retry rule that matches the values
+and to write it to the standard output. For example:
+</para>
+<literallayout class="monospaced">
+exim -brt bach.comp.mus.example
+Retry rule: *.comp.mus.example  F,2h,15m; F,4d,30m;
+</literallayout>
+<para>
+See chapter <xref linkend="CHAPretry"/> for a description of Exim&#x2019;s retry rules. The first
+argument, which is required, can be a complete address in the form
+<emphasis>local_part@domain</emphasis>, or it can be just a domain name. If the second argument
+contains a dot, it is interpreted as an optional second domain name; if no
+retry rule is found for the first argument, the second is tried. This ties in
+with Exim&#x2019;s behaviour when looking for retry rules for remote hosts &ndash; if no
+rule is found that matches the host, one that matches the mail domain is
+sought. Finally, an argument that is the name of a specific delivery error, as
+used in setting up retry rules, can be given. For example:
+</para>
+<literallayout class="monospaced">
+exim -brt haydn.comp.mus.example quota_3d
+Retry rule: *@haydn.comp.mus.example quota_3d  F,1h,15m
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-brw</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-brw</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>rewriting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>rewriting</primary>
+<secondary>testing</secondary>
+</indexterm>
+This option is for testing address rewriting rules, and it must be followed by
+a single argument, consisting of either a local part without a domain, or a
+complete address with a fully qualified domain. Exim outputs how this address
+would be rewritten for each possible place it might appear. See chapter
+<xref linkend="CHAPrewrite"/> for further details.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bS</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bS</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>batched incoming</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>batched SMTP input</primary>
+</indexterm>
+This option is used for batched SMTP input, which is an alternative interface
+for non-interactive local message submission. A number of messages can be
+submitted in a single run. However, despite its name, this is not really SMTP
+input. Exim reads each message&#x2019;s envelope from SMTP commands on the standard
+input, but generates no responses. If the caller is trusted, or
+<option>untrusted_set_sender</option> is set, the senders in the SMTP MAIL commands are
+believed; otherwise the sender is always the caller of Exim.
+</para>
+<para>
+The message itself is read from the standard input, in SMTP format (leading
+dots doubled), terminated by a line containing just a single dot. An error is
+provoked if the terminating dot is missing. A further message may then follow.
+</para>
+<para>
+As for other local message submissions, the contents of incoming batch SMTP
+messages can be checked using the non-SMTP ACL (see chapter <xref linkend="CHAPACL"/>).
+Unqualified addresses are automatically qualified using <option>qualify_domain</option> and
+<option>qualify_recipient</option>, as appropriate, unless the <option>-bnq</option> option is used.
+</para>
+<para>
+Some other SMTP commands are recognized in the input. HELO and EHLO act
+as RSET; VRFY, EXPN, ETRN, and HELP act as NOOP;
+QUIT quits, ignoring the rest of the standard input.
+</para>
+<para>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-bS</option></secondary>
+</indexterm>
+If any error is encountered, reports are written to the standard output and
+error streams, and Exim gives up immediately. The return code is 0 if no error
+was detected; it is 1 if one or more messages were accepted before the error
+was detected; otherwise it is 2.
+</para>
+<para>
+More details of input using batched SMTP are given in section
+<xref linkend="SECTincomingbatchedSMTP"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bs</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bs</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>local input</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>local SMTP input</primary>
+</indexterm>
+This option causes Exim to accept one or more messages by reading SMTP commands
+on the standard input, and producing SMTP replies on the standard output. SMTP
+policy controls, as defined in ACLs (see chapter <xref linkend="CHAPACL"/>) are applied.
+Some user agents use this interface as a way of passing locally-generated
+messages to the MTA.
+</para>
+<para>
+In
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>source of</secondary>
+</indexterm>
+this usage, if the caller of Exim is trusted, or <option>untrusted_set_sender</option> is
+set, the senders of messages are taken from the SMTP MAIL commands.
+Otherwise the content of these commands is ignored and the sender is set up as
+the calling user. Unqualified addresses are automatically qualified using
+<option>qualify_domain</option> and <option>qualify_recipient</option>, as appropriate, unless the
+<option>-bnq</option> option is used.
+</para>
+<para>
+<indexterm role="concept">
+<primary>inetd</primary>
+</indexterm>
+The
+<option>-bs</option> option is also used to run Exim from <emphasis>inetd</emphasis>, as an alternative to
+using a listening daemon. Exim can distinguish the two cases by checking
+whether the standard input is a TCP/IP socket. When Exim is called from
+<emphasis>inetd</emphasis>, the source of the mail is assumed to be remote, and the comments
+above concerning senders and qualification do not apply. In this situation,
+Exim behaves in exactly the same way as it does when receiving a message via
+the listening daemon.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bt</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bt</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>addresses</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address</primary>
+<secondary>testing</secondary>
+</indexterm>
+This option runs Exim in address testing mode, in which each argument is taken
+as a recipient address to be tested for deliverability. The results are
+written to the standard output. If a test fails, and the caller is not an admin
+user, no details of the failure are output, because these might contain
+sensitive information such as usernames and passwords for database lookups.
+</para>
+<para>
+If no arguments are given, Exim runs in an interactive manner, prompting with a
+right angle bracket for addresses to be tested.
+</para>
+<para>
+Unlike the <option>-be</option> test option, you cannot arrange for Exim to use the
+<function>readline()</function> function, because it is running as <emphasis>root</emphasis> and there are
+security issues.
+</para>
+<para>
+Each address is handled as if it were the recipient address of a message
+(compare the <option>-bv</option> option). It is passed to the routers and the result is
+written to the standard output. However, any router that has
+<option>no_address_test</option> set is bypassed. This can make <option>-bt</option> easier to use for
+genuine routing tests if your first router passes everything to a scanner
+program.
+</para>
+<para>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-bt</option></secondary>
+</indexterm>
+The return code is 2 if any address failed outright; it is 1 if no address
+failed outright but at least one could not be resolved for some reason. Return
+code 0 is given only when all addresses succeed.
+</para>
+<para>
+<indexterm role="concept">
+<primary>duplicate addresses</primary>
+</indexterm>
+<emphasis role="bold">Note</emphasis>: When actually delivering a message, Exim removes duplicate recipient
+addresses after routing is complete, so that only one delivery takes place.
+This does not happen when testing with <option>-bt</option>; the full results of routing are
+always shown.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: <option>-bt</option> can only do relatively simple testing. If any of the
+routers in the configuration makes any tests on the sender address of a
+message,
+<indexterm role="option">
+<primary><option>-f</option></primary>
+<secondary>for address testing</secondary>
+</indexterm>
+you can use the <option>-f</option> option to set an appropriate sender when running
+<option>-bt</option> tests. Without it, the sender is assumed to be the calling user at the
+default qualifying domain. However, if you have set up (for example) routers
+whose behaviour depends on the contents of an incoming message, you cannot test
+those conditions using <option>-bt</option>. The <option>-N</option> option provides a possible way of
+doing such tests.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bV</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bV</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>version number of Exim</primary>
+</indexterm>
+This option causes Exim to write the current version number, compilation
+number, and compilation date of the <emphasis>exim</emphasis> binary to the standard output.
+It also lists the DBM library that is being used, the optional modules (such as
+specific lookup types), the drivers that are included in the binary, and the
+name of the runtime configuration file that is in use.
+</para>
+<para>
+As part of its operation, <option>-bV</option> causes Exim to read and syntax check its
+configuration file. However, this is a static check only. It cannot check
+values that are to be expanded. For example, although a misspelt ACL verb is
+detected, an error in the verb&#x2019;s arguments is not. You cannot rely on <option>-bV</option>
+alone to discover (for example) all the typos in the configuration; some
+realistic testing is needed. The <option>-bh</option> and <option>-N</option> options provide more
+dynamic testing facilities.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bv</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bv</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>verifying address</primary>
+<secondary>using <option>-bv</option></secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address</primary>
+<secondary>verification</secondary>
+</indexterm>
+This option runs Exim in address verification mode, in which each argument is
+taken as a recipient address to be verified by the routers. (This does
+not involve any verification callouts). During normal operation, verification
+happens mostly as a consequence processing a <option>verify</option> condition in an ACL
+(see chapter <xref linkend="CHAPACL"/>). If you want to test an entire ACL, possibly
+including callouts, see the <option>-bh</option> and <option>-bhc</option> options.
+</para>
+<para>
+If verification fails, and the caller is not an admin user, no details of the
+failure are output, because these might contain sensitive information such as
+usernames and passwords for database lookups.
+</para>
+<para>
+If no arguments are given, Exim runs in an interactive manner, prompting with a
+right angle bracket for addresses to be verified.
+</para>
+<para>
+Unlike the <option>-be</option> test option, you cannot arrange for Exim to use the
+<function>readline()</function> function, because it is running as <emphasis>exim</emphasis> and there are
+security issues.
+</para>
+<para>
+Verification differs from address testing (the <option>-bt</option> option) in that routers
+that have <option>no_verify</option> set are skipped, and if the address is accepted by a
+router that has <option>fail_verify</option> set, verification fails. The address is
+verified as a recipient if <option>-bv</option> is used; to test verification for a sender
+address, <option>-bvs</option> should be used.
+</para>
+<para>
+If the <option>-v</option> option is not set, the output consists of a single line for each
+address, stating whether it was verified or not, and giving a reason in the
+latter case. Without <option>-v</option>, generating more than one address by redirection
+causes verification to end successfully, without considering the generated
+addresses. However, if just one address is generated, processing continues,
+and the generated address must verify successfully for the overall verification
+to succeed.
+</para>
+<para>
+When <option>-v</option> is set, more details are given of how the address has been handled,
+and in the case of address redirection, all the generated addresses are also
+considered. Verification may succeed for some and fail for others.
+</para>
+<para>
+The
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-bv</option></secondary>
+</indexterm>
+return code is 2 if any address failed outright; it is 1 if no address
+failed outright but at least one could not be resolved for some reason. Return
+code 0 is given only when all addresses succeed.
+</para>
+<para>
+If any of the routers in the configuration makes any tests on the sender
+address of a message, you should use the <option>-f</option> option to set an appropriate
+sender when running <option>-bv</option> tests. Without it, the sender is assumed to be the
+calling user at the default qualifying domain.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bvs</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bvs</option></primary>
+</indexterm>
+This option acts like <option>-bv</option>, but verifies the address as a sender rather
+than a recipient address. This affects any rewriting and qualification that
+might happen.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-bw</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-bw</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>inetd</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>inetd</primary>
+<secondary>wait mode</secondary>
+</indexterm>
+This option runs Exim as a daemon, awaiting incoming SMTP connections,
+similarly to the <option>-bd</option> option.  All port specifications on the command-line
+and in the configuration file are ignored.  Queue-running may not be specified.
+</para>
+<para>
+In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is
+listening for connections.  This permits the system to start up and have
+inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for
+each port only when the first connection is received.
+</para>
+<para>
+If the option is given as <option>-bw</option>&lt;<emphasis>time</emphasis>&gt; then the time is a timeout, after
+which the daemon will exit, which should cause inetd to listen once more.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-C</option>&nbsp;&lt;<emphasis>filelist</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-C</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>alternate</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>CONFIGURE_FILE</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>alternate configuration file</primary>
+</indexterm>
+This option causes Exim to find the runtime configuration file from the given
+list instead of from the list specified by the CONFIGURE_FILE
+compile-time setting. Usually, the list will consist of just a single filename,
+but it can be a colon-separated list of names. In this case, the first
+file that exists is used. Failure to open an existing file stops Exim from
+proceeding any further along the list, and an error is generated.
+</para>
+<para>
+When this option is used by a caller other than root, and the list is different
+from the compiled-in list, Exim gives up its root privilege immediately, and
+runs with the real and effective uid and gid set to those of the caller.
+However, if a TRUSTED_CONFIG_LIST file is defined in <filename>Local/Makefile</filename>, that
+file contains a list of full pathnames, one per line, for configuration files
+which are trusted. Root privilege is retained for any configuration file so
+listed, as long as the caller is the Exim user (or the user specified in the
+CONFIGURE_OWNER option, if any), and as long as the configuration file is
+not writeable by inappropriate users or groups.
+</para>
+<para>
+Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a
+configuration using <option>-C</option> right through message reception and delivery,
+even if the caller is root. The reception works, but by that time, Exim is
+running as the Exim user, so when it re-executes to regain privilege for the
+delivery, the use of <option>-C</option> causes privilege to be lost. However, root can
+test reception and delivery using two separate commands (one to put a message
+in the queue, using <option>-odq</option>, and another to do the delivery, using <option>-M</option>).
+</para>
+<para>
+If ALT_CONFIG_PREFIX is defined <filename>in Local/Makefile</filename>, it specifies a
+prefix string with which any file named in a <option>-C</option> command line option
+must start. In addition, the filename must not contain the sequence <literal>/../</literal>.
+However, if the value of the <option>-C</option> option is identical to the value of
+CONFIGURE_FILE in <filename>Local/Makefile</filename>, Exim ignores <option>-C</option> and proceeds as
+usual. There is no default setting for ALT_CONFIG_PREFIX; when it is
+unset, any filename can be used with <option>-C</option>.
+</para>
+<para>
+ALT_CONFIG_PREFIX can be used to confine alternative configuration files
+to a directory to which only root has access. This prevents someone who has
+broken into the Exim account from running a privileged Exim with an arbitrary
+configuration file.
+</para>
+<para>
+The <option>-C</option> facility is useful for ensuring that configuration files are
+syntactically correct, but cannot be used for test deliveries, unless the
+caller is privileged, or unless it is an exotic configuration that does not
+require privilege. No check is made on the owner or group of the files
+specified by this option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-D</option>&lt;<emphasis>macro</emphasis>&gt;=&lt;<emphasis>value</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-D</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>macro</primary>
+<secondary>setting on command line</secondary>
+</indexterm>
+This option can be used to override macro definitions in the configuration file
+(see section <xref linkend="SECTmacrodefs"/>). However, like <option>-C</option>, if it is used by an
+unprivileged caller, it causes Exim to give up its root privilege.
+If DISABLE_D_OPTION is defined in <filename>Local/Makefile</filename>, the use of <option>-D</option> is
+completely disabled, and its use causes an immediate error exit.
+</para>
+<para>
+If WHITELIST_D_MACROS is defined in <filename>Local/Makefile</filename> then it should be a
+colon-separated list of macros which are considered safe and, if <option>-D</option> only
+supplies macros from this list, and the values are acceptable, then Exim will
+not give up root privilege if the caller is root, the Exim run-time user, or
+the CONFIGURE_OWNER, if set.  This is a transition mechanism and is expected
+to be removed in the future.  Acceptable values for the macros satisfy the
+regexp: <literal>^[A-Za-z0-9_/.-]*$</literal>
+</para>
+<para>
+The entire option (including equals sign if present) must all be within one
+command line item. <option>-D</option> can be used to set the value of a macro to the empty
+string, in which case the equals sign is optional. These two commands are
+synonymous:
+</para>
+<literallayout class="monospaced">
+exim -DABC  ...
+exim -DABC= ...
+</literallayout>
+<para>
+To include spaces in a macro definition item, quotes must be used. If you use
+quotes, spaces are permitted around the macro name and the equals sign. For
+example:
+</para>
+<literallayout class="monospaced">
+exim '-D ABC = something' ...
+</literallayout>
+<para>
+<option>-D</option> may be repeated up to 10 times on a command line.
+Only macro names up to 22 letters long can be set.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-d</option>&lt;<emphasis>debug&nbsp;options</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-d</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary>list of selectors</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary><option>-d</option> option</secondary>
+</indexterm>
+This option causes debugging information to be written to the standard
+error stream. It is restricted to admin users because debugging output may show
+database queries that contain password information. Also, the details of users&#x2019;
+filter files should be protected. If a non-admin user uses <option>-d</option>, Exim
+writes an error message to the standard error stream and exits with a non-zero
+return code.
+</para>
+<para>
+When <option>-d</option> is used, <option>-v</option> is assumed. If <option>-d</option> is given on its own, a lot of
+standard debugging data is output. This can be reduced, or increased to include
+some more rarely needed information, by directly following <option>-d</option> with a string
+made up of names preceded by plus or minus characters. These add or remove sets
+of debugging data, respectively. For example, <option>-d+filter</option> adds filter
+debugging, whereas <option>-d-all+filter</option> selects only filter debugging. Note that
+no spaces are allowed in the debug setting. The available debugging categories
+are:
+</para>
+<literallayout>
+<literal>acl            </literal> ACL interpretation
+<literal>auth           </literal> authenticators
+<literal>deliver        </literal> general delivery logic
+<literal>dns            </literal> DNS lookups (see also resolver)
+<literal>dnsbl          </literal> DNS black list (aka RBL) code
+<literal>exec           </literal> arguments for <function>execv()</function> calls
+<literal>expand         </literal> detailed debugging for string expansions
+<literal>filter         </literal> filter handling
+<literal>hints_lookup   </literal> hints data lookups
+<literal>host_lookup    </literal> all types of name-to-IP address handling
+<literal>ident          </literal> ident lookup
+<literal>interface      </literal> lists of local interfaces
+<literal>lists          </literal> matching things in lists
+<literal>load           </literal> system load checks
+<literal>local_scan     </literal> can be used by <function>local_scan()</function> (see chapter <xref linkend="CHAPlocalscan"/>)
+<literal>lookup         </literal> general lookup code and all lookups
+<literal>memory         </literal> memory handling
+<literal>noutf8         </literal> modifier: avoid UTF-8 line-drawing
+<literal>pid            </literal> modifier: add pid to debug output lines
+<literal>process_info   </literal> setting info for the process log
+<literal>queue_run      </literal> queue runs
+<literal>receive        </literal> general message reception logic
+<literal>resolver       </literal> turn on the DNS resolver&#x2019;s debugging output
+<literal>retry          </literal> retry handling
+<literal>rewrite        </literal> address rewriting
+<literal>route          </literal> address routing
+<literal>timestamp      </literal> modifier: add timestamp to debug output lines
+<literal>tls            </literal> TLS logic
+<literal>transport      </literal> transports
+<literal>uid            </literal> changes of uid/gid and looking up uid/gid
+<literal>verify         </literal> address verification logic
+<literal>all            </literal> almost all of the above (see below), and also <option>-v</option>
+</literallayout>
+<para>
+The <literal>all</literal> option excludes <literal>memory</literal> when used as <literal>+all</literal>, but includes it
+for <literal>-all</literal>. The reason for this is that <literal>+all</literal> is something that people
+tend to use when generating debug output for Exim maintainers. If <literal>+memory</literal>
+is included, an awful lot of output that is very rarely of interest is
+generated, so it now has to be explicitly requested. However, <literal>-all</literal> does
+turn everything off.
+</para>
+<para>
+<indexterm role="concept">
+<primary>resolver, debugging output</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>DNS resolver, debugging output</primary>
+</indexterm>
+The <literal>resolver</literal> option produces output only if the DNS resolver was compiled
+with DEBUG enabled. This is not the case in some operating systems. Also,
+unfortunately, debugging output from the DNS resolver is written to stdout
+rather than stderr.
+</para>
+<para>
+The default (<option>-d</option> with no argument) omits <literal>expand</literal>, <literal>filter</literal>,
+<literal>interface</literal>, <literal>load</literal>, <literal>memory</literal>, <literal>pid</literal>, <literal>resolver</literal>, and <literal>timestamp</literal>.
+However, the <literal>pid</literal> selector is forced when debugging is turned on for a
+daemon, which then passes it on to any re-executed Exims. Exim also
+automatically adds the pid to debug lines when several remote deliveries are
+run in parallel.
+</para>
+<para>
+The <literal>timestamp</literal> selector causes the current time to be inserted at the start
+of all debug output lines. This can be useful when trying to track down delays
+in processing.
+</para>
+<para>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary>UTF-8 in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>UTF-8</primary>
+<secondary>in debug output</secondary>
+</indexterm>
+The <literal>noutf8</literal> selector disables the use of
+UTF-8 line-drawing characters to group related information.
+When disabled. ascii-art is used instead.
+Using the <literal>+all</literal> option does not set this modifier,
+</para>
+<para>
+If the <option>debug_print</option> option is set in any driver, it produces output whenever
+any debugging is selected, or if <option>-v</option> is used.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-dd</option>&lt;<emphasis>debug&nbsp;options</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-dd</option></primary>
+</indexterm>
+This option behaves exactly like <option>-d</option> except when used on a command that
+starts a daemon process. In that case, debugging is turned off for the
+subprocesses that the daemon creates. Thus, it is useful for monitoring the
+behaviour of the daemon without creating as much output as full debugging does.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-dropcr</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-dropcr</option></primary>
+</indexterm>
+This is an obsolete option that is now a no-op. It used to affect the way Exim
+handled CR and LF characters in incoming messages. What happens now is
+described in section <xref linkend="SECTlineendings"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-E</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-E</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>bounce message</primary>
+<secondary>generating</secondary>
+</indexterm>
+This option specifies that an incoming message is a locally-generated delivery
+failure report. It is used internally by Exim when handling delivery failures
+and is not intended for external use. Its only effect is to stop Exim
+generating certain messages to the postmaster, as otherwise message cascades
+could occur in some situations. As part of the same option, a message id may
+follow the characters <option>-E</option>. If it does, the log entry for the receipt of the
+new message contains the id, following <quote>R=</quote>, as a cross-reference.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-e</option><emphasis>x</emphasis></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-e</option><emphasis>x</emphasis></primary>
+</indexterm>
+There are a number of Sendmail options starting with <option>-oe</option> which seem to be
+called by various programs without the leading <option>o</option> in the option. For
+example, the <option>vacation</option> program uses <option>-eq</option>. Exim treats all options of the
+form <option>-e</option><emphasis>x</emphasis> as synonymous with the corresponding <option>-oe</option><emphasis>x</emphasis> options.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-F</option>&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-F</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>name</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>name</primary>
+<secondary>of sender</secondary>
+</indexterm>
+This option sets the sender&#x2019;s full name for use when a locally-generated
+message is being accepted. In the absence of this option, the user&#x2019;s <emphasis>gecos</emphasis>
+entry from the password data is used. As users are generally permitted to alter
+their <emphasis>gecos</emphasis> entries, no security considerations are involved. White space
+between <option>-F</option> and the &lt;<emphasis>string</emphasis>&gt; is optional.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-f</option>&nbsp;&lt;<emphasis>address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-f</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>address</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address</primary>
+<secondary>sender</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>trusted users</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope from</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>envelope sender</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>user</primary>
+<secondary>trusted</secondary>
+</indexterm>
+This option sets the address of the envelope sender of a locally-generated
+message (also known as the return path). The option can normally be used only
+by a trusted user, but <option>untrusted_set_sender</option> can be set to allow untrusted
+users to use it.
+</para>
+<para>
+Processes running as root or the Exim user are always trusted. Other
+trusted users are defined by the <option>trusted_users</option> or <option>trusted_groups</option>
+options. In the absence of <option>-f</option>, or if the caller is not trusted, the sender
+of a local message is set to the caller&#x2019;s login name at the default qualify
+domain.
+</para>
+<para>
+There is one exception to the restriction on the use of <option>-f</option>: an empty sender
+can be specified by any user, trusted or not, to create a message that can
+never provoke a bounce. An empty sender can be specified either as an empty
+string, or as a pair of angle brackets with nothing between them, as in these
+examples of shell commands:
+</para>
+<literallayout class="monospaced">
+exim -f '&lt;&gt;' user@domain
+exim -f "" user@domain
+</literallayout>
+<para>
+In addition, the use of <option>-f</option> is not restricted when testing a filter file
+with <option>-bf</option> or when testing or verifying addresses using the <option>-bt</option> or
+<option>-bv</option> options.
+</para>
+<para>
+Allowing untrusted users to change the sender address does not of itself make
+it possible to send anonymous mail. Exim still checks that the <emphasis>From:</emphasis> header
+refers to the local user, and if it does not, it adds a <emphasis>Sender:</emphasis> header,
+though this can be overridden by setting <option>no_local_from_check</option>.
+</para>
+<para>
+White
+<indexterm role="concept">
+<primary><quote>From</quote> line</primary>
+</indexterm>
+space between <option>-f</option> and the &lt;<emphasis>address</emphasis>&gt; is optional (that is, they can be
+given as two arguments or one combined argument). The sender of a
+locally-generated message can also be set (when permitted) by an initial
+<quote>From&nbsp;</quote> line in the message &ndash; see the description of <option>-bm</option> above &ndash; but
+if <option>-f</option> is also present, it overrides <quote>From&nbsp;</quote>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-G</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-G</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>submission fixups, suppressing (command-line)</primary>
+</indexterm>
+This option is equivalent to an ACL applying:
+</para>
+<literallayout class="monospaced">
+control = suppress_local_fixups
+</literallayout>
+<para>
+for every message received.  Note that Sendmail will complain about such
+bad formatting, where Exim silently just does not fix it up.  This may change
+in future.
+</para>
+<para>
+As this affects audit information, the caller must be a trusted user to use
+this option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-h</option>&nbsp;&lt;<emphasis>number</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-h</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-h</option> option ignored</secondary>
+</indexterm>
+This option is accepted for compatibility with Sendmail, but has no effect. (In
+Sendmail it overrides the <quote>hop count</quote> obtained by counting <emphasis>Received:</emphasis>
+headers.)
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-i</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-i</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Solaris</primary>
+<secondary><emphasis>mail</emphasis> command</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>dot</primary>
+<secondary>in incoming non-SMTP message</secondary>
+</indexterm>
+This option, which has the same effect as <option>-oi</option>, specifies that a dot on a
+line by itself should not terminate an incoming, non-SMTP message.
+Solaris 2.4 (SunOS 5.4) Sendmail has a similar <option>-i</option> processing option
+<emphasis role="bold"><ulink url="https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf">https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf</ulink></emphasis>,
+p. 1M-529), and therefore a <option>-oi</option> command line option, which both are used
+by its <emphasis>mailx</emphasis> command.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-L</option>&nbsp;&lt;<emphasis>tag</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-L</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>syslog</primary>
+<secondary>process name; set with flag</secondary>
+</indexterm>
+This option is equivalent to setting <option>syslog_processname</option> in the config
+file and setting <option>log_file_path</option> to <literal>syslog</literal>.
+Its use is restricted to administrators.  The configuration file has to be
+read and parsed, to determine access rights, before this is set and takes
+effect, so early configuration file errors will not honour this flag.
+</para>
+<para>
+The tag should not be longer than 32 characters.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-M</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-M</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>forcing delivery</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>forcing attempt</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>forcing delivery</secondary>
+</indexterm>
+This option requests Exim to run a delivery attempt on each message in turn. If
+any of the messages are frozen, they are automatically thawed before the
+delivery attempt. The settings of <option>queue_domains</option>, <option>queue_smtp_domains</option>,
+and <option>hold_domains</option> are ignored.
+</para>
+<para>
+Retry
+<indexterm role="concept">
+<primary>hints database</primary>
+<secondary>overriding retry hints</secondary>
+</indexterm>
+hints for any of the addresses are overridden &ndash; Exim tries to deliver even if
+the normal retry time has not yet been reached. This option requires the caller
+to be an admin user. However, there is an option called <option>prod_requires_admin</option>
+which can be set false to relax this restriction (and also the same requirement
+for the <option>-q</option>, <option>-R</option>, and <option>-S</option> options).
+</para>
+<para>
+The deliveries happen synchronously, that is, the original Exim process does
+not terminate until all the delivery attempts have finished. No output is
+produced unless there is a serious error. If you want to see what is happening,
+use the <option>-v</option> option as well, or inspect Exim&#x2019;s main log.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mar</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>address</emphasis>&gt;&nbsp;&lt;<emphasis>address</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mar</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>adding recipients</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>recipient</primary>
+<secondary>adding</secondary>
+</indexterm>
+This option requests Exim to add the addresses to the list of recipients of the
+message (<quote>ar</quote> for <quote>add recipients</quote>). The first argument must be a message
+id, and the remaining ones must be email addresses. However, if the message is
+active (in the middle of a delivery attempt), it is not altered. This option
+can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MC</option>&nbsp;&lt;<emphasis>transport</emphasis>&gt;&nbsp;&lt;<emphasis>hostname</emphasis>&gt;&nbsp;&lt;<emphasis>host&nbsp;IP</emphasis>&gt;&nbsp;&lt;<emphasis>sequence&nbsp;number</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MC</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>passed connection</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>multiple deliveries</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>multiple SMTP deliveries</primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim to invoke another instance of itself to deliver a waiting message using
+an existing SMTP connection, which is passed as the standard input. Details are
+given in chapter <xref linkend="CHAPSMTP"/>. This must be the final option, and the caller
+must be root or the Exim user in order to use it.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCA</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCA</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that the
+connection to the remote host has been authenticated.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCD</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCD</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that the
+remote host supports the ESMTP <filename>DSN</filename> extension.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCd</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCd</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-d</option> option
+to pass on an information string on the purpose of the process.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCG</option>&nbsp;&lt;<emphasis>queue&nbsp;name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCG</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that an
+alternate queue is used, named by the following argument.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCK</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCK</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that a
+remote host supports the ESMTP <filename>CHUNKING</filename> extension.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><option>-MCL</option></term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>-MCL</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that the server to
+which Exim is connected advertised limits on numbers of mails, recipients or
+recipient domains.
+The limits are given by the following three arguments.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCP</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCP</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that the server to
+which Exim is connected supports pipelining.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><option>-MCp</option></term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>-MCp</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option. It signifies that the connection
+t a remote server is via a SOCKS proxy, using addresses and ports given by
+the following four arguments.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCQ</option>&nbsp;&lt;<emphasis>process&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>pipe&nbsp;fd</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCQ</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option when the original delivery was
+started by a queue runner. It passes on the process id of the queue runner,
+together with the file descriptor number of an open pipe. Closure of the pipe
+signals the final completion of the sequence of processes that are passing
+messages through the same SMTP connection.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><option>-MCq</option>&nbsp;&lt;<emphasis>recipient&nbsp;address</emphasis>&gt;&nbsp;&lt;<emphasis>size</emphasis>&gt;</term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>-MCq</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim to implement quota checking for local users.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCS</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCS</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option, and passes on the fact that the
+ESMTP SIZE option should be used on messages delivered down the existing
+connection.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCT</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCT</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option, and passes on the fact that the
+host to which Exim is connected supports TLS encryption.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><option>-MCr</option>&nbsp;&lt;<emphasis>SNI</emphasis>&gt;</term>
+<term><option>-MCs</option>&nbsp;&lt;<emphasis>SNI</emphasis>&gt;</term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>-MCs</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>-MCr</option></primary>
+</indexterm>
+These options are not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MCt</option> option, and passes on the fact that
+a TLS Server Name Indication was sent as part of the channel establishment.
+The argument gives the SNI string.
+The "r" variant indicates a DANE-verified connection.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MCt</option>&nbsp;&lt;<emphasis>IP&nbsp;address</emphasis>&gt;&nbsp;&lt;<emphasis>port</emphasis>&gt;&nbsp;&lt;<emphasis>cipher</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MCt</option></primary>
+</indexterm>
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the <option>-MC</option> option, and passes on the fact that the
+connection is being proxied by a parent process for handling TLS encryption.
+The arguments give the local address and port being proxied, and the TLS cipher.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mc</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mc</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>hints database</primary>
+<secondary>not overridden by <option>-Mc</option></secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>manually started &ndash; not forced</secondary>
+</indexterm>
+This option requests Exim to run a delivery attempt on each message, in turn,
+but unlike the <option>-M</option> option, it does check for retry hints, and respects any
+that are found. This option is not very useful to external callers. It is
+provided mainly for internal use by Exim when it needs to re-invoke itself in
+order to regain root privilege for a delivery (see chapter <xref linkend="CHAPsecurity"/>).
+However, <option>-Mc</option> can be useful when testing, in order to run a delivery that
+respects retry times and other options such as <option>hold_domains</option> that are
+overridden when <option>-M</option> is used. Such a delivery does not count as a queue run.
+If you want to run a specific delivery as if in a queue run, you should use
+<option>-q</option> with a message id argument. A distinction between queue run deliveries
+and other deliveries is made in one or two places.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mes</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mes</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>changing sender</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>changing</secondary>
+</indexterm>
+This option requests Exim to change the sender address in the message to the
+given address, which must be a fully qualified address or <quote>&lt;&gt;</quote> (<quote>es</quote> for
+<quote>edit sender</quote>). There must be exactly two arguments. The first argument must
+be a message id, and the second one an email address. However, if the message
+is active (in the middle of a delivery attempt), its status is not altered.
+This option can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mf</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mf</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>freezing messages</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>manually freezing</secondary>
+</indexterm>
+This option requests Exim to mark each listed message as <quote>frozen</quote>. This
+prevents any delivery attempts taking place until the message is <quote>thawed</quote>,
+either manually or as a result of the <option>auto_thaw</option> configuration option.
+However, if any of the messages are active (in the middle of a delivery
+attempt), their status is not altered. This option can be used only by an admin
+user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mg</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mg</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>giving up on messages</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>abandoning delivery attempts</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>abandoning further attempts</secondary>
+</indexterm>
+This option requests Exim to give up trying to deliver the listed messages,
+including any that are frozen. However, if any of the messages are active,
+their status is not altered. For non-bounce messages, a delivery error message
+is sent to the sender, containing the text <quote>cancelled by administrator</quote>.
+Bounce messages are just discarded. This option can be used only by an admin
+user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-MG</option>&nbsp;&lt;<emphasis>queue&nbsp;name</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-MG</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>named</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>named queues</primary>
+<secondary>moving messages</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>moving messages</secondary>
+</indexterm>
+This option requests that each listed message be moved from its current
+queue to the given named queue.
+The destination queue name argument is required, but can be an empty
+string to define the default queue.
+If the messages are not currently located in the default queue,
+a <option>-qG&lt;name&gt;</option> option will be required to define the source queue.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mmad</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mmad</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>cancelling all</secondary>
+</indexterm>
+This option requests Exim to mark all the recipient addresses in the messages
+as already delivered (<quote>mad</quote> for <quote>mark all delivered</quote>). However, if any
+message is active (in the middle of a delivery attempt), its status is not
+altered. This option can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mmd</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>address</emphasis>&gt;&nbsp;&lt;<emphasis>address</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mmd</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>cancelling by address</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>recipient</primary>
+<secondary>removing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>removing recipients</primary>
+</indexterm>
+This option requests Exim to mark the given addresses as already delivered
+(<quote>md</quote> for <quote>mark delivered</quote>). The first argument must be a message id, and
+the remaining ones must be email addresses. These are matched to recipient
+addresses in the message in a case-sensitive manner. If the message is active
+(in the middle of a delivery attempt), its status is not altered. This option
+can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mrm</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mrm</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>removing messages</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>abandoning mail</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>manually discarding</secondary>
+</indexterm>
+This option requests Exim to remove the given messages from the queue. No
+bounce messages are sent; each message is simply forgotten. However, if any of
+the messages are active, their status is not altered. This option can be used
+only by an admin user or by the user who originally caused the message to be
+placed in the queue.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mset</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mset</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>string expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>testing</secondary>
+</indexterm>
+This option is useful only in conjunction with <option>-be</option> (that is, when testing
+string expansions). Exim loads the given message from its spool before doing
+the test expansions, thus setting message-specific variables such as
+<varname>$message_size</varname> and the header variables. The <varname>$recipients</varname> variable is made
+available. This feature is provided to make it easier to test expansions that
+make use of these variables. However, this option can be used only by an admin
+user. See also <option>-bem</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mt</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;&nbsp;...</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mt</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>thawing messages</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>unfreezing messages</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>thawing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>thawing frozen</secondary>
+</indexterm>
+This option requests Exim to <quote>thaw</quote> any of the listed messages that are
+<quote>frozen</quote>, so that delivery attempts can resume. However, if any of the
+messages are active, their status is not altered. This option can be used only
+by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mvb</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mvb</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>listing</primary>
+<secondary>message body</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>listing body of</secondary>
+</indexterm>
+This option causes the contents of the message body (-D) spool file to be
+written to the standard output. This option can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mvc</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mvc</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>listing in RFC 2822 format</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>listing</primary>
+<secondary>message in RFC 2822 format</secondary>
+</indexterm>
+This option causes a copy of the complete message (header lines plus body) to
+be written to the standard output in RFC 2822 format. This option can be used
+only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mvh</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mvh</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>listing</primary>
+<secondary>message headers</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>listing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>listing header lines</secondary>
+</indexterm>
+This option causes the contents of the message headers (-H) spool file to be
+written to the standard output. This option can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Mvl</option>&nbsp;&lt;<emphasis>message&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Mvl</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>listing</primary>
+<secondary>message log</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>listing message log</secondary>
+</indexterm>
+This option causes the contents of the message log spool file to be written to
+the standard output. This option can be used only by an admin user.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-m</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-m</option></primary>
+</indexterm>
+This is a synonym for <option>-om</option> that is accepted by Sendmail
+(<emphasis role="bold"><ulink url="https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf">https://docs.oracle.com/cd/E19457-01/801-6680-1M/801-6680-1M.pdf</ulink></emphasis>
+p. 1M-258), so Exim treats it that way too.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-N</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-N</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary><option>-N</option> option</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>debugging</primary>
+<secondary>suppressing delivery</secondary>
+</indexterm>
+This is a debugging option that inhibits delivery of a message at the transport
+level. It implies <option>-v</option>. Exim goes through many of the motions of delivery &ndash;
+it just doesn&#x2019;t actually transport the message, but instead behaves as if it
+had successfully done so. However, it does not make any updates to the retry
+database, and the log entries for deliveries are flagged with <quote>*&gt;</quote> rather
+than <quote>=&gt;</quote>.
+</para>
+<para>
+Because <option>-N</option> discards any message to which it applies, only root or the Exim
+user are allowed to use it with <option>-bd</option>, <option>-q</option>, <option>-R</option> or <option>-M</option>. In other
+words, an ordinary user can use it only when supplying an incoming message to
+which it will apply. Although transportation never fails when <option>-N</option> is set, an
+address may be deferred because of a configuration problem on a transport, or a
+routing problem. Once <option>-N</option> has been used for a delivery attempt, it sticks to
+the message, and applies to any subsequent delivery attempts that may happen
+for that message.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-n</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-n</option></primary>
+</indexterm>
+This option is interpreted by Sendmail to mean <quote>no aliasing</quote>.
+For normal modes of operation, it is ignored by Exim.
+When combined with <option>-bP</option> it makes the output more terse (suppresses
+option names, environment values and config pretty printing).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-O</option>&nbsp;&lt;<emphasis>data</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-O</option></primary>
+</indexterm>
+This option is interpreted by Sendmail to mean <literal>set option</literal>. It is ignored by
+Exim.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oA</option>&nbsp;&lt;<emphasis>file&nbsp;name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oA</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-oA</option> option</secondary>
+</indexterm>
+This option is used by Sendmail in conjunction with <option>-bi</option> to specify an
+alternative alias filename. Exim handles <option>-bi</option> differently; see the
+description above.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oB</option>&nbsp;&lt;<emphasis>n</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oB</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>passed connection</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>multiple deliveries</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>multiple SMTP deliveries</primary>
+</indexterm>
+This is a debugging option which limits the maximum number of messages that can
+be delivered down one SMTP connection, overriding the value set in any <command>smtp</command>
+transport. If &lt;<emphasis>n</emphasis>&gt; is omitted, the limit is set to 1.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-odb</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-odb</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>background delivery</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>in the background</secondary>
+</indexterm>
+This option applies to all modes in which Exim accepts incoming messages,
+including the listening daemon. It requests <quote>background</quote> delivery of such
+messages, which means that the accepting process automatically starts a
+delivery process for each message received, but does not wait for the delivery
+processes to finish.
+</para>
+<para>
+When all the messages have been received, the reception process exits,
+leaving the delivery processes to finish in their own time. The standard output
+and error streams are closed at the start of each delivery process.
+This is the default action if none of the <option>-od</option> options are present.
+</para>
+<para>
+If one of the queueing options in the configuration file
+(<option>queue_only</option> or <option>queue_only_file</option>, for example) is in effect, <option>-odb</option>
+overrides it if <option>queue_only_override</option> is set true, which is the default
+setting. If <option>queue_only_override</option> is set false, <option>-odb</option> has no effect.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-odf</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-odf</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>foreground delivery</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>in the foreground</secondary>
+</indexterm>
+This option requests <quote>foreground</quote> (synchronous) delivery when Exim has
+accepted a locally-generated message. (For the daemon it is exactly the same as
+<option>-odb</option>.) A delivery process is automatically started to deliver the message,
+and Exim waits for it to complete before proceeding.
+</para>
+<para>
+The original Exim reception process does not finish until the delivery
+process for the final message has ended. The standard error stream is left open
+during deliveries.
+</para>
+<para>
+However, like <option>-odb</option>, this option has no effect if <option>queue_only_override</option> is
+false and one of the queueing options in the configuration file is in effect.
+</para>
+<para>
+If there is a temporary delivery error during foreground delivery, the
+message is left in the queue for later delivery, and the original reception
+process exits. See chapter <xref linkend="CHAPnonqueueing"/> for a way of setting up a
+restricted configuration that never queues messages.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-odi</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-odi</option></primary>
+</indexterm>
+This option is synonymous with <option>-odf</option>. It is provided for compatibility with
+Sendmail.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-odq</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-odq</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>non-immediate delivery</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>suppressing immediate</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queueing incoming messages</primary>
+</indexterm>
+This option applies to all modes in which Exim accepts incoming messages,
+including the listening daemon. It specifies that the accepting process should
+not automatically start a delivery process for each message received. Messages
+are placed in the queue, and remain there until a subsequent queue runner
+process encounters them. There are several configuration options (such as
+<option>queue_only</option>) that can be used to queue incoming messages under certain
+conditions. This option overrides all of them and also <option>-odqs</option>. It always
+forces queueing.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-odqs</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-odqs</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>delaying delivery</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>first pass routing</primary>
+</indexterm>
+This option is a hybrid between <option>-odb</option>/<option>-odi</option> and <option>-odq</option>.
+However, like <option>-odb</option> and <option>-odi</option>, this option has no effect if
+<option>queue_only_override</option> is false and one of the queueing options in the
+configuration file is in effect.
+</para>
+<para>
+When <option>-odqs</option> does operate, a delivery process is started for each incoming
+message, in the background by default, but in the foreground if <option>-odi</option> is
+also present. The recipient addresses are routed, and local deliveries are done
+in the normal way. However, if any SMTP deliveries are required, they are not
+done at this time, so the message remains in the queue until a subsequent queue
+runner process encounters it. Because routing was done, Exim knows which
+messages are waiting for which hosts, and so a number of messages for the same
+host can be sent in a single SMTP connection. The <option>queue_smtp_domains</option>
+configuration option has the same effect for specific domains. See also the
+<option>-qq</option> option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oee</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oee</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>reporting</secondary>
+</indexterm>
+If an error is detected while a non-SMTP message is being received (for
+example, a malformed address), the error is reported to the sender in a mail
+message.
+</para>
+<para>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-oee</option></secondary>
+</indexterm>
+Provided
+this error message is successfully sent, the Exim receiving process
+exits with a return code of zero. If not, the return code is 2 if the problem
+is that the original message has no recipients, or 1 for any other error.
+This is the default <option>-oe</option><emphasis>x</emphasis> option if Exim is called as <emphasis>rmail</emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oem</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oem</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>reporting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-oem</option></secondary>
+</indexterm>
+This is the same as <option>-oee</option>, except that Exim always exits with a non-zero
+return code, whether or not the error message was successfully sent.
+This is the default <option>-oe</option><emphasis>x</emphasis> option, unless Exim is called as <emphasis>rmail</emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oep</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oep</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>reporting</secondary>
+</indexterm>
+If an error is detected while a non-SMTP message is being received, the
+error is reported by writing a message to the standard error file (stderr).
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for <option>-oep</option></secondary>
+</indexterm>
+The return code is 1 for all errors.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oeq</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oeq</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>reporting</secondary>
+</indexterm>
+This option is supported for compatibility with Sendmail, but has the same
+effect as <option>-oep</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oew</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oew</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>reporting</secondary>
+</indexterm>
+This option is supported for compatibility with Sendmail, but has the same
+effect as <option>-oem</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oi</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oi</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>dot</primary>
+<secondary>in incoming non-SMTP message</secondary>
+</indexterm>
+This option, which has the same effect as <option>-i</option>, specifies that a dot on a
+line by itself should not terminate an incoming, non-SMTP message. Otherwise, a
+single dot does terminate, though Exim does no special processing for other
+lines that start with a dot. This option is set by default if Exim is called as
+<emphasis>rmail</emphasis>. See also <option>-ti</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oitrue</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oitrue</option></primary>
+</indexterm>
+This option is treated as synonymous with <option>-oi</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMa</option>&nbsp;&lt;<emphasis>host&nbsp;address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMa</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>host address, specifying for local message</secondary>
+</indexterm>
+A number of options starting with <option>-oM</option> can be used to set values associated
+with remote hosts on locally-submitted messages (that is, messages not received
+over TCP/IP). These options can be used by any caller in conjunction with the
+<option>-bh</option>, <option>-be</option>, <option>-bf</option>, <option>-bF</option>, <option>-bt</option>, or <option>-bv</option> testing options. In
+other circumstances, they are ignored unless the caller is trusted.
+</para>
+<para>
+The <option>-oMa</option> option sets the sender host address. This may include a port
+number at the end, after a full stop (period). For example:
+</para>
+<literallayout class="monospaced">
+exim -bs -oMa 10.9.8.7.1234
+</literallayout>
+<para>
+An alternative syntax is to enclose the IP address in square brackets,
+followed by a colon and the port number:
+</para>
+<literallayout class="monospaced">
+exim -bs -oMa [10.9.8.7]:1234
+</literallayout>
+<para>
+The IP address is placed in the <varname>$sender_host_address</varname> variable, and the
+port, if present, in <varname>$sender_host_port</varname>. If both <option>-oMa</option> and <option>-bh</option>
+are present on the command line, the sender host IP address is taken from
+whichever one is last.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMaa</option>&nbsp;&lt;<emphasis>name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMaa</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>name, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMaa</option>
+option sets the value of <varname>$sender_host_authenticated</varname> (the authenticator
+name). See chapter <xref linkend="CHAPSMTPAUTH"/> for a discussion of SMTP authentication.
+This option can be used with <option>-bh</option> and <option>-bs</option> to set up an
+authenticated SMTP session without actually using the SMTP AUTH command.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMai</option>&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMai</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>id, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMai</option>
+option sets the value of <varname>$authenticated_id</varname> (the id that was authenticated).
+This overrides the default value (the caller&#x2019;s login id, except with <option>-bh</option>,
+where there is no default) for messages from local sources. See chapter
+<xref linkend="CHAPSMTPAUTH"/> for a discussion of authenticated ids.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMas</option>&nbsp;&lt;<emphasis>address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMas</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>sender, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMas</option>
+option sets the authenticated sender value in <varname>$authenticated_sender</varname>. It
+overrides the sender address that is created from the caller&#x2019;s login id for
+messages from local sources, except when <option>-bh</option> is used, when there is no
+default. For both <option>-bh</option> and <option>-bs</option>, an authenticated sender that is
+specified on a MAIL command overrides this value. See chapter
+<xref linkend="CHAPSMTPAUTH"/> for a discussion of authenticated senders.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMi</option>&nbsp;&lt;<emphasis>interface&nbsp;address</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMi</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>interface</primary>
+<secondary>address, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMi</option>
+option sets the IP interface address value. A port number may be included,
+using the same syntax as for <option>-oMa</option>. The interface address is placed in
+<varname>$received_ip_address</varname> and the port number, if present, in <varname>$received_port</varname>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMm</option>&nbsp;&lt;<emphasis>message&nbsp;reference</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMm</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>message reference</primary>
+<secondary>message reference, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMm</option>
+option sets the message reference, e.g. message-id, and is logged during
+delivery. This is useful when some kind of audit trail is required to tie
+messages together. The format of the message reference is checked and will
+abort if the format is invalid. The option will only be accepted if exim is
+running in trusted mode, not as any regular user.
+</para>
+<para>
+The best example of a message reference is when Exim sends a bounce message.
+The message reference is the message-id of the original message for which Exim
+is sending the bounce.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMr</option>&nbsp;&lt;<emphasis>protocol&nbsp;name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMr</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>protocol, specifying for local message</primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$received_protocol</varname></primary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMr</option>
+option sets the received protocol value that is stored in
+<varname>$received_protocol</varname>. However, it does not apply (and is ignored) when <option>-bh</option>
+or <option>-bs</option> is used. For <option>-bh</option>, the protocol is forced to one of the standard
+SMTP protocol names (see the description of <varname>$received_protocol</varname> in section
+<xref linkend="SECTexpvar"/>). For <option>-bs</option>, the protocol is always <quote>local-</quote> followed by
+one of those same names. For <option>-bS</option> (batched SMTP) however, the protocol can
+be set by <option>-oMr</option>. Repeated use of this option is not supported.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMs</option>&nbsp;&lt;<emphasis>host&nbsp;name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMs</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>host name, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMs</option>
+option sets the sender host name in <varname>$sender_host_name</varname>. When this option is
+present, Exim does not attempt to look up a host name from an IP address; it
+uses the name it is given.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oMt</option>&nbsp;&lt;<emphasis>ident&nbsp;string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oMt</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>ident string, specifying for local message</secondary>
+</indexterm>
+See <option>-oMa</option> above for general remarks about the <option>-oM</option> options. The <option>-oMt</option>
+option sets the sender ident value in <varname>$sender_ident</varname>. The default setting for
+local callers is the login id of the calling process, except when <option>-bh</option> is
+used, when there is no default.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-om</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-om</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-om</option> option ignored</secondary>
+</indexterm>
+In Sendmail, this option means <quote>me too</quote>, indicating that the sender of a
+message should receive a copy of the message if the sender appears in an alias
+expansion. Exim always does this, so the option does nothing.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oo</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oo</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-oo</option> option ignored</secondary>
+</indexterm>
+This option is ignored. In Sendmail it specifies <quote>old style headers</quote>,
+whatever that means.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oP</option>&nbsp;&lt;<emphasis>path</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oP</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>pid (process id)</primary>
+<secondary>of daemon</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>process id (pid)</secondary>
+</indexterm>
+This option is useful only in conjunction with <option>-bd</option> or <option>-q</option> with a time
+value. The option specifies the file to which the process id of the daemon is
+written. When <option>-oX</option> is used with <option>-bd</option>, or when <option>-q</option> with a time is used
+without <option>-bd</option>, this is the only way of causing Exim to write a pid file,
+because in those cases, the normal pid file is not used.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oPX</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oPX</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>pid (process id)</primary>
+<secondary>of daemon</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon</primary>
+<secondary>process id (pid)</secondary>
+</indexterm>
+This option is not intended for general use.
+The daemon uses it when terminating due to a SIGTEM, possibly in
+combination with <option>-oP</option>&nbsp;&lt;<emphasis>path</emphasis>&gt;.
+It causes the pid file to be removed.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-or</option>&nbsp;&lt;<emphasis>time</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-or</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>timeout</primary>
+<secondary>for non-SMTP input</secondary>
+</indexterm>
+This option sets a timeout value for incoming non-SMTP messages. If it is not
+set, Exim will wait forever for the standard input. The value can also be set
+by the <option>receive_timeout</option> option. The format used for specifying times is
+described in section <xref linkend="SECTtimeformat"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-os</option>&nbsp;&lt;<emphasis>time</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-os</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>timeout</primary>
+<secondary>for SMTP input</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>input timeout</secondary>
+</indexterm>
+This option sets a timeout value for incoming SMTP messages. The timeout
+applies to each SMTP command and block of data. The value can also be set by
+the <option>smtp_receive_timeout</option> option; it defaults to 5 minutes. The format used
+for specifying times is described in section <xref linkend="SECTtimeformat"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-ov</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-ov</option></primary>
+</indexterm>
+This option has exactly the same effect as <option>-v</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-oX</option>&nbsp;&lt;<emphasis>number&nbsp;or&nbsp;string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-oX</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>TCP/IP</primary>
+<secondary>setting listening ports</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>TCP/IP</primary>
+<secondary>setting listening interfaces</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>port</primary>
+<secondary>receiving TCP/IP</secondary>
+</indexterm>
+This option is relevant only when the <option>-bd</option> (start listening daemon) option
+is also given. It controls which ports and interfaces the daemon uses. Details
+of the syntax, and how it interacts with configuration file options, are given
+in chapter <xref linkend="CHAPinterfaces"/>. When <option>-oX</option> is used to start a daemon, no pid
+file is written unless <option>-oP</option> is also present to specify a pid filename.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><option>-oY</option></term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>-oY</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>daemon notifier socket</primary>
+</indexterm>
+This option controls the creation of an inter-process communications endpoint
+by the Exim daemon.
+It is only relevant when the <option>-bd</option> (start listening daemon) option is also
+given.
+Normally the daemon creates this socket, unless a <option>-oX</option> and <emphasis role="bold">no</emphasis> <option>-oP</option>
+option is also present.
+If this option is given then the socket will not be created.  This could be
+required if the system is running multiple daemons.
+</para>
+<para revisionflag="changed">
+The socket is currently used for
+</para>
+<itemizedlist revisionflag="changed">
+<listitem>
+<para revisionflag="changed">
+fast ramp-up of queue runner processes
+</para>
+</listitem>
+<listitem>
+<para revisionflag="changed">
+obtaining a current queue size
+</para>
+</listitem>
+</itemizedlist>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-pd</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-pd</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Perl</primary>
+<secondary>starting the interpreter</secondary>
+</indexterm>
+This option applies when an embedded Perl interpreter is linked with Exim (see
+chapter <xref linkend="CHAPperl"/>). It overrides the setting of the <option>perl_at_start</option>
+option, forcing the starting of the interpreter to be delayed until it is
+needed.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-ps</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-ps</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Perl</primary>
+<secondary>starting the interpreter</secondary>
+</indexterm>
+This option applies when an embedded Perl interpreter is linked with Exim (see
+chapter <xref linkend="CHAPperl"/>). It overrides the setting of the <option>perl_at_start</option>
+option, forcing the starting of the interpreter to occur as soon as Exim is
+started.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-p</option>&lt;<emphasis>rval</emphasis>&gt;:&lt;<emphasis>sval</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-p</option></primary>
+</indexterm>
+For compatibility with Sendmail, this option is equivalent to
+</para>
+<literallayout>
+<literal>-oMr</literal> &lt;<emphasis>rval</emphasis>&gt; <literal>-oMs</literal> &lt;<emphasis>sval</emphasis>&gt;
+</literallayout>
+<para>
+It sets the incoming protocol and host name (for trusted callers). The
+host name and its colon can be omitted when only the protocol is to be set.
+Note the Exim already has two private options, <option>-pd</option> and <option>-ps</option>, that refer
+to embedded Perl. It is therefore impossible to set a protocol value of <literal>d</literal>
+or <literal>s</literal> using this option (but that does not seem a real limitation).
+Repeated use of this option is not supported.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-q</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>starting manually</secondary>
+</indexterm>
+This option is normally restricted to admin users. However, there is a
+configuration option called <option>prod_requires_admin</option> which can be set false to
+relax this restriction (and also the same requirement for the <option>-M</option>, <option>-R</option>,
+and <option>-S</option> options).
+</para>
+<para>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>description of operation</secondary>
+</indexterm>
+If other commandline options do not specify an action,
+the <option>-q</option> option starts one queue runner process. This scans the queue of
+waiting messages, and runs a delivery process for each one in turn. It waits
+for each delivery process to finish before starting the next one. A delivery
+process may not actually do any deliveries if the retry times for the addresses
+have not been reached. Use <option>-qf</option> (see below) if you want to override this.
+</para>
+<para>
+If
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>passed connection</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>multiple deliveries</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>multiple SMTP deliveries</primary>
+</indexterm>
+the delivery process spawns other processes to deliver other messages down
+passed SMTP connections, the queue runner waits for these to finish before
+proceeding.
+</para>
+<para>
+When all the queued messages have been considered, the original queue runner
+process terminates. In other words, a single pass is made over the waiting
+mail, one message at a time. Use <option>-q</option> with a time (see below) if you want
+this to be repeated periodically.
+</para>
+<para>
+Exim processes the waiting messages in an unpredictable order. It isn&#x2019;t very
+random, but it is likely to be different each time, which is all that matters.
+If one particular message screws up a remote MTA, other messages to the same
+MTA have a chance of getting through if they get tried first.
+</para>
+<para>
+It is possible to cause the messages to be processed in lexical message id
+order, which is essentially the order in which they arrived, by setting the
+<option>queue_run_in_order</option> option, but this is not recommended for normal use.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q</option>&lt;<emphasis>qflags</emphasis>&gt;</term>
+<listitem>
+<para>
+The <option>-q</option> option may be followed by one or more flag letters that change its
+behaviour. They are all optional, but if more than one is present, they must
+appear in the correct order. Each flag is described in a separate item below.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-qq...</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qq</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>double scanning</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>routing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>routing</primary>
+<secondary>whole queue before delivery</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>first pass routing</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>two phase</secondary>
+</indexterm>
+An option starting with <option>-qq</option> requests a two-stage queue run. In the first
+stage, the queue is scanned as if the <option>queue_smtp_domains</option> option matched
+every domain. Addresses are routed, local deliveries happen, but no remote
+transports are run.
+</para>
+<para>
+Performance will be best if the <option>queue_run_in_order</option> option is false.
+If that is so and the <option>queue_fast_ramp</option> option is true then
+in the first phase of the run,
+once a threshold number of messages are routed for a given host,
+a delivery process is forked in parallel with the rest of the scan.
+</para>
+<para>
+<indexterm role="concept">
+<primary>hints database</primary>
+<secondary>remembering routing</secondary>
+</indexterm>
+The hints database that remembers which messages are waiting for specific hosts
+is updated, as if delivery to those hosts had been deferred. After this is
+complete, a second, normal queue scan happens, with routing and delivery taking
+place as normal. Messages that are routed to the same host should mostly be
+delivered down a single SMTP
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>passed connection</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>multiple deliveries</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>multiple SMTP deliveries</primary>
+</indexterm>
+connection because of the hints that were set up during the first queue scan.
+This option may be useful for hosts that are connected to the Internet
+intermittently.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q[q]i...</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qi</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>initial delivery</secondary>
+</indexterm>
+If the <emphasis>i</emphasis> flag is present, the queue runner runs delivery processes only for
+those messages that haven&#x2019;t previously been tried. (<emphasis>i</emphasis> stands for <quote>initial
+delivery</quote>.) This can be helpful if you are putting messages in the queue using
+<option>-odq</option> and want a queue runner just to process the new messages.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q[q][i]f...</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qf</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>forcing delivery</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>forcing in queue run</secondary>
+</indexterm>
+If one <emphasis>f</emphasis> flag is present, a delivery attempt is forced for each non-frozen
+message, whereas without <emphasis>f</emphasis> only those non-frozen addresses that have passed
+their retry times are tried.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q[q][i]ff...</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qff</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>forcing delivery</secondary>
+</indexterm>
+If <emphasis>ff</emphasis> is present, a delivery attempt is forced for every message, whether
+frozen or not.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q[q][i][f[f]]l</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-ql</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>local deliveries only</secondary>
+</indexterm>
+The <emphasis>l</emphasis> (the letter <quote>ell</quote>) flag specifies that only local deliveries are to
+be done. If a message requires any remote deliveries, it remains in the queue
+for later delivery.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q[q][i][f[f]][l][G&lt;name&gt;[/&lt;time&gt;]]]</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qG</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>named</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>named queues</primary>
+<secondary>deliver from</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue</primary>
+<secondary>delivering specific messages</secondary>
+</indexterm>
+If the <emphasis>G</emphasis> flag and a name is present, the queue runner operates on the
+queue with the given name rather than the default queue.
+The name should not contain a <emphasis>/</emphasis> character.
+For a periodic queue run (see below)
+append to the name a slash and a time value.
+</para>
+<para>
+If other commandline options specify an action, a <emphasis>-qG&lt;name&gt;</emphasis> option
+will specify a queue to operate on.
+For example:
+</para>
+<literallayout class="monospaced">
+exim -bp -qGquarantine
+mailq -qGquarantine
+exim -qGoffpeak -Rf @special.domain.example
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q</option>&lt;<emphasis>qflags</emphasis>&gt;&nbsp;&lt;<emphasis>start&nbsp;id</emphasis>&gt;&nbsp;&lt;<emphasis>end&nbsp;id</emphasis>&gt;</term>
+<listitem>
+<para>
+When scanning the queue, Exim can be made to skip over messages whose ids are
+lexically less than a given value by following the <option>-q</option> option with a
+starting message id. For example:
+</para>
+<literallayout class="monospaced">
+exim -q 0t5C6f-0000c8-00
+</literallayout>
+<para>
+Messages that arrived earlier than <literal>0t5C6f-0000c8-00</literal> are not inspected. If a
+second message id is given, messages whose ids are lexically greater than it
+are also skipped. If the same id is given twice, for example,
+</para>
+<literallayout class="monospaced">
+exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
+</literallayout>
+<para>
+just one delivery process is started, for that message. This differs from
+<option>-M</option> in that retry data is respected, and it also differs from <option>-Mc</option> in
+that it counts as a delivery from a queue run. Note that the selection
+mechanism does not affect the order in which the messages are scanned. There
+are also other ways of selecting specific sets of messages for delivery in a
+queue run &ndash; see <option>-R</option> and <option>-S</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-q</option>&lt;<emphasis>qflags</emphasis>&gt;&lt;<emphasis>time</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>starting periodically</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>periodic queue running</primary>
+</indexterm>
+When a time value is present, the <option>-q</option> option causes Exim to run as a daemon,
+starting a queue runner process at intervals specified by the given time value
+(whose format is described in section <xref linkend="SECTtimeformat"/>). This form of the
+<option>-q</option> option is commonly combined with the <option>-bd</option> option, in which case a
+single daemon process handles both functions. A common way of starting up a
+combined daemon at system boot time is to use a command such as
+</para>
+<literallayout class="monospaced">
+/usr/exim/bin/exim -bd -q30m
+</literallayout>
+<para>
+Such a daemon listens for incoming SMTP calls, and also starts a queue runner
+process every 30 minutes.
+</para>
+<para>
+When a daemon is started by <option>-q</option> with a time value, but without <option>-bd</option>, no
+pid file is written unless one is explicitly requested by the <option>-oP</option> option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-qR</option>&lt;<emphasis>rsflags</emphasis>&gt;&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qR</option></primary>
+</indexterm>
+This option is synonymous with <option>-R</option>. It is provided for Sendmail
+compatibility.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-qS</option>&lt;<emphasis>rsflags</emphasis>&gt;&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-qS</option></primary>
+</indexterm>
+This option is synonymous with <option>-S</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-R</option>&lt;<emphasis>rsflags</emphasis>&gt;&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-R</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>for specific recipients</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>to given domain</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain</primary>
+<secondary>delivery to</secondary>
+</indexterm>
+The &lt;<emphasis>rsflags</emphasis>&gt; may be empty, in which case the white space before the string
+is optional, unless the string is <emphasis>f</emphasis>, <emphasis>ff</emphasis>, <emphasis>r</emphasis>, <emphasis>rf</emphasis>, or <emphasis>rff</emphasis>,
+which are the possible values for &lt;<emphasis>rsflags</emphasis>&gt;. White space is required if
+&lt;<emphasis>rsflags</emphasis>&gt; is not empty.
+</para>
+<para>
+This option is similar to <option>-q</option> with no time value, that is, it causes Exim to
+perform a single queue run, except that, when scanning the messages on the
+queue, Exim processes only those that have at least one undelivered recipient
+address containing the given string, which is checked in a case-independent
+way. If the &lt;<emphasis>rsflags</emphasis>&gt; start with <emphasis>r</emphasis>, &lt;<emphasis>string</emphasis>&gt; is interpreted as a
+regular expression; otherwise it is a literal string.
+</para>
+<para>
+If you want to do periodic queue runs for messages with specific recipients,
+you can combine <option>-R</option> with <option>-q</option> and a time value. For example:
+</para>
+<literallayout class="monospaced">
+exim -q25m -R @special.domain.example
+</literallayout>
+<para>
+This example does a queue run for messages with recipients in the given domain
+every 25 minutes. Any additional flags that are specified with <option>-q</option> are
+applied to each queue run.
+</para>
+<para>
+Once a message is selected for delivery by this mechanism, all its addresses
+are processed. For the first selected message, Exim overrides any retry
+information and forces a delivery attempt for each undelivered address. This
+means that if delivery of any address in the first message is successful, any
+existing retry information is deleted, and so delivery attempts for that
+address in subsequently selected messages (which are processed without forcing)
+will run. However, if delivery of any address does not succeed, the retry
+information is updated, and in subsequently selected messages, the failing
+address will be skipped.
+</para>
+<para>
+<indexterm role="concept">
+<primary>frozen messages</primary>
+<secondary>forcing delivery</secondary>
+</indexterm>
+If the &lt;<emphasis>rsflags</emphasis>&gt; contain <emphasis>f</emphasis> or <emphasis>ff</emphasis>, the delivery forcing applies to
+all selected messages, not just the first; frozen messages are included when
+<emphasis>ff</emphasis> is present.
+</para>
+<para>
+The <option>-R</option> option makes it straightforward to initiate delivery of all messages
+to a given domain after a host has been down for some time. When the SMTP
+command ETRN is accepted by its ACL (see chapter <xref linkend="CHAPACL"/>), its default
+effect is to run Exim with the <option>-R</option> option, but it can be configured to run
+an arbitrary command instead.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-r</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-r</option></primary>
+</indexterm>
+This is a documented (for Sendmail) obsolete alternative name for <option>-f</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-S</option>&lt;<emphasis>rsflags</emphasis>&gt;&nbsp;&lt;<emphasis>string</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-S</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>from given sender</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>for specific senders</secondary>
+</indexterm>
+This option acts like <option>-R</option> except that it checks the string against each
+message&#x2019;s sender instead of against the recipients. If <option>-R</option> is also set, both
+conditions must be met for a message to be selected. If either of the options
+has <emphasis>f</emphasis> or <emphasis>ff</emphasis> in its flags, the associated action is taken.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-Tqt</option>&nbsp;&lt;<emphasis>times</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-Tqt</option></primary>
+</indexterm>
+This is an option that is exclusively for use by the Exim testing suite. It is not
+recognized when Exim is run normally. It allows for the setting up of explicit
+<quote>queue times</quote> so that various warning/retry features can be tested.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-t</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-t</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>recipient</primary>
+<secondary>extracting from header lines</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>Bcc:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>Bcc:</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>Cc:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>Cc:</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>To:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>To:</secondary>
+</indexterm>
+When Exim is receiving a locally-generated, non-SMTP message on its standard
+input, the <option>-t</option> option causes the recipients of the message to be obtained
+from the <emphasis>To:</emphasis>, <emphasis>Cc:</emphasis>, and <emphasis>Bcc:</emphasis> header lines in the message instead of
+from the command arguments. The addresses are extracted before any rewriting
+takes place and the <emphasis>Bcc:</emphasis> header line, if present, is then removed.
+</para>
+<para>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-t</option> option</secondary>
+</indexterm>
+If the command has any arguments, they specify addresses to which the message
+is <emphasis>not</emphasis> to be delivered. That is, the argument addresses are removed from
+the recipients list obtained from the headers. This is compatible with Smail 3
+and in accordance with the documented behaviour of several versions of
+Sendmail, as described in man pages on a number of operating systems (e.g.
+Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail <emphasis>add</emphasis>
+argument addresses to those obtained from the headers, and the O&#x2019;Reilly
+Sendmail book documents it that way. Exim can be made to add argument addresses
+instead of subtracting them by setting the option
+<option>extract_addresses_remove_arguments</option> false.
+</para>
+<para>
+<indexterm role="concept">
+<primary><option>Resent-</option> header lines</primary>
+<secondary>with <option>-t</option></secondary>
+</indexterm>
+If there are any <option>Resent-</option> header lines in the message, Exim extracts
+recipients from all <emphasis>Resent-To:</emphasis>, <emphasis>Resent-Cc:</emphasis>, and <emphasis>Resent-Bcc:</emphasis> header
+lines instead of from <emphasis>To:</emphasis>, <emphasis>Cc:</emphasis>, and <emphasis>Bcc:</emphasis>. This is for compatibility
+with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
+<option>-t</option> was used in conjunction with <option>Resent-</option> header lines.)
+</para>
+<para>
+RFC 2822 talks about different sets of <option>Resent-</option> header lines (for when a
+message is resent several times). The RFC also specifies that they should be
+added at the front of the message, and separated by <emphasis>Received:</emphasis> lines. It is
+not at all clear how <option>-t</option> should operate in the present of multiple sets,
+nor indeed exactly what constitutes a <quote>set</quote>.
+In practice, it seems that MUAs do not follow the RFC. The <option>Resent-</option> lines
+are often added at the end of the header, and if a message is resent more than
+once, it is common for the original set of <option>Resent-</option> headers to be renamed as
+<option>X-Resent-</option> when a new set is added. This removes any possible ambiguity.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-ti</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-ti</option></primary>
+</indexterm>
+This option is exactly equivalent to <option>-t</option> <option>-i</option>. It is provided for
+compatibility with Sendmail.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-tls-on-connect</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-tls-on-connect</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>TLS</primary>
+<secondary>use without STARTTLS</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>TLS</primary>
+<secondary>automatic start</secondary>
+</indexterm>
+This option is available when Exim is compiled with TLS support. It forces all
+incoming SMTP connections to behave as if the incoming port is listed in the
+<option>tls_on_connect_ports</option> option. See section <xref linkend="SECTsupobssmt"/> and chapter
+<xref linkend="CHAPTLS"/> for further details.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-U</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-U</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Sendmail compatibility</primary>
+<secondary><option>-U</option> option ignored</secondary>
+</indexterm>
+Sendmail uses this option for <quote>initial message submission</quote>, and its
+documentation states that in future releases, it may complain about
+syntactically invalid messages rather than fixing them when this flag is not
+set. Exim ignores this option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-v</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-v</option></primary>
+</indexterm>
+This option causes Exim to write information to the standard error stream,
+describing what it is doing. In particular, it shows the log lines for
+receiving and delivering a message, and if an SMTP connection is made, the SMTP
+dialogue is shown. Some of the log lines shown may not actually be written to
+the log if the setting of <option>log_selector</option> discards them. Any relevant
+selectors are shown with each log line. If none are shown, the logging is
+unconditional.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-x</option></term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-x</option></primary>
+</indexterm>
+AIX uses <option>-x</option> for a private purpose (<quote>mail from a local mail program has
+National Language Support extended characters in the body of the mail item</quote>).
+It sets <option>-x</option> when calling the MTA from its <option>mail</option> command. Exim ignores
+this option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-X</option>&nbsp;&lt;<emphasis>logfile</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-X</option></primary>
+</indexterm>
+This option is interpreted by Sendmail to cause debug information to be sent
+to the named file.  It is ignored by Exim.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><option>-z</option>&nbsp;&lt;<emphasis>log-line</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="option">
+<primary><option>-z</option></primary>
+</indexterm>
+This option writes its argument to Exim&#x2019;s logfile.
+Use is restricted to administrators; the intent is for operational notes.
+Quotes should be used to maintain a multi-word item as a single argument,
+under most shells.
+</para>
+</listitem></varlistentry>
+</variablelist>
+<para>
+<indexterm role="concept" startref="IIDclo1" class="endofrange"/>
+<indexterm role="concept" startref="IIDclo2" class="endofrange"/>
+</para>
+<!-- === End of command line options === -->
+</section>
+</chapter>
+
+<chapter id="CHAPconf">
+<title>The Exim runtime configuration file</title>
+<titleabbrev>The runtime configuration file</titleabbrev>
+<para>
+<indexterm role="concept">
+<primary>runtime configuration</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>general description</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>CONFIGURE_FILE</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>errors in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>error</primary>
+<secondary>in configuration file</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>for bad configuration</secondary>
+</indexterm>
+Exim uses a single runtime configuration file that is read whenever an Exim
+binary is executed. Note that in normal operation, this happens frequently,
+because Exim is designed to operate in a distributed manner, without central
+control.
+</para>
+<para>
+If a syntax error is detected while reading the configuration file, Exim
+writes a message on the standard error, and exits with a non-zero return code.
+The message is also written to the panic log. <emphasis role="bold">Note</emphasis>: Only simple syntax
+errors can be detected at this time. The values of any expanded options are
+not checked until the expansion happens, even when the expansion does not
+actually alter the string.
+</para>
+<para>
+The name of the configuration file is compiled into the binary for security
+reasons, and is specified by the CONFIGURE_FILE compilation option. In
+most configurations, this specifies a single file. However, it is permitted to
+give a colon-separated list of filenames, in which case Exim uses the first
+existing file in the list.
+</para>
+<para>
+<indexterm role="concept">
+<primary>EXIM_USER</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>EXIM_GROUP</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>CONFIGURE_OWNER</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>CONFIGURE_GROUP</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>ownership</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>ownership</primary>
+<secondary>configuration file</secondary>
+</indexterm>
+The runtime configuration file must be owned by root or by the user that is
+specified at compile time by the CONFIGURE_OWNER option (if set). The
+configuration file must not be world-writeable, or group-writeable unless its
+group is the root group or the one specified at compile time by the
+CONFIGURE_GROUP option.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: In a conventional configuration, where the Exim binary is setuid
+to root, anybody who is able to edit the runtime configuration file has an
+easy way to run commands as root. If you specify a user or group in the
+CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users
+who are members of that group will trivially be able to obtain root privileges.
+</para>
+<para>
+Up to Exim version 4.72, the runtime configuration file was also permitted to
+be writeable by the Exim user and/or group. That has been changed in Exim 4.73
+since it offered a simple privilege escalation for any attacker who managed to
+compromise the Exim user account.
+</para>
+<para>
+A default configuration file, which will work correctly in simple situations,
+is provided in the file <filename>src/configure.default</filename>. If CONFIGURE_FILE
+defines just one filename, the installation process copies the default
+configuration to a new file of that name if it did not previously exist. If
+CONFIGURE_FILE is a list, no default is automatically installed. Chapter
+<xref linkend="CHAPdefconfil"/> is a <quote>walk-through</quote> discussion of the default
+configuration.
+</para>
+<section id="SECID40">
+<title>Using a different configuration file</title>
+<para>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>alternate</secondary>
+</indexterm>
+A one-off alternate configuration can be specified by the <option>-C</option> command line
+option, which may specify a single file or a list of files. However, when
+<option>-C</option> is used, Exim gives up its root privilege, unless called by root (or
+unless the argument for <option>-C</option> is identical to the built-in value from
+CONFIGURE_FILE), or is listed in the TRUSTED_CONFIG_LIST file and the caller
+is the Exim user or the user specified in the CONFIGURE_OWNER setting. <option>-C</option>
+is useful mainly for checking the syntax of configuration files before
+installing them. No owner or group checks are done on a configuration file
+specified by <option>-C</option>, if root privilege has been dropped.
+</para>
+<para>
+Even the Exim user is not trusted to specify an arbitrary configuration file
+with the <option>-C</option> option to be used with root privileges, unless that file is
+listed in the TRUSTED_CONFIG_LIST file. This locks out the possibility of
+testing a configuration using <option>-C</option> right through message reception and
+delivery, even if the caller is root. The reception works, but by that time,
+Exim is running as the Exim user, so when it re-execs to regain privilege for
+the delivery, the use of <option>-C</option> causes privilege to be lost. However, root
+can test reception and delivery using two separate commands (one to put a
+message in the queue, using <option>-odq</option>, and another to do the delivery, using
+<option>-M</option>).
+</para>
+<para>
+If ALT_CONFIG_PREFIX is defined <filename>in Local/Makefile</filename>, it specifies a
+prefix string with which any file named in a <option>-C</option> command line option must
+start. In addition, the filename must not contain the sequence <quote><literal>/../</literal></quote>.
+There is no default setting for ALT_CONFIG_PREFIX; when it is unset, any
+filename can be used with <option>-C</option>.
+</para>
+<para>
+One-off changes to a configuration can be specified by the <option>-D</option> command line
+option, which defines and overrides values for macros used inside the
+configuration file. However, like <option>-C</option>, the use of this option by a
+non-privileged user causes Exim to discard its root privilege.
+If DISABLE_D_OPTION is defined in <filename>Local/Makefile</filename>, the use of <option>-D</option> is
+completely disabled, and its use causes an immediate error exit.
+</para>
+<para>
+The WHITELIST_D_MACROS option in <filename>Local/Makefile</filename> permits the binary builder
+to declare certain macro names trusted, such that root privilege will not
+necessarily be discarded.
+WHITELIST_D_MACROS defines a colon-separated list of macros which are
+considered safe and, if <option>-D</option> only supplies macros from this list, and the
+values are acceptable, then Exim will not give up root privilege if the caller
+is root, the Exim run-time user, or the CONFIGURE_OWNER, if set.  This is a
+transition mechanism and is expected to be removed in the future.  Acceptable
+values for the macros satisfy the regexp: <literal>^[A-Za-z0-9_/.-]*$</literal>
+</para>
+<para>
+Some sites may wish to use the same Exim binary on different machines that
+share a file system, but to use different configuration files on each machine.
+If CONFIGURE_FILE_USE_NODE is defined in <filename>Local/Makefile</filename>, Exim first
+looks for a file whose name is the configuration filename followed by a dot
+and the machine&#x2019;s node name, as obtained from the <function>uname()</function> function. If this
+file does not exist, the standard name is tried. This processing occurs for
+each filename in the list given by CONFIGURE_FILE or <option>-C</option>.
+</para>
+<para>
+In some esoteric situations different versions of Exim may be run under
+different effective uids and the CONFIGURE_FILE_USE_EUID is defined to
+help with this. See the comments in <filename>src/EDITME</filename> for details.
+</para>
+</section>
+<section id="SECTconffilfor">
+<title>Configuration file format</title>
+<para>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>format of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>configuration file</secondary>
+</indexterm>
+Exim&#x2019;s configuration file is divided into a number of different parts. General
+option settings must always appear at the start of the file. The other parts
+are all optional, and may appear in any order. Each part other than the first
+is introduced by the word <quote>begin</quote> followed by at least one literal
+space, and the name of the part. The optional parts are:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<emphasis>ACL</emphasis>: Access control lists for controlling incoming SMTP mail (see chapter
+<xref linkend="CHAPACL"/>).
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>AUTH</primary>
+<secondary>configuration</secondary>
+</indexterm>
+<emphasis>authenticators</emphasis>: Configuration settings for the authenticator drivers. These
+are concerned with the SMTP AUTH command (see chapter <xref linkend="CHAPSMTPAUTH"/>).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>routers</emphasis>: Configuration settings for the router drivers. Routers process
+addresses and determine how the message is to be delivered (see chapters
+<xref linkend="CHAProutergeneric"/>&ndash;<xref linkend="CHAPredirect"/>).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>transports</emphasis>: Configuration settings for the transport drivers. Transports
+define mechanisms for copying messages to destinations (see chapters
+<xref linkend="CHAPtransportgeneric"/>&ndash;<xref linkend="CHAPsmtptrans"/>).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>retry</emphasis>: Retry rules, for use when a message cannot be delivered immediately.
+If there is no retry section, or if it is empty (that is, no retry rules are
+defined), Exim will not retry deliveries. In this situation, temporary errors
+are treated the same as permanent errors. Retry rules are discussed in chapter
+<xref linkend="CHAPretry"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>rewrite</emphasis>: Global address rewriting rules, for use when a message arrives and
+when new addresses are generated during delivery. Rewriting is discussed in
+chapter <xref linkend="CHAPrewrite"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis>local_scan</emphasis>: Private options for the <function>local_scan()</function> function. If you
+want to use this feature, you must set
+</para>
+<literallayout class="monospaced">
+LOCAL_SCAN_HAS_OPTIONS=yes
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename> before building Exim. Details of the <function>local_scan()</function>
+facility are given in chapter <xref linkend="CHAPlocalscan"/>.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>leading white space in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>trailing white space in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>white space</primary>
+<secondary>in configuration file</secondary>
+</indexterm>
+Leading and trailing white space in configuration lines is always ignored.
+</para>
+<para>
+Blank lines in the file, and lines starting with a # character (ignoring
+leading white space) are treated as comments and are ignored. <emphasis role="bold">Note</emphasis>: A
+# character other than at the beginning of a line is not treated specially,
+and does not introduce a comment.
+</para>
+<para>
+Any non-comment line can be continued by ending it with a backslash. Note that
+the general rule for white space means that trailing white space after the
+backslash and leading white space at the start of continuation
+lines is ignored. Comment lines beginning with # (but not empty lines) may
+appear in the middle of a sequence of continuation lines.
+</para>
+<para>
+A convenient way to create a configuration file is to start from the
+default, which is supplied in <filename>src/configure.default</filename>, and add, delete, or
+change settings as required.
+</para>
+<para>
+The ACLs, retry rules, and rewriting rules have their own syntax which is
+described in chapters <xref linkend="CHAPACL"/>, <xref linkend="CHAPretry"/>, and <xref linkend="CHAPrewrite"/>,
+respectively. The other parts of the configuration file have some syntactic
+items in common, and these are described below, from section <xref linkend="SECTcos"/>
+onwards. Before that, the inclusion, macro, and conditional facilities are
+described.
+</para>
+</section>
+<section id="SECID41">
+<title>File inclusions in the configuration file</title>
+<para>
+<indexterm role="concept">
+<primary>inclusions in configuration file</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>including other files</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>.include</literal> in configuration file</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>.include_if_exists</literal> in configuration file</primary>
+</indexterm>
+You can include other files inside Exim&#x2019;s runtime configuration file by
+using this syntax:
+</para>
+<literallayout>
+<literal>.include</literal> &lt;<emphasis>filename</emphasis>&gt;
+<literal>.include_if_exists</literal> &lt;<emphasis>filename</emphasis>&gt;
+</literallayout>
+<para>
+on a line by itself. Double quotes round the filename are optional. If you use
+the first form, a configuration error occurs if the file does not exist; the
+second form does nothing for non-existent files.
+The first form allows a relative name. It is resolved relative to
+the directory of the including file. For the second form an absolute filename
+is required.
+</para>
+<para>
+Includes may be nested to any depth, but remember that Exim reads its
+configuration file often, so it is a good idea to keep them to a minimum.
+If you change the contents of an included file, you must HUP the daemon,
+because an included file is read only when the configuration itself is read.
+</para>
+<para>
+The processing of inclusions happens early, at a physical line level, so, like
+comment lines, an inclusion can be used in the middle of an option setting,
+for example:
+</para>
+<literallayout class="monospaced">
+hosts_lookup = a.b.c \
+               .include /some/file
+</literallayout>
+<para>
+Include processing happens after macro processing (see below). Its effect is to
+process the lines of the included file as if they occurred inline where the
+inclusion appears.
+</para>
+</section>
+<section id="SECTmacrodefs">
+<title>Macros in the configuration file</title>
+<para>
+<indexterm role="concept">
+<primary>macro</primary>
+<secondary>description of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>macros</secondary>
+</indexterm>
+If a line in the main part of the configuration (that is, before the first
+<quote>begin</quote> line) begins with an upper case letter, it is taken as a macro
+definition, and must be of the form
+</para>
+<literallayout>
+&lt;<emphasis>name</emphasis>&gt; = &lt;<emphasis>rest of line</emphasis>&gt;
+</literallayout>
+<para>
+The name must consist of letters, digits, and underscores, and need not all be
+in upper case, though that is recommended. The rest of the line, including any
+continuations, is the replacement text, and has leading and trailing white
+space removed. Quotes are not removed. The replacement text can never end with
+a backslash character, but this doesn&#x2019;t seem to be a serious limitation.
+</para>
+<para>
+Macros may also be defined between router, transport, authenticator, or ACL
+definitions. They may not, however, be defined within an individual driver or
+ACL, or in the <option>local_scan</option>, retry, or rewrite sections of the configuration.
+</para>
+</section>
+<section id="SECID42">
+<title>Macro substitution</title>
+<para>
+Once a macro is defined, all subsequent lines in the file (and any included
+files) are scanned for the macro name; if there are several macros, the line is
+scanned for each, in turn, in the order in which the macros are defined. The
+replacement text is not re-scanned for the current macro, though it is scanned
+for subsequently defined macros. For this reason, a macro name may not contain
+the name of a previously defined macro as a substring. You could, for example,
+define
+</para>
+<literallayout>
+<literal>ABCD_XYZ = </literal>&lt;<emphasis>something</emphasis>&gt;
+<literal>ABCD = </literal>&lt;<emphasis>something else</emphasis>&gt;
+</literallayout>
+<para>
+but putting the definitions in the opposite order would provoke a configuration
+error. Macro expansion is applied to individual physical lines from the file,
+before checking for line continuation or file inclusion (see above). If a line
+consists solely of a macro name, and the expansion of the macro is empty, the
+line is ignored. A macro at the start of a line may turn the line into a
+comment line or a <literal>.include</literal> line.
+</para>
+</section>
+<section id="SECID43">
+<title>Redefining macros</title>
+<para>
+Once defined, the value of a macro can be redefined later in the configuration
+(or in an included file). Redefinition is specified by using <emphasis>==</emphasis> instead of
+<emphasis>=</emphasis>. For example:
+</para>
+<literallayout class="monospaced">
+MAC =  initial value
+...
+MAC == updated value
+</literallayout>
+<para>
+Redefinition does not alter the order in which the macros are applied to the
+subsequent lines of the configuration file. It is still the same order in which
+the macros were originally defined. All that changes is the macro&#x2019;s value.
+Redefinition makes it possible to accumulate values. For example:
+</para>
+<literallayout class="monospaced">
+MAC =  initial value
+...
+MAC == MAC and something added
+</literallayout>
+<para>
+This can be helpful in situations where the configuration file is built
+from a number of other files.
+</para>
+</section>
+<section id="SECID44">
+<title>Overriding macro values</title>
+<para>
+The values set for macros in the configuration file can be overridden by the
+<option>-D</option> command line option, but Exim gives up its root privilege when <option>-D</option> is
+used, unless called by root or the Exim user. A definition on the command line
+using the <option>-D</option> option causes all definitions and redefinitions within the
+file to be ignored.
+</para>
+</section>
+<section id="SECID45">
+<title>Example of macro usage</title>
+<para>
+As an example of macro usage, consider a configuration where aliases are looked
+up in a MySQL database. It helps to keep the file less cluttered if long
+strings such as SQL statements are defined separately as macros, for example:
+</para>
+<literallayout class="monospaced">
+ALIAS_QUERY = select mailbox from user where \
+              login='${quote_mysql:$local_part}';
+</literallayout>
+<para>
+This can then be used in a <command>redirect</command> router setting like this:
+</para>
+<literallayout class="monospaced">
+data = ${lookup mysql{ALIAS_QUERY}}
+</literallayout>
+<para>
+In earlier versions of Exim macros were sometimes used for domain, host, or
+address lists. In Exim 4 these are handled better by named lists &ndash; see
+section <xref linkend="SECTnamedlists"/>.
+</para>
+</section>
+<section id="SECTbuiltinmacros">
+<title>Builtin macros</title>
+<para>
+Exim defines some macros depending on facilities available, which may
+differ due to build-time definitions and from one release to another.
+All of these macros start with an underscore.
+They can be used to conditionally include parts of a configuration
+(see below).
+</para>
+<para>
+The following classes of macros are defined:
+</para>
+<literallayout>
+<literal> _HAVE_*                    </literal>  build-time defines
+<literal> _DRIVER_ROUTER_*           </literal>  router drivers
+<literal> _DRIVER_TRANSPORT_*        </literal>  transport drivers
+<literal> _DRIVER_AUTHENTICATOR_*    </literal>  authenticator drivers
+<literal> _LOG_*                     </literal>  log_selector values
+<literal> _OPT_MAIN_*                </literal>  main config options
+<literal> _OPT_ROUTERS_*             </literal>  generic router options
+<literal> _OPT_TRANSPORTS_*          </literal>  generic transport options
+<literal> _OPT_AUTHENTICATORS_*      </literal>  generic authenticator options
+<literal> _OPT_ROUTER_*_*            </literal>  private router options
+<literal> _OPT_TRANSPORT_*_*         </literal>  private transport options
+<literal> _OPT_AUTHENTICATOR_*_*     </literal>  private authenticator options
+</literallayout>
+<para>
+Use an <quote>exim -bP macros</quote> command to get the list of macros.
+</para>
+</section>
+<section id="SECID46">
+<title>Conditional skips in the configuration file</title>
+<para>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>conditional skips</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>.ifdef</literal></primary>
+</indexterm>
+You can use the directives <literal>.ifdef</literal>, <literal>.ifndef</literal>, <literal>.elifdef</literal>,
+<literal>.elifndef</literal>, <literal>.else</literal>, and <literal>.endif</literal> to dynamically include or exclude
+portions of the configuration file. The processing happens whenever the file is
+read (that is, when an Exim binary starts to run).
+</para>
+<para>
+The implementation is very simple. Instances of the first four directives must
+be followed by text that includes the names of one or macros. The condition
+that is tested is whether or not any macro substitution has taken place in the
+line. Thus:
+</para>
+<literallayout class="monospaced">
+.ifdef AAA
+message_size_limit = 50M
+.else
+message_size_limit = 100M
+.endif
+</literallayout>
+<para>
+sets a message size limit of 50M if the macro <literal>AAA</literal> is defined
+(or <literal>A</literal> or <literal>AA</literal>), and 100M
+otherwise. If there is more than one macro named on the line, the condition
+is true if any of them are defined. That is, it is an <quote>or</quote> condition. To
+obtain an <quote>and</quote> condition, you need to use nested <literal>.ifdef</literal>s.
+</para>
+<para>
+Although you can use a macro expansion to generate one of these directives,
+it is not very useful, because the condition <quote>there was a macro substitution
+in this line</quote> will always be true.
+</para>
+<para>
+Text following <literal>.else</literal> and <literal>.endif</literal> is ignored, and can be used as comment
+to clarify complicated nestings.
+</para>
+</section>
+<section id="SECTcos">
+<title>Common option syntax</title>
+<para>
+<indexterm role="concept">
+<primary>common option syntax</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>syntax of common options</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration file</primary>
+<secondary>common option syntax</secondary>
+</indexterm>
+For the main set of options, driver options, and <function>local_scan()</function> options,
+each setting is on a line by itself, and starts with a name consisting of
+lower-case letters and underscores. Many options require a data value, and in
+these cases the name must be followed by an equals sign (with optional white
+space) and then the value. For example:
+</para>
+<literallayout class="monospaced">
+qualify_domain = mydomain.example.com
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>hiding configuration option values</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>configuration options</primary>
+<secondary>hiding value of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>hiding value of</secondary>
+</indexterm>
+Some option settings may contain sensitive data, for example, passwords for
+accessing databases. To stop non-admin users from using the <option>-bP</option> command
+line option to read these values, you can precede the option settings with the
+word <quote>hide</quote>. For example:
+</para>
+<literallayout class="monospaced">
+hide mysql_servers = localhost/users/admin/secret-password
+</literallayout>
+<para>
+For non-admin users, such options are displayed like this:
+</para>
+<literallayout class="monospaced">
+mysql_servers = &lt;value not displayable&gt;
+</literallayout>
+<para>
+If <quote>hide</quote> is used on a driver option, it hides the value of that option on
+all instances of the same driver.
+</para>
+<para>
+The following sections describe the syntax used for the different data types
+that are found in option settings.
+</para>
+</section>
+<section id="SECID47">
+<title>Boolean options</title>
+<para>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>boolean</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>boolean configuration values</primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>no_</option><emphasis>xxx</emphasis></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>not_</option><emphasis>xxx</emphasis></primary>
+</indexterm>
+Options whose type is given as boolean are on/off switches. There are two
+different ways of specifying such options: with and without a data value. If
+the option name is specified on its own without data, the switch is turned on;
+if it is preceded by <quote>no_</quote> or <quote>not_</quote> the switch is turned off. However,
+boolean options may be followed by an equals sign and one of the words
+<quote>true</quote>, <quote>false</quote>, <quote>yes</quote>, or <quote>no</quote>, as an alternative syntax. For example,
+the following two settings have exactly the same effect:
+</para>
+<literallayout class="monospaced">
+queue_only
+queue_only = true
+</literallayout>
+<para>
+The following two lines also have the same (opposite) effect:
+</para>
+<literallayout class="monospaced">
+no_queue_only
+queue_only = false
+</literallayout>
+<para>
+You can use whichever syntax you prefer.
+</para>
+</section>
+<section id="SECID48">
+<title>Integer values</title>
+<para>
+<indexterm role="concept">
+<primary>integer configuration values</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>integer</secondary>
+</indexterm>
+If an option&#x2019;s type is given as <quote>integer</quote>, the value can be given in decimal,
+hexadecimal, or octal. If it starts with a digit greater than zero, a decimal
+number is assumed. Otherwise, it is treated as an octal number unless it starts
+with the characters <quote>0x</quote>, in which case the remainder is interpreted as a
+hexadecimal number.
+</para>
+<para>
+If an integer value is followed by the letter K, it is multiplied by 1024; if
+it is followed by the letter M, it is multiplied by 1024x1024;
+if by the letter G, 1024x1024x1024.
+When the values
+of integer option settings are output, values which are an exact multiple of
+1024 or 1024x1024 are sometimes, but not always, printed using the letters K
+and M. The printing style is independent of the actual input format that was
+used.
+</para>
+</section>
+<section id="SECID49">
+<title>Octal integer values</title>
+<para>
+<indexterm role="concept">
+<primary>integer format</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>octal integer</secondary>
+</indexterm>
+If an option&#x2019;s type is given as <quote>octal integer</quote>, its value is always
+interpreted as an octal number, whether or not it starts with the digit zero.
+Such options are always output in octal.
+</para>
+</section>
+<section id="SECID50">
+<title>Fixed point numbers</title>
+<para>
+<indexterm role="concept">
+<primary>fixed point configuration values</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>fixed point</secondary>
+</indexterm>
+If an option&#x2019;s type is given as <quote>fixed-point</quote>, its value must be a decimal
+integer, optionally followed by a decimal point and up to three further digits.
+</para>
+</section>
+<section id="SECTtimeformat">
+<title>Time intervals</title>
+<para>
+<indexterm role="concept">
+<primary>time interval</primary>
+<secondary>specifying in configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>time interval</secondary>
+</indexterm>
+A time interval is specified as a sequence of numbers, each followed by one of
+the following letters, with no intervening white space:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="30pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<option>s</option></entry>
+<entry>seconds</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<option>m</option></entry>
+<entry>minutes</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<option>h</option></entry>
+<entry>hours</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<option>d</option></entry>
+<entry>days</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<option>w</option></entry>
+<entry>weeks</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+For example, <quote>3h50m</quote> specifies 3 hours and 50 minutes. The values of time
+intervals are output in the same format. Exim does not restrict the values; it
+is perfectly acceptable, for example, to specify <quote>90m</quote> instead of <quote>1h30m</quote>.
+</para>
+</section>
+<section id="SECTstrings">
+<title>String values</title>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>format of configuration values</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>string</secondary>
+</indexterm>
+If an option&#x2019;s type is specified as <quote>string</quote>, the value can be specified with
+or without double-quotes. If it does not start with a double-quote, the value
+consists of the remainder of the line plus any continuation lines, starting at
+the first character after any leading white space, with trailing white space
+removed, and with no interpretation of the characters in the string. Because
+Exim removes comment lines (those beginning with #) at an early stage, they can
+appear in the middle of a multi-line string. The following two settings are
+therefore equivalent:
+</para>
+<literallayout class="monospaced">
+trusted_users = uucp:mail
+trusted_users = uucp:\
+                # This comment line is ignored
+                mail
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>quoted</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>escape characters in quoted strings</primary>
+</indexterm>
+If a string does start with a double-quote, it must end with a closing
+double-quote, and any backslash characters other than those used for line
+continuation are interpreted as escape characters, as follows:
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="100pt" align="left"/>
+<colspec colwidth="254pt" align="left"/>
+<tbody>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\\</literal></entry>
+<entry>single backslash</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\n</literal></entry>
+<entry>newline</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\r</literal></entry>
+<entry>carriage return</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\t</literal></entry>
+<entry>tab</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\</literal>&lt;<emphasis>octal digits</emphasis>&gt;</entry>
+<entry>up to 3 octal digits specify one character</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<literal>\x</literal>&lt;<emphasis>hex digits</emphasis>&gt;</entry>
+<entry>up to 2 hexadecimal digits specify one character</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+If a backslash is followed by some other character, including a double-quote
+character, that character replaces the pair.
+</para>
+<para>
+Quoting is necessary only if you want to make use of the backslash escapes to
+insert special characters, or if you need to specify a value with leading or
+trailing spaces. These cases are rare, so quoting is almost never needed in
+current versions of Exim. In versions of Exim before 3.14, quoting was required
+in order to continue lines, so you may come across older configuration files
+and examples that apparently quote unnecessarily.
+</para>
+</section>
+<section id="SECID51">
+<title>Expanded strings</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>definition of</secondary>
+</indexterm>
+Some strings in the configuration file are subjected to <emphasis>string expansion</emphasis>,
+by which means various parts of the string may be changed according to the
+circumstances (see chapter <xref linkend="CHAPexpand"/>). The input syntax for such strings
+is as just described; in particular, the handling of backslashes in quoted
+strings is done as part of the input process, before expansion takes place.
+However, backslash is also an escape character for the expander, so any
+backslashes that are required for that reason must be doubled if they are
+within a quoted configuration string.
+</para>
+</section>
+<section id="SECID52">
+<title>User and group names</title>
+<para>
+<indexterm role="concept">
+<primary>user name</primary>
+<secondary>format of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>user name</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>groups</primary>
+<secondary>name format</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>group name</secondary>
+</indexterm>
+User and group names are specified as strings, using the syntax described
+above, but the strings are interpreted specially. A user or group name must
+either consist entirely of digits, or be a name that can be looked up using the
+<function>getpwnam()</function> or <function>getgrnam()</function> function, as appropriate.
+</para>
+</section>
+<section id="SECTlistconstruct">
+<title>List construction</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>syntax of in configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>format</primary>
+<secondary>list item in configuration</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>list, definition of</secondary>
+</indexterm>
+The data for some configuration options is a list of items, with colon as the
+default separator. Many of these options are shown with type <quote>string list</quote> in
+the descriptions later in this document. Others are listed as <quote>domain list</quote>,
+<quote>host list</quote>, <quote>address list</quote>, or <quote>local part list</quote>. Syntactically, they
+are all the same; however, those other than <quote>string list</quote> are subject to
+particular kinds of interpretation, as described in chapter
+<xref linkend="CHAPdomhosaddlists"/>.
+</para>
+<para>
+In all these cases, the entire list is treated as a single string as far as the
+input syntax is concerned. The <option>trusted_users</option> setting in section
+<xref linkend="SECTstrings"/> above is an example. If a colon is actually needed in an item
+in a list, it must be entered as two colons. Leading and trailing white space
+on each item in a list is ignored. This makes it possible to include items that
+start with a colon, and in particular, certain forms of IPv6 address. For
+example, the list
+</para>
+<literallayout class="monospaced">
+local_interfaces = 127.0.0.1 : ::::1
+</literallayout>
+<para>
+contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: Although leading and trailing white space is ignored in individual
+list items, it is not ignored when parsing the list. The spaces around the first
+colon in the example above are necessary. If they were not there, the list would
+be interpreted as the two items 127.0.0.1:: and 1.
+</para>
+</section>
+<section id="SECTlistsepchange">
+<title>Changing list separators</title>
+<para>
+<indexterm role="concept">
+<primary>list separator</primary>
+<secondary>changing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>IPv6</primary>
+<secondary>addresses in lists</secondary>
+</indexterm>
+Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was
+introduced to allow the separator character to be changed. If a list begins
+with a left angle bracket, followed by any punctuation character, that
+character is used instead of colon as the list separator. For example, the list
+above can be rewritten to use a semicolon separator like this:
+</para>
+<literallayout class="monospaced">
+local_interfaces = &lt;; 127.0.0.1 ; ::1
+</literallayout>
+<para>
+This facility applies to all lists, with the exception of the list in
+<option>log_file_path</option>. It is recommended that the use of non-colon separators be
+confined to circumstances where they really are needed.
+</para>
+<para>
+<indexterm role="concept">
+<primary>list separator</primary>
+<secondary>newline as</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>newline</primary>
+<secondary>as list separator</secondary>
+</indexterm>
+It is also possible to use newline and other control characters (those with
+code values less than 32, plus DEL) as separators in lists. Such separators
+must be provided literally at the time the list is processed. For options that
+are string-expanded, you can write the separator using a normal escape
+sequence. This will be processed by the expander before the string is
+interpreted as a list. For example, if a newline-separated list of domains is
+generated by a lookup, you can process it directly by a line such as this:
+</para>
+<literallayout class="monospaced">
+domains = &lt;\n ${lookup mysql{.....}}
+</literallayout>
+<para>
+This avoids having to change the list separator in such data. You are unlikely
+to want to use a control character as a separator in an option that is not
+expanded, because the value is literal text. However, it can be done by giving
+the value in quotes. For example:
+</para>
+<literallayout class="monospaced">
+local_interfaces = "&lt;\n 127.0.0.1 \n ::1"
+</literallayout>
+<para>
+Unlike printing character separators, which can be included in list items by
+doubling, it is not possible to include a control character as data when it is
+set as the separator. Two such characters in succession are interpreted as
+enclosing an empty list item.
+</para>
+</section>
+<section id="SECTempitelis">
+<title>Empty items in lists</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>empty item in</secondary>
+</indexterm>
+An empty item at the end of a list is always ignored. In other words, trailing
+separator characters are ignored. Thus, the list in
+</para>
+<literallayout class="monospaced">
+senders = user@domain :
+</literallayout>
+<para>
+contains only a single item. If you want to include an empty string as one item
+in a list, it must not be the last item. For example, this list contains three
+items, the second of which is empty:
+</para>
+<literallayout class="monospaced">
+senders = user1@domain : : user2@domain
+</literallayout>
+<para>
+<emphasis role="bold">Note</emphasis>: There must be white space between the two colons, as otherwise they
+are interpreted as representing a single colon data character (and the list
+would then contain just one item). If you want to specify a list that contains
+just one, empty item, you can do it as in this example:
+</para>
+<literallayout class="monospaced">
+senders = :
+</literallayout>
+<para>
+In this case, the first item is empty, and the second is discarded because it
+is at the end of the list.
+</para>
+</section>
+<section id="SECTfordricon">
+<title>Format of driver configurations</title>
+<para>
+<indexterm role="concept">
+<primary>drivers</primary>
+<secondary>configuration format</secondary>
+</indexterm>
+There are separate parts in the configuration for defining routers, transports,
+and authenticators. In each part, you are defining a number of driver
+instances, each with its own set of options. Each driver instance is defined by
+a sequence of lines like this:
+</para>
+<literallayout>
+&lt;<emphasis>instance name</emphasis>&gt;:
+  &lt;<emphasis>option</emphasis>&gt;
+  ...
+  &lt;<emphasis>option</emphasis>&gt;
+</literallayout>
+<para>
+In the following example, the instance name is <command>localuser</command>, and it is
+followed by three options settings:
+</para>
+<literallayout class="monospaced">
+localuser:
+  driver = accept
+  check_local_user
+  transport = local_delivery
+</literallayout>
+<para>
+For each driver instance, you specify which Exim code module it uses &ndash; by the
+setting of the <option>driver</option> option &ndash; and (optionally) some configuration
+settings. For example, in the case of transports, if you want a transport to
+deliver with SMTP you would use the <command>smtp</command> driver; if you want to deliver to
+a local file you would use the <command>appendfile</command> driver. Each of the drivers is
+described in detail in its own separate chapter later in this manual.
+</para>
+<para>
+You can have several routers, transports, or authenticators that are based on
+the same underlying driver (each must have a different instance name).
+</para>
+<para>
+The order in which routers are defined is important, because addresses are
+passed to individual routers one by one, in order. The order in which
+transports are defined does not matter at all. The order in which
+authenticators are defined is used only when Exim, as a client, is searching
+them to find one that matches an authentication mechanism offered by the
+server.
+</para>
+<para>
+<indexterm role="concept">
+<primary>generic options</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>generic &ndash; definition of</secondary>
+</indexterm>
+Within a driver instance definition, there are two kinds of option: <emphasis>generic</emphasis>
+and <emphasis>private</emphasis>. The generic options are those that apply to all drivers of the
+same type (that is, all routers, all transports or all authenticators). The
+<option>driver</option> option is a generic option that must appear in every definition.
+<indexterm role="concept">
+<primary>private options</primary>
+</indexterm>
+The private options are special for each driver, and none need appear, because
+they all have default values.
+</para>
+<para>
+The options may appear in any order, except that the <option>driver</option> option must
+precede any private options, since these depend on the particular driver. For
+this reason, it is recommended that <option>driver</option> always be the first option.
+</para>
+<para>
+Driver instance names, which are used for reference in log entries and
+elsewhere, can be any sequence of letters, digits, and underscores (starting
+with a letter) and must be unique among drivers of the same type. A router and
+a transport (for example) can each have the same name, but no two router
+instances can have the same name. The name of a driver instance should not be
+confused with the name of the underlying driver module. For example, the
+configuration lines:
+</para>
+<literallayout class="monospaced">
+remote_smtp:
+  driver = smtp
+</literallayout>
+<para>
+create an instance of the <command>smtp</command> transport driver whose name is
+<command>remote_smtp</command>. The same driver code can be used more than once, with
+different instance names and different option settings each time. A second
+instance of the <command>smtp</command> transport, with different options, might be defined
+thus:
+</para>
+<literallayout class="monospaced">
+special_smtp:
+  driver = smtp
+  port = 1234
+  command_timeout = 10s
+</literallayout>
+<para>
+The names <command>remote_smtp</command> and <command>special_smtp</command> would be used to reference
+these transport instances from routers, and these names would appear in log
+lines.
+</para>
+<para>
+Comment lines may be present in the middle of driver specifications. The full
+list of option settings for any particular driver instance, including all the
+defaulted values, can be extracted by making use of the <option>-bP</option> command line
+option.
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPdefconfil">
+<title>The default configuration file</title>
+<para>
+<indexterm role="concept" id="IIDconfiwal" class="startofrange">
+<primary>configuration file</primary>
+<secondary>default <quote>walk through</quote></secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>configuration file <quote>walk through</quote></secondary>
+</indexterm>
+The default configuration file supplied with Exim as <filename>src/configure.default</filename>
+is sufficient for a host with simple mail requirements. As an introduction to
+the way Exim is configured, this chapter <quote>walks through</quote> the default
+configuration, giving brief explanations of the settings. Detailed descriptions
+of the options are given in subsequent chapters. The default configuration file
+itself contains extensive comments about ways you might want to modify the
+initial settings. However, note that there are many options that are not
+mentioned at all in the default configuration.
+</para>
+<section id="SECTdefconfmacros">
+<title>Macros</title>
+<para>
+All macros should be defined before any options.
+</para>
+<para>
+One macro is specified, but commented out, in the default configuration:
+</para>
+<literallayout class="monospaced">
+# ROUTER_SMARTHOST=MAIL.HOSTNAME.FOR.CENTRAL.SERVER.EXAMPLE
+</literallayout>
+<para>
+If all off-site mail is expected to be delivered to a "smarthost", then set the
+hostname here and uncomment the macro.  This will affect which router is used
+later on.  If this is left commented out, then Exim will perform direct-to-MX
+deliveries using a <command>dnslookup</command> router.
+</para>
+<para>
+In addition to macros defined here, Exim includes a number of built-in macros
+to enable configuration to be guarded by a binary built with support for a
+given feature.  See section <xref linkend="SECTbuiltinmacros"/> for more details.
+</para>
+</section>
+<section id="SECTdefconfmain">
+<title>Main configuration settings</title>
+<para>
+The main (global) configuration option settings section must always come first
+in the file, after the macros.
+The first thing you&#x2019;ll see in the file, after some initial comments, is the line
+</para>
+<literallayout class="monospaced">
+# primary_hostname =
+</literallayout>
+<para>
+This is a commented-out setting of the <option>primary_hostname</option> option. Exim needs
+to know the official, fully qualified name of your host, and this is where you
+can specify it. However, in most cases you do not need to set this option. When
+it is unset, Exim uses the <function>uname()</function> system function to obtain the host name.
+</para>
+<para>
+The first three non-comment configuration lines are as follows:
+</para>
+<literallayout class="monospaced">
+domainlist local_domains    = @
+domainlist relay_to_domains =
+hostlist   relay_from_hosts = 127.0.0.1
+</literallayout>
+<para>
+These are not, in fact, option settings. They are definitions of two named
+domain lists and one named host list. Exim allows you to give names to lists of
+domains, hosts, and email addresses, in order to make it easier to manage the
+configuration file (see section <xref linkend="SECTnamedlists"/>).
+</para>
+<para>
+The first line defines a domain list called <emphasis>local_domains</emphasis>; this is used
+later in the configuration to identify domains that are to be delivered
+on the local host.
+</para>
+<para>
+<indexterm role="concept">
+<primary>@ in a domain list</primary>
+</indexterm>
+There is just one item in this list, the string <quote>@</quote>. This is a special form
+of entry which means <quote>the name of the local host</quote>. Thus, if the local host is
+called <emphasis>a.host.example</emphasis>, mail to <emphasis>any.user@???</emphasis> is expected to
+be delivered locally. Because the local host&#x2019;s name is referenced indirectly,
+the same configuration file can be used on different hosts.
+</para>
+<para>
+The second line defines a domain list called <emphasis>relay_to_domains</emphasis>, but the
+list itself is empty. Later in the configuration we will come to the part that
+controls mail relaying through the local host; it allows relaying to any
+domains in this list. By default, therefore, no relaying on the basis of a mail
+domain is permitted.
+</para>
+<para>
+The third line defines a host list called <emphasis>relay_from_hosts</emphasis>. This list is
+used later in the configuration to permit relaying from any host or IP address
+that matches the list. The default contains just the IP address of the IPv4
+loopback interface, which means that processes on the local host are able to
+submit mail for relaying by sending it over TCP/IP to that interface. No other
+hosts are permitted to submit messages for relaying.
+</para>
+<para>
+Just to be sure there&#x2019;s no misunderstanding: at this point in the configuration
+we aren&#x2019;t actually setting up any controls. We are just defining some domains
+and hosts that will be used in the controls that are specified later.
+</para>
+<para>
+The next two configuration lines are genuine option settings:
+</para>
+<literallayout class="monospaced">
+acl_smtp_rcpt = acl_check_rcpt
+acl_smtp_data = acl_check_data
+</literallayout>
+<para>
+These options specify <emphasis>Access Control Lists</emphasis> (ACLs) that are to be used
+during an incoming SMTP session for every recipient of a message (every RCPT
+command), and after the contents of the message have been received,
+respectively. The names of the lists are <emphasis>acl_check_rcpt</emphasis> and
+<emphasis>acl_check_data</emphasis>, and we will come to their definitions below, in the ACL
+section of the configuration. The RCPT ACL controls which recipients are
+accepted for an incoming message &ndash; if a configuration does not provide an ACL
+to check recipients, no SMTP mail can be accepted. The DATA ACL allows the
+contents of a message to be checked.
+</para>
+<para>
+Two commented-out option settings are next:
+</para>
+<literallayout class="monospaced">
+# av_scanner = clamd:/tmp/clamd
+# spamd_address = 127.0.0.1 783
+</literallayout>
+<para>
+These are example settings that can be used when Exim is compiled with the
+content-scanning extension. The first specifies the interface to the virus
+scanner, and the second specifies the interface to SpamAssassin. Further
+details are given in chapter <xref linkend="CHAPexiscan"/>.
+</para>
+<para>
+Three more commented-out option settings follow:
+</para>
+<literallayout class="monospaced">
+# tls_advertise_hosts = *
+# tls_certificate = /etc/ssl/exim.crt
+# tls_privatekey = /etc/ssl/exim.pem
+</literallayout>
+<para>
+These are example settings that can be used when Exim is compiled with
+support for TLS (aka SSL) as described in section <xref linkend="SECTinctlsssl"/>. The
+first one specifies the list of clients that are allowed to use TLS when
+connecting to this server; in this case, the wildcard means all clients. The
+other options specify where Exim should find its TLS certificate and private
+key, which together prove the server&#x2019;s identity to any clients that connect.
+More details are given in chapter <xref linkend="CHAPTLS"/>.
+</para>
+<para>
+Another two commented-out option settings follow:
+</para>
+<literallayout class="monospaced">
+# daemon_smtp_ports = 25 : 465 : 587
+# tls_on_connect_ports = 465
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>port</primary>
+<secondary>465 and 587</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>port</primary>
+<secondary>for message submission</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>message</primary>
+<secondary>submission, ports for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>submissions protocol</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>smtps protocol</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>ssmtp protocol</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>submissions protocol</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>ssmtp protocol</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SMTP</primary>
+<secondary>smtps protocol</secondary>
+</indexterm>
+These options provide better support for roaming users who wish to use this
+server for message submission. They are not much use unless you have turned on
+TLS (as described in the previous paragraph) and authentication (about which
+more in section <xref linkend="SECTdefconfauth"/>).
+Mail submission from mail clients (MUAs) should be separate from inbound mail
+to your domain (MX delivery) for various good reasons (eg, ability to impose
+much saner TLS protocol and ciphersuite requirements without unintended
+consequences).
+RFC 6409 (previously 4409) specifies use of port 587 for SMTP Submission,
+which uses STARTTLS, so this is the <quote>submission</quote> port.
+RFC 8314 specifies use of port 465 as the <quote>submissions</quote> protocol,
+which should be used in preference to 587.
+You should also consider deploying SRV records to help clients find
+these ports.
+Older names for <quote>submissions</quote> are <quote>smtps</quote> and <quote>ssmtp</quote>.
+</para>
+<para>
+Two more commented-out options settings follow:
+</para>
+<literallayout class="monospaced">
+# qualify_domain =
+# qualify_recipient =
+</literallayout>
+<para>
+The first of these specifies a domain that Exim uses when it constructs a
+complete email address from a local login name. This is often needed when Exim
+receives a message from a local process. If you do not set <option>qualify_domain</option>,
+the value of <option>primary_hostname</option> is used. If you set both of these options,
+you can have different qualification domains for sender and recipient
+addresses. If you set only the first one, its value is used in both cases.
+</para>
+<para>
+<indexterm role="concept">
+<primary>domain literal</primary>
+<secondary>recognizing format</secondary>
+</indexterm>
+The following line must be uncommented if you want Exim to recognize
+addresses of the form <emphasis>user@???</emphasis> that is, with a <quote>domain literal</quote>
+(an IP address within square brackets) instead of a named domain.
+</para>
+<literallayout class="monospaced">
+# allow_domain_literals
+</literallayout>
+<para>
+The RFCs still require this form, but many people think that in the modern
+Internet it makes little sense to permit mail to be sent to specific hosts by
+quoting their IP addresses. This ancient format has been used by people who
+try to abuse hosts by using them for unwanted relaying. However, some
+people believe there are circumstances (for example, messages addressed to
+<emphasis>postmaster</emphasis>) where domain literals are still useful.
+</para>
+<para>
+The next configuration line is a kind of trigger guard:
+</para>
+<literallayout class="monospaced">
+never_users = root
+</literallayout>
+<para>
+It specifies that no delivery must ever be run as the root user. The normal
+convention is to set up <emphasis>root</emphasis> as an alias for the system administrator. This
+setting is a guard against slips in the configuration.
+The list of users specified by <option>never_users</option> is not, however, the complete
+list; the build-time configuration in <filename>Local/Makefile</filename> has an option called
+FIXED_NEVER_USERS specifying a list that cannot be overridden. The
+contents of <option>never_users</option> are added to this list. By default
+FIXED_NEVER_USERS also specifies root.
+</para>
+<para>
+When a remote host connects to Exim in order to send mail, the only information
+Exim has about the host&#x2019;s identity is its IP address. The next configuration
+line,
+</para>
+<literallayout class="monospaced">
+host_lookup = *
+</literallayout>
+<para>
+specifies that Exim should do a reverse DNS lookup on all incoming connections,
+in order to get a host name. This improves the quality of the logging
+information, but if you feel it is too expensive, you can remove it entirely,
+or restrict the lookup to hosts on <quote>nearby</quote> networks.
+Note that it is not always possible to find a host name from an IP address,
+because not all DNS reverse zones are maintained, and sometimes DNS servers are
+unreachable.
+</para>
+<para>
+The next two lines are concerned with <emphasis>ident</emphasis> callbacks, as defined by RFC
+1413 (hence their names):
+</para>
+<literallayout class="monospaced">
+rfc1413_hosts = *
+rfc1413_query_timeout = 0s
+</literallayout>
+<para>
+These settings cause Exim to avoid ident callbacks for all incoming SMTP calls.
+Few hosts offer RFC1413 service these days; calls have to be
+terminated by a timeout and this needlessly delays the startup
+of an incoming SMTP connection.
+If you have hosts for which you trust RFC1413 and need this
+information, you can change this.
+</para>
+<para>
+This line enables an efficiency SMTP option.  It is negotiated by clients
+and not expected to cause problems but can be disabled if needed.
+</para>
+<literallayout class="monospaced">
+prdr_enable = true
+</literallayout>
+<para>
+When Exim receives messages over SMTP connections, it expects all addresses to
+be fully qualified with a domain, as required by the SMTP definition. However,
+if you are running a server to which simple clients submit messages, you may
+find that they send unqualified addresses. The two commented-out options:
+</para>
+<literallayout class="monospaced">
+# sender_unqualified_hosts =
+# recipient_unqualified_hosts =
+</literallayout>
+<para>
+show how you can specify hosts that are permitted to send unqualified sender
+and recipient addresses, respectively.
+</para>
+<para>
+The <option>log_selector</option> option is used to increase the detail of logging
+over the default:
+</para>
+<literallayout class="monospaced">
+log_selector = +smtp_protocol_error +smtp_syntax_error \
+               +tls_certificate_verified
+</literallayout>
+<para>
+The <option>percent_hack_domains</option> option is also commented out:
+</para>
+<literallayout class="monospaced">
+# percent_hack_domains =
+</literallayout>
+<para>
+It provides a list of domains for which the <quote>percent hack</quote> is to operate.
+This is an almost obsolete form of explicit email routing. If you do not know
+anything about it, you can safely ignore this topic.
+</para>
+<para>
+The next two settings in the main part of the default configuration are
+concerned with messages that have been <quote>frozen</quote> on Exim&#x2019;s queue. When a
+message is frozen, Exim no longer continues to try to deliver it. Freezing
+occurs when a bounce message encounters a permanent failure because the sender
+address of the original message that caused the bounce is invalid, so the
+bounce cannot be delivered. This is probably the most common case, but there
+are also other conditions that cause freezing, and frozen messages are not
+always bounce messages.
+</para>
+<literallayout class="monospaced">
+ignore_bounce_errors_after = 2d
+timeout_frozen_after = 7d
+</literallayout>
+<para>
+The first of these options specifies that failing bounce messages are to be
+discarded after 2 days in the queue. The second specifies that any frozen
+message (whether a bounce message or not) is to be timed out (and discarded)
+after a week. In this configuration, the first setting ensures that no failing
+bounce message ever lasts a week.
+</para>
+<para>
+Exim queues it&#x2019;s messages in a spool directory. If you expect to have
+large queues, you may consider using this option. It splits the spool
+directory into subdirectories to avoid file system degradation from
+many files in a single directory, resulting in better performance.
+Manual manipulation of queued messages becomes more complex (though fortunately
+not often needed).
+</para>
+<literallayout class="monospaced">
+# split_spool_directory = true
+</literallayout>
+<para>
+In an ideal world everybody follows the standards. For non-ASCII
+messages RFC 2047 is a standard, allowing a maximum line length of 76
+characters. Exim adheres that standard and won&#x2019;t process messages which
+violate this standard. (Even ${rfc2047:...} expansions will fail.)
+In particular, the Exim maintainers have had multiple reports of
+problems from Russian administrators of issues until they disable this
+check, because of some popular, yet buggy, mail composition software.
+</para>
+<literallayout class="monospaced">
+# check_rfc2047_length = false
+</literallayout>
+<para>
+If you need to be strictly RFC compliant you may wish to disable the
+8BITMIME advertisement. Use this, if you exchange mails with systems
+that are not 8-bit clean.
+</para>
+<literallayout class="monospaced">
+# accept_8bitmime = false
+</literallayout>
+<para>
+Libraries you use may depend on specific environment settings.  This
+imposes a security risk (e.g. PATH). There are two lists:
+<option>keep_environment</option> for the variables to import as they are, and
+<option>add_environment</option> for variables we want to set to a fixed value.
+Note that TZ is handled separately, by the <option>timezone</option> runtime
+option and by the TIMEZONE_DEFAULT buildtime option.
+</para>
+<literallayout class="monospaced">
+# keep_environment = ^LDAP
+# add_environment = PATH=/usr/bin::/bin
+</literallayout>
+</section>
+<section id="SECID54">
+<title>ACL configuration</title>
+<para>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>ACLs</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>access control lists (ACLs)</primary>
+<secondary>default configuration</secondary>
+</indexterm>
+In the default configuration, the ACL section follows the main configuration.
+It starts with the line
+</para>
+<literallayout class="monospaced">
+begin acl
+</literallayout>
+<para>
+and it contains the definitions of two ACLs, called <emphasis>acl_check_rcpt</emphasis> and
+<emphasis>acl_check_data</emphasis>, that were referenced in the settings of <option>acl_smtp_rcpt</option>
+and <option>acl_smtp_data</option> above.
+</para>
+<para>
+<indexterm role="concept">
+<primary>RCPT</primary>
+<secondary>ACL for</secondary>
+</indexterm>
+The first ACL is used for every RCPT command in an incoming SMTP message. Each
+RCPT command specifies one of the message&#x2019;s recipients. The ACL statements
+are considered in order, until the recipient address is either accepted or
+rejected. The RCPT command is then accepted or rejected, according to the
+result of the ACL processing.
+</para>
+<literallayout class="monospaced">
+acl_check_rcpt:
+</literallayout>
+<para>
+This line, consisting of a name terminated by a colon, marks the start of the
+ACL, and names it.
+</para>
+<literallayout class="monospaced">
+accept  hosts = :
+</literallayout>
+<para>
+This ACL statement accepts the recipient if the sending host matches the list.
+But what does that strange list mean? It doesn&#x2019;t actually contain any host
+names or IP addresses. The presence of the colon puts an empty item in the
+list; Exim matches this only if the incoming message did not come from a remote
+host, because in that case, the remote hostname is empty. The colon is
+important. Without it, the list itself is empty, and can never match anything.
+</para>
+<para>
+What this statement is doing is to accept unconditionally all recipients in
+messages that are submitted by SMTP from local processes using the standard
+input and output (that is, not using TCP/IP). A number of MUAs operate in this
+manner.
+</para>
+<literallayout class="monospaced">
+deny    domains       = +local_domains
+        local_parts   = ^[.] : ^.*[@%!/|]
+        message       = Restricted characters in address
+
+deny    domains       = !+local_domains
+        local_parts   = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
+        message       = Restricted characters in address
+</literallayout>
+<para>
+These statements are concerned with local parts that contain any of the
+characters <quote>@</quote>, <quote>%</quote>, <quote>!</quote>, <quote>/</quote>, <quote>|</quote>, or dots in unusual places.
+Although these characters are entirely legal in local parts (in the case of
+<quote>@</quote> and leading dots, only if correctly quoted), they do not commonly occur
+in Internet mail addresses.
+</para>
+<para>
+The first three have in the past been associated with explicitly routed
+addresses (percent is still sometimes used &ndash; see the <option>percent_hack_domains</option>
+option). Addresses containing these characters are regularly tried by spammers
+in an attempt to bypass relaying restrictions, and also by open relay testing
+programs. Unless you really need them it is safest to reject these characters
+at this early stage. This configuration is heavy-handed in rejecting these
+characters for all messages it accepts from remote hosts. This is a deliberate
+policy of being as safe as possible.
+</para>
+<para>
+The first rule above is stricter, and is applied to messages that are addressed
+to one of the local domains handled by this host. This is implemented by the
+first condition, which restricts it to domains that are listed in the
+<emphasis>local_domains</emphasis> domain list. The <quote>+</quote> character is used to indicate a
+reference to a named list. In this configuration, there is just one domain in
+<emphasis>local_domains</emphasis>, but in general there may be many.
+</para>
+<para>
+The second condition on the first statement uses two regular expressions to
+block local parts that begin with a dot or contain <quote>@</quote>, <quote>%</quote>, <quote>!</quote>, <quote>/</quote>,
+or <quote>|</quote>. If you have local accounts that include these characters, you will
+have to modify this rule.
+</para>
+<para>
+Empty components (two dots in a row) are not valid in RFC 2822, but Exim
+allows them because they have been encountered in practice. (Consider the
+common convention of local parts constructed as
+<quote><emphasis>first-initial.second-initial.family-name</emphasis></quote> when applied to someone like
+the author of Exim, who has no second initial.) However, a local part starting
+with a dot or containing <quote>/../</quote> can cause trouble if it is used as part of a
+filename (for example, for a mailing list). This is also true for local parts
+that contain slashes. A pipe symbol can also be troublesome if the local part
+is incorporated unthinkingly into a shell command line.
+</para>
+<para>
+The second rule above applies to all other domains, and is less strict. This
+allows your own users to send outgoing messages to sites that use slashes
+and vertical bars in their local parts. It blocks local parts that begin
+with a dot, slash, or vertical bar, but allows these characters within the
+local part. However, the sequence <quote>/../</quote> is barred. The use of <quote>@</quote>, <quote>%</quote>,
+and <quote>!</quote> is blocked, as before. The motivation here is to prevent your users
+(or your users&#x2019; viruses) from mounting certain kinds of attack on remote sites.
+</para>
+<literallayout class="monospaced">
+accept  local_parts   = postmaster
+        domains       = +local_domains
+</literallayout>
+<para>
+This statement, which has two conditions, accepts an incoming address if the
+local part is <emphasis>postmaster</emphasis> and the domain is one of those listed in the
+<emphasis>local_domains</emphasis> domain list. The <quote>+</quote> character is used to indicate a
+reference to a named list. In this configuration, there is just one domain in
+<emphasis>local_domains</emphasis>, but in general there may be many.
+</para>
+<para>
+The presence of this statement means that mail to postmaster is never blocked
+by any of the subsequent tests. This can be helpful while sorting out problems
+in cases where the subsequent tests are incorrectly denying access.
+</para>
+<literallayout class="monospaced">
+require verify        = sender
+</literallayout>
+<para>
+This statement requires the sender address to be verified before any subsequent
+ACL statement can be used. If verification fails, the incoming recipient
+address is refused. Verification consists of trying to route the address, to
+see if a bounce message could be delivered to it. In the case of remote
+addresses, basic verification checks only the domain, but <emphasis>callouts</emphasis> can be
+used for more verification if required. Section <xref linkend="SECTaddressverification"/>
+discusses the details of address verification.
+</para>
+<literallayout class="monospaced">
+accept  hosts         = +relay_from_hosts
+        control       = submission
+</literallayout>
+<para>
+This statement accepts the address if the message is coming from one of the
+hosts that are defined as being allowed to relay through this host. Recipient
+verification is omitted here, because in many cases the clients are dumb MUAs
+that do not cope well with SMTP error responses. For the same reason, the
+second line specifies <quote>submission mode</quote> for messages that are accepted. This
+is described in detail in section <xref linkend="SECTsubmodnon"/>; it causes Exim to fix
+messages that are deficient in some way, for example, because they lack a
+<emphasis>Date:</emphasis> header line. If you are actually relaying out from MTAs, you should
+probably add recipient verification here, and disable submission mode.
+</para>
+<literallayout class="monospaced">
+accept  authenticated = *
+        control       = submission
+</literallayout>
+<para>
+This statement accepts the address if the client host has authenticated itself.
+Submission mode is again specified, on the grounds that such messages are most
+likely to come from MUAs. The default configuration does not define any
+authenticators, though it does include some nearly complete commented-out
+examples described in <xref linkend="SECTdefconfauth"/>. This means that no client can in
+fact authenticate until you complete the authenticator definitions.
+</para>
+<literallayout class="monospaced">
+require message = relay not permitted
+        domains = +local_domains : +relay_to_domains
+</literallayout>
+<para>
+This statement rejects the address if its domain is neither a local domain nor
+one of the domains for which this host is a relay.
+</para>
+<literallayout class="monospaced">
+require verify = recipient
+</literallayout>
+<para>
+This statement requires the recipient address to be verified; if verification
+fails, the address is rejected.
+</para>
+<literallayout class="monospaced">
+# deny    dnslists    = black.list.example
+#         message     = rejected because $sender_host_address \
+#                       is in a black list at $dnslist_domain\n\
+#                       $dnslist_text
+#
+# warn    dnslists    = black.list.example
+#         add_header  = X-Warning: $sender_host_address is in \
+#                       a black list at $dnslist_domain
+#         log_message = found in $dnslist_domain
+</literallayout>
+<para>
+These commented-out lines are examples of how you could configure Exim to check
+sending hosts against a DNS black list. The first statement rejects messages
+from blacklisted hosts, whereas the second just inserts a warning header
+line.
+</para>
+<literallayout class="monospaced">
+# require verify = csa
+</literallayout>
+<para>
+This commented-out line is an example of how you could turn on client SMTP
+authorization (CSA) checking. Such checks do DNS lookups for special SRV
+records.
+</para>
+<literallayout class="monospaced">
+accept
+</literallayout>
+<para>
+The final statement in the first ACL unconditionally accepts any recipient
+address that has successfully passed all the previous tests.
+</para>
+<literallayout class="monospaced">
+acl_check_data:
+</literallayout>
+<para>
+This line marks the start of the second ACL, and names it. Most of the contents
+of this ACL are commented out:
+</para>
+<literallayout class="monospaced">
+# deny    malware   = *
+#         message   = This message contains a virus \
+#                     ($malware_name).
+</literallayout>
+<para>
+These lines are examples of how to arrange for messages to be scanned for
+viruses when Exim has been compiled with the content-scanning extension, and a
+suitable virus scanner is installed. If the message is found to contain a
+virus, it is rejected with the given custom error message.
+</para>
+<literallayout class="monospaced">
+# warn    spam      = nobody
+#         message   = X-Spam_score: $spam_score\n\
+#                     X-Spam_score_int: $spam_score_int\n\
+#                     X-Spam_bar: $spam_bar\n\
+#                     X-Spam_report: $spam_report
+</literallayout>
+<para>
+These lines are an example of how to arrange for messages to be scanned by
+SpamAssassin when Exim has been compiled with the content-scanning extension,
+and SpamAssassin has been installed. The SpamAssassin check is run with
+<literal>nobody</literal> as its user parameter, and the results are added to the message as a
+series of extra header line. In this case, the message is not rejected,
+whatever the spam score.
+</para>
+<literallayout class="monospaced">
+accept
+</literallayout>
+<para>
+This final line in the DATA ACL accepts the message unconditionally.
+</para>
+</section>
+<section id="SECID55">
+<title>Router configuration</title>
+<para>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>routers</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>routers</primary>
+<secondary>default</secondary>
+</indexterm>
+The router configuration comes next in the default configuration, introduced
+by the line
+</para>
+<literallayout class="monospaced">
+begin routers
+</literallayout>
+<para>
+Routers are the modules in Exim that make decisions about where to send
+messages. An address is passed to each router, in turn, until it is either
+accepted, or failed. This means that the order in which you define the routers
+matters. Each router is fully described in its own chapter later in this
+manual. Here we give only brief overviews.
+</para>
+<literallayout class="monospaced">
+# domain_literal:
+#   driver = ipliteral
+#   domains = !+local_domains
+#   transport = remote_smtp
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>domain literal</primary>
+<secondary>default router</secondary>
+</indexterm>
+This router is commented out because the majority of sites do not want to
+support domain literal addresses (those of the form <emphasis>user@???</emphasis>). If
+you uncomment this router, you also need to uncomment the setting of
+<option>allow_domain_literals</option> in the main part of the configuration.
+</para>
+<para>
+Which router is used next depends upon whether or not the ROUTER_SMARTHOST
+macro has been defined, per
+</para>
+<literallayout class="monospaced">
+.ifdef ROUTER_SMARTHOST
+smarthost:
+#...
+.else
+dnslookup:
+#...
+.endif
+</literallayout>
+<para>
+If ROUTER_SMARTHOST has been defined, either at the top of the file or on the
+command-line, then we route all non-local mail to that smarthost; otherwise, we&#x2019;ll
+perform DNS lookups for direct-to-MX lookup.  Any mail which is to a local domain will
+skip these routers because of the <option>domains</option> option.
+</para>
+<literallayout class="monospaced">
+smarthost:
+  driver = manualroute
+  domains = ! +local_domains
+  transport = smarthost_smtp
+  route_data = ROUTER_SMARTHOST
+  ignore_target_hosts = &lt;; 0.0.0.0 ; 127.0.0.0/8 ; ::1
+  no_more
+</literallayout>
+<para>
+This router only handles mail which is not to any local domains; this is
+specified by the line
+</para>
+<literallayout class="monospaced">
+domains = ! +local_domains
+</literallayout>
+<para>
+The <option>domains</option> option lists the domains to which this router applies, but the
+exclamation mark is a negation sign, so the router is used only for domains
+that are not in the domain list called <emphasis>local_domains</emphasis> (which was defined at
+the start of the configuration). The plus sign before <emphasis>local_domains</emphasis>
+indicates that it is referring to a named list. Addresses in other domains are
+passed on to the following routers.
+</para>
+<para>
+The name of the router driver is <command>manualroute</command> because we are manually
+specifying how mail should be routed onwards, instead of using DNS MX.
+While the name of this router instance is arbitrary, the <option>driver</option> option must
+be one of the driver modules that is in the Exim binary.
+</para>
+<para>
+With no pre-conditions other than <option>domains</option>, all mail for non-local domains
+will be handled by this router, and the <option>no_more</option> setting will ensure that no
+other routers will be used for messages matching the pre-conditions.  See
+<xref linkend="SECTrouprecon"/> for more on how the pre-conditions apply.  For messages which
+are handled by this router, we provide a hostname to deliver to in <option>route_data</option>
+and the macro supplies the value; the address is then queued for the
+<command>smarthost_smtp</command> transport.
+</para>
+<literallayout class="monospaced">
+dnslookup:
+  driver = dnslookup
+  domains = ! +local_domains
+  transport = remote_smtp
+  ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
+  no_more
+</literallayout>
+<para>
+The <option>domains</option> option behaves as per smarthost, above.
+</para>
+<para>
+The name of the router driver is <command>dnslookup</command>,
+and is specified by the <option>driver</option> option. Do not be confused by the fact that
+the name of this router instance is the same as the name of the driver. The
+instance name is arbitrary, but the name set in the <option>driver</option> option must be
+one of the driver modules that is in the Exim binary.
+</para>
+<para>
+The <command>dnslookup</command> router routes addresses by looking up their domains in the
+DNS in order to obtain a list of hosts to which the address is routed. If the
+router succeeds, the address is queued for the <command>remote_smtp</command> transport, as
+specified by the <option>transport</option> option. If the router does not find the domain
+in the DNS, no further routers are tried because of the <option>no_more</option> setting, so
+the address fails and is bounced.
+</para>
+<para>
+The <option>ignore_target_hosts</option> option specifies a list of IP addresses that are to
+be entirely ignored. This option is present because a number of cases have been
+encountered where MX records in the DNS point to host names
+whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1).
+Completely ignoring these IP addresses causes Exim to fail to route the
+email address, so it bounces. Otherwise, Exim would log a routing problem, and
+continue to try to deliver the message periodically until the address timed
+out.
+</para>
+<literallayout class="monospaced">
+system_aliases:
+  driver = redirect
+  allow_fail
+  allow_defer
+  data = ${lookup{$local_part}lsearch{/etc/aliases}}
+# user = exim
+  file_transport = address_file
+  pipe_transport = address_pipe
+</literallayout>
+<para>
+Control reaches this and subsequent routers only for addresses in the local
+domains. This router checks to see whether the local part is defined as an
+alias in the <filename>/etc/aliases</filename> file, and if so, redirects it according to the
+data that it looks up from that file. If no data is found for the local part,
+the value of the <option>data</option> option is empty, causing the address to be passed to
+the next router.
+</para>
+<para>
+<filename>/etc/aliases</filename> is a conventional name for the system aliases file that is
+often used. That is why it is referenced by from the default configuration
+file. However, you can change this by setting SYSTEM_ALIASES_FILE in
+<filename>Local/Makefile</filename> before building Exim.
+</para>
+<literallayout class="monospaced">
+userforward:
+  driver = redirect
+  check_local_user
+# local_part_suffix = +* : -*
+# local_part_suffix_optional
+  file = $home/.forward
+# allow_filter
+  no_verify
+  no_expn
+  check_ancestor
+  file_transport = address_file
+  pipe_transport = address_pipe
+  reply_transport = address_reply
+</literallayout>
+<para>
+This is the most complicated router in the default configuration. It is another
+redirection router, but this time it is looking for forwarding data set up by
+individual users. The <option>check_local_user</option> setting specifies a check that the
+local part of the address is the login name of a local user. If it is not, the
+router is skipped. The two commented options that follow <option>check_local_user</option>,
+namely:
+</para>
+<literallayout class="monospaced">
+# local_part_suffix = +* : -*
+# local_part_suffix_optional
+</literallayout>
+<para>
+<indexterm role="variable">
+<primary><varname>$local_part_suffix</varname></primary>
+</indexterm>
+show how you can specify the recognition of local part suffixes. If the first
+is uncommented, a suffix beginning with either a plus or a minus sign, followed
+by any sequence of characters, is removed from the local part and placed in the
+variable <varname>$local_part_suffix</varname>. The second suffix option specifies that the
+presence of a suffix in the local part is optional. When a suffix is present,
+the check for a local login uses the local part with the suffix removed.
+</para>
+<para>
+When a local user account is found, the file called <filename>.forward</filename> in the user&#x2019;s
+home directory is consulted. If it does not exist, or is empty, the router
+declines. Otherwise, the contents of <filename>.forward</filename> are interpreted as
+redirection data (see chapter <xref linkend="CHAPredirect"/> for more details).
+</para>
+<para>
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+<secondary>enabling in default router</secondary>
+</indexterm>
+Traditional <filename>.forward</filename> files contain just a list of addresses, pipes, or
+files. Exim supports this by default. However, if <option>allow_filter</option> is set (it
+is commented out by default), the contents of the file are interpreted as a set
+of Exim or Sieve filtering instructions, provided the file begins with <quote>#Exim
+filter</quote> or <quote>#Sieve filter</quote>, respectively. User filtering is discussed in the
+separate document entitled <emphasis>Exim&#x2019;s interfaces to mail filtering</emphasis>.
+</para>
+<para>
+The <option>no_verify</option> and <option>no_expn</option> options mean that this router is skipped when
+verifying addresses, or when running as a consequence of an SMTP EXPN command.
+There are two reasons for doing this:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+Whether or not a local user has a <filename>.forward</filename> file is not really relevant when
+checking an address for validity; it makes sense not to waste resources doing
+unnecessary work.
+</para>
+</listitem>
+<listitem>
+<para>
+More importantly, when Exim is verifying addresses or handling an EXPN
+command during an SMTP session, it is running as the Exim user, not as root.
+The group is the Exim group, and no additional groups are set up.
+It may therefore not be possible for Exim to read users&#x2019; <filename>.forward</filename> files at
+this time.
+</para>
+</listitem>
+</orderedlist>
+<para>
+The setting of <option>check_ancestor</option> prevents the router from generating a new
+address that is the same as any previous address that was redirected. (This
+works round a problem concerning a bad interaction between aliasing and
+forwarding &ndash; see section <xref linkend="SECTredlocmai"/>).
+</para>
+<para>
+The final three option settings specify the transports that are to be used when
+forwarding generates a direct delivery to a file, or to a pipe, or sets up an
+auto-reply, respectively. For example, if a <filename>.forward</filename> file contains
+</para>
+<literallayout class="monospaced">
+a.nother@???, /home/spqr/archive
+</literallayout>
+<para>
+the delivery to <filename>/home/spqr/archive</filename> is done by running the <option>address_file</option>
+transport.
+</para>
+<literallayout class="monospaced">
+localuser:
+  driver = accept
+  check_local_user
+# local_part_suffix = +* : -*
+# local_part_suffix_optional
+  transport = local_delivery
+</literallayout>
+<para>
+The final router sets up delivery into local mailboxes, provided that the local
+part is the name of a local login, by accepting the address and assigning it to
+the <command>local_delivery</command> transport. Otherwise, we have reached the end of the
+routers, so the address is bounced. The commented suffix settings fulfil the
+same purpose as they do for the <command>userforward</command> router.
+</para>
+</section>
+<section id="SECID56">
+<title>Transport configuration</title>
+<para>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>transports</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>transports</primary>
+<secondary>default</secondary>
+</indexterm>
+Transports define mechanisms for actually delivering messages. They operate
+only when referenced from routers, so the order in which they are defined does
+not matter. The transports section of the configuration starts with
+</para>
+<literallayout class="monospaced">
+begin transports
+</literallayout>
+<para>
+Two remote transports and four local transports are defined.
+</para>
+<literallayout class="monospaced">
+remote_smtp:
+  driver = smtp
+  message_size_limit = ${if &gt; {$max_received_linelength}{998} {1}{0}}
+.ifdef _HAVE_PRDR
+  hosts_try_prdr = *
+.endif
+</literallayout>
+<para>
+This transport is used for delivering messages over SMTP connections.
+The list of remote hosts comes from the router.
+The <option>message_size_limit</option> usage is a hack to avoid sending on messages
+with over-long lines.
+</para>
+<para>
+The <option>hosts_try_prdr</option> option enables an efficiency SMTP option.  It is
+negotiated between client and server and not expected to cause problems
+but can be disabled if needed.  The built-in macro _HAVE_PRDR guards the
+use of the <option>hosts_try_prdr</option> configuration option.
+</para>
+<para>
+The other remote transport is used when delivering to a specific smarthost
+with whom there must be some kind of existing relationship, instead of the
+usual federated system.
+</para>
+<literallayout class="monospaced">
+smarthost_smtp:
+  driver = smtp
+  message_size_limit = ${if &gt; {$max_received_linelength}{998} {1}{0}}
+  multi_domain
+  #
+.ifdef _HAVE_TLS
+  # Comment out any of these which you have to, then file a Support
+  # request with your smarthost provider to get things fixed:
+  hosts_require_tls = *
+  tls_verify_hosts = *
+  # As long as tls_verify_hosts is enabled, this this will have no effect,
+  # but if you have to comment it out then this will at least log whether
+  # you succeed or not:
+  tls_try_verify_hosts = *
+  #
+  # The SNI name should match the name which we'll expect to verify;
+  # many mail systems don't use SNI and this doesn't matter, but if it does,
+  # we need to send a name which the remote site will recognize.
+  # This _should_ be the name which the smarthost operators specified as
+  # the hostname for sending your mail to.
+  tls_sni = ROUTER_SMARTHOST
+  #
+.ifdef _HAVE_OPENSSL
+  tls_require_ciphers = HIGH:!aNULL:@STRENGTH
+.endif
+.ifdef _HAVE_GNUTLS
+  tls_require_ciphers = SECURE192:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1
+.endif
+.endif
+.ifdef _HAVE_PRDR
+  hosts_try_prdr = *
+.endif
+</literallayout>
+<para>
+After the same <option>message_size_limit</option> hack, we then specify that this Transport
+can handle messages to multiple domains in one run.  The assumption here is
+that you&#x2019;re routing all non-local mail to the same place and that place is
+happy to take all messages from you as quickly as possible.
+All other options depend upon built-in macros; if Exim was built without TLS support
+then no other options are defined.
+If TLS is available, then we configure "stronger than default" TLS ciphersuites
+and versions using the <option>tls_require_ciphers</option> option, where the value to be
+used depends upon the library providing TLS.
+Beyond that, the options adopt the stance that you should have TLS support available
+from your smarthost on today&#x2019;s Internet, so we turn on requiring TLS for the
+mail to be delivered, and requiring that the certificate be valid, and match
+the expected hostname.  The <option>tls_sni</option> option can be used by service providers
+to select an appropriate certificate to present to you and here we re-use the
+ROUTER_SMARTHOST macro, because that is unaffected by CNAMEs present in DNS.
+You want to specify the hostname which you&#x2019;ll expect to validate for, and that
+should not be subject to insecure tampering via DNS results.
+</para>
+<para>
+For the <option>hosts_try_prdr</option> option see the previous transport.
+</para>
+<para>
+All other options are defaulted.
+</para>
+<literallayout class="monospaced">
+local_delivery:
+  driver = appendfile
+  file = /var/mail/$local_part_data
+  delivery_date_add
+  envelope_to_add
+  return_path_add
+# group = mail
+# mode = 0660
+</literallayout>
+<para>
+This <command>appendfile</command> transport is used for local delivery to user mailboxes in
+traditional BSD mailbox format.
+</para>
+<para>
+We prefer to avoid using <varname>$local_part</varname> directly to define the mailbox filename,
+as it is provided by a potential bad actor.
+Instead we use <varname>$local_part_data</varname>,
+the result of looking up <varname>$local_part</varname> in the user database
+(done by using <option>check_local_user</option> in the the router).
+</para>
+<para>
+By default <command>appendfile</command> runs under the uid and gid of the
+local user, which requires the sticky bit to be set on the <filename>/var/mail</filename>
+directory. Some systems use the alternative approach of running mail deliveries
+under a particular group instead of using the sticky bit. The commented options
+show how this can be done.
+</para>
+<para>
+Exim adds three headers to the message as it delivers it: <emphasis>Delivery-date:</emphasis>,
+<emphasis>Envelope-to:</emphasis> and <emphasis>Return-path:</emphasis>. This action is requested by the three
+similarly-named options above.
+</para>
+<literallayout class="monospaced">
+address_pipe:
+  driver = pipe
+  return_output
+</literallayout>
+<para>
+This transport is used for handling deliveries to pipes that are generated by
+redirection (aliasing or users&#x2019; <filename>.forward</filename> files). The <option>return_output</option>
+option specifies that any output on stdout or stderr generated by the pipe is to
+be returned to the sender.
+</para>
+<literallayout class="monospaced">
+address_file:
+  driver = appendfile
+  delivery_date_add
+  envelope_to_add
+  return_path_add
+</literallayout>
+<para>
+This transport is used for handling deliveries to files that are generated by
+redirection. The name of the file is not specified in this instance of
+<command>appendfile</command>, because it comes from the <command>redirect</command> router.
+</para>
+<literallayout class="monospaced">
+address_reply:
+  driver = autoreply
+</literallayout>
+<para>
+This transport is used for handling automatic replies generated by users&#x2019;
+filter files.
+</para>
+</section>
+<section id="SECID57">
+<title>Default retry rule</title>
+<para>
+<indexterm role="concept">
+<primary>retry</primary>
+<secondary>default rule</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>retry rule</secondary>
+</indexterm>
+The retry section of the configuration file contains rules which affect the way
+Exim retries deliveries that cannot be completed at the first attempt. It is
+introduced by the line
+</para>
+<literallayout class="monospaced">
+begin retry
+</literallayout>
+<para>
+In the default configuration, there is just one rule, which applies to all
+errors:
+</para>
+<literallayout class="monospaced">
+*   *   F,2h,15m; G,16h,1h,1.5; F,4d,6h
+</literallayout>
+<para>
+This causes any temporarily failing address to be retried every 15 minutes for
+2 hours, then at intervals starting at one hour and increasing by a factor of
+1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address
+is not delivered after 4 days of temporary failure, it is bounced. The time is
+measured from first failure, not from the time the message was received.
+</para>
+<para>
+If the retry section is removed from the configuration, or is empty (that is,
+if no retry rules are defined), Exim will not retry deliveries. This turns
+temporary errors into permanent errors.
+</para>
+</section>
+<section id="SECID58">
+<title>Rewriting configuration</title>
+<para>
+The rewriting section of the configuration, introduced by
+</para>
+<literallayout class="monospaced">
+begin rewrite
+</literallayout>
+<para>
+contains rules for rewriting addresses in messages as they arrive. There are no
+rewriting rules in the default configuration file.
+</para>
+</section>
+<section id="SECTdefconfauth">
+<title>Authenticators configuration</title>
+<para>
+<indexterm role="concept">
+<primary>AUTH</primary>
+<secondary>configuration</secondary>
+</indexterm>
+The authenticators section of the configuration, introduced by
+</para>
+<literallayout class="monospaced">
+begin authenticators
+</literallayout>
+<para>
+defines mechanisms for the use of the SMTP AUTH command. The default
+configuration file contains two commented-out example authenticators
+which support plaintext username/password authentication using the
+standard PLAIN mechanism and the traditional but non-standard LOGIN
+mechanism, with Exim acting as the server. PLAIN and LOGIN are enough
+to support most MUA software.
+</para>
+<para>
+The example PLAIN authenticator looks like this:
+</para>
+<literallayout class="monospaced">
+#PLAIN:
+#  driver                  = plaintext
+#  server_set_id           = $auth2
+#  server_prompts          = :
+#  server_condition        = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_in_cipher }
+</literallayout>
+<para>
+And the example LOGIN authenticator looks like this:
+</para>
+<literallayout class="monospaced">
+#LOGIN:
+#  driver                  = plaintext
+#  server_set_id           = $auth1
+#  server_prompts          = &lt;| Username: | Password:
+#  server_condition        = Authentication is not yet configured
+#  server_advertise_condition = ${if def:tls_in_cipher }
+</literallayout>
+<para>
+The <option>server_set_id</option> option makes Exim remember the authenticated username
+in <varname>$authenticated_id</varname>, which can be used later in ACLs or routers. The
+<option>server_prompts</option> option configures the <command>plaintext</command> authenticator so
+that it implements the details of the specific authentication mechanism,
+i.e. PLAIN or LOGIN. The <option>server_advertise_condition</option> setting controls
+when Exim offers authentication to clients; in the examples, this is only
+when TLS or SSL has been started, so to enable the authenticators you also
+need to add support for TLS as described in section <xref linkend="SECTdefconfmain"/>.
+</para>
+<para>
+The <option>server_condition</option> setting defines how to verify that the username and
+password are correct. In the examples it just produces an error message.
+To make the authenticators work, you can use a string expansion
+expression like one of the examples in chapter <xref linkend="CHAPplaintext"/>.
+</para>
+<para>
+Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
+usercode and password are in different positions.
+Chapter <xref linkend="CHAPplaintext"/> covers both.
+</para>
+<para>
+<indexterm role="concept" startref="IIDconfiwal" class="endofrange"/>
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPregexp">
+<title>Regular expressions</title>
+<para>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>library</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>PCRE</primary>
+</indexterm>
+Exim supports the use of regular expressions in many of its options. It
+uses the PCRE regular expression library; this provides regular expression
+matching that is compatible with Perl 5. The syntax and semantics of
+regular expressions is discussed in
+online Perl manpages, in
+many Perl reference books, and also in
+Jeffrey Friedl&#x2019;s <emphasis>Mastering Regular Expressions</emphasis>, which is published by
+O&#x2019;Reilly (see <emphasis role="bold"><ulink url="http://www.oreilly.com/catalog/regex2/">http://www.oreilly.com/catalog/regex2/</ulink></emphasis>).
+</para>
+<para>
+The documentation for the syntax and semantics of the regular expressions that
+are supported by PCRE is included in the PCRE distribution, and no further
+description is included here. The PCRE functions are called from Exim using
+the default option settings (that is, with no PCRE options set), except that
+the PCRE_CASELESS option is set when the matching is required to be
+case-insensitive.
+</para>
+<para>
+In most cases, when a regular expression is required in an Exim configuration,
+it has to start with a circumflex, in order to distinguish it from plain text
+or an <quote>ends with</quote> wildcard. In this example of a configuration setting, the
+second item in the colon-separated list is a regular expression.
+</para>
+<literallayout class="monospaced">
+domains = a.b.c : ^\\d{3} : *.y.z : ...
+</literallayout>
+<para>
+The doubling of the backslash is required because of string expansion that
+precedes interpretation &ndash; see section <xref linkend="SECTlittext"/> for more discussion
+of this issue, and a way of avoiding the need for doubling backslashes. The
+regular expression that is eventually used in this example contains just one
+backslash. The circumflex is included in the regular expression, and has the
+normal effect of <quote>anchoring</quote> it to the start of the string that is being
+matched.
+</para>
+<para>
+There are, however, two cases where a circumflex is not required for the
+recognition of a regular expression: these are the <option>match</option> condition in a
+string expansion, and the <option>matches</option> condition in an Exim filter file. In
+these cases, the relevant string is always treated as a regular expression; if
+it does not start with a circumflex, the expression is not anchored, and can
+match anywhere in the subject string.
+</para>
+<para>
+In all cases, if you want a regular expression to match at the end of a string,
+you must code the $ metacharacter to indicate this. For example:
+</para>
+<literallayout class="monospaced">
+domains = ^\\d{3}\\.example
+</literallayout>
+<para>
+matches the domain <emphasis>123.example</emphasis>, but it also matches <emphasis>123.example.com</emphasis>.
+You need to use:
+</para>
+<literallayout class="monospaced">
+domains = ^\\d{3}\\.example\$
+</literallayout>
+<para>
+if you want <emphasis>example</emphasis> to be the top-level domain. The backslash before the
+$ is needed because string expansion also interprets dollar characters.
+</para>
+</chapter>
+
+<chapter id="CHAPfdlookup">
+<title>File and database lookups</title>
+<para>
+<indexterm role="concept" id="IIDfidalo1" class="startofrange">
+<primary>file</primary>
+<secondary>lookups</secondary>
+</indexterm>
+<indexterm role="concept" id="IIDfidalo2" class="startofrange">
+<primary>database</primary>
+<secondary>lookups</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>description of</secondary>
+</indexterm>
+Exim can be configured to look up data in files or databases as it processes
+messages. Two different kinds of syntax are used:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+A string that is to be expanded may contain explicit lookup requests. These
+cause parts of the string to be replaced by data that is obtained from the
+lookup. Lookups of this type are conditional expansion items. Different results
+can be defined for the cases of lookup success and failure. See chapter
+<xref linkend="CHAPexpand"/>, where string expansions are described in detail.
+The key for the lookup is <emphasis role="bold">specified</emphasis> as part of the string expansion.
+</para>
+</listitem>
+<listitem>
+<para>
+Lists of domains, hosts, and email addresses can contain lookup requests as a
+way of avoiding excessively long linear lists. In this case, the data that is
+returned by the lookup is often (but not always) discarded; whether the lookup
+succeeds or fails is what really counts. These kinds of list are described in
+chapter <xref linkend="CHAPdomhosaddlists"/>.
+The key for the lookup is <emphasis role="bold">implicit</emphasis>,
+given by the context in which the list is expanded.
+</para>
+</listitem>
+</orderedlist>
+<para>
+String expansions, lists, and lookups interact with each other in such a way
+that there is no order in which to describe any one of them that does not
+involve references to the others. Each of these three chapters makes more sense
+if you have read the other two first. If you are reading this for the first
+time, be aware that some of it will make a lot more sense after you have read
+chapters <xref linkend="CHAPdomhosaddlists"/> and <xref linkend="CHAPexpand"/>.
+</para>
+<section id="SECID60">
+<title>Examples of different lookup syntax</title>
+<para>
+It is easy to confuse the two different kinds of lookup, especially as the
+lists that may contain the second kind are always expanded before being
+processed as lists. Therefore, they may also contain lookups of the first kind.
+Be careful to distinguish between the following two examples:
+</para>
+<literallayout class="monospaced">
+domains = ${lookup{$sender_host_address}lsearch{/some/file}}
+domains = lsearch;/some/file
+</literallayout>
+<para>
+The first uses a string expansion, the result of which must be a domain list.
+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
+file that is searched could contain lines like this:
+</para>
+<literallayout class="monospaced">
+192.168.3.4: domain1:domain2:...
+192.168.1.9: domain3:domain4:...
+</literallayout>
+<para>
+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).
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+The result of the expansion is not tainted.
+</para>
+<para>
+In the second example, the lookup is a single item in a domain list. It causes
+Exim to use a lookup to see if the domain that is being processed can be found
+in the file.
+The file could contains lines like this:
+</para>
+<literallayout class="monospaced">
+domain1:
+domain2:
+</literallayout>
+<para>
+Any data that follows the keys is not relevant when checking that the domain
+matches the list item.
+</para>
+<para>
+It is possible, though no doubt confusing, to use both kinds of lookup at once.
+Consider a file containing lines like this:
+</para>
+<literallayout class="monospaced">
+192.168.5.6: lsearch;/another/file
+</literallayout>
+<para>
+If the value of <varname>$sender_host_address</varname> is 192.168.5.6, expansion of the
+first <option>domains</option> setting above generates the second setting, which therefore
+causes a second lookup to occur.
+</para>
+<para revisionflag="changed">
+The lookup type may optionally be followed by a comma
+and a comma-separated list of options.
+Each option is a <quote>name=value</quote> pair.
+Whether an option is meaningful depends on the lookup type.
+</para>
+<para revisionflag="changed">
+All lookups support the option <quote>cache=no_rd</quote>.
+If this is given then the cache that Exim manages for lookup results
+is not checked before doing the lookup.
+The result of the lookup is still written to the cache.
+</para>
+<para>
+The rest of this chapter describes the different lookup types that are
+available. Any of them can be used in any part of the configuration where a
+lookup is permitted.
+</para>
+</section>
+<section id="SECID61">
+<title>Lookup types</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>types of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>single-key lookup</primary>
+<secondary>definition of</secondary>
+</indexterm>
+Two different types of data lookup are implemented:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+The <emphasis>single-key</emphasis> type requires the specification of a file in which to look,
+and a single key to search for. The key must be a non-empty string for the
+lookup to succeed. The lookup type determines how the file is searched.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>single-key lookups</secondary>
+</indexterm>
+The file string may not be tainted
+</para>
+<para>
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+All single-key lookups support the option <quote>ret=key</quote>.
+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.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>query-style lookup</primary>
+<secondary>definition of</secondary>
+</indexterm>
+The <emphasis>query-style</emphasis> type accepts a generalized database query. No particular
+key value is assumed by Exim for query-style lookups. You can use whichever
+Exim variables you need to construct the database query.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The code for each lookup type is in a separate source file that is included in
+the binary of Exim only if the corresponding compile-time option is set. The
+default settings in <filename>src/EDITME</filename> are:
+</para>
+<literallayout class="monospaced">
+LOOKUP_DBM=yes
+LOOKUP_LSEARCH=yes
+</literallayout>
+<para>
+which means that only linear searching and DBM lookups are included by default.
+For some types of lookup (e.g. SQL databases), you need to install appropriate
+libraries and header files before building Exim.
+</para>
+</section>
+<section id="SECTsinglekeylookups">
+<title>Single-key lookup types</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>single-key types</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>single-key lookup</primary>
+<secondary>list of types</secondary>
+</indexterm>
+The following single-key lookup types are implemented:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>cdb</primary>
+<secondary>description of</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>cdb</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>binary zero</primary>
+<secondary>in lookup key</secondary>
+</indexterm>
+<command>cdb</command>: The given file is searched as a Constant DataBase file, using the key
+string without a terminating binary zero. The cdb format is designed for
+indexed files that are read frequently and never updated, except by total
+re-creation. As such, it is particularly suitable for large files containing
+aliases or other indexed data referenced by an MTA. Information about cdb and
+tools for building the files can be found in several places:
+</para>
+<literallayout>
+<emphasis role="bold"><ulink url="https://cr.yp.to/cdb.html">https://cr.yp.to/cdb.html</ulink></emphasis>
+<emphasis role="bold"><ulink url="https://www.corpit.ru/mjt/tinycdb.html">https://www.corpit.ru/mjt/tinycdb.html</ulink></emphasis>
+<emphasis role="bold"><ulink url="https://packages.debian.org/stable/utils/freecdb">https://packages.debian.org/stable/utils/freecdb</ulink></emphasis>
+<emphasis role="bold"><ulink url="https://github.com/philpennock/cdbtools">https://github.com/philpennock/cdbtools</ulink></emphasis> (in Go)
+</literallayout>
+<para>
+A cdb distribution is not needed in order to build Exim with cdb support,
+because the code for reading cdb files is included directly in Exim itself.
+However, no means of building or testing cdb files is provided with Exim, so
+you need to obtain a cdb distribution in order to do this.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>DBM</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dbm</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>binary zero</primary>
+<secondary>in lookup key</secondary>
+</indexterm>
+<command>dbm</command>: Calls to DBM library functions are used to extract data from the given
+DBM file by looking up the record with the given key. A terminating binary
+zero is included in the key that is passed to the DBM library. See section
+<xref linkend="SECTdb"/> for a discussion of DBM libraries.
+</para>
+<para>
+<indexterm role="concept">
+<primary>Berkeley DB library</primary>
+<secondary>file format</secondary>
+</indexterm>
+For all versions of Berkeley DB, Exim uses the DB_HASH style of database
+when building DBM files using the <option>exim_dbmbuild</option> utility. However, when
+using Berkeley DB versions 3 or 4, it opens existing databases for reading with
+the DB_UNKNOWN option. This enables it to handle any of the types of database
+that the library supports, and can be useful for accessing DBM files created by
+other applications. (For earlier DB versions, DB_HASH is always used.)
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dbmjz</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dbm &ndash; embedded NULs</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>sasldb2</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>dbmjz lookup type</primary>
+</indexterm>
+<command>dbmjz</command>: This is the same as <command>dbm</command>, except that the lookup key is
+interpreted as an Exim list; the elements of the list are joined together with
+ASCII NUL characters to form the lookup key.  An example usage would be to
+authenticate incoming SMTP calls using the passwords from Cyrus SASL&#x2019;s
+<filename>/etc/sasldb2</filename> file with the <command>gsasl</command> authenticator or Exim&#x2019;s own
+<command>cram_md5</command> authenticator.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dbmnz</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dbm &ndash; terminating zero</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>binary zero</primary>
+<secondary>in lookup key</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Courier</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>/etc/userdbshadow.dat</filename></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>dbmnz lookup type</primary>
+</indexterm>
+<command>dbmnz</command>: This is the same as <command>dbm</command>, except that a terminating binary zero
+is not included in the key that is passed to the DBM library. You may need this
+if you want to look up data in files that are created by or shared with some
+other application that does not use terminating zeros. For example, you need to
+use <command>dbmnz</command> rather than <command>dbm</command> if you want to authenticate incoming SMTP
+calls using the passwords from Courier&#x2019;s <filename>/etc/userdbshadow.dat</filename> file. Exim&#x2019;s
+utility program for creating DBM files (<emphasis>exim_dbmbuild</emphasis>) includes the zeros
+by default, but has an option to omit them (see section <xref linkend="SECTdbmbuild"/>).
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dsearch</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>dsearch lookup type</primary>
+</indexterm>
+<command>dsearch</command>: The given file must be an
+absolute
+directory path; this is searched for an entry
+whose name is the key by calling the <function>lstat()</function> function.
+The key may not
+contain any forward slash characters.
+If <function>lstat()</function> succeeds then so does the lookup.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>dsearch result</secondary>
+</indexterm>
+The result is regarded as untainted.
+</para>
+<para>
+Options for the lookup can be given by appending them after the word "dsearch",
+separated by a comma.  Options, if present, are a comma-separated list having
+each element starting with a tag name and an equals.
+</para>
+<para>
+Two options are supported, for the return value and for filtering match
+candidates.
+The "ret" option requests an alternate result value of
+the entire path for the entry. Example:
+</para>
+<literallayout class="monospaced">
+${lookup {passwd} dsearch,ret=full {/etc}}
+</literallayout>
+<para>
+The default result is just the requested entry.
+The "filter" option requests that only directory entries of a given type
+are matched. The match value is one of "file", "dir" or "subdir" (the latter
+not matching "." or ".."). Example:
+</para>
+<literallayout class="monospaced">
+${lookup {passwd} dsearch,filter=file {/etc}}
+</literallayout>
+<para>
+The default matching is for any entry type, including directories
+and symlinks.
+</para>
+<para>
+An example of how this
+lookup can be used to support virtual domains is given in section
+<xref linkend="SECTvirtualdomains"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>iplsearch</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>iplsearch lookup type</primary>
+</indexterm>
+<command>iplsearch</command>: The given file is a text file containing keys and data. A key is
+terminated by a colon or white space or the end of the line. The keys in the
+file must be IP addresses, or IP addresses with CIDR masks. Keys that involve
+IPv6 addresses must be enclosed in quotes to prevent the first internal colon
+being interpreted as a key terminator. For example:
+</para>
+<literallayout class="monospaced">
+1.2.3.4:           data for 1.2.3.4
+192.168.0.0/16:    data for 192.168.0.0/16
+"abcd::cdab":      data for abcd::cdab
+"abcd:abcd::/32"   data for abcd:abcd::/32
+</literallayout>
+<para>
+The key for an <command>iplsearch</command> lookup must be an IP address (without a mask). The
+file is searched linearly, using the CIDR masks where present, until a matching
+key is found. The first key that matches is used; there is no attempt to find a
+<quote>best</quote> match. Apart from the way the keys are matched, the processing for
+<command>iplsearch</command> is the same as for <command>lsearch</command>.
+</para>
+<para>
+<emphasis role="bold">Warning 1</emphasis>: Unlike most other single-key lookup types, a file of data for
+<command>iplsearch</command> can <emphasis>not</emphasis> be turned into a DBM or cdb file, because those
+lookup types support only literal keys.
+</para>
+<para>
+<emphasis role="bold">Warning 2</emphasis>: In a host list, you must always use <command>net-iplsearch</command> so that
+the implicit key is the host&#x2019;s IP address rather than its name (see section
+<xref linkend="SECThoslispatsikey"/>).
+</para>
+<para>
+<emphasis role="bold">Warning 3</emphasis>: Do not use an IPv4-mapped IPv6 address for a key; use the
+IPv4, in dotted-quad form. (Exim converts IPv4-mapped IPv6 addresses to this
+notation before executing the lookup.)
+</para>
+<para revisionflag="changed">
+One option is supported, "ret=full", to request the return of the entire line
+rather than omitting the key porttion.
+Note however that the key portion will have been de-quoted.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>json</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>json</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>JSON</primary>
+<secondary>expansions</secondary>
+</indexterm>
+<command>json</command>: The given file is a text file with a JSON structure.
+An element of the structure is extracted, defined by the search key.
+The key is a list of subelement selectors
+(colon-separated by default but changeable in the usual way)
+which are applied in turn to select smaller and smaller portions
+of the JSON structure.
+If a selector is numeric, it must apply to a JSON array; the (zero-based)
+nunbered array element is selected.
+Otherwise it must apply to a JSON object; the named element is selected.
+The final resulting element can be a simple JSON type or a JSON object
+or array; for the latter two a string-representation of the JSON
+is returned.
+For elements of type string, the returned value is de-quoted.
+</para>
+</listitem>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="concept">
+<primary>LMDB</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>lmdb</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>database</primary>
+<secondary>lmdb</secondary>
+</indexterm>
+<command>lmdb</command>: The given file is an LMDB database.
+LMDB is a memory-mapped key-value store,
+with API modeled loosely on that of BerkeleyDB.
+See <emphasis role="bold"><ulink url="https://symas.com/products/lightning-memory-mapped-database/">https://symas.com/products/lightning-memory-mapped-database/</ulink></emphasis>
+for the feature set and operation modes.
+</para>
+<para revisionflag="changed">
+Exim provides read-only access via the LMDB C library.
+The library can be obtained from <emphasis role="bold"><ulink url="https://github.com/LMDB/lmdb">https://github.com/LMDB/lmdb</ulink></emphasis>
+or your operating system package repository.
+To enable LMDB support in Exim set LOOKUP_LMDB=yes in <filename>Local/Makefile</filename>.
+</para>
+<para revisionflag="changed">
+You will need to separately create the LMDB database file,
+possibly using the <quote>mdb_load</quote> utility.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>linear search</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>lsearch</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lsearch lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>case sensitivity</primary>
+<secondary>in lsearch lookup</secondary>
+</indexterm>
+<command>lsearch</command>: The given file is a text file that is searched linearly for a
+line beginning with the search key, terminated by a colon or white space or the
+end of the line. The search is case-insensitive; that is, upper and lower case
+letters are treated as the same. The first occurrence of the key that is found
+in the file is used.
+</para>
+<para>
+White space between the key and the colon is permitted. The remainder of the
+line, with leading and trailing white space removed, is the data. This can be
+continued onto subsequent lines by starting them with any amount of white
+space, but only a single space character is included in the data at such a
+junction. If the data begins with a colon, the key must be terminated by a
+colon, for example:
+</para>
+<literallayout class="monospaced">
+baduser:  :fail:
+</literallayout>
+<para>
+Empty lines and lines beginning with # are ignored, even if they occur in the
+middle of an item. This is the traditional textual format of alias files. Note
+that the keys in an <command>lsearch</command> file are literal strings. There is no
+wildcarding of any kind.
+</para>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>lsearch &ndash; colons in keys</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>white space</primary>
+<secondary>in lsearch key</secondary>
+</indexterm>
+In most <command>lsearch</command> files, keys are not required to contain colons or #
+characters, or white space. However, if you need this feature, it is available.
+If a key begins with a doublequote character, it is terminated only by a
+matching quote (or end of line), and the normal escaping rules apply to its
+contents (see section <xref linkend="SECTstrings"/>). An optional colon is permitted after
+quoted keys (exactly as for unquoted keys). There is no special handling of
+quotes for the data part of an <command>lsearch</command> line.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>NIS lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>NIS</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>binary zero</primary>
+<secondary>in lookup key</secondary>
+</indexterm>
+<command>nis</command>: The given file is the name of a NIS map, and a NIS lookup is done with
+the given key, without a terminating binary zero. There is a variant called
+<command>nis0</command> which does include the terminating binary zero in the key. This is
+reportedly needed for Sun-style alias files. Exim does not recognize NIS
+aliases; the full map names must be used.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>wildlsearch lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>wildlsearch</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>nwildlsearch lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>nwildlsearch</secondary>
+</indexterm>
+<command>wildlsearch</command> or <command>nwildlsearch</command>: These search a file linearly, like
+<command>lsearch</command>, but instead of being interpreted as a literal string, each key in
+the file may be wildcarded. The difference between these two lookup types is
+that for <command>wildlsearch</command>, each key in the file is string-expanded before being
+used, whereas for <command>nwildlsearch</command>, no expansion takes place.
+</para>
+<para>
+<indexterm role="concept">
+<primary>case sensitivity</primary>
+<secondary>in (n)wildlsearch lookup</secondary>
+</indexterm>
+Like <command>lsearch</command>, the testing is done case-insensitively. However, keys in the
+file that are regular expressions can be made case-sensitive by the use of
+<literal>(-i)</literal> within the pattern. The following forms of wildcard are recognized:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+The string may begin with an asterisk to mean <quote>ends with</quote>. For example:
+</para>
+<literallayout class="monospaced">
+    *.a.b.c       data for anything.a.b.c
+    *fish         data for anythingfish
+</literallayout>
+</listitem>
+<listitem>
+<para>
+The string may begin with a circumflex to indicate a regular expression. For
+example, for <command>wildlsearch</command>:
+</para>
+<literallayout class="monospaced">
+    ^\N\d+\.a\.b\N    data for &lt;digits&gt;.a.b
+</literallayout>
+<para>
+Note the use of <literal>\N</literal> to disable expansion of the contents of the regular
+expression. If you are using <command>nwildlsearch</command>, where the keys are not
+string-expanded, the equivalent entry is:
+</para>
+<literallayout class="monospaced">
+    ^\d+\.a\.b        data for &lt;digits&gt;.a.b
+</literallayout>
+<para>
+The case-insensitive flag is set at the start of compiling the regular
+expression, but it can be turned off by using <literal>(-i)</literal> at an appropriate point.
+For example, to make the entire pattern case-sensitive:
+</para>
+<literallayout class="monospaced">
+    ^(?-i)\d+\.a\.b        data for &lt;digits&gt;.a.b
+</literallayout>
+<para>
+If the regular expression contains white space or colon characters, you must
+either quote it (see <command>lsearch</command> above), or represent these characters in other
+ways. For example, <literal>\s</literal> can be used for white space and <literal>\x3A</literal> for a
+colon. This may be easier than quoting, because if you quote, you have to
+escape all the backslashes inside the quotes.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: It is not possible to capture substrings in a regular expression
+match for later use, because the results of all lookups are cached. If a lookup
+is repeated, the result is taken from the cache, and no actual pattern matching
+takes place. The values of all the numeric variables are unset after a
+<command>(n)wildlsearch</command> match.
+</para>
+</listitem>
+<listitem>
+<para>
+Although I cannot see it being of much use, the general matching function that
+is used to implement <command>(n)wildlsearch</command> means that the string may begin with a
+lookup name terminated by a semicolon, and followed by lookup data. For
+example:
+</para>
+<literallayout class="monospaced">
+    cdb;/some/file  data for keys that match the file
+</literallayout>
+<para>
+The data that is obtained from the nested lookup is discarded.
+</para>
+</listitem>
+</orderedlist>
+<para>
+Keys that do not match any of these patterns are interpreted literally. The
+continuation rules for the data are the same as for <command>lsearch</command>, and keys may
+be followed by optional colons.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: Unlike most other single-key lookup types, a file of data for
+<command>(n)wildlsearch</command> can <emphasis>not</emphasis> be turned into a DBM or cdb file, because those
+lookup types support only literal keys.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>spf lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>spf</secondary>
+</indexterm>
+<command>spf</command>: If Exim is built with SPF support, manual lookups can be done
+(as opposed to the standard ACL condition method).
+For details see section <xref linkend="SECSPF"/>.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECTquerystylelookups">
+<title>Query-style lookup types</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>query-style types</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>query-style lookup</primary>
+<secondary>list of types</secondary>
+</indexterm>
+The supported query-style lookup types are listed below. Further details about
+many of them are given in later sections.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>DNS</primary>
+<secondary>as a lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>DNS</secondary>
+</indexterm>
+<command>dnsdb</command>: This does a DNS search for one or more records whose domain names
+are given in the supplied query. The resulting data is the contents of the
+records. See section <xref linkend="SECTdnsdb"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>InterBase lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>InterBase</secondary>
+</indexterm>
+<command>ibase</command>: This does a lookup in an InterBase database.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>LDAP</secondary>
+</indexterm>
+<command>ldap</command>: This does an LDAP lookup using a query in the form of a URL, and
+returns attributes from a single entry. There is a variant called <command>ldapm</command>
+that permits values from multiple entries to be returned. A third variant
+called <command>ldapdn</command> returns the Distinguished Name of a single entry instead of
+any attribute values. See section <xref linkend="SECTldap"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>MySQL</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>MySQL</secondary>
+</indexterm>
+<command>mysql</command>: The format of the query is an SQL statement that is passed to a
+MySQL database. See section <xref linkend="SECTsql"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>NIS+ lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>NIS+</secondary>
+</indexterm>
+<command>nisplus</command>: This does a NIS+ lookup using a query that can specify the name of
+the field to be returned. See section <xref linkend="SECTnisplus"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Oracle</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Oracle</secondary>
+</indexterm>
+<command>oracle</command>: The format of the query is an SQL statement that is passed to an
+Oracle database. See section <xref linkend="SECTsql"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>passwd</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>passwd lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><filename>/etc/passwd</filename></primary>
+</indexterm>
+<command>passwd</command> is a query-style lookup with queries that are just user names. The
+lookup calls <function>getpwnam()</function> to interrogate the system password data, and on
+success, the result string is the same as you would get from an <command>lsearch</command>
+lookup on a traditional <filename>/etc/passwd file</filename>, though with <literal>*</literal> for the
+password value. For example:
+</para>
+<literallayout class="monospaced">
+*:42:42:King Rat:/home/kr:/bin/bash
+</literallayout>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>PostgreSQL lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>PostgreSQL</secondary>
+</indexterm>
+<command>pgsql</command>: The format of the query is an SQL statement that is passed to a
+PostgreSQL database. See section <xref linkend="SECTsql"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Redis lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Redis</secondary>
+</indexterm>
+<command>redis</command>: The format of the query is either a simple get or simple set,
+passed to a Redis database. See section <xref linkend="SECTsql"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>sqlite lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>sqlite</secondary>
+</indexterm>
+<command>sqlite</command>: The format of the query is
+an SQL statement that is passed to an SQLite database. See section <xref linkend="SECTsqlite"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<command>testdb</command>: This is a lookup type that is used for testing Exim. It is
+not likely to be useful in normal operation.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>whoson lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>whoson</secondary>
+</indexterm>
+<command>whoson</command>: <emphasis>Whoson</emphasis> (<emphasis role="bold"><ulink url="http://whoson.sourceforge.net">http://whoson.sourceforge.net</ulink></emphasis>) is a protocol that
+allows a server to check whether a particular (dynamically allocated) IP
+address is currently allocated to a known (trusted) user and, optionally, to
+obtain the identity of the said user. For SMTP servers, <emphasis>Whoson</emphasis> was popular
+at one time for <quote>POP before SMTP</quote> authentication, but that approach has been
+superseded by SMTP authentication. In Exim, <emphasis>Whoson</emphasis> can be used to implement
+<quote>POP before SMTP</quote> checking using ACL statements such as
+</para>
+<literallayout class="monospaced">
+require condition = \
+  ${lookup whoson {$sender_host_address}{yes}{no}}
+</literallayout>
+<para>
+The query consists of a single IP address. The value returned is the name of
+the authenticated user, which is stored in the variable <varname>$value</varname>. However, in
+this example, the data in <varname>$value</varname> is not used; the result of the lookup is
+one of the fixed strings <quote>yes</quote> or <quote>no</quote>.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECID63">
+<title>Temporary errors in lookups</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>temporary error in</secondary>
+</indexterm>
+Lookup functions can return temporary error codes if the lookup cannot be
+completed. For example, an SQL or LDAP database might be unavailable. For this
+reason, it is not advisable to use a lookup that might do this for critical
+options such as a list of local domains.
+</para>
+<para>
+When a lookup cannot be completed in a router or transport, delivery
+of the message (to the relevant address) is deferred, as for any other
+temporary error. In other circumstances Exim may assume the lookup has failed,
+or may give up altogether.
+</para>
+</section>
+<section id="SECTdefaultvaluelookups">
+<title>Default values in single-key lookups</title>
+<para>
+<indexterm role="concept">
+<primary>wildcard lookups</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>default values</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>wildcard</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>* added to type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>default</primary>
+<secondary>in single-key lookups</secondary>
+</indexterm>
+In this context, a <quote>default value</quote> is a value specified by the administrator
+that is to be used if a lookup fails.
+</para>
+<para>
+<emphasis role="bold">Note:</emphasis> This section applies only to single-key lookups. For query-style
+lookups, the facilities of the query language must be used. An attempt to
+specify a default for a query-style lookup provokes an error.
+</para>
+<para>
+If <quote>*</quote> is added to a single-key lookup type (for example, <option>lsearch*</option>)
+and the initial lookup fails, the key <quote>*</quote> is looked up in the file to
+provide a default value. See also the section on partial matching below.
+</para>
+<para>
+<indexterm role="concept">
+<primary>*@ with single-key lookup</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>*@ added to type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>alias file</primary>
+<secondary>per-domain default</secondary>
+</indexterm>
+Alternatively, if <quote>*@</quote> is added to a single-key lookup type (for example
+<option>dbm*@</option>) then, if the initial lookup fails and the key contains an @
+character, a second lookup is done with everything before the last @ replaced
+by *. This makes it possible to provide per-domain defaults in alias files
+that include the domains in the keys. If the second lookup fails (or doesn&#x2019;t
+take place because there is no @ in the key), <quote>*</quote> is looked up.
+For example, a <command>redirect</command> router might contain:
+</para>
+<literallayout class="monospaced">
+data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}}
+</literallayout>
+<para>
+Suppose the address that is being processed is <emphasis>jane@???</emphasis>. Exim
+looks up these keys, in this order:
+</para>
+<literallayout class="monospaced">
+jane@???
+*@eyre.example
+*
+</literallayout>
+<para>
+The data is taken from whichever key it finds first. <emphasis role="bold">Note</emphasis>: In an
+<command>lsearch</command> file, this does not mean the first of these keys in the file. A
+complete scan is done for each key, and only if it is not found at all does
+Exim move on to try the next key.
+</para>
+</section>
+<section id="SECTpartiallookup">
+<title>Partial matching in single-key lookups</title>
+<para>
+<indexterm role="concept">
+<primary>partial matching</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>wildcard lookups</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>partial matching</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>wildcard</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in search type</secondary>
+</indexterm>
+The normal operation of a single-key lookup is to search the file for an exact
+match with the given key. However, in a number of situations where domains are
+being looked up, it is useful to be able to do partial matching. In this case,
+information in the file that has a key starting with <quote>*.</quote> is matched by any
+domain that ends with the components that follow the full stop. For example, if
+a key in a DBM file is
+</para>
+<literallayout class="monospaced">
+*.dates.fict.example
+</literallayout>
+<para>
+then when partial matching is enabled this is matched by (amongst others)
+<emphasis>2001.dates.fict.example</emphasis> and <emphasis>1984.dates.fict.example</emphasis>. It is also matched
+by <emphasis>dates.fict.example</emphasis>, if that does not appear as a separate key in the
+file.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: Partial matching is not available for query-style lookups. It is
+also not available for any lookup items in address lists (see section
+<xref linkend="SECTaddresslist"/>).
+</para>
+<para>
+Partial matching is implemented by doing a series of separate lookups using
+keys constructed by modifying the original subject key. This means that it can
+be used with any of the single-key lookup types, provided that
+partial matching keys
+beginning with a special prefix (default <quote>*.</quote>) are included in the data file.
+Keys in the file that do not begin with the prefix are matched only by
+unmodified subject keys when partial matching is in use.
+</para>
+<para>
+Partial matching is requested by adding the string <quote>partial-</quote> to the front of
+the name of a single-key lookup type, for example, <option>partial-dbm</option>. When this
+is done, the subject key is first looked up unmodified; if that fails, <quote>*.</quote>
+is added at the start of the subject key, and it is looked up again. If that
+fails, further lookups are tried with dot-separated components removed from the
+start of the subject key, one-by-one, and <quote>*.</quote> added on the front of what
+remains.
+</para>
+<para>
+A minimum number of two non-* components are required. This can be adjusted
+by including a number before the hyphen in the search type. For example,
+<option>partial3-lsearch</option> specifies a minimum of three non-* components in the
+modified keys. Omitting the number is equivalent to <quote>partial2-</quote>. If the
+subject key is <emphasis>2250.dates.fict.example</emphasis> then the following keys are looked
+up when the minimum number of non-* components is two:
+</para>
+<literallayout class="monospaced">
+2250.dates.fict.example
+*.2250.dates.fict.example
+*.dates.fict.example
+*.fict.example
+</literallayout>
+<para>
+As soon as one key in the sequence is successfully looked up, the lookup
+finishes.
+</para>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>partial matching &ndash; changing prefix</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>prefix</primary>
+<secondary>for partial matching</secondary>
+</indexterm>
+The use of <quote>*.</quote> as the partial matching prefix is a default that can be
+changed. The motivation for this feature is to allow Exim to operate with file
+formats that are used by other MTAs. A different prefix can be supplied in
+parentheses instead of the hyphen after <quote>partial</quote>. For example:
+</para>
+<literallayout class="monospaced">
+domains = partial(.)lsearch;/some/file
+</literallayout>
+<para>
+In this example, if the domain is <emphasis>a.b.c</emphasis>, the sequence of lookups is
+<literal>a.b.c</literal>, <literal>.a.b.c</literal>, and <literal>.b.c</literal> (the default minimum of 2 non-wild
+components is unchanged). The prefix may consist of any punctuation characters
+other than a closing parenthesis. It may be empty, for example:
+</para>
+<literallayout class="monospaced">
+domains = partial1()cdb;/some/file
+</literallayout>
+<para>
+For this example, if the domain is <emphasis>a.b.c</emphasis>, the sequence of lookups is
+<literal>a.b.c</literal>, <literal>b.c</literal>, and <literal>c</literal>.
+</para>
+<para>
+If <quote>partial0</quote> is specified, what happens at the end (when the lookup with
+just one non-wild component has failed, and the original key is shortened right
+down to the null string) depends on the prefix:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the prefix has zero length, the whole lookup fails.
+</para>
+</listitem>
+<listitem>
+<para>
+If the prefix has length 1, a lookup for just the prefix is done. For
+example, the final lookup for <quote>partial0(.)</quote> is for <literal>.</literal> alone.
+</para>
+</listitem>
+<listitem>
+<para>
+Otherwise, if the prefix ends in a dot, the dot is removed, and the
+remainder is looked up. With the default prefix, therefore, the final lookup is
+for <quote>*</quote> on its own.
+</para>
+</listitem>
+<listitem>
+<para>
+Otherwise, the whole prefix is looked up.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+If the search type ends in <quote>*</quote> or <quote>*@</quote> (see section
+<xref linkend="SECTdefaultvaluelookups"/> above), the search for an ultimate default that
+this implies happens after all partial lookups have failed. If <quote>partial0</quote> is
+specified, adding <quote>*</quote> to the search type has no effect with the default
+prefix, because the <quote>*</quote> key is already included in the sequence of partial
+lookups. However, there might be a use for lookup types such as
+<quote>partial0(.)lsearch*</quote>.
+</para>
+<para>
+The use of <quote>*</quote> in lookup partial matching differs from its use as a wildcard
+in domain lists and the like. Partial matching works only in terms of
+dot-separated components; a key such as <literal>*fict.example</literal>
+in a database file is useless, because the asterisk in a partial matching
+subject key is always followed by a dot.
+</para>
+</section>
+<section id="SECID64">
+<title>Lookup caching</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>caching</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>caching</primary>
+<secondary>lookup data</secondary>
+</indexterm>
+Exim caches all lookup results in order to avoid needless repetition of
+lookups. However, because (apart from the daemon) Exim operates as a collection
+of independent, short-lived processes, this caching applies only within a
+single Exim process. There is no inter-process lookup caching facility.
+</para>
+<para revisionflag="changed">
+If an option <quote>cache=no_rd</quote> is used on the lookup then
+the cache is only written to, cached data is not used for the operation
+and a real lookup is done.
+</para>
+<para>
+For single-key lookups, Exim keeps the relevant files open in case there is
+another lookup that needs them. In some types of configuration this can lead to
+many files being kept open for messages with many recipients. To avoid hitting
+the operating system limit on the number of simultaneously open files, Exim
+closes the least recently used file when it needs to open more files than its
+own internal limit, which can be changed via the <option>lookup_open_max</option> option.
+</para>
+<para>
+The single-key lookup files are closed and the lookup caches are flushed at
+strategic points during delivery &ndash; for example, after all routing is
+complete.
+</para>
+</section>
+<section id="SECID65">
+<title>Quoting lookup data</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>quoting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>in lookups</secondary>
+</indexterm>
+When data from an incoming message is included in a query-style lookup, there
+is the possibility of special characters in the data messing up the syntax of
+the query. For example, a NIS+ query that contains
+</para>
+<literallayout class="monospaced">
+[name=$local_part]
+</literallayout>
+<para>
+will be broken if the local part happens to contain a closing square bracket.
+For NIS+, data can be enclosed in double quotes like this:
+</para>
+<literallayout class="monospaced">
+[name="$local_part"]
+</literallayout>
+<para>
+but this still leaves the problem of a double quote in the data. The rule for
+NIS+ is that double quotes must be doubled. Other lookup types have different
+rules, and to cope with the differing requirements, an expansion operator
+of the following form is provided:
+</para>
+<literallayout class="monospaced">
+${quote_&lt;lookup-type&gt;:&lt;string&gt;}
+</literallayout>
+<para>
+For example, the safest way to write the NIS+ query is
+</para>
+<literallayout class="monospaced">
+[name="${quote_nisplus:$local_part}"]
+</literallayout>
+<para>
+See chapter <xref linkend="CHAPexpand"/> for full coverage of string expansions. The quote
+operator can be used for all lookup types, but has no effect for single-key
+lookups, since no quoting is ever needed in their key strings.
+</para>
+</section>
+<section id="SECTdnsdb">
+<title>More about dnsdb</title>
+<para>
+<indexterm role="concept">
+<primary>dnsdb lookup</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>dnsdb</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>DNS</primary>
+<secondary>as a lookup type</secondary>
+</indexterm>
+The <command>dnsdb</command> lookup type uses the DNS as its database. A simple query consists
+of a record type and a domain name, separated by an equals sign. For example,
+an expansion string could contain:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{mx=a.b.example}{$value}fail}
+</literallayout>
+<para>
+If the lookup succeeds, the result is placed in <varname>$value</varname>, which in this case
+is used on its own as the result. If the lookup does not succeed, the
+<literal>fail</literal> keyword causes a <emphasis>forced expansion failure</emphasis> &ndash; see section
+<xref linkend="SECTforexpfai"/> for an explanation of what this means.
+</para>
+<para>
+The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA
+and TXT, and, when Exim is compiled with IPv6 support, AAAA.
+If no type is given, TXT is assumed.
+</para>
+<para>
+For any record type, if multiple records are found, the data is returned as a
+concatenation, with newline as the default separator. The order, of course,
+depends on the DNS resolver. You can specify a different separator character
+between multiple records by putting a right angle-bracket followed immediately
+by the new separator at the start of the query. For example:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{&gt;: a=host1.example}}
+</literallayout>
+<para>
+It is permitted to specify a space as the separator character. Further
+white space is ignored.
+For lookup types that return multiple fields per record,
+an alternate field separator can be specified using a comma after the main
+separator character, followed immediately by the field separator.
+</para>
+<para>
+<indexterm role="concept">
+<primary>PTR record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+When the type is PTR,
+the data can be an IP address, written as normal; inversion and the addition of
+<option>in-addr.arpa</option> or <option>ip6.arpa</option> happens automatically. For example:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
+</literallayout>
+<para>
+If the data for a PTR record is not a syntactically valid IP address, it is not
+altered and nothing is added.
+</para>
+<para>
+<indexterm role="concept">
+<primary>MX record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SRV record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+For an MX lookup, both the preference value and the host name are returned for
+each record, separated by a space. For an SRV lookup, the priority, weight,
+port, and host name are returned for each record, separated by spaces.
+The field separator can be modified as above.
+</para>
+<para>
+<indexterm role="concept">
+<primary>TXT record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>SPF record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+For TXT records with multiple items of data, only the first item is returned,
+unless a field separator is specified.
+To concatenate items without a separator, use a semicolon instead.
+For SPF records the
+default behaviour is to concatenate multiple items without using a separator.
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{&gt;\n,: txt=a.b.example}}
+${lookup dnsdb{&gt;\n; txt=a.b.example}}
+${lookup dnsdb{spf=example.org}}
+</literallayout>
+<para>
+It is permitted to specify a space as the separator character. Further
+white space is ignored.
+</para>
+<para>
+<indexterm role="concept">
+<primary>SOA record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+For an SOA lookup, while no result is obtained the lookup is redone with
+successively more leading components dropped from the given domain.
+Only the primary-nameserver field is returned unless a field separator is
+specified.
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{&gt;:,; soa=a.b.example.com}}
+</literallayout>
+</section>
+<section id="SECTdnsdb_mod">
+<title>Dnsdb lookup modifiers</title>
+<para>
+<indexterm role="concept">
+<primary>dnsdb modifiers</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>modifiers</primary>
+<secondary>dnsdb</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>options</primary>
+<secondary>dnsdb</secondary>
+</indexterm>
+Modifiers for <command>dnsdb</command> lookups are given by optional keywords,
+each followed by a comma,
+that may appear before the record type.
+</para>
+<para>
+The <command>dnsdb</command> lookup fails only if all the DNS lookups fail. If there is a
+temporary DNS error for any of them, the behaviour is controlled by
+a defer-option modifier.
+The possible keywords are
+<quote>defer_strict</quote>, <quote>defer_never</quote>, and <quote>defer_lax</quote>.
+With <quote>strict</quote> behaviour, any temporary DNS error causes the
+whole lookup to defer. With <quote>never</quote> behaviour, a temporary DNS error is
+ignored, and the behaviour is as if the DNS lookup failed to find anything.
+With <quote>lax</quote> behaviour, all the queries are attempted, but a temporary DNS
+error causes the whole lookup to defer only if none of the other lookups
+succeed. The default is <quote>lax</quote>, so the following lookups are equivalent:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
+${lookup dnsdb{a=one.host.com:two.host.com}}
+</literallayout>
+<para>
+Thus, in the default case, as long as at least one of the DNS lookups
+yields some data, the lookup succeeds.
+</para>
+<para>
+<indexterm role="concept">
+<primary>DNSSEC</primary>
+<secondary>dns lookup</secondary>
+</indexterm>
+Use of <command>DNSSEC</command> is controlled by a dnssec modifier.
+The possible keywords are
+<quote>dnssec_strict</quote>, <quote>dnssec_lax</quote>, and <quote>dnssec_never</quote>.
+With <quote>strict</quote> or <quote>lax</quote> DNSSEC information is requested
+with the lookup.
+With <quote>strict</quote> a response from the DNS resolver that
+is not labelled as authenticated data
+is treated as equivalent to a temporary DNS error.
+The default is <quote>lax</quote>.
+</para>
+<para>
+See also the <varname>$lookup_dnssec_authenticated</varname> variable.
+</para>
+<para>
+<indexterm role="concept">
+<primary>timeout</primary>
+<secondary>dns lookup</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>DNS</primary>
+<secondary>timeout</secondary>
+</indexterm>
+Timeout for the dnsdb lookup can be controlled by a retrans modifier.
+The form is <quote>retrans_VAL</quote> where VAL is an Exim time specification
+(e.g. <quote>5s</quote>).
+The default value is set by the main configuration option <option>dns_retrans</option>.
+</para>
+<para>
+Retries for the dnsdb lookup can be controlled by a retry modifier.
+The form if <quote>retry_VAL</quote> where VAL is an integer.
+The default count is set by the main configuration option <option>dns_retry</option>.
+</para>
+<para>
+<indexterm role="concept">
+<primary>caching</primary>
+<secondary>of dns lookup</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>TTL</primary>
+<secondary>of dns lookup</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>DNS</primary>
+<secondary>TTL</secondary>
+</indexterm>
+Dnsdb lookup results are cached within a single process (and its children).
+The cache entry lifetime is limited to the smallest time-to-live (TTL)
+value of the set of returned DNS records.
+</para>
+</section>
+<section id="SECID66">
+<title>Pseudo dnsdb record types</title>
+<para>
+<indexterm role="concept">
+<primary>MX record</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+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
+the pseudo-type MXH:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{mxh=a.b.example}}
+</literallayout>
+<para>
+In this case, the preference values are omitted, and just the host names are
+returned.
+</para>
+<para>
+<indexterm role="concept">
+<primary>name server for enclosing domain</primary>
+</indexterm>
+Another pseudo-type is ZNS (for <quote>zone NS</quote>). It performs a lookup for NS
+records on the given domain, but if none are found, it removes the first
+component of the domain name, and tries again. This process continues until NS
+records are found or there are no more components left (or there is a DNS
+error). In other words, it may return the name servers for a top-level domain,
+but it never returns the root name servers. If there are no NS records for the
+top-level domain, the lookup fails. Consider these examples:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{zns=xxx.quercite.com}}
+${lookup dnsdb{zns=xxx.edu}}
+</literallayout>
+<para>
+Assuming that in each case there are no NS records for the full domain name,
+the first returns the name servers for <option>quercite.com</option>, and the second returns
+the name servers for <option>edu</option>.
+</para>
+<para>
+You should be careful about how you use this lookup because, unless the
+top-level domain does not exist, the lookup always returns some host names. The
+sort of use to which this might be put is for seeing if the name servers for a
+given domain are on a blacklist. You can probably assume that the name servers
+for the high-level domains such as <option>com</option> or <option>co.uk</option> are not going to be on
+such a list.
+</para>
+<para>
+<indexterm role="concept">
+<primary>CSA</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV
+records according to the CSA rules, which are described in section
+<xref linkend="SECTverifyCSA"/>. Although <command>dnsdb</command> supports SRV lookups directly, this is
+not sufficient because of the extra parent domain search behaviour of CSA. The
+result of a successful lookup such as:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb {csa=$sender_helo_name}}
+</literallayout>
+<para>
+has two space-separated fields: an authorization code and a target host name.
+The authorization code can be <quote>Y</quote> for yes, <quote>N</quote> for no, <quote>X</quote> for explicit
+authorization required but absent, or <quote>?</quote> for unknown.
+</para>
+<para>
+<indexterm role="concept">
+<primary>A+</primary>
+<secondary>in <command>dnsdb</command> lookup</secondary>
+</indexterm>
+The pseudo-type A+ performs an AAAA
+and then an A lookup.  All results are returned; defer processing
+(see below) is handled separately for each lookup.  Example:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb {&gt;; a+=$sender_helo_name}}
+</literallayout>
+</section>
+<section id="SECID67">
+<title>Multiple dnsdb lookups</title>
+<para>
+In the previous sections, <command>dnsdb</command> lookups for a single domain are described.
+However, you can specify a list of domains or IP addresses in a single
+<command>dnsdb</command> lookup. The list is specified in the normal Exim way, with colon as
+the default separator, but with the ability to change this. For example:
+</para>
+<literallayout class="monospaced">
+${lookup dnsdb{one.domain.com:two.domain.com}}
+${lookup dnsdb{a=one.host.com:two.host.com}}
+${lookup dnsdb{ptr = &lt;; 1.2.3.4 ; 4.5.6.8}}
+</literallayout>
+<para>
+In order to retain backwards compatibility, there is one special case: if
+the lookup type is PTR and no change of separator is specified, Exim looks
+to see if the rest of the string is precisely one IPv6 address. In this
+case, it does not treat it as a list.
+</para>
+<para>
+The data from each lookup is concatenated, with newline separators by default,
+in the same way that multiple DNS records for a single item are handled. A
+different separator can be specified, as described above.
+</para>
+</section>
+<section id="SECTldap">
+<title>More about LDAP</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>lookup, more about</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>LDAP</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Solaris</primary>
+<secondary>LDAP</secondary>
+</indexterm>
+The original LDAP implementation came from the University of Michigan; this has
+become <quote>Open LDAP</quote>, and there are now two different releases. Another
+implementation comes from Netscape, and Solaris 7 and subsequent releases
+contain inbuilt LDAP support. Unfortunately, though these are all compatible at
+the lookup function level, their error handling is different. For this reason
+it is necessary to set a compile-time variable when building Exim with LDAP, to
+indicate which LDAP library is in use. One of the following should appear in
+your <filename>Local/Makefile</filename>:
+</para>
+<literallayout class="monospaced">
+LDAP_LIB_TYPE=UMICHIGAN
+LDAP_LIB_TYPE=OPENLDAP1
+LDAP_LIB_TYPE=OPENLDAP2
+LDAP_LIB_TYPE=NETSCAPE
+LDAP_LIB_TYPE=SOLARIS
+</literallayout>
+<para>
+If LDAP_LIB_TYPE is not set, Exim assumes <literal>OPENLDAP1</literal>, which has the
+same interface as the University of Michigan version.
+</para>
+<para>
+There are three LDAP lookup types in Exim. These behave slightly differently in
+the way they handle the results of a query:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<command>ldap</command> requires the result to contain just one entry; if there are more, it
+gives an error.
+</para>
+</listitem>
+<listitem>
+<para>
+<command>ldapdn</command> also requires the result to contain just one entry, but it is the
+Distinguished Name that is returned rather than any attribute values.
+</para>
+</listitem>
+<listitem>
+<para>
+<command>ldapm</command> permits the result to contain more than one entry; the attributes
+from all of them are returned.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+For <command>ldap</command> and <command>ldapm</command>, if a query finds only entries with no attributes,
+Exim behaves as if the entry did not exist, and the lookup fails. The format of
+the data returned by a successful lookup is described in the next section.
+First we explain how LDAP queries are coded.
+</para>
+</section>
+<section id="SECTforldaque">
+<title>Format of LDAP queries</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>query format</secondary>
+</indexterm>
+An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
+the configuration of a <command>redirect</command> router one might have this setting:
+</para>
+<literallayout class="monospaced">
+data = ${lookup ldap \
+  {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
+  c=UK?mailbox?base?}}
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>with TLS</secondary>
+</indexterm>
+The URL may begin with <literal>ldap</literal> or <literal>ldaps</literal> if your LDAP library supports
+secure (encrypted) LDAP connections. The second of these ensures that an
+encrypted TLS connection is used.
+</para>
+<para>
+With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular
+LDAP connections, rather than the SSL-on-connect <literal>ldaps</literal>.
+See the <option>ldap_start_tls</option> option.
+</para>
+<para>
+Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly
+controlled. Every part of the TLS configuration can be configured by settings in
+<filename>exim.conf</filename>. Depending on the version of the client libraries installed on
+your system, some of the initialization may have required setting options in
+<filename>/etc/ldap.conf</filename> or <filename>~/.ldaprc</filename> to get TLS working with self-signed
+certificates. This revealed a nuance where the current UID that exim was
+running as could affect which config files it read. With Exim 4.83, these
+methods become optional, only taking effect if not specifically set in
+<filename>exim.conf</filename>.
+</para>
+</section>
+<section id="SECID68">
+<title>LDAP quoting</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>quoting</secondary>
+</indexterm>
+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,
+within an LDAP query, two different kinds of quoting are required. For this
+reason, there are two different LDAP-specific quoting operators.
+</para>
+<para>
+The <option>quote_ldap</option> operator is designed for use on strings that are part of
+filter specifications. Conceptually, it first does the following conversions on
+the string:
+</para>
+<literallayout class="monospaced">
+*   =&gt;   \2A
+(   =&gt;   \28
+)   =&gt;   \29
+\   =&gt;   \5C
+</literallayout>
+<para>
+in accordance with RFC 2254. The resulting string is then quoted according
+to the rules for URLs, that is, all non-alphanumeric characters except
+</para>
+<literallayout class="monospaced">
+! $ ' - . _ ( ) * +
+</literallayout>
+<para>
+are converted to their hex values, preceded by a percent sign. For example:
+</para>
+<literallayout class="monospaced">
+${quote_ldap: a(bc)*, a&lt;yz&gt;; }
+</literallayout>
+<para>
+yields
+</para>
+<literallayout class="monospaced">
+%20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
+</literallayout>
+<para>
+Removing the URL quoting, this is (with a leading and a trailing space):
+</para>
+<literallayout class="monospaced">
+a\28bc\29\2A, a&lt;yz&gt;;
+</literallayout>
+<para>
+The <option>quote_ldap_dn</option> operator is designed for use on strings that are part of
+base DN specifications in queries. Conceptually, it first converts the string
+by inserting a backslash in front of any of the following characters:
+</para>
+<literallayout class="monospaced">
+, + " \ &lt; &gt; ;
+</literallayout>
+<para>
+It also inserts a backslash before any leading spaces or # characters, and
+before any trailing spaces. (These rules are in RFC 2253.) The resulting string
+is then quoted according to the rules for URLs. For example:
+</para>
+<literallayout class="monospaced">
+${quote_ldap_dn: a(bc)*, a&lt;yz&gt;; }
+</literallayout>
+<para>
+yields
+</para>
+<literallayout class="monospaced">
+%5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
+</literallayout>
+<para>
+Removing the URL quoting, this is (with a trailing space):
+</para>
+<literallayout class="monospaced">
+\ a(bc)*\, a\&lt;yz\&gt;\;\
+</literallayout>
+<para>
+There are some further comments about quoting in the section on LDAP
+authentication below.
+</para>
+</section>
+<section id="SECID69">
+<title>LDAP connections</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>connections</secondary>
+</indexterm>
+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
+an LDAP server. A server that is reached by TCP/IP can be specified in a query
+by starting it with
+</para>
+<literallayout class="monospaced">
+ldap://&lt;hostname&gt;:&lt;port&gt;/...
+</literallayout>
+<para>
+If the port (and preceding colon) are omitted, the standard LDAP port (389) is
+used. When no server is specified in a query, a list of default servers is
+taken from the <option>ldap_default_servers</option> configuration option. This supplies a
+colon-separated list of servers which are tried in turn until one successfully
+handles a query, or there is a serious error. Successful handling either
+returns the requested data, or indicates that it does not exist. Serious errors
+are syntactical, or multiple values when only a single value is expected.
+Errors which cause the next server to be tried are connection failures, bind
+failures, and timeouts.
+</para>
+<para>
+For each server name in the list, a port number can be given. The standard way
+of specifying a host and port is to use a colon separator (RFC 1738). Because
+<option>ldap_default_servers</option> is a colon-separated list, such colons have to be
+doubled. For example
+</para>
+<literallayout class="monospaced">
+ldap_default_servers = ldap1.example.com::145:ldap2.example.com
+</literallayout>
+<para>
+If <option>ldap_default_servers</option> is unset, a URL with no server name is passed
+to the LDAP library with no server name, and the library&#x2019;s default (normally
+the local host) is used.
+</para>
+<para>
+If you are using the OpenLDAP library, you can connect to an LDAP server using
+a Unix domain socket instead of a TCP/IP connection. This is specified by using
+<literal>ldapi</literal> instead of <literal>ldap</literal> in LDAP queries. What follows here applies only
+to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
+not available.
+</para>
+<para>
+For this type of connection, instead of a host name for the server, a pathname
+for the socket is required, and the port number is not relevant. The pathname
+can be specified either as an item in <option>ldap_default_servers</option>, or inline in
+the query. In the former case, you can have settings such as
+</para>
+<literallayout class="monospaced">
+ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
+</literallayout>
+<para>
+When the pathname is given in the query, you have to escape the slashes as
+<literal>%2F</literal> to fit in with the LDAP URL syntax. For example:
+</para>
+<literallayout class="monospaced">
+${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
+</literallayout>
+<para>
+When Exim processes an LDAP lookup and finds that the <quote>hostname</quote> is really
+a pathname, it uses the Unix domain socket code, even if the query actually
+specifies <literal>ldap</literal> or <literal>ldaps</literal>. In particular, no encryption is used for a
+socket connection. This behaviour means that you can use a setting of
+<option>ldap_default_servers</option> such as in the example above with traditional <literal>ldap</literal>
+or <literal>ldaps</literal> queries, and it will work. First, Exim tries a connection via
+the Unix domain socket; if that fails, it tries a TCP/IP connection to the
+backup host.
+</para>
+<para>
+If an explicit <literal>ldapi</literal> type is given in a query when a host name is
+specified, an error is diagnosed. However, if there are more items in
+<option>ldap_default_servers</option>, they are tried. In other words:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Using a pathname with <literal>ldap</literal> or <literal>ldaps</literal> forces the use of the Unix domain
+interface.
+</para>
+</listitem>
+<listitem>
+<para>
+Using <literal>ldapi</literal> with a host name causes an error.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Using <literal>ldapi</literal> with no host or path in the query, and no setting of
+<option>ldap_default_servers</option>, does whatever the library does by default.
+</para>
+</section>
+<section id="SECID70">
+<title>LDAP authentication and control information</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>authentication</secondary>
+</indexterm>
+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
+be preceded by any number of &lt;<emphasis>name</emphasis>&gt;=&lt;<emphasis>value</emphasis>&gt; settings, separated by
+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:
+</para>
+<literallayout>
+<literal>DEREFERENCE</literal>  set the dereferencing parameter
+<literal>NETTIME    </literal>  set a timeout for a network operation
+<literal>USER       </literal>  set the DN, for authenticating the LDAP bind
+<literal>PASS       </literal>  set the password, likewise
+<literal>REFERRALS  </literal>  set the referrals parameter
+<literal>SERVERS    </literal>  set alternate server list for this query only
+<literal>SIZE       </literal>  set the limit for the number of entries returned
+<literal>TIME       </literal>  set the maximum waiting time for a query
+</literallayout>
+<para>
+The value of the DEREFERENCE parameter must be one of the words <quote>never</quote>,
+<quote>searching</quote>, <quote>finding</quote>, or <quote>always</quote>. The value of the REFERRALS parameter
+must be <quote>follow</quote> (the default) or <quote>nofollow</quote>. The latter stops the LDAP
+library from trying to follow referrals issued by the LDAP server.
+</para>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>timeout</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>timeout</primary>
+<secondary>LDAP lookup</secondary>
+</indexterm>
+The name CONNECT is an obsolete name for NETTIME, retained for
+backwards compatibility. This timeout (specified as a number of seconds) is
+enforced from the client end for operations that can be carried out over a
+network. Specifically, it applies to network connections and calls to the
+<emphasis>ldap_result()</emphasis> function. If the value is greater than zero, it is used if
+LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or
+if LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape
+SDK 4.1). A value of zero forces an explicit setting of <quote>no timeout</quote> for
+Netscape SDK; for OpenLDAP no action is taken.
+</para>
+<para>
+The TIME parameter (also a number of seconds) is passed to the server to
+set a server-side limit on the time taken to complete a search.
+</para>
+<para>
+The SERVERS parameter allows you to specify an alternate list of ldap servers
+to use for an individual lookup.  The global <option>ldap_default_servers</option> option provides a
+default list of ldap servers, and a single lookup can specify a single ldap
+server to use.  But when you need to do a lookup with a list of servers that is
+different than the default list (maybe different order, maybe a completely
+different set of servers), the SERVERS parameter allows you to specify this
+alternate list (colon-separated).
+</para>
+<para>
+Here is an example of an LDAP query in an Exim lookup that uses some of these
+values. This is a single line, folded to fit on the page:
+</para>
+<literallayout class="monospaced">
+${lookup ldap
+  {user="cn=manager,o=University of Cambridge,c=UK" pass=secret
+  ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)}
+  {$value}fail}
+</literallayout>
+<para>
+The encoding of spaces as <literal>%20</literal> is a URL thing which should not be done for
+any of the auxiliary data. Exim configuration settings that include lookups
+which contain password information should be preceded by <quote>hide</quote> to prevent
+non-admin users from using the <option>-bP</option> option to see their values.
+</para>
+<para>
+The auxiliary data items may be given in any order. The default is no
+connection timeout (the system timeout is used), no user or password, no limit
+on the number of entries returned, and no time limit on queries.
+</para>
+<para>
+When a DN is quoted in the USER= setting for LDAP authentication, Exim
+removes any URL quoting that it may contain before passing it LDAP. Apparently
+some libraries do this for themselves, but some do not. Removing the URL
+quoting has two advantages:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+It makes it possible to use the same <option>quote_ldap_dn</option> expansion for USER=
+DNs as with DNs inside actual queries.
+</para>
+</listitem>
+<listitem>
+<para>
+It permits spaces inside USER= DNs.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+For example, a setting such as
+</para>
+<literallayout class="monospaced">
+USER=cn=${quote_ldap_dn:$1}
+</literallayout>
+<para>
+should work even if <varname>$1</varname> contains spaces.
+</para>
+<para>
+Expanded data for the PASS= value should be quoted using the <option>quote</option>
+expansion operator, rather than the LDAP quote operators. The only reason this
+field needs quoting is to ensure that it conforms to the Exim syntax, which
+does not allow unquoted spaces. For example:
+</para>
+<literallayout class="monospaced">
+PASS=${quote:$3}
+</literallayout>
+<para>
+The LDAP authentication mechanism can be used to check passwords as part of
+SMTP authentication. See the <option>ldapauth</option> expansion string condition in chapter
+<xref linkend="CHAPexpand"/>.
+</para>
+</section>
+<section id="SECID71">
+<title>Format of data returned by LDAP</title>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>returned data formats</secondary>
+</indexterm>
+The <command>ldapdn</command> lookup type returns the Distinguished Name from a single entry
+as a sequence of values, for example
+</para>
+<literallayout class="monospaced">
+cn=manager,o=University of Cambridge,c=UK
+</literallayout>
+<para>
+The <command>ldap</command> lookup type generates an error if more than one entry matches the
+search filter, whereas <command>ldapm</command> permits this case, and inserts a newline in
+the result between the data from different entries. It is possible for multiple
+values to be returned for both <command>ldap</command> and <command>ldapm</command>, but in the former case
+you know that whatever values are returned all came from a single entry in the
+directory.
+</para>
+<para>
+In the common case where you specify a single attribute in your LDAP query, the
+result is not quoted, and does not contain the attribute name. If the attribute
+has multiple values, they are separated by commas. Any comma that is
+part of an attribute&#x2019;s value is doubled.
+</para>
+<para>
+If you specify multiple attributes, the result contains space-separated, quoted
+strings, each preceded by the attribute name and an equals sign. Within the
+quotes, the quote character, backslash, and newline are escaped with
+backslashes, and commas are used to separate multiple values for the attribute.
+Any commas in attribute values are doubled
+(permitting treatment of the values as a comma-separated list).
+Apart from the escaping, the string within quotes takes the same form as the
+output when a single attribute is requested. Specifying no attributes is the
+same as specifying all of an entry&#x2019;s attributes.
+</para>
+<para>
+Here are some examples of the output format. The first line of each pair is an
+LDAP query, and the second is the data that is returned. The attribute called
+<option>attr1</option> has two values, one of them with an embedded comma, whereas
+<option>attr2</option> has only one value. Both attributes are derived from <option>attr</option>
+(they have SUP <option>attr</option> in their schema definitions).
+</para>
+<literallayout class="monospaced">
+ldap:///o=base?attr1?sub?(uid=fred)
+value1.1,value1,,2
+
+ldap:///o=base?attr2?sub?(uid=fred)
+value two
+
+ldap:///o=base?attr?sub?(uid=fred)
+value1.1,value1,,2,value two
+
+ldap:///o=base?attr1,attr2?sub?(uid=fred)
+attr1="value1.1,value1,,2" attr2="value two"
+
+ldap:///o=base??sub?(uid=fred)
+objectClass="top" attr1="value1.1,value1,,2" attr2="value two"
+</literallayout>
+<para>
+You can
+make use of Exim&#x2019;s <option>-be</option> option to run expansion tests and thereby check the
+results of LDAP lookups.
+The <option>extract</option> operator in string expansions can be used to pick out
+individual fields from data that consists of <emphasis>key</emphasis>=<emphasis>value</emphasis> pairs.
+The <option>listextract</option> operator should be used to pick out individual values
+of attributes, even when only a single value is expected.
+The doubling of embedded commas allows you to use the returned data as a
+comma separated list (using the "&lt;," syntax for changing the input list separator).
+</para>
+</section>
+<section id="SECTnisplus">
+<title>More about NIS+</title>
+<para>
+<indexterm role="concept">
+<primary>NIS+ lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>NIS+</secondary>
+</indexterm>
+NIS+ queries consist of a NIS+ <emphasis>indexed name</emphasis> followed by an optional colon
+and field name. If this is given, the result of a successful query is the
+contents of the named field; otherwise the result consists of a concatenation
+of <emphasis>field-name=field-value</emphasis> pairs, separated by spaces. Empty values and
+values containing spaces are quoted. For example, the query
+</para>
+<literallayout class="monospaced">
+[name=mg1456],passwd.org_dir
+</literallayout>
+<para>
+might return the string
+</para>
+<literallayout class="monospaced">
+name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
+home=/home/mg1456 shell=/bin/bash shadow=""
+</literallayout>
+<para>
+(split over two lines here to fit on the page), whereas
+</para>
+<literallayout class="monospaced">
+[name=mg1456],passwd.org_dir:gcos
+</literallayout>
+<para>
+would just return
+</para>
+<literallayout class="monospaced">
+Martin Guerre
+</literallayout>
+<para>
+with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
+for the given indexed key. The effect of the <option>quote_nisplus</option> expansion
+operator is to double any quote characters within the text.
+</para>
+</section>
+<section id="SECTsql">
+<title>SQL lookups</title>
+<para>
+<indexterm role="concept">
+<primary>SQL lookup types</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>MySQL</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>PostgreSQL lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>MySQL</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>PostgreSQL</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Oracle</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Oracle</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>InterBase lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>InterBase</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Redis lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Redis</secondary>
+</indexterm>
+Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis,
+and SQLite
+databases. Queries for these databases contain SQL statements, so an example
+might be
+</para>
+<literallayout class="monospaced">
+${lookup mysql{select mailbox from users where id='userx'}\
+  {$value}fail}
+</literallayout>
+<para>
+If the result of the query contains more than one field, the data for each
+field in the row is returned, preceded by its name, so the result of
+</para>
+<literallayout class="monospaced">
+${lookup pgsql{select home,name from users where id='userx'}\
+  {$value}}
+</literallayout>
+<para>
+might be
+</para>
+<literallayout class="monospaced">
+home=/home/userx name="Mister X"
+</literallayout>
+<para>
+Empty values and values containing spaces are double quoted, with embedded
+quotes escaped by a backslash. If the result of the query contains just one
+field, the value is passed back verbatim, without a field name, for example:
+</para>
+<literallayout class="monospaced">
+Mister X
+</literallayout>
+<para>
+If the result of the query yields more than one row, it is all concatenated,
+with a newline between the data for each row.
+</para>
+</section>
+<section id="SECID72">
+<title>More about MySQL, PostgreSQL, Oracle, InterBase, and Redis</title>
+<para>
+<indexterm role="concept">
+<primary>MySQL</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>PostgreSQL lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>MySQL</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>PostgreSQL</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Oracle</primary>
+<secondary>lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Oracle</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>InterBase lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>InterBase</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Redis lookup type</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Redis</secondary>
+</indexterm>
+If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the
+<option>mysql_servers</option>, <option>pgsql_servers</option>, <option>oracle_servers</option>, <option>ibase_servers</option>,
+or <option>redis_servers</option>
+option (as appropriate) must be set to a colon-separated list of server
+information.
+<indexterm role="option">
+<primary><option>mysql_servers</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>pgsql_servers</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>oracle_servers</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>ibase_servers</option></primary>
+</indexterm>
+<indexterm role="option">
+<primary><option>redis_servers</option></primary>
+</indexterm>
+(For MySQL and PostgreSQL, the global option need not be set if all
+queries contain their own server information &ndash; see section
+<xref linkend="SECTspeserque"/>.)
+For all but Redis
+each item in the list is a slash-separated list of four
+items: host name, database name, user name, and password. In the case of
+Oracle, the host name field is used for the <quote>service name</quote>, and the database
+name field is not used and should be empty. For example:
+</para>
+<literallayout class="monospaced">
+hide oracle_servers = oracle.plc.example//userx/abcdwxyz
+</literallayout>
+<para>
+Because password data is sensitive, you should always precede the setting with
+<quote>hide</quote>, to prevent non-admin users from obtaining the setting via the <option>-bP</option>
+option. Here is an example where two MySQL servers are listed:
+</para>
+<literallayout class="monospaced">
+hide mysql_servers = localhost/users/root/secret:\
+                     otherhost/users/root/othersecret
+</literallayout>
+<para>
+For MySQL and PostgreSQL, a host may be specified as &lt;<emphasis>name</emphasis>&gt;:&lt;<emphasis>port</emphasis>&gt; but
+because this is a colon-separated list, the colon has to be doubled. For each
+query, these parameter groups are tried in order until a connection is made and
+a query is successfully processed. The result of a query may be that no data is
+found, but that is still a successful query. In other words, the list of
+servers provides a backup facility, not a list of different places to look.
+</para>
+<para>
+For Redis the global option need not be specified if all queries contain their
+own server information &ndash; see section <xref linkend="SECTspeserque"/>.
+If specified, the option must be set to a colon-separated list of server
+information.
+Each item in the list is a slash-separated list of three items:
+host, database number, and password.
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+The host is required and may be either an IPv4 address and optional
+port number (separated by a colon, which needs doubling due to the
+higher-level list), or a Unix socket pathname enclosed in parentheses
+</para>
+</listitem>
+<listitem>
+<para>
+The database number is optional; if present that number is selected in the backend
+</para>
+</listitem>
+<listitem>
+<para>
+The password is optional; if present it is used to authenticate to the backend
+</para>
+</listitem>
+</orderedlist>
+<para>
+The <option>quote_mysql</option>, <option>quote_pgsql</option>, and <option>quote_oracle</option> expansion operators
+convert newline, tab, carriage return, and backspace to \n, \t, \r, and \b
+respectively, and the characters single-quote, double-quote, and backslash
+itself are escaped with backslashes.
+</para>
+<para>
+The <option>quote_redis</option> expansion operator
+escapes whitespace and backslash characters with a backslash.
+</para>
+</section>
+<section id="SECTspeserque">
+<title>Specifying the server in the query</title>
+<para>
+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:
+</para>
+<literallayout>
+<literal>,servers=</literal><emphasis>server1:server2:server3:...</emphasis>
+</literallayout>
+<para>
+Each item in the list may take one of two forms:
+</para>
+<orderedlist numeration="arabic">
+<listitem>
+<para>
+If it contains no slashes it is assumed to be just a host name. The appropriate
+global option (<option>mysql_servers</option> or <option>pgsql_servers</option>) is searched for a host
+of the same name, and the remaining parameters (database, user, password) are
+taken from there.
+</para>
+</listitem>
+<listitem>
+<para>
+If it contains any slashes, it is taken as a complete parameter set.
+</para>
+</listitem>
+</orderedlist>
+<para>
+The list of servers is used in exactly the same way as the global list.
+Once a connection to a server has happened and a query has been
+successfully executed, processing of the lookup ceases.
+</para>
+<para>
+This feature is intended for use in master/slave situations where updates
+are occurring and you want to update the master rather than a slave. If the
+master is in the list as a backup for reading, you might have a global setting
+like this:
+</para>
+<literallayout class="monospaced">
+mysql_servers = slave1/db/name/pw:\
+                slave2/db/name/pw:\
+                master/db/name/pw
+</literallayout>
+<para>
+In an updating lookup, you could then write:
+</para>
+<literallayout class="monospaced">
+${lookup mysql,servers=master {UPDATE ...} }
+</literallayout>
+<para>
+That query would then be sent only to the master server. If, on the other hand,
+the master is not to be used for reading, and so is not present in the global
+option, you can still update it by a query of this form:
+</para>
+<literallayout class="monospaced">
+${lookup pgsql,servers=master/db/name/pw {UPDATE ...} }
+</literallayout>
+<para>
+An older syntax places the servers specification before the query,
+semicolon separated:
+</para>
+<literallayout class="monospaced">
+${lookup mysql{servers=master; UPDATE ...} }
+</literallayout>
+<para>
+The new version avoids potential issues with tainted
+arguments in the query, for explicit expansion.
+<emphasis role="bold">Note</emphasis>: server specifications in list-style lookups are still problematic.
+</para>
+</section>
+<section id="SECID73">
+<title>Special MySQL features</title>
+<para>
+For MySQL, an empty host name or the use of <quote>localhost</quote> in <option>mysql_servers</option>
+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.
+An option group name for MySQL option files can be specified in square brackets;
+the default value is <quote>exim</quote>.
+The full syntax of each item in <option>mysql_servers</option> is:
+</para>
+<literallayout>
+&lt;<emphasis>hostname</emphasis>&gt;::&lt;<emphasis>port</emphasis>&gt;(&lt;<emphasis>socket name</emphasis>&gt;)[&lt;<emphasis>option group</emphasis>&gt;]/&lt;<emphasis>database</emphasis>&gt;/&lt;<emphasis>user</emphasis>&gt;/&lt;<emphasis>password</emphasis>&gt;
+</literallayout>
+<para>
+Any of the four sub-parts of the first field can be omitted. For normal use on
+the local host it can be left blank or set to just <quote>localhost</quote>.
+</para>
+<para>
+No database need be supplied &ndash; but if it is absent here, it must be given in
+the queries.
+</para>
+<para>
+If a MySQL query is issued that does not request any data (an insert, update,
+or delete command), the result of the lookup is the number of rows affected.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: This can be misleading. If an update does not actually change
+anything (for example, setting a field to the value it already has), the result
+is zero because no rows are affected.
+</para>
+</section>
+<section id="SECID74">
+<title>Special PostgreSQL features</title>
+<para>
+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
+database server. A configuration line for PostgreSQL via Unix domain sockets
+looks like this:
+</para>
+<literallayout class="monospaced">
+hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
+</literallayout>
+<para>
+In other words, instead of supplying a host name, a path to the socket is
+given. The path name is enclosed in parentheses so that its slashes aren&#x2019;t
+visually confused with the delimiters for the other server parameters.
+</para>
+<para>
+If a PostgreSQL query is issued that does not request any data (an insert,
+update, or delete command), the result of the lookup is the number of rows
+affected.
+</para>
+</section>
+<section id="SECTsqlite">
+<title>More about SQLite</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>SQLite</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>sqlite lookup type</primary>
+</indexterm>
+SQLite is different to the other SQL lookups because a filename is required in
+addition to the SQL query. An SQLite database is a single file, and there is no
+daemon as in the other SQL databases.
+</para>
+<para revisionflag="changed">
+<indexterm role="option">
+<primary><option>sqlite_dbfile</option></primary>
+</indexterm>
+There are two ways of
+specifying the file.
+The first is is by using the <option>sqlite_dbfile</option> main option.
+The second, which allows separate files for each query,
+is to use an option appended, comma-separated, to the <quote>sqlite</quote>
+lookup type word.  The option is the word <quote>file</quote>, then an equals,
+then the filename.
+The filename in this case cannot contain whitespace or open-brace charachters.
+</para>
+<para>
+A deprecated method is available, prefixing the query with the filename
+separated by white space.
+This means that
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>sqlite file</secondary>
+</indexterm>
+the query cannot use any tainted values, as that taints
+the entire query including the filename - resulting in a refusal to open
+the file.
+</para>
+<para>
+In all the above cases the filename must be an absolute path.
+</para>
+<para>
+Here is a lookup expansion example:
+</para>
+<literallayout class="monospaced">
+sqlite_dbfile = /some/thing/sqlitedb
+...
+${lookup sqlite {select name from aliases where id='userx';}}
+</literallayout>
+<para>
+In a list, the syntax is similar. For example:
+</para>
+<literallayout class="monospaced">
+domainlist relay_to_domains = sqlite;\
+   select * from relays where ip='$sender_host_address';
+</literallayout>
+<para>
+The only character affected by the <option>quote_sqlite</option> operator is a single
+quote, which it doubles.
+</para>
+<para>
+<indexterm role="concept">
+<primary>timeout</primary>
+<secondary>SQLite</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>sqlite</primary>
+<secondary>lookup timeout</secondary>
+</indexterm>
+The SQLite library handles multiple simultaneous accesses to the database
+internally. Multiple readers are permitted, but only one process can
+update at once. Attempts to access the database while it is being updated
+are rejected after a timeout period, during which the SQLite library
+waits for the lock to be released. In Exim, the default timeout is set
+to 5 seconds, but it can be changed by means of the <option>sqlite_lock_timeout</option>
+option.
+</para>
+</section>
+<section id="SECTredis">
+<title>More about Redis</title>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>Redis</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>redis lookup type</primary>
+</indexterm>
+Redis is a non-SQL database. Commands are simple get and set.
+Examples:
+</para>
+<literallayout class="monospaced">
+${lookup redis{set keyname ${quote_redis:objvalue plus}}}
+${lookup redis{get keyname}}
+</literallayout>
+<para>
+As of release 4.91, "lightweight" support for Redis Cluster is available.
+Requires <option>redis_servers</option> list to contain all the servers in the cluster, all
+of which must be reachable from the running exim instance. If the cluster has
+master/slave replication, the list must contain all the master and slave
+servers.
+</para>
+<para>
+When the Redis Cluster returns a "MOVED" response to a query, Exim does not
+immediately follow the redirection but treats the response as a DEFER, moving on
+to the next server in the <option>redis_servers</option> list until the correct server is
+reached.
+</para>
+<para>
+<indexterm role="concept" startref="IIDfidalo1" class="endofrange"/>
+<indexterm role="concept" startref="IIDfidalo2" class="endofrange"/>
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPdomhosaddlists">
+<title>Domain, host, address, and local part lists</title>
+<titleabbrev>Domain, host, and address lists</titleabbrev>
+<para>
+<indexterm role="concept" id="IIDdohoadli" class="startofrange">
+<primary>lists of domains; hosts; etc.</primary>
+</indexterm>
+A number of Exim configuration options contain lists of domains, hosts,
+email addresses, or local parts. For example, the <option>hold_domains</option> option
+contains a list of domains whose delivery is currently suspended. These lists
+are also used as data in ACL statements (see chapter <xref linkend="CHAPACL"/>), and as
+arguments to expansion conditions such as <option>match_domain</option>.
+</para>
+<para>
+Each item in one of these lists is a pattern to be matched against a domain,
+host, email address, or local part, respectively. In the sections below, the
+different types of pattern for each case are described, but first we cover some
+general facilities that apply to all four kinds of list.
+</para>
+<para>
+Note that other parts of Exim use a <emphasis>string list</emphasis> which does not
+support all the complexity available in
+domain, host, address and local part lists.
+</para>
+<section id="SECTlistexpand">
+<title>Expansion of lists</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>of lists</secondary>
+</indexterm>
+Each list is expanded as a single string before it is used.
+</para>
+<para>
+<emphasis>Exception: the router headers_remove option, where list-item
+splitting is done before string-expansion.</emphasis>
+</para>
+<para>
+The result of
+expansion must be a list, possibly containing empty items, which is split up
+into separate items for matching. By default, colon is the separator character,
+but this can be varied if necessary. See sections <xref linkend="SECTlistconstruct"/> and
+<xref linkend="SECTempitelis"/> for details of the list syntax; the second of these
+discusses the way to specify empty list items.
+</para>
+<para>
+If the string expansion is forced to fail, Exim behaves as if the item it is
+testing (domain, host, address, or local part) is not in the list. Other
+expansion failures cause temporary errors.
+</para>
+<para>
+If an item in a list is a regular expression, backslashes, dollars and possibly
+other special characters in the expression must be protected against
+misinterpretation by the string expander. The easiest way to do this is to use
+the <literal>\N</literal> expansion feature to indicate that the contents of the regular
+expression should not be expanded. For example, in an ACL you might have:
+</para>
+<literallayout class="monospaced">
+deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \
+               ${lookup{$domain}lsearch{/badsenders/bydomain}}
+</literallayout>
+<para>
+The first item is a regular expression that is protected from expansion by
+<literal>\N</literal>, whereas the second uses the expansion to obtain a list of unwanted
+senders based on the receiving domain.
+</para>
+</section>
+<section id="SECID76">
+<title>Negated items in lists</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>negation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>negation</primary>
+<secondary>in lists</secondary>
+</indexterm>
+Items in a list may be positive or negative. Negative items are indicated by a
+leading exclamation mark, which may be followed by optional white space. A list
+defines a set of items (domains, etc). When Exim processes one of these lists,
+it is trying to find out whether a domain, host, address, or local part
+(respectively) is in the set that is defined by the list. It works like this:
+</para>
+<para>
+The list is scanned from left to right. If a positive item is matched, the
+subject that is being checked is in the set; if a negative item is matched, the
+subject is not in the set. If the end of the list is reached without the
+subject having matched any of the patterns, it is in the set if the last item
+was a negative one, but not if it was a positive one. For example, the list in
+</para>
+<literallayout class="monospaced">
+domainlist relay_to_domains = !a.b.c : *.b.c
+</literallayout>
+<para>
+matches any domain ending in <emphasis>.b.c</emphasis> except for <emphasis>a.b.c</emphasis>. Domains that match
+neither <emphasis>a.b.c</emphasis> nor <emphasis>*.b.c</emphasis> do not match, because the last item in the
+list is positive. However, if the setting were
+</para>
+<literallayout class="monospaced">
+domainlist relay_to_domains = !a.b.c
+</literallayout>
+<para>
+then all domains other than <emphasis>a.b.c</emphasis> would match because the last item in the
+list is negative. In other words, a list that ends with a negative item behaves
+as if it had an extra item <literal>:*</literal> on the end.
+</para>
+<para>
+Another way of thinking about positive and negative items in lists is to read
+the connector as <quote>or</quote> after a positive item and as <quote>and</quote> after a negative
+item.
+</para>
+</section>
+<section id="SECTfilnamlis">
+<title>File names in lists</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>filename in</secondary>
+</indexterm>
+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
+processed as if it were an independent item in the list, except that further
+filenames are not allowed,
+and no expansion of the data from the file takes place.
+Empty lines in the file are ignored, and the file may also contain comment
+lines:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+For domain and host lists, if a # character appears anywhere in a line of the
+file, it and all following characters are ignored.
+</para>
+</listitem>
+<listitem>
+<para>
+Because local parts may legitimately contain # characters, a comment in an
+address list or local part list file is recognized only if # is preceded by
+white space or the start of the line. For example:
+</para>
+<literallayout class="monospaced">
+not#comment@???   # but this is a comment
+</literallayout>
+</listitem>
+</itemizedlist>
+<para>
+Putting a filename in a list has the same effect as inserting each line of the
+file as an item in the list (blank lines and comments excepted). However, there
+is one important difference: the file is read each time the list is processed,
+so if its contents vary over time, Exim&#x2019;s behaviour changes.
+</para>
+<para>
+If a filename is preceded by an exclamation mark, the sense of any match
+within the file is inverted. For example, if
+</para>
+<literallayout class="monospaced">
+hold_domains = !/etc/nohold-domains
+</literallayout>
+<para>
+and the file contains the lines
+</para>
+<literallayout class="monospaced">
+!a.b.c
+*.b.c
+</literallayout>
+<para>
+then <emphasis>a.b.c</emphasis> is in the set of domains defined by <option>hold_domains</option>, whereas
+any domain matching <literal>*.b.c</literal> is not.
+</para>
+</section>
+<section id="SECID77">
+<title>An lsearch file is not an out-of-line list</title>
+<para>
+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 <command>lsearch</command> lookups work in lists. Because
+an <command>lsearch</command> file contains plain text and is scanned sequentially, it is
+sometimes thought that it is allowed to contain wild cards and other kinds of
+non-constant pattern. This is not the case. The keys in an <command>lsearch</command> file are
+always fixed strings, just as for any other single-key lookup type.
+</para>
+<para>
+If you want to use a file to contain wild-card patterns that form part of a
+list, just give the filename on its own, without a search type, as described
+in the previous section. You could also use the <command>wildlsearch</command> or
+<command>nwildlsearch</command>, but there is no advantage in doing this.
+</para>
+</section>
+<section id="SECTlistresults">
+<title>Results of list checking</title>
+<para>
+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:
+</para>
+<variablelist>
+<varlistentry>
+<term>hosts</term>
+<listitem>
+<para>
+A <option>hosts</option> ACL condition
+will store a result in the <varname>$host_data</varname> variable.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>local_parts</term>
+<listitem>
+<para>
+A <option>local_parts</option> router option or <option>local_parts</option> ACL condition
+will store a result in the <varname>$local_part_data</varname> variable.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>domains</term>
+<listitem>
+<para revisionflag="changed">
+A <option>domains</option> router option or <option>domains</option> ACL condition
+will store a result in the <varname>$domain_data</varname> variable.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>senders</term>
+<listitem>
+<para>
+A <option>senders</option> router option or <option>senders</option> ACL condition
+will store a result in the <varname>$sender_data</varname> variable.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>recipients</term>
+<listitem>
+<para>
+A <option>recipients</option> ACL condition
+will store a result in the <varname>$recipient_data</varname> variable.
+</para>
+</listitem></varlistentry>
+</variablelist>
+<para>
+The detail of the additional information depends on the
+type of match and is given below as the <emphasis role="bold">value</emphasis> information.
+</para>
+</section>
+<section id="SECTnamedlists">
+<title>Named lists</title>
+<para>
+<indexterm role="concept">
+<primary>named lists</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>named</secondary>
+</indexterm>
+A list of domains, hosts, email addresses, or local parts can be given a name
+which is then used to refer to the list elsewhere in the configuration. This is
+particularly convenient if the same list is required in several different
+places. It also allows lists to be given meaningful names, which can improve
+the readability of the configuration. For example, it is conventional to define
+a domain list called <emphasis>local_domains</emphasis> for all the domains that are handled
+locally on a host, using a configuration line such as
+</para>
+<literallayout class="monospaced">
+domainlist local_domains = localhost:my.dom.example
+</literallayout>
+<para>
+Named lists are referenced by giving their name preceded by a plus sign, so,
+for example, a router that is intended to handle local domains would be
+configured with the line
+</para>
+<literallayout class="monospaced">
+domains = +local_domains
+</literallayout>
+<para>
+The first router in a configuration is often one that handles all domains
+except the local ones, using a configuration with a negated item like this:
+</para>
+<literallayout class="monospaced">
+dnslookup:
+  driver = dnslookup
+  domains = ! +local_domains
+  transport = remote_smtp
+  no_more
+</literallayout>
+<para>
+The four kinds of named list are created by configuration lines starting with
+the words <option>domainlist</option>, <option>hostlist</option>, <option>addresslist</option>, or <option>localpartlist</option>,
+respectively. Then there follows the name that you are defining, followed by an
+equals sign and the list itself. For example:
+</para>
+<literallayout class="monospaced">
+hostlist    relay_from_hosts = 192.168.23.0/24 : my.friend.example
+addresslist bad_senders = cdb;/etc/badsenders
+</literallayout>
+<para>
+A named list may refer to other named lists:
+</para>
+<literallayout class="monospaced">
+domainlist  dom1 = first.example : second.example
+domainlist  dom2 = +dom1 : third.example
+domainlist  dom3 = fourth.example : +dom2 : fifth.example
+</literallayout>
+<para>
+<emphasis role="bold">Warning</emphasis>: If the last item in a referenced list is a negative one, the
+effect may not be what you intended, because the negation does not propagate
+out to the higher level. For example, consider:
+</para>
+<literallayout class="monospaced">
+domainlist  dom1 = !a.b
+domainlist  dom2 = +dom1 : *.b
+</literallayout>
+<para>
+The second list specifies <quote>either in the <option>dom1</option> list or <emphasis>*.b</emphasis></quote>. The first
+list specifies just <quote>not <emphasis>a.b</emphasis></quote>, so the domain <emphasis>x.y</emphasis> matches it. That
+means it matches the second list as well. The effect is not the same as
+</para>
+<literallayout class="monospaced">
+domainlist  dom2 = !a.b : *.b
+</literallayout>
+<para>
+where <emphasis>x.y</emphasis> does not match. It&#x2019;s best to avoid negation altogether in
+referenced lists if you can.
+</para>
+<para>
+<indexterm role="concept">
+<primary>hiding named list values</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>named lists</primary>
+<secondary>hiding value of</secondary>
+</indexterm>
+Some named list definitions may contain sensitive data, for example, passwords for
+accessing databases. To stop non-admin users from using the <option>-bP</option> command
+line option to read these values, you can precede the definition with the
+word <quote>hide</quote>. For example:
+</para>
+<literallayout class="monospaced">
+hide domainlist filter_for_domains = ldap;PASS=secret ldap::/// ...
+</literallayout>
+<para>
+Named lists may have a performance advantage. When Exim is routing an
+address or checking an incoming message, it caches the result of tests on named
+lists. So, if you have a setting such as
+</para>
+<literallayout class="monospaced">
+domains = +local_domains
+</literallayout>
+<para>
+on several of your routers
+or in several ACL statements,
+the actual test is done only for the first one. However, the caching works only
+if there are no expansions within the list itself or any sublists that it
+references. In other words, caching happens only for lists that are known to be
+the same each time they are referenced.
+</para>
+<para>
+By default, there may be up to 16 named lists of each type. This limit can be
+extended by changing a compile-time variable. The use of domain and host lists
+is recommended for concepts such as local domains, relay domains, and relay
+hosts. The default configuration is set up like this.
+</para>
+</section>
+<section id="SECID78">
+<title>Named lists compared with macros</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>named compared with macro</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>macro</primary>
+<secondary>compared with named list</secondary>
+</indexterm>
+At first sight, named lists might seem to be no different from macros in the
+configuration file. However, macros are just textual substitutions. If you
+write
+</para>
+<literallayout class="monospaced">
+ALIST = host1 : host2
+auth_advertise_hosts = !ALIST
+</literallayout>
+<para>
+it probably won&#x2019;t do what you want, because that is exactly the same as
+</para>
+<literallayout class="monospaced">
+auth_advertise_hosts = !host1 : host2
+</literallayout>
+<para>
+Notice that the second host name is not negated. However, if you use a host
+list, and write
+</para>
+<literallayout class="monospaced">
+hostlist alist = host1 : host2
+auth_advertise_hosts = ! +alist
+</literallayout>
+<para>
+the negation applies to the whole list, and so that is equivalent to
+</para>
+<literallayout class="monospaced">
+auth_advertise_hosts = !host1 : !host2
+</literallayout>
+</section>
+<section id="SECID79">
+<title>Named list caching</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>caching of named</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>caching</primary>
+<secondary>named lists</secondary>
+</indexterm>
+While processing a message, Exim caches the result of checking a named list if
+it is sure that the list is the same each time. In practice, this means that
+the cache operates only if the list contains no $ characters, which guarantees
+that it will not change when it is expanded. Sometimes, however, you may have
+an expanded list that you know will be the same each time within a given
+message. For example:
+</para>
+<literallayout class="monospaced">
+domainlist special_domains = \
+           ${lookup{$sender_host_address}cdb{/some/file}}
+</literallayout>
+<para>
+This provides a list of domains that depends only on the sending host&#x2019;s IP
+address. If this domain list is referenced a number of times (for example,
+in several ACL lines, or in several routers) the result of the check is not
+cached by default, because Exim does not know that it is going to be the
+same list each time.
+</para>
+<para>
+By appending <literal>_cache</literal> to <literal>domainlist</literal> you can tell Exim to go ahead and
+cache the result anyway. For example:
+</para>
+<literallayout class="monospaced">
+domainlist_cache special_domains = ${lookup{...
+</literallayout>
+<para>
+If you do this, you should be absolutely sure that caching is going to do
+the right thing in all cases. When in doubt, leave it out.
+</para>
+</section>
+<section id="SECTdomainlist">
+<title>Domain lists</title>
+<para>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>patterns for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>domain list</secondary>
+</indexterm>
+Domain lists contain patterns that are to be matched against a mail domain.
+The following types of item may appear in domain lists:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>primary host name</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>host name</primary>
+<secondary>matched in domain list</secondary>
+</indexterm>
+<indexterm role="option">
+<primary><option>primary_hostname</option></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching primary host name</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>@ in a domain list</primary>
+</indexterm>
+If a pattern consists of a single @ character, it matches the local host name,
+as set by the <option>primary_hostname</option> option (or defaulted). This makes it
+possible to use the same configuration file on several different hosts that
+differ only in their names.
+</para>
+<para>
+The value for a match will be the primary host name.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>@[] in a domain list</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching local IP interfaces</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain literal</primary>
+</indexterm>
+If a pattern consists of the string <literal>@[]</literal> it matches an IP address enclosed
+in square brackets (as in an email address that contains a domain literal), but
+only if that IP address is recognized as local for email routing purposes. The
+<option>local_interfaces</option> and <option>extra_local_interfaces</option> options can be used to
+control which of a host&#x2019;s several IP addresses are treated as local.
+In today&#x2019;s Internet, the use of domain literals is controversial;
+see the <option>allow_domain_literals</option> main option.
+</para>
+<para>
+The value for a match will be the string <literal>@[]</literal>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>@mx_any</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>@mx_primary</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>@mx_secondary</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching MX pointers to local host</secondary>
+</indexterm>
+If a pattern consists of the string <literal>@mx_any</literal> it matches any domain that
+has an MX record pointing to the local host or to any host that is listed in
+<indexterm role="option">
+<primary><option>hosts_treat_as_local</option></primary>
+</indexterm>
+<option>hosts_treat_as_local</option>. The items <literal>@mx_primary</literal> and <literal>@mx_secondary</literal>
+are similar, except that the first matches only when a primary MX target is the
+local host, and the second only when no primary MX target is the local host,
+but a secondary MX target is. <quote>Primary</quote> means an MX record with the lowest
+preference value &ndash; there may of course be more than one of them.
+</para>
+<para>
+The MX lookup that takes place when matching a pattern of this type is
+performed with the resolver options for widening names turned off. Thus, for
+example, a single-component domain will <emphasis>not</emphasis> be expanded by adding the
+resolver&#x2019;s default domain. See the <option>qualify_single</option> and <option>search_parents</option>
+options of the <command>dnslookup</command> router for a discussion of domain widening.
+</para>
+<para>
+Sometimes you may want to ignore certain IP addresses when using one of these
+patterns. You can specify this by following the pattern with <literal>/ignore=</literal>&lt;<emphasis>ip
+list</emphasis>&gt;, where &lt;<emphasis>ip list</emphasis>&gt; is a list of IP addresses. These addresses are
+ignored when processing the pattern (compare the <option>ignore_target_hosts</option> option
+on a router). For example:
+</para>
+<literallayout class="monospaced">
+domains = @mx_any/ignore=127.0.0.1
+</literallayout>
+<para>
+This example matches any domain that has an MX record pointing to one of
+the local host&#x2019;s IP addresses other than 127.0.0.1.
+</para>
+<para>
+The list of IP addresses is in fact processed by the same code that processes
+host lists, so it may contain CIDR-coded network specifications and it may also
+contain negative items.
+</para>
+<para>
+Because the list of IP addresses is a sublist within a domain list, you have to
+be careful about delimiters if there is more than one address. Like any other
+list, the default delimiter can be changed. Thus, you might have:
+</para>
+<literallayout class="monospaced">
+domains = @mx_any/ignore=&lt;;127.0.0.1;0.0.0.0 : \
+          an.other.domain : ...
+</literallayout>
+<para>
+so that the sublist uses semicolons for delimiters. When IPv6 addresses are
+involved, it is easiest to change the delimiter for the main list as well:
+</para>
+<literallayout class="monospaced">
+domains = &lt;? @mx_any/ignore=&lt;;127.0.0.1;::1 ? \
+          an.other.domain ? ...
+</literallayout>
+<para>
+The value for a match will be the list element string (starting <literal>@mx_</literal>).
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in domain list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>asterisk in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching <quote>ends with</quote></secondary>
+</indexterm>
+If a pattern starts with an asterisk, the remaining characters of the pattern
+are compared with the terminating characters of the domain. The use of <quote>*</quote> in
+domain lists differs from its use in partial matching lookups. In a domain
+list, the character following the asterisk need not be a dot, whereas partial
+matching works only in terms of dot-separated components. For example, a domain
+list item such as <literal>*key.ex</literal> matches <emphasis>donkey.ex</emphasis> as well as
+<emphasis>cipher.key.ex</emphasis>.
+</para>
+<para>
+The value for a match will be the list element string (starting with the asterisk).
+Additionally, <varname>$0</varname> will be set to the matched string
+and <varname>$1</varname> to the variable portion which the asterisk matched.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>in domain list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching regular expression</secondary>
+</indexterm>
+If a pattern starts with a circumflex character, it is treated as a regular
+expression, and matched against the domain using a regular expression matching
+function. The circumflex is treated as part of the regular expression.
+Email domains are case-independent, so this regular expression match is by
+default case-independent, but you can make it case-dependent by starting it
+with <literal>(?-i)</literal>. References to descriptions of the syntax of regular expressions
+are given in chapter <xref linkend="CHAPregexp"/>.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: Because domain lists are expanded before being processed, you
+must escape any backslash and dollar characters in the regular expression, or
+use the special <literal>\N</literal> sequence (see chapter <xref linkend="CHAPexpand"/>) to specify that
+it is not to be expanded (unless you really do want to build a regular
+expression by expansion, of course).
+</para>
+<para>
+The value for a match will be the list element string (starting with the circumflex).
+Additionally, <varname>$0</varname> will be set to the string matching the regular expression,
+and <varname>$1</varname> (onwards) to any submatches identified by parentheses.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>in domain list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching by lookup</secondary>
+</indexterm>
+If a pattern starts with the name of a single-key lookup type followed by a
+semicolon (for example, <quote>dbm;</quote> or <quote>lsearch;</quote>), the remainder of the pattern
+must be a filename in a suitable format for the lookup type. For example, for
+<quote>cdb;</quote> it must be an absolute path:
+</para>
+<literallayout class="monospaced">
+domains = cdb;/etc/mail/local_domains.cdb
+</literallayout>
+<para>
+The appropriate type of lookup is done on the file using the domain name as the
+key. In most cases, the value resulting from the lookup is not used; Exim is interested
+only in whether or not the key is present in the file. However, when a lookup
+is used for the <option>domains</option> option on a router
+or a <option>domains</option> condition in an ACL statement, the value is preserved in the
+<varname>$domain_data</varname> variable and can be referred to in other router options or
+other statements in the same ACL.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+The value will be untainted.
+</para>
+<para revisionflag="changed">
+<emphasis role="bold">Note</emphasis>: If the data result of the lookup (as opposed to the key)
+is empty, then this empty value is stored in <varname>$domain_data</varname>.
+The option to return the key for the lookup, as the value,
+may be what is wanted.
+</para>
+</listitem>
+<listitem>
+<para>
+Any of the single-key lookup type names may be preceded by
+<literal>partial</literal>&lt;<emphasis>n</emphasis>&gt;<literal>-</literal>, where the &lt;<emphasis>n</emphasis>&gt; is optional, for example,
+</para>
+<literallayout class="monospaced">
+domains = partial-dbm;/partial/domains
+</literallayout>
+<para>
+This causes partial matching logic to be invoked; a description of how this
+works is given in section <xref linkend="SECTpartiallookup"/>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in lookup type</secondary>
+</indexterm>
+Any of the single-key lookup types may be followed by an asterisk. This causes
+a default lookup for a key consisting of a single asterisk to be done if the
+original lookup fails. This is not a useful feature when using a domain list to
+select particular domains (because any domain would match), but it might have
+value if the result of the lookup is being used via the <varname>$domain_data</varname>
+expansion variable.
+</para>
+</listitem>
+<listitem>
+<para>
+If the pattern starts with the name of a query-style lookup type followed by a
+semicolon (for example, <quote>nisplus;</quote> or <quote>ldap;</quote>), the remainder of the
+pattern must be an appropriate query for the lookup type, as described in
+chapter <xref linkend="CHAPfdlookup"/>. For example:
+</para>
+<literallayout class="monospaced">
+hold_domains = mysql;select domain from holdlist \
+  where domain = '${quote_mysql:$domain}';
+</literallayout>
+<para>
+In most cases, the value resulting from the lookup is not used (so for an SQL query, for
+example, it doesn&#x2019;t matter what field you select). Exim is interested only in
+whether or not the query succeeds. However, when a lookup is used for the
+<option>domains</option> option on a router, the value is preserved in the <varname>$domain_data</varname>
+variable and can be referred to in other options.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+The value will be untainted.
+</para>
+</listitem>
+<listitem>
+<para>
+If the pattern starts with the name of a lookup type
+of either kind (single-key or query-style) it may be
+followed by a comma and options,
+The options are lookup-type specific and consist of a comma-separated list.
+Each item starts with a tag and and equals "=" sign.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>matching literal domain name</secondary>
+</indexterm>
+If none of the above cases apply, a caseless textual comparison is made
+between the pattern and the domain.
+</para>
+<para>
+The value for a match will be the list element string.
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+Note that this is commonly untainted
+(depending on the way the list was created).
+Specifically, explicit text in the configuration file in not tainted.
+This is a useful way of obtaining an untainted equivalent to
+the domain, for later operations.
+</para>
+<para>
+However if the list (including one-element lists)
+is created by expanding a variable containing tainted data,
+it is tainted and so will the match value be.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Here is an example that uses several different kinds of pattern:
+</para>
+<literallayout class="monospaced">
+domainlist funny_domains = \
+  @ : \
+  lib.unseen.edu : \
+  *.foundation.fict.example : \
+  \N^[1-2]\d{3}\.fict\.example$\N : \
+  partial-dbm;/opt/data/penguin/book : \
+  nis;domains.byname : \
+  nisplus;[name=$domain,status=local],domains.org_dir
+</literallayout>
+<para>
+There are obvious processing trade-offs among the various matching modes. Using
+an asterisk is faster than a regular expression, and listing a few names
+explicitly probably is too. The use of a file or database lookup is expensive,
+but may be the only option if hundreds of names are required. Because the
+patterns are tested in order, it makes sense to put the most commonly matched
+patterns earlier.
+</para>
+</section>
+<section id="SECThostlist">
+<title>Host lists</title>
+<para>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>patterns in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>host list</secondary>
+</indexterm>
+Host lists are used to control what remote hosts are allowed to do. For
+example, some hosts may be allowed to use the local host as a relay, and some
+may be permitted to use the SMTP ETRN command. Hosts can be identified in
+two different ways, by name or by IP address. In a host list, some types of
+pattern are matched to a host name, and some are matched to an IP address.
+You need to be particularly careful with this when single-key lookups are
+involved, to ensure that the right value is being used as the key.
+</para>
+</section>
+<section id="SECID80">
+<title>Special host list patterns</title>
+<para>
+<indexterm role="concept">
+<primary>empty item in hosts list</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>empty string in</secondary>
+</indexterm>
+If a host list item is the empty string, it matches only when no remote host is
+involved. This is the case when a message is being received from a local
+process using SMTP on the standard input, that is, when a TCP/IP connection is
+not used.
+</para>
+<para>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in host list</secondary>
+</indexterm>
+The special pattern <quote>*</quote> in a host list matches any host or no host. Neither
+the IP address nor the name is actually inspected.
+</para>
+</section>
+<section id="SECThoslispatip">
+<title>Host list patterns that match by IP address</title>
+<para>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>matching IP addresses</secondary>
+</indexterm>
+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
+<literal>::ffff:</literal>&lt;<emphasis>v4address</emphasis>&gt;. When such an address is tested against a host
+list, it is converted into a traditional IPv4 address first. (Not all operating
+systems accept IPv4 calls on IPv6 sockets, as there have been some security
+concerns.)
+</para>
+<para>
+The following types of pattern in a host list check the remote host by
+inspecting its IP address:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If the pattern is a plain domain name (not a regular expression, not starting
+with *, not a lookup of any kind), Exim calls the operating system function
+to find the associated IP address(es). Exim uses the newer
+<function>getipnodebyname()</function> function when available, otherwise <function>gethostbyname()</function>.
+This typically causes a forward DNS lookup of the name. The result is compared
+with the IP address of the subject host.
+</para>
+<para>
+If there is a temporary problem (such as a DNS timeout) with the host name
+lookup, a temporary error occurs. For example, if the list is being used in an
+ACL condition, the ACL gives a <quote>defer</quote> response, usually leading to a
+temporary SMTP error code. If no IP address can be found for the host name,
+what happens is described in section <xref linkend="SECTbehipnot"/> below.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>@ in a host list</primary>
+</indexterm>
+If the pattern is <quote>@</quote>, the primary host name is substituted and used as a
+domain name, as just described.
+</para>
+</listitem>
+<listitem>
+<para>
+If the pattern is an IP address, it is matched against the IP address of the
+subject host. IPv4 addresses are given in the normal <quote>dotted-quad</quote> notation.
+IPv6 addresses can be given in colon-separated format, but the colons have to
+be doubled so as not to be taken as item separators when the default list
+separator is used. IPv6 addresses are recognized even when Exim is compiled
+without IPv6 support. This means that if they appear in a host list on an
+IPv4-only host, Exim will not treat them as host names. They are just addresses
+that can never match a client host.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>@[] in a host list</primary>
+</indexterm>
+If the pattern is <quote>@[]</quote>, it matches the IP address of any IP interface on
+the local host. For example, if the local host is an IPv4 host with one
+interface address 10.45.23.56, these two ACL statements have the same effect:
+</para>
+<literallayout class="monospaced">
+accept hosts = 127.0.0.1 : 10.45.23.56
+accept hosts = @[]
+</literallayout>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>CIDR notation</primary>
+</indexterm>
+If the pattern is an IP address followed by a slash and a mask length, for
+example
+</para>
+<literallayout class="monospaced">
+10.11.42.0/24
+</literallayout>
+<para>
+, it is matched against the IP address of the subject
+host under the given mask. This allows an entire network of hosts to be
+included (or excluded) by a single item. The mask uses CIDR notation; it
+specifies the number of address bits that must match, starting from the most
+significant end of the address.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: The mask is <emphasis>not</emphasis> a count of addresses, nor is it the high number
+of a range of addresses. It is the number of bits in the network portion of the
+address. The above example specifies a 24-bit netmask, so it matches all 256
+addresses in the 10.11.42.0 network. An item such as
+</para>
+<literallayout class="monospaced">
+192.168.23.236/31
+</literallayout>
+<para>
+matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of
+32 for an IPv4 address is the same as no mask at all; just a single address
+matches.
+</para>
+<para>
+Here is another example which shows an IPv4 and an IPv6 network:
+</para>
+<literallayout class="monospaced">
+recipient_unqualified_hosts = 192.168.0.0/16: \
+                              3ffe::ffff::836f::::/48
+</literallayout>
+<para>
+The doubling of list separator characters applies only when these items
+appear inline in a host list. It is not required when indirecting via a file.
+For example:
+</para>
+<literallayout class="monospaced">
+recipient_unqualified_hosts = /opt/exim/unqualnets
+</literallayout>
+<para>
+could make use of a file containing
+</para>
+<literallayout class="monospaced">
+172.16.0.0/12
+3ffe:ffff:836f::/48
+</literallayout>
+<para>
+to have exactly the same effect as the previous example. When listing IPv6
+addresses inline, it is usually more convenient to use the facility for
+changing separator characters. This list contains the same two networks:
+</para>
+<literallayout class="monospaced">
+recipient_unqualified_hosts = &lt;; 172.16.0.0/12; \
+                                 3ffe:ffff:836f::/48
+</literallayout>
+<para>
+The separator is changed to semicolon by the leading <quote>&lt;;</quote> at the start of the
+list.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECThoslispatsikey">
+<title>Host list patterns for single-key lookups by host address</title>
+<para>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>lookup of IP address</secondary>
+</indexterm>
+When a host is to be identified by a single-key lookup of its complete IP
+address, the pattern takes this form:
+</para>
+<literallayout>
+<literal>net-&lt;</literal><emphasis>single-key-search-type</emphasis><literal>&gt;;&lt;</literal><emphasis>search-data</emphasis><literal>&gt;</literal>
+</literallayout>
+<para>
+For example:
+</para>
+<literallayout class="monospaced">
+hosts_lookup = net-cdb;/hosts-by-ip.db
+</literallayout>
+<para>
+The text form of the IP address of the subject host is used as the lookup key.
+IPv6 addresses are converted to an unabbreviated form, using lower case
+letters, with dots as separators because colon is the key terminator in
+<command>lsearch</command> files. [Colons can in fact be used in keys in <command>lsearch</command> files by
+quoting the keys, but this is a facility that was added later.] The data
+returned by the lookup is not used.
+</para>
+<para>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>masking</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>masked IP address</secondary>
+</indexterm>
+Single-key lookups can also be performed using masked IP addresses, using
+patterns of this form:
+</para>
+<literallayout>
+<literal>net&lt;</literal><emphasis>number</emphasis><literal>&gt;-&lt;</literal><emphasis>single-key-search-type</emphasis><literal>&gt;;&lt;</literal><emphasis>search-data</emphasis><literal>&gt;</literal>
+</literallayout>
+<para>
+For example:
+</para>
+<literallayout class="monospaced">
+net24-dbm;/networks.db
+</literallayout>
+<para>
+The IP address of the subject host is masked using &lt;<emphasis>number</emphasis>&gt; as the mask
+length. A textual string is constructed from the masked value, followed by the
+mask, and this is used as the lookup key. For example, if the host&#x2019;s IP address
+is 192.168.34.6, the key that is looked up for the above example is
+<quote>192.168.34.0/24</quote>.
+</para>
+<para>
+When an IPv6 address is converted to a string, dots are normally used instead
+of colons, so that keys in <command>lsearch</command> files need not contain colons (which
+terminate <command>lsearch</command> keys). This was implemented some time before the ability
+to quote keys was made available in <command>lsearch</command> files. However, the more
+recently implemented <command>iplsearch</command> files do require colons in IPv6 keys
+(notated using the quoting facility) so as to distinguish them from IPv4 keys.
+For this reason, when the lookup type is <command>iplsearch</command>, IPv6 addresses are
+converted using colons and not dots.
+In all cases except IPv4-mapped IPv6, full, unabbreviated IPv6
+addresses are always used.
+The latter are converted to IPv4 addresses, in dotted-quad form.
+</para>
+<para>
+Ideally, it would be nice to tidy up this anomalous situation by changing to
+colons in all cases, given that quoting is now available for <command>lsearch</command>.
+However, this would be an incompatible change that might break some existing
+configurations.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: Specifying <option>net32-</option> (for an IPv4 address) or <option>net128-</option> (for an
+IPv6 address) is not the same as specifying just <option>net-</option> without a number. In
+the former case the key strings include the mask value, whereas in the latter
+case the IP address is used on its own.
+</para>
+</section>
+<section id="SECThoslispatnam">
+<title>Host list patterns that match by host name</title>
+<para>
+<indexterm role="concept">
+<primary>host</primary>
+<secondary>lookup failures</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>unknown host name</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>matching host name</secondary>
+</indexterm>
+There are several types of pattern that require Exim to know the name of the
+remote host. These are either wildcard patterns or lookups by name. (If a
+complete hostname is given without any wildcarding, it is used to find an IP
+address to match against, as described in section <xref linkend="SECThoslispatip"/>
+above.)
+</para>
+<para>
+If the remote host name is not already known when Exim encounters one of these
+patterns, it has to be found from the IP address.
+Although many sites on the Internet are conscientious about maintaining reverse
+DNS data for their hosts, there are also many that do not do this.
+Consequently, a name cannot always be found, and this may lead to unwanted
+effects. Take care when configuring host lists with wildcarded name patterns.
+Consider what will happen if a name cannot be found.
+</para>
+<para>
+Because of the problems of determining host names from IP addresses, matching
+against host names is not as common as matching against IP addresses.
+</para>
+<para>
+By default, in order to find a host name, Exim first does a reverse DNS lookup;
+if no name is found in the DNS, the system function (<function>gethostbyaddr()</function> or
+<function>getipnodebyaddr()</function> if available) is tried. The order in which these lookups
+are done can be changed by setting the <option>host_lookup_order</option> option. For
+security, once Exim has found one or more names, it looks up the IP addresses
+for these names and compares them with the IP address that it started with.
+Only those names whose IP addresses match are accepted. Any other names are
+discarded. If no names are left, Exim behaves as if the host name cannot be
+found. In the most common case there is only one name and one IP address.
+</para>
+<para>
+There are some options that control what happens if a host name cannot be
+found. These are described in section <xref linkend="SECTbehipnot"/> below.
+</para>
+<para>
+<indexterm role="concept">
+<primary>host</primary>
+<secondary>alias for</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>alias for host</primary>
+</indexterm>
+As a result of aliasing, hosts may have more than one name. When processing any
+of the following types of pattern, all the host&#x2019;s names are checked:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in host list</secondary>
+</indexterm>
+If a pattern starts with <quote>*</quote> the remainder of the item must match the end of
+the host name. For example, <literal>*.b.c</literal> matches all hosts whose names end in
+<emphasis>.b.c</emphasis>. This special simple form is provided because this is a very common
+requirement. Other kinds of wildcarding require the use of a regular
+expression.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>in host list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>regular expression in</secondary>
+</indexterm>
+If the item starts with <quote>^</quote> it is taken to be a regular expression which is
+matched against the host name. Host names are case-independent, so this regular
+expression match is by default case-independent, but you can make it
+case-dependent by starting it with <literal>(?-i)</literal>. References to descriptions of the
+syntax of regular expressions are given in chapter <xref linkend="CHAPregexp"/>. For
+example,
+</para>
+<literallayout class="monospaced">
+^(a|b)\.c\.d$
+</literallayout>
+<para>
+is a regular expression that matches either of the two hosts <emphasis>a.c.d</emphasis> or
+<emphasis>b.c.d</emphasis>. When a regular expression is used in a host list, you must take care
+that backslash and dollar characters are not misinterpreted as part of the
+string expansion. The simplest way to do this is to use <literal>\N</literal> to mark that
+part of the string as non-expandable. For example:
+</para>
+<literallayout class="monospaced">
+sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
+</literallayout>
+<para>
+<emphasis role="bold">Warning</emphasis>: If you want to match a complete host name, you must include the
+<literal>$</literal> terminating metacharacter in the regular expression, as in the above
+example. Without it, a match at the start of the host name is all that is
+required.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECTbehipnot">
+<title>Behaviour when an IP address or name cannot be found</title>
+<para>
+<indexterm role="concept">
+<primary>host</primary>
+<secondary>lookup failures, permanent</secondary>
+</indexterm>
+While processing a host list, Exim may need to look up an IP address from a
+name (see section <xref linkend="SECThoslispatip"/>), or it may need to look up a host name
+from an IP address (see section <xref linkend="SECThoslispatnam"/>). In either case, the
+behaviour when it fails to find the information it is seeking is the same.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: This section applies to permanent lookup failures. It does <emphasis>not</emphasis>
+apply to temporary DNS errors, whose handling is described in the next section.
+</para>
+<para>
+<indexterm role="concept">
+<primary><literal>+include_unknown</literal></primary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>+ignore_unknown</literal></primary>
+</indexterm>
+Exim parses a host list from left to right. If it encounters a permanent
+lookup failure in any item in the host list before it has found a match,
+Exim treats it as a failure and the default behavior is as if the host
+does not match the list. This may not always be what you want to happen.
+To change Exim&#x2019;s behaviour, the special items <literal>+include_unknown</literal> or
+<literal>+ignore_unknown</literal> may appear in the list (at top level &ndash; they are
+not recognized in an indirected file).
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If any item that follows <literal>+include_unknown</literal> requires information that
+cannot found, Exim behaves as if the host does match the list. For example,
+</para>
+<literallayout class="monospaced">
+host_reject_connection = +include_unknown:*.enemy.ex
+</literallayout>
+<para>
+rejects connections from any host whose name matches <literal>*.enemy.ex</literal>, and also
+any hosts whose name it cannot find.
+</para>
+</listitem>
+<listitem>
+<para>
+If any item that follows <literal>+ignore_unknown</literal> requires information that cannot
+be found, Exim ignores that item and proceeds to the rest of the list. For
+example:
+</para>
+<literallayout class="monospaced">
+accept hosts = +ignore_unknown : friend.example : \
+               192.168.4.5
+</literallayout>
+<para>
+accepts from any host whose name is <emphasis>friend.example</emphasis> and from 192.168.4.5,
+whether or not its host name can be found. Without <literal>+ignore_unknown</literal>, if no
+name can be found for 192.168.4.5, it is rejected.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Both <literal>+include_unknown</literal> and <literal>+ignore_unknown</literal> may appear in the same
+list. The effect of each one lasts until the next, or until the end of the
+list.
+</para>
+</section>
+<section id="SECTmixwilhos">
+<title>Mixing wildcarded host names and addresses in host lists</title>
+<para>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>mixing names and addresses in</secondary>
+</indexterm>
+</para>
+<para>
+This section explains the host/ip processing logic with the same concepts
+as the previous section, but specifically addresses what happens when a
+wildcarded hostname is one of the items in the hostlist.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+If you have name lookups or wildcarded host names and
+IP addresses in the same host list, you should normally put the IP
+addresses first. For example, in an ACL you could have:
+</para>
+<literallayout class="monospaced">
+accept hosts = 10.9.8.7 : *.friend.example
+</literallayout>
+<para>
+The reason you normally would order it this way lies in the
+left-to-right way that Exim processes lists.  It can test IP addresses
+without doing any DNS lookups, but when it reaches an item that requires
+a host name, it fails if it cannot find a host name to compare with the
+pattern. If the above list is given in the opposite order, the
+<option>accept</option> statement fails for a host whose name cannot be found, even
+if its IP address is 10.9.8.7.
+</para>
+</listitem>
+<listitem>
+<para>
+If you really do want to do the name check first, and still recognize the IP
+address, you can rewrite the ACL like this:
+</para>
+<literallayout class="monospaced">
+accept hosts = *.friend.example
+accept hosts = 10.9.8.7
+</literallayout>
+<para>
+If the first <option>accept</option> fails, Exim goes on to try the second one. See chapter
+<xref linkend="CHAPACL"/> for details of ACLs. Alternatively, you can use
+<literal>+ignore_unknown</literal>, which was discussed in depth in the first example in
+this section.
+</para>
+</listitem>
+</itemizedlist>
+</section>
+<section id="SECTtemdnserr">
+<title>Temporary DNS errors when looking up host information</title>
+<para>
+<indexterm role="concept">
+<primary>host</primary>
+<secondary>lookup failures, temporary</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>+include_defer</literal></primary>
+</indexterm>
+<indexterm role="concept">
+<primary><literal>+ignore_defer</literal></primary>
+</indexterm>
+A temporary DNS lookup failure normally causes a defer action (except when
+<option>dns_again_means_nonexist</option> converts it into a permanent error). However,
+host lists can include <literal>+ignore_defer</literal> and <literal>+include_defer</literal>, analogous to
+<literal>+ignore_unknown</literal> and <literal>+include_unknown</literal>, as described in the previous
+section. These options should be used with care, probably only in non-critical
+host lists such as whitelists.
+</para>
+</section>
+<section id="SECThoslispatnamsk">
+<title>Host list patterns for single-key lookups by host name</title>
+<para>
+<indexterm role="concept">
+<primary>unknown host name</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>host list</primary>
+<secondary>matching host name</secondary>
+</indexterm>
+If a pattern is of the form
+</para>
+<literallayout>
+&lt;<emphasis>single-key-search-type</emphasis>&gt;;&lt;<emphasis>search-data</emphasis>&gt;
+</literallayout>
+<para>
+for example
+</para>
+<literallayout class="monospaced">
+dbm;/host/accept/list
+</literallayout>
+<para>
+a single-key lookup is performed, using the host name as its key. If the
+lookup succeeds, the host matches the item. The actual data that is looked up
+is not used.
+</para>
+<para>
+<emphasis role="bold">Reminder</emphasis>: With this kind of pattern, you must have host <emphasis>names</emphasis> as
+keys in the file, not IP addresses. If you want to do lookups based on IP
+addresses, you must precede the search type with <quote>net-</quote> (see section
+<xref linkend="SECThoslispatsikey"/>). There is, however, no reason why you could not use
+two items in the same list, one doing an address lookup and one doing a name
+lookup, both using the same file.
+</para>
+</section>
+<section id="SECID81">
+<title>Host list patterns for query-style lookups</title>
+<para>
+If a pattern is of the form
+</para>
+<literallayout>
+&lt;<emphasis>query-style-search-type</emphasis>&gt;;&lt;<emphasis>query</emphasis>&gt;
+</literallayout>
+<para>
+the query is obeyed, and if it succeeds, the host matches the item. The actual
+data that is looked up is not used. The variables <varname>$sender_host_address</varname> and
+<varname>$sender_host_name</varname> can be used in the query. For example:
+</para>
+<literallayout class="monospaced">
+hosts_lookup = pgsql;\
+  select ip from hostlist where ip='$sender_host_address'
+</literallayout>
+<para>
+The value of <varname>$sender_host_address</varname> for an IPv6 address contains colons. You
+can use the <option>sg</option> expansion item to change this if you need to. If you want to
+use masked IP addresses in database queries, you can use the <option>mask</option> expansion
+operator.
+</para>
+<para>
+If the query contains a reference to <varname>$sender_host_name</varname>, Exim automatically
+looks up the host name if it has not already done so. (See section
+<xref linkend="SECThoslispatnam"/> for comments on finding host names.)
+</para>
+<para>
+Historical note: prior to release 4.30, Exim would always attempt to find a
+host name before running the query, unless the search type was preceded by
+<literal>net-</literal>. This is no longer the case. For backwards compatibility, <literal>net-</literal> is
+still recognized for query-style lookups, but its presence or absence has no
+effect. (Of course, for single-key lookups, <literal>net-</literal> <emphasis>is</emphasis> important.
+See section <xref linkend="SECThoslispatsikey"/>.)
+</para>
+</section>
+<section id="SECTaddresslist">
+<title>Address lists</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>address list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>empty item</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>patterns</secondary>
+</indexterm>
+Address lists contain patterns that are matched against mail addresses. There
+is one special case to be considered: the sender address of a bounce message is
+always empty. You can test for this by providing an empty item in an address
+list. For example, you can set up a router to process bounce messages by
+using this option setting:
+</para>
+<literallayout class="monospaced">
+senders = :
+</literallayout>
+<para>
+The presence of the colon creates an empty item. If you do not provide any
+data, the list is empty and matches nothing. The empty sender can also be
+detected by a regular expression that matches an empty string,
+and by a query-style lookup that succeeds when <varname>$sender_address</varname> is empty.
+</para>
+<para>
+Non-empty items in an address list can be straightforward email addresses. For
+example:
+</para>
+<literallayout class="monospaced">
+senders = jbc@??? : hs@???
+</literallayout>
+<para>
+A certain amount of wildcarding is permitted. If a pattern contains an @
+character, but is not a regular expression and does not begin with a
+semicolon-terminated lookup type (described below), the local part of the
+subject address is compared with the local part of the pattern, which may start
+with an asterisk. If the local parts match, the domain is checked in exactly
+the same way as for a pattern in a domain list. For example, the domain can be
+wildcarded, refer to a named list, or be a lookup:
+</para>
+<literallayout class="monospaced">
+deny senders = *@*.spamming.site:\
+               *@+hostile_domains:\
+               bozo@partial-lsearch;/list/of/dodgy/sites:\
+               *@dbm;/bad/domains.db
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary>local part</primary>
+<secondary>starting with !</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>local part starting with !</secondary>
+</indexterm>
+If a local part that begins with an exclamation mark is required, it has to be
+specified using a regular expression, because otherwise the exclamation mark is
+treated as a sign of negation, as is standard in lists.
+</para>
+<para>
+If a non-empty pattern that is not a regular expression or a lookup does not
+contain an @ character, it is matched against the domain part of the subject
+address. The only two formats that are recognized this way are a literal
+domain, or a domain pattern that starts with *. In both these cases, the effect
+is the same as if <literal>*@</literal> preceded the pattern. For example:
+</para>
+<literallayout class="monospaced">
+deny senders = enemy.domain : *.enemy.domain
+</literallayout>
+<para>
+The following kinds of more complicated address list pattern can match any
+address, including the empty address that is characteristic of bounce message
+senders:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>in address list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>regular expression in</secondary>
+</indexterm>
+If (after expansion) a pattern starts with <quote>^</quote>, a regular expression match is
+done against the complete address, with the pattern as the regular expression.
+You must take care that backslash and dollar characters are not misinterpreted
+as part of the string expansion. The simplest way to do this is to use <literal>\N</literal>
+to mark that part of the string as non-expandable. For example:
+</para>
+<literallayout class="monospaced">
+deny senders = \N^.*this.*@example\.com$\N : \
+               \N^\d{8}.+@???$\N : ...
+</literallayout>
+<para>
+The <literal>\N</literal> sequences are removed by the expansion, so these items do indeed
+start with <quote>^</quote> by the time they are being interpreted as address patterns.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>lookup for complete address</secondary>
+</indexterm>
+Complete addresses can be looked up by using a pattern that starts with a
+lookup type terminated by a semicolon, followed by the data for the lookup. For
+example:
+</para>
+<literallayout class="monospaced">
+deny senders = cdb;/etc/blocked.senders : \
+  mysql;select address from blocked where \
+  address='${quote_mysql:$sender_address}'
+</literallayout>
+<para>
+Both query-style and single-key lookup types can be used. For a single-key
+lookup type, Exim uses the complete address as the key. However, empty keys are
+not supported for single-key lookups, so a match against the empty address
+always fails. This restriction does not apply to query-style lookups.
+</para>
+<para>
+Partial matching for single-key lookups (section <xref linkend="SECTpartiallookup"/>)
+cannot be used, and is ignored if specified, with an entry being written to the
+panic log.
+<indexterm role="concept">
+<primary>*@ with single-key lookup</primary>
+</indexterm>
+However, you can configure lookup defaults, as described in section
+<xref linkend="SECTdefaultvaluelookups"/>, but this is useful only for the <quote>*@</quote> type of
+default. For example, with this lookup:
+</para>
+<literallayout class="monospaced">
+accept senders = lsearch*@;/some/file
+</literallayout>
+<para>
+the file could contains lines like this:
+</para>
+<literallayout class="monospaced">
+user1@???
+*@domain2.example
+</literallayout>
+<para>
+and for the sender address <emphasis>nimrod@???</emphasis>, the sequence of keys
+that are tried is:
+</para>
+<literallayout class="monospaced">
+nimrod@???
+*@jaeger.example
+*
+</literallayout>
+<para>
+<emphasis role="bold">Warning 1</emphasis>: Do not include a line keyed by <quote>*</quote> in the file, because that
+would mean that every address matches, thus rendering the test useless.
+</para>
+<para>
+<emphasis role="bold">Warning 2</emphasis>: Do not confuse these two kinds of item:
+</para>
+<literallayout class="monospaced">
+deny recipients = dbm*@;/some/file
+deny recipients = *@dbm;/some/file
+</literallayout>
+<para>
+The first does a whole address lookup, with defaulting, as just described,
+because it starts with a lookup type. The second matches the local part and
+domain independently, as described in a bullet point below.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+The following kinds of address list pattern can match only non-empty addresses.
+If the subject address is empty, a match against any of these pattern types
+always fails.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>@@ with single-key lookup</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>@@ lookup type</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>split local part and domain</secondary>
+</indexterm>
+If a pattern starts with <quote>@@</quote> followed by a single-key lookup item
+(for example, <literal>@@lsearch;/some/file</literal>), the address that is being checked is
+split into a local part and a domain. The domain is looked up in the file. If
+it is not found, there is no match. If it is found, the data that is looked up
+from the file is treated as a colon-separated list of local part patterns, each
+of which is matched against the subject local part in turn.
+</para>
+<para>
+<indexterm role="concept">
+<primary>asterisk</primary>
+<secondary>in address list</secondary>
+</indexterm>
+The lookup may be a partial one, and/or one involving a search for a default
+keyed by <quote>*</quote> (see section <xref linkend="SECTdefaultvaluelookups"/>). The local part
+patterns that are looked up can be regular expressions or begin with <quote>*</quote>, or
+even be further lookups. They may also be independently negated. For example,
+with
+</para>
+<literallayout class="monospaced">
+deny senders = @@dbm;/etc/reject-by-domain
+</literallayout>
+<para>
+the data from which the DBM file is built could contain lines like
+</para>
+<literallayout class="monospaced">
+baddomain.com:  !postmaster : *
+</literallayout>
+<para>
+to reject all senders except <option>postmaster</option> from that domain.
+</para>
+<para>
+<indexterm role="concept">
+<primary>local part</primary>
+<secondary>starting with !</secondary>
+</indexterm>
+If a local part that actually begins with an exclamation mark is required, it
+has to be specified using a regular expression. In <command>lsearch</command> files, an entry
+may be split over several lines by indenting the second and subsequent lines,
+but the separating colon must still be included at line breaks. White space
+surrounding the colons is ignored. For example:
+</para>
+<literallayout class="monospaced">
+aol.com:  spammer1 : spammer2 : ^[0-9]+$ :
+  spammer3 : spammer4
+</literallayout>
+<para>
+As in all colon-separated lists in Exim, a colon can be included in an item by
+doubling.
+</para>
+<para>
+If the last item in the list starts with a right angle-bracket, the remainder
+of the item is taken as a new key to look up in order to obtain a continuation
+list of local parts. The new key can be any sequence of characters. Thus one
+might have entries like
+</para>
+<literallayout class="monospaced">
+aol.com: spammer1 : spammer 2 : &gt;*
+xyz.com: spammer3 : &gt;*
+*:       ^\d{8}$
+</literallayout>
+<para>
+in a file that was searched with <option>@@dbm*</option>, to specify a match for 8-digit
+local parts for all domains, in addition to the specific local parts listed for
+each domain. Of course, using this feature costs another lookup each time a
+chain is followed, but the effort needed to maintain the data is reduced.
+</para>
+<para>
+<indexterm role="concept">
+<primary>loop</primary>
+<secondary>in lookups</secondary>
+</indexterm>
+It is possible to construct loops using this facility, and in order to catch
+them, the chains may be no more than fifty items long.
+</para>
+</listitem>
+<listitem>
+<para>
+The @@&lt;<emphasis>lookup</emphasis>&gt; style of item can also be used with a query-style
+lookup, but in this case, the chaining facility is not available. The lookup
+can only return a single list of local parts.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+<emphasis role="bold">Warning</emphasis>: There is an important difference between the address list items
+in these two examples:
+</para>
+<literallayout class="monospaced">
+senders = +my_list
+senders = *@+my_list
+</literallayout>
+<para>
+In the first one, <literal>my_list</literal> is a named address list, whereas in the second
+example it is a named domain list.
+</para>
+</section>
+<section id="SECTcasletadd">
+<title>Case of letters in address lists</title>
+<para>
+<indexterm role="concept">
+<primary>case of local parts</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>case forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>case forcing in address lists</primary>
+</indexterm>
+Domains in email addresses are always handled caselessly, but for local parts
+case may be significant on some systems (see <option>caseful_local_part</option> for how
+Exim deals with this when routing addresses). However, RFC 2505 (<emphasis>Anti-Spam
+Recommendations for SMTP MTAs</emphasis>) suggests that matching of addresses to
+blocking lists should be done in a case-independent manner. Since most address
+lists in Exim are used for this kind of control, Exim attempts to do this by
+default.
+</para>
+<para>
+The domain portion of an address is always lowercased before matching it to an
+address list. The local part is lowercased by default, and any string
+comparisons that take place are done caselessly. This means that the data in
+the address list itself, in files included as plain filenames, and in any file
+that is looked up using the <quote>@@</quote> mechanism, can be in any case. However, the
+keys in files that are looked up by a search type other than <command>lsearch</command> (which
+works caselessly) must be in lower case, because these lookups are not
+case-independent.
+</para>
+<para>
+<indexterm role="concept">
+<primary><literal>+caseful</literal></primary>
+</indexterm>
+To allow for the possibility of caseful address list matching, if an item in
+an address list is the string <quote>+caseful</quote>, the original case of the local
+part is restored for any comparisons that follow, and string comparisons are no
+longer case-independent. This does not affect the domain, which remains in
+lower case. However, although independent matches on the domain alone are still
+performed caselessly, regular expressions that match against an entire address
+become case-sensitive after <quote>+caseful</quote> has been seen.
+</para>
+</section>
+<section id="SECTlocparlis">
+<title>Local part lists</title>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>local part list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>local part</primary>
+<secondary>list</secondary>
+</indexterm>
+These behave in the same way as domain and host lists, with the following
+changes:
+</para>
+<para>
+Case-sensitivity in local part lists is handled in the same way as for address
+lists, as just described. The <quote>+caseful</quote> item can be used if required. In a
+setting of the <option>local_parts</option> option in a router with <option>caseful_local_part</option>
+set false, the subject is lowercased and the matching is initially
+case-insensitive. In this case, <quote>+caseful</quote> will restore case-sensitive
+matching in the local part list, but not elsewhere in the router. If
+<option>caseful_local_part</option> is set true in a router, matching in the <option>local_parts</option>
+option is case-sensitive from the start.
+</para>
+<para>
+If a local part list is indirected to a file (see section <xref linkend="SECTfilnamlis"/>),
+comments are handled in the same way as address lists &ndash; they are recognized
+only if the # is preceded by white space or the start of the line.
+Otherwise, local part lists are matched in the same way as domain lists, except
+that the special items that refer to the local host (<literal>@</literal>, <literal>@[]</literal>,
+<literal>@mx_any</literal>, <literal>@mx_primary</literal>, and <literal>@mx_secondary</literal>) are not recognized.
+Refer to section <xref linkend="SECTdomainlist"/> for details of the other available item
+types.
+<indexterm role="concept" startref="IIDdohoadli" class="endofrange"/>
+</para>
+</section>
+</chapter>
+
+<chapter id="CHAPexpand">
+<title>String expansions</title>
+<para>
+<indexterm role="concept" id="IIDstrexp" class="startofrange">
+<primary>expansion</primary>
+<secondary>of strings</secondary>
+</indexterm>
+Many strings in Exim&#x2019;s runtime configuration are expanded before use. Some of
+them are expanded every time they are used; others are expanded only once.
+</para>
+<para>
+When a string is being expanded it is copied verbatim from left to right except
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string concatenation</secondary>
+</indexterm>
+when a dollar or backslash character is encountered. A dollar specifies the
+start of a portion of the string that is interpreted and replaced as described
+below in section <xref linkend="SECTexpansionitems"/> onwards. Backslash is used as an
+escape character, as described in the following section.
+</para>
+<para>
+Whether a string is expanded depends upon the context.  Usually this is solely
+dependent upon the option for which a value is sought; in this documentation,
+options for which string expansion is performed are marked with &dagger; after
+the data type.  ACL rules always expand strings.  A couple of expansion
+conditions do not expand some of the brace-delimited branches, for security
+reasons,
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>definition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>tainted data</secondary>
+</indexterm>
+and expansion of data deriving from the sender (<quote>tainted data</quote>)
+</para>
+<para revisionflag="changed">
+is not permitted (including acessing a file using a tainted name).
+The main config option <option>allow_insecure_tainted_data</option> can be used as
+mitigation during uprades to more secure configurations.
+</para>
+<para revisionflag="changed">
+Common ways of obtaining untainted equivalents of variables with
+tainted values
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>de-tainting</secondary>
+</indexterm>
+come down to using the tainted value as a lookup key in a trusted database.
+This database could be the filesystem structure,
+or the password file,
+or accessed via a DBMS.
+Specific methods are indexed under <quote>de-tainting</quote>.
+</para>
+<section id="SECTlittext">
+<title>Literal text in expanded strings</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>including literal text</secondary>
+</indexterm>
+An uninterpreted dollar can be included in an expanded string by putting a
+backslash in front of it. A backslash can be used to prevent any special
+character being treated specially in an expansion, including backslash itself.
+If the string appears in quotes in the configuration file, two backslashes are
+required because the quotes themselves cause interpretation of backslashes when
+the string is read in (see section <xref linkend="SECTstrings"/>).
+</para>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>non-expandable substrings</secondary>
+</indexterm>
+A portion of the string can specified as non-expandable by placing it between
+two occurrences of <literal>\N</literal>. This is particularly useful for protecting regular
+expressions, which often contain backslashes and dollar signs. For example:
+</para>
+<literallayout class="monospaced">
+deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
+</literallayout>
+<para>
+On encountering the first <literal>\N</literal>, the expander copies subsequent characters
+without interpretation until it reaches the next <literal>\N</literal> or the end of the
+string.
+</para>
+</section>
+<section id="SECID82">
+<title>Character escape sequences in expanded strings</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>escape sequences</secondary>
+</indexterm>
+A backslash followed by one of the letters <quote>n</quote>, <quote>r</quote>, or <quote>t</quote> in an
+expanded string is recognized as an escape sequence for the character newline,
+carriage return, or tab, respectively. A backslash followed by up to three
+octal digits is recognized as an octal encoding for a single character, and a
+backslash followed by <quote>x</quote> and up to two hexadecimal digits is a hexadecimal
+encoding.
+</para>
+<para>
+These escape sequences are also recognized in quoted strings when they are read
+in. Their interpretation in expansions as well is useful for unquoted strings,
+and for other cases such as looked-up strings that are then expanded.
+</para>
+</section>
+<section id="SECID83">
+<title>Testing string expansions</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>testing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>testing</primary>
+<secondary>string expansion</secondary>
+</indexterm>
+<indexterm role="option">
+<primary><option>-be</option></primary>
+</indexterm>
+Many expansions can be tested by calling Exim with the <option>-be</option> option. This
+takes the command arguments, or lines from the standard input if there are no
+arguments, runs them through the string expansion code, and writes the results
+to the standard output. Variables based on configuration values are set up, but
+since no message is being processed, variables such as <varname>$local_part</varname> have no
+value. Nevertheless the <option>-be</option> option can be useful for checking out file and
+database lookups, and the use of expansion operators such as <option>sg</option>, <option>substr</option>
+and <option>nhash</option>.
+</para>
+<para>
+Exim gives up its root privilege when it is called with the <option>-be</option> option, and
+instead runs under the uid and gid it was called with, to prevent users from
+using <option>-be</option> for reading files to which they do not have access.
+</para>
+<para>
+<indexterm role="option">
+<primary><option>-bem</option></primary>
+</indexterm>
+If you want to test expansions that include variables whose values are taken
+from a message, there are two other options that can be used. The <option>-bem</option>
+option is like <option>-be</option> except that it is followed by a filename. The file is
+read as a message before doing the test expansions. For example:
+</para>
+<literallayout class="monospaced">
+exim -bem /tmp/test.message '$h_subject:'
+</literallayout>
+<para>
+The <option>-Mset</option> option is used in conjunction with <option>-be</option> and is followed by an
+Exim message identifier. For example:
+</para>
+<literallayout class="monospaced">
+exim -be -Mset 1GrA8W-0004WS-LQ '$recipients'
+</literallayout>
+<para>
+This loads the message from Exim&#x2019;s spool before doing the test expansions, and
+is therefore restricted to admin users.
+</para>
+</section>
+<section id="SECTforexpfai">
+<title>Forced expansion failure</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>forced failure</secondary>
+</indexterm>
+A number of expansions that are described in the following section have
+alternative <quote>true</quote> and <quote>false</quote> substrings, enclosed in brace characters
+(which are sometimes called <quote>curly brackets</quote>). Which of the two strings is
+used depends on some condition that is evaluated as part of the expansion. If,
+instead of a <quote>false</quote> substring, the word <quote>fail</quote> is used (not in braces),
+the entire string expansion fails in a way that can be detected by the code
+that requested the expansion. This is called <quote>forced expansion failure</quote>, and
+its consequences depend on the circumstances. In some cases it is no different
+from any other expansion failure, but in others a different action may be
+taken. Such variations are mentioned in the documentation of the option that is
+being expanded.
+</para>
+</section>
+<section id="SECTexpansionitems">
+<title>Expansion items</title>
+<para>
+The following items are recognized in expanded strings. White space may be used
+between sub-items that are keywords or substrings enclosed in braces inside an
+outer set of braces, to improve readability. <emphasis role="bold">Warning</emphasis>: Within braces,
+white space is significant.
+</para>
+<variablelist>
+<varlistentry>
+<term><emphasis role="bold">$</emphasis>&lt;<emphasis>variable&nbsp;name</emphasis>&gt;&nbsp;or&nbsp;<emphasis role="bold">${</emphasis>&lt;<emphasis>variable&nbsp;name</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>variables</secondary>
+</indexterm>
+Substitute the contents of the named variable, for example:
+</para>
+<literallayout class="monospaced">
+$local_part
+${domain}
+</literallayout>
+<para>
+The second form can be used to separate the name from subsequent alphanumeric
+characters. This form (using braces) is available only for variables; it does
+<emphasis>not</emphasis> apply to message headers. The names of the variables are given in
+section <xref linkend="SECTexpvar"/> below. If the name of a non-existent variable is
+given, the expansion fails.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${</emphasis>&lt;<emphasis>op</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>operators</secondary>
+</indexterm>
+The string is first itself expanded, and then the operation specified by
+&lt;<emphasis>op</emphasis>&gt; is applied to it. For example:
+</para>
+<literallayout class="monospaced">
+${lc:$local_part}
+</literallayout>
+<para>
+The string starts with the first character after the colon, which may be
+leading white space. A list of operators is given in section <xref linkend="SECTexpop"/>
+below. The operator notation is used for simple expansion items that have just
+one argument, because it reduces the number of braces and therefore makes the
+string easier to understand.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">$bheader_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$bh_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<listitem>
+<para>
+This item inserts <quote>basic</quote> header lines. It is described with the <option>header</option>
+expansion item below.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${acl{</emphasis>&lt;<emphasis>name</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>calling an acl</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>acl</option></primary>
+<secondary>call from expansion</secondary>
+</indexterm>
+The name and zero to nine argument strings are first expanded separately.  The expanded
+arguments are assigned to the variables <varname>$acl_arg1</varname> to <varname>$acl_arg9</varname> in order.
+Any unused are made empty.  The variable <varname>$acl_narg</varname> is set to the number of
+arguments.  The named ACL (see chapter <xref linkend="CHAPACL"/>) is called
+and may use the variables; if another acl expansion is used the values
+are restored after it returns.  If the ACL sets
+a value using a "message =" modifier and returns accept or deny, the value becomes
+the result of the expansion.
+If no message is set and the ACL returns accept or deny
+the expansion result is an empty string.
+If the ACL returns defer the result is a forced-fail.  Otherwise the expansion fails.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${authresults{</emphasis>&lt;<emphasis>authserv-id</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>results header</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><emphasis>Authentication-Results:</emphasis> header line</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>Authentication-Results:</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>expansion item</secondary>
+</indexterm>
+This item returns a string suitable for insertion as an
+<emphasis>Authentication-Results:</emphasis>
+header line.
+The given &lt;<emphasis>authserv-id</emphasis>&gt; is included in the result; typically this
+will be a domain name identifying the system performing the authentications.
+Methods that might be present in the result include:
+</para>
+<literallayout class="monospaced">
+none
+iprev
+auth
+spf
+dkim
+</literallayout>
+<para>
+Example use (as an ACL modifier):
+</para>
+<literallayout class="monospaced">
+      add_header = :at_start:${authresults {$primary_hostname}}
+</literallayout>
+<para>
+This is safe even if no authentication results are available.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${certextract{</emphasis>&lt;<emphasis>field</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>certificate</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting certificate fields</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>certextract</option></primary>
+<secondary>certificate fields</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>certificate</primary>
+<secondary>extracting fields</secondary>
+</indexterm>
+The &lt;<emphasis>certificate</emphasis>&gt; must be a variable of type certificate.
+The field name is expanded and used to retrieve the relevant field from
+the certificate.  Supported fields are:
+</para>
+<literallayout>
+<literal>version        </literal>
+<literal>serial_number  </literal>
+<literal>subject        </literal> RFC4514 DN
+<literal>issuer         </literal> RFC4514 DN
+<literal>notbefore      </literal> time
+<literal>notafter       </literal> time
+<literal>sig_algorithm  </literal>
+<literal>signature      </literal>
+<literal>subj_altname   </literal> tagged list
+<literal>ocsp_uri       </literal> list
+<literal>crl_uri        </literal> list
+</literallayout>
+<para>
+If the field is found,
+&lt;<emphasis>string2</emphasis>&gt; is expanded, and replaces the whole item;
+otherwise &lt;<emphasis>string3</emphasis>&gt; is used. During the expansion of &lt;<emphasis>string2</emphasis>&gt; the
+variable <varname>$value</varname> contains the value that has been extracted. Afterwards, it
+is restored to any previous value it might have had.
+</para>
+<para>
+If {&lt;<emphasis>string3</emphasis>&gt;} is omitted, the item is replaced by an empty string if the
+key is not found. If {&lt;<emphasis>string2</emphasis>&gt;} is also omitted, the value that was
+extracted is used.
+</para>
+<para>
+Some field names take optional modifiers, appended and separated by commas.
+</para>
+<para>
+The field selectors marked as "RFC4514" above
+output a Distinguished Name string which is
+not quite
+parseable by Exim as a comma-separated tagged list
+(the exceptions being elements containing commas).
+RDN elements of a single type may be selected by
+a modifier of the type label; if so the expansion
+result is a list (newline-separated by default).
+The separator may be changed by another modifier of
+a right angle-bracket followed immediately by the new separator.
+Recognised RDN type labels include "CN", "O", "OU" and "DC".
+</para>
+<para>
+The field selectors marked as "time" above
+take an optional modifier of "int"
+for which the result is the number of seconds since epoch.
+Otherwise the result is a human-readable string
+in the timezone selected by the main "timezone" option.
+</para>
+<para>
+The field selectors marked as "list" above return a list,
+newline-separated by default,
+(embedded separator characters in elements are doubled).
+The separator may be changed by a modifier of
+a right angle-bracket followed immediately by the new separator.
+</para>
+<para>
+The field selectors marked as "tagged" above
+prefix each list element with a type string and an equals sign.
+Elements of only one type may be selected by a modifier
+which is one of "dns", "uri" or "mail";
+if so the element tags are omitted.
+</para>
+<para>
+If not otherwise noted field values are presented in human-readable form.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${dlfunc{</emphasis>&lt;<emphasis>file</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>function</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>dlfunc</option></primary>
+</indexterm>
+This expansion dynamically loads and then calls a locally-written C function.
+This functionality is available only if Exim is compiled with
+</para>
+<literallayout class="monospaced">
+EXPAND_DLFUNC=yes
+</literallayout>
+<para>
+set in <filename>Local/Makefile</filename>. Once loaded, Exim remembers the dynamically loaded
+object so that it doesn&#x2019;t reload the same object file in the same Exim process
+(but of course Exim does start new processes frequently).
+</para>
+<para>
+There may be from zero to eight arguments to the function.
+</para>
+<para>
+When compiling
+a local function that is to be called in this way,
+first <filename>DLFUNC_IMPL</filename> should be defined,
+and second <filename>local_scan.h</filename> should be included.
+The Exim variables and functions that are defined by that API
+are also available for dynamically loaded functions. The function itself
+must have the following type:
+</para>
+<literallayout class="monospaced">
+int dlfunction(uschar **yield, int argc, uschar *argv[])
+</literallayout>
+<para>
+Where <literal>uschar</literal> is a typedef for <literal>unsigned char</literal> in <filename>local_scan.h</filename>. The
+function should return one of the following values:
+</para>
+<para>
+<literal>OK</literal>: Success. The string that is placed in the variable <emphasis>yield</emphasis> is put
+into the expanded string that is being built.
+</para>
+<para>
+<literal>FAIL</literal>: A non-forced expansion failure occurs, with the error message taken
+from <emphasis>yield</emphasis>, if it is set.
+</para>
+<para>
+<literal>FAIL_FORCED</literal>: A forced expansion failure occurs, with the error message
+taken from <emphasis>yield</emphasis> if it is set.
+</para>
+<para>
+<literal>ERROR</literal>: Same as <literal>FAIL</literal>, except that a panic log entry is written.
+</para>
+<para>
+When compiling a function that is to be used in this way with gcc,
+you need to add <option>-shared</option> to the gcc command. Also, in the Exim build-time
+configuration, you must add <option>-export-dynamic</option> to EXTRALIBS.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${env{</emphasis>&lt;<emphasis>key</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting value from environment</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>environment</primary>
+<secondary>values from</secondary>
+</indexterm>
+The key is first expanded separately, and leading and trailing white space
+removed.
+This is then searched for as a name in the environment.
+If a variable is found then its value is placed in <varname>$value</varname>
+and &lt;<emphasis>string1</emphasis>&gt; is expanded, otherwise &lt;<emphasis>string2</emphasis>&gt; is expanded.
+</para>
+<para>
+Instead of {&lt;<emphasis>string2</emphasis>&gt;} the word <quote>fail</quote> (not in curly brackets) can
+appear, for example:
+</para>
+<literallayout class="monospaced">
+${env{USER}{$value} fail }
+</literallayout>
+<para>
+This forces an expansion failure (see section <xref linkend="SECTforexpfai"/>);
+{&lt;<emphasis>string1</emphasis>&gt;} must be present for <quote>fail</quote> to be recognized.
+</para>
+<para>
+If {&lt;<emphasis>string2</emphasis>&gt;} is omitted an empty string is substituted on
+search failure.
+If {&lt;<emphasis>string1</emphasis>&gt;} is omitted the search result is substituted on
+search success.
+</para>
+<para>
+The environment is adjusted by the <option>keep_environment</option> and
+<option>add_environment</option> main section options.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${extract{</emphasis>&lt;<emphasis>key</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting substrings by key</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>extract</option></primary>
+<secondary>substrings by key</secondary>
+</indexterm>
+The key and &lt;<emphasis>string1</emphasis>&gt; are first expanded separately. Leading and trailing
+white space is removed from the key (but not from any of the strings). The key
+must not be empty and must not consist entirely of digits.
+The expanded &lt;<emphasis>string1</emphasis>&gt; must be of the form:
+</para>
+<literallayout>
+&lt;<emphasis>key1</emphasis>&gt; = &lt;<emphasis>value1</emphasis>&gt;  &lt;<emphasis>key2</emphasis>&gt; = &lt;<emphasis>value2</emphasis>&gt; ...
+</literallayout>
+<para>
+<indexterm role="variable">
+<primary><varname>$value</varname></primary>
+</indexterm>
+where the equals signs and spaces (but not both) are optional. If any of the
+values contain white space, they must be enclosed in double quotes, and any
+values that are enclosed in double quotes are subject to escape processing as
+described in section <xref linkend="SECTstrings"/>. The expanded &lt;<emphasis>string1</emphasis>&gt; is searched
+for the value that corresponds to the key. The search is case-insensitive. If
+the key is found, &lt;<emphasis>string2</emphasis>&gt; is expanded, and replaces the whole item;
+otherwise &lt;<emphasis>string3</emphasis>&gt; is used. During the expansion of &lt;<emphasis>string2</emphasis>&gt; the
+variable <varname>$value</varname> contains the value that has been extracted. Afterwards, it
+is restored to any previous value it might have had.
+</para>
+<para>
+If {&lt;<emphasis>string3</emphasis>&gt;} is omitted, the item is replaced by an empty string if the
+key is not found. If {&lt;<emphasis>string2</emphasis>&gt;} is also omitted, the value that was
+extracted is used. Thus, for example, these two expansions are identical, and
+yield <quote>2001</quote>:
+</para>
+<literallayout class="monospaced">
+${extract{gid}{uid=1984 gid=2001}}
+${extract{gid}{uid=1984 gid=2001}{$value}}
+</literallayout>
+<para>
+Instead of {&lt;<emphasis>string3</emphasis>&gt;} the word <quote>fail</quote> (not in curly brackets) can
+appear, for example:
+</para>
+<literallayout class="monospaced">
+${extract{Z}{A=... B=...}{$value} fail }
+</literallayout>
+<para>
+This forces an expansion failure (see section <xref linkend="SECTforexpfai"/>);
+{&lt;<emphasis>string2</emphasis>&gt;} must be present for <quote>fail</quote> to be recognized.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${extract json{</emphasis>&lt;<emphasis>key</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<term><emphasis role="bold">${extract jsons{</emphasis>&lt;<emphasis>key</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting from JSON object</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>JSON</primary>
+<secondary>expansions</secondary>
+</indexterm>
+The key and &lt;<emphasis>string1</emphasis>&gt; are first expanded separately. Leading and trailing
+white space is removed from the key (but not from any of the strings). The key
+must not be empty and must not consist entirely of digits.
+The expanded &lt;<emphasis>string1</emphasis>&gt; must be of the form:
+</para>
+<literallayout>
+{ &lt;<emphasis>"key1"</emphasis>&gt; : &lt;<emphasis>value1</emphasis>&gt; ,  &lt;<emphasis>"key2"</emphasis>&gt; , &lt;<emphasis>value2</emphasis>&gt; ... }
+</literallayout>
+<para>
+<indexterm role="variable">
+<primary><varname>$value</varname></primary>
+</indexterm>
+The braces, commas and colons, and the quoting of the member name are required;
+the spaces are optional.
+Matching of the key against the member names is done case-sensitively.
+For the <quote>json</quote> variant,
+if a returned value is a JSON string, it retains its leading and
+trailing quotes.
+For the <quote>jsons</quote> variant, which is intended for use with JSON strings, the
+leading and trailing quotes are removed from the returned value.
+</para>
+<para>
+The results of matching are handled as above.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${extract{</emphasis>&lt;<emphasis>number</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>separators</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting substrings by number</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>extract</option></primary>
+<secondary>substrings by number</secondary>
+</indexterm>
+The &lt;<emphasis>number</emphasis>&gt; argument must consist entirely of decimal digits,
+apart from leading and trailing white space, which is ignored.
+This is what distinguishes this form of <option>extract</option> from the previous kind. It
+behaves in the same way, except that, instead of extracting a named field, it
+extracts from &lt;<emphasis>string1</emphasis>&gt; the field whose number is given as the first
+argument. You can use <varname>$value</varname> in &lt;<emphasis>string2</emphasis>&gt; or <literal>fail</literal> instead of
+&lt;<emphasis>string3</emphasis>&gt; as before.
+</para>
+<para>
+The fields in the string are separated by any one of the characters in the
+separator string. These may include space or tab characters.
+The first field is numbered one. If the number is negative, the fields are
+counted from the end of the string, with the rightmost one numbered -1. If the
+number given is zero, the entire string is returned. If the modulus of the
+number is greater than the number of fields in the string, the result is the
+expansion of &lt;<emphasis>string3</emphasis>&gt;, or the empty string if &lt;<emphasis>string3</emphasis>&gt; is not
+provided. For example:
+</para>
+<literallayout class="monospaced">
+${extract{2}{:}{x:42:99:&amp; Mailer::/bin/bash}}
+</literallayout>
+<para>
+yields <quote>42</quote>, and
+</para>
+<literallayout class="monospaced">
+${extract{-4}{:}{x:42:99:&amp; Mailer::/bin/bash}}
+</literallayout>
+<para>
+yields <quote>99</quote>. Two successive separators mean that the field between them is
+empty (for example, the fifth field above).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${extract json {</emphasis>&lt;<emphasis>number</emphasis>&gt;<emphasis role="bold">}}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<term><emphasis role="bold">${extract jsons{</emphasis>&lt;<emphasis>number</emphasis>&gt;<emphasis role="bold">}}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting from JSON array</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>JSON</primary>
+<secondary>expansions</secondary>
+</indexterm>
+The &lt;<emphasis>number</emphasis>&gt; argument must consist entirely of decimal digits,
+apart from leading and trailing white space, which is ignored.
+</para>
+<para>
+Field selection and result handling is as above;
+there is no choice of field separator.
+For the <quote>json</quote> variant,
+if a returned value is a JSON string, it retains its leading and
+trailing quotes.
+For the <quote>jsons</quote> variant, which is intended for use with JSON strings, the
+leading and trailing quotes are removed from the returned value.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${filter{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>condition</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>selecting by condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>selecting from list by condition</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$item</varname></primary>
+</indexterm>
+After expansion, &lt;<emphasis>string</emphasis>&gt; is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way (<xref linkend="SECTlistsepchange"/>).
+For each item
+in this list, its value is place in <varname>$item</varname>, and then the condition is
+evaluated. If the condition is true, <varname>$item</varname> is added to the output as an
+item in a new list; if the condition is false, the item is discarded. The
+separator used for the output list is the same as the one used for the
+input, but a separator setting is not included in the output. For example:
+</para>
+<literallayout class="monospaced">
+${filter{a:b:c}{!eq{$item}{b}}}
+</literallayout>
+<para>
+yields <literal>a:c</literal>. At the end of the expansion, the value of <varname>$item</varname> is restored
+to what it was before. See also the <option>map</option> and <option>reduce</option> expansion items.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${hash{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>hash function</primary>
+<secondary>textual</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>textual hash</secondary>
+</indexterm>
+This is a textual hashing function, and was the first to be implemented in
+early versions of Exim. In current releases, there are other hashing functions
+(numeric, MD5, and SHA-1), which are described below.
+</para>
+<para>
+The first two strings, after expansion, must be numbers. Call them &lt;<emphasis>m</emphasis>&gt; and
+&lt;<emphasis>n</emphasis>&gt;. If you are using fixed values for these numbers, that is, if
+&lt;<emphasis>string1</emphasis>&gt; and &lt;<emphasis>string2</emphasis>&gt; do not change when they are expanded, you can
+use the simpler operator notation that avoids some of the braces:
+</para>
+<literallayout class="monospaced">
+${hash_&lt;n&gt;_&lt;m&gt;:&lt;string&gt;}
+</literallayout>
+<para>
+The second number is optional (in both notations). If &lt;<emphasis>n</emphasis>&gt; is greater than
+or equal to the length of the string, the expansion item returns the string.
+Otherwise it computes a new string of length &lt;<emphasis>n</emphasis>&gt; by applying a hashing
+function to the string. The new string consists of characters taken from the
+first &lt;<emphasis>m</emphasis>&gt; characters of the string
+</para>
+<literallayout class="monospaced">
+abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789
+</literallayout>
+<para>
+If &lt;<emphasis>m</emphasis>&gt; is not present the value 26 is used, so that only lower case
+letters appear. For example:
+</para>
+<literallayout>
+<literal>$hash{3}{monty}}           </literal>   yields  <literal>jmg</literal>
+<literal>$hash{5}{monty}}           </literal>   yields  <literal>monty</literal>
+<literal>$hash{4}{62}{monty python}}</literal>   yields  <literal>fbWx</literal>
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">$header_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$h_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<term><emphasis role="bold">$bheader_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$bh_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<term><emphasis role="bold">$lheader_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$lh_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<term><emphasis role="bold">$rheader_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$rh_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>header insertion</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$header_</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$bheader_</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$lheader_</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$rheader_</varname></primary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>in expansion strings</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>character sets</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>header lines</primary>
+<secondary>decoding</secondary>
+</indexterm>
+Substitute the contents of the named message header line, for example
+</para>
+<literallayout class="monospaced">
+$header_reply-to:
+</literallayout>
+<para>
+The newline that terminates a header line is not included in the expansion, but
+internal newlines (caused by splitting the header line over several physical
+lines) may be present.
+</para>
+<para>
+The difference between the four pairs of expansions is in the way
+the data in the header line is interpreted.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>white space</primary>
+<secondary>in header lines</secondary>
+</indexterm>
+<option>rheader</option> gives the original <quote>raw</quote> content of the header line, with no
+processing at all, and without the removal of leading and trailing white space.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>of header lines</secondary>
+</indexterm>
+<option>lheader</option> gives a colon-separated list, one element per header when there
+are multiple headers with a given name.
+Any embedded colon characters within an element are doubled, so normal Exim
+list-processing facilities can be used.
+The terminating newline of each element is removed; in other respects
+the content is <quote>raw</quote>.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>base64 encoding</primary>
+<secondary>in header lines</secondary>
+</indexterm>
+<option>bheader</option> removes leading and trailing white space, and then decodes base64
+or quoted-printable MIME <quote>words</quote> within the header text, but does no
+character set translation. If decoding of what looks superficially like a MIME
+<quote>word</quote> fails, the raw string is returned. If decoding
+<indexterm role="concept">
+<primary>binary zero</primary>
+<secondary>in header line</secondary>
+</indexterm>
+produces a binary zero character, it is replaced by a question mark &ndash; this is
+what Exim does for binary zeros that are actually received in header lines.
+</para>
+</listitem>
+<listitem>
+<para>
+<option>header</option> tries to translate the string as decoded by <option>bheader</option> to a
+standard character set. This is an attempt to produce the same string as would
+be displayed on a user&#x2019;s MUA. If translation fails, the <option>bheader</option> string is
+returned. Translation is attempted only on operating systems that support the
+<function>iconv()</function> function. This is indicated by the compile-time macro HAVE_ICONV in
+a system Makefile or in <filename>Local/Makefile</filename>.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+In a filter file, the target character set for <option>header</option> can be specified by a
+command of the following form:
+</para>
+<literallayout class="monospaced">
+headers charset "UTF-8"
+</literallayout>
+<para>
+This command affects all references to <varname>$h_</varname> (or <varname>$header_</varname>) expansions in
+subsequently obeyed filter commands. In the absence of this command, the target
+character set in a filter is taken from the setting of the <option>headers_charset</option>
+option in the runtime configuration. The value of this option defaults to the
+value of HEADERS_CHARSET in <filename>Local/Makefile</filename>. The ultimate default is
+ISO-8859-1.
+</para>
+<para>
+Header names follow the syntax of RFC 2822, which states that they may contain
+any printing characters except space and colon. Consequently, curly brackets
+<emphasis>do not</emphasis> terminate header names, and should not be used to enclose them as
+if they were variables. Attempting to do so causes a syntax error.
+</para>
+<para>
+Only header lines that are common to all copies of a message are visible to
+this mechanism. These are the original header lines that are received with the
+message, and any that are added by an ACL statement or by a system
+filter. Header lines that are added to a particular copy of a message by a
+router or transport are not accessible.
+</para>
+<para>
+For incoming SMTP messages, no header lines are visible in
+ACLs that are obeyed before the data phase completes,
+because the header structure is not set up until the message is received.
+They are visible in DKIM, PRDR and DATA ACLs.
+Header lines that are added in a RCPT ACL (for example)
+are saved until the message&#x2019;s incoming header lines are available, at which
+point they are added.
+When any of the above ACLs are
+running, however, header lines added by earlier ACLs are visible.
+</para>
+<para>
+Upper case and lower case letters are synonymous in header names. If the
+following character is white space, the terminating colon may be omitted, but
+this is not recommended, because you may then forget it when it is needed. When
+white space terminates the header name, this white space is included in the
+expanded string.  If the message does not contain the given header, the
+expansion item is replaced by an empty string. (See the <option>def</option> condition in
+section <xref linkend="SECTexpcond"/> for a means of testing for the existence of a
+header.)
+</para>
+<para>
+If there is more than one header with the same name, they are all concatenated
+to form the substitution string, up to a maximum length of 64K. Unless
+<option>rheader</option> is being used, leading and trailing white space is removed from
+each header before concatenation, and a completely empty header is ignored. A
+newline character is then inserted between non-empty headers, but there is no
+newline at the very end. For the <option>header</option> and <option>bheader</option> expansion, for
+those headers that contain lists of addresses, a comma is also inserted at the
+junctions between headers. This does not happen for the <option>rheader</option> expansion.
+</para>
+<para>
+<indexterm role="concept">
+<primary>tainted data</primary>
+<secondary>message headers</secondary>
+</indexterm>
+When the headers are from an incoming message,
+the result of expanding any of these variables is tainted.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${hmac{</emphasis>&lt;<emphasis>hashname</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>secret</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>hmac hashing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>hmac</option></primary>
+</indexterm>
+This function uses cryptographic hashing (either MD5 or SHA-1) to convert a
+shared secret and some text into a message authentication code, as specified in
+RFC 2104. This differs from <literal>${md5:secret_text...}</literal> or
+<literal>${sha1:secret_text...}</literal> in that the hmac step adds a signature to the
+cryptographic hash, allowing for authentication that is not possible with MD5
+or SHA-1 alone. The hash name must expand to either <literal>md5</literal> or <literal>sha1</literal> at
+present. For example:
+</para>
+<literallayout class="monospaced">
+${hmac{md5}{somesecret}{$primary_hostname $tod_log}}
+</literallayout>
+<para>
+For the hostname <emphasis>mail.example.com</emphasis> and time 2002-10-17 11:30:59, this
+produces:
+</para>
+<literallayout class="monospaced">
+dd97e3ba5d1a61b5006108f8c8252953
+</literallayout>
+<para>
+As an example of how this might be used, you might put in the main part of
+an Exim configuration:
+</para>
+<literallayout class="monospaced">
+SPAMSCAN_SECRET=cohgheeLei2thahw
+</literallayout>
+<para>
+In a router or a transport you could then have:
+</para>
+<literallayout class="monospaced">
+headers_add = \
+  X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \
+  ${hmac{md5}{SPAMSCAN_SECRET}\
+  {${primary_hostname},${message_exim_id},$h_message-id:}}
+</literallayout>
+<para>
+Then given a message, you can check where it was scanned by looking at the
+<emphasis>X-Spam-Scanned:</emphasis> header line. If you know the secret, you can check that
+this header line is authentic by recomputing the authentication code from the
+host name, message ID and the <emphasis>Message-id:</emphasis> header line. This can be done
+using Exim&#x2019;s <option>-be</option> option, or by other means, for example, by using the
+<emphasis>hmac_md5_hex()</emphasis> function in Perl.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${if&nbsp;</emphasis>&lt;<emphasis>condition</emphasis>&gt;<emphasis role="bold">&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>conditional</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>if</option>, expansion item</primary>
+</indexterm>
+If &lt;<emphasis>condition</emphasis>&gt; is true, &lt;<emphasis>string1</emphasis>&gt; is expanded and replaces the whole
+item; otherwise &lt;<emphasis>string2</emphasis>&gt; is used. The available conditions are described
+in section <xref linkend="SECTexpcond"/> below. For example:
+</para>
+<literallayout class="monospaced">
+${if eq {$local_part}{postmaster} {yes}{no} }
+</literallayout>
+<para>
+The second string need not be present; if it is not and the condition is not
+true, the item is replaced with nothing. Alternatively, the word <quote>fail</quote> may
+be present instead of the second string (without any curly brackets). In this
+case, the expansion is forced to fail if the condition is not true (see section
+<xref linkend="SECTforexpfai"/>).
+</para>
+<para>
+If both strings are omitted, the result is the string <literal>true</literal> if the condition
+is true, and the empty string if the condition is false. This makes it less
+cumbersome to write custom ACL and router conditions. For example, instead of
+</para>
+<literallayout class="monospaced">
+condition = ${if &gt;{$acl_m4}{3}{true}{false}}
+</literallayout>
+<para>
+you can use
+</para>
+<literallayout class="monospaced">
+condition = ${if &gt;{$acl_m4}{3}}
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${imapfolder{</emphasis>&lt;<emphasis>foldername</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>imap folder</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>imapfolder</option> expansion item</primary>
+</indexterm>
+This item converts a (possibly multilevel, or with non-ASCII characters)
+folder specification to a Maildir name for filesystem use.
+For information on internationalisation support see <xref linkend="SECTi18nMDA"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${length{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string truncation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>length</option> expansion item</primary>
+</indexterm>
+The <option>length</option> item is used to extract the initial portion of a string. Both
+strings are expanded, and the first one must yield a number, &lt;<emphasis>n</emphasis>&gt;, say. If
+you are using a fixed value for the number, that is, if &lt;<emphasis>string1</emphasis>&gt; does not
+change when expanded, you can use the simpler operator notation that avoids
+some of the braces:
+</para>
+<literallayout class="monospaced">
+${length_&lt;n&gt;:&lt;string&gt;}
+</literallayout>
+<para>
+The result of this item is either the first &lt;<emphasis>n</emphasis>&gt; bytes or the whole
+of &lt;<emphasis>string2</emphasis>&gt;, whichever is the shorter. Do not confuse <option>length</option> with
+<option>strlen</option>, which gives the length of a string.
+All measurement is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${listextract{</emphasis>&lt;<emphasis>number</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>extracting list elements by number</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>listextract</option></primary>
+<secondary>extract list elements by number</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>extracting elements by number</secondary>
+</indexterm>
+The &lt;<emphasis>number</emphasis>&gt; argument must consist entirely of decimal digits,
+apart from an optional leading minus,
+and leading and trailing white space (which is ignored).
+</para>
+<para>
+After expansion, &lt;<emphasis>string1</emphasis>&gt; is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way (<xref linkend="SECTlistsepchange"/>).
+</para>
+<para>
+The first field of the list is numbered one.
+If the number is negative, the fields are
+counted from the end of the list, with the rightmost one numbered -1.
+The numbered element of the list is extracted and placed in <varname>$value</varname>,
+then &lt;<emphasis>string2</emphasis>&gt; is expanded as the result.
+</para>
+<para>
+If the modulus of the
+number is zero or greater than the number of fields in the string,
+the result is the expansion of &lt;<emphasis>string3</emphasis>&gt;.
+</para>
+<para>
+For example:
+</para>
+<literallayout class="monospaced">
+${listextract{2}{x:42:99}}
+</literallayout>
+<para>
+yields <quote>42</quote>, and
+</para>
+<literallayout class="monospaced">
+${listextract{-3}{&lt;, x,42,99,&amp; Mailer,,/bin/bash}{result: $value}}
+</literallayout>
+<para>
+yields <quote>result: 42</quote>.
+</para>
+<para>
+If {&lt;<emphasis>string3</emphasis>&gt;} is omitted, an empty string is used for string3.
+If {&lt;<emphasis>string2</emphasis>&gt;} is also omitted, the value that was
+extracted is used.
+You can use <literal>fail</literal> instead of {&lt;<emphasis>string3</emphasis>&gt;} as in a string extract.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><emphasis role="bold">${listquote{</emphasis>&lt;<emphasis>separator</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para revisionflag="changed">
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>for list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>quoting</secondary>
+</indexterm>
+This item doubles any occurrence of the separator character
+in the given string.
+An empty string is replaced with a single space.
+This converts the string into a safe form for use as a list element,
+in a list using the given separator.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${lookup&nbsp;{</emphasis>&lt;<emphasis>key</emphasis>&gt;<emphasis role="bold">}&nbsp;</emphasis>&lt;<emphasis>search&nbsp;type</emphasis>&gt;<emphasis role="bold">&nbsp;{</emphasis>&lt;<emphasis>file</emphasis>&gt;<emphasis role="bold">}&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}&nbsp;{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<term><emphasis role="bold">${lookup&nbsp;</emphasis>&lt;<emphasis>search&nbsp;type</emphasis>&gt;<emphasis role="bold">&nbsp;{</emphasis>&lt;<emphasis>query</emphasis>&gt;<emphasis role="bold">}&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}&nbsp;{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>lookup in</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>lookups</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lookup</primary>
+<secondary>in expanded string</secondary>
+</indexterm>
+The two forms of lookup item specify data lookups in files and databases, as
+discussed in chapter <xref linkend="CHAPfdlookup"/>. The first form is used for single-key
+lookups, and the second is used for query-style lookups. The &lt;<emphasis>key</emphasis>&gt;,
+&lt;<emphasis>file</emphasis>&gt;, and &lt;<emphasis>query</emphasis>&gt; strings are expanded before use.
+</para>
+<para>
+If there is any white space in a lookup item which is part of a filter command,
+a retry or rewrite rule, a routing rule for the <command>manualroute</command> router, or any
+other place where white space is significant, the lookup item must be enclosed
+in double quotes. The use of data lookups in users&#x2019; filter files may be locked
+out by the system administrator.
+</para>
+<para>
+<indexterm role="variable">
+<primary><varname>$value</varname></primary>
+</indexterm>
+If the lookup succeeds, &lt;<emphasis>string1</emphasis>&gt; is expanded and replaces the entire item.
+During its expansion, the variable <varname>$value</varname> contains the data returned by the
+lookup. Afterwards it reverts to the value it had previously (at the outer
+level it is empty). If the lookup fails, &lt;<emphasis>string2</emphasis>&gt; is expanded and replaces
+the entire item. If {&lt;<emphasis>string2</emphasis>&gt;} is omitted, the replacement is the empty
+string on failure. If &lt;<emphasis>string2</emphasis>&gt; is provided, it can itself be a nested
+lookup, thus providing a mechanism for looking up a default value when the
+original lookup fails.
+</para>
+<para>
+If a nested lookup is used as part of &lt;<emphasis>string1</emphasis>&gt;, <varname>$value</varname> contains the
+data for the outer lookup while the parameters of the second lookup are
+expanded, and also while &lt;<emphasis>string2</emphasis>&gt; of the second lookup is expanded, should
+the second lookup fail. Instead of {&lt;<emphasis>string2</emphasis>&gt;} the word <quote>fail</quote> can
+appear, and in this case, if the lookup fails, the entire expansion is forced
+to fail (see section <xref linkend="SECTforexpfai"/>). If both {&lt;<emphasis>string1</emphasis>&gt;} and
+{&lt;<emphasis>string2</emphasis>&gt;} are omitted, the result is the looked up value in the case of a
+successful lookup, and nothing in the case of failure.
+</para>
+<para>
+For single-key lookups, the string <quote>partial</quote> is permitted to precede the
+search type in order to do partial matching, and * or *@ may follow a search
+type to request default lookups if the key does not match (see sections
+<xref linkend="SECTdefaultvaluelookups"/> and <xref linkend="SECTpartiallookup"/> for details).
+</para>
+<para>
+<indexterm role="concept">
+<primary>numerical variables (<varname>$1</varname> <varname>$2</varname> etc)</primary>
+<secondary>in lookup expansion</secondary>
+</indexterm>
+If a partial search is used, the variables <varname>$1</varname> and <varname>$2</varname> contain the wild
+and non-wild parts of the key during the expansion of the replacement text.
+They return to their previous values at the end of the lookup item.
+</para>
+<para>
+This example looks up the postmaster alias in the conventional alias file:
+</para>
+<literallayout class="monospaced">
+${lookup {postmaster} lsearch {/etc/aliases} {$value}}
+</literallayout>
+<para>
+This example uses NIS+ to look up the full name of the user corresponding to
+the local part of an address, forcing the expansion to fail if it is not found:
+</para>
+<literallayout class="monospaced">
+${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \
+  {$value}fail}
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${map{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>list creation</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$item</varname></primary>
+</indexterm>
+After expansion, &lt;<emphasis>string1</emphasis>&gt; is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way (<xref linkend="SECTlistsepchange"/>).
+For each item
+in this list, its value is place in <varname>$item</varname>, and then &lt;<emphasis>string2</emphasis>&gt; is
+expanded and added to the output as an item in a new list. The separator used
+for the output list is the same as the one used for the input, but a separator
+setting is not included in the output. For example:
+</para>
+<literallayout class="monospaced">
+${map{a:b:c}{[$item]}} ${map{&lt;- x-y-z}{($item)}}
+</literallayout>
+<para>
+expands to <literal>[a]:[b]:[c] (x)-(y)-(z)</literal>. At the end of the expansion, the
+value of <varname>$item</varname> is restored to what it was before. See also the <option>filter</option>
+and <option>reduce</option> expansion items.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${nhash{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>numeric hash</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>hash function</primary>
+<secondary>numeric</secondary>
+</indexterm>
+The three strings are expanded; the first two must yield numbers. Call them
+&lt;<emphasis>n</emphasis>&gt; and &lt;<emphasis>m</emphasis>&gt;. If you are using fixed values for these numbers, that is,
+if &lt;<emphasis>string1</emphasis>&gt; and &lt;<emphasis>string2</emphasis>&gt; do not change when they are expanded, you
+can use the simpler operator notation that avoids some of the braces:
+</para>
+<literallayout class="monospaced">
+${nhash_&lt;n&gt;_&lt;m&gt;:&lt;string&gt;}
+</literallayout>
+<para>
+The second number is optional (in both notations). If there is only one number,
+the result is a number in the range 0&ndash;&lt;<emphasis>n</emphasis>&gt;-1. Otherwise, the string is
+processed by a div/mod hash function that returns two numbers, separated by a
+slash, in the ranges 0 to &lt;<emphasis>n</emphasis>&gt;-1 and 0 to &lt;<emphasis>m</emphasis>&gt;-1, respectively. For
+example,
+</para>
+<literallayout class="monospaced">
+${nhash{8}{64}{supercalifragilisticexpialidocious}}
+</literallayout>
+<para>
+returns the string <quote>6/33</quote>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${perl{</emphasis>&lt;<emphasis>subroutine</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Perl</primary>
+<secondary>use in expanded string</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>calling Perl from</secondary>
+</indexterm>
+This item is available only if Exim has been built to include an embedded Perl
+interpreter. The subroutine name and the arguments are first separately
+expanded, and then the Perl subroutine is called with those arguments. No
+additional arguments need be given; the maximum number permitted, including the
+name of the subroutine, is nine.
+</para>
+<para>
+The return value of the subroutine is inserted into the expanded string, unless
+the return value is <option>undef</option>. In that case, the entire expansion is
+forced to fail, in the same way as an explicit <quote>fail</quote> on a lookup item
+does (see section <xref linkend="SECTforexpfai"/>).  Whatever you return is evaluated
+in a scalar context, thus the return value is a scalar.  For example, if you
+return a Perl vector, the return value is the size of the vector,
+not its contents.
+</para>
+<para>
+If the subroutine exits by calling Perl&#x2019;s <option>die</option> function, the expansion fails
+with the error message that was passed to <option>die</option>. More details of the embedded
+Perl facility are given in chapter <xref linkend="CHAPperl"/>.
+</para>
+<para>
+The <command>redirect</command> router has an option called <option>forbid_filter_perl</option> which locks
+out the use of this expansion item in filter files.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${prvs{</emphasis>&lt;<emphasis>address</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>secret</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>keynumber</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>prvs</option> expansion item</primary>
+</indexterm>
+The first argument is a complete email address and the second is secret
+keystring. The third argument, specifying a key number, is optional. If absent,
+it defaults to 0. The result of the expansion is a prvs-signed email address,
+to be typically used with the <option>return_path</option> option on an <command>smtp</command> transport
+as part of a bounce address tag validation (BATV) scheme. For more discussion
+and an example, see section <xref linkend="SECTverifyPRVS"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${prvscheck{</emphasis>&lt;<emphasis>address</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>secret</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>prvscheck</option> expansion item</primary>
+</indexterm>
+This expansion item is the complement of the <option>prvs</option> item. It is used for
+checking prvs-signed addresses. If the expansion of the first argument does not
+yield a syntactically valid prvs-signed address, the whole item expands to the
+empty string. When the first argument does expand to a syntactically valid
+prvs-signed address, the second argument is expanded, with the prvs-decoded
+version of the address and the key number extracted from the address in the
+variables <varname>$prvscheck_address</varname> and <varname>$prvscheck_keynum</varname>, respectively.
+</para>
+<para>
+These two variables can be used in the expansion of the second argument to
+retrieve the secret. The validity of the prvs-signed address is then checked
+against the secret. The result is stored in the variable <varname>$prvscheck_result</varname>,
+which is empty for failure or <quote>1</quote> for success.
+</para>
+<para>
+The third argument is optional; if it is missing, it defaults to an empty
+string. This argument is now expanded. If the result is an empty string, the
+result of the expansion is the decoded version of the address. This is the case
+whether or not the signature was valid. Otherwise, the result of the expansion
+is the expansion of the third argument.
+</para>
+<para>
+All three variables can be used in the expansion of the third argument.
+However, once the expansion is complete, only <varname>$prvscheck_result</varname> remains set.
+For more discussion and an example, see section <xref linkend="SECTverifyPRVS"/>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${readfile{</emphasis>&lt;<emphasis>file&nbsp;name</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>eol&nbsp;string</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>inserting an entire file</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>inserting into expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>readfile</option> expansion item</primary>
+</indexterm>
+The filename and end-of-line (eol) string are first expanded separately. The file is
+then read, and its contents replace the entire item. All newline characters in
+the file are replaced by the end-of-line string if it is present. Otherwise,
+newlines are left in the string.
+String expansion is not applied to the contents of the file. If you want this,
+you must wrap the item in an <option>expand</option> operator. If the file cannot be read,
+the string expansion fails.
+</para>
+<para>
+The <command>redirect</command> router has an option called <option>forbid_filter_readfile</option> which
+locks out the use of this expansion item in filter files.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${readsocket{</emphasis>&lt;<emphasis>name</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>request</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>options</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>eol&nbsp;string</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>fail&nbsp;string</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>inserting from a socket</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>socket, use of in expansion</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>readsocket</option> expansion item</primary>
+</indexterm>
+This item inserts data from a Unix domain or TCP socket into the expanded
+string. The minimal way of using it uses just two arguments, as in these
+examples:
+</para>
+<literallayout class="monospaced">
+${readsocket{/socket/name}{request string}}
+${readsocket{inet:some.host:1234}{request string}}
+</literallayout>
+<para>
+For a Unix domain socket, the first substring must be the path to the socket.
+For an Internet socket, the first substring must contain <literal>inet:</literal> followed by
+a host name or IP address, followed by a colon and a port, which can be a
+number or the name of a TCP port in <filename>/etc/services</filename>. An IP address may
+optionally be enclosed in square brackets. This is best for IPv6 addresses. For
+example:
+</para>
+<literallayout class="monospaced">
+${readsocket{inet:[::1]:1234}{request string}}
+</literallayout>
+<para>
+Only a single host name may be given, but if looking it up yields more than
+one IP address, they are each tried in turn until a connection is made. For
+both kinds of socket, Exim makes a connection, writes the request string
+(unless it is an empty string; no terminating NUL is ever sent)
+and reads from the socket until an end-of-file
+is read. A timeout of 5 seconds is applied. Additional, optional arguments
+extend what can be done. Firstly, you can vary the timeout. For example:
+</para>
+<literallayout class="monospaced">
+${readsocket{/socket/name}{request string}{3s}}
+</literallayout>
+<para>
+The third argument is a list of options, of which the first element is the timeout
+and must be present if any options are given.
+Further elements are options of form <emphasis>name=value</emphasis>.
+Example:
+</para>
+<literallayout class="monospaced">
+${readsocket{/socket/name}{request string}{3s:shutdown=no}}
+</literallayout>
+<para>
+The following option names are recognised:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<emphasis role="bold">cache</emphasis>
+Defines if the result data can be cached for use by a later identical
+request in the same process.
+Values are <quote>yes</quote> or <quote>no</quote> (the default).
+If not, all cached results for this connection specification
+will be invalidated.
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="bold">shutdown</emphasis>
+Defines whether or not a write-shutdown is done on the connection after
+sending the request. Values are <quote>yes</quote> (the default) or <quote>no</quote>
+(preferred, eg. by some webservers).
+</para>
+</listitem>
+<listitem>
+<para>
+<emphasis role="bold">tls</emphasis>
+Controls the use of TLS on the connection.
+Values are <quote>yes</quote> or <quote>no</quote> (the default).
+If it is enabled, a shutdown as descripbed above is never done.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+A fourth argument allows you to change any newlines that are in the data
+that is read, in the same way as for <option>readfile</option> (see above). This example
+turns them into spaces:
+</para>
+<literallayout class="monospaced">
+${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }}
+</literallayout>
+<para>
+As with all expansions, the substrings are expanded before the processing
+happens. Errors in these sub-expansions cause the expansion to fail. In
+addition, the following errors can occur:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+Failure to create a socket file descriptor;
+</para>
+</listitem>
+<listitem>
+<para>
+Failure to connect the socket;
+</para>
+</listitem>
+<listitem>
+<para>
+Failure to write the request string;
+</para>
+</listitem>
+<listitem>
+<para>
+Timeout on reading from the socket.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+By default, any of these errors causes the expansion to fail. However, if
+you supply a fifth substring, it is expanded and used when any of the above
+errors occurs. For example:
+</para>
+<literallayout class="monospaced">
+${readsocket{/socket/name}{request string}{3s}{\n}\
+  {socket failure}}
+</literallayout>
+<para>
+You can test for the existence of a Unix domain socket by wrapping this
+expansion in <literal>${if exists</literal>, but there is a race condition between that test
+and the actual opening of the socket, so it is safer to use the fifth argument
+if you want to be absolutely sure of avoiding an expansion error for a
+non-existent Unix domain socket, or a failure to connect to an Internet socket.
+</para>
+<para>
+The <command>redirect</command> router has an option called <option>forbid_filter_readsocket</option> which
+locks out the use of this expansion item in filter files.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${reduce{</emphasis>&lt;<emphasis>string1</emphasis>&gt;}{&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>reducing a list to a scalar</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>reducing to a scalar</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$value</varname></primary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$item</varname></primary>
+</indexterm>
+This operation reduces a list to a single, scalar string. After expansion,
+&lt;<emphasis>string1</emphasis>&gt; is interpreted as a list, colon-separated by default, but the
+separator can be changed in the usual way (<xref linkend="SECTlistsepchange"/>).
+Then &lt;<emphasis>string2</emphasis>&gt; is expanded and
+assigned to the <varname>$value</varname> variable. After this, each item in the &lt;<emphasis>string1</emphasis>&gt;
+list is assigned to <varname>$item</varname>, in turn, and &lt;<emphasis>string3</emphasis>&gt; is expanded for each of
+them. The result of that expansion is assigned to <varname>$value</varname> before the next
+iteration. When the end of the list is reached, the final value of <varname>$value</varname> is
+added to the expansion output. The <option>reduce</option> expansion item can be used in a
+number of ways. For example, to add up a list of numbers:
+</para>
+<literallayout class="monospaced">
+${reduce {&lt;, 1,2,3}{0}{${eval:$value+$item}}}
+</literallayout>
+<para>
+The result of that expansion would be <literal>6</literal>. The maximum of a list of numbers
+can be found:
+</para>
+<literallayout class="monospaced">
+${reduce {3:0:9:4:6}{0}{${if &gt;{$item}{$value}{$item}{$value}}}}
+</literallayout>
+<para>
+At the end of a <emphasis role="bold">reduce</emphasis> expansion, the values of <varname>$item</varname> and <varname>$value</varname> are
+restored to what they were before. See also the <option>filter</option> and <option>map</option>
+expansion items.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">$rheader_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;or&nbsp;<emphasis role="bold">$rh_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<listitem>
+<para>
+This item inserts <quote>raw</quote> header lines. It is described with the <option>header</option>
+expansion item in section <xref linkend="SECTexpansionitems"/> above.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${run{</emphasis>&lt;<emphasis>command</emphasis>&gt;<emphasis role="bold">&nbsp;</emphasis>&lt;<emphasis>args</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>running a command</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>run</option> expansion item</primary>
+</indexterm>
+The command and its arguments are first expanded as one string. The string is
+split apart into individual arguments by spaces, and then the command is run
+in a separate process, but under the same uid and gid.  As in other command
+executions from Exim, a shell is not used by default. If the command requires
+a shell, you must explicitly code it.
+</para>
+<para>
+Since the arguments are split by spaces, when there is a variable expansion
+which has an empty result, it will cause the situation that the argument will
+simply be omitted when the program is actually executed by Exim. If the
+script/program requires a specific number of arguments and the expanded
+variable could possibly result in this empty expansion, the variable must be
+quoted. This is more difficult if the expanded variable itself could result
+in a string containing quotes, because it would interfere with the quotes
+around the command arguments. A possible guard against this is to wrap the
+variable in the <option>sg</option> operator to change any quote marks to some other
+character.
+</para>
+<para>
+The standard input for the command exists, but is empty. The standard output
+and standard error are set to the same file descriptor.
+<indexterm role="concept">
+<primary>return code</primary>
+<secondary>from <option>run</option> expansion</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$value</varname></primary>
+</indexterm>
+If the command succeeds (gives a zero return code) &lt;<emphasis>string1</emphasis>&gt; is expanded
+and replaces the entire item; during this expansion, the standard output/error
+from the command is in the variable <varname>$value</varname>. If the command fails,
+&lt;<emphasis>string2</emphasis>&gt;, if present, is expanded and used. Once again, during the
+expansion, the standard output/error from the command is in the variable
+<varname>$value</varname>.
+</para>
+<para>
+If &lt;<emphasis>string2</emphasis>&gt; is absent, the result is empty. Alternatively, &lt;<emphasis>string2</emphasis>&gt;
+can be the word <quote>fail</quote> (not in braces) to force expansion failure if the
+command does not succeed. If both strings are omitted, the result is contents
+of the standard output/error on success, and nothing on failure.
+</para>
+<para>
+<indexterm role="variable">
+<primary><varname>$run_in_acl</varname></primary>
+</indexterm>
+The standard output/error of the command is put in the variable <varname>$value</varname>.
+In this ACL example, the output of a command is logged for the admin to
+troubleshoot:
+</para>
+<literallayout class="monospaced">
+warn  condition    = ${run{/usr/bin/id}{yes}{no}}
+      log_message  = Output of id: $value
+</literallayout>
+<para>
+If the command requires shell idioms, such as the &gt; redirect operator, the
+shell must be invoked directly, such as with:
+</para>
+<literallayout class="monospaced">
+${run{/bin/bash -c "/usr/bin/id &gt;/tmp/id"}{yes}{yes}}
+</literallayout>
+<para>
+<indexterm role="variable">
+<primary><varname>$runrc</varname></primary>
+</indexterm>
+The return code from the command is put in the variable <varname>$runrc</varname>, and this
+remains set afterwards, so in a filter file you can do things like this:
+</para>
+<literallayout class="monospaced">
+if "${run{x y z}{}}$runrc" is 1 then ...
+  elif $runrc is 2 then ...
+  ...
+endif
+</literallayout>
+<para>
+If execution of the command fails (for example, the command does not exist),
+the return code is 127 &ndash; the same code that shells use for non-existent
+commands.
+</para>
+<para>
+<emphasis role="bold">Warning</emphasis>: In a router or transport, you cannot assume the order in which
+option values are expanded, except for those preconditions whose order of
+testing is documented. Therefore, you cannot reliably expect to set <varname>$runrc</varname>
+by the expansion of one option, and use it in another.
+</para>
+<para>
+The <command>redirect</command> router has an option called <option>forbid_filter_run</option> which locks
+out the use of this expansion item in filter files.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${sg{</emphasis>&lt;<emphasis>subject</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>regex</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>replacement</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string substitution</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>sg</option> expansion item</primary>
+</indexterm>
+This item works like Perl&#x2019;s substitution operator (s) with the global (/g)
+option; hence its name. However, unlike the Perl equivalent, Exim does not
+modify the subject string; instead it returns the modified string for insertion
+into the overall expansion. The item takes three arguments: the subject string,
+a regular expression, and a substitution string. For example:
+</para>
+<literallayout class="monospaced">
+${sg{abcdefabcdef}{abc}{xyz}}
+</literallayout>
+<para>
+yields <quote>xyzdefxyzdef</quote>. Because all three arguments are expanded before use,
+if any $, } or \ characters are required in the regular expression or in the
+substitution string, they have to be escaped. For example:
+</para>
+<literallayout class="monospaced">
+${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
+</literallayout>
+<para>
+yields <quote>defabc</quote>, and
+</para>
+<literallayout class="monospaced">
+${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}}
+</literallayout>
+<para>
+yields <quote>K1=A K4=D K3=C</quote>. Note the use of <literal>\N</literal> to protect the contents of
+the regular expression from string expansion.
+</para>
+<para>
+The regular expression is compiled in 8-bit mode, working against bytes
+rather than any Unicode-aware character handling.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${sort{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>comparator</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>extractor</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>sorting</primary>
+<secondary>a list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>sorting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>list sorting</secondary>
+</indexterm>
+After expansion, &lt;<emphasis>string</emphasis>&gt; is interpreted as a list, colon-separated by
+default, but the separator can be changed in the usual way (<xref linkend="SECTlistsepchange"/>).
+The &lt;<emphasis>comparator</emphasis>&gt; argument is interpreted as the operator
+of a two-argument expansion condition.
+The numeric operators plus ge, gt, le, lt (and ~i variants) are supported.
+The comparison should return true when applied to two values
+if the first value should sort before the second value.
+The &lt;<emphasis>extractor</emphasis>&gt; expansion is applied repeatedly to elements of the list,
+the element being placed in <varname>$item</varname>,
+to give values for comparison.
+</para>
+<para>
+The item result is a sorted list,
+with the original list separator,
+of the list elements (in full) of the original.
+</para>
+<para>
+Examples:
+</para>
+<literallayout class="monospaced">
+${sort{3:2:1:4}{&lt;}{$item}}
+</literallayout>
+<para>
+sorts a list of numbers, and
+</para>
+<literallayout class="monospaced">
+${sort {${lookup dnsdb{&gt;:,,mx=example.com}}} {&lt;} {${listextract{1}{&lt;,$item}}}}
+</literallayout>
+<para>
+will sort an MX lookup into priority order.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><emphasis role="bold">${srs_encode&nbsp;{</emphasis>&lt;<emphasis>secret</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>return&nbsp;path</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>original&nbsp;domain</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para revisionflag="changed">
+SRS encoding.  See SECT <xref linkend="SECTSRS"/> for details.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${substr{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string3</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>substr</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>substring extraction</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>substring extraction</secondary>
+</indexterm>
+The three strings are expanded; the first two must yield numbers. Call them
+&lt;<emphasis>n</emphasis>&gt; and &lt;<emphasis>m</emphasis>&gt;. If you are using fixed values for these numbers, that is,
+if &lt;<emphasis>string1</emphasis>&gt; and &lt;<emphasis>string2</emphasis>&gt; do not change when they are expanded, you
+can use the simpler operator notation that avoids some of the braces:
+</para>
+<literallayout class="monospaced">
+${substr_&lt;n&gt;_&lt;m&gt;:&lt;string&gt;}
+</literallayout>
+<para>
+The second number is optional (in both notations).
+If it is absent in the simpler format, the preceding underscore must also be
+omitted.
+</para>
+<para>
+The <option>substr</option> item can be used to extract more general substrings than
+<option>length</option>. The first number, &lt;<emphasis>n</emphasis>&gt;, is a starting offset, and &lt;<emphasis>m</emphasis>&gt; is the
+length required. For example
+</para>
+<literallayout class="monospaced">
+${substr{3}{2}{$local_part}}
+</literallayout>
+<para>
+If the starting offset is greater than the string length the result is the
+null string; if the length plus starting offset is greater than the string
+length, the result is the right-hand part of the string, starting from the
+given offset. The first byte (character) in the string has offset zero.
+</para>
+<para>
+The <option>substr</option> expansion item can take negative offset values to count
+from the right-hand end of its operand. The last byte (character) is offset -1,
+the second-last is offset -2, and so on. Thus, for example,
+</para>
+<literallayout class="monospaced">
+${substr{-5}{2}{1234567}}
+</literallayout>
+<para>
+yields <quote>34</quote>. If the absolute value of a negative offset is greater than the
+length of the string, the substring starts at the beginning of the string, and
+the length is reduced by the amount of overshoot. Thus, for example,
+</para>
+<literallayout class="monospaced">
+${substr{-5}{2}{12}}
+</literallayout>
+<para>
+yields an empty string, but
+</para>
+<literallayout class="monospaced">
+${substr{-3}{2}{12}}
+</literallayout>
+<para>
+yields <quote>1</quote>.
+</para>
+<para>
+When the second number is omitted from <option>substr</option>, the remainder of the string
+is taken if the offset is positive. If it is negative, all bytes (characters) in the
+string preceding the offset point are taken. For example, an offset of -1 and
+no length, as in these semantically identical examples:
+</para>
+<literallayout class="monospaced">
+${substr_-1:abcde}
+${substr{-1}{abcde}}
+</literallayout>
+<para>
+yields all but the last character of the string, that is, <quote>abcd</quote>.
+</para>
+<para>
+All measurement is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${tr{</emphasis>&lt;<emphasis>subject</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>characters</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>replacements</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>character translation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>tr</option> expansion item</primary>
+</indexterm>
+This item does single-character (in bytes) translation on its subject string. The second
+argument is a list of characters to be translated in the subject string. Each
+matching character is replaced by the corresponding character from the
+replacement list. For example
+</para>
+<literallayout class="monospaced">
+${tr{abcdea}{ac}{13}}
+</literallayout>
+<para>
+yields <literal>1b3de1</literal>. If there are duplicates in the second character string, the
+last occurrence is used. If the third string is shorter than the second, its
+last character is replicated. However, if it is empty, no translation takes
+place.
+</para>
+<para>
+All character handling is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+</variablelist>
+</section>
+<section id="SECTexpop">
+<title>Expansion operators</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>operators</secondary>
+</indexterm>
+For expansion items that perform transformations on a single argument string,
+the <quote>operator</quote> notation is used because it is simpler and uses fewer braces.
+The substring is first expanded before the operation is applied to it. The
+following operations can be performed:
+</para>
+<variablelist>
+<varlistentry>
+<term><emphasis role="bold">${address:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>RFC 2822 address handling</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>address</option> expansion item</primary>
+</indexterm>
+The string is interpreted as an RFC 2822 address, as it might appear in a
+header line, and the effective address is extracted from it. If the string does
+not parse successfully, the result is empty.
+</para>
+<para>
+The parsing correctly handles SMTPUTF8 Unicode in the string.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${addresses:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>RFC 2822 address handling</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>addresses</option> expansion item</primary>
+</indexterm>
+The string (after expansion) is interpreted as a list of addresses in RFC
+2822 format, such as can be found in a <emphasis>To:</emphasis> or <emphasis>Cc:</emphasis> header line. The
+operative address (<emphasis>local-part@domain</emphasis>) is extracted from each item, and the
+result of the expansion is a colon-separated list, with appropriate
+doubling of colons should any happen to be present in the email addresses.
+Syntactically invalid RFC2822 address items are omitted from the output.
+</para>
+<para>
+It is possible to specify a character other than colon for the output
+separator by starting the string with &gt; followed by the new separator
+character. For example:
+</para>
+<literallayout class="monospaced">
+${addresses:&gt;&amp; Chief &lt;ceo@???&gt;, sec@??? (dogsbody)}
+</literallayout>
+<para>
+expands to <literal>ceo@???&amp;sec@???</literal>. The string is expanded
+first, so if the expanded string starts with &gt;, it may change the output
+separator unintentionally. This can be avoided by setting the output
+separator explicitly:
+</para>
+<literallayout class="monospaced">
+${addresses:&gt;:$h_from:}
+</literallayout>
+<para>
+Compare the <option>address</option> (singular)
+expansion item, which extracts the working address from a single RFC2822
+address. See the <option>filter</option>, <option>map</option>, and <option>reduce</option> items for ways of
+processing lists.
+</para>
+<para>
+To clarify "list of addresses in RFC 2822 format" mentioned above, Exim follows
+a strict interpretation of header line formatting.  Exim parses the bare,
+unquoted portion of an email address and if it finds a comma, treats it as an
+email address separator. For the example header line:
+</para>
+<literallayout class="monospaced">
+From: =?iso-8859-2?Q?Last=2C_First?= &lt;user@???&gt;
+</literallayout>
+<para>
+The first example below demonstrates that Q-encoded email addresses are parsed
+properly if it is given the raw header (in this example, <literal>$rheader_from:</literal>).
+It does not see the comma because it&#x2019;s still encoded as "=2C".  The second
+example below is passed the contents of <literal>$header_from:</literal>, meaning it gets
+de-mimed. Exim sees the decoded "," so it treats it as <emphasis role="bold">two</emphasis> email addresses.
+The third example shows that the presence of a comma is skipped when it is
+quoted.  The fourth example shows SMTPUTF8 handling.
+</para>
+<literallayout class="monospaced">
+# exim -be '${addresses:From: \
+=?iso-8859-2?Q?Last=2C_First?= &lt;user@???&gt;}'
+user@???
+# exim -be '${addresses:From: Last, First &lt;user@???&gt;}'
+Last:user@???
+# exim -be '${addresses:From: "Last, First" &lt;user@???&gt;}'
+user@???
+# exim -be '${addresses:フィル &lt;フィリップ@example.jp&gt;}'
+フィリップ@example.jp
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base32:</emphasis>&lt;<emphasis>digits</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>base32</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>conversion to base 32</secondary>
+</indexterm>
+The string must consist entirely of decimal digits. The number is converted to
+base 32 and output as a (empty, for zero) string of characters.
+Only lowercase letters are used.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base32d:</emphasis>&lt;<emphasis>base-32&nbsp;digits</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>base32d</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>conversion to base 32</secondary>
+</indexterm>
+The string must consist entirely of base-32 digits.
+The number is converted to decimal and output as a string.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base62:</emphasis>&lt;<emphasis>digits</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>base62</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>conversion to base 62</secondary>
+</indexterm>
+The string must consist entirely of decimal digits. The number is converted to
+base 62 and output as a string of six characters, including leading zeros. In
+the few operating environments where Exim uses base 36 instead of base 62 for
+its message identifiers (because those systems do not have case-sensitive
+filenames), base 36 is used by this operator, despite its name. <emphasis role="bold">Note</emphasis>: Just
+to be absolutely clear: this is <emphasis>not</emphasis> base64 encoding.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base62d:</emphasis>&lt;<emphasis>base-62&nbsp;digits</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>base62d</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>conversion to base 62</secondary>
+</indexterm>
+The string must consist entirely of base-62 digits, or, in operating
+environments where Exim uses base 36 instead of base 62 for its message
+identifiers, base-36 digits. The number is converted to decimal and output as a
+string.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base64:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>base64 encoding</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>base64 encoding</primary>
+<secondary>in string expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>base64</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>certificate</primary>
+<secondary>base64 of DER</secondary>
+</indexterm>
+This operator converts a string into one that is base64 encoded.
+</para>
+<para>
+If the string is a single variable of type certificate,
+returns the base64 encoding of the DER form of the certificate.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${base64d:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>base64 decoding</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>base64 decoding</primary>
+<secondary>in string expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>base64d</option> expansion item</primary>
+</indexterm>
+This operator converts a base64-encoded string into the un-coded form.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${domain:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>domain</primary>
+<secondary>extraction</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>domain extraction</secondary>
+</indexterm>
+The string is interpreted as an RFC 2822 address and the domain is extracted
+from it. If the string does not parse successfully, the result is empty.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${escape:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>escaping non-printing characters</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>escape</option> expansion item</primary>
+</indexterm>
+If the string contains any non-printing characters, they are converted to
+escape sequences starting with a backslash. Whether characters with the most
+significant bit set (so-called <quote>8-bit characters</quote>) count as printing or not
+is controlled by the <option>print_topbitchars</option> option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${escape8bit:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>escaping 8-bit characters</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>escape8bit</option> expansion item</primary>
+</indexterm>
+If the string contains any characters with the most significant bit set,
+they are converted to escape sequences starting with a backslash.
+Backslashes and DEL characters are also converted.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${eval:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis>&nbsp;and&nbsp;<emphasis role="bold">${eval10:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>expression evaluation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>arithmetic expression</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>eval</option> expansion item</primary>
+</indexterm>
+These items supports simple arithmetic and bitwise logical operations in
+expansion strings. The string (after expansion) must be a conventional
+arithmetic expression, but it is limited to basic arithmetic operators, bitwise
+logical operators, and parentheses. All operations are carried out using
+integer arithmetic. The operator priorities are as follows (the same as in the
+C programming language):
+</para>
+<informaltable frame="none">
+<tgroup cols="2" colsep="0" rowsep="0">
+<colspec colwidth="70pt" align="left"/>
+<colspec colwidth="300pt" align="left"/>
+<tbody>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<emphasis>highest:</emphasis></entry>
+<entry>not (~), negate (-)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;</entry>
+<entry>multiply (*), divide (/), remainder (%)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;</entry>
+<entry>plus (+), minus (-)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;</entry>
+<entry>shift-left (&lt;&lt;), shift-right (&gt;&gt;)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;</entry>
+<entry>and (&amp;)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;</entry>
+<entry>xor (^)</entry>
+</row>
+<row>
+<entry>&nbsp;&nbsp;&nbsp;&nbsp;<emphasis>lowest:</emphasis></entry>
+<entry>or (|)</entry>
+</row>
+</tbody>
+</tgroup>
+</informaltable>
+<para>
+Binary operators with the same priority are evaluated from left to right. White
+space is permitted before or after operators.
+</para>
+<para>
+For <option>eval</option>, numbers may be decimal, octal (starting with <quote>0</quote>) or
+hexadecimal (starting with <quote>0x</quote>). For <option>eval10</option>, all numbers are taken as
+decimal, even if they start with a leading zero; hexadecimal numbers are not
+permitted. This can be useful when processing numbers extracted from dates or
+times, which often do have leading zeros.
+</para>
+<para>
+A number may be followed by <quote>K</quote>, <quote>M</quote> or <quote>G</quote> to multiply it by 1024, 1024*1024
+or 1024*1024*1024,
+respectively. Negative numbers are supported. The result of the computation is
+a decimal representation of the answer (without <quote>K</quote>, <quote>M</quote> or <quote>G</quote>). For example:
+</para>
+<literallayout>
+<literal>${eval:1+1}            </literal>  yields 2
+<literal>${eval:1+2*3}          </literal>  yields 7
+<literal>${eval:(1+2)*3}        </literal>  yields 9
+<literal>${eval:2+42%5}         </literal>  yields 4
+<literal>${eval:0xc&amp;5}          </literal>  yields 4
+<literal>${eval:0xc|5}          </literal>  yields 13
+<literal>${eval:0xc^5}          </literal>  yields 9
+<literal>${eval:0xc&gt;&gt;1}         </literal>  yields 6
+<literal>${eval:0xc&lt;&lt;1}         </literal>  yields 24
+<literal>${eval:~255&amp;0x1234}    </literal>  yields 4608
+<literal>${eval:-(~255&amp;0x1234)} </literal>  yields -4608
+</literallayout>
+<para>
+As a more realistic example, in an ACL you might have
+</para>
+<literallayout class="monospaced">
+deny   condition =                    \
+         ${if and {                   \
+           {&gt;{$rcpt_count}{10}}       \
+           {                          \
+           &lt;                          \
+             {$recipients_count}      \
+             {${eval:$rcpt_count/2}}  \
+           }                          \
+         }{yes}{no}}
+       message = Too many bad recipients
+</literallayout>
+<para>
+The condition is true if there have been more than 10 RCPT commands and
+fewer than half of them have resulted in a valid recipient.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${expand:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>re-expansion of substring</secondary>
+</indexterm>
+The <option>expand</option> operator causes a string to be expanded for a second time. For
+example,
+</para>
+<literallayout class="monospaced">
+${expand:${lookup{$domain}dbm{/some/file}{$value}}}
+</literallayout>
+<para>
+first looks up a string in a file while expanding the operand for <option>expand</option>,
+and then re-expands what it has found.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${from_utf8:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Unicode</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>UTF-8</primary>
+<secondary>conversion from</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>UTF-8 conversion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>from_utf8</option> expansion item</primary>
+</indexterm>
+The world is slowly moving towards Unicode, although there are no standards for
+email yet. However, other applications (including some databases) are starting
+to store data in Unicode, using UTF-8 encoding. This operator converts from a
+UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are
+converted to underscores. The input must be a valid UTF-8 string. If it is not,
+the result is an undefined sequence of bytes.
+</para>
+<para>
+Unicode code points with values less than 256 are compatible with ASCII and
+ISO-8859-1 (also known as Latin-1).
+For example, character 169 is the copyright symbol in both cases, though the
+way it is encoded is different. In UTF-8, more than one byte is needed for
+characters with code values greater than 127, whereas ISO-8859-1 is a
+single-byte encoding (but thereby limited to 256 characters). This makes
+translation from UTF-8 to ISO-8859-1 straightforward.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${hash_</emphasis>&lt;<emphasis>n</emphasis>&gt;<emphasis role="bold">_</emphasis>&lt;<emphasis>m</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>hash function</primary>
+<secondary>textual</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>textual hash</secondary>
+</indexterm>
+The <option>hash</option> operator is a simpler interface to the hashing function that can
+be used when the two parameters are fixed numbers (as opposed to strings that
+change when expanded). The effect is the same as
+</para>
+<literallayout class="monospaced">
+${hash{&lt;n&gt;}{&lt;m&gt;}{&lt;string&gt;}}
+</literallayout>
+<para>
+See the description of the general <option>hash</option> item above for details. The
+abbreviation <option>h</option> can be used when <option>hash</option> is used as an operator.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${hex2b64:</emphasis>&lt;<emphasis>hexstring</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>base64 encoding</primary>
+<secondary>conversion from hex</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>hex to base64</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>hex2b64</option> expansion item</primary>
+</indexterm>
+This operator converts a hex string into one that is base64 encoded. This can
+be useful for processing the output of the various hashing functions.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${hexquote:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>hex-encoded unprintable characters</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>hexquote</option> expansion item</primary>
+</indexterm>
+This operator converts non-printable characters in a string into a hex
+escape form. Byte values between 33 (!) and 126 (~) inclusive are left
+as is, and other byte values are converted to <literal>\xNN</literal>, for example, a
+byte value 127 is converted to <literal>\x7f</literal>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${ipv6denorm:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>ipv6denorm</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>normalisation</secondary>
+</indexterm>
+This expands an IPv6 address to a full eight-element colon-separated set
+of hex digits including leading zeroes.
+A trailing ipv4-style dotted-decimal set is converted to hex.
+Pure IPv4 addresses are converted to IPv4-mapped IPv6.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${ipv6norm:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>ipv6norm</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>normalisation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>canonical form</secondary>
+</indexterm>
+This converts an IPv6 address to canonical form.
+Leading zeroes of groups are omitted, and the longest
+set of zero-valued groups is replaced with a double colon.
+A trailing ipv4-style dotted-decimal set is converted to hex.
+Pure IPv4 addresses are converted to IPv4-mapped IPv6.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${lc:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>case forcing in strings</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>case forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>lower casing</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>case forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>lc</option> expansion item</primary>
+</indexterm>
+This forces the letters in the string into lower-case, for example:
+</para>
+<literallayout class="monospaced">
+${lc:$local_part}
+</literallayout>
+<para>
+Case is defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${length_</emphasis>&lt;<emphasis>number</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string truncation</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>length</option> expansion item</primary>
+</indexterm>
+The <option>length</option> operator is a simpler interface to the <option>length</option> function that
+can be used when the parameter is a fixed number (as opposed to a string that
+changes when expanded). The effect is the same as
+</para>
+<literallayout class="monospaced">
+${length{&lt;number&gt;}{&lt;string&gt;}}
+</literallayout>
+<para>
+See the description of the general <option>length</option> item above for details. Note that
+<option>length</option> is not the same as <option>strlen</option>. The abbreviation <option>l</option> can be used
+when <option>length</option> is used as an operator.
+All measurement is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${listcount:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>list item count</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>item count</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>count of items</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>listcount</option> expansion item</primary>
+</indexterm>
+The string is interpreted as a list and the number of items is returned.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${listnamed:</emphasis>&lt;<emphasis>name</emphasis>&gt;<emphasis role="bold">}</emphasis>&nbsp;and&nbsp;<emphasis role="bold">${listnamed_</emphasis>&lt;<emphasis>type</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>name</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>named list</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>listnamed</option> expansion item</primary>
+</indexterm>
+The name is interpreted as a named list and the content of the list is returned,
+expanding any referenced lists, re-quoting as needed for colon-separation.
+If the optional type is given it must be one of "a", "d", "h" or "l"
+and selects address-, domain-, host- or localpart- lists to search among respectively.
+Otherwise all types are searched in an undefined order and the first
+matching list is returned.
+</para>
+<para revisionflag="changed">
+<emphasis role="bold">Note</emphasis>: Neither string-expansion of lists referenced by named-list syntax elements,
+nor expansion of lookup elements, is done by the <option>listnamed</option> operator.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${local_part:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>local part extraction</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>local_part</option> expansion item</primary>
+</indexterm>
+The string is interpreted as an RFC 2822 address and the local part is
+extracted from it. If the string does not parse successfully, the result is
+empty.
+The parsing correctly handles SMTPUTF8 Unicode in the string.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${mask:</emphasis>&lt;<emphasis>IP&nbsp;address</emphasis>&gt;<emphasis role="bold">/</emphasis>&lt;<emphasis>bit&nbsp;count</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>masked IP address</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>masking</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>CIDR notation</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>IP address masking</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>mask</option> expansion item</primary>
+</indexterm>
+If the form of the string to be operated on is not an IP address followed by a
+slash and an integer (that is, a network address in CIDR notation), the
+expansion fails. Otherwise, this operator converts the IP address to binary,
+masks off the least significant bits according to the bit count, and converts
+the result back to text, with mask appended. For example,
+</para>
+<literallayout class="monospaced">
+${mask:10.111.131.206/28}
+</literallayout>
+<para>
+returns the string <quote>10.111.131.192/28</quote>. Since this operation is expected to
+be mostly used for looking up masked addresses in files, the 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,
+</para>
+<literallayout class="monospaced">
+${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99}
+</literallayout>
+<para>
+returns the string
+</para>
+<literallayout class="monospaced">
+3ffe.ffff.836f.0a00.000a.0800.2000.0000/99
+</literallayout>
+<para>
+Letters in IPv6 addresses are always output in lower case.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${md5:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>MD5 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>MD5 hash</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>certificate</primary>
+<secondary>fingerprint</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>md5</option> expansion item</primary>
+</indexterm>
+The <option>md5</option> operator computes the MD5 hash value of the string, and returns it
+as a 32-digit hexadecimal number, in which any letters are in lower case.
+</para>
+<para>
+If the string is a single variable of type certificate,
+returns the MD5 hash fingerprint of the certificate.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${nhash_</emphasis>&lt;<emphasis>n</emphasis>&gt;<emphasis role="bold">_</emphasis>&lt;<emphasis>m</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>numeric hash</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>hash function</primary>
+<secondary>numeric</secondary>
+</indexterm>
+The <option>nhash</option> operator is a simpler interface to the numeric hashing function
+that can be used when the two parameters are fixed numbers (as opposed to
+strings that change when expanded). The effect is the same as
+</para>
+<literallayout class="monospaced">
+${nhash{&lt;n&gt;}{&lt;m&gt;}{&lt;string&gt;}}
+</literallayout>
+<para>
+See the description of the general <option>nhash</option> item above for details.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${quote:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>in string expansions</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>quoting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>quote</option> expansion item</primary>
+</indexterm>
+The <option>quote</option> operator puts its argument into double quotes if it
+is an empty string or
+contains anything other than letters, digits, underscores, dots, and hyphens.
+Any occurrences of double quotes and backslashes are escaped with a backslash.
+Newlines and carriage returns are converted to <literal>\n</literal> and <literal>\r</literal>,
+respectively For example,
+</para>
+<literallayout class="monospaced">
+${quote:ab"*"cd}
+</literallayout>
+<para>
+becomes
+</para>
+<literallayout class="monospaced">
+"ab\"*\"cd"
+</literallayout>
+<para>
+The place where this is useful is when the argument is a substitution from a
+variable or a message header.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${quote_local_part:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>quote_local_part</option> expansion item</primary>
+</indexterm>
+This operator is like <option>quote</option>, except that it quotes the string only if
+required to do so by the rules of RFC 2822 for quoting local parts. For
+example, a plus sign would not cause quoting (but it would for <option>quote</option>).
+If you are creating a new email address from the contents of <varname>$local_part</varname>
+(or any other unknown data), you should always use this operator.
+</para>
+<para>
+This quoting determination is not SMTPUTF8-aware, thus quoting non-ASCII data
+will likely use the quoting form.
+Thus <emphasis>${quote_local_part:フィル}</emphasis> will always become <emphasis>"フィル"</emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${quote_</emphasis>&lt;<emphasis>lookup-type</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>lookup-specific</secondary>
+</indexterm>
+This operator applies lookup-specific quoting rules to the string. Each
+query-style lookup type has its own quoting rules which are described with
+the lookups in chapter <xref linkend="CHAPfdlookup"/>. For example,
+</para>
+<literallayout class="monospaced">
+${quote_ldap:two * two}
+</literallayout>
+<para>
+returns
+</para>
+<literallayout class="monospaced">
+two%20%5C2A%20two
+</literallayout>
+<para>
+For single-key lookup types, no quoting is ever necessary and this operator
+yields an unchanged string.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${randint:</emphasis>&lt;<emphasis>n</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>random number</primary>
+</indexterm>
+This operator returns a somewhat random number which is less than the
+supplied number and is at least 0.  The quality of this randomness depends
+on how Exim was built; the values are not suitable for keying material.
+If Exim is linked against OpenSSL then RAND_pseudo_bytes() is used.
+If Exim is linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used,
+for versions of GnuTLS with that function.
+Otherwise, the implementation may be arc4random(), random() seeded by
+srandomdev() or srandom(), or a custom implementation even weaker than
+random().
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${reverse_ip:</emphasis>&lt;<emphasis>ipaddr</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>IP address</secondary>
+</indexterm>
+This operator reverses an IP address; for IPv4 addresses, the result is in
+dotted-quad decimal form, while for IPv6 addresses the result is in
+dotted-nibble hexadecimal form.  In both cases, this is the "natural" form
+for DNS.  For example,
+</para>
+<literallayout class="monospaced">
+${reverse_ip:192.0.2.4}
+${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127}
+</literallayout>
+<para>
+returns
+</para>
+<literallayout class="monospaced">
+4.2.0.192
+f.7.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${rfc2047:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>RFC 2047</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>RFC 2047</primary>
+<secondary>expansion operator</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>rfc2047</option> expansion item</primary>
+</indexterm>
+This operator encodes text according to the rules of RFC 2047. This is an
+encoding that is used in header lines to encode non-ASCII characters. It is
+assumed that the input string is in the encoding specified by the
+<option>headers_charset</option> option, which gets its default at build time. If the string
+contains only characters in the range 33&ndash;126, and no instances of the
+characters
+</para>
+<literallayout class="monospaced">
+? = ( ) &lt; &gt; @ , ; : \ " . [ ] _
+</literallayout>
+<para>
+it is not modified. Otherwise, the result is the RFC 2047 encoding of the
+string, using as many <quote>encoded words</quote> as necessary to encode all the
+characters.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${rfc2047d:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>RFC 2047</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>RFC 2047</primary>
+<secondary>decoding</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>rfc2047d</option> expansion item</primary>
+</indexterm>
+This operator decodes strings that are encoded as per RFC 2047. Binary zero
+bytes are replaced by question marks. Characters are converted into the
+character set defined by <option>headers_charset</option>. Overlong RFC 2047 <quote>words</quote> are
+not recognized unless <option>check_rfc2047_length</option> is set false.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: If you use <option>$header</option>_<emphasis>xxx</emphasis><emphasis role="bold">:</emphasis> (or <option>$h</option>_<emphasis>xxx</emphasis><emphasis role="bold">:</emphasis>) to
+access a header line, RFC 2047 decoding is done automatically. You do not need
+to use this operator as well.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${rxquote:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>quoting</primary>
+<secondary>in regular expressions</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>quoting</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>rxquote</option> expansion item</primary>
+</indexterm>
+The <option>rxquote</option> operator inserts a backslash before any non-alphanumeric
+characters in its argument. This is useful when substituting the values of
+variables or headers inside regular expressions.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${sha1:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>SHA-1 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>SHA-1 hashing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>certificate</primary>
+<secondary>fingerprint</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>sha1</option> expansion item</primary>
+</indexterm>
+The <option>sha1</option> operator computes the SHA-1 hash value of the string, and returns
+it as a 40-digit hexadecimal number, in which any letters are in upper case.
+</para>
+<para>
+If the string is a single variable of type certificate,
+returns the SHA-1 hash fingerprint of the certificate.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${sha256:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${sha2:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${sha2_&lt;n&gt;:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>SHA-256 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>SHA-2 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>certificate</primary>
+<secondary>fingerprint</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>SHA-256 hashing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>sha256</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>sha2</option> expansion item</primary>
+</indexterm>
+The <option>sha256</option> operator computes the SHA-256 hash value of the string
+and returns
+it as a 64-digit hexadecimal number, in which any letters are in upper case.
+</para>
+<para>
+If the string is a single variable of type certificate,
+returns the SHA-256 hash fingerprint of the certificate.
+</para>
+<para>
+The operator can also be spelled <option>sha2</option> and does the same as <option>sha256</option>
+(except for certificates, which are not supported).
+Finally, if an underbar
+and a number is appended it specifies the output length, selecting a
+member of the SHA-2 family of hash functions.
+Values of 256, 384 and 512 are accepted, with 256 being the default.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${sha3:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${sha3_&lt;n&gt;:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>SHA3 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>SHA3 hashing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>sha3</option> expansion item</primary>
+</indexterm>
+The <option>sha3</option> operator computes the SHA3-256 hash value of the string
+and returns
+it as a 64-digit hexadecimal number, in which any letters are in upper case.
+</para>
+<para>
+If a number is appended, separated by an underbar, it specifies
+the output length.  Values of 224, 256, 384 and 512 are accepted;
+with 256 being the default.
+</para>
+<para>
+The <option>sha3</option> expansion item is only supported if Exim has been
+compiled with GnuTLS 3.5.0 or later,
+or OpenSSL 1.1.1 or later.
+The macro "_CRYPTO_HASH_SHA3" will be defined if it is supported.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${stat:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>statting a file</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>extracting characteristics</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>stat</option> expansion item</primary>
+</indexterm>
+The string, after expansion, must be a file path. A call to the <function>stat()</function>
+function is made for this path. If <function>stat()</function> fails, an error occurs and the
+expansion fails. If it succeeds, the data from the stat replaces the item, as a
+series of &lt;<emphasis>name</emphasis>&gt;=&lt;<emphasis>value</emphasis>&gt; pairs, where the values are all numerical,
+except for the value of <quote>smode</quote>. The names are: <quote>mode</quote> (giving the mode as
+a 4-digit octal number), <quote>smode</quote> (giving the mode in symbolic format as a
+10-character string, as for the <emphasis>ls</emphasis> command), <quote>inode</quote>, <quote>device</quote>,
+<quote>links</quote>, <quote>uid</quote>, <quote>gid</quote>, <quote>size</quote>, <quote>atime</quote>, <quote>mtime</quote>, and <quote>ctime</quote>. You
+can extract individual fields using the <option>extract</option> expansion item.
+</para>
+<para>
+The use of the <option>stat</option> expansion in users&#x2019; filter files can be locked out by
+the system administrator. <emphasis role="bold">Warning</emphasis>: The file size may be incorrect on 32-bit
+systems for files larger than 2GB.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${str2b64:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>str2b64</option> expansion item</primary>
+</indexterm>
+Now deprecated, a synonym for the <option>base64</option> expansion operator.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${strlen:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string length</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>length in expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>strlen</option> expansion item</primary>
+</indexterm>
+The item is replaced by the length of the expanded string, expressed as a
+decimal number. <emphasis role="bold">Note</emphasis>: Do not confuse <option>strlen</option> with <option>length</option>.
+All measurement is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${substr_</emphasis>&lt;<emphasis>start</emphasis>&gt;<emphasis role="bold">_</emphasis>&lt;<emphasis>length</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>substr</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>substring extraction</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>substring expansion</secondary>
+</indexterm>
+The <option>substr</option> operator is a simpler interface to the <option>substr</option> function that
+can be used when the two parameters are fixed numbers (as opposed to strings
+that change when expanded). The effect is the same as
+</para>
+<literallayout class="monospaced">
+${substr{&lt;start&gt;}{&lt;length&gt;}{&lt;string&gt;}}
+</literallayout>
+<para>
+See the description of the general <option>substr</option> item above for details. The
+abbreviation <option>s</option> can be used when <option>substr</option> is used as an operator.
+All measurement is done in bytes and is not UTF-8 aware.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${time_eval:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>time_eval</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>time interval</primary>
+<secondary>decoding</secondary>
+</indexterm>
+This item converts an Exim time interval such as <literal>2d4h5m</literal> into a number of
+seconds.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${time_interval:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>time_interval</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>time interval</primary>
+<secondary>formatting</secondary>
+</indexterm>
+The argument (after sub-expansion) must be a sequence of decimal digits that
+represents an interval of time as a number of seconds. It is converted into a
+number of larger units and output in Exim&#x2019;s normal time format, for example,
+<literal>1w3d4h2m6s</literal>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${uc:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>case forcing in strings</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>case forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>upper casing</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>case forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>uc</option> expansion item</primary>
+</indexterm>
+This forces the letters in the string into upper-case.
+Case is defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${utf8clean:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>correction of invalid utf-8 sequences in strings</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>utf-8</primary>
+<secondary>utf-8 sequences</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>incorrect utf-8</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>utf-8 forcing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>utf8clean</option> expansion item</primary>
+</indexterm>
+This replaces any invalid utf-8 sequence in the string by the character <literal>?</literal>.
+In versions of Exim before 4.92, this did not correctly do so for a truncated
+final codepoint&#x2019;s encoding, and the character would be silently dropped.
+If you must handle detection of this scenario across both sets of Exim behavior,
+the complexity will depend upon the task.
+For instance, to detect if the first character is multibyte and a 1-byte
+extraction can be successfully used as a path component (as is common for
+dividing up delivery folders), you might use:
+</para>
+<literallayout class="monospaced">
+condition = ${if inlist{${utf8clean:${length_1:$local_part}}}{:?}{yes}{no}}
+</literallayout>
+<para>
+(which will false-positive if the first character of the local part is a
+literal question mark).
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">${utf8_domain_to_alabel:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${utf8_domain_from_alabel:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${utf8_localpart_to_alabel:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">${utf8_localpart_from_alabel:</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>UTF-8</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>UTF-8</primary>
+<secondary>expansion</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>EAI</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>internationalisation</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>utf8_domain_to_alabel</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>utf8_domain_from_alabel</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>utf8_localpart_to_alabel</option> expansion item</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>utf8_localpart_from_alabel</option> expansion item</primary>
+</indexterm>
+These convert EAI mail name components between UTF-8 and a-label forms.
+For information on internationalisation support see <xref linkend="SECTi18nMTA"/>.
+</para>
+</listitem></varlistentry>
+</variablelist>
+</section>
+<section id="SECTexpcond">
+<title>Expansion conditions</title>
+<para>
+<indexterm role="concept" id="IIDexpcond" class="startofrange">
+<primary>expansion</primary>
+<secondary>conditions</secondary>
+</indexterm>
+The following conditions are available for testing by the <option>${if</option> construct
+while expanding strings:
+</para>
+<variablelist>
+<varlistentry>
+<term><emphasis role="bold">!</emphasis>&lt;<emphasis>condition</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>negating a condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>negation</primary>
+<secondary>in expansion condition</secondary>
+</indexterm>
+Preceding any condition with an exclamation mark negates the result of the
+condition.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term>&lt;<emphasis>symbolic&nbsp;operator</emphasis>&gt;&nbsp;<emphasis role="bold">{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>numeric comparison</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>numeric comparison</secondary>
+</indexterm>
+There are a number of symbolic operators for doing numeric comparisons. They
+are:
+</para>
+<literallayout>
+<literal>=   </literal>   equal
+<literal>==  </literal>   equal
+<literal>&gt;   </literal>   greater
+<literal>&gt;=  </literal>   greater or equal
+<literal>&lt;   </literal>   less
+<literal>&lt;=  </literal>   less or equal
+</literallayout>
+<para>
+For example:
+</para>
+<literallayout class="monospaced">
+${if &gt;{$message_size}{10M} ...
+</literallayout>
+<para>
+Note that the general negation operator provides for inequality testing. The
+two strings must take the form of optionally signed decimal integers,
+optionally followed by one of the letters <quote>K</quote>, <quote>M</quote> or <quote>G</quote> (in either upper or
+lower case), signifying multiplication by 1024, 1024*1024 or 1024*1024*1024, respectively.
+As a special case, the numerical value of an empty string is taken as
+zero.
+</para>
+<para>
+In all cases, a relative comparator OP is testing if &lt;<emphasis>string1</emphasis>&gt; OP
+&lt;<emphasis>string2</emphasis>&gt;; the above example is checking if <varname>$message_size</varname> is larger than
+10M, not if 10M is larger than <varname>$message_size</varname>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">acl&nbsp;{{</emphasis>&lt;<emphasis>name</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>arg2</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>calling an acl</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>acl</option></primary>
+<secondary>expansion condition</secondary>
+</indexterm>
+The name and zero to nine argument strings are first expanded separately.  The expanded
+arguments are assigned to the variables <varname>$acl_arg1</varname> to <varname>$acl_arg9</varname> in order.
+Any unused are made empty.  The variable <varname>$acl_narg</varname> is set to the number of
+arguments.  The named ACL (see chapter <xref linkend="CHAPACL"/>) is called
+and may use the variables; if another acl expansion is used the values
+are restored after it returns.  If the ACL sets
+a value using a "message =" modifier the variable $value becomes
+the result of the expansion, otherwise it is empty.
+If the ACL returns accept the condition is true; if deny, false.
+If the ACL returns defer the result is a forced-fail.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">bool&nbsp;{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>boolean parsing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>bool</option> expansion condition</primary>
+</indexterm>
+This condition turns a string holding a true or false representation into
+a boolean state.  It parses <quote>true</quote>, <quote>false</quote>, <quote>yes</quote> and <quote>no</quote>
+(case-insensitively); also integer numbers map to true if non-zero,
+false if zero.
+An empty string is treated as false.
+Leading and trailing whitespace is ignored;
+thus a string consisting only of whitespace is false.
+All other string values will result in expansion failure.
+</para>
+<para>
+When combined with ACL variables, this expansion condition will let you
+make decisions in one place and act on those decisions in another place.
+For example:
+</para>
+<literallayout class="monospaced">
+${if bool{$acl_m_privileged_sender} ...
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">bool_lax&nbsp;{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>boolean parsing</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>bool_lax</option> expansion condition</primary>
+</indexterm>
+Like <option>bool</option>, this condition turns a string into a boolean state.  But
+where <option>bool</option> accepts a strict set of strings, <option>bool_lax</option> uses the same
+loose definition that the Router <option>condition</option> option uses.  The empty string
+and the values <quote>false</quote>, <quote>no</quote> and <quote>0</quote> map to false, all others map to
+true.  Leading and trailing whitespace is ignored.
+</para>
+<para>
+Note that where <quote>bool{00}</quote> is false, <quote>bool_lax{00}</quote> is true.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">crypteq&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>encrypted comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>encrypted strings, comparing</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>crypteq</option> expansion condition</primary>
+</indexterm>
+This condition is included in the Exim binary if it is built to support any
+authentication mechanisms (see chapter <xref linkend="CHAPSMTPAUTH"/>). Otherwise, it is
+necessary to define SUPPORT_CRYPTEQ in <filename>Local/Makefile</filename> to get <option>crypteq</option>
+included in the binary.
+</para>
+<para>
+The <option>crypteq</option> condition has two arguments. The first is encrypted and
+compared against the second, which is already encrypted. The second string may
+be in the LDAP form for storing encrypted strings, which starts with the
+encryption type in curly brackets, followed by the data. If the second string
+does not begin with <quote>{</quote> it is assumed to be encrypted with <function>crypt()</function> or
+<function>crypt16()</function> (see below), since such strings cannot begin with <quote>{</quote>.
+Typically this will be a field from a password file. An example of an encrypted
+string in LDAP form is:
+</para>
+<literallayout class="monospaced">
+{md5}CY9rzUYh03PK3k6DJie09g==
+</literallayout>
+<para>
+If such a string appears directly in an expansion, the curly brackets have to
+be quoted, because they are part of the expansion syntax. For example:
+</para>
+<literallayout class="monospaced">
+${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}}
+</literallayout>
+<para>
+The following encryption types (whose names are matched case-independently) are
+supported:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>MD5 hash</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>base64 encoding</primary>
+<secondary>in encrypted password</secondary>
+</indexterm>
+<option>{md5}</option> computes the MD5 digest of the first string, and expresses this as
+printable characters to compare with the remainder of the second string. If the
+length of the comparison string is 24, Exim assumes that it is base64 encoded
+(as in the above example). If the length is 32, Exim assumes that it is a
+hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the
+comparison fails.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>SHA-1 hash</primary>
+</indexterm>
+<option>{sha1}</option> computes the SHA-1 digest of the first string, and expresses this as
+printable characters to compare with the remainder of the second string. If the
+length of the comparison string is 28, Exim assumes that it is base64 encoded.
+If the length is 40, Exim assumes that it is a hexadecimal encoding of the
+SHA-1 digest. If the length is not 28 or 40, the comparison fails.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><function>crypt()</function></primary>
+</indexterm>
+<option>{crypt}</option> calls the <function>crypt()</function> function, which traditionally used to use
+only the first eight characters of the password. However, in modern operating
+systems this is no longer true, and in many cases the entire password is used,
+whatever its length.
+</para>
+</listitem>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><function>crypt16()</function></primary>
+</indexterm>
+<option>{crypt16}</option> calls the <function>crypt16()</function> function, which was originally created to
+use up to 16 characters of the password in some operating systems. Again, in
+modern operating systems, more characters may be used.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Exim has its own version of <function>crypt16()</function>, which is just a double call to
+<function>crypt()</function>. For operating systems that have their own version, setting
+HAVE_CRYPT16 in <filename>Local/Makefile</filename> when building Exim causes it to use the
+operating system version instead of its own. This option is set by default in
+the OS-dependent <filename>Makefile</filename> for those operating systems that are known to
+support <function>crypt16()</function>.
+</para>
+<para>
+Some years after Exim&#x2019;s <function>crypt16()</function> was implemented, a user discovered that
+it was not using the same algorithm as some operating systems&#x2019; versions. It
+turns out that as well as <function>crypt16()</function> there is a function called
+<function>bigcrypt()</function> in some operating systems. This may or may not use the same
+algorithm, and both of them may be different to Exim&#x2019;s built-in <function>crypt16()</function>.
+</para>
+<para>
+However, since there is now a move away from the traditional <function>crypt()</function>
+functions towards using SHA1 and other algorithms, tidying up this area of
+Exim is seen as very low priority.
+</para>
+<para>
+If you do not put a encryption type (in curly brackets) in a <option>crypteq</option>
+comparison, the default is usually either <literal>{crypt}</literal> or <literal>{crypt16}</literal>, as
+determined by the setting of DEFAULT_CRYPT in <filename>Local/Makefile</filename>. The default
+default is <literal>{crypt}</literal>. Whatever the default, you can always use either
+function by specifying it explicitly in curly brackets.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">def:</emphasis>&lt;<emphasis>variable&nbsp;name</emphasis>&gt;</term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>checking for empty variable</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>def</option> expansion condition</primary>
+</indexterm>
+The <option>def</option> condition must be followed by the name of one of the expansion
+variables defined in section <xref linkend="SECTexpvar"/>. The condition is true if the
+variable does not contain the empty string. For example:
+</para>
+<literallayout class="monospaced">
+${if def:sender_ident {from $sender_ident}}
+</literallayout>
+<para>
+Note that the variable name is given without a leading <option>$</option> character. If the
+variable does not exist, the expansion fails.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">def:header_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis>&nbsp;&nbsp;or&nbsp;&nbsp;<emphasis role="bold">def:h_</emphasis>&lt;<emphasis>header&nbsp;name</emphasis>&gt;<emphasis role="bold">:</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>checking header line existence</secondary>
+</indexterm>
+This condition is true if a message is being processed and the named header
+exists in the message. For example,
+</para>
+<literallayout class="monospaced">
+${if def:header_reply-to:{$h_reply-to:}{$h_from:}}
+</literallayout>
+<para>
+<emphasis role="bold">Note</emphasis>: No <option>$</option> appears before <option>header_</option> or <option>h_</option> in the condition, and
+the header name must be terminated by a colon if white space does not follow.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">eq&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">eqi&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>eq</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>eqi</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The condition is true if the two
+resulting strings are identical. For <option>eq</option> the comparison includes the case of
+letters, whereas for <option>eqi</option> the comparison is case-independent, where
+case is defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">exists&nbsp;{</emphasis>&lt;<emphasis>file&nbsp;name</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>file existence test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>file</primary>
+<secondary>existence test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>exists</option>, expansion condition</primary>
+</indexterm>
+The substring is first expanded and then interpreted as an absolute path. The
+condition is true if the named file (or directory) exists. The existence test
+is done by calling the <function>stat()</function> function. The use of the <option>exists</option> test in
+users&#x2019; filter files may be locked out by the system administrator.
+</para>
+<para revisionflag="changed">
+<emphasis role="bold">Note:</emphasis> Testing a path using this condition is not a sufficient way of
+de-tainting it.
+Consider using a dsearch lookup.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">first_delivery</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>delivery</primary>
+<secondary>first</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>first delivery</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>first delivery test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>first_delivery</option> expansion condition</primary>
+</indexterm>
+This condition, which has no data, is true during a message&#x2019;s first delivery
+attempt. It is false during any subsequent delivery attempts.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">forall{</emphasis>&lt;<emphasis>a list</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">forany{</emphasis>&lt;<emphasis>a list</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>iterative conditions</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forall</emphasis> condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forany</emphasis> condition</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$item</varname></primary>
+</indexterm>
+These conditions iterate over a list. The first argument is expanded to form
+the list. By default, the list separator is a colon, but it can be changed by
+the normal method (<xref linkend="SECTlistsepchange"/>).
+The second argument is interpreted as a condition that is to
+be applied to each item in the list in turn. During the interpretation of the
+condition, the current list item is placed in a variable called <varname>$item</varname>.
+</para>
+<itemizedlist>
+<listitem>
+<para>
+For <emphasis role="bold">forany</emphasis>, interpretation stops if the condition is true for any item, and
+the result of the whole condition is true. If the condition is false for all
+items in the list, the overall condition is false.
+</para>
+</listitem>
+<listitem>
+<para>
+For <emphasis role="bold">forall</emphasis>, interpretation stops if the condition is false for any item,
+and the result of the whole condition is false. If the condition is true for
+all items in the list, the overall condition is true.
+</para>
+</listitem>
+</itemizedlist>
+<para>
+Note that negation of <emphasis role="bold">forany</emphasis> means that the condition must be false for all
+items for the overall condition to succeed, and negation of <emphasis role="bold">forall</emphasis> means
+that the condition must be false for at least one item. In this example, the
+list separator is changed to a comma:
+</para>
+<literallayout class="monospaced">
+${if forany{&lt;, $recipients}{match{$item}{^user3@}}{yes}{no}}
+</literallayout>
+<para>
+The value of <varname>$item</varname> is saved and restored while <option>forany</option> or <option>forall</option> is
+being processed, to enable these expansion items to be nested.
+</para>
+<para>
+To scan a named list, expand it with the <emphasis role="bold">listnamed</emphasis> operator.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">forall_json{</emphasis>&lt;<emphasis>a JSON array</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">forany_json{</emphasis>&lt;<emphasis>a JSON array</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">forall_jsons{</emphasis>&lt;<emphasis>a JSON array</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">forany_jsons{</emphasis>&lt;<emphasis>a JSON array</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>a condition</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>JSON</primary>
+<secondary>iterative conditions</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>JSON</primary>
+<secondary>expansions</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forall_json</emphasis> condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forany_json</emphasis> condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forall_jsons</emphasis> condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis role="bold">forany_jsons</emphasis> condition</secondary>
+</indexterm>
+As for the above, except that the first argument must, after expansion,
+be a JSON array.
+The array separator is not changeable.
+For the <quote>jsons</quote> variants the elements are expected to be JSON strings
+and have their quotes removed before the evaluation of the condition.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">ge&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">gei&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>ge</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>gei</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The condition is true if the first
+string is lexically greater than or equal to the second string. For <option>ge</option> the
+comparison includes the case of letters, whereas for <option>gei</option> the comparison is
+case-independent.
+Case and collation order are defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">gt&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">gti&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>gt</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>gti</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The condition is true if the first
+string is lexically greater than the second string. For <option>gt</option> the comparison
+includes the case of letters, whereas for <option>gti</option> the comparison is
+case-independent.
+Case and collation order are defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry revisionflag="changed">
+<term><emphasis role="bold">inbound_srs&nbsp;{</emphasis>&lt;<emphasis>local&nbsp;part</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>secret</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para revisionflag="changed">
+SRS decode.  See SECT <xref linkend="SECTSRS"/> for details.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">inlist&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">inlisti&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>list</primary>
+<secondary>iterative conditions</secondary>
+</indexterm>
+Both strings are expanded; the second string is treated as a list of simple
+strings; if the first string is a member of the second, then the condition
+is true.
+For the case-independent <option>inlisti</option> condition, case is defined per the system C locale.
+</para>
+<para>
+These are simpler to use versions of the more powerful <emphasis role="bold">forany</emphasis> condition.
+Examples, and the <emphasis role="bold">forany</emphasis> equivalents:
+</para>
+<literallayout class="monospaced">
+${if inlist{needle}{foo:needle:bar}}
+  ${if forany{foo:needle:bar}{eq{$item}{needle}}}
+${if inlisti{Needle}{fOo:NeeDLE:bAr}}
+  ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">isip&nbsp;{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">isip4&nbsp;{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">isip6&nbsp;{</emphasis>&lt;<emphasis>string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>IP address</primary>
+<secondary>testing string format</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>testing for IP address</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>isip</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>isip4</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>isip6</option> expansion condition</primary>
+</indexterm>
+The substring is first expanded, and then tested to see if it has the form of
+an IP address. Both IPv4 and IPv6 addresses are valid for <option>isip</option>, whereas
+<option>isip4</option> and <option>isip6</option> test specifically for IPv4 or IPv6 addresses.
+</para>
+<para>
+For an IPv4 address, the test is for four dot-separated components, each of
+which consists of from one to three digits. For an IPv6 address, up to eight
+colon-separated components are permitted, each containing from one to four
+hexadecimal digits. There may be fewer than eight components if an empty
+component (adjacent colons) is present. Only one empty component is permitted.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: The checks used to be just on the form of the address; actual numerical
+values were not considered. Thus, for example, 999.999.999.999 passed the IPv4
+check.
+This is no longer the case.
+</para>
+<para>
+The main use of these tests is to distinguish between IP addresses and
+host names, or between IPv4 and IPv6 addresses. For example, you could use
+</para>
+<literallayout class="monospaced">
+${if isip4{$sender_host_address}...
+</literallayout>
+<para>
+to test which IP version an incoming SMTP connection is using.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">ldapauth&nbsp;{</emphasis>&lt;<emphasis>ldap&nbsp;query</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>LDAP</primary>
+<secondary>use for authentication</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>LDAP authentication test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>ldapauth</option> expansion condition</primary>
+</indexterm>
+This condition supports user authentication using LDAP. See section
+<xref linkend="SECTldap"/> for details of how to use LDAP in lookups and the syntax of
+queries. For this use, the query must contain a user name and password. The
+query itself is not used, and can be empty. The condition is true if the
+password is not empty, and the user name and password are accepted by the LDAP
+server. An empty password is rejected without calling LDAP because LDAP binds
+with an empty password are considered anonymous regardless of the username, and
+will succeed in most configurations. See chapter <xref linkend="CHAPSMTPAUTH"/> for details
+of SMTP authentication, and chapter <xref linkend="CHAPplaintext"/> for an example of how
+this can be used.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">le&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">lei&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>le</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>lei</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The condition is true if the first
+string is lexically less than or equal to the second string. For <option>le</option> the
+comparison includes the case of letters, whereas for <option>lei</option> the comparison is
+case-independent.
+Case and collation order are defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">lt&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<term><emphasis role="bold">lti&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>string</primary>
+<secondary>comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>string comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>lt</option> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>lti</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The condition is true if the first
+string is lexically less than the second string. For <option>lt</option> the comparison
+includes the case of letters, whereas for <option>lti</option> the comparison is
+case-independent.
+Case and collation order are defined per the system C locale.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">match&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>regular expression comparison</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>regular expressions</primary>
+<secondary>match in expanded string</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>match</option> expansion condition</primary>
+</indexterm>
+The two substrings are first expanded. The second is then treated as a regular
+expression and applied to the first. Because of the pre-expansion, if the
+regular expression contains dollar, or backslash characters, they must be
+escaped. Care must also be taken if the regular expression contains braces
+(curly brackets). A closing brace must be escaped so that it is not taken as a
+premature termination of &lt;<emphasis>string2</emphasis>&gt;. The easiest approach is to use the
+<literal>\N</literal> feature to disable expansion of the regular expression.
+For example,
+</para>
+<literallayout class="monospaced">
+${if match {$local_part}{\N^\d{3}\N} ...
+</literallayout>
+<para>
+If the whole expansion string is in double quotes, further escaping of
+backslashes is also required.
+</para>
+<para>
+The condition is true if the regular expression match succeeds.
+The regular expression is not required to begin with a circumflex
+metacharacter, but if there is no circumflex, the expression is not anchored,
+and it may match anywhere in the subject, not just at the start. If you want
+the pattern to match at the end of the subject, you must include the <literal>$</literal>
+metacharacter at an appropriate point.
+All character handling is done in bytes and is not UTF-8 aware,
+but we might change this in a future Exim release.
+</para>
+<para>
+<indexterm role="concept">
+<primary>numerical variables (<varname>$1</varname> <varname>$2</varname> etc)</primary>
+<secondary>in <option>if</option> expansion</secondary>
+</indexterm>
+At the start of an <option>if</option> expansion the values of the numeric variable
+substitutions <varname>$1</varname> etc. are remembered. Obeying a <option>match</option> condition that
+succeeds causes them to be reset to the substrings of that condition and they
+will have these values during the expansion of the success string. At the end
+of the <option>if</option> expansion, the previous values are restored. After testing a
+combination of conditions using <option>or</option>, the subsequent values of the numeric
+variables are those of the condition that succeeded.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">match_address&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>match_address</option> expansion condition</primary>
+</indexterm>
+See <emphasis role="bold">match_local_part</emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">match_domain&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>match_domain</option> expansion condition</primary>
+</indexterm>
+See <emphasis role="bold">match_local_part</emphasis>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">match_ip&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><option>match_ip</option> expansion condition</primary>
+</indexterm>
+This condition matches an IP address to a list of IP address patterns. It must
+be followed by two argument strings. The first (after expansion) must be an IP
+address or an empty string. The second (not expanded) is a restricted host
+list that can match only an IP address, not a host name. For example:
+</para>
+<literallayout class="monospaced">
+${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
+</literallayout>
+<para>
+The specific types of host list item that are permitted in the list are:
+</para>
+<itemizedlist>
+<listitem>
+<para>
+An IP address, optionally with a CIDR mask.
+</para>
+</listitem>
+<listitem>
+<para>
+A single asterisk, which matches any IP address.
+</para>
+</listitem>
+<listitem>
+<para>
+An empty item, which matches only if the IP address is empty. This could be
+useful for testing for a locally submitted message or one from specific hosts
+in a single test such as
+</para>
+<literallayout class="monospaced">
+  ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
+</literallayout>
+<para>
+where the first item in the list is the empty string.
+</para>
+</listitem>
+<listitem>
+<para>
+The item @[] matches any of the local host&#x2019;s interface addresses.
+</para>
+</listitem>
+<listitem>
+<para>
+Single-key lookups are assumed to be like <quote>net-</quote> style lookups in host lists,
+even if <literal>net-</literal> is not specified. There is never any attempt to turn the IP
+address into a host name. The most common type of linear search for
+<emphasis role="bold">match_ip</emphasis> is likely to be <emphasis role="bold">iplsearch</emphasis>, in which the file can contain CIDR
+masks. For example:
+</para>
+<literallayout class="monospaced">
+  ${if match_ip{$sender_host_address}{iplsearch;/some/file}...
+</literallayout>
+<para>
+It is of course possible to use other kinds of lookup, and in such a case, you
+do need to specify the <literal>net-</literal> prefix if you want to specify a specific
+address mask, for example:
+</para>
+<literallayout class="monospaced">
+  ${if match_ip{$sender_host_address}{net24-dbm;/some/file}...
+</literallayout>
+<para>
+However, unless you are combining a <option>match_ip</option> condition with others, it is
+just as easy to use the fact that a lookup is itself a condition, and write:
+</para>
+<literallayout class="monospaced">
+  ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}...
+</literallayout>
+</listitem>
+</itemizedlist>
+<para>
+Note that &lt;<emphasis>string2</emphasis>&gt; is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+</para>
+<para>
+Consult section <xref linkend="SECThoslispatip"/> for further details of these patterns.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">match_local_part&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>domain list</primary>
+<secondary>in expansion condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>address list</primary>
+<secondary>in expansion condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>local part</primary>
+<secondary>list, in expansion condition</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>match_local_part</option> expansion condition</primary>
+</indexterm>
+This condition, together with <option>match_address</option> and <option>match_domain</option>, make it
+possible to test domain, address, and local part lists within expansions. Each
+condition requires two arguments: an item and a list to match. A trivial
+example is:
+</para>
+<literallayout class="monospaced">
+${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}}
+</literallayout>
+<para>
+In each case, the second argument may contain any of the allowable items for a
+list of the appropriate type. Also, because the second argument
+is a standard form of list, it is possible to refer to a named list.
+Thus, you can use conditions like this:
+</para>
+<literallayout class="monospaced">
+${if match_domain{$domain}{+local_domains}{...
+</literallayout>
+<para>
+<indexterm role="concept">
+<primary><literal>+caseful</literal></primary>
+</indexterm>
+For address lists, the matching starts off caselessly, but the <literal>+caseful</literal>
+item can be used, as in all address lists, to cause subsequent items to
+have their local parts matched casefully. Domains are always matched
+caselessly.
+</para>
+<para>
+Note that &lt;<emphasis>string2</emphasis>&gt; is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+</para>
+<para>
+<emphasis role="bold">Note</emphasis>: Host lists are <emphasis>not</emphasis> supported in this way. This is because
+hosts have two identities: a name and an IP address, and it is not clear
+how to specify cleanly how such a test would work. However, IP addresses can be
+matched using <option>match_ip</option>.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">pam&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">:...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>PAM authentication</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>AUTH</primary>
+<secondary>with PAM</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>Solaris</primary>
+<secondary>PAM support</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>PAM authentication test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>pam</option> expansion condition</primary>
+</indexterm>
+<emphasis>Pluggable Authentication Modules</emphasis>
+(<emphasis role="bold"><ulink url="https://mirrors.edge.kernel.org/pub/linux/libs/pam/">https://mirrors.edge.kernel.org/pub/linux/libs/pam/</ulink></emphasis>) are a facility that is
+available in the latest releases of Solaris and in some GNU/Linux
+distributions. The Exim support, which is intended for use in conjunction with
+the SMTP AUTH command, is available only if Exim is compiled with
+</para>
+<literallayout class="monospaced">
+SUPPORT_PAM=yes
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>. You probably need to add <option>-lpam</option> to EXTRALIBS, and
+in some releases of GNU/Linux <option>-ldl</option> is also needed.
+</para>
+<para>
+The argument string is first expanded, and the result must be a
+colon-separated list of strings. Leading and trailing white space is ignored.
+The PAM module is initialized with the service name <quote>exim</quote> and the user name
+taken from the first item in the colon-separated data string (&lt;<emphasis>string1</emphasis>&gt;).
+The remaining items in the data string are passed over in response to requests
+from the authentication function. In the simple case there will only be one
+request, for a password, so the data consists of just two strings.
+</para>
+<para>
+There can be problems if any of the strings are permitted to contain colon
+characters. In the usual way, these have to be doubled to avoid being taken as
+separators.
+The <option>listquote</option> expansion item can be used for this.
+For example, the configuration
+of a LOGIN authenticator might contain this setting:
+</para>
+<literallayout class="monospaced">
+server_condition = ${if pam{$auth1:${listquote{:}{$auth2}}}}
+</literallayout>
+<para>
+In some operating systems, PAM authentication can be done only from a process
+running as root. Since Exim is running as the Exim user when receiving
+messages, this means that PAM cannot be used directly in those systems.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">pwcheck&nbsp;{</emphasis>&lt;<emphasis>string1</emphasis>&gt;<emphasis role="bold">:</emphasis>&lt;<emphasis>string2</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><emphasis>pwcheck</emphasis> daemon</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Cyrus</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis>pwcheck</emphasis> authentication test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>pwcheck</option> expansion condition</primary>
+</indexterm>
+This condition supports user authentication using the Cyrus <emphasis>pwcheck</emphasis> daemon.
+This is one way of making it possible for passwords to be checked by a process
+that is not running as root. <emphasis role="bold">Note</emphasis>: The use of <emphasis>pwcheck</emphasis> is now
+deprecated. Its replacement is <emphasis>saslauthd</emphasis> (see below).
+</para>
+<para>
+The pwcheck support is not included in Exim by default. You need to specify
+the location of the pwcheck daemon&#x2019;s socket in <filename>Local/Makefile</filename> before
+building Exim. For example:
+</para>
+<literallayout class="monospaced">
+CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck
+</literallayout>
+<para>
+You do not need to install the full Cyrus software suite in order to use
+the pwcheck daemon. You can compile and install just the daemon alone
+from the Cyrus SASL library. Ensure that <emphasis>exim</emphasis> is the only user that has
+access to the <filename>/var/pwcheck</filename> directory.
+</para>
+<para>
+The <option>pwcheck</option> condition takes one argument, which must be the user name and
+password, separated by a colon. For example, in a LOGIN authenticator
+configuration, you might have this:
+</para>
+<literallayout class="monospaced">
+server_condition = ${if pwcheck{$auth1:$auth2}}
+</literallayout>
+<para>
+Again, for a PLAIN authenticator configuration, this would be:
+</para>
+<literallayout class="monospaced">
+server_condition = ${if pwcheck{$auth2:$auth3}}
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">queue_running</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>queue runner</primary>
+<secondary>detecting when delivering from</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>queue runner test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>queue_running</option> expansion condition</primary>
+</indexterm>
+This condition, which has no data, is true during delivery attempts that are
+initiated by queue runner processes, and false otherwise.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">radius&nbsp;{</emphasis>&lt;<emphasis>authentication&nbsp;string</emphasis>&gt;<emphasis role="bold">}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>Radius</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>Radius authentication</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>radius</option> expansion condition</primary>
+</indexterm>
+Radius authentication (RFC 2865) is supported in a similar way to PAM. You must
+set RADIUS_CONFIG_FILE in <filename>Local/Makefile</filename> to specify the location of
+the Radius client configuration file in order to build Exim with Radius
+support.
+</para>
+<para>
+With just that one setting, Exim expects to be linked with the <option>radiusclient</option>
+library, using the original API. If you are using release 0.4.0 or later of
+this library, you need to set
+</para>
+<literallayout class="monospaced">
+RADIUS_LIB_TYPE=RADIUSCLIENTNEW
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename> when building Exim. You can also link Exim with the
+<option>libradius</option> library that comes with FreeBSD. To do this, set
+</para>
+<literallayout class="monospaced">
+RADIUS_LIB_TYPE=RADLIB
+</literallayout>
+<para>
+in <filename>Local/Makefile</filename>, in addition to setting RADIUS_CONFIGURE_FILE.
+You may also have to supply a suitable setting in EXTRALIBS so that the
+Radius library can be found when Exim is linked.
+</para>
+<para>
+The string specified by RADIUS_CONFIG_FILE is expanded and passed to the
+Radius client library, which calls the Radius server. The condition is true if
+the authentication is successful. For example:
+</para>
+<literallayout class="monospaced">
+server_condition = ${if radius{&lt;arguments&gt;}}
+</literallayout>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">saslauthd&nbsp;{{</emphasis>&lt;<emphasis>user</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>password</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>service</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>realm</emphasis>&gt;<emphasis role="bold">}}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><emphasis>saslauthd</emphasis> daemon</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>Cyrus</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><emphasis>saslauthd</emphasis> authentication test</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary><option>saslauthd</option> expansion condition</primary>
+</indexterm>
+This condition supports user authentication using the Cyrus <emphasis>saslauthd</emphasis>
+daemon. This replaces the older <emphasis>pwcheck</emphasis> daemon, which is now deprecated.
+Using this daemon is one way of making it possible for passwords to be checked
+by a process that is not running as root.
+</para>
+<para>
+The saslauthd support is not included in Exim by default. You need to specify
+the location of the saslauthd daemon&#x2019;s socket in <filename>Local/Makefile</filename> before
+building Exim. For example:
+</para>
+<literallayout class="monospaced">
+CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux
+</literallayout>
+<para>
+You do not need to install the full Cyrus software suite in order to use
+the saslauthd daemon. You can compile and install just the daemon alone
+from the Cyrus SASL library.
+</para>
+<para>
+Up to four arguments can be supplied to the <option>saslauthd</option> condition, but only
+two are mandatory. For example:
+</para>
+<literallayout class="monospaced">
+server_condition = ${if saslauthd{{$auth1}{$auth2}}}
+</literallayout>
+<para>
+The service and the realm are optional (which is why the arguments are enclosed
+in their own set of braces). For details of the meaning of the service and
+realm, and how to run the daemon, consult the Cyrus documentation.
+</para>
+</listitem></varlistentry>
+</variablelist>
+</section>
+<section id="SECID84">
+<title>Combining expansion conditions</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>combining conditions</secondary>
+</indexterm>
+Several conditions can be tested at once by combining them using the <option>and</option>
+and <option>or</option> combination conditions. Note that <option>and</option> and <option>or</option> are complete
+conditions on their own, and precede their lists of sub-conditions. Each
+sub-condition must be enclosed in braces within the overall braces that contain
+the list. No repetition of <option>if</option> is used.
+</para>
+<variablelist>
+<varlistentry>
+<term><emphasis role="bold">or&nbsp;{{</emphasis>&lt;<emphasis>cond1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>cond2</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><quote>or</quote> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><quote>or</quote> of conditions</secondary>
+</indexterm>
+The sub-conditions are evaluated from left to right. The condition is true if
+any one of the sub-conditions is true.
+For example,
+</para>
+<literallayout class="monospaced">
+${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}...
+</literallayout>
+<para>
+When a true sub-condition is found, the following ones are parsed but not
+evaluated. If there are several <quote>match</quote> sub-conditions the values of the
+numeric variables afterwards are taken from the first one that succeeds.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><emphasis role="bold">and&nbsp;{{</emphasis>&lt;<emphasis>cond1</emphasis>&gt;<emphasis role="bold">}{</emphasis>&lt;<emphasis>cond2</emphasis>&gt;<emphasis role="bold">}...}</emphasis></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary><quote>and</quote> expansion condition</primary>
+</indexterm>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary><quote>and</quote> of conditions</secondary>
+</indexterm>
+The sub-conditions are evaluated from left to right. The condition is true if
+all of the sub-conditions are true. If there are several <quote>match</quote>
+sub-conditions, the values of the numeric variables afterwards are taken from
+the last one. When a false sub-condition is found, the following ones are
+parsed but not evaluated.
+</para>
+</listitem></varlistentry>
+</variablelist>
+<para>
+<indexterm role="concept" startref="IIDexpcond" class="endofrange"/>
+</para>
+</section>
+<section id="SECTexpvar">
+<title>Expansion variables</title>
+<para>
+<indexterm role="concept">
+<primary>expansion</primary>
+<secondary>variables, list of</secondary>
+</indexterm>
+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.
+</para>
+<variablelist>
+<varlistentry>
+<term><varname>$0</varname>, <varname>$1</varname>, etc</term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>numerical variables (<varname>$1</varname> <varname>$2</varname> etc)</primary>
+</indexterm>
+When a <option>match</option> expansion condition succeeds, these variables contain the
+captured substrings identified by the regular expression during subsequent
+processing of the success string of the containing <option>if</option> expansion item.
+In the expansion condition case
+they do not retain their values afterwards; in fact, their previous
+values are restored at the end of processing an <option>if</option> item. The numerical
+variables may also be set externally by some other matching process which
+precedes the expansion of the string. For example, the commands available in
+Exim filter files include an <option>if</option> command with its own regular expression
+matching condition.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$acl_arg1</varname>, <varname>$acl_arg2</varname>, etc</term>
+<listitem>
+<para>
+Within an acl condition, expansion condition or expansion item
+any arguments are copied to these variables,
+any unused variables being made empty.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$acl_c...</varname></term>
+<listitem>
+<para>
+Values can be placed in these variables by the <option>set</option> modifier in an ACL. They
+can be given any name that starts with <varname>$acl_c</varname> and is at least six characters
+long, but the sixth character must be either a digit or an underscore. For
+example: <varname>$acl_c5</varname>, <varname>$acl_c_mycount</varname>. The values of the <varname>$acl_c...</varname>
+variables persist throughout the lifetime of an SMTP connection. They can be
+used to pass information between ACLs and between different invocations of the
+same ACL. When a message is received, the values of these variables are saved
+with the message, and can be accessed by filters, routers, and transports
+during subsequent delivery.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$acl_m...</varname></term>
+<listitem>
+<para>
+These variables are like the <varname>$acl_c...</varname> variables, except that their values
+are reset after a message has been received. Thus, if several messages are
+received in one SMTP connection, <varname>$acl_m...</varname> values are not passed on from one
+message to the next, as <varname>$acl_c...</varname> values are. The <varname>$acl_m...</varname> variables are
+also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. When a
+message is received, the values of these variables are saved with the message,
+and can be accessed by filters, routers, and transports during subsequent
+delivery.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$acl_narg</varname></term>
+<listitem>
+<para>
+Within an acl condition, expansion condition or expansion item
+this variable has the number of arguments.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$acl_verify_message</varname></term>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$acl_verify_message</varname></primary>
+</indexterm>
+After an address verification has failed, this variable contains the failure
+message. It retains its value for use in subsequent modifiers of the verb.
+The message can be preserved by coding like this:
+</para>
+<literallayout class="monospaced">
+warn !verify = sender
+     set acl_m0 = $acl_verify_message
+</literallayout>
+<para>
+You can use <varname>$acl_verify_message</varname> during the expansion of the <option>message</option> or
+<option>log_message</option> modifiers, to include information about the verification
+failure.
+</para>
+<para revisionflag="changed">
+<emphasis role="bold">Note</emphasis>: The variable is cleared at the end of processing the ACL verb.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$address_data</varname></term>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$address_data</varname></primary>
+</indexterm>
+This variable is set by means of the <option>address_data</option> option in routers. The
+value then remains with the address while it is processed by subsequent routers
+and eventually a transport. If the transport is handling multiple addresses,
+the value from the first address is used. See chapter <xref linkend="CHAProutergeneric"/>
+for more details. <emphasis role="bold">Note</emphasis>: The contents of <varname>$address_data</varname> are visible in
+user filter files.
+</para>
+<para>
+If <varname>$address_data</varname> is set when the routers are called from an ACL to verify
+a recipient address, the final value is still in the variable for subsequent
+conditions and modifiers of the ACL statement. If routing the address caused it
+to be redirected to just one address, the child address is also routed as part
+of the verification, and in this case the final value of <varname>$address_data</varname> is
+from the child&#x2019;s routing.
+</para>
+<para>
+If <varname>$address_data</varname> is set when the routers are called from an ACL to verify a
+sender address, the final value is also preserved, but this time in
+<varname>$sender_address_data</varname>, to distinguish it from data from a recipient
+address.
+</para>
+<para>
+In both cases (recipient and sender verification), the value does not persist
+after the end of the current ACL statement. If you want to preserve
+these values for longer, you can save them in ACL variables.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$address_file</varname></term>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$address_file</varname></primary>
+</indexterm>
+When, as a result of aliasing, forwarding, or filtering, a message is directed
+to a specific file, this variable holds the name of the file when the transport
+is running. At other times, the variable is empty. For example, using the
+default configuration, if user <option>r2d2</option> has a <filename>.forward</filename> file containing
+</para>
+<literallayout class="monospaced">
+/home/r2d2/savemail
+</literallayout>
+<para>
+then when the <command>address_file</command> transport is running, <varname>$address_file</varname>
+contains the text string <literal>/home/r2d2/savemail</literal>.
+<indexterm role="concept">
+<primary>Sieve filter</primary>
+<secondary>value of <varname>$address_file</varname></secondary>
+</indexterm>
+For Sieve filters, the value may be <quote>inbox</quote> or a relative folder name. It is
+then up to the transport configuration to generate an appropriate absolute path
+to the relevant file.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$address_pipe</varname></term>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$address_pipe</varname></primary>
+</indexterm>
+When, as a result of aliasing or forwarding, a message is directed to a pipe,
+this variable holds the pipe command when the transport is running.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$auth1</varname> &ndash; <varname>$auth4</varname></term>
+<listitem>
+<para>
+<indexterm role="variable">
+<primary><varname>$auth1</varname>, <varname>$auth2</varname>, etc</primary>
+</indexterm>
+These variables are used in SMTP authenticators (see chapters
+<xref linkend="CHAPplaintext"/>&ndash;<xref linkend="CHAPtlsauth"/>). Elsewhere, they are empty.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$authenticated_id</varname></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>id</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$authenticated_id</varname></primary>
+</indexterm>
+When a server successfully authenticates a client it may be configured to
+preserve some of the authentication information in the variable
+<varname>$authenticated_id</varname> (see chapter <xref linkend="CHAPSMTPAUTH"/>). For example, a
+user/password authenticator configuration might preserve the user name for use
+in the routers. Note that this is not the same information that is saved in
+<varname>$sender_host_authenticated</varname>.
+</para>
+<para>
+When a message is submitted locally (that is, not over a TCP connection)
+the value of <varname>$authenticated_id</varname> is normally the login name of the calling
+process. However, a trusted user can override this by means of the <option>-oMai</option>
+command line option.
+This second case also sets up information used by the
+<varname>$authresults</varname> expansion item.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$authenticated_fail_id</varname></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>fail</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$authenticated_fail_id</varname></primary>
+</indexterm>
+When an authentication attempt fails, the variable <varname>$authenticated_fail_id</varname>
+will contain the failed authentication id. If more than one authentication
+id is attempted, it will contain only the last one. The variable is
+available for processing in the ACL&#x2019;s, generally the quit or notquit ACL.
+A message to a local recipient could still be accepted without requiring
+authentication, which means this variable could also be visible in all of
+the ACL&#x2019;s as well.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$authenticated_sender</varname></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>sender</primary>
+<secondary>authenticated</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>sender</secondary>
+</indexterm>
+<indexterm role="concept">
+<primary>AUTH</primary>
+<secondary>on MAIL command</secondary>
+</indexterm>
+<indexterm role="variable">
+<primary><varname>$authenticated_sender</varname></primary>
+</indexterm>
+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 <xref linkend="SECTauthparamail"/>. Unless the data is the string
+<quote>&lt;&gt;</quote>, it is set as the authenticated sender of the message, and the value is
+available during delivery in the <varname>$authenticated_sender</varname> variable. If the
+sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data.
+</para>
+<para>
+<indexterm role="variable">
+<primary><varname>$qualify_domain</varname></primary>
+</indexterm>
+When a message is submitted locally (that is, not over a TCP connection), the
+value of <varname>$authenticated_sender</varname> is an address constructed from the login
+name of the calling process and <varname>$qualify_domain</varname>, except that a trusted user
+can override this by means of the <option>-oMas</option> command line option.
+</para>
+</listitem></varlistentry>
+<varlistentry>
+<term><varname>$authentication_failed</varname></term>
+<listitem>
+<para>
+<indexterm role="concept">
+<primary>authentication</primary>
+<secondary>failure</secondary>
+</indexterm>
+<indexterm r