+++ /dev/null
-. $Cambridge: exim/doc/doc-src/filter.src,v 1.2 2005/01/11 15:17:51 ph10 Exp $
-.
-.if !set style
-.library "a4ps"
-.linelength ~~sys.linelength + 0.2in
-.emphasis ~~sys.linelength + 0.1in
-.pagedepth ~~sys.pagedepth - 0.2in
-.bindfont 53 "atl/Times-Roman" 7
-.set ssspaceb 1.50
-.fi
-
-.include "markup.sg"
-
-.set sgcal true
-.set html false
-.set texinfo false
-
-
-.if ~~sys.fancy
-.flag $sm{ "$push$g0$f53"
-.
-.else
-.pagedepth ~~sys.pagedepth - 1ld
-.linelength 75em
-.emphasis 77em
-.footdepth 0
-.disable formfeed
-.backspace none
-.set chapspaceb 24
-.set sspacea 24
-.flag $sm{ "$push"
-.fi
-
-.macro tabs 6
-.if ~~sys.fancy
-.tabset ~~1em
-.else
-.set temp (~~1 * 5)/4
-.tabset ~~temp em
-.fi
-.endm
-
-.macro startitems
-.newline
-.push
-.indent 3em
-.endm
-
-.macro enditems
-.newline
-.pop
-.endm
-
-.macro item "item"
-.newpar
-.if ~~sys.leftonpage < 5ld
-.newpage
-.fi
-.tempindent 0
-\~~1\
-.blank
-.endm
-
-.macro index
-.endm
-
-.set contents false
-.set displayindent 2em
-
-
-. ======================================================
-
-
-.if ~~sys.fancy
-.footdepth 2ld
-.foot
-$c[~~sys.pagenumber]$e
-.endfoot
-.fi
-
-
-.set chapter -1
-.chapter Exim's interfaces to mail filtering
-.space -2ld
-This document describes the user interfaces to Exim's in-built mail filtering
-facilities, and is copyright (c) University of Cambridge 2005. It corresponds
-to Exim version 4.50.
-.rule
-
-. ---------------------------------------------------------------------------
-. Some clever jiggery-pokery here. The contents list is known to be less than
-. one page long, so we arrange for it to get onto the rest of the first page.
-. Because we aren't doing any indexing, the z-rawindex file will contain only
-. the TOC entries. The Makefile arranges for it to be empty at the start, then
-. runs SGCAL twice so on the second pass it gets inserted automatically.
-
-.if ~~sgcal
-.space 1ld
-. $chead{Contents}
-. space 1ld
-.tabset 2em 2em
-.push
-.linedepth ~~sys.linedepth - 1
-.include "z-rawindex"
-.newline
-.pop
-.newpage
-.set contents true
-.fi
-. ---------------------------------------------------------------------------
-
-
-.set chapter 0
-.chapter Forwarding and filtering in Exim
-
-
-.section Introduction
-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 \(.forward)\ 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 `\(.forward)\
-with conditions'. Operating the set of rules is called $it{filtering}, and the
-file that contains them is called a $it{filter file}.
-
-Exim supports two different kinds of filter file. An \*Exim filter*\ contains
-instructions in a format that is unique to Exim. A \*Sieve filter*\ 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).
-
-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.
-
-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.
-
-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.
-
-The contents of traditional \(.forward)\ 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 \%redirect%\ router in the
-Exim specification, which also describes how the system administrator can set
-up and control the use of filtering.
-
-
-.em
-.section Filter operation
-It is important to realize that, in Exim, no deliveries are actually made while
-a filter or traditional \(.forward)\ file is being processed. Running a filter
-or processing a traditional \(.forward)\ file sets up future delivery
-operations, but does not carry them out.
-
-The result of filter or \(.forward)\ 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.
-.nem
-
-
-.section Testing a new filter file
-.rset SECTtesting "~~chapter.~~section"
-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 \(.forward)\ files.
-
-Because a filter can do tests on the content of messages, a test message is
-required. Suppose you have a new filter file called \(myfilter)\ and a test
-message called \(test-message)\. Assuming that Exim is installed with the
-conventional path name \(/usr/sbin/sendmail)\ (some operating systems use
-\(/usr/lib/sendmail)\), the following command can be used:
-.display asis
-/usr/sbin/sendmail -bf myfilter <test-message
-.endd
-The \-bf-\ 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 \-bF-\ 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.
-
-The test message is supplied on the standard input. If there are no
-message-dependent tests in the filter, an empty file (\(/dev/null)\) can be
-used. A supplied message must start with header lines or the `From' message
-separator line which 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.
-
-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
-.display asis
-Deliver message to: gulliver@lilliput.fict.example
-Save message to: /home/lemuel/mail/archive
-.endd
-means that one copy of the message would be sent to
-\gulliver@@lilliput.fict.example\, and another would be added to the file
-\(/home/lemuel/mail/archive)\, if all went well.
-
-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 \-v-\
-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
-\"if"\ commands. Further additional output from a filter test can be generated
-by the \"testprint"\ command, which is described below.
-
-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 `@\n' in the testing output.
-
-When testing a filter in this way, Exim makes up an `envelope' 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 \-f-\ option to supply a different sender.
-For example,
-.display
-.indent 0
-/usr/sbin/sendmail -bf myfilter -f islington@@never.where <test-message
-.endd
-Alternatively, if the \-f-\ option is not used, but the first line of the
-supplied message is a `From' separator from a message folder file (not the same
-thing as a \"From:"\ header line), the sender is taken from there. If \-f-\ is
-present, the contents of any `From' line are ignored.
-
-The `return path' is the same as the envelope sender, unless the message
-contains a \"Return-path:"\ 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.
-
-It is possible to change the envelope recipient by specifying further options.
-The \-bfd-\ option changes the domain of the recipient address, while the
-\-bfl-\ option changes the `local part', that is, the part before the @@ sign.
-An adviser could make use of these to test someone else's filter file.
-
-The \-bfp-\ and \-bfs-\ 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 ~~SECTmbox below.
-
-.section Installing a filter file
-A filter file is normally installed under the name \(.forward)\ in your home
-directory -- it is distinguished from a conventional \(.forward)\ 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.
-
-.section Testing an installed filter file
-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 `live' tests should therefore also be done once a filter is installed.
-
-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'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't be returned to you, and
-also that the postmaster will have to investigate the stuck message.
-
-If you have to test an Exim filter from the same account, a sensible precaution
-is to include the line
-.display asis
-if error_message then finish endif
-.endd
-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.)
-
-
-.section Details of filtering commands
-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.
-
-
-.
-.
-.
-.
-.
-.chapter Sieve filter files
-.rset CHAPsievefilter "~~chapter"
-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 a extensible language, it is important to understand `Sieve' in this
-context as `the specific implementation of Sieve for Exim'.
-
-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.
-
-The Exim Sieve implementation offers the core as defined by RFC 3028,
-.em
-comparison tests, the \%copy%\, \%envelope%\, \%fileinto%\, and \%vacation%\
-extensions,
-.nem
-but not the \%reject%\ extension. Exim does not support message delivery
-notifications (MDNs), so adding it just to the Sieve filter (as required for
-\%reject%\) makes little sense.
-
-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 \%redirect%\ router in the full Exim specification.
-
-.section Recognition of Sieve filters
-A filter file is interpreted as a Sieve filter if its first line is
-.display asis
-# Sieve filter
-.endd
-This is what distinguishes it from a conventional \(.forward)\ file or an Exim
-filter file.
-
-
-.section Saving to specified folders
-If the system administrator has set things up as suggested in the Exim
-specification, and you use \%keep%\ or \%fileinto%\ to save a mail into a
-folder, absolute files are stored where specified, relative files are stored
-relative to \$home$\, and \%inbox%\ goes to the standard mailbox location.
-
-
-.section Strings containing header names
-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 the common picture of Sieve.
-
-
-.section Exists test with empty list of headers
-The \%exists%\ test succeeds only if all 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.
-
-
-.section Header test with invalid MIME encoding in header
-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.
-
-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.
-
-
-.section Address test for multiple addresses per header
-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.
-
-
-.section Semantics of keep
-The \%keep%\ command is equivalent to
-.display
-fileinto "inbox";
-.endd
-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.
-
-
-.section Semantics of fileinto
-RFC 3028 does not specify whether \fileinto\ should try to create a mail folder
-if it does not exist. This implementation allows the sysadmin to configure that
-aspect using the \%appendfile%\ transport options \create@_directory\,
-\create@_file\, and \file@_must@_exist\. See the \%appendfile%\ transport in
-the Exim specification for details.
-
-
-.section Semantics of redirect
-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.
-
-
-.section String arguments
-There has been confusion if the string arguments to \%require%\ are to be
-matched case-sensitively or not. This implementation matches them with
-the match type \":is"\ (default, see section 2.7.1) and the comparator
-\"i;ascii-casemap"\ (default, see section 2.7.3). 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.
-
-
-.section Number units
-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
-scaling factor for the suffix G.
-
-
-.section RFC compliance
-Exim requires the first line of a Sieve filter to be
-.display asis
-# Sieve filter
-.endd
-Of course the RFC does not specify that line. Do not expect examples to work
-without adding it, though.
-
-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 newline character, this implementation
-does, too, by default, though the system administrator may choose (at Exim
-compile time) to use CRLF instead.
-
-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 to UTF-8 data.
-
-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.
-.display asis
-Subject: =?iso-8859-1?q?abc=00def
-
-header :contains "Subject" ["abc"]
-header :contains "Subject" ["def"]
-header :matches "Subject" ["abc?def"]
-.endd
-
-Note that by considering Sieve to be a 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's not recommended either.
-The above example shows why.
-
-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.
-
-The folder specified by \%fileinto%\ must not contain the character
-sequence \".."\ to avoid security problems. RFC 3028 does not specify the
-syntax of folders apart from \%keep%\ being equivalent to
-.display asis
-fileinto "INBOX";
-.endd
-This implementation uses \"inbox"\ instead.
-
-Sieve script errors currently cause messages to be silently filed into
-\"inbox"\. RFC 3028 requires that the user is notified of that condition.
-This may be implemented in future by adding a header line to mails that
-are filed into \"inbox"\ due to an error in the filter.
-
-
-.
-.
-.
-.
-.
-.chapter Exim filter files
-.rset CHAPeximfilter "~~chapter"
-This chapter contains a full description of the contents of Exim filter files.
-
-.section Format of Exim filter files
-Apart from leading white space, the first text in a filter file must be
-.display asis
-# Exim filter
-.endd
-This is what distinguishes it from a conventional \(.forward)\ 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 \(.forward)\ file, both when delivering mail and when using the
-\-bf-\ 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
-.display asis
-# Exim filter <<== do not edit or remove this line!
-.endd
-The remainder of the file is a sequence of filtering commands, which consist of
-keywords and data values. For example, in the command
-.display asis
-deliver gulliver@lilliput.fict.example
-.endd
-the keyword is \"deliver"\ and the data value is
-\"gulliver@@lilliput.fict.example"\.
-White space or line breaks separate the components of a command, except in the
-case of conditions for the \"if"\ 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.
-
-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.
-
-.section Data values in filter commands
-There are two ways in which a data value can be input:
-.numberpars $.
-If the text contains no white space then 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.
-.nextp
-Otherwise, it must be enclosed in double quotation marks. In this case, the
-character @\ (backslash) is treated as an `escape character' within the string,
-causing the following character or characters to be treated specially:
-.display rm
-.tabs 8
-@\n $t is replaced by a newline
-@\r $t is replaced by a carriage return
-@\t $t is replaced by a tab
-.endd
-Backslash followed by up to three octal digits is replaced by the character
-specified by those digits, and @\x 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, @\" becomes " and @\@\ becomes
-@\$<. 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.
-.endp
-In addition to the escape character processing that occurs when strings are
-enclosed in quotes, most data values are also subject to $it{string expansion}
-(as described in the next section), in which case the characters \@$\ and \@\\
-are also significant. This means that if a single backslash is actually
-required in such a string, and the string is also quoted, @\@\@\@\ has to be
-entered.
-
-The maximum permitted length of a data string, before expansion, is 1024
-characters.
-
-
-.section String expansion
-.rset SECTfilterstringexpansion "~~chapter.~~section"
-Most data values are expanded before use. Expansion consists of replacing
-substrings beginning with \"@$"\ 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.
-
-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
-.display asis
-$reply_address
-.endd
-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,
-.display asis
-${reply_address}
-.endd
-If a \"@$"\ 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 \"@$"\ character in a
-message:
-.display asis
-if $message_body contains \$ then ...
-if $message_body contains "\\$" then ...
-.endd
-You can prevent part of a string from being expanded by enclosing it between
-two occurrences of \"@\N"\. For example,
-.display asis
-if $message_body contains \N$$$$\N then ...
-.endd
-tests for a run of four dollar characters.
-
-.section Some useful general variables
-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:
-
-\$body@_linecount$\: The number of lines in the body of the message.
-
-.em
-\$body@_zerocount$\: The number of binary zero characters in the body of the
-message.
-.nem
-
-\$home$\: In conventional configurations, this variable normally contains the
-user's home directory. The system administrator can, however, change this.
-
-\$local@_part$\: The part of the email address that precedes the @@ sign --
-normally the user's login name. If support for multiple personal mailboxes is
-enabled (see section ~~SECTmbox below) and a prefix or suffix for the local
-part was recognized, it is removed from the string in this variable.
-
-\$local@_part@_prefix$\: If support for multiple personal mailboxes is enabled
-(see section ~~SECTmbox below), and a local part prefix was recognized,
-this variable contains the prefix. Otherwise it contains an empty string.
-
-\$local@_part@_suffix$\: If support for multiple personal mailboxes is enabled
-(see section ~~SECTmbox below), and a local part suffix was recognized,
-this variable contains the suffix. Otherwise it contains an empty string.
-
-\$message@_body$\: 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.
-
-\$message@_body@_end$\: The final portion of the body of the message, formatted
-and limited in the same way as \$message@_body$\.
-
-\$message@_body@_size$\: The size of the body of the message, in bytes.
-
-\$message@_headers$\: The header lines of the message, concatenated into a
-single string, with newline characters between them.
-
-\$message@_id$\: The message's local identification string, which is unique for
-each message handled by a single host.
-
-\$message@_size$\: The size of the entire message, in bytes.
-
-\$original@_local@_part$\: When an address that arrived with the message is
-being processed, this contains the same value as the variable \$local@_part$\.
-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.
-
-\$reply@_address$\: The contents of the \"Reply-to:"\ header, if the message
-has one; otherwise the contents of the \"From:"\ header. It is the address to
-which normal replies to the message should be sent.
-
-\$return@_path$\: The return path -- that is, the sender field that will be
-transmitted as part of the message'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 \$sender@_address$\, but if, for example,
-an incoming message to a mailing list has been expanded, \$return@_path$\ may
-have been changed to contain the address of the list maintainer.
-
-\$sender@_address$\: The sender address that was received in the envelope of
-the message. This is not necessarily the same as the contents of the \"From:"\
-or \"Sender:"\ header lines. For delivery error messages (`bounce messages')
-there is no sender address, and this variable is empty.
-
-\$tod@_full$\: 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.
-
-\$tod@_log$\: The time and date in the format used for writing Exim's log files,
-without the timezone, for example: 1995-10-12 15:32:29.
-
-\$tod@_zone$\: The local timezone offset, for example: +0100.
-
-
-.section Header variables
-.rset SECTheadervariables "~~chapter.~~section"
-There is a special set of expansion variables containing the header lines of
-the message being processed. These variables have names beginning with
-\"@$header@_"\ followed by the name of the header line, terminated by a colon.
-For example,
-.display asis
-$header_from:
-$header_subject:
-.endd
-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, ::From:: and ::To::), a comma and newline is
-inserted between each set of data. For all other header lines, just a newline
-is used.
-
-Leading and trailing white space is removed from header line data, and if there
-are any MIME `words' 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 \iconv(@)\ 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 \"headers"\ command (see below).
-
-If you want to see the actual characters that make up a header line, you can
-specify \"@$rheader@_"\ instead of \"@$header@_"\. This inserts the `raw'
-header line, unmodified.
-
-There is also an intermediate form, requested by \"@$bheader@_"\, which removes
-leading and trailing space and decodes MIME `words', but does not do any
-character translation. If an attempt to decode what looks superficially like a
-MIME `word' fails, the raw string is returned. If decoding produces a binary
-zero character, it is replaced by a question mark.
-
-The capitalization of the name following \"@$header@_"\ is not significant.
-Because any printing character except colon may appear in the name of a
-message's header (this is a requirement of RFC 2822, the document that
-describes the format of a mail message) curly brackets must $it{not} be used in
-this case, as they will be taken as part of the header name. Two shortcuts are
-allowed in naming header variables:
-.numberpars $.
-The initiating \"@$header@_"\, \"@$rheader@_"\, or \"@$bheader@_"\ can be
-abbreviated to \"@$h@_"\, \"@$rh@_"\, or \"@$bh@_"\, respectively.
-.nextp
-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.
-.endp
-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 \"@$header@_Reply@_to"\ when you really mean \"@$header@_Reply-to"\.
-
-.section User variables
-There are ten user variables with names \$n0$\ -- \$n9$\ that can be
-incremented by the \"add"\ command (see section ~~SECTadd). These can be used
-for `scoring' messages in various ways. If Exim is configured to run a `system
-filter' on every message, the values left in these variables are copied into
-the variables \$sn0$\ -- \$sn9$\ at the end of the system filter, thus making
-them available to users' filter files. How these values are used is entirely up
-to the individual installation.
-
-.section Current directory
-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 \$home$\ variable to refer to your home directory.
-The \save\ command automatically inserts \$home$\ at the start of non-absolute
-paths.
-
-
-
-.section Significant deliveries
-.rset SECTsigdel "~~chapter.~~section"
-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 $it{significant deliveries}. 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.
-
-The delivery commands \"deliver"\, \"save"\, and \"pipe"\ are by default
-significant. However, if such a command is preceded by the word \"unseen"\, its
-delivery is not considered to be significant. In contrast, other commands such
-as \"mail"\ and \"vacation"\ do not set up significant deliveries unless
-preceded by the word \"seen"\.
-
-.em
-The following example commands set up significant deliveries:
-.display asis
-deliver jack@beanstalk.example
-pipe $home/bin/mymailscript
-seen mail subject "message discarded"
-seen finish
-.endd
-The following example commands do not set up significant deliveries:
-.display asis
-unseen deliver jack@beanstalk.example
-unseen pipe $home/bin/mymailscript
-mail subject "message discarded"
-finish
-.endd
-.nem
-
-
-.section Filter commands
-The filter commands that are described in subsequent sections are listed
-below, with the section in which they are described in brackets:
-.display rm
-.tabs 15
-\add\ $t increment a user variable (section ~~SECTadd)
-\deliver\ $t deliver to an email address (section ~~SECTdeliver)
-\fail\ $t force delivery failure (sysadmin use) (section ~~SECTfail)
-\finish\ $t end processing (section ~~SECTfinish)
-\freeze\ $t freeze message (sysadmin use) (section ~~SECTfreeze)
-\headers\ $t set the header character set (section ~~SECTheaders)
-\if\ $t test condition(s) (section ~~SECTif)
-\logfile\ $t define log file (section ~~SECTlog)
-\logwrite\ $t write to log file (section ~~SECTlog)
-\mail\ $t send a reply message (section ~~SECTmail)
-\pipe\ $t pipe to a command (section ~~SECTpipe)
-\save\ $t save to a file (section ~~SECTsave)
-\testprint\ $t print while testing (section ~~SECTtestprint)
-\vacation\ $t tailored form of \mail\ (section ~~SECTmail)
-.endd
-.em
-The \"headers"\ command has additional parameters that can be used only in a
-system filter. The \"fail"\ and \"freeze"\ commands are available only when
-Exim'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.
-.nem
-
-.section The add command
-.rset SECTadd "~~chapter.~~section"
-.display
- add <<number>> to <<user variable>>
-e.g. add 2 to n3
-.endd
-There are 10 user variables of this type, with names \"n0"\ -- \"n9"\. Their
-values can be obtained by the normal expansion syntax (for example \$n3$\) in
-other commands. At the start of filtering, these variables all contain zero.
-Both arguments of the \"add"\ command are expanded before use, making it
-possible to add variables to each other. Subtraction can be obtained by adding
-negative numbers.
-
-
-.section The deliver command
-.rset SECTdeliver "~~chapter.~~section"
-.display
- deliver <<mail address>>
-e.g. deliver "Dr Livingstone <David@@somewhere.africa.example>"
-.endd
-This command provides a forwarding operation.
-.em
-The delivery that it sets up is significant unless the command is preceded by
-\"unseen"\ (see section ~~SECTsigdel).
-.nem
-The message is sent on to the given address, exactly as happens if the address
-had appeared in a traditional \(.forward)\ file. If you want to deliver the
-message to a number of different addresses, you can use more than one
-\"deliver"\ command (each one may have only one address). However, duplicate
-addresses are discarded.
-
-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.
-
-However, if you have a mail alias, you should $it{not} refer to it here. For
-example, if the mail address \"L.Gulliver"\ is aliased to \"lg303"\ then all
-references in Gulliver's \(.forward)\ file should be to \"lg303"\. A reference
-to the alias will not work for messages that are addressed to that alias,
-since, like \(.forward)\ file processing, aliasing is performed only once on an
-address, in order to avoid looping.
-
-Following the new address, an optional second address, preceded by
-\"errors@_to"\ may appear. This changes the address to which delivery errors on
-the forwarded message will be sent. Instead of going to the message'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 \"lg303"\ whose mailbox is in the domain
-\lilliput.example\ could have a filter file that contains
-.display asis
- deliver jon@elsewhere.example errors_to lg303@lilliput.example
-.endd
-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.
-
-
-.section The save command
-.rset SECTsave "~~chapter.~~section"
-.display
- save <<file name>>
-e.g. save @$home/mail/bookfolder
-.endd
-.em
-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 \"save"\ sets up is significant unless the command is preceded by
-\"unseen"\ (see section ~~SECTsigdel).
-.nem
-More than one \"save"\ command may be obeyed; each one causes a copy of the
-message to be written to its argument file, provided they are different
-(duplicate \"save"\ commands are ignored).
-
-If the file name does not start with a / character, the contents of the
-\$home$\ variable are prepended, unless it is empty. In conventional
-configurations, this variable is normally set in a user filter to the user's
-home directory, but the system administrator may set it to some other path. In
-some configurations, \$home$\ may be unset, 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, \$home$\ is never set.
-
-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'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 -- it may be forbidden on some systems.
-
-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:
-.display
- save /some/folder 640
-.endd
-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.
-
-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 \"save"\ command, for example
-.display
- save separated/messages/
-.endd
-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.
-
-
-.section The pipe command
-.rset SECTpipe "~~chapter.~~section"
-.display
- pipe <<command>>
-e.g. pipe "@$home/bin/countmail @$sender@_address"
-.endd
-.em
-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 \"unseen"\ (see section ~~SECTsigdel).
-.nem
-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.
-
-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'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 \"pipe"\ command may appear; each one causes
-a copy of the message to be written to its argument pipe, provided they are
-different (duplicate \"pipe"\ commands are ignored).
-
-When the time comes to transport the message,
-the command supplied to \"pipe"\ 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:
-.display asis
- pipe "$home/myscript \"size is $message_size\""
-.endd
-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.
-
-Documentation for some programs that are normally run via this kind of pipe
-often suggest that the command should start with
-.display asis
-IFS=" "
-.endd
-This is a shell command, and should $it{not} be present in Exim filter files,
-since it does not normally run the command under a shell.
-
-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.
-
-The default \\PATH\\ set up for the command is determined by the system
-administrator, usually containing at least \/usr/bin\ 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 \"pipe"\ command altogether.
-
-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:
-.display
-.tabs 20
-DOMAIN $t $rm{the domain of the address}
-HOME $t $rm{your home directory}
-LOCAL@_PART $t $rm{see below}
-LOCAL@_PART@_PREFIX $t $rm{see below}
-LOCAL@_PART@_SUFFIX $t $rm{see below}
-LOGNAME $t $rm{your login name}
-MESSAGE@_ID $t $rm{the message's unique id}
-PATH $t $rm{the command search path}
-RECIPIENT $t $rm{the complete recipient address}
-SENDER $t $rm{the sender of the message}
-SHELL $t $bf{/bin/sh}
-USER $t $rm{see below}
-.endd
-\\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
-\*pat-suf2@@domain.example*\ may cause user \*pat*\'s filter file to be run. If
-this sets up a pipe delivery, \\LOCAL@_PART@_SUFFIX\\ is \"-suf2"\ when the
-pipe command runs. The system administrator has to configure Exim specially for
-this feature to be available.
-
-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 legally 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:
-.display asis
-/some/command '$SENDER'
-.endd
-so that inserted shell meta-characters do not cause unwanted effects.
-
-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.
-
-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.
-
-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'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.
-
-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.
-
-
-.section Mail commands
-.rset SECTmail "~~chapter.~~section"
-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 \"seen"\ (see section ~~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.
-
-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
-.display
- mail [to <<address-list>>]
- [cc <<address-list>>]
- [bcc <<address-list>>]
- [from <<address>>]
- [reply@_to <<address>>]
- [subject <<text>>]
- [extra@_headers <<text>>]
- [text <<text>>]
- [[expand] file <<filename>>]
- [return message]
- [log <<log file name>>]
- [once <<note file name>>]
- [once@_repeat <<time interval>>]
-.blank
-e.g. mail text "Your message about @$h@_subject: has been received"
-.endd
-
-Each <<address-list>> can contain a number of addresses, separated by commas,
-in the format of a ::To:: or ::Cc:: 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:
-.display asis
-mail to "Julius Caesar <jc@rome.example>, \
- <ma@rome.example> (Mark A.)"
-.endd
-Similarly, the texts supplied for \"from"\ and \"reply@_to"\ are copied into
-their respective header lines.
-
-As a convenience for use in one common case, there is also a command called
-\vacation\. It behaves in the same way as \mail\, except that the defaults for
-the
-\"subject"\,
-\"file"\, \"log"\, \"once"\, and \"once@_repeat"\ options are
-.display
-subject "On vacation"
-expand file .vacation.msg
-log .vacation.log
-once .vacation
-once@_repeat 7d
-.endd
-respectively. These are the same file names and repeat period used by the
-traditional Unix \"vacation"\ command. The defaults can be overridden by
-explicit settings, but if a file name is given its contents are expanded only
-if explicitly requested.
-
-\**Warning**\: The \"vacation"\ command should always be used conditionally,
-subject to at least the \"personal"\ condition (see section ~~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.
-
-For both commands, the key/value argument pairs can appear in any order. At
-least one of \"text"\ or \"file"\ must appear (except with \"vacation"\, where
-there is a default for \"file"\); if both are present, the text string appears
-first in the message. If \"expand"\ precedes \"file"\, each line of the file is
-subject to string expansion before it is included in the message.
-
-Several lines of text can be supplied to \"text"\ by including the escape
-sequence `@\n' in the string wherever a newline is required. If the command is
-output during filter file testing, newlines in the text are shown as `@\n'.
-
-Note that the keyword for creating a \"Reply-To:"\ header is \reply@_to\,
-because Exim keywords may contain underscores, but not hyphens. If the \"from"\
-keyword is present and the given address does not match the user who owns the
-forward file, Exim normally adds a \"Sender:"\ header to the message,
-though it can be configured not to do this.
-
-The \extra@_headers\ keyword allows you to add custom header lines to the
-message. The text supplied must be one or more syntactically valid RFC 2882
-header lines. You can use `@\n' within quoted text to specify newlines between
-headers, and also to define continued header lines. For example:
-.display asis
-extra_headers "h1: first\nh2: second\n continued\nh3: third"
-.endd
-No newline should appear at the end of the final header line.
-
-If no \"to"\ argument appears, the message is sent to the address in the
-\"@$reply@_address"\ variable (see section ~~SECTfilterstringexpansion above).
-An \"In-Reply-To:"\ header is automatically included in the created message,
-giving a reference to the message identification of the incoming message.
-
-If \"return message"\ 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.
-
-If a log file is specified, a line is added to it for each message sent.
-
-If a \"once"\ 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 \"once@_repeat"\ 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 `seconds', `minutes', `hours', `days', or `weeks'. For example,
-.display asis
-once_repeat 5d4h
-.endd
-causes a new message to be sent if 5 days and 4 hours have elapsed since the
-last one was sent. There must be no white space in a time interval.
-
-Commonly, the file name specified for \"once"\ 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 \"once"\ results in two files being created,
-with the suffixes \".dir"\ and \".pag"\ being added to the given name. With
-some others a single file with the suffix \".db"\ is used, or the name is used
-unchanged.
-
-Using a DBM file for implementing the \"once"\ 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.
-
-More than one \"mail"\ or \"vacation"\ command may be obeyed in a single filter
-run; they are all honoured, even when they are to the same recipient.
-
-
-.section Logging commands
-.rset SECTlog "~~chapter.~~section"
-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.
-
-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:
-.display
- logfile <<file name>>
-e.g. logfile @$home/filter.log
-.endd
-The file name must be fully qualified. You can use \$home$\, 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,
-.display
- logfile @$home/filter.log 0644
-.endd
-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 \"logfile"\ command
-normally appear as the first command in a filter file. Once \"logfile"\ has
-been obeyed, the \"logwrite"\ command can be used to write to the log file:
-.display
- logwrite "<<some text string>>"
-e.g. logwrite "@$tod@_log @$message@_id processed"
-.endd
-It is possible to have more than one \"logfile"\ command, to specify writing to
-different log files in different circumstances. Writing takes place at the end
-of the file, and a newline character is added to the end of each string if
-there isn't one already there. Newlines can be put in the middle of the string
-by using the `@\n' 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.
-
-
-.section The finish command
-.rset SECTfinish "~~chapter.~~section"
-The command \"finish"\, which has no arguments, causes Exim to stop
-interpreting the filter file. This is not a significant action unless preceded
-by \"seen"\. A filter file containing only \"seen finish"\ is a black hole.
-
-.section The testprint command
-.rset SECTtestprint "~~chapter.~~section"
-It is sometimes helpful to be able to print out the values of variables when
-testing filter files. The command
-.display
- testprint <<text>>
-e.g. testprint "home=@$home reply@_address=@$reply@_address"
-.endd
-does nothing when mail is being delivered. However, when the filtering code is
-being tested by means of the \-bf-\ option (see section ~~SECTtesting above),
-the value of the string is written to the standard output.
-
-.section The fail command
-.rset SECTfail "~~chapter.~~section"
-When Exim's filtering facilities are being used as a system filter, the
-\"fail"\ 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.
-
-.section The freeze command
-.rset SECTfreeze "~~chapter.~~section"
-When Exim's filtering facilities are being used as a system filter, the
-\"freeze"\ 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.
-
-
-.section The headers command
-.rset SECTheaders "~~chapter.~~section"
-The \"headers"\ 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
-\"@$header@_"\ mechanism (see section ~~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 \"headers"\ command
-.em
-in user filters
-.nem
-is as in this example:
-.display asis
-headers charset "UTF-8"
-.endd
-That is, \"headers"\ is followed by the word \"charset"\ 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.
-
-.em
-In system filter files, the \"headers"\ command can be used to add or remove
-header lines from the message. These features are described in the main Exim
-specification.
-.nem
-
-
-
-.section Obeying commands conditionally
-.rset SECTif "~~chapter.~~section"
-Most of the power of filtering comes from the ability to test conditions and
-obey different commands depending on the outcome. The \"if"\ command is used to
-specify conditional execution, and its general form is
-.display
-if <<condition>>
-then <<commands>>
-elif <<condition>>
-then <<commands>>
-else <<commands>>
-endif
-.endd
-There may be any number of \"elif"\ and \"then"\ sections (including none) and
-the \"else"\ section is also optional. Any number of commands, including nested
-\"if"\ commands, may appear in any of the <<commands>> sections.
-
-Conditions can be combined by using the words \"and"\ and \"or"\, and round
-brackets (parentheses) can be used to specify how several conditions are to
-combine. Without brackets, \"and"\ is more binding than \"or"\.
-For example,
-.display asis
-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 spam"
-then
- seen finish
-endif
-.endd
-A condition can be preceded by \"not"\ to negate it, and there are also some
-negative forms of condition that are more English-like.
-
-
-
-.section String testing conditions
-There are a number of conditions that operate on text strings, using the words
-`begins', `ends', `is', `contains' and `matches'. 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:
-.display asis
-if "$h_to:, $h_cc:" contains me@domain.example then ...
-.endd
-
-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, `CONTAINS'), the case of letters is taken into account.
-.display
- <<text1>> begins <<text2>>
- <<text1>> does not begin <<text2>>
-e.g. @$header@_from: begins "Friend@@"
-.endd
-A `begins' test checks for the presence of the second string at the start of
-the first, both strings having been expanded.
-.display
- <<text1>> ends <<text2>>
- <<text1>> does not end <<text2>>
-e.g. @$header@_from: ends "@public.com.example"
-.endd
-An `ends' test checks for the presence of the second string at the end of
-the first, both strings having been expanded.
-.display
- <<text1>> is <<text2>>
- <<text1>> is not <<text2>>
-e.g. @$local@_part@_suffix is "-foo"
-.endd
-An `is' test does an exact match between the strings, having first expanded
-both strings.
-.display
- <<text1>> contains <<text2>>
- <<text1>> does not contain <<text2>>
-e.g. @$header@_subject: contains "evolution"
-.endd
-A `contains' test does a partial string match, having expanded both strings.
-.display
- <<text1>> matches <<text2>>
- <<text1>> does not match <<text2>>
-e.g. @$sender@_address matches "(bill|john)@@"
-.endd
-For a `matches' 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.
-
-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 @^
-or @$ metacharacters. The above example, which is not so constrained, matches
-all these addresses:
-.display asis
-bill@test.example
-john@some.example
-spoonbill@example.com
-littlejohn@example.com
-.endd
-To match only the first two, you could use this:
-.display asis
-if $sender_address matches "^(bill|john)@" then ...
-.endd
-
-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's normal processing of strings in quotes. For example, if you
-want to test the sender address for a domain ending in \".com"\ the regular
-expression is
-.display asis
-\.com$
-.endd
-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
-.display asis
-if $sender_address matches \\.com\$
-.endd
-An alternative way of handling this is to make use of the \"@\N"\ expansion
-flag for suppressing expansion:
-.display asis
-if $sender_address matches \N\.com$\N
-.endd
-Everything between the two occurrences of \"@\N"\ 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
-.display asis
-if $sender_address matches "\\\\.com\\$"
-.endd
-or
-.display asis
-if $sender_address matches "\\N\\.com$\\N"
-.endd
-
-If the regular expression contains bracketed sub-expressions, numeric
-variable substitutions such as \$1$\ 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 \"endif"\.
-In other words, only one set of values is ever available. If the condition
-contains several sub-conditions connected by \"and"\ or \"or"\, 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.
-
-.section Numeric testing conditions
-The following conditions are available for performing numerical tests:
-.display
- <<number1>> is above <<number2>>
- <<number1>> is not above <<number2>>
- <<number1>> is below <<number2>>
- <<number1>> is not below <<number2>>
-e.g. @$message@_size is not above 10k
-.endd
-The <<number>> 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.
-
-.section Testing for significant deliveries
-You can use the \"delivered"\ condition to test whether or not any previously
-obeyed filter commands have set up a significant delivery. For example:
-.display asis
-if not delivered then save mail/anomalous endif
-.endd
-
-.section Testing for error messages
-The condition \"error@_message"\ is true if the incoming message is a bounce
-(mail delivery error) message. Putting the command
-.display asis
-if error_message then finish endif
-.endd
-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. \**Note**\:
-\"error@_message"\ is a condition, not an expansion variable, and therefore is
-not preceded by \@$\.
-
-.section Testing a list of addresses
-There is a facility for looping through a list of addresses and applying a
-condition to each of them. It takes the form
-.display
-foranyaddress <<string>> (<<condition>>)
-.endd
-where <<string>> is interpreted as a list of RFC 2822 addresses, as in a
-typical header line, and <<condition>> is any valid filter condition or
-combination of conditions. The `group' syntax that is defined for certain
-header lines that contain addresses is supported.
-
-The parentheses surrounding the condition are mandatory, to delimit it from
-possible further sub-conditions of the enclosing \"if"\ command. Within the
-condition, the expansion variable \$thisaddress$\ is set to the non-comment
-portion of each of the addresses in the string in turn. For example, if the
-string is
-.display asis
-B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister)
-.endd
-then \$thisaddress$\ would take on the values \"bart@@sfld.example"\ and
-\"lisa@@sfld.example"\ in turn.
-
-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 \To:\ header:
-.display asis
-if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ...
-.endd
-When the overall condition is true, the value of \$thisaddress$\ in the
-commands that follow \"then"\ is the last value it took on inside the loop. At
-the end of the \"if"\ command, the value of \$thisaddress$\ is reset to what it
-was before. It is best to avoid the use of multiple occurrences of
-\"foranyaddress"\, nested or otherwise, in a single \"if"\ command, if the
-value of \$thisaddress$\ is to be used afterwards, because it isn't always
-clear what the value will be. Nested \"if"\ commands should be used instead.
-
-Header lines can be joined together if a check is to be applied to more than
-one of them. For example:
-.display asis
-if foranyaddress $h_to:,$h_cc: ....
-.endd
-scans through the addresses in both the \To:\ and the \Cc:\ headers.
-
-.section Testing for personal mail
-.rset SECTpersonal "~~chapter.~~section"
-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 `vacation
-messages'.
-
-.em
-The \"personal"\ condition checks that the message is not a bounce message and
-that the current user's email address appears in the \"To:"\ 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 \"List-"\ in the message.
-Finally, it checks the content of the \"Precedence:"\ header line, if there is
-one.
-
-You should always use the \"personal"\ condition when generating automatic
-responses.
-.nem
-This example shows the use of \"personal"\ in a filter file that is sending out
-vacation messages:
-.display asis
-if personal then
- mail
- to $reply_address
-.newline
-.em
- subject "I am on holiday"
-.nem
-.newline
- file $home/vacation/message
- once $home/vacation/once
- once_repeat 10d
-endif
-.endd
-.em
-It is tempting, when writing commands like the above, to quote the original
-subject in the reply. For example:
-.display asis
-subject "Re: $h_subject:"
-.endd
-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.
-
-If prefixes or suffixes are in use for local parts -- something which depends
-on the configuration of Exim (see section ~~SECTmbox below) -- 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
-`dag46' as `Dirk.Gently', the rewritten form of the address is also used in the
-tests.
-.nem
-
-.em
-.section Alias addresses for the personal condition
-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 \"personal"\ condition keyword can be followed by
-.display
-alias <<address>>
-.endd
-any number of times, for example
-.display asis
-if personal alias smith@else.where.example
- alias jones@other.place.example
-then ...
-.endd
-The alias addresses are treated as alternatives to the current user's email
-address when testing the contents of header lines.
-.nem
-
-
-.em
-.section Details of the personal condition
-The basic \"personal"\ test is roughly equivalent to the following:
-.display flow asis
-not error_message and
-$message_headers does not contain "\nList-" and
-$header_auto-submitted: does not contain "auto-" 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-[^@]+@"
- )
-.endd
-The variable \$local@_part$\ contains the local part of the mail address of
-the user whose filter file is being run -- it is normally your login id. The
-\$domain$\ 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.
-.nem
-
-
-.section Testing delivery status
-There are two conditions that are intended mainly for use in system filter
-files, but which are available in users' filter files as well. The condition
-\"first@_delivery"\ 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 `first delivery'.
-
-In a user filter file \"first@_delivery"\ will be false only 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.
-
-The condition \"manually@_thawed"\ is true only if the message was `frozen' for
-some reason, and was subsequently released by the system administrator. It is
-unlikely to be of use in users' filter files.
-
-.section Multiple personal mailboxes
-.rset SECTmbox "~~chapter.~~section"
-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.
-
-The facility involves the use of a prefix or a suffix on an email address. For
-example, all mail addressed to \lg303-<<something>>\ would be the property of
-user \lg303\, who could determine how it was to be handled, depending on the
-value of <<something>>.
-
-There are two possible ways in which this can be set up. The first possibility
-is the use of multiple \(.forward)\ files. In this case, mail to \lg303-foo\,
-for example, is handled by looking for a file called \.forward-foo\ in
-\lg303's\ home directory. If such a file does not exist, delivery fails and the
-message is returned to its sender.
-
-The alternative approach is to pass all messages through a single \(.forward)\
-file, which must be a filter file so that it can distinguish between the
-different cases by referencing the variables \$local@_part@_prefix$\ or
-\$local@_part@_suffix$\, as in the final example in section ~~SECTex below.
-
-It is possible to configure Exim to support both schemes at once. In this case,
-a specific \.forward-foo\ file is first sought; if it is not found, the basic
-\(.forward)\ file is used.
-
-The \"personal"\ test (see section ~~SECTpersonal) includes prefixes and
-suffixes in its checking.
-
-
-.section Ignoring delivery errors
-As was explained above, filtering just sets up addresses for delivery -- 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 \"noerror"\, errors for that delivery,
-$it{and any deliveries consequent on it} (that is, from alias, forwarding, or
-filter files it invokes) are ignored.
-
-
-.section Examples of Exim filter commands
-.rset SECTex "~~chapter.~~section"
-Simple forwarding:
-.display asis
-# Exim filter
-deliver baggins@rivendell.middle-earth.example
-.endd
-Vacation handling using traditional means, assuming that the \.vacation.msg\
-and other files have been set up in your home directory:
-.display asis
-# Exim filter
-unseen pipe "/usr/ucb/vacation \"$local_part\""
-.endd
-Vacation handling inside Exim, having first created a file called
-\.vacation.msg\ in your home directory:
-.display asis
-# Exim filter
-if personal then vacation endif
-.endd
-File some messages by subject:
-.display asis
-# Exim filter
-if $header_subject: contains "empire" or
- $header_subject: contains "foundation"
-then
- save $home/mail/f+e
-endif
-.endd
-Save all non-urgent messages by weekday:
-.display asis
-# Exim filter
-if $header_subject: does not contain "urgent" and
- $tod_full matches "^(...),"
-then
- save $home/mail/$1
-endif
-.endd
-Throw away all mail from one site, except from postmaster:
-.display asis
-# Exim filter
-if $reply_address contains "@spam.site.example" and
- $reply_address does not contain "postmaster@"
-then
- seen finish
-endif
-.endd
-.if ~~sgcal
-.if ~~sys.leftonpage < 6ld
-.newpage
-.fi
-.fi
-Handle multiple personal mailboxes
-.display asis
-# 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
-.endd
-
-. End of filter
+++ /dev/null
-. $Cambridge: exim/doc/doc-src/spec.src,v 1.9 2008/01/16 09:51:00 tom Exp $
-.
-.set version "4.50"
-.set previousversion "4.40"
-.set versionmonth "February"
-.set versionyear "2005"
-.set ACL "ACL"
-
-. The last of those is to make ACL index entries easier to type. It is put
-. up here so that it gets picked up by the HTML converter, which otherwise
-. skips to the first chapter. A longer version is set below for use in the
-. printed index.
-
-.set sgcal true
-.set html false
-.set texinfo false
-
-.if !set style
-.library "a4ps"
-.linelength ~~sys.linelength + 0.2in
-.set newlinelength ~~sys.linelength
-.emphasis ~~sys.linelength + 0.1in
-.pagedepth ~~sys.pagedepth - 0.2in
-.bindfont 51 "atl/Times-Bold" 9
-.bindfont 52 "atl/Times-Roman" 9
-.bindfont 53 "atl/Times-Roman" 7
-.bindfont 54 "atl/Courier" 9
-.bindfont 55 "atl/Courier-Bold" ~~maintypesize
-.bindfont 56 "atl/Times-Italic" 7
-.bindfont 57 "atl/Times-Bold" 7
-.bindfont 58 "atl/Symbol" 7
-.set ssspaceb 1.50
-
-.if ~~sgcal
-. Used for the "small print" incorporated code stuff. Only rm, it, bf, sp are
-. actually used at present.
-. rm it sl bf bi ss tt sp sc
-.fontgroup 9 = 53 56 0 57 0 0 0 58 0
-.fi
-.fi
-
-.if !~~sys.fancy
-.fontgroup 9 = 0 0 0 0 0 0 0 0 0
-.fi
-
-.include "markup.sg"
-
-.if ~~sys.fancy
-.flag $smc{ "$push$g0$f54"
-.flag $sm{ "$push$g0$f53"
-.flag $smi{ "$push$g0$f56"
-.flag $as{ "$push$g0$f52"
-.flag $ab{ "$push$g0$f51"
-.flag $cb{ "$push$g0$f55"
-.
-.else
-.flag $smc{ "$push"
-.flag $sm{ "$push"
-.flag $smi{ "$push"
-.flag $cb{ "$push"
-.fi
-
-.macro isunderscore "string"
-.set string "~~1"
-.set length length "~~1"
-.undrec 1
-.endm
-
-.macro undrec "offset"
-.if ~~1 > ~~length
-.set underscore false
-.else
-.set sub "~~string"(1,~~1)
-.if "~~sub" == "_"
-.set underscore true
-.else
-.set next ~~1 + 1
-.undrec ~~next
-.fi
-.fi
-.endm
-
-.macro testunderscore "string"
-.isunderscore "~~1"
-.newline
-.endm
-
-.macro tabs 6
-.if ~~sys.fancy
-.tabset ~~1em
-.else
-.set temp (~~1 * 5)/4
-.tabset ~~temp em
-.fi
-.endm
-
-.macro startoptions
-.newline
-.push
-.if ~~sys.fancy
-.indent 6em
-.else
-.indent 7em
-.fi
-.endm
-
-.macro endoptions
-.newline
-.pop
-.endm
-
-.macro option "option" ""
-.newpar
-.index \-~~1-\ option
-.tempindent 0
-\-~~1-\~~2#$i
-.nosep
-.endm
-
-.macro startitems
-.newline
-.push
-.indent 3em
-.endm
-
-.macro enditems
-.newline
-.pop
-.endm
-
-.macro item "item" "6"
-.newpar
-.if ~~sys.leftonpage < ~~2ld
-.newpage
-.fi
-.tempindent 0
-\**~~1**\
-.blank
-.endm
-
-.macro startconf ""
-.set confsection "~~1"
-.newline
-.push
-.if ~~sys.fancy
-.indent 2em
-.tabset 9em
-.else
-.indent 4em
-.tabset 13em
-.fi
-.endm
-
-.macro endconf
-.newline
-.pop
-.endm
-
-.macro conf "option" "type" "default" "6"
-.newpar
-.if ~~sys.leftonpage < ~~4ld
-.newpage
-.fi
-.testunderscore "~~1"
-.if ~~underscore
-.index \~~1\
-.else
-.index \~~1\ option
-.fi
-.if "~~confsection" == ""
-.set inssect ""
-.else
-.set inssect "$rm{Use:} $it{~~confsection}###"
-.fi
-.tempindent 0
-\**~~1**\ $c ~~inssect$rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3}
-.blank
-.endm
-
-.set contents true
-.set figurenumber -1
-.set displayindent 2em
-
-.index @$1, @$2, etc. $it{see numerical variables}
-.index address||rewriting $it{see rewriting}
-.index CR character $it{see carriage return}
-.index CRL $it{see certificate revocation list}
-.index delivery||failure report $it{see bounce message}
-.index dialup $it{see intermittently connected hosts}
-.index exiscan $it{see content scanning}
-.index failover $it{see fallback}
-.index fallover $it{see fallback}
-.index filter||Sieve $it{see Sieve filter}
-.index ident $it{see RFC 1413}
-.index LF character $it{see linefeed}
-.index maximum $it{see limit}
-.index NUL $it{see binary zero}
-.index passwd file $it{see \(/etc/passwd)\}
-.index process id $it{see pid}
-.index RBL $it{see DNS list}
-.index redirection $it{see address redirection}
-.index return path||$it{see also envelope sender}
-.index scanning $it{see content scanning}
-.index SSL $it{see TLS}
-.index string||expansion $it{see expansion}
-.index top bit $it{see 8-bit characters}
-.index variables $it{see expansion, variables}
-.index zero, binary $it{see binary zero}
-
-. This is used for the printed index. See setting above for
-. the HTML index value.
-
-.set ACL "access control lists (ACLs)"
-
-. ======================================================
-
-.push
-.disable filling
-.justify centre
-.nofoot
-.space 8ld
-$chead{University of Cambridge Computing Service}
-.space 2ld
-$chead{Specification of the Exim Mail Transfer Agent}
-.space 3ld
-by
-.space 1ld
-Philip Hazel
-.space ~~sys.leftonpage - 15*~~sys.linedepth
-.justify left
-University Computing Service
-New Museums Site
-Pembroke Street
-Cambridge CB2 3QH
-United Kingdom
-.blank
-.tabs 6
-$it{phone:} $t +44 1223 334600
-$it{fax:} $t +44 1223 334679
-$it{email:} $t ph10 $it{at} cus.cam.ac.uk
-.blank
-Edition for Exim ~~version, ~~versionmonth ~~versionyear
-.space 2ld
-.if ~~sgcal
-.fontgroup 1
-.fi
-$c$rm{Copyright (c) University of Cambridge ~~versionyear}
-
-
-.if ~~sgcal
-.fontgroup 0
-.font 0
-.fi
-
-.pop
-.newpage
-
-. Blank verso for title page
-.space 1ld
-.newpage
-
-
-. Set up for actual text pages
-.page 1
-. The first one to prevent a warning from sgfr
-. set runningfoot "~~chapter"
-.set runningfoot ""
-
-.if ~~sys.fancy
-.footdepth 2ld
-.foot
-.if "~~runningfoot" == ""
-.set rhs ""
-.else
-.set rhs "~~runningfoot (~~chapter)"
-.fi
-.set lhs "Exim ~~version"
-.linelength ~~newlinelength
-$it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs}
-.endfoot
-.fi
-
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter Introduction
-.set runningfoot "introduction"
-
-.if ~~sys.fancy
-$c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton)
-.elif !~~html
-$c"If I have seen further it is by standing on the shoulders of giants."
-.newline
-$e (Isaac Newton)
-.else
-\*If I have seen further it is by standing on the shoulders of giants.*\
-(Isaac Newton).
-.fi
-.blank 4
-
-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.
-
-Configuration files currently exist for the following operating systems: AIX,
-BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux,
-HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, 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.
-
-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.
-
-The terms and conditions for the use and distribution of Exim are contained in
-the file \(NOTICE)\. Exim is distributed under the terms of the GNU General
-Public Licence, a copy of which may be found in the file \(LICENCE)\.
-
-The use, supply or promotion of Exim for the purpose of sending bulk,
-unsolicited electronic mail is incompatible with the basic aims of the program,
-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.
-
-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.
-
-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
-\(ACKNOWLEDGMENTS)\, in which I have started recording the names of
-contributors.
-
-
-.section Exim documentation
-.index documentation
-.em
-This edition of the Exim specification applies to version ~~version of Exim.
-Substantive changes from the ~~previousversion edition are marked by bars in
-the right-hand margin in the PostScript, PDF, and plain text versions of the
-document, and by green text in the HTML version, as shown by this paragraph.
-Changes are not marked in the Texinfo version, because Texinfo doesn't support
-change bars. Minor corrections and rewordings are not marked.
-.nem
-
-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, the 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.
-
-.index books about Exim
-An `easier' discussion of Exim which provides more in-depth explanatory,
-introductory, and tutorial material can be found in a book entitled
-.if ~~html
-[(A HREF="http://www.uit.co.uk/exim-book/")]
-$it{The Exim SMTP Mail Server},
-[(/A)]
-published by UIT Cambridge.
-.else
-$it{The Exim SMTP Mail Server}, published by UIT Cambridge
-(\?http://www.uit.co.uk/exim-book/?\).
-.fi
-
-This 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'Reilly, covers Exim 3, and many things have changed in Exim 4.)
-
-.index \(doc/NewStuff)\
-.index \(doc/ChangeLog)\
-.index change log
-As the program 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
-\(doc/NewStuff)\ in the Exim distribution.
-
-.em
-Some features may be classified as `experimental'. 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 \(doc/experimental.txt)\.
-.nem
-
-All changes to the program (whether new features, bug fixes, or other kinds of
-change) are noted briefly in the file called \(doc/ChangeLog)\.
-
-.index \(doc/spec.txt)\
-This specification itself is available as an ASCII file in \(doc/spec.txt)\ so
-that it can easily be searched with a text editor. Other files in the \(doc)\
-directory are:
-.display rm
-.tabs 18
-\(OptionLists.txt)\ $t $rm{list of all options in alphabetical order}
-\(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries}
-\(exim.8)\ $t $rm{a man page of Exim's command line options}
-.newline
-.em
-\(experimental.txt)\ $t $rm{documentation of experimental features}
-.nem
-.newline
-\(filter.txt)\ $t $rm{specification of the filter language}
-\(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions}
-\(pcretest.txt)\ $t $rm{specification of the PCRE testing program}
-\(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3}
-\(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4}
-.endd
-The main specification and the specification of the filtering language are also
-available in other formats (HTML, PostScript, PDF, and Texinfo). Section
-~~SECTavail below tells you how to get hold of these.
-
-
-.section FTP and web sites
-.index web site
-.index FTP site
-.em
-The primary distribution site for Exim is currently the University of
-Cambridge's FTP site, whose contents are described in \*Where to find the Exim
-distribution*\ below. In addition, there is a
-.if ~~html
-[(A HREF="http://www.exim.org/")]
-.fi
-web site
-.if ~~html
-[(/A)]
-.fi
-and an
-.if ~~html
-[(A HREF="ftp://ftp.exim.org/")]
-.fi
-FTP site
-.if ~~html
-[(/A)]
-.fi
-at \exim.org\. These are now also hosted at the University of Cambridge.
-The \exim.org\ site was previously hosted for a number of years by Energis
-Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge.
-
-As well as Exim distribution tar files, the Exim web site contains a number of
-differently formatted versions of the documentation, including the
-.index FAQ
-.if ~~html
-[(A HREF="FAQ.html")]
-.fi
-FAQ
-.if ~~html
-[(/A)]
-.fi
-in both text and HTML formats. The HTML version comes with a keyword-in-context
-index. A recent addition to the online information is the
-.index wiki
-.if ~~html
-[(A HREF="http://www.exim.org/eximwiki/")]
-Exim wiki.
-[(/A)]
-.else
-Exim wiki (\?http://www.exim.org/eximwiki/?\).
-.fi
-We hope that this will make it easier for Exim users to contribute examples,
-tips, and know-how for the benefit of others.
-.nem
-
-.section Mailing lists
-.index mailing lists||for Exim users
-.em
-The following are the three main Exim mailing lists:
-.display rm
-.tabs 28
-$it{exim-users@@exim.org} $t general discussion list
-$it{exim-dev@@exim.org} $t discussion of bugs, enhancements, etc.
-$it{exim-announce@@exim.org} $t moderated, low volume announcements list
-.endd
-.nem
-You can subscribe to these lists, change your existing subscriptions, and view
-or search the archives via the
-.if ~~html
-[(A HREF="http://www.exim.org/maillist.html")]
-.fi
-mailing lists
-.if ~~html
-[(/A)]
-.fi
-link on the Exim home page. The $it{exim-users} mailing list is also forwarded
-to \?http://www.egroups.com/list/exim-users?\, an archiving system with
-searching capabilities.
-
-.section Exim training
-.index training courses
-From time to time (approximately annually at the time of writing),
-lecture-based training courses are run by the author of Exim in Cambridge, UK.
-Details can be found on the web site
-.if ~~html
-[(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")]
-.fi
-\?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\.
-.if ~~html
-[(/A)]
-.fi
-
-.section Bug reports
-.index bug reports
-.index reporting bugs
-Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. 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 $it{exim-users} mailing list and have it discussed.
-
-
-.em
-.section Where to find the Exim distribution
-.rset SECTavail "~~chapter.~~section"
-.index FTP site
-.index distribution||ftp site
-The master ftp site for the Exim distribution is
-.display rm
-.if ! ~~sys.fancy
-.indent 0
-.fi
-\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\
-.endd
-This is mirrored by
-.display rm
-.if ! ~~sys.fancy
-.indent 0
-.fi
-\?ftp://ftp.exim.org/pub/exim?\
-.endd
-The file references that follow are relative to the \(exim)\ directories at
-these sites.
-
-There are now quite a number of independent mirror sites around the world.
-Those that I know about are listed in the file called \(Mirrors)\.
-
-Within the \(exim)\ directory there are subdirectories called \(exim3)\ (for
-previous Exim 3 distributions), \(exim4)\ (for the latest Exim 4
-distributions), and \(Testing)\ for testing versions. In the \(exim4)\
-subdirectory, the current release can always be found in files called
-.display rm
-\(exim-$it{n.nn}.tar.gz)\
-\(exim-$it{n.nn}.tar.bz2)\
-.endd
-where $it{n.nn} is the highest such version number in the directory. The two
-files contain identical data; the only difference is the type of compression.
-The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file.
-.index distribution||signing details
-.index distribution||public key
-.index public key for signed distribution
-The distributions are currently signed with Philip Hazel's GPG key. The
-corresponding public key is available from a number of keyservers, and there is
-also a copy in the file \(Public-Key)\. The signatures for the tar bundles are
-in:
-.display rm
-\(exim-$it{n.nn}.tar.gz.sig)\
-\(exim-$it{n.nn}.tar.bz2.sig)\
-.endd
-For each released version, the log of changes is made separately available in a
-separate file in the directory \(ChangeLogs)\ so that it is possible to
-find out what has changed without having to download the entire distribution.
-
-.index documentation||available formats
-The main distribution contains ASCII versions of this specification and other
-documentation; other formats of the documents are available in separate files
-inside the \(exim4)\ directory of the FTP site:
-.display rm
-\(exim-html-$it{n.nn}.tar.gz)\
-\(exim-pdf-$it{n.nn}.tar.gz)\
-\(exim-postscript-$it{n.nn}.tar.gz)\
-\(exim-texinfo-$it{n.nn}.tar.gz)\
-.endd
-These tar files contain only the \(doc)\ directory, not the complete
-distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms.
-
-.index FAQ
-The FAQ is available for downloading in two different formats in these files:
-.display rm
-\(exim4/FAQ.txt.gz)\
-\(exim4/FAQ.html.tar.gz)\
-.endd
-The first of these is a single ASCII file that can be searched with a text
-editor. The second is a directory of HTML files, normally accessed by starting
-at \(index.html)\. The HTML version of the FAQ (which is also included in the
-HTML documentation tarbundle) includes a keyword-in-context index, which is
-often the most convenient way of finding your way around.
-
-.section Wish list
-.index wish list
-A wish list is maintained, containing ideas for new features that have been
-submitted. From time to time the file is exported to the ftp site into the file
-\(exim4/WishList)\. Items are removed from the list if they get implemented.
-
-
-.section Contributed material
-.index contributed material
-At the ftp site, there is a directory called \(Contrib)\ that contains
-miscellaneous files contributed to the Exim community by Exim users. There is
-also a collection of contributed configuration examples in
-\(exim4/config.samples.tar.gz)\. These samples are referenced from the FAQ.
-.nem
-
-.section Limitations
-.index limitations of Exim
-.numberpars $.
-Exim is designed for use as an Internet MTA, and therefore handles addresses
-in RFC 2822 domain format only.
-.index bang paths||not handled by Exim
-It cannot handle UUCP `bang paths', 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.
-.nextp
-.index domainless addresses
-.index address||without domain
-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.
-.nextp
-.index transport||external
-.index external transports
-The only external transport currently implemented is an SMTP transport over a
-TCP/IP network (using sockets, including support for IPv6). However, a pipe
-transport is available, and there are facilities for writing messages to files
-and pipes, optionally in \*batched SMTP*\ format; these facilities can be used
-to send messages to some other transport mechanism such as UUCP, provided it
-can handle domain-style addresses. Batched SMTP input is also catered for.
-.nextp
-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 `delivered' into files
-(that is, off Exim's queue) and subsequently passed on to the dial-in hosts by
-other means.
-.nextp
-.em
-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.
-.nem
-.endp
-
-
-
-.section Run time configuration
-Exim's run time 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 ~~CHAPdefconfil below.
-
-
-.section Calling interface
-.index Sendmail compatibility||command line interface
-Like many MTAs, Exim has adopted the Sendmail command line interface so that it
-can be a straight replacement for \(/usr/lib/sendmail)\ or
-\(/usr/sbin/sendmail)\ 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, \-bp-\, which lists the messages on the queue) do so in Exim'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 ~~CHAPcommandline
-documents all Exim's command line options. This information is automatically
-made into the man page that forms part of the Exim distribution.
-
-Control of messages on the queue can be done via certain privileged command
-line options. There is also an optional monitor program called \*eximon*\, which
-displays current information in an X window, and which contains a menu
-interface to Exim's command line administration options.
-
-
-.section Terminology
-.index terminology definitions
-.index body of message||definition of
-The \*body*\ 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 \*header*\ (see
-below) by a blank line.
-
-.index bounce message||definition of
-When a message cannot be delivered, it is normally returned to the sender in a
-delivery failure message or a `non-delivery report' (NDR). The term \*bounce*\
-is commonly used for this action, and the error reports are often called
-\*bounce messages*\. This is a convenient shorthand for `delivery failure error
-report'. Such messages have an empty sender address in the message's
-\*envelope*\ (see below) to ensure that they cannot themselves give rise to
-further bounce messages.
-
-The term \*default*\ 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.
-
-The term \*defer*\ 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's local mailbox may be full). Such deliveries are \*deferred*\
-until a later time.
-
-The word \*domain*\ is sometimes used to mean all but the first component of a
-host's name. It is $it{not} used in that sense here, where it normally
-refers to the part of an email address following the @@ sign.
-
-.index envelope, definition of
-.index sender||definition of
-A message in transit has an associated \*envelope*\, 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.
-
-.index message||header, definition of
-.index header section||definition of
-The \*header*\ of a message is the first part of a message's text, consisting
-of a number of lines, each of which has a name such as ::From::, ::To::,
-::Subject::, 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.
-
-.index local part||definition of
-.index domain||definition of
-The term \*local part*\, which is taken from RFC 2822, is used to refer to that
-part of an email address that precedes the @@ sign. The part that follows the
-@@ sign is called the \*domain*\ or \*mail domain*\.
-
-.index local delivery||definition of
-.index remote delivery, definition of
-The terms \*local delivery*\ and \*remote delivery*\ are used to distinguish
-delivery to a file or a pipe on the local host from delivery by SMTP over
-TCP/IP to a remote host.
-
-.index return path||definition of
-\*Return path*\ is another name that is used for the sender address in a
-message's envelope.
-
-.index queue||definition of
-The term \*queue*\ 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's case the reality is more like a pool than a queue, because there is
-normally no ordering of waiting messages.
-
-.index queue runner||definition of
-The term \*queue runner*\ 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 \runq\, but in Exim
-the waiting messages are normally processed in an unpredictable order.
-
-.index spool directory||definition of
-The term \*spool directory*\ is used for a directory in which Exim keeps the
-messages on its queue -- 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 `spool directory' by some people. In
-the Exim documentation, `spool' is always used in the first sense.
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter Incorporated code
-.set runningfoot "incorporated code"
-.index incorporated code
-.index regular expressions||library
-.index PCRE
-A number of pieces of external code are included in the Exim distribution.
-.numberpars $.
-Regular expressions are supported in the main Exim program and in the Exim
-monitor using the freely-distributable PCRE library, copyright (c) University
-of Cambridge. The source is distributed in the directory \(src/pcre)\. However,
-this is a cut-down version of PCRE. If you want to use the PCRE library in
-other programs, you should obtain and install the full version from
-\?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\.
-
-.space 1ld
-.nextp
-.index cdb||acknowledgement
-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. which contains the following statements:
-.rule
-.push
-.if ~~sgcal
-.fontgroup 9
-.font 0
-.fi
-Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd
-
-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's Constant DataBase (cdb) spec. Information,
-the spec and sample code for cdb can be obtained from
-\?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code
-from Dan Bernstein's implementation (which has no license restrictions applied
-to it).
-.newline
-.pop
-.rule
-The implementation is completely contained within the code of Exim.
-It does not link against an external cdb library.
-.space 1ld
-.nextp
-.index SPA authentication
-.index Samba project
-.index Microsoft Secure Password Authentication
-Client support for Microsoft's \*Secure Password Authentication*\ is provided
-by code contributed by Marc Prud'hommeaux. Server support was contributed by
-Tom Kistner. This includes code taken from the Samba project, which is released
-under the Gnu GPL.
-
-.space 1ld
-.nextp
-.index Cyrus
-.index \*pwcheck*\ daemon
-.index \*pwauthd*\ daemon
-Support for calling the Cyrus \*pwcheck*\ and \*saslauthd*\ 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.
-
-.rule
-.push
-.if ~~sgcal
-.fontgroup 9
-.font 0
-.fi
-Copyright (c) 2001 Carnegie Mellon University. All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions
-are met:
-
-.if ~~sgcal
-.cancelflag $npbracket
-.flag $npbracket "" "."
-.fi
-.numberpars
-Redistributions of source code must retain the above copyright
-notice, this list of conditions and the following disclaimer.
-.nextp
-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.
-.nextp
-The name `Carnegie Mellon University' 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
-.display rm
-Office of Technology Transfer
-Carnegie Mellon University
-5000 Forbes Avenue
-Pittsburgh, PA 15213-3890
-(412) 268-4387, fax: (412) 268-7395
-tech-transfer@@andrew.cmu.edu
-.endd
-.nextp
-Redistributions of any form whatsoever must retain the following
-acknowledgment:
-.newline
-.push
-.indent ~~sys.indent + 3em
-.justify left
-$it{This product includes software developed by Computing Services
-at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).}
-.newline
-.pop
-.endp
-.if ~~sgcal
-.cancelflag $npbracket
-.flag $npbracket "(" ")"
-.fi
-
-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.
-.newline
-.pop
-.rule
-
-.space 1ld
-.nextp
-.index monitor
-.index X-windows
-.index Athena
-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.
-
-.rule
-.push
-.if ~~sgcal
-.fontgroup 9
-.font 0
-.fi
-Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts,
-and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
-.blank
-$c All Rights Reserved
-.blank
-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.
-
-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.
-.newline
-.pop
-.rule
-.space 1ld
-.nextp
-.em
-Many people have contributed code fragments, some large, some small, that were
-not covered by any specific licence requirements. It is assumed that the
-contributors are happy to see their code incoporated into Exim under the GPL.
-.nem
-.endp
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter How Exim receives and delivers mail
-.set runningfoot "receiving & delivering mail"
-
-.section Overall philosophy
-.index design philosophy
-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.
-
-
-.section Policy control
-.index policy control||overview
-Policy controls are now an important feature of MTAs that are connected to the
-Internet. Perhaps their most important job is to stop MTAs being abused as
-`open relays' 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:
-.numberpars $.
-.index ~~ACL||introduction
-Exim 4 (unlike previous versions of Exim) implements policy controls on
-incoming mail by means of \*Access Control Lists*\ (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 ~~CHAPACL). Denial of access results in an SMTP
-error code.
-.nextp
-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.
-.nextp
-.em
-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.
-.nem
-.nextp
-When a message has been received, either from a remote host or from the local
-host, but before the final acknowledgement has been sent, a locally supplied C
-function called \*local@_scan()*\ can be run to inspect the message and decide
-whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is
-accepted, the list of recipients can be modified by the function.
-.nextp
-.em
-Using the \*local@_scan()*\ mechanism is another way of calling external
-scanner software. The \SA-Exim\ add-on package works this way. It does not
-require Exim to be compiled with the content-scanning extension.
-.nem
-.nextp
-After a message has been accepted, a further checking mechanism is available in
-the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs
-at the start of every delivery process.
-.endp
-
-.section User filters
-.index filter||introduction
-.index Sieve filter
-In a conventional Exim configuration, users are able to run private filters by
-setting up appropriate \(.forward)\ files in their home directories. See
-chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration
-needed to support this, and the separate document entitled
-.if ~~html
-[(A HREF="filter_toc.html")]
-.fi
-\*Exim's interfaces to mail filtering*\
-.if ~~html
-[(/A)]
-.fi
-for user details. Two different kinds of filtering are available:
-.numberpars $.
-Sieve filters are written in the standard filtering language that is defined by
-RFC 3028.
-.nextp
-Exim filters are written in a syntax that is unique to Exim, but which is more
-powerful than Sieve, which it pre-dates.
-.endp
-User filters are run as part of the routing process, described below.
-
-
-.section Message identification
-.rset SECTmessiden "~~chapter.~~section"
-.index message||ids, details of format
-.index format||of message id
-.index id of message
-.index base62
-.index base36
-.index Darwin
-.index Cygwin
-Every message handled by Exim is given a \*message id*\ which is sixteen
-characters long. It is divided into three parts, separated by hyphens, for
-example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits,
-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 file names, and the names of files in those systems are
-not case-sensitive.
-
-.index pid (process id)||re-use of
-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:
-.numberpars $.
-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).
-.nextp
-After the first hyphen, the next six characters are the id of the process that
-received the message.
-.nextp
-There are two different possibilities for the final two characters:
-.numberpars alpha
-.index \localhost@_number\
-If \localhost@_number\ is not set, this value is the fractional part of the
-time of reception, normally in units of 1/2000 of a second, but for systems
-that must use base 36 instead of base 62 (because of case-insensitive file
-systems), the units are 1/1000 of a second.
-.nextp
-If \localhost@_number\ is set, it is multiplied by 200 (100) and added to
-the fractional part of the time, which in this case is in units of 1/200
-(1/100) of a second.
-.endp
-.endp
-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.
-
-.section Receiving mail
-.index receiving mail
-.index message||reception
-The only way Exim can receive mail from a remote host is using SMTP over
-TCP/IP, in which case the sender and recipient addresses are tranferred using
-SMTP commands. However, from a locally running process (such as a user's MUA),
-there are several possibilities:
-.numberpars $.
-If the process runs Exim with the \-bm-\ 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 \-t-\ is also used.
-.nextp
-If the process runs Exim with the \-bS-\ 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 so-called `batch SMTP' format,
-but it isn't really SMTP. The SMTP commands are just another way of passing
-envelope addresses in a non-interactive submission.
-.nextp
-If the process runs Exim with the \-bs-\ 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 `real' 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.
-.nextp
-A local process may also make a TCP/IP call to the host'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.
-.endp
-
-.index message||sender, constructed by Exim
-.index sender||constructed by Exim
-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 \qualify@_domain\ 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 (`trusted users') to specify a different sender address
-unconditionally, or all users to specify certain forms of different sender
-address. The \-f-\ option or the SMTP \\MAIL\\ command is used to specify these
-different addresses. See section ~~SECTtrustedadmin for details of trusted
-users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted
-users to change sender addresses.
-
-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 \*local@_scan()*\ function (see chapter
-~~CHAPlocalscan) is run for all incoming messages.
-
-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.
-
-
-
-
-.section Handling an incoming message
-.index spool directory||files that hold a message
-.index file||how a message is held
-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 $tt{-H} for
-the file containing the envelope and header, and $tt{-D} for the data file.
-
-.index spool directory||\(input)\ sub-directory
-By default all these message files are held in a single directory called
-\(input)\ inside the general Exim spool directory. Some operating systems do
-not perform very well if the number of files in a directory gets very large; to
-improve performance in such cases, the \split@_spool@_directory\ option can be
-used. This causes Exim to split up the input files into 62 sub-directories
-whose names are single letters or digits.
-
-The envelope information consists of the address of the message'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 ~~CHAPspool.
-
-.index rewriting||addresses
-Address rewriting that is specified in the rewrite section of the configuration
-(see chapter ~~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 ~~CHAProutergeneric and ~~CHAPtransportgeneric).
-
-
-.section Life of a message
-.index message||life of
-.index message||frozen
-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 -- for example, when a message can neither be delivered to its
-recipients nor returned to its sender, the message is marked `frozen' on the
-spool, and no more deliveries are attempted.
-
-.index frozen messages||thawing
-.index message||thawing frozen
-An administrator can `thaw' 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.
-
-.index \auto@_thaw\
-There is an option called \auto@_thaw\, which can be used to cause Exim to
-retry frozen messages after a certain time. When this is set, no message will
-remain on the queue for ever, because the delivery timeout will eventually be
-reached. Delivery failure reports (bounce messages) that reach this timeout are
-discarded.
-.index \timeout@_frozen@_after\
-There is also an option called \timeout@_frozen@_after\, which discards frozen
-messages after a certain time.
-
-.index message||log file for
-.index log||file for each message
-While Exim is working on a message, it writes information about each delivery
-attempt to the main log file. This includes successful, unsuccessful, and
-delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines
-are also written to a separate $it{message log} 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
-\no@_message@_logs\; this might give an improvement in performance on very
-busy systems.
-
-.index journal file
-.index file||journal
-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 $tt{-J}. At the end of a delivery run, if there are some
-addresses left to be tried again later, the first spool file (the $tt{-H} 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.
-
-Should the system or the program 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.
-
-
-.section Processing an address for delivery
-.rset SECTprocaddress "~~chapter.~~section"
-.index drivers||definition of
-.index router||definition of
-.index transport||definition of
-The main delivery processing elements of Exim are called $it{routers} and
-$it{transports}, and collectively these are known as $it{drivers}. Code for a
-number of them is provided in the source distribution, and compile-time options
-specify which ones are included in the binary. Run time options specify which
-ones are actually used for delivering messages.
-
-.index drivers||instance definition
-Each driver that is specified in the run time configuration is an \*instance*\
-of that particular driver type. Multiple instances are allowed; for example,
-you can set up several different \%smtp%\ 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's features in general.
-
-A $it{router} is a driver that operates on an address, either determining how
-its delivery should happen, by routing 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.
-
-A $it{transport} is a driver that transmits a copy of the message from Exim's
-spool to some destination. There are two kinds of transport: for a $it{local}
-transport, the destination is a file or a pipe on the local host, whereas for a
-$it{remote} 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.
-
-.index preconditions||definition of
-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. As a simple example, the diagram below illustrates how each
-recipient address in a message is processed in a small configuration of three
-routers that are configured in various ways.
-
-.if ~~sys.fancy
-.figure "Routing an address" rm
-.indent 0
-.call aspic -sgcal -nv
-centre ~~sys.linelength;
-magnify 0.8;
-boundingbox 30;
- ibox depth 14 "address";
-B: arrow down 44;
- textdepth 14;
-A: box width 100 "first router" "conditions ok?";
- arrow right "yes";
-C: box width 100 "run" "first router";
- arrow down "fail";
-D: ibox depth 20 "address bounces";
-
- arc clockwise from right of C "accept";
- arrow down 10;
- ibox "queue for" "transport";
-
- arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r;
-E: box width 100 "second router" "conditions ok?";
- arrow right "yes";
-F: box width 100 "run" "second router";
- line right 100 "redirect";
- line up align middle of B;
- arrow left to middle of B "new addresses";
-
- line down 20 from bottom left of F plus (30,0);
- arrow left align centre of E "decline";
-
- line down 20 from bottom right of F plus (-30,0);
- arrow right "fail";
- ibox width 64 "address" "bounces";
-
- arrow down 64 from E "no"(-6,20)/r;
-G: box width 100 "third router" "conditions ok?";
- arrow right "yes";
-H: box width 100 "run" "third router";
- arc clockwise from right of H "accept";
- arrow down 10;
- ibox "queue for" "transport";
-
- line down 20 from bottom of H;
- arrow left align centre of G "decline";
- arrow down 64 from G "no"(-6,20)/r;
-
- ibox "no more routers" "address bounces";
-.endcall
-.endfigure
-.elif !~~html
-.display asis
-
- address
- |
- |<------------- new addresses -----------------------------
- V |
- ----------------- ----------------- |
- | first router |----- yes ----->| run |--- accept |
- | conditions ok?| | first router | | |
- ----------------- ----------------- | |
- | | V |
- no | fail | queue for |
- | V transport |
- | address bounces |
- | |
- V |
- ----------------- ----------------- |
- | second router |----- yes ----->| run |----redirect ----
- | conditions ok?| | second router |
- ----------------- -----------------
- | | |
- no | | |
- |<-------- decline ----------- --- fail ---> address
- | bounces
- V
- ----------------- -----------------
- | third router |----- yes ----->| run |--- accept
- | conditions ok?| | third router | |
- ----------------- ----------------- |
- | | V
- no | | queue for
- |<-------- decline --------------- transport
- |
- V
- no more routers
- address bounces
-.endd
-.else
-[(img src="routing.gif" alt="Routing an address")][(br)]
-.fi
-To make this a more concrete example, we'll describe it in terms of some actual
-routers, but remember, this is only an example. You can configure Exim's
-routers in many different ways, and there may be any number of routers in a
-configuration.
-
-The first router that is specified in a configuration is often one that handles
-addresses in domains that are not recognized specially by the local host. These
-are typically 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 $it{not}
-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
-queued for a suitable SMTP transport; if it does not succeed, the router is
-configured to fail the address.
-
-The example pictured could be a configuration of this type. The second and
-third routers can only be run for addresses for which the preconditions for
-the first router are not met. If one of these preconditions checks the
-domain, the second and third routers are run only for domains that are somehow
-special to the local host.
-
-The second router does redirection -- 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.
-
-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.
-
-
-.section Processing an address for verification
-.index router||for verification
-.index verifying||address, overview
-As well as being used to decide how to deliver to an address, Exim's routers
-are also used for \*address verification*\. 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 \-bv-\ and
-\-bvs-\ command line options.
-
-When an address is being verified, the routers are run in `verify mode'. 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 \no@_verify\ option
-would be set for such a router, causing it to be skipped in verify mode.
-
-
-
-.section Running an individual router
-.rset SECTrunindrou "~~chapter.~~section"
-.index router||running details
-.index preconditions||checking
-.index router||result of running
-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 $it{are} met,
-the router is run. What happens next depends on the outcome, which is one of
-the following:
-.numberpars $.
-\*accept*\: The router accepts the address, and either queues it for a
-transport, or generates one or more `child' addresses. Processing the original
-address ceases,
-.index \unseen\ option
-unless the \unseen\ 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 \unseen\ is set, the address is
-passed to the next router. Normally, however, an \*accept*\ return marks the
-end of routing.
-
-.index case of local parts
-.index address||duplicate, discarding
-If child addresses are generated, Exim checks to see whether they are
-duplicates of any existing recipient addresses. During this check, local parts
-are treated as case-sensitive. Duplicate addresses are discarded. Each of the
-remaining child addresses is then processed independently, starting with the
-first router by default. It is possible to change this by setting the
-\redirect@_router\ option to specify which router to start at for child
-addresses. Unlike \pass@_router\ (see below) the router specified by
-\redirect@_router\ may be anywhere in the router configuration.
-.nextp
-\*pass*\: 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
-\pass@_router\ option. However, (unlike \redirect@_router\) the named router
-must be below the current router (to avoid loops).
-.nextp
-\*decline*\: 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 \no@_more\ option. When \no@_more\ is set,
-all the remaining routers are skipped.
-.nextp
-\*fail*\: 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 \unseen\ is set on the router.
-.nextp
-\*defer*\: 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.
-.nextp
-\*error*\: There is some error in the router (for example, a syntax error in
-its configuration). The action is as for defer.
-.endp
-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 `unrouteable address', but you
-can set your own message by making use of the \cannot@_route@_message\ option.
-This can be set for any router; the value from the last router that `saw'
-the address is used.
-
-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 \%redirect%\ router has a `fail'
-facility for this purpose.
-
-
-
-.section Router preconditions
-.rset SECTrouprecon "~~chapter.~~section"
-.index router||preconditions, order of processing
-.index preconditions||order of processing
-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 ~~CHAProutergeneric.
-.numberpars $.
-The \local@_part@_prefix\ and \local@_part@_suffix\ options can specify that
-the local parts handled by the router may or must have certain prefixes and/or
-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.
-.nextp
-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
-\verify\ option is set false, the router is skipped when Exim is verifying an
-address.
-Setting the \verify\ option actually sets two options, \verify@_sender\ and
-\verify@_recipient\, 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.
-.nextp
-If the \address@_test\ option is set false, the router is skipped when Exim is
-run with the \-bt-\ 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 \-bt-\ to test subsequent delivery routing without having to
-simulate the effect of the scanner.
-.nextp
-Routers can be designated for use only when verifying an address, as
-opposed to routing it for delivery. The \verify@_only\ option controls this.
-.nextp
-Certain routers can be explicitly skipped when running the routers to check an
-address given in the SMTP \\EXPN\\ command (see the \expn\ option).
-.nextp
-If the \domains\ option is set, the domain of the address must be in the set of
-domains that it defines.
-.nextp
-If the \local@_parts\ option is set, the local part of the address must be in
-the set of local parts that it defines. If \local@_part@_prefix\ or
-\local@_part@_suffix\ 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 \condition\ option (see below)
-that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and
-\$local@_part@_suffix$\ as necessary.
-.nextp
-If the \check@_local@_user\ 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
-\$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the
-remaining preconditions.
-.nextp
-If the \router@_home@_directory\ option is set, it is expanded at this point,
-because it overrides the value of \$home$\. If this expansion were left till
-later, the value of \$home$\ as set by \check@_local@_user\ would be used in
-subsequent tests. Having two different values of \$home$\ in the same router
-could lead to confusion.
-.nextp
-If the \senders\ option is set, the envelope sender address must be in the set
-of addresses that it defines.
-.nextp
-If the \require@_files\ option is set, the existence or non-existence of
-specified files is tested.
-.nextp
-.index customizing||precondition
-If the \condition\ 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 ~~CHAPexpand.
-.endp
-
-Note that \require@_files\ 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
-\exists\ expansion condition to make such tests within each condition. The
-\require@_files\ 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, \(.procmailrc)\).
-
-
-.section Delivery in detail
-.index delivery||in detail
-When a message is to be delivered, the sequence of events is as follows:
-.numberpars $.
-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
-.if ~~html
-[(A HREF="filter.html")]
-.fi
-\*Exim's interfaces to mail filtering*\.
-.if ~~html
-[(/A)]
-.fi
-.index Sieve filter||not available for system filter
-(\**Note**\: Sieve cannot be used for system filter files.)
-Some additional features are available in system filters -- see chapter
-~~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 \first@_delivery\ can be used to detect the first run of the system
-filter.
-.nextp
-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.
-.nextp
-.index routing||loops in
-.index loop||while routing
-A router that accepts an address may set up a local or a remote transport for
-it. However, the transport is not run at this time. Instead, the address is
-placed on a list for the particular transport, to 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.
-.nextp
-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.
-.nextp
-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 (`the Exim user'), 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 \remote@_max@_parallel\ option.
-The order in which deliveries are done is not defined, except that all local
-deliveries happen before any remote deliveries.
-.nextp
-.index queue runner
-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).
-.nextp
-.index delivery||retry in remote transports
-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 ~~CHAPretry for details of retry strategies.
-.nextp
-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.
-.nextp
-.index delivery||deferral
-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
-\*deferred*\.
-.nextp
-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.
-.endp
-
-
-.section Retry mechanism
-.index delivery||retry mechanism
-.index retry||description of mechanism
-.index queue runner
-Exim'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 \-q-\ option with a time interval to start queue runners at regular
-intervals, or use some other means (such as \*cron*\) to start them. If you do
-not arrange for queue runners to be run, messages that fail temporarily at the
-first attempt will remain on your queue for ever. A queue runner process works
-it 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.
-
-Exim uses a set of configured rules to determine when next to retry the failing
-address (see chapter ~~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.
-
-
-.section Temporary delivery failure
-.index delivery||temporary failure
-There are many reasons why a message may not be immediately deliverable to a
-particular address. Failure to connect to a remote machine (because it, or the
-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.
-
-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,
-.index hints database
-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.
-
-
-
-.section Permanent delivery failure
-.index delivery||permanent failure
-.index bounce message||when generated
-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 ~~CHAPemsgcust for details.
-
-.index ::X-Failed-Recipients:: header line
-Bounce messages contain an ::X-Failed-Recipients:: header line that lists the
-failed addresses, for the benefit of programs that try to analyse such messages
-automatically.
-
-.index bounce message||recipient of
-A bounce message is normally sent to the sender of the original message, as
-obtained from the message'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 ~~SECTmailinglists) it is common to direct bounce messages to the
-manager of the list.
-
-
-
-.section Failures to deliver bounce messages
-.index bounce message||failure to deliver
-If a bounce message (either locally generated or received from a remote host)
-itself suffers a permanent delivery failure, the message is left on the queue,
-but it is frozen, awaiting the attention of an administrator. There are options
-which can be used to make Exim discard such failed messages, or to keep them
-for only a short time (see \timeout@_frozen@_after\ and
-\ignore@_bounce@_errors@_after\).
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter Building and installing Exim
-.set runningfoot "building/installing"
-
-.index building Exim
-.section Unpacking
-Exim is distributed as a gzipped or bzipped tar file which, when upacked,
-creates a directory with the name of the current release (for example,
-\(exim-~~version)\) into which the following files are placed:
-.display rm
-.if !~~sys.fancy && ~~sgcal
-.tabs 16
-.else
-.tabs 22
-.fi
-\(ACKNOWLEDGMENTS)\ $t contains some acknowledgments
-.newline
-\(CHANGES)\ $t contains a reference to where changes are documented
-\(LICENCE)\ $t the GNU General Public Licence
-\(Makefile)\ $t top-level make file
-\(NOTICE)\ $t conditions for the use of Exim
-\(README)\ $t list of files, directories and simple build instructions
-.endd
-Other files whose names begin with \(README)\ may also be present. The
-following subdirectories are created:
-.display rm
-.if !~~sys.fancy && ~~sgcal
-.tabs 16
-.else
-.tabs 22
-.fi
-\(Local)\ $t an empty directory for local configuration files
-\(OS)\ $t OS-specific files
-\(doc)\ $t documentation files
-\(exim@_monitor)\$t source files for the Exim monitor
-\(scripts)\ $t scripts used in the build process
-\(src)\ $t remaining source files
-\(util)\ $t independent utilities
-.endd
-The main utility programs are contained in the \(src)\ directory, and are built
-with the Exim binary. The \(util)\ directory contains a few optional scripts
-that may be useful to some sites.
-
-.section Multiple machine architectures and operating systems
-.index building Exim||multiple OS/architectures
-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 \(src)\ directory. Instead,
-a \*build directory*\ is created for each architecture and operating system.
-.index symbolic link||to build directory
-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.
-
-.section DBM libraries
-.rset SECTdb "~~chapter.~~section"
-.index DBM||libraries, discussion of
-.index hints database||DBM files used for
-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.
-
-.index Solaris||DBM library for
-.index IRIX, DBM library for
-.index BSD, DBM library for
-.index Linux, DBM library for
-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.
-
-.index \*ndbm*\ DBM library
-Licensed versions of Unix normally contain a library of DBM functions operating
-via the \*ndbm*\ 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 standardised on the
-Berkeley DB library.
-
-Different DBM libraries have different conventions for naming the files they
-use. When a program opens a file called \(dbmfile)\, there are four
-possibilities:
-.numberpars
-A traditional \*ndbm*\ implementation, such as that supplied as part of
-Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\.
-.nextp
-.index \*gdbm*\ DBM library
-The GNU library, \*gdbm*\, operates on a single file. If used via its \*ndbm*\
-compatibility interface it makes two different hard links to it with names
-\(dbmfile.dir)\ and \(dbmfile.pag)\, but if used via its native interface, the
-file name is used unmodified.
-.nextp
-.index Berkeley DB library
-The Berkeley DB package, if called via its \*ndbm*\ compatibility interface,
-operates on a single file called \(dbmfile.db)\, but otherwise looks to the
-programmer exactly the same as the traditional \*ndbm*\ implementation.
-.nextp
-If the Berkeley package is used in its native mode, it operates on a single
-file called \(dbmfile)\; the programmer's interface is somewhat different to
-the traditional \*ndbm*\ interface.
-.nextp
-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.$it{x} and 3.$it{x} were current for a while, but the latest versions are now
-numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All
-versions of Berkeley DB can be obtained from
-.display rm
-\?http://www.sleepycat.com/?\
-.endd
-.nextp
-.index \*tdb*\ DBM library
-Yet another DBM library, called \*tdb*\, has become available from
-.display rm
-\?http://download.sourceforge.net/tdb?\
-.endd
-It has its own interface, and also operates on a single file.
-.endp
-.index \\USE@_DB\\
-.index DBM||libraries, configuration for building
-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
-\(Local/Makefile)\). For example:
-.display asis
-USE_DB=yes
-.endd
-Similarly, for gdbm you set \\USE@_GDBM\\, and for tdb you set \\USE@_TDB\\. An
-error is diagnosed if you set more than one of these.
-
-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
-\(Local/Makefile)\, however, overrides these system defaults.
-
-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:
-.display asis
-DBMLIB = -ldb
-DBMLIB = -ltdb
-.endd
-Settings like that will work if the DBM library is installed in the standard
-place. Sometimes it is not, and the library's header file may also not be in
-the default path. You may need to set \\INCLUDE\\ to specify where the header
-file is, and to specify the path to the library more fully in \\DBMLIB\\, as in
-this example:
-.display asis
-INCLUDE=-I/usr/local/include/db-4.1
-DBMLIB=/usr/local/lib/db-4.1/libdb.a
-.endd
-
-There is further detailed discussion about the various DBM libraries in the
-file \(doc/dbm.discuss.txt)\ in the Exim distribution.
-
-
-.section Pre-building configuration
-.index building Exim||pre-building configuration
-.index configuration for building Exim
-.index \(Local/Makefile)\
-.index \(src/EDITME)\
-Before building Exim, a local configuration file that specifies options
-independent of any operating system has to be created with the name
-\(Local/Makefile)\. A template for this file is supplied as the file
-\(src/EDITME)\, 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
-\(src/EDITME)\ to \(Local/Makefile)\, then read it and edit it appropriately.
-
-There are three settings that you must supply, because Exim will not build
-without them. They are the location of the run time 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 file names; Exim uses the first of them that exists.
-
-There are a few other parameters that can be specified either at build time or
-at run time, to enable the same binary to be used on a number of different
-machines. However, if the locations of Exim's spool directory and log file
-directory (if not within the spool directory) are fixed, it is recommended that
-you specify them in \(Local/Makefile)\ instead of at run time, so that errors
-detected early in Exim's execution (such as a malformed configuration file) can
-be logged.
-
-.index content scanning||specifying at build time
-.em
-Exim's interfaces for calling virus and spam scanning sofware directly from
-access control lists are not compiled by default. If you want to include these
-facilities, you need to set
-.display asis
-WITH_CONTENT_SCAN=yes
-.endd
-in your \(Local/Makefile)\. For details of the facilities themselves, see
-chapter ~~CHAPexiscan.
-.nem
-
-.index \(Local/eximon.conf)\
-.index \(exim@_monitor/EDITME)\
-If you are going to build the Exim monitor, a similar configuration process is
-required. The file \(exim@_monitor/EDITME)\ must be edited appropriately for
-your installation and saved under the name \(Local/eximon.conf)\. If you are
-happy with the default settings described in \(exim@_monitor/EDITME)\,
-\(Local/eximon.conf)\ can be empty, but it must exist.
-
-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 name of the C compiler, which
-defaults to \gcc\. See section ~~SECToverride below for details of how to do
-this.
-
-
-.section Support for iconv()
-.index \*iconv()*\ support
-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 \@$h@_\
-mechanism, it decodes them, and translates them into a specified character set
-(default ISO-8859-1). The translation is possible only if the operating system
-supports the \*iconv()*\ function.
-
-However, some of the operating systems that supply \*iconv()*\ do not support
-very many conversions. The GNU \libiconv\ library (available from
-\?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to
-remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at
-all. After installing \libiconv\, you should add
-.display asis
-HAVE_ICONV=yes
-.endd
-to your \(Local/Makefile)\ and rebuild Exim.
-
-
-.section Including TLS/SSL encryption support
-.rset SECTinctlsssl "~~chapter.~~section"
-.index TLS||including support for TLS
-.index encryption||including support for
-.index \\SUPPORT@_TLS\\
-.index OpenSSL||building Exim with
-.index GnuTLS||building Exim with
-Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\
-command as per RFC 2487. It can also support legacy clients that expect to
-start a TLS session immediately on connection to a non-standard port (see the
-\tls@_on@_connect@_ports\ runtime option and the \-tls-on-connect-\ command
-line option).
-
-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.
-
-If OpenSSL is installed, you should set
-.display asis
-SUPPORT_TLS=yes
-TLS_LIBS=-lssl -lcrypto
-.endd
-in \(Local/Makefile)\. You may also need to specify the locations of the
-OpenSSL library and include files. For example:
-.display asis
-SUPPORT_TLS=yes
-TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
-TLS_INCLUDE=-I/usr/local/openssl/include/
-.endd
-
-If GnuTLS is installed, you should set
-.index \\USE@_GNUTLS\\
-.display asis
-SUPPORT_TLS=yes
-USE_GNUTLS=yes
-TLS_LIBS=-lgnutls -ltasn1 -lgcrypt
-.endd
-in \(Local/Makefile)\, and again you may need to specify the locations of the
-library and include files. For example:
-.display asis
-SUPPORT_TLS=yes
-USE_GNUTLS=yes
-TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
-TLS_INCLUDE=-I/usr/gnu/include
-.endd
-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 ~~CHAPTLS.
-
-
-
-.section Use of tcpwrappers
-.index tcpwrappers, building Exim to support
-.index \\USE@_TCP@_WRAPPERS\\
-Exim can be linked with the \*tcpwrappers*\ library in order to check incoming
-SMTP calls using the \*tcpwrappers*\ control files. This may be a convenient
-alternative to Exim's own checking facilities for installations that are
-already making use of \*tcpwrappers*\ for other purposes. To do this, you should
-set \\USE@_TCP@_WRAPPERS\\ in \(Local/Makefile)\, arrange for the file
-\(tcpd.h)\ to be available at compile time, and also ensure that the library
-\(libwrap.a)\ is available at link time, typically by including \-lwrap-\ in
-\\EXTRALIBS@_EXIM\\. For example, if \*tcpwrappers*\ is installed in
-\(/usr/local)\, you might have
-.display
-USE@_TCP@_WRAPPERS=yes
-CFLAGS=-O -I/usr/local/include
-.newline
-EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap
-.endd
-in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is
-`exim'. For example, the line
-.display
-exim : LOCAL 192.168.1. .friendly.domain.example
-.endd
-in your \(/etc/hosts.allow)\ file allows connections from the local host, from
-the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\.
-All other connections are denied. Consult the \*tcpwrappers*\ documentation for
-further details.
-
-
-.section Including support for IPv6
-.index IPv6||including support for
-Exim contains code for use on systems that have IPv6 support. Setting
-\\HAVE@_IPV6=YES\\ in \(Local/Makefile)\ 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.
-
-.em
-Two different types of DNS record for handling IPv6 addresses have been
-defined. AAAA records (analagous 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 `experimental'. It is not known
-if anyone is actually using A6 records. Exim has support for A6 records, but
-this is included only if you set \\SUPPORT@_A6=YES\\ in \(Local/Makefile)\. The
-support has not been tested for some time.
-.nem
-
-.section The building process
-.index build directory
-Once \(Local/Makefile)\ (and \(Local/eximon.conf)\, if required) have been
-created, run \*make*\ 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
-\(build-SunOS5-5.8-sparc)\ is created.
-.index symbolic link||to source files
-Symbolic links to relevant source files are installed in the build directory.
-
-\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the
-building process fails if it is set.
-
-If this is the first time \*make*\ has been run, it calls a script that builds
-a make file inside the build directory, using the configuration files from the
-\(Local)\ directory. The new make file is then passed to another instance of
-\*make*\. 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 \*make
-makefile*\ can be used to force a rebuild of the make file in the build
-directory, should this ever be necessary.
-
-If you have problems building Exim, check for any comments there may be in the
-\(README)\ file concerning your operating system, and also take a look at the
-.if ~~html
-[(A HREF="FAQ.html")]
-.fi
-FAQ,
-.if ~~html
-[(/A)]
-.fi
-where some common problems are covered.
-
-
-
-.section Overriding build-time options for Exim
-.index build-time options, overriding
-.rset SECToverride "~~chapter.~~section"
-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 \*make*\ 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:
-.display rm
-\(OS/Makefile-Default)\
-\(OS/Makefile-)\<<ostype>>
-\(Local/Makefile)\
-\(Local/Makefile-)\<<ostype>>
-\(Local/Makefile-)\<<archtype>>
-\(Local/Makefile-)\<<ostype>>-<<archtype>>
-\(OS/Makefile-Base)\
-.endd
-.index \(Local/Makefile)\
-where <<ostype>> is the operating system type and <<archtype>> is the
-.index building Exim||operating system type
-.index building Exim||architecture type
-architecture type. \(Local/Makefile)\ is required to exist, and the building
-process fails if it is absent. The other three \(Local)\ files are optional,
-and are often not needed.
-
-The values used for <<ostype>> and <<archtype>> are obtained from scripts
-called \(scripts/os-type)\ and \(scripts/arch-type)\ 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 \uname\ command. If this
-fails, the shell variables \\OSTYPE\\ and \\ARCHTYPE\\ are inspected. A number
-of $it{ad hoc} 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.
-
-
-\(OS/Makefile-Default)\ 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 (\(OS/Makefile-<<ostype>>)\) to see what the
-default values are.
-
-
-.index building Exim||overriding default settings
-If you need to change any of the values that are set in \(OS/Makefile-Default)\
-or in \(OS/Makefile-<<ostype>>)\, 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 \(Local)\ file. For example,
-.index Tru64-Unix build-time settings
-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 \*cc*\ rather than \*gcc*\. Also, the compiler must be
-called with the option \-std1-\, 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 \(Local/Makefile-OSF1)\
-containing the lines
-.display
-CC=cc
-CFLAGS=-std1
-.endd
-If you are compiling for just one operating system, it may be easier to put
-these lines directly into \(Local/Makefile)\.
-
-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 \(Local)\ directory.
-
-
-.index NIS lookup type||including support for
-.index NIS@+ lookup type||including support for
-.index LDAP||including support for
-.index lookup||inclusion in binary
-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 \(Local/Makefile)\ are:
-.display asis
-LOOKUP_LDAP=yes
-LOOKUP_NIS=yes
-LOOKUP_NISPLUS=yes
-.endd
-and similar settings apply to the other lookup types. They are all listed in
-\(src/EDITME)\. In most cases the relevant include files and interface
-libraries need to be installed before compiling Exim.
-.index cdb||including support for
-However, in the case of cdb, which is included in the binary only if
-.display asis
-LOOKUP_CDB=yes
-.endd
-is set, 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 run time configuration
-errors.
-
-.index Perl||including support for
-Exim can be linked with an embedded Perl interpreter, allowing Perl
-subroutines to be called during string expansion. To enable this facility,
-.display asis
-EXIM_PERL=perl.o
-.endd
-must be defined in \(Local/Makefile)\. Details of this facility are given in
-chapter ~~CHAPperl.
-
-.index X11 libraries, location of
-The location of the X11 libraries is something that varies a lot between
-operating systems, and of course there are 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 \(OS/Makefile-Default)\:
-.display asis
-X11=/usr/X11R6
-XINCLUDE=-I$(X11)/include
-XLFLAGS=-L$(X11)/lib
-.endd
-These are overridden in some of the operating-system configuration files. For
-example, in \(OS/Makefile-SunOS5)\ there is
-.display asis
-X11=/usr/openwin
-XINCLUDE=-I$(X11)/include
-XLFLAGS=-L$(X11)/lib -R$(X11)/lib
-.endd
-If you need to override the default setting for your operating system, place a
-definition of all three of these variables into your
-\(Local/Makefile-<<ostype>>)\ file.
-
-.index \\EXTRALIBS\\
-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.
-.index DBM||libraries, configuration for building
-There is also \\DBMLIB\\, which appears in the link commands for binaries that
-use DBM functions (see also section ~~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.
-
-.index configuration file||editing
-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, \(Local/Makefile)\
-or \(Local/eximon.conf)\) before rebuilding.
-
-.section OS-specific header files
-.index \(os.h)\
-.index building Exim||OS-specific C header files
-The \(OS)\ directory contains a number of files with names of the form
-\(os.h-<<ostype>>)\. 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 \(OS/os.configuring)\, which should be consulted if you
-are porting Exim to a new operating system.
-
-
-.section Overriding build-time options for the monitor
-.index building Eximon||overriding default options
-A similar process is used for overriding things when building the Exim monitor,
-where the files that are involved are
-.display rm
-\(OS/eximon.conf-Default)\
-\(OS/eximon.conf-)\<<ostype>>
-\(Local/eximon.conf)\
-\(Local/eximon.conf-)\<<ostype>>
-\(Local/eximon.conf-)\<<archtype>>
-\(Local/eximon.conf-)\<<ostype>>-<<archtype>>
-.endd
-.index \(Local/eximon.conf)\
-As with Exim itself, the final three files need not exist, and in this case the
-\(OS/eximon.conf-<<ostype>>)\ file is also optional. The default values in
-\(OS/eximon.conf-Default)\ 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 run time.
-
-
-
-.section Installing Exim binaries and scripts
-.index installing Exim
-.index \\BIN@_DIRECTORY\\
-The command \*make install*\ runs the \*exim@_install*\ script with no
-arguments. The script copies binaries and utility scripts into the directory
-whose name is specified by the \\BIN@_DIRECTORY\\ setting in
-\(Local/Makefile)\.
-
-Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting
-.index \\CONFIGURE@_FILE\\
-in \(Local/Makefile)\. If this names a single file, and the file does not
-exist, the default configuration file \(src/configure.default)\ is copied there
-by the installation script. If a run time configuration file already exists, it
-is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several
-alternative files, no default is installed.
-
-.index system aliases file
-.index \(/etc/aliases)\
-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 \(Local/Makefile)\ (\(/etc/aliases)\ by default).
-If the system aliases file does not exist, the installation script creates it,
-and outputs a comment to the user.
-
-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 \(/etc/aliases)\. However, some operating systems are now using
-\(/etc/mail/aliases)\. You should check if yours is one of these, and change
-Exim's configuration if necessary.
-
-The default configuration uses the local host's name as the only local domain,
-and is set up to do local deliveries into the shared directory \(/var/mail)\,
-running as the local user. System aliases and \(.forward)\ files in users' 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.
-
-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
-\*setuid*\ bit set,
-.index setuid||installing Exim with
-for normal configurations. Therefore, you must run \*make install*\ 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
-~~CHAPsecurity for details).
-
-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
-.display asis
-make DESTDIR=/some/directory/ install
-.endd
-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 \*is*\ modified.)
-For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set,
-but this usage is deprecated.
-
-.index installing Exim||what is not installed
-Running \*make install*\ does not copy the Exim 4 conversion script
-\*convert4r4*\, or the \*pcretest*\ test program. You will probably run the
-first of these only once (if you are upgrading from Exim 3), and the second
-isn't really part of Exim. None of the documentation files in the \(doc)\
-directory are copied, except for the info files when you have set
-\\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc below.
-
-For the utility programs, old versions are renamed by adding the suffix \(.O)\
-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 \(exim-~~version-1)\. The script then arranges for a symbolic link
-called \(exim)\ to point to the binary. If you are updating a previous version
-of Exim, the script takes care to ensure that the name \(exim)\ is never absent
-from the directory (as seen by other processes).
-
-.index installing Exim||testing the script
-If you want to see what the \*make install*\ will do before running it for
-real, you can pass the \-n-\ option to the installation script by this command:
-.display asis
-make INSTALL_ARG=-n install
-.endd
-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:
-.display
-(cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n)
-.endd
-
-.index installing Exim||install script options
-There are two other options that can be supplied to the installation script.
-.numberpars $.
-\-no@_chown-\ bypasses the call to change the owner of the installed binary
-to root, and the call to make it a setuid binary.
-.nextp
-\-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the
-installed binary.
-.endp
-\\INSTALL@_ARG\\ can be used to pass these options to the script. For example:
-.display asis
-make INSTALL_ARG=-no_symlink install
-.endd
-
-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:
-.display asis
-make INSTALL_ARG='-no_symlink exim' install
-.endd
-
-
-.section Installing info documentation
-.rset SECTinsinfdoc "~~chapter.~~section"
-.index installing Exim||\*info*\ documentation
-Not all systems use the GNU \*info*\ system for documentation, and for this
-reason, the Texinfo source of Exim's documentation is not included in the main
-distribution. Instead it is available separately from the ftp site (see section
-~~SECTavail).
-
-If you have defined \\INFO@_DIRECTORY\\ in \(Local/Makefile)\ and the Texinfo
-source of the documentation is found in the source tree, running \*make
-install*\ automatically builds the info files and installs them.
-
-
-.section Setting up the spool directory
-.index spool directory||creating
-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.
-
-
-
-.section Testing
-.index testing||installation
-Having installed Exim, you can check that the run time configuration file is
-syntactically valid by running the following command, which assumes that the
-Exim binary directory is within your \\PATH\\ environment variable:
-.display
-exim -bV
-.endd
-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,
-.display
-exim -bt <<local username>>
-.endd
-should verify that it recognizes a local mailbox, and
-.display
-exim -bt <<remote address>>
-.endd
-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:
-.display
-exim -v postmaster@@your.domain.example
-From: user@@your.domain.example
-To: postmaster@@your.domain.example
-Subject: Testing Exim
-
-This is a test message.
-^D
-.endd
-The \-v-\ 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's
-arrival, one for its delivery, and one containing `Completed'.
-
-.index delivery||problems with
-If you encounter problems, look at Exim's log files (\*mainlog*\ and
-\*paniclog*\) to see if there is any relevant information there. Another source
-of information is running Exim with debugging turned on, by specifying the
-\-d-\ option. If a message is stuck on Exim's spool, you can force a delivery
-with debugging turned on by a command of the form
-.display
-exim -d -M <<message-id>>
-.endd
-You must be root or an `admin user' in order to do this. The \-d-\ option
-produces rather a lot of output, but you can cut this down to specific areas.
-For example, if you use \-d-all+route-\ only the debugging information relevant
-to routing is included. (See the \-d-\ option in chapter ~~CHAPcommandline for
-more details.)
-
-.index `sticky' bit
-.index lock files
-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
-`sticky bit' 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 `sticky bit' 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
-\%local@_delivery%\ transport in the default configuration file). Another
-approach is to configure Exim not to use lock files, but just to rely on
-\*fcntl()*\ locking instead. However, you should do this only if all user
-agents also use \*fcntl()*\ locking. For further discussion of locking issues,
-see chapter ~~CHAPappendfile.
-
-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
-\-oX-\ option can be used to run an Exim daemon that listens on some other
-port, or \*inetd*\ can be used to do this. The \-bh-\ option and the
-\*exim@_checkaccess*\ utility can be used to check out policy controls on
-incoming SMTP mail.
-
-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 run time configuration, all other file and directory names
-that Exim uses can be altered, in order to keep it entirely clear of the
-production version.
-
-.section Replacing another MTA with Exim
-.index replacing another MTA
-Building and installing Exim for the first time does not of itself put it in
-general use. The name by which the system's MTA is called by mail user agents
-is either \(/usr/sbin/sendmail)\, or \(/usr/lib/sendmail)\ (depending on the
-operating system), and it is necessary to make this name point to the \*exim*\
-binary in order to get the user agents to pass messages to Exim. This is
-normally done by renaming any existing file and making \(/usr/sbin/sendmail)\
-or \(/usr/lib/sendmail)\
-.index symbolic link||to \*exim*\ binary
-a symbolic link to the \*exim*\ 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.
-
-.index FreeBSD, MTA indirection
-.index \(/etc/mail/mailer.conf)\
-Some operating systems have introduced alternative ways of switching MTAs. For
-example, if you are running FreeBSD, you need to edit the file
-\(/etc/mail/mailer.conf)\ 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:
-.display asis
-sendmail /usr/exim/bin/exim
-send-mail /usr/exim/bin/exim
-mailq /usr/exim/bin/exim -bp
-newaliases /usr/bin/true
-.endd
-
-Once you have set up the symbolic link, or edited \(/etc/mail/mailer.conf)\,
-your Exim installation is `live'. Check it by sending a message from your
-favourite user agent.
-
-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's filtering capabilities, you should make the document entitled
-.if ~~html
-[(A HREF="filter.html")]
-.fi
-\*Exim's interface to mail filtering*\
-.if ~~html
-[(/A)]
-.fi
-available to them.
-
-
-.section Upgrading Exim
-.index upgrading Exim
-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
-to send it a HUP signal, to make it re-exec 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.
-
-
-.section Stopping the Exim daemon on Solaris
-.index Solaris||stopping Exim on
-The standard command for stopping the mailer daemon on Solaris is
-.display
-/etc/init.d/sendmail stop
-.endd
-If \(/usr/lib/sendmail)\ has been turned into a symbolic link, this script
-fails to stop Exim because it uses the command \*ps -e*\ and greps the output
-for the text `sendmail'; this is not present because the actual program name
-(that is, `exim') is given by the \*ps*\ command with these options. A solution
-is to replace the line that finds the process id with something like
-.display asis
-pid=`cat /var/spool/exim/exim-daemon.pid`
-.endd
-to obtain the daemon's pid directly from the file that Exim saves it in.
-
-Note, however, that stopping the daemon does not `stop Exim'. Messages can
-still be received from local processes, and if automatic delivery is configured
-(the normal case), deliveries will still occur.
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter The Exim command line
-.set runningfoot "command line"
-.rset CHAPcommandline ~~chapter
-.index command line||options
-.index options||command line
-
-Exim'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.
-
-.section Setting options by program name
-.index \*mailq*\
-If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\
-were present before any other options.
-The \-bp-\ 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
-\(/usr/sbin/sendmail)\ or \(/usr/lib/sendmail)\.
-
-.index \*rsmtp*\
-If Exim is called under the name \*rsmtp*\ it behaves as if the option \-bS-\
-were present before any other options, for compatibility with Smail. The \-bS-\
-option is used for reading in a number of messages in batched SMTP format.
-
-.index \*rmail*\
-If Exim is called under the name \*rmail*\ it behaves as if the \-i-\ and
-\-oee-\ options were present before any other options, for compatibility with
-Smail. The name \*rmail*\ is used as an interface by some UUCP systems.
-
-.index \*runq*\
-.index queue runner
-If Exim is called under the name \*runq*\ it behaves as if the option \-q-\ were
-present before any other options, for compatibility with Smail. The \-q-\
-option causes a single queue runner process to be started.
-
-.index \*newaliases*\
-.index alias file||building
-.index Sendmail compatibility||calling Exim as \*newaliases*\
-If Exim is called under the name \*newaliases*\ it behaves as if the option
-\-bi-\ were present before any other options, for compatibility with Sendmail.
-This option is used for rebuilding Sendmail'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 \-bi-\ option.
-
-.section Trusted and admin users
-.rset SECTtrustedadmin "~~chapter.~~section"
-Some Exim options are available only to \*trusted users*\ and others are
-available only to \*admin users*\. In the description below, the phrases `Exim
-user' and `Exim group' mean the user and group defined by \\EXIM@_USER\\ and
-\\EXIM@_GROUP\\ in \(Local/Makefile)\ or set by the \exim@_user\ and
-\exim@_group\ options. These do not necessarily have to use the name `exim'.
-
-.numberpars $.
-.index trusted user||definition of
-.index user||trusted, definition of
-The trusted users are root, the Exim user, any user listed in the
-\trusted@_users\ configuration option, and any user whose current group or any
-supplementary group is one of those listed in the \trusted@_groups\
-configuration option. Note that the Exim group is not automatically trusted.
-
-.index `From' line
-.index envelope sender
-Trusted users are always permitted to use the \-f-\ option or a leading `From '
-line to specify the envelope sender of a message that is passed to Exim through
-the local interface (see the \-bm-\ and \-f-\ options below). See the
-\untrusted@_set@_sender\ option for a way of permitting non-trusted users to
-set envelope senders.
-.index ::From:: header line
-.index ::Sender:: header line
-For a trusted user, there is never any check on the contents of the ::From::
-header line, and a ::Sender:: line is never added. Furthermore, any existing
-::Sender:: line in incoming local (non-TCP/IP) messages is not removed.
-
-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's queue locally that
-have the characteristics of messages received from a remote host. Untrusted
-users may in some circumstances use \-f-\, but can never set the other values
-that are available to trusted users.
-.nextp
-.index user||admin, definition of
-.index admin user||definition of
-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 \admin@_groups\ configuration option.
-The current group does not have to be one of these groups.
-
-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.
-
-By default, the use of the \-M-\, \-q-\, \-R-\, and \-S-\ 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 \prod@_requires@_admin\
-option false (that is, specifying \no@_prod@_requires@_admin\).
-
-Similarly, the use of the \-bp-\ option to list all the messages in the queue
-is restricted to admin users unless \queue@_list@_requires@_admin\ is set
-false.
-.endp
-
-\**Warning**\: If you configure your system so that admin users are able to
-edit Exim'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
-~~CHAPconf.
-
-
-
-.section Command line options
-The command options are described in alphabetical order below.
-
-.startoptions
-
-.option @-
-.index options||command line, terminating
-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.
-
-.option -help
-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.
-
-.option B <<type>>
-.index 8-bit characters
-.index Sendmail compatibility||8-bit characters
-This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit
-clean; it ignores this option.
-
-.option bd
-.index daemon
-.index SMTP listener
-.index queue runner
-This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually
-the \-bd-\ option is combined with the \-q-\<<time>> option, to specify that
-the daemon should also initiate periodic queue runs.
-
-The \-bd-\ option can be used only by an admin user. If either of the \-d-\
-(debugging) or \-v-\ (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.
-
-By default, Exim listens for incoming connections to the standard SMTP port on
-all the host's running interfaces. However, it is possible to listen on other
-ports, on multiple ports, and only on specific interfaces. Chapter
-~~CHAPinterfaces contains a description of the options that control this.
-
-.index daemon||process id (pid)
-.index pid (process id)||of daemon
-When a listening daemon is started without the use of \-oX-\ (that is, without
-overriding the normal configuration), it writes its process id to a file called
-\(exim-daemon.pid)\ in Exim's spool directory. This location can be overridden
-by setting \\PID@_FILE@_PATH\\ in \(Local/Makefile)\. The file is written while
-Exim is still running as root.
-
-When \-oX-\ is used on the command line to start a listening daemon, the
-process id is not written to the normal pid file path. However, \-oP-\ can be
-used to specify a path on the command line if a pid file is required.
-
-.index \\SIGHUP\\
-The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This
-should be done whenever Exim's configuration file, or any file that is
-incorporated into it by means of the \.include\ 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.
-
-.option bdf
-This option has the same effect as \-bd-\ except that it never disconnects from
-the controlling terminal, even when no debugging is specified.
-
-.option be
-.index testing||string expansion
-.index expansion||testing
-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.
-.em
-If Exim was built with \\USE@_READLINE\\=yes in \(Local/Makefile)\, it tries
-to load the \libreadline\ library dynamically whenever the \-be-\ option is
-used without command line arguments. If successful, it uses the \*readline()*\
-function, which provides extensive line-editing facilities, for reading the
-test data. A line history is supported.
-.nem
-
-Long expansion expressions can be split over several lines by using backslash
-continuations. As in Exim's run time configuration, whitespace 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, \$qualify@_domain$\) are available, but no
-message-specific values (such as \$domain$\) are set, because no message is
-being processed.
-
-.option bF #<<filename>>
-.index system filter||testing
-.index testing||system filter
-This option is the same as \-bf-\ 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.
-
-.option bf #<<filename>>
-.index filter||testing
-.index testing||filter file
-.index forward file||testing
-.index testing||forward file
-.index Sieve filter||testing
-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.
-.em
-If you want to test a system filter file, use \-bF-\ instead of \-bf-\. You can
-use both \-bF-\ and \-bf-\ on the same command, in order to
-test a system filter and a user filter in the same run. For example:
-.display asis
-exim -bF /system/filter -bf /user/filter </test/message
-.endd
-This is helpful when the system filter adds header lines or sets filter
-variables that are used by the user filter.
-.nem
-
-If the test filter file does not begin with one of the special lines
-.display asis
-# Exim filter
-# Sieve filter
-.endd
-it is taken to be a normal \(.forward)\ file, and is tested for validity under
-that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a
-description of the possible contents of non-filter redirection lists.
-
-The result of an Exim command that uses \-bf-\, 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 \*Exim's interfaces to mail filtering*\.
-
-.index `From' line
-.index envelope sender
-.index \-f-\ option||for filter testing
-When testing a filter file, the envelope sender can be set by the \-f-\ option,
-or by a `From ' 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).
-
-.em
-.option bfd #<<domain>>
-This sets the domain of the recipient address when a filter file is being
-tested by means of the \-bf-\ option. The default is the value of
-\$qualify@_domain$\.
-
-.option bfl #<<local part>>
-This sets the local part of the recipient address when a filter file is being
-tested by means of the \-bf-\ 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.
-
-.option bfp #<<prefix>>
-This sets the prefix of the local part of the recipient address when a filter
-file is being tested by means of the \-bf-\ option. The default is an empty
-prefix.
-
-.option bfp #<<suffix>>
-This sets the suffix of the local part of the recipient address when a filter
-file is being tested by means of the \-bf-\ option. The default is an empty
-suffix.
-.em
-
-
-.option bh #<<IP address>>
-.index testing||incoming SMTP
-.index SMTP||testing incoming
-.index testing||relay control
-.index relaying||testing configuration
-.index policy control||testing
-.index debugging||\-bh-\ option
-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:
-.display asis
-exim -bh 10.9.8.7.1234
-exim -bh fe80::a00:20ff:fe86:a061.5678
-.endd
-.em
-When an IPv6 address is given, it is converted into canonical form. In the case
-of the second example above, the value of \$sender@_host@_address$\ after
-conversion to the canonical form is \"fe80:0000:0000:0a00:20ff:fe86:a061.5678"\.
-.nem
-
-Comments as to what is going on are written to the standard error file. These
-include lines beginning with `LOG' 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 \-bh-\.
-
-.index RFC 1413
-\**Warning 1**\: You cannot test features of the configuration that rely on
-ident (RFC 1413) callouts. These cannot be done when testing using
-\-bh-\ because there is no incoming SMTP connection.
-
-\**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are
-also skipped when testing using \-bh-\. If you want these callouts to occur,
-use \-bhc-\ instead.
-
-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 \-oMi-\ option
-can be used to specify a specific IP interface and port if this is important.
-
-The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\ whose
-output just states whether a given recipient address from a given host is
-acceptable or not. See section ~~SECTcheckaccess.
-
-.option bhc #<<IP address>>
-This option operates in the same way as \-bh-\, except that address
-verification callouts are performed if required. This includes consulting and
-updating the callout cache database.
-
-.option bi
-.index alias file||building
-.index building alias file
-.index Sendmail compatibility||\-bi-\ option
-Sendmail interprets the \-bi-\ 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 \(/usr/lib/sendmail)\ with the \-bi-\ option
-tend to appear in various scripts such as NIS make files, so the option must be
-recognized.
-
-If \-bi-\ is encountered, the command specified by the \bi@_command\
-configuration option is run, under the uid and gid of the caller of Exim. If
-the \-oA-\ option is used, its value is passed to the command as an argument.
-The command set by \bi@_command\ may not contain arguments. The command can use
-the \*exim@_dbmbuild*\ utility, or some other means, to rebuild alias files if
-this is required. If the \bi@_command\ option is not set, calling Exim with
-\-bi-\ is a no-op.
-
-.option bm
-.index local message reception
-This option runs an Exim receiving process that accepts an incoming,
-locally-generated message on the current input. The recipients are given as the
-command arguments (except when \-t-\ is also present -- 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.
-
-If any addresses in the message are unqualified (have no domain), they are
-qualified by the values of the \qualify@_domain\ or \qualify@_recipient\
-options, as appropriate. The \-bnq-\ option (see below) provides a way of
-suppressing this for special cases.
-
-Policy checks on the contents of local messages can be enforced by means of the
-non-SMTP ACL. See chapter ~~CHAPACL for details.
-.index return code||for \-bm-\
-The return code is zero if the message is successfully accepted. Otherwise, the
-action is controlled by the \-oe$it{x}-\ option setting -- see below.
-
-.index message||format
-.index format||message
-.index `From' line
-.index UUCP||`From' line
-.index Sendmail compatibility||`From' line
-The format 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
-.display
-From sender Fri Jan 5 12:55 GMT 1997
-From sender Fri, 5 Jan 97 12:55:01
-.endd
-(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 \uucp@_from@_pattern\
-option, which can be changed if necessary.
-.index \-f-\ option||overriding `From' line
-The specified sender is treated as if it were given as the argument to the
-\-f-\ option, but if a \-f-\ 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.
-
-.option bnq
-.index address||qualification, suppressing
-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
-\qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which
-defaults to the value of \qualify@_domain\).
-
-Sometimes, qualification is not wanted. For example, if \-bS-\ (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.)
-
-The \-bnq-\ 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.
-
-
-.option bP
-.index configuration options, extracting
-.index options||configuration, extracting
-If this option is given with no arguments, it causes the values of all Exim'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:
-.display
-exim -bP qualify@_domain hold@_domains
-.endd
-However, any option setting that is preceded by the word `hide' in the
-configuration file is not shown in full, except to an admin user. For other
-users, the output is as in this example:
-.display asis
-mysql_servers = <value not displayable>
-.endd
-If \configure@_file\ is given as an argument, the name of the run time
-configuration file is output.
-If a list of configuration files was supplied, the value that is output here
-is the name of the file that was actually used.
-
-.index daemon||process id (pid)
-.index pid (process id)||of daemon
-If \log__file__path\ or \pid@_file@_path\ 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 \log\, and the pid file is written
-directly into the spool directory.
-
-If \-bP-\ is followed by a name preceded by \"+"\, for example,
-.display asis
-exim -bP +local_domains
-.endd
-it searches for a matching named list of any type (domain, host, address, or
-local part) and outputs what it finds.
-
-.index options||router, extracting
-.index options||transport, extracting
-If one of the words \router\, \transport\, or \authenticator\ is given,
-followed by the name of an appropriate driver instance, the option settings for
-that driver are output. For example:
-.display
-exim -bP transport local@_delivery
-.endd
-The generic driver options are output first, followed by the driver's private
-options. A list of the names of drivers of a particular type can be obtained by
-using one of the words \router@_list\, \transport@_list\, or
-\authenticator@_list\, and a complete list of all drivers with their option
-settings can be obtained by using \routers\, \transports\, or \authenticators\.
-
-
-.option bp
-.index queue||listing messages on
-.index listing||messages on the queue
-This option requests a listing of the contents of the mail queue on the
-standard output. If the \-bp-\ 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 \queue__list__requires__admin\ option can be set false
-to allow any user to see the queue.
-
-Each message on the queue is displayed as in the following example:
-.display
-25m 2.9K 0t5C6f-0000c8-00 <alice@@wonderland.fict.example>
- red.king@@looking-glass.fict.example
- <<other addresses>>
-.endd
-.index message||size in queue listing
-.index size||of message
-The first line contains the length of time the message has been on 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
-`<>'. If the message was submitted locally by an untrusted user who overrode
-the default sender address, the user's login name is shown in parentheses
-before the sender address.
-.index frozen messages||in queue listing
-If the message is frozen (attempts to deliver it are suspended) then the text
-`$*$$*$$*$ frozen $*$$*$$*$' is displayed at the end of this line.
-
-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.
-
-
-.option bpa
-This option operates like \-bp-\, 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 `+D' instead
-of just `D'.
-
-
-.option bpc
-.index queue||count of messages on
-This option counts the number of messages on the queue, and writes the total
-to the standard output. It is restricted to admin users, unless
-\queue__list__requires__admin\ is set false.
-
-
-.option bpr
-This option operates like \-bp-\, but the output is not sorted into
-chronological order of message arrival. This can speed it up when there are
-lots of messages on the queue, and is particularly useful if the output is
-going to be post-processed in a way that doesn't need the sorting.
-
-.option bpra
-This option is a combination of \-bpr-\ and \-bpa-\.
-
-.option bpru
-This option is a combination of \-bpr-\ and \-bpu-\.
-
-
-.option bpu
-This option operates like \-bp-\ 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 \one@_time\ option set.
-
-
-.option brt
-.index testing||retry configuration
-.index retry||configuration testing
-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:
-.display asis
-exim -brt bach.comp.mus.example
-Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m;
-.endd
-See chapter ~~CHAPretry for a description of Exim's retry rules. The first
-argument, which is required, can be a complete address in the form
-\*local@_part@@domain*\, or it can be just a domain name. The second argument is
-an optional second domain name; if no retry rule is found for the first
-argument, the second is tried. This ties in with Exim's behaviour when looking
-for retry rules for remote hosts -- if no rule is found that matches the host,
-one that matches the mail domain is sought. The final argument is the name of a
-specific delivery error, as used in setting up retry rules, for example
-`quota@_3d'.
-
-.option brw
-.index testing||rewriting
-.index rewriting||testing
-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
-~~CHAPrewrite for further details.
-
-.option bS
-.index SMTP||batched incoming
-.index batched SMTP input
-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's envelope from SMTP commands on the standard
-input, but generates no responses. If the caller is trusted, or
-\untrusted@_set@_sender\ is set, the senders in the SMTP \\MAIL\\ commands are
-believed; otherwise the sender is always the caller of Exim.
-
-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.
-
-As for other local message submissions, the contents of incoming batch SMTP
-messages can be checked using the non-SMTP ACL (see chapter ~~CHAPACL).
-Unqualified addresses are automatically qualified using \qualify@_domain\ and
-\qualify@_recipient\, as appropriate, unless the \-bnq-\ option is used.
-
-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.
-
-If any error is encountered, reports are written to the standard output and
-error streams, and Exim gives up immediately.
-.index return code||for \-bS-\
-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.
-
-More details of input using batched SMTP are given in section
-~~SECTincomingbatchedSMTP.
-
-.option bs
-.index SMTP||local input
-.index local SMTP input
-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 ~~CHAPACL) are applied.
-
-Some user agents use this interface as a way of passing locally-generated
-messages to the MTA.
-.index sender||source of
-In this usage, if the caller of Exim is trusted, or \untrusted@_set@_sender\ 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
-\qualify@_domain\ and \qualify@_recipient\, as appropriate, unless the \-bnq-\
-option is used.
-
-.index inetd
-The \-bs-\ option is also used to run Exim from \*inetd*\, 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
-\*inetd*\, 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.
-
-.option bt
-.index testing||addresses
-.index address||testing
-This option runs Exim in address testing mode, in which each argument is taken
-as an 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.
-
-If no arguments are given, Exim runs in an interactive manner, prompting with a
-right angle bracket for addresses to be tested.
-.em
-Unlike the \-be-\ test option, you cannot arrange for Exim to use the
-\*readline()*\ function, because it is running as \*root*\ and there are
-security issues.
-.nem
-
-Each address is handled as if it were the recipient address of a message
-(compare the \-bv-\ option). It is passed to the routers and the result is
-written to the standard output. However, any router that has
-\no@_address@_test\ set is bypassed. This can make \-bt-\ easier to use for
-genuine routing tests if your first router passes everything to a scanner
-program.
-
-.index return code||for \-bt-\
-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.
-
-\**Warning**\: \-bt-\ can only do relatively simple testing. If any of the
-routers in the configuration makes any tests on the sender address of a
-message,
-.index \-f-\ option||for address testing
-you can use the \-f-\ option to set an appropriate sender when running
-\-bt-\ 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 \-bt-\. The \-N-\ option provides a possible way of
-doing such tests.
-
-.option bV
-.index version number of Exim, verifying
-This option causes Exim to write the current version number, compilation
-number, and compilation date of the \*exim*\ binary to the standard output.
-It also lists the DBM library this is being used, the optional modules (such as
-specific lookup types), the drivers that are included in the binary, and the
-name of the run time configuration file that is in use.
-
-.em
-As part of its operation, \-bV-\ 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's arguments is not. You cannot rely on \-bV-\
-alone to discover (for example) all the typos in the configuration; some
-realistic testing is needed. The \-bh-\ and \-N-\ options provide more dynamic
-testing facilities.
-.nem
-
-
-.option bv
-.index verifying||address, using \-bv-\
-.index address||verification
-This option runs Exim in address verification mode, in which each argument is
-taken as an address to be verified. During normal operation, verification
-happens mostly as a consequence processing a \verify\ condition in an ACL (see
-chapter ~~CHAPACL). If you want to test an entire ACL, see the \-bh-\ option.
-
-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.
-
-If no arguments are given, Exim runs in an interactive manner, prompting with a
-right angle bracket for addresses to be verified.
-.em
-Unlike the \-be-\ test option, you cannot arrange for Exim to use the
-\*readline()*\ function, because it is running as \*exim*\ and there are
-security issues.
-.nem
-
-Verification differs from address testing (the \-bt-\ option) in that routers
-that have \no@_verify\ set are skipped, and if the address is accepted by a
-router that has \fail@_verify\ set, verification fails. The address is verified
-as a recipient if \-bv-\ is used; to test verification for a sender address,
-\-bvs-\ should be used.
-
-If the \-v-\ 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. Otherwise, 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. Without \-v-\, generating more than one address by
-redirection causes verification to end sucessfully.
-
-.index return code||for \-bv-\
-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.
-
-If any of the routers in the configuration makes any tests on the sender
-address of a message, you should use the \-f-\ option to set an appropriate
-sender when running \-bv-\ tests. Without it, the sender is assumed to be the
-calling user at the default qualifying domain.
-
-.option bvs
-This option acts like \-bv-\, but verifies the address as a sender rather
-than a recipient address. This affects any rewriting and qualification that
-might happen.
-
-.option C #<<filelist>>
-.index configuration file||alternate
-.index \\CONFIGURE@_FILE\\
-.index alternate configuration file
-This option causes Exim to find the run time 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 file
-name, 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.
-
-When this option is used by a caller other than root or the Exim user, 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 \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in
-\(Local/Makefile)\, root privilege is retained for \-C-\ only if the caller of
-Exim is root.
-.em
-That is, the Exim user is no longer privileged in this regard. This build-time
-option is not set by default in the Exim source distribution tarbundle.
-However, if you are using a `packaged' version of Exim (source or binary), the
-packagers might have enabled it.
-.nem
-
-Setting \\ALT@_CONFIG@_ROOT@_ONLY\\ locks out the possibility of testing a
-configuration using \-C-\ 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 \-C-\ causes privilege to be lost. However, root can test reception and
-delivery using two separate commands (one to put a message on the queue, using
-\-odq-\, and another to do the delivery, using \-M-\).
-
-If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
-prefix string with which any file named in a \-C-\ command line option
-must start. In addition, the file name must not contain the sequence \"/../"\.
-However, if the value of the \-C-\ option is identical to the value of
-\\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as
-usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is
-unset, any file name can be used with \-C-\.
-
-\\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.
-
-The \-C-\ 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.
-
-.option D <<macro>>=<<value>>
-.index macro||setting on command line
-This option can be used to override macro definitions in the configuration file
-(see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an
-unprivileged caller, it causes Exim to give up its root privilege.
-If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
-completely disabled, and its use causes an immediate error exit.
-
-The entire option (including equals sign if present) must all be within one
-command line item. \-D-\ 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:
-.display asis
-exim -DABC ...
-exim -DABC= ...
-.endd
-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:
-.display asis
-exim '-D ABC = something' ...
-.endd
-\-D-\ may be repeated up to 10 times on a command line.
-
-.option d <<debug options>>
-.index debugging||list of selectors
-.index debugging||\-d-\ option
-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'
-filter files should be protected. When \-d-\ is used, \-v-\ is assumed. If
-\-d-\ 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
-following \-d-\ with a string made up of names preceded by plus or minus
-characters. These add or remove sets of debugging data, respectively. For
-example, \-d+filter-\ adds filter debugging, whereas \-d-all+filter-\ selects
-only filter debugging. The available debugging categories are:
-.display flow
-.tabs 21
-.
-. The odd formatting of the lines below is deliberate. It does not affect the
-. SGCAL output, but by putting in the space it keeps things aligned in the man
-. page that is automatically generated from this text.
-.
-acl $t $rm{ACL interpretation}
-auth $t $rm{authenticators}
-deliver $t $rm{general delivery logic}
-dns $t $rm{DNS lookups (see also resolver)}
-dnsbl $t $rm{DNS black list (aka RBL) code}
-exec $t $rm{arguments for \execv@(@)\ calls}
-expand $t $rm{detailed debugging for string expansions}
-filter $t $rm{filter handling}
-hints@_lookup $t $rm{hints data lookups}
-host@_lookup $t $rm{all types of name-to-IP address handling}
-ident $t $rm{ident lookup}
-interface $t $rm{lists of local interfaces}
-lists $t $rm{matching things in lists}
-load $t $rm{system load checks}
-local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)}
-lookup $t $rm{general lookup code and all lookups}
-memory $t $rm{memory handling}
-pid $t $rm{add pid to debug output lines}
-process@_info $t $rm{setting info for the process log}
-queue@_run $t $rm{queue runs}
-receive $t $rm{general message reception logic}
-resolver $t $rm{turn on the DNS resolver's debugging output}
-retry $t $rm{retry handling}
-rewrite $t $rm{address rewriting}
-route $t $rm{address routing}
-timestamp $t $rm{add timestamp to debug output lines}
-tls $t $rm{TLS logic}
-transport $t $rm{transports}
-uid $t $rm{changes of uid/gid and looking up uid/gid}
-verify $t $rm{address verification logic}
-
-all $t $rm{all of the above, and also \-v-\}
-.endd
-.index resolver, debugging output
-.index DNS||resolver, debugging output
-The \"resolver"\ 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.
-
-The default (\-d-\ with no argument) omits \"expand"\, \"filter"\,
-\"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\.
-However, the \"pid"\ 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.
-
-The \"timestamp"\ 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.
-
-If the \debug@_print\ option is set in any driver, it produces output whenever
-any debugging is selected, or if \-v-\ is used.
-
-.em
-.option dd <<debug options>>
-This option behaves exactly like \-d-\ 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.
-.nem
-
-.option dropcr
-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 ~~SECTlineendings.
-
-
-.option E
-.index bounce message||generating
-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 \-E-\. If it does, the log entry for the receipt of the
-new message contains the id, following `R=', as a cross-reference.
-
-.option e$it{x}
-There are a number of Sendmail options starting with \-oe-\ which seem to be
-called by various programs without the leading \o\ in the option. For example,
-the \vacation\ program uses \-eq-\. Exim treats all options of the form
-\-e$it{x}-\ as synonymous with the corresponding \-oe$it{x}-\ options.
-
-.option F #<<string>>
-.index sender||name
-.index name||of sender
-This option sets the sender's full name for use when a locally-generated
-message is being accepted. In the absence of this option, the user's \*gecos*\
-entry from the password data is used. As users are generally permitted to alter
-their \*gecos*\ entries, no security considerations are involved. White space
-between \-F-\ and the <<string>> is optional.
-
-.option f #<<address>>
-.index sender||address
-.index address||sender
-.index trusted user
-.index envelope sender
-.index user||trusted
-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 \untrusted@_set@_sender\ can be set to allow untrusted
-users to use it.
-.em
-Processes running as root or the Exim user are always trusted. Other
-trusted users are defined by the \trusted@_users\ or \trusted@_groups\ options.
-
-In the absence of \-f-\, or if the caller is not trusted, the sender of a local
-message is set to the caller's login name at the default qualify domain.
-
-There is one exception to the restriction on the use of \-f-\: an empty sender
-can be specified by any user, trusted or not,
-.nem
-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:
-.display asis
-exim -f '<>' user@domain
-exim -f "" user@domain
-.endd
-In addition, the use of \-f-\ is not restricted when testing a filter file with
-\-bf-\ or when testing or verifying addresses using the \-bt-\ or \-bv-\
-options.
-
-Allowing untrusted users to change the sender address does not of itself make
-it possible to send anonymous mail. Exim still checks that the ::From:: header
-refers to the local user, and if it does not, it adds a ::Sender:: header,
-though this can be overridden by setting \no@_local@_from@_check\.
-
-.index `From' line
-White space between \-f-\ and the <<address>> 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 `From ' line in the message -- see the description of \-bm-\ above
--- but if \-f-\ is also present, it overrides `From'.
-
-.option G
-.index Sendmail compatibility||\-G-\ option ignored
-This is a Sendmail option which is ignored by Exim.
-
-.option h #<<number>>
-.index Sendmail compatibility||\-h-\ option ignored
-This option is accepted for compatibility with Sendmail, but has no effect. (In
-Sendmail it overrides the `hop count' obtained by counting ::Received::
-headers.)
-
-.option i
-.index Solaris||\*mail*\ command
-.index dot||in incoming, non-SMTP message
-This option, which has the same effect as \-oi-\, specifies that a dot on a
-line by itself should not terminate an incoming, non-SMTP message. I can find
-no documentation for this option in Solaris 2.4 Sendmail, but the \*mailx*\
-command in Solaris 2.4 uses it. See also \-ti-\.
-
-.option M #<<message id>>#<<message id>> ...
-.index forcing delivery
-.index delivery||forcing attempt
-.index frozen messages||forcing delivery
-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 \queue@_domains\, \queue@_smtp@_domains\, and
-\hold@_domains\ are ignored.
-.index hints database||overriding retry hints
-Retry hints for any of the addresses are
-overridden -- 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 \prod@_requires@_admin\ which can be set false to
-relax this restriction (and also the same requirement for the \-q-\, \-R-\, and
-\-S-\ options).
-
-
-.option Mar #<<message id>>#<<address>>#<<address>> ...
-.index message||adding recipients
-.index recipient||adding
-This option requests Exim to add the addresses to the list of recipients of the
-message (`ar' for `add recipients'). 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.
-
-.index SMTP||passed connection
-.index SMTP||multiple deliveries
-.index multiple SMTP deliveries
-.option MC #<<transport>>#<<hostname>>#<<sequence number>>#<<message id>>
-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 ~~CHAPSMTP. This must be the final option, and the caller must
-be root or the Exim user in order to use it.
-
-.option MCA
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ option. It signifies that the connection
-to the remote host has been authenticated.
-
-.option MCP
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ option. It signifies that the server to
-which Exim is connected supports pipelining.
-
-.option MCQ #<<process id>> <<pipe fd>>
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ 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.
-
-.option MCS
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ option, and passes on the fact that the
-SMTP \\SIZE\\ option should be used on messages delivered down the existing
-connection.
-
-.option MCT
-This option is not intended for use by external callers. It is used internally
-by Exim in conjunction with the \-MC-\ option, and passes on the fact that the
-host to which Exim is connected supports TLS encryption.
-
-.option Mc #<<message id>>#<<message id>> ...
-.index hints database||not overridden by \-Mc-\
-.index delivery||manually started, not forced
-This option requests Exim to run a delivery attempt on each message in turn,
-but unlike the \-M-\ 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 ~~CHAPsecurity).
-However, \-Mc-\ can be useful when testing, in order to run a delivery that
-respects retry times and other options such as \hold@_domains\ that are
-overridden when \-M-\ 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
-\-q-\ with a message id argument. A distinction between queue run deliveries
-and other deliveries is made in one or two places.
-
-.option Mes #<<message id>>#<<address>>
-.index message||changing sender
-.index sender||changing
-This option requests Exim to change the sender address in the message to the
-given address, which must be a fully qualified address or `<>' (`es' for `edit
-sender'). 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.
-
-.option Mf #<<message id>>#<<message id>> ...
-.index freezing messages
-.index message||manually freezing
-This option requests Exim to mark each listed message as `frozen'. This
-prevents any delivery attempts taking place until the message is `thawed',
-either manually or as a result of the \auto@_thaw\ 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.
-
-.option Mg #<<message id>>#<<message id>> ...
-.index giving up on messages
-.index message||abandoning delivery attempts
-.index delivery||abandoning further attempts
-This option requests Exim to give up trying to deliver the listed messages,
-including any that are frozen. However, if any of the messages are active,
-their status is not altered.
-For non-bounce messages, a delivery error message is sent to the sender,
-containing the text `cancelled by administrator'. Bounce messages are just
-discarded.
-This option can be used only by an admin user.
-
-.option Mmad #<<message id>>#<<message id>> ...
-.index delivery||cancelling all
-This option requests Exim to mark all the recipient addresses in the messages
-as already delivered (`mad' for `mark all delivered'). 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.
-
-.option Mmd #<<message id>>#<<address>>#<<address>> ...
-.index delivery||cancelling by address
-.index recipient||removing
-.index removing recipients
-This option requests Exim to mark the given addresses as already delivered
-(`md' for `mark delivered'). 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.
-
-.option Mrm #<<message id>>#<<message id>> ...
-.index removing messages
-.index abandoning mail
-.index message||manually discarding
-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 on the queue.
-
-.option Mt #<<message id>>#<<message id>> ...
-.index thawing messages
-.index unfreezing messages
-.index frozen messages||thawing
-.index message||thawing frozen
-This option requests Exim to `thaw' any of the listed messages that are
-`frozen', 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.
-
-.option Mvb #<<message id>>
-.index listing||message body
-.index message||listing body of
-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.
-
-.option Mvh #<<message id>>
-.index listing||message headers
-.index header lines||listing
-.index message||listing header lines
-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.
-
-.option Mvl #<<message id>>
-.index listing||message log
-.index message||listing message log
-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.
-
-.option m
-This is apparently a synonym for \-om-\ that is accepted by Sendmail, so Exim
-treats it that way too.
-
-.option N
-.index debugging||\-N-\ option
-.index debugging||suppressing delivery
-This is a debugging option that inhibits delivery of a message at the transport
-level. It implies \-v-\. Exim goes through many of the motions of delivery --
-it just doesn'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 `$*$>' rather
-than `=>'.
-
-Because \-N-\ discards any message to which it applies, only root or the Exim
-user are allowed to use it with \-bd-\, \-q-\, \-R-\ or \-M-\. 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 \-N-\ is set, an address
-may be deferred because of a configuration problem on a transport, or a routing
-problem. Once \-N-\ 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.
-
-.option n
-.index Sendmail compatibility||\-n-\ option ignored
-This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by
-Exim.
-
-.option O #<<data>>
-This option is interpreted by Sendmail to mean `set option`. It is ignored by
-Exim.
-
-.option oA #<<file name>>
-.index Sendmail compatibility||\-oA-\ option
-This option is used by Sendmail in conjunction with \-bi-\ to specify an
-alternative alias file name. Exim handles \-bi-\ differently; see the
-description above.
-
-.index SMTP||passed connection
-.option oB #<<n>>
-.index SMTP||multiple deliveries
-.index multiple SMTP deliveries
-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 \%smtp%\
-transport. If <<n>> is omitted, the limit is set to 1.
-
-.option odb
-.index background delivery
-.index delivery||in the background
-This option applies to all modes in which Exim accepts incoming messages,
-including the listening daemon. It requests `background' 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.
-.em
-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.
-.nem
-This is the default action if none of the \-od-\ options are present.
-
-If one of the queueing options in the configuration file
-(\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\
-overrides it if \queue@_only@_override\ is set true, which is the default
-setting. If \queue@_only@_override\ is set false, \-odb-\ has no effect.
-
-.option odf
-.index foreground delivery
-.index delivery||in the foreground
-This option requests `foreground' (synchronous) delivery when Exim has accepted
-a locally-generated message. (For the daemon it is exactly the same as
-\-odb-\.) A delivery process is automatically started to deliver the
-message, and Exim waits for it to complete before proceeding.
-.em
-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.
-.nem
-However, like \-odb-\, this option has no effect if \queue@_only@_override\ is
-false and one of the queueing options in the configuration file is in effect.
-
-.em
-If there is a temporary delivery error during foreground delivery, the message
-is left on the queue for later delivery, and the original reception process
-exists. See chapter ~~CHAPnonqueueing for a way of setting up a restricted
-configuration that never queues messages.
-.nem
-
-.option odi
-This option is synonymous with \-odf-\. It is provided for compatibility with
-Sendmail.
-
-.option odq
-.index non-immediate delivery
-.index delivery||suppressing immediate
-.index queueing incoming messages
-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 on the queue, and remain there until a subsequent queue runner
-process encounters them.
-There are several configuration options (such as \queue@_only\) that can be
-used to queue incoming messages under certain conditions. This option overrides
-all of them and also \-odqs-\. It always forces queueing.
-
-.option odqs
-.index SMTP||delaying delivery
-This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\.
-However, like \-odb-\ and \-odi-\, this option has no effect if
-\queue@_only@_override\ is false and one of the queueing options in the
-configuration file is in effect.
-
-When \-odqs-\ does operate, a delivery process is started for each incoming
-message, in the background by default, but in the foreground if \-odi-\ 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 on 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 \queue@_smtp@_domains\ configuration
-option has the same effect for specific domains. See also the \-qq-\ option.
-
-.option oee
-.index error||reporting
-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.
-.index return code||for \-oee-\
-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 any other error. This is
-the default \-oe$it{x}-\ option if Exim is called as \*rmail*\.
-
-.option oem
-.index error||reporting
-.index return code||for \-oem-\
-This is the same as \-oee-\, except that Exim always exits with a non-zero
-return code, whether or not the error message was successfully sent.
-This is the default \-oe$it{x}-\ option, unless Exim is called as \*rmail*\.
-
-.option oep
-.index error||reporting
-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).
-.index return code||for \-oep-\
-The return code is 1 for all errors.
-
-.option oeq
-.index error||reporting
-This option is supported for compatibility with Sendmail, but has the same
-effect as \-oep-\.
-
-.option oew
-.index error||reporting
-This option is supported for compatibility with Sendmail, but has the same
-effect as \-oem-\.
-
-.option oi
-.index dot||in incoming, non-SMTP message
-This option, which has the same effect as \-i-\, 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 \*rmail*\. See also \-ti-\.
-
-.option oitrue
-This option is treated as synonymous with \-oi-\.
-
-.option oMa #<<host address>>
-.index sender||host address, specifying for local message
-A number of options starting with \-oM-\ 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
-\-bh-\,
-\-be-\,
-\-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they
-are ignored unless the caller is trusted.
-
-The \-oMa-\ option sets the sender host address. This may include a port number
-at the end, after a full stop (period). For example:
-.display asis
-exim -bs -oMa 10.9.8.7.1234
-.endd
-An alternative syntax is to enclose the IP address in square brackets, followed
-by a colon and the port number:
-.display asis
-exim -bs -oMa [10.9.8.7]:1234
-.endd
-The IP address is placed in the \$sender@_host@_address$\ variable, and the
-port, if present, in \$sender@_host@_port$\.
-
-.option oMaa #<<name>>
-.index authentication||name, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMaa-\
-option sets the value of \$sender@_host@_authenticated$\ (the authenticator
-name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication.
-
-.option oMai #<<string>>
-.index authentication||id, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\
-option sets the
-value of \$authenticated@_id$\ (the id that was authenticated).
-This overrides the default value (the caller's login id) for messages from
-local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated
-ids.
-
-.option oMas #<<address>>
-.index authentication||sender, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\
-option sets the authenticated sender value
-in \$authenticated@_sender$\.
-It overrides the sender address that is created from the caller's login id for
-messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of
-authenticated senders.
-
-.option oMi #<<interface address>>
-.index interface||address, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\
-option sets the IP interface address value. A port number may be included,
-using the same syntax as for \-oMa-\.
-The interface address is placed in \$interface@_address$\ and the port number,
-if present, in \$interface@_port$\.
-
-.option oMr #<<protocol name>>
-.index protocol||incoming, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\
-option sets the received protocol value that is stored in
-\$received@_protocol$\. However, this applies only when \-bs-\ is not used. For
-interactive SMTP input (\-bs-\), the protocol is always
-.em
-`local-' followed by one of the standard SMTP protocol names (see the
-description of \$received@_protocol$\ in section ~~SECTexpvar).
-.nem
-For \-bS-\ (batch SMTP) however, the protocol can be set by \-oMr-\.
-
-.option oMs #<<host name>>
-.index sender||host name, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\
-option sets the sender host name
-in \$sender@_host@_name$\. 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.
-
-.option oMt #<<ident string>>
-.index sender||ident string, specifying for local message
-See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\
-option sets the sender ident value
-in \$sender@_ident$\.
-The default setting for local callers is the login id of the calling process.
-
-.option om
-.index Sendmail compatibility||\-om-\ option ignored
-In Sendmail, this option means `me too', 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.
-
-.option oo
-.index Sendmail compatibility||\-oo-\ option ignored
-This option is ignored. In Sendmail it specifies `old style headers', whatever
-that means.
-
-.option oP #<<path>>
-.index pid (process id)||of daemon
-.index daemon||process id (pid)
-This option is useful only in conjunction with \-bd-\ or \-q-\ with a time
-value. The option specifies the file to which the process id of the daemon is
-written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used
-without \-bd-\, this is the only way of causing Exim to write a pid file,
-because in those cases, the normal pid file is not used.
-
-.option or #<<time>>
-.index timeout||for non-SMTP input
-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 \receive@_timeout\ option. The format used for specifying times is
-described in section ~~SECTtimeformat.
-
-.option os #<<time>>
-.index timeout||for SMTP input
-.index SMTP||timeout, input
-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 \smtp@_receive@_timeout\ option; it defaults to 5 minutes. The format used
-for specifying times is described in section ~~SECTtimeformat.
-
-.option ov
-This option has exactly the same effect as \-v-\.
-
-.option oX #<<number or string>>
-.index TCP/IP||setting listening ports
-.index TCP/IP||setting listening interfaces
-.index port||receiving TCP/IP
-This option is relevant only when the \-bd-\ (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 ~~CHAPinterfaces. When \-oX-\ is used to start a daemon, no pid file is
-written unless \-oP-\ is also present to specify a pid file name.
-
-.option pd
-.index Perl||starting the interpreter
-This option applies when an embedded Perl interpreter is linked with Exim (see
-chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option,
-forcing the starting of the interpreter to be delayed until it is needed.
-
-.option ps
-.index Perl||starting the interpreter
-This option applies when an embedded Perl interpreter is linked with Exim (see
-chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option,
-forcing the starting of the interpreter to occur as soon as Exim is started.
-
-.option p<<rval>>:<<sval>>
-For compatibility with Sendmail, this option
-is equivalent to
-.display
--oMr <<rval>> -oMs <<sval>>
-.endd
-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, \-pd-\ and \-ps-\, that refer to
-embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or
-\"s"\ using this option (but that does not seem a real limitation).
-
-.option q
-.index queue runner||starting manually
-This option is normally restricted to admin users. However, there is a
-configuration option called \prod@_requires@_admin\ which can be set false to
-relax this restriction (and also the same requirement for the \-M-\, \-R-\, and
-\-S-\ options).
-
-.index queue runner||description of operation
-The \-q-\ 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 \-qf-\ (see below) if you want to override this.
-.index SMTP||passed connection
-.index SMTP||multiple deliveries
-.index multiple SMTP deliveries
-If the delivery process spawns other processes to deliver other messages down
-passed SMTP connections, the queue runner waits for these to finish before
-proceeding.
-
-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 \-q-\ with a time (see below) if you want this
-to be repeated periodically.
-
-Exim processes the waiting messages in an unpredictable order. It isn'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.
-
-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
-\queue@_run@_in@_order\ option, but this is not recommended for normal use.
-
-.option q <<qflags>>
-The \-q-\ 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.
-
-.option qq...
-.index queue||double scanning
-.index queue||routing
-.index routing||whole queue before delivery
-An option starting with \-qq-\ requests a two-stage queue run. In the first
-stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched
-every domain. Addresses are routed, local deliveries happen, but no remote
-transports are run.
-.index hints database||remembering routing
-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
-.index SMTP||passed connection
-.index SMTP||multiple deliveries
-.index multiple SMTP deliveries
-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.
-
-.option q[q]i...
-.index queue||initial delivery
-If the \*i*\ flag is present, the queue runner runs delivery processes only for
-those messages that haven't previously been tried. (\*i*\ stands for `initial
-delivery'.) This can be helpful if you are putting messages on the queue using
-\-odq-\ and want a queue runner just to process the new messages.
-
-.option q[q][i]f...
-.index queue||forcing delivery
-.index delivery||forcing in queue run
-If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen
-message, whereas without \f\ only those non-frozen addresses that have passed
-their retry times are tried.
-
-.option q[q][i]ff...
-.index frozen messages||forcing delivery
-If \*ff*\ is present, a delivery attempt is forced for every message, whether
-frozen or not.
-
-.option q[q][i][f[f]]l
-.index queue||local deliveries only
-The \*l*\ (the letter `ell') flag specifies that only local deliveries are to be
-done. If a message requires any remote deliveries, it remains on the queue for
-later delivery.
-
-.option q <<qflags>>#<<start id>>#<<end id>>
-.index queue||delivering specific messages
-When scanning the queue, Exim can be made to skip over messages whose ids are
-lexically less than a given value by following the \-q-\ option with a starting
-message id. For example:
-.display
-exim -q 0t5C6f-0000c8-00
-.endd
-Messages that arrived earlier than \"0t5C6f-0000c8-00"\ 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,
-.display
-exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00
-.endd
-just one delivery process is started, for that message. This differs from \-M-\
-in that retry data is respected, and it also differs from \-Mc-\ 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 -- see
-\-R-\ and \-S-\.
-
-.option q <<qflags>><<time>>
-.index queue runner||starting periodically
-.index periodic queue running
-When a time value is present, the \-q-\ 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 ~~SECTtimeformat). This form of the \-q-\
-option is commonly combined with the \-bd-\ 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
-.display
-/usr/exim/bin/exim -bd -q30m
-.endd
-Such a daemon listens for incoming SMTP calls, and also starts a queue runner
-process every 30 minutes.
-
-When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid
-file is written unless one is explicitly requested by the \-oP-\ option.
-
-.option qR <<rsflags>>#<<string>>
-This option is synonymous with \-R-\. It is provided for Sendmail
-compatibility.
-
-.option qS <<rsflags>>#<<string>>
-This option is synonymous with \-S-\.
-
-.option R <<rsflags>>#<<string>>
-.index queue runner||for specific recipients
-.index delivery||to given domain
-.index domain||delivery to
-The <<rsflags>> may be empty, in which case the white space before the string
-is optional, unless the string is \*f*\, \*ff*\, \*r*\, \*rf*\, or \*rff*\,
-which are the possible values for <<rsflags>>. White space is required if
-<<rsflags>> is not empty.
-
-This option is similar to \-q-\ 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 <<rsflags>> start with \*r*\, <<string>> is interpreted as a regular
-expression; otherwise it is a literal string.
-
-Once a message is selected, 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.
-
-If the <<rsflags>> contain \*f*\ or \*ff*\, the delivery forcing applies to all
-selected messages, not just the first;
-.index frozen messages||forcing delivery
-frozen messages are included when \*ff*\ is present.
-
-The \-R-\ 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 ~~CHAPACL), its default
-effect is to run Exim with the \-R-\ option, but it can be configured to run an
-arbitrary command instead.
-
-.option r
-This is a documented (for Sendmail) obsolete alternative name for \-f-\.
-
-.index delivery||from given sender
-.option S <<rsflags>>#<<string>>
-.index queue runner||for specific senders
-This option acts like \-R-\ except that it checks the string against each
-message's sender instead of against the recipients. If \-R-\ is also set, both
-conditions must be met for a message to be selected. If either of the options
-has \*f*\ or \*ff*\ in its flags, the associated action is taken.
-
-.option Tqt#<<times>>
-This 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 `queue times' so that various warning/retry features can be
-tested.
-
-.option t
-.index recipient||extracting from header lines
-.index ::Bcc:: header line
-.index ::Cc:: header line
-.index ::To:: header line
-When Exim is receiving a locally-generated, non-SMTP message on its standard
-input, the \-t-\ option causes the recipients of the message to be obtained
-from the ::To::, ::Cc::, and ::Bcc:: header lines in the message instead of from
-the command arguments. The addresses are extracted before any rewriting takes
-place.
-
-.index Sendmail compatibility||\-t-\ option
-If the command has any arguments, they specify addresses to which the message
-is $it{not} 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 $it{add}
-argument addresses to those obtained from the headers, and the O'Reilly
-Sendmail book documents it that way. Exim can be made to add argument addresses
-instead of subtracting them by setting the option
-\extract__addresses__remove__arguments\ false.
-
-If a ::Bcc:: header line is present, it is removed from the message unless
-there is no ::To:: or ::Cc::, in which case a ::Bcc:: line with no data is
-created. This is necessary for conformity with the original RFC 822 standard;
-the requirement has been removed in RFC 2822, but that is still very new.
-
-.index \Resent@-\ header lines||with \-t-\
-If there are any \Resent@-\ header lines in the message, Exim extracts
-recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header
-lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility
-with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if
-\-t-\ was used in conjunction with \Resent@-\ header lines.)
-
-RFC 2822 talks about different sets of \Resent@-\ 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 ::Received:: lines. It is
-not at all clear how \-t-\ should operate in the present of multiple sets,
-nor indeed exactly what constitutes a `set'.
-In practice, it seems that MUAs do not follow the RFC. The \Resent@-\ 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 \Resent@-\ headers to be renamed as
-\X-Resent@-\ when a new set is added. This removes any possible ambiguity.
-
-.option ti
-This option is exactly equivalent to \-t-\ \-i-\. It is provided for
-compatibility with Sendmail.
-
-.option tls-on-connect
-.index TLS||use without STARTTLS
-.index TLS||automatic start
-This option is available when Exim is compiled with TLS support.
-.em
-It forces all incoming SMTP connections to behave as if the incoming port is
-listed in the \tls@_on@_connect@_ports\ option. See section ~~SECTsupobssmt and
-chapter ~~CHAPTLS for further details.
-.nem
-
-.option U
-.index Sendmail compatibility||\-U-\ option ignored
-Sendmail uses this option for `initial message submission', 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.
-
-.option v
-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 \log@_selector\ discards them. Any relevant selectors
-are shown with each log line. If none are shown, the logging is unconditional.
-
-.option x
-AIX uses \-x-\ for a private purpose (`mail from a local mail program has
-National Language Support extended characters in the body of the mail item').
-It sets \-x-\ when calling the MTA from its \mail\ command. Exim ignores this
-option.
-
-.endoptions
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter The Exim run time configuration file
-.set runningfoot "configuration file"
-.rset CHAPconf ~~chapter
-
-.index run time configuration
-.index configuration file||general description
-.index \\CONFIGURE@_FILE\\
-.index configuration file||errors in
-.index error||in configuration file
-.index return code||for bad configuration
-Exim uses a single run time 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.
-
-.em
-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. \**Note**\: 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.
-.nem
-
-
-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 file names, in which case Exim uses the first
-existing file in the list.
-
-.index \\EXIM@_USER\\
-.index \\EXIM@_GROUP\\
-.index \\CONFIGURE@_OWNER\\
-.index \\CONFIGURE@_GROUP\\
-.index configuration file||ownership
-.index ownership||configuration file
-The run time configuration file must be owned by root or by the user that is
-specified at compile time by the \\EXIM@_USER\\ option, 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 one specified at compile time by the \\EXIM@_GROUP\\ option
-.em
-or by the \\CONFIGURE@_GROUP\\ option.
-.nem
-
-\**Warning**\: In a conventional configuration, where the Exim binary is setuid
-to root, anybody who is able to edit the run time configuration file has an
-easy way to run commands as root. If you make your mail administrators members
-of the Exim group, but do not trust them with root, make sure that the run time
-configuration is not group writeable.
-
-A default configuration file, which will work correctly in simple situations,
-is provided in the file \(src/configure.default)\. If \\CONFIGURE@_FILE\\
-defines just one file name, 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
-~~CHAPdefconfil is a `walk-through' discussion of the default configuration.
-
-
-.section Using a different configuration file
-.index configuration file||alternate
-A one-off alternate configuration can be specified by the \-C-\ command line
-option, which may specify a single file or a list of files. However, when \-C-\
-is used, Exim gives up its root privilege, unless called by root or the Exim
-user (or unless the argument for \-C-\ is identical to the built-in value from
-\\CONFIGURE@_FILE\\). \-C-\ 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 \-C-\.
-
-The privileged use of \-C-\ by the Exim user can be locked out by setting
-\\ALT@_CONFIG@_ROOT@_ONLY\\ in \(Local/Makefile)\ when building Exim. However,
-if you do this, you also lock out the possibility of testing a
-configuration using \-C-\ 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 \-C-\ causes privilege to be lost. However, root can test reception and
-delivery using two separate commands (one to put a message on the queue, using
-\-odq-\, and another to do the delivery, using \-M-\).
-
-If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a
-prefix string with which any file named in a \-C-\ command line option must
-start. In addition, the file name must not contain the sequence \"/../"\. There
-is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is unset, any file
-name can be used with \-C-\.
-
-One-off changes to a configuration can be specified by the \-D-\ command line
-option, which defines and overrides values for macros used inside the
-configuration file. However, like \-C-\, the use of this option by a
-non-privileged user causes Exim to discard its root privilege.
-If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is
-completely disabled, and its use causes an immediate error exit.
-
-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 \(Local/Makefile)\, Exim first
-looks for a file whose name is the configuration file name followed by a dot
-and the machine's node name, as obtained from the \*uname()*\ function. If this
-file does not exist, the standard name is tried. This processing occurs for
-each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\.
-
-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 \(src/EDITME)\ for details.
-
-
-.section Configuration file format
-.rset SECTconffilfor "~~chapter.~~section"
-.index configuration file||format of
-.index format||configuration file
-Exim'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 `begin' followed by the name of the part. The
-optional parts are:
-
-.numberpars $.
-\*ACL*\: Access control lists for controlling incoming SMTP mail.
-.nextp
-.index \\AUTH\\||configuration
-\*authenticators*\: Configuration settings for the authenticator drivers. These
-are concerned with the SMTP \\AUTH\\ command (see chapter ~~CHAPSMTPAUTH).
-.nextp
-\*routers*\: Configuration settings for the router drivers. Routers process
-addresses and determine how the message is to be delivered.
-.nextp
-\*transports*\: Configuration settings for the transport drivers. Transports
-define mechanisms for copying messages to destinations.
-.nextp
-\*retry*\: Retry rules, for use when a message cannot be immediately delivered.
-.nextp
-\*rewrite*\: Global address rewriting rules, for use when a message arrives and
-when new addresses are generated during delivery.
-.nextp
-\*local@_scan*\: Private options for the \*local@_scan()*\ function. If you
-want to use this feature, you must set
-.display asis
-LOCAL_SCAN_HAS_OPTIONS=yes
-.endd
-in \(Local/Makefile)\ before building Exim. Full details of the
-\*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan.
-.endp
-.index configuration file||leading whitespace in
-.index configuration file||trailing whitespace in
-.index whitespace||in configuration file
-.em
-Leading and trailing whitespace in configuration lines is always ignored.
-.nem
-Blank lines in the file, and lines starting with a @# character (ignoring
-leading white space) are treated as comments and are ignored. \**Note**\: a
-@# character other than at the beginning of a line is not treated specially,
-and does not introduce a comment.
-
-Any non-comment line can be continued by ending it with a backslash.
-.em
-Note that the general rule for whitespace means that trailing white space after
-the backslash is ignored, and leading white space at the start of continuation
-lines is also ignored.
-.nem
-Comment lines beginning with @# (but not empty lines) may appear in the middle
-of a sequence of continuation lines.
-
-A convenient way to create a configuration file is to start from the
-default, which is supplied in \(src/configure.default)\, and add, delete, or
-change settings as required.
-
-The ACLs, retry rules, and rewriting rules have their own syntax which is
-described in chapters ~~CHAPACL, ~~CHAPretry, and ~~CHAPrewrite, respectively.
-The other parts of the configuration file have some syntactic items in common,
-and these are described below, from section ~~SECTcos onwards. Before that, the
-inclusion, macro, and conditional facilities are described.
-
-
-.section File inclusions in the configuration file
-.index inclusions in configuration file
-.index configuration file||including other files
-.index .include in configuration file
-.index .include@_if@_exists in configuration file
-You can include other files inside Exim's run time configuration file by
-using this syntax:
-.display
-@.include <<file name>>
-.endd
-or
-.display
-@.include@_if@_exists <<file name>>
-.endd
-on a line by itself. Double quotes round the file name 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.
-
-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.
-
-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:
-.display asis
-hosts_lookup = a.b.c \
- .include /some/file
-.endd
-Include processing happens
-after
-macro processing (see below). Its effect is to process the lines of the file as
-if they occurred inline where the inclusion appears.
-
-
-.section Macros in the configuration file
-.rset SECTmacrodefs "~~chapter.~~section"
-.index macro||description of
-.index configuration file||macros
-If a line in the main part of the configuration (that is, before the first
-`begin' line) begins with an upper case letter, it is taken as a macro
-definition, and must be of the form
-.display
-<<name>> = <<rest of line>>
-.endd
-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't seem to be a serious limitation.
-
-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 they 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
-.display asis
-ABCD_XYZ = <<something>>
-ABCD = <<something else>>
-.endd
-but putting the definitions in the opposite order would provoke a configuration
-error.
-
-Macro expansion is applied to individual lines from the file, before checking
-for line continuation or file inclusion (see below). 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
-\".include"\ line.
-
-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:
-.display asis
-ALIAS_QUERY = select mailbox from user where \
- login=${quote_mysql:$local_part};
-.endd
-This can then be used in a \%redirect%\ router setting like this:
-.display asis
-data = ${lookup mysql{ALIAS_QUERY}}
-.endd
-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 -- see section
-~~SECTnamedlists.
-
-Macros in the configuration file can be overridden by the \-D-\ command line
-option, but Exim gives up its root privilege when \-D-\ is used, unless called
-by root or the Exim user.
-
-
-.section Conditional skips in the configuration file
-.index configuration file||conditional skips
-.index .ifdef
-You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\,
-\".elifndef"\, \".else"\, and \".endif"\ 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).
-
-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:
-.display
-@.ifdef AAA
-message@_size@_limit = 50M
-@.else
-message@_size@_limit = 100M
-@.endif
-.endd
-sets a message size limit of 50M if the macro \"AAA"\ is defined, 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 `or' condition. To
-obtain an `and' condition, you need to use nested \".ifdef"\s.
-
-Although you can use a macro expansion to generate one of these directives,
-it is not very useful, because the condition `there was a macro substitution
-in this line' will always be true.
-
-Text following \".else"\ and \".endif"\ is ignored, and can be used as comment
-to clarify complicated nestings.
-
-
-.section Common option syntax
-.rset SECTcos "~~chapter.~~section"
-.index common option syntax
-.index syntax of common options
-.index configuration file||common option syntax
-For the main set of options, driver options, and \*local@_scan()*\ 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:
-.display asis
-qualify_domain = mydomain.example.com
-.endd
-Some option settings may contain sensitive data, for example, passwords for
-accessing databases. To stop non-admin users from using the \-bP-\ command line
-option to read these values, you can precede the option settings with the word
-`hide'. For example:
-.display asis
-hide mysql_servers = localhost/users/admin/secret-password
-.endd
-For non-admin users, such options are displayed like this:
-.display asis
-mysql_servers = <value not displayable>
-.endd
-If `hide' is used on a driver option, it hides the value of that option on all
-instances of the same driver.
-
-The following sections describe the syntax used for the different data types
-that are found in option settings.
-
-.section Boolean options
-.index format||boolean
-.index boolean configuration values
-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 `no@_' or `not@_' the switch is turned off. However,
-boolean options may optionally be followed by an equals sign and one of the
-words `true', `false', `yes', or `no', as an alternative syntax. For example,
-the following two settings have exactly the same effect:
-.display asis
-queue_only
-queue_only = true
-.endd
-The following two lines also have the same (opposite) effect:
-.display asis
-no_queue_only
-queue_only = false
-.endd
-You can use whichever syntax you prefer.
-
-
-
-.section Integer values
-.index integer configuration values
-.index format||integer
-If an integer data item starts with the characters `0x', the remainder of it
-is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it
-starts with the digit 0, and decimal if not. 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.
-
-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.
-
-.section Octal integer values
-.index integer format
-.index format||octal integer
-The value of an option specified as an octal integer is always interpreted in
-octal, whether or not it starts with the digit zero. Such options are always
-output in octal.
-
-
-.section Fixed point number values
-.index fixed point configuration values
-.index format||fixed point
-A fixed point number consists of a decimal integer, optionally followed by a
-decimal point and up to three further digits.
-
-
-.section Time interval values
-.index time interval||specifying in configuration
-.index format||time interval
-.rset SECTtimeformat "~~chapter.~~section"
-A time interval is specified as a sequence of numbers, each followed by one of
-the following letters, with no intervening white space:
-.display rm
-.tabs 5
-\s\ $t seconds
-\m\ $t minutes
-\h\ $t hours
-\d\ $t days
-\w\ $t weeks
-.endd
-For example, `3h50m' 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 `90m' instead of `1h30m'.
-
-
-.section String values
-.index string||format of configuration values
-.index format||string
-.rset SECTstrings "~~chapter.~~section"
-If a string data item does not start with a double-quote character, it is taken
-as consisting of the remainder of the line plus any continuation lines,
-starting at the first character after any leading white space, with trailing
-white space characters 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 settings are therefore equivalent:
-.display asis
-trusted_users = uucp:mail
-
-trusted_users = uucp:\
- # This comment line is ignored
- mail
-.endd
-.index string||quoted
-.index escape characters in quoted strings
-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:
-.display
-.tabs 15
-@\@\ $t $rm{single backslash}
-@\n $t $rm{newline}
-@\r $t $rm{carriage return}
-@\t $t $rm{tab}
-@\<<octal digits>> $t $rm{up to 3 octal digits specify one character}
-@\x<<hex digits>> $t $rm{up to 2 hexadecimal digits specify one character}
-.endd
-If a backslash is followed by some other character, including a double-quote
-character, that character replaces the pair.
-
-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.
-
-.section Expanded strings
-.index string||expansion, definition of
-.index expansion||definition of
-Some strings in the configuration file are subjected to \*string expansion*\,
-by which means various parts of the string may be changed according to the
-circumstances (see chapter ~~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.
-
-.section User and group names
-.index user name||format of
-.index format||user name
-.index group||name format
-.index format||group name
-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
-\*getpwnam()*\ or \*getgrnam()*\ function, as appropriate.
-
-.section List construction
-.index list||syntax of in configuration
-.index format||list item in configuration
-.index string list, definition
-.rset SECTlistconstruct "~~chapter.~~section"
-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 `string list' in
-the descriptions later in this document. Others are listed as `domain list',
-`host list', `address list', or `local part list'. Syntactically, they are all
-the same; however, those other than `string list' are subject to particular
-kinds of interpretation, as described in chapter ~~CHAPdomhosaddlists.
-
-In all these cases, the entire list is treated as a single string as far as the
-input syntax is concerned. The \trusted@_users\ setting in section
-~~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
-.display asis
-local_interfaces = 127.0.0.1 : ::::1
-.endd
-contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address
-@:@:1.
-.index list||separator, changing
-.index IPv6||addresses in lists
-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:
-.display asis
-local_interfaces = <; 127.0.0.1 ; ::1
-.endd
-This facility applies to all lists, with the exception of the list in
-\log@_file@_path\. It is recommended that the use of non-colon separators be
-confined to circumstances where they really are needed.
-
-
-.em
-.section Empty items in lists
-.rset SECTempitelis "~~chapter.~~section"
-.index list||empty item in
-An empty item at the end of a list is always ignored. In other words, trailing
-separator characters are ignored. Thus, the list in
-.display asis
-senders = user@domain :
-.endd
-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:
-.display asis
-senders = user1@domain : : user2@domain
-.endd
-\**Note**\: there must be whitespace 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:
-.display asis
-senders = :
-.endd
-In this case, the first item is empty, and the second is discarded because it
-is at the end of the list.
-.nem
-
-
-.section Format of driver configurations
-.rset SECTfordricon "~~chapter.~~section"
-.index drivers||configuration format
-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:
-.display
-<<instance name>>:
- <<option>>
- ...
- <<option>>
-.endd
-In the following example, the instance name is \%localuser%\, and it is
-followed by three options settings:
-.display asis
-localuser:
- driver = accept
- check_local_user
- transport = local_delivery
-.endd
-For each driver instance, you specify which Exim code module it uses -- by the
-setting of the \driver\ option -- 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 \%smtp%\ driver; if you want to deliver to a local file
-you would use the \%appendfile%\ driver. Each of the drivers is described in
-detail in its own separate chapter later in this manual.
-
-You can have several routers, transports, or authenticators that are based on
-the same underlying driver (each must have a different name).
-
-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.
-
-.index generic options
-.index options||generic, definition of
-Within a driver instance definition, there are two kinds of option:
-$it{generic} and $it{private}. The generic options are those that apply to all
-drivers of the same type (that is, all routers, all transports or all
-authenticators).
-The \driver\ option is a generic option that must appear in every definition.
-.index private options
-The private options are special for each driver, and none need appear, because
-they all have default values.
-
-The options may appear in any order, except that the \driver\ option must
-precede any private options, since these depend on the particular driver. For
-this reason, it is recommended that \driver\ always be the first option.
-
-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:
-.display asis
-remote_smtp:
- driver = smtp
-.endd
-create an instance of the \%smtp%\ transport driver whose name is
-\%remote@_smtp%\. 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 \%smtp%\ transport, with different options, might be defined
-thus:
-.display asis
-special_smtp:
- driver = smtp
- port = 1234
- command_timeout = 10s
-.endd
-The names \%remote@_smtp%\ and \%special@_smtp%\ would be used to reference
-these transport instances from routers, and these names would appear in log
-lines.
-
-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 \-bP-\ command line
-option.
-
-
-
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter The default configuration file
-.set runningfoot "default configuration"
-.rset CHAPdefconfil "~~chapter"
-.index configuration file||default, `walk through'
-.index default||configuration file `walk through'
-The default configuration file supplied with Exim as \(src/configure.default)\
-is sufficient for a host with simple mail requirements. As an introduction to
-the way Exim is configured, this chapter `walks through' 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.
-
-
-.section Main configuration settings
-The main (global) configuration option settings must always come first in the
-file. The first thing you'll see in the file, after some initial comments, is
-the line
-.display asis
-# primary_hostname =
-.endd
-This is a commented-out setting of the \primary@_hostname\ 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 \*uname()*\ system function to obtain the host name.
-
-The first three non-comment configuration lines are as follows:
-.display asis
-domainlist local_domains = @
-domainlist relay_to_domains =
-hostlist relay_from_hosts = 127.0.0.1
-.endd
-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 ~~SECTnamedlists).
-
-The first line defines a domain list called \*local@_domains*\; this is used
-later in the configuration to identify domains that are to be delivered
-on the local host.
-.index @@ in a domain list
-There is just one item in this list, the string `@@'. This is a special form of
-entry which means `the name of the local host'. Thus, if the local host is
-called \*a.host.example*\, mail to \*any.user@@a.host.example*\ is expected to
-be delivered locally. Because the local host's name is referenced indirectly,
-the same configuration file can be used on different hosts.
-
-The second line defines a domain list called \*relay@_to@_domains*\, 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.
-
-The third line defines a host list called \*relay@_from@_hosts*\. 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.
-
-Just to be sure there's no misunderstanding: at this point in the configuration
-we aren'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.
-
-The next configuration line is a genuine option setting:
-.display asis
-acl_smtp_rcpt = acl_check_rcpt
-.endd
-This option specifies an \*Access Control List*\ (ACL) which is to be used
-during an incoming SMTP session for every recipient of a message (every
-\\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will
-come to its definition below, in the ACL section of the configuration. ACLs
-control which recipients are accepted for an incoming message -- if a
-configuration does not provide an ACL to check recipients, no SMTP mail can be
-accepted.
-
-Two commented-out options settings are next:
-.display asis
-# qualify_domain =
-# qualify_recipient =
-.endd
-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 \qualify@_domain\,
-the value of \primary@_hostname\ 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.
-
-.index domain literal||recognizing format
-The following line must be uncommented if you want Exim to recognize
-addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal'
-(an IP address) instead of a named domain.
-.display asis
-# allow_domain_literals
-.endd
-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
-\*postmaster*\) where domain literals are still useful.
-
-The next configuration line is a kind of trigger guard:
-.display asis
-never_users = root
-.endd
-It specifies that no delivery must ever be run as the root user. The normal
-convention is to set up \*root*\ as an alias for the system administrator. This
-setting is a guard against slips in the configuration.
-The list of users specified by \never@_users\ is not, however, the complete
-list; the build-time configuration in \(Local/Makefile)\ has an option called
-\\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The
-contents of \never@_users\ are added to this list. By default
-\\FIXED@_NEVER@_USERS\\ also specifies root.
-
-When a remote host connects to Exim in order to send mail, the only information
-Exim has about the host's identity is its IP address. The next configuration
-line,
-.display asis
-host_lookup = *
-.endd
-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 `nearby' 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.
-
-The next two lines are concerned with \*ident*\ callbacks, as defined by RFC
-1413 (hence their names):
-.display asis
-rfc1413_hosts = *
-rfc1413_query_timeout = 30s
-.endd
-These settings cause Exim to make ident callbacks for all incoming SMTP calls.
-You can limit the hosts to which these calls are made, or change the timeout
-that is used. If you set the timeout to zero, all ident calls are disabled.
-Although they are cheap and can provide useful information for tracing problem
-messages, some hosts and firewalls have problems with ident calls. This can
-result in a timeout instead of an immediate refused connection, leading to
-delays on starting up an incoming SMTP session.
-
-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:
-.display asis
-# sender_unqualified_hosts =
-# recipient_unqualified_hosts =
-.endd
-show how you can specify hosts that are permitted to send unqualified sender
-and recipient addresses, respectively.
-
-The \percent@_hack@_domains\ option is also commented out:
-.display asis
-# percent_hack_domains =
-.endd
-It provides a list of domains for which the `percent hack' 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.
-
-The last two settings in the main part of the default configuration are
-concerned with messages that have been `frozen' on Exim'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.
-.display asis
-ignore_bounce_errors_after = 2d
-timeout_frozen_after = 7d
-.endd
-The first of these options specifies that failing bounce messages are to be
-discarded after 2 days on 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.
-
-
-.section ACL configuration
-.index default||ACLs
-.index ~~ACL||default configuration
-In the default configuration, the ACL section follows the main configuration.
-It starts with the line
-.display asis
-begin acl
-.endd
-and it contains the definition of one ACL called \*acl@_check@_rcpt*\ that was
-referenced in the setting of \acl@_smtp@_rcpt\ above.
-.index \\RCPT\\||ACL for
-This ACL is used for every \\RCPT\\ command in an incoming SMTP message. Each
-\\RCPT\\ command specifies one of the message'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.
-.display asis
-acl_check_rcpt:
-.endd
-This line, consisting of a name terminated by a colon, marks the start of the
-ACL, and names it.
-.display asis
-accept hosts = :
-.endd
-This ACL statement accepts the recipient if the sending host matches the list.
-But what does that strange list mean? It doesn'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 didn't come from a remote
-host. The colon is important. Without it, the list itself is empty, and can
-never match anything.
-
-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.
-.display asis
-deny domains = +local_domains
- local_parts = ^[.] : ^.*[@%!/|]
-
-deny domains = !+local_domains
- local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./
-.endd
-These statements are concerned with local parts that contain any of the
-characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these
-characters are entirely legal in local parts (in the case of `@@' and leading
-dots, only if correctly quoted), they do not commonly occur in Internet mail
-addresses.
-
-The first three have in the past been associated with explicitly routed
-addresses (percent is still sometimes used -- see the \percent@_hack@_domains\
-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.
-
-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
-\*local@_domains*\ domain list. The `+' character is used to indicate a
-reference to a named list. In this configuration, there is just one domain in
-\*local@_domains*\, but in general there may be many.
-
-The second condition on the first statement uses two regular expressions to
-block local parts that begin with a dot or contain `@@', `%', `!', `/', or `|'.
-If you have local accounts that include these characters, you will have to
-modify this rule.
-
-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 local
-parts constructed as `first-initial.second-initial.family-name' when applied to
-someone like the author of Exim, who has no second initial.) However, a local
-part starting with a dot or containing `/../' can cause trouble if it is used
-as part of a file name (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.
-
-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 `/../' is barred. The use of `@@', `%', and
-`!' is blocked, as before. The motivation here is to prevent your users (or
-your users' viruses) from mounting certain kinds of attack on remote sites.
-
-.display asis
-accept local_parts = postmaster
- domains = +local_domains
-.endd
-This statement, which has two conditions, accepts an incoming address if the
-local part is \*postmaster*\ and the domain is one of those listed in the
-\*local@_domains*\ domain list. The `+' character is used to indicate a
-reference to a named list. In this configuration, there is just one domain in
-\*local@_domains*\, but in general there may be many.
-
-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.
-.display asis
-require verify = sender
-.endd
-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 \*callouts*\ can be used for more
-verification if required. Section ~~SECTaddressverification discusses the
-details of address verification.
-
-.display asis
-# deny message = rejected because $sender_host_address is \
-# in a black list at $dnslist_domain\n\
-# $dnslist_text
-# dnslists = black.list.example
-#
-# warn message = X-Warning: $sender_host_address is \
-# in a black list at $dnslist_domain
-# log_message = found in $dnslist_domain
-# dnslists = black.list.example
-.endd
-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 merely inserts a warning header
-line.
-
-.display asis
-accept domains = +local_domains
- endpass
- message = unknown user
- verify = recipient
-.endd
-This statement accepts the incoming recipient address if its domain is one of
-the local domains, but only if the address can be verified. Verification of
-local addresses normally checks both the local part and the domain. The
-\endpass\ line needs some explanation: if the condition above \endpass\ fails,
-that is, if the address is not in a local domain, control is passed to the next
-ACL statement. However, if the condition below \endpass\ fails, that is, if a
-recipient in a local domain cannot be verified, access is denied and the
-recipient is rejected.
-.index customizing||ACL failure message
-The \message\ modifier provides a customized error message for the failure.
-.display asis
-accept domains = +relay_to_domains
- endpass
- message = unrouteable address
- verify = recipient
-.endd
-This statement accepts the incoming recipient address if its domain is one of
-the domains for which this host is a relay, but again, only if the address can
-be verified.
-.display asis
-accept hosts = +relay_from_hosts
-.endd
-Control reaches this statement only if the recipient's domain is neither a
-local domain, nor a relay domain. The 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. If you are actually relaying out from MTAs, you should probably add
-recipient verification here.
-.display asis
-accept authenticated = *
-.endd
-Control reaches here for attempts to relay to arbitrary domains from arbitrary
-hosts. The statement accepts the address only if the client host has
-authenticated itself. The default configuration does not define any
-authenticators, which means that no client can in fact authenticate. You will
-need to add authenticator definitions if you want to make use of this ACL
-statement.
-.display asis
-deny message = relay not permitted
-.endd
-The final statement denies access, giving a specific error message. Reaching
-the end of the ACL also causes access to be denied, but with the generic
-message `administrative prohibition'.
-
-
-.section Router configuration
-.index default||routers
-.index routers||default
-The router configuration comes next in the default configuration, introduced
-by the line
-.display asis
-begin routers
-.endd
-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.
-
-.index domain literal||default router
-.display asis
-# domain_literal:
-# driver = ipliteral
-# domains = !+local_domains
-# transport = remote_smtp
-.endd
-This router is commented out because the majority of sites do not want to
-support domain literal addresses (those of the form \*user@@[10.9.8.7]*\). If
-you uncomment this router, you also need to uncomment the setting of
-\allow@_domain@_literals\ in the main part of the configuration.
-
-.display asis
-dnslookup:
- driver = dnslookup
- domains = ! +local_domains
- transport = remote_smtp
-.newline
- ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8
-.newline
- no_more
-.endd
-The first uncommented router handles addresses that do not involve any local
-domains. This is specified by the line
-.display asis
-domains = ! +local_domains
-.endd
-The \domains\ 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 \*local@_domains*\ (which was defined at
-the start of the configuration). The plus sign before \*local@_domains*\
-indicates that it is referring to a named list. Addresses in other domains are
-passed on to the following routers.
-
-The name of the router driver is \%dnslookup%\,
-and is specified by the \driver\ 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 \driver\ option must be one
-of the driver modules that is in the Exim binary.
-
-The \%dnslookup%\ 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 \%remote@_smtp%\ transport, as
-specified by the \transport\ option. If the router does not find the domain in
-the DNS, no further routers are tried because of the \no@_more\ setting, so the
-address fails and is bounced.
-
-The \ignore@_target@_hosts\ 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.
-.display asis
-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
-.endd
-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 \(/etc/aliases)\ 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 \data\ option is empty, causing the address to be passed to
-the next router.
-
-\(/etc/aliases)\ 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
-\(Local/Makefile)\ before building Exim.
-
-.display asis
-userforward:
- driver = redirect
- check_local_user
- file = $home/.forward
- no_verify
- no_expn
- check_ancestor
-# allow_filter
- file_transport = address_file
- pipe_transport = address_pipe
- reply_transport = address_reply
-.endd
-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 \check@_local@_user\ setting means that the first thing it
-does is to check that the local part of the address is the login name of a
-local user. If it is not, the router is skipped. When a local user is found,
-the file called \(.forward)\ in the user's home directory is consulted. If it
-does not exist, or is empty, the router declines. Otherwise, the contents of
-\(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect
-for more details).
-
-.index Sieve filter||enabling in default router
-Traditional \(.forward)\ files contain just a list of addresses, pipes, or
-files. Exim supports this by default. However, if \allow@_filter\ 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 `@#Exim
-filter' or `@#Sieve filter', respectively. User filtering is discussed in the
-separate document entitled \*Exim's interfaces to mail filtering*\.
-
-The \no@_verify\ and \no@_expn\ 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:
-.numberpars
-Whether or not a local user has a \(.forward)\ file is not really relevant when
-checking an address for validity; it makes sense not to waste resources doing
-unnecessary work.
-.nextp
-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' \(.forward)\ files at
-this time.
-.endp
-
-The setting of \check@_ancestor\ 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 -- see section ~~SECTredlocmai).
-
-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 \(.forward)\ file contains
-.display asis
-a.nother@elsewhere.example, /home/spqr/archive
-.endd
-the delivery to \(/home/spqr/archive)\ is done by running the \address@_file\
-transport.
-.display asis
-localuser:
- driver = accept
- check_local_user
- transport = local_delivery
-.endd
-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 queuing it for
-the \%local@_delivery%\ transport. Otherwise, we have reached the end of the
-routers, so the address is bounced.
-
-
-.section Transport configuration
-.index default||transports
-.index transports||default
-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
-.display asis
-begin transports
-.endd
-One remote transport and four local transports are defined.
-.display asis
-remote_smtp:
- driver = smtp
-.endd
-This transport is used for delivering messages over SMTP connections. All its
-options are defaulted. The list of remote hosts comes from the router.
-.display asis
-local_delivery:
- driver = appendfile
- file = /var/mail/$local_part
- delivery_date_add
- envelope_to_add
- return_path_add
-# group = mail
-# mode = 0660
-.endd
-This \%appendfile%\ transport is used for local delivery to user mailboxes in
-traditional BSD mailbox format. By default it runs under the uid and gid of the
-local user, which requires the sticky bit to be set on the \(/var/mail)\
-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.
-
-Exim adds three headers to the message as it delivers it: ::Delivery-date::,
-::Envelope-to:: and ::Return-path::. This action is requested by the three
-similarly-named options above.
-.display asis
-address_pipe:
- driver = pipe
- return_output
-.endd
-This transport is used for handling deliveries to pipes that are generated by
-redirection (aliasing or users' \(.forward)\ files). The \return@_output\
-option specifies that any output generated by the pipe is to be returned to the
-sender.
-.display asis
-address_file:
- driver = appendfile
- delivery_date_add
- envelope_to_add
- return_path_add
-.endd
-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
-\%appendfile%\, because it comes from the \%redirect%\ router.
-.display asis
-address_reply:
- driver = autoreply
-.endd
-This transport is used for handling automatic replies generated by users'
-filter files.
-
-
-.section Default retry rule
-.index retry||default rule
-.index default||retry rule
-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
-.display asis
-begin retry
-.endd
-In the default configuration, there is just one rule, which applies to all
-errors:
-.display asis
-* * F,2h,15m; G,16h,1h,1.5; F,4d,6h
-.endd
-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 failure, it is bounced.
-
-
-.section Rewriting configuration
-The rewriting section of the configuration, introduced by
-.display asis
-begin rewrite
-.endd
-contains rules for rewriting addresses in messages as they arrive. There are no
-rewriting rules in the default configuration file.
-
-
-.section Authenticators configuration
-.index \\AUTH\\||configuration
-The authenticators section of the configuration, introduced by
-.display asis
-begin authenticators
-.endd
-defines mechanisms for the use of the SMTP \\AUTH\\ command. No authenticators
-are specified in the default configuration file.
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter Regular expressions
-.set runningfoot "regular expressions"
-.rset CHAPregexp ~~chapter
-
-.index regular expressions||library
-.index PCRE
-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 many Perl reference books, and also in
-Jeffrey Friedl's
-.if ~~html
-[(A HREF="http://www.oreilly.com/catalog/regex/")]
-.fi
-$it{Mastering Regular Expressions}
-.if ~~html
-[(/A)]
-.fi
-(O'Reilly, ISBN 0-596-00289-0).
-
-The documentation for the syntax and semantics of the regular expressions that
-are supported by PCRE is included in plain text in the file
-\(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML
-tarbundle of Exim documentation, and as an appendix to the
-.if ~~html
-[(A HREF="http://www.uit.co.uk/exim-book/")]
-.fi
-Exim book.
-.if ~~html
-[(/A)]
-.fi
-It describes in detail the features of the regular expressions that PCRE
-supports, so 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.
-
-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 `ends with' wildcard. In this example of a configuration setting, the
-second item in the colon-separated list is a regular expression.
-.display asis
-domains = a.b.c : ^\\d{3} : *.y.z : ...
-.endd
-The doubling of the backslash is required because of string expansion that
-precedes interpretation -- see section ~~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 `anchoring' it to the start of the string that is being
-matched.
-
-There are, however, two cases where a circumflex is not required for the
-recognition of a regular expression: these are the \match\ condition in a
-string expansion, and the \matches\ 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.
-
-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:
-.display asis
-domains = ^\\d{3}\\.example
-.endd
-matches the domain \*123.example*\, but it also matches \*123.example.com*\.
-You need to use:
-.display asis
-domains = ^\\d{3}\\.example\$
-.endd
-if you want \*example*\ to be the top-level domain. (The backslash before the
-@$ is another artefact of string expansion.)
-
-
-.section Testing regular expressions
-.index testing||regular expressions
-.index regular expressions||testing
-.index \*pcretest*\
-A program called \*pcretest*\ forms part of the PCRE distribution and is built
-with PCRE during the process of building Exim. It is primarily intended for
-testing PCRE itself, but it can also be used for experimenting with regular
-expressions. After building Exim, the binary can be found in the build
-directory (it is not installed anywhere automatically). There is documentation
-of various options in \(doc/pcretest.txt)\, but for simple testing, none are
-needed. This is the output of a sample run of \*pcretest*\:
-.display
- re> $cb{/^([^@@]+)@@.+@\.(ac|edu)@\.(?!kr)[a-z]@{2@}@$/}
-data> $cb{x@@y.ac.uk}
- 0: x@@y.ac.uk
- 1: x
- 2: ac
-data> $cb{x@@y.ac.kr}
-No match
-data> $cb{x@@y.edu.com}
-No match
-data> $cb{x@@y.edu.co}
- 0: x@@y.edu.co
- 1: x
- 2: edu
-.endd
-.if ~~sys.fancy
-Input typed by the user is shown in bold face.
-.fi
-After the `re>' prompt, a regular expression enclosed in delimiters is
-expected. If this compiles without error, `data>' prompts are given for strings
-against which the expression is matched. An empty data line causes a new
-regular expression to be read. If the match is successful, the captured
-substring values (that is, what would be in the variables \$0$\, \$1$\, \$2$\,
-etc.) are shown. The above example tests for an email address whose domain ends
-with either `ac' or `edu' followed by a two-character top-level domain that is
-not `kr'. The local part is captured in \$1$\ and the `ac' or `edu' in \$2$\.
-
-
-
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter File and database lookups
-.set runningfoot "file/database lookups"
-.rset CHAPfdlookup "~~chapter"
-.index file||lookup
-.index database lookups
-.index lookup||description of
-Exim can be configured to look up data in files or databases as it processes
-messages. Two different kinds of syntax are used:
-.numberpars
-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.
-.nextp
-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 ~~CHAPdomhosaddlists.
-.endp
-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:
-.display asis
-domains = ${lookup{$sender_host_address}lsearch{/some/file}}
-domains = lsearch;/some/file
-.endd
-The first uses a string expansion, the result of which must be a domain list.
-String expansions are described in detail in chapter ~~CHAPexpand. The
-expansion takes place first, and the file that is searched could contain lines
-like this:
-.display asis
-192.168.3.4: domain1 : domain2 : ...
-192.168.1.9: domain3 : domain4 : ...
-.endd
-Thus, the result of the expansion is a list of domains (and possibly other
-types of item that are allowed in domain lists).
-
-In the second case, 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:
-.display asis
-domain1:
-domain2:
-.endd
-Any data that follows the keys is not relevant when checking that the domain
-matches the list item.
-
-It is possible to use both kinds of lookup at once. Consider a file containing
-lines like this:
-.display asis
-192.168.5.6: lsearch;/another/file
-.endd
-If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the
-first \domains\ setting above generates the second setting, which therefore
-causes a second lookup to occur.
-
-The rest of this chapter describes the different lookup types that are
-available. Any of them can be used in either of the circumstances described
-above. The syntax requirements for the two cases are described in chapters
-~~CHAPexpand and ~~CHAPdomhosaddlists, respectively.
-
-.section Lookup types
-.index lookup||types of
-.index single-key lookup||definition of
-Two different styles of data lookup are implemented:
-.numberpars $.
-The \*single-key*\ style requires the specification of a file in which to look,
-and a single key to search for.
-.em
-The key must be a non-empty string for the lookup to succeed.
-.nem
-The lookup type determines how the file is searched.
-.nextp
-.index query-style lookup||definition of
-The \*query*\ style accepts a generalized database query.
-No particular key value is assumed by Exim for query-style lookups. You can
-use whichever Exim variable(s) you need to construct the database query.
-.endp
-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 \(src/EDITME)\ are:
-.display asis
-LOOKUP_DBM=yes
-LOOKUP_LSEARCH=yes
-.endd
-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.
-
-
-
-.section Single-key lookup types
-.rset SECTsinglekeylookups "~~chapter.~~section"
-.index lookup||single-key types
-.index single-key lookup||list of types
-The following single-key lookup types are implemented:
-.numberpars $.
-.index cdb||description of
-.index lookup||cdb
-.index binary zero||in lookup key
-\%cdb%\: 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 particulary suitable for large files containing
-aliases or other indexed data referenced by an MTA. Information about cdb can
-be found in several places:
-.display rm
-\?http://www.pobox.com/@~djb/cdb.html?\
-\?ftp://ftp.corpit.ru/pub/tinycdb/?\
-\?http://packages.debian.org/stable/utils/freecdb.html?\
-.endd
-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.
-.nextp
-.index DBM||lookup type
-.index lookup||dbm
-.index binary zero||in lookup key
-\%dbm%\: 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
-~~SECTdb for a discussion of DBM libraries.
-.index Berkeley DB library||file format
-For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database
-when building DBM files using the \exim@_dbmbuild\ 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.)
-
-.nextp
-.index lookup||dbmnz
-.index lookup||dbm, terminating zero
-.index binary zero||in lookup key
-.index Courier
-.index \(/etc/userdbshadow.dat)\
-.index dmbnz lookup type
-\%dbmnz%\: This is the same as \%dbm%\, 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 \%dbmnz%\ rather than \%dbm%\ if you want to authenticate incoming SMTP
-calls using the passwords from Courier's \(/etc/userdbshadow.dat)\ file. Exim's
-utility program for creating DBM files (\*exim@_dbmbuild*\) includes the zeros
-by default, but has an option to omit them (see section ~~SECTdbmbuild).
-.nextp
-.index lookup||dsearch
-.index dsearch lookup type
-\%dsearch%\: The given file must be a directory; this is searched for a file
-whose name is the key. The key may not contain any forward slash characters.
-The result of a successful lookup is the name of the file. An example of how
-this lookup can be used to support virtual domains is given in section
-~~SECTvirtualdomains.
-.nextp
-.index lookup||iplsearch
-.index iplsearch lookup type
-\%iplsearch%\: 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:
-.display asis
-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
-.endd
-The key for an \%iplsearch%\ 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
-`best' match. Apart from the way the keys are matched, the processing for
-\%iplsearch%\ is the same as for \%lsearch%\.
-
-\**Warning 1**\: Unlike most other single-key lookup types, a file of data for
-\%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those
-lookup types support only literal keys.
-
-\**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that
-the implicit key is the host's IP address rather than its name (see section
-~~SECThoslispatsikey).
-
-.nextp
-.index linear search
-.index lookup||lsearch
-.index lsearch lookup type
-\%lsearch%\: 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 first occurrence that is found in the file is used. 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:
-.display
-baduser: :fail:
-.endd
-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 \%lsearch%\ file are literal strings. There is no
-wildcarding of any kind.
-
-.index lookup||lsearch, colons in keys
-.index whitespace||in lsearch key
-In most \%lsearch%\ files, keys are not required to contain colons or @#
-characters, or whitespace. 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 ~~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 \%lsearch%\ line.
-.nextp
-.index NIS lookup type
-.index lookup||NIS
-.index binary zero||in lookup key
-\%nis%\: 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
-\%nis0%\ 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.
-.nextp
-.index wildlsearch lookup type
-.index lookup||wildlsearch
-.index nwildlsearch lookup type
-.index lookup||nwildlsearch
-\%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like
-\%lsearch%\, but instead of being interpreted as a literal string, each key may
-be wildcarded. The difference between these two lookup types is that for
-\%wildlsearch%\, each key in the file is string-expanded before being used,
-whereas for \%nwildlsearch%\, no expansion takes place.
-
-Like \%lsearch%\, the testing is done case-insensitively. The following forms
-of wildcard are recognized:
-.numberpars "$*$"
-The string may begin with an asterisk to mean `ends with'. For example:
-.display asis
-*.a.b.c data for anything.a.b.c
-*fish data for anythingfish
-.endd
-.nextp
-The string may begin with a circumflex to indicate a regular expression. For
-example, for \%wildlsearch%\:
-.display asis
-^\N\d+\.a\.b\N data for <digits>.a.b
-.endd
-Note the use of \"@\N"\ to disable expansion of the contents of the regular
-expression. If you are using \%nwildlsearch%\, where the keys are not
-string-expanded, the equivalent entry is:
-.display asis
-^\d+\.a\.b data for <digits>.a.b
-.endd
-
-If the regular expression contains white space or colon characters, you must
-either quote it (see \%lsearch%\ above), or represent these characters in other
-ways. For example, \"@\s"\ can be used for white space and \"@\x3A"\ for a
-colon. This may be easier than quoting, because if you quote, you have to
-escape all the backslashes inside the quotes.
-.nextp
-Although I cannot see it being of much use, the general matching function
-that is used to implement
-\%(n)wildlsearch%\
-means that the string may begin with a lookup name terminated by a semicolon,
-and followed by lookup data. For example:
-.display asis
-cdb;/some/file data for keys that match the file
-.endd
-The data that is obtained from the nested lookup is discarded.
-.endp
-Keys that do not match any of these patterns are interpreted literally. The
-continuation rules for the data are the same as for \%lsearch%\, and keys may
-be followed by optional colons.
-
-\**Warning**\: Unlike most other single-key lookup types, a file of data for
-\%(n)wildlsearch%\ can \*not*\ be turned into a DBM or cdb file, because those
-lookup types support only literal keys.
-.endp
-
-.section Query-style lookup types
-.index lookup||query-style types
-.index query-style lookup||list of types
-The supported query-style lookup types are listed below. Further details about
-many of them are given in later sections.
-.numberpars $.
-.index DNS||as a lookup type
-.index lookup||DNS
-\%dnsdb%\: This does a DNS search for
-.em
-one or more records whose domain names are given in the supplied query. The
-resulting data is the contents of the records.
-.nem
-See section ~~SECTdnsdb.
-.nextp
-.index Interbase lookup type
-.index lookup||Interbase
-\%ibase%\: This does a lookup in an Interbase database.
-.nextp
-.index LDAP||lookup type
-.index lookup||LDAP
-\%ldap%\: 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 \%ldapm%\
-that permits values from multiple entries to be returned. A third variant
-called \%ldapdn%\ returns the Distinguished Name of a single entry instead of
-any attribute values. See section ~~SECTldap.
-.nextp
-.index MySQL||lookup type
-.index lookup||MySQL
-\%mysql%\: The format of the query is an SQL statement that is passed to a MySQL
-database. See section ~~SECTsql.
-.nextp
-.index NIS@+ lookup type
-.index lookup||NIS+
-\%nisplus%\: This does a NIS+ lookup using a query that can specify the name of
-the field to be returned. See section ~~SECTnisplus.
-.nextp
-.index Oracle||lookup type
-.index lookup||Oracle
-\%oracle%\: The format of the query is an SQL statement that is passed to an
-Oracle database. See section ~~SECTsql.
-.nextp
-.index lookup||passwd
-.index passwd lookup type
-.index \(/etc/passwd)\
-\%passwd%\ is a query-style lookup with queries that are just user names. The
-lookup calls \*getpwnam()*\ to interrogate the system password data, and on
-success, the result string is the same as you would get from an \%lsearch%\
-lookup on a traditional \(/etc/passwd file)\, though with \"*"\ for the
-password value. For example:
-.display asis
-*:42:42:King Rat:/home/kr:/bin/bash
-.endd
-.nextp
-.index PostgreSQL lookup type
-.index lookup||PostgreSQL
-\%pgsql%\: The format of the query is an SQL statement that is passed to a
-PostgreSQL database. See section ~~SECTsql.
-.nextp
-\%testdb%\: This is a lookup type that is used for testing Exim. It is
-not likely to be useful in normal operation.
-.nextp
-.index whoson lookup type
-.index lookup||whoson
-\%whoson%\: \*Whoson*\ (\?http://whoson.sourceforge.net?\) is a proposed
-Internet protocol that allows Internet server programs 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. In
-Exim, this can be used to implement `POP before SMTP' checking using ACL
-statements such as
-.display asis
-require condition = \
- ${lookup whoson {$sender_host_address}{yes}{no}}
-.endd
-The query consists of a single IP address. The value returned is the name of
-the authenticated user.
-.endp
-
-.section Temporary errors in lookups
-.index lookup||temporary error in
-Lookup functions can return temporary error codes if the lookup cannot be
-completed. For example, a NIS 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.
-
-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.
-
-
-.section Default values in single-key lookups
-.rset SECTdefaultvaluelookups "~~chapter.~~section"
-.index wildcard lookups
-.index lookup||default values
-.index lookup||wildcard
-.index lookup||$*$ added to type
-.index default||in single-key lookups
-In this context, a `default value' is a value specified by the administrator
-that is to be used if a lookup fails.
-
-If `$*$' is added to a single-key lookup type (for example, \lsearch$*$\) and
-the initial lookup fails, the key `$*$' is looked up in the file to provide
-a default value. See also the section on partial matching below.
-
-.index @*@@ with single-key lookup
-.index lookup||$*$@@ added to type
-.index alias file||per-domain default
-Alternatively, if `$*$@@' is added to a single-key lookup type (for example
-\dbm$*$@@\) 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't
-take place because there is no @@ in the key), `$*$' is looked up.
-For example, a \%redirect%\ router might contain:
-.display asis
-data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}}
-.endd
-Suppose the address that is being processed is \*jane@@eyre.example*\. Exim
-looks up these keys, in this order:
-.display asis
-jane@eyre.example
-*@eyre.example
-*
-.endd
-The data is taken from whichever key it finds first. \**Note**\: in an
-\%lsearch%\ 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.
-
-
-.section Partial matching in single-key lookups
-.rset SECTpartiallookup "~~chapter.~~section"
-.index partial matching
-.index wildcard lookups
-.index lookup||partial matching
-.index lookup||wildcard
-.index asterisk||in search type
-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 `$*$.' 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
-.display
-*.dates.fict.example
-.endd
-then when partial matching is enabled this is matched by (amongst others)
-\*2001.dates.fict.example*\ and \*1984.dates.fict.example*\. It is also matched
-by \*dates.fict.example*\, if that does not appear as a separate key in the
-file.
-
-\**Note**\: Partial matching is not available for query-style lookups. It is
-also not available for any lookup items in address lists (see section
-~~SECTaddresslist).
-
-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 `$*$.') 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.
-
-Partial matching is requested by adding the string `partial-' to the front of
-the name of a single-key lookup type, for example, \partial-dbm\. When this is
-done, the subject key is first looked up unmodified; if that fails, `$*$.'
-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 `$*$.' added on the front of
-what remains.
-
-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,
-\partial3-lsearch\ specifies a minimum of three non-$*$ components in the
-modified keys. Omitting the number is equivalent to `partial2-'. If the subject
-key is \*2250.dates.fict.example*\ then the following keys are looked up when
-the minimum number of non-$*$ components is two:
-.display asis
-2250.dates.fict.example
-*.2250.dates.fict.example
-*.dates.fict.example
-*.fict.example
-.endd
-As soon as one key in the sequence is successfully looked up, the lookup
-finishes.
-
-.index lookup||partial matching, changing prefix
-.index prefix||for partial matching
-The use of `$*$.' 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 `partial'. For example:
-.display asis
-domains = partial(.)lsearch;/some/file
-.endd
-In this example, if the domain is \*a.b.c*\, the sequence of lookups is
-\"a.b.c"\, \".a.b.c"\, and \".b.c"\ (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:
-.display asis
-domains = partial1()cdb;/some/file
-.endd
-For this example, if the domain is \*a.b.c*\, the sequence of lookups is
-\"a.b.c"\, \"b.c"\, and \"c"\.
-
-If `partial0' 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:
-.numberpars $.
-If the prefix has zero length, the whole lookup fails.
-.nextp
-If the prefix has length 1, a lookup for just the prefix is done. For
-example, the final lookup for `partial0(.)' is for \"."\ alone.
-.nextp
-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 `$*$' on its own.
-.nextp
-Otherwise, the whole prefix is looked up.
-.endp
-
-If the search type ends in `$*$' or `$*$@@' (see section
-~~SECTdefaultvaluelookups above), the search for an ultimate default that this
-implies happens after all partial lookups have failed. If `partial0' is
-specified, adding `$*$' to the search type has no effect with the default
-prefix, because the `$*$' key is already included in the sequence of partial
-lookups. However, there might be a use for lookup types such as
-`partial0(.)lsearch$*$'.
-
-The use of `$*$' 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 \"*fict.example"\
-in a database file is useless, because the asterisk in a partial matching
-subject key is always followed by a dot.
-
-
-
-.section Lookup caching
-.index lookup||caching
-.index caching||lookup data
-.em
-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 caching facility.
-
-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 \lookup@_open@_max\ option.
-
-The single-key lookup files are closed and the lookup caches are flushed at
-strategic points during delivery -- for example, after all routing is complete.
-.nem
-
-
-.section Quoting lookup data
-.index lookup||quoting
-.index quoting||in lookups
-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
-.display asis
-[name=$local_part]
-.endd
-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:
-.display asis
-[name="$local_part"]
-.endd
-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:
-.display
-@$@{quote@_<<lookup-type>>:<<string>>@}
-.endd
-For example, the safest way to write the NIS+ query is
-.display asis
-[name="${quote_nisplus:$local_part}"]
-.endd
-See chapter ~~CHAPexpand for full coverage of string expansions. The quote
-operator can be used for all lookup types, but has no effect for single-key
-lookups, since no quoting is ever needed in their key strings.
-
-
-
-.section More about dnsdb
-.rset SECTdnsdb "~~chapter.~~section"
-.index dnsdb lookup
-.index lookup||dnsdb
-.index DNS||as a lookup type
-The \%dnsdb%\ 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:
-.display asis
-${lookup dnsdb{mx=a.b.example}{$value}fail}
-.endd
-The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and,
-when Exim is compiled with IPv6 support, AAAA (and A6 if that is also
-configured). If no type is given, TXT is assumed. When the type is PTR,
-.em
-the data can be an IP address, written as normal; inversion and the addition of
-\in-addr.arpa\ or \ip6.arpa\ happens automatically. For example:
-.display asis
-${lookup dnsdb{ptr=192.168.4.5}{$value}fail}
-.endd
-If the data for a PTR record is not a syntactically valid IP address, it is not
-altered and nothing is added.
-
-For any record type, if multiple records are found (or, for A6 lookups, if a
-single record leads to multiple addresses), 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:
-.display asis
-${lookup dnsdb{>: a=host1.example}}
-.endd
-It is permitted to specify a space as the separator character. Further
-whitespace is ignored.
-
-.index SRV record||in \%dnsdb%\ lookup
-For SRV records, the priority, weight, port, and host name are returned for
-each record, separated by spaces.
-
-.index MX record||in \%dnsdb%\ lookup
-For MX records, both the preference value and the host name are returned for
-each record, separated by a space. However, if you want only host names, you
-can use the pseudo-type MXH:
-.display asis
-${lookup dnsdb{mxh=a.b.example}}
-.endd
-In this case, the preference values are omitted.
-
-.index name server||for enclosing domain
-Another pseudo-type is ZNS (for `zone NS'). 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:
-.display asis
-${lookup dnsdb{zns=xxx.quercite.com}}
-${lookup dnsdb{zns=xxx.edu}}
-.endd
-Assuming that in each case there are no NS records for the full domain name,
-the first returns the name servers for \quercite.com\, and the second returns
-the name servers for \edu\.
-
-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 \com\ or \co.uk\ are not going to be on such
-a list.
-
-.nem
-
-.em
-.section Multiple dnsdb lookups
-In the previous section, \%dnsdb%\ lookups for a single domain are described.
-However, you can specify a list of domains or IP addresses in a single
-\%dnsdb%\ lookup. The list is specified in the normal Exim way, with colon as
-the default separator, but with the ability to change this. For example:
-.display asis
-${lookup dnsdb{one.domain.com:two.domain.com}}
-${lookup dnsdb{a=one.host.com:two.host.com}}
-${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}}
-.endd
-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.
-
-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.
-
-The \%dnsdb%\ 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
-an optional keyword followed by a comma that may appear before the record
-type. The possible keywords are `defer@_strict', `defer@_never', and
-`defer@_lax'. With `strict' behaviour, any temporary DNS error causes the
-whole lookup to defer. With `never' behaviour, a temporary DNS error is
-ignored, and the behaviour is as if the DNS lookup failed to find anything.
-With `lax' 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 `lax', so the following lookups are equivalent:
-.display asis
-${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}}
-${lookup dnsdb{a=one.host.com:two.host.com}}
-.endd
-Thus, in the default case, as long as at least one of the DNS lookups
-yields some data, the lookup succeeds.
-.nem
-
-
-.section More about LDAP
-.rset SECTldap "~~chapter.~~section"
-.index LDAP lookup
-.index lookup||LDAP
-.index Solaris||LDAP
-The original LDAP implementation came from the University of Michigan; this has
-become `Open LDAP', 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 \(Local/Makefile)\:
-.display asis
-LDAP_LIB_TYPE=UMICHIGAN
-LDAP_LIB_TYPE=OPENLDAP1
-LDAP_LIB_TYPE=OPENLDAP2
-LDAP_LIB_TYPE=NETSCAPE
-LDAP_LIB_TYPE=SOLARIS
-.endd
-If \\LDAP@_LIB@_TYPE\\ is not set, Exim assumes \"OPENLDAP1"\, which has the
-same interface as the University of Michigan version.
-
-There are three LDAP lookup types in Exim. These behave slightly differently in
-the way they handle the results of a query:
-.numberpars $.
-\%ldap%\ requires the result to contain just one entry; if there are more, it
-gives an error.
-.nextp
-\%ldapdn%\ also requires the result to contain just one entry, but it is the
-Distinguished Name that is returned rather than any attribute values.
-.nextp
-\%ldapm%\ permits the result to contain more than one entry; the attributes from
-all of them are returned.
-.endp
-
-For \%ldap%\ and \%ldapm%\, 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.
-
-.section Format of LDAP queries
-.rset SECTforldaque "~~chapter.~~section"
-.index LDAP||query format
-An LDAP query takes the form of a URL as defined in RFC 2255. For example, in
-the configuration of a \%redirect%\ router one might have this setting:
-.display asis
-data = ${lookup ldap \
- {ldap:///cn=$local_part,o=University%20of%20Cambridge,\
- c=UK?mailbox?base?}}
-.endd
-.index LDAP||with TLS
-The URL may begin with \"ldap"\ or \"ldaps"\ if your LDAP library supports
-secure (encrypted) LDAP connections. The second of these ensures that an
-encrypted TLS connection is used.
-
-.section LDAP quoting
-.index LDAP||quoting
-Two levels of quoting are required in LDAP queries, the first for LDAP itself
-and the second because the LDAP query is represented as a URL. Furthermore,
-within an LDAP query, two different kinds of quoting are required. For this
-reason, there are two different LDAP-specific quoting operators.
-
-The \quote@_ldap\ operator is designed for use on strings that are part of
-filter specifications. Conceptually, it first does the following conversions on
-the string:
-.display asis
-* => \2A
-( => \28
-) => \29
-\ => \5C
-.endd
-in accordance with RFC 2254. The resulting string is then quoted according
-to the rules for URLs, that is, all characters except
-.display asis
-! $ ' - . _ ( ) * +
-.endd
-are converted to their hex values, preceded by a percent sign. For example:
-.display asis
-${quote_ldap: a(bc)*, a<yz>; }
-.endd
-yields
-.display asis
-%20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20
-.endd
-Removing the URL quoting, this is (with a leading and a trailing space):
-.display asis
-a\28bc\29\2A, a<yz>;
-.endd
-
-The \quote@_ldap@_dn\ 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:
-.display asis
-, + " \ < > ;
-.endd
-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:
-.display asis
-${quote_ldap_dn: a(bc)*, a<yz>; }
-.endd
-yields
-.display asis
-%5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20
-.endd
-Removing the URL quoting, this is (with a trailing space):
-.display asis
-\ a(bc)*\, a\<yz\>\;\
-.endd
-There are some further comments about quoting in the section on LDAP
-authentication below.
-
-.section LDAP connections
-.index LDAP||connections
-The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP
-is in use, via a Unix domain socket. The example given above does not specify
-an LDAP server. A server that is reached by TCP/IP can be specified in a query
-by starting it with
-.display
-ldap://<<hostname>>:<<port>>/...
-.endd
-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 \ldap@_default@_servers\ 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.
-
-For each server name in the list, a port number can be given. The standard way
-of specifing a host and port is to use a colon separator (RFC 1738). Because
-\ldap@_default@_servers\ is a colon-separated list, such colons have to be
-doubled. For example
-.display asis
-ldap_default_servers = ldap1.example.com::145:ldap2.example.com
-.endd
-If \ldap@_default@_servers\ is unset, a URL with no server name is passed
-to the LDAP library with no server name, and the library's default (normally
-the local host) is used.
-
-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
-\"ldapi"\ instead of \"ldap"\ in LDAP queries. What follows here applies only
-to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is
-not available.
-
-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 \ldap@_default@_servers\, or inline in
-the query. In the former case, you can have settings such as
-.display asis
-ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain
-.endd
-When the pathname is given in the query, you have to escape the slashes as
-\"%2F"\ to fit in with the LDAP URL syntax. For example:
-.display asis
-${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=...
-.endd
-When Exim processes an LDAP lookup and finds that the `hostname' is really
-a pathname, it uses the Unix domain socket code, even if the query actually
-specifies \"ldap"\ or \"ldaps"\. In particular, no encryption is used for a
-socket connection. This behaviour means that you can use a setting of
-\ldap@_default@_servers\ such as in the example above with traditional \"ldap"\
-or \"ldaps"\ 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.
-
-If an explicit \"ldapi"\ type is given in a query when a host name is
-specified, an error is diagnosed. However, if there are more items in
-\ldap@_default@_servers\, they are tried. In other words:
-.numberpars $.
-Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain
-interface.
-.nextp
-Using \"ldapi"\ with a host name causes an error.
-.endp
-
-Using \"ldapi"\ with no host or path in the query, and no setting of
-\ldap@_default@_servers\, does whatever the library does by default.
-
-
-.section LDAP authentication and control information
-.index LDAP||authentication
-The LDAP URL syntax provides no way of passing authentication and other control
-information to the server. To make this possible, the URL in an LDAP query may
-be preceded by any number of `<<name>>=<<value>>' 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:
-.display
-DEREFERENCE $rm{set the dereferencing parameter}
-.newline
-.em
-NETTIME $rm{set a timeout for a network operation}
-.nem
-.newline
-USER $rm{set the DN, for authenticating the LDAP bind}
-PASS $rm{set the password, likewise}
-SIZE $rm{set the limit for the number of entries returned}
-TIME $rm{set the maximum waiting time for a query}
-.endd
-The value of the \\DEREFERENCE\\ parameter must be one of the words `never',
-`searching', `finding', or `always'.
-
-.em
-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
-\*ldap@_result()*\ 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 `no timeout' for
-Netscape SDK; for OpenLDAP no action is taken.
-
-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.
-.nem
-
-Here is an example of an LDAP query in an Exim lookup that uses some of these
-values. This is a single line, folded for ease of reading:
-.display asis
-.indent 0
-${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}
-.endd
-The encoding of spaces as %20 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 `hide' to prevent non-admin
-users from using the \-bP-\ option to see their values.
-
-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.
-
-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:
-.numberpars $.
-It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\
-DNs as with DNs inside actual queries.
-.nextp
-It permits spaces inside \\USER=\\ DNs.
-.endp
-For example, a setting such as
-.display asis
-USER=cn=${quote_ldap_dn:$1}
-.endd
-should work even if \$1$\ contains spaces.
-
-Expanded data for the \\PASS=\\ value should be quoted using the \quote\
-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:
-.display asis
-PASS=${quote:$3}
-.endd
-
-The LDAP authentication mechanism can be used to check passwords as part of
-SMTP authentication. See the \ldapauth\ expansion string condition in chapter
-~~CHAPexpand.
-
-
-.section Format of data returned by LDAP
-.index LDAP||returned data formats
-The \%ldapdn%\ lookup type returns the Distinguished Name from a single entry as
-a sequence of values, for example
-.display asis
-cn=manager, o=University of Cambridge, c=UK
-.endd
-
-The \%ldap%\ lookup type generates an error if more than one entry matches the
-search filter, whereas \%ldapm%\ 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 \%ldap%\ and \%ldapm%\, but in the former case
-you know that whatever values are returned all came from a single entry in the
-directory.
-
-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.
-
-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.
-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's attributes.
-
-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
-\attr1\ has two values, whereas \attr2\ has only one value:
-.display asis
-ldap:///o=base?attr1?sub?(uid=fred)
-value1.1, value1.2
-
-ldap:///o=base?attr2?sub?(uid=fred)
-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"
-.endd
-The \extract\ operator in string expansions can be used to pick out individual
-fields from data that consists of $it{key}=$it{value} pairs. You can make use
-of Exim's \-be-\ option to run expansion tests and thereby check the results of
-LDAP lookups.
-
-
-
-.section More about NIS+
-.rset SECTnisplus "~~chapter.~~section"
-.index NIS@+ lookup type
-.index lookup||NIS+
-NIS+ queries consist of a NIS+ \*indexed name*\ 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 \*field-name=field-value*\ pairs, separated by spaces. Empty values and
-values containing spaces are quoted. For example, the query
-.display asis
-[name=mg1456],passwd.org_dir
-.endd
-might return the string
-.display asis
-name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre"
-home=/home/mg1456 shell=/bin/bash shadow=""
-.endd
-(split over two lines here to fit on the page), whereas
-.display asis
-[name=mg1456],passwd.org_dir:gcos
-.endd
-would just return
-.display asis
-Martin Guerre
-.endd
-with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry
-for the given indexed key. The effect of the \quote@_nisplus\ expansion
-operator is to double any quote characters within the text.
-
-
-.section More about MySQL, PostgreSQL, Oracle, and Interbase
-.rset SECTsql "~~chapter.~~section"
-.index MySQL||lookup type
-.index PostgreSQL lookup type
-.index lookup||MySQL
-.index lookup||PostgreSQL
-.index Oracle||lookup type
-.index lookup||Oracle
-.index Interbase lookup type
-.index lookup||Interbase
-If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the
-\mysql@_servers\, \pgsql@_servers\, \oracle@_servers\, or \ibase@_servers\
-option (as appropriate) must be set to a colon-separated list of server
-information. 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 `service name', and the database name field is
-not used and should be empty. For example:
-.display asis
-hide oracle_servers = oracle.plc.example//ph10/abcdwxyz
-.endd
-Because password data is sensitive, you should always precede the setting with
-`hide', to prevent non-admin users from obtaining the setting via the \-bP-\
-option. Here is an example where two MySQL servers are listed:
-.display asis
-hide mysql_servers = localhost/users/root/secret:\
- otherhost/users/root/othersecret
-.endd
-For MySQL and PostgreSQL, a host may be specified as <<name>>:<<port>> 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
-and a query succeeds. Queries for these databases are SQL statements, so an
-example might be
-.display asis
-.indent 0
-${lookup mysql{select mailbox from users where id='ph10'}{$value}fail}
-.endd
-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
-.display asis
-.indent 0
-${lookup pgsql{select home,name from users where id='ph10'}{$value}}
-.endd
-might be
-.display asis
-home=/home/ph10 name="Philip Hazel"
-.endd
-Values containing spaces and empty values 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:
-.display asis
-Philip Hazel
-.endd
-If the result of the query yields more than one row, it is all concatenated,
-with a newline between the data for each row.
-
-The \quote@_mysql\, \quote@_pgsql\, and \quote@_oracle\ 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. The \quote@_pgsql\ expansion operator, in
-addition, escapes the percent and underscore characters. This cannot be done
-for MySQL because these escapes are not recognized in contexts where these
-characters are not special.
-
-
-.section Special MySQL features
-For MySQL, an empty host name or the use of `localhost' in \mysql@_servers\
-causes a connection to the server on the local host by means of a Unix domain
-socket. An alternate socket can be specified in parentheses. The full syntax of
-each item in \mysql@_servers\ is:
-.display
-<<hostname>>@:@:<<port>>(<<socket name>>)/<<database>>/<<user>>/<<password>>
-.endd
-Any of the three 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 `localhost'.
-
-No database need be supplied -- but if it is absent here, it must be given in
-the queries.
-
-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.
-.em
-\**Warning**\: 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.
-.nem
-
-
-.section Special PostgreSQL features
-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:
-.display asis
-hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ...
-.endd
-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't
-visually confused with the delimiters for the other server parameters.
-
-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.
-
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter Domain, host, address, and local part lists
-.set runningfoot "domain, host, and address lists"
-.rset CHAPdomhosaddlists "~~chapter"
-.index list||of domains, hosts, etc.
-A number of Exim configuration options contain lists of domains, hosts,
-email addresses, or local parts. For example, the \hold@_domains\ option
-contains a list of domains whose delivery is currently suspended. These lists
-are also used as data in ACL statements (see chapter ~~CHAPACL).
-
-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.
-
-
-.section Expansion of lists
-.index expansion||of lists
-.em
-Each list is expanded as a single string before it is used. 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 ~~SECTlistconstruct and
-~~SECTempitelis for details of the list syntax; the second of these discusses
-the way you specify empty list items.
-.nem
-
-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.
-
-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 \"@\N"\ expansion feature to indicate that the contents of the regular
-expression should not be expanded. For example, in an ACL you might have:
-.display asis
-deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N :
- ${lookup{$domain}lsearch{/badsenders/bydomain}}
-.endd
-The first item is a regular expression that is protected from expansion by
-\"@\N"\, whereas the second uses the expansion to obtain a list of unwanted
-senders based on the receiving domain.
-
-
-
-.section Negated items in lists
-.index list||negation
-.index negation in lists
-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:
-
-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
-.display asis
-domainlist relay_domains = !a.b.c : *.b.c
-.endd
-matches any domain ending in \*.b.c*\ except for \*a.b.c*\. Domains that match
-neither \*a.b.c*\ nor \*@*.b.c*\ do not match, because the last item in the
-list is positive. However, if the setting were
-.display asis
-domainlist relay_domains = !a.b.c
-.endd
-then all domains other than \*a.b.c*\ 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 \":*"\ on the end.
-
-Another way of thinking about positive and negative items in lists is to read
-the connector as `or' after a positive item and as `and' after a negative
-item.
-
-
-.section File names in lists
-.rset SECTfilnamlis "~~chapter.~~section"
-.index list||file name in
-If an item in a domain, host, address, or local part list is an absolute file
-name (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
-file names 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:
-.numberpars $.
-For domain and host lists, if a @# character appears anywhere in a line of the
-file, it and all following characters are ignored.
-.nextp
-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:
-.display asis
-not#comment@x.y.z # but this is a comment
-.endd
-.endp
-Putting a file name 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's behaviour changes.
-
-If a file name is preceded by an exclamation mark, the sense of any match
-within the file is inverted. For example, if
-.display asis
-hold_domains = !/etc/nohold-domains
-.endd
-and the file contains the lines
-.display asis
-!a.b.c
-*.b.c
-.endd
-then \*a.b.c*\ is in the set of domains defined by \hold@_domains\, whereas any
-domain matching \"*.b.c"\ is not.
-
-
-.section An lsearch file is not an out-of-line list
-As will be described in the sections that follow, lookups can be used in lists
-to provide indexed methods of checking list membership. There has been some
-confusion about the way \%lsearch%\ lookups work in lists. Because
-an \%lsearch%\ 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 \%lsearch%\ file are
-always fixed strings, just as for any other single-key lookup type.
-
-If you want to use a file to contain wild-card patterns that form part of a
-list, just give the file name on its own, without a search type, as described
-in the previous section.
-
-
-
-.section Named lists
-.rset SECTnamedlists "~~chapter.~~section"
-.index named lists
-.index list||named
-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 \*local@_domains*\ for all the domains that are handled
-locally on a host, using a configuration line such as
-.display asis
-domainlist local_domains = localhost:my.dom.example
-.endd
-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
-.display asis
-domains = +local_domains
-.endd
-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:
-.display asis
-dnslookup:
- driver = dnslookup
- domains = ! +local_domains
- transport = remote_smtp
- no_more
-.endd
-The four kinds of named list are created by configuration lines starting with
-the words \domainlist\, \hostlist\, \addresslist\, or \localpartlist\,
-respectively. Then there follows the name that you are defining, followed by an
-equals sign and the list itself. For example:
-.display asis
-hostlist relay_hosts = 192.168.23.0/24 : my.friend.example
-addresslist bad_senders = cdb;/etc/badsenders
-.endd
-A named list may refer to other named lists:
-.display asis
-domainlist dom1 = first.example : second.example
-domainlist dom2 = +dom1 : third.example
-domainlist dom3 = fourth.example : +dom2 : fifth.example
-.endd
-
-\**Warning**\: 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:
-.display asis
-domainlist dom1 = !a.b
-domainlist dom2 = +dom1 : *.b
-.endd
-The second list specifies `either in the \dom1\ list or \*@*.b*\'. The first
-list specifies just `not \*a.b*\', so the domain \*x.y*\ matches it. That means
-it matches the second list as well. The effect is not the same as
-.display asis
-domainlist dom2 = !a.b : *.b
-.endd
-where \*x.y*\ does not match. It's best to avoid negation altogether in
-referenced lists if you can.
-
-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
-.display asis
-domains = +local_domains
-.endd
-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.
-
-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.
-
-
-.section Named lists compared with macros
-.index list||named compared with macro
-.index macro||compared with named list
-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
-.display asis
-ALIST = host1 : host2
-auth_advertise_hosts = !ALIST
-.endd
-it probably won't do what you want, because that is exactly the same as
-.display asis
-auth_advertise_hosts = !host1 : host2
-.endd
-Notice that the second host name is not negated. However, if you use a host
-list, and write
-.display asis
-hostlist alist = host1 : host2
-auth_advertise_hosts = ! +alist
-.endd
-the negation applies to the whole list, and so that is equivalent to
-.display asis
-auth_advertise_hosts = !host1 : !host2
-.endd
-
-
-.section Named list caching
-.index list||caching of named
-.index caching||named lists
-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:
-.display asis
-domainlist special_domains = \
- ${lookup{$sender_host_address}cdb{/some/file}}
-.endd
-This provides a list of domains that depends only on the sending host'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.
-
-By appending \"@_cache"\ to \"domainlist"\ you can tell Exim to go ahead and
-cache the result anyway. For example:
-.display asis
-domainlist_cache special_domains = ${lookup{...
-.endd
-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.
-
-
-.section Domain lists
-.rset SECTdomainlist "~~chapter.~~section"
-.index domain list||patterns for
-.index list||domain list
-Domain lists contain patterns that are to be matched against a mail domain.
-The following types of item may appear in domain lists:
-.numberpars $.
-.index primary host name
-.index host||name, matched in domain list
-.index \primary@_hostname\
-.index domain list||matching primary host name
-.index @@ in a domain list
-If a pattern consists of a single @@ character, it matches the local host name,
-as set by the \primary@_hostname\ option (or defaulted). This makes it possible
-to use the same configuration file on several different hosts that differ only
-in their names.
-.nextp
-.index @@[] in a domain list
-.index domain list||matching local IP interfaces
-.index domain literal
-If a pattern consists of the string \"@@[]"\ it matches any local IP interface
-address, enclosed in square brackets, as in an email address that contains a
-domain literal.
-In today's Internet, the use of domain literals is controversial.
-.nextp
-.index @@mx@_any
-.index @@mx@_primary
-.index @@mx@_secondary
-.index domain list||matching MX pointers to local host
-If a pattern consists of the string \"@@mx@_any"\ it matches any domain that
-has an MX record pointing to the local host or to any host that is listed in
-.index \hosts@_treat@_as@_local\
-\hosts@_treat@_as@_local\. The items \"@@mx@_primary"\ and \"@@mx@_secondary"\
-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. `Primary' means an MX record with the lowest
-preference value -- there may of course be more than one of them.
-
-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 \*not*\ be expanded by adding the
-resolver's default domain. See the \qualify@_single\ and \search@_parents\
-options of the \%dnslookup%\ router for a discussion of domain widening.
-
-Sometimes you may want to ignore certain IP addresses when using one of these
-patterns. You can specify this by following the pattern with \"/ignore=<<ip
-list>>"\, where <<ip list>> is a list of IP addresses. These addresses are
-ignored when processing the pattern (compare the \ignore@_target@_hosts\ option
-on a router). For example:
-.display asis
-domains = @mx_any/ignore=127.0.0.1
-.endd
-This example matches any domain that has an MX record pointing to one of
-the local host's IP addresses other than 127.0.0.1.
-
-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.
-
-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:
-.display asis
-domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \
- an.other.domain : ...
-.endd
-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:
-.display asis
-domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \
- an.other.domain ? ...
-.endd
-
-.nextp
-.index asterisk||in domain list
-.index domain list||asterisk in
-.index domain list||matching `ends with'
-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 `$*$' 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 \"*key.ex"\ matches \*donkey.ex*\ as well as
-\*cipher.key.ex*\.
-.nextp
-.index regular expressions||in domain list
-.index domain list||matching regular expression
-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.
-References to descriptions of the syntax of regular expressions are given in
-chapter ~~CHAPregexp.
-
-\**Warning**\: Because domain lists are expanded before being processed, you
-must escape any backslash and dollar characters in the regular expression, or
-use the special \"@\N"\ sequence (see chapter ~~CHAPexpand) to specify that it
-is not to be expanded (unless you really do want to build a regular expression
-by expansion, of course).
-.nextp
-.index lookup||in domain list
-.index domain list||matching by lookup
-If a pattern starts with the name of a single-key lookup type followed by a
-semicolon (for example, `dbm;' or `lsearch;'), the remainder of the pattern
-must be a file name in a suitable format for the lookup type. For example, for
-`cdb;' it must be an absolute path:
-.display asis
-domains = cdb;/etc/mail/local_domains.cdb
-.endd
-The appropriate type of lookup is done on the file using the domain name as the
-key. In most cases, the data that is looked up 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 \domains\ option on a router
-or a \domains\ condition in an ACL statement, the data is preserved in the
-\$domain@_data$\ variable and can be referred to in other router options or
-other statements in the same ACL.
-.nextp
-Any of the single-key lookup type names may be preceded by `partial<<n>>-',
-where the <<n>> is optional, for example,
-.display asis
-domains = partial-dbm;/partial/domains
-.endd
-This causes partial matching logic to be invoked; a description of how this
-works is given in section ~~SECTpartiallookup.
-.nextp
-.index asterisk||in lookup type
-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 \$domain@_data$\
-expansion variable.
-.nextp
-If the pattern starts with the name of a query-style lookup type followed by a
-semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern
-must be an appropriate query for the lookup type, as described in chapter
-~~CHAPfdlookup. For example:
-.display asis
-hold_domains = mysql;select domain from holdlist \
- where domain = '$domain';
-.endd
-In most cases, the data that is looked up is not used (so for an SQL query, for
-example, it doesn'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
-\domains\ option on a router, the data is preserved in the \$domain@_data$\
-variable and can be referred to in other options.
-.nextp
-.index domain list||matching literal domain name
-If none of the above cases apply, a caseless textual comparison is made between
-the pattern and the domain.
-.endp
-
-Here is an example that uses several different kinds of pattern:
-.display asis
-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
-.endd
-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.
-
-
-.section Host lists
-.rset SECThostlist "~~chapter.~~section"
-.index host list||patterns in
-.index list||host list
-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.
-
-.section Special host list patterns
-.index empty item in hosts list
-.index host list||empty string in
-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.
-
-.index asterisk||in host list
-The special pattern `$*$' in a host list matches any host or no host. Neither
-the IP address nor the name is actually inspected.
-
-
-.section Host list patterns that match by IP address
-.rset SECThoslispatip "~~chapter.~~section"
-.index host list||matching IP addresses
-If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket,
-the incoming address actually appears in the IPv6 host as
-`@:@:$tt{ffff}:<<v4address>>'. 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.)
-
-The following types of pattern in a host list check the remote host by
-inspecting its IP address:
-.numberpars $.
-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
-\*getipnodebyname()*\ function when available, otherwise \*gethostbyname()*\.
-This typically causes a forward DNS lookup of the name. The result is compared
-with the IP address of the subject host.
-
-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 `defer' 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 ~~SECTbehipnot below.
-
-.nextp
-.index @@ in a host list
-If the pattern is `@@', the primary host name is substituted and used as a
-domain name, as just described.
-.nextp
-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 `dotted-quad' 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.
-.nextp
-.index @@[] in a host list
-If the pattern is `@@[]', 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:
-.display asis
-accept hosts = 127.0.0.1 : 10.45.23.56
-accept hosts = @[]
-.endd
-.nextp
-If the pattern is an IP address followed by a slash and a mask length (for
-example 10.11.42.0/24), 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.
-.index CIDR notation
-The mask uses CIDR notation; it specifies the number of address bits that must
-match, starting from the most significant end of the address.
-
-\**Note**\: the mask is \*not*\ 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
-.display asis
-192.168.23.236/31
-.endd
-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.
-
-Here is another example which shows an IPv4 and an IPv6 network:
-.display asis
-recipient_unqualified_hosts = 192.168.0.0/16: \
- 3ffe::ffff::836f::::/48
-.endd
-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,
-.display asis
-recipient_unqualified_hosts = /opt/exim/unqualnets
-.endd
-could make use of a file containing
-.display asis
-172.16.0.0/12
-3ffe:ffff:836f::/48
-.endd
-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:
-.display asis
-recipient_unqualified_hosts = <; 172.16.0.0/12; \
- 3ffe:ffff:836f::/48
-.endd
-The separator is changed to semicolon by the leading `<;' at the start of the
-list.
-.endp
-
-
-.section Host list patterns for single-key lookups by host address
-.rset SECThoslispatsikey "~~chapter.~~section"
-.index host list||lookup of IP address
-When a host is to be identified by a single-key lookup of its complete IP
-address, the pattern takes this form:
-.display
-net-<<single-key-search-type>>;<<search-data>>
-.endd
-For example:
-.display asis
-hosts_lookup = net-cdb;/hosts-by-ip.db
-.endd
-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
-\%lsearch%\ files. [Colons can in fact be used in keys in \%lsearch%\ files by
-quoting the keys, but this is a facility that was added later.] The data
-returned by the lookup is not used.
-
-.index IP address||masking
-.index host list||masked IP address
-Single-key lookups can also be performed using masked IP addresses, using
-patterns of this form:
-.display
-net<<number>>-<<single-key-search-type>>;<<search-data>>
-.endd
-For example:
-.display asis
-net24-dbm;/networks.db
-.endd
-The IP address of the subject host is masked using <<number>> 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's IP address
-is 192.168.34.6, the key that is looked up for the above example is
-`192.168.34.0/24'. IPv6 addresses are converted to a text value using lower
-case letters and dots as separators instead of the more usual colon, because
-colon is the key terminator in \%lsearch%\ files. Full, unabbreviated IPv6
-addresses are always used.
-
-\**Warning**\: Specifing \net32@-\ (for an IPv4 address) or \net128@-\ (for an
-IPv6 address) is not the same as specifing just \net@-\ 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.
-
-
-.section Host list patterns that match by host name
-.rset SECThoslispatnam "~~chapter.~~section"
-.index host||lookup failures
-.index unknown host name
-.index host list||matching host name
-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 the section ~~SECThoslispatip above.)
-
-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.
-
-Because of the problems of determining host names from IP addresses, matching
-against host names is not as common as matching against IP addresses.
-
-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 (\*gethostbyaddr()*\ or
-\*getipnodebyaddr()*\ if available) is tried. The order in which these lookups
-are done can be changed by setting the \host@_lookup@_order\ option.
-
-There are some options that control what happens if a host name cannot be
-found. These are described in section ~~SECTbehipnot below.
-
-
-.index host||alias for
-.index alias for host
-As a result of aliasing, hosts may have more than one name. When processing any
-of the following types of pattern, all the host's names are checked:
-.numberpars $.
-.index asterisk||in host list
-If a pattern starts with `$*$' the remainder of the item must match the end of
-the host name. For example, \"*.b.c"\ matches all hosts whose names end in
-\*.b.c*\. This special simple form is provided because this is a very common
-requirement. Other kinds of wildcarding require the use of a regular
-expression.
-.nextp
-.index regular expressions||in host list
-.index host list||regular expression in
-If the item starts with `@^' it is taken to be a regular expression which is
-matched against the host name. For example,
-.display asis
-^(a|b)\.c\.d$
-.endd
-is a regular expression that matches either of the two hosts \*a.c.d*\ or
-\*b.c.d*\. 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 \"@\N"\ to mark that
-part of the string as non-expandable. For example:
-.display asis
-sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : ....
-.endd
-\**Warning**\: If you want to match a complete host name, you must include the
-\"@$"\ 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.
-.endp
-
-
-.section Behaviour when an IP address or name cannot be found
-.rset SECTbehipnot "~~chapter.~~section"
-.index host||lookup failures
-While processing a host list, Exim may need to look up an IP address from a
-name (see section ~~SECThoslispatip), or it may need to look up a host name
-from an IP address (see section ~~SECThoslispatnam). In either case, the
-behaviour when it fails to find the information it is seeking is the same.
-
-.index \"+include@_unknown"\
-.index \"+ignore@_unknown"\
-By default, Exim behaves as if the host does not match the list. This may not
-always be what you want to happen. To change Exim's behaviour, the special
-items \"+include@_unknown"\ or \"+ignore@_unknown"\ may appear in the list (at
-top level -- they are not recognized in an indirected file).
-.numberpars $.
-If any item that follows \"+include@_unknown"\ requires information that
-cannot found, Exim behaves as if the host does match the list. For example,
-.display asis
-host_reject_connection = +include_unknown:*.enemy.ex
-.endd
-rejects connections from any host whose name matches \"*.enemy.ex"\, and also
-any hosts whose name it cannot find.
-.nextp
-If any item that follows \"+ignore@_unknown"\ requires information that cannot
-be found, Exim ignores that item and proceeds to the rest of the list. For
-example:
-.display asis
-accept hosts = +ignore_unknown : friend.example : \
- 192.168.4.5
-.endd
-accepts from any host whose name is \*friend.example*\ and from 192.168.4.5,
-whether or not its host name can be found. Without \"+ignore@_unknown"\, if no
-name can be found for 192.168.4.5, it is rejected.
-.endp
-Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same
-list. The effect of each one lasts until the next, or until the end of the
-list.
-
-\**Note**\: This section applies to permanent lookup failures. It does \*not*\
-apply to temporary DNS errors. They always cause a defer action.
-
-
-.section Host list patterns for single-key lookups by host name
-.rset SECThoslispatnamsk "~~chapter.~~section"
-.index host||lookup failures
-.index unknown host name
-.index host list||matching host name
-If a pattern is of the form
-.display
-<<single-key-search-type>>;<<search-data>>
-.endd
-for example
-.display asis
-dbm;/host/accept/list
-.endd
-a single-key lookup is performend, 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.
-
-\**Reminder**\: With this kind of pattern, you must have host $it{names} 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 `net-' (see section
-~~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.
-
-
-.section Host list patterns for query-style lookups
-If a pattern is of the form
-.display
-<<query-style-search-type>>;<<query>>
-.endd
-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 \$sender@_host@_address$\ and
-\$sender@_host@_name$\ can be used in the query. For example:
-.display asis
-hosts_lookup = pgsql;\
- select ip from hostlist where ip='$sender_host_address'
-.endd
-The value of \$sender@_host@_address$\ for an IPv6 address contains colons. You
-can use the \sg\ expansion item to change this if you need to. If you want to
-use masked IP addresses in database queries, you can use the \mask\ expansion
-operator.
-
-If the query contains a reference to \$sender@_host@_name$\, Exim automatically
-looks up the host name if has not already done so. (See section
-~~SECThoslispatnam for comments on finding host names.)
-
-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
-\"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is
-still recognized for query-style lookups, but its presence or absence has no
-effect. (Of course, for single-key lookups, \"net-"\ $it{is} important.
-See section ~~SECThoslispatsikey.)
-
-
-.section Mixing wildcarded host names and addresses in host lists
-.rset SECTmixwilhos "~~chapter.~~section"
-.index host list||mixing names and addresses in
-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:
-.display asis
-accept hosts = 10.9.8.7 : *.friend.example
-.endd
-The reason for this 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
-\accept\ statement fails for a host whose name cannot be found, even if its
-IP address is 10.9.8.7.
-
-If you really do want to do the name check first, and still recognize the IP
-address, you can rewrite the ACL like this:
-.display asis
-accept hosts = *.friend.example
-accept hosts = 10.9.8.7
-.endd
-If the first \accept\ fails, Exim goes on to try the second one. See chapter
-~~CHAPACL for details of ACLs.
-
-
-
-
-.section Address lists
-.index list||address list
-.index address list||empty item
-.index address list||patterns
-.rset SECTaddresslist "~~chapter.~~section"
-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:
-.display asis
-senders = :
-.endd
-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,
-.em
-and by a query-style lookup that succeeds when \$sender@_address$\ is empty.
-
-The following kinds of address list pattern can match any address, including
-the empty address that is characteristic of bounce message senders:
-.nem
-.numberpars $.
-.em
-As explained above, if a pattern item is empty, it matches the empty address
-(and no others).
-.nem
-.nextp
-.index regular expressions||in address list
-.index address list||regular expression in
-If (after expansion) a pattern starts with `@^', 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 \"@\N"\
-to mark that part of the string as non-expandable. For example:
-.display asis
-deny senders = \N^\d{8}.+@spamhaus.example$\N : ...
-.endd
-The \"@\N"\ sequences are removed by the expansion, so the item does start
-with `@^' by the time it is being interpreted as an address pattern.
-.nextp
-.index address list||lookup for complete address
-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:
-.display asis
-deny senders = cdb;/etc/blocked.senders : \
- mysql;select address from blocked where \
- address='${quote_mysql:$sender_address}'
-.endd
-.em
-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.
-
-.nem
-Partial matching for single-key lookups (section ~~SECTpartiallookup) cannot be
-used, and is ignored if specified, with an entry being written to the panic
-log.
-.index @*@@ with single-key lookup
-However, you can configure lookup defaults, as described in section
-~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of
-default. For example, with this lookup:
-.display asis
-accept senders = lsearch*@;/some/file
-.endd
-the file could contains lines like this:
-.display asis
-user1@domain1.example
-*@domain2.example
-.endd
-and for the sender address \*nimrod@@jaeger.example*\, the sequence of keys
-that are tried is:
-.display asis
-nimrod@jaeger.example
-*@jaeger.example
-*
-.endd
-\**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that
-would mean that every address matches, thus rendering the test useless.
-
-\**Warning 2**\: Do not confuse these two kinds of item:
-.display asis
-deny recipients = dbm*@;/some/file
-deny recipients = *@dbm;/some/file
-.endd
-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.
-.endp
-
-
-.em
-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.
-.nem
-
-.numberpars $.
-.index @@@@ with single-key lookup
-.index address list||@@@@ lookup type
-.index address list||split local part and domain
-If a pattern starts with `@@@@' followed by a single-key lookup item
-(for example, \"@@@@lsearch;/some/file"\), 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.
-
-.index asterisk||in address list
-The lookup may be a partial one, and/or one involving a search for a default
-keyed by `$*$' (see section ~~SECTdefaultvaluelookups). The local part patterns
-that are looked up can be regular expressions or begin with `$*$', or even be
-further lookups. They may also be independently negated. For example, with
-.display asis
-deny senders = @@dbm;/etc/reject-by-domain
-.endd
-the data from which the DBM file is built could contain lines like
-.display asis
-baddomain.com: !postmaster : *
-.endd
-to reject all senders except \postmaster\ from that domain.
-.index local part||starting with !
-If a local part that actually begins with an exclamation mark is required, it
-has to be specified using a regular expression. In \%lsearch%\ 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:
-.display asis
-aol.com: spammer1 : spammer2 : ^[0-9]+$ :
- spammer3 : spammer4
-.endd
-As in all colon-separated lists in Exim, a colon can be included in an item by
-doubling.
-
-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
-.display asis
-aol.com: spammer1 : spammer 2 : >*
-xyz.com: spammer3 : >*
-*: ^\d{8}$
-.endd
-in a file that was searched with \@@@@dbm$*$\, 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.
-.index loop||in lookups
-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.
-.nextp
-The @@@@<<lookup>> 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.
-.nextp
-If a pattern contains an @@ character, but is not a regular expression and does
-not begin with a lookup type as described above, 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:
-.display asis
-deny senders = *@*.spamming.site:\
- *@+hostile_domains:\
- bozo@partial-lsearch;/list/of/dodgy/sites:\
-.newline
- *@dbm;/bad/domains.db
-.endd
-.index local part||starting with !
-.index address list||local part starting with !
-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.
-.nextp
-If a pattern is not one of the above syntax forms, that is, if a
-.em
-non-empty
-.nem
-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
-\"*@@"\ preceded the pattern.
-.endp
-
-\**Warning**\: there is an important difference between the address list items
-in these two examples:
-.display asis
-senders = +my_list
-senders = *@+my_list
-.endd
-In the first one, \"my@_list"\ is a named address list, whereas in the second
-example it is a named domain list.
-
-
-
-.section Case of letters in address lists
-.rset SECTcasletadd "~~chapter.~~section"
-.index case of local parts
-.index address list||case forcing
-.index case forcing in address lists
-Domains in email addresses are always handled caselessly, but for local parts
-case may be significant on some systems (see \caseful@_local@_part\ for how
-Exim deals with this when routing addresses). However, RFC 2505 ($it{Anti-Spam
-Recommendations for SMTP MTAs}) 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.
-
-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 file names, and in any file
-that is looked up using the `@@@@' mechanism, can be in any case. However, the
-keys in files that are looked up by a search type other than \%lsearch%\ (which
-works caselessly) must be in lower case, because these lookups are not
-case-independent.
-
-.index \"+caseful"\
-To allow for the possibility of caseful address list matching, if an item in
-an address list is the string `+caseful', 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 `+caseful' has been seen.
-
-
-.section Local part lists
-.rset SECTlocparlis "~~chapter.~~section"
-.index list||local part list
-.index local part||list
-Case-sensitivity in local part lists is handled in the same way as for address
-lists, as just described. The `+caseful' item can be used if required. In a
-setting of the \local@_parts\ option in a router with \caseful@_local@_part\
-set false, the subject is lowercased and the matching is initially
-case-insensitive. In this case, `+caseful' will restore case-sensitive matching
-in the local part list, but not elsewhere in the router. If
-\caseful@_local@_part\ is set true in a router, matching in the \local@_parts\
-option is case-sensitive from the start.
-
-If a local part list is indirected to a file (see section ~~SECTfilnamlis),
-comments are handled in the same way as address lists -- 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 (\"@@"\, \"@@[]"\,
-\"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\) are not recognized.
-Refer to section ~~SECTdomainlist for details of the other available item
-types.
-
-
-
-.
-.
-.
-.
-. ============================================================================
-.chapter String expansions
-.set runningfoot "string expansions"
-.rset CHAPexpand ~~chapter
-.index expansion||of strings
-Many strings in Exim's run time configuration are expanded before use. Some of
-them are expanded every time they are used; others are expanded only once.
-
-When a string is being expanded it is copied verbatim from left to right except
-when a dollar or backslash character is encountered. A dollar specifies the
-start of a portion of the string which is interpreted and replaced as described
-below in section ~~SECTexpansionitems onwards. Backslash is used as an escape
-character, as described in the following section.
-
-
-.section Literal text in expanded strings
-.rset SECTlittext "~~chapter.~~section"
-.index expansion||including literal text
-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 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 ~~SECTstrings).
-
-.index expansion||non-expandable substrings
-A portion of the string can specified as non-expandable by placing it between
-two occurrences of \"@\N"\. This is particularly useful for protecting regular
-expressions, which often contain backslashes and dollar signs. For example:
-.display asis
-deny senders = \N^\d{8}[a-z]@some\.site\.example$\N
-.endd
-On encountering the first \"@\N"\, the expander copies subsequent characters
-without interpretation until it reaches the next \"@\N"\ or the end of the
-string.
-
-
-.section Character escape sequences in expanded strings
-.index expansion||escape sequences
-A backslash followed by one of the letters `n', `r', or `t' 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 `x' and up to two hexadecimal digits is a hexadecimal encoding.
-
-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.
-
-.section Testing string expansions
-.index expansion||testing
-.index testing||string expansion
-.index \-be-\ option
-Many expansions can be tested by calling Exim with the \-be-\ 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 \$local@_part$\ have no
-value. Nevertheless the \-be-\ option can be useful for checking out file and
-database lookups, and the use of expansion operators such as \sg\, \substr\ and
-\nhash\.
-
-Exim gives up its root privilege when it is called with the \-be-\ option, and
-instead runs under the uid and gid it was called with, to prevent users from
-using \-be-\ for reading files to which they do not have access.
-
-
-.em
-.section Forced expansion failure
-.rset SECTforexpfai "~~chapter.~~section"
-.index expansion||forced failure
-A number of expansions that are described in the following section have
-alternative `true' and `false' substrings, enclosed in curly brackets. Which
-one is used depends on some condition that is evaluated as part of the
-expansion. If, instead of a `false' substring, the word `fail' is used (not in
-curly brackets), the entire string expansion fails in a way that can be
-detected by the code that requested the expansion. This is called `forced
-expansion failure', 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.
-.nem
-
-
-.section Expansion items
-.rset SECTexpansionitems "~~chapter.~~section"
-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. \**Warning**\: Within braces,
-white space is significant.
-
-.startitems
-
-.item "@$<<variable name>>#$rm{or}#@$@{<<variable name>>@}"
-.index expansion||variables
-Substitute the contents of the named variable, for example
-.display asis
-$local_part
-${domain}
-.endd
-The second form can be used to separate the name from subsequent alphanumeric
-characters. This form (using curly brackets) is available only for variables;
-it does $it{not} apply to message headers. The names of the variables are given
-in section ~~SECTexpvar below. If the name of a non-existent variable is given,
-the expansion fails.
-
-.item "@$@{<<op>>:<<string>>@}"
-.index expansion||operators
-The string is first itself expanded, and then the operation specified by <<op>>
-is applied to it. For example,
-.display asis
-${lc:$local_part}
-.endd
-The string starts with the first character after the colon, which may be
-leading white space. A list of operators is given in section ~~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.
-
-.item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
-.index expansion||extracting substrings by key
-The key and <<string1>> are first expanded separately.
-Leading and trailing whitespace is removed from the key (but not from any of
-the strings).
-The key must not consist entirely of digits. The expanded <<string1>> must be
-of the form:
-.display
-<<key1>> = <<value1>> <<key2>> = <<value2>> ...
-.endd
-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 ~~SECTstrings. The expanded <<string1>> is searched for
-the value that corresponds to the key. The search is case-insensitive. If the
-key is found, <<string2>> is expanded, and replaces the whole item; otherwise
-<<string3>> is used. During the expansion of <<string2>> the variable \$value$\
-contains the value that has been extracted. Afterwards, it is restored to any
-previous value it might have had.
-
-If @{<<string3>>@} is omitted, the item is replaced by an empty string if the
-key is not found. If @{<<string2>>@} is also omitted, the value that was
-extracted is used. Thus, for example, these two expansions are identical, and
-yield `2001':
-.display
-@$@{extract@{gid@}{uid=1984 gid=2001@}@}
-@$@{extract@{gid@}{uid=1984 gid=2001@}@{@$value@}@}
-.endd
-Instead of @{<<string3>>@} the word `fail' (not in curly brackets) can appear,
-for example:
-.display
-@$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @}
-.endd
-This forces an expansion failure (see section ~~SECTforexpfai); @{<<string2>>@}
-must be present for `fail' to be recognized.
-
-
-.item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
-.index expansion||extracting substrings by number
-The <<number>> argument must consist entirely of decimal digits,
-apart from leading and trailing whitespace, which is ignored.
-This is what distinguishes this form of \extract\ from the previous kind. It
-behaves in the same way, except that, instead of extracting a named field, it
-extracts from <<string1>> the field whose number is given as the first
-argument. You can use \$value$\ in <<string2>> or \"fail"\ instead of
-<<string3>> as before.
-
-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 <<string3>>, or the empty string if <<string3>> is not provided.
-For example:
-.display asis
-${extract{2}{:}{x:42:99:& Mailer::/bin/
projects / exim.git / commitdiff