author Nigel Metheringham Thu, 17 Jan 2008 13:14:07 +0000 (13:14 +0000) committer Nigel Metheringham Thu, 17 Jan 2008 13:14:07 +0000 (13:14 +0000)
 doc/doc-src/ABOUT patch | blob | blame | history doc/doc-src/filter.src [deleted file] patch | blob | blame | history doc/doc-src/spec.src [deleted file] patch | blob | blame | history

index 9907901..35b77f2 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-src/ABOUT,v 1.2 2005/06/16 10:32:31 ph10 Exp$
+$Cambridge: exim/doc/doc-src/ABOUT,v 1.3 2008/01/17 13:14:07 nm4 Exp$

CVS directory exim/exim-doc/doc-src
-----------------------------------
@@ -11,4 +11,7 @@ Subsequent documentation releases operate using DocBook input, so these files
are now historical relics. The FAQ source is still (June 2005) current, but may
be superseded in due course.

+The filter and spec source files have now been removed from here to
+prevent further confusion.
+
End
diff --git a/doc/doc-src/filter.src b/doc/doc-src/filter.src
deleted file mode 100644 (file)
index 8688721..0000000
+++ /dev/null
@@ -1,1735 +0,0 @@
-. $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).
-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.
-
-
-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 diff --git a/doc/doc-src/spec.src b/doc/doc-src/spec.src deleted file mode 100644 (file) index 0daf090..0000000 +++ /dev/null @@ -1,30675 +0,0 @@ -. 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{ "pushg0f54" -.flag sm{ "pushg0f53" -.flag smi{ "pushg0f56" -.flag as{ "pushg0f52" -.flag ab{ "pushg0f51" -.flag cb{ "pushg0f55" -. -.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 ~~inssectrm{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 -crm{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]eit{~~rhs} -.endfoot -.fi - - - - -. -. -. -. -. ============================================================================ -.chapter Introduction -.set runningfoot "introduction" - -.if ~~sys.fancy -cbi{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
-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
-.nextp
-If the \senders\ option is set, the envelope sender address must be in the set
-.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 \-oeit{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 eit{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 -\-eit{x}-\ as synonymous with the corresponding \-oeit{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 \-oeit{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
-
-
-.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.
-
-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
-.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
-.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
-.index case of local parts
-.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/bash}} -.endd -yields 42', and -.display asis -${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}}
-.endd
-yields `99'. Two successive separators mean that the field between them is
-empty (for example, the fifth field above).
-
-
-.item "@\$@{hash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}"
-.index hash function||textual
-.index expansion||textual hash
-This is a textual hashing function, and was the first to be implemented in
-early versions of Exim. In current releases, there are other hashing functions
-(numeric, MD5, and SHA-1), which are described below.
-
-The first two strings, after expansion, must be numbers. Call them <<m>> and
-<<n>>. If you are using fixed values for&nb