diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/doc-src/ABOUT | 5 | ||||
| -rw-r--r-- | doc/doc-src/filter.src | 1735 | ||||
| -rw-r--r-- | doc/doc-src/spec.src | 30675 |
3 files changed, 4 insertions, 32411 deletions
diff --git a/doc/doc-src/ABOUT b/doc/doc-src/ABOUT index 990790101..35b77f247 100644 --- a/doc/doc-src/ABOUT +++ b/doc/doc-src/ABOUT @@ -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 index 8688721af..000000000 --- a/doc/doc-src/filter.src +++ /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). -An \"In-Reply-To:"\ header is automatically included in the created message, -giving a reference to the message identification of the incoming message. - -If \"return message"\ is specified, the incoming message that caused the filter -file to be run is added to the end of the message, subject to a maximum size -limitation. - -If a log file is specified, a line is added to it for each message sent. - -If a \"once"\ file is specified, it is used to hold a database for remembering -who has received a message, and no more than one message is ever sent to any -particular address, unless \"once@_repeat"\ is set. This specifies a time -interval after which another copy of the message is sent. The interval is -specified as a sequence of numbers, each followed by the initial letter of one -of `seconds', `minutes', `hours', `days', or `weeks'. For example, -.display asis -once_repeat 5d4h -.endd -causes a new message to be sent if 5 days and 4 hours have elapsed since the -last one was sent. There must be no white space in a time interval. - -Commonly, the file name specified for \"once"\ is used as the base name for -direct-access (DBM) file operations. There are a number of different DBM -libraries in existence. Some operating systems provide one as a default, but -even in this case a different one may have been used when building Exim. With -some DBM libraries, specifying \"once"\ results in two files being created, -with the suffixes \".dir"\ and \".pag"\ being added to the given name. With -some others a single file with the suffix \".db"\ is used, or the name is used -unchanged. - -Using a DBM file for implementing the \"once"\ feature means that the file -grows as large as necessary. This is not usually a problem, but some system -administrators want to put a limit on it. The facility can be configured not to -use a DBM file, but instead, to use a regular file with a maximum size. The -data in such a file is searched sequentially, and if the file fills up, the -oldest entry is deleted to make way for a new one. This means that some -correspondents may receive a second copy of the message after an unpredictable -interval. Consult your local information to see if your system is configured -this way. - -More than one \"mail"\ or \"vacation"\ command may be obeyed in a single filter -run; they are all honoured, even when they are to the same recipient. - - -.section Logging commands -.rset SECTlog "~~chapter.~~section" -A log can be kept of actions taken by a filter file. This facility is normally -available in conventional configurations, but there are some situations where -it might not be. Also, the system administrator may choose to disable it. Check -your local information if in doubt. - -Logging takes place while the filter file is being interpreted. It does not -queue up for later like the delivery commands. The reason for this is so that a -log file need be opened only once for several write operations. There are two -commands, neither of which constitutes a significant delivery. The first -defines a file to which logging output is subsequently written: -.display - logfile <<file name>> -e.g. logfile @$home/filter.log -.endd -The file name must be fully qualified. You can use \$home$\, as in this -example, to refer to your home directory. The file name may optionally be -followed by a mode for the file, which is used if the file has to be created. -For example, -.display - logfile @$home/filter.log 0644 -.endd -The number is interpreted as octal, even if it does not begin with a zero. -The default for the mode is 600. It is suggested that the \"logfile"\ command -normally appear as the first command in a filter file. Once \"logfile"\ has -been obeyed, the \"logwrite"\ command can be used to write to the log file: -.display - logwrite "<<some text string>>" -e.g. logwrite "@$tod@_log @$message@_id processed" -.endd -It is possible to have more than one \"logfile"\ command, to specify writing to -different log files in different circumstances. Writing takes place at the end -of the file, and a newline character is added to the end of each string if -there isn't one already there. Newlines can be put in the middle of the string -by using the `@\n' escape sequence. Lines from simultaneous deliveries may get -interleaved in the file, as there is no interlocking, so you should plan your -logging with this in mind. However, data should not get lost. - - -.section The finish command -.rset SECTfinish "~~chapter.~~section" -The command \"finish"\, which has no arguments, causes Exim to stop -interpreting the filter file. This is not a significant action unless preceded -by \"seen"\. A filter file containing only \"seen finish"\ is a black hole. - -.section The testprint command -.rset SECTtestprint "~~chapter.~~section" -It is sometimes helpful to be able to print out the values of variables when -testing filter files. The command -.display - testprint <<text>> -e.g. testprint "home=@$home reply@_address=@$reply@_address" -.endd -does nothing when mail is being delivered. However, when the filtering code is -being tested by means of the \-bf-\ option (see section ~~SECTtesting above), -the value of the string is written to the standard output. - -.section The fail command -.rset SECTfail "~~chapter.~~section" -When Exim's filtering facilities are being used as a system filter, the -\"fail"\ command is available, to force delivery failure. Because this command -is normally usable only by the system administrator, and not enabled for use by -ordinary users, it is described in more detail in the main Exim specification -rather than in this document. - -.section The freeze command -.rset SECTfreeze "~~chapter.~~section" -When Exim's filtering facilities are being used as a system filter, the -\"freeze"\ command is available, to freeze a message on the queue. Because this -command is normally usable only by the system administrator, and not enabled -for use by ordinary users, it is described in more detail in the main Exim -specification rather than in this document. - - -.section The headers command -.rset SECTheaders "~~chapter.~~section" -The \"headers"\ command can be used to change the target character set that is -used when translating the contents of encoded header lines for insertion by the -\"@$header@_"\ mechanism (see section ~~SECTheadervariables above). The default -can be set in the Exim configuration; if not specified, ISO-8859-1 is used. The -only currently supported format for the \"headers"\ command -.em -in user filters -.nem -is as in this example: -.display asis -headers charset "UTF-8" -.endd -That is, \"headers"\ is followed by the word \"charset"\ and then the name of a -character set. This particular example would be useful if you wanted to compare -the contents of a header to a UTF-8 string. - -.em -In system filter files, the \"headers"\ command can be used to add or remove -header lines from the message. These features are described in the main Exim -specification. -.nem - - - -.section Obeying commands conditionally -.rset SECTif "~~chapter.~~section" -Most of the power of filtering comes from the ability to test conditions and -obey different commands depending on the outcome. The \"if"\ command is used to -specify conditional execution, and its general form is -.display -if <<condition>> -then <<commands>> -elif <<condition>> -then <<commands>> -else <<commands>> -endif -.endd -There may be any number of \"elif"\ and \"then"\ sections (including none) and -the \"else"\ section is also optional. Any number of commands, including nested -\"if"\ commands, may appear in any of the <<commands>> sections. - -Conditions can be combined by using the words \"and"\ and \"or"\, and round -brackets (parentheses) can be used to specify how several conditions are to -combine. Without brackets, \"and"\ is more binding than \"or"\. -For example, -.display asis -if - $h_subject: contains "Make money" or - $h_precedence: is "junk" or - ($h_sender: matches ^\\d{8}@ and not personal) or - $message_body contains "this is spam" -then - seen finish -endif -.endd -A condition can be preceded by \"not"\ to negate it, and there are also some -negative forms of condition that are more English-like. - - - -.section String testing conditions -There are a number of conditions that operate on text strings, using the words -`begins', `ends', `is', `contains' and `matches'. If you want to apply the same -test to more than one header line, you can easily concatenate them into a -single string for testing, as in this example: -.display asis -if "$h_to:, $h_cc:" contains me@domain.example then ... -.endd - -If a string-testing condition name is written in lower case, the testing -of letters is done without regard to case; if it is written in upper case -(for example, `CONTAINS'), the case of letters is taken into account. -.display - <<text1>> begins <<text2>> - <<text1>> does not begin <<text2>> -e.g. @$header@_from: begins "Friend@@" -.endd -A `begins' test checks for the presence of the second string at the start of -the first, both strings having been expanded. -.display - <<text1>> ends <<text2>> - <<text1>> does not end <<text2>> -e.g. @$header@_from: ends "@public.com.example" -.endd -An `ends' test checks for the presence of the second string at the end of -the first, both strings having been expanded. -.display - <<text1>> is <<text2>> - <<text1>> is not <<text2>> -e.g. @$local@_part@_suffix is "-foo" -.endd -An `is' test does an exact match between the strings, having first expanded -both strings. -.display - <<text1>> contains <<text2>> - <<text1>> does not contain <<text2>> -e.g. @$header@_subject: contains "evolution" -.endd -A `contains' test does a partial string match, having expanded both strings. -.display - <<text1>> matches <<text2>> - <<text1>> does not match <<text2>> -e.g. @$sender@_address matches "(bill|john)@@" -.endd -For a `matches' test, after expansion of both strings, the second one is -interpreted as a regular expression. Exim uses the PCRE regular expression -library, which provides regular expressions that are compatible with Perl. - -The match succeeds if the regular expression matches any part of the first -string. If you want a regular expression to match only at the start or end of -the subject string, you must encode that requirement explicitly, using the @^ -or @$ metacharacters. The above example, which is not so constrained, matches -all these addresses: -.display asis -bill@test.example -john@some.example -spoonbill@example.com -littlejohn@example.com -.endd -To match only the first two, you could use this: -.display asis -if $sender_address matches "^(bill|john)@" then ... -.endd - -Care must be taken if you need a backslash in a regular expression, because -backslashes are interpreted as escape characters both by the string expansion -code and by Exim's normal processing of strings in quotes. For example, if you -want to test the sender address for a domain ending in \".com"\ the regular -expression is -.display asis -\.com$ -.endd -The backslash and dollar sign in that expression have to be escaped when used -in a filter command, as otherwise they would be interpreted by the expansion -code. Thus what you actually write is -.display asis -if $sender_address matches \\.com\$ -.endd -An alternative way of handling this is to make use of the \"@\N"\ expansion -flag for suppressing expansion: -.display asis -if $sender_address matches \N\.com$\N -.endd -Everything between the two occurrences of \"@\N"\ is copied without change by -the string expander (and in fact you do not need the final one, because it is -at the end of the string). - -If the regular expression is given in quotes (mandatory only if it contains -white space) you have to write either -.display asis -if $sender_address matches "\\\\.com\\$" -.endd -or -.display asis -if $sender_address matches "\\N\\.com$\\N" -.endd - -If the regular expression contains bracketed sub-expressions, numeric -variable substitutions such as \$1$\ can be used in the subsequent actions -after a successful match. If the match fails, the values of the numeric -variables remain unchanged. Previous values are not restored after \"endif"\. -In other words, only one set of values is ever available. If the condition -contains several sub-conditions connected by \"and"\ or \"or"\, it is the -strings extracted from the last successful match that are available in -subsequent actions. Numeric variables from any one sub-condition are also -available for use in subsequent sub-conditions, because string expansion of a -condition occurs just before it is tested. - -.section Numeric testing conditions -The following conditions are available for performing numerical tests: -.display - <<number1>> is above <<number2>> - <<number1>> is not above <<number2>> - <<number1>> is below <<number2>> - <<number1>> is not below <<number2>> -e.g. @$message@_size is not above 10k -.endd -The <<number>> arguments must expand to strings of digits, optionally followed -by one of the letters K or M (upper case or lower case) which cause -multiplication by 1024 and 1024x1024 respectively. - -.section Testing for significant deliveries -You can use the \"delivered"\ condition to test whether or not any previously -obeyed filter commands have set up a significant delivery. For example: -.display asis -if not delivered then save mail/anomalous endif -.endd - -.section Testing for error messages -The condition \"error@_message"\ is true if the incoming message is a bounce -(mail delivery error) message. Putting the command -.display asis -if error_message then finish endif -.endd -at the head of your filter file is a useful insurance against things going -wrong in such a way that you cannot receive delivery error reports. \**Note**\: -\"error@_message"\ is a condition, not an expansion variable, and therefore is -not preceded by \@$\. - -.section Testing a list of addresses -There is a facility for looping through a list of addresses and applying a -condition to each of them. It takes the form -.display -foranyaddress <<string>> (<<condition>>) -.endd -where <<string>> is interpreted as a list of RFC 2822 addresses, as in a -typical header line, and <<condition>> is any valid filter condition or -combination of conditions. The `group' syntax that is defined for certain -header lines that contain addresses is supported. - -The parentheses surrounding the condition are mandatory, to delimit it from -possible further sub-conditions of the enclosing \"if"\ command. Within the -condition, the expansion variable \$thisaddress$\ is set to the non-comment -portion of each of the addresses in the string in turn. For example, if the -string is -.display asis -B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister) -.endd -then \$thisaddress$\ would take on the values \"bart@@sfld.example"\ and -\"lisa@@sfld.example"\ in turn. - -If there are no valid addresses in the list, the whole condition is false. If -the internal condition is true for any one address, the overall condition is -true and the loop ends. If the internal condition is false for all addresses in -the list, the overall condition is false. This example tests for the presence -of an eight-digit local part in any address in a \To:\ header: -.display asis -if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ... -.endd -When the overall condition is true, the value of \$thisaddress$\ in the -commands that follow \"then"\ is the last value it took on inside the loop. At -the end of the \"if"\ command, the value of \$thisaddress$\ is reset to what it -was before. It is best to avoid the use of multiple occurrences of -\"foranyaddress"\, nested or otherwise, in a single \"if"\ command, if the -value of \$thisaddress$\ is to be used afterwards, because it isn't always -clear what the value will be. Nested \"if"\ commands should be used instead. - -Header lines can be joined together if a check is to be applied to more than -one of them. For example: -.display asis -if foranyaddress $h_to:,$h_cc: .... -.endd -scans through the addresses in both the \To:\ and the \Cc:\ headers. - -.section Testing for personal mail -.rset SECTpersonal "~~chapter.~~section" -A common requirement is to distinguish between incoming personal mail and mail -from a mailing list, or from a robot or other automatic process (for example, a -bounce message). In particular, this test is normally required for `vacation -messages'. - -.em -The \"personal"\ condition checks that the message is not a bounce message and -that the current user's email address appears in the \"To:"\ header. It also -checks that the sender is not the current user or one of a number of common -daemons, and that there are no header lines starting \"List-"\ in the message. -Finally, it checks the content of the \"Precedence:"\ header line, if there is -one. - -You should always use the \"personal"\ condition when generating automatic -responses. -.nem -This example shows the use of \"personal"\ in a filter file that is sending out -vacation messages: -.display asis -if personal then - mail - to $reply_address -.newline -.em - subject "I am on holiday" -.nem -.newline - file $home/vacation/message - once $home/vacation/once - once_repeat 10d -endif -.endd -.em -It is tempting, when writing commands like the above, to quote the original -subject in the reply. For example: -.display asis -subject "Re: $h_subject:" -.endd -There is a danger in doing this, however. It may allow a third party to -subscribe you to an opt-in mailing list, provided that the list accepts bounce -messages as subscription confirmations. (Messages sent from filters are always -sent as bounce messages.) Well-managed lists require a non-bounce message to -confirm a subscription, so the danger is relatively small. - -If prefixes or suffixes are in use for local parts -- something which depends -on the configuration of Exim (see section ~~SECTmbox below) -- the tests for -the current user are done with the full address (including the prefix and -suffix, if any) as well as with the prefix and suffix removed. If the system is -configured to rewrite local parts of mail addresses, for example, to rewrite -`dag46' as `Dirk.Gently', the rewritten form of the address is also used in the -tests. -.nem - -.em -.section Alias addresses for the personal condition -It is quite common for people who have mail accounts on a number of different -systems to forward all their mail to one system, and in this case a check for -personal mail should test all their various mail addresses. To allow for this, -the \"personal"\ condition keyword can be followed by -.display -alias <<address>> -.endd -any number of times, for example -.display asis -if personal alias smith@else.where.example - alias jones@other.place.example -then ... -.endd -The alias addresses are treated as alternatives to the current user's email -address when testing the contents of header lines. -.nem - - -.em -.section Details of the personal condition -The basic \"personal"\ test is roughly equivalent to the following: -.display flow asis -not error_message and -$message_headers does not contain "\nList-" and -$header_auto-submitted: does not contain "auto-" and -$header_precedence: does not contain "bulk" and -$header_precedence: does not contain "list" and -$header_precedence: does not contain "junk" and -foranyaddress $header_to: - ( $thisaddress contains "$local_part@$domain" ) and -not foranyaddress $header_from: - ( - $thisaddress contains "$local_part@domain" or - $thisaddress contains "server@" or - $thisaddress contains "daemon@" or - $thisaddress contains "root@" or - $thisaddress contains "listserv@" or - $thisaddress contains "majordomo@" or - $thisaddress contains "-request@" or - $thisaddress matches "^owner-[^@]+@" - ) -.endd -The variable \$local@_part$\ contains the local part of the mail address of -the user whose filter file is being run -- it is normally your login id. The -\$domain$\ variable contains the mail domain. As explained above, if aliases -or rewriting are defined, or if prefixes or suffixes are in use, the tests for -the current user are also done with alternative addresses. -.nem - - -.section Testing delivery status -There are two conditions that are intended mainly for use in system filter -files, but which are available in users' filter files as well. The condition -\"first@_delivery"\ is true if this is the first process that is attempting to -deliver the message, and false otherwise. This indicator is not reset until the -first delivery process successfully terminates; if there is a crash or a power -failure (for example), the next delivery attempt is also a `first delivery'. - -In a user filter file \"first@_delivery"\ will be false only if -there was previously an error in the filter, or if a delivery for the user -failed owing to, for example, a quota error, or if forwarding to a remote -address was deferred for some reason. - -The condition \"manually@_thawed"\ is true only if the message was `frozen' for -some reason, and was subsequently released by the system administrator. It is -unlikely to be of use in users' filter files. - -.section Multiple personal mailboxes -.rset SECTmbox "~~chapter.~~section" -The system administrator can configure Exim so that users can set up variants -on their email addresses and handle them separately. Consult your system -administrator or local documentation to see if this facility is enabled on your -system, and if so, what the details are. - -The facility involves the use of a prefix or a suffix on an email address. For -example, all mail addressed to \lg303-<<something>>\ would be the property of -user \lg303\, who could determine how it was to be handled, depending on the -value of <<something>>. - -There are two possible ways in which this can be set up. The first possibility -is the use of multiple \(.forward)\ files. In this case, mail to \lg303-foo\, -for example, is handled by looking for a file called \.forward-foo\ in -\lg303's\ home directory. If such a file does not exist, delivery fails and the -message is returned to its sender. - -The alternative approach is to pass all messages through a single \(.forward)\ -file, which must be a filter file so that it can distinguish between the -different cases by referencing the variables \$local@_part@_prefix$\ or -\$local@_part@_suffix$\, as in the final example in section ~~SECTex below. - -It is possible to configure Exim to support both schemes at once. In this case, -a specific \.forward-foo\ file is first sought; if it is not found, the basic -\(.forward)\ file is used. - -The \"personal"\ test (see section ~~SECTpersonal) includes prefixes and -suffixes in its checking. - - -.section Ignoring delivery errors -As was explained above, filtering just sets up addresses for delivery -- no -deliveries are actually done while a filter file is active. If any of the -generated addresses subsequently suffers a delivery failure, an error message -is generated in the normal way. However, if a filter command that sets up a -delivery is preceded by the word \"noerror"\, errors for that delivery, -$it{and any deliveries consequent on it} (that is, from alias, forwarding, or -filter files it invokes) are ignored. - - -.section Examples of Exim filter commands -.rset SECTex "~~chapter.~~section" -Simple forwarding: -.display asis -# Exim filter -deliver baggins@rivendell.middle-earth.example -.endd -Vacation handling using traditional means, assuming that the \.vacation.msg\ -and other files have been set up in your home directory: -.display asis -# Exim filter -unseen pipe "/usr/ucb/vacation \"$local_part\"" -.endd -Vacation handling inside Exim, having first created a file called -\.vacation.msg\ in your home directory: -.display asis -# Exim filter -if personal then vacation endif -.endd -File some messages by subject: -.display asis -# Exim filter -if $header_subject: contains "empire" or - $header_subject: contains "foundation" -then - save $home/mail/f+e -endif -.endd -Save all non-urgent messages by weekday: -.display asis -# Exim filter -if $header_subject: does not contain "urgent" and - $tod_full matches "^(...)," -then - save $home/mail/$1 -endif -.endd -Throw away all mail from one site, except from postmaster: -.display asis -# Exim filter -if $reply_address contains "@spam.site.example" and - $reply_address does not contain "postmaster@" -then - seen finish -endif -.endd -.if ~~sgcal -.if ~~sys.leftonpage < 6ld -.newpage -.fi -.fi -Handle multiple personal mailboxes -.display asis -# Exim filter -if $local_part_suffix is "-foo" -then - save $home/mail/foo -elif $local_part_suffix is "-bar" -then - save $home/mail/bar -endif -.endd - -. End of filter diff --git a/doc/doc-src/spec.src b/doc/doc-src/spec.src deleted file mode 100644 index 0daf0909f..000000000 --- a/doc/doc-src/spec.src +++ /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{ "$push$g0$f54" -.flag $sm{ "$push$g0$f53" -.flag $smi{ "$push$g0$f56" -.flag $as{ "$push$g0$f52" -.flag $ab{ "$push$g0$f51" -.flag $cb{ "$push$g0$f55" -. -.else -.flag $smc{ "$push" -.flag $sm{ "$push" -.flag $smi{ "$push" -.flag $cb{ "$push" -.fi - -.macro isunderscore "string" -.set string "~~1" -.set length length "~~1" -.undrec 1 -.endm - -.macro undrec "offset" -.if ~~1 > ~~length -.set underscore false -.else -.set sub "~~string"(1,~~1) -.if "~~sub" == "_" -.set underscore true -.else -.set next ~~1 + 1 -.undrec ~~next -.fi -.fi -.endm - -.macro testunderscore "string" -.isunderscore "~~1" -.newline -.endm - -.macro tabs 6 -.if ~~sys.fancy -.tabset ~~1em -.else -.set temp (~~1 * 5)/4 -.tabset ~~temp em -.fi -.endm - -.macro startoptions -.newline -.push -.if ~~sys.fancy -.indent 6em -.else -.indent 7em -.fi -.endm - -.macro endoptions -.newline -.pop -.endm - -.macro option "option" "" -.newpar -.index \-~~1-\ option -.tempindent 0 -\-~~1-\~~2#$i -.nosep -.endm - -.macro startitems -.newline -.push -.indent 3em -.endm - -.macro enditems -.newline -.pop -.endm - -.macro item "item" "6" -.newpar -.if ~~sys.leftonpage < ~~2ld -.newpage -.fi -.tempindent 0 -\**~~1**\ -.blank -.endm - -.macro startconf "" -.set confsection "~~1" -.newline -.push -.if ~~sys.fancy -.indent 2em -.tabset 9em -.else -.indent 4em -.tabset 13em -.fi -.endm - -.macro endconf -.newline -.pop -.endm - -.macro conf "option" "type" "default" "6" -.newpar -.if ~~sys.leftonpage < ~~4ld -.newpage -.fi -.testunderscore "~~1" -.if ~~underscore -.index \~~1\ -.else -.index \~~1\ option -.fi -.if "~~confsection" == "" -.set inssect "" -.else -.set inssect "$rm{Use:} $it{~~confsection}###" -.fi -.tempindent 0 -\**~~1**\ $c ~~inssect$rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} -.blank -.endm - -.set contents true -.set figurenumber -1 -.set displayindent 2em - -.index @$1, @$2, etc. $it{see numerical variables} -.index address||rewriting $it{see rewriting} -.index CR character $it{see carriage return} -.index CRL $it{see certificate revocation list} -.index delivery||failure report $it{see bounce message} -.index dialup $it{see intermittently connected hosts} -.index exiscan $it{see content scanning} -.index failover $it{see fallback} -.index fallover $it{see fallback} -.index filter||Sieve $it{see Sieve filter} -.index ident $it{see RFC 1413} -.index LF character $it{see linefeed} -.index maximum $it{see limit} -.index NUL $it{see binary zero} -.index passwd file $it{see \(/etc/passwd)\} -.index process id $it{see pid} -.index RBL $it{see DNS list} -.index redirection $it{see address redirection} -.index return path||$it{see also envelope sender} -.index scanning $it{see content scanning} -.index SSL $it{see TLS} -.index string||expansion $it{see expansion} -.index top bit $it{see 8-bit characters} -.index variables $it{see expansion, variables} -.index zero, binary $it{see binary zero} - -. This is used for the printed index. See setting above for -. the HTML index value. - -.set ACL "access control lists (ACLs)" - -. ====================================================== - -.push -.disable filling -.justify centre -.nofoot -.space 8ld -$chead{University of Cambridge Computing Service} -.space 2ld -$chead{Specification of the Exim Mail Transfer Agent} -.space 3ld -by -.space 1ld -Philip Hazel -.space ~~sys.leftonpage - 15*~~sys.linedepth -.justify left -University Computing Service -New Museums Site -Pembroke Street -Cambridge CB2 3QH -United Kingdom -.blank -.tabs 6 -$it{phone:} $t +44 1223 334600 -$it{fax:} $t +44 1223 334679 -$it{email:} $t ph10 $it{at} cus.cam.ac.uk -.blank -Edition for Exim ~~version, ~~versionmonth ~~versionyear -.space 2ld -.if ~~sgcal -.fontgroup 1 -.fi -$c$rm{Copyright (c) University of Cambridge ~~versionyear} - - -.if ~~sgcal -.fontgroup 0 -.font 0 -.fi - -.pop -.newpage - -. Blank verso for title page -.space 1ld -.newpage - - -. Set up for actual text pages -.page 1 -. The first one to prevent a warning from sgfr -. set runningfoot "~~chapter" -.set runningfoot "" - -.if ~~sys.fancy -.footdepth 2ld -.foot -.if "~~runningfoot" == "" -.set rhs "" -.else -.set rhs "~~runningfoot (~~chapter)" -.fi -.set lhs "Exim ~~version" -.linelength ~~newlinelength -$it{~~lhs}$c[~~sys.pagenumber]$e$it{~~rhs} -.endfoot -.fi - - - - -. -. -. -. -. ============================================================================ -.chapter Introduction -.set runningfoot "introduction" - -.if ~~sys.fancy -$c$bi{If I have seen further it is by standing on the shoulders of giants.}##(Isaac Newton) -.elif !~~html -$c"If I have seen further it is by standing on the shoulders of giants." -.newline -$e (Isaac Newton) -.else -\*If I have seen further it is by standing on the shoulders of giants.*\ -(Isaac Newton). -.fi -.blank 4 - -Exim is a mail transfer agent (MTA) for hosts that are running Unix or -Unix-like operating systems. It was designed on the assumption that it would be -run on hosts that are permanently connected to the Internet. However, it can be -used on intermittently connected hosts with suitable configuration adjustments. - -Configuration files currently exist for the following operating systems: AIX, -BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, FreeBSD, GNU/Hurd, GNU/Linux, -HI-OSF (Hitachi), HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, QNX, SCO, SCO -SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, Tru64-Unix (formerly -Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. Some of these operating -systems are no longer current and cannot easily be tested, so the configuration -files may no longer work in practice. - -There are also configuration files for compiling Exim in the Cygwin environment -that can be installed on systems running Windows. However, this document does -not contain any information about running Exim in the Cygwin environment. - -The terms and conditions for the use and distribution of Exim are contained in -the file \(NOTICE)\. Exim is distributed under the terms of the GNU General -Public Licence, a copy of which may be found in the file \(LICENCE)\. - -The use, supply or promotion of Exim for the purpose of sending bulk, -unsolicited electronic mail is incompatible with the basic aims of the program, -which revolve around the free provision of a service that enhances the quality -of personal communications. The author of Exim regards indiscriminate -mass-mailing as an antisocial, irresponsible abuse of the Internet. - -Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the -experience of running and working on the Smail 3 code, I could never have -contemplated starting to write a new MTA. Many of the ideas and user interfaces -were originally taken from Smail 3, though the actual code of Exim is entirely -new, and has developed far beyond the initial concept. - -Many people, both in Cambridge and around the world, have contributed to the -development and the testing of Exim, and to porting it to various operating -systems. I am grateful to them all. The distribution now contains a file called -\(ACKNOWLEDGMENTS)\, in which I have started recording the names of -contributors. - - -.section Exim documentation -.index documentation -.em -This edition of the Exim specification applies to version ~~version of Exim. -Substantive changes from the ~~previousversion edition are marked by bars in -the right-hand margin in the PostScript, PDF, and plain text versions of the -document, and by green text in the HTML version, as shown by this paragraph. -Changes are not marked in the Texinfo version, because Texinfo doesn't support -change bars. Minor corrections and rewordings are not marked. -.nem - -This document is very much a reference manual; it is not a tutorial. The reader -is expected to have some familiarity with the SMTP mail transfer protocol and -with general Unix system administration. Although there are some discussions -and examples in places, the information is mostly organized in a way that makes -it easy to look up, rather than in a natural order for sequential reading. -Furthermore, the manual aims to cover every aspect of Exim in detail, including -a number of rarely-used, special-purpose features that are unlikely to be of -very wide interest. - -.index books about Exim -An `easier' discussion of Exim which provides more in-depth explanatory, -introductory, and tutorial material can be found in a book entitled -.if ~~html -[(A HREF="http://www.uit.co.uk/exim-book/")] -$it{The Exim SMTP Mail Server}, -[(/A)] -published by UIT Cambridge. -.else -$it{The Exim SMTP Mail Server}, published by UIT Cambridge -(\?http://www.uit.co.uk/exim-book/?\). -.fi - -This book also contains a chapter that gives a general introduction to SMTP and -Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date -with the latest release of Exim. (Note that the earlier book about Exim, -published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) - -.index \(doc/NewStuff)\ -.index \(doc/ChangeLog)\ -.index change log -As the program develops, there may be features in newer versions that have not -yet made it into this document, which is updated only when the most significant -digit of the fractional part of the version number changes. Specifications of -new features that are not yet in this manual are placed in the file -\(doc/NewStuff)\ in the Exim distribution. - -.em -Some features may be classified as `experimental'. These may change -incompatibly while they are developing, or even be withdrawn. For this reason, -they are not documented in this manual. Information about experimental features -can be found in the file \(doc/experimental.txt)\. -.nem - -All changes to the program (whether new features, bug fixes, or other kinds of -change) are noted briefly in the file called \(doc/ChangeLog)\. - -.index \(doc/spec.txt)\ -This specification itself is available as an ASCII file in \(doc/spec.txt)\ so -that it can easily be searched with a text editor. Other files in the \(doc)\ -directory are: -.display rm -.tabs 18 -\(OptionLists.txt)\ $t $rm{list of all options in alphabetical order} -\(dbm.discuss.txt)\ $t $rm{discussion about DBM libraries} -\(exim.8)\ $t $rm{a man page of Exim's command line options} -.newline -.em -\(experimental.txt)\ $t $rm{documentation of experimental features} -.nem -.newline -\(filter.txt)\ $t $rm{specification of the filter language} -\(pcrepattern.txt)\ $t $rm{specification of PCRE regular expressions} -\(pcretest.txt)\ $t $rm{specification of the PCRE testing program} -\(Exim3.upgrade)\ $t $rm{upgrade notes from release 2 to release 3} -\(Exim4.upgrade)\ $t $rm{upgrade notes from release 3 to release 4} -.endd -The main specification and the specification of the filtering language are also -available in other formats (HTML, PostScript, PDF, and Texinfo). Section -~~SECTavail below tells you how to get hold of these. - - -.section FTP and web sites -.index web site -.index FTP site -.em -The primary distribution site for Exim is currently the University of -Cambridge's FTP site, whose contents are described in \*Where to find the Exim -distribution*\ below. In addition, there is a -.if ~~html -[(A HREF="http://www.exim.org/")] -.fi -web site -.if ~~html -[(/A)] -.fi -and an -.if ~~html -[(A HREF="ftp://ftp.exim.org/")] -.fi -FTP site -.if ~~html -[(/A)] -.fi -at \exim.org\. These are now also hosted at the University of Cambridge. -The \exim.org\ site was previously hosted for a number of years by Energis -Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. - -As well as Exim distribution tar files, the Exim web site contains a number of -differently formatted versions of the documentation, including the -.index FAQ -.if ~~html -[(A HREF="FAQ.html")] -.fi -FAQ -.if ~~html -[(/A)] -.fi -in both text and HTML formats. The HTML version comes with a keyword-in-context -index. A recent addition to the online information is the -.index wiki -.if ~~html -[(A HREF="http://www.exim.org/eximwiki/")] -Exim wiki. -[(/A)] -.else -Exim wiki (\?http://www.exim.org/eximwiki/?\). -.fi -We hope that this will make it easier for Exim users to contribute examples, -tips, and know-how for the benefit of others. -.nem - -.section Mailing lists -.index mailing lists||for Exim users -.em -The following are the three main Exim mailing lists: -.display rm -.tabs 28 -$it{exim-users@@exim.org} $t general discussion list -$it{exim-dev@@exim.org} $t discussion of bugs, enhancements, etc. -$it{exim-announce@@exim.org} $t moderated, low volume announcements list -.endd -.nem -You can subscribe to these lists, change your existing subscriptions, and view -or search the archives via the -.if ~~html -[(A HREF="http://www.exim.org/maillist.html")] -.fi -mailing lists -.if ~~html -[(/A)] -.fi -link on the Exim home page. The $it{exim-users} mailing list is also forwarded -to \?http://www.egroups.com/list/exim-users?\, an archiving system with -searching capabilities. - -.section Exim training -.index training courses -From time to time (approximately annually at the time of writing), -lecture-based training courses are run by the author of Exim in Cambridge, UK. -Details can be found on the web site -.if ~~html -[(A HREF="http://www-tus.csx.cam.ac.uk/courses/exim/")] -.fi -\?http://www-tus@.csx@.cam@.ac.uk/courses/exim/?\. -.if ~~html -[(/A)] -.fi - -.section Bug reports -.index bug reports -.index reporting bugs -Reports of obvious bugs should be emailed to \*bugs@@exim.org*\. However, if -you are unsure whether some behaviour is a bug or not, the best thing to do is -to post a message to the $it{exim-users} mailing list and have it discussed. - - -.em -.section Where to find the Exim distribution -.rset SECTavail "~~chapter.~~section" -.index FTP site -.index distribution||ftp site -The master ftp site for the Exim distribution is -.display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\ -.endd -This is mirrored by -.display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.exim.org/pub/exim?\ -.endd -The file references that follow are relative to the \(exim)\ directories at -these sites. - -There are now quite a number of independent mirror sites around the world. -Those that I know about are listed in the file called \(Mirrors)\. - -Within the \(exim)\ directory there are subdirectories called \(exim3)\ (for -previous Exim 3 distributions), \(exim4)\ (for the latest Exim 4 -distributions), and \(Testing)\ for testing versions. In the \(exim4)\ -subdirectory, the current release can always be found in files called -.display rm -\(exim-$it{n.nn}.tar.gz)\ -\(exim-$it{n.nn}.tar.bz2)\ -.endd -where $it{n.nn} is the highest such version number in the directory. The two -files contain identical data; the only difference is the type of compression. -The \(.bz2)\ file is usually a lot smaller than the \(.gz)\ file. -.index distribution||signing details -.index distribution||public key -.index public key for signed distribution -The distributions are currently signed with Philip Hazel's GPG key. The -corresponding public key is available from a number of keyservers, and there is -also a copy in the file \(Public-Key)\. The signatures for the tar bundles are -in: -.display rm -\(exim-$it{n.nn}.tar.gz.sig)\ -\(exim-$it{n.nn}.tar.bz2.sig)\ -.endd -For each released version, the log of changes is made separately available in a -separate file in the directory \(ChangeLogs)\ so that it is possible to -find out what has changed without having to download the entire distribution. - -.index documentation||available formats -The main distribution contains ASCII versions of this specification and other -documentation; other formats of the documents are available in separate files -inside the \(exim4)\ directory of the FTP site: -.display rm -\(exim-html-$it{n.nn}.tar.gz)\ -\(exim-pdf-$it{n.nn}.tar.gz)\ -\(exim-postscript-$it{n.nn}.tar.gz)\ -\(exim-texinfo-$it{n.nn}.tar.gz)\ -.endd -These tar files contain only the \(doc)\ directory, not the complete -distribution, and are also available in \(.bz2)\ as well as \(.gz)\ forms. - -.index FAQ -The FAQ is available for downloading in two different formats in these files: -.display rm -\(exim4/FAQ.txt.gz)\ -\(exim4/FAQ.html.tar.gz)\ -.endd -The first of these is a single ASCII file that can be searched with a text -editor. The second is a directory of HTML files, normally accessed by starting -at \(index.html)\. The HTML version of the FAQ (which is also included in the -HTML documentation tarbundle) includes a keyword-in-context index, which is -often the most convenient way of finding your way around. - -.section Wish list -.index wish list -A wish list is maintained, containing ideas for new features that have been -submitted. From time to time the file is exported to the ftp site into the file -\(exim4/WishList)\. Items are removed from the list if they get implemented. - - -.section Contributed material -.index contributed material -At the ftp site, there is a directory called \(Contrib)\ that contains -miscellaneous files contributed to the Exim community by Exim users. There is -also a collection of contributed configuration examples in -\(exim4/config.samples.tar.gz)\. These samples are referenced from the FAQ. -.nem - -.section Limitations -.index limitations of Exim -.numberpars $. -Exim is designed for use as an Internet MTA, and therefore handles addresses -in RFC 2822 domain format only. -.index bang paths||not handled by Exim -It cannot handle UUCP `bang paths', though simple two-component bang paths can -be converted by a straightforward rewriting configuration. This restriction -does not prevent Exim from being interfaced to UUCP as a transport mechanism, -provided that domain addresses are used. -.nextp -.index domainless addresses -.index address||without domain -Exim insists that every address it handles has a domain attached. For incoming -local messages, domainless addresses are automatically qualified with a -configured domain value. Configuration options specify from which remote -systems unqualified addresses are acceptable. These are then qualified on -arrival. -.nextp -.index transport||external -.index external transports -The only external transport currently implemented is an SMTP transport over a -TCP/IP network (using sockets, including support for IPv6). However, a pipe -transport is available, and there are facilities for writing messages to files -and pipes, optionally in \*batched SMTP*\ format; these facilities can be used -to send messages to some other transport mechanism such as UUCP, provided it -can handle domain-style addresses. Batched SMTP input is also catered for. -.nextp -Exim is not designed for storing mail for dial-in hosts. When the volumes of -such mail are large, it is better to get the messages `delivered' into files -(that is, off Exim's queue) and subsequently passed on to the dial-in hosts by -other means. -.nextp -.em -Although Exim does have basic facilities for scanning incoming messages, these -are not comprehensive enough to do full virus or spam scanning. Such operations -are best carried out using additional specialized software packages. If you -compile Exim with the content-scanning extension, straightforward interfaces to -a number of common scanners are provided. -.nem -.endp - - - -.section Run time configuration -Exim's run time configuration is held in a single text file that is divided -into a number of sections. The entries in this file consist of keywords and -values, in the style of Smail 3 configuration files. A default configuration -file which is suitable for simple online installations is provided in the -distribution, and is described in chapter ~~CHAPdefconfil below. - - -.section Calling interface -.index Sendmail compatibility||command line interface -Like many MTAs, Exim has adopted the Sendmail command line interface so that it -can be a straight replacement for \(/usr/lib/sendmail)\ or -\(/usr/sbin/sendmail)\ when sending mail, but you do not need to know anything -about Sendmail in order to run Exim. For actions other than sending messages, -Sendmail-compatible options also exist, but those that produce output (for -example, \-bp-\, which lists the messages on the queue) do so in Exim's own -format. There are also some additional options that are compatible with Smail -3, and some further options that are new to Exim. Chapter ~~CHAPcommandline -documents all Exim's command line options. This information is automatically -made into the man page that forms part of the Exim distribution. - -Control of messages on the queue can be done via certain privileged command -line options. There is also an optional monitor program called \*eximon*\, which -displays current information in an X window, and which contains a menu -interface to Exim's command line administration options. - - -.section Terminology -.index terminology definitions -.index body of message||definition of -The \*body*\ of a message is the actual data that the sender wants to transmit. -It is the last part of a message, and is separated from the \*header*\ (see -below) by a blank line. - -.index bounce message||definition of -When a message cannot be delivered, it is normally returned to the sender in a -delivery failure message or a `non-delivery report' (NDR). The term \*bounce*\ -is commonly used for this action, and the error reports are often called -\*bounce messages*\. This is a convenient shorthand for `delivery failure error -report'. Such messages have an empty sender address in the message's -\*envelope*\ (see below) to ensure that they cannot themselves give rise to -further bounce messages. - -The term \*default*\ appears frequently in this manual. It is used to qualify a -value which is used in the absence of any setting in the configuration. It may -also qualify an action which is taken unless a configuration setting specifies -otherwise. - -The term \*defer*\ is used when the delivery of a message to a specific -destination cannot immediately take place for some reason (a remote host may be -down, or a user's local mailbox may be full). Such deliveries are \*deferred*\ -until a later time. - -The word \*domain*\ is sometimes used to mean all but the first component of a -host's name. It is $it{not} used in that sense here, where it normally -refers to the part of an email address following the @@ sign. - -.index envelope, definition of -.index sender||definition of -A message in transit has an associated \*envelope*\, as well as a header and a -body. The envelope contains a sender address (to which bounce messages should -be delivered), and any number of recipient addresses. References to the -sender or the recipients of a message usually mean the addresses in the -envelope. An MTA uses these addresses for delivery, and for returning bounce -messages, not the addresses that appear in the header lines. - -.index message||header, definition of -.index header section||definition of -The \*header*\ of a message is the first part of a message's text, consisting -of a number of lines, each of which has a name such as ::From::, ::To::, -::Subject::, etc. Long header lines can be split over several text lines by -indenting the continuations. The header is separated from the body by a blank -line. - -.index local part||definition of -.index domain||definition of -The term \*local part*\, which is taken from RFC 2822, is used to refer to that -part of an email address that precedes the @@ sign. The part that follows the -@@ sign is called the \*domain*\ or \*mail domain*\. - -.index local delivery||definition of -.index remote delivery, definition of -The terms \*local delivery*\ and \*remote delivery*\ are used to distinguish -delivery to a file or a pipe on the local host from delivery by SMTP over -TCP/IP to a remote host. - -.index return path||definition of -\*Return path*\ is another name that is used for the sender address in a -message's envelope. - -.index queue||definition of -The term \*queue*\ is used to refer to the set of messages awaiting delivery, -because this term is in widespread use in the context of MTAs. However, in -Exim's case the reality is more like a pool than a queue, because there is -normally no ordering of waiting messages. - -.index queue runner||definition of -The term \*queue runner*\ is used to describe a process that scans the queue -and attempts to deliver those messages whose retry times have come. This term -is used by other MTAs, and also relates to the command \runq\, but in Exim -the waiting messages are normally processed in an unpredictable order. - -.index spool directory||definition of -The term \*spool directory*\ is used for a directory in which Exim keeps the -messages on its queue -- that is, those that it is in the process of -delivering. This should not be confused with the directory in which local -mailboxes are stored, which is called a `spool directory' by some people. In -the Exim documentation, `spool' is always used in the first sense. - - - -. -. -. -. -. ============================================================================ -.chapter Incorporated code -.set runningfoot "incorporated code" -.index incorporated code -.index regular expressions||library -.index PCRE -A number of pieces of external code are included in the Exim distribution. -.numberpars $. -Regular expressions are supported in the main Exim program and in the Exim -monitor using the freely-distributable PCRE library, copyright (c) University -of Cambridge. The source is distributed in the directory \(src/pcre)\. However, -this is a cut-down version of PCRE. If you want to use the PCRE library in -other programs, you should obtain and install the full version from -\?ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre?\. - -.space 1ld -.nextp -.index cdb||acknowledgement -Support for the cdb (Constant DataBase) lookup method is provided by code -contributed by Nigel Metheringham of (at the time he contributed it) Planet -Online Ltd. which contains the following statements: -.rule -.push -.if ~~sgcal -.fontgroup 9 -.font 0 -.fi -Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd - -This program is free software; you can redistribute it and/or modify it under -the terms of the GNU General Public License as published by the Free Software -Foundation; either version 2 of the License, or (at your option) any later -version. - -This code implements Dan Bernstein's Constant DataBase (cdb) spec. Information, -the spec and sample code for cdb can be obtained from -\?http://www.pobox.com/@~djb/cdb.html?\. This implementation borrows some code -from Dan Bernstein's implementation (which has no license restrictions applied -to it). -.newline -.pop -.rule -The implementation is completely contained within the code of Exim. -It does not link against an external cdb library. -.space 1ld -.nextp -.index SPA authentication -.index Samba project -.index Microsoft Secure Password Authentication -Client support for Microsoft's \*Secure Password Authentication*\ is provided -by code contributed by Marc Prud'hommeaux. Server support was contributed by -Tom Kistner. This includes code taken from the Samba project, which is released -under the Gnu GPL. - -.space 1ld -.nextp -.index Cyrus -.index \*pwcheck*\ daemon -.index \*pwauthd*\ daemon -Support for calling the Cyrus \*pwcheck*\ and \*saslauthd*\ daemons is provided -by code taken from the Cyrus-SASL library and adapted by Alexander S. -Sabourenkov. The permission notice appears below, in accordance with the -conditions expressed therein. - -.rule -.push -.if ~~sgcal -.fontgroup 9 -.font 0 -.fi -Copyright (c) 2001 Carnegie Mellon University. All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions -are met: - -.if ~~sgcal -.cancelflag $npbracket -.flag $npbracket "" "." -.fi -.numberpars -Redistributions of source code must retain the above copyright -notice, this list of conditions and the following disclaimer. -.nextp -Redistributions in binary form must reproduce the above copyright -notice, this list of conditions and the following disclaimer in -the documentation and/or other materials provided with the -distribution. -.nextp -The name `Carnegie Mellon University' must not be used to -endorse or promote products derived from this software without -prior written permission. For permission or any other legal -details, please contact -.display rm -Office of Technology Transfer -Carnegie Mellon University -5000 Forbes Avenue -Pittsburgh, PA 15213-3890 -(412) 268-4387, fax: (412) 268-7395 -tech-transfer@@andrew.cmu.edu -.endd -.nextp -Redistributions of any form whatsoever must retain the following -acknowledgment: -.newline -.push -.indent ~~sys.indent + 3em -.justify left -$it{This product includes software developed by Computing Services -at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).} -.newline -.pop -.endp -.if ~~sgcal -.cancelflag $npbracket -.flag $npbracket "(" ")" -.fi - -CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO -THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY -AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE -FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN -AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING -OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.newline -.pop -.rule - -.space 1ld -.nextp -.index monitor -.index X-windows -.index Athena -The Exim Monitor program, which is an X-Window application, includes -modified versions of the Athena StripChart and TextPop widgets. -This code is copyright by DEC and MIT, and their permission notice appears -below, in accordance with the conditions expressed therein. - -.rule -.push -.if ~~sgcal -.fontgroup 9 -.font 0 -.fi -Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, Massachusetts, -and the Massachusetts Institute of Technology, Cambridge, Massachusetts. -.blank -$c All Rights Reserved -.blank -Permission to use, copy, modify, and distribute this software and its -documentation for any purpose and without fee is hereby granted, -provided that the above copyright notice appear in all copies and that -both that copyright notice and this permission notice appear in -supporting documentation, and that the names of Digital or MIT not be -used in advertising or publicity pertaining to distribution of the -software without specific, written prior permission. - -DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING -ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL -DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR -ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, -WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, -ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS -SOFTWARE. -.newline -.pop -.rule -.space 1ld -.nextp -.em -Many people have contributed code fragments, some large, some small, that were -not covered by any specific licence requirements. It is assumed that the -contributors are happy to see their code incoporated into Exim under the GPL. -.nem -.endp - - - -. -. -. -. -. ============================================================================ -.chapter How Exim receives and delivers mail -.set runningfoot "receiving & delivering mail" - -.section Overall philosophy -.index design philosophy -Exim is designed to work efficiently on systems that are permanently connected -to the Internet and are handling a general mix of mail. In such circumstances, -most messages can be delivered immediately. Consequently, Exim does not -maintain independent queues of messages for specific domains or hosts, though -it does try to send several messages in a single SMTP connection after a host -has been down, and it also maintains per-host retry information. - - -.section Policy control -.index policy control||overview -Policy controls are now an important feature of MTAs that are connected to the -Internet. Perhaps their most important job is to stop MTAs being abused as -`open relays' by misguided individuals who send out vast amounts of unsolicited -junk, and want to disguise its source. Exim provides flexible facilities for -specifying policy controls on incoming mail: -.numberpars $. -.index ~~ACL||introduction -Exim 4 (unlike previous versions of Exim) implements policy controls on -incoming mail by means of \*Access Control Lists*\ (ACLs). Each list is a -series of statements that may either grant or deny access. ACLs can be used at -several places in the SMTP dialogue while receiving a message from a remote -host. However, the most common places are after each \\RCPT\\ command, and at -the very end of the message. The sysadmin can specify conditions for accepting -or rejecting individual recipients or the entire message, respectively, at -these two points (see chapter ~~CHAPACL). Denial of access results in an SMTP -error code. -.nextp -An ACL is also available for locally generated, non-SMTP messages. In this -case, the only available actions are to accept or deny the entire message. -.nextp -.em -When Exim is compiled with the content-scanning extension, facilities are -provided in the ACL mechanism for passing the message to external virus and/or -spam scanning software. The result of such a scan is passed back to the ACL, -which can then use it to decide what to do with the message. -.nem -.nextp -When a message has been received, either from a remote host or from the local -host, but before the final acknowledgement has been sent, a locally supplied C -function called \*local@_scan()*\ can be run to inspect the message and decide -whether to accept it or not (see chapter ~~CHAPlocalscan). If the message is -accepted, the list of recipients can be modified by the function. -.nextp -.em -Using the \*local@_scan()*\ mechanism is another way of calling external -scanner software. The \SA-Exim\ add-on package works this way. It does not -require Exim to be compiled with the content-scanning extension. -.nem -.nextp -After a message has been accepted, a further checking mechanism is available in -the form of the $it{system filter} (see chapter ~~CHAPsystemfilter). This runs -at the start of every delivery process. -.endp - -.section User filters -.index filter||introduction -.index Sieve filter -In a conventional Exim configuration, users are able to run private filters by -setting up appropriate \(.forward)\ files in their home directories. See -chapter ~~CHAPredirect (about the \%redirect%\ router) for the configuration -needed to support this, and the separate document entitled -.if ~~html -[(A HREF="filter_toc.html")] -.fi -\*Exim's interfaces to mail filtering*\ -.if ~~html -[(/A)] -.fi -for user details. Two different kinds of filtering are available: -.numberpars $. -Sieve filters are written in the standard filtering language that is defined by -RFC 3028. -.nextp -Exim filters are written in a syntax that is unique to Exim, but which is more -powerful than Sieve, which it pre-dates. -.endp -User filters are run as part of the routing process, described below. - - -.section Message identification -.rset SECTmessiden "~~chapter.~~section" -.index message||ids, details of format -.index format||of message id -.index id of message -.index base62 -.index base36 -.index Darwin -.index Cygwin -Every message handled by Exim is given a \*message id*\ which is sixteen -characters long. It is divided into three parts, separated by hyphens, for -example \"16VDhn-0001bo-D3"\. Each part is a sequence of letters and digits, -normally encoding numbers in base 62. However, in the Darwin operating -system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36 -(avoiding the use of lower case letters) is used instead, because the message -id is used to construct file names, and the names of files in those systems are -not case-sensitive. - -.index pid (process id)||re-use of -The detail of the contents of the message id have changed as Exim has evolved. -Earlier versions relied on the operating system not re-using a process id (pid) -within one second. On modern operating systems, this assumption can no longer -be made, so the algorithm had to be changed. To retain backward compatibility, -the format of the message id was retained, which is why the following rules are -somewhat eccentric: -.numberpars $. -The first six characters of the message id are the time at which the message -started to be received, to a granularity of one second. That is, this field -contains the number of seconds since the start of the epoch (the normal Unix -way of representing the date and time of day). -.nextp -After the first hyphen, the next six characters are the id of the process that -received the message. -.nextp -There are two different possibilities for the final two characters: -.numberpars alpha -.index \localhost@_number\ -If \localhost@_number\ is not set, this value is the fractional part of the -time of reception, normally in units of 1/2000 of a second, but for systems -that must use base 36 instead of base 62 (because of case-insensitive file -systems), the units are 1/1000 of a second. -.nextp -If \localhost@_number\ is set, it is multiplied by 200 (100) and added to -the fractional part of the time, which in this case is in units of 1/200 -(1/100) of a second. -.endp -.endp -After a message has been received, Exim waits for the clock to tick at the -appropriate resolution before proceeding, so that if another message is -received by the same process, or by another process with the same (re-used) -pid, it is guaranteed that the time will be different. In most cases, the clock -will already have ticked while the message was being received. - -.section Receiving mail -.index receiving mail -.index message||reception -The only way Exim can receive mail from a remote host is using SMTP over -TCP/IP, in which case the sender and recipient addresses are tranferred using -SMTP commands. However, from a locally running process (such as a user's MUA), -there are several possibilities: -.numberpars $. -If the process runs Exim with the \-bm-\ option, the message is read -non-interactively (usually via a pipe), with the recipients taken from the -command line, or from the body of the message if \-t-\ is also used. -.nextp -If the process runs Exim with the \-bS-\ option, the message is also read -non-interactively, but in this case the recipients are listed at the start of -the message in a series of SMTP \\RCPT\\ commands, terminated by a \\DATA\\ -command. This is so-called `batch SMTP' format, -but it isn't really SMTP. The SMTP commands are just another way of passing -envelope addresses in a non-interactive submission. -.nextp -If the process runs Exim with the \-bs-\ option, the message is read -interactively, using the SMTP protocol. A two-way pipe is normally used for -passing data between the local process and the Exim process. -This is `real' SMTP and is handled in the same way as SMTP over TCP/IP. For -example, the ACLs for SMTP commands are used for this form of submission. -.nextp -A local process may also make a TCP/IP call to the host's loopback address -(127.0.0.1) or any other of its IP addresses. When receiving messages, Exim -does not treat the loopback address specially. It treats all such connections -in the same way as connections from other hosts. -.endp - -.index message||sender, constructed by Exim -.index sender||constructed by Exim -In the three cases that do not involve TCP/IP, the sender address is -constructed from the login name of the user that called Exim and a default -qualification domain (which can be set by the \qualify@_domain\ configuration -option). For local or batch SMTP, a sender address that is passed using the -SMTP \\MAIL\\ command is ignored. However, the system administrator may allow -certain users (`trusted users') to specify a different sender address -unconditionally, or all users to specify certain forms of different sender -address. The \-f-\ option or the SMTP \\MAIL\\ command is used to specify these -different addresses. See section ~~SECTtrustedadmin for details of trusted -users, and the \untrusted@_set@_sender\ option for a way of allowing untrusted -users to change sender addresses. - -Messages received by either of the non-interactive mechanisms are subject to -checking by the non-SMTP ACL, if one is defined. Messages received using SMTP -(either over TCP/IP, or interacting with a local process) can be checked by a -number of ACLs that operate at different times during the SMTP session. Either -individual recipients, or the entire message, can be rejected if local policy -requirements are not met. The \*local@_scan()*\ function (see chapter -~~CHAPlocalscan) is run for all incoming messages. - -Exim can be configured not to start a delivery process when a message is -received; this can be unconditional, or depend on the number of incoming SMTP -connections or the system load. In these situations, new messages wait on the -queue until a queue runner process picks them up. However, in standard -configurations under normal conditions, delivery is started as soon as a -message is received. - - - - -.section Handling an incoming message -.index spool directory||files that hold a message -.index file||how a message is held -When Exim accepts a message, it writes two files in its spool directory. The -first contains the envelope information, the current status of the message, -and the header lines, and the second contains the body of the message. The -names of the two spool files consist of the message id, followed by $tt{-H} for -the file containing the envelope and header, and $tt{-D} for the data file. - -.index spool directory||\(input)\ sub-directory -By default all these message files are held in a single directory called -\(input)\ inside the general Exim spool directory. Some operating systems do -not perform very well if the number of files in a directory gets very large; to -improve performance in such cases, the \split@_spool@_directory\ option can be -used. This causes Exim to split up the input files into 62 sub-directories -whose names are single letters or digits. - -The envelope information consists of the address of the message's sender and -the addresses of the recipients. This information is entirely separate from -any addresses contained in the header lines. The status of the message includes -a list of recipients who have already received the message. The format of the -first spool file is described in chapter ~~CHAPspool. - -.index rewriting||addresses -Address rewriting that is specified in the rewrite section of the configuration -(see chapter ~~CHAPrewrite) is done once and for all on incoming addresses, -both in the header lines and the envelope, at the time the message is accepted. -If during the course of delivery additional addresses are generated (for -example, via aliasing), these new addresses are rewritten as soon as they are -generated. At the time a message is actually delivered (transported) further -rewriting can take place; because this is a transport option, it can be -different for different forms of delivery. It is also possible to specify the -addition or removal of certain header lines at the time the message is -delivered (see chapters ~~CHAProutergeneric and ~~CHAPtransportgeneric). - - -.section Life of a message -.index message||life of -.index message||frozen -A message remains in the spool directory until it is completely delivered to -its recipients or to an error address, or until it is deleted by an -administrator or by the user who originally created it. In cases when delivery -cannot proceed -- for example, when a message can neither be delivered to its -recipients nor returned to its sender, the message is marked `frozen' on the -spool, and no more deliveries are attempted. - -.index frozen messages||thawing -.index message||thawing frozen -An administrator can `thaw' such messages when the problem has been corrected, -and can also freeze individual messages by hand if necessary. In addition, an -administrator can force a delivery error, causing a bounce message to be sent. - -.index \auto@_thaw\ -There is an option called \auto@_thaw\, which can be used to cause Exim to -retry frozen messages after a certain time. When this is set, no message will -remain on the queue for ever, because the delivery timeout will eventually be -reached. Delivery failure reports (bounce messages) that reach this timeout are -discarded. -.index \timeout@_frozen@_after\ -There is also an option called \timeout@_frozen@_after\, which discards frozen -messages after a certain time. - -.index message||log file for -.index log||file for each message -While Exim is working on a message, it writes information about each delivery -attempt to the main log file. This includes successful, unsuccessful, and -delayed deliveries for each recipient (see chapter ~~CHAPlog). The log lines -are also written to a separate $it{message log} file for each message. These -logs are solely for the benefit of the administrator, and are normally deleted -along with the spool files when processing of a message is complete. -The use of individual message logs can be disabled by setting -\no@_message@_logs\; this might give an improvement in performance on very -busy systems. - -.index journal file -.index file||journal -All the information Exim itself needs to set up a delivery is kept in the first -spool file, along with the header lines. When a successful delivery occurs, the -address is immediately written at the end of a journal file, whose name is the -message id followed by $tt{-J}. At the end of a delivery run, if there are some -addresses left to be tried again later, the first spool file (the $tt{-H} file) -is updated to indicate which these are, and the journal file is then deleted. -Updating the spool file is done by writing a new file and renaming it, to -minimize the possibility of data loss. - -Should the system or the program crash after a successful delivery but before -the spool file has been updated, the journal is left lying around. The next -time Exim attempts to deliver the message, it reads the journal file and -updates the spool file before proceeding. This minimizes the chances of double -deliveries caused by crashes. - - -.section Processing an address for delivery -.rset SECTprocaddress "~~chapter.~~section" -.index drivers||definition of -.index router||definition of -.index transport||definition of -The main delivery processing elements of Exim are called $it{routers} and -$it{transports}, and collectively these are known as $it{drivers}. Code for a -number of them is provided in the source distribution, and compile-time options -specify which ones are included in the binary. Run time options specify which -ones are actually used for delivering messages. - -.index drivers||instance definition -Each driver that is specified in the run time configuration is an \*instance*\ -of that particular driver type. Multiple instances are allowed; for example, -you can set up several different \%smtp%\ transports, each with different -option values that might specify different ports or different timeouts. Each -instance has its own identifying name. In what follows we will normally use the -instance name when discussing one particular instance (that is, one specific -configuration of the driver), and the generic driver name when discussing -the driver's features in general. - -A $it{router} is a driver that operates on an address, either determining how -its delivery should happen, by routing it to a specific transport, or -converting the address into one or more new addresses (for example, via an -alias file). A router may also explicitly choose to fail an address, causing it -to be bounced. - -A $it{transport} is a driver that transmits a copy of the message from Exim's -spool to some destination. There are two kinds of transport: for a $it{local} -transport, the destination is a file or a pipe on the local host, whereas for a -$it{remote} transport the destination is some other host. A message is passed -to a specific transport as a result of successful routing. If a message has -several recipients, it may be passed to a number of different transports. - -.index preconditions||definition of -An address is processed by passing it to each configured router instance in -turn, subject to certain preconditions, until a router accepts the address or -specifies that it should be bounced. We will describe this process in more -detail shortly. As a simple example, the diagram below illustrates how each -recipient address in a message is processed in a small configuration of three -routers that are configured in various ways. - -.if ~~sys.fancy -.figure "Routing an address" rm -.indent 0 -.call aspic -sgcal -nv -centre ~~sys.linelength; -magnify 0.8; -boundingbox 30; - ibox depth 14 "address"; -B: arrow down 44; - textdepth 14; -A: box width 100 "first router" "conditions ok?"; - arrow right "yes"; -C: box width 100 "run" "first router"; - arrow down "fail"; -D: ibox depth 20 "address bounces"; - - arc clockwise from right of C "accept"; - arrow down 10; - ibox "queue for" "transport"; - - arrow down from A align bottom of D plus (0,-20) "no"(-6,20)/r; -E: box width 100 "second router" "conditions ok?"; - arrow right "yes"; -F: box width 100 "run" "second router"; - line right 100 "redirect"; - line up align middle of B; - arrow left to middle of B "new addresses"; - - line down 20 from bottom left of F plus (30,0); - arrow left align centre of E "decline"; - - line down 20 from bottom right of F plus (-30,0); - arrow right "fail"; - ibox width 64 "address" "bounces"; - - arrow down 64 from E "no"(-6,20)/r; -G: box width 100 "third router" "conditions ok?"; - arrow right "yes"; -H: box width 100 "run" "third router"; - arc clockwise from right of H "accept"; - arrow down 10; - ibox "queue for" "transport"; - - line down 20 from bottom of H; - arrow left align centre of G "decline"; - arrow down 64 from G "no"(-6,20)/r; - - ibox "no more routers" "address bounces"; -.endcall -.endfigure -.elif !~~html -.display asis - - address - | - |<------------- new addresses ----------------------------- - V | - ----------------- ----------------- | - | first router |----- yes ----->| run |--- accept | - | conditions ok?| | first router | | | - ----------------- ----------------- | | - | | V | - no | fail | queue for | - | V transport | - | address bounces | - | | - V | - ----------------- ----------------- | - | second router |----- yes ----->| run |----redirect ---- - | conditions ok?| | second router | - ----------------- ----------------- - | | | - no | | | - |<-------- decline ----------- --- fail ---> address - | bounces - V - ----------------- ----------------- - | third router |----- yes ----->| run |--- accept - | conditions ok?| | third router | | - ----------------- ----------------- | - | | V - no | | queue for - |<-------- decline --------------- transport - | - V - no more routers - address bounces -.endd -.else -[(img src="routing.gif" alt="Routing an address")][(br)] -.fi -To make this a more concrete example, we'll describe it in terms of some actual -routers, but remember, this is only an example. You can configure Exim's -routers in many different ways, and there may be any number of routers in a -configuration. - -The first router that is specified in a configuration is often one that handles -addresses in domains that are not recognized specially by the local host. These -are typically addresses for arbitrary domains on the Internet. A precondition -is set up which looks for the special domains known to the host (for example, -its own domain name), and the router is run for addresses that do $it{not} -match. Typically, this is a router that looks up domains in the DNS in order to -find the hosts to which this address routes. If it succeeds, the address is -queued for a suitable SMTP transport; if it does not succeed, the router is -configured to fail the address. - -The example pictured could be a configuration of this type. The second and -third routers can only be run for addresses for which the preconditions for -the first router are not met. If one of these preconditions checks the -domain, the second and third routers are run only for domains that are somehow -special to the local host. - -The second router does redirection -- also known as aliasing and forwarding. -When it generates one or more new addresses from the original, each of them is -routed independently from the start. Otherwise, the router may cause an address -to fail, or it may simply decline to handle the address, in which case the -address is passed to the next router. - -The final router in many configurations is one that checks to see if the -address belongs to a local mailbox. The precondition may involve a check to -see if the local part is the name of a login account, or it may look up the -local part in a file or a database. If its preconditions are not met, or if -the router declines, we have reached the end of the routers. When this happens, -the address is bounced. - - -.section Processing an address for verification -.index router||for verification -.index verifying||address, overview -As well as being used to decide how to deliver to an address, Exim's routers -are also used for \*address verification*\. Verification can be requested as -one of the checks to be performed in an ACL for incoming messages, on both -sender and recipient addresses, and it can be tested using the \-bv-\ and -\-bvs-\ command line options. - -When an address is being verified, the routers are run in `verify mode'. This -does not affect the way the routers work, but it is a state that can be -detected. By this means, a router can be skipped or made to behave differently -when verifying. A common example is a configuration in which the first router -sends all messages to a message-scanning program, unless they have been -previously scanned. Thus, the first router accepts all addresses without any -checking, making it useless for verifying. Normally, the \no@_verify\ option -would be set for such a router, causing it to be skipped in verify mode. - - - -.section Running an individual router -.rset SECTrunindrou "~~chapter.~~section" -.index router||running details -.index preconditions||checking -.index router||result of running -As explained in the example above, a number of preconditions are checked before -running a router. If any are not met, the router is skipped, and the address is -passed to the next router. When all the preconditions on a router $it{are} met, -the router is run. What happens next depends on the outcome, which is one of -the following: -.numberpars $. -\*accept*\: The router accepts the address, and either queues it for a -transport, or generates one or more `child' addresses. Processing the original -address ceases, -.index \unseen\ option -unless the \unseen\ option is set on the router. This option -can be used to set up multiple deliveries with different routing (for example, -for keeping archive copies of messages). When \unseen\ is set, the address is -passed to the next router. Normally, however, an \*accept*\ return marks the -end of routing. - -.index case of local parts -.index address||duplicate, discarding -If child addresses are generated, Exim checks to see whether they are -duplicates of any existing recipient addresses. During this check, local parts -are treated as case-sensitive. Duplicate addresses are discarded. Each of the -remaining child addresses is then processed independently, starting with the -first router by default. It is possible to change this by setting the -\redirect@_router\ option to specify which router to start at for child -addresses. Unlike \pass@_router\ (see below) the router specified by -\redirect@_router\ may be anywhere in the router configuration. -.nextp -\*pass*\: The router recognizes the address, but cannot handle it itself. It -requests that the address be passed to another router. By default the address -is passed to the next router, but this can be changed by setting the -\pass@_router\ option. However, (unlike \redirect@_router\) the named router -must be below the current router (to avoid loops). -.nextp -\*decline*\: The router declines to accept the address because it does not -recognize it at all. By default, the address is passed to the next router, but -this can be prevented by setting the \no@_more\ option. When \no@_more\ is set, -all the remaining routers are skipped. -.nextp -\*fail*\: The router determines that the address should fail, and queues it for -the generation of a bounce message. There is no further processing of the -original address unless \unseen\ is set on the router. -.nextp -\*defer*\: The router cannot handle the address at the present time. (A database -may be offline, or a DNS lookup may have timed out.) No further processing of -the address happens in this delivery attempt. It is tried again next time the -message is considered for delivery. -.nextp -\*error*\: There is some error in the router (for example, a syntax error in -its configuration). The action is as for defer. -.endp -If an address reaches the end of the routers without having been accepted by -any of them, it is bounced as unrouteable. -The default error message in this situation is `unrouteable address', but you -can set your own message by making use of the \cannot@_route@_message\ option. -This can be set for any router; the value from the last router that `saw' -the address is used. - -Sometimes while routing you want to fail a delivery when some conditions are -met but others are not, instead of passing the address on for further routing. -You can do this by having a second router that explicitly fails the delivery -when the relevant conditions are met. The \%redirect%\ router has a `fail' -facility for this purpose. - - - -.section Router preconditions -.rset SECTrouprecon "~~chapter.~~section" -.index router||preconditions, order of processing -.index preconditions||order of processing -The preconditions that are tested for each router are listed below, in the -order in which they are tested. The individual configuration options are -described in more detail in chapter ~~CHAProutergeneric. -.numberpars $. -The \local@_part@_prefix\ and \local@_part@_suffix\ options can specify that -the local parts handled by the router may or must have certain prefixes and/or -suffixes. If a mandatory affix (prefix or suffix) is not present, the router is -skipped. These conditions are tested first. When an affix is present, it is -removed from the local part before further processing, including the evaluation -of any other conditions. -.nextp -Routers can be designated for use only when not verifying an address, that is, -only when routing it for delivery (or testing its delivery routing). If the -\verify\ option is set false, the router is skipped when Exim is verifying an -address. -Setting the \verify\ option actually sets two options, \verify@_sender\ and -\verify@_recipient\, which independently control the use of the router for -sender and recipient verification. You can set these options directly if -you want a router to be used for only one type of verification. -.nextp -If the \address@_test\ option is set false, the router is skipped when Exim is -run with the \-bt-\ option to test an address routing. This can be helpful when -the first router sends all new messages to a scanner of some sort; it makes it -possible to use \-bt-\ to test subsequent delivery routing without having to -simulate the effect of the scanner. -.nextp -Routers can be designated for use only when verifying an address, as -opposed to routing it for delivery. The \verify@_only\ option controls this. -.nextp -Certain routers can be explicitly skipped when running the routers to check an -address given in the SMTP \\EXPN\\ command (see the \expn\ option). -.nextp -If the \domains\ option is set, the domain of the address must be in the set of -domains that it defines. -.nextp -If the \local@_parts\ option is set, the local part of the address must be in -the set of local parts that it defines. If \local@_part@_prefix\ or -\local@_part@_suffix\ is in use, the prefix or suffix is removed from the local -part before this check. If you want to do precondition tests on local parts -that include affixes, you can do so by using a \condition\ option (see below) -that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and -\$local@_part@_suffix$\ as necessary. -.nextp -If the \check@_local@_user\ option is set, the local part must be the name of -an account on the local host. -If this check succeeds, the uid and gid of the local user are placed in -\$local@_user@_uid$\ and \$local@_user@_gid$\; these values can be used in the -remaining preconditions. -.nextp -If the \router@_home@_directory\ option is set, it is expanded at this point, -because it overrides the value of \$home$\. If this expansion were left till -later, the value of \$home$\ as set by \check@_local@_user\ would be used in -subsequent tests. Having two different values of \$home$\ in the same router -could lead to confusion. -.nextp -If the \senders\ option is set, the envelope sender address must be in the set -of addresses that it defines. -.nextp -If the \require@_files\ option is set, the existence or non-existence of -specified files is tested. -.nextp -.index customizing||precondition -If the \condition\ option is set, it is evaluated and tested. This option uses -an expanded string to allow you to set up your own custom preconditions. -Expanded strings are described in chapter ~~CHAPexpand. -.endp - -Note that \require@_files\ comes near the end of the list, so you cannot use it -to check for the existence of a file in which to lookup up a domain, local -part, or sender. However, as these options are all expanded, you can use the -\exists\ expansion condition to make such tests within each condition. The -\require@_files\ option is intended for checking files that the router may be -going to use internally, or which are needed by a specific transport (for -example, \(.procmailrc)\). - - -.section Delivery in detail -.index delivery||in detail -When a message is to be delivered, the sequence of events is as follows: -.numberpars $. -If a system-wide filter file is specified, the message is passed to it. The -filter may add recipients to the message, replace the recipients, discard the -message, cause a new message to be generated, or cause the message delivery to -fail. The format of the system filter file is the same as for Exim user filter -files, described in the separate document entitled -.if ~~html -[(A HREF="filter.html")] -.fi -\*Exim's interfaces to mail filtering*\. -.if ~~html -[(/A)] -.fi -.index Sieve filter||not available for system filter -(\**Note**\: Sieve cannot be used for system filter files.) -Some additional features are available in system filters -- see chapter -~~CHAPsystemfilter for details. Note that a message is passed to the system -filter only once per delivery attempt, however many recipients it has. However, -if there are several delivery attempts because one or more addresses could not -be immediately delivered, the system filter is run each time. The filter -condition \first@_delivery\ can be used to detect the first run of the system -filter. -.nextp -Each recipient address is offered to each configured router in turn, subject to -its preconditions, until one is able to handle it. If no router can handle -the address, that is, if they all decline, the address is failed. Because -routers can be targeted at particular domains, several locally handled domains -can be processed entirely independently of each other. -.nextp -.index routing||loops in -.index loop||while routing -A router that accepts an address may set up a local or a remote transport for -it. However, the transport is not run at this time. Instead, the address is -placed on a list for the particular transport, to be run later. Alternatively, -the router may generate one or more new addresses (typically from alias, -forward, or filter files). New addresses are fed back into this process from -the top, but in order to avoid loops, a router ignores any address which has an -identically-named ancestor that was processed by itself. -.nextp -When all the routing has been done, addresses that have been successfully -handled are passed to their assigned transports. When local transports are -doing real local deliveries, they handle only one address at a time, but if a -local transport is being used as a pseudo-remote transport (for example, to -collect batched SMTP messages for transmission by some other means) multiple -addresses can be handled. Remote transports can always handle more than one -address at a time, but can be configured not to do so, or to restrict multiple -addresses to the same domain. -.nextp -Each local delivery to a file or a pipe runs in a separate process under a -non-privileged uid, and these deliveries are run one at a time. Remote -deliveries also run in separate processes, normally under a uid that is private -to Exim (`the Exim user'), but in this case, several remote deliveries can be -run in parallel. The maximum number of simultaneous remote deliveries for any -one message is set by the \remote@_max@_parallel\ option. -The order in which deliveries are done is not defined, except that all local -deliveries happen before any remote deliveries. -.nextp -.index queue runner -When it encounters a local delivery during a queue run, Exim checks its retry -database to see if there has been a previous temporary delivery failure for the -address before running the local transport. If there was a previous failure, -Exim does not attempt a new delivery until the retry time for the address is -reached. However, this happens only for delivery attempts that are part of a -queue run. Local deliveries are always attempted when delivery immediately -follows message reception, even if retry times are set for them. This makes for -better behaviour if one particular message is causing problems (for example, -causing quota overflow, or provoking an error in a filter file). -.nextp -.index delivery||retry in remote transports -Remote transports do their own retry handling, since an address may be -deliverable to one of a number of hosts, each of which may have a different -retry time. If there have been previous temporary failures and no host has -reached its retry time, no delivery is attempted, whether in a queue run or -not. See chapter ~~CHAPretry for details of retry strategies. -.nextp -If there were any permanent errors, a bounce message is returned to an -appropriate address (the sender in the common case), with details of the error -for each failing address. Exim can be configured to send copies of bounce -messages to other addresses. -.nextp -.index delivery||deferral -If one or more addresses suffered a temporary failure, the message is left on -the queue, to be tried again later. Delivery of these addresses is said to be -\*deferred*\. -.nextp -When all the recipient addresses have either been delivered or bounced, -handling of the message is complete. The spool files and message log are -deleted, though the message log can optionally be preserved if required. -.endp - - -.section Retry mechanism -.index delivery||retry mechanism -.index retry||description of mechanism -.index queue runner -Exim's mechanism for retrying messages that fail to get delivered at the first -attempt is the queue runner process. You must either run an Exim daemon that -uses the \-q-\ option with a time interval to start queue runners at regular -intervals, or use some other means (such as \*cron*\) to start them. If you do -not arrange for queue runners to be run, messages that fail temporarily at the -first attempt will remain on your queue for ever. A queue runner process works -it way through the queue, one message at a time, trying each delivery that has -passed its retry time. -You can run several queue runners at once. - -Exim uses a set of configured rules to determine when next to retry the failing -address (see chapter ~~CHAPretry). These rules also specify when Exim should -give up trying to deliver to the address, at which point it generates a bounce -message. If no retry rules are set for a particular host, address, and error -combination, no retries are attempted, and temporary errors are treated as -permanent. - - -.section Temporary delivery failure -.index delivery||temporary failure -There are many reasons why a message may not be immediately deliverable to a -particular address. Failure to connect to a remote machine (because it, or the -connection to it, is down) is one of the most common. Temporary failures may be -detected during routing as well as during the transport stage of delivery. -Local deliveries may be delayed if NFS files are unavailable, or if a mailbox -is on a file system where the user is over quota. Exim can be configured to -impose its own quotas on local mailboxes; where system quotas are set they will -also apply. - -If a host is unreachable for a period of time, a number of messages may be -waiting for it by the time it recovers, and sending them in a single SMTP -connection is clearly beneficial. Whenever a delivery to a remote host is -deferred, -.index hints database -Exim makes a note in its hints database, and whenever a successful -SMTP delivery has happened, it looks to see if any other messages are waiting -for the same host. If any are found, they are sent over the same SMTP -connection, subject to a configuration limit as to the maximum number in any -one connection. - - - -.section Permanent delivery failure -.index delivery||permanent failure -.index bounce message||when generated -When a message cannot be delivered to some or all of its intended recipients, a -bounce message is generated. Temporary delivery failures turn into permanent -errors when their timeout expires. All the addresses that fail in a given -delivery attempt are listed in a single message. If the original message has -many recipients, it is possible for some addresses to fail in one delivery -attempt and others to fail subsequently, giving rise to more than one bounce -message. The wording of bounce messages can be customized by the administrator. -See chapter ~~CHAPemsgcust for details. - -.index ::X-Failed-Recipients:: header line -Bounce messages contain an ::X-Failed-Recipients:: header line that lists the -failed addresses, for the benefit of programs that try to analyse such messages -automatically. - -.index bounce message||recipient of -A bounce message is normally sent to the sender of the original message, as -obtained from the message's envelope. For incoming SMTP messages, this is the -address given in the \\MAIL\\ command. However, when an address is -expanded via a forward or alias file, an alternative address can be specified -for delivery failures of the generated addresses. For a mailing list expansion -(see section ~~SECTmailinglists) it is common to direct bounce messages to the -manager of the list. - - - -.section Failures to deliver bounce messages -.index bounce message||failure to deliver -If a bounce message (either locally generated or received from a remote host) -itself suffers a permanent delivery failure, the message is left on the queue, -but it is frozen, awaiting the attention of an administrator. There are options -which can be used to make Exim discard such failed messages, or to keep them -for only a short time (see \timeout@_frozen@_after\ and -\ignore@_bounce@_errors@_after\). - - - -. -. -. -. -. ============================================================================ -.chapter Building and installing Exim -.set runningfoot "building/installing" - -.index building Exim -.section Unpacking -Exim is distributed as a gzipped or bzipped tar file which, when upacked, -creates a directory with the name of the current release (for example, -\(exim-~~version)\) into which the following files are placed: -.display rm -.if !~~sys.fancy && ~~sgcal -.tabs 16 -.else -.tabs 22 -.fi -\(ACKNOWLEDGMENTS)\ $t contains some acknowledgments -.newline -\(CHANGES)\ $t contains a reference to where changes are documented -\(LICENCE)\ $t the GNU General Public Licence -\(Makefile)\ $t top-level make file -\(NOTICE)\ $t conditions for the use of Exim -\(README)\ $t list of files, directories and simple build instructions -.endd -Other files whose names begin with \(README)\ may also be present. The -following subdirectories are created: -.display rm -.if !~~sys.fancy && ~~sgcal -.tabs 16 -.else -.tabs 22 -.fi -\(Local)\ $t an empty directory for local configuration files -\(OS)\ $t OS-specific files -\(doc)\ $t documentation files -\(exim@_monitor)\$t source files for the Exim monitor -\(scripts)\ $t scripts used in the build process -\(src)\ $t remaining source files -\(util)\ $t independent utilities -.endd -The main utility programs are contained in the \(src)\ directory, and are built -with the Exim binary. The \(util)\ directory contains a few optional scripts -that may be useful to some sites. - -.section Multiple machine architectures and operating systems -.index building Exim||multiple OS/architectures -The building process for Exim is arranged to make it easy to build binaries for -a number of different architectures and operating systems from the same set of -source files. Compilation does not take place in the \(src)\ directory. Instead, -a \*build directory*\ is created for each architecture and operating system. -.index symbolic link||to build directory -Symbolic links to the sources are installed in this directory, which is where -the actual building takes place. - -In most cases, Exim can discover the machine architecture and operating system -for itself, but the defaults can be overridden if necessary. - -.section DBM libraries -.rset SECTdb "~~chapter.~~section" -.index DBM||libraries, discussion of -.index hints database||DBM files used for -Even if you do not use any DBM files in your configuration, Exim still needs a -DBM library in order to operate, because it uses indexed files for its hints -databases. Unfortunately, there are a number of DBM libraries in existence, and -different operating systems often have different ones installed. - -.index Solaris||DBM library for -.index IRIX, DBM library for -.index BSD, DBM library for -.index Linux, DBM library for -If you are using Solaris, IRIX, one of the modern BSD systems, or a modern -Linux distribution, the DBM configuration should happen automatically, and you -may be able to ignore this section. Otherwise, you may have to learn more than -you would like about DBM libraries from what follows. - -.index \*ndbm*\ DBM library -Licensed versions of Unix normally contain a library of DBM functions operating -via the \*ndbm*\ interface, and this is what Exim expects by default. Free -versions of Unix seem to vary in what they contain as standard. In particular, -some early versions of Linux have no default DBM library, and different -distributors have chosen to bundle different libraries with their packaged -versions. However, the more recent releases seem to have standardised on the -Berkeley DB library. - -Different DBM libraries have different conventions for naming the files they -use. When a program opens a file called \(dbmfile)\, there are four -possibilities: -.numberpars -A traditional \*ndbm*\ implementation, such as that supplied as part of -Solaris, operates on two files called \(dbmfile.dir)\ and \(dbmfile.pag)\. -.nextp -.index \*gdbm*\ DBM library -The GNU library, \*gdbm*\, operates on a single file. If used via its \*ndbm*\ -compatibility interface it makes two different hard links to it with names -\(dbmfile.dir)\ and \(dbmfile.pag)\, but if used via its native interface, the -file name is used unmodified. -.nextp -.index Berkeley DB library -The Berkeley DB package, if called via its \*ndbm*\ compatibility interface, -operates on a single file called \(dbmfile.db)\, but otherwise looks to the -programmer exactly the same as the traditional \*ndbm*\ implementation. -.nextp -If the Berkeley package is used in its native mode, it operates on a single -file called \(dbmfile)\; the programmer's interface is somewhat different to -the traditional \*ndbm*\ interface. -.nextp -To complicate things further, there are several very different versions of the -Berkeley DB package. Version 1.85 was stable for a very long time, releases -2.$it{x} and 3.$it{x} were current for a while, but the latest versions are now -numbered 4.$it{x}. Maintenance of some of the earlier releases has ceased. All -versions of Berkeley DB can be obtained from -.display rm -\?http://www.sleepycat.com/?\ -.endd -.nextp -.index \*tdb*\ DBM library -Yet another DBM library, called \*tdb*\, has become available from -.display rm -\?http://download.sourceforge.net/tdb?\ -.endd -It has its own interface, and also operates on a single file. -.endp -.index \\USE@_DB\\ -.index DBM||libraries, configuration for building -Exim and its utilities can be compiled to use any of these interfaces. In order -to use any version of the Berkeley DB package in native mode, you must set -\\USE@_DB\\ in an appropriate configuration file (typically -\(Local/Makefile)\). For example: -.display asis -USE_DB=yes -.endd -Similarly, for gdbm you set \\USE@_GDBM\\, and for tdb you set \\USE@_TDB\\. An -error is diagnosed if you set more than one of these. - -At the lowest level, the build-time configuration sets none of these options, -thereby assuming an interface of type (1). However, some operating system -configuration files (for example, those for the BSD operating systems and -Linux) assume type (4) by setting \\USE@_DB\\ as their default, and the -configuration files for Cygwin set \\USE@_GDBM\\. Anything you set in -\(Local/Makefile)\, however, overrides these system defaults. - -As well as setting \\USE@_DB\\, \\USE@_GDBM\\, or \\USE@_TDB\\, it may also be -necessary to set \\DBMLIB\\, to cause inclusion of the appropriate library, as -in one of these lines: -.display asis -DBMLIB = -ldb -DBMLIB = -ltdb -.endd -Settings like that will work if the DBM library is installed in the standard -place. Sometimes it is not, and the library's header file may also not be in -the default path. You may need to set \\INCLUDE\\ to specify where the header -file is, and to specify the path to the library more fully in \\DBMLIB\\, as in -this example: -.display asis -INCLUDE=-I/usr/local/include/db-4.1 -DBMLIB=/usr/local/lib/db-4.1/libdb.a -.endd - -There is further detailed discussion about the various DBM libraries in the -file \(doc/dbm.discuss.txt)\ in the Exim distribution. - - -.section Pre-building configuration -.index building Exim||pre-building configuration -.index configuration for building Exim -.index \(Local/Makefile)\ -.index \(src/EDITME)\ -Before building Exim, a local configuration file that specifies options -independent of any operating system has to be created with the name -\(Local/Makefile)\. A template for this file is supplied as the file -\(src/EDITME)\, and it contains full descriptions of all the option settings -therein. These descriptions are therefore not repeated here. If you are -building Exim for the first time, the simplest thing to do is to copy -\(src/EDITME)\ to \(Local/Makefile)\, then read it and edit it appropriately. - -There are three settings that you must supply, because Exim will not build -without them. They are the location of the run time configuration file -(\\CONFIGURE@_FILE\\), the directory in which Exim binaries will be installed -(\\BIN@_DIRECTORY\\), and the identity of the Exim user (\\EXIM@_USER\\ and -maybe \\EXIM@_GROUP\\ as well). The value of \\CONFIGURE@_FILE\\ can in fact be -a colon-separated list of file names; Exim uses the first of them that exists. - -There are a few other parameters that can be specified either at build time or -at run time, to enable the same binary to be used on a number of different -machines. However, if the locations of Exim's spool directory and log file -directory (if not within the spool directory) are fixed, it is recommended that -you specify them in \(Local/Makefile)\ instead of at run time, so that errors -detected early in Exim's execution (such as a malformed configuration file) can -be logged. - -.index content scanning||specifying at build time -.em -Exim's interfaces for calling virus and spam scanning sofware directly from -access control lists are not compiled by default. If you want to include these -facilities, you need to set -.display asis -WITH_CONTENT_SCAN=yes -.endd -in your \(Local/Makefile)\. For details of the facilities themselves, see -chapter ~~CHAPexiscan. -.nem - -.index \(Local/eximon.conf)\ -.index \(exim@_monitor/EDITME)\ -If you are going to build the Exim monitor, a similar configuration process is -required. The file \(exim@_monitor/EDITME)\ must be edited appropriately for -your installation and saved under the name \(Local/eximon.conf)\. If you are -happy with the default settings described in \(exim@_monitor/EDITME)\, -\(Local/eximon.conf)\ can be empty, but it must exist. - -This is all the configuration that is needed in straightforward cases for known -operating systems. However, the building process is set up so that it is easy -to override options that are set by default or by operating-system-specific -configuration files, for example to change the name of the C compiler, which -defaults to \gcc\. See section ~~SECToverride below for details of how to do -this. - - -.section Support for iconv() -.index \*iconv()*\ support -The contents of header lines in messages may be encoded according to the rules -described RFC 2047. This makes it possible to transmit characters that are not -in the ASCII character set, and to label them as being in a particular -character set. When Exim is inspecting header lines by means of the \@$h@_\ -mechanism, it decodes them, and translates them into a specified character set -(default ISO-8859-1). The translation is possible only if the operating system -supports the \*iconv()*\ function. - -However, some of the operating systems that supply \*iconv()*\ do not support -very many conversions. The GNU \libiconv\ library (available from -\?http:/@/www.gnu.org/software/libiconv/?\) can be installed on such systems to -remedy this deficiency, as well as on systems that do not supply \*iconv()*\ at -all. After installing \libiconv\, you should add -.display asis -HAVE_ICONV=yes -.endd -to your \(Local/Makefile)\ and rebuild Exim. - - -.section Including TLS/SSL encryption support -.rset SECTinctlsssl "~~chapter.~~section" -.index TLS||including support for TLS -.index encryption||including support for -.index \\SUPPORT@_TLS\\ -.index OpenSSL||building Exim with -.index GnuTLS||building Exim with -Exim can be built to support encrypted SMTP connections, using the \\STARTTLS\\ -command as per RFC 2487. It can also support legacy clients that expect to -start a TLS session immediately on connection to a non-standard port (see the -\tls@_on@_connect@_ports\ runtime option and the \-tls-on-connect-\ command -line option). - -If you want to build Exim with TLS support, you must first install either the -OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for -implementing SSL. - -If OpenSSL is installed, you should set -.display asis -SUPPORT_TLS=yes -TLS_LIBS=-lssl -lcrypto -.endd -in \(Local/Makefile)\. You may also need to specify the locations of the -OpenSSL library and include files. For example: -.display asis -SUPPORT_TLS=yes -TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto -TLS_INCLUDE=-I/usr/local/openssl/include/ -.endd - -If GnuTLS is installed, you should set -.index \\USE@_GNUTLS\\ -.display asis -SUPPORT_TLS=yes -USE_GNUTLS=yes -TLS_LIBS=-lgnutls -ltasn1 -lgcrypt -.endd -in \(Local/Makefile)\, and again you may need to specify the locations of the -library and include files. For example: -.display asis -SUPPORT_TLS=yes -USE_GNUTLS=yes -TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt -TLS_INCLUDE=-I/usr/gnu/include -.endd -You do not need to set \\TLS@_INCLUDE\\ if the relevant directory is already -specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS -are given in chapter ~~CHAPTLS. - - - -.section Use of tcpwrappers -.index tcpwrappers, building Exim to support -.index \\USE@_TCP@_WRAPPERS\\ -Exim can be linked with the \*tcpwrappers*\ library in order to check incoming -SMTP calls using the \*tcpwrappers*\ control files. This may be a convenient -alternative to Exim's own checking facilities for installations that are -already making use of \*tcpwrappers*\ for other purposes. To do this, you should -set \\USE@_TCP@_WRAPPERS\\ in \(Local/Makefile)\, arrange for the file -\(tcpd.h)\ to be available at compile time, and also ensure that the library -\(libwrap.a)\ is available at link time, typically by including \-lwrap-\ in -\\EXTRALIBS@_EXIM\\. For example, if \*tcpwrappers*\ is installed in -\(/usr/local)\, you might have -.display -USE@_TCP@_WRAPPERS=yes -CFLAGS=-O -I/usr/local/include -.newline -EXTRALIBS@_EXIM=-L/usr/local/lib -lwrap -.endd -in \(Local/Makefile)\. The name to use in the \*tcpwrappers*\ control files is -`exim'. For example, the line -.display -exim : LOCAL 192.168.1. .friendly.domain.example -.endd -in your \(/etc/hosts.allow)\ file allows connections from the local host, from -the subnet 192.168.1.0/24, and from all hosts in \*friendly.domain.example*\. -All other connections are denied. Consult the \*tcpwrappers*\ documentation for -further details. - - -.section Including support for IPv6 -.index IPv6||including support for -Exim contains code for use on systems that have IPv6 support. Setting -\\HAVE@_IPV6=YES\\ in \(Local/Makefile)\ causes the IPv6 code to be included; -it may also be necessary to set \\IPV6@_INCLUDE\\ and \\IPV6@_LIBS\\ on systems -where the IPv6 support is not fully integrated into the normal include and -library files. - -.em -Two different types of DNS record for handling IPv6 addresses have been -defined. AAAA records (analagous to A records for IPv4) are in use, and are -currently seen as the mainstream. Another record type called A6 was proposed -as better than AAAA because it had more flexibility. However, it was felt to -be over-complex, and its status was reduced to `experimental'. It is not known -if anyone is actually using A6 records. Exim has support for A6 records, but -this is included only if you set \\SUPPORT@_A6=YES\\ in \(Local/Makefile)\. The -support has not been tested for some time. -.nem - -.section The building process -.index build directory -Once \(Local/Makefile)\ (and \(Local/eximon.conf)\, if required) have been -created, run \*make*\ at the top level. It determines the architecture and -operating system types, and creates a build directory if one does not exist. -For example, on a Sun system running Solaris 8, the directory -\(build-SunOS5-5.8-sparc)\ is created. -.index symbolic link||to source files -Symbolic links to relevant source files are installed in the build directory. - -\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the -building process fails if it is set. - -If this is the first time \*make*\ has been run, it calls a script that builds -a make file inside the build directory, using the configuration files from the -\(Local)\ directory. The new make file is then passed to another instance of -\*make*\. This does the real work, building a number of utility scripts, and -then compiling and linking the binaries for the Exim monitor (if configured), a -number of utility programs, and finally Exim itself. The command \*make -makefile*\ can be used to force a rebuild of the make file in the build -directory, should this ever be necessary. - -If you have problems building Exim, check for any comments there may be in the -\(README)\ file concerning your operating system, and also take a look at the -.if ~~html -[(A HREF="FAQ.html")] -.fi -FAQ, -.if ~~html -[(/A)] -.fi -where some common problems are covered. - - - -.section Overriding build-time options for Exim -.index build-time options, overriding -.rset SECToverride "~~chapter.~~section" -The main make file that is created at the beginning of the building process -consists of the concatenation of a number of files which set configuration -values, followed by a fixed set of \*make*\ instructions. If a value is set -more than once, the last setting overrides any previous ones. This provides a -convenient way of overriding defaults. The files that are concatenated are, in -order: -.display rm -\(OS/Makefile-Default)\ -\(OS/Makefile-)\<<ostype>> -\(Local/Makefile)\ -\(Local/Makefile-)\<<ostype>> -\(Local/Makefile-)\<<archtype>> -\(Local/Makefile-)\<<ostype>>-<<archtype>> -\(OS/Makefile-Base)\ -.endd -.index \(Local/Makefile)\ -where <<ostype>> is the operating system type and <<archtype>> is the -.index building Exim||operating system type -.index building Exim||architecture type -architecture type. \(Local/Makefile)\ is required to exist, and the building -process fails if it is absent. The other three \(Local)\ files are optional, -and are often not needed. - -The values used for <<ostype>> and <<archtype>> are obtained from scripts -called \(scripts/os-type)\ and \(scripts/arch-type)\ respectively. If either of -the environment variables \\EXIM@_OSTYPE\\ or \\EXIM@_ARCHTYPE\\ is set, their -values are used, thereby providing a means of forcing particular settings. -Otherwise, the scripts try to get values from the \uname\ command. If this -fails, the shell variables \\OSTYPE\\ and \\ARCHTYPE\\ are inspected. A number -of $it{ad hoc} transformations are then applied, to produce the standard names -that Exim expects. You can run these scripts directly from the shell in order -to find out what values are being used on your system. - - -\(OS/Makefile-Default)\ contains comments about the variables that are set -therein. Some (but not all) are mentioned below. If there is something that -needs changing, review the contents of this file and the contents of the make -file for your operating system (\(OS/Makefile-<<ostype>>)\) to see what the -default values are. - - -.index building Exim||overriding default settings -If you need to change any of the values that are set in \(OS/Makefile-Default)\ -or in \(OS/Makefile-<<ostype>>)\, or to add any new definitions, you do not -need to change the original files. Instead, you should make the changes by -putting the new values in an appropriate \(Local)\ file. For example, -.index Tru64-Unix build-time settings -when building Exim in many releases of the Tru64-Unix (formerly Digital UNIX, -formerly DEC-OSF1) operating system, it is necessary to specify that the C -compiler is called \*cc*\ rather than \*gcc*\. Also, the compiler must be -called with the option \-std1-\, to make it recognize some of the features of -Standard C that Exim uses. (Most other compilers recognize Standard C by -default.) To do this, you should create a file called \(Local/Makefile-OSF1)\ -containing the lines -.display -CC=cc -CFLAGS=-std1 -.endd -If you are compiling for just one operating system, it may be easier to put -these lines directly into \(Local/Makefile)\. - -Keeping all your local configuration settings separate from the distributed -files makes it easy to transfer them to new versions of Exim simply by copying -the contents of the \(Local)\ directory. - - -.index NIS lookup type||including support for -.index NIS@+ lookup type||including support for -.index LDAP||including support for -.index lookup||inclusion in binary -Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file -lookup, but not all systems have these components installed, so the default is -not to include the relevant code in the binary. All the different kinds of file -and database lookup that Exim supports are implemented as separate code modules -which are included only if the relevant compile-time options are set. In the -case of LDAP, NIS, and NIS+, the settings for \(Local/Makefile)\ are: -.display asis -LOOKUP_LDAP=yes -LOOKUP_NIS=yes -LOOKUP_NISPLUS=yes -.endd -and similar settings apply to the other lookup types. They are all listed in -\(src/EDITME)\. In most cases the relevant include files and interface -libraries need to be installed before compiling Exim. -.index cdb||including support for -However, in the case of cdb, which is included in the binary only if -.display asis -LOOKUP_CDB=yes -.endd -is set, the code is entirely contained within Exim, and no external include -files or libraries are required. When a lookup type is not included in the -binary, attempts to configure Exim to use it cause run time configuration -errors. - -.index Perl||including support for -Exim can be linked with an embedded Perl interpreter, allowing Perl -subroutines to be called during string expansion. To enable this facility, -.display asis -EXIM_PERL=perl.o -.endd -must be defined in \(Local/Makefile)\. Details of this facility are given in -chapter ~~CHAPperl. - -.index X11 libraries, location of -The location of the X11 libraries is something that varies a lot between -operating systems, and of course there are different versions of X11 to cope -with. Exim itself makes no use of X11, but if you are compiling the Exim -monitor, the X11 libraries must be available. -The following three variables are set in \(OS/Makefile-Default)\: -.display asis -X11=/usr/X11R6 -XINCLUDE=-I$(X11)/include -XLFLAGS=-L$(X11)/lib -.endd -These are overridden in some of the operating-system configuration files. For -example, in \(OS/Makefile-SunOS5)\ there is -.display asis -X11=/usr/openwin -XINCLUDE=-I$(X11)/include -XLFLAGS=-L$(X11)/lib -R$(X11)/lib -.endd -If you need to override the default setting for your operating system, place a -definition of all three of these variables into your -\(Local/Makefile-<<ostype>>)\ file. - -.index \\EXTRALIBS\\ -If you need to add any extra libraries to the link steps, these can be put in a -variable called \\EXTRALIBS\\, which appears in all the link commands, but by -default is not defined. In contrast, \\EXTRALIBS@_EXIM\\ is used only on the -command for linking the main Exim binary, and not for any associated utilities. -.index DBM||libraries, configuration for building -There is also \\DBMLIB\\, which appears in the link commands for binaries that -use DBM functions (see also section ~~SECTdb). Finally, there is -\\EXTRALIBS@_EXIMON\\, which appears only in the link step for the Exim monitor -binary, and which can be used, for example, to include additional X11 -libraries. - -.index configuration file||editing -The make file copes with rebuilding Exim correctly if any of the configuration -files are edited. However, if an optional configuration file is deleted, it is -necessary to touch the associated non-optional file (that is, \(Local/Makefile)\ -or \(Local/eximon.conf)\) before rebuilding. - -.section OS-specific header files -.index \(os.h)\ -.index building Exim||OS-specific C header files -The \(OS)\ directory contains a number of files with names of the form -\(os.h-<<ostype>>)\. These are system-specific C header files that should not -normally need to be changed. There is a list of macro settings that are -recognized in the file \(OS/os.configuring)\, which should be consulted if you -are porting Exim to a new operating system. - - -.section Overriding build-time options for the monitor -.index building Eximon||overriding default options -A similar process is used for overriding things when building the Exim monitor, -where the files that are involved are -.display rm -\(OS/eximon.conf-Default)\ -\(OS/eximon.conf-)\<<ostype>> -\(Local/eximon.conf)\ -\(Local/eximon.conf-)\<<ostype>> -\(Local/eximon.conf-)\<<archtype>> -\(Local/eximon.conf-)\<<ostype>>-<<archtype>> -.endd -.index \(Local/eximon.conf)\ -As with Exim itself, the final three files need not exist, and in this case the -\(OS/eximon.conf-<<ostype>>)\ file is also optional. The default values in -\(OS/eximon.conf-Default)\ can be overridden dynamically by setting environment -variables of the same name, preceded by \\EXIMON@_\\. For example, setting -\\EXIMON@_LOG@_DEPTH\\ in the environment overrides the value of -\\LOG@_DEPTH\\ at run time. - - - -.section Installing Exim binaries and scripts -.index installing Exim -.index \\BIN@_DIRECTORY\\ -The command \*make install*\ runs the \*exim@_install*\ script with no -arguments. The script copies binaries and utility scripts into the directory -whose name is specified by the \\BIN@_DIRECTORY\\ setting in -\(Local/Makefile)\. - -Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting -.index \\CONFIGURE@_FILE\\ -in \(Local/Makefile)\. If this names a single file, and the file does not -exist, the default configuration file \(src/configure.default)\ is copied there -by the installation script. If a run time configuration file already exists, it -is left alone. If \\CONFIGURE@_FILE\\ is a colon-separated list, naming several -alternative files, no default is installed. - -.index system aliases file -.index \(/etc/aliases)\ -One change is made to the default configuration file when it is installed: the -default configuration contains a router that references a system aliases file. -The path to this file is set to the value specified by -\\SYSTEM@_ALIASES@_FILE\\ in \(Local/Makefile)\ (\(/etc/aliases)\ by default). -If the system aliases file does not exist, the installation script creates it, -and outputs a comment to the user. - -The created file contains no aliases, but it does contain comments about the -aliases a site should normally have. Mail aliases have traditionally been -kept in \(/etc/aliases)\. However, some operating systems are now using -\(/etc/mail/aliases)\. You should check if yours is one of these, and change -Exim's configuration if necessary. - -The default configuration uses the local host's name as the only local domain, -and is set up to do local deliveries into the shared directory \(/var/mail)\, -running as the local user. System aliases and \(.forward)\ files in users' home -directories are supported, but no NIS or NIS+ support is configured. Domains -other than the name of the local host are routed using the DNS, with delivery -over SMTP. - -The install script copies files only if they are newer than the files they are -going to replace. The Exim binary is required to be owned by root and have the -\*setuid*\ bit set, -.index setuid||installing Exim with -for normal configurations. Therefore, you must run \*make install*\ as root so -that it can set up the Exim binary in this way. However, in some special -situations (for example, if a host is doing no local deliveries) it may be -possible to run Exim without making the binary setuid root (see chapter -~~CHAPsecurity for details). - -It is possible to install Exim for special purposes (such as building a binary -distribution) in a private part of the file system. You can do this by a -command such as -.display asis -make DESTDIR=/some/directory/ install -.endd -This has the effect of pre-pending the specified directory to all the file -paths, except the name of the system aliases file that appears in the default -configuration. (If a default alias file is created, its name \*is*\ modified.) -For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set, -but this usage is deprecated. - -.index installing Exim||what is not installed -Running \*make install*\ does not copy the Exim 4 conversion script -\*convert4r4*\, or the \*pcretest*\ test program. You will probably run the -first of these only once (if you are upgrading from Exim 3), and the second -isn't really part of Exim. None of the documentation files in the \(doc)\ -directory are copied, except for the info files when you have set -\\INFO@_DIRECTORY\\, as described in section ~~SECTinsinfdoc below. - -For the utility programs, old versions are renamed by adding the suffix \(.O)\ -to their names. The Exim binary itself, however, is handled differently. It is -installed under a name that includes the version number and the compile number, -for example \(exim-~~version-1)\. The script then arranges for a symbolic link -called \(exim)\ to point to the binary. If you are updating a previous version -of Exim, the script takes care to ensure that the name \(exim)\ is never absent -from the directory (as seen by other processes). - -.index installing Exim||testing the script -If you want to see what the \*make install*\ will do before running it for -real, you can pass the \-n-\ option to the installation script by this command: -.display asis -make INSTALL_ARG=-n install -.endd -The contents of the variable \\INSTALL@_ARG\\ are passed to the installation -script. You do not need to be root to run this test. Alternatively, you can run -the installation script directly, but this must be from within the build -directory. For example, from the top-level Exim directory you could use this -command: -.display -(cd build-SunOS5-5.5.1-sparc; ../scripts/exim@_install -n) -.endd - -.index installing Exim||install script options -There are two other options that can be supplied to the installation script. -.numberpars $. -\-no@_chown-\ bypasses the call to change the owner of the installed binary -to root, and the call to make it a setuid binary. -.nextp -\-no@_symlink-\ bypasses the setting up of the symbolic link \(exim)\ to the -installed binary. -.endp -\\INSTALL@_ARG\\ can be used to pass these options to the script. For example: -.display asis -make INSTALL_ARG=-no_symlink install -.endd - -The installation script can also be given arguments specifying which files are -to be copied. For example, to install just the Exim binary, and nothing else, -without creating the symbolic link, you could use: -.display asis -make INSTALL_ARG='-no_symlink exim' install -.endd - - -.section Installing info documentation -.rset SECTinsinfdoc "~~chapter.~~section" -.index installing Exim||\*info*\ documentation -Not all systems use the GNU \*info*\ system for documentation, and for this -reason, the Texinfo source of Exim's documentation is not included in the main -distribution. Instead it is available separately from the ftp site (see section -~~SECTavail). - -If you have defined \\INFO@_DIRECTORY\\ in \(Local/Makefile)\ and the Texinfo -source of the documentation is found in the source tree, running \*make -install*\ automatically builds the info files and installs them. - - -.section Setting up the spool directory -.index spool directory||creating -When it starts up, Exim tries to create its spool directory if it does not -exist. The Exim uid and gid are used for the owner and group of the spool -directory. Sub-directories are automatically created in the spool directory as -necessary. - - - -.section Testing -.index testing||installation -Having installed Exim, you can check that the run time configuration file is -syntactically valid by running the following command, which assumes that the -Exim binary directory is within your \\PATH\\ environment variable: -.display -exim -bV -.endd -If there are any errors in the configuration file, Exim outputs error messages. -Otherwise it outputs the version number and build date, -the DBM library that is being used, and information about which drivers and -other optional code modules are included in the binary. -Some simple routing tests can be done by using the address testing option. For -example, -.display -exim -bt <<local username>> -.endd -should verify that it recognizes a local mailbox, and -.display -exim -bt <<remote address>> -.endd -a remote one. Then try getting it to deliver mail, both locally and remotely. -This can be done by passing messages directly to Exim, without going through a -user agent. For example: -.display -exim -v postmaster@@your.domain.example -From: user@@your.domain.example -To: postmaster@@your.domain.example -Subject: Testing Exim - -This is a test message. -^D -.endd -The \-v-\ option causes Exim to output some verification of what it is doing. -In this case you should see copies of three log lines, one for the message's -arrival, one for its delivery, and one containing `Completed'. - -.index delivery||problems with -If you encounter problems, look at Exim's log files (\*mainlog*\ and -\*paniclog*\) to see if there is any relevant information there. Another source -of information is running Exim with debugging turned on, by specifying the -\-d-\ option. If a message is stuck on Exim's spool, you can force a delivery -with debugging turned on by a command of the form -.display -exim -d -M <<message-id>> -.endd -You must be root or an `admin user' in order to do this. The \-d-\ option -produces rather a lot of output, but you can cut this down to specific areas. -For example, if you use \-d-all+route-\ only the debugging information relevant -to routing is included. (See the \-d-\ option in chapter ~~CHAPcommandline for -more details.) - -.index `sticky' bit -.index lock files -One specific problem that has shown up on some sites is the inability to do -local deliveries into a shared mailbox directory, because it does not have the -`sticky bit' set on it. By default, Exim tries to create a lock file before -writing to a mailbox file, and if it cannot create the lock file, the delivery -is deferred. You can get round this either by setting the `sticky bit' on the -directory, or by setting a specific group for local deliveries and allowing -that group to create files in the directory (see the comments above the -\%local@_delivery%\ transport in the default configuration file). Another -approach is to configure Exim not to use lock files, but just to rely on -\*fcntl()*\ locking instead. However, you should do this only if all user -agents also use \*fcntl()*\ locking. For further discussion of locking issues, -see chapter ~~CHAPappendfile. - -One thing that cannot be tested on a system that is already running an MTA is -the receipt of incoming SMTP mail on the standard SMTP port. However, the -\-oX-\ option can be used to run an Exim daemon that listens on some other -port, or \*inetd*\ can be used to do this. The \-bh-\ option and the -\*exim@_checkaccess*\ utility can be used to check out policy controls on -incoming SMTP mail. - -Testing a new version on a system that is already running Exim can most easily -be done by building a binary with a different \\CONFIGURE@_FILE\\ setting. From -within the run time configuration, all other file and directory names -that Exim uses can be altered, in order to keep it entirely clear of the -production version. - -.section Replacing another MTA with Exim -.index replacing another MTA -Building and installing Exim for the first time does not of itself put it in -general use. The name by which the system's MTA is called by mail user agents -is either \(/usr/sbin/sendmail)\, or \(/usr/lib/sendmail)\ (depending on the -operating system), and it is necessary to make this name point to the \*exim*\ -binary in order to get the user agents to pass messages to Exim. This is -normally done by renaming any existing file and making \(/usr/sbin/sendmail)\ -or \(/usr/lib/sendmail)\ -.index symbolic link||to \*exim*\ binary -a symbolic link to the \*exim*\ binary. It is a good idea to remove any setuid -privilege and executable status from the old MTA. It is then necessary to stop -and restart the mailer daemon, if one is running. - -.index FreeBSD, MTA indirection -.index \(/etc/mail/mailer.conf)\ -Some operating systems have introduced alternative ways of switching MTAs. For -example, if you are running FreeBSD, you need to edit the file -\(/etc/mail/mailer.conf)\ instead of setting up a symbolic link as just -described. A typical example of the contents of this file for running Exim is -as follows: -.display asis -sendmail /usr/exim/bin/exim -send-mail /usr/exim/bin/exim -mailq /usr/exim/bin/exim -bp -newaliases /usr/bin/true -.endd - -Once you have set up the symbolic link, or edited \(/etc/mail/mailer.conf)\, -your Exim installation is `live'. Check it by sending a message from your -favourite user agent. - -You should consider what to tell your users about the change of MTA. Exim may -have different capabilities to what was previously running, and there are -various operational differences such as the text of messages produced by -command line options and in bounce messages. If you allow your users to make -use of Exim's filtering capabilities, you should make the document entitled -.if ~~html -[(A HREF="filter.html")] -.fi -\*Exim's interface to mail filtering*\ -.if ~~html -[(/A)] -.fi -available to them. - - -.section Upgrading Exim -.index upgrading Exim -If you are already running Exim on your host, building and installing a new -version automatically makes it available to MUAs, or any other programs that -call the MTA directly. However, if you are running an Exim daemon, you do need -to send it a HUP signal, to make it re-exec itself, and thereby pick up the new -binary. You do not need to stop processing mail in order to install a new -version of Exim. - - -.section Stopping the Exim daemon on Solaris -.index Solaris||stopping Exim on -The standard command for stopping the mailer daemon on Solaris is -.display -/etc/init.d/sendmail stop -.endd -If \(/usr/lib/sendmail)\ has been turned into a symbolic link, this script -fails to stop Exim because it uses the command \*ps -e*\ and greps the output -for the text `sendmail'; this is not present because the actual program name -(that is, `exim') is given by the \*ps*\ command with these options. A solution -is to replace the line that finds the process id with something like -.display asis -pid=`cat /var/spool/exim/exim-daemon.pid` -.endd -to obtain the daemon's pid directly from the file that Exim saves it in. - -Note, however, that stopping the daemon does not `stop Exim'. Messages can -still be received from local processes, and if automatic delivery is configured -(the normal case), deliveries will still occur. - - -. -. -. -. -. ============================================================================ -.chapter The Exim command line -.set runningfoot "command line" -.rset CHAPcommandline ~~chapter -.index command line||options -.index options||command line - -Exim's command line takes the standard Unix form of a sequence of options, -each starting with a hyphen character, followed by a number of arguments. The -options are compatible with the main options of Sendmail, and there are also -some additional options, some of which are compatible with Smail 3. Certain -combinations of options do not make sense, and provoke an error if used. -The form of the arguments depends on which options are set. - -.section Setting options by program name -.index \*mailq*\ -If Exim is called under the name \*mailq*\, it behaves as if the option \-bp-\ -were present before any other options. -The \-bp-\ option requests a listing of the contents of the mail queue on the -standard output. -This feature is for compatibility with some systems that contain a command of -that name in one of the standard libraries, symbolically linked to -\(/usr/sbin/sendmail)\ or \(/usr/lib/sendmail)\. - -.index \*rsmtp*\ -If Exim is called under the name \*rsmtp*\ it behaves as if the option \-bS-\ -were present before any other options, for compatibility with Smail. The \-bS-\ -option is used for reading in a number of messages in batched SMTP format. - -.index \*rmail*\ -If Exim is called under the name \*rmail*\ it behaves as if the \-i-\ and -\-oee-\ options were present before any other options, for compatibility with -Smail. The name \*rmail*\ is used as an interface by some UUCP systems. - -.index \*runq*\ -.index queue runner -If Exim is called under the name \*runq*\ it behaves as if the option \-q-\ were -present before any other options, for compatibility with Smail. The \-q-\ -option causes a single queue runner process to be started. - -.index \*newaliases*\ -.index alias file||building -.index Sendmail compatibility||calling Exim as \*newaliases*\ -If Exim is called under the name \*newaliases*\ it behaves as if the option -\-bi-\ were present before any other options, for compatibility with Sendmail. -This option is used for rebuilding Sendmail's alias file. Exim does not have -the concept of a single alias file, but can be configured to run a given -command if called with the \-bi-\ option. - -.section Trusted and admin users -.rset SECTtrustedadmin "~~chapter.~~section" -Some Exim options are available only to \*trusted users*\ and others are -available only to \*admin users*\. In the description below, the phrases `Exim -user' and `Exim group' mean the user and group defined by \\EXIM@_USER\\ and -\\EXIM@_GROUP\\ in \(Local/Makefile)\ or set by the \exim@_user\ and -\exim@_group\ options. These do not necessarily have to use the name `exim'. - -.numberpars $. -.index trusted user||definition of -.index user||trusted, definition of -The trusted users are root, the Exim user, any user listed in the -\trusted@_users\ configuration option, and any user whose current group or any -supplementary group is one of those listed in the \trusted@_groups\ -configuration option. Note that the Exim group is not automatically trusted. - -.index `From' line -.index envelope sender -Trusted users are always permitted to use the \-f-\ option or a leading `From ' -line to specify the envelope sender of a message that is passed to Exim through -the local interface (see the \-bm-\ and \-f-\ options below). See the -\untrusted@_set@_sender\ option for a way of permitting non-trusted users to -set envelope senders. -.index ::From:: header line -.index ::Sender:: header line -For a trusted user, there is never any check on the contents of the ::From:: -header line, and a ::Sender:: line is never added. Furthermore, any existing -::Sender:: line in incoming local (non-TCP/IP) messages is not removed. - -Trusted users may also specify a host name, host address, interface address, -protocol name, ident value, and authentication data when submitting a message -locally. Thus, they are able to insert messages into Exim's queue locally that -have the characteristics of messages received from a remote host. Untrusted -users may in some circumstances use \-f-\, but can never set the other values -that are available to trusted users. -.nextp -.index user||admin, definition of -.index admin user||definition of -The admin users are root, the Exim user, and any user that is a member of the -Exim group or of any group listed in the \admin@_groups\ configuration option. -The current group does not have to be one of these groups. - -Admin users are permitted to list the queue, and to carry out certain -operations on messages, for example, to force delivery failures. It is also -necessary to be an admin user in order to see the full information provided by -the Exim monitor, and full debugging output. - -By default, the use of the \-M-\, \-q-\, \-R-\, and \-S-\ options to cause Exim -to attempt delivery of messages on its queue is restricted to admin users. -However, this restriction can be relaxed by setting the \prod@_requires@_admin\ -option false (that is, specifying \no@_prod@_requires@_admin\). - -Similarly, the use of the \-bp-\ option to list all the messages in the queue -is restricted to admin users unless \queue@_list@_requires@_admin\ is set -false. -.endp - -\**Warning**\: If you configure your system so that admin users are able to -edit Exim's configuration file, you are giving those users an easy way of -getting root. There is further discussion of this issue at the start of chapter -~~CHAPconf. - - - -.section Command line options -The command options are described in alphabetical order below. - -.startoptions - -.option @- -.index options||command line, terminating -This is a pseudo-option whose only purpose is to terminate the options and -therefore to cause subsequent command line items to be treated as arguments -rather than options, even if they begin with hyphens. - -.option -help -This option causes Exim to output a few sentences stating what it is. -The same output is generated if the Exim binary is called with no options and -no arguments. - -.option B <<type>> -.index 8-bit characters -.index Sendmail compatibility||8-bit characters -This is a Sendmail option for selecting 7 or 8 bit processing. Exim is 8-bit -clean; it ignores this option. - -.option bd -.index daemon -.index SMTP listener -.index queue runner -This option runs Exim as a daemon, awaiting incoming SMTP connections. Usually -the \-bd-\ option is combined with the \-q-\<<time>> option, to specify that -the daemon should also initiate periodic queue runs. - -The \-bd-\ option can be used only by an admin user. If either of the \-d-\ -(debugging) or \-v-\ (verifying) options are set, the daemon does not -disconnect from the controlling terminal. When running this way, it can be -stopped by pressing ctrl-C. - -By default, Exim listens for incoming connections to the standard SMTP port on -all the host's running interfaces. However, it is possible to listen on other -ports, on multiple ports, and only on specific interfaces. Chapter -~~CHAPinterfaces contains a description of the options that control this. - -.index daemon||process id (pid) -.index pid (process id)||of daemon -When a listening daemon is started without the use of \-oX-\ (that is, without -overriding the normal configuration), it writes its process id to a file called -\(exim-daemon.pid)\ in Exim's spool directory. This location can be overridden -by setting \\PID@_FILE@_PATH\\ in \(Local/Makefile)\. The file is written while -Exim is still running as root. - -When \-oX-\ is used on the command line to start a listening daemon, the -process id is not written to the normal pid file path. However, \-oP-\ can be -used to specify a path on the command line if a pid file is required. - -.index \\SIGHUP\\ -The \\SIGHUP\\ signal can be used to cause the daemon to re-exec itself. This -should be done whenever Exim's configuration file, or any file that is -incorporated into it by means of the \.include\ facility, is changed, and also -whenever a new version of Exim is installed. It is not necessary to do this -when other files that are referenced from the configuration (for example, alias -files) are changed, because these are reread each time they are used. - -.option bdf -This option has the same effect as \-bd-\ except that it never disconnects from -the controlling terminal, even when no debugging is specified. - -.option be -.index testing||string expansion -.index expansion||testing -Run Exim in expansion testing mode. Exim discards its root privilege, to -prevent ordinary users from using this mode to read otherwise inaccessible -files. If no arguments are given, Exim runs interactively, prompting for lines -of data. -.em -If Exim was built with \\USE@_READLINE\\=yes in \(Local/Makefile)\, it tries -to load the \libreadline\ library dynamically whenever the \-be-\ option is -used without command line arguments. If successful, it uses the \*readline()*\ -function, which provides extensive line-editing facilities, for reading the -test data. A line history is supported. -.nem - -Long expansion expressions can be split over several lines by using backslash -continuations. As in Exim's run time configuration, whitespace at the start of -continuation lines is ignored. Each argument or data line is passed through the -string expansion mechanism, and the result is output. Variable values from the -configuration file (for example, \$qualify@_domain$\) are available, but no -message-specific values (such as \$domain$\) are set, because no message is -being processed. - -.option bF #<<filename>> -.index system filter||testing -.index testing||system filter -This option is the same as \-bf-\ except that it assumes that the filter being -tested is a system filter. The additional commands that are available only in -system filters are recognized. - -.option bf #<<filename>> -.index filter||testing -.index testing||filter file -.index forward file||testing -.index testing||forward file -.index Sieve filter||testing -This option runs Exim in user filter testing mode; the file is the filter file -to be tested, and a test message must be supplied on the standard input. If -there are no message-dependent tests in the filter, an empty file can be -supplied. -.em -If you want to test a system filter file, use \-bF-\ instead of \-bf-\. You can -use both \-bF-\ and \-bf-\ on the same command, in order to -test a system filter and a user filter in the same run. For example: -.display asis -exim -bF /system/filter -bf /user/filter </test/message -.endd -This is helpful when the system filter adds header lines or sets filter -variables that are used by the user filter. -.nem - -If the test filter file does not begin with one of the special lines -.display asis -# Exim filter -# Sieve filter -.endd -it is taken to be a normal \(.forward)\ file, and is tested for validity under -that interpretation. See sections ~~SECTitenonfilred to ~~SECTspecitredli for a -description of the possible contents of non-filter redirection lists. - -The result of an Exim command that uses \-bf-\, provided no errors are -detected, is a list of the actions that Exim would try to take if presented -with the message for real. More details of filter testing are given in the -separate document entitled \*Exim's interfaces to mail filtering*\. - -.index `From' line -.index envelope sender -.index \-f-\ option||for filter testing -When testing a filter file, the envelope sender can be set by the \-f-\ option, -or by a `From ' line at the start of the test message. Various parameters that -would normally be taken from the envelope recipient address of the message can -be set by means of additional command line options (see the next four options). - -.em -.option bfd #<<domain>> -This sets the domain of the recipient address when a filter file is being -tested by means of the \-bf-\ option. The default is the value of -\$qualify@_domain$\. - -.option bfl #<<local part>> -This sets the local part of the recipient address when a filter file is being -tested by means of the \-bf-\ option. The default is the username of the -process that calls Exim. A local part should be specified with any prefix or -suffix stripped, because that is how it appears to the filter when a message is -actually being delivered. - -.option bfp #<<prefix>> -This sets the prefix of the local part of the recipient address when a filter -file is being tested by means of the \-bf-\ option. The default is an empty -prefix. - -.option bfp #<<suffix>> -This sets the suffix of the local part of the recipient address when a filter -file is being tested by means of the \-bf-\ option. The default is an empty -suffix. -.em - - -.option bh #<<IP address>> -.index testing||incoming SMTP -.index SMTP||testing incoming -.index testing||relay control -.index relaying||testing configuration -.index policy control||testing -.index debugging||\-bh-\ option -This option runs a fake SMTP session as if from the given IP address, using the -standard input and output. The IP address may include a port number at the end, -after a full stop. For example: -.display asis -exim -bh 10.9.8.7.1234 -exim -bh fe80::a00:20ff:fe86:a061.5678 -.endd -.em -When an IPv6 address is given, it is converted into canonical form. In the case -of the second example above, the value of \$sender@_host@_address$\ after -conversion to the canonical form is \"fe80:0000:0000:0a00:20ff:fe86:a061.5678"\. -.nem - -Comments as to what is going on are written to the standard error file. These -include lines beginning with `LOG' for anything that would have been logged. -This facility is provided for testing configuration options for incoming -messages, to make sure they implement the required policy. For example, you can -test your relay controls using \-bh-\. - -.index RFC 1413 -\**Warning 1**\: You cannot test features of the configuration that rely on -ident (RFC 1413) callouts. These cannot be done when testing using -\-bh-\ because there is no incoming SMTP connection. - -\**Warning 2**\: Address verification callouts (see section ~~SECTcallver) are -also skipped when testing using \-bh-\. If you want these callouts to occur, -use \-bhc-\ instead. - -Messages supplied during the testing session are discarded, and nothing is -written to any of the real log files. There may be pauses when DNS (and other) -lookups are taking place, and of course these may time out. The \-oMi-\ option -can be used to specify a specific IP interface and port if this is important. - -The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\ whose -output just states whether a given recipient address from a given host is -acceptable or not. See section ~~SECTcheckaccess. - -.option bhc #<<IP address>> -This option operates in the same way as \-bh-\, except that address -verification callouts are performed if required. This includes consulting and -updating the callout cache database. - -.option bi -.index alias file||building -.index building alias file -.index Sendmail compatibility||\-bi-\ option -Sendmail interprets the \-bi-\ option as a request to rebuild its alias file. -Exim does not have the concept of a single alias file, and so it cannot mimic -this behaviour. However, calls to \(/usr/lib/sendmail)\ with the \-bi-\ option -tend to appear in various scripts such as NIS make files, so the option must be -recognized. - -If \-bi-\ is encountered, the command specified by the \bi@_command\ -configuration option is run, under the uid and gid of the caller of Exim. If -the \-oA-\ option is used, its value is passed to the command as an argument. -The command set by \bi@_command\ may not contain arguments. The command can use -the \*exim@_dbmbuild*\ utility, or some other means, to rebuild alias files if -this is required. If the \bi@_command\ option is not set, calling Exim with -\-bi-\ is a no-op. - -.option bm -.index local message reception -This option runs an Exim receiving process that accepts an incoming, -locally-generated message on the current input. The recipients are given as the -command arguments (except when \-t-\ is also present -- see below). Each -argument can be a comma-separated list of RFC 2822 addresses. This is the -default option for selecting the overall action of an Exim call; it is assumed -if no other conflicting option is present. - -If any addresses in the message are unqualified (have no domain), they are -qualified by the values of the \qualify@_domain\ or \qualify@_recipient\ -options, as appropriate. The \-bnq-\ option (see below) provides a way of -suppressing this for special cases. - -Policy checks on the contents of local messages can be enforced by means of the -non-SMTP ACL. See chapter ~~CHAPACL for details. -.index return code||for \-bm-\ -The return code is zero if the message is successfully accepted. Otherwise, the -action is controlled by the \-oe$it{x}-\ option setting -- see below. - -.index message||format -.index format||message -.index `From' line -.index UUCP||`From' line -.index Sendmail compatibility||`From' line -The format of the message must be as defined in RFC 2822, except that, for -compatibility with Sendmail and Smail, a line in one of the forms -.display -From sender Fri Jan 5 12:55 GMT 1997 -From sender Fri, 5 Jan 97 12:55:01 -.endd -(with the weekday optional, and possibly with additional text after the date) -is permitted to appear at the start of the message. There appears to be no -authoritative specification of the format of this line. Exim recognizes it by -matching against the regular expression defined by the \uucp@_from@_pattern\ -option, which can be changed if necessary. -.index \-f-\ option||overriding `From' line -The specified sender is treated as if it were given as the argument to the -\-f-\ option, but if a \-f-\ option is also present, its argument is used in -preference to the address taken from the message. The caller of Exim must be a -trusted user for the sender of a message to be set in this way. - -.option bnq -.index address||qualification, suppressing -By default, Exim automatically qualifies unqualified addresses (those -without domains) that appear in messages that are submitted locally (that -is, not over TCP/IP). This qualification applies both to addresses in -envelopes, and addresses in header lines. Sender addresses are qualified using -\qualify@_domain\, and recipient addresses using \qualify@_recipient\ (which -defaults to the value of \qualify@_domain\). - -Sometimes, qualification is not wanted. For example, if \-bS-\ (batch SMTP) is -being used to re-submit messages that originally came from remote hosts after -content scanning, you probably do not want to qualify unqualified addresses in -header lines. (Such lines will be present only if you have not enabled a header -syntax check in the appropriate ACL.) - -The \-bnq-\ option suppresses all qualification of unqualified addresses in -messages that originate on the local host. When this is used, unqualified -addresses in the envelope provoke errors (causing message rejection) and -unqualified addresses in header lines are left alone. - - -.option bP -.index configuration options, extracting -.index options||configuration, extracting -If this option is given with no arguments, it causes the values of all Exim's -main configuration options to be written to the standard output. The values -of one or more specific options can be requested by giving their names as -arguments, for example: -.display -exim -bP qualify@_domain hold@_domains -.endd -However, any option setting that is preceded by the word `hide' in the -configuration file is not shown in full, except to an admin user. For other -users, the output is as in this example: -.display asis -mysql_servers = <value not displayable> -.endd -If \configure@_file\ is given as an argument, the name of the run time -configuration file is output. -If a list of configuration files was supplied, the value that is output here -is the name of the file that was actually used. - -.index daemon||process id (pid) -.index pid (process id)||of daemon -If \log__file__path\ or \pid@_file@_path\ are given, the names of the -directories where log files and daemon pid files are written are output, -respectively. If these values are unset, log files are written in a -sub-directory of the spool directory called \log\, and the pid file is written -directly into the spool directory. - -If \-bP-\ is followed by a name preceded by \"+"\, for example, -.display asis -exim -bP +local_domains -.endd -it searches for a matching named list of any type (domain, host, address, or -local part) and outputs what it finds. - -.index options||router, extracting -.index options||transport, extracting -If one of the words \router\, \transport\, or \authenticator\ is given, -followed by the name of an appropriate driver instance, the option settings for -that driver are output. For example: -.display -exim -bP transport local@_delivery -.endd -The generic driver options are output first, followed by the driver's private -options. A list of the names of drivers of a particular type can be obtained by -using one of the words \router@_list\, \transport@_list\, or -\authenticator@_list\, and a complete list of all drivers with their option -settings can be obtained by using \routers\, \transports\, or \authenticators\. - - -.option bp -.index queue||listing messages on -.index listing||messages on the queue -This option requests a listing of the contents of the mail queue on the -standard output. If the \-bp-\ option is followed by a list of message ids, -just those messages are listed. By default, this option can be used only by an -admin user. However, the \queue__list__requires__admin\ option can be set false -to allow any user to see the queue. - -Each message on the queue is displayed as in the following example: -.display -25m 2.9K 0t5C6f-0000c8-00 <alice@@wonderland.fict.example> - red.king@@looking-glass.fict.example - <<other addresses>> -.endd -.index message||size in queue listing -.index size||of message -The first line contains the length of time the message has been on the queue -(in this case 25 minutes), the size of the message (2.9K), the unique local -identifier for the message, and the message sender, as contained in the -envelope. For bounce messages, the sender address is empty, and appears as -`<>'. If the message was submitted locally by an untrusted user who overrode -the default sender address, the user's login name is shown in parentheses -before the sender address. -.index frozen messages||in queue listing -If the message is frozen (attempts to deliver it are suspended) then the text -`$*$$*$$*$ frozen $*$$*$$*$' is displayed at the end of this line. - -The recipients of the message (taken from the envelope, not the headers) are -displayed on subsequent lines. Those addresses to which the message has already -been delivered are marked with the letter D. If an original address gets -expanded into several addresses via an alias or forward file, the original is -displayed with a D only when deliveries for all of its child addresses are -complete. - - -.option bpa -This option operates like \-bp-\, but in addition it shows delivered addresses -that were generated from the original top level address(es) in each message by -alias or forwarding operations. These addresses are flagged with `+D' instead -of just `D'. - - -.option bpc -.index queue||count of messages on -This option counts the number of messages on the queue, and writes the total -to the standard output. It is restricted to admin users, unless -\queue__list__requires__admin\ is set false. - - -.option bpr -This option operates like \-bp-\, but the output is not sorted into -chronological order of message arrival. This can speed it up when there are -lots of messages on the queue, and is particularly useful if the output is -going to be post-processed in a way that doesn't need the sorting. - -.option bpra -This option is a combination of \-bpr-\ and \-bpa-\. - -.option bpru -This option is a combination of \-bpr-\ and \-bpu-\. - - -.option bpu -This option operates like \-bp-\ but shows only undelivered top-level addresses -for each message displayed. Addresses generated by aliasing or forwarding are -not shown, unless the message was deferred after processing by a router with -the \one@_time\ option set. - - -.option brt -.index testing||retry configuration -.index retry||configuration testing -This option is for testing retry rules, and it must be followed by up to three -arguments. It causes Exim to look for a retry rule that matches the values -and to write it to the standard output. For example: -.display asis -exim -brt bach.comp.mus.example -Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; -.endd -See chapter ~~CHAPretry for a description of Exim's retry rules. The first -argument, which is required, can be a complete address in the form -\*local@_part@@domain*\, or it can be just a domain name. The second argument is -an optional second domain name; if no retry rule is found for the first -argument, the second is tried. This ties in with Exim's behaviour when looking -for retry rules for remote hosts -- if no rule is found that matches the host, -one that matches the mail domain is sought. The final argument is the name of a -specific delivery error, as used in setting up retry rules, for example -`quota@_3d'. - -.option brw -.index testing||rewriting -.index rewriting||testing -This option is for testing address rewriting rules, and it must be followed by -a single argument, consisting of either a local part without a domain, or a -complete address with a fully qualified domain. Exim outputs how this address -would be rewritten for each possible place it might appear. See chapter -~~CHAPrewrite for further details. - -.option bS -.index SMTP||batched incoming -.index batched SMTP input -This option is used for batched SMTP input, which is an alternative interface -for non-interactive local message submission. A number of messages can be -submitted in a single run. However, despite its name, this is not really SMTP -input. Exim reads each message's envelope from SMTP commands on the standard -input, but generates no responses. If the caller is trusted, or -\untrusted@_set@_sender\ is set, the senders in the SMTP \\MAIL\\ commands are -believed; otherwise the sender is always the caller of Exim. - -The message itself is read from the standard input, in SMTP format (leading -dots doubled), terminated by a line containing just a single dot. An error is -provoked if the terminating dot is missing. A further message may then follow. - -As for other local message submissions, the contents of incoming batch SMTP -messages can be checked using the non-SMTP ACL (see chapter ~~CHAPACL). -Unqualified addresses are automatically qualified using \qualify@_domain\ and -\qualify@_recipient\, as appropriate, unless the \-bnq-\ option is used. - -Some other SMTP commands are recognized in the input. \\HELO\\ and \\EHLO\\ act -as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\, and \\HELP\\ act as \\NOOP\\; -\\QUIT\\ quits, ignoring the rest of the standard input. - -If any error is encountered, reports are written to the standard output and -error streams, and Exim gives up immediately. -.index return code||for \-bS-\ -The return code is 0 if no error was detected; it is 1 if one or more messages -were accepted before the error was detected; otherwise it is 2. - -More details of input using batched SMTP are given in section -~~SECTincomingbatchedSMTP. - -.option bs -.index SMTP||local input -.index local SMTP input -This option causes Exim to accept one or more messages by reading SMTP commands -on the standard input, and producing SMTP replies on the standard output. SMTP -policy controls, as defined in ACLs (see chapter ~~CHAPACL) are applied. - -Some user agents use this interface as a way of passing locally-generated -messages to the MTA. -.index sender||source of -In this usage, if the caller of Exim is trusted, or \untrusted@_set@_sender\ is -set, the senders of messages are taken from the SMTP \\MAIL\\ commands. -Otherwise the content of these commands is ignored and the sender is set up as -the calling user. Unqualified addresses are automatically qualified using -\qualify@_domain\ and \qualify@_recipient\, as appropriate, unless the \-bnq-\ -option is used. - -.index inetd -The \-bs-\ option is also used to run Exim from \*inetd*\, as an alternative to -using a listening daemon. Exim can distinguish the two cases by checking -whether the standard input is a TCP/IP socket. When Exim is called from -\*inetd*\, the source of the mail is assumed to be remote, and the comments -above concerning senders and qualification do not apply. In this situation, -Exim behaves in exactly the same way as it does when receiving a message via -the listening daemon. - -.option bt -.index testing||addresses -.index address||testing -This option runs Exim in address testing mode, in which each argument is taken -as an address to be tested for deliverability. The results are written to the -standard output. If a test fails, and the caller is not an admin user, no -details of the failure are output, because these might contain sensitive -information such as usernames and passwords for database lookups. - -If no arguments are given, Exim runs in an interactive manner, prompting with a -right angle bracket for addresses to be tested. -.em -Unlike the \-be-\ test option, you cannot arrange for Exim to use the -\*readline()*\ function, because it is running as \*root*\ and there are -security issues. -.nem - -Each address is handled as if it were the recipient address of a message -(compare the \-bv-\ option). It is passed to the routers and the result is -written to the standard output. However, any router that has -\no@_address@_test\ set is bypassed. This can make \-bt-\ easier to use for -genuine routing tests if your first router passes everything to a scanner -program. - -.index return code||for \-bt-\ -The return code is 2 if any address failed outright; it is 1 if no address -failed outright but at least one could not be resolved for some reason. Return -code 0 is given only when all addresses succeed. - -\**Warning**\: \-bt-\ can only do relatively simple testing. If any of the -routers in the configuration makes any tests on the sender address of a -message, -.index \-f-\ option||for address testing -you can use the \-f-\ option to set an appropriate sender when running -\-bt-\ tests. Without it, the sender is assumed to be the calling user at the -default qualifying domain. However, if you have set up (for example) routers -whose behaviour depends on the contents of an incoming message, you cannot test -those conditions using \-bt-\. The \-N-\ option provides a possible way of -doing such tests. - -.option bV -.index version number of Exim, verifying -This option causes Exim to write the current version number, compilation -number, and compilation date of the \*exim*\ binary to the standard output. -It also lists the DBM library this is being used, the optional modules (such as -specific lookup types), the drivers that are included in the binary, and the -name of the run time configuration file that is in use. - -.em -As part of its operation, \-bV-\ causes Exim to read and syntax check its -configuration file. However, this is a static check only. It cannot check -values that are to be expanded. For example, although a misspelt ACL verb is -detected, an error in the verb's arguments is not. You cannot rely on \-bV-\ -alone to discover (for example) all the typos in the configuration; some -realistic testing is needed. The \-bh-\ and \-N-\ options provide more dynamic -testing facilities. -.nem - - -.option bv -.index verifying||address, using \-bv-\ -.index address||verification -This option runs Exim in address verification mode, in which each argument is -taken as an address to be verified. During normal operation, verification -happens mostly as a consequence processing a \verify\ condition in an ACL (see -chapter ~~CHAPACL). If you want to test an entire ACL, see the \-bh-\ option. - -If verification fails, and the caller is not an admin user, no details of the -failure are output, because these might contain sensitive information such as -usernames and passwords for database lookups. - -If no arguments are given, Exim runs in an interactive manner, prompting with a -right angle bracket for addresses to be verified. -.em -Unlike the \-be-\ test option, you cannot arrange for Exim to use the -\*readline()*\ function, because it is running as \*exim*\ and there are -security issues. -.nem - -Verification differs from address testing (the \-bt-\ option) in that routers -that have \no@_verify\ set are skipped, and if the address is accepted by a -router that has \fail@_verify\ set, verification fails. The address is verified -as a recipient if \-bv-\ is used; to test verification for a sender address, -\-bvs-\ should be used. - -If the \-v-\ option is not set, the output consists of a single line for each -address, stating whether it was verified or not, and giving a reason in the -latter case. Otherwise, more details are given of how the address has been -handled, and in the case of address redirection, all the generated addresses -are also considered. Without \-v-\, generating more than one address by -redirection causes verification to end sucessfully. - -.index return code||for \-bv-\ -The return code is 2 if any address failed outright; it is 1 if no address -failed outright but at least one could not be resolved for some reason. Return -code 0 is given only when all addresses succeed. - -If any of the routers in the configuration makes any tests on the sender -address of a message, you should use the \-f-\ option to set an appropriate -sender when running \-bv-\ tests. Without it, the sender is assumed to be the -calling user at the default qualifying domain. - -.option bvs -This option acts like \-bv-\, but verifies the address as a sender rather -than a recipient address. This affects any rewriting and qualification that -might happen. - -.option C #<<filelist>> -.index configuration file||alternate -.index \\CONFIGURE@_FILE\\ -.index alternate configuration file -This option causes Exim to find the run time configuration file from the given -list instead of from the list specified by the \\CONFIGURE@_FILE\\ -compile-time setting. Usually, the list will consist of just a single file -name, but it can be a colon-separated list of names. In this case, the first -file that exists is used. Failure to open an existing file stops Exim from -proceeding any further along the list, and an error is generated. - -When this option is used by a caller other than root or the Exim user, and the -list is different from the compiled-in list, Exim gives up its root privilege -immediately, and runs with the real and effective uid and gid set to those of -the caller. However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in -\(Local/Makefile)\, root privilege is retained for \-C-\ only if the caller of -Exim is root. -.em -That is, the Exim user is no longer privileged in this regard. This build-time -option is not set by default in the Exim source distribution tarbundle. -However, if you are using a `packaged' version of Exim (source or binary), the -packagers might have enabled it. -.nem - -Setting \\ALT@_CONFIG@_ROOT@_ONLY\\ locks out the possibility of testing a -configuration using \-C-\ right through message reception and delivery, even if -the caller is root. The reception works, but by that time, Exim is running as -the Exim user, so when it re-execs to regain privilege for the delivery, the -use of \-C-\ causes privilege to be lost. However, root can test reception and -delivery using two separate commands (one to put a message on the queue, using -\-odq-\, and another to do the delivery, using \-M-\). - -If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a -prefix string with which any file named in a \-C-\ command line option -must start. In addition, the file name must not contain the sequence \"/../"\. -However, if the value of the \-C-\ option is identical to the value of -\\CONFIGURE@_FILE\\ in \(Local/Makefile)\, Exim ignores \-C-\ and proceeds as -usual. There is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is -unset, any file name can be used with \-C-\. - -\\ALT@_CONFIG@_PREFIX\\ can be used to confine alternative configuration files -to a directory to which only root has access. This prevents someone who has -broken into the Exim account from running a privileged Exim with an arbitrary -configuration file. - -The \-C-\ facility is useful for ensuring that configuration files are -syntactically correct, but cannot be used for test deliveries, unless the -caller is privileged, or unless it is an exotic configuration that does not -require privilege. No check is made on the owner or group of the files -specified by this option. - -.option D <<macro>>=<<value>> -.index macro||setting on command line -This option can be used to override macro definitions in the configuration file -(see section ~~SECTmacrodefs). However, like \-C-\, if it is used by an -unprivileged caller, it causes Exim to give up its root privilege. -If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is -completely disabled, and its use causes an immediate error exit. - -The entire option (including equals sign if present) must all be within one -command line item. \-D-\ can be used to set the value of a macro to the empty -string, in which case the equals sign is optional. These two commands are -synonymous: -.display asis -exim -DABC ... -exim -DABC= ... -.endd -To include spaces in a macro definition item, quotes must be used. If you use -quotes, spaces are permitted around the macro name and the equals sign. For -example: -.display asis -exim '-D ABC = something' ... -.endd -\-D-\ may be repeated up to 10 times on a command line. - -.option d <<debug options>> -.index debugging||list of selectors -.index debugging||\-d-\ option -This option causes debugging information to be written to the standard -error stream. It is restricted to admin users because debugging output may show -database queries that contain password information. Also, the details of users' -filter files should be protected. When \-d-\ is used, \-v-\ is assumed. If -\-d-\ is given on its own, a lot of standard debugging data is output. This can -be reduced, or increased to include some more rarely needed information, by -following \-d-\ with a string made up of names preceded by plus or minus -characters. These add or remove sets of debugging data, respectively. For -example, \-d+filter-\ adds filter debugging, whereas \-d-all+filter-\ selects -only filter debugging. The available debugging categories are: -.display flow -.tabs 21 -. -. The odd formatting of the lines below is deliberate. It does not affect the -. SGCAL output, but by putting in the space it keeps things aligned in the man -. page that is automatically generated from this text. -. -acl $t $rm{ACL interpretation} -auth $t $rm{authenticators} -deliver $t $rm{general delivery logic} -dns $t $rm{DNS lookups (see also resolver)} -dnsbl $t $rm{DNS black list (aka RBL) code} -exec $t $rm{arguments for \execv@(@)\ calls} -expand $t $rm{detailed debugging for string expansions} -filter $t $rm{filter handling} -hints@_lookup $t $rm{hints data lookups} -host@_lookup $t $rm{all types of name-to-IP address handling} -ident $t $rm{ident lookup} -interface $t $rm{lists of local interfaces} -lists $t $rm{matching things in lists} -load $t $rm{system load checks} -local@_scan $t $rm{can be used by \*local@_scan()*\ (see chapter ~~CHAPlocalscan)} -lookup $t $rm{general lookup code and all lookups} -memory $t $rm{memory handling} -pid $t $rm{add pid to debug output lines} -process@_info $t $rm{setting info for the process log} -queue@_run $t $rm{queue runs} -receive $t $rm{general message reception logic} -resolver $t $rm{turn on the DNS resolver's debugging output} -retry $t $rm{retry handling} -rewrite $t $rm{address rewriting} -route $t $rm{address routing} -timestamp $t $rm{add timestamp to debug output lines} -tls $t $rm{TLS logic} -transport $t $rm{transports} -uid $t $rm{changes of uid/gid and looking up uid/gid} -verify $t $rm{address verification logic} - -all $t $rm{all of the above, and also \-v-\} -.endd -.index resolver, debugging output -.index DNS||resolver, debugging output -The \"resolver"\ option produces output only if the DNS resolver was compiled -with \\DEBUG\\ enabled. This is not the case in some operating systems. Also, -unfortunately, debugging output from the DNS resolver is written to stdout -rather than stderr. - -The default (\-d-\ with no argument) omits \"expand"\, \"filter"\, -\"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\. -However, the \"pid"\ selector is forced when debugging is turned on for a -daemon, which then passes it on to any re-executed Exims. Exim also -automatically adds the pid to debug lines when several remote deliveries are -run in parallel. - -The \"timestamp"\ selector causes the current time to be inserted at the start -of all debug output lines. This can be useful when trying to track down delays -in processing. - -If the \debug@_print\ option is set in any driver, it produces output whenever -any debugging is selected, or if \-v-\ is used. - -.em -.option dd <<debug options>> -This option behaves exactly like \-d-\ except when used on a command that -starts a daemon process. In that case, debugging is turned off for the -subprocesses that the daemon creates. Thus, it is useful for monitoring the -behaviour of the daemon without creating as much output as full debugging does. -.nem - -.option dropcr -This is an obsolete option that is now a no-op. It used to affect the way Exim -handled CR and LF characters in incoming messages. What happens now is -described in section ~~SECTlineendings. - - -.option E -.index bounce message||generating -This option specifies that an incoming message is a locally-generated delivery -failure report. It is used internally by Exim when handling delivery failures -and is not intended for external use. Its only effect is to stop Exim -generating certain messages to the postmaster, as otherwise message cascades -could occur in some situations. As part of the same option, a message id may -follow the characters \-E-\. If it does, the log entry for the receipt of the -new message contains the id, following `R=', as a cross-reference. - -.option e$it{x} -There are a number of Sendmail options starting with \-oe-\ which seem to be -called by various programs without the leading \o\ in the option. For example, -the \vacation\ program uses \-eq-\. Exim treats all options of the form -\-e$it{x}-\ as synonymous with the corresponding \-oe$it{x}-\ options. - -.option F #<<string>> -.index sender||name -.index name||of sender -This option sets the sender's full name for use when a locally-generated -message is being accepted. In the absence of this option, the user's \*gecos*\ -entry from the password data is used. As users are generally permitted to alter -their \*gecos*\ entries, no security considerations are involved. White space -between \-F-\ and the <<string>> is optional. - -.option f #<<address>> -.index sender||address -.index address||sender -.index trusted user -.index envelope sender -.index user||trusted -This option sets the address of the envelope sender of a locally-generated -message (also known as the return path). The option can normally be used only -by a trusted user, but \untrusted@_set@_sender\ can be set to allow untrusted -users to use it. -.em -Processes running as root or the Exim user are always trusted. Other -trusted users are defined by the \trusted@_users\ or \trusted@_groups\ options. - -In the absence of \-f-\, or if the caller is not trusted, the sender of a local -message is set to the caller's login name at the default qualify domain. - -There is one exception to the restriction on the use of \-f-\: an empty sender -can be specified by any user, trusted or not, -.nem -to create a message that can never provoke a bounce. An empty sender can be -specified either as an empty string, or as a pair of angle brackets with -nothing between them, as in these examples of shell commands: -.display asis -exim -f '<>' user@domain -exim -f "" user@domain -.endd -In addition, the use of \-f-\ is not restricted when testing a filter file with -\-bf-\ or when testing or verifying addresses using the \-bt-\ or \-bv-\ -options. - -Allowing untrusted users to change the sender address does not of itself make -it possible to send anonymous mail. Exim still checks that the ::From:: header -refers to the local user, and if it does not, it adds a ::Sender:: header, -though this can be overridden by setting \no@_local@_from@_check\. - -.index `From' line -White space between \-f-\ and the <<address>> is optional -(that is, they can be given as two arguments or one combined argument). -The sender of a locally-generated message can also be set (when permitted) by -an initial `From ' line in the message -- see the description of \-bm-\ above --- but if \-f-\ is also present, it overrides `From'. - -.option G -.index Sendmail compatibility||\-G-\ option ignored -This is a Sendmail option which is ignored by Exim. - -.option h #<<number>> -.index Sendmail compatibility||\-h-\ option ignored -This option is accepted for compatibility with Sendmail, but has no effect. (In -Sendmail it overrides the `hop count' obtained by counting ::Received:: -headers.) - -.option i -.index Solaris||\*mail*\ command -.index dot||in incoming, non-SMTP message -This option, which has the same effect as \-oi-\, specifies that a dot on a -line by itself should not terminate an incoming, non-SMTP message. I can find -no documentation for this option in Solaris 2.4 Sendmail, but the \*mailx*\ -command in Solaris 2.4 uses it. See also \-ti-\. - -.option M #<<message id>>#<<message id>> ... -.index forcing delivery -.index delivery||forcing attempt -.index frozen messages||forcing delivery -This option requests Exim to run a delivery attempt on each message in turn. If -any of the messages are frozen, they are automatically thawed before the -delivery attempt. The settings of \queue@_domains\, \queue@_smtp@_domains\, and -\hold@_domains\ are ignored. -.index hints database||overriding retry hints -Retry hints for any of the addresses are -overridden -- Exim tries to deliver even if the normal retry time has not yet -been reached. This option requires the caller to be an admin user. However, -there is an option called \prod@_requires@_admin\ which can be set false to -relax this restriction (and also the same requirement for the \-q-\, \-R-\, and -\-S-\ options). - - -.option Mar #<<message id>>#<<address>>#<<address>> ... -.index message||adding recipients -.index recipient||adding -This option requests Exim to add the addresses to the list of recipients of the -message (`ar' for `add recipients'). The first argument must be a message id, -and the remaining ones must be email addresses. However, if the message is -active (in the middle of a delivery attempt), it is not altered. This option -can be used only by an admin user. - -.index SMTP||passed connection -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -.option MC #<<transport>>#<<hostname>>#<<sequence number>>#<<message id>> -This option is not intended for use by external callers. It is used internally -by Exim to invoke another instance of itself to deliver a waiting message using -an existing SMTP connection, which is passed as the standard input. Details are -given in chapter ~~CHAPSMTP. This must be the final option, and the caller must -be root or the Exim user in order to use it. - -.option MCA -This option is not intended for use by external callers. It is used internally -by Exim in conjunction with the \-MC-\ option. It signifies that the connection -to the remote host has been authenticated. - -.option MCP -This option is not intended for use by external callers. It is used internally -by Exim in conjunction with the \-MC-\ option. It signifies that the server to -which Exim is connected supports pipelining. - -.option MCQ #<<process id>> <<pipe fd>> -This option is not intended for use by external callers. It is used internally -by Exim in conjunction with the \-MC-\ option when the original delivery was -started by a queue runner. It passes on the process id of the queue runner, -together with the file descriptor number of an open pipe. Closure of the pipe -signals the final completion of the sequence of processes that are passing -messages through the same SMTP connection. - -.option MCS -This option is not intended for use by external callers. It is used internally -by Exim in conjunction with the \-MC-\ option, and passes on the fact that the -SMTP \\SIZE\\ option should be used on messages delivered down the existing -connection. - -.option MCT -This option is not intended for use by external callers. It is used internally -by Exim in conjunction with the \-MC-\ option, and passes on the fact that the -host to which Exim is connected supports TLS encryption. - -.option Mc #<<message id>>#<<message id>> ... -.index hints database||not overridden by \-Mc-\ -.index delivery||manually started, not forced -This option requests Exim to run a delivery attempt on each message in turn, -but unlike the \-M-\ option, it does check for retry hints, and respects any -that are found. This option is not very useful to external callers. It is -provided mainly for internal use by Exim when it needs to re-invoke itself in -order to regain root privilege for a delivery (see chapter ~~CHAPsecurity). -However, \-Mc-\ can be useful when testing, in order to run a delivery that -respects retry times and other options such as \hold@_domains\ that are -overridden when \-M-\ is used. Such a delivery does not count as a queue run. -If you want to run a specific delivery as if in a queue run, you should use -\-q-\ with a message id argument. A distinction between queue run deliveries -and other deliveries is made in one or two places. - -.option Mes #<<message id>>#<<address>> -.index message||changing sender -.index sender||changing -This option requests Exim to change the sender address in the message to the -given address, which must be a fully qualified address or `<>' (`es' for `edit -sender'). There must be exactly two arguments. The first argument must be a -message id, and the second one an email address. However, if the message is -active (in the middle of a delivery attempt), its status is not altered. This -option can be used only by an admin user. - -.option Mf #<<message id>>#<<message id>> ... -.index freezing messages -.index message||manually freezing -This option requests Exim to mark each listed message as `frozen'. This -prevents any delivery attempts taking place until the message is `thawed', -either manually or as a result of the \auto@_thaw\ configuration option. -However, if any of the messages are active (in the middle of a delivery -attempt), their status is not altered. This option can be used only by an admin -user. - -.option Mg #<<message id>>#<<message id>> ... -.index giving up on messages -.index message||abandoning delivery attempts -.index delivery||abandoning further attempts -This option requests Exim to give up trying to deliver the listed messages, -including any that are frozen. However, if any of the messages are active, -their status is not altered. -For non-bounce messages, a delivery error message is sent to the sender, -containing the text `cancelled by administrator'. Bounce messages are just -discarded. -This option can be used only by an admin user. - -.option Mmad #<<message id>>#<<message id>> ... -.index delivery||cancelling all -This option requests Exim to mark all the recipient addresses in the messages -as already delivered (`mad' for `mark all delivered'). However, if any message -is active (in the middle of a delivery attempt), its status is not altered. -This option can be used only by an admin user. - -.option Mmd #<<message id>>#<<address>>#<<address>> ... -.index delivery||cancelling by address -.index recipient||removing -.index removing recipients -This option requests Exim to mark the given addresses as already delivered -(`md' for `mark delivered'). The first argument must be a message id, and the -remaining ones must be email addresses. These are matched to recipient -addresses in the message in a case-sensitive manner. If the message is active -(in the middle of a delivery attempt), its status is not altered. This option -can be used only by an admin user. - -.option Mrm #<<message id>>#<<message id>> ... -.index removing messages -.index abandoning mail -.index message||manually discarding -This option requests Exim to remove the given messages from the queue. No -bounce messages are sent; each message is simply forgotten. However, if any of -the messages are active, their status is not altered. This option can be used -only by an admin user or by the user who originally caused the message to be -placed on the queue. - -.option Mt #<<message id>>#<<message id>> ... -.index thawing messages -.index unfreezing messages -.index frozen messages||thawing -.index message||thawing frozen -This option requests Exim to `thaw' any of the listed messages that are -`frozen', so that delivery attempts can resume. However, if any of the messages -are active, their status is not altered. This option can be used only by an -admin user. - -.option Mvb #<<message id>> -.index listing||message body -.index message||listing body of -This option causes the contents of the message body (-D) spool file to be -written to the standard output. This option can be used only by an admin user. - -.option Mvh #<<message id>> -.index listing||message headers -.index header lines||listing -.index message||listing header lines -This option causes the contents of the message headers (-H) spool file to be -written to the standard output. This option can be used only by an admin user. - -.option Mvl #<<message id>> -.index listing||message log -.index message||listing message log -This option causes the contents of the message log spool file to be written to -the standard output. This option can be used only by an admin user. - -.option m -This is apparently a synonym for \-om-\ that is accepted by Sendmail, so Exim -treats it that way too. - -.option N -.index debugging||\-N-\ option -.index debugging||suppressing delivery -This is a debugging option that inhibits delivery of a message at the transport -level. It implies \-v-\. Exim goes through many of the motions of delivery -- -it just doesn't actually transport the message, but instead behaves as if it -had successfully done so. However, it does not make any updates to the retry -database, and the log entries for deliveries are flagged with `$*$>' rather -than `=>'. - -Because \-N-\ discards any message to which it applies, only root or the Exim -user are allowed to use it with \-bd-\, \-q-\, \-R-\ or \-M-\. In other words, -an ordinary user can use it only when supplying an incoming message to which it -will apply. Although transportation never fails when \-N-\ is set, an address -may be deferred because of a configuration problem on a transport, or a routing -problem. Once \-N-\ has been used for a delivery attempt, it sticks to the -message, and applies to any subsequent delivery attempts that may happen for -that message. - -.option n -.index Sendmail compatibility||\-n-\ option ignored -This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by -Exim. - -.option O #<<data>> -This option is interpreted by Sendmail to mean `set option`. It is ignored by -Exim. - -.option oA #<<file name>> -.index Sendmail compatibility||\-oA-\ option -This option is used by Sendmail in conjunction with \-bi-\ to specify an -alternative alias file name. Exim handles \-bi-\ differently; see the -description above. - -.index SMTP||passed connection -.option oB #<<n>> -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -This is a debugging option which limits the maximum number of messages that can -be delivered down one SMTP connection, overriding the value set in any \%smtp%\ -transport. If <<n>> is omitted, the limit is set to 1. - -.option odb -.index background delivery -.index delivery||in the background -This option applies to all modes in which Exim accepts incoming messages, -including the listening daemon. It requests `background' delivery of such -messages, which means that the accepting process automatically starts a -delivery process for each message received, but does not wait for the delivery -processes to finish. -.em -When all the messages have been received, the reception process exits, leaving -the delivery processes to finish in their own time. The standard output and -error streams are closed at the start of each delivery process. -.nem -This is the default action if none of the \-od-\ options are present. - -If one of the queueing options in the configuration file -(\queue@_only\ or \queue@_only@_file\, for example) is in effect, \-odb-\ -overrides it if \queue@_only@_override\ is set true, which is the default -setting. If \queue@_only@_override\ is set false, \-odb-\ has no effect. - -.option odf -.index foreground delivery -.index delivery||in the foreground -This option requests `foreground' (synchronous) delivery when Exim has accepted -a locally-generated message. (For the daemon it is exactly the same as -\-odb-\.) A delivery process is automatically started to deliver the -message, and Exim waits for it to complete before proceeding. -.em -The original Exim reception process does not finish until the delivery -process for the final message has ended. The standard error stream is left open -during deliveries. -.nem -However, like \-odb-\, this option has no effect if \queue@_only@_override\ is -false and one of the queueing options in the configuration file is in effect. - -.em -If there is a temporary delivery error during foreground delivery, the message -is left on the queue for later delivery, and the original reception process -exists. See chapter ~~CHAPnonqueueing for a way of setting up a restricted -configuration that never queues messages. -.nem - -.option odi -This option is synonymous with \-odf-\. It is provided for compatibility with -Sendmail. - -.option odq -.index non-immediate delivery -.index delivery||suppressing immediate -.index queueing incoming messages -This option applies to all modes in which Exim accepts incoming messages, -including the listening daemon. It specifies that the accepting process should -not automatically start a delivery process for each message received. Messages -are placed on the queue, and remain there until a subsequent queue runner -process encounters them. -There are several configuration options (such as \queue@_only\) that can be -used to queue incoming messages under certain conditions. This option overrides -all of them and also \-odqs-\. It always forces queueing. - -.option odqs -.index SMTP||delaying delivery -This option is a hybrid between \-odb-\/\-odi-\ and \-odq-\. -However, like \-odb-\ and \-odi-\, this option has no effect if -\queue@_only@_override\ is false and one of the queueing options in the -configuration file is in effect. - -When \-odqs-\ does operate, a delivery process is started for each incoming -message, in the background by default, but in the foreground if \-odi-\ is also -present. -The recipient addresses are routed, and local deliveries are done in the normal -way. However, if any SMTP deliveries are required, they are not done at this -time, so the message remains on the queue until a subsequent queue runner -process encounters it. Because routing was done, Exim knows which messages are -waiting for which hosts, and so a number of messages for the same host can be -sent in a single SMTP connection. The \queue@_smtp@_domains\ configuration -option has the same effect for specific domains. See also the \-qq-\ option. - -.option oee -.index error||reporting -If an error is detected while a non-SMTP message is being received (for -example, a malformed address), the error is reported to the sender in a mail -message. -.index return code||for \-oee-\ -Provided this error message is successfully sent, the Exim receiving process -exits with a return code of zero. If not, the return code is 2 if the problem -is that the original message has no recipients, or 1 any other error. This is -the default \-oe$it{x}-\ option if Exim is called as \*rmail*\. - -.option oem -.index error||reporting -.index return code||for \-oem-\ -This is the same as \-oee-\, except that Exim always exits with a non-zero -return code, whether or not the error message was successfully sent. -This is the default \-oe$it{x}-\ option, unless Exim is called as \*rmail*\. - -.option oep -.index error||reporting -If an error is detected while a non-SMTP message is being received, the -error is reported by writing a message to the standard error file (stderr). -.index return code||for \-oep-\ -The return code is 1 for all errors. - -.option oeq -.index error||reporting -This option is supported for compatibility with Sendmail, but has the same -effect as \-oep-\. - -.option oew -.index error||reporting -This option is supported for compatibility with Sendmail, but has the same -effect as \-oem-\. - -.option oi -.index dot||in incoming, non-SMTP message -This option, which has the same effect as \-i-\, specifies that a dot on a line -by itself should not terminate an incoming, non-SMTP message. -Otherwise, a single dot does terminate, though Exim does no special processing -for other lines that start with a dot. -This option is set by default if Exim is called as \*rmail*\. See also \-ti-\. - -.option oitrue -This option is treated as synonymous with \-oi-\. - -.option oMa #<<host address>> -.index sender||host address, specifying for local message -A number of options starting with \-oM-\ can be used to set values associated -with remote hosts on locally-submitted messages (that is, messages not received -over TCP/IP). These options can be used by any caller in conjunction with the -\-bh-\, -\-be-\, -\-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they -are ignored unless the caller is trusted. - -The \-oMa-\ option sets the sender host address. This may include a port number -at the end, after a full stop (period). For example: -.display asis -exim -bs -oMa 10.9.8.7.1234 -.endd -An alternative syntax is to enclose the IP address in square brackets, followed -by a colon and the port number: -.display asis -exim -bs -oMa [10.9.8.7]:1234 -.endd -The IP address is placed in the \$sender@_host@_address$\ variable, and the -port, if present, in \$sender@_host@_port$\. - -.option oMaa #<<name>> -.index authentication||name, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMaa-\ -option sets the value of \$sender@_host@_authenticated$\ (the authenticator -name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication. - -.option oMai #<<string>> -.index authentication||id, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\ -option sets the -value of \$authenticated@_id$\ (the id that was authenticated). -This overrides the default value (the caller's login id) for messages from -local sources. See chapter ~~CHAPSMTPAUTH for a discussion of authenticated -ids. - -.option oMas #<<address>> -.index authentication||sender, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMas-\ -option sets the authenticated sender value -in \$authenticated@_sender$\. -It overrides the sender address that is created from the caller's login id for -messages from local sources. See chapter ~~CHAPSMTPAUTH for a discussion of -authenticated senders. - -.option oMi #<<interface address>> -.index interface||address, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMi-\ -option sets the IP interface address value. A port number may be included, -using the same syntax as for \-oMa-\. -The interface address is placed in \$interface@_address$\ and the port number, -if present, in \$interface@_port$\. - -.option oMr #<<protocol name>> -.index protocol||incoming, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMr-\ -option sets the received protocol value that is stored in -\$received@_protocol$\. However, this applies only when \-bs-\ is not used. For -interactive SMTP input (\-bs-\), the protocol is always -.em -`local-' followed by one of the standard SMTP protocol names (see the -description of \$received@_protocol$\ in section ~~SECTexpvar). -.nem -For \-bS-\ (batch SMTP) however, the protocol can be set by \-oMr-\. - -.option oMs #<<host name>> -.index sender||host name, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMs-\ -option sets the sender host name -in \$sender@_host@_name$\. When this option is present, Exim does not attempt -to look up a host name from an IP address; it uses the name it is given. - -.option oMt #<<ident string>> -.index sender||ident string, specifying for local message -See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMt-\ -option sets the sender ident value -in \$sender@_ident$\. -The default setting for local callers is the login id of the calling process. - -.option om -.index Sendmail compatibility||\-om-\ option ignored -In Sendmail, this option means `me too', indicating that the sender of a -message should receive a copy of the message if the sender appears in an alias -expansion. Exim always does this, so the option does nothing. - -.option oo -.index Sendmail compatibility||\-oo-\ option ignored -This option is ignored. In Sendmail it specifies `old style headers', whatever -that means. - -.option oP #<<path>> -.index pid (process id)||of daemon -.index daemon||process id (pid) -This option is useful only in conjunction with \-bd-\ or \-q-\ with a time -value. The option specifies the file to which the process id of the daemon is -written. When \-oX-\ is used with \-bd-\, or when \-q-\ with a time is used -without \-bd-\, this is the only way of causing Exim to write a pid file, -because in those cases, the normal pid file is not used. - -.option or #<<time>> -.index timeout||for non-SMTP input -This option sets a timeout value for incoming non-SMTP messages. If it is not -set, Exim will wait forever for the standard input. The value can also be set -by the \receive@_timeout\ option. The format used for specifying times is -described in section ~~SECTtimeformat. - -.option os #<<time>> -.index timeout||for SMTP input -.index SMTP||timeout, input -This option sets a timeout value for incoming SMTP messages. The timeout -applies to each SMTP command and block of data. The value can also be set by -the \smtp@_receive@_timeout\ option; it defaults to 5 minutes. The format used -for specifying times is described in section ~~SECTtimeformat. - -.option ov -This option has exactly the same effect as \-v-\. - -.option oX #<<number or string>> -.index TCP/IP||setting listening ports -.index TCP/IP||setting listening interfaces -.index port||receiving TCP/IP -This option is relevant only when the \-bd-\ (start listening daemon) option is -also given. It controls which ports and interfaces the daemon uses. Details of -the syntax, and how it interacts with configuration file options, are given in -chapter ~~CHAPinterfaces. When \-oX-\ is used to start a daemon, no pid file is -written unless \-oP-\ is also present to specify a pid file name. - -.option pd -.index Perl||starting the interpreter -This option applies when an embedded Perl interpreter is linked with Exim (see -chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, -forcing the starting of the interpreter to be delayed until it is needed. - -.option ps -.index Perl||starting the interpreter -This option applies when an embedded Perl interpreter is linked with Exim (see -chapter ~~CHAPperl). It overrides the setting of the \perl@_at@_start\ option, -forcing the starting of the interpreter to occur as soon as Exim is started. - -.option p<<rval>>:<<sval>> -For compatibility with Sendmail, this option -is equivalent to -.display --oMr <<rval>> -oMs <<sval>> -.endd -It sets the incoming protocol and host name (for trusted callers). The -host name and its colon can be omitted when only the protocol is to be set. -Note the Exim already has two private options, \-pd-\ and \-ps-\, that refer to -embedded Perl. It is therefore impossible to set a protocol value of \"p"\ or -\"s"\ using this option (but that does not seem a real limitation). - -.option q -.index queue runner||starting manually -This option is normally restricted to admin users. However, there is a -configuration option called \prod@_requires@_admin\ which can be set false to -relax this restriction (and also the same requirement for the \-M-\, \-R-\, and -\-S-\ options). - -.index queue runner||description of operation -The \-q-\ option starts one queue runner process. This scans the queue of -waiting messages, and runs a delivery process for each one in turn. It waits -for each delivery process to finish before starting the next one. A delivery -process may not actually do any deliveries if the retry times for the addresses -have not been reached. Use \-qf-\ (see below) if you want to override this. -.index SMTP||passed connection -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -If the delivery process spawns other processes to deliver other messages down -passed SMTP connections, the queue runner waits for these to finish before -proceeding. - -When all the queued messages have been considered, the original queue runner -process terminates. In other words, a single pass is made over the waiting -mail, one message at a time. Use \-q-\ with a time (see below) if you want this -to be repeated periodically. - -Exim processes the waiting messages in an unpredictable order. It isn't very -random, but it is likely to be different each time, which is all that matters. -If one particular message screws up a remote MTA, other messages to the same -MTA have a chance of getting through if they get tried first. - -It is possible to cause the messages to be processed in lexical message id -order, which is essentially the order in which they arrived, by setting the -\queue@_run@_in@_order\ option, but this is not recommended for normal use. - -.option q <<qflags>> -The \-q-\ option may be followed by one or more flag letters that change its -behaviour. They are all optional, but if more than one is present, they must -appear in the correct order. Each flag is described in a separate item below. - -.option qq... -.index queue||double scanning -.index queue||routing -.index routing||whole queue before delivery -An option starting with \-qq-\ requests a two-stage queue run. In the first -stage, the queue is scanned as if the \queue@_smtp@_domains\ option matched -every domain. Addresses are routed, local deliveries happen, but no remote -transports are run. -.index hints database||remembering routing -The hints database that remembers which messages are -waiting for specific hosts is updated, as if delivery to those hosts had been -deferred. After this is complete, a second, normal queue scan happens, with -routing and delivery taking place as normal. Messages that are routed to the -same host should mostly be delivered down a single SMTP -.index SMTP||passed connection -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -connection because of the hints that were set up during the first queue scan. -This option may be useful for hosts that are connected to the Internet -intermittently. - -.option q[q]i... -.index queue||initial delivery -If the \*i*\ flag is present, the queue runner runs delivery processes only for -those messages that haven't previously been tried. (\*i*\ stands for `initial -delivery'.) This can be helpful if you are putting messages on the queue using -\-odq-\ and want a queue runner just to process the new messages. - -.option q[q][i]f... -.index queue||forcing delivery -.index delivery||forcing in queue run -If one \*f*\ flag is present, a delivery attempt is forced for each non-frozen -message, whereas without \f\ only those non-frozen addresses that have passed -their retry times are tried. - -.option q[q][i]ff... -.index frozen messages||forcing delivery -If \*ff*\ is present, a delivery attempt is forced for every message, whether -frozen or not. - -.option q[q][i][f[f]]l -.index queue||local deliveries only -The \*l*\ (the letter `ell') flag specifies that only local deliveries are to be -done. If a message requires any remote deliveries, it remains on the queue for -later delivery. - -.option q <<qflags>>#<<start id>>#<<end id>> -.index queue||delivering specific messages -When scanning the queue, Exim can be made to skip over messages whose ids are -lexically less than a given value by following the \-q-\ option with a starting -message id. For example: -.display -exim -q 0t5C6f-0000c8-00 -.endd -Messages that arrived earlier than \"0t5C6f-0000c8-00"\ are not inspected. If a -second message id is given, messages whose ids are lexically greater than it -are also skipped. If the same id is given twice, for example, -.display -exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 -.endd -just one delivery process is started, for that message. This differs from \-M-\ -in that retry data is respected, and it also differs from \-Mc-\ in that it -counts as a delivery from a queue run. Note that the selection mechanism does -not affect the order in which the messages are scanned. There are also other -ways of selecting specific sets of messages for delivery in a queue run -- see -\-R-\ and \-S-\. - -.option q <<qflags>><<time>> -.index queue runner||starting periodically -.index periodic queue running -When a time value is present, the \-q-\ option causes Exim to run as a daemon, -starting a queue runner process at intervals specified by the given time value -(whose format is described in section ~~SECTtimeformat). This form of the \-q-\ -option is commonly combined with the \-bd-\ option, in which case a single -daemon process handles both functions. A common way of starting up a combined -daemon at system boot time is to use a command such as -.display -/usr/exim/bin/exim -bd -q30m -.endd -Such a daemon listens for incoming SMTP calls, and also starts a queue runner -process every 30 minutes. - -When a daemon is started by \-q-\ with a time value, but without \-bd-\, no pid -file is written unless one is explicitly requested by the \-oP-\ option. - -.option qR <<rsflags>>#<<string>> -This option is synonymous with \-R-\. It is provided for Sendmail -compatibility. - -.option qS <<rsflags>>#<<string>> -This option is synonymous with \-S-\. - -.option R <<rsflags>>#<<string>> -.index queue runner||for specific recipients -.index delivery||to given domain -.index domain||delivery to -The <<rsflags>> may be empty, in which case the white space before the string -is optional, unless the string is \*f*\, \*ff*\, \*r*\, \*rf*\, or \*rff*\, -which are the possible values for <<rsflags>>. White space is required if -<<rsflags>> is not empty. - -This option is similar to \-q-\ with no time value, that is, it causes Exim to -perform a single queue run, except that, when scanning the messages on the -queue, Exim processes only those that have at least one undelivered recipient -address containing the given string, which is checked in a case-independent -way. If the <<rsflags>> start with \*r*\, <<string>> is interpreted as a regular -expression; otherwise it is a literal string. - -Once a message is selected, all its addresses are processed. For the first -selected message, Exim overrides any retry information and forces a delivery -attempt for each undelivered address. This means that if delivery of any -address in the first message is successful, any existing retry information is -deleted, and so delivery attempts for that address in subsequently selected -messages (which are processed without forcing) will run. However, if delivery -of any address does not succeed, the retry information is updated, and in -subsequently selected messages, the failing address will be skipped. - -If the <<rsflags>> contain \*f*\ or \*ff*\, the delivery forcing applies to all -selected messages, not just the first; -.index frozen messages||forcing delivery -frozen messages are included when \*ff*\ is present. - -The \-R-\ option makes it straightforward to initiate delivery of all messages -to a given domain after a host has been down for some time. When the SMTP -command \\ETRN\\ is accepted by its ACL (see chapter ~~CHAPACL), its default -effect is to run Exim with the \-R-\ option, but it can be configured to run an -arbitrary command instead. - -.option r -This is a documented (for Sendmail) obsolete alternative name for \-f-\. - -.index delivery||from given sender -.option S <<rsflags>>#<<string>> -.index queue runner||for specific senders -This option acts like \-R-\ except that it checks the string against each -message's sender instead of against the recipients. If \-R-\ is also set, both -conditions must be met for a message to be selected. If either of the options -has \*f*\ or \*ff*\ in its flags, the associated action is taken. - -.option Tqt#<<times>> -This an option that is exclusively for use by the Exim testing suite. -It is not recognized when Exim is run normally. It allows for the setting up -of explicit `queue times' so that various warning/retry features can be -tested. - -.option t -.index recipient||extracting from header lines -.index ::Bcc:: header line -.index ::Cc:: header line -.index ::To:: header line -When Exim is receiving a locally-generated, non-SMTP message on its standard -input, the \-t-\ option causes the recipients of the message to be obtained -from the ::To::, ::Cc::, and ::Bcc:: header lines in the message instead of from -the command arguments. The addresses are extracted before any rewriting takes -place. - -.index Sendmail compatibility||\-t-\ option -If the command has any arguments, they specify addresses to which the message -is $it{not} to be delivered. That is, the argument addresses are removed from -the recipients list obtained from the headers. This is compatible with Smail 3 -and in accordance with the documented behaviour of several versions of -Sendmail, as described in man pages on a number of operating systems (e.g. -Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail $it{add} -argument addresses to those obtained from the headers, and the O'Reilly -Sendmail book documents it that way. Exim can be made to add argument addresses -instead of subtracting them by setting the option -\extract__addresses__remove__arguments\ false. - -If a ::Bcc:: header line is present, it is removed from the message unless -there is no ::To:: or ::Cc::, in which case a ::Bcc:: line with no data is -created. This is necessary for conformity with the original RFC 822 standard; -the requirement has been removed in RFC 2822, but that is still very new. - -.index \Resent@-\ header lines||with \-t-\ -If there are any \Resent@-\ header lines in the message, Exim extracts -recipients from all ::Resent-To::, ::Resent-Cc::, and ::Resent-Bcc:: header -lines instead of from ::To::, ::Cc::, and ::Bcc::. This is for compatibility -with Sendmail and other MTAs. (Prior to release 4.20, Exim gave an error if -\-t-\ was used in conjunction with \Resent@-\ header lines.) - -RFC 2822 talks about different sets of \Resent@-\ header lines (for when a -message is resent several times). The RFC also specifies that they should be -added at the front of the message, and separated by ::Received:: lines. It is -not at all clear how \-t-\ should operate in the present of multiple sets, -nor indeed exactly what constitutes a `set'. -In practice, it seems that MUAs do not follow the RFC. The \Resent@-\ lines are -often added at the end of the header, and if a message is resent more than -once, it is common for the original set of \Resent@-\ headers to be renamed as -\X-Resent@-\ when a new set is added. This removes any possible ambiguity. - -.option ti -This option is exactly equivalent to \-t-\ \-i-\. It is provided for -compatibility with Sendmail. - -.option tls-on-connect -.index TLS||use without STARTTLS -.index TLS||automatic start -This option is available when Exim is compiled with TLS support. -.em -It forces all incoming SMTP connections to behave as if the incoming port is -listed in the \tls@_on@_connect@_ports\ option. See section ~~SECTsupobssmt and -chapter ~~CHAPTLS for further details. -.nem - -.option U -.index Sendmail compatibility||\-U-\ option ignored -Sendmail uses this option for `initial message submission', and its -documentation states that in future releases, it may complain about -syntactically invalid messages rather than fixing them when this flag is not -set. Exim ignores this option. - -.option v -This option causes Exim to write information to the standard error stream, -describing what it is doing. In particular, it shows the log lines for -receiving and delivering a message, and if an SMTP connection is made, the SMTP -dialogue is shown. Some of the log lines shown may not actually be written to -the log if the setting of \log@_selector\ discards them. Any relevant selectors -are shown with each log line. If none are shown, the logging is unconditional. - -.option x -AIX uses \-x-\ for a private purpose (`mail from a local mail program has -National Language Support extended characters in the body of the mail item'). -It sets \-x-\ when calling the MTA from its \mail\ command. Exim ignores this -option. - -.endoptions - - - -. -. -. -. -. ============================================================================ -.chapter The Exim run time configuration file -.set runningfoot "configuration file" -.rset CHAPconf ~~chapter - -.index run time configuration -.index configuration file||general description -.index \\CONFIGURE@_FILE\\ -.index configuration file||errors in -.index error||in configuration file -.index return code||for bad configuration -Exim uses a single run time configuration file that is read whenever an Exim -binary is executed. Note that in normal operation, this happens frequently, -because Exim is designed to operate in a distributed manner, without central -control. - -.em -If a syntax error is detected while reading the configuration file, Exim -writes a message on the standard error, and exits with a non-zero return code. -The message is also written to the panic log. \**Note**\: only simple syntax -errors can be detected at this time. The values of any expanded options are -not checked until the expansion happens, even when the expansion does not -actually alter the string. -.nem - - -The name of the configuration file is compiled into the binary for security -reasons, and is specified by the \\CONFIGURE@_FILE\\ compilation option. In -most configurations, this specifies a single file. However, it is permitted to -give a colon-separated list of file names, in which case Exim uses the first -existing file in the list. - -.index \\EXIM@_USER\\ -.index \\EXIM@_GROUP\\ -.index \\CONFIGURE@_OWNER\\ -.index \\CONFIGURE@_GROUP\\ -.index configuration file||ownership -.index ownership||configuration file -The run time configuration file must be owned by root or by the user that is -specified at compile time by the \\EXIM@_USER\\ option, or by the user that is -specified at compile time by the \\CONFIGURE@_OWNER\\ option (if set). The -configuration file must not be world-writeable or group-writeable, unless its -group is the one specified at compile time by the \\EXIM@_GROUP\\ option -.em -or by the \\CONFIGURE@_GROUP\\ option. -.nem - -\**Warning**\: In a conventional configuration, where the Exim binary is setuid -to root, anybody who is able to edit the run time configuration file has an -easy way to run commands as root. If you make your mail administrators members -of the Exim group, but do not trust them with root, make sure that the run time -configuration is not group writeable. - -A default configuration file, which will work correctly in simple situations, -is provided in the file \(src/configure.default)\. If \\CONFIGURE@_FILE\\ -defines just one file name, the installation process copies the default -configuration to a new file of that name if it did not previously exist. If -\\CONFIGURE@_FILE\\ is a list, no default is automatically installed. Chapter -~~CHAPdefconfil is a `walk-through' discussion of the default configuration. - - -.section Using a different configuration file -.index configuration file||alternate -A one-off alternate configuration can be specified by the \-C-\ command line -option, which may specify a single file or a list of files. However, when \-C-\ -is used, Exim gives up its root privilege, unless called by root or the Exim -user (or unless the argument for \-C-\ is identical to the built-in value from -\\CONFIGURE@_FILE\\). \-C-\ is useful mainly for checking the syntax of -configuration files before installing them. No owner or group checks are done -on a configuration file specified by \-C-\. - -The privileged use of \-C-\ by the Exim user can be locked out by setting -\\ALT@_CONFIG@_ROOT@_ONLY\\ in \(Local/Makefile)\ when building Exim. However, -if you do this, you also lock out the possibility of testing a -configuration using \-C-\ right through message reception and delivery, even if -the caller is root. The reception works, but by that time, Exim is running as -the Exim user, so when it re-execs to regain privilege for the delivery, the -use of \-C-\ causes privilege to be lost. However, root can test reception and -delivery using two separate commands (one to put a message on the queue, using -\-odq-\, and another to do the delivery, using \-M-\). - -If \\ALT@_CONFIG@_PREFIX\\ is defined \(in Local/Makefile)\, it specifies a -prefix string with which any file named in a \-C-\ command line option must -start. In addition, the file name must not contain the sequence \"/../"\. There -is no default setting for \\ALT@_CONFIG@_PREFIX\\; when it is unset, any file -name can be used with \-C-\. - -One-off changes to a configuration can be specified by the \-D-\ command line -option, which defines and overrides values for macros used inside the -configuration file. However, like \-C-\, the use of this option by a -non-privileged user causes Exim to discard its root privilege. -If \\DISABLE@_D@_OPTION\\ is defined in \(Local/Makefile)\, the use of \-D-\ is -completely disabled, and its use causes an immediate error exit. - -Some sites may wish to use the same Exim binary on different machines that -share a file system, but to use different configuration files on each machine. -If \\CONFIGURE@_FILE@_USE@_NODE\\ is defined in \(Local/Makefile)\, Exim first -looks for a file whose name is the configuration file name followed by a dot -and the machine's node name, as obtained from the \*uname()*\ function. If this -file does not exist, the standard name is tried. This processing occurs for -each file name in the list given by \\CONFIGURE@_FILE\\ or \-C-\. - -In some esoteric situations different versions of Exim may be run under -different effective uids and the \\CONFIGURE@_FILE@_USE@_EUID\\ is defined to -help with this. See the comments in \(src/EDITME)\ for details. - - -.section Configuration file format -.rset SECTconffilfor "~~chapter.~~section" -.index configuration file||format of -.index format||configuration file -Exim's configuration file is divided into a number of different parts. General -option settings must always appear at the start of the file. The other parts -are all optional, and may appear in any order. Each part other than the first -is introduced by the word `begin' followed by the name of the part. The -optional parts are: - -.numberpars $. -\*ACL*\: Access control lists for controlling incoming SMTP mail. -.nextp -.index \\AUTH\\||configuration -\*authenticators*\: Configuration settings for the authenticator drivers. These -are concerned with the SMTP \\AUTH\\ command (see chapter ~~CHAPSMTPAUTH). -.nextp -\*routers*\: Configuration settings for the router drivers. Routers process -addresses and determine how the message is to be delivered. -.nextp -\*transports*\: Configuration settings for the transport drivers. Transports -define mechanisms for copying messages to destinations. -.nextp -\*retry*\: Retry rules, for use when a message cannot be immediately delivered. -.nextp -\*rewrite*\: Global address rewriting rules, for use when a message arrives and -when new addresses are generated during delivery. -.nextp -\*local@_scan*\: Private options for the \*local@_scan()*\ function. If you -want to use this feature, you must set -.display asis -LOCAL_SCAN_HAS_OPTIONS=yes -.endd -in \(Local/Makefile)\ before building Exim. Full details of the -\*local@_scan()*\ facility are given in chapter ~~CHAPlocalscan. -.endp -.index configuration file||leading whitespace in -.index configuration file||trailing whitespace in -.index whitespace||in configuration file -.em -Leading and trailing whitespace in configuration lines is always ignored. -.nem -Blank lines in the file, and lines starting with a @# character (ignoring -leading white space) are treated as comments and are ignored. \**Note**\: a -@# character other than at the beginning of a line is not treated specially, -and does not introduce a comment. - -Any non-comment line can be continued by ending it with a backslash. -.em -Note that the general rule for whitespace means that trailing white space after -the backslash is ignored, and leading white space at the start of continuation -lines is also ignored. -.nem -Comment lines beginning with @# (but not empty lines) may appear in the middle -of a sequence of continuation lines. - -A convenient way to create a configuration file is to start from the -default, which is supplied in \(src/configure.default)\, and add, delete, or -change settings as required. - -The ACLs, retry rules, and rewriting rules have their own syntax which is -described in chapters ~~CHAPACL, ~~CHAPretry, and ~~CHAPrewrite, respectively. -The other parts of the configuration file have some syntactic items in common, -and these are described below, from section ~~SECTcos onwards. Before that, the -inclusion, macro, and conditional facilities are described. - - -.section File inclusions in the configuration file -.index inclusions in configuration file -.index configuration file||including other files -.index .include in configuration file -.index .include@_if@_exists in configuration file -You can include other files inside Exim's run time configuration file by -using this syntax: -.display -@.include <<file name>> -.endd -or -.display -@.include@_if@_exists <<file name>> -.endd -on a line by itself. Double quotes round the file name are optional. If you use -the first form, a configuration error occurs if the file does not exist; the -second form does nothing for non-existent files. - -Includes may be nested to any depth, but remember that Exim reads its -configuration file often, so it is a good idea to keep them to a minimum. -If you change the contents of an included file, you must HUP the daemon, -because an included file is read only when the configuration itself is read. - -The processing of inclusions happens early, at a physical line level, so, like -comment lines, an inclusion can be used in the middle of an option setting, -for example: -.display asis -hosts_lookup = a.b.c \ - .include /some/file -.endd -Include processing happens -after -macro processing (see below). Its effect is to process the lines of the file as -if they occurred inline where the inclusion appears. - - -.section Macros in the configuration file -.rset SECTmacrodefs "~~chapter.~~section" -.index macro||description of -.index configuration file||macros -If a line in the main part of the configuration (that is, before the first -`begin' line) begins with an upper case letter, it is taken as a macro -definition, and must be of the form -.display -<<name>> = <<rest of line>> -.endd -The name must consist of letters, digits, and underscores, and need not all be -in upper case, though that is recommended. The rest of the line, including any -continuations, is the replacement text, and has leading and trailing white -space removed. Quotes are not removed. The replacement text can never end with -a backslash character, but this doesn't seem to be a serious limitation. - -Once a macro is defined, all subsequent lines in the file (and any included -files) are scanned for the macro name; if there are several macros, the line is -scanned for each in turn, in the order in which they are defined. The -replacement text is not re-scanned for the current macro, though it is scanned -for subsequently defined macros. For this reason, a macro name may not contain -the name of a previously defined macro as a substring. You could, for example, -define -.display asis -ABCD_XYZ = <<something>> -ABCD = <<something else>> -.endd -but putting the definitions in the opposite order would provoke a configuration -error. - -Macro expansion is applied to individual lines from the file, before checking -for line continuation or file inclusion (see below). If a line consists solely -of a macro name, and the expansion of the macro is empty, the line is ignored. -A macro at the start of a line may turn the line into a comment line or a -\".include"\ line. - -As an example of macro usage, consider a configuration where aliases are looked -up in a MySQL database. It helps to keep the file less cluttered if long -strings such as SQL statements are defined separately as macros, for example: -.display asis -ALIAS_QUERY = select mailbox from user where \ - login=${quote_mysql:$local_part}; -.endd -This can then be used in a \%redirect%\ router setting like this: -.display asis -data = ${lookup mysql{ALIAS_QUERY}} -.endd -In earlier versions of Exim macros were sometimes used for domain, host, or -address lists. In Exim 4 these are handled better by named lists -- see section -~~SECTnamedlists. - -Macros in the configuration file can be overridden by the \-D-\ command line -option, but Exim gives up its root privilege when \-D-\ is used, unless called -by root or the Exim user. - - -.section Conditional skips in the configuration file -.index configuration file||conditional skips -.index .ifdef -You can use the directives \".ifdef"\, \".ifndef"\, \".elifdef"\, -\".elifndef"\, \".else"\, and \".endif"\ to dynamically include or exclude -portions of the configuration file. The processing happens whenever the file is -read (that is, when an Exim binary starts to run). - -The implementation is very simple. Instances of the first four directives must -be followed by text that includes the names of one or macros. The condition -that is tested is whether or not any macro substitution has taken place in the -line. Thus: -.display -@.ifdef AAA -message@_size@_limit = 50M -@.else -message@_size@_limit = 100M -@.endif -.endd -sets a message size limit of 50M if the macro \"AAA"\ is defined, and 100M -otherwise. If there is more than one macro named on the line, the condition -is true if any of them are defined. That is, it is an `or' condition. To -obtain an `and' condition, you need to use nested \".ifdef"\s. - -Although you can use a macro expansion to generate one of these directives, -it is not very useful, because the condition `there was a macro substitution -in this line' will always be true. - -Text following \".else"\ and \".endif"\ is ignored, and can be used as comment -to clarify complicated nestings. - - -.section Common option syntax -.rset SECTcos "~~chapter.~~section" -.index common option syntax -.index syntax of common options -.index configuration file||common option syntax -For the main set of options, driver options, and \*local@_scan()*\ options, -each setting is on a line by itself, and starts with a name consisting of -lower-case letters and underscores. Many options require a data value, and in -these cases the name must be followed by an equals sign (with optional white -space) and then the value. For example: -.display asis -qualify_domain = mydomain.example.com -.endd -Some option settings may contain sensitive data, for example, passwords for -accessing databases. To stop non-admin users from using the \-bP-\ command line -option to read these values, you can precede the option settings with the word -`hide'. For example: -.display asis -hide mysql_servers = localhost/users/admin/secret-password -.endd -For non-admin users, such options are displayed like this: -.display asis -mysql_servers = <value not displayable> -.endd -If `hide' is used on a driver option, it hides the value of that option on all -instances of the same driver. - -The following sections describe the syntax used for the different data types -that are found in option settings. - -.section Boolean options -.index format||boolean -.index boolean configuration values -Options whose type is given as boolean are on/off switches. There are two -different ways of specifying such options: with and without a data value. If -the option name is specified on its own without data, the switch is turned on; -if it is preceded by `no@_' or `not@_' the switch is turned off. However, -boolean options may optionally be followed by an equals sign and one of the -words `true', `false', `yes', or `no', as an alternative syntax. For example, -the following two settings have exactly the same effect: -.display asis -queue_only -queue_only = true -.endd -The following two lines also have the same (opposite) effect: -.display asis -no_queue_only -queue_only = false -.endd -You can use whichever syntax you prefer. - - - -.section Integer values -.index integer configuration values -.index format||integer -If an integer data item starts with the characters `0x', the remainder of it -is interpreted as a hexadecimal number. Otherwise, it is treated as octal if it -starts with the digit 0, and decimal if not. If an integer value is followed by -the letter K, it is multiplied by 1024; if it is followed by the letter M, it -is multiplied by 1024x1024. - -When the values of integer option settings are output, values which are an -exact multiple of 1024 or 1024x1024 are -sometimes, but not always, -printed using the letters K and M. The printing style is independent of the -actual input format that was used. - -.section Octal integer values -.index integer format -.index format||octal integer -The value of an option specified as an octal integer is always interpreted in -octal, whether or not it starts with the digit zero. Such options are always -output in octal. - - -.section Fixed point number values -.index fixed point configuration values -.index format||fixed point -A fixed point number consists of a decimal integer, optionally followed by a -decimal point and up to three further digits. - - -.section Time interval values -.index time interval||specifying in configuration -.index format||time interval -.rset SECTtimeformat "~~chapter.~~section" -A time interval is specified as a sequence of numbers, each followed by one of -the following letters, with no intervening white space: -.display rm -.tabs 5 -\s\ $t seconds -\m\ $t minutes -\h\ $t hours -\d\ $t days -\w\ $t weeks -.endd -For example, `3h50m' specifies 3 hours and 50 minutes. The values of time -intervals are output in the same format. -Exim does not restrict the values; it is perfectly acceptable, for example, to -specify `90m' instead of `1h30m'. - - -.section String values -.index string||format of configuration values -.index format||string -.rset SECTstrings "~~chapter.~~section" -If a string data item does not start with a double-quote character, it is taken -as consisting of the remainder of the line plus any continuation lines, -starting at the first character after any leading white space, with trailing -white space characters removed, and with no interpretation of the characters in -the string. Because Exim removes comment lines (those beginning with @#) at an -early stage, they can appear in the middle of a multi-line string. The -following settings are therefore equivalent: -.display asis -trusted_users = uucp:mail - -trusted_users = uucp:\ - # This comment line is ignored - mail -.endd -.index string||quoted -.index escape characters in quoted strings -If a string does start with a double-quote, it must end with a closing -double-quote, and any backslash characters other than those used for line -continuation are interpreted as escape characters, as follows: -.display -.tabs 15 -@\@\ $t $rm{single backslash} -@\n $t $rm{newline} -@\r $t $rm{carriage return} -@\t $t $rm{tab} -@\<<octal digits>> $t $rm{up to 3 octal digits specify one character} -@\x<<hex digits>> $t $rm{up to 2 hexadecimal digits specify one character} -.endd -If a backslash is followed by some other character, including a double-quote -character, that character replaces the pair. - -Quoting is necessary only if you want to make use of the backslash escapes to -insert special characters, or if you need to specify a value with leading or -trailing spaces. These cases are rare, so quoting is almost never needed in -current versions of Exim. In versions of Exim before 3.14, quoting was required -in order to continue lines, so you may come across older configuration files -and examples that apparently quote unnecessarily. - -.section Expanded strings -.index string||expansion, definition of -.index expansion||definition of -Some strings in the configuration file are subjected to \*string expansion*\, -by which means various parts of the string may be changed according to the -circumstances (see chapter ~~CHAPexpand). The input syntax for such strings is -as just described; in particular, the handling of backslashes in quoted strings -is done as part of the input process, before expansion takes place. However, -backslash is also an escape character for the expander, so any backslashes that -are required for that reason must be doubled if they are within a quoted -configuration string. - -.section User and group names -.index user name||format of -.index format||user name -.index group||name format -.index format||group name -User and group names are specified as strings, using the syntax described -above, but the strings are interpreted specially. A user or group name must -either consist entirely of digits, or be a name that can be looked up using the -\*getpwnam()*\ or \*getgrnam()*\ function, as appropriate. - -.section List construction -.index list||syntax of in configuration -.index format||list item in configuration -.index string list, definition -.rset SECTlistconstruct "~~chapter.~~section" -The data for some configuration options is a list of items, with colon as the -default separator. Many of these options are shown with type `string list' in -the descriptions later in this document. Others are listed as `domain list', -`host list', `address list', or `local part list'. Syntactically, they are all -the same; however, those other than `string list' are subject to particular -kinds of interpretation, as described in chapter ~~CHAPdomhosaddlists. - -In all these cases, the entire list is treated as a single string as far as the -input syntax is concerned. The \trusted@_users\ setting in section -~~SECTstrings above is an example. If a colon is actually needed in an item in -a list, it must be entered as two colons. Leading and trailing white space on -each item in a list is ignored. This makes it possible to include items that -start with a colon, and in particular, certain forms of IPv6 address. For -example, the list -.display asis -local_interfaces = 127.0.0.1 : ::::1 -.endd -contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address -@:@:1. -.index list||separator, changing -.index IPv6||addresses in lists -Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was -introduced to allow the separator character to be changed. If a list begins -with a left angle bracket, followed by any punctuation character, that -character is used instead of colon as the list separator. For example, the list -above can be rewritten to use a semicolon separator like this: -.display asis -local_interfaces = <; 127.0.0.1 ; ::1 -.endd -This facility applies to all lists, with the exception of the list in -\log@_file@_path\. It is recommended that the use of non-colon separators be -confined to circumstances where they really are needed. - - -.em -.section Empty items in lists -.rset SECTempitelis "~~chapter.~~section" -.index list||empty item in -An empty item at the end of a list is always ignored. In other words, trailing -separator characters are ignored. Thus, the list in -.display asis -senders = user@domain : -.endd -contains only a single item. If you want to include an empty string as one item -in a list, it must not be the last item. For example, this list contains three -items, the second of which is empty: -.display asis -senders = user1@domain : : user2@domain -.endd -\**Note**\: there must be whitespace between the two colons, as otherwise they -are interpreted as representing a single colon data character (and the list -would then contain just one item). If you want to specify a list that contains -just one, empty item, you can do it as in this example: -.display asis -senders = : -.endd -In this case, the first item is empty, and the second is discarded because it -is at the end of the list. -.nem - - -.section Format of driver configurations -.rset SECTfordricon "~~chapter.~~section" -.index drivers||configuration format -There are separate parts in the configuration for defining routers, transports, -and authenticators. In each part, you are defining a number of driver -instances, each with its own set of options. Each driver instance is defined by -a sequence of lines like this: -.display -<<instance name>>: - <<option>> - ... - <<option>> -.endd -In the following example, the instance name is \%localuser%\, and it is -followed by three options settings: -.display asis -localuser: - driver = accept - check_local_user - transport = local_delivery -.endd -For each driver instance, you specify which Exim code module it uses -- by the -setting of the \driver\ option -- and (optionally) some configuration settings. -For example, in the case of transports, if you want a transport to deliver with -SMTP you would use the \%smtp%\ driver; if you want to deliver to a local file -you would use the \%appendfile%\ driver. Each of the drivers is described in -detail in its own separate chapter later in this manual. - -You can have several routers, transports, or authenticators that are based on -the same underlying driver (each must have a different name). - -The order in which routers are defined is important, because addresses are -passed to individual routers one by one, in order. The order in which -transports are defined does not matter at all. The order in which -authenticators are defined is used only when Exim, as a client, is searching -them to find one that matches an authentication mechanism offered by the -server. - -.index generic options -.index options||generic, definition of -Within a driver instance definition, there are two kinds of option: -$it{generic} and $it{private}. The generic options are those that apply to all -drivers of the same type (that is, all routers, all transports or all -authenticators). -The \driver\ option is a generic option that must appear in every definition. -.index private options -The private options are special for each driver, and none need appear, because -they all have default values. - -The options may appear in any order, except that the \driver\ option must -precede any private options, since these depend on the particular driver. For -this reason, it is recommended that \driver\ always be the first option. - -Driver instance names, which are used for reference in log entries and -elsewhere, can be any sequence of letters, digits, and underscores (starting -with a letter) and must be unique among drivers of the same type. A router and -a transport (for example) can each have the same name, but no two router -instances can have the same name. The name of a driver instance should not be -confused with the name of the underlying driver module. For example, the -configuration lines: -.display asis -remote_smtp: - driver = smtp -.endd -create an instance of the \%smtp%\ transport driver whose name is -\%remote@_smtp%\. The same driver code can be used more than once, with -different instance names and different option settings each time. A second -instance of the \%smtp%\ transport, with different options, might be defined -thus: -.display asis -special_smtp: - driver = smtp - port = 1234 - command_timeout = 10s -.endd -The names \%remote@_smtp%\ and \%special@_smtp%\ would be used to reference -these transport instances from routers, and these names would appear in log -lines. - -Comment lines may be present in the middle of driver specifications. The full -list of option settings for any particular driver instance, including all the -defaulted values, can be extracted by making use of the \-bP-\ command line -option. - - - - - - -. -. -. -. -. ============================================================================ -.chapter The default configuration file -.set runningfoot "default configuration" -.rset CHAPdefconfil "~~chapter" -.index configuration file||default, `walk through' -.index default||configuration file `walk through' -The default configuration file supplied with Exim as \(src/configure.default)\ -is sufficient for a host with simple mail requirements. As an introduction to -the way Exim is configured, this chapter `walks through' the default -configuration, giving brief explanations of the settings. Detailed descriptions -of the options are given in subsequent chapters. The default configuration file -itself contains extensive comments about ways you might want to modify the -initial settings. However, note that there are many options that are not -mentioned at all in the default configuration. - - -.section Main configuration settings -The main (global) configuration option settings must always come first in the -file. The first thing you'll see in the file, after some initial comments, is -the line -.display asis -# primary_hostname = -.endd -This is a commented-out setting of the \primary@_hostname\ option. Exim needs -to know the official, fully qualified name of your host, and this is where you -can specify it. However, in most cases you do not need to set this option. When -it is unset, Exim uses the \*uname()*\ system function to obtain the host name. - -The first three non-comment configuration lines are as follows: -.display asis -domainlist local_domains = @ -domainlist relay_to_domains = -hostlist relay_from_hosts = 127.0.0.1 -.endd -These are not, in fact, option settings. They are definitions of two named -domain lists and one named host list. Exim allows you to give names to lists of -domains, hosts, and email addresses, in order to make it easier to manage the -configuration file (see section ~~SECTnamedlists). - -The first line defines a domain list called \*local@_domains*\; this is used -later in the configuration to identify domains that are to be delivered -on the local host. -.index @@ in a domain list -There is just one item in this list, the string `@@'. This is a special form of -entry which means `the name of the local host'. Thus, if the local host is -called \*a.host.example*\, mail to \*any.user@@a.host.example*\ is expected to -be delivered locally. Because the local host's name is referenced indirectly, -the same configuration file can be used on different hosts. - -The second line defines a domain list called \*relay@_to@_domains*\, but the -list itself is empty. Later in the configuration we will come to the part that -controls mail relaying through the local host; it allows relaying to any -domains in this list. By default, therefore, no relaying on the basis of a mail -domain is permitted. - -The third line defines a host list called \*relay@_from@_hosts*\. This list is -used later in the configuration to permit relaying from any host or IP address -that matches the list. The default contains just the IP address of the IPv4 -loopback interface, which means that processes on the local host are able to -submit mail for relaying by sending it over TCP/IP to that interface. No other -hosts are permitted to submit messages for relaying. - -Just to be sure there's no misunderstanding: at this point in the configuration -we aren't actually setting up any controls. We are just defining some domains -and hosts that will be used in the controls that are specified later. - -The next configuration line is a genuine option setting: -.display asis -acl_smtp_rcpt = acl_check_rcpt -.endd -This option specifies an \*Access Control List*\ (ACL) which is to be used -during an incoming SMTP session for every recipient of a message (every -\\RCPT\\ command). The name of the list is \*acl@_check@_rcpt*\, and we will -come to its definition below, in the ACL section of the configuration. ACLs -control which recipients are accepted for an incoming message -- if a -configuration does not provide an ACL to check recipients, no SMTP mail can be -accepted. - -Two commented-out options settings are next: -.display asis -# qualify_domain = -# qualify_recipient = -.endd -The first of these specifies a domain that Exim uses when it constructs a -complete email address from a local login name. This is often needed when Exim -receives a message from a local process. If you do not set \qualify@_domain\, -the value of \primary@_hostname\ is used. If you set both of these options, you -can have different qualification domains for sender and recipient addresses. If -you set only the first one, its value is used in both cases. - -.index domain literal||recognizing format -The following line must be uncommented if you want Exim to recognize -addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal' -(an IP address) instead of a named domain. -.display asis -# allow_domain_literals -.endd -The RFCs still require this form, but many people think that in the modern -Internet it makes little sense to permit mail to be sent to specific hosts by -quoting their IP addresses. This ancient format has been used by people who -try to abuse hosts by using them for unwanted relaying. However, some -people believe there are circumstances (for example, messages addressed to -\*postmaster*\) where domain literals are still useful. - -The next configuration line is a kind of trigger guard: -.display asis -never_users = root -.endd -It specifies that no delivery must ever be run as the root user. The normal -convention is to set up \*root*\ as an alias for the system administrator. This -setting is a guard against slips in the configuration. -The list of users specified by \never@_users\ is not, however, the complete -list; the build-time configuration in \(Local/Makefile)\ has an option called -\\FIXED@_NEVER@_USERS\\ specifying a list that cannot be overridden. The -contents of \never@_users\ are added to this list. By default -\\FIXED@_NEVER@_USERS\\ also specifies root. - -When a remote host connects to Exim in order to send mail, the only information -Exim has about the host's identity is its IP address. The next configuration -line, -.display asis -host_lookup = * -.endd -specifies that Exim should do a reverse DNS lookup on all incoming connections, -in order to get a host name. This improves the quality of the logging -information, but if you feel it is too expensive, you can remove it entirely, -or restrict the lookup to hosts on `nearby' networks. -Note that it is not always possible to find a host name from an IP address, -because not all DNS reverse zones are maintained, and sometimes DNS servers are -unreachable. - -The next two lines are concerned with \*ident*\ callbacks, as defined by RFC -1413 (hence their names): -.display asis -rfc1413_hosts = * -rfc1413_query_timeout = 30s -.endd -These settings cause Exim to make ident callbacks for all incoming SMTP calls. -You can limit the hosts to which these calls are made, or change the timeout -that is used. If you set the timeout to zero, all ident calls are disabled. -Although they are cheap and can provide useful information for tracing problem -messages, some hosts and firewalls have problems with ident calls. This can -result in a timeout instead of an immediate refused connection, leading to -delays on starting up an incoming SMTP session. - -When Exim receives messages over SMTP connections, it expects all addresses to -be fully qualified with a domain, as required by the SMTP definition. However, -if you are running a server to which simple clients submit messages, you may -find that they send unqualified addresses. The two commented-out options: -.display asis -# sender_unqualified_hosts = -# recipient_unqualified_hosts = -.endd -show how you can specify hosts that are permitted to send unqualified sender -and recipient addresses, respectively. - -The \percent@_hack@_domains\ option is also commented out: -.display asis -# percent_hack_domains = -.endd -It provides a list of domains for which the `percent hack' is to operate. This -is an almost obsolete form of explicit email routing. If you do not know -anything about it, you can safely ignore this topic. - -The last two settings in the main part of the default configuration are -concerned with messages that have been `frozen' on Exim's queue. When a message -is frozen, Exim no longer continues to try to deliver it. Freezing occurs when -a bounce message encounters a permanent failure because the sender address of -the original message that caused the bounce is invalid, so the bounce cannot be -delivered. This is probably the most common case, but there are also other -conditions that cause freezing, and frozen messages are not always bounce -messages. -.display asis -ignore_bounce_errors_after = 2d -timeout_frozen_after = 7d -.endd -The first of these options specifies that failing bounce messages are to be -discarded after 2 days on the queue. The second specifies that any frozen -message (whether a bounce message or not) is to be timed out (and discarded) -after a week. In this configuration, the first setting ensures that no failing -bounce message ever lasts a week. - - -.section ACL configuration -.index default||ACLs -.index ~~ACL||default configuration -In the default configuration, the ACL section follows the main configuration. -It starts with the line -.display asis -begin acl -.endd -and it contains the definition of one ACL called \*acl@_check@_rcpt*\ that was -referenced in the setting of \acl@_smtp@_rcpt\ above. -.index \\RCPT\\||ACL for -This ACL is used for every \\RCPT\\ command in an incoming SMTP message. Each -\\RCPT\\ command specifies one of the message's recipients. The ACL statements -are considered in order, until the recipient address is either accepted or -rejected. The \\RCPT\\ command is then accepted or rejected, according to the -result of the ACL processing. -.display asis -acl_check_rcpt: -.endd -This line, consisting of a name terminated by a colon, marks the start of the -ACL, and names it. -.display asis -accept hosts = : -.endd -This ACL statement accepts the recipient if the sending host matches the list. -But what does that strange list mean? It doesn't actually contain any host -names or IP addresses. The presence of the colon puts an empty item in the -list; Exim matches this only if the incoming message didn't come from a remote -host. The colon is important. Without it, the list itself is empty, and can -never match anything. - -What this statement is doing is to accept unconditionally all recipients in -messages that are submitted by SMTP from local processes using the standard -input and output (that is, not using TCP/IP). A number of MUAs operate in this -manner. -.display asis -deny domains = +local_domains - local_parts = ^[.] : ^.*[@%!/|] - -deny domains = !+local_domains - local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ -.endd -These statements are concerned with local parts that contain any of the -characters `@@', `%', `!', `/', `|', or dots in unusual places. Although these -characters are entirely legal in local parts (in the case of `@@' and leading -dots, only if correctly quoted), they do not commonly occur in Internet mail -addresses. - -The first three have in the past been associated with explicitly routed -addresses (percent is still sometimes used -- see the \percent@_hack@_domains\ -option). Addresses containing these characters are regularly tried by spammers -in an attempt to bypass relaying restrictions, and also by open relay testing -programs. Unless you really need them it is safest to reject these characters -at this early stage. This configuration is heavy-handed in rejecting these -characters for all messages it accepts from remote hosts. This is a deliberate -policy of being as safe as possible. - -The first rule above is stricter, and is applied to messages that are addressed -to one of the local domains handled by this host. This is implemented by the -first condition, which restricts it to domains that are listed in the -\*local@_domains*\ domain list. The `+' character is used to indicate a -reference to a named list. In this configuration, there is just one domain in -\*local@_domains*\, but in general there may be many. - -The second condition on the first statement uses two regular expressions to -block local parts that begin with a dot or contain `@@', `%', `!', `/', or `|'. -If you have local accounts that include these characters, you will have to -modify this rule. - -Empty components (two dots in a row) are not valid in RFC 2822, but Exim -allows them because they have been encountered in practice. (Consider local -parts constructed as `first-initial.second-initial.family-name' when applied to -someone like the author of Exim, who has no second initial.) However, a local -part starting with a dot or containing `/../' can cause trouble if it is used -as part of a file name (for example, for a mailing list). This is also true for -local parts that contain slashes. A pipe symbol can also be troublesome if the -local part is incorporated unthinkingly into a shell command line. - -The second rule above applies to all other domains, and is less strict. This -allows your own users to send outgoing messages to sites that use slashes -and vertical bars in their local parts. It blocks local parts that begin -with a dot, slash, or vertical bar, but allows these characters within the -local part. However, the sequence `/../' is barred. The use of `@@', `%', and -`!' is blocked, as before. The motivation here is to prevent your users (or -your users' viruses) from mounting certain kinds of attack on remote sites. - -.display asis -accept local_parts = postmaster - domains = +local_domains -.endd -This statement, which has two conditions, accepts an incoming address if the -local part is \*postmaster*\ and the domain is one of those listed in the -\*local@_domains*\ domain list. The `+' character is used to indicate a -reference to a named list. In this configuration, there is just one domain in -\*local@_domains*\, but in general there may be many. - -The presence of this statement means that mail to postmaster is never blocked -by any of the subsequent tests. This can be helpful while sorting out problems -in cases where the subsequent tests are incorrectly denying access. -.display asis -require verify = sender -.endd -This statement requires the sender address to be verified before any subsequent -ACL statement can be used. If verification fails, the incoming recipient -address is refused. Verification consists of trying to route the address, to -see if a -bounce -message could be delivered to it. In the case of remote addresses, basic -verification checks only the domain, but \*callouts*\ can be used for more -verification if required. Section ~~SECTaddressverification discusses the -details of address verification. - -.display asis -# deny message = rejected because $sender_host_address is \ -# in a black list at $dnslist_domain\n\ -# $dnslist_text -# dnslists = black.list.example -# -# warn message = X-Warning: $sender_host_address is \ -# in a black list at $dnslist_domain -# log_message = found in $dnslist_domain -# dnslists = black.list.example -.endd -These commented-out lines are examples of how you could configure Exim to check -sending hosts against a DNS black list. The first statement rejects messages -from blacklisted hosts, whereas the second merely inserts a warning header -line. - -.display asis -accept domains = +local_domains - endpass - message = unknown user - verify = recipient -.endd -This statement accepts the incoming recipient address if its domain is one of -the local domains, but only if the address can be verified. Verification of -local addresses normally checks both the local part and the domain. The -\endpass\ line needs some explanation: if the condition above \endpass\ fails, -that is, if the address is not in a local domain, control is passed to the next -ACL statement. However, if the condition below \endpass\ fails, that is, if a -recipient in a local domain cannot be verified, access is denied and the -recipient is rejected. -.index customizing||ACL failure message -The \message\ modifier provides a customized error message for the failure. -.display asis -accept domains = +relay_to_domains - endpass - message = unrouteable address - verify = recipient -.endd -This statement accepts the incoming recipient address if its domain is one of -the domains for which this host is a relay, but again, only if the address can -be verified. -.display asis -accept hosts = +relay_from_hosts -.endd -Control reaches this statement only if the recipient's domain is neither a -local domain, nor a relay domain. The statement accepts the address if the -message is coming from one of the hosts that are defined as being allowed to -relay through this host. Recipient verification is omitted here, because in -many cases the clients are dumb MUAs that do not cope well with SMTP error -responses. If you are actually relaying out from MTAs, you should probably add -recipient verification here. -.display asis -accept authenticated = * -.endd -Control reaches here for attempts to relay to arbitrary domains from arbitrary -hosts. The statement accepts the address only if the client host has -authenticated itself. The default configuration does not define any -authenticators, which means that no client can in fact authenticate. You will -need to add authenticator definitions if you want to make use of this ACL -statement. -.display asis -deny message = relay not permitted -.endd -The final statement denies access, giving a specific error message. Reaching -the end of the ACL also causes access to be denied, but with the generic -message `administrative prohibition'. - - -.section Router configuration -.index default||routers -.index routers||default -The router configuration comes next in the default configuration, introduced -by the line -.display asis -begin routers -.endd -Routers are the modules in Exim that make decisions about where to send -messages. An address is passed to each router in turn, until it is either -accepted, or failed. This means that the order in which you define the routers -matters. Each router is fully described in its own chapter later in this -manual. Here we give only brief overviews. - -.index domain literal||default router -.display asis -# domain_literal: -# driver = ipliteral -# domains = !+local_domains -# transport = remote_smtp -.endd -This router is commented out because the majority of sites do not want to -support domain literal addresses (those of the form \*user@@[10.9.8.7]*\). If -you uncomment this router, you also need to uncomment the setting of -\allow@_domain@_literals\ in the main part of the configuration. - -.display asis -dnslookup: - driver = dnslookup - domains = ! +local_domains - transport = remote_smtp -.newline - ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 -.newline - no_more -.endd -The first uncommented router handles addresses that do not involve any local -domains. This is specified by the line -.display asis -domains = ! +local_domains -.endd -The \domains\ option lists the domains to which this router applies, but the -exclamation mark is a negation sign, so the router is used only for domains -that are not in the domain list called \*local@_domains*\ (which was defined at -the start of the configuration). The plus sign before \*local@_domains*\ -indicates that it is referring to a named list. Addresses in other domains are -passed on to the following routers. - -The name of the router driver is \%dnslookup%\, -and is specified by the \driver\ option. Do not be confused by the fact that -the name of this router instance is the same as the name of the driver. The -instance name is arbitrary, but the name set in the \driver\ option must be one -of the driver modules that is in the Exim binary. - -The \%dnslookup%\ router routes addresses by looking up their domains in the -DNS in order to obtain a list of hosts to which the address is routed. If the -router succeeds, the address is queued for the \%remote@_smtp%\ transport, as -specified by the \transport\ option. If the router does not find the domain in -the DNS, no further routers are tried because of the \no@_more\ setting, so the -address fails and is bounced. - -The \ignore@_target@_hosts\ option specifies a list of IP addresses that are to -be entirely ignored. This option is present because a number of cases have been -encountered where MX records in the DNS point to host names -whose IP addresses are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). -Completely ignoring these IP addresses causes Exim to fail to route the -email address, so it bounces. Otherwise, Exim would log a routing problem, and -continue to try to deliver the message periodically until the address timed -out. -.display asis -system_aliases: - driver = redirect - allow_fail - allow_defer - data = ${lookup{$local_part}lsearch{/etc/aliases}} -# user = exim - file_transport = address_file - pipe_transport = address_pipe -.endd -Control reaches this and subsequent routers only for addresses in the local -domains. This router checks to see whether the local part is defined as an -alias in the \(/etc/aliases)\ file, and if so, redirects it according to the -data that it looks up from that file. If no data is found for the local part, -the value of the \data\ option is empty, causing the address to be passed to -the next router. - -\(/etc/aliases)\ is a conventional name for the system aliases file that is -often used. That is why it is referenced by from the default configuration -file. However, you can change this by setting \\SYSTEM@_ALIASES@_FILE\\ in -\(Local/Makefile)\ before building Exim. - -.display asis -userforward: - driver = redirect - check_local_user - file = $home/.forward - no_verify - no_expn - check_ancestor -# allow_filter - file_transport = address_file - pipe_transport = address_pipe - reply_transport = address_reply -.endd -This is the most complicated router in the default configuration. It is another -redirection router, but this time it is looking for forwarding data set up by -individual users. The \check@_local@_user\ setting means that the first thing it -does is to check that the local part of the address is the login name of a -local user. If it is not, the router is skipped. When a local user is found, -the file called \(.forward)\ in the user's home directory is consulted. If it -does not exist, or is empty, the router declines. Otherwise, the contents of -\(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect -for more details). - -.index Sieve filter||enabling in default router -Traditional \(.forward)\ files contain just a list of addresses, pipes, or -files. Exim supports this by default. However, if \allow@_filter\ is set (it is -commented out by default), the contents of the file are interpreted as a set of -Exim or Sieve filtering instructions, provided the file begins with `@#Exim -filter' or `@#Sieve filter', respectively. User filtering is discussed in the -separate document entitled \*Exim's interfaces to mail filtering*\. - -The \no@_verify\ and \no@_expn\ options mean that this router is skipped when -verifying addresses, or when running as a consequence of an SMTP \\EXPN\\ -command. -There are two reasons for doing this: -.numberpars -Whether or not a local user has a \(.forward)\ file is not really relevant when -checking an address for validity; it makes sense not to waste resources doing -unnecessary work. -.nextp -More importantly, when Exim is verifying addresses or handling an \\EXPN\\ -command during an SMTP session, it is running as the Exim user, not as root. -The group is the Exim group, and no additional groups are set up. -It may therefore not be possible for Exim to read users' \(.forward)\ files at -this time. -.endp - -The setting of \check@_ancestor\ prevents the router from generating a new -address that is the same as any previous address that was redirected. (This -works round a problem concerning a bad interaction between aliasing and -forwarding -- see section ~~SECTredlocmai). - -The final three option settings specify the transports that are to be used when -forwarding generates a direct delivery to a file, or to a pipe, or sets up an -auto-reply, respectively. For example, if a \(.forward)\ file contains -.display asis -a.nother@elsewhere.example, /home/spqr/archive -.endd -the delivery to \(/home/spqr/archive)\ is done by running the \address@_file\ -transport. -.display asis -localuser: - driver = accept - check_local_user - transport = local_delivery -.endd -The final router sets up delivery into local mailboxes, provided that the local -part is the name of a local login, by accepting the address and queuing it for -the \%local@_delivery%\ transport. Otherwise, we have reached the end of the -routers, so the address is bounced. - - -.section Transport configuration -.index default||transports -.index transports||default -Transports define mechanisms for actually delivering messages. They operate -only when referenced from routers, so the order in which they are defined does -not matter. The transports section of the configuration starts with -.display asis -begin transports -.endd -One remote transport and four local transports are defined. -.display asis -remote_smtp: - driver = smtp -.endd -This transport is used for delivering messages over SMTP connections. All its -options are defaulted. The list of remote hosts comes from the router. -.display asis -local_delivery: - driver = appendfile - file = /var/mail/$local_part - delivery_date_add - envelope_to_add - return_path_add -# group = mail -# mode = 0660 -.endd -This \%appendfile%\ transport is used for local delivery to user mailboxes in -traditional BSD mailbox format. By default it runs under the uid and gid of the -local user, which requires the sticky bit to be set on the \(/var/mail)\ -directory. Some systems use the alternative approach of running mail deliveries -under a particular group instead of using the sticky bit. The commented options -show how this can be done. - -Exim adds three headers to the message as it delivers it: ::Delivery-date::, -::Envelope-to:: and ::Return-path::. This action is requested by the three -similarly-named options above. -.display asis -address_pipe: - driver = pipe - return_output -.endd -This transport is used for handling deliveries to pipes that are generated by -redirection (aliasing or users' \(.forward)\ files). The \return@_output\ -option specifies that any output generated by the pipe is to be returned to the -sender. -.display asis -address_file: - driver = appendfile - delivery_date_add - envelope_to_add - return_path_add -.endd -This transport is used for handling deliveries to files that are generated by -redirection. The name of the file is not specified in this instance of -\%appendfile%\, because it comes from the \%redirect%\ router. -.display asis -address_reply: - driver = autoreply -.endd -This transport is used for handling automatic replies generated by users' -filter files. - - -.section Default retry rule -.index retry||default rule -.index default||retry rule -The retry section of the configuration file contains rules which affect the way -Exim retries deliveries that cannot be completed at the first attempt. It is -introduced by the line -.display asis -begin retry -.endd -In the default configuration, there is just one rule, which applies to all -errors: -.display asis -* * F,2h,15m; G,16h,1h,1.5; F,4d,6h -.endd -This causes any temporarily failing address to be retried every 15 minutes for -2 hours, then at intervals starting at one hour and increasing by a factor of -1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address -is not delivered after 4 days of failure, it is bounced. - - -.section Rewriting configuration -The rewriting section of the configuration, introduced by -.display asis -begin rewrite -.endd -contains rules for rewriting addresses in messages as they arrive. There are no -rewriting rules in the default configuration file. - - -.section Authenticators configuration -.index \\AUTH\\||configuration -The authenticators section of the configuration, introduced by -.display asis -begin authenticators -.endd -defines mechanisms for the use of the SMTP \\AUTH\\ command. No authenticators -are specified in the default configuration file. - - - -. -. -. -. -. ============================================================================ -.chapter Regular expressions -.set runningfoot "regular expressions" -.rset CHAPregexp ~~chapter - -.index regular expressions||library -.index PCRE -Exim supports the use of regular expressions in many of its options. It -uses the PCRE regular expression library; this provides regular expression -matching that is compatible with Perl 5. The syntax and semantics of -regular expressions is discussed in many Perl reference books, and also in -Jeffrey Friedl's -.if ~~html -[(A HREF="http://www.oreilly.com/catalog/regex/")] -.fi -$it{Mastering Regular Expressions} -.if ~~html -[(/A)] -.fi -(O'Reilly, ISBN 0-596-00289-0). - -The documentation for the syntax and semantics of the regular expressions that -are supported by PCRE is included in plain text in the file -\(doc/pcrepattern.txt)\ in the Exim distribution, and also in the HTML -tarbundle of Exim documentation, and as an appendix to the -.if ~~html -[(A HREF="http://www.uit.co.uk/exim-book/")] -.fi -Exim book. -.if ~~html -[(/A)] -.fi -It describes in detail the features of the regular expressions that PCRE -supports, so no further description is included here. The PCRE functions are -called from Exim using the default option settings (that is, with no PCRE -options set), except that the \\PCRE@_CASELESS\\ option is set when the -matching is required to be case-insensitive. - -In most cases, when a regular expression is required in an Exim configuration, -it has to start with a circumflex, in order to distinguish it from plain text -or an `ends with' wildcard. In this example of a configuration setting, the -second item in the colon-separated list is a regular expression. -.display asis -domains = a.b.c : ^\\d{3} : *.y.z : ... -.endd -The doubling of the backslash is required because of string expansion that -precedes interpretation -- see section ~~SECTlittext for more discussion of -this issue, and a way of avoiding the need for doubling backslashes. The -regular expression that is eventually used in this example contains just one -backslash. The circumflex is included in the regular expression, and has the -normal effect of `anchoring' it to the start of the string that is being -matched. - -There are, however, two cases where a circumflex is not required for the -recognition of a regular expression: these are the \match\ condition in a -string expansion, and the \matches\ condition in an Exim filter file. In these -cases, the relevant string is always treated as a regular expression; if it -does not start with a circumflex, the expression is not anchored, and can match -anywhere in the subject string. - -In all cases, if you want a regular expression to match at the end of a string, -you must code the @$ metacharacter to indicate this. For example: -.display asis -domains = ^\\d{3}\\.example -.endd -matches the domain \*123.example*\, but it also matches \*123.example.com*\. -You need to use: -.display asis -domains = ^\\d{3}\\.example\$ -.endd -if you want \*example*\ to be the top-level domain. (The backslash before the -@$ is another artefact of string expansion.) - - -.section Testing regular expressions -.index testing||regular expressions -.index regular expressions||testing -.index \*pcretest*\ -A program called \*pcretest*\ forms part of the PCRE distribution and is built -with PCRE during the process of building Exim. It is primarily intended for -testing PCRE itself, but it can also be used for experimenting with regular -expressions. After building Exim, the binary can be found in the build -directory (it is not installed anywhere automatically). There is documentation -of various options in \(doc/pcretest.txt)\, but for simple testing, none are -needed. This is the output of a sample run of \*pcretest*\: -.display - re> $cb{/^([^@@]+)@@.+@\.(ac|edu)@\.(?!kr)[a-z]@{2@}@$/} -data> $cb{x@@y.ac.uk} - 0: x@@y.ac.uk - 1: x - 2: ac -data> $cb{x@@y.ac.kr} -No match -data> $cb{x@@y.edu.com} -No match -data> $cb{x@@y.edu.co} - 0: x@@y.edu.co - 1: x - 2: edu -.endd -.if ~~sys.fancy -Input typed by the user is shown in bold face. -.fi -After the `re>' prompt, a regular expression enclosed in delimiters is -expected. If this compiles without error, `data>' prompts are given for strings -against which the expression is matched. An empty data line causes a new -regular expression to be read. If the match is successful, the captured -substring values (that is, what would be in the variables \$0$\, \$1$\, \$2$\, -etc.) are shown. The above example tests for an email address whose domain ends -with either `ac' or `edu' followed by a two-character top-level domain that is -not `kr'. The local part is captured in \$1$\ and the `ac' or `edu' in \$2$\. - - - - - - -. -. -. -. -. ============================================================================ -.chapter File and database lookups -.set runningfoot "file/database lookups" -.rset CHAPfdlookup "~~chapter" -.index file||lookup -.index database lookups -.index lookup||description of -Exim can be configured to look up data in files or databases as it processes -messages. Two different kinds of syntax are used: -.numberpars -A string that is to be expanded may contain explicit lookup requests. These -cause parts of the string to be replaced by data that is obtained from the -lookup. -.nextp -Lists of domains, hosts, and email addresses can contain lookup requests as a -way of avoiding excessively long linear lists. In this case, the data that is -returned by the lookup is often (but not always) discarded; whether the lookup -succeeds or fails is what really counts. These kinds of list are described in -chapter ~~CHAPdomhosaddlists. -.endp -It is easy to confuse the two different kinds of lookup, especially as the -lists that may contain the second kind are always expanded before being -processed as lists. Therefore, they may also contain lookups of the first kind. -Be careful to distinguish between the following two examples: -.display asis -domains = ${lookup{$sender_host_address}lsearch{/some/file}} -domains = lsearch;/some/file -.endd -The first uses a string expansion, the result of which must be a domain list. -String expansions are described in detail in chapter ~~CHAPexpand. The -expansion takes place first, and the file that is searched could contain lines -like this: -.display asis -192.168.3.4: domain1 : domain2 : ... -192.168.1.9: domain3 : domain4 : ... -.endd -Thus, the result of the expansion is a list of domains (and possibly other -types of item that are allowed in domain lists). - -In the second case, the lookup is a single item in a domain list. It causes -Exim to use a lookup to see if the domain that is being processed can be found -in the file. The file could contains lines like this: -.display asis -domain1: -domain2: -.endd -Any data that follows the keys is not relevant when checking that the domain -matches the list item. - -It is possible to use both kinds of lookup at once. Consider a file containing -lines like this: -.display asis -192.168.5.6: lsearch;/another/file -.endd -If the value of \$sender@_host@_address$\ is 192.168.5.6, expansion of the -first \domains\ setting above generates the second setting, which therefore -causes a second lookup to occur. - -The rest of this chapter describes the different lookup types that are -available. Any of them can be used in either of the circumstances described -above. The syntax requirements for the two cases are described in chapters -~~CHAPexpand and ~~CHAPdomhosaddlists, respectively. - -.section Lookup types -.index lookup||types of -.index single-key lookup||definition of -Two different styles of data lookup are implemented: -.numberpars $. -The \*single-key*\ style requires the specification of a file in which to look, -and a single key to search for. -.em -The key must be a non-empty string for the lookup to succeed. -.nem -The lookup type determines how the file is searched. -.nextp -.index query-style lookup||definition of -The \*query*\ style accepts a generalized database query. -No particular key value is assumed by Exim for query-style lookups. You can -use whichever Exim variable(s) you need to construct the database query. -.endp -The code for each lookup type is in a separate source file that is included in -the binary of Exim only if the corresponding compile-time option is set. The -default settings in \(src/EDITME)\ are: -.display asis -LOOKUP_DBM=yes -LOOKUP_LSEARCH=yes -.endd -which means that only linear searching and DBM lookups are included by default. -For some types of lookup (e.g. SQL databases), you need to install appropriate -libraries and header files before building Exim. - - - -.section Single-key lookup types -.rset SECTsinglekeylookups "~~chapter.~~section" -.index lookup||single-key types -.index single-key lookup||list of types -The following single-key lookup types are implemented: -.numberpars $. -.index cdb||description of -.index lookup||cdb -.index binary zero||in lookup key -\%cdb%\: The given file is searched as a Constant DataBase file, using the key -string without a terminating binary zero. The cdb format is designed for -indexed files that are read frequently and never updated, except by total -re-creation. As such, it is particulary suitable for large files containing -aliases or other indexed data referenced by an MTA. Information about cdb can -be found in several places: -.display rm -\?http://www.pobox.com/@~djb/cdb.html?\ -\?ftp://ftp.corpit.ru/pub/tinycdb/?\ -\?http://packages.debian.org/stable/utils/freecdb.html?\ -.endd -A cdb distribution is not needed in order to build Exim with cdb support, -because the code for reading cdb files is included directly in Exim itself. -However, no means of building or testing cdb files is provided with Exim, so -you need to obtain a cdb distribution in order to do this. -.nextp -.index DBM||lookup type -.index lookup||dbm -.index binary zero||in lookup key -\%dbm%\: Calls to DBM library functions are used to extract data from the given -DBM file by looking up the record with the given key. A terminating binary -zero is included in the key that is passed to the DBM library. See section -~~SECTdb for a discussion of DBM libraries. -.index Berkeley DB library||file format -For all versions of Berkeley DB, Exim uses the \\DB@_HASH\\ style of database -when building DBM files using the \exim@_dbmbuild\ utility. However, when using -Berkeley DB versions 3 or 4, it opens existing databases for reading with the -\\DB@_UNKNOWN\\ option. This enables it to handle any of the types of database -that the library supports, and can be useful for accessing DBM files created by -other applications. (For earlier DB versions, \\DB@_HASH\\ is always used.) - -.nextp -.index lookup||dbmnz -.index lookup||dbm, terminating zero -.index binary zero||in lookup key -.index Courier -.index \(/etc/userdbshadow.dat)\ -.index dmbnz lookup type -\%dbmnz%\: This is the same as \%dbm%\, except that a terminating binary zero -is not included in the key that is passed to the DBM library. You may need this -if you want to look up data in files that are created by or shared with some -other application that does not use terminating zeros. For example, you need to -use \%dbmnz%\ rather than \%dbm%\ if you want to authenticate incoming SMTP -calls using the passwords from Courier's \(/etc/userdbshadow.dat)\ file. Exim's -utility program for creating DBM files (\*exim@_dbmbuild*\) includes the zeros -by default, but has an option to omit them (see section ~~SECTdbmbuild). -.nextp -.index lookup||dsearch -.index dsearch lookup type -\%dsearch%\: The given file must be a directory; this is searched for a file -whose name is the key. The key may not contain any forward slash characters. -The result of a successful lookup is the name of the file. An example of how -this lookup can be used to support virtual domains is given in section -~~SECTvirtualdomains. -.nextp -.index lookup||iplsearch -.index iplsearch lookup type -\%iplsearch%\: The given file is a text file containing keys and data. A key is -terminated by a colon or white space or the end of the line. The keys in the -file must be IP addresses, or IP addresses with CIDR masks. Keys that involve -IPv6 addresses must be enclosed in quotes to prevent the first internal colon -being interpreted as a key terminator. For example: -.display asis -1.2.3.4: data for 1.2.3.4 -192.168.0.0/16 data for 192.168.0.0/16 -"abcd::cdab": data for abcd::cdab -"abcd:abcd::/32" data for abcd:abcd::/32 -.endd -The key for an \%iplsearch%\ lookup must be an IP address (without a mask). The -file is searched linearly, using the CIDR masks where present, until a matching -key is found. The first key that matches is used; there is no attempt to find a -`best' match. Apart from the way the keys are matched, the processing for -\%iplsearch%\ is the same as for \%lsearch%\. - -\**Warning 1**\: Unlike most other single-key lookup types, a file of data for -\%iplsearch%\ can \*not*\ be turned into a DBM or cdb file, because those -lookup types support only literal keys. - -\**Warning 2**\: In a host list, you must always use \%net-iplsearch%\ so that -the implicit key is the host's IP address rather than its name (see section -~~SECThoslispatsikey). - -.nextp -.index linear search -.index lookup||lsearch -.index lsearch lookup type -\%lsearch%\: The given file is a text file that is searched linearly for a -line beginning with the search key, terminated by a colon or white space or the -end of the line. The first occurrence that is found in the file is used. White -space between the key and the colon is permitted. The remainder of the line, -with leading and trailing white space removed, is the data. This can be -continued onto subsequent lines by starting them with any amount of white -space, but only a single space character is included in the data at such a -junction. If the data begins with a colon, the key must be terminated by a -colon, for example: -.display -baduser: :fail: -.endd -Empty lines and lines beginning with @# are ignored, even if they occur in the -middle of an item. This is the traditional textual format of alias files. Note -that the keys in an \%lsearch%\ file are literal strings. There is no -wildcarding of any kind. - -.index lookup||lsearch, colons in keys -.index whitespace||in lsearch key -In most \%lsearch%\ files, keys are not required to contain colons or @# -characters, or whitespace. However, if you need this feature, it is available. -If a key begins with a doublequote character, it is terminated only by a -matching quote (or end of line), and the normal escaping rules apply to its -contents (see section ~~SECTstrings). An optional colon is permitted after -quoted keys (exactly as for unquoted keys). There is no special handling of -quotes for the data part of an \%lsearch%\ line. -.nextp -.index NIS lookup type -.index lookup||NIS -.index binary zero||in lookup key -\%nis%\: The given file is the name of a NIS map, and a NIS lookup is done with -the given key, without a terminating binary zero. There is a variant called -\%nis0%\ which does include the terminating binary zero in the key. This is -reportedly needed for Sun-style alias files. Exim does not recognize NIS -aliases; the full map names must be used. -.nextp -.index wildlsearch lookup type -.index lookup||wildlsearch -.index nwildlsearch lookup type -.index lookup||nwildlsearch -\%wildlsearch%\ or \%nwildlsearch%\: These search a file linearly, like -\%lsearch%\, but instead of being interpreted as a literal string, each key may -be wildcarded. The difference between these two lookup types is that for -\%wildlsearch%\, each key in the file is string-expanded before being used, -whereas for \%nwildlsearch%\, no expansion takes place. - -Like \%lsearch%\, the testing is done case-insensitively. The following forms -of wildcard are recognized: -.numberpars "$*$" -The string may begin with an asterisk to mean `ends with'. For example: -.display asis -*.a.b.c data for anything.a.b.c -*fish data for anythingfish -.endd -.nextp -The string may begin with a circumflex to indicate a regular expression. For -example, for \%wildlsearch%\: -.display asis -^\N\d+\.a\.b\N data for <digits>.a.b -.endd -Note the use of \"@\N"\ to disable expansion of the contents of the regular -expression. If you are using \%nwildlsearch%\, where the keys are not -string-expanded, the equivalent entry is: -.display asis -^\d+\.a\.b data for <digits>.a.b -.endd - -If the regular expression contains white space or colon characters, you must -either quote it (see \%lsearch%\ above), or represent these characters in other -ways. For example, \"@\s"\ can be used for white space and \"@\x3A"\ for a -colon. This may be easier than quoting, because if you quote, you have to -escape all the backslashes inside the quotes. -.nextp -Although I cannot see it being of much use, the general matching function -that is used to implement -\%(n)wildlsearch%\ -means that the string may begin with a lookup name terminated by a semicolon, -and followed by lookup data. For example: -.display asis -cdb;/some/file data for keys that match the file -.endd -The data that is obtained from the nested lookup is discarded. -.endp -Keys that do not match any of these patterns are interpreted literally. The -continuation rules for the data are the same as for \%lsearch%\, and keys may -be followed by optional colons. - -\**Warning**\: Unlike most other single-key lookup types, a file of data for -\%(n)wildlsearch%\ can \*not*\ be turned into a DBM or cdb file, because those -lookup types support only literal keys. -.endp - -.section Query-style lookup types -.index lookup||query-style types -.index query-style lookup||list of types -The supported query-style lookup types are listed below. Further details about -many of them are given in later sections. -.numberpars $. -.index DNS||as a lookup type -.index lookup||DNS -\%dnsdb%\: This does a DNS search for -.em -one or more records whose domain names are given in the supplied query. The -resulting data is the contents of the records. -.nem -See section ~~SECTdnsdb. -.nextp -.index Interbase lookup type -.index lookup||Interbase -\%ibase%\: This does a lookup in an Interbase database. -.nextp -.index LDAP||lookup type -.index lookup||LDAP -\%ldap%\: This does an LDAP lookup using a query in the form of a URL, and -returns attributes from a single entry. There is a variant called \%ldapm%\ -that permits values from multiple entries to be returned. A third variant -called \%ldapdn%\ returns the Distinguished Name of a single entry instead of -any attribute values. See section ~~SECTldap. -.nextp -.index MySQL||lookup type -.index lookup||MySQL -\%mysql%\: The format of the query is an SQL statement that is passed to a MySQL -database. See section ~~SECTsql. -.nextp -.index NIS@+ lookup type -.index lookup||NIS+ -\%nisplus%\: This does a NIS+ lookup using a query that can specify the name of -the field to be returned. See section ~~SECTnisplus. -.nextp -.index Oracle||lookup type -.index lookup||Oracle -\%oracle%\: The format of the query is an SQL statement that is passed to an -Oracle database. See section ~~SECTsql. -.nextp -.index lookup||passwd -.index passwd lookup type -.index \(/etc/passwd)\ -\%passwd%\ is a query-style lookup with queries that are just user names. The -lookup calls \*getpwnam()*\ to interrogate the system password data, and on -success, the result string is the same as you would get from an \%lsearch%\ -lookup on a traditional \(/etc/passwd file)\, though with \"*"\ for the -password value. For example: -.display asis -*:42:42:King Rat:/home/kr:/bin/bash -.endd -.nextp -.index PostgreSQL lookup type -.index lookup||PostgreSQL -\%pgsql%\: The format of the query is an SQL statement that is passed to a -PostgreSQL database. See section ~~SECTsql. -.nextp -\%testdb%\: This is a lookup type that is used for testing Exim. It is -not likely to be useful in normal operation. -.nextp -.index whoson lookup type -.index lookup||whoson -\%whoson%\: \*Whoson*\ (\?http://whoson.sourceforge.net?\) is a proposed -Internet protocol that allows Internet server programs to check whether a -particular (dynamically allocated) IP address is currently allocated to a known -(trusted) user and, optionally, to obtain the identity of the said user. In -Exim, this can be used to implement `POP before SMTP' checking using ACL -statements such as -.display asis -require condition = \ - ${lookup whoson {$sender_host_address}{yes}{no}} -.endd -The query consists of a single IP address. The value returned is the name of -the authenticated user. -.endp - -.section Temporary errors in lookups -.index lookup||temporary error in -Lookup functions can return temporary error codes if the lookup cannot be -completed. For example, a NIS or LDAP database might be unavailable. For this -reason, it is not advisable to use a lookup that might do this for critical -options such as a list of local domains. - -When a lookup cannot be completed in a router or transport, delivery -of the message (to the relevant address) is deferred, as for any other -temporary error. In other circumstances Exim may assume the lookup has failed, -or may give up altogether. - - -.section Default values in single-key lookups -.rset SECTdefaultvaluelookups "~~chapter.~~section" -.index wildcard lookups -.index lookup||default values -.index lookup||wildcard -.index lookup||$*$ added to type -.index default||in single-key lookups -In this context, a `default value' is a value specified by the administrator -that is to be used if a lookup fails. - -If `$*$' is added to a single-key lookup type (for example, \lsearch$*$\) and -the initial lookup fails, the key `$*$' is looked up in the file to provide -a default value. See also the section on partial matching below. - -.index @*@@ with single-key lookup -.index lookup||$*$@@ added to type -.index alias file||per-domain default -Alternatively, if `$*$@@' is added to a single-key lookup type (for example -\dbm$*$@@\) then, if the initial lookup fails and the key contains an @@ -character, a second lookup is done with everything before the last @@ replaced -by $*$. This makes it possible to provide per-domain defaults in alias files -that include the domains in the keys. If the second lookup fails (or doesn't -take place because there is no @@ in the key), `$*$' is looked up. -For example, a \%redirect%\ router might contain: -.display asis -data = ${lookup{$local_part@$domain}lsearch*@{/etc/mixed-aliases}} -.endd -Suppose the address that is being processed is \*jane@@eyre.example*\. Exim -looks up these keys, in this order: -.display asis -jane@eyre.example -*@eyre.example -* -.endd -The data is taken from whichever key it finds first. \**Note**\: in an -\%lsearch%\ file, this does not mean the first of these keys in the file. A -complete scan is done for each key, and only if it is not found at all does -Exim move on to try the next key. - - -.section Partial matching in single-key lookups -.rset SECTpartiallookup "~~chapter.~~section" -.index partial matching -.index wildcard lookups -.index lookup||partial matching -.index lookup||wildcard -.index asterisk||in search type -The normal operation of a single-key lookup is to search the file for an exact -match with the given key. However, in a number of situations where domains are -being looked up, it is useful to be able to do partial matching. In this case, -information in the file that has a key starting with `$*$.' is matched by any -domain that ends with the components that follow the full stop. For example, if -a key in a DBM file is -.display -*.dates.fict.example -.endd -then when partial matching is enabled this is matched by (amongst others) -\*2001.dates.fict.example*\ and \*1984.dates.fict.example*\. It is also matched -by \*dates.fict.example*\, if that does not appear as a separate key in the -file. - -\**Note**\: Partial matching is not available for query-style lookups. It is -also not available for any lookup items in address lists (see section -~~SECTaddresslist). - -Partial matching is implemented by doing a series of separate lookups using -keys constructed by modifying the original subject key. This means that it can -be used with any of the single-key lookup types, provided that -partial matching keys -beginning with a special prefix (default `$*$.') are included in the data file. -Keys in the file that do not begin with the prefix are matched only by -unmodified subject keys when partial matching is in use. - -Partial matching is requested by adding the string `partial-' to the front of -the name of a single-key lookup type, for example, \partial-dbm\. When this is -done, the subject key is first looked up unmodified; if that fails, `$*$.' -is added at the start of the subject key, and it is looked up again. If that -fails, further lookups are tried with dot-separated components removed -from the start of the subject key, one-by-one, and `$*$.' added on the front of -what remains. - -A minimum number of two non-$*$ components are required. This can be adjusted -by including a number before the hyphen in the search type. For example, -\partial3-lsearch\ specifies a minimum of three non-$*$ components in the -modified keys. Omitting the number is equivalent to `partial2-'. If the subject -key is \*2250.dates.fict.example*\ then the following keys are looked up when -the minimum number of non-$*$ components is two: -.display asis -2250.dates.fict.example -*.2250.dates.fict.example -*.dates.fict.example -*.fict.example -.endd -As soon as one key in the sequence is successfully looked up, the lookup -finishes. - -.index lookup||partial matching, changing prefix -.index prefix||for partial matching -The use of `$*$.' as the partial matching prefix is a default that can be -changed. The motivation for this feature is to allow Exim to operate with file -formats that are used by other MTAs. A different prefix can be supplied in -parentheses instead of the hyphen after `partial'. For example: -.display asis -domains = partial(.)lsearch;/some/file -.endd -In this example, if the domain is \*a.b.c*\, the sequence of lookups is -\"a.b.c"\, \".a.b.c"\, and \".b.c"\ (the default minimum of 2 non-wild -components is unchanged). The prefix may consist of any punctuation characters -other than a closing parenthesis. It may be empty, for example: -.display asis -domains = partial1()cdb;/some/file -.endd -For this example, if the domain is \*a.b.c*\, the sequence of lookups is -\"a.b.c"\, \"b.c"\, and \"c"\. - -If `partial0' is specified, what happens at the end (when the lookup with just -one non-wild component has failed, and the original key is shortened right down -to the null string) depends on the prefix: -.numberpars $. -If the prefix has zero length, the whole lookup fails. -.nextp -If the prefix has length 1, a lookup for just the prefix is done. For -example, the final lookup for `partial0(.)' is for \"."\ alone. -.nextp -Otherwise, if the prefix ends in a dot, the dot is removed, and the -remainder is looked up. With the default prefix, therefore, the final lookup is -for `$*$' on its own. -.nextp -Otherwise, the whole prefix is looked up. -.endp - -If the search type ends in `$*$' or `$*$@@' (see section -~~SECTdefaultvaluelookups above), the search for an ultimate default that this -implies happens after all partial lookups have failed. If `partial0' is -specified, adding `$*$' to the search type has no effect with the default -prefix, because the `$*$' key is already included in the sequence of partial -lookups. However, there might be a use for lookup types such as -`partial0(.)lsearch$*$'. - -The use of `$*$' in lookup partial matching differs from its use as a wildcard -in domain lists and the like. Partial matching works only in terms of -dot-separated components; a key such as \"*fict.example"\ -in a database file is useless, because the asterisk in a partial matching -subject key is always followed by a dot. - - - -.section Lookup caching -.index lookup||caching -.index caching||lookup data -.em -Exim caches all lookup results in order to avoid needless repetition of -lookups. However, because (apart from the daemon) Exim operates as a collection -of independent, short-lived processes, this caching applies only within a -single Exim process. There is no inter-process caching facility. - -For single-key lookups, Exim keeps the relevant files open in case there is -another lookup that needs them. In some types of configuration this can lead to -many files being kept open for messages with many recipients. To avoid hitting -the operating system limit on the number of simultaneously open files, Exim -closes the least recently used file when it needs to open more files than its -own internal limit, which can be changed via the \lookup@_open@_max\ option. - -The single-key lookup files are closed and the lookup caches are flushed at -strategic points during delivery -- for example, after all routing is complete. -.nem - - -.section Quoting lookup data -.index lookup||quoting -.index quoting||in lookups -When data from an incoming message is included in a query-style lookup, there -is the possibility of special characters in the data messing up the syntax of -the query. For example, a NIS+ query that contains -.display asis -[name=$local_part] -.endd -will be broken if the local part happens to contain a closing square bracket. -For NIS+, data can be enclosed in double quotes like this: -.display asis -[name="$local_part"] -.endd -but this still leaves the problem of a double quote in the data. The rule for -NIS+ is that double quotes must be doubled. Other lookup types have different -rules, and to cope with the differing requirements, an expansion operator -of the following form is provided: -.display -@$@{quote@_<<lookup-type>>:<<string>>@} -.endd -For example, the safest way to write the NIS+ query is -.display asis -[name="${quote_nisplus:$local_part}"] -.endd -See chapter ~~CHAPexpand for full coverage of string expansions. The quote -operator can be used for all lookup types, but has no effect for single-key -lookups, since no quoting is ever needed in their key strings. - - - -.section More about dnsdb -.rset SECTdnsdb "~~chapter.~~section" -.index dnsdb lookup -.index lookup||dnsdb -.index DNS||as a lookup type -The \%dnsdb%\ lookup type uses the DNS as its database. A simple query consists -of a record type and a domain name, separated by an equals sign. For example, -an expansion string could contain: -.display asis -${lookup dnsdb{mx=a.b.example}{$value}fail} -.endd -The supported DNS record types are A, CNAME, MX, NS, PTR, SRV, and TXT, and, -when Exim is compiled with IPv6 support, AAAA (and A6 if that is also -configured). If no type is given, TXT is assumed. When the type is PTR, -.em -the data can be an IP address, written as normal; inversion and the addition of -\in-addr.arpa\ or \ip6.arpa\ happens automatically. For example: -.display asis -${lookup dnsdb{ptr=192.168.4.5}{$value}fail} -.endd -If the data for a PTR record is not a syntactically valid IP address, it is not -altered and nothing is added. - -For any record type, if multiple records are found (or, for A6 lookups, if a -single record leads to multiple addresses), the data is returned as a -concatenation, with newline as the default separator. The order, of course, -depends on the DNS resolver. You can specify a different separator character -between multiple records by putting a right angle-bracket followed immediately -by the new separator at the start of the query. For example: -.display asis -${lookup dnsdb{>: a=host1.example}} -.endd -It is permitted to specify a space as the separator character. Further -whitespace is ignored. - -.index SRV record||in \%dnsdb%\ lookup -For SRV records, the priority, weight, port, and host name are returned for -each record, separated by spaces. - -.index MX record||in \%dnsdb%\ lookup -For MX records, both the preference value and the host name are returned for -each record, separated by a space. However, if you want only host names, you -can use the pseudo-type MXH: -.display asis -${lookup dnsdb{mxh=a.b.example}} -.endd -In this case, the preference values are omitted. - -.index name server||for enclosing domain -Another pseudo-type is ZNS (for `zone NS'). It performs a lookup for NS -records on the given domain, but if none are found, it removes the first -component of the domain name, and tries again. This process continues until NS -records are found or there are no more components left (or there is a DNS -error). In other words, it may return the name servers for a top-level domain, -but it never returns the root name servers. If there are no NS records for the -top-level domain, the lookup fails. Consider these examples: -.display asis -${lookup dnsdb{zns=xxx.quercite.com}} -${lookup dnsdb{zns=xxx.edu}} -.endd -Assuming that in each case there are no NS records for the full domain name, -the first returns the name servers for \quercite.com\, and the second returns -the name servers for \edu\. - -You should be careful about how you use this lookup because, unless the -top-level domain does not exist, the lookup always returns some host names. The -sort of use to which this might be put is for seeing if the name servers for a -given domain are on a blacklist. You can probably assume that the name servers -for the high-level domains such as \com\ or \co.uk\ are not going to be on such -a list. - -.nem - -.em -.section Multiple dnsdb lookups -In the previous section, \%dnsdb%\ lookups for a single domain are described. -However, you can specify a list of domains or IP addresses in a single -\%dnsdb%\ lookup. The list is specified in the normal Exim way, with colon as -the default separator, but with the ability to change this. For example: -.display asis -${lookup dnsdb{one.domain.com:two.domain.com}} -${lookup dnsdb{a=one.host.com:two.host.com}} -${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} -.endd -In order to retain backwards compatibility, there is one special case: if -the lookup type is PTR and no change of separator is specified, Exim looks -to see if the rest of the string is precisely one IPv6 address. In this -case, it does not treat it as a list. - -The data from each lookup is concatenated, with newline separators by default, -in the same way that multiple DNS records for a single item are handled. A -different separator can be specified, as described above. - -The \%dnsdb%\ lookup fails only if all the DNS lookups fail. If there is a -temporary DNS error for any of them, the behaviour is controlled by -an optional keyword followed by a comma that may appear before the record -type. The possible keywords are `defer@_strict', `defer@_never', and -`defer@_lax'. With `strict' behaviour, any temporary DNS error causes the -whole lookup to defer. With `never' behaviour, a temporary DNS error is -ignored, and the behaviour is as if the DNS lookup failed to find anything. -With `lax' behaviour, all the queries are attempted, but a temporary DNS -error causes the whole lookup to defer only if none of the other lookups -succeed. The default is `lax', so the following lookups are equivalent: -.display asis -${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} -${lookup dnsdb{a=one.host.com:two.host.com}} -.endd -Thus, in the default case, as long as at least one of the DNS lookups -yields some data, the lookup succeeds. -.nem - - -.section More about LDAP -.rset SECTldap "~~chapter.~~section" -.index LDAP lookup -.index lookup||LDAP -.index Solaris||LDAP -The original LDAP implementation came from the University of Michigan; this has -become `Open LDAP', and there are now two different releases. Another -implementation comes from Netscape, and Solaris 7 and subsequent releases -contain inbuilt LDAP support. Unfortunately, though these are all compatible at -the lookup function level, their error handling is different. For this reason -it is necessary to set a compile-time variable when building Exim with LDAP, to -indicate which LDAP library is in use. One of the following should appear in -your \(Local/Makefile)\: -.display asis -LDAP_LIB_TYPE=UMICHIGAN -LDAP_LIB_TYPE=OPENLDAP1 -LDAP_LIB_TYPE=OPENLDAP2 -LDAP_LIB_TYPE=NETSCAPE -LDAP_LIB_TYPE=SOLARIS -.endd -If \\LDAP@_LIB@_TYPE\\ is not set, Exim assumes \"OPENLDAP1"\, which has the -same interface as the University of Michigan version. - -There are three LDAP lookup types in Exim. These behave slightly differently in -the way they handle the results of a query: -.numberpars $. -\%ldap%\ requires the result to contain just one entry; if there are more, it -gives an error. -.nextp -\%ldapdn%\ also requires the result to contain just one entry, but it is the -Distinguished Name that is returned rather than any attribute values. -.nextp -\%ldapm%\ permits the result to contain more than one entry; the attributes from -all of them are returned. -.endp - -For \%ldap%\ and \%ldapm%\, if a query finds only entries with no attributes, -Exim behaves as if the entry did not exist, and the lookup fails. The format of -the data returned by a successful lookup is described in the next section. -First we explain how LDAP queries are coded. - -.section Format of LDAP queries -.rset SECTforldaque "~~chapter.~~section" -.index LDAP||query format -An LDAP query takes the form of a URL as defined in RFC 2255. For example, in -the configuration of a \%redirect%\ router one might have this setting: -.display asis -data = ${lookup ldap \ - {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ - c=UK?mailbox?base?}} -.endd -.index LDAP||with TLS -The URL may begin with \"ldap"\ or \"ldaps"\ if your LDAP library supports -secure (encrypted) LDAP connections. The second of these ensures that an -encrypted TLS connection is used. - -.section LDAP quoting -.index LDAP||quoting -Two levels of quoting are required in LDAP queries, the first for LDAP itself -and the second because the LDAP query is represented as a URL. Furthermore, -within an LDAP query, two different kinds of quoting are required. For this -reason, there are two different LDAP-specific quoting operators. - -The \quote@_ldap\ operator is designed for use on strings that are part of -filter specifications. Conceptually, it first does the following conversions on -the string: -.display asis -* => \2A -( => \28 -) => \29 -\ => \5C -.endd -in accordance with RFC 2254. The resulting string is then quoted according -to the rules for URLs, that is, all characters except -.display asis -! $ ' - . _ ( ) * + -.endd -are converted to their hex values, preceded by a percent sign. For example: -.display asis -${quote_ldap: a(bc)*, a<yz>; } -.endd -yields -.display asis -%20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 -.endd -Removing the URL quoting, this is (with a leading and a trailing space): -.display asis -a\28bc\29\2A, a<yz>; -.endd - -The \quote@_ldap@_dn\ operator is designed for use on strings that are part of -base DN specifications in queries. Conceptually, it first converts the string -by inserting a backslash in front of any of the following characters: -.display asis -, + " \ < > ; -.endd -It also inserts a backslash before any leading spaces or @# characters, and -before any trailing spaces. (These rules are in RFC 2253.) The resulting string -is then quoted according to the rules for URLs. For example: -.display asis -${quote_ldap_dn: a(bc)*, a<yz>; } -.endd -yields -.display asis -%5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 -.endd -Removing the URL quoting, this is (with a trailing space): -.display asis -\ a(bc)*\, a\<yz\>\;\ -.endd -There are some further comments about quoting in the section on LDAP -authentication below. - -.section LDAP connections -.index LDAP||connections -The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP -is in use, via a Unix domain socket. The example given above does not specify -an LDAP server. A server that is reached by TCP/IP can be specified in a query -by starting it with -.display -ldap://<<hostname>>:<<port>>/... -.endd -If the port (and preceding colon) are omitted, the standard LDAP port (389) is -used. When no server is specified in a query, a list of default servers is -taken from the \ldap@_default@_servers\ configuration option. This supplies a -colon-separated list of servers which are tried in turn until one successfully -handles a query, or there is a serious error. Successful handling either -returns the requested data, or indicates that it does not exist. Serious errors -are syntactical, or multiple values when only a single value is expected. -Errors which cause the next server to be tried are connection failures, bind -failures, and timeouts. - -For each server name in the list, a port number can be given. The standard way -of specifing a host and port is to use a colon separator (RFC 1738). Because -\ldap@_default@_servers\ is a colon-separated list, such colons have to be -doubled. For example -.display asis -ldap_default_servers = ldap1.example.com::145:ldap2.example.com -.endd -If \ldap@_default@_servers\ is unset, a URL with no server name is passed -to the LDAP library with no server name, and the library's default (normally -the local host) is used. - -If you are using the OpenLDAP library, you can connect to an LDAP server using -a Unix domain socket instead of a TCP/IP connection. This is specified by using -\"ldapi"\ instead of \"ldap"\ in LDAP queries. What follows here applies only -to OpenLDAP. If Exim is compiled with a different LDAP library, this feature is -not available. - -For this type of connection, instead of a host name for the server, a pathname -for the socket is required, and the port number is not relevant. The pathname -can be specified either as an item in \ldap@_default@_servers\, or inline in -the query. In the former case, you can have settings such as -.display asis -ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain -.endd -When the pathname is given in the query, you have to escape the slashes as -\"%2F"\ to fit in with the LDAP URL syntax. For example: -.display asis -${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... -.endd -When Exim processes an LDAP lookup and finds that the `hostname' is really -a pathname, it uses the Unix domain socket code, even if the query actually -specifies \"ldap"\ or \"ldaps"\. In particular, no encryption is used for a -socket connection. This behaviour means that you can use a setting of -\ldap@_default@_servers\ such as in the example above with traditional \"ldap"\ -or \"ldaps"\ queries, and it will work. First, Exim tries a connection via -the Unix domain socket; if that fails, it tries a TCP/IP connection to the -backup host. - -If an explicit \"ldapi"\ type is given in a query when a host name is -specified, an error is diagnosed. However, if there are more items in -\ldap@_default@_servers\, they are tried. In other words: -.numberpars $. -Using a pathname with \"ldap"\ or \"ldaps"\ forces the use of the Unix domain -interface. -.nextp -Using \"ldapi"\ with a host name causes an error. -.endp - -Using \"ldapi"\ with no host or path in the query, and no setting of -\ldap@_default@_servers\, does whatever the library does by default. - - -.section LDAP authentication and control information -.index LDAP||authentication -The LDAP URL syntax provides no way of passing authentication and other control -information to the server. To make this possible, the URL in an LDAP query may -be preceded by any number of `<<name>>=<<value>>' settings, separated by -spaces. If a value contains spaces it must be enclosed in double quotes, and -when double quotes are used, backslash is interpreted in the usual way inside -them. The following names are recognized: -.display -DEREFERENCE $rm{set the dereferencing parameter} -.newline -.em -NETTIME $rm{set a timeout for a network operation} -.nem -.newline -USER $rm{set the DN, for authenticating the LDAP bind} -PASS $rm{set the password, likewise} -SIZE $rm{set the limit for the number of entries returned} -TIME $rm{set the maximum waiting time for a query} -.endd -The value of the \\DEREFERENCE\\ parameter must be one of the words `never', -`searching', `finding', or `always'. - -.em -The name \\CONNECT\\ is an obsolete name for \\NETTIME\\, retained for -backwards compatibility. This timeout (specified as a number of seconds) is -enforced from the client end for operations that can be carried out over a -network. Specifically, it applies to network connections and calls to the -\*ldap@_result()*\ function. If the value is greater than zero, it is used if -\\LDAP@_OPT@_NETWORK@_TIMEOUT\\ is defined in the LDAP headers (OpenLDAP), or -if \\LDAP@_X@_OPT@_CONNECT@_TIMEOUT\\ is defined in the LDAP headers (Netscape -SDK 4.1). A value of zero forces an explicit setting of `no timeout' for -Netscape SDK; for OpenLDAP no action is taken. - -The \\TIME\\ parameter (also a number of seconds) is passed to the server to -set a server-side limit on the time taken to complete a search. -.nem - -Here is an example of an LDAP query in an Exim lookup that uses some of these -values. This is a single line, folded for ease of reading: -.display asis -.indent 0 -${lookup ldap - {user="cn=manager,o=University of Cambridge,c=UK" pass=secret - ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} - {$value}fail} -.endd -The encoding of spaces as %20 is a URL thing which should not be done for any -of the auxiliary data. Exim configuration settings that include lookups which -contain password information should be preceded by `hide' to prevent non-admin -users from using the \-bP-\ option to see their values. - -The auxiliary data items may be given in any order. The default is no -connection timeout (the system timeout is used), no user or password, no limit -on the number of entries returned, and no time limit on queries. - -When a DN is quoted in the \\USER=\\ setting for LDAP authentication, Exim -removes any URL quoting that it may contain before passing it LDAP. Apparently -some libraries do this for themselves, but some do not. Removing the URL -quoting has two advantages: -.numberpars $. -It makes it possible to use the same \quote@_ldap@_dn\ expansion for \\USER=\\ -DNs as with DNs inside actual queries. -.nextp -It permits spaces inside \\USER=\\ DNs. -.endp -For example, a setting such as -.display asis -USER=cn=${quote_ldap_dn:$1} -.endd -should work even if \$1$\ contains spaces. - -Expanded data for the \\PASS=\\ value should be quoted using the \quote\ -expansion operator, rather than the LDAP quote operators. The only reason this -field needs quoting is to ensure that it conforms to the Exim syntax, which -does not allow unquoted spaces. For example: -.display asis -PASS=${quote:$3} -.endd - -The LDAP authentication mechanism can be used to check passwords as part of -SMTP authentication. See the \ldapauth\ expansion string condition in chapter -~~CHAPexpand. - - -.section Format of data returned by LDAP -.index LDAP||returned data formats -The \%ldapdn%\ lookup type returns the Distinguished Name from a single entry as -a sequence of values, for example -.display asis -cn=manager, o=University of Cambridge, c=UK -.endd - -The \%ldap%\ lookup type generates an error if more than one entry matches the -search filter, whereas \%ldapm%\ permits this case, and inserts a newline in -the result between the data from different entries. It is possible for multiple -values to be returned for both \%ldap%\ and \%ldapm%\, but in the former case -you know that whatever values are returned all came from a single entry in the -directory. - -In the common case where you specify a single attribute in your LDAP query, the -result is not quoted, and does not contain the attribute name. If the attribute -has multiple values, they are separated by commas. - -If you specify multiple attributes, the result contains space-separated, quoted -strings, each preceded by the attribute name and an equals sign. Within the -quotes, the quote character, backslash, and newline are escaped with -backslashes, and commas are used to separate multiple values for the attribute. -Apart from the escaping, the string within quotes takes the same form as the -output when a single attribute is requested. Specifying no attributes is the -same as specifying all of an entry's attributes. - -Here are some examples of the output format. The first line of each pair is an -LDAP query, and the second is the data that is returned. The attribute called -\attr1\ has two values, whereas \attr2\ has only one value: -.display asis -ldap:///o=base?attr1?sub?(uid=fred) -value1.1, value1.2 - -ldap:///o=base?attr2?sub?(uid=fred) -value two - -ldap:///o=base?attr1,attr2?sub?(uid=fred) -attr1="value1.1, value1.2" attr2="value two" - -ldap:///o=base??sub?(uid=fred) -objectClass="top" attr1="value1.1, value1.2" attr2="value two" -.endd -The \extract\ operator in string expansions can be used to pick out individual -fields from data that consists of $it{key}=$it{value} pairs. You can make use -of Exim's \-be-\ option to run expansion tests and thereby check the results of -LDAP lookups. - - - -.section More about NIS+ -.rset SECTnisplus "~~chapter.~~section" -.index NIS@+ lookup type -.index lookup||NIS+ -NIS+ queries consist of a NIS+ \*indexed name*\ followed by an optional colon -and field name. If this is given, the result of a successful query is the -contents of the named field; otherwise the result consists of a concatenation -of \*field-name=field-value*\ pairs, separated by spaces. Empty values and -values containing spaces are quoted. For example, the query -.display asis -[name=mg1456],passwd.org_dir -.endd -might return the string -.display asis -name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" -home=/home/mg1456 shell=/bin/bash shadow="" -.endd -(split over two lines here to fit on the page), whereas -.display asis -[name=mg1456],passwd.org_dir:gcos -.endd -would just return -.display asis -Martin Guerre -.endd -with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry -for the given indexed key. The effect of the \quote@_nisplus\ expansion -operator is to double any quote characters within the text. - - -.section More about MySQL, PostgreSQL, Oracle, and Interbase -.rset SECTsql "~~chapter.~~section" -.index MySQL||lookup type -.index PostgreSQL lookup type -.index lookup||MySQL -.index lookup||PostgreSQL -.index Oracle||lookup type -.index lookup||Oracle -.index Interbase lookup type -.index lookup||Interbase -If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the -\mysql@_servers\, \pgsql@_servers\, \oracle@_servers\, or \ibase@_servers\ -option (as appropriate) must be set to a colon-separated list of server -information. Each item in the list is a slash-separated list of four items: -host name, database name, user name, and password. In the case of Oracle, the -host name field is used for the `service name', and the database name field is -not used and should be empty. For example: -.display asis -hide oracle_servers = oracle.plc.example//ph10/abcdwxyz -.endd -Because password data is sensitive, you should always precede the setting with -`hide', to prevent non-admin users from obtaining the setting via the \-bP-\ -option. Here is an example where two MySQL servers are listed: -.display asis -hide mysql_servers = localhost/users/root/secret:\ - otherhost/users/root/othersecret -.endd -For MySQL and PostgreSQL, a host may be specified as <<name>>:<<port>> but -because this is a colon-separated list, the colon has to be doubled. - -For each query, these parameter groups are tried in order until a connection -and a query succeeds. Queries for these databases are SQL statements, so an -example might be -.display asis -.indent 0 -${lookup mysql{select mailbox from users where id='ph10'}{$value}fail} -.endd -If the result of the query contains more than one field, the data for -each field in the row is returned, preceded by its name, so the result -of -.display asis -.indent 0 -${lookup pgsql{select home,name from users where id='ph10'}{$value}} -.endd -might be -.display asis -home=/home/ph10 name="Philip Hazel" -.endd -Values containing spaces and empty values are double quoted, with embedded -quotes escaped by a backslash. - -If the result of the query contains just one field, the value is passed back -verbatim, without a field name, for example: -.display asis -Philip Hazel -.endd -If the result of the query yields more than one row, it is all concatenated, -with a newline between the data for each row. - -The \quote@_mysql\, \quote@_pgsql\, and \quote@_oracle\ expansion operators -convert newline, tab, carriage return, and backspace to @\n, @\t, @\r, and @\b -respectively, and the characters single-quote, double-quote, and backslash -itself are escaped with backslashes. The \quote@_pgsql\ expansion operator, in -addition, escapes the percent and underscore characters. This cannot be done -for MySQL because these escapes are not recognized in contexts where these -characters are not special. - - -.section Special MySQL features -For MySQL, an empty host name or the use of `localhost' in \mysql@_servers\ -causes a connection to the server on the local host by means of a Unix domain -socket. An alternate socket can be specified in parentheses. The full syntax of -each item in \mysql@_servers\ is: -.display -<<hostname>>@:@:<<port>>(<<socket name>>)/<<database>>/<<user>>/<<password>> -.endd -Any of the three sub-parts of the first field can be omitted. For normal use on -the local host it can be left blank or set to just `localhost'. - -No database need be supplied -- but if it is absent here, it must be given in -the queries. - -If a MySQL query is issued that does not request any data (an insert, update, -or delete command), the result of the lookup is the number of rows affected. -.em -\**Warning**\: this can be misleading. If an update does not actually change -anything (for example, setting a field to the value it already has), the result -is zero because no rows are affected. -.nem - - -.section Special PostgreSQL features -PostgreSQL lookups can also use Unix domain socket connections to the database. -This is usually faster and costs less CPU time than a TCP/IP connection. -However it can be used only if the mail server runs on the same machine as the -database server. A configuration line for PostgreSQL via Unix domain sockets -looks like this: -.display asis -hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... -.endd -In other words, instead of supplying a host name, a path to the socket is -given. The path name is enclosed in parentheses so that its slashes aren't -visually confused with the delimiters for the other server parameters. - -If a PostgreSQL query is issued that does not request any data (an insert, -update, or delete command), the result of the lookup is the number of rows -affected. - - - - -. -. -. -. -. ============================================================================ -.chapter Domain, host, address, and local part lists -.set runningfoot "domain, host, and address lists" -.rset CHAPdomhosaddlists "~~chapter" -.index list||of domains, hosts, etc. -A number of Exim configuration options contain lists of domains, hosts, -email addresses, or local parts. For example, the \hold@_domains\ option -contains a list of domains whose delivery is currently suspended. These lists -are also used as data in ACL statements (see chapter ~~CHAPACL). - -Each item in one of these lists is a pattern to be matched against a domain, -host, email address, or local part, respectively. In the sections below, the -different types of pattern for each case are described, but first we cover some -general facilities that apply to all four kinds of list. - - -.section Expansion of lists -.index expansion||of lists -.em -Each list is expanded as a single string before it is used. The result of -expansion must be a list, possibly containing empty items, which is split up -into separate items for matching. By default, colon is the separator character, -but this can be varied if necessary. See sections ~~SECTlistconstruct and -~~SECTempitelis for details of the list syntax; the second of these discusses -the way you specify empty list items. -.nem - -If the string expansion is forced to fail, Exim behaves as if the item it is -testing (domain, host, address, or local part) is not in the list. Other -expansion failures cause temporary errors. - -If an item in a list is a regular expression, backslashes, dollars and possibly -other special characters in the expression must be protected against -misinterpretation by the string expander. The easiest way to do this is to use -the \"@\N"\ expansion feature to indicate that the contents of the regular -expression should not be expanded. For example, in an ACL you might have: -.display asis -deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : - ${lookup{$domain}lsearch{/badsenders/bydomain}} -.endd -The first item is a regular expression that is protected from expansion by -\"@\N"\, whereas the second uses the expansion to obtain a list of unwanted -senders based on the receiving domain. - - - -.section Negated items in lists -.index list||negation -.index negation in lists -Items in a list may be positive or negative. Negative items are indicated by a -leading exclamation mark, which may be followed by optional white space. A list -defines a set of items (domains, etc). When Exim processes one of these lists, -it is trying to find out whether a domain, host, address, or local part -(respectively) is in the set that is defined by the list. It works like this: - -The list is scanned from left to right. If a positive item is matched, the -subject that is being checked is in the set; if a negative item is matched, the -subject is not in the set. If the end of the list is reached without the -subject having matched any of the patterns, it is in the set if the last item -was a negative one, but not if it was a positive one. For example, the list in -.display asis -domainlist relay_domains = !a.b.c : *.b.c -.endd -matches any domain ending in \*.b.c*\ except for \*a.b.c*\. Domains that match -neither \*a.b.c*\ nor \*@*.b.c*\ do not match, because the last item in the -list is positive. However, if the setting were -.display asis -domainlist relay_domains = !a.b.c -.endd -then all domains other than \*a.b.c*\ would match because the last item in the -list is negative. In other words, a list that ends with a negative item behaves -as if it had an extra item \":*"\ on the end. - -Another way of thinking about positive and negative items in lists is to read -the connector as `or' after a positive item and as `and' after a negative -item. - - -.section File names in lists -.rset SECTfilnamlis "~~chapter.~~section" -.index list||file name in -If an item in a domain, host, address, or local part list is an absolute file -name (beginning with a slash character), each line of the file is read and -processed as if it were an independent item in the list, except that further -file names are not allowed, -and no expansion of the data from the file takes place. -Empty lines in the file are ignored, and the file may also contain comment -lines: -.numberpars $. -For domain and host lists, if a @# character appears anywhere in a line of the -file, it and all following characters are ignored. -.nextp -Because local parts may legitimately contain @# characters, a comment in an -address list or local part list file is recognized only if @# is preceded by -white space or the start of the line. For example: -.display asis -not#comment@x.y.z # but this is a comment -.endd -.endp -Putting a file name in a list has the same effect as inserting each line of the -file as an item in the list (blank lines and comments excepted). However, there -is one important difference: the file is read each time the list is processed, -so if its contents vary over time, Exim's behaviour changes. - -If a file name is preceded by an exclamation mark, the sense of any match -within the file is inverted. For example, if -.display asis -hold_domains = !/etc/nohold-domains -.endd -and the file contains the lines -.display asis -!a.b.c -*.b.c -.endd -then \*a.b.c*\ is in the set of domains defined by \hold@_domains\, whereas any -domain matching \"*.b.c"\ is not. - - -.section An lsearch file is not an out-of-line list -As will be described in the sections that follow, lookups can be used in lists -to provide indexed methods of checking list membership. There has been some -confusion about the way \%lsearch%\ lookups work in lists. Because -an \%lsearch%\ file contains plain text and is scanned sequentially, it is -sometimes thought that it is allowed to contain wild cards and other kinds of -non-constant pattern. This is not the case. The keys in an \%lsearch%\ file are -always fixed strings, just as for any other single-key lookup type. - -If you want to use a file to contain wild-card patterns that form part of a -list, just give the file name on its own, without a search type, as described -in the previous section. - - - -.section Named lists -.rset SECTnamedlists "~~chapter.~~section" -.index named lists -.index list||named -A list of domains, hosts, email addresses, or local parts can be given a name -which is then used to refer to the list elsewhere in the configuration. This is -particularly convenient if the same list is required in several different -places. It also allows lists to be given meaningful names, which can improve -the readability of the configuration. For example, it is conventional to define -a domain list called \*local@_domains*\ for all the domains that are handled -locally on a host, using a configuration line such as -.display asis -domainlist local_domains = localhost:my.dom.example -.endd -Named lists are referenced by giving their name preceded by a plus sign, so, -for example, a router that is intended to handle local domains would be -configured with the line -.display asis -domains = +local_domains -.endd -The first router in a configuration is often one that handles all domains -except the local ones, using a configuration with a negated item like this: -.display asis -dnslookup: - driver = dnslookup - domains = ! +local_domains - transport = remote_smtp - no_more -.endd -The four kinds of named list are created by configuration lines starting with -the words \domainlist\, \hostlist\, \addresslist\, or \localpartlist\, -respectively. Then there follows the name that you are defining, followed by an -equals sign and the list itself. For example: -.display asis -hostlist relay_hosts = 192.168.23.0/24 : my.friend.example -addresslist bad_senders = cdb;/etc/badsenders -.endd -A named list may refer to other named lists: -.display asis -domainlist dom1 = first.example : second.example -domainlist dom2 = +dom1 : third.example -domainlist dom3 = fourth.example : +dom2 : fifth.example -.endd - -\**Warning**\: If the last item in a referenced list is a negative one, the -effect may not be what you intended, because the negation does not propagate -out to the higher level. For example, consider: -.display asis -domainlist dom1 = !a.b -domainlist dom2 = +dom1 : *.b -.endd -The second list specifies `either in the \dom1\ list or \*@*.b*\'. The first -list specifies just `not \*a.b*\', so the domain \*x.y*\ matches it. That means -it matches the second list as well. The effect is not the same as -.display asis -domainlist dom2 = !a.b : *.b -.endd -where \*x.y*\ does not match. It's best to avoid negation altogether in -referenced lists if you can. - -Named lists may have a performance advantage. When Exim is routing an -address or checking an incoming message, it caches the result of tests on named -lists. So, if you have a setting such as -.display asis -domains = +local_domains -.endd -on several of your routers -or in several ACL statements, -the actual test is done only for the first one. However, the caching works only -if there are no expansions within the list itself or any sublists that it -references. In other words, caching happens only for lists that are known to be -the same each time they are referenced. - -By default, there may be up to 16 named lists of each type. This limit can be -extended by changing a compile-time variable. The use of domain and host lists -is recommended for concepts such as local domains, relay domains, and relay -hosts. The default configuration is set up like this. - - -.section Named lists compared with macros -.index list||named compared with macro -.index macro||compared with named list -At first sight, named lists might seem to be no different from macros in the -configuration file. However, macros are just textual substitutions. If you -write -.display asis -ALIST = host1 : host2 -auth_advertise_hosts = !ALIST -.endd -it probably won't do what you want, because that is exactly the same as -.display asis -auth_advertise_hosts = !host1 : host2 -.endd -Notice that the second host name is not negated. However, if you use a host -list, and write -.display asis -hostlist alist = host1 : host2 -auth_advertise_hosts = ! +alist -.endd -the negation applies to the whole list, and so that is equivalent to -.display asis -auth_advertise_hosts = !host1 : !host2 -.endd - - -.section Named list caching -.index list||caching of named -.index caching||named lists -While processing a message, Exim caches the result of checking a named list if -it is sure that the list is the same each time. In practice, this means that -the cache operates only if the list contains no @$ characters, which guarantees -that it will not change when it is expanded. Sometimes, however, you may have -an expanded list that you know will be the same each time within a given -message. For example: -.display asis -domainlist special_domains = \ - ${lookup{$sender_host_address}cdb{/some/file}} -.endd -This provides a list of domains that depends only on the sending host's IP -address. If this domain list is referenced a number of times (for example, -in several ACL lines, or in several routers) the result of the check is not -cached by default, because Exim does not know that it is going to be the -same list each time. - -By appending \"@_cache"\ to \"domainlist"\ you can tell Exim to go ahead and -cache the result anyway. For example: -.display asis -domainlist_cache special_domains = ${lookup{... -.endd -If you do this, you should be absolutely sure that caching is going to do -the right thing in all cases. When in doubt, leave it out. - - -.section Domain lists -.rset SECTdomainlist "~~chapter.~~section" -.index domain list||patterns for -.index list||domain list -Domain lists contain patterns that are to be matched against a mail domain. -The following types of item may appear in domain lists: -.numberpars $. -.index primary host name -.index host||name, matched in domain list -.index \primary@_hostname\ -.index domain list||matching primary host name -.index @@ in a domain list -If a pattern consists of a single @@ character, it matches the local host name, -as set by the \primary@_hostname\ option (or defaulted). This makes it possible -to use the same configuration file on several different hosts that differ only -in their names. -.nextp -.index @@[] in a domain list -.index domain list||matching local IP interfaces -.index domain literal -If a pattern consists of the string \"@@[]"\ it matches any local IP interface -address, enclosed in square brackets, as in an email address that contains a -domain literal. -In today's Internet, the use of domain literals is controversial. -.nextp -.index @@mx@_any -.index @@mx@_primary -.index @@mx@_secondary -.index domain list||matching MX pointers to local host -If a pattern consists of the string \"@@mx@_any"\ it matches any domain that -has an MX record pointing to the local host or to any host that is listed in -.index \hosts@_treat@_as@_local\ -\hosts@_treat@_as@_local\. The items \"@@mx@_primary"\ and \"@@mx@_secondary"\ -are similar, except that the first matches only when a primary MX target is the -local host, and the second only when no primary MX target is the local host, -but a secondary MX target is. `Primary' means an MX record with the lowest -preference value -- there may of course be more than one of them. - -The MX lookup that takes place when matching a pattern of this type is -performed with the resolver options for widening names turned off. Thus, for -example, a single-component domain will \*not*\ be expanded by adding the -resolver's default domain. See the \qualify@_single\ and \search@_parents\ -options of the \%dnslookup%\ router for a discussion of domain widening. - -Sometimes you may want to ignore certain IP addresses when using one of these -patterns. You can specify this by following the pattern with \"/ignore=<<ip -list>>"\, where <<ip list>> is a list of IP addresses. These addresses are -ignored when processing the pattern (compare the \ignore@_target@_hosts\ option -on a router). For example: -.display asis -domains = @mx_any/ignore=127.0.0.1 -.endd -This example matches any domain that has an MX record pointing to one of -the local host's IP addresses other than 127.0.0.1. - -The list of IP addresses is in fact processed by the same code that processes -host lists, so it may contain CIDR-coded network specifications and it may also -contain negative items. - -Because the list of IP addresses is a sublist within a domain list, you have to -be careful about delimiters if there is more than one address. Like any other -list, the default delimiter can be changed. Thus, you might have: -.display asis -domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ - an.other.domain : ... -.endd -so that the sublist uses semicolons for delimiters. When IPv6 addresses are -involved, it is easiest to change the delimiter for the main list as well: -.display asis -domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ - an.other.domain ? ... -.endd - -.nextp -.index asterisk||in domain list -.index domain list||asterisk in -.index domain list||matching `ends with' -If a pattern starts with an asterisk, the remaining characters of the pattern -are compared with the terminating characters of the domain. The use of `$*$' in -domain lists differs from its use in partial matching lookups. In a domain -list, the character following the asterisk need not be a dot, whereas partial -matching works only in terms of dot-separated components. For example, a domain -list item such as \"*key.ex"\ matches \*donkey.ex*\ as well as -\*cipher.key.ex*\. -.nextp -.index regular expressions||in domain list -.index domain list||matching regular expression -If a pattern starts with a circumflex character, it is treated as a regular -expression, and matched against the domain using a regular expression matching -function. The circumflex is treated as part of the regular expression. -References to descriptions of the syntax of regular expressions are given in -chapter ~~CHAPregexp. - -\**Warning**\: Because domain lists are expanded before being processed, you -must escape any backslash and dollar characters in the regular expression, or -use the special \"@\N"\ sequence (see chapter ~~CHAPexpand) to specify that it -is not to be expanded (unless you really do want to build a regular expression -by expansion, of course). -.nextp -.index lookup||in domain list -.index domain list||matching by lookup -If a pattern starts with the name of a single-key lookup type followed by a -semicolon (for example, `dbm;' or `lsearch;'), the remainder of the pattern -must be a file name in a suitable format for the lookup type. For example, for -`cdb;' it must be an absolute path: -.display asis -domains = cdb;/etc/mail/local_domains.cdb -.endd -The appropriate type of lookup is done on the file using the domain name as the -key. In most cases, the data that is looked up is not used; Exim is interested -only in whether or not the key is present in the file. However, when a lookup -is used for the \domains\ option on a router -or a \domains\ condition in an ACL statement, the data is preserved in the -\$domain@_data$\ variable and can be referred to in other router options or -other statements in the same ACL. -.nextp -Any of the single-key lookup type names may be preceded by `partial<<n>>-', -where the <<n>> is optional, for example, -.display asis -domains = partial-dbm;/partial/domains -.endd -This causes partial matching logic to be invoked; a description of how this -works is given in section ~~SECTpartiallookup. -.nextp -.index asterisk||in lookup type -Any of the single-key lookup types may be followed by an asterisk. This causes -a default lookup for a key consisting of a single asterisk to be done if the -original lookup fails. This is not a useful feature when using a domain list to -select particular domains (because any domain would match), but it might have -value if the result of the lookup is being used via the \$domain@_data$\ -expansion variable. -.nextp -If the pattern starts with the name of a query-style lookup type followed by a -semicolon (for example, `nisplus;' or `ldap;'), the remainder of the pattern -must be an appropriate query for the lookup type, as described in chapter -~~CHAPfdlookup. For example: -.display asis -hold_domains = mysql;select domain from holdlist \ - where domain = '$domain'; -.endd -In most cases, the data that is looked up is not used (so for an SQL query, for -example, it doesn't matter what field you select). Exim is interested only in -whether or not the query succeeds. However, when a lookup is used for the -\domains\ option on a router, the data is preserved in the \$domain@_data$\ -variable and can be referred to in other options. -.nextp -.index domain list||matching literal domain name -If none of the above cases apply, a caseless textual comparison is made between -the pattern and the domain. -.endp - -Here is an example that uses several different kinds of pattern: -.display asis -domainlist funny_domains = \ - @ : \ - lib.unseen.edu : \ - *.foundation.fict.example : \ - \N^[1-2]\d{3}\.fict\.example$\N : \ - partial-dbm;/opt/data/penguin/book : \ - nis;domains.byname : \ - nisplus;[name=$domain,status=local],domains.org_dir -.endd -There are obvious processing trade-offs among the various matching modes. Using -an asterisk is faster than a regular expression, and listing a few names -explicitly probably is too. The use of a file or database lookup is expensive, -but may be the only option if hundreds of names are required. Because the -patterns are tested in order, it makes sense to put the most commonly matched -patterns earlier. - - -.section Host lists -.rset SECThostlist "~~chapter.~~section" -.index host list||patterns in -.index list||host list -Host lists are used to control what remote hosts are allowed to do. For -example, some hosts may be allowed to use the local host as a relay, and some -may be permitted to use the SMTP \\ETRN\\ command. Hosts can be identified in -two different ways, by name or by IP address. In a host list, some types of -pattern are matched to a host name, and some are matched to an IP address. -You need to be particularly careful with this when single-key lookups are -involved, to ensure that the right value is being used as the key. - -.section Special host list patterns -.index empty item in hosts list -.index host list||empty string in -If a host list item is the empty string, it matches only when no remote host is -involved. This is the case when a message is being received from a local -process using SMTP on the standard input, that is, when a TCP/IP connection is -not used. - -.index asterisk||in host list -The special pattern `$*$' in a host list matches any host or no host. Neither -the IP address nor the name is actually inspected. - - -.section Host list patterns that match by IP address -.rset SECThoslispatip "~~chapter.~~section" -.index host list||matching IP addresses -If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, -the incoming address actually appears in the IPv6 host as -`@:@:$tt{ffff}:<<v4address>>'. When such an address is tested against a host -list, it is converted into a traditional IPv4 address first. (Not all operating -systems accept IPv4 calls on IPv6 sockets, as there have been some security -concerns.) - -The following types of pattern in a host list check the remote host by -inspecting its IP address: -.numberpars $. -If the pattern is a plain domain name (not a regular expression, not starting -with $*$, not a lookup of any kind), Exim calls the operating system function -to find the associated IP address(es). Exim uses the newer -\*getipnodebyname()*\ function when available, otherwise \*gethostbyname()*\. -This typically causes a forward DNS lookup of the name. The result is compared -with the IP address of the subject host. - -If there is a temporary problem (such as a DNS timeout) with the host name -lookup, a temporary error occurs. For example, if the list is being used in an -ACL condition, the ACL gives a `defer' response, usually leading to a temporary -SMTP error code. If no IP address can be found for the host name, what happens -is described in section ~~SECTbehipnot below. - -.nextp -.index @@ in a host list -If the pattern is `@@', the primary host name is substituted and used as a -domain name, as just described. -.nextp -If the pattern is an IP address, it is matched against the IP address of the -subject host. IPv4 addresses are given in the normal `dotted-quad' notation. -IPv6 addresses can be given in colon-separated format, but the colons have to -be doubled so as not to be taken as item separators when the default list -separator is used. IPv6 addresses are recognized even when Exim is compiled -without IPv6 support. This means that if they appear in a host list on an -IPv4-only host, Exim will not treat them as host names. They are just addresses -that can never match a client host. -.nextp -.index @@[] in a host list -If the pattern is `@@[]', it matches the IP address of any IP interface on -the local host. For example, if the local host is an IPv4 host with one -interface address 10.45.23.56, these two ACL statements have the same effect: -.display asis -accept hosts = 127.0.0.1 : 10.45.23.56 -accept hosts = @[] -.endd -.nextp -If the pattern is an IP address followed by a slash and a mask length (for -example 10.11.42.0/24), it is matched against the IP address of the subject -host under the given mask. -This allows, an entire network of hosts to be included (or excluded) by a -single item. -.index CIDR notation -The mask uses CIDR notation; it specifies the number of address bits that must -match, starting from the most significant end of the address. - -\**Note**\: the mask is \*not*\ a count of addresses, nor is it the high number -of a range of addresses. It is the number of bits in the network portion of the -address. The above example specifies a 24-bit netmask, so it matches all 256 -addresses in the 10.11.42.0 network. An item such as -.display asis -192.168.23.236/31 -.endd -matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value of -32 for an IPv4 address is the same as no mask at all; just a single address -matches. - -Here is another example which shows an IPv4 and an IPv6 network: -.display asis -recipient_unqualified_hosts = 192.168.0.0/16: \ - 3ffe::ffff::836f::::/48 -.endd -The doubling of list separator characters applies only when these items -appear inline in a host list. It is not required when indirecting via a file. -For example, -.display asis -recipient_unqualified_hosts = /opt/exim/unqualnets -.endd -could make use of a file containing -.display asis -172.16.0.0/12 -3ffe:ffff:836f::/48 -.endd -to have exactly the same effect as the previous example. When listing IPv6 -addresses inline, it is usually more convenient to use the facility for -changing separator characters. This list contains the same two networks: -.display asis -recipient_unqualified_hosts = <; 172.16.0.0/12; \ - 3ffe:ffff:836f::/48 -.endd -The separator is changed to semicolon by the leading `<;' at the start of the -list. -.endp - - -.section Host list patterns for single-key lookups by host address -.rset SECThoslispatsikey "~~chapter.~~section" -.index host list||lookup of IP address -When a host is to be identified by a single-key lookup of its complete IP -address, the pattern takes this form: -.display -net-<<single-key-search-type>>;<<search-data>> -.endd -For example: -.display asis -hosts_lookup = net-cdb;/hosts-by-ip.db -.endd -The text form of the IP address of the subject host is used as the lookup key. -IPv6 addresses are converted to an unabbreviated form, using lower case -letters, with dots as separators because colon is the key terminator in -\%lsearch%\ files. [Colons can in fact be used in keys in \%lsearch%\ files by -quoting the keys, but this is a facility that was added later.] The data -returned by the lookup is not used. - -.index IP address||masking -.index host list||masked IP address -Single-key lookups can also be performed using masked IP addresses, using -patterns of this form: -.display -net<<number>>-<<single-key-search-type>>;<<search-data>> -.endd -For example: -.display asis -net24-dbm;/networks.db -.endd -The IP address of the subject host is masked using <<number>> as the mask -length. A textual string is constructed from the masked value, followed by the -mask, and this is used as the lookup key. For example, if the host's IP address -is 192.168.34.6, the key that is looked up for the above example is -`192.168.34.0/24'. IPv6 addresses are converted to a text value using lower -case letters and dots as separators instead of the more usual colon, because -colon is the key terminator in \%lsearch%\ files. Full, unabbreviated IPv6 -addresses are always used. - -\**Warning**\: Specifing \net32@-\ (for an IPv4 address) or \net128@-\ (for an -IPv6 address) is not the same as specifing just \net@-\ without a number. In -the former case the key strings include the mask value, whereas in the latter -case the IP address is used on its own. - - -.section Host list patterns that match by host name -.rset SECThoslispatnam "~~chapter.~~section" -.index host||lookup failures -.index unknown host name -.index host list||matching host name -There are several types of pattern that require Exim to know the name of the -remote host. These are either wildcard patterns or lookups by name. (If a -complete hostname is given without any wildcarding, it is used to find an IP -address to match against, as described in the section ~~SECThoslispatip above.) - -If the remote host name is not already known when Exim encounters one of these -patterns, it has to be found from the IP address. -Although many sites on the Internet are conscientious about maintaining reverse -DNS data for their hosts, there are also many that do not do this. -Consequently, a name cannot always be found, and this may lead to unwanted -effects. Take care when configuring host lists with wildcarded name patterns. -Consider what will happen if a name cannot be found. - -Because of the problems of determining host names from IP addresses, matching -against host names is not as common as matching against IP addresses. - -By default, in order to find a host name, Exim first does a reverse DNS lookup; -if no name is found in the DNS, the system function (\*gethostbyaddr()*\ or -\*getipnodebyaddr()*\ if available) is tried. The order in which these lookups -are done can be changed by setting the \host@_lookup@_order\ option. - -There are some options that control what happens if a host name cannot be -found. These are described in section ~~SECTbehipnot below. - - -.index host||alias for -.index alias for host -As a result of aliasing, hosts may have more than one name. When processing any -of the following types of pattern, all the host's names are checked: -.numberpars $. -.index asterisk||in host list -If a pattern starts with `$*$' the remainder of the item must match the end of -the host name. For example, \"*.b.c"\ matches all hosts whose names end in -\*.b.c*\. This special simple form is provided because this is a very common -requirement. Other kinds of wildcarding require the use of a regular -expression. -.nextp -.index regular expressions||in host list -.index host list||regular expression in -If the item starts with `@^' it is taken to be a regular expression which is -matched against the host name. For example, -.display asis -^(a|b)\.c\.d$ -.endd -is a regular expression that matches either of the two hosts \*a.c.d*\ or -\*b.c.d*\. When a regular expression is used in a host list, you must take care -that backslash and dollar characters are not misinterpreted as part of the -string expansion. The simplest way to do this is to use \"@\N"\ to mark that -part of the string as non-expandable. For example: -.display asis -sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... -.endd -\**Warning**\: If you want to match a complete host name, you must include the -\"@$"\ terminating metacharacter in the regular expression, as in the above -example. Without it, a match at the start of the host name is all that is -required. -.endp - - -.section Behaviour when an IP address or name cannot be found -.rset SECTbehipnot "~~chapter.~~section" -.index host||lookup failures -While processing a host list, Exim may need to look up an IP address from a -name (see section ~~SECThoslispatip), or it may need to look up a host name -from an IP address (see section ~~SECThoslispatnam). In either case, the -behaviour when it fails to find the information it is seeking is the same. - -.index \"+include@_unknown"\ -.index \"+ignore@_unknown"\ -By default, Exim behaves as if the host does not match the list. This may not -always be what you want to happen. To change Exim's behaviour, the special -items \"+include@_unknown"\ or \"+ignore@_unknown"\ may appear in the list (at -top level -- they are not recognized in an indirected file). -.numberpars $. -If any item that follows \"+include@_unknown"\ requires information that -cannot found, Exim behaves as if the host does match the list. For example, -.display asis -host_reject_connection = +include_unknown:*.enemy.ex -.endd -rejects connections from any host whose name matches \"*.enemy.ex"\, and also -any hosts whose name it cannot find. -.nextp -If any item that follows \"+ignore@_unknown"\ requires information that cannot -be found, Exim ignores that item and proceeds to the rest of the list. For -example: -.display asis -accept hosts = +ignore_unknown : friend.example : \ - 192.168.4.5 -.endd -accepts from any host whose name is \*friend.example*\ and from 192.168.4.5, -whether or not its host name can be found. Without \"+ignore@_unknown"\, if no -name can be found for 192.168.4.5, it is rejected. -.endp -Both \"+include@_unknown"\ and \"+ignore@_unknown"\ may appear in the same -list. The effect of each one lasts until the next, or until the end of the -list. - -\**Note**\: This section applies to permanent lookup failures. It does \*not*\ -apply to temporary DNS errors. They always cause a defer action. - - -.section Host list patterns for single-key lookups by host name -.rset SECThoslispatnamsk "~~chapter.~~section" -.index host||lookup failures -.index unknown host name -.index host list||matching host name -If a pattern is of the form -.display -<<single-key-search-type>>;<<search-data>> -.endd -for example -.display asis -dbm;/host/accept/list -.endd -a single-key lookup is performend, using the host name as its key. If the -lookup succeeds, the host matches the item. The actual data that is looked up -is not used. - -\**Reminder**\: With this kind of pattern, you must have host $it{names} as -keys in the file, not IP addresses. If you want to do lookups based on IP -addresses, you must precede the search type with `net-' (see section -~~SECThoslispatsikey). There is, however, no reason why you could not use two -items in the same list, one doing an address lookup and one doing a name -lookup, both using the same file. - - -.section Host list patterns for query-style lookups -If a pattern is of the form -.display -<<query-style-search-type>>;<<query>> -.endd -the query is obeyed, and if it succeeds, the host matches the item. The actual -data that is looked up is not used. The variables \$sender@_host@_address$\ and -\$sender@_host@_name$\ can be used in the query. For example: -.display asis -hosts_lookup = pgsql;\ - select ip from hostlist where ip='$sender_host_address' -.endd -The value of \$sender@_host@_address$\ for an IPv6 address contains colons. You -can use the \sg\ expansion item to change this if you need to. If you want to -use masked IP addresses in database queries, you can use the \mask\ expansion -operator. - -If the query contains a reference to \$sender@_host@_name$\, Exim automatically -looks up the host name if has not already done so. (See section -~~SECThoslispatnam for comments on finding host names.) - -Historical note: prior to release 4.30, Exim would always attempt to find a -host name before running the query, unless the search type was preceded by -\"net-"\. This is no longer the case. For backwards compatibility, \"net-"\ is -still recognized for query-style lookups, but its presence or absence has no -effect. (Of course, for single-key lookups, \"net-"\ $it{is} important. -See section ~~SECThoslispatsikey.) - - -.section Mixing wildcarded host names and addresses in host lists -.rset SECTmixwilhos "~~chapter.~~section" -.index host list||mixing names and addresses in -If you have name lookups or wildcarded host names and IP addresses in the same -host list, you should normally put the IP addresses first. For example, in an -ACL you could have: -.display asis -accept hosts = 10.9.8.7 : *.friend.example -.endd -The reason for this lies in the left-to-right way that Exim processes lists. -It can test IP addresses without doing any DNS lookups, but when it reaches an -item that requires a host name, it fails if it cannot find a host name to -compare with the pattern. If the above list is given in the opposite order, the -\accept\ statement fails for a host whose name cannot be found, even if its -IP address is 10.9.8.7. - -If you really do want to do the name check first, and still recognize the IP -address, you can rewrite the ACL like this: -.display asis -accept hosts = *.friend.example -accept hosts = 10.9.8.7 -.endd -If the first \accept\ fails, Exim goes on to try the second one. See chapter -~~CHAPACL for details of ACLs. - - - - -.section Address lists -.index list||address list -.index address list||empty item -.index address list||patterns -.rset SECTaddresslist "~~chapter.~~section" -Address lists contain patterns that are matched against mail addresses. There -is one special case to be considered: the sender address of a bounce message is -always empty. You can test for this by providing an empty item in an address -list. For example, you can set up a router to process bounce messages by -using this option setting: -.display asis -senders = : -.endd -The presence of the colon creates an empty item. If you do not provide any -data, the list is empty and matches nothing. The empty sender can also be -detected by a regular expression that matches an empty string, -.em -and by a query-style lookup that succeeds when \$sender@_address$\ is empty. - -The following kinds of address list pattern can match any address, including -the empty address that is characteristic of bounce message senders: -.nem -.numberpars $. -.em -As explained above, if a pattern item is empty, it matches the empty address -(and no others). -.nem -.nextp -.index regular expressions||in address list -.index address list||regular expression in -If (after expansion) a pattern starts with `@^', a regular expression match is -done against the complete address, with the pattern as the regular expression. -You must take care that backslash and dollar characters are not misinterpreted -as part of the string expansion. The simplest way to do this is to use \"@\N"\ -to mark that part of the string as non-expandable. For example: -.display asis -deny senders = \N^\d{8}.+@spamhaus.example$\N : ... -.endd -The \"@\N"\ sequences are removed by the expansion, so the item does start -with `@^' by the time it is being interpreted as an address pattern. -.nextp -.index address list||lookup for complete address -Complete addresses can be looked up by using a pattern that starts with a -lookup type terminated by a semicolon, followed by the data for the lookup. For -example: -.display asis -deny senders = cdb;/etc/blocked.senders : \ - mysql;select address from blocked where \ - address='${quote_mysql:$sender_address}' -.endd -.em -Both query-style and single-key lookup types can be used. For a single-key -lookup type, Exim uses the complete address as the key. However, empty keys are -not supported for single-key lookups, so a match against the empty address -always fails. This restriction does not apply to query-style lookups. - -.nem -Partial matching for single-key lookups (section ~~SECTpartiallookup) cannot be -used, and is ignored if specified, with an entry being written to the panic -log. -.index @*@@ with single-key lookup -However, you can configure lookup defaults, as described in section -~~SECTdefaultvaluelookups, but this is useful only for the `$*$@@' type of -default. For example, with this lookup: -.display asis -accept senders = lsearch*@;/some/file -.endd -the file could contains lines like this: -.display asis -user1@domain1.example -*@domain2.example -.endd -and for the sender address \*nimrod@@jaeger.example*\, the sequence of keys -that are tried is: -.display asis -nimrod@jaeger.example -*@jaeger.example -* -.endd -\**Warning 1**\: Do not include a line keyed by `$*$' in the file, because that -would mean that every address matches, thus rendering the test useless. - -\**Warning 2**\: Do not confuse these two kinds of item: -.display asis -deny recipients = dbm*@;/some/file -deny recipients = *@dbm;/some/file -.endd -The first does a whole address lookup, with defaulting, as just described, -because it starts with a lookup type. The second matches the local part and -domain independently, as described in a bullet point below. -.endp - - -.em -The following kinds of address list pattern can match only non-empty addresses. -If the subject address is empty, a match against any of these pattern types -always fails. -.nem - -.numberpars $. -.index @@@@ with single-key lookup -.index address list||@@@@ lookup type -.index address list||split local part and domain -If a pattern starts with `@@@@' followed by a single-key lookup item -(for example, \"@@@@lsearch;/some/file"\), the address that is being checked is -split into a local part and a domain. The domain is looked up in the file. If -it is not found, there is no match. If it is found, the data that is looked up -from the file is treated as a colon-separated list of local part patterns, each -of which is matched against the subject local part in turn. - -.index asterisk||in address list -The lookup may be a partial one, and/or one involving a search for a default -keyed by `$*$' (see section ~~SECTdefaultvaluelookups). The local part patterns -that are looked up can be regular expressions or begin with `$*$', or even be -further lookups. They may also be independently negated. For example, with -.display asis -deny senders = @@dbm;/etc/reject-by-domain -.endd -the data from which the DBM file is built could contain lines like -.display asis -baddomain.com: !postmaster : * -.endd -to reject all senders except \postmaster\ from that domain. -.index local part||starting with ! -If a local part that actually begins with an exclamation mark is required, it -has to be specified using a regular expression. In \%lsearch%\ files, an entry -may be split over several lines by indenting the second and subsequent lines, -but the separating colon must still be included at line breaks. White space -surrounding the colons is ignored. For example: -.display asis -aol.com: spammer1 : spammer2 : ^[0-9]+$ : - spammer3 : spammer4 -.endd -As in all colon-separated lists in Exim, a colon can be included in an item by -doubling. - -If the last item in the list starts with a right angle-bracket, the remainder -of the item is taken as a new key to look up in order to obtain a continuation -list of local parts. The new key can be any sequence of characters. Thus one -might have entries like -.display asis -aol.com: spammer1 : spammer 2 : >* -xyz.com: spammer3 : >* -*: ^\d{8}$ -.endd -in a file that was searched with \@@@@dbm$*$\, to specify a match for 8-digit -local parts for all domains, in addition to the specific local parts listed for -each domain. Of course, using this feature costs another lookup each time a -chain is followed, but the effort needed to maintain the data is reduced. -.index loop||in lookups -It is possible to construct loops using this facility, and in order to catch -them, the chains may be no more than fifty items long. -.nextp -The @@@@<<lookup>> style of item can also be used with a query-style -lookup, but in this case, the chaining facility is not available. The lookup -can only return a single list of local parts. -.nextp -If a pattern contains an @@ character, but is not a regular expression and does -not begin with a lookup type as described above, the local part of the subject -address is compared with the local part of the pattern, which may start with an -asterisk. If the local parts match, the domain is checked in exactly the same -way as for a pattern in a domain list. For example, the domain can be -wildcarded, refer to a named list, or be a lookup: -.display asis -deny senders = *@*.spamming.site:\ - *@+hostile_domains:\ - bozo@partial-lsearch;/list/of/dodgy/sites:\ -.newline - *@dbm;/bad/domains.db -.endd -.index local part||starting with ! -.index address list||local part starting with ! -If a local part that begins with an exclamation mark is required, it has to be -specified using a regular expression, because otherwise the exclamation mark is -treated as a sign of negation. -.nextp -If a pattern is not one of the above syntax forms, that is, if a -.em -non-empty -.nem -pattern that is not a regular expression or a lookup does not contain an @@ -character, it is matched against the domain part of the subject address. The -only two formats that are recognized this way are a literal domain, or a domain -pattern that starts with $*$. In both these cases, the effect is the same as if -\"*@@"\ preceded the pattern. -.endp - -\**Warning**\: there is an important difference between the address list items -in these two examples: -.display asis -senders = +my_list -senders = *@+my_list -.endd -In the first one, \"my@_list"\ is a named address list, whereas in the second -example it is a named domain list. - - - -.section Case of letters in address lists -.rset SECTcasletadd "~~chapter.~~section" -.index case of local parts -.index address list||case forcing -.index case forcing in address lists -Domains in email addresses are always handled caselessly, but for local parts -case may be significant on some systems (see \caseful@_local@_part\ for how -Exim deals with this when routing addresses). However, RFC 2505 ($it{Anti-Spam -Recommendations for SMTP MTAs}) suggests that matching of addresses to blocking -lists should be done in a case-independent manner. Since most address lists in -Exim are used for this kind of control, Exim attempts to do this by default. - -The domain portion of an address is always lowercased before matching it to an -address list. The local part is lowercased by default, and any string -comparisons that take place are done caselessly. This means that the data in -the address list itself, in files included as plain file names, and in any file -that is looked up using the `@@@@' mechanism, can be in any case. However, the -keys in files that are looked up by a search type other than \%lsearch%\ (which -works caselessly) must be in lower case, because these lookups are not -case-independent. - -.index \"+caseful"\ -To allow for the possibility of caseful address list matching, if an item in -an address list is the string `+caseful', the original case of the local -part is restored for any comparisons that follow, and string comparisons are no -longer case-independent. This does not affect the domain, which remains in -lower case. However, although independent matches on the domain alone are still -performed caselessly, regular expressions that match against an entire address -become case-sensitive after `+caseful' has been seen. - - -.section Local part lists -.rset SECTlocparlis "~~chapter.~~section" -.index list||local part list -.index local part||list -Case-sensitivity in local part lists is handled in the same way as for address -lists, as just described. The `+caseful' item can be used if required. In a -setting of the \local@_parts\ option in a router with \caseful@_local@_part\ -set false, the subject is lowercased and the matching is initially -case-insensitive. In this case, `+caseful' will restore case-sensitive matching -in the local part list, but not elsewhere in the router. If -\caseful@_local@_part\ is set true in a router, matching in the \local@_parts\ -option is case-sensitive from the start. - -If a local part list is indirected to a file (see section ~~SECTfilnamlis), -comments are handled in the same way as address lists -- they are recognized -only if the @# is preceded by white space or the start of the line. -Otherwise, local part lists are matched in the same way as domain lists, except -that the special items that refer to the local host (\"@@"\, \"@@[]"\, -\"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\) are not recognized. -Refer to section ~~SECTdomainlist for details of the other available item -types. - - - -. -. -. -. -. ============================================================================ -.chapter String expansions -.set runningfoot "string expansions" -.rset CHAPexpand ~~chapter -.index expansion||of strings -Many strings in Exim's run time configuration are expanded before use. Some of -them are expanded every time they are used; others are expanded only once. - -When a string is being expanded it is copied verbatim from left to right except -when a dollar or backslash character is encountered. A dollar specifies the -start of a portion of the string which is interpreted and replaced as described -below in section ~~SECTexpansionitems onwards. Backslash is used as an escape -character, as described in the following section. - - -.section Literal text in expanded strings -.rset SECTlittext "~~chapter.~~section" -.index expansion||including literal text -An uninterpreted dollar can be included in an expanded string by putting a -backslash in front of it. A backslash can be used to prevent any special -character being treated specially in an expansion, including itself. If the -string appears in quotes in the configuration file, two backslashes are -required because the quotes themselves cause interpretation of backslashes when -the string is read in (see section ~~SECTstrings). - -.index expansion||non-expandable substrings -A portion of the string can specified as non-expandable by placing it between -two occurrences of \"@\N"\. This is particularly useful for protecting regular -expressions, which often contain backslashes and dollar signs. For example: -.display asis -deny senders = \N^\d{8}[a-z]@some\.site\.example$\N -.endd -On encountering the first \"@\N"\, the expander copies subsequent characters -without interpretation until it reaches the next \"@\N"\ or the end of the -string. - - -.section Character escape sequences in expanded strings -.index expansion||escape sequences -A backslash followed by one of the letters `n', `r', or `t' in an expanded -string is recognized as an escape sequence for the character newline, carriage -return, or tab, respectively. A backslash followed by up to three octal digits -is recognized as an octal encoding for a single character, and a backslash -followed by `x' and up to two hexadecimal digits is a hexadecimal encoding. - -These escape sequences are also recognized in quoted strings when they are read -in. Their interpretation in expansions as well is useful for unquoted strings, -and for other cases such as looked-up strings that are then expanded. - -.section Testing string expansions -.index expansion||testing -.index testing||string expansion -.index \-be-\ option -Many expansions can be tested by calling Exim with the \-be-\ option. This takes -the command arguments, or lines from the standard input if there are no -arguments, runs them through the string expansion code, and writes the results -to the standard output. Variables based on configuration values are set up, but -since no message is being processed, variables such as \$local@_part$\ have no -value. Nevertheless the \-be-\ option can be useful for checking out file and -database lookups, and the use of expansion operators such as \sg\, \substr\ and -\nhash\. - -Exim gives up its root privilege when it is called with the \-be-\ option, and -instead runs under the uid and gid it was called with, to prevent users from -using \-be-\ for reading files to which they do not have access. - - -.em -.section Forced expansion failure -.rset SECTforexpfai "~~chapter.~~section" -.index expansion||forced failure -A number of expansions that are described in the following section have -alternative `true' and `false' substrings, enclosed in curly brackets. Which -one is used depends on some condition that is evaluated as part of the -expansion. If, instead of a `false' substring, the word `fail' is used (not in -curly brackets), the entire string expansion fails in a way that can be -detected by the code that requested the expansion. This is called `forced -expansion failure', and its consequences depend on the circumstances. In some -cases it is no different from any other expansion failure, but in others a -different action may be taken. Such variations are mentioned in the -documentation of the option that is being expanded. -.nem - - -.section Expansion items -.rset SECTexpansionitems "~~chapter.~~section" -The following items are recognized in expanded strings. White space may be used -between sub-items that are keywords or substrings enclosed in braces inside an -outer set of braces, to improve readability. \**Warning**\: Within braces, -white space is significant. - -.startitems - -.item "@$<<variable name>>#$rm{or}#@$@{<<variable name>>@}" -.index expansion||variables -Substitute the contents of the named variable, for example -.display asis -$local_part -${domain} -.endd -The second form can be used to separate the name from subsequent alphanumeric -characters. This form (using curly brackets) is available only for variables; -it does $it{not} apply to message headers. The names of the variables are given -in section ~~SECTexpvar below. If the name of a non-existent variable is given, -the expansion fails. - -.item "@$@{<<op>>:<<string>>@}" -.index expansion||operators -The string is first itself expanded, and then the operation specified by <<op>> -is applied to it. For example, -.display asis -${lc:$local_part} -.endd -The string starts with the first character after the colon, which may be -leading white space. A list of operators is given in section ~~SECTexpop below. -The operator notation is used for simple expansion items that have just one -argument, because it reduces the number of braces and therefore makes the -string easier to understand. - -.item "@$@{extract@{<<key>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" -.index expansion||extracting substrings by key -The key and <<string1>> are first expanded separately. -Leading and trailing whitespace is removed from the key (but not from any of -the strings). -The key must not consist entirely of digits. The expanded <<string1>> must be -of the form: -.display -<<key1>> = <<value1>> <<key2>> = <<value2>> ... -.endd -where the equals signs and spaces (but not both) are optional. If any of the -values contain white space, they must be enclosed in double quotes, and any -values that are enclosed in double quotes are subject to escape processing as -described in section ~~SECTstrings. The expanded <<string1>> is searched for -the value that corresponds to the key. The search is case-insensitive. If the -key is found, <<string2>> is expanded, and replaces the whole item; otherwise -<<string3>> is used. During the expansion of <<string2>> the variable \$value$\ -contains the value that has been extracted. Afterwards, it is restored to any -previous value it might have had. - -If @{<<string3>>@} is omitted, the item is replaced by an empty string if the -key is not found. If @{<<string2>>@} is also omitted, the value that was -extracted is used. Thus, for example, these two expansions are identical, and -yield `2001': -.display -@$@{extract@{gid@}{uid=1984 gid=2001@}@} -@$@{extract@{gid@}{uid=1984 gid=2001@}@{@$value@}@} -.endd -Instead of @{<<string3>>@} the word `fail' (not in curly brackets) can appear, -for example: -.display -@$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @} -.endd -This forces an expansion failure (see section ~~SECTforexpfai); @{<<string2>>@} -must be present for `fail' to be recognized. - - -.item "@$@{extract@{<<number>>@}@{<<separators>>@}@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" -.index expansion||extracting substrings by number -The <<number>> argument must consist entirely of decimal digits, -apart from leading and trailing whitespace, which is ignored. -This is what distinguishes this form of \extract\ from the previous kind. It -behaves in the same way, except that, instead of extracting a named field, it -extracts from <<string1>> the field whose number is given as the first -argument. You can use \$value$\ in <<string2>> or \"fail"\ instead of -<<string3>> as before. - -The fields in the string are separated by any one of the characters in the -separator string. These may include space or tab characters. -The first field is numbered one. If the number is negative, the fields are -counted from the end of the string, with the rightmost one numbered -1. If the -number given is zero, the entire string is returned. If the modulus of the -number is greater than the number of fields in the string, the result is the -expansion of <<string3>>, or the empty string if <<string3>> is not provided. -For example: -.display asis -${extract{2}{:}{x:42:99:& Mailer::/bin/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 these numbers, that is, if <<string1>> -and <<string2>> do not change when they are expanded, you can use the -simpler operator notation that avoids some of the braces: -.display -@$@{hash@_<<n>>@_<<m>>:<<string>>@} -.endd -The second number is optional (in both notations). - -If <<n>> is greater than or equal to the length of the string, the expansion -item returns the string. Otherwise it computes a new string of length <<n>> by -applying a hashing function to the string. The new string consists of -characters taken from the first <<m>> characters of the string -.display asis -abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 -.endd -If <<m>> is not present the value 26 is used, so that only lower case -letters appear. For example: -.display -@$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\ -@$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\ -@$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\ -.endd - - -.item "@$header@_<<header name>>:#$rm{or}#@$h@_<<header name>>:" -.item "@$bheader@_<<header name>>:#$rm{or}#@$bh@_<<header name>>:" -.item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" -.index expansion||header insertion -.index \$header@_$\ -.index \$bheader@_$\ -.index \$rheader@_$\ -.index header lines||in expansion strings -.index header lines||character sets -.index header lines||decoding -Substitute the contents of the named message header line, for example -.display asis -$header_reply-to: -.endd -The newline that terminates a header line is not included in the expansion, but -internal newlines (caused by splitting the header line over several physical -lines) may be present. - -The difference between \rheader\, \bheader\, and \header\ is in the way the -data in the header line is interpreted. -.numberpars $. -.index whitespace||in header lines -\rheader\ gives the original `raw' content of the header line, with no -processing at all, and without the removal of leading and trailing whitespace. -.nextp -.index base64 encoding||in header lines -\bheader\ removes leading and trailing whitespace, and then decodes base64 or -quoted-printable MIME `words' within the header text, but does no character -set translation. If decoding of what looks superficially like a MIME `word' -fails, the raw string is returned. -.index binary zero||in header line -If decoding produces a binary zero character, it is replaced by a question mark --- this is what Exim does for binary zeros that are actually received in header -lines. -.nextp -\header\ tries to translate the string as decoded by \bheader\ to a standard -character set. This is an attempt to produce the same string as would be -displayed on a user's MUA. If translation fails, the \bheader\ string is -returned. Translation is attempted only on operating systems that support the -\*iconv()*\ function. This is indicated by the compile-time macro -\\HAVE@_ICONV\\ in a system Makefile or in \(Local/Makefile)\. -.endp - -In a filter file, the target character set for \header\ can be specified by a -command of the following form: -.display asis -headers charset "UTF-8" -.endd -This command affects all references to \$h@_$\ (or \$header@_$\) expansions in -subsequently obeyed filter commands. In the absence of this command, the target -character set in a filter is taken from the setting of the \headers@_charset\ -option in the runtime configuration. The value of this option defaults to the -value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The ultimate default is -ISO-8859-1. - -Header names follow the syntax of RFC 2822, which states that they may contain -any printing characters except space and colon. Consequently, curly brackets -$it{do not} terminate header names, and should not be used to enclose them as -if they were variables. Attempting to do so causes a syntax error. - -Only header lines that are common to all copies of a message are visible to -this mechanism. These are the original header lines that are received with the -message, and any that are added by -an ACL \warn\ statement or by -a system filter. Header lines that are added to a particular copy of a message -by a router or transport are not accessible. - -For incoming SMTP messages, no header lines are visible in ACLs that are obeyed -before the \\DATA\\ ACL, because the header structure is not set up until the -message is received. Header lines that are added by \warn\ statements in a -\\RCPT\\ ACL (for example) are saved until the message's incoming header lines -are available, at which point they are added. When a \\DATA\\ ACL is running, -however, header lines added by earlier ACLs are visible. - -Upper case and lower case letters are synonymous in header names. If the -following character is white space, the terminating colon may be omitted, but -this is not recommended, because you may then forget it when it is needed. When -white space terminates the header name, it is included in the expanded string. -If the message does not contain the given header, the expansion item is -replaced by an empty string. (See the \def\ condition in section ~~SECTexpcond -for a means of testing for the existence of a header.) - -If there is more than one header with the same name, they are all concatenated -to form the substitution string, up to a maximum length of 64K. A newline -character is inserted between each line. -For the \header\ expansion, for those headers that contain lists of addresses, -a comma is also inserted at the junctions between lines. This does not happen -for the \rheader\ expansion. - - - -.item "@$@{hmac@{<<hashname>>@}@{<<secret>>@}@{<<string>>@}@}" -.index expansion||hmac hashing -This function uses cryptographic hashing (either MD5 or SHA-1) to convert a -shared secret and some text into a message authentication code, as specified in -RFC 2104. -This differs from \"@$@{md5:secret@_text...@}"\ or -\"@$@{sha1:secret@_text...@}"\ in that the hmac step adds a signature to the -cryptographic hash, allowing for authentication that is not possible with MD5 -or SHA-1 alone. -The hash name must expand to either \"md5"\ or \"sha1"\ at present. For -example: -.display asis -${hmac{md5}{somesecret}{$primary_hostname $tod_log}} -.endd -For the hostname \*mail.example.com*\ and time 2002-10-17 11:30:59, this -produces: -.display asis -dd97e3ba5d1a61b5006108f8c8252953 -.endd -As an example of how this might be used, you might put in the main part of -an Exim configuration: -.display asis -SPAMSCAN_SECRET=cohgheeLei2thahw -.endd -In a router or a transport you could then have: -.display asis -headers_add = \ - X-Spam-Scanned: ${primary_hostname} ${message_id} \ - ${hmac{md5}{SPAMSCAN_SECRET}\ - {${primary_hostname},${message_id},$h_message-id:}} -.endd -Then given a message, you can check where it was scanned by looking at the -::X-Spam-Scanned:: header line. If you know the secret, you can check that this -header line is authentic by recomputing the authentication code from the host -name, message ID and the ::Message-id:: header line. This can be done using -Exim's \-be-\ option, or by other means, for example by using the -\*hmac@_md5@_hex()*\ function in Perl. - - -.item "@${if <<condition>> @{<<string1>>@}@{<<string2>>@}@}" -.index expansion||conditional -If <<condition>> is true, <<string1>> is expanded and replaces the whole item; -otherwise <<string2>> is used. The available conditions are described in -section ~~SECTexpcond below. For example: -.display asis -${if eq {$local_part}{postmaster} {yes}{no} } -.endd -The second string need not be present; if it is not and the condition is not -true, the item is replaced with nothing. Alternatively, the word `fail' may be -present instead of the second string (without any curly brackets). In this -case, the expansion is forced to fail if the condition is not true (see section -~~SECTforexpfai). - -.em -If both strings are omitted, the result is the string \"true"\ if the condition -is true, and the empty string if the condition is false. This makes it less -cumbersome to write custom ACL and router conditions. For example, instead of -.display asis -condition = ${if >{$acl_m4}{3}{true}{false}} -.endd -you can use -.display asis -condition = ${if >{$acl_m4}{3}} -.endd -.nem - - -.item "@$@{length@{<<string1>>@}@{<<string2>>@}@}" -.index expansion||string truncation -The \length\ item is used to extract the initial portion of a string. Both -strings are expanded, and the first one must yield a number, <<n>>, say. If you -are using a fixed value for the number, that is, if <<string1>> does not change -when expanded, you can use the simpler operator notation that avoids some of -the braces: -.display -@$@{length@_<<n>>:<<string>>@} -.endd -The result of this item is either the first <<n>> characters or the whole -of <<string2>>, whichever is the shorter. Do not confuse \length\ with -\strlen\, which gives the length of a string. - - -.item "@${lookup@{<<key>>@} <<search type>> @{<<file>>@} @{<<string1>>@} @{<<string2>>@}@}" -.item "@${lookup <<search type>> @{<<query>>@} @{<<string1>>@} @{<<string2>>@}@}" -.index expansion||lookup in -.index file||lookup -.index lookup||in expanded string -These items specify data lookups in files and databases, as discussed in -chapter ~~CHAPfdlookup. The first form is used for single-key lookups, and the -second is used for query-style lookups. The <<key>>, <<file>>, and <<query>> -strings are expanded before use. - -If there is any white space in a lookup item which is part of a filter command, -a retry or rewrite rule, a routing rule for the \%manualroute%\ router, or any -other place where white space is significant, the lookup item must be enclosed -in double quotes. The use of data lookups in users' filter files may be locked -out by the system administrator. - -.index \$value$\ -If the lookup succeeds, <<string1>> is expanded and replaces the entire item. -During its expansion, the variable \$value$\ contains the data returned by the -lookup. Afterwards it reverts to the value it had previously (at the outer -level it is empty). If the lookup fails, <<string2>> is expanded and replaces -the entire item. If @{<<string2>>@} is omitted, the replacement is the empty -string on failure. If <<string2>> is provided, it can itself be a nested -lookup, thus providing a mechanism for looking up a default value when the -original lookup fails. - -If a nested lookup is used as part of <<string1>>, \$value$\ contains the data -for the outer lookup while the parameters of the second lookup are expanded, -and also while <<string2>> of the second lookup is expanded, should the second -lookup fail. - -Instead of @{<<string2>>@} the word `fail' can appear, and in this case, if the -lookup fails, the entire expansion is forced to fail (see section -~~SECTforexpfai). If both @{<<string1>>@} and @{<<string2>>@} are omitted, the -result is the looked up value in the case of a successful lookup, and nothing -in the case of failure. - -For single-key lookups, the string `partial' is permitted to precede the -search type in order to do partial matching, and $*$ or $*$@@ may follow a -search type to request default lookups if the key does not match (see sections -~~SECTdefaultvaluelookups and ~~SECTpartiallookup for details). - -.index numerical variables (\$1$\, \$2$\, etc)||in lookup expansion -If a partial search is used, the variables \$1$\ and \$2$\ contain the wild -and non-wild parts of the key during the expansion of the replacement text. -They return to their previous values at the end of the lookup item. - -This example looks up the postmaster alias in the conventional alias file: -.display asis -${lookup {postmaster} lsearch {/etc/aliases} {$value}} -.endd -This example uses NIS+ to look up the full name of the user corresponding to -the local part of an address, forcing the expansion to fail if it is not found: -.display asis -${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ - {$value}fail} -.endd - - -.item "@$@{nhash@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" -.index expansion||numeric hash -.index hash function||numeric -The three strings are expanded; the first two must yield numbers. Call them -<<n>> and <<m>>. If you are using fixed values for these numbers, that is, if -<<string1>> and <<string2>> do not change when they are expanded, you can use -the simpler operator notation that avoids some of the braces: -.display -@$@{nhash@_<<n>>@_<<m>>:<<string>>@} -.endd -The second number is optional (in both notations). If there is only one number, -the result is a number in the range 0--<<n>>-1. Otherwise, the string is -processed by a div/mod hash function that returns two numbers, separated by a -slash, in the ranges 0 to <<n>>-1 and 0 to <<m>>-1, respectively. For example, -.display asis -${nhash{8}{64}{supercalifragilisticexpialidocious}} -.endd -returns the string `6/33'. - - - -.item "@$@{perl@{<<subroutine>>@}@{<<arg>>@}@{<<arg>>@}...@}" -.index Perl||use in expanded string -.index expansion||calling Perl from -This item is available only if Exim has been built to include an embedded Perl -interpreter. The subroutine name and the arguments are first separately -expanded, and then the Perl subroutine is called with those arguments. No -additional arguments need be given; the maximum number permitted, including the -name of the subroutine, is nine. - -The return value of the subroutine is inserted into the expanded string, unless -the return value is \undef\. In that case, the expansion fails in the same way -as an explicit `fail' on a lookup item. -The return value is a scalar. Whatever you return is evaluated in a scalar -context. For example, if you return the name of a Perl vector, the -return value is the size of the vector, not its contents. - -If the subroutine exits by calling Perl's \die\ function, the expansion fails -with the error message that was passed to \die\. More details of the embedded -Perl facility are given in chapter ~~CHAPperl. - -The \%redirect%\ router has an option called \forbid@_filter@_perl\ which locks -out the use of this expansion item in filter files. - - -.item "@$@{readfile@{<<file name>>@}@{<<eol string>>@}@}" -.index expansion||inserting an entire file -.index file||inserting into expansion -The file name and end-of-line string are first expanded separately. The file is -then read, and its contents replace the entire item. All newline characters in -the file are replaced by the end-of-line string if it is present. Otherwise, -newlines are left in the string. -String expansion is not applied to the contents of the file. If you want this, -you must wrap the item in an \expand\ operator. If the file cannot be read, the -string expansion fails. - -The \%redirect%\ router has an option called \forbid@_filter@_readfile\ which -locks out the use of this expansion item in filter files. - - - -.item "@$@{readsocket@{<<name>>@}@{<<request>>@}@{<<timeout>>@}@{<<eol string>>@}@{<<fail string>>@}@}" -.index expansion||inserting from a socket -.index socket, use of in expansion -This item inserts data that is read from a Unix domain socket into the expanded -string. The minimal way of using it uses just two arguments: -.display asis -${readsocket{/socket/name}{request string}} -.endd -Exim connects to the socket, writes the request string (unless it is an -empty string) and reads from the socket until an end-of-file is read. A timeout -of 5 seconds is applied. Additional, optional arguments extend what can be -done. Firstly, you can vary the timeout. For example: -.display asis -${readsocket{/socket/name}{request-string}{3s}} -.endd -A fourth argument allows you to change any newlines that are in the data -that is read, in the same way as for \readfile\ (see above). This example turns -them into spaces: -.display asis -${readsocket{/socket/name}{request-string}{3s}{ }} -.endd -As with all expansions, the substrings are expanded before the processing -happens. Errors in these sub-expansions cause the expansion to fail. In -addition, the following errors can occur: -.numberpars $. -Failure to create a socket file descriptor; -.nextp -Failure to connect the socket; -.nextp -Failure to write the request-string; -.nextp -Timeout on reading from the socket. -.endp -By default, any of these errors causes the expansion to fail. However, if -you supply a fifth substring, it is expanded and used when any of the above -errors occurs. For example: -.display asis -${readsocket{/socket/name}{request-string}{3s}{\n}\ - {socket failure}} -.endd -You can test for the existence of the socket by wrapping this expansion in -\"@$@{if exists"\, but there is a race condition between that test and the -actual opening of the socket, so it is safer to use the fifth argument if you -want to be absolutely sure of avoiding an expansion error for a non-existent -socket. - -The \%redirect%\ router has an option called \forbid@_filter@_readsocket\ which -locks out the use of this expansion item in filter files. - -.item "@$rheader@_<<header name>>:#$rm{or}#@$rh@_<<header name>>:" -This item inserts `raw' header lines. It is described with the \header\ -expansion item above. - - - -.item "@$@{run@{<<command>> <<args>>@}@{<<string1>>@}@{<<string2>>@}@}" -.index expansion||running a command -The command and its arguments are first expanded separately, and then the -command is run in a separate process, but under the same uid and gid. As in -other command executions from Exim, a shell is not used by default. If you want -a shell, you must explicitly code it. -.index return code||from \run\ expansion -If the command succeeds (gives a zero return code) <<string1>> is expanded and -replaces the entire item; during this expansion, the standard output from the -command is in the variable \$value$\. If the command fails, <<string2>>, if -present, is expanded. If it is absent, the result is empty. Alternatively, -<<string2>> can be the word `fail' (not in braces) to force expansion failure -if the command does not succeed. If both strings are omitted, the result is the -standard output on success, and nothing on failure. - -The return code from the command is put in the variable \$runrc$\, and this -remains set afterwards, so in a filter file you can do things like this: -.display asis -if "${run{x y z}{}}$runrc" is 1 then ... - elif $runrc is 2 then ... - ... -endif -.endd -If execution of the command fails (for example, the command does not exist), -the return code is 127 -- the same code that shells use for non-existent -commands. - -\**Warning**\: In a router or transport, you cannot assume the order in which -option values are expanded, except for those pre-conditions whose order of -testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ -by the expansion of one option, and use it in another. - -The \%redirect%\ router has an option called \forbid@_filter@_run\ which locks -out the use of this expansion item in filter files. - - -.item "@$@{sg@{<<subject>>@}@{<<regex>>@}@{<<replacement>>@}@}" -.index expansion||string substitution -This item works like Perl's substitution operator (s) with the global (/g) -option; hence its name. However, unlike the Perl equivalent, Exim does not -modify the subject string; instead it returns the modified string for insertion -into the overall expansion. The item takes three arguments: the subject string, -a regular expression, and a substitution string. For example -.display asis -${sg{abcdefabcdef}{abc}{xyz}} -.endd -yields `xyzdefxyzdef'. Because all three arguments are expanded before use, if -any @$ or @\ characters are required in the regular expression or in the -substitution string, they have to be escaped. For example -.display asis -${sg{abcdef}{^(...)(...)\$}{\$2\$1}} -.endd -yields `defabc', and -.display asis -${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} -.endd -yields `K1=A K4=D K3=C'. -Note the use of \"@\N"\ to protect the contents of the regular expression from -string expansion. - - - -.item "@$@{substr@{<<string1>>@}@{<<string2>>@}@{<<string3>>@}@}" -.index \substr\ -.index substring extraction -.index expansion||substring extraction -The three strings are expanded; the first two must yield numbers. Call them -<<n>> and <<m>>. If you are using fixed values for these numbers, that is, if -<<string1>> and <<string2>> do not change when they are expanded, you can use -the simpler operator notation that avoids some of the braces: -.display -@$@{substr@_<<n>>@_<<m>>:<<string>>@} -.endd -The second number is optional (in both notations). -.em -If it is absent in the simpler format, the preceding underscore must also be -omitted. -.nem - -The \substr\ item can be used to extract more general substrings than \length\. -The first number, <<n>>, is a starting offset, and <<m>> is the length -required. For example -.display asis -${substr{3}{2}{$local_part}} -.endd -If the starting offset is greater than the string length the result is the null -string; if the length plus starting offset is greater than the string length, -the result is the right-hand part of the string, starting from the given -offset. The first character in the string has offset zero. - -The \substr\ expansion item can take negative offset values to count -from the right-hand end of its operand. The last character is offset -1, the -second-last is offset -2, and so on. Thus, for example, -.display asis -${substr{-5}{2}{1234567}} -.endd -yields `34'. If the absolute value of a negative offset is greater than the -length of the string, the substring starts at the beginning of the string, and -the length is reduced by the amount of overshoot. Thus, for example, -.display asis -${substr{-5}{2}{12}} -.endd -yields an empty string, but -.display asis -${substr{-3}{2}{12}} -.endd -yields `1'. - -When the second number is omitted from \substr\, the remainder of the string is -taken if the offset is positive. If it is negative, all characters in the -string preceding the offset point are taken. For example, an offset of -1 and -no length, as in these semantically identical examples: -.display asis -${substr_-1:abcde} -${substr{-1}{abcde}} -.endd -yields all but the last character of the string, that is, `abcd'. - - - -.item "@$@{tr@{<<subject>>@}@{<<characters>>@}@{<<replacements>>@}@}" -.index expansion||character translation -This item does single-character translation on its subject string. The second -argument is a list of characters to be translated in the subject string. Each -matching character is replaced by the corresponding character from the -replacement list. For example -.display asis -${tr{abcdea}{ac}{13}} -.endd -yields `1b3de1'. If there are duplicates in the second character string, the -last occurrence is used. If the third string is shorter than the second, its -last character is replicated. However, if it is empty, no translation takes -place. - -.enditems - - -.section Expansion operators -.rset SECTexpop "~~chapter.~~section" -.index expansion||operators -For expansion items that perform transformations on a single argument string, -the `operator' notation is used because it is simpler and uses fewer braces. -The substring is first expanded before the operation is applied to it. The -following operations can be performed: - -.startitems - -.item "@$@{address:<<string>>@}" -.index expansion||RFC 2822 address handling -The string is interpreted as an RFC 2822 address, as it might appear in a -header line, and the effective address is extracted from it. If the string does -not parse successfully, the result is empty. - - -.item "@$@{base62:<<digits>>@}" -.index base62 -.index expansion||conversion to base 62 -The string must consist entirely of decimal digits. The number is converted to -base 62 (sic) and output as a string of six characters, including leading -zeros. \**Note**\: Just to be absolutely clear: this is \*not*\ base64 -encoding. - -.item "@$@{base62d:<<base-62 digits>>@}" -.index base62 -.index expansion||conversion to base 62 -The string must consist entirely of base-62 digits. The number is converted to -decimal and output as a string. - - -.item "@$@{domain:<<string>>@}" -.index domain||extraction -.index expansion||domain extraction -The string is interpreted as an RFC 2822 address and the domain is extracted -from it. If the string does not parse successfully, the result is empty. - - -.item "@$@{escape:<<string>>@}" -.index expansion||escaping non-printing characters -If the string contains any non-printing characters, they are converted to -escape sequences starting with a backslash. Whether characters with the most -significant bit set (so-called `8-bit characters') count as printing or not is -controlled by the \print@_topbitchars\ option. - - -.item "@$@{eval:<<string>>@}" -.item "@$@{eval10:<<string>>@}" -.index expansion||expression evaluation -.index expansion||arithmetic expression -These items supports simple arithmetic in expansion strings. The string (after -expansion) must be a conventional arithmetic expression, but it is limited to -the four basic operators (plus, minus, times, divide) and parentheses. All -operations are carried out using integer arithmetic. Plus and minus have a -lower priority than times and divide; operators with the same priority are -evaluated from left to right. - -For \eval\, numbers may be decimal, octal (starting with `0') or hexadecimal -(starting with `0x'). For \eval10\, all numbers are taken as decimal, even if -they start with a leading zero. This can be useful when processing numbers -extracted from dates or times, which often do have leading zeros. - -A number may be followed by `K' or `M' to multiply it by 1024 or 1024$*$1024, -respectively. Negative numbers are supported. The result of the computation is -a decimal representation of the answer (without `K' or `M'). For example: -.display - @$@{eval:1+1@} $rm{yields} 2 - @$@{eval:1+2*3@} $rm{yields} 7 - @$@{eval:(1+2)*3@} $rm{yields} 9 -.endd -As a more realistic example, in an ACL you might have -.display asis -deny message = Too many bad recipients - condition = \ - ${if and { \ - {>{$rcpt_count}{10}} \ - { \ - < \ - {$recipients_count} \ - {${eval:$rcpt_count/2}} \ - } \ - }{yes}{no}} -.endd -The condition is true if there have been more than 10 \\RCPT\\ commands and -fewer than half of them have resulted in a valid recipient. - - -.item "@$@{expand:<<string>>@}" -.index expansion||re-expansion of substring -The \expand\ operator causes a string to be expanded for a second time. For -example, -.display asis -${expand:${lookup{$domain}dbm{/some/file}{$value}}} -.endd -first looks up a string in a file while expanding the operand for \expand\, and -then re-expands what it has found. - - -.item "@$@{from@_utf8:<<string>>@}" -.index Unicode -.index UTF-8||conversion from -.index expansion||UTF-8 conversion -The world is slowly moving towards Unicode, although there are no standards for -email yet. However, other applications (including some databases) are starting -to store data in Unicode, using UTF-8 encoding. This operator converts from a -UTF-8 string to an ISO-8859-1 string. UTF-8 code values greater than 255 are -converted to underscores. The input must be a valid UTF-8 string. If it is not, -the result is an undefined sequence of bytes. - -Unicode code points with values less than 256 are compatible with ASCII and -ISO-8859-1 (also known as Latin-1). -For example, character 169 is the copyright symbol in both cases, though the -way it is encoded is different. In UTF-8, more than one byte is needed for -characters with code values greater than 127, whereas ISO-8859-1 is a -single-byte encoding (but thereby limited to 256 characters). This makes -translation from UTF-8 to ISO-8859-1 straightforward. - - -.item "@$@{hash@_<<n>>@_<<m>>:<<string>>@}" -.index hash function||textual -.index expansion||textual hash -The \hash\ operator is a simpler interface to the hashing function that can be -used when the two parameters are fixed numbers (as opposed to strings that -change when expanded). The effect is the same as -.display -@$@{hash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} -.endd -See the description of the general \hash\ item above for details. The -abbreviation \h\ can be used when \hash\ is used as an operator. - - - -.item "@$@{hex2b64:<<hexstring>>@}" -.index base64 encoding||conversion from hex -.index expansion||hex to base64 -This operator converts a hex string into one that is base64 encoded. This can -be useful for processing the output of the MD5 and SHA-1 hashing functions. - - -.item "@$@{lc:<<string>>@}" -.index case forcing in strings -.index string||case forcing -.index lower casing -.index expansion||case forcing -This forces the letters in the string into lower-case, for example: -.display asis -${lc:$local_part} -.endd - - -.item "@$@{length@_<<number>>:<<string>>@}" -.index expansion||string truncation -The \length\ operator is a simpler interface to the \length\ function that can -be used when the parameter is a fixed number (as opposed to a string that -changes when expanded). The effect is the same as -.display -@$@{length@{<<number>>@}@{<<string>>@}@} -.endd -See the description of the general \length\ item above for details. Note that -\length\ is not the same as \strlen\. The abbreviation \l\ can be used when -\length\ is used as an operator. - - -.item "@$@{local@_part:<<string>>@}" -.index expansion||local part extraction -The string is interpreted as an RFC 2822 address and the local part is -extracted from it. If the string does not parse successfully, the result is -empty. - - -.item "@$@{mask:<<IP address>>/<<bit count>>@}" -.index masked IP address -.index IP address||masking -.index CIDR notation -.index expansion||IP address masking -If the form of the string to be operated on is not an IP address followed by a -slash and an integer (that is, a network address in CIDR notation), the -expansion fails. Otherwise, this operator converts the IP address to binary, -masks off the least significant bits according to the bit count, and converts -the result back to text, with mask appended. For example, -.display asis -${mask:10.111.131.206/28} -.endd -returns the string `10.111.131.192/28'. Since this operation is expected to be -mostly used for looking up masked addresses in files, the result for an IPv6 -address uses dots to separate components instead of colons, because colon -terminates a key string in lsearch files. So, for example, -.display asis -${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} -.endd -returns the string -.display asis -3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 -.endd -Letters in IPv6 addresses are always output in lower case. - - -.item "@$@{md5:<<string>>@}" -.index MD5 hash -.index expansion||MD5 hash -The \md5\ operator computes the MD5 hash value of the string, and returns it as -a 32-digit hexadecimal number, -in which any letters are in lower case. - - -.item "@$@{nhash@_<<n>>@_<<m>>:<<string>>@}" -.index expansion||numeric hash -.index hash function||numeric -The \nhash\ operator is a simpler interface to the numeric hashing function -that can be used when the two parameters are fixed numbers (as opposed to -strings that change when expanded). The effect is the same as -.display -@$@{nhash@{<<n>>@}@{<<m>>@}@{<<string>>@}@} -.endd -See the description of the general \nhash\ item above for details. - - -.item "@$@{quote:<<string>>@}" -.index quoting||in string expansions -.index expansion||quoting -The \quote\ operator puts its argument into double quotes if it -is an empty string or -contains anything other than letters, digits, underscores, dots, and hyphens. -Any occurrences of double quotes and backslashes are escaped with a backslash. -Newlines and carriage returns are converted to \"@\n"\ and \"@\r"\, -respectively For example, -.display asis -${quote:ab"*"cd} -.endd -becomes -.display asis -"ab\"*\"cd" -.endd -The place where this is useful is when the argument is a substitution from a -variable or a message header. - -.item "@$@{quote@_local@_part:<<string>>@}" -This operator is like \quote\, except that it quotes the string only if -required to do so by the rules of RFC 2822 for quoting local parts. For -example, a plus sign would not cause quoting (but it would for \quote\). -If you are creating a new email address from the contents of \$local@_part$\ -(or any other unknown data), you should always use this operator. - - -.item "@$@{quote@_<<lookup-type>>:<<string>>@}" -.index quoting||lookup-specific -This operator applies lookup-specific quoting rules to the string. Each -query-style lookup type has its own quoting rules which are described with -the lookups in chapter ~~CHAPfdlookup. For example, -.display asis -${quote_ldap:two * two} -.endd -returns -.display asis -two%20%5C2A%20two -.endd -For single-key lookup types, no quoting is ever necessary and this operator -yields an unchanged string. - - -.item "@$@{rxquote:<<string>>@}" -.index quoting||in regular expressions -.index regular expressions||quoting -The \rxquote\ operator inserts a backslash before any non-alphanumeric -characters in its argument. This is useful when substituting the values of -variables or headers inside regular expressions. - - -.item "@$@{rfc2047:<<string>>@}" -.index expansion||RFC 2047 -This operator encodes text according to the rules of RFC 2047. This is an -encoding that is used in header lines to encode non-ASCII characters. It is -assumed that the input string is in the encoding specified by the -\headers@_charset\ option, which defaults to ISO-8859-1. If the string contains -only characters in the range 33--126, and no instances of the characters -.display asis -? = ( ) < > @ , ; : \ " . [ ] _ -.endd -it is not modified. Otherwise, the result is the RFC 2047 encoding of the -string, -.em -using as many `coded words' as necessary to encode all the characters. -.nem - - -.item "@$@{sha1:<<string>>@}" -.index SHA-1 hash -.index expansion||SHA-1 hashing -The \sha1\ operator computes the SHA-1 hash value of the string, and returns it -as a 40-digit hexadecimal number, in which any letters are in upper case. - - -.item "@$@{stat:<<string>>@}" -.index expansion||statting a file -.index file||extracting characteristics -The string, after expansion, must be a file path. A call to the \*stat()*\ -function is made for this path. If \*stat()*\ fails, an error occurs and the -expansion fails. If it succeeds, the data from the stat replaces the item, as a -series of <<name>>=<<value>> pairs, where the values are all numerical, -except for the value of `smode'. The names are: `mode' (giving the mode as a -4-digit octal number), `smode' (giving the mode in symbolic format as a -10-character string, as for the \*ls*\ command), `inode', `device', `links', -`uid', `gid', `size', `atime', `mtime', and `ctime'. You can extract individual -fields using the \extract\ expansion item. \**Warning**\: The file size may be -incorrect on 32-bit systems for files larger than 2GB. - - -.em -.item "@$@{str2b64:<<string>>@}" -.index expansion||base64 encoding -.index base64 encoding||in string expansion -This operator converts a string into one that is base64 encoded. -.nem - - -.item "@$@{strlen:<<string>>@}" -.index expansion||string length -.index string||length in expansion -The item is replace by the length of the expanded string, expressed as a -decimal number. \**Note**\: Do not confuse \strlen\ with \length\. - - -.item "@$@{substr@_<<start>>@_<<length>>:<<string>>@}" -.index \substr\ -.index substring extraction -.index expansion||substring expansion -The \substr\ operator is a simpler interface to the \substr\ function that can -be used when the two parameters are fixed numbers (as opposed to strings that -change when expanded). The effect is the same as -.display -@$@{substr@{<<start>>@}@{<<length>>@}@{<<string>>@}@} -.endd -See the description of the general \substr\ item above for details. The -abbreviation \s\ can be used when \substr\ is used as an operator. - -.item "@$@{time@_interval:<<string>>@}" -.index \time@_interval\ -.index time interval||formatting -The argument (after sub-expansion) must be a sequence of decimal digits that -represents an interval of time as a number of seconds. It is converted into a -number of larger units and output in Exim's normal time format, for example, -\"1w3d4h2m6s"\. - -.item "@$@{uc:<<string>>@}" -.index case forcing in strings -.index string||case forcing -.index upper casing -.index expansion||case forcing -This forces the letters in the string into upper-case. - -.enditems - - - -.section Expansion conditions -.rset SECTexpcond "~~chapter.~~section" -.index expansion||conditions -The following conditions are available for testing by the \@$@{if\ construct -while expanding strings: - -.startitems - -.item "!<<condition>>" -.index expansion||negating a condition -Preceding any condition with an exclamation mark negates the result of the -condition. - -.item "<<symbolic operator>> @{<<string1>>@}@{<<string2>>@}" -.index numeric comparison -.index expansion||numeric comparison -There are a number of symbolic operators for doing numeric comparisons. They -are: -.display -.tabs 8 -= $t $rm{equal} -== $t $rm{equal} -> $t $rm{greater} ->= $t $rm{greater or equal} -< $t $rm{less} -<= $t $rm{less or equal} -.endd -For example, -.display asis -${if >{$message_size}{10M} ... -.endd -Note that the general negation operator provides for inequality testing. The -two strings must take the form of optionally signed decimal integers, -optionally followed by one of the letters `K' or `M' (in either upper or lower -case), signifying multiplication by 1024 or 1024$*$1024, respectively. - -.item "crypteq @{<<string1>>@}@{<<string2>>@}" -.index expansion||encrypted comparison -.index encrypted strings, comparing -This condition is included in the Exim binary if it is built to support any -authentication mechanisms (see chapter ~~CHAPSMTPAUTH). Otherwise, it is -necessary to define \\SUPPORT@_CRYPTEQ\\ in \(Local/Makefile)\ to get \crypteq\ -included in the binary. - -The \crypteq\ condition has two arguments. The first is encrypted and compared -against the second, which is already encrypted. The second string may be in the -LDAP form for storing encrypted strings, which starts with the encryption type -in curly brackets, followed by the data. If the second string does not begin -with `{' it is assumed to be encrypted with \*crypt()*\ -or \*crypt16()*\ (see below), -since such strings cannot begin with `{'. Typically this will be a field from a -password file. - -An example of an encrypted string in LDAP form is: -.display asis -{md5}CY9rzUYh03PK3k6DJie09g== -.endd -If such a string appears directly in an expansion, the curly brackets have to -be quoted, because they are part of the expansion syntax. For example: -.display asis -${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} -.endd -The following encryption types -(whose names are matched case-independently) -are supported: -.numberpars $. -.index MD5 hash -.index base64 encoding||in encrypted password -\@{md5@}\ computes the MD5 digest of the first string, and expresses this as -printable characters to compare with the remainder of the second string. If the -length of the comparison string is 24, Exim assumes that it is base64 encoded -(as in the above example). If the length is 32, Exim assumes that it is a -hexadecimal encoding of the MD5 digest. If the length not 24 or 32, the -comparison fails. -.nextp -.index SHA-1 hash -\@{sha1@}\ computes the SHA-1 digest of the first string, and expresses this as -printable characters to compare with the remainder of the second string. If the -length of the comparison string is 28, Exim assumes that it is base64 encoded. -If the length is 40, Exim assumes that it is a hexadecimal encoding of the -SHA-1 digest. If the length is not 28 or 40, the comparison fails. -.nextp -.index \*crypt()*\ -\@{crypt@}\ calls the \*crypt()*\ function, -.em -which traditionally used to use only the first eight characters of the -password. However, in modern operating systems this is no longer true, and in -many cases the entire password is used, whatever its length. -.nem -.nextp -.index \*crypt16()*\ -\@{crypt16@}\ calls the \*crypt16()*\ function (also known as \*bigcrypt()*\), -which -.em -was orginally created to use up to 16 characters of the password. Again, in -modern operating systems, more characters may be used. -.nem -.endp -Exim has its own version of \*crypt16()*\ (which is just a double call to -\*crypt()*\). For operating systems that have their own version, setting -\\HAVE@_CRYPT16\\ in \(Local/Makefile)\ when building Exim causes it to use the -operating system version instead of its own. This option is set by default in -the OS-dependent \(Makefile)\ for those operating systems that are known to -support \*crypt16()*\. - -If you do not put any curly bracket encryption type in a \crypteq\ comparison, -the default is either \"@{crypt@}"\ or \"@{crypt16@}"\, as determined by the -setting of \\DEFAULT@_CRYPT\\ in \(Local/Makefile)\. The default default is -\"@{crypt@}"\. Whatever the default, you can always use either function by -specifying it explicitly in curly brackets. - -Note that if a password is no longer than 8 characters, the results of -encrypting it with \*crypt()*\ and \*crypt16()*\ are identical. That means that -\*crypt16()*\ is backwards compatible, as long as nobody feeds it a password -longer than 8 characters. - - -.item "def:<<variable name>>" -.index expansion||checking for empty variable -The \def\ condition must be followed by the name of one of the expansion -variables defined in section ~~SECTexpvar. The condition is true if the named -expansion variable does not contain the empty string, for example -.display asis -${if def:sender_ident {from $sender_ident}} -.endd -Note that the variable name is given without a leading \@$\ character. If the -variable does not exist, the expansion fails. - -.item "def:header@_<<header name>>:##or##def:h@_<<header name>>:" -.index expansion||checking header line existence -This condition is true if a message is being processed and the named header -exists in the message. For example, -.display asis -${if def:header_reply-to:{$h_reply-to:}{$h_from:}} -.endd -Note that no \@$\ appears before \header@_\ or \h@_\ in the condition, -and that header names must be terminated by colons if white space does not -follow. - -.item "eq @{<<string1>>@}@{<<string2>>@}" -.item "eqi @{<<string1>>@}@{<<string2>>@}" -.index string||comparison -.index expansion||string comparison -The two substrings are first expanded. The condition is true if the two -resulting strings are identical: for \eq\ the comparison includes the case of -letters, whereas for \eqi\ the comparison is case-independent. - -.item "exists @{<<file name>>@}" -.index expansion||file existence test -.index file||existence test -The substring is first expanded and then interpreted as an absolute path. The -condition is true if the named file (or directory) exists. The existence test -is done by calling the \*stat()*\ function. The use of the \exists\ test in -users' filter files may be locked out by the system administrator. - -.item "first@_delivery" -.index delivery||first -.index first delivery -.index expansion||first delivery test -This condition, which has no data, is true during a message's first delivery -attempt. It is false during any subsequent delivery attempts. - -.item "ge @{<<string1>>@}@{<<string2>>@}" -.item "gei @{<<string1>>@}@{<<string2>>@}" -.index string||comparison -.index expansion||string comparison -The two substrings are first expanded. The condition is true if the first -string is lexically greater than or equal to the second string: for \ge\ the -comparison includes the case of letters, whereas for \gei\ the comparison is -case-independent. - -.item "gt @{<<string1>>@}@{<<string2>>@}" -.item "gti @{<<string1>>@}@{<<string2>>@}" -.index string||comparison -.index expansion||string comparison -The two substrings are first expanded. The condition is true if the first -string is lexically greater than the second string: for \gt\ the comparison -includes the case of letters, whereas for \gti\ the comparison is -case-independent. - -.item "isip @{<<string>>@}" 8 -.item "isip4 @{<<string>>@}" -.item "isip6 @{<<string>>@}" -.index IP address||testing string format -.index string||testing for IP address -The substring is first expanded, and then tested to see if it has the form of -an IP address. Both IPv4 and IPv6 addresses are valid for \isip\, whereas -\isip4\ and \isip6\ test just for IPv4 or IPv6 addresses, respectively. For -example, you could use -.display asis -${if isip4{$sender_host_address}... -.endd -to test which version of IP an incoming SMTP connection is using. - - -.item "ldapauth @{<<ldap query>>@}" -.index LDAP||use for authentication -.index expansion||LDAP authentication test -This condition supports user authentication using LDAP. See section ~~SECTldap -for details of how to use LDAP in lookups and the syntax of queries. For this -use, the query must contain a user name and password. The query itself is not -used, and can be empty. The condition is true if -the password is not empty, and the user name and password are accepted by the -LDAP server. An empty password is rejected without calling LDAP because LDAP -binds with an empty password are considered anonymous regardless of -the username, and will succeed in most configurations. -See chapter ~~CHAPSMTPAUTH for details of SMTP authentication, and chapter -~~CHAPplaintext for an example of how this can be used. - - -.item "le @{<<string1>>@}@{<<string2>>@}" -.item "lei @{<<string1>>@}@{<<string2>>@}" -.index string||comparison -.index expansion||string comparison -The two substrings are first expanded. The condition is true if the first -string is lexically less than or equal to the second string: for \le\ the -comparison includes the case of letters, whereas for \lei\ the comparison is -case-independent. - -.item "lt @{<<string1>>@}@{<<string2>>@}" -.item "lti @{<<string1>>@}@{<<string2>>@}" -.index string||comparison -.index expansion||string comparison -The two substrings are first expanded. The condition is true if the first -string is lexically less than the second string: for \lt\ the comparison -includes the case of letters, whereas for \lti\ the comparison is -case-independent. - - -.item "match @{<<string1>>@}@{<<string2>>@}" -.index expansion||regular expression comparison -.index regular expressions||match in expanded string -The two substrings are first expanded. The second is then treated as a regular -expression and applied to the first. Because of the pre-expansion, if the -regular expression contains dollar, or backslash characters, they must be -escaped. Care must also be taken if the regular expression contains braces -(curly brackets). A closing brace must be escaped so that it is not taken as a -premature termination of <<string2>>. The easiest approach is to use the -\"@\N"\ feature to disable expansion of the regular expression. -For example, -.display asis -${if match {$local_part}{\N^\d{3}\N} ... -.endd -If the whole expansion string is in double quotes, further escaping of -backslashes is also required. - -The condition is true if the regular expression match succeeds. -The regular expression is not required to begin with a circumflex -metacharacter, but if there is no circumflex, the expression is not anchored, -and it may match anywhere in the subject, not just at the start. If you want -the pattern to match at the end of the subject, you must include the \"@$"\ -metacharacter at an appropriate point. - -.index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion -At the start of an \if\ expansion the values of the numeric variable -substitutions \$1$\ etc. are remembered. Obeying a \match\ condition that -succeeds causes them to be reset to the substrings of that condition and they -will have these values during the expansion of the success string. At the end -of the \if\ expansion, the previous values are restored. After testing a -combination of conditions using \or\, the subsequent values of the numeric -variables are those of the condition that succeeded. - -.item "match@_domain @{<<string1>>@}@{<<string2>>@}" -.item "match@_address @{<<string1>>@}@{<<string2>>@}" -.item "match@_local@_part @{<<string1>>@}@{<<string2>>@}" -.index domain list||in expansion condition -.index address list||in expansion condition -.index local part list||in expansion condition -These conditions make it possible to test domain, address, and local -part lists within expansions. Each condition requires two arguments: an item -and a list to match. A trivial example is: -.display asis -${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} -.endd -In each case, the second argument may contain any of the allowable items for a -list of the appropriate type. Also, because the second argument (after -expansion) is a standard form of list, it is possible to refer to a named list. -Thus, you can use conditions like this: -.display asis -${if match_domain{$domain}{+local_domains}{... -.endd -.index \"+caseful"\ -For address lists, the matching starts off caselessly, but the \"+caseful"\ -item can be used, as in all address lists, to cause subsequent items to -have their local parts matched casefully. Domains are always matched -caselessly. - -\**Note**\: Host lists are \*not*\ supported in this way. This is because -hosts have two identities: a name and an IP address, and it is not clear -how to specify cleanly how such a test would work. At least, I haven't come -up with anything yet. - -.item "pam {<<string1>>:<<string2>>:...@}" -.index PAM authentication -.index \\AUTH\\||with PAM -.index Solaris||PAM support -.index expansion||PAM authentication test -\*Pluggable Authentication Modules*\ -(\?http://www.kernel.org/pub/linux/libs/pam/?\) -are a facility which is available in the latest releases of Solaris and in some -GNU/Linux distributions. The Exim support, which is intended for use in -conjunction with the SMTP \\AUTH\\ command, is available only if Exim is -compiled with -.display asis -SUPPORT_PAM=yes -.endd -in \(Local/Makefile)\. You probably need to add \-lpam-\ to \\EXTRALIBS\\, and -in some releases of GNU/Linux \-ldl-\ is also needed. - -The argument string is first expanded, and the result must be a colon-separated -list of strings. -Leading and trailing whitespace is ignored. -The PAM module is initialized with the service name `exim' and the user name -taken from the first item in the colon-separated data string (<<string1>>). The -remaining items in the data string are passed over in response to requests from -the authentication function. In the simple case there will only be one request, -for a password, so the data consists of just two strings. - -There can be problems if any of the strings are permitted to contain colon -characters. In the usual way, these have to be doubled to avoid being taken as -separators. If the data is being inserted from a variable, the \sg\ expansion -item can be used to double any existing colons. For example, the configuration -of a LOGIN authenticator might contain this setting: -.display asis -server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} -.endd -For a PLAIN authenticator you could use: -.display asis -server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} -.endd -In some operating systems, PAM authentication can be done only from a process -running as root. Since Exim is running as the Exim user when receiving -messages, this means that PAM cannot be used directly in those systems. -A patched version of the \*pam@_unix*\ module that comes with the -Linux PAM package is available from \?http:@/@/www.e-admin.de/pam@_exim/?\. -The patched module allows one special uid/gid combination, in addition to root, -to authenticate. If you build the patched module to allow the Exim user and -group, PAM can then be used from an Exim authenticator. - - -.item "pwcheck {<<string1>>:<<string2>>@}" -.index \*pwcheck*\ daemon -.index Cyrus -.index expansion||\*pwcheck*\ authentication test -This condition supports user authentication using the Cyrus \*pwcheck*\ daemon. -This is one way of making it possible for passwords to be checked by a process -that is not running as root. -\**Note:**\ The use of \*pwcheck*\ is now deprecated. Its replacement is -\*saslauthd*\ (see below). - -The pwcheck support is not included in Exim by default. You need to specify -the location of the pwcheck daemon's socket in \(Local/Makefile)\ before -building Exim. For example: -.display asis -CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck -.endd -You do not need to install the full Cyrus software suite in order to use -the pwcheck daemon. You can compile and install just the daemon alone -from the Cyrus SASL library. Ensure that \*exim*\ is the only user that has -access to the \(/var/pwcheck)\ directory. - -The \pwcheck\ condition takes one argument, which must be the user name and -password, separated by a colon. For example, in a LOGIN authenticator -configuration, you might have this: -.display asis -server_condition = ${if pwcheck{$1:$2}{1}{0}} -.endd - -.item "queue@_running" -.index queue runner||detecting when delivering from -.index expansion||queue runner test -This condition, which has no data, is true during delivery attempts that are -initiated by queue runner processes, and false otherwise. - - -.item "radius {<<authentication string>>@}" -.index Radius -.index expansion||Radius authentication -Radius authentication (RFC 2865) is supported in a similar way to PAM. You must -set \\RADIUS@_CONFIG@_FILE\\ in \(Local/Makefile)\ to specify the location of -the Radius client configuration file in order to build Exim with Radius -support. -.em -With just that one setting, Exim expects to be linked with the \radiusclient\ -library. You can also link Exim with the \libradius\ library that comes with -FreeBSD. To do this, set -.display asis -RADIUS_LIB_TYPE=RADLIB -.endd -in \(Local/Makefile)\, in addition to setting \\RADIUS@_CONFIGURE@_FILE\\. -.nem -You may also have to supply a suitable setting in \\EXTRALIBS\\ so that the -Radius library can be found when Exim is linked. - -The string specified by \\RADIUS@_CONFIG@_FILE\\ is expanded and passed to the -Radius client library, which calls the Radius server. The condition is true if -the authentication is successful. For example -.display -server@_condition = @$@{if radius@{<<arguments>>@}@{yes@}@{no@}@} -.endd - - - -.item "saslauthd @{@{<<user>>@}@{<<password>>@}@{<<service>>@}@{<<realm>>@}@}" -.index \*saslauthd*\ daemon -.index Cyrus -.index expansion||\*saslauthd*\ authentication test -This condition supports user authentication using the Cyrus \*saslauthd*\ -daemon. This replaces the older \*pwcheck*\ daemon, which is now deprecated. -Using this daemon is one way of making it possible for passwords to be checked -by a process that is not running as root. - -The saslauthd support is not included in Exim by default. You need to specify -the location of the saslauthd daemon's socket in \(Local/Makefile)\ before -building Exim. For example: -.display asis -CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux -.endd -You do not need to install the full Cyrus software suite in order to use -the saslauthd daemon. You can compile and install just the daemon alone -from the Cyrus SASL library. - -Up to four arguments can be supplied to the \saslauthd\ condition, but only two -are mandatory. For example: -.display asis -server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} -.endd -The service and the realm are optional (which is why the arguments are enclosed -in their own set of braces). For details of the meaning of the service and -realm, and how to run the daemon, consult the Cyrus documentation. - -.enditems - - - -.section Combining expansion conditions -.index expansion||combining conditions -Several conditions can be tested at once by combining them using the \and\ and -\or\ combination conditions. Note that \and\ and \or\ are complete conditions -on their own, and precede their lists of sub-conditions. Each sub-condition -must be enclosed in braces within the overall braces that contain the list. No -repetition of \if\ is used. - -.startitems - -.item "or @{@{<<cond1>>@}@{<<cond2>>@}...@}" -.index `or' expansion condition -.index expansion||`or' of conditions -The sub-conditions are evaluated from left to right. The condition is true if -any one of the sub-conditions is true. -For example, -.display asis -${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... -.endd -When a true sub-condition is found, the following ones are parsed but not -evaluated. If there are several `match' sub-conditions the values of the -numeric variables afterwards are taken from the first one that succeeds. - -.item "and @{@{<<cond1>>@}@{<<cond2>>@}...@}" -.index `and' expansion condition -.index expansion||`and' of conditions -The sub-conditions are evaluated from left to right. The condition is true if -all of the sub-conditions are true. If there are several `match' -sub-conditions, the values of the numeric variables afterwards are taken from -the last one. When a false sub-condition is found, the following ones are -parsed but not evaluated. - -.enditems - - - -.section Expansion variables -.rset SECTexpvar "~~chapter.~~section" -.index expansion||variables, list of - -.em -This section contains an alphabetical list of all the expansion variables. Some -of them are available only when Exim is compiled with specific options such as -support for TLS or the content scanning extension. -.nem - -.push -.indent 2em -.index numerical variables (\$1$\, \$2$\, etc) -.tempindent 0 -\$0$\, \$1$\, etc: When a \match\ expansion condition succeeds, these -variables contain the captured substrings identified by the regular expression -during subsequent processing of the success string of the containing \if\ -expansion item. They may also be set externally by some other matching process -which precedes the expansion of the string. For example, the commands available -in Exim filter files include an \if\ command with its own regular expression -matching condition. - -.tempindent 0 -\$acl@_c0$\ -- \$acl@_c9$\: Values can be placed in these variables by the -\set\ modifier in an ACL. The values persist throughout the lifetime of an SMTP -connection. They can be used to pass information between ACLs and different -invocations of the same ACL. -When a message is received, the values of these variables are saved with the -message, and can be accessed by filters, routers, and transports during -subsequent delivery. - -.tempindent 0 -\$acl@_m0$\ -- \$acl@_m9$\: Values can be placed in these variables by the -\set\ modifier in an ACL. They retain their values while a message is being -received, but are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, -\\EHLO\\, \\HELO\\, and after starting a TLS session. -When a message is received, the values of these variables are saved with the -message, and can be accessed by filters, routers, and transports during -subsequent delivery. - - -.tempindent 0 -\$acl@_verify@_message$\: During the expansion of the \message\ and -\log@_message\ modifiers in an ACL statement after an address verification has -failed, this variable contains the original failure message that will be -overridden by the expanded string. - -.tempindent 0 -\$address@_data$\: This variable is set by means of the \address@_data\ -option in routers. The value then remains with the address while it is -processed by subsequent routers and eventually a transport. If the transport is -handling multiple addresses, the value from the first address is used. See -chapter ~~CHAProutergeneric for more details. \**Note**\: the contents of -\$address@_data$\ are visible in user filter files. - -.em -If \$address@_data$\ is set when the routers are called from an ACL to verify -a recipient address, the final value is still in the variable for subsequent -conditions and modifiers of the ACL statement. If routing the address caused it -to be redirected to just one address, the child address is also routed as part -of the verification, and in this case the final value of \$address@_data$\ is -from the child's routing. - -If \$address@_data$\ is set when the routers are called from an ACL to verify a -sender address, the final value is also preserved, but this time in -\$sender@_address@_data$\, to distinguish it from data from a recipient -address. - -In both cases (recipient and sender verification), the value does not persist -after the end of the current ACL statement. If you want to preserve -these values for longer, you can save them in ACL variables. -.nem - -.tempindent 0 -\$address@_file$\: When, as a result of aliasing, forwarding, or filtering, a -message is directed to a specific file, this variable holds the name of the -file when the transport is running. At other times, the variable is empty. For -example, using the default configuration, if user \r2d2\ has a \(.forward)\ -file containing -.display asis -/home/r2d2/savemail -.endd -then when the \%address@_file%\ transport is running, \$address@_file$\ -contains `/home/r2d2/savemail'. -.index Sieve filter||value of \$address@_file$\ -For Sieve filters, the value may be `inbox' or a relative folder name. It is -then up to the transport configuration to generate an appropriate absolute path -to the relevant file. - - -.tempindent 0 -\$address@_pipe$\: When, as a result of aliasing or forwarding, a message is -directed to a pipe, this variable holds the pipe command when the transport is -running. - -.index authentication||id -.tempindent 0 -\$authenticated@_id$\: When a server successfully authenticates a client it may -be configured to preserve some of the authentication information in the -variable \$authenticated@_id$\ (see chapter ~~CHAPSMTPAUTH). For example, a -user/password authenticator configuration might preserve the user name for use -in the routers. When a message is submitted locally (that is, not over a TCP -connection), the value of \$authenticated@_id$\ is the login name of the -calling process. - -.index sender||authenticated -.index authentication||sender -.index \\AUTH\\||on \\MAIL\\ command -.tempindent 0 -\$authenticated@_sender$\: -When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an -incoming SMTP \\MAIL\\ command -if it believes the sender is sufficiently trusted, as described in section -~~SECTauthparamail. Unless the data is the string `@<@>', it is set as the -authenticated sender of the message, and the value is available during delivery -in the \$authenticated@_sender$\ variable. If the sender is not trusted, Exim -accepts the syntax of \\AUTH=\\, but ignores the data. - -When a message is submitted locally (that is, not over a TCP connection), the -value of \$authenticated@_sender$\ is an address constructed from the login -name of the calling process and \$qualify@_domain$\. - - -.index authentication||failure -.tempindent 0 -\$authentication@_failed$\: -This variable is set to `1' in an Exim server if a client issues an \\AUTH\\ -command that does not succeed. Otherwise it is set to `0'. This makes it -possible to distinguish between `did not try to authenticate' -(\$sender@_host@_authenticated$\ is empty and \$authentication__failed$\ is set -to `0') and `tried to authenticate but failed' (\$sender@_host@_authenticated$\ -is empty and \$authentication@_failed$\ is set to `1'). Failure includes any -negative response to an \\AUTH\\ command, including (for example) an attempt to -use an undefined mechanism. - - -.index message||body, line count -.index body of message||line count -.tempindent 0 -\$body@_linecount$\: -When a message is being received or delivered, this variable contains the -number of lines in the message's body. - -.index message||body, binary zero count -.index body of message||binary zero count -.index binary zero||in message body -.tempindent 0 -\$body@_zerocount$\: -When a message is being received or delivered, this variable contains the -number of binary zero bytes in the message's body. - -.tempindent 0 -\$bounce@_recipient$\: -This is set to the recipient address of a bounce message while Exim is creating -it. It is useful if a customized bounce message text file is in use (see -chapter ~~CHAPemsgcust). - -.tempindent 0 -\$bounce@_return@_size@_limit$\: This contains the value set in the -\bounce@_return@_size@_limit\ option, rounded up to a multiple of 1000. It is -useful when a customized error message text file is in use (see chapter -~~CHAPemsgcust). - -.index gid (group id)||caller -.tempindent 0 -\$caller@_gid$\: The -real -group id under which the process that called Exim was -running. This is not the same as the group id of the originator of a message -(see \$originator@_gid$\). If Exim re-execs itself, this variable in the new -incarnation normally contains the Exim gid. - -.index uid (user id)||caller -.tempindent 0 -\$caller@_uid$\: The -real -user id under which the process that called Exim was -running. This is not the same as the user id of the originator of a message -(see \$originator@_uid$\). If Exim re-execs itself, this variable in the new -incarnation normally contains the Exim uid. - -.tempindent 0 -\$compile@_date$\: The date on which the Exim binary was compiled. - -.tempindent 0 -\$compile@_number$\: The building process for Exim keeps a count of the number -of times it has been compiled. This serves to distinguish different -compilations of the same version of the program. - -.em -.tempindent 0 -\$demime@_errorlevel$\: This variable is available when Exim is compiled with -the content-scanning extension and the obsolete \demime\ condition. For -details, see section ~~SECTdemimecond. - -.tempindent 0 -\$demime@_reason$\: This variable is available when Exim is compiled with the -content-scanning extension and the obsolete \demime\ condition. For details, -see section ~~SECTdemimecond. -.nem - -.index black list (DNS) -.tempindent 0 -\$dnslist@_domain$\: When a client host is found to be on a DNS (black) list, -the list's domain name is put into this variable so that it can be included in -the rejection message. - -.tempindent 0 -\$dnslist@_text$\: When a client host is found to be on a DNS (black) list, the -contents of any associated TXT record are placed in this variable. - -.tempindent 0 -\$dnslist@_value$\: When a client host is found to be on a DNS (black) list, -the IP address from the resource record is placed in this variable. -If there are multiple records, all the addresses are included, comma-space -separated. - -.tempindent 0 -\$domain$\: When an address is being routed, or delivered on its own, this -variable contains the domain. Global address rewriting happens when a message -is received, so the value of \$domain$\ during routing and delivery is the -value after rewriting. \$domain$\ is set during user filtering, but not during -system filtering, because a message may have many recipients and the system -filter is called just once. - -When more than one address is being delivered at once (for example, several -\\RCPT\\ commands in one SMTP delivery), \$domain$\ is set only if they all -have the same domain. Transports can be restricted to handling only one domain -at a time if the value of \$domain$\ is required at transport time -- this is -the default for local transports. For further details of the environment in -which local transports are run, see chapter ~~CHAPenvironment. - -.index \delay@_warning@_condition\ -At the end of a delivery, if all deferred addresses have the same domain, it is -set in \$domain$\ during the expansion of \delay@_warning@_condition\. - -The \$domain$\ variable is also used in some other circumstances: -.numberpars $. -When an ACL is running for a \\RCPT\\ command, \$domain$\ contains the domain -of the recipient address. -\**Note:**\ the domain of the sender address is in \$sender@_address@_domain$\ -at \\MAIL\\ time and at \\RCPT\\ time. \$domain$\ is not set for the \\MAIL\\ -ACL. -.nextp -When a rewrite item is being processed (see chapter ~~CHAPrewrite), \$domain$\ -contains the domain portion of the address that is being rewritten; it can be -used in the expansion of the replacement address, for example, to rewrite -domains by file lookup. -.nextp -With one important exception, whenever a domain list is being scanned, -\$domain$\ contains the subject domain. \**Exception**\: When a domain list in -a \sender@_domains\ condition in an ACL is being processed, the subject domain -is in \$sender@_address@_domain$\ and not in \$domain$\. It works this way so -that, in a \\RCPT\\ ACL, the sender domain list can be dependent on the -recipient domain (which is what is in \$domain$\ at this time). -.nextp -.index \\ETRN\\||value of \$domain$\ -.index \smtp@_etrn@_command\ -When the \smtp@_etrn@_command\ option is being expanded, \$domain$\ contains -the complete argument of the \\ETRN\\ command (see section ~~SECTETRN). -.endp - -.tempindent 0 -\$domain@_data$\: When the \domains\ option on a router matches a domain by -means of a lookup, the data read by the lookup is available during the running -of the router as \$domain@_data$\. In addition, if the driver routes the -address to a transport, the value is available in that transport. If the -transport is handling multiple addresses, the value from the first address is -used. - -\$domain@_data$\ is also set when the \domains\ condition in an ACL matches a -domain by means of a lookup. The data read by the lookup is available during -the rest of the ACL statement. In all other situations, this variable expands -to nothing. - -.tempindent 0 -\$exim@_gid$\: This variable contains the numerical value of the Exim group id. - -.tempindent 0 -\$exim@_path$\: This variable contains the path to the Exim binary. - -.tempindent 0 -\$exim@_uid$\: This variable contains the numerical value of the Exim user id. - -.em -.tempindent 0 -\$found@_extension$\: This variable is available when Exim is compiled with the -content-scanning extension and the obsolete \demime\ condition. For details, -see section ~~SECTdemimecond. -.nem - -.tempindent 0 -\$header@_<<name>>$\: This is not strictly an expansion variable. It is -expansion syntax for inserting the message header line with the given name. -Note that the name must be terminated by colon or white space, because it may -contain a wide variety of characters. -Note also that braces must \*not*\ be used. - -.tempindent 0 -\$home$\: -When the \check@_local@_user\ option is set for a router, the user's home -directory is placed in \$home$\ when the check succeeds. In particular, this -means it is set during the running of users' filter files. A router may also -explicitly set a home directory for use by a transport; this can be overridden -by a setting on the transport itself. - -When running a filter test via the \-bf-\ option, \$home$\ is set to the value -of the environment variable \\HOME\\. - -.tempindent 0 -\$host$\: -When the \%smtp%\ transport is expanding its options for encryption using TLS, -\$host$\ contains the name of the host to which it is connected. Likewise, when -used in the client part of an authenticator configuration (see chapter -~~CHAPSMTPAUTH), \$host$\ contains the name of the server to which the client -is connected. -.index transport||filter -.index filter||transport filter -When used in a transport filter (see chapter ~~CHAPtransportgeneric) \$host$\ -refers to the host involved in the current connection. When a local transport -is run as a result of a router that sets up a host list, \$host$\ contains the -name of the first host. - -.tempindent 0 -\$host@_address$\: -This variable is set to the remote host's IP address whenever \$host$\ is set -for a remote connection. -.em -It is also set to the IP address that is being checked when the -\ignore@_target@_hosts\ option is being processed. -.nem - -.tempindent 0 -\$host@_data$\: -If a \hosts\ condition in an ACL is satisfied by means of a lookup, the result -of the lookup is made available in the \$host@_data$\ variable. This -allows you, for example, to do things like this: -.display asis -deny hosts = net-lsearch;/some/file - message = $host_data -.endd - -.em -.index host||name lookup, failure of -.tempindent 0 -\$host@_lookup@_deferred$\: -This variable normally contains `0', as does \$host@_lookup@_failed$\. When a -message comes from a remote host and there is an attempt to look up the host's -name from its IP address, and the attempt is not successful, one of these -variables is set to `1'. -.numberpars $. -If the lookup receives a definite negative response (for example, a DNS lookup -succeeded, but no records were found), \$host@_lookup@_failed$\ is set to `1'. -.nextp -If there is any kind of problem during the lookup, such that Exim cannot -tell whether or not the host name is defined (for example, a timeout for a DNS -lookup), \$host@_lookup@_deferred$\ is set to `1'. -.endp -Looking up a host's name from its IP address consists of more than just a -single reverse lookup. Exim checks that a forward lookup of at least one of the -names it receives from a reverse lookup yields the original IP address. If this -is not the case, Exim does not accept the looked up name(s), and -\$host@_lookup@_failed$\ is set to `1'. Thus, being able to find a name from an -IP address (for example, the existence of a PTR record in the DNS) is not -sufficient on its own for the success of a host name lookup. If the reverse -lookup succeeds, but there is a lookup problem such as a timeout when checking -the result, the name is not accepted, and \$host@_lookup@_deferred$\ is set to -`1'. See also \$sender@_host@_name$\. - -.tempindent 0 -\$host@_lookup@_failed$\: See \$host@_lookup@_deferred$\. -.nem - -.tempindent 0 -\$inode$\: -The only time this variable is set is while expanding the \directory@_file\ -option in the \%appendfile%\ transport. The variable contains the inode number -of the temporary file which is about to be renamed. It can be used to construct -a unique name for the file. - -.tempindent 0 -\$interface@_address$\: -When a message is received over a TCP/IP connection, this variable contains the -address of the local IP interface. See also the \-oMi-\ command line option. -This variable can be used in ACLs and also, for example, to make the file name -for a TLS certificate depend on which interface is being used. - -.tempindent 0 -\$interface@_port$\: -When a message is received over a TCP/IP connection, this variable contains the -local port number. See also the \-oMi-\ command line option. -This variable can be used in ACLs and also, for example, to make the file name -for a TLS certificate depend on which port is being used. - -.tempindent 0 -\$ldap@_dn$\: -This variable, which is available only when Exim is compiled with LDAP support, -contains the DN from the last entry in the most recently successful LDAP -lookup. - -.tempindent 0 -\$load@_average$\: -This variable contains the system load average, multiplied by 1000 to that it -is an integer. For example, if the load average is 0.21, the value of the -variable is 210. The value is recomputed every time the variable is referenced. - -.tempindent 0 -\$local@_part$\: When an address is being routed, or delivered on its own, this -variable contains the local part. When a number of addresses are being -delivered together (for example, multiple \\RCPT\\ commands in an SMTP -session), \$local@_part$\ is not set. - -Global address rewriting happens when a message is received, so the value of -\$local@_part$\ during routing and delivery is the value after rewriting. -\$local@_part$\ is set during user filtering, but not during system filtering, -because a message may have many recipients and the system filter is called just -once. - -If a local part prefix or suffix has been recognized, it is not included in the -value of \$local@_part$\ during routing and subsequent delivery. The values of -any prefix or suffix are in \$local@_part@_prefix$\ and -\$local@_part@_suffix$\, respectively. - -When a message is being delivered to a file, pipe, or autoreply transport as a -result of aliasing or forwarding, \$local@_part$\ is set to the local part of -the parent address, not to the file name or command (see \$address@_file$\ and -\$address@_pipe$\). - -When an ACL is running for a \\RCPT\\ command, \$local@_part$\ contains the -local part of the recipient address. - -When a rewrite item is being processed (see chapter ~~CHAPrewrite), -\$local@_part$\ contains the local part of the address that is being rewritten; -it can be used in the expansion of the replacement address, for example. - -In all cases, all quoting is removed from the local part. For example, for both -the addresses -.display asis -"abc:xyz"@test.example -abc\:xyz@test.example -.endd -the value of \$local@_part$\ is -.display asis -abc:xyz -.endd -If you use \$local@_part$\ to create another address, you should always wrap it -inside a quoting operator. For example, in a \%redirect%\ router you could have: -.display asis -data = ${quote_local_part:$local_part}@new.domain.example -.endd -\**Note**\: The value of \$local@_part$\ is normally lower cased. If you want -to process local parts in a case-dependent manner in a router, you can set the -\caseful@_local@_part\ option (see chapter ~~CHAProutergeneric). - -.tempindent 0 -\$local@_part@_data$\: -When the \local@_parts\ option on a router matches a local part by means of a -lookup, the data read by the lookup is available during the running of the -router as \$local@_part@_data$\. In addition, if the driver routes the address -to a transport, the value is available in that transport. If the transport is -handling multiple addresses, the value from the first address is used. - -\$local@_part@_data$\ is also set when the \local@_parts\ condition in an ACL -matches a local part by means of a lookup. The data read by the lookup is -available during the rest of the ACL statement. In all other situations, this -variable expands to nothing. - -.tempindent 0 -\$local@_part@_prefix$\: When an address is being routed or delivered, and a -specific prefix for the local part was recognized, it is available in this -variable, having been removed from \$local@_part$\. - -.tempindent 0 -\$local@_part@_suffix$\: When an address is being routed or delivered, and a -specific suffix for the local part was recognized, it is available in this -variable, having been removed from \$local@_part$\. - -.tempindent 0 -\$local@_scan@_data$\: This variable contains the text returned by the -\*local@_scan()*\ function when a message is received. See chapter -~~CHAPlocalscan for more details. - -.tempindent 0 -\$local@_user@_gid$\: See \$local@_user@_uid$\. - -.tempindent 0 -\$local@_user@_uid$\: This variable and \$local@_user@_gid$\ are set to -the uid and gid after the \check__local__user\ router precondition succeeds. -This means that their values are available for the remaining preconditions -(\senders\, \require@_files\, and \condition\), for the \address@_data\ -expansion, and for any router-specific expansions. At all other times, the -values in these variables are \"(uid@_t)(-1)"\ and \"(gid@_t)(-1)"\, -respectively. - -.tempindent 0 -\$localhost@_number$\: This contains the expanded value of the -\localhost@_number\ option. The expansion happens after the main options have -been read. - -.em -.tempindent 0 -\$log@_inodes$\: The number of free inodes in the disk partition where Exim's -log files are being written. The value is recalculated whenever the variable is -referenced. If the relevant file system does not have the concept of inodes, -the value of is -1. See also the \check@_log@_inodes\ option. - -.tempindent 0 -\$log@_space$\: The amount of free space (as a number of kilobytes) in the disk -partition where Exim's log files are being written. The value is recalculated -whenever the variable is referenced. If the operating system does not have the -ability to find the amount of free space (only true for experimental systems), -the space value is -1. See also the \check@_log@_space\ option. -.nem - -.tempindent 0 -\$mailstore@_basename$\: This variable is set only when doing deliveries in -`mailstore' format in the \%appendfile%\ transport. During the expansion of the -\mailstore@_prefix\, \mailstore@_suffix\, \message__prefix\, and -\message@_suffix\ options, it contains the basename of the files that are being -written, that is, the name without the `.tmp', `.env', or `.msg' suffix. At all -other times, this variable is empty. - -.em -.tempindent 0 -\$malware@_name$\: This variable is available when Exim is compiled with the -content-scanning extension. It is set to the name of the virus that was found -when the ACL \malware\ condition is true (see section ~~SECTscanvirus). -.nem - -.index message||age of -.tempindent 0 -\$message@_age$\: This variable is set at the start of a delivery attempt to -contain the number of seconds since the message was received. It does not -change during a single delivery attempt. - -.index body of message||expansion variable -.index message||body, in expansion -.index binary zero||in message body -.tempindent 0 -\$message@_body$\: This variable contains the initial portion of a message's -body while it is being delivered, and is intended mainly for use in filter -files. The maximum number of characters of the body that are put into the -variable is set by the \message@_body@_visible\ configuration option; the -default is 500. Newlines are converted into spaces to make it easier to search -for phrases that might be split over a line break. -Binary zeros are also converted into spaces. - -.index body of message||expansion variable -.index message||body, in expansion -.tempindent 0 -\$message@_body@_end$\: This variable contains the final portion of a message's -body while it is being delivered. The format and maximum size are as for -\$message@_body$\. - -.index body of message||size -.index message||body, size -.tempindent 0 -\$message@_body@_size$\: When a message is being delivered, this variable -contains the size of the body in bytes. The count starts from the character -after the blank line that separates the body from the header. Newlines are -included in the count. See also \$message@_size$\, \$body@_linecount$\, and -\$body@_zerocount$\. - -.tempindent 0 -\$message@_headers$\: -This variable contains a concatenation of all the header lines when a message -is being processed, except for lines added by routers or transports. The header -lines are separated by newline characters. - -.tempindent 0 -\$message@_id$\: -When a message is being received or delivered, this variable contains the -unique message id that is used by Exim to identify the message. -An id is not created for a message until after its header has been -successfully received. -\**Note**\: This is \*not*\ the contents of the ::Message-ID:: header line; it -is the local id that Exim assigns to the message, for example: -\"1BXTIK-0001yO-VA"\. - -.index size||of message -.index message||size -.tempindent 0 -\$message@_size$\: -When a message is being processed, this variable contains its size in bytes. In -most cases, the size includes those headers that were received with the -message, but not those (such as ::Envelope-to::) that are added to individual -deliveries as they are written. However, there is one special case: during the -expansion of the \maildir@_tag\ option in the \%appendfile%\ transport while -doing a delivery in maildir format, the value of \$message@_size$\ is the -precise size of the file that has been written. See also -\$message@_body@_size$\, \$body@_linecount$\, and \$body@_zerocount$\. - -.index \\RCPT\\||value of \$message@_size$\ -While running an ACL at the time of an SMTP \\RCPT\\ command, \$message@_size$\ -contains the size supplied on the \\MAIL\\ command, or --1 -if no size was given. The value may not, of course, be truthful. - -.em -.tempindent 0 -\$mime@_$\\*xxx*\: A number of variables whose names start with \$mime$\ are -available when Exim is compiled with the content-scanning extension. For -details, see section ~~SECTscanmimepart. -.nem - -.tempindent 0 -\$n0$\ -- \$n9$\: These variables are counters that can be incremented by means -of the \add\ command in filter files. - -.tempindent 0 -\$original@_domain$\: When a top-level address is being processed for delivery, -this contains the same value as \$domain$\. However, if a `child' address (for -example, generated by an alias, forward, or filter file) is being processed, -this variable contains the domain of the original address. This differs from -\$parent@_domain$\ only when there is more than one level of aliasing or -forwarding. When more than one address is being delivered in a single transport -run, \$original@_domain$\ is not set. - -If new an address is created by means of a \deliver\ command in a system -filter, it is set up with an artificial `parent' address. This has the local -part \*system-filter*\ and the default qualify domain. - -.tempindent 0 -\$original@_local@_part$\: When a top-level address is being processed for -delivery, this contains the same value as \$local@_part$\, unless a prefix or -suffix was removed from the local part, because \$original@_local@_part$\ -always contains the full local part. When a `child' address (for example, -generated by an alias, forward, or filter file) is being processed, this -variable contains the full local part of the original address. - -If the router that did the redirection processed the local part -case-insensitively, the value in \$original@_local@_part$\ is in lower case. -This variable differs from \$parent@_local@_part$\ only when there is more than -one level of aliasing or forwarding. When more than one address is being -delivered in a single transport run, \$original@_local@_part$\ is not set. - -If new an address is created by means of a \deliver\ command in a system -filter, it is set up with an artificial `parent' address. This has the local -part \*system-filter*\ and the default qualify domain. - - -.index gid (group id)||of originating user -.index sender||gid -.tempindent 0 -\$originator@_gid$\: The value of \$caller@_gid$\ that was set when the message -was received. For messages received via the command line, this is the gid of -the sending user. For messages received by SMTP over TCP/IP, this is normally -the gid of the Exim user. - -.index uid (user id)||of originating user -.index sender||uid -.tempindent 0 -\$originator@_uid$\: The value of \$caller@_uid$\ that was set when the message -was received. For messages received via the command line, this is the uid of -the sending user. For messages received by SMTP over TCP/IP, this is normally -the uid of the Exim user. - -.tempindent 0 -\$parent@_domain$\: This variable is similar to \$original@_domain$\ (see -above), except that it refers to the immediately preceding parent address. - -.tempindent 0 -\$parent@_local@_part$\: This variable is similar to \$original@_local@_part$\ -(see above), except that it refers to the immediately preceding parent address. - -.index pid (process id)||of current process -.tempindent 0 -\$pid$\: This variable contains the current process id. - -.index filter||transport filter -.index transport||filter -.tempindent 0 -\$pipe@_addresses$\: This is not an expansion variable, but is mentioned here -because the string `@$pipe@_addresses' is handled specially in the command -specification for the \%pipe%\ transport (chapter ~~CHAPpipetransport) and in -transport filters (described under \transport@_filter\ in chapter -~~CHAPtransportgeneric). It cannot be used in general expansion strings, and -provokes an `unknown variable' error if encountered. - -.tempindent 0 -\$primary@_hostname$\: The value set in the configuration file, or read by the -\*uname()*\ function. If \*uname()*\ returns a single-component name, Exim -calls \*gethostbyname()*\ (or \*getipnodebyname()*\ where available) in an -attempt to acquire a fully qualified host name. -See also \$smtp@_active@_hostname$\. - -.tempindent 0 -\$qualify@_domain$\: The value set for this option in the configuration file. - -.tempindent 0 -\$qualify@_recipient$\: The value set for this option in the configuration file, -or if not set, the value of \$qualify@_domain$\. - -.tempindent 0 -\$rcpt@_count$\: When a message is being received by SMTP, this variable -contains the number of \\RCPT\\ commands received for the current message. If -this variable is used in a \\RCPT\\ ACL, its value includes the current -command. - -.tempindent 0 -\$rcpt@_defer@_count$\: When a message is being received by SMTP, this variable -contains the number of \\RCPT\\ commands in the current message that have -previously been rejected with a temporary (4\*xx*\) response. - -.tempindent 0 -\$rcpt@_fail@_count$\: When a message is being received by SMTP, this variable -contains the number of \\RCPT\\ commands in the current message that have -previously been rejected with a permanent (5\*xx*\) response. - -.tempindent 0 -\$received@_count$\: This variable contains the number of ::Received:: header -lines in the message, including the one added by Exim (so its value is always -greater than zero). It is available in the \\DATA\\ ACL, the non-SMTP ACL, and -while routing and delivering. - -.tempindent 0 -\$received@_for$\: If there is only a single recipient address in an incoming -message, this variable contains that address when the ::Received:: header line -is being built. -The value is copied after recipient rewriting has happened, but before the -\*local@_scan()*\ function is run. - -.tempindent 0 -\$received@_protocol$\: When a message is being processed, this variable -contains the name of the protocol by which it was received. -.em -Most of the names used by Exim are defined by RFCs 821, 2821, and 3848. They -start with `smtp' (the client used \\HELO\\) or `esmtp' (the client used -\\EHLO\\). This can be followed by `s' for secure (encrypted) and/or `a' for -authenticated. Thus, for example, if the protocol is set to `esmtpsa', the -message was received over an encrypted SMTP connection and the client was -successfully authenticated. - -Exim uses the protocol name `smtps' for the case when encryption is -automatically set up on connection without the use of \\STARTTLS\\ (see -\tls@_on@_connect@_ports\), and the client uses \\HELO\\ to initiate the -encrypted SMTP session. The name `smtps' is also used for the rare situation -where the client initially uses \\EHLO\\, sets up an encrypted connection using -\\STARTTLS\\, and then uses \\HELO\\ afterwards. - -The \-oMr-\ option provides a way of specifying a custom protocol name for -messages that are injected locally by trusted callers. This is commonly used to -identify messages that are being re-injected after some kind of scanning. -.nem - -.tempindent 0 -\$recipient@_data$\: This variable is set after an indexing lookup success in -an ACL \recipients\ condition. It contains the data from the lookup, and the -value remains set until the next \recipients\ test. Thus, you can do things -like this: -.display -require recipients = cdb*@@;/some/file -deny \*some further test involving*\ @$recipient@_data -.endd -\**Warning**\: This variable is set only when a lookup is used as an indexing -method in the address list, using the semicolon syntax as in the example above. -The variable is not set for a lookup that is used as part of the string -expansion that all such lists undergo before being interpreted. - -.em -.tempindent 0 -\$recipient@_verify@_failure$\: In an ACL, when a recipient verification fails, -this variable contains information about the failure. It is set to one of the -following words: -.numberpars " " -`qualify': The address was unqualified (no domain), and the message -was neither local nor came from an exempted host. -.nextp -`route': Routing failed. -.nextp -`mail': Routing succeeded, and a callout was attempted; rejection occurred at -or before the \\MAIL\\ command (that is, on initial connection, \\HELO\\, or -\\MAIL\\). -.nextp -`recipient': The \\RCPT\\ command in a callout was rejected. -.nextp -`postmaster': The postmaster check in a callout was rejected. -.endp -The main use of this variable is expected to be to distinguish between -rejections of \\MAIL\\ and rejections of \\RCPT\\. -.nem - -.tempindent 0 -\$recipients$\: This variable contains a list of envelope recipients for a -message. A comma and a space separate the addresses in the replacement text. -However, the variable is not generally available, to prevent exposure of Bcc -recipients in unprivileged users' filter files. You can use \$recipients$\ only -in these two cases: -.numberpars -In a system filter file. -.nextp -.em -In the ACLs associated with the \\DATA\\ command, that is, the ACLs defined by -\acl@_smtp@_predata\ and \acl@_smtp@_data\. -.nem -.endp - -.tempindent 0 -\$recipients@_count$\: When a message is being processed, this variable -contains the number of envelope recipients that came with the message. -Duplicates are not excluded from the count. While a message is being received -over SMTP, the number increases for each accepted recipient. It can be -referenced in an ACL. - -.tempindent 0 -\$reply@_address$\: When a message is being processed, this variable contains -the contents of the ::Reply-To:: header line if one exists -and it is not empty, -or otherwise the contents of the ::From:: header line. - -.tempindent 0 -\$return@_path$\: When a message is being delivered, this variable contains the -return path -- the sender field that will be sent as part of the envelope. It -is not enclosed in @<@> characters. -At the start of routing an address, -\$return@_path$\ has the same value as \$sender@_address$\, but if, for -example, an incoming message to a mailing list has been expanded by a router -which specifies a different address for bounce messages, \$return@_path$\ -subsequently contains the new bounce address, whereas \$sender@_address$\ -always contains the original sender address that was received with the message. -In other words, \$sender@_address$\ contains the incoming envelope sender, and -\$return@_path$\ contains the outgoing envelope sender. - -.tempindent 0 -\$return@_size@_limit$\: This is an obsolete name for -\$bounce@_return@_size@_limit$\. - -.index return code||from \run\ expansion -.tempindent 0 -\$runrc$\: This variable contains the return code from a command that is run by -the \@$@{run...@}\ expansion item. -\**Warning**\: In a router or transport, you cannot assume the order in which -option values are expanded, except for those pre-conditions whose order of -testing is documented. Therefore, you cannot reliably expect to set \$runrc$\ -by the expansion of one option, and use it in another. - -.tempindent 0 -\$self@_hostname$\: When an address is routed to a supposedly remote host that -turns out to be the local host, what happens is controlled by the -.index \self\ option||value of host name -\self\ generic router option. One of its values causes the address to be passed -to another router. When this happens, \$self@_hostname$\ is set to the name of -the local host that the original router encountered. In other circumstances its -contents are null. - -.tempindent 0 -\$sender@_address$\: When a message is being processed, this variable contains -the sender's address that was received in the message's envelope. For bounce -messages, the value of this variable is the empty string. -See also \$return@_path$\. - -.em -.tempindent 0 -\$sender@_address@_data$\: If \$address@_data$\ is set when the routers are -called from an ACL to verify a sender address, the final value is preserved in -\$sender@_address@_data$\, to distinguish it from data from a recipient -address. The value does not persist after the end of the current ACL statement. -If you want to preserve it for longer, you can save it in an ACL variable. -.nem - -.tempindent 0 -\$sender@_address@_domain$\: The domain portion of \$sender@_address$\. - -.tempindent 0 -\$sender@_address@_local@_part$\: The local part portion of \$sender@_address$\. - -.tempindent 0 -\$sender@_data$\: This variable is set after a lookup success in an ACL -\senders\ condition or in a router \senders\ option. It contains the data from -the lookup, and the value remains set until the next \senders\ test. Thus, you -can do things like this: -.display -require senders = cdb*@@;/some/file -deny \*some further test involving*\ @$sender@_data -.endd -\**Warning**\: This variable is set only when a lookup is used as an indexing -method in the address list, using the semicolon syntax as in the example above. -The variable is not set for a lookup that is used as part of the string -expansion that all such lists undergo before being interpreted. - -.tempindent 0 -\$sender@_fullhost$\: When a message is received from a remote host, this -variable contains the host name and IP address in a single string. It ends -with the IP address in square brackets, followed by a colon and a port number -if the logging of ports is enabled. The format of the rest of the string -depends on whether the host issued a \\HELO\\ or \\EHLO\\ SMTP command, and -whether the host name was verified by looking up its IP address. (Looking up -the IP address can be forced by the \host@_lookup\ option, independent of -verification.) A plain host name at the start of the string is a verified host -name; if this is not present, verification either failed or was not requested. -A host name in parentheses is the argument of a \\HELO\\ or \\EHLO\\ command. -This is omitted if it is identical to the verified host name or to the host's -IP address in square brackets. - -.tempindent 0 -\$sender@_helo@_name$\: When a message is received from a remote host that has -issued a \\HELO\\ or \\EHLO\\ command, the argument of that command is placed -in this variable. It is also set if \\HELO\\ or \\EHLO\\ is used when a message -is received using SMTP locally via the \-bs-\ or \-bS-\ options. - -.tempindent 0 -\$sender@_host@_address$\: When a message is received from a remote host, this -variable contains that host's IP address. For locally submitted messages, it is -empty. - -.tempindent 0 -\$sender@_host@_authenticated$\: This variable contains the name (not the -public name) of the authenticator driver which successfully authenticated the -client from which the message was received. It is empty if there was no -successful authentication. - -.tempindent 0 -\$sender@_host@_name$\: When a message is received from a remote host, this -variable contains the host's name as obtained by looking up its IP address. -For messages received by other means, this variable is empty. - -If the host name has not previously been looked up, a reference to -\$sender@_host@_name$\ triggers a lookup (for messages from remote hosts). -A looked up name is accepted only if it leads back to the original IP address -via a forward lookup. If either the reverse or the forward lookup fails -.em -to find any data, -.nem -or if the forward lookup does not yield the original IP address, -\$sender@_host@_name$\ remains empty, and \$host@_lookup@_failed$\ is set to -`1'. -.em -However, if either of the lookups cannot be completed (for example, there is a -DNS timeout), \$host@_lookup@_deferred$\ is set to `1', and -\$host@_lookup@_failed$\ remains set to `0'. - -Once \$host@_lookup@_failed$\ is set to `1', Exim does not try to look up the -host name again if there is a subsequent reference to \$sender@_host@_name$\ -in the same Exim process, but it does try again if \$sender@_host@_deferred$\ -is set to `1'. -.nem - -Exim does not automatically look up every calling host's name. If you want -maximum efficiency, you should arrange your configuration so that it avoids -these lookups altogether. The lookup happens only if one or more of the -following are true: -.numberpars -A string containing \$sender@_host@_name$\ is expanded. -.nextp -The calling host matches the list in \host@_lookup\. In the default -configuration, this option is set to $*$, so it must be changed if lookups are -to be avoided. (In the code, the default for \host@_lookup\ is unset.) -.nextp -Exim needs the host name in order to test an item in a host list. The items -that require this are described in sections ~~SECThoslispatnam and -~~SECThoslispatnamsk. -.nextp -The calling host matches \helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\. -In this case, the host name is required to compare with the name quoted in any -\\EHLO\\ or \\HELO\\ commands that the client issues. -.nextp -The remote host issues a \\EHLO\\ or \\HELO\\ command that quotes one of the -domains in \helo@_lookup@_domains\. The default value of this option is -.display asis -helo_lookup_domains = @ : @[] -.endd -which causes a lookup if a remote host (incorrectly) gives the server's name or -IP address in an \\EHLO\\ or \\HELO\\ command. -.endp - -.tempindent 0 -\$sender@_host@_port$\: When a message is received from a remote host, this -variable contains the port number that was used on the remote host. - -.tempindent 0 -\$sender@_ident$\: When a message is received from a remote host, this variable -contains the identification received in response to an RFC 1413 request. When a -message has been received locally, this variable contains the login name of the -user that called Exim. - -.tempindent 0 -\$sender@_rcvhost$\: This is provided specifically for use in ::Received:: -headers. It starts with either the verified host name (as obtained from a -.index DNS||reverse lookup -.index reverse DNS lookup -reverse DNS lookup) or, if there is no verified host name, the IP address in -square brackets. After that there may be text in parentheses. When the first -item is a verified host name, the first thing in the parentheses is the IP -address in square brackets, followed by a colon and a port number if port -logging is enabled. When the first item is an IP address, the port is recorded -as `port=$it{xxxx}' inside the parentheses. - -There may also be items of the form `helo=$it{xxxx}' if \\HELO\\ or \\EHLO\\ -was used and its argument was not identical to the real host name or IP -address, and `ident=$it{xxxx}' if an RFC 1413 ident string is available. If all -three items are present in the parentheses, a newline and tab are inserted into -the string, to improve the formatting of the ::Received:: header. - -.em -.tempindent 0 -\$sender@_verify@_failure$\: In an ACL, when a sender verification fails, this -variable contains information about the failure. The details are the same as -for \$recipient@_verify@_failure$\. - -.tempindent 0 -\$smtp@_active@_hostname$\: During an SMTP session, this variable contains the -value of the active host name, as specified by the \smtp@_active@_hostname\ -option. The value of \$smtp@_active@_hostname$\ is saved with any message that -is received, so its value can be consulted during routing and delivery. -.nem - -.index \\AUTH\\||argument -.index \\EXPN\\||argument -.index \\ETRN\\||argument -.index \\VRFY\\||argument -.tempindent 0 -\$smtp@_command@_argument$\: While an ACL is running to check an \\AUTH\\, -\\EHLO\\, \\EXPN\\, \\ETRN\\, \\HELO\\, or \\VRFY\\ command, this variable -contains the argument for the SMTP command. - -.tempindent 0 -\$sn0$\ -- \$sn9$\: These variables are copies of the values of the \$n0$\ --- \$n9$\ accumulators that were current at the end of the system filter file. -This allows a system filter file to set values that can be tested in users' -filter files. For example, a system filter could set a value indicating how -likely it is that a message is junk mail. - -.em -.tempindent 0 -\$spam@_$\\*xxx*\: A number of variables whose names start with \$spam$\ are -available when Exim is compiled with the content-scanning extension. For -details, see section ~~SECTscanspamass. -.nem - -.tempindent 0 -\$spool@_directory$\: The name of Exim's spool directory. - -.em -.tempindent 0 -\$spool@_inodes$\: The number of free inodes in the disk partition where Exim's -spool files are being written. The value is recalculated whenever the variable -is referenced. If the relevant file system does not have the concept of inodes, -the value of is -1. -See also the \check@_spool@_inodes\ option. - -.tempindent 0 -\$spool@_space$\: The amount of free space (as a number of kilobytes) in the -disk partition where Exim's spool files are being written. The value is -recalculated whenever the variable is referenced. If the operating system does -not have the ability to find the amount of free space (only true for -experimental systems), the space value is -1. For example, to check in an ACL -that there is at least 50 megabytes free on the spool, you could write: -.display asis -condition = ${if > {$spool_space}{50000}} -.endd -See also the \check@_spool@_space\ option. -.nem - -.tempindent 0 -\$thisaddress$\: This variable is set only during the processing of the -\foranyaddress\ command in a filter file. Its use is explained in the -description of that command. - -.tempindent 0 -\$tls@_certificate@_verified$\: -This variable is set to `1' if a TLS certificate was verified when the message -was received, and `0' otherwise. - -.tempindent 0 -\$tls@_cipher$\: When a message is received from a remote host over an -encrypted SMTP connection, this variable is set to the cipher suite that was -negotiated, for example DES-CBC3-SHA. -In other circumstances, in particular, for message received over unencrypted -connections, the variable is empty. -See chapter ~~CHAPTLS for details of TLS support. - -.tempindent 0 -\$tls@_peerdn$\: When a message is received from a remote host over an -encrypted SMTP connection, -and Exim is configured to request a certificate from the client, -the value of the Distinguished Name of the certificate is made available in the -\$tls@_peerdn$\ during subsequent processing. - -.tempindent 0 -\$tod@_bsdinbox$\: The time of day and date, in the format required for -BSD-style mailbox files, for example: Thu Oct 17 17:14:09 1995. - -.tempindent 0 -\$tod@_epoch$\: The time and date as a number of seconds since the start of the -Unix epoch. - -.tempindent 0 -\$tod@_full$\: A full version of the time and date, for example: Wed, 16 Oct -1995 09:51:40 +0100. The timezone is always given as a numerical offset from -UTC, with positive values used for timezones that are ahead (east) of UTC, and -negative values for those that are behind (west). - -.tempindent 0 -\$tod@_log$\: The time and date in the format used for writing Exim's log -files, for example: 1995-10-12 15:32:29, -but without a timezone. - -.tempindent 0 -\$tod@_logfile$\: -This variable contains the date in the format yyyymmdd. This is the format that -is used for datestamping log files when \log@_file@_path\ contains the \"%D"\ -flag. - -.tempindent 0 -\$tod@_zone$\: This variable contains the numerical value of the local -timezone, for example: -0500. - -.tempindent 0 -\$tod@_zulu$\: -This variable contains the UTC date and time in `Zulu' format, as specified by -ISO 8601, for example: 20030221154023Z. - -.index \$value$\ -.tempindent 0 -\$value$\: This variable contains the result of an expansion lookup, extraction -operation, or external command, as described above. - -.tempindent 0 -\$version@_number$\: The version number of Exim. - -.tempindent 0 -\$warn@_message@_delay$\: This variable is set only during the creation of a -message warning about a delivery delay. Details of its use are explained in -section ~~SECTcustwarn. - -.tempindent 0 -\$warn@_message@_recipients$\: This variable is set only during the creation of -a message warning about a delivery delay. Details of its use are explained in -section ~~SECTcustwarn. -.pop - - - -. -. -. ============================================================================ -.chapter Embedded Perl -.set runningfoot "embedded Perl" -.rset CHAPperl "~~chapter" -.index Perl||calling from Exim - -Exim can be built to include an embedded Perl interpreter. When this is done, -Perl subroutines can be called as part of the string expansion process. To make -use of the Perl support, you need version 5.004 or later of Perl installed on -your system. To include the embedded interpreter in the Exim binary, include -the line -.display asis -EXIM_PERL = perl.o -.endd -in your \(Local/Makefile)\ and then build Exim in the normal way. - -.section Setting up so Perl can be used -Access to Perl subroutines is via a global configuration option called -.index \perl@_startup\ -\perl@_startup\ and an expansion string operator \@$@{perl ...@}\. If there is -no \perl@_startup\ option in the Exim configuration file then no Perl -interpreter is started and there is almost no overhead for Exim (since none of -the Perl library will be paged in unless used). If there is a \perl@_startup\ -option then the associated value is taken to be Perl code which is executed in -a newly created Perl interpreter. - -The value of \perl@_startup\ is not expanded in the Exim sense, so you do not -need backslashes before any characters to escape special meanings. The option -should usually be something like -.display asis -perl_startup = do '/etc/exim.pl' -.endd -where \(/etc/exim.pl)\ is Perl code which defines any subroutines you want to -use from Exim. Exim can be configured either to start up a Perl interpreter as -soon as it is entered, or to wait until the first time it is needed. Starting -the interpreter at the beginning ensures that it is done while Exim still has -its setuid privilege, but can impose an unnecessary overhead if Perl is not in -fact used in a particular run. Also, note that this does not mean that Exim is -necessarily running as root when Perl is called at a later time. By default, -the interpreter is started only when it is needed, but this can be changed in -two ways: -.numberpars $. -.index \perl@_at@_start\ -Setting \perl@_at@_start\ (a boolean option) in the configuration requests -a startup when Exim is entered. -.nextp -The command line option \-ps-\ also requests a startup when Exim is entered, -overriding the setting of \perl@_at@_start\. -.endp -There is also a command line option \-pd-\ (for delay) which suppresses the -initial startup, even if \perl@_at@_start\ is set. - -.section Calling Perl subroutines -When the configuration file includes a \perl@_startup\ option you can make use -of the string expansion item to call the Perl subroutines that are defined -by the \perl@_startup\ code. The operator is used in any of the following -forms: -.display asis -${perl{foo}} -${perl{foo}{argument}} -${perl{foo}{argument1}{argument2} ... } -.endd -which calls the subroutine \foo\ with the given arguments. A maximum of eight -arguments may be passed. Passing more than this results in an expansion failure -with an error message of the form -.display asis -Too many arguments passed to Perl subroutine "foo" (max is 8) -.endd -The return value of the Perl subroutine is evaluated in a scalar context before -it is passed back to Exim to be inserted into the expanded string. If the -return value is \*undef*\, the expansion is forced to fail in the same way as -an explicit `fail' on an \@$@{if ...@}\ or \@$@{lookup...@}\ item. If the -subroutine aborts by obeying Perl's \die\ function, the expansion fails with -the error message that was passed to \die\. - -.section Calling Exim functions from Perl -Within any Perl code called from Exim, the function \*Exim@:@:expand@_string*\ -is available to call back into Exim's string expansion function. For example, -the Perl code -.display asis -my $lp = Exim::expand_string('$local_part'); -.endd -makes the current Exim \$local@_part$\ available in the Perl variable \$lp$\. -Note those are single quotes and not double quotes to protect against -\$local@_part$\ being interpolated as a Perl variable. - -If the string expansion is forced to fail by a `fail' item, the result of -\*Exim@:@:expand@_string*\ is \undef\. If there is a syntax error in the -expansion string, the Perl call from the original expansion string fails with -an appropriate error message, in the same way as if \die\ were used. - -.index debugging||from embedded Perl -.index log||writing from embedded Perl -Two other Exim functions are available for use from within Perl code. -\*Exim@:@:debug@_write(<<string>>)*\ writes the string to the standard error -stream if Exim's debugging is enabled. If you want a newline at the end, you -must supply it. \*Exim@:@:log@_write(<<string>>)*\ writes the string to Exim's -main log, adding a leading timestamp. In this case, you should not supply a -terminating newline. - -.em -.section Use of standard output and error by Perl -.index Perl||standard output and error -You should not write to the standard error or output streams from within your -Perl code, as it is not defined how these are set up. In versions of Exim -before 4.50, it is possible for the standard output or error to refer to the -SMTP connection during message reception via the daemon. Writing to this stream -is certain to cause chaos. From Exim 4.50 onwards, the standard output and -error streams are connected to \(/dev/null)\ in the daemon. The chaos is -avoided, but the output is lost. - -.index Perl||\warn\, use of -The Perl \warn\ statement writes to the standard error stream by default. Calls -to \warn\ may be embedded in Perl modules that you use, but over which you have -no control. When Exim starts up the Perl interpreter, it arranges for output -from the \warn\ statement to be written to the Exim main log. You can change -this by including appropriate Perl magic somewhere in your Perl code. For -example, to discard \warn\ output completely, you need this: -.display asis -$SIG{__WARN__} = sub { }; -.endd -Whenever a \warn\ is obeyed, the anonymous subroutine is called. In this -example, the code for the subroutine is empty, so it does nothing, but you can -include any Perl code that you like. The text of the \warn\ message is passed -as the first subroutine argument. -.nem - - -. -. -. -. -. ============================================================================ -.chapter Starting the daemon and the use of network interfaces -.set runningfoot "starting the daemon" -.rset CHAPinterfaces "~~chapter" -.index daemon||starting -.index interface||listening -.index network interface -.index interface||network -.index IP address||for listening -.index daemon||listening IP addresses -.index TCP/IP||setting listening interfaces -.index TCP/IP||setting listening ports - -A host that is connected to a TCP/IP network may have one or more physical -hardware network interfaces. Each of these interfaces may be configured as one -or more `logical' interfaces, which are the entities that a program actually -works with. Each of these logical interfaces is associated with an IP address. -In addition, TCP/IP software supports `loopback' interfaces (127.0.0.1 in IPv4 -and @:@:1 in IPv6), which do not use any physical hardware. Exim requires -knowledge about the host's interfaces for use in three different circumstances: -.numberpars -When a listening daemon is started, Exim needs to know which interfaces -and ports to listen on. -.nextp -When Exim is routing an address, it needs to know which IP addresses -are associated with local interfaces. This is required for the correct -processing of MX lists by removing the local host and others with the -same or higher priority values. Also, Exim needs to detect cases -when an address is routed to an IP address that in fact belongs to the -local host. Unless the \self\ router option or the \allow@_localhost\ -option of the smtp transport is set (as appropriate), this is treated -as an error situation. -.nextp -When Exim connects to a remote host, it may need to know which interface to use -for the outgoing connection. -.endp - -Exim's default behaviour is likely to be appropriate in the vast majority -of cases. If your host has only one interface, and you want all its IP -addresses to be treated in the same way, and you are using only the -standard SMTP port, you should not need to take any special action. The -rest of this chapter does not apply to you. - -In a more complicated situation you may want to listen only on certain -interfaces, or on different ports, and for this reason there are a number of -options that can be used to influence Exim's behaviour. The rest of this -chapter describes how they operate. - -When a message is received over TCP/IP, the interface and port that were -actually used are set in \$interface@_address$\ and \$interface@_port$\. - - -.section Starting a listening daemon -When a listening daemon is started (by means of the \-bd-\ command line -option), the interfaces and ports on which it listens are controlled by the -following options: -.numberpars $. -\daemon@_smtp@_ports\ contains a list of default ports. (For backward -compatibility, this option can also be specified in the singular.) -.nextp -\local@_interfaces\ contains list of interface IP addresses on which to -listen. Each item may optionally also specify a port. -.endp -The default list separator in both cases is a colon, but this can be changed as -described in section ~~SECTlistconstruct. When IPv6 addresses are involved, it -is usually best to change the separator to avoid having to double all the -colons. For example: -.display asis -local_interfaces = <; 127.0.0.1 ; \ - 192.168.23.65 ; \ - ::1 ; \ - 3ffe:ffff:836f::fe86:a061 -.endd -There are two different formats for specifying a port along with an IP address -in \local@_interfaces\: -.numberpars -The port is added onto the address with a dot separator. For example, to listen -on port 1234 on two different IP addresses: -.display asis -local_interfaces = <; 192.168.23.65.1234 ; \ - 3ffe:ffff:836f::fe86:a061.1234 -.endd -.nextp -The IP address is enclosed in square brackets, and the port is added -with a colon separator, for example: -.display asis -local_interfaces = <; [192.168.23.65]:1234 ; \ - [3ffe:ffff:836f::fe86:a061]:1234 -.endd -.endp -When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The -default setting contains just one port: -.display asis -daemon_smtp_ports = smtp -.endd -If more than one port is listed, each interface that does not have its own port -specified listens on all of them. Ports that are listed in -\daemon@_smtp@_ports\ can be identified either by name (defined in -\(/etc/services)\) or by number. However, when ports are given with individual -IP addresses in \local@_interfaces\, only numbers (not names) can be used. - - -.section Special IP listening addresses -The addresses 0.0.0.0 and @:@:0 are treated specially. They are interpreted -as `all IPv4 interfaces' and `all IPv6 interfaces', respectively. In each -case, Exim tells the TCP/IP stack to `listen on all IPv\*x*\ interfaces' -instead of setting up separate listening sockets for each interface. The -default value of \local@_interfaces\ is -.display asis -local_interfaces = 0.0.0.0 -.endd -when Exim is built without IPv6 support; otherwise it is: -.display asis -local_interfaces = <; ::0 ; 0.0.0.0 -.endd -Thus, by default, Exim listens on all available interfaces, on the SMTP port. - - -.section Overriding local@_interfaces and daemon@_smtp@_ports -The \-oX-\ command line option can be used to override the values of -\daemon@_smtp@_ports\ and/or \local@_interfaces\ for a particular daemon -instance. Another way of doing this would be to use macros and the \-D-\ -option. However, \-oX-\ can be used by any admin user, whereas modification of -the runtime configuration by \-D-\ is allowed only when the caller is root or -exim. - -The value of \-oX-\ is a list of items. The default colon separator can be -changed in the usual way if required. If there are any items that do not -contain dots or colons (that is, are not IP addresses), the value of -\daemon@_smtp@_ports\ is replaced by the list of those items. If there are any -items that do contain dots or colons, the value of \local@_interfaces\ is -replaced by those items. Thus, for example, -.display asis --oX 1225 -.endd -overrides \daemon@_smtp@_ports\, but leaves \local@_interfaces\ unchanged, -whereas -.display asis --oX 192.168.34.5.1125 -.endd -overrides \local@_interfaces\, leaving \daemon@_smtp@_ports\ unchanged. -(However, since \local@_interfaces\ now contains no items without ports, the -value of \daemon@_smtp@_ports\ is no longer relevant in this example.) - - -.em -.section Support for the obsolete SSMTP (or SMTPS) protocol -.rset SECTsupobssmt "~~chapter.~~section" -.index ssmtp protocol -.index smtps protocol -.index SMTP||ssmtp protocol -.index SMTP||smtps protocol -Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used -before the \\STARTTLS\\ command was standardized for SMTP. Some legacy clients -still use this protocol. If the \tls@_on@_connect@_ports\ option is set to a -list of port numbers, connections to those ports must use SSMTP. The most -common use of this option is expected to be -.display asis -tls_on_connect_ports = 465 -.endd -because 465 is the usual port number used by the legacy clients. There is also -a command line option \-tls-on-connect-\, which forces all ports to behave in -this way when a daemon is started. - -\**Warning**\: Setting \tls@_on@_connect@_ports\ does not of itself cause the -daemon to listen on those ports. You must still specify them in -\daemon@_smtp@_ports\, \local@_interfaces\, or the \-oX-\ option. (This is -because \tls@_on@_connect@_ports\ applies to \inetd\ connections as well as to -connections via the daemon.) -.nem - - -.section IPv6 address scopes -IPv6 addresses have `scopes', and a host with multiple hardware interfaces -can, in principle, have the same link-local IPv6 address on different -interfaces. Thus, additional information is needed, over and above the IP -address, to distinguish individual interfaces. A convention of using a -percent sign followed by something (often the interface name) has been -adopted in some cases, leading to addresses like this: -.display asis -fe80::202:b3ff:fe03:45c1%eth0 -.endd -To accommodate this usage, a percent sign followed by an arbitrary string is -allowed at the end of an IPv6 address. By default, Exim calls \*getaddrinfo()*\ -to convert a textual IPv6 address for actual use. This function recognizes the -percent convention in operating systems that support it, and it processes the -address appropriately. Unfortunately, some older libraries have problems with -\*getaddrinfo()*\. If -.display asis -IPV6_USE_INET_PTON=yes -.endd -is set in \(Local/Makefile)\ (or an OS-dependent Makefile) when Exim is built, -Exim uses \*inet@_pton()*\ to convert a textual IPv6 address for actual use, -instead of \*getaddrinfo()*\. (Before version 4.14, it always used this -function.) Of course, this means that the additional functionality of -\*getaddrinfo()*\ -- recognizing scoped addresses -- is lost. - - -.section Examples of starting a listening daemon -The default case in an IPv6 environment is -.display asis -daemon_smtp_ports = smtp -local_interfaces = <; ::0 ; 0.0.0.0 -.endd -This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. -Either one or two sockets may be used, depending on the characteristics of -the TCP/IP stack. (This is complicated and messy; for more information, -read the comments in the \(daemon.c)\ source file.) - -To specify listening on ports 25 and 26 on all interfaces: -.display asis -daemon_smtp_ports = 25 : 26 -.endd -(leaving \local@_interfaces\ at the default setting) or, more explicitly: -.display asis -local_interfaces = <; ::0.25 ; ::0.26 \ - 0.0.0.0.25 ; 0.0.0.0.26 -.endd -To listen on the default port on all IPv4 interfaces, and on port 26 on the -IPv4 loopback address only: -.display asis -local_interfaces = 0.0.0.0 : 127.0.0.1.26 -.endd -To specify listening on the default port on specific interfaces only: -.display asis -local_interfaces = 192.168.34.67 : 192.168.34.67 -.endd -\**Warning**\: such a setting excludes listening on the loopback interfaces. - - -.section Recognising the local host -.rset SECTreclocipadd "~~chapter.~~section" -The \local@_interfaces\ option is also used when Exim needs to determine -whether or not an IP address refers to the local host. That is, the IP -addresses of all the interfaces on which a daemon is listening are always -treated as local. - -For this usage, port numbers in \local@_interfaces\ are ignored. If either of -the items 0.0.0.0 or @:@:0 are encountered, Exim gets a complete list of -available interfaces from the operating system, and extracts the relevant -(that is, IPv4 or IPv6) addresses to use for checking. - -Some systems set up large numbers of virtual interfaces in order to provide -many virtual web servers. In this situation, you may want to listen for -email on only a few of the available interfaces, but nevertheless treat all -interfaces as local when routing. You can do this by setting -\extra@_local@_interfaces\ to a list of IP addresses, possibly including the -`all' wildcard values. These addresses are recognized as local, but are not -used for listening. Consider this example: -.display asis -local_interfaces = <; 127.0.0.1 ; ::1 ; \ - 192.168.53.235 ; \ - 3ffe:2101:12:1:a00:20ff:fe86:a061 - -extra_local_interfaces = <; ::0 ; 0.0.0.0 -.endd -The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 -address, but all available interface addresses are treated as local when -Exim is routing. - -In some environments the local host name may be in an MX list, but with an IP -address that is not assigned to any local interface. In other cases it may be -desirable to treat other host names as if they referred to the local host. Both -these cases can be handled by setting the \hosts@_treat@_as@_local\ option. -This contains host names rather than IP addresses. When a host is referenced -during routing, either via an MX record or directly, it is treated as the local -host if its name matches \hosts@_treat@_as@_local\, or if any of its IP -addresses match \local@_interfaces\ or \extra@_local@_interfaces\. - - -.section Delivering to a remote host -Delivery to a remote host is handled by the smtp transport. By default, it -allows the system's TCP/IP functions to choose which interface to use (if -there is more than one) when connecting to a remote host. However, the -\interface\ option can be set to specify which interface is used. See the -description of the smtp transport in chapter ~~CHAPsmtptrans for more details. - - - - -. -. -. -. -. ============================================================================ -.chapter Main configuration -.set runningfoot "main configuration" -.rset CHAPmainconfig "~~chapter" -.index configuration file||main section -.index main configuration -The first part of the run time configuration file contains three types of item: -.numberpars $. -Macro definitions: These lines start with an upper case letter. See section -~~SECTmacrodefs for details of macro processing. -.nextp -Named list definitions: These lines start with one of the words `domainlist', -`hostlist', `addresslist', or `localpartlist'. Their use is described in -section ~~SECTnamedlists. -.nextp -Main configuration settings: Each setting occupies one line of the file -(with possible continuations). If any setting is preceded by the word -`hide', the \-bP-\ command line option displays its value to admin users only. -See section ~~SECTcos for a description of the syntax of these option settings. -.endp -This chapter specifies all the main configuration options, along with their -types and default values. For ease of finding a particular option, they appear -in alphabetical order in section ~~SECTalomo below. However, because there are -now so many options, they are first listed briefly in functional groups, as an -aid to finding the name of the option you are looking for. Some options are -listed in more than one group. - -.set savedisplayflowcheck ~~displayflowcheck -.set displayflowcheck 0 - -.section Miscellaneous -.display flow rm -.tabs 31 -\bi@_command\ $t$rm{to run for \-bi-\ command line option} -\keep@_malformed\ $t$rm{for broken files -- should not happen} -\localhost@_number\ $t$rm{for unique message ids in clusters} -\message@_body@_visible\ $t$rm{how much to show in \$message@_body$\} -.newline -.em -\mua@_wrapper\ $t$rm{run in `MUA wrapper' mode} -.nem -.newline -\print@_topbitchars\ $t$rm{top-bit characters are printing} -\timezone\ $t$rm{force time zone} -.endd - -.section Exim parameters -.display flow rm -.tabs 31 -\exim@_group\ $t$rm{override compiled-in value} -\exim@_path\ $t$rm{override compiled-in value} -\exim@_user\ $t$rm{override compiled-in value} -\primary@_hostname\ $t$rm{default from \*uname()*\} -\split@_spool@_directory\ $t$rm{use multiple directories} -\spool@_directory\ $t$rm{override compiled-in value} -.endd - -.section Privilege controls -.display flow rm -.tabs 31 -\admin@_groups\ $t$rm{groups that are Exim admin users} -\deliver@_drop@_privilege\ $t$rm{drop root for delivery processes} -\local@_from@_check\ $t$rm{insert ::Sender:: if necessary} -\local@_from@_prefix\ $t$rm{for testing ::From:: for local sender} -\local@_from@_suffix\ $t$rm{for testing ::From:: for local sender} -\local@_sender@_retain\ $t$rm{keep ::Sender:: from untrusted user} -\never@_users\ $t$rm{do not run deliveries as these} -\prod@_requires@_admin\ $t$rm{forced delivery requires admin user} -\queue@_list@_requires@_admin\ $t$rm{queue listing requires admin user} -\trusted@_groups\ $t$rm{groups that are trusted} -\trusted@_users\ $t$rm{users that are trusted} -.endd - -.section Logging -.display flow rm -.tabs 31 -.em -\hosts@_connection@_nolog\ $t$rm{exemption from connect logging} -.nem -.newline -\log@_file@_path\ $t$rm{override compiled-in value} -\log@_selector\ $t$rm{set/unset optional logging} -\log@_timezone\ $t$rm{add timezone to log lines} -\message@_logs\ $t$rm{create per-message logs} -\preserve@_message@_logs\ $t$rm{after message completion} -\process@_log@_path\ $t$rm{for SIGUSR1 and \*exiwhat*\} -\syslog@_duplication\ $t$rm{controls duplicate log lines on syslog } -\syslog@_facility\ $t$rm{set syslog `facility' field} -\syslog@_processname\ $t$rm{set syslog `ident' field} -\syslog@_timestamp\ $t$rm{timestamp syslog lines} -.newline -\write@_rejectlog\ $t$rm{control use of message log} -.newline -.endd - -.section Frozen messages -.display flow rm -.tabs 31 -\auto@_thaw\ $t$rm{sets time for retrying frozen messages} -\freeze@_tell\ $t$rm{send message when freezing} -\move@_frozen@_messages\ $t$rm{to another directory} -\timeout@_frozen@_after\ $t$rm{keep frozen messages only so long} -.endd - -.section Data lookups -.display flow rm -.tabs 31 -\ldap@_default@_servers\ $t$rm{used if no server in query} -\ldap@_version\ $t$rm{set protocol version} -\lookup@_open@_max\ $t$rm{lookup files held open} -\mysql@_servers\ $t$rm{as it says} -\oracle@_servers\ $t$rm{as it says} -\pgsql@_servers\ $t$rm{as it says} -.endd - -.section Message ids -.display flow rm -.tabs 31 -\message@_id@_header@_domain\ $t$rm{used to build ::Message-ID:: header} -\message@_id@_header@_text\ $t$rm{ditto} -.endd - -.section Embedded Perl Startup -.display flow rm -.tabs 31 -\perl@_at@_start\ $t$rm{always start the interpreter} -\perl@_startup\ $t$rm{code to obey when starting Perl} -.endd - -.section Daemon -.display flow rm -.tabs 31 -\daemon@_smtp@_ports\ $t$rm{default ports} -\extra@_local@_interfaces\ $t$rm{not necessarily listened on} -\local@_interfaces\ $t$rm{on which to listen, with optional ports} -\pid@_file@_path\ $t$rm{override compiled-in value} -\queue@_run@_max\ $t$rm{maximum simultaneous queue runners} -.endd - -.section Resource control -.display flow rm -.tabs 31 -\check@_log@_inodes\ $t$rm{before accepting a message} -\check@_log@_space\ $t$rm{before accepting a message} -\check@_spool@_inodes\ $t$rm{before accepting a message} -\check@_spool@_space\ $t$rm{before accepting a message} -\deliver@_queue@_load@_max\ $t$rm{no queue deliveries if load high} -\queue@_only@_load\ $t$rm{queue incoming if load high} -\queue@_run@_max\ $t$rm{maximum simultaneous queue runners} -\remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} -\smtp@_accept@_max\ $t$rm{simultaneous incoming connections} -\smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} -\smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} -\smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} -\smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} -\smtp@_accept@_queue\ $t$rm{queue mail if more connections} -\smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} -\smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} -\smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} -\smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} -\smtp@_load@_reserve\ $t$rm{SMTP from reserved hosts if load high} -\smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} -.endd - -.section Policy controls -.display flow rm -.tabs 31 -\acl@_not@_smtp\ $t$rm{set ACL for non-SMTP messages} -\acl@_smtp@_auth\ $t$rm{set ACL for \\AUTH\\} -\acl@_smtp@_connect\ $t$rm{set ACL for connection} -\acl@_smtp@_data\ $t$rm{set ACL for \\DATA\\} -\acl@_smtp@_etrn\ $t$rm{set ACL for \\ETRN\\} -\acl@_smtp@_expn\ $t$rm{set ACL for \\EXPN\\} -\acl@_smtp@_helo\ $t$rm{set ACL for \\EHLO\\ or \\HELO\\} -\acl@_smtp@_mail\ $t$rm{set ACL for \\MAIL\\} -\acl@_smtp@_mailauth\ $t$rm{set ACL for \\AUTH\\ on \\MAIL\\ command} -.newline -.em -\acl@_smtp@_mime\ $t$rm{set ACL for MIME parts} -\acl@_smtp@_predata\ $t$rm{set ACL for start of data} -\acl@_smtp@_quit\ $t$rm{set ACL for \\QUIT\\} -.nem -.newline -\acl@_smtp@_rcpt\ $t$rm{set ACL for \\RCPT\\} -\acl@_smtp@_starttls\ $t$rm{set ACL for \\STARTTLS\\} -\acl@_smtp@_vrfy\ $t$rm{set ACL for \\VRFY\\} -.newline -.em -\av@_scanner\ $t$rm{specify virus scanner} -.nem -.newline -\header@_maxsize\ $t$rm{total size of message header} -\header@_line@_maxsize\ $t$rm{individual header line limit} -\helo@_accept@_junk@_hosts\ $t$rm{allow syntactic junk from these hosts} -\helo@_allow@_chars\ $t$rm{allow illegal chars in \\HELO\\ names} -\helo@_lookup@_domains\ $t$rm{lookup hostname for these \\HELO\\ names} -\helo@_try@_verify@_hosts\ $t$rm{\\HELO\\ soft-checked for these hosts} -\helo@_verify@_hosts\ $t$rm{\\HELO\\ hard-checked for these hosts} -\host@_lookup\ $t$rm{host name looked up for these hosts} -\host@_lookup@_order\ $t$rm{order of DNS and local name lookups} -\host@_reject@_connection\ $t$rm{reject connection from these hosts} -\hosts@_treat@_as@_local\ $t$rm{useful in some cluster configurations} -\local@_scan@_timeout\ $t$rm{timeout for \*local@_scan()*\} -\message@_size@_limit\ $t$rm{for all messages} -\percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} -.newline -.em -\spamd@_address\ $t$rm{set interface to SpamAssassin} -.nem -.newline -.endd - -.section Callout cache -.display flow rm -.tabs 31 -\callout@_domain@_negative@_expire\ $t$rm{timeout for negative domain cache item} -\callout@_domain@_positive@_expire\ $t$rm{timeout for positive domain cache item} -\callout@_negative@_expire\ $t$rm{timeout for negative address cache item} -\callout@_positive@_expire\ $t$rm{timeout for positive address cache item} -\callout@_random@_local@_part\ $t$rm{string to use for `random' testing} -.endd - -.section TLS -.display flow rm -.tabs 31 -\tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} -\tls@_certificate\ $t$rm{location of server certificate} -\tls@_crl\ $t$rm{certificate revocation list} -\tls@_dhparam\ $t$rm{DH parameters for server} -.newline -.em -\tls@_on@_connect@_ports\ $t$rm{specify SSMTP (SMTPS) ports} -.nem -.newline -\tls@_privatekey\ $t$rm{location of server private key} -\tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS} -\tls@_require@_ciphers\ $t$rm{specify acceptable cipers} -\tls@_try@_verify@_hosts\ $t$rm{try to verify client certificate} -\tls@_verify@_certificates\ $t$rm{expected client certificates} -\tls@_verify@_hosts\ $t$rm{insist on client certificate verify} -.endd - -.section Local user handling -.display flow rm -.tabs 31 -\finduser@_retries\ $t$rm{useful in NIS environments} -\gecos@_name\ $t$rm{used when creating ::Sender::} -\gecos@_pattern\ $t$rm{ditto} -\max@_username@_length\ $t$rm{for systems that truncate} -\unknown@_login\ $t$rm{used when no login name found} -\unknown@_username\ $t$rm{ditto} -\uucp@_from@_pattern\ $t$rm{for recognizing `From ' lines} -\uucp@_from@_sender\ $t$rm{ditto} -.endd - -.section All incoming messages (SMTP and non-SMTP) -.display flow rm -.tabs 31 -\header@_maxsize\ $t$rm{total size of message header} -\header@_line@_maxsize\ $t$rm{individual header line limit} -\message@_size@_limit\ $t$rm{applies to all messages} -\percent@_hack@_domains\ $t$rm{recognize %-hack for these domains} -\received@_header@_text\ $t$rm{expanded to make ::Received::} -\received@_headers@_max\ $t$rm{for mail loop detection} -\recipients@_max\ $t$rm{limit per message} -\recipients@_max@_reject\ $t$rm{permanently reject excess} -.endd - - -.section Non-SMTP incoming messages -.display rm -.tabs 31 -\receive@_timeout\ $t$rm{for non-SMTP messages} -.endd - - - -.section Incoming SMTP messages -See also the \*Policy controls*\ section above. -.display flow rm -.tabs 31 -\host@_lookup\ $t$rm{host name looked up for these hosts} -\host@_lookup@_order\ $t$rm{order of DNS and local name lookups} -\recipient@_unqualified@_hosts\ $t$rm{may send unqualified recipients} -\rfc1413@_hosts\ $t$rm{make ident calls to these hosts} -\rfc1413@_query@_timeout\ $t$rm{zero disables ident calls} -\sender@_unqualified@_hosts\ $t$rm{may send unqualified senders} -\smtp@_accept@_keepalive\ $t$rm{some TCP/IP magic} -\smtp@_accept@_max\ $t$rm{simultaneous incoming connections} -\smtp@_accept@_max@_nommail\ $t$rm{non-mail commands} -\smtp@_accept@_max@_nonmail@_hosts\ $t$rm{hosts to which the limit applies} -\smtp@_accept@_max@_per@_connection\ $t$rm{messages per connection} -\smtp@_accept@_max@_per@_host\ $t$rm{connections from one host} -\smtp@_accept@_queue\ $t$rm{queue mail if more connections} -\smtp@_accept@_queue@_per@_connection\ $t$rm{queue if more messages per connection} -\smtp@_accept@_reserve\ $t$rm{only reserve hosts if more connections} -.newline -\smtp@_active@_hostname\ $t$rm{host name to use in messages} -.newline -\smtp@_banner\ $t$rm{text for welcome banner} -\smtp@_check@_spool@_space\ $t$rm{from \\SIZE\\ on \\MAIL\\ command} -\smtp@_connect@_backlog\ $t$rm{passed to TCP/IP stack} -\smtp@_enforce@_sync\ $t$rm{of SMTP command/responses} -\smtp@_etrn@_command\ $t$rm{what to run for \\ETRN\\} -\smtp@_etrn@_serialize\ $t$rm{only one at once} -\smtp@_load@_reserve\ $t$rm{only reserve hosts if this load} -\smtp@_max@_unknown@_commands\ $t$rm{before dropping connection} -\smtp@_ratelimit@_hosts\ $t$rm{apply ratelimiting to these hosts} -\smtp@_ratelimit@_mail\ $t$rm{ratelimit for \\MAIL\\ commands} -\smtp@_ratelimit@_rcpt\ $t$rm{ratelimit for \\RCPT\\ commands} -\smtp@_receive@_timeout\ $t$rm{per command or data line} -\smtp@_reserve@_hosts\ $t$rm{these are the reserve hosts} -\smtp@_return@_error@_details\ $t$rm{give detail on rejections} -.endd - -.section SMTP extensions -.display flow rm -.tabs 31 -\accept@_8bitmime\ $t$rm{advertise \\8BITMIME\\} -\auth@_advertise@_hosts\ $t$rm{advertise \\AUTH\\ to these hosts} -\ignore@_fromline@_hosts\ $t$rm{allow `From ' from these hosts} -\ignore@_fromline@_local\ $t$rm{allow `From ' from local SMTP} -\pipelining@_advertise@_hosts\ $t$rm{advertise pipelining to these hosts} -\tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} -.endd - -.section Processing messages -.display flow rm -.tabs 31 -\allow@_domain@_literals\ $t$rm{recognize domain literal syntax} -\allow@_mx@_to@_ip\ $t$rm{allow MX to point to IP address} -\allow@_utf8@_domains\ $t$rm{in addresses} -\delivery@_date@_remove\ $t$rm{from incoming messages} -\envelope@_to@_remote\ $t$rm{from incoming messages} -\extract@_addresses@_remove@_arguments\ $t$rm{affects \-t-\ processing} -\headers@_charset\ $t$rm{default for translations} -\qualify@_domain\ $t$rm{default for senders} -\qualify@_recipient\ $t$rm{default for recipients} -\return@_path@_remove\ $t$rm{from incoming messages} -\strip@_excess@_angle@_brackets\ $t$rm{in addresses} -\strip@_trailing@_dot\ $t$rm{at end of addresses} -\untrusted@_set@_sender\ $t$rm{untrusted can set envelope sender} -.endd - -.section System filter -.display flow rm -.tabs 31 -\system@_filter\ $t$rm{locate system filter} -\system@_filter@_directory@_transport\ $t$rm{transport for delivery to a directory} -\system@_filter@_file@_transport\ $t$rm{transport for delivery to a file} -\system@_filter@_group\ $t$rm{group for filter running} -\system@_filter@_pipe@_transport\ $t$rm{transport for delivery to a pipe} -\system@_filter@_reply@_transport\ $t$rm{transport for autoreply delivery} -\system@_filter@_user\ $t$rm{user for filter running} -.endd - -.section Routing and delivery -.display flow rm -.tabs 31 -\dns@_again@_means@_nonexist\ $t$rm{for broken domains} -\dns@_check@_names@_pattern\ $t$rm{pre-DNS syntax check} -\dns@_ipv4@_lookup\ $t$rm{only v4 lookup for these domains} -\dns@_retrans\ $t$rm{parameter for resolver} -\dns@_retry\ $t$rm{parameter for resolver} -\hold@_domains\ $t$rm{hold delivery for these domains} -\local@_interfaces\ $t$rm{for routing checks} -\queue@_domains\ $t$rm{no immediate delivery for these} -\queue@_only\ $t$rm{no immediate delivery at all} -\queue@_only@_file\ $t$rm{no immediate deliveryif file exists} -\queue@_only@_load\ $t$rm{no immediate delivery if load is high} -\queue@_only@_override\ $t$rm{allow command line to override} -\queue@_run@_in@_order\ $t$rm{order of arrival} -\queue@_run@_max\ $t$rm{of simultaneous queue runners} -\queue@_smtp@_domains\ $t$rm{no immediate SMTP delivery for these} -\remote@_max@_parallel\ $t$rm{parallel SMTP delivery per message} -\remote@_sort@_domains\ $t$rm{order of remote deliveries} -\retry@_data@_expire\ $t$rm{timeout for retry data} -\retry@_interval@_max\ $t$rm{safety net for retry rules} -.endd - -.section Bounce and warning messages -.display flow rm -.tabs 31 -\bounce@_message@_file\ $t$rm{content of bounce} -\bounce@_message@_text\ $t$rm{content of bounce} -\bounce@_return@_body\ $t$rm{include body if returning message} -\bounce@_return@_message\ $t$rm{include original message in bounce} -\bounce@_return@_size@_limit\ $t$rm{limit on returned message} -\bounce@_sender@_authentication\ $t$rm{send authenticated sender with bounce} -\errors@_copy\ $t$rm{copy bounce messages} -\errors@_reply@_to\ $t$rm{::Reply-to:: in bounces} -\delay@_warning\ $t$rm{time schedule} -\delay@_warning@_condition\ $t$rm{condition for warning messages} -\ignore@_bounce@_errors@_after\ $t$rm{discard undeliverable bounces} -\warn@_message@_file\ $t$rm{content of warning message} -.endd - -.set displayflowcheck ~~savedisplayflowcheck - -.section Alphabetical list of main options -.rset SECTalomo "~~chapter.~~section" -.if ~~sgcal -Those options that undergo string expansion before use are marked with $**$. -.fi - -.startconf main - -.index \\8BITMIME\\ -.index 8-bit characters -.conf accept@_8bitmime boolean false -This option causes Exim to send \\8BITMIME\\ in its response to an SMTP -\\EHLO\\ command, and to accept the \\BODY=\\ parameter on \\MAIL\\ commands. -However, though Exim is 8-bit clean, it is not a protocol converter, and it -takes no steps to do anything special with messages received by this route. -Consequently, this option is turned off by default. - -.index ~~ACL||for non-SMTP messages -.index non-SMTP messages, ACL for -.conf acl@_not@_smtp string$**$ unset -This option defines the ACL that is run when a non-SMTP message is on the point -of being accepted. See chapter ~~CHAPACL for further details. - -.index ~~ACL||setting up for SMTP commands -.index \\AUTH\\||ACL for -.conf acl@_smtp@_auth string$**$ unset -This option defines the ACL that is run when an SMTP \\AUTH\\ command is -received. See chapter ~~CHAPACL for further details. - -.index ~~ACL||on SMTP connection -.conf acl@_smtp@_connect string$**$ unset -This option defines the ACL that is run when an SMTP connection is received. -See chapter ~~CHAPACL for further details. - -.index \\DATA\\, ACL for -.conf acl@_smtp@_data string$**$ unset -This option defines the ACL that is run after an SMTP \\DATA\\ command has been -processed and the message itself has been received, but before the final -acknowledgement is sent. See chapter ~~CHAPACL for further details. - -.index \\ETRN\\||ACL for -.conf acl@_smtp@_etrn string$**$ unset -This option defines the ACL that is run when an SMTP \\ETRN\\ command is -received. See chapter ~~CHAPACL for further details. - -.index \\EXPN\\||ACL for -.conf acl@_smtp@_expn string$**$ unset -This option defines the ACL that is run when an SMTP \\EXPN\\ command is -received. See chapter ~~CHAPACL for further details. - -.index \\EHLO\\||ACL for -.index \\HELO\\||ACL for -.conf acl@_smtp@_helo string$**$ unset -This option defines the ACL that is run when an SMTP \\EHLO\\ or \\HELO\\ -command is received. See chapter ~~CHAPACL for further details. - -.index \\MAIL\\||ACL for -.conf acl@_smtp@_mail string$**$ unset -This option defines the ACL that is run when an SMTP \\MAIL\\ command is -received. See chapter ~~CHAPACL for further details. - -.index \\AUTH\\||on \\MAIL\\ command -.conf acl@_smtp@_mailauth string$**$ unset -This option defines the ACL that is run when there is an \\AUTH\\ parameter on -a \\MAIL\\ command. See chapter ~~CHAPACL for details of ACLs, and chapter -~~CHAPSMTPAUTH for details of authentication. - -.em -.index MIME content scanning||ACL for -.conf acl@_smtp@_mime string$**$ unset -This option is available when Exim is built with the content-scanning -extension. It defines the ACL that is run for each MIME part in a message. See -section ~~SECTscanmimepart for details. - -.conf acl@_smtp@_predata string$**$ unset -This option defines the ACL that is run when an SMTP \\DATA\\ command is -received, before the message itself is received. See chapter ~~CHAPACL for -further details. - -.index \\QUIT\\||ACL for -.conf acl@_smtp@_quit string$**$ unset -This option defines the ACL that is run when an SMTP \\QUIT\\ command is -received. See chapter ~~CHAPACL for further details. -.nem - -.index \\RCPT\\||ACL for -.conf acl@_smtp@_rcpt string$**$ unset -This option defines the ACL that is run when an SMTP \\RCPT\\ command is -received. See chapter ~~CHAPACL for further details. - -.index \\STARTTLS\\, ACL for -.conf acl@_smtp@_starttls string$**$ unset -This option defines the ACL that is run when an SMTP \\STARTTLS\\ command is -received. See chapter ~~CHAPACL for further details. - -.index \\VRFY\\||ACL for -.conf acl@_smtp@_vrfy string$**$ unset -This option defines the ACL that is run when an SMTP \\VRFY\\ command is -received. See chapter ~~CHAPACL for further details. - -.conf admin@_groups "string list" unset -.index admin user -If the current group or any of the supplementary groups of the caller is in -this colon-separated list, the caller has admin privileges. If all your system -programmers are in a specific group, for example, you can give them all Exim -admin privileges by putting that group in \admin@_groups\. However, this does -not permit them to read Exim's spool files (whose group owner is the Exim gid). -To permit this, you have to add individuals to the Exim group. - -.conf allow@_domain@_literals boolean false -.index domain literal -If this option is set, the RFC 2822 domain literal format is permitted in -email addresses. The option is not set by default, because the domain literal -format is not normally required these days, and few people know about it. It -has, however, been exploited by mail abusers. - -Unfortunately, it seems that some DNS black list maintainers are using this -format to report black listing to postmasters. If you want to accept messages -addressed to your hosts by IP address, you need to set -\allow@_domain@_literals\ true, and also to add \"@@[]"\ to the list of local -domains (defined in the named domain list \local@_domains\ in the default -configuration). This `magic string' matches the domain literal form of all the -local host's IP addresses. - -.conf allow@_mx@_to@_ip boolean false -.index MX record||pointing to IP address -It appears that more and more DNS zone administrators are breaking the rules -and putting domain names that look like IP addresses on the right hand side of -MX records. Exim follows the rules and rejects this, giving an error message -that explains the mis-configuration. However, some other MTAs support this -practice, so to avoid `Why can't Exim do this?' complaints, \allow@_mx@_to@_ip\ -exists, in order to enable this heinous activity. It is not recommended, except -when you have no other choice. - -.index domain||UTF-8 characters in -.index UTF-8||in domain name -.conf allow@_utf8@_domains boolean false -Lots of discussion is going on about internationalized domain names. One -camp is strongly in favour of just using UTF-8 characters, and it seems -that at least two other MTAs permit this. This option allows Exim users to -experiment if they wish. - -If it is set true, Exim's domain parsing function allows valid -UTF-8 multicharacters to appear in domain name components, in addition to -letters, digits, and hyphens. However, just setting this option is not -enough; if you want to look up these domain names in the DNS, you must also -adjust the value of \dns@_check@_names@_pattern\ to match the extended form. A -suitable setting is: -.display asis -dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ - (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ -.endd -Alternatively, you can just disable this feature by setting -.display asis -dns_check_names_pattern = -.endd -That is, set the option to an empty string so that no check is done. - -.conf auth@_advertise@_hosts "host list$**$" $*$ -.index authentication||advertising -.index \\AUTH\\||advertising -If any server authentication mechanisms are configured, Exim advertises them in -response to an \\EHLO\\ command only if the calling host matches this list. -Otherwise, Exim does not advertise \\AUTH\\. -Exim does not accept \\AUTH\\ commands from clients to which it has not -advertised the availability of \\AUTH\\. The advertising of individual -authentication mechanisms can be controlled by the use of the -\server@_advertise@_condition\ generic authenticator option on the individual -authenticators. See chapter ~~CHAPSMTPAUTH for further details. - -Certain mail clients (for example, Netscape) require the user to provide a name -and password for authentication if \\AUTH\\ is advertised, even though it may -not be needed (the host may accept messages from hosts on its local LAN without -authentication, for example). The \auth@_advertise@_hosts\ option can be used -to make these clients more friendly by excluding them from the set of hosts to -which Exim advertises \\AUTH\\. - -.index \\AUTH\\||advertising when encrypted -If you want to advertise the availability of \\AUTH\\ only when the connection -is encrypted using TLS, you can make use of the fact that the value of this -option is expanded, with a setting like this: -.display asis -auth_advertise_hosts = ${if eq{$tls_cipher}{}{}{*}} -.endd -If \$tls@_cipher$\ is empty, the session is not encrypted, and the result of -the expansion is empty, thus matching no hosts. Otherwise, the result of the -expansion is $*$, which matches all hosts. - -.conf auto@_thaw time 0s -.index thawing messages -.index unfreezing messages -If this option is set to a time greater than zero, a queue runner will try a -new delivery attempt on any frozen message if this much time has passed since -it was frozen. This may result in the message being re-frozen if nothing has -changed since the last attempt. It is a way of saying `keep on trying, even -though there are big problems'. See also \timeout@_frozen@_after\ and -\ignore@_bounce@_errors@_after\. - -.em -.conf av@_scanner string "see below" -This option is available if Exim is built with the content-scanning extension. -It specifies which anti-virus scanner to use. The default value is: -.display asis -sophie:/var/run/sophie -.endd -If the value of \av@_scanner\ starts with dollar character, it is expanded -before use. See section ~~SECTscanvirus for further details. -.nem - -.conf bi@_command string unset -.index \-bi-\ option -This option supplies the name of a command that is run when Exim is called with -the \-bi-\ option (see chapter ~~CHAPcommandline). The string value is just the -command name, it is not a complete command line. If an argument is required, it -must come from the \-oA-\ command line option. - -.conf bounce@_message@_file string unset -.index bounce message||customizing -.index customizing||bounce message -This option defines a template file containing paragraphs of text to be used -for constructing bounce messages. Details of the file's contents are given in -chapter ~~CHAPemsgcust. See also \warn@_message@_file\. - -.conf bounce@_message@_text string unset -When this option is set, its contents are included in the default bounce -message immediately after `This message was created automatically by mail -delivery software.' It is not used if \bounce@_message@_file\ is set. - -.index bounce message||including body -.conf bounce@_return@_body boolean true -This option controls whether the body of an incoming message is included in a -bounce message when \bounce@_return@_message\ is true. If it is not set, only -the message header is included. - -.index bounce message||including original -.conf bounce@_return@_message boolean true -If this option is set false, the original message is not included in bounce -messages generated by Exim. See also \bounce@_return@_size@_limit\. - -.conf bounce@_return@_size@_limit integer 100K -.index size||of bounce, limit -.index bounce message||size limit -.index limit||bounce message size -This option sets a limit in bytes on the size of messages that are returned to -senders as part of bounce messages when \bounce@_return@_message\ is true. The -limit should be less than the value of the global \message@_size@_limit\ and of -any \message@_size@_limit\ settings on transports, to allow for the bounce text -that Exim generates. If this option is set to zero there is no limit. - -When the body of any message that is to be included in a bounce message is -greater than the limit, it is truncated, and a comment pointing this out is -added at the top. The actual cutoff may be greater than the value given, owing -to the use of buffering for transferring the message in chunks (typically 8K in -size). The idea is to save bandwidth on those undeliverable 15-megabyte -messages. - -.index bounce message||sender authentication -.index authentication||bounce message -.index \\AUTH\\||on bounce message -.conf bounce@_sender@_authentication string unset -This option provides an authenticated sender address that is sent with any -bounce messages generated by Exim that are sent over an authenticated SMTP -connection. A typical setting might be: -.display asis -bounce_sender_authentication = mailer-daemon@my.domain.example -.endd -which would cause bounce messages to be sent using the SMTP command: -.display asis -MAIL FROM:<> AUTH=mailer-daemon@my.domain.example -.endd -The value of \bounce@_sender@_authentication\ must always be a complete email -address. - -.index caching||callout, timeouts -.index callout||caching timeouts -.conf callout@_domain@_negative@_expire time 3h -This option specifies the expiry time for negative callout cache data for a -domain. See section ~~SECTcallver for details of callout verification, and -section ~~SECTcallvercache for details of the caching. - -.conf callout@_domain@_positive@_expire time 7d -This option specifies the expiry time for positive callout cache data for a -domain. See section ~~SECTcallver for details of callout verification, and -section ~~SECTcallvercache for details of the caching. - -.conf callout@_negative@_expire time 2h -This option specifies the expiry time for negative callout cache data for an -address. See section ~~SECTcallver for details of callout verification, and -section ~~SECTcallvercache for details of the caching. - -.conf callout@_positive@_expire time 24h -This option specifies the expiry time for positive callout cache data for an -address. See section ~~SECTcallver for details of callout verification, and -section ~~SECTcallvercache for details of the caching. - -.conf callout@_random@_local@_part string$**$ "see below" -This option defines the `random' local part that can be used as part of callout -verification. The default value is -.display asis -$primary_host_name-$tod_epoch-testing -.endd -See section ~~CALLaddparcall for details of how this value is used. - -.conf check@_log@_inodes integer 0 -See \check@_spool@_space\ below. - -.conf check@_log@_space integer 0 -See \check@_spool@_space\ below. - -.conf check@_spool@_inodes integer 0 -See \check@_spool@_space\ below. - -.conf check@_spool@_space integer 0 -.index checking disk space -.index disk space, checking -.index spool directory||checking space -The four \check@_...\ options allow for checking of disk resources before a -message is accepted. -.em -When any of these options are set, they apply to all incoming messages. If you -want to apply different checks to different kinds of message, you can do so -by testing the the variables \$log@_inodes$\, \$log@_space$\, -\$spool@_inodes$\, and \$spool@_space$\ in an ACL with appropriate additional -conditions. -.nem - -\check@_spool@_space\ and \check@_spool@_inodes\ check the spool partition if -either value is greater than zero, for example: -.display asis -check_spool_space = 10M -check_spool_inodes = 100 -.endd -The spool partition is the one that contains the directory defined by -\\SPOOL@_DIRECTORY\\ in \(Local/Makefile)\. It is used for holding messages in -transit. - -\check@_log@_space\ and \check@_log@_inodes\ check the partition in which log -files are written if either is greater than zero. These should be set only if -\log@_file@_path\ and \spool@_directory\ refer to different partitions. - -If there is less space or fewer inodes than requested, Exim refuses to accept -incoming mail. In the case of SMTP input this is done by giving a 452 temporary -error response to the \\MAIL\\ command. If ESMTP is in use and there was a -\\SIZE\\ parameter on the \\MAIL\\ command, its value is added to the -\check@_spool@_space\ value, and the check is performed even if -\check@_spool@_space\ is zero, unless \no@_smtp@_check@_spool@_space\ is set. - -The values for \check@_spool@_space\ and \check@_log@_space\ are held as a -number of kilobytes. If a non-multiple of 1024 is specified, it is rounded up. - -For non-SMTP input and for batched SMTP input, the test is done at start-up; on -failure a message is written to stderr and Exim exits with a non-zero code, as -it obviously cannot send an error message of any kind. - -.index port||for daemon -.index TCP/IP||setting listening ports -.conf daemon@_smtp@_ports string "$tt{smtp}" -This option specifies one or more default SMTP ports on which the Exim daemon -listens. See chapter ~~CHAPinterfaces for details of how it is used. For -backward compatibility, \daemon@_smtp@_port\ (singular) is a synonym. - -.conf delay@_warning "time list" 24h -.index warning of delay -.index delay warning, specifying -When a message is delayed, Exim sends a warning message to the sender at -intervals specified by this option. The data is a colon-separated list of times -after which to send warning messages. -.em -If the value of the option is an empty string or a zero time, no warnings are -sent. -.nem -Up to 10 times may be given. If a message has been on the queue for longer than -the last time, the last interval between the times is used to compute -subsequent warning times. For example, with -.display asis -delay_warning = 4h:8h:24h -.endd -the first message is sent after 4 hours, the second after 8 hours, and -the third one after 24 hours. After that, messages are sent every 16 hours, -because that is the interval between the last two times on the list. If you set -just one time, it specifies the repeat interval. For example, with: -.display asis -delay_warning = 6h -.endd -messages are repeated every six hours. To stop warnings after a given time, set -a very large time at the end of the list. For example: -.display asis -delay_warning = 2h:12h:99d -.endd - -.conf delay@_warning@_condition string$**$ "see below" -The string is expanded at the time a warning message might be sent. If all the -deferred addresses have the same domain, it is set in \$domain$\ during the -expansion. Otherwise \$domain$\ is empty. If the result of the expansion is a -forced failure, an empty string, or a string matching any of `0', `no' or -`false' (the comparison being done caselessly) then the warning message is not -sent. The default is -.display asis -delay_warning_condition = \ - ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} -.endd -which suppresses the sending of warnings about messages that have `bulk', -`list' or `junk' in a ::Precedence:: header. - -.index unprivileged delivery -.index delivery||unprivileged -.conf deliver@_drop@_privilege boolean false -If this option is set true, Exim drops its root privilege at the start of a -delivery process, and runs as the Exim user throughout. This severely restricts -the kinds of local delivery that are possible, but is viable in certain types -of configuration. There is a discussion about the use of root privilege in -chapter ~~CHAPsecurity. - -.index load average -.index queue runner||abandoning -.conf deliver@_queue@_load@_max fixed-point unset -When this option is set, a queue run is abandoned if the system load average -becomes greater than the value of the option. The option has no effect on -ancient operating systems on which Exim cannot determine the load average. -See also \queue@_only@_load\ and \smtp@_load@_reserve\. - -.conf delivery@_date@_remove boolean true -.index ::Delivery-date:: header line -Exim's transports have an option for adding a ::Delivery-date:: header to a -message when it is delivered -- in exactly the same way as ::Return-path:: is -handled. ::Delivery-date:: records the actual time of delivery. Such headers -should not be present in incoming messages, and this option causes them to be -removed at the time the message is received, to avoid any problems that might -occur when a delivered message is subsequently sent on to some other recipient. - -.index DNS||`try again' response, overriding -.conf dns@_again@_means@_nonexist "domain list$**$" unset -DNS lookups give a `try again' response for the DNS errors `non-authoritative -host not found' and `\\SERVERFAIL\\'. This can cause Exim to keep trying to -deliver a message, or to give repeated temporary errors to incoming mail. -Sometimes the effect is caused by a badly set up name server and may persist -for a long time. If a domain which exhibits this problem matches anything in -\dns__again__means__nonexist\, it is treated as if it did not exist. This -option should be used with care. -You can make it apply to reverse lookups by a setting such as this: -.display asis -dns_again_means_nonexist = *.in-addr.arpa -.endd -.em -This option applies to all DNS lookups that Exim does. The \%dnslookup%\ router -has some options of its own for controlling what happens when lookups for MX or -SRV records give temporary errors. These more specific options are applied -after the global option. -.nem - -.index DNS||pre-check of name syntax -.conf dns@_check@_names@_pattern string "see below" -When this option is set to a non-empty string, it causes Exim to check domain -names for illegal characters before handing them to the DNS resolver, because -some resolvers give temporary errors for malformed names. If a domain name -contains any illegal characters, a `not found' result is forced, and the -resolver is not called. The check is done by matching the domain name against a -regular expression, which is the value of this option. The default pattern is -.display asis -dns_check_names_pattern = \ - (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9-]*[^\W_])?)+$ -.endd -which permits only letters, digits, and hyphens in components, but they may not -start or end with a hyphen. -If you set \allow@_utf8@_domains\, you must modify this pattern, or set the -option to an empty string. - -.conf dns@_ipv4@_lookup "domain list$**$" unset -.index IPv6||DNS lookup for AAAA records -.index DNS||IPv6 lookup for AAAA records -When Exim is compiled with IPv6 support, it looks for IPv6 address records -(AAAA and, if configured, A6) as well as IPv4 address records when trying to -find IP addresses for hosts, unless the host's domain matches this list. - -This is a fudge to help with name servers that give big delays or otherwise do -not work for the new IPv6 record types. If Exim is handed an IPv6 address -record as a result of an MX lookup, it always recognizes it, and may as a -result make an outgoing IPv6 connection. All this option does is to make Exim -look only for IPv4-style A records when it needs to find an IP address for a -host name. In due course, when the world's name servers have all been upgraded, -there should be no need for this option. - -.conf dns@_retrans time 0s -.index DNS||resolver options -The options \dns@_retrans\ and \dns@_retry\ can be used to set the -retransmission and retry parameters for DNS lookups. Values of zero (the -defaults) leave the system default settings unchanged. The first value is the -time between retries, and the second is the number of retries. It isn't -totally clear exactly how these settings affect the total time a DNS lookup may -take. I haven't found any documentation about timeouts on DNS lookups; these -parameter values are available in the external resolver interface structure, -but nowhere does it seem to describe how they are used or what you might want -to set in them. - -.conf dns@_retry integer 0 -See \dns@_retrans\ above. - -.conf drop@_cr boolean false -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. - -.conf envelope@_to@_remove boolean true -.index ::Envelope-to:: header line -Exim's transports have an option for adding an ::Envelope-to:: header to a -message when it is delivered -- in exactly the same way as ::Return-path:: is -handled. ::Envelope-to:: records the original recipient address from the -messages's envelope that caused the delivery to happen. Such headers should not -be present in incoming messages, and this option causes them to be removed at -the time the message is received, to avoid any problems that might occur when a -delivered message is subsequently sent on to some other recipient. - -.conf errors@_copy "string list$**$" unset -.index bounce message||copy to other address -.index copy of bounce message -Setting this option causes Exim to send bcc copies of bounce messages that it -generates to other addresses. \**Note**\: this does not apply to bounce messages -coming from elsewhere. The value of the option is a colon-separated list of -items. Each item consists of a pattern, terminated by white space, followed by -a comma-separated list of email addresses. If a pattern contains spaces, it -must be enclosed in double quotes. - -Each pattern is processed in the same way as a single item in an address list -(see section ~~SECTaddresslist). When a pattern matches the recipient of the -bounce message, the message is copied to the addresses on the list. The items -are scanned in order, and once a matching one is found, no further items are -examined. For example: -.display asis -errors_copy = spqr@mydomain postmaster@mydomain.example :\ - rqps@mydomain hostmaster@mydomain.example,\ - postmaster@mydomain.example -.endd -The address list is expanded before use. The expansion variables -\$local@_part$\ and \$domain$\ are set from the original recipient of the error -message, and if there was any wildcard matching in the pattern, the expansion -.index numerical variables (\$1$\, \$2$\, etc)||in \errors@_copy\ -variables \$0$\, \$1$\, etc. are set in the normal way. - -.conf errors@_reply@_to string unset -.index bounce message||::Reply-to:: in -Exim's bounce and delivery warning messages contain the header line -.display -From: Mail Delivery System @<Mailer-Daemon@@<<qualify-domain>>@> -.endd -where <<qualify-domain>> is the value of the \qualify@_domain\ option. -Experience shows that people reply to bounce messages. If the -\errors@_reply@_to\ option is set, a ::Reply-To:: header is added to bounce and -warning messages. For example: -.display asis -errors_reply_to = postmaster@my.domain.example -.endd -The value of the option is not expanded. It must specify a valid RFC 2822 -address. - -.conf exim@_group string "compile-time configured" -.index gid (group id)||Exim's own -.index Exim group -This option changes the gid under which Exim runs when it gives up root -privilege. The default value is compiled into the binary. The value of this -option is used only when \exim@_user\ is also set. Unless it consists entirely -of digits, the string is looked up using \*getgrnam()*\, and failure causes a -configuration error. See chapter ~~CHAPsecurity for a discussion of security -issues. - -.conf exim@_path string "see below" -.index Exim binary, path name -This option specifies the path name of the Exim binary, which is used when Exim -needs to re-exec itself. The default is set up to point to the file \*exim*\ in -the directory configured at compile time by the \\BIN@_DIRECTORY\\ setting. It -is necessary to change \exim@_path\ if, exceptionally, Exim is run from some -other place. -\**Warning**\: Do not use a macro to define the value of this option, because -you will break those Exim utilities that scan the configuration file to find -where the binary is. (They then use the \-bP-\ option to extract option -settings such as the value of \spool@_directory\.) - -.conf exim@_user string "compile-time configured" -.index uid (user id)||Exim's own -.index Exim user -This option changes the uid under which Exim runs when it gives up root -privilege. The default value is compiled into the binary. Ownership of the run -time configuration file and the use of the \-C-\ and \-D-\ command line options -is checked against the values in the binary, not what is set here. - -Unless it consists entirely of digits, the string is looked up using -\*getpwnam()*\, and failure causes a configuration error. If \exim@_group\ is -not also supplied, the gid is taken from the result of \*getpwnam()*\ if it is -used. See chapter ~~CHAPsecurity for a discussion of security issues. - -.conf extra@_local@_interfaces "string list" unset -.index -This option defines network interfaces that are to be considered local when -routing, but which are not used for listening by the daemon. See section -~~SECTreclocipadd for details. - -.conf extract@_addresses@_remove@_arguments boolean true -.index \-t-\ option -.index command line||addresses with \-t-\ -.index Sendmail compatibility||\-t-\ option -According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses -are present on the command line when the \-t-\ option is used to build an -envelope from a message's ::To::, ::Cc:: and ::Bcc:: headers, the command line -addresses are removed from the recipients list. This is also how Smail behaves. -However, other Sendmail documentation (the O'Reilly book) states that command -line addresses are added to those obtained from the header lines. When -\extract__addresses__remove__arguments\ is true (the default), Exim subtracts -argument headers. If it is set false, Exim adds rather than removes argument -addresses. - -.conf finduser@_retries integer 0 -.index NIS, looking up users, retrying -On systems running NIS or other schemes in which user and group information is -distributed from a remote system, there can be times when \*getpwnam()*\ and -related functions fail, even when given valid data, because things time out. -Unfortunately these failures cannot be distinguished from genuine `not found' -errors. If \finduser@_retries\ is set greater than zero, Exim will try that -many extra times to find a user or a group, waiting for one second between -retries. - -.index \(/etc/passwd)\, multiple reading of -.em -You should not set this option greater than zero if your user information is in -a traditional \(/etc/passwd)\ file, because it will cause Exim needlessly to -search the file multiple times for non-existent users, and also cause delay. -.nem - -.conf freeze@_tell "string list, comma separated" unset -.index freezing messages||sending a message when freezing -On encountering certain errors, or when configured to do so in a system filter, -or in an ACL, -Exim freezes a message. This means that no further delivery attempts take place -until an administrator (or the \auto@_thaw\ feature) thaws the message. If -\freeze@_tell\ is set, Exim generates a warning message whenever it freezes -something, unless the message it is freezing is a -locally-generated -bounce message. (Without this exception there is the possibility of looping.) -The warning message is sent to the addresses supplied as the comma-separated -value of this option. If several of the message's addresses cause freezing, -only a single message is sent. -If the freezing was automatic, the reason(s) for freezing can be found in the -message log. If you configure freezing in a filter or ACL, you must arrange for -any logging that you require. - -.conf gecos@_name string$**$ unset -.index HP-UX -.index `gecos' field, parsing -Some operating systems, notably HP-UX, use the `gecos' field in the system -password file to hold other information in addition to users' real names. Exim -looks up this field for use when it is creating ::Sender:: or ::From:: headers. -If either \gecos@_pattern\ or \gecos@_name\ are unset, the contents of the -field are used unchanged, except that, if an ampersand is encountered, it is -replaced by the user's login name with the first character forced to -upper case, since this is a convention that is observed on many systems. - -When these options are set, \gecos@_pattern\ is treated as a regular expression -that is to be applied to the field (again with & replaced by the login name), -and if it matches, \gecos@_name\ is expanded and used as the user's name. -.index numerical variables (\$1$\, \$2$\, etc)||in \gecos@_name\ -Numeric variables such as \$1$\, \$2$\, etc. can be used in the expansion to -pick up sub-fields that were matched by the pattern. In HP-UX, where the user's -name terminates at the first comma, the following can be used: -.display asis -gecos_pattern = ([^,]*) -gecos_name = $1 -.endd - -.conf gecos@_pattern string unset -See \gecos@_name\ above. - -.conf headers@_charset string "see below" -This option sets a default character set for translating from encoded MIME -`words' in header lines, when referenced by an \$h@_xxx$\ expansion item. The -default is the value of \\HEADERS@_CHARSET\\ in \(Local/Makefile)\. The -ultimate default is ISO-8859-1. For more details see the description of header -insertions in section ~~SECTexpansionitems. - - -.conf header@_maxsize integer "see below" -.index header section||maximum size of -.index limit||size of message header section -This option controls the overall maximum size of a message's header -section. The default is the value of \\HEADER@_MAXSIZE\\ in -\(Local/Makefile)\; the default for that is 1M. Messages with larger header -sections are rejected. - -.conf header@_line@_maxsize integer 0 -.index header lines||maximum size of -.index limit||size of one header line -This option limits the length of any individual header line in a message, after -all the continuations have been joined together. Messages with individual -header lines that are longer than the limit are rejected. The default value of -zero means `no limit'. - - - -.conf helo@_accept@_junk@_hosts "host list$**$" unset -.index \\HELO\\||accepting junk data -.index \\EHLO\\||accepting junk data -Exim checks the syntax of \\HELO\\ and \\EHLO\\ commands for incoming SMTP -mail, and gives an error response for invalid data. Unfortunately, there are -some SMTP clients that send syntactic junk. They can be accommodated by setting -this option. Note that this is a syntax check only. See \helo@_verify@_hosts\ -if you want to do semantic checking. -See also \helo@_allow@_chars\ for a way of extending the permitted character -set. - -.conf helo@_allow@_chars string unset -.index \\HELO\\||underscores in -.index \\EHLO\\||underscores in -.index underscore in \\EHLO\\/\\HELO\\ -This option can be set to a string of rogue characters that are permitted in -all \\EHLO\\ and \\HELO\\ names in addition to the standard letters, digits, -hyphens, and dots. If you really must allow underscores, you can set -.display asis -helo_allow_chars = _ -.endd -Note that the value is one string, not a list. - -.conf helo@_lookup@_domains "domain list$**$" "$tt{@@:@@[]}" -.index \\HELO\\||forcing reverse lookup -.index \\EHLO\\||forcing reverse lookup -If the domain given by a client in a \\HELO\\ or \\EHLO\\ command matches this -list, a reverse lookup is done in order to establish the host's true name. The -default forces a lookup if the client host gives the server's name or any of -its IP addresses (in brackets), something that broken clients have been seen to -do. - -.conf helo@_try@_verify@_hosts "host list$**$" unset -.index \\HELO\\||verifying, optional -.index \\EHLO\\||verifying, optional -The RFCs mandate that a server must not reject a message because it doesn't -like the \\HELO\\ or \\EHLO\\ command. By default, Exim just checks the syntax -of these commands (see \helo__accept__junk__hosts\ and \helo@_allow@_chars\ -above). However, some sites like to be stricter. If the calling host matches -\helo@_try@_verify@_hosts\, Exim checks that the host name given in the \\HELO\\ -or \\EHLO\\ command either: -.numberpars $. -is an IP literal matching the calling address of the host (the RFCs -specifically allow this), or -.nextp -.index DNS||reverse lookup -.index reverse DNS lookup -matches the host name that Exim obtains by doing a reverse lookup of the -calling host address, or -.nextp -when looked up using \*gethostbyname()*\ (or \*getipnodebyname()*\ when -available) yields the calling host address. -.endp -However, the \\EHLO\\ or \\HELO\\ command is not rejected if any of the checks -fail. Processing continues, but the result of the check is remembered, and can -be detected later in an ACL by the \"verify = helo"\ condition. If you want -verification failure to cause rejection of \\EHLO\\ or \\HELO\\, use -\helo@_verify@_hosts\ instead. - - -.conf helo@_verify@_hosts "host list$**$" unset -.index \\HELO\\||verifying, mandatory -.index \\EHLO\\||verifying, mandatory -For hosts that match this option, Exim checks the host name given in the -\\HELO\\ or \\EHLO\\ in the same way as for \helo@_try@_verify@_hosts\. If the -check fails, the \\HELO\\ or \\EHLO\\ command is rejected with a 550 error, and -entries are written to the main and reject logs. If a \\MAIL\\ command is -received before \\EHLO\\ or \\HELO\\, it is rejected with a -503 -error. - -.conf hold@_domains "domain list$**$" unset -.index domain||delaying delivery -.index delivery||delaying certain domains -This option allows mail for particular domains to be held on the queue -manually. The option is overridden if a message delivery is forced with the -\-M-\, \-qf-\, \-Rf-\ or \-Sf-\ options, and also while testing or verifying -addresses using \-bt-\ or \-bv-\. Otherwise, if a domain matches an item in -\hold@_domains\, no routing or delivery for that address is done, and it is -deferred every time the message is looked at. - -This option is intended as a temporary operational measure for delaying the -delivery of mail while some problem is being sorted out, or some new -configuration tested. If you just want to delay the processing of some -domains until a queue run occurs, you should use \queue@_domains\ or -\queue@_smtp@_domains\, not \hold@_domains\. - -A setting of \hold@_domains\ does not override Exim's code for removing -messages from the queue if they have been there longer than the longest retry -time in any retry rule. If you want to hold messages for longer than the normal -retry times, insert a dummy retry rule with a long retry time. - -.conf host@_lookup "host list$**$" unset -.index host||name lookup, forcing -Exim does not look up the name of a calling host from its IP address unless it -is required to compare against some host list, or the host matches -\helo@_try@_verify@_hosts\ or \helo@_verify@_hosts\, or the host matches this -option (which normally contains IP addresses rather than host names). The -default configuration file contains -.display asis -host_lookup = * -.endd -which causes a lookup to happen for all hosts. If the expense of these lookups -is felt to be too great, the setting can be changed or removed. - -After a successful reverse lookup, Exim does a forward lookup on the name it -has obtained, to verify that it yields the IP address that it started with. If -this check fails, Exim behaves as if the name lookup failed. - -After any kind of failure, the host name (in \$sender@_host@_name$\) remains -unset, and \$host@_lookup@_failed$\ is set to the string `1'. See also -\dns@_again@_means@_nonexist\, \helo__lookup__domains\, and \"verify = -reverse@_host@_lookup"\ in ACLs. - -.conf host@_lookup@_order "string list" $tt{bydns:byaddr} -This option specifies the order of different lookup methods when Exim is trying -to find a host name from an IP address. The default is to do a DNS lookup -first, and then to try a local lookup (using \*gethostbyaddr()*\ or equivalent) -if that fails. You can change the order of these lookups, or omit one entirely, -if you want. - -\**Warning**\: the `byaddr' method does not always yield aliases when there are -multiple PTR records in the DNS and the IP address is not listed in -\(/etc/hosts)\. Different operating systems give different results in this -case. That is why the default tries a DNS lookup first. - - -.conf host@_reject@_connection "host list$**$" unset -.index host||rejecting connections from -If this option is set, incoming SMTP calls from the hosts listed are rejected -as soon as the connection is made. -This option is obsolete, and retained only for backward compatibility, because -nowadays the ACL specified by \acl@_smtp@_connect\ can also reject incoming -connections immediately. - -The ability to give an immediate rejection (either by this option or using an -ACL) is provided for use in unusual cases. Many hosts will just try again, -sometimes without much delay. Normally, it is better to use an ACL to reject -incoming messages at a later stage, such as after \\RCPT\\ commands. See -chapter ~~CHAPACL. - -.em -.conf hosts@_connection@_nolog "host list$**$" unset -.index host||not logging connections from -This option defines a list of hosts for which connection logging does not -happen, even though the \smtp@_connection\ log selector is set. For example, -you might want not to log SMTP connections from local processes, or from -127.0.0.1, or from your local LAN. This option is consulted in the main loop of -the daemon; you should therefore strive to restrict its value to a short inline -list of IP addresses and networks. To disable logging SMTP connections from -local processes, you must create a host list with an empty item. For example: -.display asis -hosts_connection_nolog = : -.endd -If the \smtp@_connection\ log selector is not set, this option has no effect. -.nem - -.conf hosts@_treat@_as@_local "domain list$**$" unset -.index local host||domains treated as -.index host||treated as local -If this option is set, any host names that match the domain list are treated as -if they were the local host when Exim is scanning host lists obtained from MX -records -or other sources. Note that the value of this option is a domain list, not a -host list, because it is always used to check host names, not IP addresses. - -This option also applies when Exim is matching the special items -\"@@mx@_any"\, \"@@mx@_primary"\, and \"@@mx@_secondary"\ in a domain list (see -section ~~SECTdomainlist), and when checking the \hosts\ option in the \%smtp%\ -transport for the local host (see the \allow@_localhost\ option in that -transport). -See also \local@_interfaces\, \extra@_local@_interfaces\, and chapter -~~CHAPinterfaces, which contains a discussion about local network interfaces -and recognising the local host. - -.conf ignore@_bounce@_errors@_after time 10w -.index bounce message||discarding -.index discarding bounce message -This option affects the processing of bounce messages that cannot be delivered, -that is, those that suffer a permanent delivery failure. (Bounce messages that -suffer temporary delivery failures are of course retried in the usual way.) - -After a permanent delivery failure, bounce messages are frozen, -because there is no sender to whom they can be returned. When a frozen bounce -message has been on the queue for more than the given time, it is unfrozen at -the next queue run, and a further delivery is attempted. If delivery fails -again, the bounce message is discarded. This makes it possible to keep failed -bounce messages around for a shorter time than the normal maximum retry time -for frozen messages. For example, -.display asis -ignore_bounce_errors_after = 12h -.endd -retries failed bounce message deliveries after 12 hours, discarding any further -failures. If the value of this option is set to a zero time period, bounce -failures are discarded immediately. Setting a very long time (as in the default -value) has the effect of disabling this option. For ways of automatically -dealing with other kinds of frozen message, see \auto@_thaw\ and -\timeout@_frozen@_after\. - -.conf ignore@_fromline@_hosts "host list$**$" unset -.index `From' line -.index UUCP||`From' line -Some broken SMTP clients insist on sending a UUCP-like `From' line before the -headers of a message. By default this is treated as the start of the message's -body, which means that any following headers are not recognized as such. Exim -can be made to ignore it by setting \ignore@_fromline@_hosts\ to match those -hosts that insist on sending it. If the sender is actually a local process -rather than a remote host, and is using \-bs-\ to inject the messages, -\ignore__fromline__local\ must be set to achieve this effect. - -.conf ignore@_fromline@_local boolean false -See \ignore@_fromline@_hosts\ above. - -.conf keep@_malformed time 4d -This option specifies the length of time to keep messages whose spool files -have been corrupted in some way. This should, of course, never happen. At the -next attempt to deliver such a message, it gets removed. The incident is -logged. - -.conf ldap@_default@_servers "string list" unset -.index LDAP||default servers -This option provides a list of LDAP servers which are tried in turn when an -LDAP query does not contain a server. See section ~~SECTforldaque for details -of LDAP queries. This option is available only when Exim has been built with -LDAP support. - -.conf ldap@_version integer unset -.index LDAP||protocol version, forcing -This option can be used to force Exim to set a specific protocol version for -LDAP. If it option is unset, it is shown by the \-bP-\ command line option as --1. When this is the case, the default is 3 if \\LDAP@_VERSION3\\ is defined in -the LDAP headers; otherwise it is 2. This option is available only when Exim -has been built with LDAP support. - - -.conf local@_from@_check boolean true -.index ::Sender:: header line||disabling addition of -.index ::From:: header line||disabling checking of -When a message is submitted locally (that is, not over a TCP/IP connection) by -an untrusted user, Exim removes any existing ::Sender:: header line, and checks -that the ::From:: header line matches -.em -the login of the calling user and the domain specified by \qualify@_domain\. - -\**Note**\: An unqualified address (no domain) in the ::From:: header in a -locally submitted message is automatically qualified by Exim, unless the -\-bnq-\ command line option is used. -.nem - -You can use \local@_from@_prefix\ and \local@_from@_suffix\ to permit affixes -on the local part. If the ::From:: header line does not match, Exim adds a -::Sender:: header with an address constructed from the calling user's login and -the default qualify domain. - -If \local@_from@_check\ is set false, the ::From:: header check is disabled, -and no ::Sender:: header is ever added. If, in addition, you want to retain -::Sender:: header lines supplied by untrusted users, you must also set -\local@_sender@_retain\ to be true. - -.index envelope sender -These options affect only the header lines in the message. The envelope sender -is still forced to be the login id at the qualify domain unless -\untrusted@_set@_sender\ permits the user to supply an envelope sender. - -.em -For messages received over TCP/IP, an ACL can specify `submission mode' to -request similar header line checking. See section ~~SECTthesenhea, which has -more details about ::Sender:: processing. -.nem - - -.conf local@_from@_prefix string unset -When Exim checks the ::From:: header line of locally submitted messages for -matching the login id (see \local@_from@_check\ above), it can be configured to -ignore certain prefixes and suffixes in the local part of the address. This is -done by setting \local@_from@_prefix\ and/or \local@_from@_suffix\ to -appropriate lists, in the same form as the \local@_part@_prefix\ and -\local@_part@_suffix\ router options (see chapter ~~CHAProutergeneric). For -example, if -.display asis -local_from_prefix = *- -.endd -is set, a ::From:: line containing -.display asis -From: anything-user@your.domain.example -.endd -will not cause a ::Sender:: header to be added if \*user@@your.domain.example*\ -matches the actual sender address that is constructed from the login name and -qualify domain. - -.conf local@_from@_suffix string unset -See \local@_from@_prefix\ above. - -.conf local@_interfaces "string list" "see below" -This option controls which network interfaces are used by the daemon for -listening; they are also used to identify the local host when routing. Chapter -~~CHAPinterfaces contains a full description of this option and the related -options -.em -\daemon@_smtp@_ports\, \extra@_local@_interfaces\, \hosts@_treat@_as@_local\, -and \tls@_on@_connect@_ports\. -.nem -The default value for \local@_interfaces\ is -.display asis -local_interfaces = 0.0.0.0 -.endd -when Exim is built without IPv6 support; otherwise it is -.display asis -local_interfaces = <; ::0 ; 0.0.0.0 -.endd - -.conf local@_scan@_timeout time 5m -.index timeout||for \*local@_scan()*\ function -.index \*local@_scan()*\ function||timeout -This timeout applies to the \*local@_scan()*\ function (see chapter -~~CHAPlocalscan). Zero means `no timeout'. If the timeout is exceeded, the -incoming message is rejected with a temporary error if it is an SMTP message. -For a non-SMTP message, the message is dropped and Exim ends with a non-zero -code. The incident is logged on the main and reject logs. - - -.conf local@_sender@_retain boolean false -.index ::Sender:: header line||retaining from local submission -When a message is submitted locally (that is, not over a TCP/IP connection) by -an untrusted user, Exim removes any existing ::Sender:: header line. If you -do not want this to happen, you must set \local@_sender@_retain\, and you must -also set \local@_from@_check\ to be false (Exim will complain if you do not). -Section ~~SECTthesenhea has more details about ::Sender:: processing. - - - -.conf localhost@_number string$**$ unset -.index host||locally unique number for -.index message||ids, with multiple hosts -Exim's message ids are normally unique only within the local host. If -uniqueness among a set of hosts is required, each host must set a different -value for the \localhost@_number\ option. The string is expanded immediately -after reading the configuration file (so that a number can be computed from the -host name, for example) and the result of the expansion must be a number in the -range 0--16 (or 0--10 on operating systems with case-insensitive file systems). -This is available in subsequent string expansions via the variable -\$localhost@_number$\. When \localhost@_number is set\, the final two -characters of the message id, instead of just being a fractional part of the -time, are computed from the time and the local host number as described in -section ~~SECTmessiden. - - -.conf log@_file@_path "string list$**$" "set at compile time" -.index log||file path for -This option sets the path which is used to determine the names of Exim's log -files, or indicates that logging is to be to syslog, or both. It is expanded -when Exim is entered, so it can, for example, contain a reference to the host -name. If no specific path is set for the log files at compile or run time, they -are written in a sub-directory called \(log)\ in Exim's spool directory. -Chapter ~~CHAPlog contains further details about Exim's logging, and section -~~SECTwhelogwri describes how the contents of \log@_file@_path\ are used. If -this string is fixed at your installation (contains no expansion variables) it -is recommended that you do not set this option in the configuration file, but -instead supply the path using \\LOG@_FILE@_PATH\\ in \(Local/Makefile)\ so that -it is available to Exim for logging errors detected early on -- in particular, -failure to read the configuration file. - -.conf log@_selector string unset -.index log||selectors -This option can be used to reduce or increase the number of things that Exim -writes to its log files. Its argument is made up of names preceded by plus or -minus characters. For example: -.display asis -log_selector = +arguments -retry_defer -.endd -A list of possible names and what they control is given in the chapter on -logging, in section ~~SECTlogselector. - -.conf log@_timezone boolean false -.index log||timezone for entries -By default, the timestamps on log lines are in local time without the -timezone. This means that if your timezone changes twice a year, the timestamps -in log lines are ambiguous for an hour when the clocks go back. One way of -avoiding this problem is to set the timezone to UTC. An alternative is to set -\log@_timezone\ true. This turns on the addition of the timezone offset to -timestamps in log lines. Turning on this option can add quite a lot to the size -of log files because each line is extended by 6 characters. Note that the -\$tod@_log$\ variable contains the log timestamp without the zone, but there is -another variable called \$tod@_zone$\ that contains just the timezone offset. - -.conf lookup@_open@_max integer 25 -.index too many open files -.index open files, too many -.index file||too many open -.index lookup||maximum open files -.index limit||open files for lookups -This option limits the number of simultaneously open files for single-key -lookups that use regular files (that is, \%lsearch%\, \%dbm%\, and \%cdb%\). Exim -normally keeps these files open during routing, because often the same file is -required several times. If the limit is reached, Exim closes the least recently -used file. Note that if you are using the \*ndbm*\ library, it actually opens -two files for each logical DBM database, though it still counts as one for the -purposes of \lookup@_open@_max\. If you are getting `too many open files' -errors with NDBM, you need to reduce the value of \lookup@_open@_max\. - -.conf max@_username@_length integer 0 -.index length of login name -.index user name||maximum length -.index limit||user name length -Some operating systems are broken in that they truncate long arguments to -\*getpwnam()*\ to eight characters, instead of returning `no such user'. If -this option is set greater than zero, any attempt to call \*getpwnam()*\ with -an argument that is longer behaves as if \*getpwnam()*\ failed. - - -.conf message@_body@_visible integer 500 -.index body of message||visible size -.index message||body, visible size -This option specifies how much of a message's body is to be included in the -\$message@_body$\ and \$message@_body@_end$\ expansion variables. - -.conf message@_id@_header@_domain string$**$ unset -.index ::Message-ID:: header line -If this option is set, the string is expanded and used as the right hand side -(domain) of the ::Message-ID:: header that Exim creates if a -locally-originated incoming message does not have one. `Locally-originated' -means `not received over TCP/IP.' -Otherwise, the primary host name is used. -Only letters, digits, dot and hyphen are accepted; any other characters are -replaced by hyphens. If the expansion is forced to fail, or if the result is an -empty string, the option is ignored. - -.conf message@_id@_header@_text string$**$ unset -If this variable is set, the string is expanded and used to augment the text of -the ::Message-id:: header that Exim creates if a -locally-originated -incoming message does not have one. The text of this header is required by RFC -2822 to take the form of an address. By default, Exim uses its internal message -id as the local part, and the primary host name as the domain. If this option -is set, it is expanded, and provided the expansion is not forced to fail, and -does not yield an empty string, the result is inserted into the header -immediately before the @@, separated from the internal message id by a dot. Any -characters that are illegal in an address are automatically converted into -hyphens. This means that variables such as \$tod@_log$\ can be used, because -the spaces and colons will become hyphens. - -.conf message@_logs boolean true -.index message||log, disabling -.index log||message log, disabling -If this option is turned off, per-message log files are not created in the -\(msglog)\ spool sub-directory. This reduces the amount of disk I/O required by -Exim, by reducing the number of files involved in handling a message from a -minimum of four (header spool file, body spool file, delivery journal, and -per-message log) to three. The other major I/O activity is Exim's main log, -which is not affected by this option. - -.conf message@_size@_limit string$**$ 50M -.index message||size limit -.index limit||message size -.index size||of message, limit -This option limits the maximum size of message that Exim will process. The -value is expanded for each incoming -connection so, for example, it can be made to depend on the IP address of the -remote host for messages arriving via TCP/IP. \**Note**\: This limit cannot be -made to depend on a message's sender or any other properties of an individual -message, because it has to be advertised in the server's response to \\EHLO\\. -String expansion failure causes a temporary error. A value of zero means no -limit, but its use is not recommended. See also \bounce@_return@_size@_limit\. - -Incoming SMTP messages are failed with a 552 error if the limit is -exceeded; locally-generated messages either get a stderr message or a delivery -failure message to the sender, depending on the \-oe-\ setting. Rejection of an -oversized message is logged in both the main and the reject logs. See also the -generic transport option \message@_size@_limit\, which limits the size of -message that an individual transport can process. - -.conf move@_frozen@_messages boolean false -.index frozen messages||moving -This option, which is available only if Exim has been built with the setting -.display asis -SUPPORT_MOVE_FROZEN_MESSAGES=yes -.endd -in \(Local/Makefile)\, causes frozen messages and their message logs to be -moved from the \(input)\ and \(msglog)\ directories on the spool to \(Finput)\ -and \(Fmsglog)\, respectively. There is currently no support in Exim or the -standard utilities for handling such moved messages, and they do not show up in -lists generated by \-bp-\ or by the Exim monitor. - -.em -.conf mua@_wrapper boolean false -Setting this option true causes Exim to run in a very restrictive mode in which -it passes messages synchronously to a smart host. Chapter ~~CHAPnonqueueing -contains a full description of this facility. -.nem - -.conf mysql@_servers "string list" unset -.index MySQL||server list -This option provides a list of MySQL servers and associated connection data, to -be used in conjunction with \%mysql%\ lookups (see section ~~SECTsql). The -option is available only if Exim has been built with MySQL support. - -.conf never@_users "string list" unset -Local message deliveries are normally run in processes that are setuid to the -recipient, and remote deliveries are normally run under Exim's own uid and gid. -It is usually desirable to prevent any deliveries from running as root, as a -safety precaution. - -When Exim is built, an option called \\FIXED@_NEVER@_USERS\\ can be set to a -list of users that must not be used for local deliveries. This list is fixed in -the binary and cannot be overridden by the configuration file. By default, it -contains just the single user name `root'. The \never@_users\ runtime option -can be used to add more users to the fixed list. - -If a message is to be delivered as one of the users on the fixed list or the -\never@_users\ list, an error occurs, and delivery is deferred. A common -example is -.display -never@_users = root:daemon:bin -.endd -Including root is redundant if it is also on the fixed list, but it does no -harm. -This option overrides the \pipe@_as@_creator\ option of the \%pipe%\ transport -driver. - -.conf oracle@_servers "string list" unset -.index Oracle||server list -This option provides a list of Oracle servers and associated connection data, -to be used in conjunction with \%oracle%\ lookups (see section ~~SECTsql). The -option is available only if Exim has been built with Oracle support. - -.conf percent@_hack@_domains "domain list$**$" unset -.index `percent hack' -.index source routing||in email address -.index address||source-routed -The `percent hack' is the convention whereby a local part containing a percent -sign is re-interpreted as a new email address, with the percent replaced by @@. -This is sometimes called `source routing', though that term is also applied to -RFC 2822 addresses that begin with an @@ character. If this option is set, Exim -implements the percent facility for those domains listed, but no others. This -happens before an incoming SMTP address is tested against an ACL. - -\**Warning**\: The `percent hack' has often been abused by people who are -trying to get round relaying restrictions. For this reason, it is best avoided -if at all possible. Unfortunately, a number of less security-conscious MTAs -implement it unconditionally. If you are running Exim on a gateway host, and -routing mail through to internal MTAs without processing the local parts, it is -a good idea to reject recipient addresses with percent characters in their -local parts. Exim's default configuration does this. - -.conf perl@_at@_start boolean false -This option is available only when Exim is built with an embedded Perl -interpreter. See chapter ~~CHAPperl for details of its use. - -.conf perl@_startup string unset -This option is available only when Exim is built with an embedded Perl -interpreter. See chapter ~~CHAPperl for details of its use. - -.conf pgsql@_servers "string list" unset -.index PostgreSQL lookup type||server list -This option provides a list of PostgreSQL servers and associated connection -data, to be used in conjunction with \%pgsql%\ lookups (see section ~~SECTsql). -The option is available only if Exim has been built with PostgreSQL support. - -.conf pid@_file@_path string$**$ "set at compile time" -.index daemon||pid file path -.index pid file, path for -This option sets the name of the file to which the Exim daemon writes its -process id. The string is expanded, so it can contain, for example, references -to the host name: -.display asis -pid_file_path = /var/log/$primary_hostname/exim.pid -.endd -If no path is set, the pid is written to the file \(exim-daemon.pid)\ in Exim's -spool directory. -The value set by the option can be overridden by the \-oP-\ command line -option. A pid file is not written if a `non-standard' daemon is run by means of -the \-oX-\ option, unless a path is explicitly supplied by \-oP-\. - -.conf pipelining@_advertise@_hosts "host list$**$" $*$ -.index \\PIPELINING\\||advertising, suppressing -This option can be used to suppress the advertisement of the SMTP -\\PIPELINING\\ extension to specific hosts. When \\PIPELINING\\ is not -advertised and \smtp@_enforce@_sync\ is true, an Exim server enforces strict -synchronization for each SMTP command and response. -When \\PIPELINING\\ is advertised, Exim assumes that clients will use it; `out -of order' commands that are `expected' do not count as protocol errors (see -\smtp@_max@_synprot@_errors\). - -.conf preserve@_message@_logs boolean false -.index message logs, preserving -If this option is set, message log files are not deleted when messages are -completed. Instead, they are moved to a sub-directory of the spool directory -called \(msglog.OLD)\, where they remain available for statistical or debugging -purposes. This is a dangerous option to set on systems with any appreciable -volume of mail. Use with care! - -.conf primary@_hostname string "see below" -.index name||of local host -.index host||name of local -.index local host||name of -This specifies the name of the current host. It is used in the default \\EHLO\\ -or \\HELO\\ command for outgoing SMTP messages (changeable via the \helo@_data\ -option in the \%smtp%\ transport), -and as the default for \qualify@_domain\. If it is not set, Exim calls -\*uname()*\ to find it. If this fails, Exim panics and dies. If the name -returned by \*uname()*\ contains only one component, Exim passes it to -\*gethostbyname()*\ (or \*getipnodebyname()*\ when available) in order to -obtain the fully qualified version. - -The value of \$primary@_hostname$\ is also used by default in some SMTP -response messages from an Exim server. This can be changed dynamically by -setting \smtp@_active@_hostname\. - -.conf print@_topbitchars boolean false -.index printing characters -.index 8-bit characters -By default, Exim considers only those characters whose codes lie in the range -32--126 to be printing characters. In a number of circumstances (for example, -when writing log entries) non-printing characters are converted into escape -sequences, primarily to avoid messing up the layout. If \print@_topbitchars\ is -set, code values of 128 and above are also considered to be printing -characters. - -.conf process@_log@_path string unset -.index process log path -.index log||process log -.index \*exiwhat*\ -This option sets the name of the file to which an Exim process writes its -`process log' when sent a USR1 signal. This is used by the \*exiwhat*\ utility -script. If this option is unset, the file called \(exim-process.info)\ in -Exim's spool directory is used. The ability to specify the name explicitly can -be useful in environments where two different Exims are running, using -different spool directories. - -.conf prod@_requires@_admin boolean true -.index \-M-\ option -.index \-R-\ option -.index \-q-\ option -The \-M-\, \-R-\, and \-q-\ command-line options require the caller to be an -admin user unless \prod@_requires@_admin\ is set false. See also -\queue@_list@_requires@_admin\. - -.conf qualify@_domain string "see below" -.index domain||for qualifying addresses -.index address||qualification -This option specifies the domain name that is added to any envelope sender -addresses that do not have a domain qualification. It also applies to -recipient addresses if \qualify@_recipient\ is not set. -.em -Unqualified addresses are accepted by default only for locally-generated -messages. - -Qualification is also applied to addresses in header lines such as ::From:: and -::To:: for locally-generated messages, unless the \-bnq-\ command line option -is used. -.nem - -Messages from external sources must always contain fully qualified addresses, -unless the sending host matches \sender@_unqualified@_hosts\ or -\recipient@_unqualified@_hosts\ (as appropriate), in which case incoming -addresses are qualified with \qualify@_domain\ or \qualify@_recipient\ as -necessary. Internally, Exim always works with fully qualified envelope -addresses. If \qualify@_domain\ is not set, it defaults to the -\primary@_hostname\ value. - -.conf qualify@_recipient string "see below" -.em -This option allows you to specify a different domain for qualifying recipient -addresses to the one that is used for senders. See \qualify@_domain\ above. -.nem - -.conf queue@_domains "domain list$**$" unset -.index domain||specifying non-immediate delivery -.index queueing incoming messages -.index message||queueing certain domains -This option lists domains for which immediate delivery is not required. -A delivery process is started whenever a message is received, but only those -domains that do not match are processed. All other deliveries wait until the -next queue run. See also \hold@_domains\ and \queue@_smtp@_domains\. - -.conf queue@_list@_requires@_admin boolean true -.index \-bp-\ option -The \-bp-\ command-line option, which lists the messages that are on the queue, -requires the caller to be an admin user unless \queue__list__requires__admin\ -is set false. See also \prod@_requires@_admin\. - -.conf queue@_only boolean false -.index queueing incoming messages -.index message||queueing unconditionally -If \queue@_only\ is set, a delivery process is not automatically started -whenever a message is received. Instead, the message waits on the queue for the -next queue run. Even if \queue@_only\ is false, incoming messages may not get -delivered immediately when certain conditions (such as heavy load) occur. - -The \-odq-\ command line has the same effect as \queue@_only\. The \-odb-\ and -\-odi-\ command line options override \queue@_only\ unless -\queue@_only@_override\ is set false. See also \queue@_only@_file\, -\queue@_only@_load\, and \smtp@_accept@_queue\. - -.conf queue@_only@_file string unset -.index queueing incoming messages -.index message||queueing by file existence -This option can be set to a colon-separated list of absolute path names, each -one optionally preceded by `smtp'. When Exim is receiving a message, -it tests for the existence of each listed path using a call to \*stat()*\. For -each path that exists, the corresponding queuing option is set. -For paths with no prefix, \queue@_only\ is set; for paths prefixed by `smtp', -\queue@_smtp@_domains\ is set to match all domains. So, for example, -.display asis -queue_only_file = smtp/some/file -.endd -causes Exim to behave as if \queue@_smtp@_domains\ were set to `$*$' whenever -\(/some/file)\ exists. - -.conf queue@_only@_load fixed-point unset -.index load average -.index queueing incoming messages -.index message||queueing by load -If the system load average is higher than this value, incoming messages from -all sources are queued, and no automatic deliveries are started. If this -happens during local or remote SMTP input, all subsequent messages on the same -connection are queued. Deliveries will subsequently be performed by queue -runner processes. This option has no effect on ancient operating systems on -which Exim cannot determine the load average. See also -\deliver@_queue@_load@_max\ and \smtp@_load@_reserve\. - -.conf queue@_only@_override boolean true -.index queueing incoming messages -When this option is true, the \-od\*x*\-\ command line options override the -setting of \queue@_only\ or \queue@_only@_file\ in the configuration file. If -\queue@_only@_override\ is set false, the \-od\*x*\-\ options cannot be used to -override; they are accepted, but ignored. - -.conf queue@_run@_in@_order boolean false -.index queue runner||processing messages in order -If this option is set, queue runs happen in order of message arrival instead of -in an arbitrary order. For this to happen, a complete list of the entire queue -must be set up before the deliveries start. When the queue is all held in a -single directory (the default), -.em -a single list is created for both the ordered and the non-ordered cases. -However, if \split@_spool@_directory\ is set, a single list is not created when -\queue@_run@_in@_order\ is false. In this case, the sub-directories are -processed one at a time (in a random order), and this avoids setting up one -huge list for the whole queue. Thus, setting \queue@_run@_in@_order\ with -\split@_spool@_directory\ may degrade performance when the queue is large, -because of the extra work in setting up the single, large list. In most -situations, \queue@_run@_in@_order\ should not be set. -.nem - -.conf queue@_run@_max integer 5 -.index queue runner||maximum number of -This controls the maximum number of queue runner processes that an Exim daemon -can run simultaneously. This does not mean that it starts them all at once, -but rather that if the maximum number are still running when the time comes to -start another one, it refrains from starting another one. This can happen with -very large queues and/or very sluggish deliveries. This option does not, -however, interlock with other processes, so additional queue runners can be -started by other means, or by killing and restarting the daemon. - -.conf queue@_smtp@_domains "domain list$**$" unset -.index queueing incoming messages -.index message||queueing remote deliveries -When this option is set, a delivery process is started whenever a message is -received, routing is performed, and local deliveries take place. -However, if any SMTP deliveries are required for domains that match -\queue@_smtp@_domains\, they are not immediately delivered, but instead the -message waits on the queue for the next queue run. Since routing of the message -has taken place, Exim knows to which remote hosts it must be delivered, and so -when the queue run happens, multiple messages for the same host are delivered -over a single SMTP connection. The \-odqs-\ command line option causes all SMTP -deliveries to be queued in this way, and is equivalent to setting -\queue@_smtp@_domains\ to `$*$'. See also \hold@_domains\ and \queue@_domains\. - -.conf receive@_timeout time 0s -.index timeout||for non-SMTP input -This option sets the timeout for accepting a non-SMTP message, that is, the -maximum time that Exim waits when reading a message on the standard input. If -the value is zero, it will wait for ever. This setting is overridden by the -\-or-\ command line option. The timeout for incoming SMTP messages is -controlled by \smtp@_receive@_timeout\. - -.index customizing|| ::Received:: header -.index ::Received:: header line||customizing -.conf received@_header@_text string$**$ "see below" -This string defines the contents of the ::Received:: message header that is -added to each message, except for the timestamp, which is automatically added -on at the end (preceded by a semicolon). The string is expanded each time it is -used. If the expansion yields an empty string, no ::Received:: header line is -added to the message. Otherwise, the string should start with the text -`Received:' and conform to the RFC 2822 specification for ::Received:: header -lines. The default setting is: -.display asis -received_header_text = Received: \ - ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ - {${if def:sender_ident {from $sender_ident }}\ - ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ - by $primary_hostname \ - ${if def:received_protocol {with $received_protocol}} \ - ${if def:tls_cipher {($tls_cipher)\n\t}}\ - (Exim $version_number)\n\t\ - id $message_id\ - ${if def:received_for {\n\tfor $received_for}} -.endd -Note the use of quotes, to allow the sequences \"@\n"\ and \"@\t"\ to be used -for newlines and tabs, respectively. The reference to the TLS cipher is omitted -when Exim is built without TLS support. The use of conditional expansions -ensures that this works for both locally generated messages and messages -received from remote hosts, giving header lines such as the following: -.display asis -Received: from scrooge.carol.example ([192.168.12.25] ident=root) - by marley.carol.example with esmtp (Exim 4.00) - id 16IOWa-00019l-00 - for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 -Received: by scrooge.carol.example with local (Exim 4.00) - id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 -.endd -Until the body of the message has been received, the timestamp is the time when -the message started to be received. Once the body has arrived, and all policy -checks have taken place, the timestamp is updated to the time at which the -message was accepted. - -.conf received@_headers@_max integer 30 -.index loop||prevention -.index mail loop prevention -.index ::Received:: header line||counting -When a message is to be delivered, the number of ::Received:: headers is -counted, and if it is greater than this parameter, a mail loop is assumed to -have occurred, the delivery is abandoned, and an error message is generated. -This applies to both local and remote deliveries. - -.conf recipient@_unqualified@_hosts "host list$**$" unset -.index unqualified addresses -.index host||unqualified addresses from -This option lists those hosts from which Exim is prepared to accept unqualified -recipient addresses in message envelopes. The addresses are made fully -qualified by the addition of the \qualify@_recipient\ value. This option also -affects message header lines. Exim does not reject unqualified recipient -addresses in headers, but it qualifies them only if the message came from a -host that matches \recipient@_unqualified@_hosts\, -or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ -option was not set. - -.conf recipients@_max integer 0 -.index limit||number of recipients -.index recipient||maximum number -If this option is set greater than zero, it specifies the maximum number of -original recipients for any message. Additional recipients that are generated -by aliasing or forwarding do not count. SMTP messages get a 452 response for -all recipients over the limit; earlier recipients are delivered as normal. -Non-SMTP messages with too many recipients are failed, and no deliveries are -done. -.index \\RCPT\\||maximum number of incoming -Note that the RFCs specify that an SMTP server should accept at least 100 -\\RCPT\\ commands in a single message. - -.conf recipients@_max@_reject boolean false -If this option is set true, Exim rejects SMTP messages containing too many -recipients by giving 552 errors to the surplus \\RCPT\\ commands, and a 554 -error to the eventual \\DATA\\ command. Otherwise (the default) it gives a 452 -error to the surplus \\RCPT\\ commands and accepts the message on behalf of the -initial set of recipients. The remote server should then re-send the message -for the remaining recipients at a later time. - -.conf remote@_max@_parallel integer 2 -.index delivery||parallelism for remote -This option controls parallel delivery of one message to a number of remote -hosts. If the value is less than 2, parallel delivery is disabled, and Exim -does all the remote deliveries for a message one by one. Otherwise, if a single -message has to be delivered to more than one remote host, or if several copies -have to be sent to the same remote host, up to \remote@_max@_parallel\ -deliveries are done simultaneously. If more than \remote@_max@_parallel\ -deliveries are required, the maximum number of processes are started, and as -each one finishes, another is begun. The order of starting processes is the -same as if sequential delivery were being done, and can be controlled by the -\remote@_sort@_domains\ option. If parallel delivery takes place while running -with debugging turned on, the debugging output from each delivery process is -tagged with its process id. - -This option controls only the maximum number of parallel deliveries for one -message in one Exim delivery process. Because Exim has no central queue -manager, there is no way of controlling the total number of simultaneous -deliveries if the configuration allows a delivery attempt as soon as a message -is received. -.index number of deliveries -.index delivery||maximum number of -If you want to control the total number of deliveries on the system, you -need to set the \queue@_only\ option. This ensures that all incoming messages -are added to the queue without starting a delivery process. Then set up an Exim -daemon to start queue runner processes at appropriate intervals (probably -fairly often, for example, every minute), and limit the total number of queue -runners by setting the \queue__run__max\ parameter. Because each queue runner -delivers only one message at a time, the maximum number of deliveries that can -then take place at once is \queue@_run@_max\ multiplied by -\remote@_max@_parallel\. - -If it is purely remote deliveries you want to control, use -\queue@_smtp@_domains\ instead of \queue@_only\. This has the added benefit of -doing the SMTP routing before queuing, so that several messages for the same -host will eventually get delivered down the same connection. - -.conf remote@_sort@_domains "domain list$**$" unset -.index sorting remote deliveries -.index delivery||sorting remote -When there are a number of remote deliveries for a message, they are sorted by -domain into the order given by this list. For example, -.display asis -remote_sort_domains = *.cam.ac.uk:*.uk -.endd -would attempt to deliver to all addresses in the \*cam.ac.uk*\ domain first, then -to those in the \uk\ domain, then to any others. - -.conf retry@_data@_expire time 7d -.index hints database||data expiry -This option sets a `use before' time on retry information in Exim's hints -database. Any older retry data is ignored. This means that, for example, once a -host has not been tried for 7 days, Exim behaves as if it has no knowledge of -past failures. - -.conf retry@_interval@_max time 24h -.index retry||limit on interval -.index limit||on retry interval -Chapter ~~CHAPretry describes Exim's mechanisms for controlling the intervals -between delivery attempts for messages that cannot be delivered straight away. -This option sets an overall limit to the length of time between retries. - -.conf return@_path@_remove boolean true -.index ::Return-path:: header line||removing -RFC 2821, section 4.4, states that an SMTP server must insert a ::Return-path:: -header line into a message when it makes a `final delivery'. The ::Return-path:: -header preserves the sender address as received in the \\MAIL\\ command. This -description implies that this header should not be present in an incoming -message. If \return@_path@_remove\ is true, any existing ::Return-path:: -headers are removed from messages at the time they are received. Exim's -transports have options for adding ::Return-path:: headers at the time of -delivery. They are normally used only for final local deliveries. - -.conf return@_size@_limit integer 100K -This option is an obsolete synonym for \bounce@_return@_size@_limit\. - -.conf rfc1413@_hosts "host list$**$" $*$ -.index RFC 1413 -.index host||for RFC 1413 calls -RFC 1413 identification calls are made to any client host which matches an item -in the list. - -.conf rfc1413@_query@_timeout time 30s -.index RFC 1413||query timeout -.index timeout||for RFC 1413 call -This sets the timeout on RFC 1413 identification calls. If it is set to zero, -no RFC 1413 calls are ever made. - -.conf sender@_unqualified@_hosts "host list$**$" unset -.index unqualified addresses -.index host||unqualified addresses from -This option lists those hosts from which Exim is prepared to accept unqualified -sender addresses. The addresses are made fully qualified by the addition of -\qualify@_domain\. This option also affects message header lines. Exim does not -reject unqualified addresses in headers that contain sender addresses, but it -qualifies them only if the message came from a host that matches -\sender@_unqualified@_hosts\, -or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ -option was not set. - -.conf smtp@_accept@_keepalive boolean true -.index keepalive||on incoming connection -This option controls the setting of the \\SO@_KEEPALIVE\\ option on incoming -TCP/IP socket connections. When set, it causes the kernel to probe idle -connections periodically, by sending packets with `old' sequence numbers. The -other end of the connection should send an acknowledgement if the connection is -still okay or a reset if the connection has been aborted. The reason for doing -this is that it has the beneficial effect of freeing up certain types of -connection that can get stuck when the remote host is disconnected without -tidying up the TCP/IP call properly. The keepalive mechanism takes several -hours to detect unreachable hosts. - - -.conf smtp@_accept@_max integer 20 -.index limit||incoming SMTP connections -.index SMTP||incoming connection count -.index inetd -This option specifies the maximum number of simultaneous incoming SMTP calls -that Exim will accept. It applies only to the listening daemon; there is no -control (in Exim) when incoming SMTP is being handled by \*inetd*\. If the value -is set to zero, no limit is applied. However, it is required to be non-zero if -either \smtp@_accept@_max@_per@_host\ or \smtp@_accept@_queue\ is set. See also -\smtp@_accept@_reserve\. - - -.conf smtp@_accept@_max@_nonmail integer 10 -.index limit||non-mail SMTP commands -.index SMTP||limiting non-mail commands -Exim counts the number of `non-mail' commands in an SMTP session, and drops the -connection if there are too many. This option defines `too many'. The check -catches some denial-of-service attacks, repeated failing \\AUTH\\s, or a mad -client looping sending \\EHLO\\, for example. The check is applied only if the -client host matches \smtp@_accept@_max@_nonmail@_hosts\. - -When a new message is expected, one occurrence of \\RSET\\ is not counted. This -allows a client to send one \\RSET\\ between messages (this is not necessary, -but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ -or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After -starting up a TLS session, another \\EHLO\\ is expected, and so it too is not -counted. The first occurrence of \\AUTH\\ in a connection, or immediately -following \\STARTTLS\\ is not counted. Otherwise, all commands other than -\\MAIL\\, \\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. - -.conf smtp@_accept@_max@_nonmail@_hosts "host list$**$" $*$ -You can control which hosts are subject to the \smtp@_accept@_max@_nonmail\ -check by setting this option. The default value makes it apply to all hosts. By -changing the value, you can exclude any badly-behaved hosts that you have to -live with. - - -.conf smtp@_accept@_max@_per@_connection integer 1000 -.index SMTP||incoming message count, limiting -.index limit||messages per SMTP connection -The value of this option limits the number of \\MAIL\\ commands that Exim is -prepared to accept over a single SMTP connection, whether or not each command -results in the transfer of a message. After the limit is reached, a 421 -response is given to subsequent \\MAIL\\ commands. This limit is a safety -precaution against a client that goes mad (incidents of this type have been -seen). - -.conf smtp@_accept@_max@_per@_host string$**$ unset -.index limit||SMTP connections from one host -.index host||limiting SMTP connections from -This option restricts the number of simultaneous IP connections from a single -host (strictly, from a single IP address) to the Exim daemon. The option is -expanded, to enable different limits to be applied to different hosts by -reference to \$sender@_host@_address$\. Once the limit is reached, additional -connection attempts from the same host are rejected with error code 421. The -default value of zero imposes no limit. If this option is set, it is required -that \smtp@_accept@_max\ be non-zero. - -\**Warning**\: When setting this option you should not use any expansion -constructions that take an appreciable amount of time. The expansion and test -happen in the main daemon loop, in order to reject additional connections -without forking additional processes (otherwise a denial-of-service attack -could cause a vast number or processes to be created). While the daemon is -doing this processing, it cannot accept any other incoming connections. - - -.conf smtp@_accept@_queue integer 0 -.index SMTP||incoming connection count -.index queueing incoming messages -.index message||queueing by SMTP connection count -If the number of simultaneous incoming SMTP calls handled via the listening -daemon exceeds this value, messages received by SMTP are just placed on the -queue; no delivery processes are started automatically. A value of zero implies -no limit, and clearly any non-zero value is useful only if it is less than the -\smtp@_accept@_max\ value (unless that is zero). See also \queue@_only\, -\queue@_only@_load\, \queue@_smtp@_domains\, and the various \-od-\ command -line options. - -.conf smtp@_accept@_queue@_per@_connection integer 10 -.index queueing incoming messages -.index message||queueing by message count -This option limits the number of delivery processes that Exim starts -automatically when receiving messages via SMTP, whether via the daemon or by -the use of \-bs-\ or \-bS-\. If the value of the option is greater than zero, -and the number of messages received in a single SMTP session exceeds this -number, subsequent messages are placed on the queue, but no delivery processes -are started. This helps to limit the number of Exim processes when a server -restarts after downtime and there is a lot of mail waiting for it on other -systems. On large systems, the default should probably be increased, and on -dial-in client systems it should probably be set to zero (that is, disabled). - -.conf smtp@_accept@_reserve integer 0 -.index SMTP||incoming call count -.index host||reserved -When \smtp@_accept@_max\ is set greater than zero, this option specifies a -number of SMTP connections that are reserved for connections from the hosts -that are specified in \smtp@_reserve@_hosts\. The value set in -\smtp@_accept@_max\ includes this reserve pool. The specified hosts are not -restricted to this number of connections; the option specifies a minimum number -of connection slots for them, not a maximum. It is a guarantee that that group -of hosts can always get at least \smtp@_accept@_reserve\ connections. - -For example, if \smtp@_accept@_max\ is set to 50 and \smtp@_accept@_reserve\ is -set to 5, once there are 45 active connections (from any hosts), new -connections are accepted only from hosts listed in \smtp@_reserve@_hosts\. -See also \smtp@_accept@_max@_per@_host\. - -.conf smtp@_active@_hostname string$**$ unset -.index host||name in SMTP responses -.index SMTP||host name in responses -This option is provided for multi-homed servers that want to masquerade as -several different hosts. At the start of an SMTP connection, its value is -expanded and used instead of the value of \$primary@_hostname$\ in SMTP -responses. For example, it is used as domain name in the response to an -incoming \\HELO\\ or \\EHLO\\ command. -.em -It is also used in \\HELO\\ commands for callout verification. -The active hostname is placed in the \$smtp__active__hostname$\ variable, which -is saved with any messages that are received. It is therefore available for use -in routers and transports when the message is later delivered. -.nem - -If this option is unset, or if its expansion is forced to fail, or if the -expansion results in an empty string, the value of \$primary@_hostname$\ is -used. Other expansion failures cause a message to be written to the main and -panic logs, and the SMTP command receives a temporary error. Typically, the -value of \smtp@_active@_hostname\ depends on the incoming interface address. -For example: -.display asis -smtp_active_hostname = ${if eq{$interface_address}{10.0.0.1}\ - {cox.mydomain}{box.mydomain}} -.endd - -.conf smtp@_banner string$**$ "see below" -.index SMTP||welcome banner -.index banner for SMTP -.index welcome banner for SMTP -.index customizing||SMTP banner -This string, which is expanded every time it is used, is output as the initial -positive response to an SMTP connection. The default setting is: -.display asis -.em -smtp_banner = $smtp_active_hostname ESMTP Exim \ - $version_number $tod_full -.nem -.endd -Failure to expand the string causes a panic error. If you want to create a -multiline response to the initial SMTP connection, use `@\n' in the string at -appropriate points, but not at the end. Note that the 220 code is not included -in this string. Exim adds it automatically (several times in the case of a -multiline response). - -.conf smtp@_check@_spool@_space boolean true -.index checking disk space -.index disk space, checking -.index spool directory||checking space -When this option is set, if an incoming SMTP session encounters the \\SIZE\\ -option on a \\MAIL\\ command, it checks that there is enough space in the -spool directory's partition to accept a message of that size, while still -leaving free the amount specified by \check@_spool@_space\ (even if that value -is zero). If there isn't enough space, a temporary error code is returned. - -.conf smtp@_connect@_backlog integer 20 -.index connection backlog -.index SMTP||connection backlog -.index backlog of connections -This option specifies a maximum number of waiting SMTP connections. Exim passes -this value to the TCP/IP system when it sets up its listener. Once this number -of connections are waiting for the daemon's attention, subsequent connection -attempts are refused at the TCP/IP level. At least, that is what the manuals -say; in some circumstances such connection attempts have been observed to time -out instead. For large systems it is probably a good idea to increase the -value (to 50, say). It also gives some protection against denial-of-service -attacks by SYN flooding. - -.conf smtp@_enforce@_sync boolean true -.index SMTP||synchronization checking -.index synchronization checking in SMTP -The SMTP protocol specification requires the client to wait for a response from -the server at certain points in the dialogue. Without \\PIPELINING\\ these -synchronization points are after every command; with \\PIPELINING\\ they are -fewer, but they still exist. - -Some spamming sites send out a complete set of SMTP commands without waiting -for any response. Exim protects against this by rejecting a message if the -client has sent further input when it should not have. The error response `554 -SMTP synchronization error' is sent, and the connection is dropped. Testing for -this error cannot be perfect because of transmission delays (unexpected input -may be on its way but not yet received when Exim checks). However, it does -detect many instances. - -.em -The check can be globally disabled by setting \smtp@_enforce@_sync\ false. -If you want to disable the check selectively (for example, only for certain -hosts), you can do so by an appropriate use of a \control\ modifier in an ACL -(see section ~~SECTcontrols). See also \pipelining@_advertise@_hosts\. -.nem - -.conf smtp@_etrn@_command string$**$ unset -.index \\ETRN\\||command to be run -If this option is set, the given command is run whenever an SMTP \\ETRN\\ -command is received from a host that is permitted to issue such commands (see -chapter ~~CHAPACL). The string is split up into separate arguments which are -independently expanded. The expansion variable \$domain$\ is set to the -argument of the \\ETRN\\ command, and no syntax checking is done on it. For -example: -.display asis -smtp_etrn_command = /etc/etrn_command $domain $sender_host_address -.endd -A new process is created to run the command, but Exim does not wait for it to -complete. Consequently, its status cannot be checked. If the command cannot be -run, a line is written to the panic log, but the \\ETRN\\ caller still receives -a 250 success response. Exim is normally running under its own uid when -receiving SMTP, so it is not possible for it to change the uid before running -the command. - -.conf smtp@_etrn@_serialize boolean true -.index \\ETRN\\||serializing -When this option is set, it prevents the simultaneous execution of more than -one identical command as a result of \\ETRN\\ in an SMTP connection. See -section ~~SECTETRN for details. - -.conf smtp@_load@_reserve fixed-point unset -.index load average -If the system load average ever gets higher than this, incoming SMTP calls are -accepted only from those hosts that match an entry in \smtp@_reserve@_hosts\. -If \smtp@_reserve@_hosts\ is not set, no incoming SMTP calls are accepted when -the load is over the limit. The option has no effect on ancient operating -systems on which Exim cannot determine the load average. See also -\deliver@_queue@_load@_max\ and \queue@_only@_load\. - - -.conf smtp@_max@_synprot@_errors integer 3 -.index SMTP||limiting syntax and protocol errors -.index limit||SMTP syntax and protocol errors -Exim rejects SMTP commands that contain syntax or protocol errors. In -particular, a syntactically invalid email address, as in this command: -.display asis -RCPT TO:<abc xyz@a.b.c> -.endd -causes immediate rejection of the command, before any other tests are done. -(The ACL cannot be run if there is no valid address to set up for it.) An -example of a protocol error is receiving \\RCPT\\ before \\MAIL\\. If there are -too many syntax or protocol errors in one SMTP session, the connection is -dropped. The limit is set by this option. - -.index \\PIPELINING\\||expected errors -When the \\PIPELINING\\ extension to SMTP is in use, some protocol errors are -`expected', for instance, a \\RCPT\\ command after a rejected \\MAIL\\ command. -Exim assumes that \\PIPELINING\\ will be used if it advertises it (see -\pipelining@_advertise@_hosts\), and in this situation, `expected' errors do -not count towards the limit. - - -.conf smtp@_max@_unknown@_commands integer 3 -.index SMTP||limiting unknown commands -.index limit||unknown SMTP commands -If there are too many unrecognized commands in an incoming SMTP session, an -Exim server drops the connection. This is a defence against some kinds of abuse -that subvert web -clients -into making connections to SMTP ports; in these circumstances, a number of -non-SMTP command lines are sent first. - - -.conf smtp@_ratelimit@_hosts "host list$**$" unset -.index SMTP||rate limiting -.index limit||rate of message arrival -.index \\RCPT\\||rate limiting -Some sites find it helpful to be able to limit the rate at which certain hosts -can send them messages, and the rate at which an individual message can specify -recipients. When a host matches \smtp@_ratelimit@_hosts\, the values of -\smtp@_ratelimit@_mail\ and \smtp@_ratelimit@_rcpt\ are used to control the -rate of acceptance of \\MAIL\\ and \\RCPT\\ commands in a single SMTP session, -respectively. Each option, if set, must contain a set of four comma-separated -values: -.numberpars $. -A threshold, before which there is no rate limiting. -.nextp -An initial time delay. Unlike other times in Exim, numbers with decimal -fractional parts are allowed here. -.nextp -A factor by which to increase the delay each time. -.nextp -A maximum value for the delay. This should normally be less than 5 minutes, -because after that time, the client is liable to timeout the SMTP command. -.endp -For example, these settings have been used successfully at the site which -first suggested this feature, for controlling mail from their customers: -.display asis -smtp_ratelimit_mail = 2,0.5s,1.05,4m -smtp_ratelimit_rcpt = 4,0.25s,1.015,4m -.endd -The first setting specifies delays that are applied to \\MAIL\\ commands after -two have been received over a single connection. The initial delay is 0.5 -seconds, increasing by a factor of 1.05 each time. The second setting applies -delays to \\RCPT\\ commands when more than four occur in a single message. - -It is also possible to configure delays explicitly in ACLs. See section -~~SECTACLmodi for details. - - -.conf smtp@_ratelimit@_mail string unset -See \smtp@_ratelimit@_hosts\ above. - -.conf smtp@_ratelimit@_rcpt string unset -See \smtp@_ratelimit@_hosts\ above. - -.conf smtp@_receive@_timeout time 5m -.index timeout||for SMTP input -.index SMTP||timeout, input -This sets a timeout value for SMTP reception. It applies to all forms of SMTP -input, including batch SMTP. If a line of input (either an SMTP command or a -data line) is not received within this time, the SMTP connection is dropped and -the message is abandoned. -A line is written to the log containing one of the following messages: -.display asis -SMTP command timeout on connection from... -SMTP data timeout on connection from... -.endd -The former means that Exim was expecting to read an SMTP command; the latter -means that it was in the \\DATA\\ phase, reading the contents of a message. - - -.index \-os-\ option -The value set by this option can be overridden by the -\-os-\ command-line option. A setting of zero time disables the timeout, but -this should never be used for SMTP over TCP/IP. (It can be useful in some cases -of local input using \-bs-\ or \-bS-\.) For non-SMTP input, the reception -timeout is controlled by \receive@_timeout\ and \-or-\. - -.conf smtp@_reserve@_hosts "host list$**$" unset -This option defines hosts for which SMTP connections are reserved; see -\smtp@_accept@_reserve\ and \smtp@_load@_reserve\ above. - -.conf smtp@_return@_error@_details boolean false -.index SMTP||details policy failures -.index policy control||rejection, returning details -In the default state, Exim uses bland messages such as -`Administrative prohibition' when it rejects SMTP commands for policy -reasons. Many sysadmins like this because it gives away little information -to spammers. However, some other syadmins who are applying strict checking -policies want to give out much fuller information about failures. Setting -\smtp@_return@_error@_details\ true causes Exim to be more forthcoming. For -example, instead of `Administrative prohibition', it might give: -.display asis -550-Rejected after DATA: '>' missing at end of address: -550 failing address in "From" header is: <user@dom.ain -.endd - -.em -.conf spamd@_address string "$tt{127.0.0.1 783}" -This option is available when Exim is compiled with the content-scanning -extension. It specifies how Exim connects to SpamAssassin's \spamd\ daemon. See -section ~~SECTscanspamass for more details. -.nem - -.conf split@_spool@_directory boolean false -.index multiple spool directories -.index spool directory||split -.index directories, multiple -If this option is set, it causes Exim to split its input directory into 62 -subdirectories, each with a single alphanumeric character as its name. The -sixth character of the message id is used to allocate messages to -subdirectories; this is the least significant base-62 digit of the time of -arrival of the message. - -Splitting up the spool in this way may provide better performance on systems -where there are long mail queues, by reducing the number of files in any one -directory. The msglog directory is also split up in a similar way to the input -directory; however, if \preserve@_message@_logs\ is set, all old msglog files -are still placed in the single directory \(msglog.OLD)\. - -It is not necessary to take any special action for existing messages when -changing \split@_spool@_directory\. Exim notices messages that are in the -`wrong' place, and continues to process them. If the option is turned off after -a period of being on, the subdirectories will eventually empty and be -automatically deleted. - -When \split@_spool@_directory\ is set, the behaviour of queue runner processes -changes. Instead of creating a list of all messages in the queue, and then -trying to deliver each one in turn, it constructs a list of those in one -sub-directory and tries to deliver them, before moving on to the next -sub-directory. The sub-directories are processed in a random order. This -spreads out the scanning of the input directories, and uses less memory. It is -particularly beneficial when there are lots of messages on the queue. However, -if \queue@_run@_in@_order\ is set, none of this new processing happens. The -entire queue has to be scanned and sorted before any deliveries can start. - -.conf spool@_directory string$**$ "set at compile time" -.index spool directory||path to -This defines the directory in which Exim keeps its spool, that is, the messages -it is waiting to deliver. The default value is taken from the compile-time -configuration setting, if there is one. If not, this option must be set. The -string is expanded, so it can contain, for example, a reference to -\$primary@_hostname$\. - -If the spool directory name is fixed on your installation, it is recommended -that you set it at build time rather than from this option, particularly if the -log files are being written to the spool directory (see \log@_file@_path\). -Otherwise log files cannot be used for errors that are detected early on, such -as failures in the configuration file. - -By using this option to override the compiled-in path, it is possible to run -tests of Exim without using the standard spool. - -.conf strip@_excess@_angle@_brackets boolean false -.index angle brackets, excess -If this option is set, redundant pairs of angle brackets round `route-addr' -items in addresses are stripped. For example, \*@<@<xxx@@a.b.c.d@>@>*\ is treated -as \*@<xxx@@a.b.c.d@>*\. If this is in the envelope and the message is passed on -to another MTA, the excess angle brackets are not passed on. If this option is -not set, multiple pairs of angle brackets cause a syntax error. - -.conf strip@_trailing@_dot boolean false -.index trailing dot on domain -.index dot||trailing on domain -If this option is set, a trailing dot at the end of a domain in an address is -ignored. If this is in the envelope and the message is passed on to another -MTA, the dot is not passed on. If this option is not set, a dot at the end of a -domain causes a syntax error. -However, addresses in header lines are checked only when an ACL requests header -syntax checking. - -.conf syslog@_duplication boolean true -.index syslog||duplicate log lines, suppressing -When Exim is logging to syslog, it writes the log lines for its three -separate logs at different syslog priorities so that they can in principle -be separated on the logging hosts. Some installations do not require this -separation, and in those cases, the duplication of certain log lines is a -nuisance. If \syslog@_duplication\ is set false, only one copy of any -particular log line is written to syslog. For lines that normally go to -both the main log and the reject log, the reject log version (possibly -containing message header lines) is written, at \\LOG@_NOTICE\\ priority. -Lines that normally go to both the main and the panic log are written at -the \\LOG@_ALERT\\ priority. - -.conf syslog@_facility string unset -.index syslog||facility, setting -This option sets the syslog `facility' name, used when Exim is logging to -syslog. The value must be one of the strings `mail', `user', `news', `uucp', -`daemon', or `local\*x*\' where \*x*\ is a digit between 0 and 7. If this -option is unset, `mail' is used. See chapter ~~CHAPlog for details of Exim's -logging. - - -.conf syslog@_processname string "$tt{exim}" -.index syslog||process name, setting -This option sets the syslog `ident' name, used when Exim is logging to syslog. -The value must be no longer than 32 characters. See chapter ~~CHAPlog for -details of Exim's logging. - - -.conf syslog@_timestamp boolean true -.index syslog||timestamps -If \syslog@_timestamp\ is set false, the timestamps on Exim's log lines are -omitted when these lines are sent to syslog. See chapter ~~CHAPlog for -details of Exim's logging. - -.conf system@_filter string$**$ unset -.index filter||system filter -.index system filter||specifying -.index Sieve filter||not available for system filter -This option specifies an Exim filter file that is applied to all messages at -the start of each delivery attempt, before any routing is done. System filters -must be Exim filters; they cannot be Sieve filters. If the system filter -generates any deliveries to files or pipes, or any new mail messages, the -appropriate \system@_filter@_...@_transport\ option(s) must be set, to define -which transports are to be used. Details of this facility are given in chapter -~~CHAPsystemfilter. - -.conf system@_filter@_directory@_transport string$**$ unset -This sets the name of the transport driver that is to be used when the -\save\ command in a system message filter specifies a path ending in `/', -implying delivery of each message into a separate file in some directory. -During the delivery, the variable \$address@_file$\ contains the path name. - -.conf system@_filter@_file@_transport string$**$ unset -.index file||transport for system filter -This sets the name of the transport driver that is to be used when the \save\ -command in a system message filter specifies a path not ending in `/'. During -the delivery, the variable \$address@_file$\ contains the path name. - -.index gid (group id)||system filter -.conf system@_filter@_group string unset -This option is used only when \system@_filter@_user\ is also set. It sets the -gid under which the system filter is run, overriding any gid that is associated -with the user. The value may be numerical or symbolic. - -.conf system@_filter@_pipe@_transport string$**$ unset 7 -.index \%pipe%\ transport||for system filter -This specifies the transport driver that is to be used when a \pipe\ command is -used in a system filter. During the delivery, the variable \$address@_pipe$\ -contains the pipe command. - -.conf system@_filter@_reply@_transport string$**$ unset -.index \%autoreply%\ transport||for system filter -This specifies the transport driver that is to be used when a \mail\ command is -used in a system filter. - -.index uid (user id)||system filter -.conf system@_filter@_user string unset -If this option is not set, the system filter is run in the main Exim delivery -process, as root. When the option is set, the system filter runs in a separate -process, as the given user. Unless the string consists entirely of digits, it -is looked up in the password data. Failure to find the named user causes a -configuration error. The gid is either taken from the password data, or -specified by \system@_filter@_group\. When the uid is specified numerically, -\system@_filter@_group\ is required to be set. - -If the system filter generates any pipe, file, or reply deliveries, the uid -under which the filter is run is used when transporting them, unless a -transport option overrides. -Normally you should set \system@_filter@_user\ if your system filter generates -these kinds of delivery. - -.conf tcp@_nodelay boolean true -.index daemon||\\TCP@_NODELAY\\ on sockets -.index Nagle algorithm -.index \\TCP@_NODELAY\\ on listening sockets -If this option is set false, it stops the Exim daemon setting the -\\TCP@_NODELAY\\ option on its listening sockets. Setting \\TCP@_NODELAY\\ -turns off the `Nagle algorithm', which is a way of improving network -performance in interactive (character-by-character) situations. Turning it off -should improve Exim's performance a bit, so that is what happens by default. -However, it appears that some broken clients cannot cope, and time out. Hence -this option. It affects only those sockets that are set up for listening by the -daemon. Sockets created by the smtp transport for delivering mail always set -\\TCP@_NODELAY\\. - -.conf timeout@_frozen@_after time 0s -.index frozen messages||timing out -.index timeout||frozen messages -If \timeout@_frozen@_after\ is set to a time greater than zero, a frozen -message of any kind that has been on the queue for longer than the given -time is automatically cancelled at the next queue run. If it is a bounce -message, it is just discarded; otherwise, a bounce is sent to the sender, in a -similar manner to cancellation by the \-Mg-\ command line option. If you want -to timeout frozen bounce messages earlier than other kinds of frozen message, -see \ignore@_bounce@_errors@_after\. - -.conf timezone string unset -.index timezone, setting -The value of \timezone\ is used to set the environment variable \\TZ\\ while -running Exim (if it is different on entry). This ensures that all timestamps -created by Exim are in the required timezone. If you want all your timestamps -to be in UTC (aka GMT) you should set -.display asis -timezone = UTC -.endd -The default value is taken from \\TIMEZONE@_DEFAULT\\ in \(Local/Makefile)\, -or, if that is not set, from the value of the TZ environment variable when Exim -is built. If \timezone\ is set to the empty string, either at build or run -time, any existing \\TZ\\ variable is removed from the environment when Exim -runs. This is appropriate behaviour for obtaining wall-clock time on some, but -unfortunately not all, operating systems. - -.conf tls@_advertise@_hosts "host list$**$" unset -.index TLS||advertising -.index encryption||on SMTP connection -.index SMTP||encrypted connection -When Exim is built with support for TLS encrypted connections, the availability -of the \\STARTTLS\\ command to set up an encrypted session is advertised in -response to \\EHLO\\ only to those client hosts that match this option. See -chapter ~~CHAPTLS for details of Exim's support for TLS. - -.conf tls@_certificate string$**$ unset -.index TLS||server certificate, location of -.index certificate||for server, location of -The value of this option is expanded, and must then be the absolute path to a -file which contains the server's certificates. The server's private key is also -assumed to be in this file if \tls@_privatekey\ is unset. See chapter ~~CHAPTLS -for further details. - -\**Note**\: The certificates defined by this option are used only when Exim is -receiving incoming messages as a server. If you want to supply certificates for -use when sending messages as a client, you must set the \tls@_certificate\ -option in the relevant \%smtp%\ transport. - -.conf tls@_crl string$**$ unset -.index TLS||server certificate revocation list -.index certificate||revocation list for server -This option specifies a certificate revocation list. The expanded value must -be the name of a file that contains a CRL in PEM format. - -.conf tls@_dhparam string$**$ unset -.index TLS||D-H parameters for server -The value of this option is expanded, and must then be the absolute path to -a file which contains the server's DH parameter values. -This is used only for OpenSSL. When Exim is linked with GnuTLS, this option is -ignored. See section ~~SECTopenvsgnu for further details. - -.em -.conf tls@_on@_connect@_ports "string list" unset -This option specifies a list of incoming SSMTP (aka SMTPS) ports that should -operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately -set up without waiting for the client to issue a \\STARTTLS\\ command. For -further details, see section ~~SECTsupobssmt. -.nem - -.conf tls@_privatekey string$**$ unset -.index TLS||server private key, location of -The value of this option is expanded, and must then be the absolute path to a -file which contains the server's private key. If this option is unset, the -private key is assumed to be in the same file as the server's certificates. See -chapter ~~CHAPTLS for further details. - -.conf tls@_remember@_esmtp boolean false -.index TLS||esmtp state, remembering -.index TLS||broken clients -If this option is set true, Exim violates the RFCs by remembering that it is in -`esmtp' state after successfully negotiating a TLS session. This provides -support for broken clients that fail to send a new \\EHLO\\ after starting a -TLS session. - -.conf tls@_require@_ciphers string$**$ unset -.index TLS||requiring specific ciphers -.index cipher||requiring specific -This option controls which ciphers can be used for incoming TLS connections. -The \%smtp%\ transport has an option of the same name for controlling outgoing -connections. This option is expanded for each connection, so can be varied for -different clients if required. The value of this option must be a list of -permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control -in somewhat different ways. -.em -If GnuTLS is being used, the client controls the preference order of the -available ciphers. -.nem -Details are given in sections ~~SECTreqciphssl and ~~SECTreqciphgnu. - -.conf tls@_try@_verify@_hosts "host list$**$" unset -.index TLS||client certificate verification -.index certificate||verification of client -See \tls@_verify@_hosts\ below. - -.conf tls@_verify@_certificates string$**$ unset -.index TLS||client certificate verification -.index certificate||verification of client -The value of this option is expanded, and must then be the absolute path to -a file containing permitted certificates for clients that -match \tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\. Alternatively, if you -are using OpenSSL, you can set \tls@_verify@_certificates\ to the name of a -directory containing certificate files. This does not work with GnuTLS; the -option must be set to the name of a single file if you are using GnuTLS. - -.conf tls@_verify@_hosts "host list$**$" unset -.index TLS||client certificate verification -.index certificate||verification of client -This option, along with \tls@_try@_verify@_hosts\, controls the checking of -certificates from clients. -The expected certificates are defined by \tls@_verify@_certificates\, which -must be set. A configuration error occurs if either \tls@_verify@_hosts\ or -\tls@_try@_verify@_hosts\ is set and \tls@_verify@_certificates\ is not set. - -Any client that matches \tls@_verify@_hosts\ is constrained by -\tls@_verify@_certificates\. The client must present one of the listed -certificates. If it does not, the connection is aborted. - -A weaker form of checking is provided by \tls@_try@_verify@_hosts\. If a client -matches this option (but not \tls@_verify@_hosts\), Exim requests a -certificate and checks it against \tls@_verify@_certificates\, but does not -abort the connection if there is no certificate or if it does not match. This -state can be detected in an ACL, which makes it possible to implement policies -such as `accept for relay only if a verified certificate has been received, but -accept for local delivery if encrypted, even without a verified certificate'. - -Client hosts that match neither of these lists are not asked to present -certificates. - -.conf trusted@_groups "string list" unset -.index trusted group -.index group||trusted -If this option is set, any process that is running in one of the listed groups, -or which has one of them as a supplementary group, is trusted. -The groups can be specified numerically or by name. -See section ~~SECTtrustedadmin for details of what trusted callers are -permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only -root and the Exim user are trusted. - -.conf trusted@_users "string list" unset -.index trusted user -.index user||trusted -If this option is set, any process that is running as one of the listed users -is trusted. -The users can be specified numerically or by name. -See section ~~SECTtrustedadmin for details of what trusted callers are -permitted to do. If neither \trusted@_groups\ nor \trusted@_users\ is set, only -root and the Exim user are trusted. - -.index uid (user id)||unknown caller -.conf unknown@_login string$**$ unset -This is a specialized feature for use in unusual configurations. By default, if -the uid of the caller of Exim cannot be looked up using \*getpwuid()*\, Exim -gives up. The \unknown@_login\ option can be used to set a login name to be -used in this circumstance. It is expanded, so values like \user@$caller@_uid\ -can be set. When \unknown@_login\ is used, the value of \unknown@_username\ is -used for the user's real name (gecos field), unless this has been set by the -\-F-\ option. - -.conf unknown@_username string unset -See \unknown@_login\. - -.conf untrusted@_set@_sender "address list$**$" unset -.index trusted user -.index sender||setting by untrusted user -.index untrusted user, setting sender -.index user||untrusted setting sender -.index envelope sender -When an untrusted user submits a message to Exim using the standard input, Exim -normally creates an envelope sender address from the user's login and the -default qualification domain. Data from the \-f-\ option (for setting envelope -senders on non-SMTP messages) or the SMTP \\MAIL\\ command (if \-bs-\ or \-bS-\ -is used) is ignored. - -However, untrusted users are permitted to set an empty envelope sender address, -to declare that a message should never generate any bounces. For example: -.display asis -exim -f '<>' user@domain.example -.endd -The \untrusted@_set@_sender\ option allows you to permit untrusted users to set -other envelope sender addresses in a controlled way. When it is set, untrusted -users are allowed to set envelope sender addresses that match any of the -patterns in the list. Like all address lists, the string is expanded. The -identity of the user is in \$sender@_ident$\, so you can, for example, restrict -users to setting senders that start with their login ids -followed by a hyphen -by a setting like this: -.display asis -untrusted_set_sender = ^$sender_ident- -.endd -If you want to allow untrusted users to set envelope sender addresses without -restriction, you can use -.display asis -untrusted_set_sender = * -.endd -The \untrusted@_set@_sender\ option applies to all forms of local input, but -only to the setting of the envelope sender. It does not permit untrusted users -to use the other options which trusted user can use to override message -parameters. Furthermore, it does not stop Exim from removing an existing -::Sender:: header in the message, or from adding a ::Sender:: header if -necessary. See \local__sender__retain\ and \local@_from@_check\ for ways of -overriding these actions. The handling of the ::Sender:: header is also -described in section ~~SECTthesenhea. - -The log line for a message's arrival shows the envelope sender following `<='. -For local messages, the user's login always follows, after `U='. In \-bp-\ -displays, and in the Exim monitor, if an untrusted user sets an envelope sender -address, the user's login is shown in parentheses after the sender address. - -.conf uucp@_from@_pattern string "see below" -.index `From' line -.index UUCP||`From' line -Some applications that pass messages to an MTA via a command line interface use -an initial line starting with `From' to pass the envelope sender. In -particular, this is used by UUCP software. Exim recognizes such a line by means -of a regular expression that is set in \uucp@_from@_pattern\. When the pattern -matches, the sender address is constructed by expanding the contents of -\uucp@_from@_sender\, provided that the caller of Exim is a trusted user. The -default pattern recognizes lines in the following two forms: -.display asis - From ph10 Fri Jan 5 12:35 GMT 1996 - From ph10 Fri, 7 Jan 97 14:00:00 GMT -.endd -The pattern can be seen by running -.display asis -exim -bP uucp_from_pattern -.endd -It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit -year in the second case. The first word after `From' is matched in the regular -expression by a parenthesized subpattern. The default value for -\uucp@_from@_sender\ is `$1', which therefore just uses this first word (`ph10' -in the example above) as the message's sender. See also -\ignore@_fromline@_hosts\. - -.conf uucp@_from@_sender string$**$ "$tt{@$1}" -See \uucp@_from@_pattern\ above. - -.conf warn@_message@_file string unset -.index warning of delay||customizing the message -.index customizing||warning message -This option defines a template file containing paragraphs of text to be used -for constructing the warning message which is sent by Exim when a message has -been on the queue for a specified amount of time, as specified by -\delay@_warning\. Details of the file's contents are given in chapter -~~CHAPemsgcust. See also \bounce@_message@_file\. - -.conf write@_rejectlog boolean true -.index reject log||disabling -If this option is set false, Exim no longer writes anything to the reject log. -See chapter ~~CHAPlog for details of what Exim writes to its logs. - -.endconf - - - -. -. -. -. -. ============================================================================ -.chapter Generic options for routers -.rset CHAProutergeneric "~~chapter" -.set runningfoot "generic router options" -.index options||generic, for routers -.index generic options||router - -This chapter describes the generic options that apply to all routers, -identifying those that are preconditions. For a general description of how a -router operates, see sections ~~SECTrunindrou and ~~SECTrouprecon. The latter -specifies the order in which the preconditions are tested. The order of -expansion of the options that provide data for a transport is: \errors@_to\, -\headers@_add\, \headers@_remove\, \transport\. - -.startconf routers - -.conf address@_data string$**$ unset -.index router||data attached to address -The string is expanded just before the router is run, that is, after all the -precondition tests have succeeded. If the expansion is forced to fail, the -router declines. Other expansion failures cause delivery of the address to be -deferred. - -When the expansion succeeds, the value is retained with the address, and can be -accessed using the variable \$address@_data$\ in the current router, subsequent -routers, and the eventual transport. - -\**Warning**\: if the current or any subsequent router is a \%redirect%\ router -that runs a user's filter file, the contents of \$address@_data$\ are -accessible in the filter. This is not normally a problem, because such data is -usually either not confidential or it `belongs' to the current user, but if you -do put confidential data into \$address@_data$\ you need to remember this -point. - -Even if the router declines or passes, the value of \$address@_data$\ remains -with the address, though it can be changed by another \address@_data\ setting -on a subsequent router. If a router generates child addresses, the value of -\$address@_data$\ propagates to them. This also applies to the special kind of -`child' that is generated by a router with the \unseen\ option. - -The idea of \address@_data\ is that you can use it to look up a lot of data for -the address once, and then pick out parts of the data later. For example, you -could use a single LDAP lookup to return a string of the form -.display asis -uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward -.endd -In the transport you could pick out the mailbox by a setting such as -.display asis -file = ${extract{mailbox}{$address_data}} -.endd -This makes the configuration file less messy, and also reduces the number of -lookups (though Exim does cache lookups). - -The \address@_data\ facility is also useful as a means of passing information -from one router to another, and from a router to a transport. In addition, if -.em -\$address@_data$\ is set by a router when verifying a recipient address from an -ACL, it remains available for use in the rest of the ACL statement. After -verifying a sender, the value is transferred to \$sender@_address@_data$\. -.nem - - -.conf address@_test "boolean (precondition)" true -.index \-bt-\ option -.index router||skipping when address testing -If this option is set false, the router is skipped when routing is being tested -by means of the \-bt-\ command line option. This can be a convenience when your -first router sends messages to an external scanner, because it saves you -having to set the `already scanned' indicator when testing real address -routing. - - -.conf cannot@_route@_message string$**$ unset -.index router||customizing `cannot route' message -.index customizing||`cannot route' message -This option specifies a text message that is used when an address cannot be -routed because Exim has run out of routers. The default message is `Unrouteable -address'. This option is useful only on routers that have \more\ set false, or -on the very last router in a configuration, because the value that is used is -taken from the last router that inspects an address. For example, using the -default configuration, you could put: -.display asis -cannot_route_message = Remote domain not found in DNS -.endd -on the first (\%dnslookup%\) router, and -.display asis -cannot_route_message = Unknown local user -.endd -on the final router that checks for local users. If string expansion fails, the -default message is used. -Unless the expansion failure was explicitly forced, a message about the failure -is written to the main and panic logs, in addition to the normal message about -the routing failure. - -.conf caseful@_local@_part boolean false -.index case of local parts -.index router||case of local parts -By default, routers handle the local parts of addresses in a case-insensitive -manner, though the actual case is preserved for transmission with the message. -If you want the case of letters to be significant in a router, you must set -this option true. For individual router options that contain address or local -part lists (for example, \local@_parts\), case-sensitive matching can be turned -on by `+caseful' as a list item. See section ~~SECTcasletadd for more details. - -.em -The value of the \$local@_part$\ variable is forced to lower case while a -router is running unless \caseful@_local@_part\ is set. When a router assigns -an address to a transport, the value of \$local@_part$\ when the transport runs -is the same as it was in the router. Similarly, when a router generates child -addresses by aliasing or forwarding, the values of \$original@_local@_part$\ -and \$parent@_local@_part$\ are those that were used by the redirecting router. - -This option applies to the processing of an address by a router. When a -recipient address is being processed in an ACL, there is a separate \control\ -modifier that can be used to specify case-sensitive processing within the ACL -(see section ~~SECTcontrols). -.nem - -.conf check@_local@_user "boolean (precondition)" false -.index local user, checking in router -.index router||checking for local user -.index \(/etc/passwd)\ -When this option is true, Exim checks that the local part of the recipient -address (with affixes removed if relevant) is the name of an account on the -local system. The check is done by calling the \*getpwnam()*\ function rather -than trying to read \(/etc/passwd)\ directly. This means that other methods of -holding password data (such as NIS) are supported. If the local part is a local -user, \$home$\ is set from the password data, and can be tested in other -preconditions that are evaluated after this one (the order of evaluation is -given in section ~~SECTrouprecon). However, the value of \$home$\ can be -overridden by \router@_home@_directory\. If the local part is not a local user, -the router is skipped. - -If you want to check that the local part is either the name of a local user -or matches something else, you cannot combine \check@_local@_user\ with a -setting of \local@_parts\, because that specifies the logical \*and*\ of the -two conditions. However, you can use a \%passwd%\ lookup in a \local@_parts\ -setting to achieve this. For example: -.display asis -local_parts = passwd;$local_part : lsearch;/etc/other/users -.endd -Note, however, that the side effects of \check@_local@_user\ (such as setting -up a home directory) do not occur when a \%passwd%\ lookup is used in a -\local@_parts\ (or any other) precondition. - - -.conf condition "string$**$ (precondition)" unset -.index router||customized precondition -This option specifies a general precondition test that has to succeed for the -router to be called. The \condition\ option is the last precondition to be -evaluated (see section ~~SECTrouprecon). The string is expanded, and if the -result is a forced failure, or an empty string, or one of the strings `0' or -`no' or `false' (checked without regard to the case of the letters), the router -is skipped, and the address is offered to the next one. -.em -If the result is any other value, the router is run (as this is the last -precondition to be evaluated, all the other preconditions must be true). - -The \condition\ option provides a means of applying custom conditions to the -running of routers. Note that in the case of a simple conditional expansion, -the default expansion values are exactly what is wanted. For example: -.display asis -condition = ${if >{$message_age}{600}} -.endd -Because of the default behaviour of the string expansion, this is equivalent to -.display asis -condition = ${if >{$message_age}{600}{true}{}} -.endd -.nem - -If the expansion fails (other than forced failure) delivery is deferred. Some -of the other precondition options are common special cases that could in fact -be specified using \condition\. - - -.conf debug@_print string$**$ unset -.index testing||variables in drivers -If this option is set and debugging is enabled (see the \-d-\ command line -option), the string is expanded and included in the debugging output. -If expansion of the string fails, the error message is written to the debugging -output, and Exim carries on processing. -This option is provided to help with checking out the values of variables and -so on when debugging router configurations. For example, if a \condition\ -option appears not to be working, \debug@_print\ can be used to output the -variables it references. The output happens after checks for \domains\, -\local@_parts\, and \check@_local@_user\ but before any other preconditions are -tested. A newline is added to the text if it does not end with one. - - -.conf disable@_logging boolean false -If this option is set true, nothing is logged for any routing errors -or for any deliveries caused by this router. You should not set this option -unless you really, really know what you are doing. See also the generic -transport option of the same name. - -.conf domains "domain list$**$ (precondition)" unset -.index router||restricting to specific domains -If this option is set, the router is skipped unless the current domain matches -the list. If the match is achieved by means of a file lookup, the data that the -lookup returned for the domain is placed in \$domain@_data$\ for use in string -expansions of the driver's private options. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - - -.conf driver string unset -This option must always be set. It specifies which of the available routers is -to be used. - - -.conf errors@_to string$**$ unset -.index envelope sender -.index router||changing address for errors -If a router successfully handles an address, it may queue the address for -delivery or it may generate child addresses. In both cases, if there is a -delivery problem during later processing, the resulting bounce message is sent -to the address that results from expanding this string, provided that the -address verifies successfully. -\errors@_to\ is expanded before \headers@_add\, \headers@_remove\, and -\transport\. - -If the option is unset, or the expansion is forced to fail, or the result of -the expansion fails to verify, the errors address associated with the incoming -address is used. At top level, this is the envelope sender. A non-forced -expansion failure causes delivery to be deferred. - -If an address for which \errors@_to\ has been set ends up being delivered over -SMTP, the envelope sender for that delivery is the \errors@_to\ value, so that -any bounces that are generated by other MTAs on the delivery route are also -sent there. The most common use of \errors@_to\ is probably to direct mailing -list bounces to the manager of the list, as described in section -~~SECTmailinglists. - -The \errors@_to\ setting associated with an address can be overridden if it -subsequently passes through other routers that have their own \errors@_to\ -settings, -or if it is delivered by a transport with a \return@_path\ setting. - -You can set \errors@_to\ to the empty string by either of these settings: -.display asis -errors_to = -errors_to = "" -.endd -An expansion item that yields an empty string has the same effect. If you do -this, a locally detected delivery error for addresses processed by this router -no longer gives rise to a bounce message; the error is discarded. If the -address is delivered to a remote host, the return path is set to \"<>"\, unless -overridden by the \return@_path\ option on the transport. - -If for some reason you want to discard local errors, but use a non-empty -\\MAIL\\ command for remote delivery, you can preserve the original return -path in \$address@_data$\ in the router, and reinstate it in the transport by -setting \return@_path\. - - -.conf expn "boolean (precondition)" true -.index address||testing -.index testing||addresses -.index \\EXPN\\||router skipping -.index router||skipping for \\EXPN\\ -If this option is turned off, the router is skipped when testing an address -as a result of processing an SMTP \\EXPN\\ command. You might, for example, -want to turn it off on a router for users' \(.forward)\ files, while leaving it -on for the system alias file. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - -The use of the SMTP \\EXPN\\ command is controlled by an ACL (see chapter -~~CHAPACL). When Exim is running an \\EXPN\\ command, it is similar to testing -an address with \-bt-\. Compare \\VRFY\\, whose counterpart is \-bv-\. - - -.conf fail@_verify boolean false -.index router||forcing verification failure -Setting this option has the effect of setting both \fail@_verify@_sender\ and -\fail@_verify@_recipient\ to the same value. - - -.conf fail@_verify@_recipient boolean false -If this option is true and an address is accepted by this router when -verifying a recipient, verification fails. - - -.conf fail@_verify@_sender boolean false -If this option is true and an address is accepted by this router when -verifying a sender, verification fails. - - -.conf fallback@_hosts "string list" unset -.index router||fallback hosts -.index fallback||hosts specified on router -String expansion is not applied to this option. The argument must be a -colon-separated list of host names or IP addresses. If a router queues an -address for a remote transport, this host list is associated with the address, -and used instead of the transport's fallback host list. If \hosts@_randomize\ -is set on the transport, the order of the list is randomized for each use. See -the \fallback@_hosts\ option of the \%smtp%\ transport for further details. - -.conf group string$**$ "see below" -.index gid (group id)||local delivery -.index local transports||uid and gid -.index transport||local -.index router||setting group -When a router queues an address for a transport, and the transport does not -specify a group, the group given here is used when running the delivery -process. -The group may be specified numerically or by name. If expansion fails, the -error is logged and delivery is deferred. -The default is unset, unless \check@_local@_user\ is set, when the default -is taken from the password information. See also \initgroups\ and \user\ and -the discussion in chapter ~~CHAPenvironment. - - -.conf headers@_add string$**$ unset -.index header lines||adding -.index router||adding header lines -.em -This option specifies a string of text that is expanded at routing time, and -associated with any addresses that are accepted by the router. However, this -option has no effect when an address is just being verified. The way in which -the text is used to add header lines at transport time is described in section -~~SECTheadersaddrem. - -The \headers@_add\ option is expanded after \errors@_to\, but before -\headers@_remove\ and \transport\. If the expanded string is empty, or if the -expansion is forced to fail, the option has no effect. Other expansion failures -are treated as configuration errors. - -\**Warning**\: The \headers@_add\ option cannot be used for a \%redirect%\ -router that has the \one@_time\ option set. -.nem - - -.conf headers@_remove string$**$ unset -.index header lines||removing -.index router||removing header lines -.em -This option specifies a string of text that is expanded at routing time, and -associated with any addresses that are accepted by the router. However, this -option has no effect when an address is just being verified. The way in which -the text is used to remove header lines at transport time is described in -section ~~SECTheadersaddrem. - -The \headers@_remove\ option is expanded after \errors@_to\ and \headers@_add\, -but before \transport\. If the expansion is forced to fail, the option has no -effect. Other expansion failures are treated as configuration errors. - -\**Warning**\: The \headers@_remove\ option cannot be used for a \%redirect%\ -router that has the \one@_time\ option set. -.nem - - -.conf ignore@_target@_hosts "host list$**$" unset -.index IP address||discarding -.index router||discarding IP addresses -Although this option is a host list, it should normally contain IP address -entries rather than names. If any host that is looked up by the router has an -IP address that matches an item in this list, Exim behaves as if that IP -address did not exist. This option allows you to cope with rogue DNS entries -like -.display asis -remote.domain.example. A 127.0.0.1 -.endd -by setting -.display asis -ignore_target_hosts = 127.0.0.1 -.endd -on the relevant router. If all the hosts found by a \%dnslookup%\ router are -discarded in this way, the router declines. In a conventional configuration, an -attempt to mail to such a domain would normally provoke the `unrouteable -domain' error, and an attempt to verify an address in the domain would fail. - -Similarly, if \ignore@_target@_hosts\ is set on an \%ipliteral%\ router, the -router declines if presented with one of the listed addresses. - -This option may also be useful for ignoring link-local and site-local IPv6 -addresses. Because, like all host lists, the value of \ignore@_target@_hosts\ -is expanded before use as a list, it is possible to make it dependent on the -domain that is being routed. -.em -During its expansion, \$host@_address$\ is set to the IP address that is being -checked. -.nem - - - -.index additional groups -.index groups, additional -.index local transports||uid and gid -.index transport||local -.conf initgroups boolean false -If the router queues an address for a transport, and this option is true, and -the uid supplied by the router is not overridden by the transport, the -\*initgroups()*\ function is called when running the transport to ensure that -any additional groups associated with the uid are set up. See also \group\ and -\user\ and the discussion in chapter ~~CHAPenvironment. - - -.conf local@_part@_prefix "string list (precondition)" unset -.index router||prefix for local part -.index prefix||for local part, used in router -If this option is set, the router is skipped unless the local part -starts with one of the given strings, or \local@_part@_prefix@_optional\ is -true. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - -The list is scanned from left to right, and the first prefix that matches is -used. A limited form of wildcard is available; if the prefix begins with an -asterisk, it matches the longest possible sequence of arbitrary characters at -the start of the local part. An asterisk should therefore always be followed by -some character that does not occur in normal local parts. -.index multiple mailboxes -.index mailbox||multiple -Wildcarding can be used to set up multiple user mailboxes, as described in -section ~~SECTmulbox. - -During the testing of the \local@_parts\ option, and while the router is -running, the prefix is removed from the local part, and is available in the -expansion variable \$local@_part@_prefix$\. If the router accepts the address, -this remains true during subsequent delivery. -In particular, the local part that is transmitted in the \\RCPT\\ command -for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. This -behaviour can be overridden by setting \rcpt@_include@_affixes\ true on the -relevant transport. - -The prefix facility is commonly used to handle local parts of the form -\owner-something\. Another common use is to support local parts of the form -\real-username\ to bypass a user's \(.forward)\ file -- helpful when trying to -tell a user their forwarding is broken -- by placing a router like this one -immediately before the router that handles \(.forward)\ files: -.display asis -real_localuser: - driver = accept - local_part_prefix = real- - check_local_user - transport = local_delivery -.endd -If both \local@_part@_prefix\ and \local@_part@_suffix\ are set for a router, -both conditions must be met if not optional. Care must be taken if wildcards -are used in both a prefix and a suffix on the same router. Different -separator characters must be used to avoid ambiguity. - -.conf local@_part@_prefix@_optional boolean false -See \local@_part@_prefix\ above. - - -.conf local@_part@_suffix "string list (precondition)" unset -.index router||suffix for local part -.index suffix for local part, used in router -This option operates in the same way as \local@_part@_prefix\, except that the -local part must end (rather than start) with the given string, the -\local@_part@_suffix@_optional\ option determines whether the suffix is -mandatory, and the wildcard $*$ character, if present, must be the last -character of the suffix. This option facility is commonly used to handle local -parts of the form \something-request\ and multiple user mailboxes of the form -\username-foo\. - -.conf local@_part@_suffix@_optional boolean false -See \local@_part@_suffix\ above. - - -.conf local@_parts "local part list$**$ (precondition)" unset -.index router||restricting to specific local parts -.index local part||checking in router -The router is run only if the local part of the address matches the list. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated, and -section ~~SECTlocparlis for a discussion of local part lists. Because the -string is expanded, it is possible to make it depend on the domain, for -example: -.display asis -local_parts = dbm;/usr/local/specials/$domain -.endd -If the match is achieved by a lookup, the data that the lookup returned -for the local part is placed in the variable \$local@_part@_data$\ for use in -expansions of the router's private options. You might use this option, for -example, if you have a large number of local virtual domains, and you want to -send all postmaster mail to the same place without having to set up an alias in -each virtual domain: -.display asis -postmaster: - driver = redirect - local_parts = postmaster - data = postmaster@real.domain.example -.endd - - -.conf log@_as@_local boolean "see below" -.index log||delivery line -.index delivery||log line format -Exim has two logging styles for delivery, the idea being to make local -deliveries stand out more visibly from remote ones. In the `local' style, the -recipient address is given just as the local part, without a domain. The use of -this style is controlled by this option. It defaults to true for the \%accept%\ -router, and false for all the others. - - -.conf more boolean$**$ true -The result of string expansion for this option must be a valid boolean value, -that is, one of the strings `yes', `no', `true', or `false'. Any other result -causes an error, and delivery is deferred. If the expansion is forced to fail, -the default value for the option (true) is used. Other failures cause delivery -to be deferred. - -If this option is set false, and the router is run, but declines to handle the -address, no further routers are tried, routing fails, and the address is -bounced. -.index \self\ option -However, if the router explicitly passes an address to the following router by -means of the setting -.display asis -self = pass -.endd -or otherwise, the setting of \more\ is ignored. Also, the setting of \more\ -does not affect the behaviour if one of the precondition tests fails. In that -case, the address is always passed to the next router. - - -.conf pass@_on@_timeout boolean false -.index timeout||of router -.index router||timeout -If a router times out during a host lookup, it normally causes deferral of the -address. If \pass@_on@_timeout\ is set, the address is passed on to the next -router, overriding \no@_more\. This may be helpful for systems that are -intermittently connected to the Internet, or those that want to pass to a smart -host any messages that cannot immediately be delivered. - -There are occasional other temporary errors that can occur while doing DNS -lookups. They are treated in the same way as a timeout, and this option -applies to all of them. - - -.conf pass@_router string unset -.index router||go to after `pass' -When a router returns `pass', the address is normally handed on to the next -router in sequence. This can be changed by setting \pass@_router\ to the name -of another router. However (unlike \redirect@_router\) the named router must be -below the current router, to avoid loops. Note that this option applies only to -the special case of `pass'. It does not apply when a router returns `decline'. - - -.conf redirect@_router string unset -.index router||start at after redirection -Sometimes an administrator knows that it is pointless to reprocess addresses -generated from alias or forward files with the same router again. For -example, if an alias file translates real names into login ids there is no -point searching the alias file a second time, especially if it is a large file. - -The \redirect@_router\ option can be set to the name of any router instance. It -causes the routing of any generated addresses to start at the named router -instead of at the first router. This option has no effect if the router in -which it is set does not generate new addresses. - - -.conf require@_files "string list$**$ (precondition)" unset -.index file||requiring for router -.index router||requiring file existence -This option provides a general mechanism for predicating the running of a -router on the existence or non-existence of certain files or directories. -Before running a router, as one of its precondition tests, Exim works its way -through the \require@_files\ list, expanding each item separately. - -Because the list is split before expansion, any colons in expansion items must -be doubled, or the facility for using a different list separator must be used. -If any expansion is forced to fail, the item is ignored. Other expansion -failures cause routing of the address to be deferred. - -If any expanded string is empty, it is ignored. Otherwise, except as described -below, each string must be a fully qualified file path, optionally preceded by -`!'. The paths are passed to the \*stat()*\ function to test for the existence -of the files or directories. The router is skipped if any paths not preceded by -`!' do not exist, or if any paths preceded by `!' do exist. - -.index NFS -If \*stat()*\ cannot determine whether a file exists or not, delivery of -the message is deferred. This can happen when NFS-mounted filesystems are -unavailable. - -This option is checked after the \domains\, \local@_parts\, and \senders\ -options, so you cannot use it to check for the existence of a file in which to -look up a domain, local part, or sender. (See section ~~SECTrouprecon for a -full list of the order in which preconditions are evaluated.) However, as -these options are all expanded, you can use the \exists\ expansion condition to -make such tests. The \require@_files\ option is intended for checking files -that the router may be going to use internally, or which are needed by a -transport (for example \(.procmailrc)\). - -During delivery, the \*stat()*\ function is run as root, but there is a -facility for some checking of the accessibility of a file by another user. -This is not a proper permissions check, but just a `rough' check that -operates as follows: - -If an item in a \require@_files\ list does not contain any forward slash -characters, it is taken to be the user (and optional group, separated by a -comma) to be checked for subsequent files in the list. If no group is specified -but the user is specified symbolically, the gid associated with the uid is -used. For example: -.display asis -require_files = mail:/some/file -require_files = $local_part:$home/.procmailrc -.endd -If a user or group name in a \require@_files\ list does not exist, the -\require@_files\ condition fails. - -Exim performs the check by scanning along the components of the file path, and -checking the access for the given uid and gid. It checks for `x' access on -directories, and `r' access on the final file. Note that this means that file -access control lists, if the operating system has them, are ignored. - -\**Warning 1**\: When the router is being run to verify addresses for an -incoming SMTP message, Exim is not running as root, but under its own uid. This -may affect the result of a \require@_files\ check. In particular, \*stat()*\ -may yield the error \\EACCES\\ (`Permission denied'). This means that the Exim -user is not permitted to read one of the directories on the file's path. - -\**Warning 2**\: Even when Exim is running as root while delivering a message, -\*stat()*\ can yield \\EACCES\\ for a file in an NFS directory that is mounted -without root access. -.em -In this case, if a check for access by a particular user is requested, Exim -creates a subprocess that runs as that user, and tries the check again in that -process. - -The default action for handling an unresolved \\EACCES\\ is to consider it to -be caused by a configuration error, -.nem -and routing is deferred because the existence or non-existence of the file -cannot be determined. However, in some circumstances it may be desirable to -treat this condition as if the file did not exist. If the file name (or the -exclamation mark that precedes the file name for non-existence) is preceded by -a plus sign, the \\EACCES\\ error is treated as if the file did not exist. For -example: -.display asis -require_files = +/some/file -.endd -If the router is not an essential part of verification (for example, it -handles users' \(.forward)\ files), another solution is to set the \verify\ -option false so that the router is skipped when verifying. - - -.conf retry@_use@_local@_part boolean "see below" -.index hints database||retry keys -.index local part||in retry keys -When a delivery suffers a temporary routing failure, a retry record is created -in Exim's hints database. For addresses whose routing depends only on the -domain, the key for the retry record should not involve the local part, but for -other addresses, both the domain and the local part should be included. -Usually, remote routing is of the former kind, and local routing is of the -latter kind. - -This option controls whether the local part is used to form the key for retry -hints for addresses that suffer temporary errors while being handled by this -router. The default value is true for any router that has \check@_local@_user\ -set, and false otherwise. Note that this option does not apply to hints keys -for transport delays; they are controlled by a generic transport option of the -same name. - -The setting of \retry@_use@_local@_part\ applies only to the router on which it -appears. If the router generates child addresses, they are routed -independently; this setting does not become attached to them. - - -.conf router@_home@_directory string$**$ unset -.index router||home directory for -.index home directory||for router -This option sets a home directory for use while the router is running. (Compare -\transport__home@_directory\, which sets a home directory for later -transporting.) In particular, if used on a \%redirect%\ router, this option -sets a value for \$home$\ while a filter is running. The value is expanded; -forced expansion failure causes the option to be ignored -- other failures -cause the router to defer. - -Expansion of \router@_home@_directory\ happens immediately after the -\check@_local@_user\ test (if configured), before any further expansions take -place. -(See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated.) -While the router is running, \router__home@_directory\ overrides the value of -\$home$\ that came from \check@_local@_user\. - -When a router accepts an address and routes it to a transport (including the -cases when a redirect router generates a pipe, file, or autoreply delivery), -the home directory setting for the transport is taken from the first of these -values that is set: -.numberpars $. -The \home@_directory\ option on the transport; -.nextp -The \transport@_home@_directory\ option on the router; -.nextp -The password data if \check@_local@_user\ is set on the router; -.nextp -The \router@_home@_directory\ option on the router. -.endp -In other words, \router@_home@_directory\ overrides the password data for the -router, but not for the transport. - - -.conf self string "freeze" -.index MX record||pointing to local host -.index local host||MX pointing to -This option applies to those routers that use a recipient address to find a -list of remote hosts. Currently, these are the \%dnslookup%\, \%ipliteral%\, -and \%manualroute%\ routers. -Certain configurations of the \%queryprogram%\ router can also specify a list -of remote hosts. -Usually such routers are configured to send the message to a remote host via an -\%smtp%\ transport. The \self\ option specifies what happens when the first -host on the list turns out to be the local host. -The way in which Exim checks for the local host is described in section -~~SECTreclocipadd. - -Normally this situation indicates either an error in Exim's configuration (for -example, the router should be configured not to process this domain), or an -error in the DNS (for example, the MX should not point to this host). For this -reason, the default action is to log the incident, defer the address, and -freeze the message. The following alternatives are provided for use in special -cases: -.numberpars $. -\defer\ -.newline -Delivery of the message is tried again later, but the message is not frozen. -.nextp -\reroute: <<domain>>\ -.newline -The domain is changed to the given domain, and the address is passed back to -be reprocessed by the routers. No rewriting of headers takes place. This -behaviour is essentially a redirection. -.nextp -\reroute: rewrite: <<domain>>\ -.newline -The domain is changed to the given domain, and the address is passed back to be -reprocessed by the routers. Any headers that contain the original domain are -rewritten. -.nextp -\pass\ -.newline -The router passes the address to the next router, or to the router named in the -\pass@_router\ option if it is set. -.index \more\ option -This overrides \no@_more\. - -During subsequent routing and delivery, the variable -\$self@_hostname$\ contains the name of the local host that the router -encountered. This can be used to distinguish between different cases for hosts -with multiple names. The combination -.display asis -self = pass -no_more -.endd -ensures that only those addresses that routed to the local host are passed on. -Without \no@_more\, addresses that were declined for other reasons would also -be passed to the next router. -.nextp -\fail\ -.newline -Delivery fails and an error report is generated. -.nextp -\send\ -.newline -.index local host||sending to -The anomaly is ignored and the address is queued for the transport. This -setting should be used with extreme caution. For an \%smtp%\ transport, it makes -sense only in cases where the program that is listening on the SMTP port is not -this version of Exim. That is, it must be some other MTA, or Exim with a -different configuration file that handles the domain in another way. -.endp - -.conf senders "address list$**$ (precondition)" unset -.index router||checking senders -If this option is set, the router is skipped unless the message's sender -address matches something on the list. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - -There are issues concerning verification when the running of routers is -dependent on the sender. When Exim is verifying the address in an \errors@_to\ -setting, it sets the sender to the null string. When using the \-bt-\ option to -check a configuration file, it is necessary also to use the \-f-\ option to set -an appropriate sender. For incoming mail, the sender is unset when verifying -the sender, but is available when verifying any recipients. If the SMTP -\\VRFY\\ command is enabled, it must be used after \\MAIL\\ if the sender -address matters. - -.conf translate@_ip@_address string$**$ unset -.index IP address||translating -.index packet radio -.index router||IP address translation -There exist some rare networking situations (for example, packet radio) where -it is helpful to be able to translate IP addresses generated by normal routing -mechanisms into other IP addresses, thus performing a kind of manual IP -routing. This should be done only if the normal IP routing of the TCP/IP stack -is inadequate or broken. Because this is an extremely uncommon requirement, the -code to support this option is not included in the Exim binary unless -\\SUPPORT__TRANSLATE__IP__ADDRESS\\=yes is set in \(Local/Makefile)\. - -The \translate@_ip@_address\ string is expanded for every IP address generated -by the router, with the generated address set in \$host@_address$\. If the -expansion is forced to fail, no action is taken. -For any other expansion error, delivery of the message is deferred. -If the result of the expansion is an IP address, that replaces the original -address; otherwise the result is assumed to be a host name -- this is looked up -using \*gethostbyname()*\ (or \*getipnodebyname()*\ when available) to produce -one or more replacement IP addresses. For example, to subvert all IP addresses -in some specific networks, this could be added to a router: -.display -$smc{translate@_ip@_address = @\ - @$@{lookup@{@$@{mask:@$host@_address/26@}@}lsearch@{/some/file@}@{@$value@}fail@}} -.endd -The file would contain lines like -.display asis -10.2.3.128/26 some.host -10.8.4.34/26 10.44.8.15 -.endd -You should not make use of this facility unless you really understand what you -are doing. - - -.conf transport string$**$ unset -This option specifies the transport to be used when a router accepts an address -and sets it up for delivery. A transport is never needed if a router is used -only for verification. The value of the option is expanded at routing time, -after the expansion of \errors@_to\, \headers@_add\, and \headers@_remove\, and -result must be the name of one of the configured transports. If it is not, -delivery is deferred. - -The \transport\ option is not used by the \%redirect%\ router, but it does have -some private options that set up transports for pipe and file deliveries (see -chapter ~~CHAPredirect). - - -.conf transport@_current@_directory string$**$ unset -.index current directory for local transport -This option associates a current directory with any address that is routed -to a local transport. This can happen either because a transport is -explicitly configured for the router, or because it generates a delivery to a -file or a pipe. During the delivery process (that is, at transport time), this -option string is expanded and is set as the current directory, unless -overridden by a setting on the transport. -If the expansion fails for any reason, including forced failure, an error is -logged, and delivery is deferred. -See chapter ~~CHAPenvironment for details of the local delivery environment. - - - -.conf transport@_home@_directory string$**$ "see below" -.index home directory||for local transport -This option associates a home directory with any address that is routed to a -local transport. This can happen either because a transport is explicitly -configured for the router, or because it generates a delivery to a file or a -pipe. During the delivery process (that is, at transport time), the option -string is expanded and is set as the home directory, unless overridden by a -setting of \home@_directory\ on the transport. -If the expansion fails for any reason, including forced failure, an error is -logged, and delivery is deferred. - -If the transport does not specify a home directory, and -\transport@_home@_directory\ is not set for the router, the home directory for -the tranport is taken from the password data if \check@_local@_user\ is set for -the router. Otherwise it is taken from \router@_home@_directory\ if that option -is set; if not, no home directory is set for the transport. - -See chapter ~~CHAPenvironment for further details of the local delivery -environment. - - - -.conf unseen boolean$**$ false -.index router||carrying on after success -The result of string expansion for this option must be a valid boolean value, -that is, one of the strings `yes', `no', `true', or `false'. Any other result -causes an error, and delivery is deferred. If the expansion is forced to fail, -the default value for the option (false) is used. Other failures cause delivery -to be deferred. - -When this option is set true, routing does not cease if the router accepts the -address. Instead, a copy of the incoming address is passed to the next router, -overriding a false setting of \more\. There is little point in setting \more\ -false if \unseen\ is always true, but it may be useful in cases when the value -of \unseen\ contains expansion items (and therefore, presumably, is sometimes -true and sometimes false). - -The \unseen\ option can be used to cause -.index copy of message (\unseen\ option) -copies of messages to be delivered to some other destination, while also -carrying out a normal delivery. In effect, the current address is made into a -`parent' that has two children -- one that is delivered as specified by this -router, and a clone that goes on to be routed further. - -Header lines added to the address (or specified for removal) by this router or -by previous routers affect the `unseen' copy of the message only. The clone -that continues to be processed by further routers starts with no added headers -and none specified for removal. - -However, any data that was set by the \address@_data\ option in the current or -previous routers is passed on. Setting this option has a similar effect to the -\unseen\ command qualifier in filter files. - - -.conf user string$**$ "see below" -.index uid (user id)||local delivery -.index local transports||uid and gid -.index transport||local -.index router||user for filter processing -.index filter||user for processing -When a router queues an address for a transport, and the transport does not -specify a user, the user given here is used when running the delivery process. -The user may be specified numerically or by name. If expansion fails, the -error is logged and delivery is deferred. -This user is also used by the \%redirect%\ router when running a filter file. -The default is unset, except when \check@_local@_user\ is set. In this case, -the default is taken from the password information. If the user is specified as -a name, and \group\ is not set, the group associated with the user is used. See -also \initgroups\ and \group\ and the discussion in chapter ~~CHAPenvironment. - - -.conf verify "boolean (precondition)" true -Setting this option has the effect of setting \verify@_sender\ and -\verify@_recipient\ to the same value. - -.conf verify@_only "boolean (precondition)" false -.index \\EXPN\\||with \verify@_only\ -.index \-bv-\ option -.index router||used only when verifying -If this option is set, the router is used only when verifying an address or -testing with the \-bv-\ option, not when actually doing a delivery, testing -with the \-bt-\ option, or running the SMTP \\EXPN\\ command. It can be further -restricted to verifying only senders or recipients by means of \verify@_sender\ -and \verify@_recipient\. - -\**Warning**\: When the router is being run to verify addresses for an incoming -SMTP message, Exim is not running as root, but under its own uid. If the router -accesses any files, you need to make sure that they are accessible to the Exim -user or group. - -.conf verify@_recipient "boolean (precondition)" true -If this option is false, the router is skipped when verifying recipient -addresses -or testing recipient verification using \-bv-\. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - -.conf verify@_sender "boolean (precondition)" true -If this option is false, the router is skipped when verifying sender addresses -or testing sender verification using \-bvs-\. -See section ~~SECTrouprecon for a list of the order in which preconditions -are evaluated. - -.endconf - - - - - -. -. -. -. -. ============================================================================ -.chapter The accept router -.set runningfoot "accept router" -.index \%accept%\ router -.index routers||\%accept%\ -The \%accept%\ router has no private options of its own. Unless it is being used -purely for verification (see \verify@_only\) a transport is required to be -defined by the generic \transport\ option. If the preconditions that are -specified by generic options are met, the router accepts the address and queues -it for the given transport. The most common use of this router is for setting -up deliveries to local mailboxes. For example: -.display asis -localusers: - driver = accept - domains = mydomain.example - check_local_user - transport = local_delivery -.endd -The \domains\ condition in this example checks the domain of the address, and -\check@_local@_user\ checks that the local part is the login of a local user. -When both preconditions are met, the \%accept%\ router runs, and queues the -address for the \%local@_delivery%\ transport. - - - - - - -. -. -. -. -. ============================================================================ -.chapter The dnslookup router -.rset CHAPdnslookup "~~chapter" -.set runningfoot "dnslookup router" -.index \%dnslookup%\ router -.index routers||\%dnslookup%\ -The \%dnslookup%\ router looks up the hosts that handle mail for the -recipient's domain in the DNS. A transport must always be set for this router, -unless \verify@_only\ is set. - -If SRV support is configured (see \check@_srv\ below), Exim first searches for -SRV records. If none are found, or if SRV support is not configured, -MX records are looked up. If no MX records exist, address records are sought. -However, \mx@_domains\ can be set to disable the direct use of address records. - -MX records of equal priority are sorted by Exim into a random order. Exim then -looks for address records for the host names obtained from MX or SRV records. -When a host has more than one IP address, they are sorted into a random order, -except that IPv6 addresses are always sorted before IPv4 addresses. If all the -IP addresses found are discarded by a setting of the \ignore@_target@_hosts\ -generic option, the router declines. - -Unless they have the highest priority (lowest MX value), MX records that point -to the local host, or to any host name that matches \hosts__treat__as__local\, -are discarded, together with any other MX records of equal or lower priority. - -.index MX record||pointing to local host -.index local host||MX pointing to -.index \self\ option||in \%dnslookup%\ router -If the host pointed to by the highest priority MX record, or looked up as an -address record, is the local host, or matches \hosts__treat__as__local\, what -happens is controlled by the generic \self\ option. - -.em -.section Problems with DNS lookups -.rset SECTprowitdnsloo "~~chapter.~~section" -There have been problems with DNS servers when SRV records are looked up. -Some mis-behaving servers return a DNS error or timeout when a non-existent -SRV record is sought. Similar problems have in the past been reported for -MX records. The global \dns@_again@_means@_nonexist\ option can help with this -problem, but it is heavy-handed because it is a global option. - -For this reason, there are two options, \srv@_fail@_domains\ and -\mx@_fail@_domains\, that control what happens when a DNS lookup in a -\%dnslookup%\ router results in a DNS failure or a `try again' response. If an -attempt to look up an SRV or MX record causes one of these results, and the -domain matches the relevant list, Exim behaves as if the DNS had responded `no -such record'. In the case of an SRV lookup, this means that the router proceeds -to look for MX records; in the case of an MX lookup, it proceeds to look for A -or AAAA records, unless the domain matches \mx@_domains\, in which case routing -fails. -.nem - - -.section Private options for dnslookup -The private options for the \%dnslookup%\ router are as follows: - - -.startconf dnslookup - -.index options||\%dnslookup%\ router -.conf check@_secondary@_mx boolean false -.index MX record||checking for secondary -If this option is set, the router declines unless the local host is found in -(and removed from) the list of hosts obtained by MX lookup. This can be used to -process domains for which the local host is a secondary mail exchanger -differently to other domains. The way in which Exim decides whether a host is -the local host is described in section ~~SECTreclocipadd. - -.conf check@_srv string$**$ unset -.index SRV record||enabling use of -The \%dnslookup%\ router supports the use of SRV records (see RFC 2782) in -addition to MX and address records. The support is disabled by default. To -enable SRV support, set the \check@_srv\ option to the name of the service -required. For example, -.display asis -check_srv = smtp -.endd -looks for SRV records that refer to the normal smtp service. The option is -expanded, so the service name can vary from message to message or address -to address. This might be helpful if SRV records are being used for a -submission service. If the expansion is forced to fail, the \check@_srv\ -option is ignored, and the router proceeds to look for MX records in the -normal way. - -When the expansion succeeds, the router searches first for SRV records for -the given service (it assumes TCP protocol). A single SRV record with a -host name that consists of just a single dot indicates `no such service for -this domain'; if this is encountered, the router declines. If other kinds of -SRV record are found, they are used to construct a host list for delivery -according to the rules of RFC 2782. MX records are not sought in this case. - -When no SRV records are found, MX records (and address records) are sought in -the traditional way. In other words, SRV records take precedence over MX -records, just as MX records take precedence over address records. Note that -this behaviour is not sanctioned by RFC 2782, though a previous draft RFC -defined it. It is apparently believed that MX records are sufficient for email -and that SRV records should not be used for this purpose. However, SRV records -have an additional `weight' feature which some people might find useful when -trying to split an SMTP load between hosts of different power. - -.em -See section ~~SECTprowitdnsloo above for a discussion of Exim's behaviour when -there is a DNS lookup error. -.nem - -.conf mx@_domains "domain list$**$" unset -.index MX record||required to exist -.index SRV record||required to exist -A domain that matches \mx@_domains\ is required to have either an MX or an SRV -record in order to be recognised. (The name of this option could be improved.) -For example, if all the mail hosts in \*fict.example*\ are known to have MX -records, except for those in \*discworld.fict.example*\, you could use this -setting: -.display asis -mx_domains = ! *.discworld.fict.example : *.fict.example -.endd -This specifies that messages addressed to a domain that matches the list but -has no MX record should be bounced immediately instead of being routed using -the address record. - -.em -.conf mx@_fail@_domains "domain list$**$" unset -If the DNS lookup for MX records for one of the domains in this list causes a -DNS lookup error, Exim behaves as if no MX records were found. See section -~~SECTprowitdnsloo for more discussion. -.nem - - -.conf qualify@_single boolean true -.index DNS||resolver options -.index DNS||qualifying single-component names -When this option is true, the resolver option \\RES@_DEFNAMES\\ is set for DNS -lookups. Typically, but not standardly, this causes the resolver to qualify -single-component names with the default domain. For example, on a machine -called \*dictionary.ref.example*\, the domain \*thesaurus*\ would be changed to -\*thesaurus.ref.example*\ inside the resolver. For details of what your resolver -actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. - - -.conf rewrite@_headers boolean true -.index rewriting||header lines -.index header lines||rewriting -If the domain name in the address that is being processed is not fully -qualified, it may be expanded to its full form by a DNS lookup. For example, if -an address is specified as \*dormouse@@teaparty*\, the domain might be -expanded to \*teaparty.wonderland.fict.example*\. Domain expansion can also -occur as a result of setting the \widen@_domains\ option. If \rewrite@_headers\ -is true, all occurrences of the abbreviated domain name in any ::Bcc::, ::Cc::, -::From::, ::Reply-to::, ::Sender::, and ::To:: header lines of the message are -rewritten with the full domain name. - -This option should be turned off only when it is known that no message is -ever going to be sent outside an environment where the abbreviation makes -sense. - -When an MX record is looked up in the DNS and matches a wildcard record, name -servers normally return a record containing the name that has been looked up, -making it impossible to detect whether a wildcard was present or not. However, -some name servers have recently been seen to return the wildcard entry. If the -name returned by a DNS lookup begins with an asterisk, it is not used for -header rewriting. - -.conf same@_domain@_copy@_routing boolean false -.index address||copying routing -Addresses with the same domain are normally routed by the \%dnslookup%\ router -to the same list of hosts. However, this cannot be presumed, because the router -options and preconditions may refer to the local part of the address. By -default, therefore, Exim routes each address in a message independently. DNS -servers run caches, so repeated DNS lookups are not normally expensive, and in -any case, personal messages rarely have more than a few recipients. - -If you are running mailing lists with large numbers of subscribers at the same -domain, and you are using a \%dnslookup%\ router which is independent of the -local part, you can set \same__domain__copy@_routing\ to bypass repeated DNS -lookups for identical domains in one message. In this case, when \%dnslookup%\ -routes an address to a remote transport, any other unrouted addresses in the -message that have the same domain are automatically given the same routing -without processing them independently, -provided the following conditions are met: -.numberpars $. -No router that processed the address specified \headers@_add\ or -\headers@_remove\. -.nextp -The router did not change the address in any way, for example, by `widening' -the domain. -.endp - - -.conf search@_parents boolean false -.index DNS||resolver options -When this option is true, the resolver option \\RES@_DNSRCH\\ is set for DNS -lookups. This is different from the \qualify@_single\ option in that it applies -to domains containing dots. Typically, but not standardly, it causes the -resolver to search for the name in the current domain and in parent domains. -For example, on a machine in the \*fict.example*\ domain, if looking up -\*teaparty.wonderland*\ failed, the resolver would try -\*teaparty.wonderland.fict.example*\. For details of what your resolver -actually does, consult your man pages for \*resolver*\ and \*resolv.conf*\. - -Setting this option true can cause problems in domains that have a wildcard MX -record, because any domain that does not have its own MX record matches the -local wildcard. - - -.em -.conf srv@_fail@_domains "domain list$**$" unset -If the DNS lookup for SRV records for one of the domains in this list causes a -DNS lookup error, Exim behaves as if no SRV records were found. See section -~~SECTprowitdnsloo for more discussion. -.nem - - -.conf widen@_domains "string list" unset -.index domain||partial, widening -If a DNS lookup fails and this option is set, each of its strings in turn is -added onto the end of the domain, and the lookup is tried again. For example, -if -.display asis -widen_domains = fict.example:ref.example -.endd -is set and a lookup of \*klingon.dictionary*\ fails, -\*klingon.dictionary.fict.example*\ is looked up, and if this fails, -\*klingon.dictionary.ref.example*\ is tried. Note that the \qualify@_single\ -and \search@_parents\ options can cause some widening to be undertaken inside -the DNS resolver. - -.endconf - -.section Effect of qualify@_single and search@_parents -When a domain from an envelope recipient is changed by the resolver as a result -of the \qualify@_single\ or \search@_parents\ options, Exim rewrites the -corresponding address in the message's header lines unless \rewrite@_headers\ -is set false. Exim then re-routes the address, using the full domain. - -These two options affect only the DNS lookup that takes place inside the router -for the domain of the address that is being routed. They do not affect lookups -such as that implied by -.display asis -domains = @mx_any -.endd -that may happen while processing a router precondition before the router is -entered. No widening ever takes place for these lookups. - - - - - - - - - -. -. -. -. -. ============================================================================ -.chapter The ipliteral router -.set runningfoot "ipliteral router" -.index \%ipliteral%\ router -.index domain literal||routing -.index routers||\%ipliteral%\ -This router has no private options. Unless it is being used purely for -verification (see \verify@_only\) a transport is required to be defined by the -generic \transport\ option. The router accepts the address if its domain part -takes the form of an RFC 2822 domain literal, that is, an IP address enclosed -in square brackets. For example, this router handles the address -.display asis -root@[192.168.1.1] -.endd -by setting up delivery to the host with that IP address. - -If the IP address matches something in \ignore@_target@_hosts\, the router -declines. -.index \self\ option||in \%ipliteral%\ router -If an IP literal turns out to refer to the local host, the generic \self\ -option determines what happens. - -The RFCs require support for domain literals; however, their use is -controversial in today's Internet. If you want to use this router, you must -also set the main configuration option \allow@_domain@_literals\. Otherwise, -Exim will not recognize the domain literal syntax in addresses. - - - -. -. -. -. -. ============================================================================ -.chapter The iplookup router -.set runningfoot "iplookup router" -.index \%iplookup%\ router -.index routers||\%iplookup%\ -The \%iplookup%\ router was written to fulfil a specific requirement in -Cambridge University (which in fact no longer exists). For this reason, it is -not included in the binary of Exim by default. If you want to include it, you -must set -.display asis -ROUTER_IPLOOKUP=yes -.endd -in your \(Local/Makefile)\ configuration file. - -The \%iplookup%\ router routes an address by sending it over a TCP or UDP -connection to one or more specific hosts. The host can then return the same or -a different address -- in effect rewriting the recipient address in the -message's envelope. The new address is then passed on to subsequent routers. - - -If this process fails, the address can be passed on to -other routers, or delivery can be deferred. - -Background, for those that are interested: We have an Oracle database of all -Cambridge users, and one of the items of data it maintains for each user is -where to send mail addressed to \*user@@cam.ac.uk*\. The MX records for -\*cam.ac.uk*\ point to a central machine that has a large alias list that is -abstracted from the database. Mail from outside is switched by this system, and -originally internal mail was also done this way. However, this resulted in a -fair number of messages travelling from some of our larger systems to the -switch and back again. The Oracle machine now runs a UDP service that can be -called by the \%iplookup%\ router in Exim to find out where \*user@@cam.ac.uk*\ -addresses really have to go; this saves passing through the central switch, and -in many cases saves doing any remote delivery at all. - -Since \%iplookup%\ is just a rewriting router, a transport must not be -specified for it. - -.startconf iplookup -.index options||\%iplookup%\ router - -.conf hosts string unset -This option must be supplied. Its value is a colon-separated list of host -names. The hosts are looked up using \*gethostbyname()*\ -(or \*getipnodebyname()*\ when available) -and are tried in order until one responds to the query. If none respond, what -happens is controlled by \optional\. - -.conf optional boolean false -If \optional\ is true, if no response is obtained from any host, the address is -passed to the next router, overriding \no@_more\. If \optional\ is false, -delivery to the address is deferred. - -.conf port integer 0 -.index port||\%iplookup%\ router -This option must be supplied. It specifies the port number for the TCP or UDP -call. - -.conf protocol string "udp" -This option can be set to `udp' or `tcp' to specify which of the two protocols -is to be used. - -.conf query string$**$ "$tt{@$local@_part@@@$domain @$local@_part@@@$domain}" -This defines the content of the query that is sent to the remote hosts. The -repetition serves as a way of checking that a response is to the correct query -in the default case (see \response@_pattern\ below). - -.conf reroute string$**$ unset -If this option is not set, the rerouted address is precisely the byte string -returned by the remote host, up to the first white space, if any. If set, the -string is expanded to form the rerouted address. It can include parts matched -in the response by \response@_pattern\ by means of numeric variables such as -\$1$\, \$2$\, etc. The variable \$0$\ refers to the entire input string, -whether or not a pattern is in use. In all cases, the rerouted address must end -up in the form \*local@_part@@domain*\. - -.conf response@_pattern string unset -This option can be set to a regular expression that is applied to the string -returned from the remote host. If the pattern does not match the response, the -router declines. If \response@_pattern\ is not set, no checking of the response -is done, unless the query was defaulted, in which case there is a check that -the text returned after the first white space is the original address. This -checks that the answer that has been received is in response to the correct -question. For example, if the response is just a new domain, the following -could be used: -.display asis -response_pattern = ^([^@]+)$ -reroute = $local_part@$1 -.endd - -.conf timeout time 5s -This specifies the amount of time to wait for a response from the remote -machine. The same timeout is used for the \*connect()*\ function for a TCP -call. It does not apply to UDP. - -.endconf - - - - -. -. -. -. -. ============================================================================ -.chapter The manualroute router -.set runningfoot "manualroute router" -.index \%manualroute%\ router -.index routers||\%manualroute%\ -.index domain||manually routing -The \%manualroute%\ router is so-called because it provides a way of manually -routing an address according to its domain. It is mainly used when you want to -route addresses to remote hosts according to your own rules, bypassing the -normal DNS routing that looks up MX records. However, \%manualroute%\ can also -route to local transports, a facility that may be useful if you want to save -messages for dial-in hosts in local files. - -The \%manualroute%\ router compares a list of domain patterns with the domain it -is trying to route. If there is no match, the router declines. Each pattern has -associated with it a list of hosts and some other optional data, which may -include a transport. The combination of a pattern and its data is called a -`routing rule'. For patterns that do not have an associated transport, the -generic \transport\ option must specify a transport, unless the router is being -used purely for verification (see \verify@_only\). - -In the case of verification, matching the domain pattern is sufficient for the -router to accept the address. When actually routing an address for delivery, -an address that matches a domain pattern is queued for the associated -transport. If the transport is not a local one, a host list must be associated -with the pattern; IP addresses are looked up for the hosts, and these are -passed to the transport along with the mail address. For local transports, a -host list is optional. If it is present, it is passed in \$host$\ as a single -text string. - -The list of routing rules can be provided as an inline string in \route@_list\, -or the data can be obtained by looking up the domain in a file or database by -setting \route@_data\. Only one of these settings may appear in any one -instance of \%manualroute%\. The format of routing rules is described below, -following the list of private options. - -.section Private options for manualroute -.rset SECTprioptman "~~chapter.~~section" - -The private options for the \%manualroute%\ router are as follows: - -.startconf manualroute -.index options||\%manualroute%\ router - -.conf host@_find@_failed string "freeze" -This option controls what happens when \%manualroute%\ tries to find an IP -address for a host, and the host does not exist. The option can be set to one -of -.display asis -decline -defer -fail -freeze -pass -.endd -The default assumes that this state is a serious configuration error. The -difference between `pass' and `decline' is that the former forces the address -to be passed to the next router (or the router defined by \pass@_router\), -.index \more\ option -overriding \no@_more\, whereas the latter passes the address to the next router -only if \more\ is true. - -This option applies only to a definite `does not exist' state; if a host lookup -gets a temporary error, delivery is deferred unless the generic -\pass@_on@_timeout\ option is set. - -.conf hosts@_randomize boolean false -.index randomized host list -.index host||list of, randomized -If this option is set, the order of the items in a host list in a routing rule -is randomized each time the list is used, unless an option in the routing rule -overrides (see below). Randomizing the order of a host list can be used to do -crude load sharing. However, if more than one mail address is routed by the -same router to the same host list, the host lists are considered to be the same -(even though they may be randomized into different orders) for the purpose of -deciding whether to batch the deliveries into a single SMTP transaction. - -When \hosts@_randomize\ is true, a host list may be split -into groups whose order is separately randomized. This makes it possible to -set up MX-like behaviour. The boundaries between groups are indicated by an -item that is just \"+"\ in the host list. For example: -.display asis -route_list = * host1:host2:host3:+:host4:host5 -.endd -The order of the first three hosts and the order of the last two hosts is -randomized for each use, but the first three always end up before the last two. -If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. If a -randomized host list is passed to an \%smtp%\ transport that also has -\hosts@_randomize set\, the list is not re-randomized. - -.conf route@_data string$**$ unset -If this option is set, it must expand to yield the data part of a routing rule. -Typically, the expansion string includes a lookup based on the domain. For -example: -.display asis -route_data = ${lookup{$domain}dbm{/etc/routes}} -.endd -If the expansion is forced to fail, or the result is an empty string, the -router declines. Other kinds of expansion failure cause delivery to be -deferred. - -.conf route@_list "string list, semicolon-separated" unset -This string is a list of routing rules, in the form defined below. Note that, -unlike most string lists, the items are separated by semicolons. This is so -that they may contain colon-separated host lists. - -.conf same@_domain@_copy@_routing boolean false -.index address||copying routing -Addresses with the same domain are normally routed by the \%manualroute%\ router -to the same list of hosts. However, this cannot be presumed, because the router -options and preconditions may refer to the local part of the address. By -default, therefore, Exim routes each address in a message independently. DNS -servers run caches, so repeated DNS lookups are not normally expensive, and in -any case, personal messages rarely have more than a few recipients. - -If you are running mailing lists with large numbers of subscribers at the same -domain, and you are using a \%manualroute%\ router which is independent of the -local part, you can set \same@_domain@_copy@_routing\ to bypass repeated DNS -lookups for identical domains in one message. In this case, when \%manualroute%\ -routes an address to a remote transport, any other unrouted addresses in the -message that have the same domain are automatically given the same routing -without processing them independently. However, this is only done if -\headers@_add\ and \headers@_remove\ are unset. - -.endconf - - -.section Routing rules in route@_list -The value of \route@_list\ is a string consisting of a sequence of routing -rules, separated by semicolons. If a semicolon is needed in a rule, it can be -entered as two semicolons. Empty rules are ignored. The format of each rule is -.display -<<domain pattern>> <<list of hosts>> <<options>> -.endd -The following example contains two rules, each with a simple domain pattern and -no options: -.display asis -route_list = \ - dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ - thes.ref.example mail-3.ref.example:mail-4.ref.example -.endd -The three parts of a rule are separated by white space. The pattern and the -list of hosts can be enclosed in quotes if necessary, and if they are, the -usual quoting rules apply. Each rule in a \route@_list\ must start with a -single domain pattern, which is the only mandatory item in the rule. The -pattern is in the same format as one item in a domain list (see section -~~SECTdomainlist), -except that it may not be the name of an interpolated file. -That is, it may be wildcarded, or a regular expression, or a file or database -lookup (with semicolons doubled, because of the use of semicolon as a separator -in a \route@_list\). - -The rules in \route@_list\ are searched in order until one of the patterns -matches the domain that is being routed. The list of hosts and then options are -then used as described below. If there is no match, the router declines. When -\route@_list\ is set, \route@_data\ must not be set. - - -.section Routing rules in route@_data -The use of \route@_list\ is convenient when there are only a small number of -routing rules. For larger numbers, it is easier to use a file or database to -hold the routing information, and use the \route@_data\ option instead. -The value of \route@_data\ is a list of hosts, followed by (optional) options. -Most commonly, \route@_data\ is set as a string that contains an -expansion lookup. For example, suppose we place two routing rules in a file -like this: -.display asis -dict.ref.example: mail-1.ref.example:mail-2.ref.example -thes.ref.example: mail-3.ref.example:mail-4.ref.example -.endd -This data can be accessed by setting -.display asis -route_data = ${lookup{$domain}lsearch{/the/file/name}} -.endd -Failure of the lookup results in an empty string, causing the router to -decline. However, you do not have to use a lookup in \route@_data\. The only -requirement is that the result of expanding the string is a list of hosts, -possibly followed by options, separated by white space. The list of hosts must -be enclosed in quotes if it contains white space. - - - -.section Format of the list of hosts -A list of hosts, whether obtained via \route@_data\ or \route@_list\, is always -separately expanded before use. If the expansion fails, the router declines. -The result of the expansion must be a colon-separated list of names and/or -IP addresses. IP addresses are not enclosed in brackets. - -If the list of hosts was obtained from a \route@_list\ item, the following -variables are set during its expansion: -.index numerical variables (\$1$\, \$2$\, etc)||in \%manualroute%\ router -.numberpars $. -If the domain was matched against a regular expression, the numeric variables -\$1$\, \$2$\, etc. may be set. -.nextp -\$0$\ is always set to the entire domain. -.nextp -\$1$\ is also set when partial matching is done in a file lookup. -.nextp -.index \$value$\ -If the pattern that matched the domain was a lookup item, the data that was -looked up is available in the expansion variable \$value$\. -.endp - - -.section How the list of hosts is used -When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of -the hosts is tried, in the order specified, when carrying out the SMTP -delivery. However, the order can be changed by setting the \hosts@_randomize\ -option, either on the router (see section ~~SECTprioptman above), or on the -transport. - -Hosts may be listed by name or by IP address. An unadorned name in the list of -hosts is interpreted as a host name. A name that is followed by \"/MX"\ is -interpreted as an indirection to a sublist of hosts obtained by looking up MX -records in the DNS. For example: -.display asis -route_list = * x.y.z:p.q.r/MX:e.f.g -.endd -If the \hosts@_randomize\ option is set, the order of the items in the list is -randomized before any lookups are done. Exim then scans the list; for any name -that is not followed by \"/MX"\ it looks up an IP address. If this turns out to -be an interface on the local host and the item is not the first in the list, -Exim discards it and any subsequent items. If it is the first item, what -happens is controlled by the -.index \self\ option||in \%manualroute%\ router -\self\ option of the router. - -A name on the list that is followed by \"/MX"\ is replaced with the list of -hosts obtained by looking up MX records for the name. This is always a DNS -lookup; the \bydns\ and \byname\ options (see section ~~SECThowoptused below) -are not relevant here. The order of these hosts is determined by the preference -values in the MX records, according to the usual rules. Because randomizing -happens before the MX lookup, it does not affect the order that is defined by -MX preferences. - -If the local host is present in the sublist obtained from MX records, but is -not the most preferred host in that list, it and any equally or less -preferred hosts are removed before the sublist is inserted into the main list. - -If the local host is the most preferred host in the MX list, what happens -depends on where in the original list of hosts the \"/MX"\ item appears. If it -is not the first item (that is, there are previous hosts in the main list), -Exim discards this name and any subsequent items in the main list. - -If the MX item is first in the list of hosts, and the local host is the -most preferred host, what happens is controlled by the \self\ option of the -router. - -DNS failures when lookup up the MX records are treated in the same way as DNS -failures when looking up IP addresses: \pass@_on@_timeout\ and -\host@_find@_failed\ are used when relevant. - -The generic \ignore@_target@_hosts\ option applies to all hosts in the list, -whether obtained from an MX lookup or not. - - -.section How the options are used -.rset SECThowoptused "~~chapter.~~section" -The options are a sequence of words; in practice no more than three are ever -present. One of the words can be the name of a transport; this overrides the -\transport\ option on the router for this particular routing rule only. The -other words (if present) control randomization of the list of hosts on a -per-rule basis, and how the IP addresses of the hosts are to be found when -routing to a remote transport. These options are as follows: -.numberpars $. -\randomize\: randomize the order of the hosts in this list, overriding the -setting of \hosts@_randomize\ for this routing rule only. -.nextp -\no@_randomize\: do not randomize the order of the hosts in this list, -overriding the setting of \hosts@_randomize\ for this routing rule only. -.nextp -\byname\: use \*getipnodebyname()*\ (\*gethostbyname()*\ on older systems) to -find IP addresses. This function may ultimately cause a DNS lookup, but it may -also look in \(/etc/hosts)\ or other sources of information. -.nextp -\bydns\: look up address records for the hosts directly in the DNS; fail if -no address records are found. If there is a temporary DNS error (such as a -timeout), delivery is deferred. -.endp -For example: -.display asis -route_list = domain1 host1:host2:host3 randomize bydns;\ - domain2 host4:host5 -.endd -If neither \byname\ nor \bydns\ is given, Exim behaves as follows: First, a DNS -lookup is done. If this yields anything other than \\HOST@_NOT@_FOUND\\, that -result is used. Otherwise, Exim goes on to try a call to \*getipnodebyname()*\ -or \*gethostbyname()*\, and the result of the lookup is the result of that -call. - -\**Warning**\: It has been discovered that on some systems, if a DNS lookup -called via \*getipnodebyname()*\ times out, \\HOST@_NOT@_FOUND\\ is returned -instead of \\TRY@_AGAIN\\. That is why the default action is to try a DNS -lookup first. Only if that gives a definite `no such host' is the local -function called. - - - -If no IP address for a host can be found, what happens is controlled by the -\host@_find@_failed\ option. - -When an address is routed to a local transport, IP addresses are not looked up. -The host list is passed to the transport in the \$host$\ variable. - - -.section Manualroute examples -In some of the examples that follow, the presence of the \remote@_smtp\ -transport, as defined in the default configuration file, is assumed: - -.numberpars $. -.index smart host||example router -The \%manualroute%\ router can be used to forward all external mail to a -\*smart host*\. If you have set up, in the main part of the configuration, a -named domain list that contains your local domains, for example, -.display asis -domainlist local_domains = my.domain.example -.endd -you can arrange for all other domains to be routed to a smart host by making -your first router something like this: -.display asis -smart_route: - driver = manualroute - domains = !+local_domains - transport = remote_smtp - route_list = * smarthost.ref.example -.endd -This causes all non-local addresses to be sent to the single host -\*smarthost.ref.example*\. If a colon-separated list of smart hosts is given, -they are tried in order -(but you can use \hosts@_randomize\ to vary the order each time). -Another way of configuring the same thing is this: -.display asis -smart_route: - driver = manualroute - transport = remote_smtp - route_list = !+local_domains smarthost.ref.example -.endd -There is no difference in behaviour between these two routers as they stand. -However, they behave differently if \no@_more\ is added to them. In the first -example, the router is skipped if the domain does not match the \domains\ -precondition; the following router is always tried. If the router runs, it -always matches the domain and so can never decline. Therefore, \no@_more\ would -have no effect. In the second case, the router is never skipped; it always -runs. However, if it doesn't match the domain, it declines. In this case -\no@_more\ would prevent subsequent routers from running. - -.nextp -.index mail hub example -A \*mail hub*\ is a host which receives mail for a number of domains via MX -records in the DNS and delivers it via its own private routing mechanism. Often -the final destinations are behind a firewall, with the mail hub being the one -machine that can connect to machines both inside and outside the firewall. The -\%manualroute%\ router is usually used on a mail hub to route incoming messages -to the correct hosts. For a small number of domains, the routing can be inline, -using the \route@_list\ option, but for a larger number a file or database -lookup is easier to manage. - -If the domain names are in fact the names of the machines to which the mail is -to be sent by the mail hub, the configuration can be quite simple. For -example, -.display asis -hub_route: - driver = manualroute - transport = remote_smtp - route_list = *.rhodes.tvs.example $domain -.endd -This configuration routes domains that match \"*.rhodes.tvs.example"\ to hosts -whose names are the same as the mail domains. A similar approach can be taken -if the host name can be obtained from the domain name by a string manipulation -that the expansion facilities can handle. Otherwise, a lookup based on the -domain can be used to find the host: -.display asis -through_firewall: - driver = manualroute - transport = remote_smtp - route_data = ${lookup {$domain} cdb {/internal/host/routes}} -.endd -The result of the lookup must be the name or IP address of the host (or -hosts) to which the address is to be routed. If the lookup fails, the route -data is empty, causing the router to decline. The address then passes to the -next router. - -.nextp -.index batched SMTP output example -.index SMTP||batched outgoing, example -You can use \%manualroute%\ to deliver messages to pipes or files in batched -SMTP format for onward transportation by some other means. This is one way of -storing mail for a dial-up host when it is not connected. The route list entry -can be as simple as a single domain name in a configuration like this: -.display asis -save_in_file: - driver = manualroute - transport = batchsmtp_appendfile - route_list = saved.domain.example -.endd -though often a pattern is used to pick up more than one domain. If there are -several domains or groups of domains with different transport requirements, -different transports can be listed in the routing information: -.display asis -save_in_file: - driver = manualroute - route_list = \ - *.saved.domain1.example $domain batch_appendfile; \ - *.saved.domain2.example \ - ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ - batch_pipe -.endd -The first of these just passes the domain in the \$host$\ variable, which -doesn't achieve much (since it is also in \$domain$\), but the second does a -file lookup to find a value to pass, causing the router to decline to handle -the address if the lookup fails. -.nextp -.index UUCP||example of router for -Routing mail directly to UUCP software is a specific case of the use of -\%manualroute%\ in a gateway to another mail environment. This is an example of -one way it can be done: -.display asis -# Transport -uucp: - driver = pipe - user = nobody - command = /usr/local/bin/uux -r - \ - ${substr_-5:$host}!rmail ${local_part} - return_fail_output = true -.endd -.display asis -# Router -uucphost: - transport = uucp - driver = manualroute - route_data = \ - ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} -.endd -The file \(/usr/local/exim/uucphosts)\ contains entries like -.display asis -darksite.ethereal.example: darksite.UUCP -.endd -It can be set up more simply without adding and removing `.UUCP' but this way -makes clear the distinction between the domain name -\*darksite.ethereal.example*\ and the UUCP host name \*darksite*\. -.endp - - - - - - -. -. -. -. -. ============================================================================ -.chapter The queryprogram router -.set runningfoot "queryprogram router" -.rset CHAPdriverlast "~~chapter" -.index \%queryprogram%\ router -.index routers||\%queryprogram%\ -.index routing||by external program -The \%queryprogram%\ router routes an address by running an external command and -acting on its output. This is an expensive way to route, and is intended mainly -for use in lightly-loaded systems, or for performing experiments. However, if -it is possible to use the precondition options (\domains\, \local@_parts\, -etc) to skip this router for most addresses, it could sensibly be used in -special cases, even on a busy host. There are the following private options: - -.startconf queryprogram -.index options||\%queryprogram%\ router -.conf command string$**$ unset -This option must be set. It specifies the command that is to be run. The -command is split up into a command name and arguments, and then each is -expanded separately (exactly as for a \%pipe%\ transport, described in chapter -~~CHAPpipetransport). - -.conf command@_group string unset -.index gid (group id)||in \%queryprogram%\ router -This option specifies a gid to be set when running the command. It must be set -if \command@_user\ specifies a numerical uid. If it begins with a digit, it is -interpreted as the numerical value of the gid. Otherwise it is looked up using -\*getgrnam()*\. - -.conf command@_user string unset -.index uid (user id)||for \%queryprogram%\ -This option must be set. It specifies the uid which is set when running the -command. If it begins with a digit it is interpreted as the numerical value of -the uid. Otherwise, it is looked up using \*getpwnam()*\ to obtain a value for -the uid and, if \command@_group\ is not set, a value for the gid also. - -.conf current@_directory string / -This option specifies an absolute path which is made the current directory -before running the command. - -.conf timeout time 1h -If the command does not complete within the timeout period, its process group -is killed and the message is frozen. A value of zero time specifies no -timeout. - -.endconf - -The standard output of the command is connected to a pipe, which is read when -the command terminates. It should consist of a single line of output, -containing up to five fields, separated by white space. -.em -The maximum length of the line is 1023 characters. Longer lines are silently -truncated. -.nem -The first field is one of the following words (case-insensitive): -.numberpars $. -\*Accept*\: routing succeeded; the remaining fields specify what to do (see -below). -.nextp -\*Decline*\: the router declines; pass the address to the next router, unless -\no@_more\ is set. -.nextp -\*Fail*\: routing failed; do not pass the address to any more routers. Any -subsequent text on the line is an error message. If the router is run as part -of address verification during an incoming SMTP message, the message is -included in the SMTP response. -.nextp -\*Defer*\: routing could not be completed at this time; try again later. Any -subsequent text on the line is an error message which is logged. It is not -included in any SMTP response. -.nextp -\*Freeze*\: the same as \*defer*\, except that the message is frozen. -.nextp -\*Pass*\: pass the address to the next router (or the router specified by -\pass@_router\), overriding \no@_more\. -.nextp -\*Redirect*\: the message is redirected. The remainder of the line is a list of -new addresses, which are routed independently, starting with the first router, -or the router specified by \redirect@_router\, if set. -.endp -When the first word is \*accept*\, the remainder of the line consists of a -number of keyed data values, as follows (split into two lines here, to fit on -the page): -.display -ACCEPT TRANSPORT=<<transport>> HOSTS=<<list of hosts>> - LOOKUP=byname|bydns DATA=<<text>> -.endd -The data items can be given in any order, and all are optional. If no transport -is included, the transport specified by the generic \transport\ option is used. -The list of hosts and the lookup type are needed only if the transport is an -\%smtp%\ transport that does not itself supply a list of hosts. - -The format of the list of hosts is the same as for the \%manualroute%\ router. -As well as host names and IP addresses, it may contain names followed by -\"/MX"\ to specify sublists of hosts that are obtained by looking up MX -records. - -If the lookup type is not specified, Exim behaves as follows when trying to -find an IP address for each host: First, a DNS lookup is done. If this yields -anything other than \\HOST@_NOT@_FOUND\\, that result is used. Otherwise, Exim -goes on to try a call to \*getipnodebyname()*\ or \*gethostbyname()*\, and the -result of the lookup is the result of that call. - -If the DATA field is set, its value is placed in the \$address@_data$\ -variable. For example, this return line -.display asis -accept hosts=x1.y.example:x2.y.example data="rule1" -.endd -routes the address to the default transport, passing a list of two hosts. When -the transport runs, the string `rule1' is in \$address@_data$\. - - - -. -. -. -. -. ============================================================================ -.chapter The redirect router -.set runningfoot "redirect router" -.rset CHAPredirect "~~chapter" -.index \%redirect%\ router -.index routers||\%redirect%\ -.index alias file||in a \%redirect%\ router -.index address redirection||\%redirect%\ router -The \%redirect%\ router handles several kinds of address redirection. Its most -common uses are for resolving local part aliases from a central alias file -(usually called \(/etc/aliases)\) and for handling users' personal \(.forward)\ -files, but it has many other potential uses. The incoming address can be -redirected in several different ways: -.numberpars $. -It can be replaced by one or more new addresses which are themselves routed -independently. -.nextp -It can be routed to be delivered to a given file or directory. -.nextp -It can be routed to be delivered to a specified pipe command. -.nextp -It can cause an automatic reply to be generated. -.nextp -It can be forced to fail, with a custom error message. -.nextp -It can be temporarily deferred. -.nextp -It can be discarded. -.endp -The generic \transport\ option must not be set for \%redirect%\ routers. -However, there are some private options which define transports for delivery to -files and pipes, and for generating autoreplies. See the \file@_transport\, -\pipe@_transport\ and \reply@_transport\ descriptions below. - - -.section Redirection data -The router operates by interpreting a text string which it obtains either by -expanding the contents of the \data\ option, or by reading the entire contents -of a file whose name is given in the \file\ option. These two options are -mutually exclusive. The first is commonly used for handling system aliases, in -a configuration like this: -.display asis -system_aliases: - driver = redirect - data = ${lookup{$local_part}lsearch{/etc/aliases}} -.endd -If the lookup fails, the expanded string in this example is empty. When the -expansion of \data\ results in an empty string, the router declines. A forced -expansion failure also causes the router to decline; other expansion failures -cause delivery to be deferred. - -A configuration using \file\ is commonly used for handling users' \(.forward)\ -files, like this: -.display asis -userforward: - driver = redirect - check_local_user - file = $home/.forward - no_verify -.endd -If the file does not exist, or causes no action to be taken (for example, it is -empty or consists only of comments), the router declines. \**Warning**\: This -is not the case when the file contains syntactically valid items that happen to -yield empty addresses, for example, items containing only RFC 2822 address -comments. - - -.section Forward files and address verification -.index address redirection||while verifying -It is usual to set \no@_verify\ on \%redirect%\ routers which handle users' -\(.forward)\ files, as in the example above. There are two reasons for this: -.numberpars $. -When Exim is receiving an incoming SMTP message from a remote host, it is -running under the Exim uid, not as root. -No additional groups are set up, even if the Exim uid is a member of other -groups (that is, the \*initgroups()*\ function is not run). -Exim is unable to change uid to read the file as the user, and it may not be -able to read it as the Exim user. So in practice the router may not be able to -operate. -.nextp -However, even when the router can operate, the existence of a \(.forward)\ file -is unimportant when verifying an address. What should be checked is whether the -local part is a valid user name or not. Cutting out the redirection processing -saves some resources. -.endp - - - - -.section Interpreting redirection data -.index Sieve filter||specifying in redirection data -.index filter||specifying in redirection data -The contents of the data string, whether obtained from \data\ or \file\, can be -interpreted in two different ways: -.numberpars $. -If the \allow@_filter\ option is set true, and the data begins with the text -`@#Exim filter' or `@#Sieve filter', it is interpreted as a list of -\*filtering*\ instructions in the form of an Exim or Sieve filter file, -respectively. Details of the syntax and semantics of filter files are described -in a separate document entitled \*Exim's interfaces to mail filtering*\; this -document is intended for use by end users. -.nextp -Otherwise, the data must be a comma-separated list of redirection items, as -described in the next section. -.endp -When a message is redirected to a file (a `mail folder'), the file name given -in a non-filter redirection list must always be an absolute path. A filter may -generate a relative path -- how this is handled depends on the transport's -configuration. See section ~~SECTfildiropt for a discussion of this issue for -the \%appendfile%\ transport. - - -.section Items in a non-filter redirection list -.rset SECTitenonfilred "~~chapter.~~section" -.index address redirection||non-filter list items -When the redirection data is not an Exim or Sieve filter, for example, if it -comes from a conventional alias or forward file, it consists of a list of -addresses, file names, pipe commands, or certain special items (see section -~~SECTspecitredli below). The special items can be individually enabled or -disabled by means of options whose names begin with \allow@_\ or \forbid@_\, -depending on their default values. The items in the list are separated by -commas or newlines. -If a comma is required in an item, the entire item must be enclosed in double -quotes. - -Lines starting with a @# character are comments, and are ignored, and @# may -also appear following a comma, in which case everything between the @# and the -next newline character is ignored. - -If an item is entirely enclosed in double quotes, these are removed. Otherwise -double quotes are retained because some forms of mail address require their use -(but never to enclose the entire address). In the following description, `item' -refers to what remains after any surrounding double quotes have been removed. - -\**Warning**\: If you use an Exim expansion to construct a redirection address, -and the expansion contains a reference to \$local@_part$\, you should make use -of the \quote\ expansion operator, in case the local part contains special -characters. For example, to redirect all mail for the domain -\*obsolete.example*\, retaining the existing local part, you could use this -setting: -.display asis -data = ${quote:$local_part}@newdomain.example -.endd - - -.section Redirecting to a local mailbox -.rset SECTredlocmai "~~chapter.~~section" -.index routing||loops in -.index loop||while routing, avoidance of -.index address redirection||to local mailbox -A redirection item may safely be the same as the address currently under -consideration. This does not cause a routing loop, because a router is -automatically skipped if any ancestor of the address that is being processed -is the same as the current address and was processed by the current router. -Such an address is therefore passed to the following routers, so it is handled -as if there were no redirection. When making this loop-avoidance test, the -complete local part, including any prefix or suffix, is used. - -.index address redirection||local part without domain -Specifying the same local part without a domain is a common usage in personal -filter files when the user wants to have messages delivered to the local -mailbox and also forwarded elsewhere. For example, the user whose login is -\*cleo*\ might have a \(.forward)\ file containing this: -.display asis -cleo, cleopatra@egypt.example -.endd -.index backslash in alias file -.index alias file||backslash in -For compatibility with other MTAs, such unqualified local parts may be -preceeded by `@\', but this is not a requirement for loop prevention. However, -it does make a difference if more than one domain is being handled -synonymously. - -If an item begins with `@\' and the rest of the item parses as a valid RFC 2822 -address that does not include a domain, the item is qualified using the domain -of the incoming address. In the absence of a leading `@\', unqualified -addresses are qualified using the value in \qualify@_recipient\, but you can -force the incoming domain to be used by setting \qualify__preserve@_domain\. - -Care must be taken if there are alias names for local users. -Consider an MTA handling a single local domain where the system alias file -contains: -.display asis -Sam.Reman: spqr -.endd -Now suppose that Sam (whose login id is \*spqr*\) wants to save copies of -messages in the local mailbox, and also forward copies elsewhere. He creates -this forward file: -.display asis -Sam.Reman, spqr@reme.elsewhere.example -.endd -With these settings, an incoming message addressed to \*Sam.Reman*\ fails. The -\%redirect%\ router for system aliases does not process \*Sam.Reman*\ the -second time round, because it has previously routed it, -and the following routers presumably cannot handle the alias. The forward file -should really contain -.display asis -spqr, spqr@reme.elsewhere.example -.endd -but because this is such a common error, the \check@_ancestor\ option (see -below) exists to provide a way to get round it. This is normally set on a -\%redirect%\ router that is handling users' \(.forward)\ files. - - -.section Special items in redirection lists -.rset SECTspecitredli "~~chapter.~~section" -In addition to addresses, the following types of item may appear in redirection -lists (that is, in non-filter redirection data): - -.numberpars $. -.index pipe||in redirection list -.index address redirection||to pipe -An item is treated as a pipe command if it begins with `|' and does not parse -as a valid RFC 2822 address that includes a domain. A transport for running the -command must be specified by the \pipe@_transport\ option. -Normally, either the router or the transport specifies a user and a group under -which to run the delivery. The default is to use the Exim user and group. - -Single or double quotes can be used for enclosing the individual arguments of -the pipe command; no interpretation of escapes is done for single quotes. If -the command contains a comma character, it is necessary to put the whole item -in double quotes, for example: -.display asis -"|/some/command ready,steady,go" -.endd -since items in redirection lists are terminated by commas. Do not, however, -quote just the command. An item such as -.display asis -|"/some/command ready,steady,go" -.endd -is interpreted as a pipe with a rather strange command name, and no arguments. -.nextp -.index file||in redirection list -.index address redirection||to file -An item is interpreted as a path name if it begins with `/' and does not parse -as a valid RFC 2822 address that includes a domain. For example, -.display asis -/home/world/minbari -.endd -is treated as a file name, but -.display asis -/s=molari/o=babylon/@x400gate.way -.endd -is treated as an address. For a file name, a transport must be specified using -the \file@_transport\ option. However, if the generated path name ends with a -forward slash character, it is interpreted as a directory name rather than a -file name, and \directory@_transport\ is used instead. - -Normally, either the router or the transport specifies a user and a group under -which to run the delivery. The default is to use the Exim user and group. -.index \(/dev/null)\ -However, if a redirection item is the path \(/dev/null)\, delivery to it is -bypassed at a high level, and the log entry shows `$*$$*$bypassed$*$$*$' -instead of a transport name. In this case the user and group are not used. -.nextp -.index included address list -.index address redirection||included external list -If an item is of the form -.display -:include:<<path name>> -.endd -a list of further items is taken from the given file and included at that -point. -\**Note**\: such a file can not be a filter file; it is just an out-of-line -addition to the list. -The items in the included list are separated by commas or newlines and are not -subject to expansion. If this is the first item in an alias list in an -\%lsearch%\ file, a colon must be used to terminate the alias name. This -example is incorrect: -.display asis -list1 :include:/opt/lists/list1 -.endd -It must be given as -.display asis -list1: :include:/opt/lists/list1 -.endd -.nextp -.index address redirection||to black hole -Sometimes you want to throw away mail to a particular local part. Making the -\data\ option expand to an empty string does not work, because that causes the -router to decline. Instead, the alias item -.index black hole -.index abandoning mail -.display -:blackhole: -.endd -can be used. It does what its name implies. No delivery is done, and no error -message is generated. This has the same effect as specifing \(/dev/null)\, but -can be independently disabled. - -\**Warning**\: If \":blackhole:"\ appears anywhere in a redirection list, no -delivery is done for the original local part, even if other redirection items -are present. If you are generating a multi-item list (for example, by reading a -database) and need the ability to provide a no-op item, you must use -\(/dev/null)\. - -.nextp -.index delivery||forcing failure -.index delivery||forcing deferral -.index failing delivery||forcing -.index deferred delivery, forcing -.index customizing||failure message -An attempt to deliver a particular address can be deferred or forced to fail by -redirection items of the form -.display -:defer: -$rm{or} -:fail: -.endd -respectively. When a redirection list contains such an item, it applies to the -entire redirection; any other items in the list are ignored (:::blackhole:: is -different). Any text following :::fail:: or :::defer:: is placed in the error -text associated with the failure. For example, an alias file might contain: -.display asis -X.Employee: :fail: Gone away, no forwarding address -.endd -In the case of an address that is being verified from an ACL or as the subject -of a -.index \\VRFY\\||error text, display of -\\VRFY\\ command, the text is included in the SMTP error response by -default. -.em -.index \\EXPN\\||error text, display of -The text is not included in the response to an \\EXPN\\ command. -.nem - -In an ACL, an explicitly provided message overrides the default, but the -default message is available in the variable \$acl@_verify@_message$\ and can -therefore be included in a custom message if this is desired. Exim sends a 451 -SMTP code for a :::defer::, and 550 for :::fail::. In non-SMTP cases the text -is included in the error message that Exim generates. - - - -Normally the error text is the rest of the redirection list -- a comma does not -terminate it -- but a newline does act as a terminator. Newlines are not -normally present in alias expansions. In \%lsearch%\ lookups they are removed as -part of the continuation process, but they may exist in other kinds of lookup -and in :::include:: files. - -During routing for message delivery (as opposed to verification), a redirection -containing :::fail:: causes an immediate failure of the incoming address, -whereas :::defer:: causes the message to remain on the queue so that a -subsequent delivery attempt can happen at a later time. If an address is -deferred for too long, it will ultimately fail, because the normal retry -rules still apply. -.nextp -.index alias file||exception to default -Sometimes it is useful to use a single-key search type with a default (see -chapter ~~CHAPfdlookup) to look up aliases. However, there may be a need for -exceptions to the default. These can be handled by aliasing them to -.display asis -:unknown: -.endd -This differs from :::fail:: in that it causes the \%redirect%\ router to decline, -whereas :::fail:: forces routing to fail. A lookup which results in an empty -redirection list has the same effect. -.endp - -.section Duplicate addresses -.index duplicate addresses -.index address||duplicate, discarding -.index pipe||duplicated -Exim removes duplicate addresses from the list to which it is delivering, so as -to deliver just one copy to each address. This does not apply to deliveries -routed to pipes by different immediate parent addresses, but an indirect -aliasing scheme of the type -.display asis -pipe: |/some/command $local_part -localpart1: pipe -localpart2: pipe -.endd -does not work with a message that is addressed to both local parts, because -when the second is aliased to the intermediate local part `pipe' it gets -discarded as being the same as a previously handled address. However, a scheme -such as -.display asis -localpart1: |/some/command $local_part -localpart2: |/some/command $local_part -.endd -does result in two different pipe deliveries, because the immediate parents of -the pipes are distinct. - - -.section Repeated redirection expansion -.index repeated redirection expansion -.index address redirection||repeated for each delivery attempt -When a message cannot be delivered to all of its recipients immediately, -leading to two or more delivery attempts, redirection expansion is carried out -afresh each time for those addresses whose children were not all previously -delivered. If redirection is being used as a mailing list, this can lead to new -members of the list receiving copies of old messages. The \one@_time\ option -can be used to avoid this. - -.section Errors in redirection lists -.index address redirection||errors -If \skip@_syntax@_errors\ is set, a malformed address that causes a parsing -error is skipped, and an entry is written to the main log. This may be useful -for mailing lists that are automatically managed. Otherwise, if an error is -detected while generating the list of new addresses, the original address is -deferred. See also \syntax@_errors@_to\. - - -.section Private options for the redirect router - -The private options for the \%redirect%\ router are as follows: - -.startconf redirect -.index options||\%redirect%\ router - -.conf allow@_defer boolean false -Setting this option allows the use of :::defer:: in non-filter redirection -data, -or the \defer\ command in an Exim filter file. - -.conf allow@_fail boolean false -.index failing delivery||from filter -If this option is true, the :::fail:: item can be used in a redirection list, -and the \fail\ command may be used in a filter file. - -.conf allow@_filter boolean false -.index filter||enabling use of -.index Sieve filter||enabling use of -Setting this option allows Exim to interpret redirection data that starts with -`@#Exim filter' or `@#Sieve filter' as a set of filtering instructions. There -are some features of Exim filter files that some administrators may wish to -lock out; see the \forbid@_filter@_xxx\ options below. -.em -It is also possible to lock out Exim filters or Sieve filters while allowing -the other type; see \forbid@_exim@_filter\ and \forbid@_sieve@_filter\. -.nem - -The filter is run using the uid and gid set by the generic \user\ and \group\ -options. These take their defaults from the password data if -\check@_local@_user\ is set, so in the normal case of users' personal filter -files, the filter is run as the relevant user. When \allow@_filter\ is set -true, Exim insists that either \check@_local@_user\ or \user\ is set. - - -.conf allow@_freeze boolean false -.index freezing messages||allowing in filter -Setting this option allows the use of the \freeze\ command in an Exim filter. -This command is more normally encountered in system filters, and is disabled by -default for redirection filters because it isn't something you usually want to -let ordinary users do. - - -.conf check@_ancestor boolean false -This option is concerned with handling generated addresses that are the same -as some address in the list of redirection ancestors of the current address. -Although it is turned off by default in the code, it is set in the default -configuration file for handling users' \(.forward)\ files. It is recommended -for this use of the \%redirect%\ router. - -When \check@_ancestor\ is set, if a generated address (including the domain) is -the same as any ancestor of the current address, it is replaced by a copy of -the current address. This helps in the case where local part A is aliased to B, -and B has a \(.forward)\ file pointing back to A. For example, within a single -domain, the local part `Joe.Bloggs' is aliased to `jb' and \(@~jb/.forward)\ -contains: -.display -@\Joe.Bloggs, <<other item(s)>> -.endd -Without the \check@_ancestor\ setting, either local part (`jb' or `joe.bloggs') -gets processed once by each router and so ends up as it was originally. If `jb' -is the real mailbox name, mail to `jb' gets delivered (having been turned into -`joe.bloggs' by the \(.forward)\ file and back to `jb' by the alias), but mail -to `joe.bloggs' fails. Setting \check@_ancestor\ on the \%redirect%\ router that -handles the \(.forward)\ file prevents it from turning `jb' back into -`joe.bloggs' when that was the original address. See also the \repeat@_use\ -option below. - -.conf check@_group boolean "see below" -When the \file\ option is used, the group owner of the file is checked only -when this option is set. The permitted groups are those listed in the -\owngroups\ option, together with the user's default group if -\check@_local@_user\ is set. If the file has the wrong group, routing is -deferred. The default setting for this option is true if \check@_local@_user\ -is set and the \modemask\ option permits the group write bit, or if the -\owngroups\ option is set. Otherwise it is false, and no group check occurs. - - -.conf check@_owner boolean "see below" -When the \file\ option is used, the owner of the file is checked only when this -option is set. If \check@_local@_user\ is set, the local user is permitted; -otherwise the owner must be one of those listed in the \owners\ option. The -default value for this option is true if \check@_local@_user\ or \owners\ is -set. Otherwise the default is false, and no owner check occurs. - -.conf data string$**$ unset -This option is mutually exclusive with \file\. One or other of them must be -set, but not both. The contents of \data\ are expanded, and then used as the -list of forwarding items, or as a set of filtering instructions. If the -expansion is forced to fail, or the result is an empty string or a string that -has no effect (consists entirely of comments), the router declines. - -When filtering instructions are used, the string must begin with `@#Exim -filter', and all comments in the string, including this initial one, must be -terminated with newline characters. For example: -.display asis -data = #Exim filter\n\ - if $h_to: contains Exim then save $home/mail/exim endif -.endd -If you are reading the data from a database where newlines cannot be included, -you can use the \$@{sg@}$\ expansion item to turn the escape string of your -choice into a newline. - -.conf directory@_transport string$**$ unset -A \%redirect%\ router sets up a direct delivery to a directory when a path name -ending with a slash is specified as a new `address'. The transport used is -specified by this option, which, after expansion, must be the name of a -configured transport. This should normally be an \%appendfile%\ transport. - -.conf file string$**$ unset -This option specifies the name of a file that contains the redirection data. It -is mutually exclusive with the \data\ option. The string is expanded before -use; if the expansion is forced to fail, the router declines. Other expansion -failures cause delivery to be deferred. The result of a successful expansion -must be an absolute path. The entire file is read and used as the redirection -data. If the data is an empty string or a string that has no effect (consists -entirely of comments), the router declines. - -.index NFS||checking for file existence -If the attempt to open the file fails with a `does not exist' error, Exim -runs a check on the containing directory, -unless \ignore@_enotdir\ is true (see below). -If the directory does not appear to exist, delivery is deferred. This can -happen when users' \(.forward)\ files are in NFS-mounted directories, and there -is a mount problem. If the containing directory does exist, but the file does -not, the router declines. - -.conf file@_transport string$**$ unset -A \%redirect%\ router sets up a direct delivery to a file when a path name not -ending in a slash is specified as a new `address'. The transport used is -specified by this option, which, after expansion, must be the name of a -configured transport. -This should normally be an \%appendfile%\ transport. -When it is running, the file name is in \$address@_file$\. - -.conf forbid@_blackhole boolean false -If this option is true, the :::blackhole:: item may not appear in a redirection -list. - -.em -.conf forbid@_exim@_filter boolean false -If this option is set true, only Sieve filters are permitted when -\allow@_filter\ is true. -.nem - - -.conf forbid@_file boolean false -.index delivery||to file, forbidding -.index Sieve filter||forbidding delivery to a file -.index Sieve filter||`keep' facility, disabling -If this option is true, this router may not generate a new address that -specifies delivery to a local file or directory, either from a filter or from a -conventional forward file. This option is forced to be true if \one@_time\ is -set. It applies to Sieve filters as well as to Exim filters, but if true, it -locks out the Sieve's `keep' facility. - -.conf forbid@_filter@_existstest boolean false -.index filter||locking out certain features -If this option is true, string expansions in Exim filters are not allowed to -make use of the \exists\ condition. - -.conf forbid@_filter@_logwrite boolean false -If this option is true, use of the logging facility in Exim filters is not -permitted. Logging is in any case available only if the filter is being run -under some unprivileged uid (which is normally the case for ordinary users' -\(.forward)\ files). - -.conf forbid@_filter@_lookup boolean false -If this option is true, string expansions in Exim filter files are not allowed -to make use of \lookup\ items. - -.conf forbid@_filter@_perl boolean false -This option is available only if Exim is built with embedded Perl support. If -it is true, string expansions in Exim filter files are not allowed to make use -of the embedded Perl support. - -.conf forbid@_filter@_readfile boolean false -If this option is true, string expansions in Exim filter files are not allowed -to make use of \readfile\ items. - -.conf forbid@_filter@_readsocket boolean false -If this option is true, string expansions in Exim filter files are not allowed -to make use of \readsocket\ items. - -.conf forbid@_filter@_reply boolean false -If this option is true, this router may not generate an automatic reply -message. Automatic replies can be generated only from Exim -.em -or Sieve filter files, not from traditional forward files. -.nem -This option is forced to be true if \one@_time\ is set. - -.conf forbid@_filter@_run boolean false -If this option is true, string expansions in Exim filter files are not allowed -to make use of \run\ items. - -.conf forbid@_include boolean false -If this option is true, items of the form -.display -:include:<<path name>> -.endd -are not permitted in non-filter redirection lists. - -.conf forbid@_pipe boolean false -.index delivery||to pipe, forbidding -If this option is true, this router may not generate a new address which -specifies delivery to a pipe, either from an Exim filter or from a conventional -forward file. This option is forced to be true if \one@_time\ is set. - -.em -.conf forbid@_sieve@_filter boolean false -If this option is set true, only Exim filters are permitted when -\allow@_filter\ is true. -.nem - - -.conf hide@_child@_in@_errmsg boolean false -.index bounce message||redirection details, suppressing -If this option is true, it prevents Exim from quoting a child address if it -generates a bounce or delay message for it. Instead it says `an address -generated from <<the top level address>>'. Of course, this applies only to -bounces generated locally. If a message is forwarded to another host, $it{its} -bounce may well quote the generated address. - -.conf ignore@_eacces boolean false -.index \\EACCES\\ -If this option is set and an attempt to open a redirection file yields the -\\EACCES\\ error (permission denied), the \%redirect%\ router behaves as if the -file did not exist. - -.conf ignore@_enotdir boolean false -.index \\ENOTDIR\\ -If this option is set and an attempt to open a redirection file yields the -\\ENOTDIR\\ error (something on the path is not a directory), the \%redirect%\ -router behaves as if the file did not exist. - -Setting \ignore@_enotdir\ has another effect as well: When a \%redirect%\ -router that has the \file\ option set discovers that the file does not exist -(the \\ENOENT\\ error), it tries to \*stat()*\ the parent directory, as a check -against unmounted NFS directories. If the parent can not be statted, delivery -is deferred. However, it seems wrong to do this check when \ignore@_enotdir\ is -set, because that option tells Exim to ignore `something on the path is not a -directory' (the \\ENOTDIR\\ error). This is a confusing area, because it seems -that some operating systems give \\ENOENT\\ where others give \\ENOTDIR\\. - - -.conf include@_directory string unset -If this option is set, the path names of any :::include:: items in a redirection -list must start with this directory. - -.conf modemask "octal integer" 022 -This specifies mode bits which must not be set for a file specified by the -\file\ option. If any of the forbidden bits are set, delivery is deferred. - -.conf one@_time boolean false -.index one-time aliasing/forwarding expansion -.index alias file||one-time expansion -.index forward file||one-time expansion -.index mailing lists||one-time expansion -.index address redirection||one-time expansion -Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection -files each time it tries to deliver a message causes a problem -when one or more of the generated addresses fails be delivered at the first -attempt. The problem is not one of duplicate delivery -- Exim is clever enough -to handle that -- but of what happens when the redirection list changes during -the time that the message is on Exim's queue. This is particularly true in the -case of mailing lists, where new subscribers might receive copies of messages -that were posted before they subscribed. - -If \one@_time\ is set and any addresses generated by the router fail to -deliver at the first attempt, the failing addresses are added to the message as -`top level' addresses, and the parent address that generated them is marked -`delivered'. Thus, redirection does not happen again at the next -delivery attempt. - -\**Warning 1**\: This means that any header line addition or removal that is -specified by this router would be lost if delivery did not succeed at the -first attempt. For this reason, the \headers@_add\ and \headers@_remove\ -generic options are not permitted when \one@_time\ is set. - -\**Warning 2**\: To ensure that the router generates only addresses (as opposed -to pipe or file deliveries or auto-replies) \forbid@_file\, \forbid@_pipe\, -and \forbid@_filter@_reply\ are forced to be true when \one@_time\ is set. - -The original top-level address is remembered with each of the generated -addresses, and is output in any log messages. However, any intermediate parent -addresses are not recorded. This makes a difference to the log only if -\all__parents\ log selector is set. It is expected that \one@_time\ will -typically be used for mailing lists, where there is normally just one level of -expansion. - -.conf owners "string list" unset -.index ownership||alias file -.index ownership||forward file -.index alias file||ownership -.index forward file||ownership -This specifies a list of permitted owners for the file specified by \file\. -This list is in addition to the local user when \check@_local@_user\ is set. -See \check@_owner\ above. - -.conf owngroups "string list" unset -This specifies a list of permitted groups for the file specified by \file\. The -list is in addition to the local user's primary group when \check@_local@_user\ -is set. See \check@_group\ above. - -.conf pipe@_transport string$**$ unset -A \%redirect%\ router sets up a direct delivery to a pipe when a string starting -with a vertical bar character is specified as a new `address'. The transport -used is specified by this option, which, after expansion, must be the name of a -configured transport. -This should normally be a \%pipe%\ transport. -When the transport is run, the pipe command is in \$address@_pipe$\. - -.conf qualify@_domain string$**$ unset -If this option is set and an unqualified address (one without a domain) is -generated, it is qualified with the domain specified by expanding this string, -instead of the global setting in \qualify@_recipient\. If the expansion fails, -the router declines. If you want to revert to the default, you can have the -expansion generate \$qualify@_recipient$\. - -.conf qualify@_preserve@_domain boolean false -.index domain||in redirection, preserving -.index preserving domain in redirection -.index address redirection||domain, preserving -If this is set and an unqualified address (one without a domain) is generated, -it is qualified with the domain of the -parent address (the immediately preceding ancestor) instead of the local -\qualify@_domain\ or global \qualify@_recipient\ value. - -.conf repeat@_use boolean true -If this option is set false, the router is skipped for a child address that has -any ancestor that was routed by this router. This test happens before any of -the other preconditions are tested. Exim's default anti-looping rules skip -only when the ancestor is the same as the current address. See also -\check@_ancestor\ above and the generic \redirect@_router\ option. - -.conf reply@_transport string$**$ unset -A \%redirect%\ router sets up an automatic reply when a \mail\ or \vacation\ -command is used in a filter file. The transport used is specified by this -option, which, after expansion, must be the name of a configured transport. -This should normally be an \%autoreply%\ transport. Other transports are -unlikely to do anything sensible or useful. - -.conf rewrite boolean true -.index address redirection||disabling rewriting -If this option is set false, addresses generated by the router are not -subject to address rewriting. Otherwise, they are treated like new addresses -and are rewritten according to the global rewriting rules. - - -.em -.conf sieve@_vacation@_directory string$**$ unset -.index Sieve filter||vacation directory -To enable the `vacation' extension for Sieve filters, you must set -\sieve@_vacation@_directory\ to the directory where vacation databases are held -(do not put anything else in that directory), and ensure that the -\reply@_transport\ option refers to an \%autoreply%\ transport. -.nem - - -.conf skip@_syntax@_errors boolean false -.index forward file||broken -.index address redirection||broken files -.index alias file||broken -.index broken alias or forward files -.index ignoring faulty addresses -.index skipping faulty addresses -.index error||skipping bad syntax -If \skip@_syntax@_errors\ is set, syntactically malformed addresses in -non-filter redirection data are skipped, and each failing address is logged. If -\syntax@_errors@_to\ is set, a message is sent to the address it defines, -giving details of the failures. If \syntax@_errors@_text\ is set, its contents -are expanded and placed at the head of the error message generated by -\syntax@_errors@_to\. Usually it is appropriate to set \syntax@_errors@_to\ to -be the same address as the generic \errors@_to\ option. The -\skip@_syntax@_errors\ option is often used when handling mailing lists. - -If all the addresses in a redirection list are skipped because of syntax -errors, the router declines to handle the original address, and it is passed to -the following routers. - -If \skip@_syntax@_errors\ is set when an Exim filter is interpreted, any syntax -error in the filter causes filtering to be abandoned without any action being -taken. The incident is logged, and the router declines to handle the address, -so it is passed to the following routers. - -.index Sieve filter||syntax errors in -.em -Syntax errors in a Sieve filter file cause the `keep' action to -occur. This action is specified by RFC 3028. -.nem -The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and -\syntax@_errors@_text\ are not used. - -\skip@_syntax@_errors\ can be used to specify that errors in users' forward -lists or filter files should not prevent delivery. The \syntax@_errors@_to\ -option, used with an address that does not get redirected, can be used to -notify users of these errors, by means of a router like this: -.display flow asis -userforward: - driver = redirect - allow_filter - check_local_user - file = $home/.forward - file_transport = address_file - pipe_transport = address_pipe - reply_transport = address_reply - no_verify - skip_syntax_errors - syntax_errors_to = real-$local_part@$domain - syntax_errors_text = \ - This is an automatically generated message. An error has\n\ - been found in your .forward file. Details of the error are\n\ - reported below. While this error persists, you will receive\n\ - a copy of this message for every message that is addressed\n\ - to you. If your .forward file is a filter file, or if it is\n\ - a non-filter file containing no valid forwarding addresses,\n\ - a copy of each incoming message will be put in your normal\n\ - mailbox. If a non-filter file contains at least one valid\n\ - forwarding address, forwarding to the valid addresses will\n\ - happen, and those will be the only deliveries that occur. -.endd -You also need a router to ensure that local addresses that are prefixed by -\"real-"\ are recognized, but not forwarded or filtered. For example, you could -put this immediately before the \%userforward%\ router: -.display asis -real_localuser: - driver = accept - check_local_user - local_part_prefix = real- - transport = local_delivery -.endd - -.conf syntax@_errors@_text string$**$ unset -See \skip@_syntax@_errors\ above. - -.conf syntax@_errors@_to string unset -See \skip@_syntax@_errors\ above. - -.endconf - - - - - -. -. -. -. ============================================================================ -.chapter Environment for running local transports -.rset CHAPenvironment "~~chapter" -.set runningfoot "local transport environment" -.index local transports||environment for -.index environment for local transports -.index transport||local, environment for -Local transports handle deliveries to files and pipes. (The \%autoreply%\ -transport can be thought of as similar to a pipe.) Exim always runs transports -in subprocesses, under specified uids and gids. Typical deliveries to local -mailboxes run under the uid and gid of the local user. - -Exim also sets a specific current directory while running the transport; for -some transports a home directory setting is also relevant. The \%pipe%\ -transport is the only one that sets up environment variables; see section -~~SECTpipeenv for details. - -The values used for the uid, gid, and the directories may come from several -different places. In many cases, the router that handles the address associates -settings with that address as a result of its \check@_local@_user\, \group\, or -\user\ options. However, values may also be given in the transport's own -configuration, and these override anything that comes from the router. - - -.em -.section Concurrent deliveries -.index concurrent deliveries -.index simultaneous deliveries -If two different messages for the same local recpient arrive more or less -simultaneously, the two delivery processes are likely to run concurrently. When -the \%appendfile%\ transport is used to write to a file, Exim applies locking -rules to stop concurrent processes from writing to the same file at the same -time. - -However, when you use a \%pipe%\ transport, it is up to you to arrange any -locking that is needed. Here is a silly example: -.display asis -my_transport: - driver = pipe - command = /bin/sh -c 'cat >>/some/file' -.endd -This is supposed to write the message at the end of the file. However, if two -messages arrive at the same time, the file will be scrambled. You can use the -\exim@_lock\ utility program (see section ~~SECTmailboxmaint) to lock a file -using the same algorithm that Exim itself uses. -.nem - - -.section Uids and gids -.rset SECTenvuidgid "~~chapter.~~section" -.index local transports||uid and gid -.index transport||local, uid and gid -All transports have the options \group\ and \user\. If \group\ is set, it -overrides any group that the router set in the address, even if \user\ is not -set for the transport. This makes it possible, for example, to run local mail -delivery under the uid of the recipient (set by the router), but in a special -group (set by the transport). For example: -.display asis -# Routers ... -# User/group are set by check_local_user in this router -local_users: - driver = accept - check_local_user - transport = group_delivery - -# Transports ... -# This transport overrides the group -group_delivery: - driver = appendfile - file = /var/spool/mail/$local_part - group = mail -.endd -If \user\ is set for a transport, its value overrides what is set in the -address. If \user\ is non-numeric and \group\ is not set, the gid associated -with the user is used. If \user\ is numeric, \group\ must be set. - -.index \initgroups\ option -When the uid is taken from the transport's configuration, the \*initgroups()*\ -function is called for the groups associated with that uid if the \initgroups\ -option is set for the transport. When the uid is not specified by the -transport, but is associated with the address by a router, the option for -calling \*initgroups()*\ is taken from the router configuration. - -.index \%pipe%\ transport||uid for -The \%pipe%\ transport contains the special option \pipe@_as@_creator\. If this -is set and \user\ is not set, the uid of the process that called Exim to -receive the message is used, and if \group\ is not set, the corresponding -original gid is also used. - - -.section Current and home directories -.index current directory for local transport -.index home directory||for local transport -.index transport||local, home directory for -.index transport||local, current directory for -Routers may set current and home directories for local transports by means of -the \transport__current@_directory\ and \transport@_home@_directory\ options. -However, if the transport's \current__directory\ or \home@_directory\ options -are set, they override the router's values. In detail, the home directory -for a local transport is taken from the first of these values that is set: -.numberpars $. -The \home@_directory\ option on the transport; -.nextp -The \transport@_home@_directory\ option on the router; -.nextp -The password data if \check@_local@_user\ is set on the router; -.nextp -The \router@_home@_directory\ option on the router. -.endp -The current directory is taken from the first of these values that is set: -.numberpars $. -The \current@_directory\ option on the transport; -.nextp -The \transport@_current@_directory\ option on the router. -.endp - -If neither the router nor the transport sets a current directory, Exim uses the -value of the home directory, if it is set. Otherwise it sets the current -directory to \(/)\ before running a local transport. - - -.section Expansion variables derived from the address -Normally a local delivery is handling a single address, and in that case the -variables such as \$domain$\ and \$local@_part$\ are set during local -deliveries. However, in some circumstances more than one address may be handled -at once (for example, while writing batch SMTP for onward transmission by some -other means). In this case, the variables associated with the local part are -never set, \$domain$\ is set only if all the addresses have the same -domain, and \$original@_domain$\ is never set. - - - - - - - -. -. -. -. ============================================================================ -.chapter Generic options for transports -.rset CHAPtransportgeneric "~~chapter" -.set runningfoot "generic transport options" - -.index generic options||transport -.index options||generic, for transports -.index transport||generic options for -The following generic options apply to all transports: - -.startconf transports -.conf body@_only boolean false -.index transport||body only -.index message||transporting body only -.index body of message||transporting -If this option is set, the message's headers are not transported. It is -mutually exclusive with \headers@_only\. If it is used with the \%appendfile%\ or -\%pipe%\ transports, the settings of \message@_prefix\ and \message@_suffix\ -should be checked, because this option does not automatically suppress them. - -.conf current@_directory string$**$ unset -.index transport||current directory for -This specifies the current directory that is to be set while running the -transport, overriding any value that may have been set by the router. -If the expansion fails for any reason, including forced failure, an error is -logged, and delivery is deferred. - -.conf disable@_logging boolean false -If this option is set true, nothing is logged for any -deliveries by the transport or for any -transport errors. You should not set this option unless you really, really know -what you are doing. - -.conf debug@_print string$**$ unset -.index testing||variables in drivers -If this option is set and debugging is enabled (see the \-d-\ command line -option), the string is expanded and included in the debugging output when the -transport is run. -If expansion of the string fails, the error message is written to the debugging -output, and Exim carries on processing. -This facility is provided to help with checking out the values of variables and -so on when debugging driver configurations. For example, if a \headers@_add\ -option is not working properly, \debug@_print\ could be used to output the -variables it references. A newline is added to the text if it does not end with -one. - -.conf delivery@_date@_add boolean false -.index ::Delivery-date:: header line -If this option is true, a ::Delivery-date:: header is added to the message. This -gives the actual time the delivery was made. As this is not a standard header, -Exim has a configuration option (\delivery@_date@_remove\) which requests its -removal from incoming messages, so that delivered messages can safely be resent -to other recipients. - -.conf driver string unset -This specifies which of the available transport drivers is to be used. -There is no default, and this option must be set for every transport. - -.conf envelope@_to@_add boolean false -.index ::Envelope-to:: header line -If this option is true, an ::Envelope-to:: header is added to the message. This -gives the original address(es) in the incoming envelope that caused this -delivery to happen. More than one address may be present if the transport is -configured to handle several addresses at once, or if more than one original -address was redirected to the same final address. As this is not a standard -header, Exim has a configuration option (\envelope@_to@_remove\) which requests -its removal from incoming messages, so that delivered messages can safely be -resent to other recipients. - -.conf group string$**$ "Exim group" -.index transport||group, specifying -This option specifies a gid for running the transport process, overriding any -value that the router supplies, and also overriding any value associated with -\user\ (see below). - -.conf headers@_add string$**$ unset -.index header lines||adding in transport -.index transport||header lines, adding -.em -This option specifies a string of text that is expanded and added to the header -portion of a message as it is transported, as described in section -~~SECTheadersaddrem. Additional header lines can also be specified by routers. -If the result of the expansion is an empty string, or if the expansion is -forced to fail, no action is taken. Other expansion failures are treated as -errors and cause the delivery to be deferred. -.nem - -.conf headers@_only boolean false -.index transport||header lines only -.index message||transporting headers only -.index header lines||transporting -If this option is set, the message's body is not transported. It is mutually -exclusive with \body@_only\. If it is used with the \%appendfile%\ or \%pipe%\ -transports, the settings of \message@_prefix\ and \message__suffix\ should be -checked, since this option does not automatically suppress them. - -.conf headers@_remove string$**$ unset -.index header lines||removing -.index transport||header lines, removing -.em -This option specifies a string that is expanded into a list of header names; -these headers are omitted from the message as it is transported, as described -in section ~~SECTheadersaddrem. Header removal can also be specified by -routers. If the result of the expansion is an empty string, or if the expansion -is forced to fail, no action is taken. Other expansion failures are treated as -errors and cause the delivery to be deferred. -.nem - -.conf headers@_rewrite string unset -.index transport||header lines, rewriting -.index rewriting||at transport time -This option allows addresses in header lines to be rewritten at transport time, -that is, as the message is being copied to its destination. The contents of the -option are a colon-separated list of rewriting rules. Each rule is in exactly -the same form as one of the general rewriting rules that are applied when a -message is received. These are described in chapter ~~CHAPrewrite. For example, -.display asis -headers_rewrite = a@b c@d f : \ - x@y w@z -.endd -changes \a@@b\ into \c@@d\ in ::From:: header lines, and \x@@y\ into \w@@z\ in -all address-bearing header lines. The rules are applied to the header lines -just before they are written out at transport time, so they affect only those -copies of the message that pass through the transport. However, only the -message's original header lines, and any that were added by a system filter, -are rewritten. If a router or transport adds header lines, they are -not affected by this option. These rewriting rules are $it{not} applied to the -envelope. You can change the return path using \return@_path\, but you cannot -change envelope recipients at this time. - -.conf home@_directory string$**$ unset -.index transport||home directory for -This option specifies a home directory setting for the transport, overriding -any value that may be set by the router. The home directory is placed in -\$home$\ while expanding the transport's private options. It is also used as -the current directory if no current directory is set by the -\current__directory\ option on the transport or the -\transport__current__directory\ option on the router. -If the expansion fails for any reason, including forced failure, an error is -logged, and delivery is deferred. - - -.index additional groups -.index groups, additional -.index transport||group, additional -.conf initgroups boolean false -If this option is true and the uid for the delivery process is provided by the -transport, the \*initgroups()*\ function is called when running the transport -to ensure that any additional groups associated with the uid are set up. - -.conf message@_size@_limit string$**$ 0 -.index limit||message size per transport -.index size||of message, limit -.index transport||message size, limiting -This option controls the size of messages passed through the transport. It is -expanded before use; the result of the expansion must be a sequence of digits, -optionally followed by K or M. -If the expansion fails for any reason, including forced failure, or if the -result is not of the required form, delivery is deferred. -If the value is greater than zero and the size of a message exceeds this -limit, the address is failed. If there is any chance that the resulting bounce -message could be routed to the same transport, you should ensure that -\return@_size@_limit\ is less than the transport's \message@_size@_limit\, as -otherwise the bounce message will fail to get delivered. - - -.conf rcpt@_include@_affixes boolean false -.index prefix||for local part, including in envelope -.index suffix||for local part, including in envelope -.index local part||prefix -.index local part||suffix -When this option is false (the default), and an address that has had any -affixes (prefixes or suffixes) removed from the local part is delivered by any -form of SMTP or LMTP, the affixes are not included. For example, if a router -that contains -.display asis -local_part_prefix = *- -.endd -routes the address \*abc-xyz@@some.domain*\ to an SMTP transport, the envelope -is delivered with -.display asis -RCPT TO:<xyz@some.domain> -.endd -If \rcpt@_include@_affixes\ is set true, the whole local part is included in -the \\RCPT\\ command. This option applies to BSMTP deliveries by the -\%appendfile%\ and \%pipe%\ transports as well as to the \%lmtp%\ and \%smtp%\ -transports. - -.conf retry@_use@_local@_part boolean "see below" -.index hints database||retry keys -When a delivery suffers a temporary failure, a retry record is created -in Exim's hints database. For remote deliveries, the key for the retry record -is based on the name and/or IP address of the failing remote host. For local -deliveries, the key is normally the entire address, including both the local -part and the domain. This is suitable for most common cases of local delivery -temporary failure -- for example, exceeding a mailbox quota should delay only -deliveries to that mailbox, not to the whole domain. - -However, in some special cases you may want to treat a temporary local delivery -as a failure associated with the domain, and not with a particular local part. -(For example, if you are storing all mail for some domain in files.) You can do -this by setting \retry@_use@_local@_part\ false. - -For all the local transports, its default value is true. For remote transports, -the default value is false for tidiness, but changing the value has no effect -on a remote transport in the current implementation. - -.conf return@_path string$**$ unset -.index envelope sender -.index transport||return path, changing -.index return path||changing in transport -If this option is set, the string is expanded at transport time and replaces -the existing return path (envelope sender) value in the copy of the message -that is being delivered. An empty return path is permitted. This feature is -designed for remote deliveries, where the value of this option is used in the -SMTP \\MAIL\\ command. If you set \return@_path\ for a local transport, the -only effect is to change the address that is placed in the ::Return-path:: -header line, if one is added to the message (see the next option). - -The expansion can refer to the existing value via \$return@_path$\. This is -either the message's envelope sender, or an address set by the -\errors@_to\ option on a router. If the expansion is forced to fail, no -replacement occurs; if it fails for another reason, delivery is deferred. This -option can be used to support VERP (Variable Envelope Return Paths) -- see -chapter ~~CHAPSMTP. - -\**Note**\: If a delivery error is detected locally, -including the case when a remote server rejects a message at SMTP time, -the bounce message is not sent to the value of this option, but to the -previously set errors address (which defaults to the incoming sender address). - - -.conf return@_path@_add boolean false -.index ::Return-path:: header line -If this option is true, a ::Return-path:: header is added to the message. -Although the return path is normally available in the prefix line of BSD -mailboxes, this is commonly not displayed by MUAs, and so the user does not -have easy access to it. - -RFC 2821 states that the ::Return-path:: header is added to a message `when the -delivery SMTP server makes the final delivery'. This implies that this header -should not be present in incoming messages. Exim has a configuration option, -\return@_path@_remove\, which requests removal of this header from incoming -messages, so that delivered messages can safely be resent to other recipients. - -.conf shadow@_condition string$**$ unset -See \shadow@_transport\ below. - -.conf shadow@_transport string unset -.index shadow transport -.index transport||shadow -A local transport may set the \shadow@_transport\ option to the name of another -local transport. Shadow remote transports are not supported. - -Whenever a delivery to the main transport succeeds, and either -\shadow@_condition\ is unset, or its expansion does not result in the empty -string or one of the strings `0' or `no' or `false', the message is also passed -to the shadow transport, with the same delivery address or addresses. -If expansion fails, no action is taken except that non-forced expansion -failures cause a log line to be written. - -The result of the shadow transport is discarded and does not affect the -subsequent processing of the message. Only a single level of shadowing is -provided; the \shadow@_transport\ option is ignored on any transport when it is -running as a shadow. Options concerned with output from pipes are also ignored. - -The log line for the successful delivery has an item added on the end, of the -form -.display -ST=<<shadow transport name>> -.endd -If the shadow transport did not succeed, the error message is put in -parentheses afterwards. - -Shadow transports can be used for a number of different purposes, including -keeping more detailed log information than Exim normally provides, and -implementing automatic acknowledgement policies based on message headers that -some sites insist on. - -.conf transport@_filter string$**$ unset -.index transport||filter -.index filter||transport filter -This option sets up a filtering (in the Unix shell sense) process for messages -at transport time. It should not be confused with mail filtering as set up by -individual users or via a system filter. - -When the message is about to be written out, the command specified by -\transport@_filter\ is started up in a separate process, and the entire -message, including the header lines, is passed to it on its standard input -(this in fact is done from a third process, to avoid deadlock). -The command must be specified as an absolute path. - -.em -The lines of the message that are written to the transport filter are -terminated by newline (`@\n'). -.nem -The message is passed to the filter before any SMTP-specific processing, such -as turning `@\n' into `@\r@\n' and escaping lines beginning with a dot, and -also before any processing implied by the settings of \check@_string\ and -\escape@_string\ in the \%appendfile%\ or \%pipe%\ transports. - -.em -The standard error for the filter process is set to the same destination as its -standard output; this is read and written to the message's ultimate -destination. -.nem -The filter can perform any transformations it likes, but of course should take -care not to break RFC 2822 syntax. A demonstration Perl script is provided in -\(util/transport-filter.pl)\; this makes a few arbitrary modifications just to -show the possibilities. Exim does not check the result, except to test for a -final newline when SMTP is in use. All messages transmitted over SMTP must end -with a newline, so Exim supplies one if it is missing. - -.index SMTP||\\SIZE\\ -A problem might arise if the filter increases the size of a message that is -being sent down an SMTP connection. If the receiving SMTP server has indicated -support for the \\SIZE\\ parameter, Exim will have sent the size of the message -at the start of the SMTP session. If what is actually sent is substantially -more, the server might reject the message. This can be worked round by setting -the \size@_addition\ option on the \%smtp%\ transport, either to allow for -additions to the message, or to disable the use of \\SIZE\\ altogether. - -The value of the \transport@_filter\ option is the command string for starting -the filter, which is run directly from Exim, not under a shell. The string is -parsed by Exim in the same way as a command string for the \%pipe%\ transport: -Exim breaks it up into arguments and then expands each argument separately. The -special argument \$pipe@_addresses$\ is replaced by a number of arguments, one -for each address that applies to this delivery. (This isn't an ideal name for -this feature here, but as it was already implemented for the \%pipe%\ -transport, it seemed sensible not to change it.) - -.index \$host$\ -.index \$host@_address$\ -The expansion variables \$host$\ and \$host@_address$\ are available when the -transport is a remote one. They contain the name and IP address of the host to -which the message is being sent. For example: -.display asis -transport_filter = /some/directory/transport-filter.pl \ - $host $host_address $sender_address $pipe_addresses -.endd -The filter process is run under the same uid and gid as the normal delivery. -For remote deliveries this is the Exim uid/gid by default. -.em -The command should normally yield a zero return code. A non-zero code is taken -to mean that the transport filter failed in some way. Delivery of the message -is deferred. It is not possible to cause a message to be bounced from a -transport filter. -.nem - -If a transport filter is set on an autoreply transport, the original message is -passed through the filter as it is being copied into the newly generated -message, which happens if the \return@_message\ option is set. - -.conf transport@_filter@_timeout time 5m -.index transport||filter, timeout -When Exim is reading the output of a transport filter, it a applies a timeout -that can be set by this option. Exceeding the timeout is treated as a -temporary delivery failure. - - -.conf user string$**$ "Exim user" -.index uid (user id)||local delivery -.index transport||user, specifying -This option specifies the user under whose uid the delivery process is to be -run, overriding any uid that may have been set by the router. If the user is -given as a name, the uid is looked up from the password data, and the -associated group is taken as the value of the gid to be used if the \group\ -option is not set. - -For deliveries that use local transports, a user and group are normally -specified explicitly or implicitly (for example, as a result of -\check@_local@_user\) by the router or transport. - -.index hints database||access by remote transport -For remote transports, you should leave this option unset unless you really are -sure you know what you are doing. When a remote transport is running, it needs -to be able to access Exim's hints databases, because each host may have its own -retry data. - -.endconf - - - - - -. -. -. -. ============================================================================ -.chapter Address batching in local transports -.set runningfoot "address batching" -.rset CHAPbatching ~~chapter -.index transport||local, address batching in -The only remote transport (\%smtp%\) is normally configured to handle more than -one address at a time, so that when several addresses are routed to the same -remote host, just one copy of the message is sent. Local transports, however, -normally handle one address at a time. That is, a separate instance of the -transport is run for each address that is routed to the transport. A separate -copy of the message is delivered each time. - -.index batched local delivery -.index \batch@_max\ -.index \batch@_id\ -In special cases, it may be desirable to handle several addresses at once in a -local transport, for example: -.numberpars $. -In an \%appendfile%\ transport, when storing messages in files for later -delivery by some other means, a single copy of the message with multiple -recipients saves space. -.nextp -In an \%lmtp%\ transport, when delivering over `local SMTP' to some process, -a single copy saves time, and is the normal way LMTP is expected to work. -.nextp -In a \%pipe%\ transport, when passing the message -to a scanner program or -to some other delivery mechanism such as UUCP, multiple recipients may be -acceptable. -.endp -The three local transports (\%appendfile%\, \%lmtp%\, and \%pipe%\) all have -the same options for controlling multiple (`batched') deliveries, namely -\batch@_max\ and \batch@_id\. To save repeating the information for each -transport, these options are described here. - -The \batch@_max\ option specifies the maximum number of addresses that can be -delivered together in a single run of the transport. Its default value is one. -When more than one address is routed to a transport that has a \batch@_max\ -value greater than one, the addresses are delivered in a batch (that is, in a -single run of the transport), subject to certain conditions: -.numberpars $. -If any of the transport's options contain a reference to \$local@_part$\, no -batching is possible. -.nextp -If any of the transport's options contain a reference to \$domain$\, only -addresses with the same domain are batched. -.nextp -.index customizing||batching condition -If \batch@_id\ is set, it is expanded for each address, and only those -addresses with the same expanded value are batched. This allows you to specify -customized batching conditions. -Failure of the expansion for any reason, including forced failure, disables -batching, but it does not stop the delivery from taking place. -.nextp -Batched addresses must also have the same errors address (where to send -delivery errors), the same header additions and removals, the same user and -group for the transport, and if a host list is present, the first host must -be the same. -.endp -.index ::Envelope-to:: header line -If the generic \envelope@_to@_add\ option is set for the transport, the -::Envelope-to:: header that is added to the message contains all the addresses -that are batched together. - -The \%appendfile%\ and \%pipe%\ transports have an option called \use@_bsmtp\, -which causes them to deliver the message in `batched SMTP' format, with the -envelope represented as SMTP commands. The \check@_string\ and \escape@_string\ -options are forced to the values -.display asis -check_string = "." -escape_string = ".." -.endd -when batched SMTP is in use. A full description of the batch SMTP mechanism is -given in section ~~SECTbatchSMTP. The \%lmtp%\ transport does not have a -\use@_bsmtp\ option, because it always delivers using the SMTP protocol. - -.index \%pipe%\ transport||with multiple addresses -If you are not using BSMTP, but are using a \%pipe%\ transport, you can include -\$pipe@_addresses$\ as part of the command. This is not a true variable; it is -a bit of magic that causes each of the recipient addresses to be inserted into -the command as a separate argument. This provides a way of accessing all the -addresses that are being delivered in the batch. - -If you are using a batching \%appendfile%\ transport without \use@_bsmtp\, the -only way to preserve the recipient addresses is to set the \envelope@_to@_add\ -option. This causes an ::Envelope-to:: header line to be added to the message, -containing all the recipients. - - - -. -. -. -. ============================================================================ -.chapter The appendfile transport -.set runningfoot "appendfile transport" -.rset CHAPappendfile ~~chapter -.index \%appendfile%\ transport -.index transports||\%appendfile%\ -.index directory creation -.index creating directories -The \%appendfile%\ transport delivers a message by appending it to an existing -file, or by creating an entirely new file in a specified directory. Single -files to which messages are appended can be in the traditional Unix mailbox -format, or optionally in the MBX format supported by the Pine MUA and -University of Washington IMAP daemon, $it{inter alia}. When each message is -being delivered as a separate file, `maildir' format can optionally be used to -give added protection against failures that happen part-way through the -delivery. A third form of separate-file delivery known as `mailstore' is also -supported. For all file formats, Exim attempts to create as many levels of -directory as necessary, provided that \create@_directory\ is set. - -The code for the optional formats is not included in the Exim binary by -default. It is necessary to set \\SUPPORT@_MBX\\, \\SUPPORT@_MAILDIR\\ and/or -\\SUPPORT@_MAILSTORE\\ in \(Local/Makefile)\ to have the appropriate code -included. - -.index quota||system -Exim recognises system quota errors, and generates an appropriate message. Exim -also supports its own quota control within the transport, for use when the -system facility is unavailable or cannot be used for some reason. - -If there is an error while appending to a file (for example, quota exceeded or -partition filled), Exim attempts to reset the file's length and last -modification time back to what they were before. If there is an error while -creating an entirely new file, the new file is removed. - -Before appending to a file, a number of security checks are made, and the -file is locked. A detailed description is given below, after the list of -private options. - -\%appendfile%\ is most commonly used for local deliveries to users' mailboxes. -However, it can also be used as a pseudo-remote transport for putting messages -into files for remote delivery by some means other than Exim. `Batch SMTP' -format is often used in this case (see the \use@_bsmtp\ option). - - -.section The file and directory options -.rset SECTfildiropt "~~chapter.~~section" -The \file\ option specifies a single file, to which the message is appended; -the \directory\ option specifies a directory, in which a new file containing -the message is created. Only one of these two options can be set, and for -normal deliveries to mailboxes, one of them \*must*\ be set. - -However, \%appendfile%\ is also used for delivering messages to files or -directories whose names (or parts of names) are obtained from alias, -forwarding, or filtering operations (for example, a \save\ command in a user's -Exim filter). When such a transport is running, \$local@_part$\ contains the -local part that was aliased or forwarded, and \$address@_file$\ contains the -name (or partial name) of the file or directory generated by the redirection -operation. There are two cases: -.numberpars $. -If neither \file\ nor \directory\ is set, the redirection operation -must specify an absolute path (one that begins with \"/"\). This is the most -common case when users with local accounts use filtering to sort mail into -different folders. See for example, the \%address@_file%\ transport in the -default configuration. If the path ends with a slash, it is assumed to be the -name of a directory. A delivery to a directory can also be forced by setting -\maildir@_format\ or \mailstore@_format\. -.nextp -If \file\ or \directory\ is set for a delivery from a redirection, it is used -to determine the file or directory name for the delivery. Normally, the -contents of \$address@_file$\ are used in some way in the string expansion. -.endp - -.index Sieve filter||configuring \%appendfile%\ -.index Sieve filter||relative mailbox path handling -As an example of the second case, consider an environment where users do not -have home directories. They may be permitted to use Exim filter commands of the -form: -.display asis -save folder23 -.endd -or Sieve filter commands of the form: -.display asis -require "fileinto"; -fileinto "folder23"; -.endd -In this situation, the expansion of \file\ or \directory\ in the transport must -transform the relative path into an appropriate absolute file name. In the case -of Sieve filters, the name \*inbox*\ must be handled. It is the name that is -used as a result of a `keep' action in the filter. This example shows one way -of handling this requirement: -.display asis -file = ${if eq{$address_file}{inbox} \ - {/var/mail/$local_part} \ - {${if eq{${substr_0_1:$address_file}}{/} \ - {$address_file} \ - {$home/mail/$address_file} \ - }} \ - } -.endd -With this setting of \file\, \*inbox*\ refers to the standard mailbox location, -absolute paths are used without change, and other folders are in the \(mail)\ -directory within the home directory. - -\**Note 1**\: While processing an Exim filter, a relative path such as -\(folder23)\ is turned into an absolute path if a home directory is known to -the router. In particular, this is the case if \check@_local@_user\ is set. If -you want to prevent this happening at routing time, you can set -\router@_home@_directory\ empty. This forces the router to pass the relative -path to the transport. - -\**Note 2**\: An absolute path in \$address@_file$\ is not treated specially; -the \file\ or \directory\ option is still used if it is set. - - - -.section Private options for appendfile -.index options||\%appendfile%\ transport - -.startconf appendfile - -.conf allow@_fifo boolean false -.index fifo (named pipe) -.index named pipe (fifo) -.index pipe||named (fifo) -Setting this option permits delivery to named pipes (FIFOs) as well as to -regular files. If no process is reading the named pipe at delivery time, the -delivery is deferred. - -.conf allow@_symlink boolean false -.index symbolic link||to mailbox -.index mailbox||symbolic link -By default, \%appendfile%\ will not deliver if the path name for the file is -that of a symbolic link. Setting this option relaxes that constraint, but there -are security issues involved in the use of symbolic links. Be sure you know -what you are doing if you set this. Details of exactly what this option affects -are included in the discussion which follows this list of options. - -.conf batch@_id string$**$ unset -See the description of local delivery batching in chapter ~~CHAPbatching. -However, batching is automatically disabled for \%appendfile%\ deliveries that -happen as a result of forwarding or aliasing or other redirection directly to a -file. - -.conf batch@_max integer 1 -See the description of local delivery batching in chapter ~~CHAPbatching. - -.conf check@_group boolean false -When this option is set, the group owner of the file defined by the \file\ -option is checked to see that it is the same as the group under which the -delivery process is running. The default setting is false because the default -file mode is 0600, which means that the group is irrelevant. - -.conf check@_owner boolean true -When this option is set, the owner of the file defined by the \file\ option is -checked to ensure that it is the same as the user under which the delivery -process is running. - -.conf check@_string string "see below" -.index `From' line -As \%appendfile%\ writes the message, the start of each line is tested for -matching \check@_string\, and if it does, the initial matching characters are -replaced by the contents of \escape@_string\. The value of \check@_string\ is a -literal string, not a regular expression, and the case of any letters it -contains is significant. - -If \use@_bsmtp\ is set the values of \check@_string\ and \escape@_string\ are -forced to `.' and `..' respectively, and any settings in the configuration are -ignored. Otherwise, they default to `From ' and `>From ' when the \file\ option -is set, and unset when -any of the \directory\, \maildir\, or \mailstore\ options are set. - -The default settings, along with \message@_prefix\ and \message@_suffix\, are -suitable for traditional `BSD' mailboxes, where a line beginning with `From ' -indicates the start of a new message. All four options need changing if another -format is used. For example, to deliver to mailboxes in MMDF format: -.index MMDF format mailbox -.index mailbox||MMDF format -.display asis -check_string = "\1\1\1\1\n" -escape_string = "\1\1\1\1 \n" -message_prefix = "\1\1\1\1\n" -message_suffix = "\1\1\1\1\n" -.endd - -.index directory creation -.conf create@_directory boolean true -When this option is true, Exim attempts to create any missing superior -directories for the file that it is about to write. A created directory's mode -is given by the \directory@_mode\ option. -.em -The group ownership of a newly created directory is highly dependent on the -operating system (and possibly the file system) that is being used. For -example, in Solaris, if the parent directory has the setgid bit set, its group -is propagated to the child; if not, the currently set group is used. However, -in FreeBSD, the parent's group is always used. -.nem - -.conf create@_file string "anywhere" -This option constrains the location of files and directories that are created -by this transport. It applies to files defined by the \file\ option and -directories defined by the \directory\ option. In the case of maildir delivery, -it applies to the top level directory, not the maildir directories beneath. - -The option must be set to one of the words `anywhere', `inhome', or -`belowhome'. In the second and third cases, a home directory must have been set -for the transport. This option is not useful when an explicit file name is -given for normal mailbox deliveries. It is intended for the case when file -names are generated from users' \(.forward)\ files. These are usually handled -by an \%appendfile%\ transport called \address@_file\. See also -\file@_must@_exist\. - -.conf directory string$**$ unset -This option is mutually exclusive with the \file\ option, but one of \file\ or -\directory\ must be set, unless the delivery is the direct result of a -redirection (see section ~~SECTfildiropt). - -When \directory\ is set, the string is expanded, and the message is delivered -into a new file or files in or below the given directory, instead of being -appended to a single mailbox file. A number of different formats are provided -(see \maildir@_format\ and \mailstore@_format\), and see section ~~SECTopdir -for further details of this form of delivery. - -.conf directory@_file string$**$ "$tt{q@$@{base62:@$tod@_epoch@}-@$inode}" -.index base62 -When \directory\ is set, but neither \maildir@_format\ nor \mailstore@_format\ -is set, \%appendfile%\ delivers each message into a file whose name is obtained -by expanding this string. The default value generates a unique name from the -current time, in base 62 form, and the inode of the file. The variable -\$inode$\ is available only when expanding this option. - -.conf directory@_mode "octal integer" 0700 -If \%appendfile%\ creates any directories as a result of the \create@_directory\ -option, their mode is specified by this option. - -.conf escape@_string string "see description" -See \check@_string\ above. - -.conf file string$**$ unset -This option is mutually exclusive with the \directory\ option, but one of -\file\ or \directory\ must be set, unless the delivery is the direct result of -a redirection (see section ~~SECTfildiropt). The \file\ option specifies a -single file, to which the message is appended. One or more of -\use@_fcntl@_lock\, \use@_flock@_lock\, or \use@_lockfile\ must be set with -\file\. -.index NFS||lock file -.index locking files -.index lock files -If you are using more than one host to deliver over NFS into the same -mailboxes, you should always use lock files. - -The string value is expanded for each delivery, and must yield an absolute -path. The most common settings of this option are variations on one of these -examples: -.display asis -file = /var/spool/mail/$local_part -file = /home/$local_part/inbox -file = $home/inbox -.endd -.index `sticky' bit -In the first example, all deliveries are done into the same directory. If Exim -is configured to use lock files (see \use@_lockfile\ below) it must be able to -create a file in the directory, so the `sticky' bit must be turned on for -deliveries to be possible, or alternatively the \group\ option can be used to -run the delivery under a group id which has write access to the directory. - - -.conf file@_format string unset -.index file||mailbox, checking existing format -This option requests the transport to check the format of an existing file -before adding to it. The check consists of matching a specific string at the -start of the file. The value of the option consists of an even number of -colon-separated strings. The first of each pair is the test string, and the -second is the name of a transport. If the transport associated with a matched -string is not the current transport, control is passed over to the other -transport. For example, suppose the standard \%local@_delivery%\ transport has -this added to it: -.display asis -file_format = "From : local_delivery :\ - \1\1\1\1\n : local_mmdf_delivery" -.endd -Mailboxes that begin with `From' are still handled by this transport, but if a -mailbox begins with four binary ones followed by a newline, control is passed -to a transport called \local__mmdf__delivery\, which presumably is configured -to do the delivery in MMDF format. If a mailbox does not exist or is empty, it -is assumed to match the current transport. If the start of a mailbox doesn't -match any string, or if the transport named for a given string is not defined, -delivery is deferred. - -.conf file@_must@_exist boolean false -If this option is true, the file specified by the \file\ option must exist, and -an error occurs if it does not. Otherwise, it is created if it does not exist. - -.conf lock@_fcntl@_timeout time 0s -.index timeout||mailbox locking -.index mailbox locking||blocking and non-blocking -.index locking files -By default, the \%appendfile%\ transport uses non-blocking calls to \*fcntl()*\ -when locking an open mailbox file. If the call fails, the delivery process -sleeps for \lock@_interval\ and tries again, up to \lock@_retries\ times. -Non-blocking calls are used so that the file is not kept open during the wait -for the lock; the reason for this is to make it as safe as possible for -deliveries over NFS in the case when processes might be accessing an NFS -mailbox without using a lock file. This should not be done, but -misunderstandings and hence misconfigurations are not unknown. - -On a busy system, however, the performance of a non-blocking lock approach is -not as good as using a blocking lock with a timeout. In this case, the waiting -is done inside the system call, and Exim's delivery process acquires the lock -and can proceed as soon as the previous lock holder releases it. - -If \lock@_fcntl@_timeout\ is set to a non-zero time, blocking locks, with that -timeout, are used. There may still be some retrying: the maximum number of -retries is -.display asis -(lock_retries * lock_interval) / lock_fcntl_timeout -.endd -rounded up to the next whole number. In other words, the total time during -which \%appendfile%\ is trying to get a lock is roughly the same, unless -\lock@_fcntl@_timeout\ is set very large. - -You should consider setting this option if you are getting a lot of delayed -local deliveries because of errors of the form -.display asis -failed to lock mailbox /some/file (fcntl) -.endd - -.conf lock@_flock@_timeout time 0s -This timeout applies to file locking when using \*flock()*\ (see \use@_flock\); -the timeout operates in a similar manner to \lock@_fcntl@_timeout\. - -.conf lock@_interval time 3s -This specifies the time to wait between attempts to lock the file. See below -for details of locking. - -.conf lock@_retries integer 10 -This specifies the maximum number of attempts to lock the file. A value of zero -is treated as 1. See below for details of locking. - -.conf lockfile@_mode "octal integer" 0600 -This specifies the mode of the created lock file, when a lock file is being -used (see \use@_lockfile\). - -.conf lockfile@_timeout time 30m -.index timeout||mailbox locking -When a lock file is being used (see \use@_lockfile\), if a lock file already -exists and is older than this value, it is assumed to have been left behind by -accident, and Exim attempts to remove it. - -.em -.conf mailbox@_filecount string$**$ unset -.index mailbox||specifying size of -.index size||of mailbox -If this option is set, it is expanded, and the result is taken as the current -number of files in the mailbox. It must be a decimal number, optionally -followed by K or M. This provides a way of obtaining this information from an -external source that maintains the data. - -.conf mailbox@_size string$**$ unset -.index mailbox||specifying size of -.index size||of mailbox -If this option is set, it is expanded, and the result is taken as the current -size the mailbox. It must be a decimal number, optionally followed by K or M. -This provides a way of obtaining this information from an external source that -maintains the data. This is likely to be helpful for maildir deliveries where -it is computationally expensive to compute the size of a mailbox. -.nem - -.conf maildir@_format boolean false -.index maildir format||specifying -If this option is set with the \directory\ option, the delivery is into a new -file, in the `maildir' format that is used by other mail software. When the -transport is activated directly from a \%redirect%\ router (for example, the -\%address@_file%\ transport in the default configuration), setting -\maildir@_format\ causes the path received from the router to be treated as a -directory, whether or not it ends with \"/"\. This option is available only if -\\SUPPORT@_MAILDIR\\ is present in \(Local/Makefile)\. See section -~~SECTmaildirdelivery below for further details. - -.conf maildir@_quota@_directory@_regex string "See below" -.index maildir format||quota, directories included in -.index quota||maildir, directories included in -This option is relevant only when \maildir@_use@_size@_file\ is set. It defines -a regular expression for specifying directories that should be included in the -quota calculation. The default value is -.display asis -maildir_quota_directory_regex = ^(?:cur|new|\..*)$ -.endd -which includes the \(cur)\ and \(new)\ directories, and any maildir++ folders -(directories whose names begin with a dot). If you want to exclude the -\(Trash)\ -folder from the count (as some sites do), you need to change this setting to -.display asis -maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ -.endd -This uses a negative lookahead in the regular expression to exclude the -directory whose name is \(.Trash)\. - -.conf maildir@_retries integer 10 -This option specifies the number of times to retry when writing a file in -`maildir' format. See section ~~SECTmaildirdelivery below. - -.conf maildir@_tag string$**$ unset -This option applies only to deliveries in maildir format, and is described in -section ~~SECTmaildirdelivery below. - -.conf maildir@_use@_size@_file boolean false -.index maildir format||\(maildirsize)\ file -Setting this option true enables support for \(maildirsize)\ files. Exim -creates a \(maildirsize)\ file in a maildir if one does not exist, taking the -quota from the \quota\ option of the transport. If \quota\ is unset, the value -is zero. See section ~~SECTmaildirdelivery below for further details. - -.conf mailstore@_format boolean false -.index mailstore format||specifying -If this option is set with the \directory\ option, the delivery is into two new -files in `mailstore' format. The option is available only if -\\SUPPORT@_MAILSTORE\\ is present in \(Local/Makefile)\. See section -~~SECTopdir below for further details. - -.conf mailstore@_prefix string$**$ unset -This option applies only to deliveries in mailstore format, and is described in -section ~~SECTopdir below. - -.conf mailstore@_suffix string$**$ unset -This option applies only to deliveries in mailstore format, and is described in -section ~~SECTopdir below. - -.conf mbx@_format boolean false -.index locking files -.index file||locking -.index file||MBX format -.index MBX format, specifying -This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ -set in \(Local/Makefile)\. If \mbx@_format\ is set with the \file\ option, -the message is appended to the mailbox file in MBX format instead of -traditional Unix format. This format is supported by Pine4 and its associated -IMAP and POP daemons, by means of the \*c-client*\ library that they all use. - -\**Note**\: The \message@_prefix\ and \message@_suffix\ options are not -automatically changed by the use of \mbx@_format\. They should normally be set -empty when using MBX format, so this option almost always appears in this -combination: -.display asis -mbx_format = true -message_prefix = -message_suffix = -.endd - -If none of the locking options are mentioned in the configuration, -\use@_mbx@_lock\ is assumed and the other locking options default to false. It -is possible to specify the other kinds of locking with \mbx@_format\, but -\use@_fcntl@_lock\ and \use@_mbx@_lock\ are mutually exclusive. MBX locking -interworks with \*c-client*\, providing for shared access to the mailbox. It -should not be used if any program that does not use this form of locking is -going to access the mailbox, nor should it be used if the mailbox file is NFS -mounted, because it works only when the mailbox is accessed from a single host. - -If you set \use@_fcntl@_lock\ with an MBX-format mailbox, you cannot use -the standard version of \*c-client*\, because as long as it has a mailbox open -(this means for the whole of a Pine or IMAP session), Exim will not be able to -append messages to it. - -.conf message@_prefix string$**$ "see below" -.index `From' line -The string specified here is expanded and output at the start of every message. -The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in -which case it is: -.display asis -message_prefix = "From ${if def:return_path{$return_path}\ - {MAILER-DAEMON}} $tod_bsdinbox\n" -.endd - -.conf message@_suffix string$**$ "see below" -The string specified here is expanded and output at the end of every message. -The default is unset unless \file\ is specified and \use@_bsmtp\ is not set, in -which case it is a single newline character. The suffix can be suppressed by -setting -.display asis -message_suffix = -.endd - -.conf mode "octal integer" 0600 -If the output file is created, it is given this mode. If it already exists and -has wider permissions, they are reduced to this mode. If it has narrower -permissions, an error occurs unless \mode__fail__narrower\ is false. However, -if the delivery is the result of a \save\ command in a filter file specifing a -particular mode, the mode of the output file is always forced to take that -value, and this option is ignored. - -.conf mode@_fail@_narrower boolean true -This option applies in the case when an existing mailbox file has a narrower -mode than that specified by the \mode\ option. If \mode@_fail@_narrower\ is -true, the delivery is deferred (`mailbox has the wrong mode'); otherwise Exim -continues with the delivery attempt, using the existing mode of the file. - -.conf notify@_comsat boolean false -If this option is true, the \*comsat*\ daemon is notified after every successful -delivery to a user mailbox. This is the daemon that notifies logged on users -about incoming mail. - -.conf quota string$**$ unset -.index quota||imposed by Exim -This option imposes a limit on the size of the file to which Exim is appending, -or to the total space used in the directory tree when the \directory\ option is -set. In the latter case, computation of the space used is expensive, because -all the files in the directory (and any sub-directories) have to be -individually inspected and their sizes summed. -(See \quota@_size@_regex\ and \maildir@_use@_size@_file\ for ways to avoid this -in environments where users have no shell access to their mailboxes). - -As there is no interlock against two simultaneous deliveries into a -multi-file mailbox, it is possible for the quota to be overrun in this case. -For single-file mailboxes, of course, an interlock is a necessity. - -A file's size is taken as its \*used*\ value. Because of blocking effects, this -may be a lot less than the actual amount of disk space allocated to the file. -If the sizes of a number of files are being added up, the rounding effect can -become quite noticeable, especially on systems that have large block sizes. -Nevertheless, it seems best to stick to the \*used*\ figure, because this is -the obvious value which users understand most easily. - -The value of the option is expanded, and must then be a numerical value -(decimal point allowed), optionally followed by one of the letters K or M. The -expansion happens while Exim is running as root, before it changes uid for the -delivery. This means that files which are inaccessible to the end user can be -used to hold quota values that are looked up in the expansion. When delivery -fails because this quota is exceeded, the handling of the error is as for -system quota failures. - -\**Note**\: A value of zero is interpreted as `no quota'. - -By default, Exim's quota checking mimics system quotas, and restricts the -mailbox to the specified maximum size, though the value is not accurate to the -last byte, owing to separator lines and additional headers that may get added -during message delivery. When a mailbox is nearly full, large messages may get -refused even though small ones are accepted, because the size of the current -message is added to the quota when the check is made. This behaviour can be -changed by setting \quota@_is@_inclusive\ false. When this is done, the check -for exceeding the quota does not include the current message. Thus, deliveries -continue until the quota has been exceeded; thereafter, no further messages are -delivered. See also \quota@_warn@_threshold\. - -.conf quota@_directory string$**$ unset -This option defines the directory to check for quota purposes when delivering -into individual files. The default is the delivery directory, or, if a file -called \(maildirfolder)\ exists in a maildir directory, the parent of the -delivery directory. - -.conf quota@_filecount string$**$ 0 -This option applies when the \directory\ option is set. It limits the total -number of files in the directory (compare the inode limit in system quotas). It -can only be used if \quota\ is also set. The value is expanded; an expansion -failure causes delivery to be deferred. - -.conf quota@_is@_inclusive boolean true -See \quota\ above. - -.conf quota@_size@_regex string unset -This option applies when one of the delivery modes that writes a separate file -for each message is being used. When Exim wants to find the size of one of -these files in order to test the quota, it first checks \quota@_size@_regex\. -If this is set to a regular expression that matches the file name, and it -captures one string, that string is interpreted as a representation of the -file's size. The value of \quota@_size@_regex\ is not expanded. - -This feature is useful only when users have no shell access to their mailboxes --- otherwise they could defeat the quota simply by renaming the files. This -facility can be used with maildir deliveries, by setting \maildir@_tag\ to add -the file length to the file name. For example: -.display asis -maildir_tag = ,S=$message_size -quota_size_regex = ,S=(\d+) -.endd -The regular expression should not assume that the length is at the end of the -file name (even though \maildir@_tag\ puts it there) because maildir MUAs -sometimes add other information onto the ends of message file names. - -.conf quota@_warn@_message string$**$ "see below" -See below for the use of this option. If it is not set when -\quota@_warn@_threshold\ is set, it defaults to -.display asis -quota_warn_message = "\ - To: $local_part@$domain\n\ - Subject: Your mailbox\n\n\ - This message is automatically created \ - by mail delivery software.\n\n\ - The size of your mailbox has exceeded \ - a warning threshold that is\n\ - set by the system administrator.\n" -.endd - -.conf quota@_warn@_threshold string$**$ 0 -.index quota||warning threshold -.index mailbox||size warning -.index size||of mailbox -This option is expanded in the same way as \quota\ (see above). If the -resulting value is greater than zero, and delivery of the message causes the -size of the file or total space in the directory tree to cross the given -threshold, a warning message is sent. If \quota\ is also set, the threshold may -be specified as a percentage of it by following the value with a percent sign. -For example: -.display asis -quota = 10M -quota_warn_threshold = 75% -.endd -If \quota\ is not set, a setting of \quota@_warn@_threshold\ that ends with a -percent sign is ignored. - -The warning message itself is specified by the \quota@_warn@_message\ option, -and it must start with a ::To:: header line containing the recipient(s). A -::Subject:: line should also normally be supplied. The \quota\ option does not -have to be set in order to use this option; they are independent of one -another except when the threshold is specified as a percentage. - -.conf use@_bsmtp boolean false -.index envelope sender -If this option is set true, \%appendfile%\ writes messages in `batch SMTP' -format, with the envelope sender and recipient(s) included as SMTP commands. If -you want to include a leading \\HELO\\ command with such messages, you can do -so by setting the \message@_prefix\ option. See section ~~SECTbatchSMTP for -details of batch SMTP. - -.conf use@_crlf boolean false -.index carriage return -.index linefeed -This option causes lines to be terminated with the two-character CRLF sequence -(carriage return, linefeed) instead of just a linefeed character. In the case -of batched SMTP, the byte sequence written to the file is then an exact image -of what would be sent down a real SMTP connection. - -The contents of the \message@_prefix\ and \message@_suffix\ options are written -verbatim, so must contain their own carriage return characters if these are -needed. In cases where these options have non-empty defaults, the values end -with a single linefeed, so they -must -be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. - -.conf use@_fcntl@_lock boolean "see below" -This option controls the use of the \*fcntl()*\ function to lock a file for -exclusive use when a message is being appended. It is set by default unless -\use@_flock@_lock\ is set. Otherwise, it should be turned off only if you know -that all your MUAs use lock file locking. When both \use@_fcntl@_lock\ and -\use@_flock@_lock\ are unset, \use@_lockfile\ must be set. - -.conf use@_flock@_lock boolean false -This option is provided to support the use of \*flock()*\ for file locking, for -the few situations where it is needed. Most modern operating systems support -\*fcntl()*\ and \*lockf()*\ locking, and these two functions interwork with -each other. Exim uses \*fcntl()*\ locking by default. - -This option is required only if you are using an operating system where -\*flock()*\ is used by programs that access mailboxes (typically MUAs), and -where \*flock()*\ does not correctly interwork with \*fcntl()*\. You can use -both \*fcntl()*\ and \*flock()*\ locking simultaneously if you want. - -.index Solaris||\*flock()*\ support -Not all operating systems provide \*flock()*\. Some versions of Solaris do not -have it (and some, I think, provide a not quite right version built on top of -\*lockf()*\). If the OS does not have \*flock()*\, Exim will be built without -the ability to use it, and any attempt to do so will cause a configuration -error. - -\**Warning**\: \*flock()*\ locks do not work on NFS files (unless \*flock()*\ -is just being mapped onto \*fcntl()*\ by the OS). - -.conf use@_lockfile boolean "see below" -If this option is turned off, Exim does not attempt to create a lock file when -appending to a mailbox file. In this situation, the only locking is by -\*fcntl()*\. You should only turn \use@_lockfile\ off if you are absolutely -sure that every MUA that is ever going to look at your users' mailboxes uses -\*fcntl()*\ rather than a lock file, and even then only when you are not -delivering over NFS from more than one host. - -.index NFS||lock file -In order to append to an NFS file safely from more than one host, it is -necessary to take out a lock $it{before} opening the file, and the lock file -achieves this. Otherwise, even with \*fcntl()*\ locking, there is a risk of -file corruption. - -The \use@_lockfile\ option is set by default unless \use@_mbx@_lock\ is set. It -is not possible to turn both \use@_lockfile\ and \use@_fcntl@_lock\ off, except -when \mbx@_format\ is set. - -.conf use@_mbx@_lock boolean "see below" -This option is available only if Exim has been compiled with \\SUPPORT@_MBX\\ -set in \(Local/Makefile)\. Setting the option specifies that special MBX -locking rules be used. It is set by default if \mbx@_format\ is set and none of -the locking options are mentioned in the configuration. The locking rules are -the same as are used by the \*c-client*\ library that underlies Pine and the -IMAP4 and POP daemons that come with it (see the discussion below). The rules -allow for shared access to the mailbox. However, this kind of locking does not -work when the mailbox is NFS mounted. - -You can set \use@_mbx@_lock\ with either (or both) of \use@_fcntl@_lock\ and -\use@_flock@_lock\ to control what kind of locking is used in implementing the -MBX locking rules. The default is to use \*fcntl()*\ if \use@_mbx@_lock\ is set -without \use@_fcntl@_lock\ or \use@_flock@_lock\. -.endconf - - -.section Operational details for appending -.rset SECTopappend "~~chapter.~~section" -.index appending to a file -.index file||appending -Before appending to a file, the following preparations are made: -.numberpars $. -If the name of the file is \(/dev/null)\, no action is taken, and a success -return is given. -.nextp -.index directory creation -If any directories on the file's path are missing, Exim creates them if the -\create@_directory\ option is set. A created directory's mode is given by the -\directory@_mode\ option. -.nextp -If \file@_format\ is set, the format of an existing file is checked. If this -indicates that a different transport should be used, control is passed to that -transport. -.nextp -.index file||locking -.index locking files -.index NFS||lock file -If \use@_lockfile\ is set, a lock file is built in a way that will work -reliably over NFS, as follows: -.numberpars $. -Create a `hitching post' file whose name is that of the lock file with the -current time, primary host name, and process id added, by opening for writing -as a new file. If this fails with an access error, delivery is deferred. -.nextp -Close the hitching post file, and hard link it to the lock file name. -.nextp -If the call to \*link()*\ succeeds, creation of the lock file has succeeded. -Unlink the hitching post name. -.nextp -Otherwise, use \*stat()*\ to get information about the hitching post file, and -then unlink hitching post name. If the number of links is exactly two, creation -of the lock file succeeded but something (for example, an NFS server crash and -restart) caused this fact not to be communicated to the \*link()*\ call. -.nextp -If creation of the lock file failed, wait for \lock@_interval\ and try again, -up to \lock@_retries\ times. However, since any program that writes to a -mailbox should complete its task very quickly, it is reasonable to time out old -lock files that are normally the result of user agent and system crashes. If an -existing lock file is older than \lockfile@_timeout\ Exim attempts to unlink it -before trying again. -.endp -.nextp -A call is made to \*lstat()*\ to discover whether the main file exists, and if -so, what its characteristics are. If \*lstat()*\ fails for any reason other -than non-existence, delivery is deferred. -.nextp -.index symbolic link||to mailbox -.index mailbox||symbolic link -If the file does exist and is a symbolic link, delivery is deferred, unless the -\allow@_symlink\ option is set, in which case the ownership of the link is -checked, and then \*stat()*\ is called to find out about the real file, which -is then subjected to the checks below. The check on the top-level link -ownership prevents one user creating a link for another's mailbox in a sticky -directory, though allowing symbolic links in this case is definitely not a good -idea. If there is a chain of symbolic links, the intermediate ones are not -checked. -.nextp -If the file already exists but is not a regular file, or if the file's owner -and group (if the group is being checked -- see \check@_group\ above) are -different from the user and group under which the delivery is running, -delivery is deferred. -.nextp -If the file's permissions are more generous than specified, they are reduced. -If they are insufficient, delivery is deferred, unless \mode@_fail@_narrower\ -is set false, in which case the delivery is tried using the existing -permissions. -.nextp -The file's inode number is saved, and the file is then opened for appending. If -this fails because the file has vanished, \%appendfile%\ behaves as if it hadn't -existed (see below). For any other failures, delivery is deferred. -.nextp -If the file is opened successfully, check that the inode number hasn't -changed, that it is still a regular file, and that the owner and permissions -have not changed. If anything is wrong, defer delivery and freeze the message. -.nextp -If the file did not exist originally, defer delivery if the \file@_must@_exist\ -option is set. Otherwise, check that the file is being created in a permitted -directory if the \create@_file\ option is set (deferring on failure), and then -open for writing as a new file, with the \\O@_EXCL\\ and \\O@_CREAT\\ options, -except when dealing with a symbolic link (the \allow@_symlink\ option must be -set). In this case, which can happen if the link points to a non-existent file, -the file is opened for writing using \\O@_CREAT\\ but not \\O@_EXCL\\, because -that prevents link following. -.nextp -.index loop||while file testing -If opening fails because the file exists, obey the tests given above for -existing files. However, to avoid looping in a situation where the file is -being continuously created and destroyed, the exists/not-exists loop is broken -after 10 repetitions, and the message is then frozen. -.nextp -If opening fails with any other error, defer delivery. -.nextp -.index file||locking -.index locking files -Once the file is open, unless both \use@_fcntl@_lock\ and \use@_flock@_lock\ -are false, it is locked using \*fcntl()*\ or \*flock()*\ or both. If -\use@_mbx@_lock\ is false, an exclusive lock is requested in each case. -However, if \use@_mbx@_lock\ is true, -Exim takes out a shared lock on the open file, -and an exclusive lock on the file whose name is -.display -/tmp/.<<device-number>>.<<inode-number>> -.endd -using the device and inode numbers of the open mailbox file, in accordance with -the MBX locking rules. - -If Exim fails to lock the file, there are two possible courses of action, -depending on the value of the locking timeout. This is obtained from -\lock@_fcntl@_timeout\ or \lock@_flock@_timeout\, as appropriate. - -If the timeout value is zero, the file is closed, Exim waits for -\lock@_interval\, and then goes back and re-opens the file as above and tries -to lock it again. This happens up to \lock@_retries\ times, after which the -delivery is deferred. - -If the timeout has a value greater than zero, blocking calls to \*fcntl()*\ or -\*flock()*\ are used (with the given timeout), so there has already been some -waiting involved by the time locking fails. Nevertheless, Exim does not give up -immediately. It retries up to -.display -(lock@_retries * lock@_interval) / <<timeout>> -.endd -times (rounded up). -.endp - -At the end of delivery, Exim closes the file (which releases the \*fcntl()*\ -and/or \*flock()*\ locks) and then deletes the lock file if one was created. - -.section Operational details for delivery to a new file -.rset SECTopdir "~~chapter.~~section" -.index delivery||to single file -.index `From' line -When the \directory\ option is set instead of \file\, each message is delivered -into a newly-created file or set of files. When \%appendfile%\ is activated -directly from a \%redirect%\ router, neither \file\ nor \directory\ is normally -set, because the path for delivery is supplied by the router. (See for example, -the \%address@_file%\ transport in the default configuration.) In this case, -delivery is to a new file if either the path name ends in \"/"\, or the -\maildir@_format\ or \mailstore@_format\ option is set. - -No locking is required while writing the message to a new file, so the various -locking options of the transport are ignored. The `From' line that by default -separates messages in a single file is not normally needed, nor is the escaping -of message lines that start with `From', and there is no need to ensure a -newline at the end of each message. Consequently, the default values for -\check@_string\, \message@_prefix\, and \message@_suffix\ are all unset when -any of \directory\, \maildir@_format\, or \mailstore@_format\ is set. - -If Exim is required to check a \quota\ setting, it adds up the sizes of all the -files in the delivery directory by default. However, you can specify a -different directory by setting \quota@_directory\. Also, for maildir deliveries -(see below) the \(maildirfolder)\ convention is honoured. - - -.index maildir format -.index mailstore format -There are three different ways in which delivery to individual files can be -done, controlled by the settings of the \maildir@_format\ and -\mailstore@_format\ options. Note that code to support maildir or mailstore -formats is not included in the binary unless \\SUPPORT@_MAILDIR\\ or -\\SUPPORT@_MAILSTORE\\, respectively, is set in \(Local/Makefile)\. - -.index directory creation -In all three cases an attempt is made to create the directory and any necessary -sub-directories if they do not exist, provided that the \create@_directory\ -option is set (the default). The location of a created directory can be -constrained by setting \create@_file\. A created directory's mode is given by -the \directory@_mode\ option. If creation fails, or if the \create@_directory\ -option is not set when creation is required, delivery is deferred. - - -.section Maildir delivery -.rset SECTmaildirdelivery "~~chapter.~~section" -.index maildir format||description of -If the \maildir@_format\ option is true, Exim delivers each message by writing -it to a file whose name is \(tmp/<<stime>>.H<<mtime>>P<<pid>>.<<host>>)\ in the -given directory. If the delivery is successful, the file is renamed into the -\(new)\ subdirectory. - -In the file name, <<stime>> is the current time of day in seconds, and -<<mtime>> is the microsecond fraction of the time. After a maildir delivery, -Exim checks that the time-of-day clock has moved on by at least one microsecond -before terminating the delivery process. This guarantees uniqueness for the -file name. However, as a precaution, Exim calls \*stat()*\ for the file before -opening it. If any response other than \\ENOENT\\ (does not exist) is given, -Exim waits 2 seconds and tries again, up to \maildir@_retries\ times. - -.index quota||in maildir delivery -.index maildir++ -If Exim is required to check a \quota\ setting before a maildir delivery, and -\quota@_directory\ is not set, it looks for a file called \(maildirfolder)\ in -the maildir directory (alongside \(new)\, \(cur)\, \(tmp)\). If this exists, -Exim assumes the directory is a maildir++ folder directory, which is one level -down from the user's top level mailbox directory. This causes it to start at -the parent directory instead of the current directory when calculating the -amount of space used. - -.em -One problem with delivering into a multi-file mailbox is that it is -computationally expensive to compute the size of the mailbox for quota -checking. Various approaches have been taken to reduce the amount of work -needed. The next two sections describe two of them. A third alternative is to -use some external process for maintaining the size data, and use the expansion -of the \mailbox@_size\ option as a way of importing it into Exim. -.nem - - -.section Using tags to record message sizes -If \maildir@_tag\ is set, the string is expanded for each delivery. -When the maildir file is renamed into the \(new)\ sub-directory, the -tag is added to its name. However, if adding the tag takes the length of the -name to the point where the test \*stat()*\ call fails with \\ENAMETOOLONG\\, -the tag is dropped and the maildir file is created with no tag. - -Tags can be used to encode the size of files in their names; see -\quota@_size@_regex\ above for an example. The expansion of \maildir@_tag\ -happens after the message has been written. The value of the \$message@_size$\ -variable is set to the number of bytes actually written. If the expansion is -forced to fail, the tag is ignored, but a non-forced failure causes delivery to -be deferred. The expanded tag may contain any printing characters except `/'. -Non-printing characters in the string are ignored; if the resulting string is -empty, it is ignored. If it starts with an alphanumeric character, a leading -colon is inserted. - - -.section Using a maildirsize file -.index quota||in maildir delivery -.index maildir format||\(maildirsize)\ file -If \maildir@_use@_size@_file\ is true, Exim implements the maildir++ rules for -storing quota and message size information in a file called \(maildirsize)\ -within the maildir directory. If this file does not exist, Exim creates it, -setting the quota from the \quota\ option of the transport. If the maildir -directory itself does not exist, it is created before any attempt to write a -\(maildirsize)\ file. - -The \(maildirsize)\ file is used to hold information about the sizes of -messages in the maildir, thus speeding up quota calculations. The quota value -in the file is just a cache; if the quota is changed in the transport, the new -value overrides the cached value when the next message is delivered. The cache -is maintained for the benefit of other programs that access the maildir and -need to know the quota. - -If the \quota\ option in the transport is unset or zero, the \(maildirsize)\ -file is maintained (with a zero quota setting), but no quota is imposed. - -A regular expression is available for controlling which directories in the -maildir participate in quota calculations. See the description of the -\maildir@_quota@_directory@_regex\ option above for details. - - -.section Mailstore delivery -.index mailstore format||description of -If the \mailstore@_format\ option is true, each message is written as two files -in the given directory. A unique base name is constructed from the message id -and the current delivery process, and the files that are written use this base -name plus the suffixes \(.env)\ and \(.msg)\. The \(.env)\ file contains the -message's envelope, and the \(.msg)\ file contains the message itself. - -During delivery, the envelope is first written to a file with the suffix -\(.tmp)\. The \(.msg)\ file is then written, and when it is complete, the -\(.tmp)\ file is renamed as the \(.env)\ file. Programs that access messages in -mailstore format should wait for the presence of both a \(.msg)\ and a \(.env)\ -file before accessing either of them. An alternative approach is to wait for -the absence of a \(.tmp)\ file. - -The envelope file starts with any text defined by the \mailstore@_prefix\ -option, expanded and terminated by a newline if there isn't one. Then follows -the sender address on one line, then all the recipient addresses, one per line. -There can be more than one recipient only if the \batch@_max\ option is set -greater than one. Finally, \mailstore@_suffix\ is expanded and the result -appended to the file, followed by a newline if it does not end with one. - -If expansion of \mailstore@_prefix\ or \mailstore@_suffix\ ends with a forced -failure, it is ignored. Other expansion errors are treated as serious -configuration errors, and delivery is deferred. - - -.section Non-special new file delivery -If neither \maildir@_format\ nor \mailstore@_format\ is set, a single new file -is created directly in the named directory. For example, when delivering -messages into files in batched SMTP format for later delivery to some host (see -section ~~SECTbatchSMTP), a setting such as -.display asis -directory = /var/bsmtp/$host -.endd -might be used. A message is written to a file with a temporary name, which is -then renamed when the delivery is complete. The final name is obtained by -expanding the contents of the \directory@_file\ option. - - - - - -. -. -. -. -. ============================================================================ -.chapter The autoreply transport -.set runningfoot "autoreply transport" -.index transports||\%autoreply%\ -.index \%autoreply%\ transport -The \%autoreply%\ transport is not a true transport in that it does not cause -the message to be transmitted. Instead, it generates a new mail message. -.em -If the router that passes the message to this transport does not have the -\unseen\ option set, the original message (for the current recipient) is not -delivered anywhere. However, when the \unseen\ option is set on the router that -passes the message to this transport, routing of the address continues, so -another router can set up a normal message delivery. -.nem - -The \%autoreply%\ transport is usually run as the result of mail filtering, a -`vacation' message being the standard example. However, it can also be run -directly from a router like any other transport. To reduce the possibility of -message cascades, messages created by the \%autoreply%\ transport always have -empty envelope sender addresses, like bounce messages. - -The parameters of the message to be sent can be specified in the configuration -by options described below. However, these are used only when the address -passed to the transport does not contain its own reply information. When the -transport is run as a consequence of a -\mail\ -or \vacation\ command in a filter file, the parameters of the message are -supplied by the filter, and passed with the address. The transport's options -that define the message are then ignored (so they are not usually set in this -case). The message is specified entirely by the filter or by the transport; it -is never built from a mixture of options. However, the \file@_optional\, -\mode\, and \return@_message\ options apply in all cases. - -\%Autoreply%\ is implemented as a local transport. When used as a result of a -command in a user's filter file, \%autoreply%\ normally runs under the uid and -gid of the user, and with appropriate current and home directories (see chapter -~~CHAPenvironment). - -There is a subtle difference between routing a message to a \%pipe%\ transport -that generates some text to be returned to the sender, and routing it to an -\%autoreply%\ transport. This difference is noticeable only if more than one -address from the same message is so handled. In the case of a pipe, the -separate outputs from the different addresses are gathered up and returned to -the sender in a single message, whereas if \%autoreply%\ is used, a separate -message is generated for each address that is passed to it. - -Non-printing characters are not permitted in the header lines generated for the -message that \%autoreply%\ creates, with the exception of newlines that are -immediately followed by whitespace. If any non-printing characters are found, -the transport defers. -Whether characters with the top bit set count as printing characters or not is -controlled by the \print@_topbitchars\ global option. - -If any of the generic options for manipulating headers (for example, -\headers@_add\) are set on an \%autoreply%\ transport, they apply to the copy of -the original message that is included in the generated message when -\return@_message\ is set. They do not apply to the generated message itself. - -If the \%autoreply%\ transport receives return code 2 from Exim when it submits -the message, indicating that there were no recipients, it does not treat this -as an error. This means that autoreplies sent to \$sender@_address$\ when this -is empty (because the incoming message is a bounce message) do not cause -problems. They are just discarded. - - -.section Private options for autoreply - -.startconf autoreply -.index options||\%autoreply%\ transport -.conf bcc string$**$ unset -This specifies the addresses that are to receive `blind carbon copies' of the -message when the message is specified by the transport. - -.conf cc string$**$ unset -This specifies recipients of the message and the contents of the ::Cc:: header -when the message is specified by the transport. - -.conf file string$**$ unset -The contents of the file are sent as the body of the message when the message -is specified by the transport. If both \file\ and \text\ are set, the text -string comes first. - -.conf file@_expand boolean false -If this is set, the contents of the file named by the \file\ option are -subjected to string expansion as they are added to the message. - -.conf file@_optional boolean false -If this option is true, no error is generated if the file named by the \file\ -option or passed with the address does not exist or cannot be read. - -.conf from string$**$ unset -This specifies the contents of the ::From:: header when the message is specified -by the transport. - -.conf headers string$**$ unset -This specifies additional RFC 2822 headers that are to be added to the message when -the message is specified by the transport. Several can be given by using `@\n' -to separate them. There is no check on the format. - -.conf log string$**$ unset -This option names a file in which a record of every message sent is logged when -the message is specified by the transport. - -.conf mode "octal integer" 0600 -If either the log file or the `once' file has to be created, this mode is used. - -.em -.conf never@_mail "address list$**$" unset -If any run of the transport creates a message with a recipient that matches any -item in the list, that recipient is quietly discarded. If all recipients are -discarded, no message is created. -.nem - -.conf once string$**$ unset -This option names a file or DBM database in which a record of each -::To:: recipient is kept when the message is specified by the transport. -\**Note**\: This does not apply to ::Cc:: or ::Bcc:: recipients. -If \once@_file@_size\ is not set, a DBM database is used, and it is allowed to -grow as large as necessary. If a potential recipient is already in the -database, no message is sent by default. However, if \once@_repeat\ specifies a -time greater than zero, the message is sent if that much time has elapsed since -a message was last sent to this recipient. If \once\ is unset, the message is -always sent. - -If \once@_file@_size\ is set greater than zero, it changes the way Exim -implements the \once\ option. Instead of using a DBM file to record every -recipient it sends to, it uses a regular file, whose size will never get larger -than the given value. In the file, it keeps a linear list of recipient -addresses and times at which they were sent messages. If the file is full when -a new address needs to be added, the oldest address is dropped. If -\once@_repeat\ is not set, this means that a given recipient may receive -multiple messages, but at unpredictable intervals that depend on the rate of -turnover of addresses in the file. If \once@_repeat\ is set, it specifies a -maximum time between repeats. - -.conf once@_file@_size integer 0 -See \once\ above. - -.conf once@_repeat time$**$ 0s -See \once\ above. -After expansion, the value of this option must be a valid time value. - -.conf reply@_to string$**$ unset -This specifies the contents of the ::Reply-To:: header when the message is -specified by the transport. - -.conf return@_message boolean false -If this is set, a copy of the original message is returned with the new -message, subject to the maximum size set in the \return@_size@_limit\ global -configuration option. - -.conf subject string$**$ unset -This specifies the contents of the ::Subject:: header when the message is -specified by the transport. -.em -It is tempting to quote the original subject in automatic responses. 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 your users to an opt-in mailing list, provided that the list accepts -bounce messages as subscription confirmations. Well-managed lists require a -non-bounce message to confirm a subscription, so the danger is relatively -small. -.nem - -.conf text string$**$ unset -This specifies a single string to be used as the body of the message when the -message is specified by the transport. If both \text\ and \file\ are set, the -text comes first. - -.conf to string$**$ unset -This specifies recipients of the message and the contents of the ::To:: header -when the message is specified by the transport. - -.endconf - - - -. -. -. -. -. ============================================================================ -.chapter The lmtp transport -.set runningfoot "lmtp transport" -.index transports||\%lmtp%\ -.index \%lmtp%\ transport -.index LMTP||over a pipe -.index LMTP||over a socket -.rset CHAPLMTP "~~chapter" -The \%lmtp%\ transport runs the LMTP protocol (RFC 2033) over a pipe to a -specified command -or by interacting with a Unix domain socket. -This transport is something of a cross between the \%pipe%\ and \%smtp%\ -transports. Exim also has support for using LMTP over TCP/IP; this is -implemented as an option for the \%smtp%\ transport. Because LMTP is expected -to be of minority interest, the default build-time configure in \(src/EDITME)\ -has it commented out. You need to ensure that -.display asis -TRANSPORT_LMTP=yes -.endd -is present in your \(Local/Makefile)\ in order to have the \%lmtp%\ transport -included in the Exim binary. - -The private options of the \%lmtp%\ transport are as follows: - -.startconf lmtp -.index options||\%lmtp%\ transport - -.conf batch@_id string$**$ unset -See the description of local delivery batching in chapter ~~CHAPbatching. - -.conf batch@_max integer 1 -This limits the number of addresses that can be handled in a single delivery. -Most LMTP servers can handle several addresses at once, so it is normally a -good idea to increase this value. See the description of local delivery -batching in chapter ~~CHAPbatching. - -.conf command string$**$ unset -This option must be set if \socket\ is not set. -The string is a command which is run in a separate process. It is split up into -a command name and list of arguments, each of which is separately expanded (so -expansion cannot change the number of arguments). The command is run directly, -not via a shell. The message is passed to the new process using the standard -input and output to operate the LMTP protocol. - -.conf socket string$**$ unset -This option must be set if \command\ is not set. The result of expansion must -be the name of a Unix domain socket. The transport connects to the socket and -delivers the message to it using the LMTP protocol. - -.conf timeout time 5m -The transport is aborted if the created process -or Unix domain socket -does not respond to LMTP commands or message input within this timeout. - -.endconf - -Here is an example of a typical LMTP transport: -.display asis -lmtp: - driver = lmtp - command = /some/local/lmtp/delivery/program - batch_max = 20 - user = exim -.endd -This delivers up to 20 addresses at a time, in a mixture of domains if -necessary, running as the user \*exim*\. - - - -. -. -. -. -. ============================================================================ -.chapter The pipe transport -.rset CHAPpipetransport "~~chapter" -.set runningfoot "pipe transport" -.index transports||\%pipe%\ -.index \%pipe%\ transport -The \%pipe%\ transport is used to deliver messages via a pipe to a command -running in another process. -.em -One example is the -use of \%pipe%\ as a pseudo-remote transport for passing messages to some other -delivery mechanism (such as UUCP). Another is the use by individual users to -automatically process their incoming messages. The \%pipe%\ transport can be -used in one of the following ways: -.nem -.numberpars $. -A router routes one address to a transport in the normal way, and the transport -is configured as a \%pipe%\ transport. In this case, \$local@_part$\ contains -the local part of the address (as usual), and the command that is run is -specified by the \command\ option on the transport. -.nextp -.em -If the \batch@_max\ option is set greater than 1 (the default), the transport -can be called upon to handle more than one address in a single run. In this -case, \$local@_part$\ is not set (because it is not unique). However, the -pseudo-variable \$pipe@_addresses$\ (described in section ~~SECThowcommandrun -below) contains all the addresses that are being handled. -.nem -.nextp -A router redirects an address directly to a pipe command (for example, from an -alias or forward file). In this case, \$local@_part$\ contains the local part -that was redirected, and \$address@_pipe$\ contains the text of the pipe -command itself. The \command\ option on the transport is ignored. -.endp - -The \%pipe%\ transport is a non-interactive delivery method. Exim can also -deliver messages over pipes using the LMTP interactive protocol. This is -implemented by the \%lmtp%\ transport. - -In the case when \%pipe%\ is run as a consequence of an entry in a local user's -\(.forward)\ file, the command runs under the uid and gid of that user. In -other cases, the uid and gid have to be specified explicitly, either on the -transport or on the router that handles the address. Current and `home' -directories are also controllable. See chapter ~~CHAPenvironment for details of -the local delivery environment. - - -.em -.section Concurrent delivery -If two messages arrive at almost the same time, and both are routed to a pipe -delivery, the two pipe transports may be run concurrently. You must ensure that -any pipe commands you set up are robust against this happening. If the commands -write to a file, the \exim@_lock\ utility might be of use. -.nem - - -.section Returned status and data -.index \%pipe%\ transport||returned data -If the command exits with a non-zero return code, the delivery is deemed to -have failed, unless either the \ignore@_status\ option is set (in which case -the return code is treated as zero), or the return code is one of those listed -in the \temp@_errors\ option, which are interpreted as meaning `try again -later'. In this case, delivery is deferred. Details of a permanent failure are -logged, but are not included in the bounce message, which merely contains -`local delivery failed'. - -If the return code is greater than 128 and the command being run is a shell -script, it normally means that the script was terminated by a signal whose -value is the return code minus 128. - -If Exim is unable to run the command (that is, if \*execve()*\ fails), the -return code is set to 127. This is the value that a shell returns if it is -asked to run a non-existent command. The wording for the log line suggests that -a non-existent command may be the problem. - -The \return@_output\ option can affect the result of a pipe delivery. If it is -set and the command produces any output on its standard output or standard -error streams, the command is considered to have failed, even if it gave a zero -return code or if \ignore@_status\ is set. The output from the command is -included as part of the bounce message. The \return@_fail@_output\ option is -similar, except that output is returned only when the command exits with a -failure return code, that is, a value other than zero or a code that matches -\temp@_errors\. - - -.section How the command is run -.rset SECThowcommandrun "~~chapter.~~section" -.index \%pipe%\ transport||path for command -The command line is (by default) broken down into a command name and arguments -by the \%pipe%\ transport itself. The \allow@_commands\ and \restrict@_to@_path\ -options can be used to restrict the commands that may be run. -.index quoting||in pipe command -Unquoted arguments are delimited by white space. If an argument appears in -double quotes, backslash is interpreted as an escape character in the usual -way. If an argument appears in single quotes, no escaping is done. - -String expansion is applied to the command line except when it comes from a -traditional \(.forward)\ file (commands from a filter file are expanded). The -expansion is applied to each argument in turn rather than to the whole line. -For this reason, any string expansion item that contains white space must be -quoted so as to be contained within a single argument. A setting such as -.display asis -command = /some/path ${if eq{$local_part}{postmaster}{xxx}{yyy}} -.endd -will not work, because the expansion item gets split between several -arguments. You have to write -.display asis -command = /some/path "${if eq{$local_part}{postmaster}{xxx}{yyy}}" -.endd -to ensure that it is all in one argument. The expansion is done in this way, -argument by argument, so that the number of arguments cannot be changed as a -result of expansion, and quotes or backslashes in inserted variables do not -interact with external quoting. - -.index transport||filter -.index filter||transport filter -Special handling takes place when an argument consists of precisely the text -`$tt{@$pipe@_addresses}'. This is not a general expansion variable; the only -place this string is recognized is when it appears as an argument for a pipe or -transport filter command. It causes each address that is being handled to be -inserted in the argument list at that point $it{as a separate argument}. This -avoids any problems with spaces or shell metacharacters, and is of use when a -\%pipe%\ transport is handling groups of addresses in a batch. - -After splitting up into arguments and expansion, the resulting command is run -in a subprocess directly from the transport, $it{not} under a shell. The -message that is being delivered is supplied on the standard input, and the -standard output and standard error are both connected to a single pipe that is -read by Exim. The \max@_output\ option controls how much output the command may -produce, and the \return@_output\ and \return@_fail@_output\ options control -what is done with it. - -Not running the command under a shell (by default) lessens the security risks -in cases when a command from a user's filter file is built out of data that was -taken from an incoming message. If a shell is required, it can of course be -explicitly specified as the command to be run. However, there are circumstances -where existing commands (for example, in \(.forward)\ files) expect to be run -under a shell and cannot easily be modified. To allow for these cases, there is -an option called \use@_shell\, which changes the way the \%pipe%\ transport -works. Instead of breaking up the command line as just described, it expands it -as a single string and passes the result to \(/bin/sh)\. The -\restrict@_to@_path\ option and the \$pipe@_addresses$\ facility cannot be used -with \use@_shell\, and the whole mechanism is inherently less secure. - - -.section Environment variables -.rset SECTpipeenv "~~chapter.~~section" -.index \%pipe%\ transport||environment for command -.index environment for pipe transport -The environment variables listed below are set up when the command is invoked. -This list is a compromise for maximum compatibility with other MTAs. Note that -the \environment\ option can be used to add additional variables to this -environment. -.display flow -.tabs 20 -DOMAIN $t $rm{the domain of the address} -HOME $t $rm{the home directory, if set} -HOST $t $rm{the host name when called from a router (see below)} -LOCAL@_PART $t $rm{see below} -LOCAL@_PART@_PREFIX $t $rm{see below} -LOCAL@_PART@_SUFFIX $t $rm{see below} -LOGNAME $t $rm{see below} -MESSAGE@_ID $t $rm{the message's id} -PATH $t $rm{as specified by the \path\ option below} -QUALIFY@_DOMAIN $t $rm{the sender qualification domain} -RECIPIENT $t $rm{the complete recipient address} -SENDER $t $rm{the sender of the message (empty if a bounce)} -SHELL $t `$tt{/bin/sh}' -TZ $t $rm{the value of the \timezone\ option, if set} -USER $t $rm{see below} -.endd - -When a \%pipe%\ transport is called directly from (for example) an \%accept%\ -router, \\LOCAL@_PART\\ is set to the local part of the address. When it is -called as a result of a forward or alias expansion, \\LOCAL@_PART\\ is set to -the local part of the address that was expanded. In both cases, any affixes are -removed from the local part, and made available in \\LOCAL@_PART@_PREFIX\\ and -\\LOCAL@_PART@_SUFFIX\\, respectively. \\LOGNAME\\ and \\USER\\ are set to the -same value as \\LOCAL@_PART\\ for compatibility with other MTAs. - -.index \\HOST\\ -\\HOST\\ is set only when a \%pipe%\ transport is called from a router that -associates hosts with an address, typically when using \%pipe%\ as a -pseudo-remote transport. \\HOST\\ is set to the first host name specified by -the router. - -.index \\HOME\\ -If the transport's generic \home@_directory\ option is set, its value is used -for the \\HOME\\ environment variable. Otherwise, a home directory may be set -by the router's \transport@_home@_directory\ option, which defaults to the -user's home directory if \check@_local@_user\ is set. - -.section Private options for pipe -.index options||\%pipe%\ transport - -.startconf pipe - -.conf allow@_commands "string list$**$" unset -.index \%pipe%\ transport||permitted commands -The string is expanded, and is then interpreted as a colon-separated list of -permitted commands. If \restrict@_to@_path\ is not set, the only commands -permitted are those in the \allow@_commands\ list. They need not be absolute -paths; the \path\ option is still used for relative paths. If -\restrict@_to@_path\ is set with \allow@_commands\, the command must either be -in the \allow@_commands\ list, or a name without any slashes that is found on -the path. In other words, if neither \allow@_commands\ nor \restrict@_to@_path\ -is set, there is no restriction on the command, but otherwise only commands -that are permitted by one or the other are allowed. For example, if -.display asis -allow_commands = /usr/bin/vacation -.endd -and \restrict@_to@_path\ is not set, the only permitted command is -\(/usr/bin/vacation)\. The \allow@_commands\ option may not be set if -\use@_shell\ is set. - -.conf batch@_id string$**$ unset -See the description of local delivery batching in chapter ~~CHAPbatching. - -.conf batch@_max integer 1 -This limits the number of addresses that can be handled in a single delivery. -See the description of local delivery batching in chapter ~~CHAPbatching. - -.conf check@_string string unset -As \%pipe%\ writes the message, the start of each line is tested for matching -\check@_string\, and if it does, the initial matching characters are replaced -by the contents of \escape@_string\, provided both are set. The value of -\check@_string\ is a literal string, not a regular expression, and the case of -any letters it contains is significant. When \use@_bsmtp\ is set, the contents -of \check@_string\ and \escape@_string\ are forced to values that implement the -SMTP escaping protocol. Any settings made in the configuration file are -ignored. - -.conf command string$**$ unset -This option need not be set when \%pipe%\ is being used to deliver to pipes -obtained directly from address redirections. In other cases, the option must be -set, to provide a command to be run. It need not yield an absolute path (see -the \path\ option below). The command is split up into separate arguments by -Exim, and each argument is separately expanded, as described in section -~~SECThowcommandrun above. - -.conf environment string$**$ unset -.index \%pipe%\ transport||environment for command -.index environment for \%pipe%\ transport -This option is used to add additional variables to the environment in which the -command runs (see section ~~SECTpipeenv for the default list). Its value is a -string which is expanded, and then interpreted as a colon-separated list of -environment settings of the form `<<name>>=<<value>>'. - -.conf escape@_string string unset -See \check@_string\ above. - -.conf freeze@_exec@_fail boolean false -.index exec failure -.index failure of exec -.index \%pipe%\ transport||failure of exec -Failure to exec the command in a pipe transport is by default treated like -any other failure while running the command. However, if \freeze@_exec@_fail\ -is set, failure to exec is treated specially, and causes the message to be -frozen, whatever the setting of \ignore@_status\. - -.conf ignore@_status boolean false -If this option is true, the status returned by the subprocess that is set up to -run the command is ignored, and Exim behaves as if zero had been returned. -Otherwise, a non-zero status -or termination by signal -causes an error return from the transport unless the status value is one of -those listed in \temp@_errors\; these cause the delivery to be deferred and -tried again later. - -.conf log@_defer@_output boolean false -.index \%pipe%\ transport||logging output -If this option is set, and the status returned by the command is -one of the codes listed in \temp@_errors\ (that is, delivery was deferred), -and any output was produced, the first line of it is written to the main log. - -.conf log@_fail@_output boolean false -If this option is set, and the command returns any output, and also ends with a -return code that is neither zero nor one of the return codes listed in -\temp@_errors\ (that is, the delivery failed), the first line of output is -written to the main log. -.em -This option and \log@_output\ are mutually exclusive. Only one of them may be -set. -.nem - -.conf log@_output boolean false -If this option is set and the command returns any output, the first line of -output is written to the main log, whatever the return code. -.em -This option and \log@_fail@_output\ are mutually exclusive. Only one of them -may be set. -.nem - -.conf max@_output integer 20K -This specifies the maximum amount of output that the command may produce on its -standard output and standard error file combined. If the limit is exceeded, the -process running the command is killed. This is intended as a safety measure to -catch runaway processes. The limit is applied independently of the settings of -the options that control what is done with such output (for example, -\return@_output\). Because of buffering effects, the amount of output may -exceed the limit by a small amount before Exim notices. - -.conf message@_prefix string$**$ "see below" -The string specified here is expanded and output at the start of every message. -The default is unset if \use@_bsmtp\ is set. Otherwise it is -.display asis -message_prefix = \ - From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ - ${tod_bsdinbox}\n -.endd -.index Cyrus -.index \tmail\ -.index `From' line -This is required by the commonly used \(/usr/bin/vacation)\ program. -However, it must $it{not} be present if delivery is to the Cyrus IMAP server, -or to the \tmail\ local delivery agent. The prefix can be suppressed by setting -.display asis -message_prefix = -.endd - -.conf message@_suffix string$**$ "see below" -The string specified here is expanded and output at the end of every message. -The default is unset if \use@_bsmtp\ is set. Otherwise it is a single newline. -The suffix can be suppressed by setting -.display asis -message_suffix = -.endd - -.conf path string $tt{/usr/bin} -This option specifies the string that is set up in the \\PATH\\ environment -variable of the subprocess. If the \command\ option does not yield an absolute -path name, the command is sought in the \\PATH\\ directories, in the usual way. -\**Warning**\: This does not apply to a command specified as a transport -filter. - -.conf pipe@_as@_creator boolean false -.index uid (user id)||local delivery -If the generic \user\ option is not set and this option is true, the delivery -process is run under the uid that was in force when Exim was originally called -to accept the message. If the group id is not otherwise set (via the generic -\group\ option), the gid that was in force when Exim was originally called to -accept the message is used. - -.conf restrict@_to@_path boolean false -When this option is set, any command name not listed in \allow@_commands\ must -contain no slashes. The command is searched for only in the directories listed -in the \path\ option. This option is intended for use in the case when a pipe -command has been generated from a user's \(.forward)\ file. This is usually -handled by a \%pipe%\ transport called \address@_pipe\. - -.conf return@_fail@_output boolean false -If this option is true, and the command produced any output and ended with a -return code other than zero or one of the codes listed in \temp@_errors\ (that -is, the delivery failed), the output is returned in the bounce message. -However, if the message has a null sender (that is, it is itself a bounce -message), output from the command is discarded. -.em -This option and \return@_output\ are mutually exclusive. Only one of them may -be set. -.nem - -.conf return@_output boolean false -If this option is true, and the command produced any output, the delivery is -deemed to have failed whatever the return code from the command, and the output -is returned in the bounce message. Otherwise, the output is just discarded. -However, if the message has a null sender (that is, it is a bounce message), -output from the command is always discarded, whatever the setting of this -option. -.em -This option and \return@_fail@_output\ are mutually exclusive. Only one of them -may be set. -.nem - -.conf temp@_errors "string list" "see below" -.index \%pipe%\ transport||temporary failure -This option contains either a colon-separated list of numbers, or a single -asterisk. If \ignore@_status\ is false -and \return@_output\ is not set, -and the command exits with a non-zero return code, the failure is treated as -temporary and the delivery is deferred if the return code matches one of the -numbers, or if the setting is a single asterisk. Otherwise, non-zero return -codes are treated as permanent errors. The default setting contains the codes -defined by \\EX@_TEMPFAIL\\ and \\EX@_CANTCREAT\\ in \(sysexits.h)\. If Exim is -compiled on a system that does not define these macros, it assumes values of 75 -and 73, respectively. - -.conf timeout time 1h -If the command fails to complete within this time, it is killed. This normally -causes the delivery to fail. A zero time interval specifies no timeout. In -order to ensure that any subprocesses created by the command are also killed, -Exim makes the initial process a process group leader, and kills the whole -process group on a timeout. However, this can be defeated if one of the -processes starts a new process group. - -.conf umask "octal integer" 022 -This specifies the umask setting for the subprocess that runs the command. - -.conf use@_bsmtp boolean false -.index envelope sender -If this option is set true, the \%pipe%\ transport writes messages in `batch -SMTP' format, with the envelope sender and recipient(s) included as SMTP -commands. If you want to include a leading \\HELO\\ command with such messages, -you can do so by setting the \message@_prefix\ option. See section -~~SECTbatchSMTP for details of batch SMTP. - -.conf use@_crlf boolean false -.index carriage return -.index linefeed -This option causes lines to be terminated with the two-character CRLF sequence -(carriage return, linefeed) instead of just a linefeed character. In the case -of batched SMTP, the byte sequence written to the pipe is then an exact image -of what would be sent down a real SMTP connection. - -The contents of the \message@_prefix\ and \message@_suffix\ options are written -verbatim, so must contain their own carriage return characters if these are -needed. Since the default values for both \message@_prefix\ and -\message@_suffix\ end with a single linefeed, their values -must -be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. - -.conf use@_shell boolean false -If this option is set, it causes the command to be passed to \(/bin/sh)\ -instead of being run directly from the transport, as described in section -~~SECThowcommandrun. This is less secure, but is needed in some situations -where the command is expected to be run under a shell and cannot easily be -modified. The \allow@_commands\ and \restrict@_to@_path\ options, and the -`$tt{@$pipe@_addresses}' facility are incompatible with \use@_shell\. The -command is expanded as a single string, and handed to \(/bin/sh)\ as data for -its \-c-\ option. - -.endconf - -.section Using an external local delivery agent -.index local delivery||using an external agent -.index \*procmail*\ -.index external local delivery -.index delivery||\*procmail*\ -.index delivery||by external agent -The \%pipe%\ transport can be used to pass all messages that require local -delivery to a separate local delivery agent such as \procmail\. When doing -this, care must be taken to ensure that the pipe is run under an appropriate -uid and gid. In some configurations one wants this to be a uid that is trusted -by the delivery agent to supply the correct sender of the message. It may be -necessary to recompile or reconfigure the delivery agent so that it trusts an -appropriate user. The following is an example transport and router -configuration for \procmail\: -.display asis -# transport -procmail_pipe: - driver = pipe - command = /usr/local/bin/procmail -d $local_part - return_path_add - delivery_date_add - envelope_to_add - check_string = "From " - escape_string = ">From " - user = $local_part - group = mail -.endd -.display asis -# router -procmail: - driver = accept - check_local_user - transport = procmail_pipe -.endd - -In this example, the pipe is run as the local user, but with the group set to -\*mail*\. An alternative is to run the pipe as a specific user such as \*mail*\ -or \*exim*\, but in this case you must arrange for \procmail\ to trust that -user to supply a correct sender address. If you do not specify either a \group\ -or a \user\ option, the pipe command is run as the local user. The home -directory is the user's home directory by default. - -Note that the command that the pipe transport runs does $it{not} begin with -.display asis -IFS=" " -.endd -as shown in the \procmail\ documentation, because Exim does not by default use -a shell to run pipe commands. - -.index Cyrus -The next example shows a transport and a router for a system where local -deliveries are handled by the Cyrus IMAP server. -.display asis -# transport -local_delivery_cyrus: - driver = pipe - command = /usr/cyrus/bin/deliver \ - -m ${substr_1:$local_part_suffix} -- $local_part - user = cyrus - group = mail - return_output - log_output - message_prefix = - message_suffix = -.endd -.display asis -# router -local_user_cyrus: - driver = accept - check_local_user - local_part_suffix = .* - transport = local_delivery_cyrus -.endd -Note the unsetting of \message@_prefix\ and \message@_suffix\, and the use of -\return@_output\ to cause any text written by Cyrus to be returned to the -sender. - - -. -. -. -. -. ============================================================================ -.chapter The smtp transport -.rset CHAPsmtptrans "~~chapter" -.set runningfoot "smtp transport" -.index transports||\%smtp%\ -.index \%smtp%\ transport -The \%smtp%\ transport delivers messages over TCP/IP connections using the SMTP -or LMTP protocol. The list of hosts to try can either be taken from the address -that is being processed (having been set up by the router), or specified -explicitly for the transport. Timeout and retry processing (see chapter -~~CHAPretry) is applied to each IP address independently. - -.section Multiple messages on a single connection -The sending of multiple messages over a single TCP/IP connection can arise in -two ways: -.numberpars $. -If a message contains more than \max@_rcpt\ (see below) addresses that are -routed to the same host, more than one copy of the message has to be sent to -that host. In this situation, multiple copies may be sent in a single run of -the \%smtp%\ transport over a single TCP/IP connection. (What Exim actually does -when it has too many addresses to send in one message also depends on the value -of the global \remote@_max@_parallel\ option. Details are given in section -~~SECToutSMTPTCP.) -.nextp -.index hints database||remembering routing -When a message has been successfully delivered over a TCP/IP connection, Exim -looks in its hints database to see if there are any other messages awaiting a -connection to the same host. If there are, a new delivery process is started -for one of them, and the current TCP/IP connection is passed on to it. The new -process may in turn send multiple copies and possibly create yet another -process. -.endp - -For each copy sent over the same TCP/IP connection, a sequence counter is -incremented, and if it ever gets to the value of \connection@_max@_messages\, -no further messages are sent over that connection. - - -.section Use of the @$host variable -.index \$host$\ -.index \$host@_address$\ -At the start of a run of the \%smtp%\ transport, the values of \$host$\ and -\$host@_address$\ are the name and IP address of the first host on the host list -passed by the router. However, when the transport is about to connect to a -specific host, and while it is connected to that host, \$host$\ and -\$host@_address$\ are set to the values for that host. These are the values -that are in force when the \helo@_data\, \hosts@_try@_auth\, \interface\, -\serialize@_hosts\, and the various TLS options are expanded. - - -.section Private options for smtp -The private options of the \%smtp%\ transport are as follows: - -.index options||\%smtp%\ transport -.startconf smtp -.conf allow@_localhost boolean false -.index local host||sending to -.index fallback||hosts specified on transport -When a host specified in \hosts\ or \fallback@_hosts\ (see below) turns out to -be the local host, or is listed in \hosts@_treat@_as@_local\, delivery is -deferred by default. However, if \allow@_localhost\ is set, Exim goes on to do -the delivery anyway. This should be used only in special cases when the -configuration ensures that no looping will result (for example, a differently -configured Exim is listening on the port to which the message is sent). - -.conf authenticated@_sender string$**$ unset -.index Cyrus -When Exim has authenticated as a client, this option sets a value for the -\\AUTH=\\ item on outgoing \\MAIL\\ commands, overriding any existing -authenticated sender value. If the string expansion is forced to fail, the -option is ignored. Other expansion failures cause delivery to be deferred. If -the result of expansion is an empty string, that is also ignored. - -If the SMTP session is not authenticated, the expansion of -\authenticated@_sender\ still happens (and can cause the delivery to be -deferred if it fails), but no \\AUTH=\\ item is added to \\MAIL\\ commands. - -This option allows you to use the \%smtp%\ transport in LMTP mode to -deliver mail to Cyrus IMAP and provide the proper local part as the -`authenticated sender', via a setting such as: -.display asis -authenticated_sender = $local_part -.endd -This removes the need for IMAP subfolders to be assigned special ACLs to -allow direct delivery to those subfolders. - -Because of expected uses such as that just described for Cyrus (when no -domain is involved), there is no checking on the syntax of the provided -value. - -.conf command@_timeout time 5m -This sets a timeout for receiving a response to an SMTP command that has been -sent out. It is also used when waiting for the initial banner line from the -remote host. Its value must not be zero. - -.conf connect@_timeout time 5m -This sets a timeout for the \*connect()*\ function, which sets up a TCP/IP call -to a remote host. A setting of zero allows the system timeout (typically -several minutes) to act. To have any effect, the value of this option must be -less than the system timeout. However, it has been observed that on some -systems there is no system timeout, which is why the default value for this -option is 5 minutes, a value recommended by RFC 1123. - -.index SMTP||passed connection -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -.conf connection@_max@_messages integer 500 -This controls the maximum number of separate message deliveries that are sent -over a single TCP/IP connection. If the value is zero, there is no limit. -For testing purposes, this value can be overridden by the \-oB-\ command line -option. - -.conf data@_timeout time 5m -This sets a timeout for the transmission of each block in the data portion of -the message. As a result, the overall timeout for a message depends on the size -of the message. Its value must not be zero. See also \final@_timeout\. - -.conf delay@_after@_cutoff boolean true -This option controls what happens when all remote IP addresses for a given -domain have been inaccessible for so long that they have passed their retry -cutoff times. - -In the default state, if the next retry time has not been reached for any of -them, the address is bounced without trying any deliveries. In other words, -Exim delays retrying an IP address after the final cutoff time until a new -retry time is reached, and can therefore bounce an address without ever trying -a delivery, when machines have been down for a long time. Some people are -unhappy at this prospect, so... - -If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP -addresses are past their final cutoff time, Exim tries to deliver to those -IP addresses that have not been tried since the message arrived. If there are -none, of if they all fail, the address is bounced. In other words, it does not -delay when a new message arrives, but immediately tries those expired IP -addresses that haven't been tried since the message arrived. If there is a -continuous stream of messages for the dead hosts, unsetting -\delay@_after@_cutoff\ means that there will be many more attempts to deliver -to them. - -.conf dns@_qualify@_single boolean true -If the \hosts\ or \fallback@_hosts\ option is being used, -and the \gethostbyname\ option is false, -the \\RES@_DEFNAMES\\ resolver option is set. See the \qualify@_single\ option -in chapter ~~CHAPdnslookup for more details. - -.conf dns@_search@_parents boolean false -.index \search@_parents\ -If the \hosts\ or \fallback@_hosts\ option is being used, and the -\gethostbyname\ option is false, the \\RES@_DNSRCH\\ resolver option is set. -See the \search@_parents\ option in chapter ~~CHAPdnslookup for more details. - - -.conf fallback@_hosts "string list" unset -.index fallback||hosts specified on transport -String expansion is not applied to this option. The argument must be a -colon-separated list of host names or IP addresses. Fallback hosts can also be -specified on routers, which associate them with the addresses they process. As -for the \hosts\ option without \hosts@_override\, \fallback@_hosts\ specified -on the transport is used only if the address does not have its own associated -fallback host list. Unlike \hosts\, a setting of \fallback@_hosts\ on an -address is not overridden by \hosts@_override\. However, \hosts@_randomize\ -does apply to fallback host lists. - -If Exim is unable to deliver to any of the hosts for a particular address, and -the errors are not permanent rejections, the address is put on a separate -transport queue with its host list replaced by the fallback hosts, unless the -address was routed via MX records and the current host was in the original MX -list. In that situation, the fallback host list is not used. - -Once normal deliveries are complete, the fallback queue is delivered by -re-running the same transports with the new host lists. If several failing -addresses have the same fallback hosts (and \max@_rcpt\ permits it), a single -copy of the message is sent. - -The resolution of the host names on the fallback list is controlled by the -\gethostbyname\ option, as for the \hosts\ option. Fallback hosts apply -both to cases when the host list comes with the address and when it is taken -from \hosts\. This option provides a `use a smart host only if delivery fails' -facility. - -.conf final@_timeout time 10m -This is the timeout that applies while waiting for the response to the final -line containing just `.' that terminates a message. Its value must not be zero. - -.conf gethostbyname boolean false -If this option is true when the \hosts\ and/or \fallback@_hosts\ options are -being used, names are looked up using \*gethostbyname()*\ -(or \*getipnodebyname()*\ when available) -instead of using the DNS. Of course, that function may in fact use the DNS, but -it may also consult other sources of information such as \(/etc/hosts)\. - -.index \\HELO\\||argument, setting -.index \\EHLO\\||argument, setting -.conf helo@_data string$**$ $tt{@$primary@_hostname} -The value of this option is expanded, and used as the argument for the \\EHLO\\ -or \\HELO\\ command that starts the outgoing SMTP session. - -.conf hosts "string list$**$" unset -Hosts are associated with an address by a router such as \%dnslookup%\, which -finds the hosts by looking up the address domain in the DNS. However, addresses -can be passed to the \%smtp%\ transport by any router, and not all of them can -provide an associated host list. The \hosts\ option specifies a list of hosts -which are used if the address being processed does not have any hosts -associated with it. The hosts specified by \hosts\ are also used, whether or -not the address has its own hosts, if \hosts@_override\ is set. - -The string is first expanded, before being interpreted as a colon-separated -list of host names or IP addresses. If the expansion fails, delivery is -deferred. Unless the failure was caused by the inability to complete a lookup, -the error is logged to the panic log as well as the main log. Host names are -looked up either by searching directly for address records in the DNS or by -calling \*gethostbyname()*\ -(or \*getipnodebyname()*\ when available), -depending on the setting of the \gethostbyname\ option. When Exim is compiled -with IPv6 support, if a host that is looked up in the DNS has both IPv4 and -IPv6 addresses, both types of address are used. - -During delivery, the hosts are tried in order, subject to their retry status, -unless \hosts@_randomize\ is set. - -.conf hosts@_avoid@_esmtp "host list$**$" unset -.index ESMTP, avoiding use of -.index \\HELO\\||forcing use of -.index \\EHLO\\||avoiding use of -.index \\PIPELINING\\||avoiding the use of -This option is for use with broken hosts that announce ESMTP facilities (for -example, \\PIPELINING\\) and then fail to implement them properly. When a host -matches \hosts@_avoid@_esmtp\, Exim sends \\HELO\\ rather than \\EHLO\\ at the -start of the SMTP session. This means that it cannot use any of the ESMTP -facilities such as \\AUTH\\, \\PIPELINING\\, \\SIZE\\, and \\STARTTLS\\. - -.conf hosts@_avoid@_tls "host list$**$" unset -.index TLS||avoiding for certain hosts -Exim will not try to start a TLS session when delivering to any host that -matches this list. See chapter ~~CHAPTLS for details of TLS. - -.conf hosts@_max@_try integer 5 -.index host||maximum number to try -.index limit||number of hosts tried -.index limit||number of MX tried -.index MX record||maximum tried -This option limits the number of IP addresses that are tried for any one -delivery in cases where there are temporary delivery errors. Section -~~SECTvalhosmax describes in detail how the value of this option is used. - -.em -.conf hosts@_max@_try@_hardlimit integer 50 -This is an additional check on the maximum number of IP addresses that Exim -tries for any one delivery. Section ~~SECTvalhosmax describes its use and why -it exists. -.nem - -.conf hosts@_nopass@_tls "host list$**$" unset -.index TLS||passing connection -.index multiple SMTP deliveries -.index TLS||multiple message deliveries -For any host that matches this list, a connection on which a TLS session has -been started will not be passed to a new delivery process for sending another -message on the same connection. See section ~~SECTmulmessam for an explanation -of when this might be needed. - -.conf hosts@_override boolean false -If this option is set and the \hosts\ option is also set, any hosts that are -attached to the address are ignored, and instead the hosts specified by the -\hosts\ option are always used. This option does not apply to -\fallback@_hosts\. - -.conf hosts@_randomize boolean false -.index randomized host list -.index host||list of, randomized -.index fallback||randomized hosts -If this option is set, and either the list of hosts is taken from the -\hosts\ or the \fallback@_hosts\ option, or the hosts supplied by the router -were not obtained from MX records (this includes fallback hosts from the -router), and were not randomizied by the router, the order of trying the hosts -is randomized each time the transport runs. Randomizing the order of a host -list can be used to do crude load sharing. - -When \hosts@_randomize\ is true, a host list may be split into groups whose -order is separately randomized. This makes it possible to set up MX-like -behaviour. The boundaries between groups are indicated by an item that is just -\"+"\ in the host list. For example: -.display asis -hosts = host1:host2:host3:+:host4:host5 -.endd -The order of the first three hosts and the order of the last two hosts is -randomized for each use, but the first three always end up before the last two. -If \hosts@_randomize\ is not set, a \"+"\ item in the list is ignored. - -.index authentication||required by client -.conf hosts@_require@_auth "host list$**$" unset -This option provides a list of servers for which authentication must succeed -before Exim will try to transfer a message. If authentication fails for -servers which are not in this list, Exim tries to send unauthenticated. If -authentication fails for one of these servers, delivery is deferred. This -temporary error is detectable in the retry rules, so it can be turned into a -hard failure if required. See also \hosts@_try@_auth\, and chapter -~~CHAPSMTPAUTH for details of authentication. - -.conf hosts@_require@_tls "host list$**$" unset -.index TLS||requiring for certain servers -Exim will insist on using a TLS session when delivering to any host that -matches this list. See chapter ~~CHAPTLS for details of TLS. -\**Note**\: This option affects outgoing mail only. To insist on TLS for -incoming messages, use an appropriate ACL. - -.index authentication||optional in client -.conf hosts@_try@_auth "host list$**$" unset -This option provides a list of servers to which, provided they announce -authentication support, Exim will attempt to authenticate as a client when it -connects. If authentication fails, Exim will try to transfer the message -unauthenticated. See also \hosts@_require@_auth\, and chapter ~~CHAPSMTPAUTH -for details of authentication. - -.index bind IP address -.index IP address||binding -.conf interface "string list$**$" unset -This option specifies which interface to bind to when making an outgoing SMTP -call. The variables \$host$\ and \$host@_address$\ refer to the host to which a -connection is about to be made during the expansion of the string. Forced -expansion failure, or an empty string result causes the option to be ignored. -Otherwise, after expansion, -the string must be a list of IP addresses, colon-separated by default, but the -separator can be changed in the usual way. -For example: -.display asis -interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 -.endd -The first interface of the correct type (IPv4 or IPv6) is used for the outgoing -connection. If none of them are the correct type, the option is ignored. If -\interface\ is not set, or is ignored, the system's IP functions choose which -interface to use if the host has more than one. - -.conf keepalive boolean true -.index keepalive||on outgoing connection -This option controls the setting of \\SO@_KEEPALIVE\\ on outgoing TCP/IP socket -connections. When set, it causes the kernel to probe idle connections -periodically, by sending packets with `old' sequence numbers. The other end of -the connection should send a acknowledgement if the connection is still okay or -a reset if the connection has been aborted. The reason for doing this is that -it has the beneficial effect of freeing up certain types of connection that can -get stuck when the remote host is disconnected without tidying up the TCP/IP -call properly. The keepalive mechanism takes several hours to detect -unreachable hosts. - -.conf max@_rcpt integer 100 -.index \\RCPT\\||maximum number of outgoing -This option limits the number of \\RCPT\\ commands that are sent in a single -SMTP message transaction. Each set of addresses is treated independently, and -so can cause parallel connections to the same host if \remote@_max@_parallel\ -permits this. - -.conf multi@_domain boolean true -When this option is set, the \%smtp%\ transport can handle a number of addresses -containing a mixture of different domains provided they all resolve to the same -list of hosts. Turning the option off restricts the transport to handling only -one domain at a time. This is useful if you want to use \$domain$\ in an -expansion for the transport, because it is set only when there is a single -domain involved in a remote delivery. - -.conf port string$**$ "see below" -.index port||sending TCP/IP -.index TCP/IP||setting outgoing port -This option specifies the TCP/IP port on the server to which Exim connects. If -it begins with a digit it is taken as a port number; otherwise it is looked up -using \*getservbyname()*\. The default value is normally `smtp', but if -\protocol\ is set to `lmtp', the default is `lmtp'. -If the expansion fails, or if a port number cannot be found, delivery is -deferred. - - -.conf protocol string "smtp" -.index LMTP||over TCP/IP -If this option is set to `lmtp' instead of `smtp', the default value for the -\port\ option changes to `lmtp', and the transport operates the LMTP protocol -(RFC 2033) instead of SMTP. This protocol is sometimes used for local -deliveries into closed message stores. Exim also has support for running LMTP -over a pipe to a local process -- see chapter ~~CHAPLMTP. - -.conf retry@_include@_ip@_address boolean true -Exim normally includes both the host name and the IP address in the key it -constructs for indexing retry data after a temporary delivery failure. This -means that when one of several IP addresses for a host is failing, it gets -tried periodically (controlled by the retry rules), but use of the other IP -addresses is not affected. - -However, in some dialup environments hosts are assigned a different IP address -each time they connect. In this situation the use of the IP address as part of -the retry key leads to undesirable behaviour. Setting this option false causes -Exim to use only the host name. This should normally be done on a separate -instance of the \%smtp%\ transport, set up specially to handle the dialup hosts. - -.conf serialize@_hosts "host list$**$" unset -.index serializing connections -.index host||serializing connections -Because Exim operates in a distributed manner, if several messages for the same -host arrive at around the same time, more than one simultaneous connection to -the remote host can occur. This is not usually a problem except when there is a -slow link between the hosts. In that situation it may be helpful to restrict -Exim to one connection at a time. This can be done by setting -\serialize@_hosts\ to match the relevant hosts. - -.index hints database||serializing deliveries to a host -Exim implements serialization by means of a hints database in which a record is -written whenever a process connects to one of the restricted hosts. The record -is deleted when the connection is completed. Obviously there is scope for -records to get left lying around if there is a system or program crash. To -guard against this, Exim ignores any records that are more than six hours old. - -If you set up this kind of serialization, you should also arrange to delete the -relevant hints database whenever your system reboots. The names of the files -start with \(misc)\ and they are kept in the \(spool/db)\ directory. There -may be one or two files, depending on the type of DBM in use. The same files -are used for ETRN serialization. - -.conf size@_addition integer 1024 -.index SMTP||\\SIZE\\ -.index message||size issue for transport filter -.index size||of message -.index transport||filter -.index filter||transport filter -If a remote SMTP server indicates that it supports the \\SIZE\\ option of the -\\MAIL\\ command, Exim uses this to pass over the message size at the start of -an SMTP transaction. It adds the value of \size@_addition\ to the value it -sends, to allow for headers and other text that may be added during delivery by -configuration options or in a transport filter. It may be necessary to increase -this if a lot of text is added to messages. - -Alternatively, if the value of \size@_addition\ is set negative, it disables -the use of the \\SIZE\\ option altogether. - -.conf tls@_certificate string$**$ unset -.index TLS||client certificate, location of -.index certificate||for client, location of -The value of this option must be the absolute path to a file which contains the -client's certificate, for use when sending a message over an encrypted -connection. The values of \$host$\ and \$host@_address$\ are set to the name -and address of the server during the expansion. See chapter ~~CHAPTLS for -details of TLS. - -\**Note**\: This option must be set if you want Exim to use TLS when sending -messages as a client. The global option of the same name specifies the -certificate for Exim as a server; it is not automatically assumed that the same -certificate should be used when Exim is operating as a client. - -.conf tls@_crl string$**$ unset -.index TLS||client certificate revocation list -.index certificate||revocation list for client -This option specifies a certificate revocation list. The expanded value must -be the name of a file that contains a CRL in PEM format. - -.conf tls@_privatekey string$**$ unset -.index TLS||client private key, location of -The value of this option must be the absolute path to a file which contains the -client's private key, for use when sending a message over an encrypted -connection. The values of \$host$\ and \$host@_address$\ are set to the name -and address of the server during the expansion. -If this option is unset, the private key is assumed to be in the same file as -the certificate. -See chapter ~~CHAPTLS for details of TLS. - -.conf tls@_require@_ciphers string$**$ unset -.index TLS||requiring specific ciphers -.index cipher||requiring specific -The value of this option must be a list of permitted cipher suites, for use -when setting up an outgoing encrypted connection. (There is a global option of -the same name for controlling incoming connections.) The values of \$host$\ and -\$host@_address$\ are set to the name and address of the server during the -expansion. See chapter ~~CHAPTLS for details of TLS; note that this option is -used in different ways by OpenSSL and GnuTLS (see sections ~~SECTreqciphssl and -~~SECTreqciphgnu). -.em -For GnuTLS, the order of the ciphers is a preference order. -.nem - -.conf tls@_tempfail@_tryclear boolean true -When the server host is not in \hosts@_require@_tls\, and there is a problem in -setting up a TLS session, this option determines whether or not Exim should try -to deliver the message unencrypted. If it is set false, delivery to the -current host is deferred; if there are other hosts, they are tried. If this -option is set true, Exim attempts to deliver unencrypted after a 4\*xx*\ -response to \\STARTTLS\\. Also, if \\STARTTLS\\ is accepted, but the subsequent -TLS negotiation fails, Exim closes the current connection (because it is in an -unknown state), opens a new one to the same host, and then tries the delivery -in clear. - -.conf tls@_verify@_certificates string$**$ unset -.index TLS||server certificate verification -.index certificate||verification of server -The value of this option must be the absolute path to a file containing -permitted server certificates, for use when setting up an encrypted connection. -Alternatively, if you are using OpenSSL, you can set -\tls@_verify@_certificates\ to the name of a directory containing certificate -files. This does not work with GnuTLS; the option must be set to the name of a -single file if you are using GnuTLS. The values of \$host$\ and -\$host@_address$\ are set to the name and address of the server during the -expansion of this option. See chapter ~~CHAPTLS for details of TLS. - -.endconf - - -.section How the limits for the number of hosts to try are used -.rset SECTvalhosmax "~~chapter.~~section" -.index host||maximum number to try -.index limit||hosts, maximum number tried -.em -There are two options that are concerned with the number of hosts that are -tried when an SMTP delivery takes place. They are \hosts@_max@_try\ and -\hosts@_max@_try@_hardlimit\. -.nem - -The \hosts@_max@_try\ option limits the number of hosts that are tried -for a single delivery. However, despite the term `host' in its name, the option -actually applies to each IP address independently. In other words, a multihomed -host is treated as several independent hosts, just as it is for retrying. - -Many of the larger ISPs have multiple MX records which often point to -multihomed hosts. As a result, a list of a dozen or more IP addresses may be -created as a result of routing one of these domains. - -Trying every single IP address on such a long list does not seem sensible; if -several at the top of the list fail, it is reasonable to assume there is some -problem that is likely to affect all of them. Roughly speaking, the value of -\hosts@_max@_try\ is the maximum number that are tried before deferring the -delivery. However, the logic cannot be quite that simple. - -Firstly, IP addresses that are skipped because their retry times have not -arrived do not count, and in addition, addresses that are past their retry -limits are also not counted, even when they are tried. This means that when -some IP addresses are past their retry limits, more than the value of -\hosts@_max@_retry\ may be tried. The reason for this behaviour is to ensure -that all IP addresses are considered before timing out an email address (but -see below for an exception). - -Secondly, when the \hosts@_max@_try\ limit is reached, Exim looks down the host -list to see if there is a subsequent host with a different (higher valued) MX. -If there is, that host is considered next, and the current IP address is used -but not counted. This behaviour helps in the case of a domain with a retry rule -that hardly ever delays any hosts, as is now explained: - -Consider the case of a long list of hosts with one MX value, and a few with a -higher MX value. If \hosts@_max@_try\ is small (the default is 5) only a few -hosts at the top of the list are tried at first. With the default retry rule, -which specifies increasing retry times, the higher MX hosts are eventually -tried when those at the top of the list are skipped because they have not -reached their retry times. - -However, it is common practice to put a fixed short retry time on domains for -large ISPs, on the grounds that their servers are rarely down for very long. -Unfortunately, these are exactly the domains that tend to resolve to long lists -of hosts. The short retry time means that the lowest MX hosts are tried every -time. The attempts may be in a different order because of random sorting, but -without the special MX check, the higher MX hosts would never be tried -.em -until all the lower MX hosts had timed out (which might be several days), -because there are always some lower MX hosts that have reached their retry -times. With the special check, Exim considers at least one IP address from each -MX value at every delivery attempt, even if the \hosts@_max@_try\ limit has -already been reached. - -The above logic means that \hosts@_max@_try\ is not a hard limit, and in -particular, Exim normally eventually tries all the IP addresses before timing -out an email address. When \hosts@_max@_try\ was implemented, this seemed a -reasonable thing to do. Recently, however, some lunatic DNS configurations have -been set up with hundreds of IP addresses for some domains. It can -take a very long time indeed for an address to time out in these cases. - -The \hosts@_max@_try@_hardlimit\ option was added to help with this problem. -Exim never tries more than this number of IP addresses; if it hits this limit -and they are all timed out, the email address is bounced, even though not all -possible IP addresses have been tried. -.nem - - - - -. -. -. -. -. ============================================================================ -.chapter Address rewriting -.set runningfoot "address rewriting" -.rset CHAPrewrite ~~chapter -.index rewriting||addresses -There are some circumstances in which Exim automatically rewrites domains in -addresses. The two most common are when an address is given without a domain -(referred to as an `unqualified address') or when an address contains an -abbreviated domain that is expanded by DNS lookup. - -Unqualified envelope addresses are accepted only for locally submitted -messages, or messages from hosts that match \sender@_unqualified@_hosts\ or -\recipient@_unqualified@_hosts\, respectively. Unqualified addresses in header -lines are qualified if they are in locally submitted messages, or messages from -hosts that are permitted to send unqualified envelope addresses. Otherwise, -unqualified addresses in header lines are neither qualified nor rewritten. - -One situation in which Exim does $it{not} automatically rewrite a domain is -when it is the name of a CNAME record in the DNS. The older RFCs suggest that -such a domain should be rewritten using the `canonical' name, and some MTAs do -this. The new RFCs do not contain this suggestion. - -.section Explicitly configured address rewriting -This chapter describes the rewriting rules that can be used in the -main rewrite section of the configuration file, and also in the generic -\headers@_rewrite\ option that can be set on any transport. - -Some people believe that configured address rewriting is a Mortal Sin. -Others believe that life is not possible without it. Exim provides the -facility; you do not have to use it. - -The main rewriting rules that appear in the `rewrite' section of the -configuration file are applied to addresses in incoming messages, both envelope -addresses and addresses in header lines. Each rule specifies the types of -address to which it applies. - -Rewriting of addresses in header lines applies only to those headers that -were received with the message, and, in the case of transport rewriting, those -that were added by a system filter. That is, it applies only to those headers -that are common to all copies of the message. Header lines that are added by -individual routers or transports (and which are therefore specific to -individual recipient addresses) are not rewritten. - -In general, rewriting addresses from your own system or domain has some -legitimacy. Rewriting other addresses should be done only with great care and -in special circumstances. The author of Exim believes that rewriting should be -used sparingly, and mainly for `regularizing' addresses in your own domains. -Although it can sometimes be used as a routing tool, this is very strongly -discouraged. - -There are two commonly encountered circumstances where rewriting is used, as -illustrated by these examples: -.numberpars $. -The company whose domain is \*hitch.fict.example*\ has a number of hosts that -exchange mail with each other behind a firewall, but there is only a single -gateway to the outer world. The gateway rewrites \*@*.hitch.fict.example*\ as -\*hitch.fict.example*\ when sending mail off-site. -.nextp -A host rewrites the local parts of its own users so that, for example, -\*fp42@@hitch.fict.example*\ becomes \*Ford.Prefect@@hitch.fict.example*\. -.endp - -.section When does rewriting happen? -.index rewriting||timing of -.index ~~ACL||rewriting addresses in -Configured address rewriting can take place at several different stages of a -message's processing. - -At the start of an ACL for \\MAIL\\, the sender address may have been rewritten -by a special SMTP-time rewrite rule (see section ~~SECTrewriteS), but no -ordinary rewrite rules have yet been applied. If, however, the sender address -is verified in the ACL, it is rewritten before verification, and remains -rewritten thereafter. The subsequent value of \$sender@_address$\ is the -rewritten address. This also applies if sender verification happens in a -\\RCPT\\ ACL. Otherwise, when the sender address is not verified, it is -rewritten as soon as a message's header lines have been received. - -Similarly, at the start of an ACL for \\RCPT\\, the current recipient's address -may have been rewritten by a special SMTP-time rewrite rule, but no ordinary -rewrite rules have yet been applied to it. However, the behaviour is different -from the sender address when a recipient is verified. The address is rewritten -for the verification, but the rewriting is not remembered at this stage. The -value of \$local@_part$\ and \$domain$\ after verification are always the same -as they were before (that is, they contain the unrewritten -- except for -SMTP-time rewriting -- address). - -Once a message's header lines have been received, all the envelope recipient -addresses are permanently rewritten, and rewriting is also applied to the -addresses in the header lines (if configured). -.index \*local@_scan()*\ function||address rewriting, timing of -Thus, all the rewriting is completed before the \\DATA\\ ACL and -\*local@_scan()*\ functions are run. - -When an address is being routed, either for delivery or for verification, -rewriting is applied immediately to child addresses that are generated by -redirection, unless \no@_rewrite\ is set on the router. - -.index envelope sender, rewriting -.index rewriting||at transport time -At transport time, additional rewriting of addresses in header lines can be -specified by setting the generic \headers@_rewrite\ option on a transport. This -option contains rules that are identical in form to those in the rewrite -section of the configuration file. In addition, the outgoing envelope sender -can be rewritten by means of the \return@_path\ transport option. However, it -is not possible to rewrite envelope recipients at transport time. - - - -.section Testing the rewriting rules that apply on input -.index rewriting||testing -.index testing||rewriting -Exim's input rewriting configuration appears in a part of the run time -configuration file headed by `begin rewrite'. It can be tested by the \-brw-\ -command line option. This takes an address (which can be a full RFC 2822 -address) as its argument. The output is a list of how the address would be -transformed by the rewriting rules for each of the different places it might -appear in an incoming message, that is, for each different header and for the -envelope sender and recipient fields. For example, -.display asis -exim -brw ph10@exim.workshop.example -.endd -might produce the output -.display asis - sender: Philip.Hazel@exim.workshop.example - from: Philip.Hazel@exim.workshop.example - to: ph10@exim.workshop.example - cc: ph10@exim.workshop.example - bcc: ph10@exim.workshop.example -reply-to: Philip.Hazel@exim.workshop.example -env-from: Philip.Hazel@exim.workshop.example - env-to: ph10@exim.workshop.example -.endd -which shows that rewriting has been set up for that address when used in any of -the source fields, but not when it appears as a recipient address. At the -present time, there is no equivalent way of testing rewriting rules that are -set for a particular transport. - -.section Rewriting rules -.index rewriting||rules -The rewrite section of the configuration file consists of lines of rewriting -rules in the form -.display -<<source pattern>> <<replacement>> <<flags>> -.endd -Rewriting rules that are specified for the \headers@_rewrite\ generic transport -option are given as a colon-separated list. Each item in the list takes the -same form as a line in the main rewriting configuration -(except that any colons must be doubled, of course). - -The formats of source patterns and replacement strings are described below. -Each is terminated by white space, unless enclosed in double quotes, in which -case normal quoting conventions apply inside the quotes. The flags are single -characters which may appear in any order. Spaces and tabs between them are -ignored. - -For each address that could potentially be rewritten, the rules are scanned in -order, and replacements for the address from earlier rules can themselves be -replaced by later rules (but see the `q' and `R' flags). - -The order in which addresses are rewritten is undefined, may change between -releases, and must not be relied on, with one exception: when a message is -received, the envelope sender is always rewritten first, before any header -lines are rewritten. For example, the replacement string for a rewrite of an -address in ::To:: must not assume that the message's address in ::From:: has (or -has not) already been rewritten. However, a rewrite of ::From:: may assume that -the envelope sender has already been rewritten. - -The variables \$local@_part$\ and \$domain$\ can be used in the replacement -string to refer to the address that is being rewritten. Note that lookup-driven -rewriting can be done by a rule of the form -.display asis -*@* ${lookup ... -.endd -where the lookup key uses \$1$\ and \$2$\ or \$local@_part$\ and \$domain$\ to -refer to the address that is being rewritten. - -.section Rewriting patterns -.index rewriting||patterns -.index address list||in a rewriting pattern -The source pattern in a rewriting rule is any item which may appear in an -address list (see section ~~SECTaddresslist). It is in fact processed as a -single-item address list, which means that it is expanded before being tested -against the address. - -Domains in patterns should be given in lower case. Local parts in patterns are -case-sensitive. If you want to do case-insensitive matching of local parts, you -can use a regular expression that starts with \"^(?i)"\. - -.index numerical variables (\$1$\, \$2$\, etc)||in rewriting rules -After matching, the numerical variables \$1$\, \$2$\, etc. may be set, -depending on the type of match which occurred. These can be used in the -replacement string to insert portions of the incoming address. \$0$\ always -refers to the complete incoming address. When a regular expression is used, the -numerical variables are set from its capturing subexpressions. For other types -of pattern they are set as follows: - -.numberpars $. -If a local part or domain starts with an asterisk, the numerical variables -refer to the character strings matched by asterisks, with \$1$\ associated with -the first asterisk, and \$2$\ with the second, if present. For example, if the -pattern -.display -*queen@@*.fict.example -.endd -is matched against the address \*hearts-queen@@wonderland.fict.example*\ then -.display asis -$0 = hearts-queen@wonderland.fict.example -$1 = hearts- -$2 = wonderland -.endd -Note that if the local part does not start with an asterisk, but the domain -does, it is \$1$\ that contains the wild part of the domain. -.nextp -If the domain part of the pattern is a partial lookup, the wild and fixed parts -of the domain are placed in the next available numerical variables. Suppose, -for example, that the address \*foo@@bar.baz.example*\ is processed by a -rewriting rule of the form -.display -*@@partial-dbm;/some/dbm/file <<replacement string>> -.endd -and the key in the file that matches the domain is \"*.baz.example"\. Then -.display asis -$1 = foo -$2 = bar -$3 = baz.example -.endd -If the address \*foo@@baz.example*\ is looked up, this matches the same -wildcard file entry, and in this case \$2$\ is set to the empty string, but -\$3$\ is still set to \*baz.example*\. If a non-wild key is matched in a -partial lookup, \$2$\ is again set to the empty string and \$3$\ is set to the -whole domain. For non-partial domain lookups, no numerical variables are set. -.endp - -.section Rewriting replacements -.index rewriting||replacements -If the replacement string for a rule is a single asterisk, addresses that -match the pattern and the flags are $it{not} rewritten, and no subsequent -rewriting rules are scanned. For example, -.display asis -hatta@lookingglass.fict.example * f -.endd -specifies that \*hatta@@lookingglass.fict.example*\ is never to be rewritten in -::From:: headers. - -If the replacement string is not a single asterisk, it is expanded, and must -yield a fully qualified address. Within the expansion, the variables -\$local@_part$\ and \$domain$\ refer to the address that is being rewritten. -Any letters they contain retain their original case -- they are not lower -cased. The numerical variables are set up according to the type of pattern that -matched the address, as described above. If the expansion is forced to fail by -the presence of `fail' in a conditional or lookup item, rewriting by the -current rule is abandoned, but subsequent rules may take effect. Any other -expansion failure causes the entire rewriting operation to be abandoned, and an -entry written to the panic log. - - -.section Rewriting flags -There are three different kinds of flag that may appear on rewriting rules: -.numberpars $. -Flags that specify which headers and envelope addresses to rewrite: E, F, T, b, -c, f, h, r, s, t. -.nextp -A flag that specifies rewriting at SMTP time: S. -.nextp -Flags that control the rewriting process: Q, q, R, w. -.endp -For rules that are part of the \headers@_rewrite\ generic transport option, -E, F, T, and S are not permitted. - - -.section Flags specifying which headers and envelope addresses to rewrite -.index rewriting||flags -If none of the following flag letters, nor the `S' flag (see section -~~SECTrewriteS) are present, a main rewriting rule applies to all headers and -to both the sender and recipient fields of the envelope, whereas a -transport-time rewriting rule just applies to all headers. Otherwise, the -rewriting rule is skipped unless the relevant addresses are being processed. -.display -E $rm{rewrite all envelope fields} -F $rm{rewrite the envelope From field} -T $rm{rewrite the envelope To field} -b $rm{rewrite the ::Bcc:: header} -c $rm{rewrite the ::Cc:: header} -f $rm{rewrite the ::From:: header} -h $rm{rewrite all headers} -r $rm{rewrite the ::Reply-To:: header} -s $rm{rewrite the ::Sender:: header} -t $rm{rewrite the ::To:: header} -.endd -You should be particularly careful about rewriting ::Sender:: headers, and -restrict this to special known cases in your own domains. - -.section The SMTP-time rewriting flag -.rset SECTrewriteS "~~chapter.~~section" -.index SMTP||rewriting malformed addresses -.index \\RCPT\\||rewriting argument of -.index \\MAIL\\||rewriting argument of -The rewrite flag `S' specifies a rewrite of incoming envelope addresses at SMTP -time, as soon as an address is received in a \\MAIL\\ or \\RCPT\\ command, and -before any other processing; even before syntax checking. The pattern is -required to be a regular expression, and it is matched against the whole of the -data for the command, including any surrounding angle brackets. - -This form of rewrite rule allows for the handling of addresses that are not -compliant with RFCs 2821 and 2822 (for example, `bang paths' in batched SMTP -input). Because the input is not required to be a syntactically valid address, -the variables \$local@_part$\ and \$domain$\ are not available during the -expansion of the replacement string. The result of rewriting replaces the -original address in the \\MAIL\\ or \\RCPT\\ command. - -.section Flags controlling the rewriting process -There are four flags which control the way the rewriting process works. These -take effect only when a rule is invoked, that is, when the address is of the -correct type (matches the flags) and matches the pattern: -.numberpars $. -If the `Q' flag is set on a rule, the rewritten address is permitted to be an -unqualified local part. It is qualified with \qualify@_recipient\. In the -absence of `Q' the rewritten address must always include a domain. -.nextp -If the `q' flag is set on a rule, no further rewriting rules are considered, -even if no rewriting actually takes place because of a `fail' in the expansion. -The `q' flag is not effective if the address is of the wrong type (does not -match the flags) or does not match the pattern. -.nextp -The `R' flag causes a successful rewriting rule to be re-applied to the new -address, up to ten times. It can be combined with the `q' flag, to stop -rewriting once it fails to match (after at least one successful rewrite). -.nextp -.index rewriting||whole addresses -When an address in a header is rewritten, the rewriting normally applies only -to the working part of the address, with any comments and RFC 2822 `phrase' -left unchanged. For example, rewriting might change -.display asis -From: Ford Prefect <fp42@restaurant.hitch.fict.example> -.endd -into -.display asis -From: Ford Prefect <prefectf@hitch.fict.example> -.endd -Sometimes there is a need to replace the whole address item, and this can be -done by adding the flag letter `w' to a rule. If this is set on a rule that -causes an address in a header line to be rewritten, the entire address is -replaced, not just the working part. The replacement must be a complete RFC -2822 address, including the angle brackets if necessary. If text outside angle -brackets contains a character whose value is greater than 126 or less than 32 -(except for tab), the text is encoded according to RFC 2047. -The character set is taken from \headers@_charset\, which defaults to -ISO-8859-1. - -When the `w' flag is set on a rule that causes an envelope address to be -rewritten, all but the working part of the replacement address is discarded. -.endp - -.section Rewriting examples -Here is an example of the two common rewriting paradigms: -.display asis -*@*.hitch.fict.example $1@hitch.fict.example -*@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ - {$value}fail}@hitch.fict.example bctfrF -.endd -Note the use of `fail' in the lookup expansion in the second rule, forcing -the string expansion to fail if the lookup does not succeed. In this context it -has the effect of leaving the original address unchanged, but Exim goes on to -consider subsequent rewriting rules, if any, because the `q' flag is not -present in that rule. An alternative to `fail' would be to supply \$1$\ -explicitly, which would cause the rewritten address to be the same as before, -at the cost of a small bit of processing. Not supplying either of these is an -error, since the rewritten address would then contain no local part. - -The first example above replaces the domain with a superior, more general -domain. This may not be desirable for certain local parts. If the rule -.display asis -root@*.hitch.fict.example * -.endd -were inserted before the first rule, rewriting would be suppressed for the -local part \*root*\ at any domain ending in \*hitch.fict.example*\. - -Rewriting can be made conditional on a number of tests, by making use of -\${if$\ in the expansion item. For example, to apply a rewriting rule only to -messages that originate outside the local host: -.display asis -*@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ - {$1@hitch.fict.example}fail}" -.endd -The replacement string is quoted in this example because it contains white -space. - -.index rewriting||bang paths -.index bang paths||rewriting -Exim does not handle addresses in the form of `bang paths'. If it sees such an -address it treats it as an unqualified local part which it qualifies with the -local qualification domain (if the source of the message is local or if the -remote host is permitted to send unqualified addresses). Rewriting can -sometimes be used to handle simple bang paths with a fixed number of -components. For example, the rule -.display asis -\N^([^!]+)!(.*)@your.domain.example$\N $2@$1 -.endd -rewrites a two-component bang path \*host.name!user*\ as the domain address -\*user@@host.name*\. However, there is a security implication in using this as -a global rewriting rule for envelope addresses. It can provide a backdoor -method for using your system as a relay, because the incoming addresses appear -to be local. If the bang path addresses are received via SMTP, it is safer to -use the `S' flag to rewrite them as they are received, so that relay checking -can be done on the rewritten addresses. - - - - - -. -. -. -. -. ============================================================================ -.chapter Retry configuration -.set runningfoot "retry configuration" -.rset CHAPretry ~~chapter -.index retry||configuration, description of -.index configuration file||retry section -The `retry' section of the run time configuration file contains a list of retry -rules which control how often Exim tries to deliver messages that cannot be -delivered at the first attempt. If there are no retry rules, temporary errors -are treated as permanent. The \-brt-\ command line option can be used to test -which retry rule will be used for a given address or domain. - -The most common cause of retries is temporary failure to deliver to a remote -host because the host is down, or inaccessible because of a network problem. -Exim's retry processing in this case is applied on a per-host (strictly, per IP -address) basis, not on a per-message basis. Thus, if one message has recently -been delayed, delivery of a new message to the same host is not immediately -tried, but waits for the host's retry time to arrive. If the \retry@_defer\ log -selector is set, the message -.index retry||time not reached -`retry time not reached' is written to the main log whenever a delivery is -skipped for this reason. Section ~~SECToutSMTPerr contains more details of the -handling of errors during remote deliveries. - -Retry processing applies to routing as well as to delivering, except as covered -in the next paragraph. The retry rules do not distinguish between these -actions. It is not possible, for example, to specify different behaviour for -failures to route the domain \*snark.fict.example*\ and failures to deliver to -the host \*snark.fict.example*\. I didn't think anyone would ever need this -added complication, so did not implement it. However, although they share the -same retry rule, the actual retry times for routing and transporting a given -domain are maintained independently. - -When a delivery is not part of a queue run (typically an immediate delivery on -receipt of a message), the routers are always run, and local deliveries are -always attempted, 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). If such a delivery -suffers a temporary failure, the retry data is updated as normal, and -subsequent delivery attempts from queue runs occur only when the retry time for -the local address is reached. - - -.section Retry rules -.index retry||rules -.em -Each retry rule occupies one line and consists of three or four parts, -separated by white space: a pattern, an error name, an optional list of sender -addresses, and a list of retry parameters. The pattern and sender lists must be -enclosed in double quotes if they contain white space. The rules are searched in -order until one is found where the pattern, error name, and sender list (if -present) match the failing host or address, the error that occurred, and the -message's sender, respectively. -.nem - -The pattern is any single item that may appear in an address list (see section -~~SECTaddresslist). It is in fact processed as a one-item address list, which -means that it is expanded before being tested against the address that has -been delayed. Address list processing treats a plain domain name as if it were -preceded by `*@@', which makes it possible for many retry rules to start with -just a domain. For example, -.display asis -lookingglass.fict.example * F,24h,30m; -.endd -provides a rule for any address in the \*lookingglass.fict.example*\ domain, -whereas -.display asis -alice@lookingglass.fict.example * F,24h,30m; -.endd -applies only to temporary failures involving the local part \alice\. -In practice, almost all rules start with a domain name pattern without a local -part. - -.index regular expressions||in retry rules -\**Warning**\: If you use a regular expression in a routing rule pattern, it -must match a complete address, not just a domain, because that is how regular -expressions work in address lists. -.display -^@\Nxyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Wrong\ -^@\N[^@@]+@@xyz@\d+@\.abc@\.example@$@\N * G,1h,10m,2 \Right\ -.endd - - -.section Choosing which retry rule to use -When Exim is looking for a retry rule after a routing attempt has failed (for -example, after a DNS timeout), each line in the retry configuration is tested -against the complete address only if \retry__use@_local@_part\ is set for the -router. Otherwise, only the domain is used, except when matching against a -regular expression, when the local part of the address is replaced with `*'. A -domain on its own can match a domain pattern, or a pattern that starts with -`*@@'. By default, \retry@_use@_local@_part\ is true for routers where -\check@_local@_user\ is true, and false for other routers. - -Similarly, when Exim is looking for a retry rule after a local delivery has -failed (for example, after a mailbox full error), each line in the retry -configuration is tested against the complete address only if -\retry@_use@_local@_part\ is set for the transport (it defaults true for all -local transports). - -When Exim is looking for a retry rule after a remote delivery attempt has -failed, what happens depends on the type of failure. After a 4\*xx*\ SMTP -response for a recipient address, the whole address is used when searching the -retry rules. The rule that is found is used to create a retry time for the -failing address. - -For a temporary error that is not related to an individual address, -(for example, a connection timeout), each line in the retry configuration is -checked twice. First, the name of the remote host is used as a domain name -(preceded by `*@@' when matching a regular expression). If this does not match -the line, the domain from the email address is tried in a similar fashion. For -example, suppose the MX records for \*a.b.c.example*\ are -.display asis -a.b.c.example MX 5 x.y.z.example - MX 6 p.q.r.example - MX 7 m.n.o.example -.endd -and the retry rules are -.display asis -p.q.r.example * F,24h,30m; -a.b.c.example * F,4d,45m; -.endd -and a delivery to the host \*x.y.z.example*\ fails. The first rule matches -neither the host nor the domain, so Exim looks at the second rule. This does -not match the host, but it does match the domain, so it is used to calculate -the retry time for the host \*x.y.z.example*\. Meanwhile, Exim tries to deliver -to \*p.q.r.example*\. If this fails, the first retry rule is used, because it -matches the host. - -In other words, failures to deliver to host \*p.q.r.example*\ use the first -rule to determine retry times, but for all the other hosts for the domain -\*a.b.c.example*\, the second rule is used. The second rule is also used if -routing to \*a.b.c.example*\ suffers a temporary failure. - -.section Retry rules for specific errors -.index retry||specific errors, specifying -The second field in a retry rule is the name of a particular error, or an -asterisk, which matches any error. The errors that can be tested for are: -.em - -.push -.indent 2em -.tempindent 0 -\auth@_failed\: Authentication failed when trying to send to a host in the -\hosts@_require@_auth\ list in an \%smtp%\ transport. - -.tempindent 0 -\rcpt@_4xx\: A 4\*xx*\ error was received for an outgoing \\RCPT\\ command. -Either the first or both of the x's can be given as specific digits, for -example: \"rcpt@_45x"\ or \"rcpt@_436"\. For example, to recognize 452 errors -given to \\RCPT\\ commands by a particular host, and have retries every ten -minutes and a one-hour timeout, you could set up a retry rule of this form: -.display asis -the.host.name rcpt_452 F,1h,10m -.endd -These errors apply to both outgoing SMTP (the \%smtp%\ transport) and outgoing -LMTP (either the \%lmtp%\ transport, or the \%smtp%\ transport in LMTP mode). -Note, however, that they apply only to responses to \\RCPT\\ commands. - -.tempindent 0 -\refused@_MX\: A connection to a host obtained from an MX record was refused. - -.tempindent 0 -\refused@_A\: A connection to a host not obtained from an MX record was -refused. - -.tempindent 0 -\refused\: A connection was refused. - -.tempindent 0 -\timeout@_connect@_MX\: A connection attempt to a host obtained from an MX -record timed out. - -.tempindent 0 -\timeout@_connect@_A\: A connection attempt to a host not obtained from an MX -record timed out. - -.tempindent 0 -\timeout@_connect\: A connection attempt timed out. - -.tempindent 0 -\timeout@_MX\: There was a timeout while connecting or during an SMTP session -with a host obtained from an MX record. - -.tempindent 0 -\timeout@_A\: There was a timeout while connecting or during an SMTP session -with a host not obtained from an MX record. - -.tempindent 0 -\timeout\: There was a timeout while connecting or during an SMTP session. - -.tempindent 0 -\quota\: A mailbox quota was exceeded in a local delivery by the -\%appendfile%\ transport. - -.index quota||error testing in retry rule -.index retry||quota error testing -.tempindent 0 -\quota@_\<<time>>: A mailbox quota was exceeded in a local delivery by -the \%appendfile%\ transport, and the mailbox has not been accessed for -<<time>>. For example, \*quota@_4d*\ applies to a quota error when the mailbox -has not been accessed for four days. - -.pop - - -.index mailbox||time of last read -The idea of \quota@_\<<time>> is to make it possible to have shorter timeouts -when the mailbox is full and is not being read by its owner. Ideally, it should -be based on the last time that the user accessed the mailbox. However, it is -not always possible to determine this. Exim uses the following heuristic rules: -.numberpars $. -If the mailbox is a single file, the time of last access (the `atime') is used. -As no new messages are being delivered (because the mailbox is over quota), -Exim does not access the file, so this is the time of last user access. -.nextp -.index maildir format||time of last read -For a maildir delivery, the time of last modification of the \(new)\ -subdirectory is used. As the mailbox is over quota, no new files are created in -the \(new)\ subdirectory, because no new messages are being delivered. Any -change to the \(new)\ subdirectory is therefore assumed to be the result of an -MUA moving a new message to the \(cur)\ directory when it is first read. The -time that is used is therefore the last time that the user read a new message. -.nextp -For other kinds of multi-file mailbox, the time of last access cannot be -obtained, so a retry rule that uses this type of error field is never matched. -.endp -.nem -The quota errors apply both to system-enforced quotas and to Exim's own quota -mechanism in the \%appendfile%\ transport. The \*quota*\ error also applies -when a local delivery is deferred because a partition is full (the \\ENOSPC\\ -error). - - -.em -.section Retry rules for specified senders -.index retry||rules, sender-specific -You can specify retry rules that apply only when the failing message has a -specific sender. In particular, this can be used to define retry rules that -apply only to bounce messages. The third item in a retry rule can be of this -form: -.display -senders=<<address list>> -.endd -The retry timings themselves are then the fourth item. For example: -.display asis -* * senders=: F,1h,30m -.endd -matches all temporary errors for bounce messages sent to any host. If the -address list contains white space, it must be enclosed in quotes. For example: -.display -a.domain timeout senders="x@b.dom : y@c.dom" G,8h,10m,1.5 -.endd -When testing retry rules using \-brt-\, you can supply a sender using the \-f-\ -command line option, like this: -.display asis -exim -f "" -brt user@dom.ain -.endd -If you do not set \-f-\ with \-brt-\, a retry rule that contains a senders list -is never matched. -.nem - - - -.section Retry parameters -.index retry||parameters in rules -The third -.em -(or fourth, if a senders list is present) -.nem -field in a retry rule is a sequence of retry parameter sets, separated by -semicolons. Each set consists of -.display -<<letter>>,<<cutoff time>>,<<arguments>> -.endd -The letter identifies the algorithm for computing a new retry time; the cutoff -time is the time beyond which this algorithm no longer applies, and the -arguments vary the algorithm's action. The cutoff time is measured from the -time that the first failure for the domain (combined with the local part if -relevant) was detected, not from the time the message was received. -.index retry||algorithms -The available algorithms are: -.numberpars $. -\*F*\: retry at fixed intervals. There is a single time parameter specifying -the interval. -.nextp -\*G*\: retry at geometrically increasing intervals. The first argument -specifies a starting value for the interval, and the second a multiplier, which -is used to increase the size of the interval at each retry. -.endp -When computing the next retry time, the algorithm definitions are scanned in -order until one whose cutoff time has not yet passed is reached. This is then -used to compute a new retry time that is later than the current time. In the -case of fixed interval retries, this simply means adding the interval to the -current time. For geometrically increasing intervals, retry intervals are -computed from the rule's parameters until one that is greater than the previous -interval is found. The main configuration variable -.index limit||retry interval -.index retry||interval, maximum -.index \retry@_interval@_max\ -\retry@_interval@_max\ limits the maximum interval between retries. - -A single remote domain may have a number of hosts associated with it, and each -host may have more than one IP address. Retry algorithms are selected on the -basis of the domain name, but are applied to each IP address independently. If, -for example, a host has two IP addresses and one is unusable, Exim will -generate retry times for it and will not try to use it until its next retry -time comes. Thus the good IP address is likely to be tried first most of the -time. - -.index hints database||use for retrying -Retry times are hints rather than promises. Exim does not make any attempt to -run deliveries exactly at the computed times. Instead, a queue runner process -starts delivery processes for delayed messages periodically, and these attempt -new deliveries only for those addresses that have passed their next retry time. -If a new message arrives for a deferred address, an immediate delivery attempt -occurs only if the address has passed its retry time. In the absence of new -messages, the minimum time between retries is the interval between queue runner -processes. There is not much point in setting retry times of five minutes if -your queue runners happen only once an hour, unless there are a significant -number of incoming messages (which might be the case on a system that is -sending everything to a smart host, for example). - -The data in the retry hints database can be inspected by using the -\*exim@_dumpdb*\ or \*exim@_fixdb*\ utility programs (see chapter ~~CHAPutils). The -latter utility can also be used to change the data. The \*exinext*\ utility -script can be used to find out what the next retry times are for the hosts -associated with a particular mail domain, and also for local deliveries that -have been deferred. - -.section Retry rule examples -Here are some example retry rules: -.display asis -alice@wonderland.fict.example quota_5d F,7d,3h -wonderland.fict.example quota_5d -wonderland.fict.example * F,1h,15m; G,2d,1h,2; -lookingglass.fict.example * F,24h,30m; -* refused_A F,2h,20m; -* * F,2h,15m; G,16h,1h,1.5; F,5d,8h -.endd -The first rule sets up special handling for mail to -\*alice@@wonderland.fict.example*\ when there is an over-quota error and the -mailbox has not been read for at least 5 days. Retries continue every three -hours for 7 days. The second rule handles over-quota errors for all other local -parts at \*wonderland.fict.example*\; the absence of a local part has the same -effect as supplying `$*$@@'. As no retry algorithms are supplied, messages that -fail are bounced immediately if the mailbox has not been read for at least 5 -days. - -The third rule handles all other errors at \*wonderland.fict.example*\; retries -happen every 15 minutes for an hour, then with geometrically increasing -intervals until two days have passed since a delivery first failed. After the -first hour there is a delay of one hour, then two hours, then four hours, and -so on (this is a rather extreme example). - -The fourth rule controls retries for the domain \*lookingglass.fict.example*\. -They happen every 30 minutes for 24 hours only. The remaining two rules handle -all other domains, with special action for connection refusal from hosts that -were not obtained from an MX record. - -The final rule in a retry configuration should always have asterisks in the -first two fields so as to provide a general catch-all for any addresses that do -not have their own special handling. This example tries every 15 minutes for 2 -hours, then with intervals starting at one hour and increasing by a factor of -1.5 up to 16 hours, then every 8 hours up to 5 days. - - -.section Timeout of retry data -.index timeout||of retry data -.index \retry@_data@_expire\ -.index hints database||data expiry -.index retry||timeout of data -Exim timestamps the data that it writes to its retry hints database. When it -consults the data during a delivery it ignores any that is older than the value -set in \retry@_data@_expire\ (default 7 days). If, for example, a host hasn't -been tried for 7 days, Exim will try to deliver to it immediately a message -arrives, and if that fails, it will calculate a retry time as if it were -failing for the first time. - -This improves the behaviour for messages routed to rarely-used hosts such as MX -backups. If such a host was down at one time, and happens to be down again when -Exim tries a month later, using the old retry data would imply that it had been -down all the time, which is not a justified assumption. - -If a host really is permanently dead, this behaviour causes a burst of retries -every now and again, but only if messages routed to it are rare. It there is a -message at least once every 7 days the retry data never expires. - - - -.section Long-term failures -.index delivery||failure, long-term -.index retry||after long-term failure -Special processing happens when an email address has been failing for so long -that the cutoff time for the last algorithm is reached. For example, using the -default retry rule: -.display asis -* * F,2h,15m; G,16h,1h,1.5; F,4d,6h -.endd -the cutoff time is four days. Reaching the retry cutoff is independent of how -long any specific message has been failing; it is the length of continuous -failure for the recipient address that counts. - -When the cutoff time is reached for a local delivery, or for all the IP -addresses associated with a remote delivery, a subsequent delivery failure -causes Exim to give up on the address, and a bounce message is generated. -In order to cater for new messages that use the failing address, a next retry -time is still computed from the final algorithm, and is used as follows: - -For local deliveries, one delivery attempt is always made for any subsequent -messages. If this delivery fails, the address fails immediately. The -post-cutoff retry time is not used. - -If the delivery is remote, there are two possibilities, controlled by the -.index \delay@_after@_cutoff\ -\delay@_after@_cutoff\ option of the \%smtp%\ transport. The option is true by -default and in that case: -.numberpars " " -Until the post-cutoff retry time for one of the IP addresses is reached, -the failing email address is bounced immediately, without a delivery attempt -taking place. After that time, one new delivery attempt is made to those IP -addresses that are past their retry times, and if that still fails, the address -is bounced and new retry times are computed. -.endp - -In other words, when all the hosts for a given email address have been failing -for a long time, Exim bounces rather then defers until one of the hosts' retry -times is reached. Then it tries once, and bounces if that attempt fails. This -behaviour ensures that few resources are wasted in repeatedly trying to deliver -to a broken destination, but if the host does recover, Exim will eventually -notice. - -If \delay@_after@_cutoff\ is set false, Exim behaves differently. If all IP -addresses are past their final cutoff time, Exim tries to deliver to those IP -addresses that have not been tried since the message arrived. If there are -no suitable IP addresses, or if they all fail, the address is bounced. In other -words, it does not delay when a new message arrives, but tries the expired -addresses immediately, unless they have been tried since the message arrived. -If there is a continuous stream of messages for the failing domains, setting -\delay@_after@_cutoff\ false means that there will be many more attempts to -deliver to permanently failing IP addresses than when \delay@_after@_cutoff\ is -true. - -.section Ultimate address timeout -.index retry||ultimate address timeout -An additional rule is needed to cope with cases where a host is intermittently -available, or when a message has some attribute that prevents its delivery when -others to the same address get through. In this situation, because some -messages are successfully delivered, the `retry clock' for the address keeps -getting restarted, and so a message could remain on the queue for ever. To -prevent this, if a message has been on the queue for longer than the cutoff -time of any applicable retry rule for a given address, a delivery is attempted -for that address, even if it is not yet time, and if this delivery fails, the -address is timed out. A new retry time is not computed in this case, so that -other messages for the same address are considered immediately. - - - - - -. -. -. -. -. ============================================================================ -.chapter SMTP authentication -.set runningfoot "SMTP authentication" -.rset CHAPSMTPAUTH "~~chapter" -.index SMTP||authentication configuration -.index authentication -The `authenticators' section of Exim's run time configuration is concerned with -SMTP authentication. This facility is an extension to the SMTP protocol, -described in RFC 2554, which allows a client SMTP host to authenticate itself -to a server. This is a common way for a server to recognize clients that -are permitted to use it as a relay. SMTP authentication is not of relevance to -the transfer of mail between servers that have no managerial connection with -each other. - -.index \\AUTH\\||description of -Very briefly, the way SMTP authentication works is as follows: -.numberpars $. -The server advertises a number of authentication \*mechanisms*\ in response to -the client's \\EHLO\\ command. -.nextp -The client issues an \\AUTH\\ command, naming a specific mechanism. The command -may, optionally, contain some authentication data. -.nextp -The server may issue one or more \*challenges*\, to which the client must send -appropriate responses. In simple authentication mechanisms, the challenges are -just prompts for user names and passwords. The server does not have to issue -any challenges -- in some mechanisms the relevant data may all be transmitted -with the \\AUTH\\ command. -.nextp -The server either accepts or denies authentication. -.nextp -If authentication succeeds, the client may optionally make use of the \\AUTH\\ -option on the \\MAIL\\ command to pass an authenticated sender in subsequent -mail transactions. Authentication lasts for the remainder of the SMTP -connection. -.nextp -If authentication fails, the client may give up, or it may try a different -authentication mechanism, or it may try transferring mail over the -unauthenticated connection. -.endp -If you are setting up a client, and want to know which authentication -mechanisms the server supports, you can use Telnet to connect to port 25 (the -SMTP port) on the server, and issue an \\EHLO\\ command. The response to this -includes the list of supported mechanisms. For example: -.display -@$ $cb{telnet server.example 25} -Trying 192.168.34.25... -Connected to server.example. -Escape character is '@^]'. -220 server.example ESMTP Exim 4.20 ... -$cb{ehlo client.example} -250-server.example Hello client.example [10.8.4.5] -250-SIZE 52428800 -250-PIPELINING -250-AUTH PLAIN -250 HELP -.endd -The second-last line of this example output shows that the server supports -authentication using the PLAIN mechanism. In Exim, the different authentication -mechanisms are configured by specifying \*authenticator*\ drivers. Like the -routers and transports, which authenticators are included in the binary is -controlled by build-time definitions. The following are currently available, -included by setting -.display asis -AUTH_CRAM_MD5=yes -AUTH_PLAINTEXT=yes -AUTH_SPA=yes -.endd -in \(Local/Makefile)\, respectively. The first of these supports the CRAM-MD5 -authentication mechanism (RFC 2195), and the second can be configured to -support the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, -which is not formally documented, but used by several MUAs. The third -authenticator supports Microsoft's \*Secure Password Authentication*\ -mechanism. - -The authenticators are configured using the same syntax as other drivers (see -section ~~SECTfordricon). If no authenticators are required, no authentication -section need be present in the configuration file. Each authenticator can in -principle have both server and client functions. When Exim is receiving SMTP -mail, it is acting as a server; when it is sending out messages over SMTP, it -is acting as a client. Authenticator configuration options are provided for use -in both these circumstances. - -To make it clear which options apply to which situation, the prefixes -\server@_\ and \client@_\ are used on option names that are specific to either -the server or the client function, respectively. Server and client functions -are disabled if none of their options are set. If an authenticator is to be -used for both server and client functions, a single definition, using both sets -of options, is required. For example: -.display asis -cram: - driver = cram_md5 - public_name = CRAM-MD5 - server_secret = ${if eq{$1}{ph10}{secret1}fail} - client_name = ph10 - client_secret = secret2 -.endd -The \server@_\ option is used when Exim is acting as a server, and the -\client@_\ options when it is acting as a client. - -Descriptions of the individual authenticators are given in subsequent chapters. -The remainder of this chapter covers the generic options for the -authenticators, followed by general discussion of the way authentication works -in Exim. - - -.section Generic options for authenticators -.index authentication||generic options - -.startconf authenticators -.index options||generic, for authenticators - -.conf driver string unset -This option must always be set. It specifies which of the available -authenticators is to be used. - -.conf public@_name string unset -This option specifies the name of the authentication mechanism that the driver -implements, and by which it is known to the outside world. These names should -contain only upper case letters, digits, underscores, and hyphens (RFC 2222), -but Exim in fact matches them caselessly. If \public@_name\ is not set, it -defaults to the driver's instance name. - -.conf server@_advertise@_condition string$**$ unset -When a server is about to advertise an authentication mechanism, the condition -is expanded. If it yields the empty string, `0', `no', or `false', the -mechanism is not advertised. -If the expansion fails, the mechanism is not advertised. If the failure was not -forced, and was not caused by a lookup defer, the incident is logged. -See section ~~SECTauthexiser below for further discussion. - -.conf server@_debug@_print string$**$ unset -If this option is set and authentication debugging is enabled (see the \-d-\ -command line option), the string is expanded and included in the debugging -output when the authenticator is run as a server. This can help with checking -out the values of variables. -If expansion of the string fails, the error message is written to the debugging -output, and Exim carries on processing. - -.conf server@_set@_id string$**$ unset -When an Exim server successfully authenticates a client, this string is -expanded using data from the authentication, and preserved for any incoming -messages in the variable \$authenticated@_id$\. It is also included in the log -lines for incoming messages. For example, a user/password authenticator -configuration might preserve the user name that was used to authenticate, and -refer to it subsequently during delivery of the message. -If expansion fails, the option is ignored. - -.conf server@_mail@_auth@_condition string$**$ unset -This option allows a server to discard authenticated sender addresses supplied -as part of \\MAIL\\ commands in SMTP connections that are authenticated by the -driver on which \server__mail__auth@_condition\ is set. The option is not used -as part of the authentication process; instead its (unexpanded) value is -remembered for later use. -How it is used is described in the following section. -.endconf - - - -.section The AUTH parameter on MAIL commands -.rset SECTauthparamail "~~chapter.~~section" -.index authentication||sender, authenticated -.index \\AUTH\\||on \\MAIL\\ command -When a client supplied an \\AUTH=\\ item on a \\MAIL\\ command, Exim applies -the following checks before accepting it as the authenticated sender of the -message: -.numberpars $. -If the connection is not using extended SMTP (that is, \\HELO\\ was used rather -than \\EHLO\\), the use of \\AUTH=\\ is a syntax error. -.nextp -If the value of the \\AUTH=\\ parameter is `@<@>', it is ignored. -.nextp -If \acl@_smtp@_mailauth\ is defined, the ACL it specifies is run. While it is -running, the value of \$authenticated@_sender$\ is set to the value obtained -from the \\AUTH=\\ parameter. If the ACL does not yield `accept', the value of -\$authenticated@_sender$\ is deleted. The \acl@_smtp@_mailauth\ ACL may not -return `drop' or `discard'. If it defers, a temporary error code (451) is given -for the \\MAIL\\ command. -.nextp -If \acl@_smtp@_mailauth\ is not defined, the value of the \\AUTH=\\ parameter -is accepted and placed in \$authenticated@_sender$\ only if the client has -authenticated. -.nextp -If the \\AUTH=\\ value was accepted by either of the two previous rules, and -the client has authenticated, and the authenticator has a setting for the -\server@_mail@_auth@_condition\, the condition is checked at this point. The -valued that was saved from the authenticator is expanded. If the expansion -fails, or yields an empty string, `0', `no', or `false', the value of -\$authenticated__sender$\ is deleted. If the expansion yields any other value, -the value of \$authenticated@_sender$\ is retained and passed on with the -message. -.endp - -When \$authenticated@_sender$\ is set for a message, it is passed on to other -hosts to which Exim authenticates as a client. Do not confuse this value with -\$authenticated@_id$\, which is a string obtained from the authentication -process, and which is not usually a complete email address. - -Whenever an \\AUTH=\\ value is ignored, the incident is logged. The ACL for -\\MAIL\\, if defined, is run after \\AUTH=\\ is accepted or ignored. It can -therefore make use of \$authenticated@_sender$\. The converse is not true: the -value of \$sender@_address$\ is not yet set up when the \acl@_smtp@_mailauth\ -ACL is run. - - -.section Authentication on an Exim server -.rset SECTauthexiser "~~chapter.~~section" -.index authentication||on an Exim server -When Exim receives an \\EHLO\\ command, it advertises the public names of those -authenticators that are configured as servers, subject to the following -conditions: -.numberpars $. -The client host must match \auth@_advertise@_hosts\ (default $*$). -.nextp -It the \server@_advertise@_condition\ option is set, its expansion must not -yield the empty string, `0', `no', or `false'. -.endp -The order in which the authenticators are defined controls the order in which -the mechanisms are advertised. - -Some mail clients (for example, some versions of Netscape) require the user to -provide a name and password for authentication whenever \\AUTH\\ is advertised, -even though authentication may not in fact be needed (for example, Exim may be -set up to allow unconditional relaying from the client by an IP address check). -You can make such clients more friendly by not advertising \\AUTH\\ to them. -For example, if clients on the 10.9.8.0/24 network are permitted (by the ACL -that runs for \\RCPT\\) to relay without authentication, you should set -.display asis -auth_advertise_hosts = ! 10.9.8.0/24 -.endd -so that no authentication mechanisms are advertised to them. - -The \server@_advertise@_condition\ controls the advertisement of individual -authentication mechanisms. For example, it can be used to restrict the -advertisement of a patricular mechanism to encrypted connections, by a setting -such as: -.display asis -server_advertise_condition = ${if eq{$tls_cipher}{}{no}{yes}} -.endd -If the session is encrypted, \$tls@_cipher$\ is not empty, and so the expansion -yields `yes', which allows the advertisement to happen. - -When an Exim server receives an \\AUTH\\ command from a client, it rejects it -immediately if \\AUTH\\ was not advertised in response to an earlier \\EHLO\\ -command. This is the case if -.numberpars $. -The client host does not match \auth@_advertise@_hosts\; or -.nextp -No authenticators are configured with server options; or -.nextp -Expansion of \server@_advertise@_condition\ blocked the advertising of all the -server authenticators. -.endp - -Otherwise, Exim runs the ACL specified by \acl@_smtp@_auth\ in order -to decide whether to accept the command. If \acl@_smtp@_auth\ is not set, -\\AUTH\\ is accepted from any client host. - -If \\AUTH\\ is not rejected by the ACL, Exim searches its configuration for a -server authentication mechanism that was advertised in response to \\EHLO\\ and -that matches the one named in the \\AUTH\\ command. If it finds one, it runs -the appropriate authentication protocol, and authentication either succeeds or -fails. If there is no matching advertised mechanism, the \\AUTH\\ command is -rejected with a 504 error. - -When a message is received from an authenticated host, the value of -\$received@_protocol$\ is set to -.em -`esmtpa' -.nem -instead of `esmtp', and \$sender@_host@_authenticated$\ contains the name (not -the public name) of the authenticator driver that successfully authenticated -the client from which the message was received. This variable is empty if there -was no successful authentication. - - - -.section Testing server authentication -.index authentication||testing a server -.index \\AUTH\\||testing a server -.index base64 encoding||creating authentication test data -Exim's \-bh-\ option can be useful for testing server authentication -configurations. The data for the \\AUTH\\ command has to be sent using base64 -encoding. A quick way to produce such data for testing is the following Perl -script: -.display asis -use MIME::Base64; -printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); -.endd -.index binary zero||in authentication data -This interprets its argument as a Perl string, and then encodes it. The -interpretation as a Perl string allows binary zeros, which are required for -some kinds of authentication, to be included in the data. For example, a -command line to run this script on such data might be -.display asis -encode '\0user\0password' -.endd -Note the use of single quotes to prevent the shell interpreting the -backslashes, so that they can be interpreted by Perl to specify characters -whose code value is zero. - -\**Warning 1**\: If either of the user or password strings starts with an octal -digit, you must use three zeros instead of one after the leading backslash. If -you do not, the octal digit that starts your string will be incorrectly -interpreted as part of the code for the first character. - -\**Warning 2**\: If there are characters in the strings that Perl interprets -specially, you must use a Perl escape to prevent them being misinterpreted. For -example, a command such as -.display asis -encode '\0user@domain.com\0pas$$word' -.endd -gives an incorrect answer because of the unescaped `@@' and `@$' characters. - -If you have the \mimencode\ command installed, another way to do produce -base64-encoded strings is to run the command -.display asis -echo -e -n `\0user\0password' | mimencode -.endd -The \-e-\ option of \echo\ enables the interpretation of backslash escapes in -the argument, and the \-n-\ option specifies no newline at the end of its -output. However, not all versions of \echo\ recognize these options, so you -should check your version before relying on this suggestion. - - -.section Authentication by an Exim client -.index authentication||on an Exim client -The \%smtp%\ transport has two options called \hosts@_require@_auth\ and -\hosts@_try@_auth\. When the \%smtp%\ transport connects to a server that -announces support for authentication, and the host matches an entry in either -of these options, Exim (as a client) tries to authenticate as follows: -.numberpars $. -For each authenticator that is configured as a client, it searches the -authentication mechanisms announced by the server for one whose name -matches the public name of the authenticator. -.nextp -When it finds one that matches, it runs the authenticator's client code. -The variables \$host$\ and \$host@_address$\ are available for any string -expansions that the client might do. They are set to the server's name and -IP address. If any expansion is forced to fail, the authentication attempt -is abandoned, -and Exim moves on to the next authenticator. -Otherwise an expansion failure causes delivery to be -deferred. -.nextp -If the result of the authentication attempt is a temporary error or a timeout, -Exim abandons trying to send the message to the host for the moment. It will -try again later. If there are any backup hosts available, they are tried in the -usual way. -.nextp -If the response to authentication is a permanent error (5xx code), Exim carries -on searching the list of authenticators and tries another one if possible. If -all authentication attempts give permanent errors, or if there are no attempts -because no mechanisms match -(or option expansions force failure), -what happens depends on whether the host matches \hosts@_require@_auth\ or -\hosts@_try@_auth\. In the first case, a temporary error is generated, and -delivery is deferred. The error can be detected in the retry rules, and thereby -turned into a permanent error if you wish. In the second case, Exim tries to -deliver the message unauthenticated. -.endp -.index \\AUTH\\||on \\MAIL\\ command -When Exim has authenticated itself to a remote server, it adds the \\AUTH\\ -parameter to the \\MAIL\\ commands it sends, if it has an authenticated sender -for the message. -If the message came from a remote host, the authenticated sender is the one -that was receiving on an incoming \\MAIL\\ command, provided that the incoming -connection was authenticated and the \server@_mail@_auth\ condition allowed the -authenticated sender to be retained. If a local process calls Exim to send a -message, the sender address that is built from the login name and -\qualify@_domain\ is treated as authenticated. However, if the -\authenticated@_sender\ option is set on the \%smtp%\ transport, it overrides -the authenticated sender that was received with the message. - - - - - - -. -. -. -. -. ============================================================================ -.chapter The plaintext authenticator -.rset CHAPplaintext "~~chapter" -.set runningfoot "plaintext authenticator" -.index \%plaintext%\ authenticator -.index authenticators||\%plaintext%\ -The \%plaintext%\ authenticator can be configured to support the PLAIN and -LOGIN authentication mechanisms, both of which transfer authentication data as -plain (unencrypted) text (though base64 encoded). The use of plain text is a -security risk. If you use one of these mechanisms without also making use of -SMTP encryption (see chapter ~~CHAPTLS) you should not use the same passwords -for SMTP connections as you do for login accounts. - -.section Using plaintext in a server -When running as a server, \%plaintext%\ performs the authentication test by -expanding a string. It has the following options: - -.startconf plaintext -.index options||\%plaintext%\ authenticator (server) - -.conf server@_prompts string$**$ unset -The contents of this option, after expansion, must be a colon-separated list of -prompt strings. If expansion fails, a temporary authentication rejection is -given. - -.conf server@_condition string$**$ unset -This option must be set in order to configure the driver as a server. Its use -is described below. - -.endconf - -.index \\AUTH\\||in \%plaintext%\ authenticator -.index binary zero||in \%plaintext%\ authenticator -.index numerical variables (\$1$\, \$2$\, etc)||in \%plaintext%\ authenticator -.index base64 encoding||in \%plaintext%\ authenticator -The data sent by the client with the \\AUTH\\ command, or in response to -subsequent prompts, is base64 encoded, and so may contain any byte values -when decoded. If any data is supplied with the command, it is treated as a -list of strings, separated by NULs (binary zeros), which are placed in the -expansion variables \$1$\, \$2$\, etc. If there are more strings in -\server@_prompts\ than the number of strings supplied with the \\AUTH\\ -command, the remaining prompts are used to obtain more data. Each response from -the client may be a list of NUL-separated strings. - -Once a sufficient number of data strings have been received, -\server@_condition\ is expanded. -If the expansion is forced to fail, authentication fails. Any other expansion -failure causes a temporary error code to be returned. -If the result of a successful expansion is an empty string, `0', `no', or -`false', authentication fails. If the result of the expansion is `1', `yes', or -`true', authentication succeeds and the generic \server@_set@_id\ option is -expanded and saved in \$authenticated@_id$\. For any other result, a temporary -error code is returned, with the expanded string as the error text. - -\**Warning**\: If you use a lookup in the expansion to find the user's -password, be sure to make the authentication fail if the user is unknown. -There are good and bad examples at the end of the next section. - - -.section The PLAIN authentication mechanism -.index PLAIN authentication mechanism -.index authentication||PLAIN mechanism -.index binary zero||in \%plaintext%\ authenticator -The PLAIN authentication mechanism (RFC 2595) specifies that three strings be -sent as one item of data (that is, one combined string containing two NUL -separators). The data is sent either as part of the \\AUTH\\ command, or -subsequently in response to an empty prompt from the server. - -The second and third strings are a user name and a corresponding password. -Using a single fixed user name and password as an example, this could be -configured as follows: -.display asis -fixed_plain: - driver = plaintext - public_name = PLAIN - server_prompts = : - server_condition = \ - ${if and {{eq{$2}{username}}{eq{$3}{mysecret}}}{yes}{no}} - server_set_id = $2 -.endd -The \server@_prompts\ setting specifies a single, empty prompt (empty items at -the end of a string list are ignored). If all the data comes as part of the -\\AUTH\\ command, as is commonly the case, the prompt is not used. This -authenticator is advertised in the response to \\EHLO\\ as -.display asis -250-AUTH PLAIN -.endd -and a client host can authenticate itself by sending the command -.display asis -AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 -.endd -As this contains three strings (more than the number of prompts), no further -data is required from the client. Alternatively, the client may just send -.display asis -AUTH PLAIN -.endd -to initiate authentication, in which case the server replies with an empty -prompt. The client must respond with the combined data string. - -The data string is base64 encoded, as required by the RFC. This example, -when decoded, is \"<<NUL>>username<<NUL>>mysecret"\, where <<NUL>> represents a -zero byte. This is split up into three strings, the first of which is empty. -The \server@_condition\ option in the authenticator checks that the second two -are \"username"\ and \"mysecret"\ respectively. - -Having just one fixed user name and password, as in this example, is not very -realistic, though for a small organization with only a handful of -authenticating clients it could make sense. - -A more sophisticated instance of this authenticator could use the user name in -\$2$\ to look up a password in a file or database, and maybe do an encrypted -comparison (see \crypteq\ in chapter ~~CHAPexpand). Here is a example of this -approach, where the passwords are looked up in a DBM file. \**Warning**\: This -is an incorrect example: -.display asis -server_condition = \ - ${if eq{$3}{${lookup{$2}dbm{/etc/authpwd}}}{yes}{no}} -.endd -The expansion uses the user name (\$2$\) as the key to look up a password, -which it then compares to the supplied password (\$3$\). Why is this example -incorrect? It works fine for existing users, but consider what happens if a -non-existent user name is given. The lookup fails, but as no success/failure -strings are given for the lookup, it yields an empty string. Thus, to defeat -the authentication, all a client has to do is to supply a non-existent user -name and an empty password. The correct way of writing this test is: -.display asis -server_condition = ${lookup{$2}dbm{/etc/authpwd}\ - {${if eq{$value}{$3}{yes}{no}}}{no}} -.endd -In this case, if the lookup succeeds, the result is checked; if the lookup -fails, authentication fails. If \crypteq\ is being used instead of \eq\, the -first example is in fact safe, because \crypteq\ always fails if its second -argument is empty. However, the second way of writing the test makes the logic -clearer. - - -.section The LOGIN authentication mechanism -.index LOGIN authentication mechanism -.index authentication||LOGIN mechanism -The LOGIN authentication mechanism is not documented in any RFC, but is in use -in a number of programs. No data is sent with the \\AUTH\\ command. Instead, a -user name and password are supplied separately, in response to prompts. The -plaintext authenticator can be configured to support this as in this example: -.display asis -fixed_login: - driver = plaintext - public_name = LOGIN - server_prompts = User Name : Password - server_condition = \ - ${if and {{eq{$1}{username}}{eq{$2}{mysecret}}}{yes}{no}} - server_set_id = $1 -.endd -Because of the way plaintext operates, this authenticator accepts data supplied -with the \\AUTH\\ command (in contravention of the specification of LOGIN), but -if the client does not supply it (as is the case for LOGIN clients), the prompt -strings are used to obtain two data items. - -Some clients are very particular about the precise text of the prompts. For -example, Outlook Express is reported to recognize only `Username:' and -`Password:'. Here is an example of a LOGIN authenticator which uses those -strings, and which uses the \ldapauth\ expansion condition to check the user -name and password by binding to an LDAP server: -.display asis -login: - driver = plaintext - public_name = LOGIN - server_prompts = Username:: : Password:: - server_condition = ${if ldapauth \ -.newline - {user="cn=${quote_ldap_dn:$1},ou=people,o=example.org" \ - pass=${quote:$2} \ -.newline - ldap://ldap.example.org/}{yes}{no}} - server_set_id = uid=$1,ou=people,o=example.org -.endd -Note the use of the \quote@_ldap@_dn\ operator to correctly quote the DN for -authentication. However, the basic \quote\ operator, rather than any of the -LDAP quoting operators, is the correct one to use for the password, because -quoting is needed only to make the password conform to the Exim syntax. At the -LDAP level, the password is an uninterpreted string. - - -.section Support for different kinds of authentication -A number of string expansion features are provided for the purpose of -interfacing to different ways of user authentication. These include checking -traditionally encrypted passwords from \(/etc/passwd)\ (or equivalent), PAM, -Radius, \ldapauth\, and \*pwcheck*\. For details see section ~~SECTexpcond. - - - -.section Using plaintext in a client -The \%plaintext%\ authenticator has just one client option: - -.startconf plaintext -.index options||\%plaintext%\ authenticator (client) - -.conf client@_send string$**$ unset -The string is a colon-separated list of authentication data strings. Each -string is independently expanded before being sent to the server. The first -string is sent with the \\AUTH\\ command; any more strings are sent in response -to prompts from the server. - -\**Note**\: you cannot use expansion to create multiple strings, because -splitting takes priority and happens first. - -Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in -the data, further processing is applied to each string before it is sent. If -there are any single circumflex characters in the string, they are converted to -NULs. Should an actual circumflex be required as data, it must be doubled in -the string. - -.endconf - -This is an example of a client configuration that implements the PLAIN -authentication mechanism with a fixed user name and password: -.display asis -fixed_plain: - driver = plaintext - public_name = PLAIN - client_send = ^username^mysecret -.endd -The lack of colons means that the entire text is sent with the \\AUTH\\ -command, with the circumflex characters converted to NULs. A similar example -that uses the LOGIN mechanism is: -.display asis -fixed_login: - driver = plaintext - public_name = LOGIN - client_send = : username : mysecret -.endd -The initial colon means that the first string is empty, so no data is sent with -the \\AUTH\\ command itself. The remaining strings are sent in response to -prompts. - - - - -. -. -. -. -. ============================================================================ -.chapter The cram@_md5 authenticator -.set runningfoot "cram@_md5 authenticator" -.index \%cram@_md5%\ authenticator -.index authenticators||\%cram@_md5%\ -.index CRAM-MD5 authentication mechanism -.index authentication||CRAM-MD5 mechanism -The CRAM-MD5 authentication mechanism is described in RFC 2195. The server -sends a challenge string to the client, and the response consists of a user -name and the CRAM-MD5 digest of the challenge string combined with a secret -string (password) which is known to both server and client. Thus, the secret -is not sent over the network as plain text, which makes this authenticator more -secure than \%plaintext%\. However, the downside is that the secret has to be -available in plain text at either end. - -.section Using cram@_md5 as a server -This authenticator has one server option, which must be set to configure the -authenticator as a server: - -.startconf cram@_md5 -.index options||\%cram@_md5%\ authenticator (server) - -.conf server@_secret string$**$ unset -.index numerical variables (\$1$\, \$2$\, etc)||in \%cram@_md5%\ authenticator -When the server receives the client's response, the user name is placed in -the expansion variable \$1$\, and \server@_secret\ is expanded to obtain the -password for that user. The server then computes the CRAM-MD5 digest that the -client should have sent, and checks that it received the correct string. If the -expansion of \server@_secret\ is forced to fail, authentication fails. If the -expansion fails for some other reason, a temporary error code is returned to -the client. - -.endconf - -For example, the following authenticator checks that the user name given by the -client is `ph10', and if so, uses `secret' as the password. For any other user -name, authentication fails. -.display asis -fixed_cram: - driver = cram_md5 - public_name = CRAM-MD5 - server_secret = ${if eq{$1}{ph10}{secret}fail} - server_set_id = $1 -.endd -If authentication succeeds, the setting of \server@_set@_id\ preserves the user -name in \$authenticated@_id$\. -A more tyical configuration might look up the secret string in a file, using -the user name as the key. For example: -.display asis -lookup_cram: - driver = cram_md5 - public_name = CRAM-MD5 - server_secret = ${lookup{$1}lsearch{/etc/authpwd}{$value}fail} - server_set_id = $1 -.endd -Note that this expansion explicitly forces failure if the lookup fails -because \$1$\ contains an unknown user name. - -.section Using cram@_md5 as a client -When used as a client, the \%cram@_md5%\ authenticator has two options: - -.startconf cram@_md5 -.index options||\%cram@_md5%\ authenticator (client) - -.conf client@_name string$**$ "the primary host name" -This string is expanded, and the result used as the user name data when -computing the response to the server's challenge. - -.conf client@_secret string$**$ unset -This option must be set for the authenticator to work as a client. Its value is -expanded and the result used as the secret string when computing the response. - -.endconf - -Different user names and secrets can be used for different servers by referring -to \$host$\ or \$host@_address$\ in the options. - -Forced failure of either expansion string is treated as an indication that this -authenticator is not prepared to handle this case. Exim moves on to the next -configured client authenticator. Any other expansion failure causes Exim to -give up trying to send the message to the current server. - -A simple example configuration of a \%cram@_md5%\ authenticator, using fixed -strings, is: -.display asis -fixed_cram: - driver = cram_md5 - public_name = CRAM-MD5 - client_name = ph10 - client_secret = secret -.endd - - - - -. -. -. -. -. ============================================================================ -.chapter The cyrus@_sasl authenticator -.set runningfoot "cyrus@_sasl authenticator" -.index \%cyrus@_sasl%\ authenticator -.index authenticators||\%cyrus@_sasl%\ -.index Cyrus, SASL library -.em -The code for this authenticator was provided by Matthew Byng-Maddick of A L -Digital Ltd (\?http://www.aldigital.co.uk?\). - -The \%cyrus@_sasl%\ authenticator provides server support for the Cyrus SASL -library implementation of the RFC 2222 (`Simple Authentication and Security -Layer'). This library supports a number of authentication mechanisms, including -PLAIN and LOGIN, but also several others that Exim does not support directly. -In particular, there is support for Kerberos authentication. - -The \%cyrus@_sasl%\ authenticator provides a gatewaying mechanism directly to -the Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, -then so can the \%cyrus@_sasl%\ authenticator. By default it uses the public -name of the driver to determine which mechanism to support. - -Where access to some kind of secret file is required, for example in GSSAPI -or CRAM-MD5, it is worth noting that the authenticator runs as the \*exim*\ -user, and that the Cyrus SASL library has no way of escalating privileges -by default. You may also find you need to set environment variables, -depending on the driver you are using. - -.section Using cyrus@_sasl as a server -The \%cyrus@_sasl%\ authenticator has four private options. It puts the -username (on a successful authentication) into \$1$\. - -.startconf cyrus@_sasl -.conf server@_hostname string$**$ $tt{$primary@_hostname} -This option selects the hostname that is used when communicating with -the library. It is up to the underlying SASL plug-in what it does with -this data. - -.conf server@_mech string $tt{public@_name} -This option selects the authentication mechanism this driver should -use. It allows you to use a different underlying mechanism from the -advertised name. For example: -.display asis -sasl: - driver = cyrus_sasl - public_name = X-ANYTHING - server_mech = CRAM-MD5 - server_set_id = $1 -.endd - -.conf server@_realm string unset -This specifies the SASL realm that the server claims to be in. - -.conf server@_service string $tt{smtp} -This is the SASL service that the server claims to implement. - -.endconf - -For straightforward cases, you do not need to set any of the authenticator's -private options. All you need to do is to specify an appropriate mechanism as -the public name. Thus, if you have a SASL library that supports CRAM-MD5 and -PLAIN, you could have two authenticators as follows: -.display asis -sasl_cram_md5: - driver = cyrus_sasl - public_name = CRAM-MD5 - server_set_id = $1 - -sasl_plain: - driver = cyrus_sasl - public_name = PLAIN - server_set_id = $1 -.endd - -Cyrus SASL does implement the LOGIN authentication method, even though it is -not a standard method. It is disabled by default in the source distribution, -but it is present in many binary distributions. - -.nem - - - -. -. -. -. -. ============================================================================ -.chapter The spa authenticator -.set runningfoot "spa authenticator" -.index \%spa%\ authenticator -.index authenticators||\%spa%\ -.index authentication||Microsoft Secure Password -.index authentication||NTLM -.index Microsoft Secure Password Authentication -.index NTLM authentication -The \%spa%\ authenticator provides client support for Microsoft's \*Secure -Password Authentication*\ mechanism, -which is also sometimes known as NTLM (NT LanMan). The code for client side of -this authenticator was contributed by Marc Prud'hommeaux, and much of it is -taken from the Samba project (\?http://www.samba.org?\). The code for the -server side was subsequently contributed by Tom Kistner. - -The mechanism works as follows: -.numberpars $. -After the \\AUTH\\ command has been accepted, the client sends an SPA -authentication request based on the user name and optional domain. -.nextp -The server sends back a challenge. -.nextp -The client builds a challenge response which makes use of the user's password -and sends it to the server, which then accepts or rejects it. -.endp -Encryption is used to protect the password in transit. - - -.section Using spa as a server -The \%spa%\ authenticator has just one server option: - -.startconf spa -.index options||\%spa%\ authenticator (server) - -.conf server@_password string$**$ unset -.index numerical variables (\$1$\, \$2$\, etc)||in \%spa%\ authenticator -This option is expanded, and the result must be the cleartext password for the -authenticating user, whose name is at this point in \$1$\. For example: -.display asis -spa: - driver = spa - public_name = NTLM - server_password = ${lookup{$1}lsearch{/etc/exim/spa_clearpass}} -.endd -If the expansion is forced to fail, authentication fails. Any other expansion -failure causes a temporary error code to be returned. - -.endconf - - - -.section Using spa as a client -The \%spa%\ authenticator has the following client options: - -.startconf spa -.index options||\%spa%\ authenticator (client) - -.conf client@_domain string$**$ unset -This option specifies an optional domain for the authentication. - -.conf client@_password string$**$ unset -This option specifies the user's password, and must be set. - -.conf client@_username string$**$ unset -This option specifies the user name, and must be set. - -.endconf - -Here is an example of a configuration of this authenticator for use with the -mail servers at \*msn.com*\: -.display asis -msn: - driver = spa - public_name = MSN - client_username = msn/msn_username - client_password = msn_plaintext_password - client_domain = DOMAIN_OR_UNSET -.endd - - - - - - -. -. -. -. -. ============================================================================ -.chapter Encrypted SMTP connections using TLS/SSL -.set runningfoot "TLS encryption" -.rset CHAPTLS "~~chapter" -.index encryption||on SMTP connection -.index SMTP||encryption -.index TLS||on SMTP connection -.index OpenSSL -.index GnuTLS -Support for TLS (Transport Layer Security), formerly known as SSL (Secure -Sockets Layer), is implemented by making use of the OpenSSL library or the -GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no -cryptographic code in the Exim distribution itself for implementing TLS. In -order to use this feature you must install OpenSSL or GnuTLS, and then build a -version of Exim that includes TLS support (see section ~~SECTinctlsssl). You -also need to understand the basic concepts of encryption at a managerial level, -and in particular, the way that public keys, private keys, and certificates are -used. - -RFC 2487 defines how SMTP connections can make use of encryption. Once a -connection is established, the client issues a \\STARTTLS\\ command. If the -server accepts this, the client and the server negotiate an encryption -mechanism. If the negotiation succeeds, the data that subsequently passes -between them is encrypted. - -Exim's ACLs can detect whether the current SMTP session is encrypted or not, -and if so, what cipher suite is in use, whether the client supplied a -certificate, and whether or not that certificate was verified. This makes it -possible for an Exim server to deny or accept certain commands based on the -encryption state. - -\**Warning**\: certain types of firewall and certain anti-virus products can -disrupt TLS connections. You need to turn off SMTP scanning for these products -in order to get TLS to work. - - -.em -.section Support for the legacy `ssmtp' (aka `smtps') protocol -.index ssmtp protocol -.index smtps protocol -.index SMTP||ssmtp protocol -.index SMTP||smtps protocol -Early implementations of encrypted SMTP used a different TCP port from normal -SMTP, and expected an encryption negotiation to start immediately, instead of -waiting for a \\STARTTLS\\ command from the client using the standard SMTP -port. The protocol was called `ssmtp' or `smtps', and port 465 was allocated -for this purpose. - -This approach was abandoned when encrypted SMTP was standardised, but there are -still some legacy clients that use it. Exim supports these clients by means of -the \tls@_on@_connect@_ports\ global option. Its value must be a list of port -numbers; the most common use is expected to be: -.display asis -tls_on_connect_ports = 465 -.endd -The port numbers specified by this option apply to all SMTP connections, both -via the daemon and via \*inetd*\. You still need to specify all the ports that -the daemon uses (by setting \daemon@_smtp@_ports\ or \local@_interfaces\ or the -\-oX-\ command line option) because \tls@_on@_connect@_ports\ does not add an -extra port -- rather, it specifies different behaviour on a port that is -defined elsewhere. - -There is also a \-tls-on-connect-\ command line option. This overrides -\tls@_on@_connect@_ports\; it forces the legacy behaviour for all ports. -.nem - - - - -.section OpenSSL vs GnuTLS -.index TLS||OpenSSL \*vs*\ GnuTLS -.rset SECTopenvsgnu "~~chapter.~~section" -The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS -followed later, when the first versions of GnuTLS were released. To build Exim -to use GnuTLS, you need to set -.display asis -USE_GNUTLS=yes -.endd -in Local/Makefile, in addition to -.display asis -SUPPORT_TLS=yes -.endd -You must also set \\TLS@_LIBS\\ and \\TLS@_INCLUDE\\ appropriately, so that the -include files and libraries for GnuTLS can be found. - -There are some differences in usage when using GnuTLS instead of OpenSSL: -.numberpars $. -The \tls@_verify@_certificates\ option must contain the name of a file, not the -name of a directory (for OpenSSL it can be either). -.nextp -The \tls@_dhparam\ option is ignored, because early versions of GnuTLS had no -facility for varying its Diffie-Hellman parameters. I understand that this has -changed, but Exim has not been updated to provide this facility. -.nextp -GnuTLS uses RSA and D-H parameters that take a substantial amount of -time to compute. It is unreasonable to re-compute them for every TLS -session. Therefore, Exim keeps this data in a file in its spool -directory, called \(gnutls-params)\. The file is owned by the Exim user and is -readable only by its owner. Every Exim process that start up GnuTLS reads the -RSA and D-H parameters from this file. If the file does not exist, the first -Exim process that needs it computes the data and writes it to a temporary file -which is renamed once it is complete. It does not matter if several Exim -processes do this simultaneously (apart from wasting a few resources). Once a -file is in place, new Exim processes immediately start using it. - -For maximum security, the parameters that are stored in this file should be -recalculated periodically, the frequency depending on your paranoia level. -Arranging this is easy; just delete the file when you want new values to be -computed. -.nextp -Distinguished Name (DN) strings reported by the OpenSSL library use a slash for -separating fields; GnuTLS uses commas, in accordance with RFC 2253. This -affects the value of the \$tls@_peerdn$\ variable. -.nextp -OpenSSL identifies cipher suites using hyphens as separators, for example: -DES-CBC3-SHA. GnuTLS uses underscores, for example: RSA@_ARCFOUR@_SHA. What is -more, OpenSSL complains if underscores are present in a cipher list. To make -life simpler, Exim changes underscores to hyhens for OpenSSL and hyphens to -underscores for GnuTLS when processing lists of cipher suites in the -\tls@_require@_ciphers\ options (the global option and the \%smtp%\ transport -option). -.nextp -The \tls@_require@_ciphers\ options operate differently, as described in the -following sections. -.endp - -.section Requiring specific ciphers in OpenSSL -.rset SECTreqciphssl "~~chapter.~~section" -.index TLS||requiring specific ciphers (OpenSSL) -.index \tls@_require@_ciphers\||OpenSSL -There is a function in the OpenSSL library that can be passed a list of cipher -suites before the cipher negotiation takes place. This specifies which ciphers -are acceptable. The list is colon separated and may contain names like -DES-CBC3-SHA. Exim passes the expanded value of \tls@_require@_ciphers\ -directly to this function call. The following quotation from the OpenSSL -documentation specifies what forms of item are allowed in the cipher string: -.numberpars $. -It can consist of a single cipher suite such as RC4-SHA. -.nextp -It can represent a list of cipher suites containing a certain algorithm, -or cipher suites of a certain type. For example SHA1 represents all -ciphers suites using the digest algorithm SHA1 and SSLv3 represents all -SSL v3 algorithms. -.nextp -Lists of cipher suites can be combined in a single cipher string using -the + character. This is used as a logical and operation. For example -SHA1+DES represents all cipher suites containing the SHA1 and the DES -algorithms. -.nextp -Each cipher string can be optionally preceded by the characters \"!"\, \"-"\ or -\"+"\. -.numberpars " " -If \"!"\ is used then the ciphers are permanently deleted from the list. The -ciphers deleted can never reappear in the list even if they are explicitly -stated. -.nextp -If \"-"\ is used then the ciphers are deleted from the list, but some or all -of the ciphers can be added again by later options. -.nextp -If \"+"\ is used then the ciphers are moved to the end of the list. This -option doesn't add any new ciphers it just moves matching existing ones. -.nextp -If none of these characters is present then the string is just interpreted as a -list of ciphers to be appended to the current preference list. If the list -includes any ciphers already present they will be ignored: that is, they will -not moved to the end of the list. -.endp -.endp - - -.section Requiring specific ciphers in GnuTLS -.rset SECTreqciphgnu "~~chapter.~~section" -.index TLS||requiring specific ciphers (GnuTLS) -.index \tls@_require@_ciphers\||GnuTLS -The GnuTLS library does not have a combined function like OpenSSL. Instead, -it allows the caller to specify separate lists of key-exchange methods, -main cipher algorithms, and MAC algorithms. Unfortunately, these lists are -numerical, and the library does not have a function for turning names into -numbers. Consequently, the list of recognized names has to be built into -the application. - -At present, Exim permits only the list of main cipher algorithms to be -changed. The \tls@_require@_ciphers\ option is in the same format as for -OpenSSL. Exim searches each item for the name of available algorithm. For -example, if the list contains RSA@_AES@_SHA then AES is recognized. - -The cipher algorithms list starts out with a default set of algorithms. If -the first item in \tls@_require@_ciphers\ does \*not*\ start with an -exclamation mark, all the default items are deleted. Thus, only those specified -can be used. If the first item in \tls@_require@_ciphers\ \*does*\ start with -an exclamation mark, the defaults are left on the list. - -Then, any item that starts with an exclamation mark causes the relevent -algorithms to be removed from the list, and any item that does not start -with an exclamation mark causes the relevant algorithms to be added to the -list. Thus, -.display asis -tls_require_ciphers = !RSA_ARCFOUR_SHA -.endd -allows all the defaults except those that use ARCFOUR, whereas -.display asis -tls_require_ciphers = AES : 3DES -.endd -allows only cipher suites that use AES and 3DES. The currently recognized -algorithms are: -.em -AES@_256, AES@_128, AES (both of the preceding), 3DES, and ARCFOUR@_128. -Unrecognized algorithms are ignored. In a server, the order of the list is -unimportant; the server will advertise the availability of all the relevant -cipher suites. However, in a client, the order of the list specifies a -preference order for the algorithms. The first one in the client's list that is -also advertised by the server is tried first. The default order is as listed -above. -.nem - - -.section Configuring an Exim server to use TLS -.index TLS||configuring an Exim server -When Exim has been built with TLS support, it advertises the availability of -the \\STARTTLS\\ command to client hosts that match \tls@_advertise@_hosts\, -but not to any others. The default value of this option is unset, which means -that \\STARTTLS\\ is not advertised at all. This default is chosen because you -need to set some other options in order to make TLS avaliable, and also it is -sensible for systems that want to use TLS only as a client. - -If a client issues a \\STARTTLS\\ command and there is some configuration -problem in the server, the command is rejected with a 454 error. If the client -persists in trying to issue SMTP commands, all except \\QUIT\\ are rejected -with the error -.display asis -554 Security failure -.endd -If a \\STARTTLS\\ command is issued within an existing TLS session, it is -rejected with a 554 error code. - -To enable TLS operations on a server, you must set \tls@_advertise@_hosts\ to -match some hosts. You can, of course, set it to $*$ to match all hosts. -However, this is not all you need to do. TLS sessions to a server won't work -without some further configuration at the server end. - -It is rumoured that all existing clients that support TLS/SSL use RSA -encryption. To make this work you need to set, in the server, -.display asis -tls_certificate = /some/file/name -tls_privatekey = /some/file/name -.endd -The first file contains the server's X509 certificate, and the second contains -the private key that goes with it. These files need to be readable by the Exim -user, and must always be given as full path names. They can be the same file if -both the certificate and the key are contained within it. If \tls@_privatekey\ -is not set, this is assumed to be the case. The certificate file may also -contain intermediate certificates that need to be sent to the client to enable -it to authenticate the server's certificate. - -If you do not understand about certificates and keys, please try to find a -source of this background information, which is not Exim-specific. (There are a -few comments below in section ~~SECTcerandall.) - -\**Note**\: These options do not apply when Exim is operating as a client -- -they apply only in the case of a server. For a client, you must set the options -of the same name in an \%smtp%\ transport. - -With just these options, Exim will work as a server with clients such as -Netscape. It does not require the client to have a certificate (but see below -for how to insist on this). There is one other option that may be needed in -other situations. If -.display asis -tls_dhparam = /some/file/name -.endd -is set, the SSL library is initialized for the use of Diffie-Hellman ciphers -with the parameters contained in the file. This increases the set of cipher -suites that the server supports. See the command -.display asis -openssl dhparam -.endd -for a way of generating this data. -At present, \tls@_dhparam\ is used only when Exim is linked with OpenSSL. It is -ignored if GnuTLS is being used. - -The strings supplied for these three options are expanded every time a client -host connects. It is therefore possible to use different certificates and keys -for different hosts, if you so wish, by making use of the client's IP address -in \$sender@_host@_address$\ to control the expansion. If a string expansion is -forced to fail, Exim behaves as if the option is not set. - -.index cipher||logging -.index log||TLS cipher -The variable \$tls@_cipher$\ is set to the cipher suite that was negotiated for -an incoming TLS connection. It is included in the ::Received:: header of an -incoming message (by default -- you can, of course, change this), and it is -also included in the log line that records a message's arrival, keyed by `X=', -unless the \tls@_cipher\ log selector is turned off. -The \encrypted\ condition can be used to test for specific cipher suites in -ACLs. - -The ACLs that run for subsequent SMTP commands can check the name of the cipher -suite and vary their actions accordingly. The cipher suite names are those used -by OpenSSL. These may differ from the names used elsewhere. For example, -OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other contexts -is known as TLS@_RSA@_WITH@_3DES@_EDE@_CBC@_SHA. Check the OpenSSL -documentation for more details. - - -.section Requesting and verifying client certificates -.index certificate||verification of client -.index TLS||client certificate verification -If you want an Exim server to request a certificate when negotiating a TLS -session with a client, you must set either \tls@_verify@_hosts\ or -\tls@_try@_verify@_hosts\. You can, of course, set either of them to $*$ to -apply to all TLS connections. For any host that matches one of these options, -Exim requests a certificate as part of the setup of the TLS session. The -contents of the certificate are verified by comparing it with a list of -expected certificates. These must be available in a file or, -for OpenSSL only (not GnuTLS), a directory, identified by -\tls@_verify@_certificates\. - -A file can contain multiple certificates, concatenated end to end. If a -directory is used -(OpenSSL only), -each certificate must be in a separate file, with a name (or a symbolic link) -of the form <<hash>>.0, where <<hash>> is a hash value constructed from the -certificate. You can compute the relevant hash by running the command -.display asis -openssl x509 -hash -noout -in /cert/file -.endd -where \(/cert/file)\ contains a single certificate. - -The difference between \tls@_verify@_hosts\ and \tls@_try@_verify@_hosts\ is -what happens if the client does not supply a certificate, or if the certificate -does not match any of the certificates in the collection named by -\tls@_verify@_certificates\. If the client matches \tls@_verify@_hosts\, the -attempt to set up a TLS session is aborted, and the incoming connection is -dropped. If the client matches \tls@_try@_verify@_hosts\, the (encrypted) SMTP -session continues. ACLs that run for subsequent SMTP commands can detect the -fact that no certificate was verified, and vary their actions accordingly. For -example, you can insist on a certificate before accepting a message for -relaying, but not when the message is destined for local delivery. - -When a client supplies a certificate (whether it verifies or not), the value of -the Distinguished Name of the certificate is made available in the variable -\$tls@_peerdn$\ during subsequent processing of the message. -.index log||distinguished name -Because it is often a long text string, it is not included in the log line or -::Received:: header by default. You can arrange for it to be logged, keyed by -`DN=', by setting the \tls@_peerdn\ log selector, and you can use -\received@_header@_text\ to change the ::Received:: header. When no certificate -is supplied, \$tls@_peerdn$\ is empty. - -.section Revoked certificates -.index TLS||revoked certificates -.index revocation list -.index certificate||revocation list -Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when -certificates are revoked. If you have such a list, you can pass it to an Exim -server using the global option called \tls@_crl\ and to an Exim client using an -identically named option for the \%smtp%\ transport. In each case, the value of -the option is expanded and must then be the name of a file that contains a CRL -in PEM format. - -.section Configuring an Exim client to use TLS -.index cipher||logging -.index log||TLS cipher -.index log||distinguished name -.index TLS||configuring an Exim client -The \tls@_cipher\ and \tls@_peerdn\ log selectors apply to outgoing SMTP -deliveries as well as to incoming, the latter one causing logging of the -server certificate's DN. The remaining client configuration for TLS is all -within the \%smtp%\ transport. - -It is not necessary to set any options to have TLS work in the \%smtp%\ -transport. If Exim is built with TLS support, and TLS is advertised by a -server, the \%smtp%\ transport always tries to start a TLS session. However, -this can be prevented by setting \hosts@_avoid@_tls\ (an option of the -transport) to a list of server hosts for which TLS should not be used. - -If you do not want Exim to attempt to send messages unencrypted when an attempt -to set up an encrypted connection fails in any way, you can set -\hosts@_require@_tls\ to a list of hosts for which encryption is mandatory. For -those hosts, delivery is always deferred if an encrypted connection cannot be -set up. If there are any other hosts for the address, they are tried in the -usual way. - -When the server host is not in \hosts@_require@_tls\, Exim may try to deliver -the message unencrypted. It always does this if the response to \\STARTTLS\\ is -a 5\*xx*\ code. For a temporary error code, or for a failure to negotiate a TLS -session after a success response code, what happens is controlled by the -\tls@_tempfail@_tryclear\ option of the \%smtp%\ transport. If it is false, -delivery to this host is deferred, and other hosts (if available) are tried. If -it is true, Exim attempts to deliver unencrypted after a 4\*xx*\ response to -\\STARTTLS\\, and if \\STARTTLS\\ is accepted, but the subsequent TLS -negotiation fails, Exim closes the current connection (because it is in an -unknown state), opens a new one to the same host, and then tries the delivery -unencrypted. - - -The \tls@_certificate\ and \tls@_privatekey\ options of the \%smtp%\ transport -provide the client with a certificate, which is passed to the server if it -requests it. If the server is Exim, it will request a certificate only if -\tls@_verify@_hosts\ or \tls@_try@_verify@_hosts\ matches the client. -\**Note**\: these options must be set in the \%smtp%\ transport for Exim to use -TLS when it is operating as a client. Exim does not assume that a server -certificate (set by the global options of the same name) should also be used -when operating as a client. - -If \tls@_verify@_certificates\ is set, it must name a file or, -for OpenSSL only (not GnuTLS), a directory, that contains a collection of -expected server certificates. The client verifies the server's certificate -against this collection, taking into account any revoked certificates that are -in the list defined by \tls@_crl\. - -If -\tls@_require@_ciphers\ is set on the \%smtp%\ transport, it must contain a -list of permitted cipher suites. If either of these checks fails, delivery to -the current host is abandoned, and the \%smtp%\ transport tries to deliver to -alternative hosts, if any. - -All the TLS options in the \%smtp%\ transport are expanded before use, with -\$host$\ and \$host@_address$\ containing the name and address of the server to -which the client is connected. Forced failure of an expansion causes Exim to -behave as if the relevant option were unset. - - -.section Multiple messages on the same encrypted TCP/IP connection -.rset SECTmulmessam "~~chapter.~~section" -.index multiple SMTP deliveries with TLS -.index TLS||multiple message deliveries -Exim sends multiple messages down the same TCP/IP connection by starting up -an entirely new delivery process for each message, passing the socket from -one process to the next. This implementation does not fit well with the use -of TLS, because there is quite a lot of state information associated with a TLS -connection, not just a socket identification. Passing all the state information -to a new process is not feasible. Consequently, Exim shuts down an existing TLS -session before passing the socket to a new process. The new process may then -try to start a new TLS session, and if successful, may try to re-authenticate -if \\AUTH\\ is in use, before sending the next message. - -The RFC is not clear as to whether or not an SMTP session continues in clear -after TLS has been shut down, or whether TLS may be restarted again later, as -just described. However, if the server is Exim, this shutdown and -reinitialization works. It is not known which (if any) other servers operate -successfully if the client closes a TLS session and continues with unencrypted -SMTP, but there are certainly some that do not work. For such servers, Exim -should not pass the socket to another process, because the failure of the -subsequent attempt to use it would cause Exim to record a temporary host error, -and delay other deliveries to that host. - -To test for this case, Exim sends an \\EHLO\\ command to the server after -closing down the TLS session. If this fails in any way, the connection is -closed instead of being passed to a new delivery process, but no retry -information is recorded. - -There is also a manual override; you can set \hosts@_nopass@_tls\ on the -\%smtp%\ transport to match those hosts for which Exim should not pass -connections to new processes if TLS has been used. - - - -.section Certificates and all that -.rset SECTcerandall "~~chapter.~~section" -.index certificate||references to discussion -In order to understand fully how TLS works, you need to know about -certificates, certificate signing, and certificate authorities. This is not the -place to give a tutorial, especially as I do not know very much about it -myself. Some helpful introduction can be found in the FAQ for the SSL addition -to Apache, currently at -.display rm -\?http://www.modssl.org/docs/2.7/ssl@_faq.html@#ToC24?\ -.endd -Other parts of the \*modssl*\ documentation are also helpful, and have -links to further files. -Eric Rescorla's book, \*SSL and TLS*\, published by Addison-Wesley (ISBN -0-201-61598-3), contains both introductory and more in-depth descriptions. -Some sample programs taken from the book are available from -.display rm -\?http://www.rtfm.com/openssl-examples/?\ -.endd - -.section Certificate chains -The file named by \tls@_certificate\ may contain more than one -certificate. This is useful in the case where the certificate that is being -sent is validated by an intermediate certificate which the other end does -not have. Multiple certificates must be in the correct order in the file. -First the host's certificate itself, then the first intermediate -certificate to validate the issuer of the host certificate, then the next -intermediate certificate to validate the issuer of the first intermediate -certificate, and so on, until finally (optionally) the root certificate. -The root certificate must already be trusted by the recipient for -validation to succeed, of course, but if it's not preinstalled, sending the -root certificate along with the rest makes it available for the user to -install if the receiving end is a client MUA that can interact with a user. - -.section Self-signed certificates -.index certificate||self-signed -You can create a self-signed certificate using the \*req*\ command provided -with OpenSSL, like this: -.display asis -openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ - -days 9999 -nodes -.endd -\(file1)\ and \(file2)\ can be the same file; the key and the certificate are -delimited and so can be identified independently. The \-days-\ option -specifies a period for which the certificate is valid. The \-nodes-\ option is -important: if you do not set it, the key is encrypted with a passphrase -that you are prompted for, and any use that is made of the key causes more -prompting for the passphrase. This is not helpful if you are going to use -this certificate and key in an MTA, where prompting is not possible. - -A self-signed certificate made in this way is sufficient for testing, and -may be adequate for all your requirements if you are mainly interested in -encrypting transfers, and not in secure identification. - -However, many clients require that the certificate presented by the server be a -user (also called `leaf' or `site') certificate, and not a self-signed -certificate. In this situation, the self-signed certificate described above -must be installed on the client host as a trusted root \*certification -authority*\ (CA), and the certificate used by Exim must be a user certificate -signed with that self-signed certificate. - -For information on creating self-signed CA certificates and using them to sign -user certificates, see the \*General implementation overview*\ chapter of the -Open-source PKI book, available online at \?http://ospkibook.sourceforge.net/?\. - - - -. -. -. -. -. ============================================================================ -.chapter Access control lists -.set runningfoot "ACL" -.rset CHAPACL "~~chapter" -.index ~~ACL||description -.index control of incoming mail -.index message||controlling incoming -.index policy control||access control lists -Access Control Lists (ACLs) are defined in a separate section of the run time -configuration file, headed by `begin acl'. Each ACL definition starts with a -name, terminated by a colon. Here is a complete ACL section that contains just -one very small ACL: -.display asis -begin acl - -small_acl: - accept hosts = one.host.only -.endd -You can have as many lists as you like in the ACL section, and the order in -which they appear does not matter. The lists are self-terminating. - -The majority of ACLs are used to control Exim's behaviour when it receives -certain SMTP commands. This applies both to incoming TCP/IP connections, and -when a local process submits a message using SMTP by specifying the \-bs-\ -option. The most common use is for controlling which recipients are accepted -in incoming messages. In addition, you can define an ACL that is used to check -local non-SMTP messages. The default configuration file contains an example of -a realistic ACL for checking \\RCPT\\ commands. This is discussed in chapter -~~CHAPdefconfil. - -.section Testing ACLs -The \-bh-\ command line option provides a way of testing your ACL configuration -locally by running a fake SMTP session with which you interact. The host -\*relay-test.mail-abuse.org*\ provides a service for checking your relaying -configuration (see section ~~SECTcheralcon for more details). - - -.section Specifying when ACLs are used -.index ~~ACL||options for specifying -In order to cause an ACL to be used, you have to name it in one of the relevant -options in the main part of the configuration. These options are: -.index \\AUTH\\||ACL for -.index \\DATA\\, ACLs for -.index \\ETRN\\||ACL for -.index \\EXPN\\||ACL for -.index \\HELO\\||ACL for -.index \\EHLO\\||ACL for -.index \\MAIL\\||ACL for -.index \\QUIT\\, ACL for -.index \\RCPT\\||ACL for -.index \\STARTTLS\\, ACL for -.index \\VRFY\\||ACL for -.index SMTP||connection, ACL for -.index non-smtp message, ACL for -.display -.tabs 20 -.if !~~sys.fancy -.tabs 24 -.fi -\acl@_not@_smtp\ $t $rm{ACL for non-SMTP messages} -\acl@_smtp@_auth\ $t $rm{ACL for \\AUTH\\} -\acl@_smtp@_connect\ $t $rm{ACL for start of SMTP connection} -\acl@_smtp@_data\ $t $rm{ACL after \\DATA\\ is complete} -\acl@_smtp@_etrn\ $t $rm{ACL for \\ETRN\\} -\acl@_smtp@_expn\ $t $rm{ACL for \\EXPN\\} -\acl@_smtp@_helo\ $t $rm{ACL for \\HELO\\ or \\EHLO\\} -\acl@_smtp@_mail\ $t $rm{ACL for \\MAIL\\} -\acl@_smtp@_mailauth\ $t $rm{ACL for the \\AUTH\\ parameter of \\MAIL\\} -.newline -.em -\acl@_smtp@_mime\ $t $rm{ACL for content-scanning MIME parts} -\acl@_smtp@_predata\ $t $rm{ACL at start of \\DATA\\ command} -\acl@_smtp@_quit\ $t $rm{ACL for \\QUIT\\} -.nem -.newline -\acl@_smtp@_rcpt\ $t $rm{ACL for \\RCPT\\} -\acl@_smtp@_starttls\ $t $rm{ACL for \\STARTTLS\\} -\acl@_smtp@_vrfy\ $t $rm{ACL for \\VRFY\\} -.endd -For example, if you set -.display asis -acl_smtp_rcpt = small_acl -.endd -the little ACL defined above is used whenever Exim receives a \\RCPT\\ command -in an SMTP dialogue. The majority of policy tests on incoming messages can be -done when \\RCPT\\ commands arrive. A rejection of \\RCPT\\ should cause the -sending MTA to give up on the recipient address contained in the \\RCPT\\ -command, whereas rejection at other times may cause the client MTA to keep on -trying to deliver the message. It is therefore recommended that you do as much -testing as possible at \\RCPT\\ time. - -.section The non-SMTP ACL -.index non-smtp message, ACL for -The non-SMTP ACL applies to all non-interactive incoming messages, that is, it -applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not -really SMTP.) This ACL is run just before the \*local@_scan()*\ function. Any -kind of rejection is treated as permanent, because there is no way of sending a -temporary error for these kinds of message. Many of the ACL conditions (for -example, host tests, and tests on the state of the SMTP connection such as -encryption and authentication) are not relevant and are forbidden in this ACL. - -.section The connect ACL -.index SMTP||connection, ACL for -The ACL test specified by \acl@_smtp@_connect\ happens after the test specified -by \host__reject__connection\ (which is now an anomaly) and any TCP Wrappers -testing (if configured). - -.em -.section The DATA ACLs -.index \\DATA\\, ACLs for -Two ACLs are associated with the \\DATA\\ command, because it is two-stage -command, with two responses being sent to the client. -When the \\DATA\\ command is received, the ACL defined by \acl@_smtp@_predata\ -is obeyed. This gives you control after all the \\RCPT\\ commands, but before -the message itself is received. It offers the opportunity to give a negative -response to the \\DATA\\ command before the data is transmitted. Header lines -added by \\MAIL\\ or \\RCPT\\ ACLs are not visible at this time, but any that -are defined here are visible when the \acl@_smtp@_data\ ACL is run. - -You cannot test the contents of the message, for example, to verify addresses -in the headers, at \\RCPT\\ time or when the \\DATA\\ command is received. Such -tests have to appear in the ACL that is run after the message itself has been -received, before the final response to the \\DATA\\ command is sent. This is -the ACL specified by \acl@_smtp@_data\, which is the second ACL that is -associated with the \\DATA\\ command. - -For both of these ACLs, it is not possible to reject individual recipients. An -error response rejects the entire message. Unfortunately, it is known that some -MTAs do not treat hard (5$it{xx}) responses to the \\DATA\\ command (either -before or after the data) correctly -- they keep the message on their queues -and try again later, but that is their problem, though it does waste some of -your resources. - -.section The MIME ACL -The \acl@_smtp@_mime\ option is available only when Exim is compiled with the -content-scanning extension. For details, see chapter ~~CHAPexiscan. - -.section The QUIT ACL -.rset SECTQUITACL "~~chapter.~~section" -.index \\QUIT\\, ACL for -The ACL for the SMTP \\QUIT\\ command is anomalous, in that the -outcome of the ACL does not affect the response code to \\QUIT\\, -which is always 221. Thus, the ACL does not in fact control any access. -For this reason, the only verbs that are permitted are \accept\ and \warn\. - -This ACL can be used for tasks such as custom logging at the end of an SMTP -session. For example, you can use ACL variables in other ACLs to count -messages, recipients, etc., and log the totals at \\QUIT\\ time using one or -more \logwrite\ modifiers on a \warn\ verb. - -You do not need to have a final \accept\, but if you do, you can use a -\message\ modifier to specify custom text that is sent as part of the 221 -response to \\QUIT\\. - -This ACL is run only for a `normal' \\QUIT\\. For certain kinds of disastrous -failure (for example, failure to open a log file, or when Exim is bombing out -because it has detected an unrecoverable error), all SMTP commands from the -client are given temporary error responses until \\QUIT\\ is received or the -connection is closed. In these special cases, the \\QUIT\\ ACL does not run. -.nem - -.section Finding an ACL to use -.index ~~ACL||finding which to use -The value of an \acl@_smtp@_$it{xxx}\ option is expanded before use, so you can -use different ACLs in different circumstances. The resulting string does not -have to be the name of an ACL in the configuration file; there are other -possibilities. Having expanded the string, Exim searches for an ACL as follows: -.numberpars $. -If the string begins with a slash, Exim uses it as a file name, and reads its -contents as an ACL. The lines are processed in the same way as lines in the -Exim configuration file. In particular, continuation lines are supported, blank -lines are ignored, as are lines whose first non-whitespace character is `@#'. -If the file does not exist or cannot be read, an error occurs (typically -causing a temporary failure of whatever caused the ACL to be run). For example: -.display asis -acl_smtp_data = /etc/acls/\ - ${lookup{$sender_host_address}lsearch\ - {/etc/acllist}{$value}{default}} -.endd -This looks up an ACL file to use on the basis of the host's IP address, falling -back to a default if the lookup fails. If an ACL is successfully read from a -file, it is retained in memory for the duration of the Exim process, so that it -can be re-used without having to re-read the file. -.nextp -If the string does not start with a slash, and does not contain any spaces, -Exim searches the ACL section of the configuration for an ACL whose name -matches the string. -.nextp -If no named ACL is found, or if the string contains spaces, Exim parses -the string as an inline ACL. This can save typing in cases where you just -want to have something like -.display asis -acl_smtp_vrfy = accept -.endd -in order to allow free use of the \\VRFY\\ command. Such a string may contain -newlines; it is processed in the same way as an ACL that is read from a file. -.endp - - -.section ACL return codes -.index ~~ACL||return codes -.em -Except for the \\QUIT\\ ACL, which does not affect the SMTP return code (see -section ~~SECTQUITACL above), the -.nem -result of running an ACL is either `accept' or `deny', or, if some test -cannot be completed (for example, if a database is down), `defer'. These -results cause 2$it{xx}, 5$it{xx}, and 4$it{xx} return codes, respectively, to -be used in the SMTP dialogue. A fourth return, `error', occurs when there is an -error such as invalid syntax in the ACL. This also causes a 4$it{xx} return -code. - -.em -For the non-SMTP ACL, `defer' and `error' are treated in the same way as -`deny', because there is no mechanism for passing temporary errors to the -submitters of non-SMTP messages. -.nem - -ACLs that are relevant to message reception may also return `discard'. This -has the effect of `accept', but causes either the entire message or an -individual recipient address to be discarded. In other words, it is a -blackholing facility. Use it with care. - -If the ACL for \\MAIL\\ returns `discard', all recipients are discarded, and no -ACL is run for subsequent \\RCPT\\ commands. The effect of `discard' in a -\\RCPT\\ ACL is to discard just the one recipient address. If there are no -recipients left when the message's data is received, the \\DATA\\ ACL is not -run. A `discard' return from the \\DATA\\ or the non-SMTP ACL discards all the -remaining recipients. -.em -The `discard' return is not permitted for the \acl@_smtp@_predata\ ACL. -.nem - -.index \*local@_scan()*\ function||when all recipients discarded -The \*local@_scan()*\ function is always run, even if there are no remaining -recipients; it may create new recipients. - - -.section Unset ACL options -.index ~~ACL||unset options -The default actions when any of the \acl@_$it{xxx}\ options are unset are not -all the same. \**Note**\: These defaults apply only when the relevant ACL is -not defined at all. For any defined ACL, the default action when control reaches -the end of the ACL statements is `deny'. - -For \acl@_not@_smtp\, \acl@_smtp@_auth\, \acl@_smtp@_connect\, -\acl@_smtp@_data\, \acl@_smtp@_helo\, \acl__smtp__mail\, \acl@_smtp@_mailauth\, -.em -\acl@_smtp@_mime\, \acl@_smtp@_predata\, \acl@_smtp@_quit\, -.nem -and \acl__smtp__starttls\, the action when the ACL is not defined is `accept'. - -For the others (\acl@_smtp@_etrn\, \acl@_smtp@_expn\, \acl@_smtp@_rcpt\, and -\acl@_smtp@_vrfy\), the action when the ACL is not defined is `deny'. -This means that \acl@_smtp@_rcpt\ must be defined in order to receive any -messages over an SMTP connection. For an example, see the ACL in the default -configuration file. - - - -.section Data for message ACLs -.index ~~ACL||data for message ACL -.em -When a \\MAIL\\ or \\RCPT\\ ACL, or either of the \\DATA\\ ACLs, is running, -the variables that contain information about the host and the message's sender -(for example, \$sender@_host@_address$\ and \$sender@_address$\) are set, and -can be used in ACL statements. In the case of \\RCPT\\ (but not \\MAIL\\ or -\\DATA\\), \$domain$\ and \$local@_part$\ are set from the argument address. - -When an ACL for the \\AUTH\\ parameter of \\MAIL\\ is running, the variables -that contain information about the host are set, but \$sender@_address$\ is not -yet set. Section ~~SECTauthparamail contains a discussion of this parameter and -how it is used. - -The \$message@_size$\ variable is set to the value of the \\SIZE\\ parameter on -the \\MAIL\\ command at \\MAIL\\, \\RCPT\\ and pre-data time, or to -1 if -that parameter is not given. The value is updated to the true message size by -the time the final \\DATA\\ ACL is run (after the message data has been -received). - -The \$rcpt@_count$\ variable increases by one for each \\RCPT\\ command -received. The \$recipients@_count$\ variable increases by one each time a -\\RCPT\\ command is accepted, so while an ACL for \\RCPT\\ is being processed, -it contains the number of previously accepted recipients. At \\DATA\\ time (for -both the \\DATA\\ ACLs), \$rcpt@_count$\ contains the total number of \\RCPT\\ -commands, and \$recipients@_count$\ contains the total number of accepted -recipients. -.nem - - - -.section Data for non-message ACLs -.rset SECTdatfornon "~~chapter.~~section" -.index ~~ACL||data for non-message ACL -.em -When an ACL is being run for \\AUTH\\, \\EHLO\\, \\ETRN\\, \\EXPN\\, \\HELO\\, -.nem -\\STARTTLS\\, or \\VRFY\\, the remainder of the SMTP command line is placed in -\$smtp@_command@_argument$\. This can be tested using a \condition\ condition. -For example, here is an ACL for use with \\AUTH\\, which insists that either -the session is encrypted, or the CRAM-MD5 authentication method is used. In -other words, it does not permit authentication methods that use cleartext -passwords on unencrypted connections. -.display asis -acl_check_auth: - accept encrypted = * -.newline -.em - accept condition = ${if eq{${uc:$smtp_command_argument}}\ - {CRAM-MD5}} -.nem -.newline - deny message = TLS encryption or CRAM-MD5 required -.endd -(Another way of applying this restriction is to arrange for the authenticators -that use cleartext passwords not to be advertised when the connection is not -encrypted. You can use the generic \server@_advertise@_condition\ authenticator -option to do this.) - - -.section Format of an ACL -.index ~~ACL||format of -.index ~~ACL||verbs, definition of -An individual ACL consists of a number of statements. Each statement starts -with a verb, optionally followed by a number of conditions and `modifiers'. -.em -Modifiers can change the way the verb operates, define error and log messages, -set variables, insert delays, and vary the processing of accepted messages. -.nem - -If all the conditions are met, the verb is obeyed. The same condition may be -used (with different arguments) more than once in the same statement. This -provides a means of specifying an `and' conjunction between conditions. For -example: -.display asis -deny dnslists = list1.example - dnslists = list2.example -.endd -If there are no conditions, the verb is always obeyed. -.em -Exim stops evaluating the conditions and modifiers when it reaches a condition -that fails. What happens then -.nem -depends on the verb (and in one case, on a special modifier). Not all the -conditions make sense at every testing point. For example, you cannot test a -sender address in the ACL that is run for a \\VRFY\\ command. - -.section ACL verbs -The ACL verbs are as follows: -.numberpars $. -.index \accept\, ACL verb -\accept\: If all the conditions are met, the ACL returns `accept'. If any of -the conditions are not met, what happens depends on whether \endpass\ appears -among the conditions (for syntax see below). If the failing condition is before -\endpass\, control is passed to the next ACL statement; if it is after -\endpass\, the ACL returns `deny'. Consider this statement, used to check a -\\RCPT\\ command: -.display asis -accept domains = +local_domains - endpass - verify = recipient -.endd -If the recipient domain does not match the \domains\ condition, control passes -to the next statement. If it does match, the recipient is verified, and the -command is accepted if verification succeeds. However, if verification fails, -the ACL yields `deny', because the failing condition is after \endpass\. -.nextp -.index \defer\, ACL verb -\defer\: If all the conditions are met, the ACL returns `defer' which, in an -SMTP session, causes a 4\*xx*\ response to be given. For a non-SMTP ACL, -\defer\ is the same as \deny\, because there is no way of sending a temporary -error. For a \\RCPT\\ command, \defer\ is much the same as using a -\%redirect%\ router and \":defer:"\ while verifying, but the \defer\ verb can -be used in any ACL, and even for a recipient it might be a simpler approach. -.nextp -.index \deny\, ACL verb -\deny\: If all the conditions are met, the ACL returns `deny'. If any of the -conditions are not met, control is passed to the next ACL statement. For -example, -.display asis -deny dnslists = blackholes.mail-abuse.org -.endd -rejects commands from hosts that are on a DNS black list. -.nextp -.index \discard\, ACL verb -\discard\: This verb behaves like \accept\, except that it returns `discard' -from the ACL instead of `accept'. It is permitted only on ACLs that are -concerned with receiving messages, and it causes recipients to be discarded. -If the \log@_message\ modifier is set when \discard\ operates, its contents are -added to the line that is automatically written to the log. - -If \discard\ is used in an ACL for \\RCPT\\, just the one recipient is -discarded; if used for \\MAIL\\, \\DATA\\ or in the non-SMTP ACL, all the -message's recipients are discarded. Recipients that are discarded before -\\DATA\\ do not appear in the log line when the \log@_recipients\ log selector -is set. -.nextp -.index \drop\, ACL verb -\drop\: This verb behaves like \deny\, except that an SMTP connection is -forcibly closed after the 5\*xx*\ error message has been sent. For example: -.display asis -drop message = I don't take more than 20 RCPTs -.newline -.em - condition = ${if > {$rcpt_count}{20}} -.nem -.endd -There is no difference between \deny\ and \drop\ for the connect-time ACL. The -connection is always dropped after sending a 550 response. -.nextp -.index \require\, ACL verb -\require\: If all the conditions are met, control is passed to the next ACL -statement. If any of the conditions are not met, the ACL returns `deny'. For -example, when checking a \\RCPT\\ command, -.display asis -require verify = sender -.endd -passes control to subsequent statements only if the message's sender can be -verified. Otherwise, it rejects the command. -.nextp -.index \warn\, ACL verb -\warn\: If all the conditions are met, a header line is added to an incoming -message and/or a line is written to Exim's main log. In all cases, control -passes to the next ACL statement. The text of the added header line and the log -line are specified by modifiers; if they are not present, a \warn\ verb just -checks its conditions and obeys any `immediate' modifiers such as \set\ and -\logwrite\. -.em -There is more about adding header lines in section ~~SECTaddheadwarn. -.nem - -If any condition on a \warn\ statement cannot be completed (that is, there is -some sort of defer), no header lines are added and the configured log line is -not written. No further conditions or modifiers in the \warn\ statement are -processed. The incident is logged, but the ACL continues to be processed, from -the next statement onwards. - -If a \message\ modifier is present on a \warn\ verb in an ACL that is not -testing an incoming message, it is ignored, and the incident is logged. - -A \warn\ statement may use the \log@_message\ modifier to cause a line to be -written to the main log when the statement's conditions are true. -If an identical log line is requested several times in the same message, only -one copy is actually written to the log. If you want to force duplicates to be -written, use the \logwrite\ modifier instead. - -When one of the \warn\ conditions is an address verification that fails, the -text of the verification failure message is in \$acl@_verify@_message$\. If you -want this logged, you must set it up explicitly. For example: -.display asis -warn !verify = sender - log_message = sender verify failed: $acl_verify_message -.endd -.endp - -At the end of each ACL there is an implicit unconditional \deny\. - -As you can see from the examples above, the conditions and modifiers are -written one to a line, with the first one on the same line as the verb, and -subsequent ones on following lines. If you have a very long condition, you can -continue it onto several physical lines by the usual backslash continuation -mechanism. It is conventional to align the conditions vertically. - - -.section ACL variables -.rset SECTaclvariables "~~chapter.~~section" -.index ~~ACL||variables -There are some special variables that can be set during ACL processing. They -can be used to pass information between different ACLs, different invocations -of the same ACL in the same SMTP connection, and between ACLs and the routers, -transports, and filters that are used to deliver a message. There are two sets -of these variables: -.numberpars $. -The values of \$acl@_c0$\ to \$acl@_c9$\ persist throughout an SMTP connection. -They are never reset. Thus, a value that is set while receiving one message is -still available when receiving the next message on the same SMTP connection. -.nextp -The values of \$acl@_m0$\ to \$acl@_m9$\ persist only while a message is being -received. They are reset afterwards. They are also reset by \\MAIL\\, \\RSET\\, -\\EHLO\\, \\HELO\\, and after starting up a TLS session. -.endp -When a message is accepted, the current values of all the ACL variables are -preserved with the message and are subsequently made available at delivery -time. The ACL variables are set by modifier called \set\. For example: -.display asis -accept hosts = whatever - set acl_m4 = some value -.endd -\**Note**\: a leading dollar sign is not used when naming a variable that is to -be set. If you want to set a variable without taking any action, you can use a -\warn\ verb without any other modifiers or conditions. - - -.section Condition and modifier processing -.index ~~ACL||conditions, processing -.index ~~ACL||modifiers, processing -An exclamation mark preceding a condition negates its result. For example, -.display asis -deny domains = *.dom.example - !verify = recipient -.endd -causes the ACL to return `deny' if the recipient domain ends in -\*dom.example*\ and the recipient address cannot be verified. - -The arguments of conditions and modifiers are expanded. A forced failure -of an expansion causes a condition to be ignored, that is, it behaves as if the -condition is true. Consider these two statements: -.display asis -accept senders = ${lookup{$host_name}lsearch\ - {/some/file}{$value}fail} -accept senders = ${lookup{$host_name}lsearch\ - {/some/file}{$value}{}} -.endd -Each attempts to look up a list of acceptable senders. If the lookup succeeds, -the returned list is searched, but if the lookup fails the behaviour is -different in the two cases. The \fail\ in the first statement causes the -condition to be ignored, leaving no further conditions. The \accept\ verb -therefore succeeds. The second statement, however, generates an empty list when -the lookup fails. No sender can match an empty list, so the condition fails, -and therefore the \accept\ also fails. - -ACL modifiers appear mixed in with conditions in ACL statements. Some of them -specify actions that are taken as the conditions for a statement are checked; -others specify text for messages that are used when access is denied or a -warning is generated. -.em -The \control\ modifier affects the way an incoming message is handled. -.nem - -The positioning of the modifiers in an ACL statement important, because the -processing of a verb ceases as soon as its outcome is known. Only those -modifiers that have already been encountered will take effect. For example, -consider this use of the \message\ modifier: -.display asis -require message = Can't verify sender - verify = sender - message = Can't verify recipient - verify = recipient - message = This message cannot be used -.endd -If sender verification fails, Exim knows that the result of the statement is -`deny', so it goes no further. The first \message\ modifier has been seen, so -its text is used as the error message. If sender verification succeeds, but -recipient verification fails, the second message is used. If recipient -verification succeeds, the third message becomes `current', but is never used -because there are no more conditions to cause failure. - -For the \deny\ verb, on the other hand, it is always the last \message\ -modifier that is used, because all the conditions must be true for rejection to -happen. Specifying more than one \message\ modifier does not make sense, and -the message can even be specified after all the conditions. For example: -.display asis -deny hosts = ... - !senders = *@my.domain.example - message = Invalid sender from client host -.endd -The `deny' result does not happen until the end of the statement is reached, by -which time Exim has set up the message. - - -.section ACL modifiers -.rset SECTACLmodi "~~chapter.~~section" -.index ~~ACL||modifiers, list of -The ACL modifiers are as follows: - -.startitems - -.item "control = <<text>>" -.index \control\, ACL modifier -.em -This modifier affects the subsequent processing of the SMTP connection or of an -incoming message that is accepted. The effect of the first type of control -lasts for the duration of the connection, whereas the effect of the second type -lasts only until the current message has been received. The message-specific -controls always apply to the whole message, not to individual recipients, -even if the \control\ modifier appears in a \\RCPT\\ ACL. - -As there are now quite a few controls that can be applied, they are described -separately in section ~~SECTcontrols. -.nem -The \control\ modifier can be used in several different ways. For example: -.numberpars $. -It can be at the end of an \accept\ statement: -.display asis -accept ...some conditions - control = queue_only -.endd -In this case, the control is applied when this statement yields `accept', in -other words, when the conditions are all true. -.nextp -It can be in the middle of an \accept\ statement: -.display asis -accept ...some conditions... - control = queue_only - ...some more conditions... -.endd -If the first set of conditions are true, the control is applied, even if the -statement does not accept because one of the second set of conditions is false. -In this case, some subsequent statement must yield `accept' for the control to -be relevant. -.nextp -It can be used with \warn\ to apply the control, leaving the -decision about accepting or denying to a subsequent verb. For -example: -.display asis -warn ...some conditions... - control = freeze -accept ... -.endd -This example of \warn\ does not contain \message\, \log@_message\, or -\logwrite\, so it does not add anything to the message and does not write a log -entry. -.nextp -.em -If you want to apply a control unconditionally, you can use it with a \require\ -verb. For example: -.display asis -require control = no_multiline_response -.nem -.endd -.endp - -.item "delay = <<time>>" -.index \delay\, ACL modifier -.index \-bh-\ option -This modifier causes Exim to wait for the time interval before proceeding. The -time is given in the usual Exim notation. This modifier may appear in any ACL. -The delay happens as soon as the modifier is processed. However, when testing -Exim using the \-bh-\ option, the delay is not actually imposed (an appropriate -message is output instead). - -Like \control\, \delay\ can be used with \accept\ or -\deny\, for example: -.display asis -deny ...some conditions... - delay = 30s -.endd -The delay happens if all the conditions are true, before the statement returns -`deny'. Compare this with: -.display asis -deny delay = 30s - ...some conditions... -.endd -which waits for 30s before processing the conditions. The \delay\ modifier can -also be used with \warn\ and together with \control\: -.display -warn ...some conditions... - delay = 2m - control = freeze -accept ... -.endd - -.item endpass -.index \endpass\, ACL modifier -This modifier, which has no argument, is recognized only in \accept\ -statements. It marks the boundary between the conditions whose failure causes -control to pass to the next statement, and the conditions whose failure causes -the ACL to return `deny'. See the description of \accept\ above. - -.item "log@_message = <<text>>" -.index \log@_message\, ACL modifier -This modifier sets up a message that is used as part of the log message if the -ACL denies access or a \warn\ statement's conditions are true. For example: -.display asis -require log_message = wrong cipher suite $tls_cipher - encrypted = DES-CBC3-SHA -.endd -\log@_message\ adds to any underlying error message that may exist because of -the condition failure. For example, while verifying a recipient address, a -:::fail:: redirection might have already set up a message. Although the message -is usually defined before the conditions to which it applies, the expansion -does not happen until Exim decides that access is to be denied. This means that -any variables that are set by the condition are available for inclusion in the -message. For example, the \$dnslist@_<<xxx>>$\ variables are set after a DNS -black list lookup succeeds. If the expansion of \log@_message\ fails, or if the -result is an empty string, the modifier is ignored. - -If you want to use a \warn\ statement to log the result of an address -verification, you can use \$acl__verify__message$\ to include the verification -error message. - -If \log@_message\ is used with a \warn\ statement, `Warning:' is added to the -start of the logged message. If the same warning log message is requested more -than once while receiving a single email message, only one copy is actually -logged. If you want to log multiple copies, use \logwrite\ instead of -\log@_message\. In the absence of \log@_message\ and \logwrite\, nothing is -logged for a succesful \warn\ statement. - -If \log@_message\ is not present and there is no underlying error message (for -example, from the failure of address verification), but \message\ is present, -the \message\ text is used for logging rejections. However, if any text for -logging contains newlines, only the first line is logged. In the absence of -both \log@_message\ and \message\, a default built-in message is used for -logging rejections. - -.item "logwrite = <<text>>" -.index \logwrite\, ACL modifier -.index log||in ACL, immediate -This modifier writes a message to a log file as soon as it is encountered when -processing an ACL. (Compare \log@_message\, which, except in the case of -\warn\, is used only if the ACL statement denies access.) The \logwrite\ -modifier can be used to log special incidents in ACLs. For example: -.display -accept <<some special conditions>> - control = freeze - logwrite = froze message because ... -.endd -By default, the message is written to the main log. However, it may begin -with a colon, followed by a comma-separated list of log names, and then -another colon, to specify exactly which logs are to be written. For -example: -.display asis -logwrite = :main,reject: text for main and reject logs -logwrite = :panic: text for panic log only -.endd - -.item "message = <<text>>" -.index \message\, ACL modifier -This modifier sets up a text string that is expanded and used as an error -message if the current statement causes the ACL to deny access. The expansion -happens at the time Exim decides that access is to be denied, not at the time -it processes \message\. If the expansion fails, or generates an empty string, -the modifier is ignored. For ACLs that are triggered by SMTP commands, the -message is returned as part of the SMTP error response. - -The \message\ modifier is also used with the \warn\ verb to specify one or more -header lines to be added to an incoming message when all the conditions are -true. See section ~~SECTaddheadwarn for more details. If \message\ is used with -\warn\ in an ACL that is not concerned with receiving a message, it has no -effect. - -The text is literal; any quotes are taken as literals, but because the string -is expanded, backslash escapes are processed anyway. If the message contains -newlines, this gives rise to a multi-line SMTP response. Like \log@_message\, -the contents of \message\ are not expanded until after a condition has failed. - -If \message\ is used on a statement that verifies an address, the message -specified overrides any message that is generated by the verification process. -However, the original message is available in the variable -\$acl@_verify@_message$\, so you can incorporate it into your message if you -wish. In particular, if you want the text from \:fail:\ items in \%redirect%\ -routers to be passed back as part of the SMTP response, you should either not -use a \message\ modifier, or make use of \$acl@_verify@_message$\. - -.item "set <<acl@_name>> = <<value>>" -.index \set\, ACL modifier -This modifier puts a value into one of the ACL variables (see section -~~SECTaclvariables). - -.enditems - - -.em -.section Use of the control modifier -.rset SECTcontrols "~~chapter.~~section" -.index \control\, ACL modifier -The \control\ modifier supports the following settings: - -.startitems - -.item "control = caseful@_local@_part" -.item "control = caselower@_local@_part" -.index ~~ACL||case of local part in -.index case of local parts -These two controls are permitted only in the ACL specified by \acl@_smtp@_rcpt\ -(that is, during \\RCPT\\ processing). By default, the contents of -\$local@_part$\ are lower cased before ACL processing. If -`caseful@_local@_part' is specified, any uppercase letters in the original -local part are restored in \$local@_part$\ for the rest of the ACL, or until a -control that sets `caselower@_local@_part' is encountered. - -This control affects only the current recipient. Moreover, it applies only to -local part handling that takes place directly in the ACL (for example, as a key -in lookups). If a test to verify the recipient is obeyed, the case-related -handling of the local part during the verification is controlled by the router -configuration (see the \caseful@_local@_part\ generic router option). - -This facility could be used, for example, to add a spam score to local parts -containing upper case letters. For example, using \$acl@_m4$\ to accumulate the -spam score: -.display asis -warn control = caseful_local_part - set acl_m4 = ${eval:\ - $acl_m4 + \ - ${if match{$local_part}{[A-Z]}{1}{0}}\ - } - control = caselower_local_part -.endd -Notice that we put back the lower cased version afterwards, assuming that -is what is wanted for subsequent tests. - -.item "control = enforce@_sync" -.item "control = no@_enforce@_sync" -.index SMTP||synchronization checking -.index synchronization checking in SMTP -These controls make it possible to be selective about when SMTP synchronization -is enforced. The global option \smtp@_enforce@_sync\ specifies the initial -state of the switch (it is true by default). See the description of this option -in chapter ~~CHAPmainconfig for details of SMTP synchronization checking. - -The effect of these two controls lasts for the remainder of the SMTP -connection. They can appear in any ACL except the one for the non-SMTP -messages. The most straightforward place to put them is in the ACL defined by -\acl@_smtp@_connect\, which is run at the start of an incoming SMTP connection, -before the first synchronization check. The expected use is to turn off the -synchronization checks for badly-behaved hosts that you nevertheless need to -work with. - -.item "control = fakereject/<<message>>" -.index fake rejection -.index rejection, fake -This control is permitted only for the \\MAIL\\, \\RCPT\\, and \\DATA\\ ACLs, -in other words, only when an SMTP message is being received. If Exim accepts -the message, instead the final 250 response, a 550 rejection message is sent. -However, Exim proceeds to deliver the message as normal. The control applies -only to the current message, not to any subsequent ones that may be received in -the same SMTP connection. - -The text for the 550 response is taken from the \control\ modifier. If no -message is supplied, the following is used: -.display asis -550-Your message has been rejected but is being -550-kept for evaluation. -550-If it was a legitimate message, it may still be -550 delivered to the target recipient(s). -.endd -This facilty should be used with extreme caution. - - -.item "control = freeze" -.index frozen messages||forcing in ACL -This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and -non-SMTP ACLs, in other words, only when a message is being received. If the -message is accepted, it is placed on Exim's queue and frozen. The control -applies only to the current message, not to any subsequent ones that may be -received in the same SMTP connection. - - -.item "control = no@_mbox@_unspool" -This control is available when Exim is compiled with the content scanning -extension. Content scanning may require a copy of the current message, or parts -of it, to be written in `mbox format' to a spool file, for passing to a virus -or spam scanner. Normally, such copies are deleted when they are no longer -needed. If this control is set, the copies are not deleted. The control -applies only to the current message, not to any subsequent ones that may be -received in the same SMTP connection. It is provided for debugging purposes and -is unlikely to be useful in production. - - -.item "control = no@_multiline@_response" -.index multiline responses, suppressing -This control is permitted for any ACL except the one for non-SMTP messages. -It seems that there are broken clients in use that cannot handle multiline -SMTP responses, despite the fact that RFC 821 defined them over 20 years ago. - -If this control is set, multiline SMTP responses from ACL rejections are -suppressed. One way of doing this would have been to put out these responses as -one long line. However, RFC 2821 specifies a maximum of 512 bytes per response -(`use multiline responses for more' it says -- ha!), and some of the responses -might get close to that. So this facility, which is after all only a sop to -broken clients, is implemented by doing two very easy things: -.numberpars -Extra information that is normally output as part of a rejection caused by -sender verification failure is omitted. Only the final line (typically `sender -verification failed') is sent. -.nextp -If a \message\ modifier supplies a multiline response, only the first -line is output. -.endp -The setting of the switch can, of course, be made conditional on the -calling host. Its effect lasts until the end of the SMTP connection. - - -.item "control = queue@_only" -.index \queue@_only\ -.index queueing incoming messages -This control is permitted only for the \\MAIL\\, \\RCPT\\, \\DATA\\, and -non-SMTP ACLs, in other words, only when a message is being received. If the -message is accepted, it is placed on Exim's queue and left there for delivery -by a subsequent queue runner. No immediate delivery process is started. In -other words, it has the effect as the \queue@_only\ global option. However, the -control applies only to the current message, not to any subsequent ones that -may be received in the same SMTP connection. - - -.item "control = submission/<<options>>" -.index message||submission -.index submission mode -This control is permitted only for the \\MAIL\\, \\RCPT\\, and start of data -ACLs (the latter is the one defined by \acl@_smtp@_predata\). Setting it tells -Exim that the current message is a submission from a local MUA. In this case, -Exim operates in `submission mode', and applies certain fixups to the message -if necessary. For example, it add a ::Date:: header line if one is not present. -This control is not permitted in the \acl@_smtp@_data\ ACL, because that is too -late (the message has already been created). - -Chapter ~~CHAPmsgproc describes the processing that Exim applies to messages. -Section ~~SECTsubmodnon covers the processing that happens in submission mode; -the available options for this control are described there. The control applies -only to the current message, not to any subsequent ones that may be received in -the same SMTP connection. - -.enditems -.nem - - -.em -.section Adding header lines with the warn verb -.rset SECTaddheadwarn "~~chapter.~~section" -.index header lines||adding in an ACL -.index header lines||position of added lines -.index \warn\, ACL verb -.index \message\, ACL modifier -The \message\ modifier can be used on a \warn\ statement to add an extra header -line to an incoming message, as in this example: -.display asis -warn message = X-blacklisted-at: $dnslist_domain - dnslists = sbl.spamhaus.org : \ - dialup.mail-abuse.org -.endd -If an identical header line is requested several times (provoked, for example, -by multiple \\RCPT\\ commands), only one copy is actually added to the message. -If the text of the \message\ modifier contains one or more newlines that are -not followed by a space or a tab, it is assumed to contain multiple header -lines. Each one is checked for valid syntax; \"X-ACL-Warn:"\ is added to the -front of any line that is not a valid header line. - -By default, new lines are added at the end of the existing header lines. -However, you can specify that any particular header line should be added right -at the start (before all the ::Received:: lines), immediately after the first -block of ::Received:: lines, or immediately before any line that is not a -::Received:: or ::Resent-something:: header. - -This is done by specifying `:at@_start:', `:after@_received:', or -`:at@_start@_rfc:' (or, for completeness, `:at@_end:') before the text of the -header line, respectively. (Header text cannot start with a colon, as there has -to be a header name first.) For example: -.display asis -warn message = :after_received:X-My-Header: something or other... -.endd - -If more than one header is supplied in a single warn statement, each one is -treated independently and can therefore be placed differently. If you add -more than one line at the start, or after the Received: block, they will -end up in reverse order. - -\**Warning**\: This facility currently applies only to header lines that are -added in an ACL. It does NOT work for header lines that are added in a -system filter or in a router or transport. - -.index header lines||added, visibility of -Header lines that are added by an ACL at \\MAIL\\ or \\RCPT\\ time are not -visible in string expansions in ACLs for subsequent \\RCPT\\ commands or in the -\acl@_smtp@_predata\ ACL. However, they are visible in string expansions in the -ACL that is run after \\DATA\\ is complete (the \acl@_smtp@_data\ ACL). This is -also true for header lines that are added in the \acl@_smtp@_predata\ ACL. -If a message is rejected after \\DATA\\, all added header lines are included in -the entry that is written to the reject log. - -If you want to preserve data between \\MAIL\\, \\RCPT\\, and the -\acl@_smtp@_predata\ ACLs, you can use ACL variables, as described in section -~~SECTaclvariables. -.nem - - - -.section ACL conditions -.rset SECTaclconditions "~~chapter.~~section" -.index ~~ACL||conditions, list of -.em -Some of conditions listed in this section are available only when Exim is -compiled with the content-scanning extension. They are included here briefly -for completeness. More detailed descriptions can be found in the discussion on -content scanning in chapter ~~CHAPexiscan. -.nem - -Not all conditions are relevant in all circumstances. For example, testing -senders and recipients does not make sense in an ACL that is being run as the -result of the arrival of an \\ETRN\\ command, and checks on message headers can -be done only in the ACLs specified by \acl@_smtp@_data\ and \acl__not__smtp\. -You can use the same condition (with different parameters) more than once in -the same ACL statement. This provides a way of specifying an `and' conjunction. -The conditions are as follows: - -.startitems - -.item "acl = <<name of acl or ACL string or file name >>" -.index ~~ACL||nested -.index ~~ACL||indirect -.index \acl\, ACL condition -The possible values of the argument are the same as for the -\acl@_smtp@_$it{xxx}\ options. The named or inline ACL is run. If it returns -`accept' the condition is true; if it returns `deny' the condition is false. If -it returns `defer', the current ACL returns `defer' -.em -unless the condition is on a \warn\ verb. In that case, a `defer' return makes -the condition false. This means that further processing of the \warn\ verb -ceases, but processing of the ACL continues. -.nem - -If the nested \acl\ returns `drop' and the outer condition denies access, -the connection is dropped. If it returns `discard', the verb must be \accept\ -or \discard\, and the action is taken immediately -- no further conditions are -tested. - -ACLs may be nested up to 20 deep; the limit exists purely to catch runaway -loops. This condition allows you to use different ACLs in different -circumstances. For example, different ACLs can be used to handle \\RCPT\\ -commands for different local users or different local domains. - -.item "authenticated = <<string list>>" -.index \authenticated\, ACL condition -.index authentication||ACL checking -.index ~~ACL||testing for authentication -If the SMTP connection is not authenticated, the condition is false. Otherwise, -the name of the authenticator is tested against the list. To test for -authentication by any authenticator, you can set -.display asis -authenticated = * -.endd - -.item "condition = <<string>>" -.index \condition\, ACL condition -.index customizing||ACL condition -.index ~~ACL||customized test -.index ~~ACL||testing, customized -This feature allows you to make up custom conditions. If the result of -expanding the string is an empty string, the number zero, or one of the strings -`no' or `false', the condition is false. If the result is any non-zero number, -or one of the strings `yes' or `true', the condition is true. For any other -values, some error is assumed to have occured, and the ACL returns `defer'. - - -.em -.item "decode = <<location>>" -.index \decode\, ACL condition -This condition is available only when Exim is compiled with the -content-scanning extension, and it is allowed only the the ACL defined by -\acl@_smtp@_mime\. It causes the current MIME part to be decoded into a file. -For details, see chapter ~~CHAPexiscan. -.nem - - -.item "dnslists = <<list of domain names and other data>>" -.index \dnslists\, ACL condition -.index DNS list||in ACL -.index black list (DNS) -.index ~~ACL||testing a DNS list -This condition checks for entries in DNS black lists. These are also known as -`RBL lists', after the original Realtime Blackhole List, but note that the use -of the lists at \*mail-abuse.org*\ now carries a charge. -There are too many different variants of this condition to describe briefly -here. See sections ~~SECTmorednslists--~~SECTmorednslistslast for details. - -.item "domains = <<domain list>>" -.index \domains\, ACL condition -.index domain||ACL checking -.index ~~ACL||testing a recipient domain -This condition is relevant only after a \\RCPT\\ command. It checks that the -domain of the recipient address is in the domain list. If percent-hack -processing is enabled, it is done before this test is done. If the check -succeeds with a lookup, the result of the lookup is placed in \$domain@_data$\ -until the next \domains\ test. - -.item "encrypted = <<string list>>" -.index \encrypted\, ACL condition -.index encryption||checking in an ACL -.index ~~ACL||testing for encryption -If the SMTP connection is not encrypted, the condition is false. Otherwise, the -name of the cipher suite in use is tested against the list. To test for -encryption without testing for any specific cipher suite(s), set -.display asis -encrypted = * -.endd - -.item "hosts = << host list>>" -.index \hosts\, ACL condition -.index host||ACL checking -.index ~~ACL||testing the client host -This condition tests that the calling host matches the host list. 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, you could have: -.display asis -accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts -.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 even if the name lookup fails, you can rewrite the ACL like this: -.display asis -accept hosts = dbm;/etc/friendly/hosts -accept hosts = 10.9.8.7 -.endd -The default action on failing to find the host name is to assume that the host -is not in the list, so the first \accept\ statement fails. The second statement -can then check the IP address. - -If a \hosts\ condition is satisfied by means of a lookup, the result -of the lookup is made available in the \$host@_data$\ variable. This -allows you, for example, to set up a statement like this: -.display asis -deny hosts = net-lsearch;/some/file - message = $host_data -.endd -which gives a custom error message for each denied host. - -.item "local@_parts = <<local part list>>" -.index \local@_parts\, ACL condition -.index local part||ACL checking -.index ~~ACL||testing a local part -This condition is relevant only after a \\RCPT\\ command. It checks that the -local part of the recipient address is in the list. If percent-hack processing -is enabled, it is done before this test. If the check succeeds with a lookup, -the result of the lookup is placed in \$local@_part@_data$\ until the next -\local@_parts\ test. - - -.em -.item "malware = <<option>>" -.index \malware\, ACL condition -.index ~~ACL||virus scanning -.index ~~ACL||scanning for viruses -This condition is available only when Exim is compiled with the -content-scanning extension. It causes the incoming message to be scanned for -viruses. For details, see chapter ~~CHAPexiscan. -.nem - - -.em -.item "mime@_regex = <<list of regular expressions>>" -.index \mime@_regex\, ACL condition -.index ~~ACL||testing by regex matching -This condition is available only when Exim is compiled with the -content-scanning extension, and it is allowed only the the ACL defined by -\acl@_smtp@_mime\. It causes the current MIME part to be scanned for a match -with any of the regular expressions. For details, see chapter ~~CHAPexiscan. -.nem - - -.item "recipients = <<address list>>" -.index \recipients\, ACL condition -.index recipient||ACL checking -.index ~~ACL||testing a recipient -This condition is relevant only after a \\RCPT\\ command. It checks the entire -recipient address against a list of recipients. - - -.em -.item "regex = <<list of regular expressions>>" -.index \regex\, ACL condition -.index ~~ACL||testing by regex matching -This condition is available only when Exim is compiled with the -content-scanning extension. It causes the incoming message to be scanned -for a match with any of the regular expressions. For details, see chapter -~~CHAPexiscan. -.nem - - -.item "sender@_domains = <<domain list>>" -.index \sender@_domains\, ACL condition -.index sender||ACL checking -.index ~~ACL||testing a sender domain -This condition tests the domain of the sender of the message against the given -domain list. -\**Note**\: the domain of the sender address is in -\$sender@_address@_domain$\. It is \*not*\ put in \$domain$\ during the testing -of this condition. This is an exception to the general rule for testing -domain lists. It is done this way so that, if this condition is used in an -ACL for a \\RCPT\\ command, the recipient's domain (which is in \$domain$\) can -be used to influence the sender checking. - -.item "senders = <<address list>>" -.index \senders\, ACL condition -.index sender||ACL checking -.index ~~ACL||testing a sender -This condition tests the sender of the message against the given list. To test -for a bounce message, which has an empty sender, set -.display asis -senders = : -.endd - - -.em -.item "spam = <<username>>" -.index \spam\, ACL condition -.index ~~ACL||scanning for spam -This condition is available only when Exim is compiled with the -content-scanning extension. It causes the incoming message to be scanned by -SpamAssassin. For details, see chapter ~~CHAPexiscan. -.nem - - -.item "verify = certificate" -.index \verify\, ACL condition -.index TLS||client certificate verification -.index certificate||verification of client -.index ~~ACL||certificate verification -.index ~~ACL||testing a TLS certificate -This condition is true in an SMTP session if the session is encrypted, and a -certificate was received from the client, and the certificate was verified. The -server requests a certificate only if the client matches \tls@_verify@_hosts\ -or \tls@_try@_verify@_hosts\ (see chapter ~~CHAPTLS). - -.item "verify = header@_sender/<<options>>" -.index \verify\, ACL condition -.index ~~ACL||verifying sender in the header -.index header lines||verifying the sender in -.index sender||verifying in header -.index verifying||sender in header -This condition is relevant only in an ACL that is run after a message has been -received, that is, in an ACL specified by \acl@_smtp@_data\ -.em -or \acl@_not@_smtp\. It checks that there is a verifiable address in at least -one of the ::Sender::, ::Reply-To::, or ::From:: header lines. Such an address -is loosely thought of as a `sender' address (hence the name of the test). -However, an address that appears in one of these headers need not be an address -that accepts bounce messages; only sender addresses in envelopes are required -to accept bounces. Therefore, if you use the callout option on this check, you -might want to arrange for a non-empty address in the \\MAIL\\ command. -.nem - -Details of address verification and the options are given later, starting at -section ~~SECTaddressverification (callouts are described in section -~~SECTcallver). You can combine this condition with the \senders\ condition to -restrict it to bounce messages only: -.display asis -deny senders = : - message = A valid sender header is required for bounces - !verify = header_sender -.endd - -.item "verify = header@_syntax" -.index \verify\, ACL condition -.index ~~ACL||verifying header syntax -.index header lines||verifying syntax -.index verifying||header syntax -This condition is relevant only in an ACL that is run after a message has been -received, that is, in an ACL specified by \acl@_smtp@_data\ -or \acl@_not@_smtp\. -It checks the syntax of all header lines that can contain lists of addresses -(::Sender::, ::From::, ::Reply-To::, ::To::, ::Cc::, and ::Bcc::). -Unqualified addresses (local parts without domains) are permitted only in -locally generated messages and from hosts that match -\sender@_unqualified@_hosts\ or \recipient@_unqualified@_hosts\, as -appropriate. - -Note that this condition is a syntax check only. However, a common spamming -ploy is to send syntactically invalid headers such as -.display asis -To: @ -.endd -and this condition can be used to reject such messages. - -.item "verify = helo" -.index \verify\, ACL condition -.index ~~ACL||verifying HELO/EHLO -.index \\HELO\\||verifying -.index \\EHLO\\||verifying -.index verifying||\\EHLO\\ -.index verifying||\\HELO\\ -This condition is true if a \\HELO\\ or \\EHLO\\ command has been received from -the client host, and its contents have been verified. Verification of these -commands does not happen by default. See the description of the -\helo@_verify@_hosts\ and \helo@_try@_verify@_hosts\ options for details of how -to request it. - -.item "verify = recipient/<<options>>" -.index \verify\, ACL condition -.index ~~ACL||verifying recipient -.index recipient||verifying -.index verifying||recipient -This condition is relevant only after a \\RCPT\\ command. It verifies the -current recipient. Details of address verification are given later, starting at -section ~~SECTaddressverification. After a recipient has been verified, the -value of \$address@_data$\ is the last value that was set while routing the -address. This applies even if the verification fails. When an address that is -being verified is redirected to a single address, verification continues with -the new address, and in that case, the subsequent value of \$address@_data$\ is -the value for the child address. - - -.item "verify = reverse@_host@_lookup" -.index \verify\, ACL condition -.index ~~ACL||verifying host reverse lookup -.index host||verifying reverse lookup -This condition ensures that a verified host name has been looked up from the IP -address of the client host. (This may have happened already if the host name -was needed for checking a host list, or if the host matched \host@_lookup\.) -Verification ensures that the host name obtained from a reverse DNS lookup, or -one of its aliases, does, when it is itself looked up in the DNS, yield the -original IP address. - -If this condition is used for a locally generated message (that is, when there -is no client host involved), it always succeeds. - - -.item "verify = sender/<<options>>" -.index \verify\, ACL condition -.index ~~ACL||verifying sender -.index sender||verifying -.index verifying||sender -This condition is relevant only after a \\MAIL\\ or \\RCPT\\ command, or after -a message has been received (the \acl@_smtp@_data\ or \acl@_not@_smtp\ ACLs). -If the message's sender is empty (that is, this is a bounce message), the -condition is true. Otherwise, the sender address is verified. -.em -If there is data in the \$address@_data$\ variable at the end of routing, its -value is placed in \$sender__address__data$\ at the end of verification. This -value can be used in subsequent conditions and modifiers in the same ACL -statement. It does not persist after the end of the current statement. If you -want to preserve the value for longer, you can save it in an ACL variable. - -Details of verification are given later, starting at section -~~SECTaddressverification. Exim caches the result of sender verification, to -avoid doing it more than once per message. - -.item "verify = sender=<<address>>/<<options>>" -.index \verify\, ACL condition -This is a variation of the previous option, in which a modified address is -verified as a sender. - -.enditems - - - -.section Using DNS lists -.rset SECTmorednslists "~~chapter.~~section" -.index DNS list||in ACL -.index black list (DNS) -.index ~~ACL||testing a DNS list -In its simplest form, the \dnslists\ condition tests whether the calling host -is on at least one of a number of DNS lists by looking up the inverted IP -address in one or more DNS domains. For example, if the calling host's IP -address is 192.168.62.43, and the ACL statement is -.display asis -deny dnslists = blackholes.mail-abuse.org : \ - dialups.mail-abuse.org -.endd -the following records are looked up: -.display asis -43.62.168.192.blackholes.mail-abuse.org -43.62.168.192.dialups.mail-abuse.org -.endd -.em -As soon as Exim finds an existing DNS record, processing of the list stops. -Thus, multiple entries on the list provide an `or' conjunction. If you want to -test that a host is on more than one list (an `and' conjunction), you can use -two separate conditions: -.display asis -deny dnslists = blackholes.mail-abuse.org - dnslists = dialups.mail-abuse.org -.endd -.nem -If a DNS lookup times out or otherwise fails to give a decisive answer, Exim -behaves as if the host -.em -does not match the list item, that is, as if the DNS record does not exist. If -there are further items in the DNS list, they are processed. -.nem -This is usually the required action when \dnslists\ is used with \deny\ (which -is the most common usage), because it prevents a DNS failure from blocking -mail. However, you can change this behaviour by putting one of the following -special items in the list: -.index \"+include@_unknown"\ -.index \"+exclude@_unknown"\ -.index \"+defer@_unknown"\ -.display -+include@_unknown $rm{behave as if the item is on the list} -+exclude@_unknown $rm{behave as if the item is not on the list (default)} -+defer@_unknown $rm{give a temporary error} -.endd -Each of these applies to any subsequent items on the list. For example: -.display asis -deny dnslists = +defer_unknown : foo.bar.example -.endd - -Testing the list of domains stops as soon as a match is found. If you want to -warn for one list and block for another, you can use two different statements: -.display asis -deny dnslists = blackholes.mail-abuse.org -warn message = X-Warn: sending host is on dialups list - dnslists = dialups.mail-abuse.org -.endd - -DNS list lookups are cached by Exim for the duration of the SMTP session, -so a lookup based on the IP address is done at most once for any incoming -connection. Exim does not share information between multiple incoming -connections (but your local name server cache should be active). - - -.em -.section Specifying the IP address for a DNS list lookup -.index DNS list||keyed by explicit IP address -By default, the IP address that is used in a DNS list lookup is the IP address -of the calling host. However, you can specify another IP address by listing it -after the domain name, introduced by a slash. For example: -.display asis -deny dnslists = black.list.tls/192.168.1.2 -.endd -This feature is not very helpful with explicit IP addresses; it is intended for -use with IP addresses that are looked up, for example, the IP addresses of the -MX hosts or nameservers of an email sender address. For an example, see section -~~SECTmulkeyfor below. -.nem - - -.section DNS lists keyed on domain names -.index DNS list||keyed by domain name -There are some lists that are keyed on domain names rather than inverted IP -addresses (see for example the \*domain based zones*\ link at -\?http://www.rfc-ignorant.org/?\). No reversing of components is used with -these lists. You can change the name that is looked up in a DNS list by listing -it after the domain name, introduced by a slash. For example, -.display asis -deny message = Sender's domain is listed at $dnslist_domain - dnslists = dsn.rfc-ignorant.org/$sender_address_domain -.endd -This particular example is useful only in ACLs that are obeyed after the -\\RCPT\\ or \\DATA\\ commands, when a sender address is available. If (for -example) the message's sender is \*user@@tld.example*\ the name that is looked -up by this example is -.display asis -tld.example.dsn.rfc-ignorant.org -.endd -.em -A single \dnslists\ condition can contain entries for both names and IP -addresses. For example: -.display asis -deny dnslists = sbl.spamhaus.org : \ - dsn.rfc-ignorant.org/$sender_address_domain -.endd -The first item checks the sending host's IP address; the second checks a domain -name. The whole condition is true if either of the DNS lookups succeeds. -.nem - - -.em -.section Multiple explicit keys for a DNS list -.rset SECTmulkeyfor "~~chapter.~~section" -.index DNS list||multiple keys for -The syntax described above for looking up explicitly-defined values (either -names or IP addresses) in a DNS blacklist is a simplification. After the domain -name for the DNS list, what follows the slash can in fact be a list of items. -As with all lists in Exim, the default separator is a colon. However, because -this is a sublist within the list of DNS blacklist domains, it is necessary -either to double the separators like this: -.display asis -dnslists = black.list.tld/name.1::name.2 -.endd -or to change the separator character, like this: -.display asis -dnslists = black.list.tld/<;name.1;name.2 -.endd -If an item in the list is an IP address, it is inverted before the DNS -blacklist domain is appended. If it is not an IP address, no inversion -occurs. Consider this condition: -.display asis -dnslists = black.list.tld/<;192.168.1.2;a.domain -.endd -The DNS lookups that occur are: -.display asis -2.1.168.192.black.list.tld -a.domain.black.list.tld -.endd -Once a DNS record has been found (that matches a specific IP return -address, if specified -- see section ~~SECTaddmatcon), no further lookups are -done. If there is a temporary DNS error, the rest of the sublist of domains or -IP addresses is tried. A temporary error for the whole dnslists item occurs -only if no other DNS lookup in this sublist succeeds. In other words, a -successful lookup for any of the items in the sublist overrides a temporary -error for a previous item. - -The ability to supply a list of items after the slash is in some sense just a -syntactic convenience. These two examples have the same effect: -.display asis -dnslists = black.list.tld/a.domain : black.list.tld/b.domain -dnslists = black.list.tld/a.domain::b.domain -.endd -However, when the data for the list is obtained from a lookup, the second form -is usually much more convenient. Consider this example: -.display asis -deny message = The mail servers for the domain \ - $sender_address_domain \ - are listed at $dnslist_domain ($dnslist_value); \ - see $dnslist_text. - dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ - ${lookup dnsdb {>|mxh=\ - $sender_address_domain} }} } -.endd -Note the use of \">|"\ in the dnsdb lookup to specify the separator for -multiple DNS records. The inner dnsdb lookup produces a list of MX hosts -and the outer dnsdb lookup finds the IP addresses for these hosts. The result -of expanding the condition might be something like this: -.display asis -dnslists = sbl.spahmaus.org/<|192.168.2.3|192.168.5.6|... -.endd -Thus, this example checks whether or not the IP addresses of the sender -domain's mail servers are on the Spamhaus black list. -.nem - - - -.section Data returned by DNS lists -.index DNS list||data returned from -DNS lists are constructed using address records in the DNS. The original RBL -just used the address 127.0.0.1 on the right hand side of each record, but the -RBL+ list and some other lists use a number of values with different meanings. -The values used on the RBL+ list are: -.display rm -.tabs 12 -127.1.0.1 $t RBL -127.1.0.2 $t DUL -127.1.0.3 $t DUL and RBL -127.1.0.4 $t RSS -127.1.0.5 $t RSS and RBL -127.1.0.6 $t RSS and DUL -127.1.0.7 $t RSS and DUL and RBL -.endd -Some DNS lists may return more than one address record. - -.section Variables set from DNS lists -.index DNS list||variables set from -When an entry is found in a DNS list, the variable \$dnslist@_domain$\ -contains the name of the domain that matched, \$dnslist@_value$\ contains the -data from the entry, and \$dnslist@_text$\ contains the contents of any -associated TXT record. If more than one address record is returned by the DNS -lookup, all the IP addresses are included in \$dnslist@_value$\, separated by -commas and spaces. - -You can use these variables in \message\ or \log@_message\ modifiers -- -although these appear before the condition in the ACL, they are not expanded -until after it has failed. For example: -.display asis -deny hosts = !+local_networks - message = $sender_host_address is listed \ - at $dnslist_domain - dnslists = rbl-plus.mail-abuse.example -.endd - - -.section Additional matching conditions for DNS lists -.rset SECTaddmatcon "~~chapter.~~section" -.index DNS list||matching specific returned data -You can add an equals sign and an IP address after a \dnslists\ domain name in -order to restrict its action to DNS records with a matching right hand side. -For example, -.display asis -deny dnslists = rblplus.mail-abuse.org=127.0.0.2 -.endd -rejects only those hosts that yield 127.0.0.2. Without this additional data, -any address record is considered to be a match. If more than one address record -is found on the list, they are all checked for a matching right-hand side. - -More than one IP address may be given for checking, using a comma as a -separator. These are alternatives -- if any one of them matches, the \dnslists\ -condition is true. For example: -.display asis -deny dnslists = a.b.c=127.0.0.2,127.0.0.3 -.endd - -If you want to specify a constraining address list and also specify names or IP -addresses to be looked up, the constraining address list must be specified -first. For example: -.display asis -deny dnslists = dsn.rfc-ignorant.org\ - =127.0.0.2/$sender_address_domain -.endd - -If the character `&' is used instead of `=', the comparison for each listed -IP address is done by a bitwise `and' instead of by an equality test. In -other words, the listed addresses are used as bit masks. The comparison is -true if all the bits in the mask are present in the address that is being -tested. For example: -.display asis -dnslists = a.b.c&0.0.0.3 -.endd -matches if the address is \*x.x.x.*\3, \*x.x.x.*\7, \*x.x.x.*\11, etc. If you -want to test whether one bit or another bit is present (as opposed to both -being present), you must use multiple values. For example: -.display asis -dnslists = a.b.c&0.0.0.1,0.0.0.2 -.endd -matches if the final component of the address is an odd number or two times -an odd number. - - -.section Negated DNS matching conditions -You can supply a negative list of IP addresses as part of a \dnslists\ -condition. Whereas -.display asis -deny dnslists = a.b.c=127.0.0.2,127.0.0.3 -.endd -means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP -address yielded by the list is either 127.0.0.2 or 127.0.0.3', -.display asis -deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 -.endd -means `deny if the host is in the black list at the domain \*a.b.c*\ and the IP -address yielded by the list is not 127.0.0.2 and not 127.0.0.3'. In other -words, the result of the test is inverted if an exclamation mark appears before -the `=' (or the `&') sign. - -\**Note**\: this kind of negation is not the same as negation in a domain, -host, or address list (which is why the syntax is different). - -If you are using just one list, the negation syntax does not gain you much. The -previous example is precisely equivalent to -.display asis -deny dnslists = a.b.c - !dnslists = a.b.c=127.0.0.2,127.0.0.3 -.endd -However, if you are using multiple lists, the negation syntax is clearer. -Consider this example: -.display asis -deny dnslists = sbl.spamhaus.org : \ - list.dsbl.org : \ - dnsbl.njabl.org!=127.0.0.3 : \ - relays.ordb.org -.endd -Using only positive lists, this would have to be: -.display asis -deny dnslists = sbl.spamhaus.org : \ - list.dsbl.org -deny dnslists = dnsbl.njabl.org - !dnslists = dnsbl.njabl.org=127.0.0.3 -deny dnslists = relays.ordb.org -.endd -which is less clear, and harder to maintain. - - - -.section DNS lists and IPv6 -.rset SECTmorednslistslast "~~chapter.~~section" -.index IPv6||DNS black lists -.index DNS list||IPv6 usage -If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it -nibble by nibble. For example, if the calling host's IP address is -3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up -.display asis -1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. - f.f.f.f.e.f.f.3.blackholes.mail-abuse.org -.endd -(split over two lines here to fit on the page). Unfortunately, some of the DNS -lists contain wildcard records, intended for IPv4, that interact badly with -IPv6. For example, the DNS entry -.display asis -*.3.some.list.example. A 127.0.0.1 -.endd -is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. -Unfortunately, it also matches the entire 3@:@:/4 IPv6 network. - -You can exclude IPv6 addresses from DNS lookups by making use of a suitable -\condition\ condition, as in this example: -.display asis -.newline -.em -deny condition = ${if isip4{$sender_host_address}} -.nem -.newline - dnslists = some.list.example -.endd - - -.section Address verification -.rset SECTaddressverification "~~chapter.~~section" -.index verifying||address, options for -.index policy control||address verification -Several of the \verify\ conditions described in section ~~SECTaclconditions -cause addresses to be verified. These conditions can be followed by options -that modify the verification process. The options are separated from the -keyword and from each other by slashes, and some of them contain parameters. -For example: -.display asis -verify = sender/callout -verify = recipient/defer_ok/callout=10s,defer_ok -.endd -.em -The first stage of address verification, which always happens, is to run the -address through the routers, in `verify mode'. Routers can detect the -difference between verification and routing for delivery, and their actions can -be varied by a number of generic options such as \verify\ and \verify@_only\ -(see chapter ~~CHAProutergeneric). If routing fails, verification fails. -The available options are as follows: -.numberpars $. -If the \callout\ option is specified, successful routing to one or more remote -hosts is followed by a `callout' to those hosts as an additional check. -Callouts and their sub-options are discussed in the next section. -.nextp -If there is a defer error while doing verification routing, the ACL -normally returns `defer'. However, if you include \defer@_ok\ in the options, -the condition is forced to be true instead. Note that this is a main -verification option as well as a suboption for callouts. -.nextp -The \no@_details\ option is covered in section ~~SECTsenaddver, which discusses -the reporting of sender address verification failures. -.endp - -.index verifying||address, differentiating failures -After an address verification failure, \$sender@_verify@_failure$\ or -\$recipient@_verify@_failure$\ (as appropriate) contains one of the following -words: -.numberpars $. -\qualify\: The address was unqualified (no domain), and the message -was neither local nor came from an exempted host. -.nextp -\route\: Routing failed. -.nextp -\mail\: Routing succeeded, and a callout was attempted; rejection -occurred at or before the \\MAIL\\ command (that is, on initial -connection, \\HELO\\, or \\MAIL\\). -.nextp -\recipient\: The \\RCPT\\ command in a callout was rejected. -.nextp -\postmaster\: The postmaster check in a callout was rejected. -.endp - -The main use of these variables is expected to be to distinguish between -rejections of \\MAIL\\ and rejections of \\RCPT\\ in callouts. - -.nem - - -.section Callout verification -.rset SECTcallver "~~chapter.~~section" -.index verifying||address, by callout -.index callout||verification -.index SMTP||callout verification -For non-local addresses, routing verifies the domain, but is unable to do any -checking of the local part. There are situations where some means of verifying -the local part is desirable. One way this can be done is to make an SMTP -\*callback*\ to the sending host (for a sender address) or a \*callforward*\ to -a subsequent host (for a recipient address), to see if the host accepts the -address. We use the term \*callout*\ to cover both cases. This facility should -be used with care, because it can add a lot of resource usage to the cost of -verifying an address. However, Exim does cache the results of callouts, which -helps to reduce the cost. Details of caching are in the next section. - -Recipient callouts are usually used only between hosts that are controlled by -the same administration. For example, a corporate gateway host could use -callouts to check for valid recipients on an internal mailserver. -A successful callout does not guarantee that a real delivery to the address -would succeed; on the other hand, a failing callout does guarantee that -a delivery would fail. - -If the \callout\ option is present on a condition that verifies an address, a -second stage of verification occurs if the address is successfully routed to -one or more remote hosts. The usual case is routing by a \%dnslookup%\ or a -\%manualroute%\ router, where the router specifies the hosts. However, if a -router that does not set up hosts routes to an \%smtp%\ transport with a -\hosts\ setting, the transport's hosts are used. If an \%smtp%\ transport has -\hosts@_override\ set, its hosts are always used, whether or not the router -supplies a host list. - -The port that is used is taken from the transport, if it is specified and is a -remote transport. (For routers that do verification only, no transport need be -specified.) Otherwise, the default SMTP port is used. If a remote transport -specifies an outgoing interface, this is used; otherwise the interface is not -specified. - -For a sender callout check, Exim makes SMTP connections to the remote hosts, to -test whether a bounce message could be delivered to the sender address. The -following SMTP commands are sent: -.display -.newline -.em -HELO <<smtp active host name>> -.nem -.newline -MAIL FROM:@<@> -RCPT TO:<<the address to be tested>> -QUIT -.endd -\\LHLO\\ is used instead of \\HELO\\ if the transport's \protocol\ option is -set to `lmtp'. - -A recipient callout check is similar. By default, it also uses an empty address -for the sender. This default is chosen because most hosts do not make use of -the sender address when verifying a recipient. Using the same address means -that a single cache entry can be used for each recipient. Some sites, however, -do make use of the sender address when verifying. These are catered for by the -\use@_sender\ and \use@_postmaster\ options, described in the next section. - -If the response to the \\RCPT\\ command is a 2$it{xx} code, the verification -succeeds. If it is 5$it{xx}, the verification fails. For any other condition, -Exim tries the next host, if any. If there is a problem with all the remote -hosts, the ACL yields `defer', unless the \defer@_ok\ parameter of the -\callout\ option is given, in which case the condition is forced to succeed. - - - - -.section Additional parameters for callouts -.rset CALLaddparcall "~~chapter.~~section" -.index callout||additional parameters for -The \callout\ option can be followed by an equals sign and a number of optional -parameters, separated by commas. For example: -.display asis -verify = recipient/callout=10s,defer_ok -.endd -The old syntax, which had \callout@_defer@_ok\ and \check@_postmaster\ as -separate verify options, is retained for backwards compatibility, but is now -deprecated. The additional parameters for \callout\ are as follows: - -.startitems - -.item "<<a time interval>>" -.index callout||timeout, specifying -This specifies the timeout that applies for the callout attempt to each host. -For example: -.display asis -verify = sender/callout=5s -.endd -The default is 30 seconds. The timeout is used for each response from the -remote host. -.em -It is also used for the intial connection, unless overridden by the \connect\ -parameter. -.nem - -.em -.item "connect = <<time interval>>" -.index callout||connection timeout, specifying -This parameter makes it possible to set a different (usually -smaller) timeout for making the SMTP connection. -For example: -.display asis -verify = sender/callout=5s,connect=1s -.endd -If not specified, this timeout defaults to the general timeout value. -.nem - -.item "defer@_ok" -.index callout||defer, action on -When this parameter is present, failure to contact any host, or any other kind -of temporary error, is treated as success by the ACL. However, the cache is not -updated in this circumstance. - -.em -.item "mailfrom = <<email address>>" -.index callout||sender when verifying header -When verifying addresses in header lines using the \header@_sender\ -verification option, Exim behaves by default as if the addresses are envelope -sender addresses from a message. Callout verification therefore tests to see -whether a bounce message could be delivered, by using an empty address in the -\\MAIL\\ command. However, it is arguable that these addresses might never be -used as envelope senders, and could therefore justifiably reject bounce -messages (empty senders). The \mailfrom\ callout parameter allows you to -specify what address to use in the \\MAIL\\ command. For example: -.display asis -require verify = header_sender/callout=mailfrom=abcd@x.y.z -.endd -This parameter is available only for the \header@_sender\ verification option. -.nem - -.em -.item "maxwait = <<time interval>>" -.index callout||overall timeout, specifying -This parameter sets an overall timeout for performing a callout verification. -For example: -.display asis -verify = sender/callout=5s,maxwait=30s -.endd -This timeout defaults to four times the callout timeout for individual SMTP -commands. The overall timeout applies when there is more than one host that can -be tried. The timeout is checked before trying the next host. This prevents -very long delays if there are a large number of hosts and all are timing out -(for example, when network connections are timing out). -.nem - -.item "no@_cache" -.index callout||cache, suppressing -.index caching||callout, suppressing -When this parameter is given, the callout cache is neither read nor updated. - -.item "postmaster" -.index callout||postmaster, checking -When this parameter is set, a sucessful callout check is followed by a similar -check for the local part \*postmaster*\ at the same domain. If this address is -rejected, the callout fails. The result of the postmaster check is recorded in -a cache record; if it is a failure, this is used to fail subsequent callouts -for the domain without a connection being made, until the cache record expires. - -.em -.item "postmaster@_mailfrom = <<email address>>" -The postmaster check uses an empty sender in the \\MAIL\\ command by default. -You can use this parameter to do a postmaster check using a different address. -For example: -.display asis -require verify = sender/callout=postmaster_mailfrom=abc@x.y.z -.endd -If both \postmaster\ and \postmaster@_mailfrom\ are present, the rightmost one -overrides. The \postmaster\ parameter is equivalent to this example: -.display asis -require verify = sender/callout=postmaster_mailfrom= -.endd -\**Warning**\: The caching arrangements for postmaster checking do not take -account of the sender address. It is assumed that either the empty address or -a fixed non-empty address will be used. All that Exim remembers is that the -postmaster check for the domain succeeded or failed. -.nem - -.item "random" -.index callout||`random' check -When this parameter is set, before doing the normal callout check, Exim does a -check for a `random' local part at the same domain. The local part is not -really random -- it is defined by the expansion of the option -\callout@_random@_local@_part\, which defaults to -.display asis -$primary_host_name-$tod_epoch-testing -.endd -The idea here is to try to determine whether the remote host accepts all local -parts without checking. If it does, there is no point in doing callouts for -specific local parts. If the `random' check succeeds, the result is saved in -a cache record, and used to force the current and subsequent callout checks to -succeed without a connection being made, until the cache record expires. - -.item "use@_postmaster" -.index callout||sender for recipient check -This parameter applies to recipient callouts only. For example: -.display asis -deny !verify = recipient/callout=use_postmaster -.endd -It causes a non-empty postmaster address to be used in the \\MAIL\\ command -when performing the callout. The local part of the address is \"postmaster"\ -and the domain is the contents of \$qualify@_domain$\. - -.item "use@_sender" -This option applies to recipient callouts only. For example: -.display asis -require verify = recipient/callout=use_sender -.endd -It causes the message's actual sender address to be used in the \\MAIL\\ -command when performing the callout, instead of an empty address. There is no -need to use this option unless you know that the called hosts make use of the -sender when checking recipients. If used indiscriminately, it reduces the -usefulness of callout caching. - -.enditems - -.em -If you use any of the parameters that set a non-empty sender for the \\MAIL\\ -command (\mailfrom\, \postmaster@_mailfrom\, \use@_postmaster\, or -\use@_sender\), you should think about possible loops. Recipient checking is -usually done between two hosts that are under the same management, and the host -that receives the callouts is not normally configured to do callouts itself. -Therefore, it is normally safe to use \use@_postmaster\ or \use@_sender\ in -these circumstances. - -However, if you use a non-empty sender address for a callout to an arbitrary -host, there is the likelihood that the remote host will itself initiate a -callout check back to your host. As it is checking what appears to be a message -sender, it is likely to use an empty address in \\MAIL\\, thus avoiding a -callout loop. However, to be on the safe side it would be best to set up your -own ACLs so that they do not do sender verification checks when the recipient -is the address you use for header sender or postmaster callout checking. - -Another issue to think about when using non-empty senders for callouts is -caching. When you set \mailfrom\ or \use@_sender\, the cache record is keyed by -the sender/recipient combination; thus, for any given recipient, many more -actual callouts are performed than when an empty sender or postmaster is used. - -.nem - - -.section Callout caching -.rset SECTcallvercache "~~chapter.~~section" -.index hints database||callout cache -.index callout||caching -.index caching||callout -Exim caches the results of callouts in order to reduce the amount of resources -used, unless you specify the \no@_cache\ parameter with the \callout\ option. -A hints database called `callout' is used for the cache. Two different record -types are used: one records the result of a callout check for a specific -address, and the other records information that applies to the entire domain -(for example, that it accepts the local part \*postmaster*\). - -When an original callout fails, a detailed SMTP error message is given about -the failure. However, for subsequent failures use the cache data, this message -is not available. - -The expiry times for negative and positive address cache records are -independent, and can be set by the global options \callout@_negative@_expire\ -(default 2h) and \callout@_positive@_expire\ (default 24h), respectively. - -If a host gives a negative response to an SMTP connection, or rejects any -commands up to and including -.display asis -MAIL FROM:<> -.endd -(but not including the \\MAIL\\ command with a non-empty address), -any callout attempt is bound to fail. Exim remembers such failures in a -domain cache record, which it uses to fail callouts for the domain without -making new connections, until the domain record times out. There are two -separate expiry times for domain cache records: -\callout@_domain@_negative@_expire\ (default 3h) and -\callout__domain__positive@_expire\ (default 7d). - -Domain records expire when the negative expiry time is reached if callouts -cannot be made for the domain, or if the postmaster check failed. -Otherwise, they expire when the positive expiry time is reached. This -ensures that, for example, a host that stops accepting `random' local parts -will eventually be noticed. - -The callout caching mechanism is based on the domain of the address that is -being tested. If the domain routes to several hosts, it is assumed that their -behaviour will be the same. - - -.section Sender address verification reporting -.rset SECTsenaddver "~~chapter.~~section" -.index verifying||suppressing error details -When sender verification fails in an ACL, the details of the failure are -given as additional output lines before the 550 response to the relevant -SMTP command (\\RCPT\\ or \\DATA\\). For example, if sender callout is in use, -you might see: -.display asis -MAIL FROM:<xyz@abc.example> -250 OK -RCPT TO:<pqr@def.example> -550-Verification failed for <xyz@abc.example> -550-Called: 192.168.34.43 -550-Sent: RCPT TO:<xyz@abc.example> -550-Response: 550 Unknown local part xyz in <xyz@abc.example> -550 Sender verification failed -.endd -If more than one \\RCPT\\ command fails in the same way, the details are given -only for the first of them. However, some administrators do not want to send -out this much information. You can suppress the details by adding -`/no@_details' to the ACL statement that requests sender verification. For -example: -.display asis -verify = sender/no_details -.endd - - -.section Redirection while verifying -.index verifying||redirection while -.index address redirection||while verifying -A dilemma arises when a local address is redirected by aliasing or forwarding -during verification: should the generated addresses themselves be verified, -or should the successful expansion of the original address be enough to verify -it? Exim takes the following pragmatic approach: -.numberpars $. -When an incoming address is redirected to just one child address, verification -continues with the child address, and if that fails to verify, the original -verification also fails. -.nextp -When an incoming address is redirected to more than one child address, -verification does not continue. A success result is returned. -.endp -This seems the most reasonable behaviour for the common use of aliasing as a -way of redirecting different local parts to the same mailbox. It means, for -example, that a pair of alias entries of the form -.display asis -A.Wol: aw123 -aw123: :fail: Gone away, no forwarding address -.endd -work as expected, with both local parts causing verification failure. When a -redirection generates more than one address, the behaviour is more like a -mailing list, where the existence of the alias itself is sufficient for -verification to succeed. - - -.section Using an ACL to control relaying -.rset SECTrelaycontrol "~~chapter.~~section" -.index ~~ACL||relay control -.index relaying||control by ACL -.index policy control||relay control -An MTA is said to \*relay*\ a message if it receives it from some host and -delivers it directly to another host as a result of a remote address contained -within it. Redirecting a local address via an alias or forward file and then -passing the message on to another host is not relaying, -.index `percent hack' -but a redirection as a result of the `percent hack' is. - -Two kinds of relaying exist, which are termed `incoming' and `outgoing'. A host -which is acting as a gateway or an MX backup is concerned with incoming -relaying from arbitrary hosts to a specific set of domains. On the other hand, -a host which is acting as a smart host for a number of clients is concerned -with outgoing relaying from those clients to the Internet at large. Often the -same host is fulfilling both functions, as illustrated in the diagram below, -but in principle these two kinds of relaying are entirely independent. What is -not wanted is the transmission of mail from arbitrary remote hosts through your -system to arbitrary domains. -.if ~~sys.fancy -.figure "Controlled relaying" rm -.indent 0 -.call aspic -sgcal -nv -centre ~~sys.linelength; -magnify 0.8; -boundingbox 30; -textdepth 16; - boxwidth 120; - boxdepth 44; -A: box "Arbitrary" "remote hosts"; -C: ibox; -D: box "Arbitrary" "domains"; - iline down 50 from bottom of C; -H: box width 180 "Local host"; - iline down 50; -E: ibox; -SH: box "Specific" "hosts"; -SD: box join right to E "Specific" "domains"; - arcarrow clockwise from top of SH to bottom of D plus (-10,-4) - via right of H plus (-20,0); - arcarrow clockwise from bottom of A to top of SD plus (10,4) - via left of H plus (20,0); - - ibox join left to right of H "$it{Outgoing}"; - goto H; - ibox join right to left of H "$it{Incoming}"; - -L: line dashed from right of A to top of H plus (-15,0); - arc dashed to top of H plus (15,0); - arrow dashed to left of D plus (-2,0); - - arrow dashed back up 72 right 32 from middle of L plus (8,0); - text at end plus (0, 4) "$it{Not wanted}"; -.endcall -.endfigure -.elif !~~html -.display asis - -------------- ----------- - | Arbitrary | |Arbitrary| - |remote hosts| | domains | - -------------- ----------- - I v ^ O - n v ^ u - c ---v----------------^--- t - o | v Local ^ | g - m | v host ^ | o - i ---v----------------^--- i - n v ^ n - g v ^ g - Specific Specific - domains hosts -.endd -.else -[(IMG SRC="relaying.gif" alt="Controlled relaying")][(br)] -.fi - -You can implement relay control by means of suitable statements in the ACL that -runs for each \\RCPT\\ command. For convenience, it is often easiest to use -Exim's named list facility to define the domains and hosts involved. For -example, suppose you want to do the following: -.numberpars $. -Deliver a number of domains to mailboxes on the local host (or process them -locally in some other way). Let's say these are \*my.dom1.example*\ and -\*my.dom2.example*\. -.nextp -Relay mail for a number of other domains for which you are the secondary MX. -These might be \*friend1.example*\ and \*friend2.example*\. -.nextp -Relay mail from the hosts on your local LAN, to whatever domains are involved. -Suppose your LAN is 192.168.45.0/24. -.endp -In the main part of the configuration, you put the following definitions: -.display asis -domainlist local_domains = my.dom1.example : my.dom2.example -domainlist relay_domains = friend1.example : friend2.example -hostlist relay_hosts = 192.168.45.0/24 -.endd -Now you can use these definitions in the ACL that is run for every \\RCPT\\ -command: -.display asis -acl_check_rcpt: - accept domains = +local_domains : +relay_domains - accept hosts = +relay_hosts -.endd -The first statement accepts any \\RCPT\\ command that contains an address in -the local or relay domains. For any other domain, control passes to the second -statement, which accepts the command only if it comes from one of the relay -hosts. In practice, you will probably want to make your ACL more sophisticated -than this, for example, by including sender and recipient verification. The -default configuration includes a more comprehensive example, which is described -in chapter ~~CHAPdefconfil. - - -.section Checking a relay configuration -.rset SECTcheralcon "~~chapter.~~section" -.index relaying||checking control of -You can check the relay characteristics of your configuration in the same way -that you can test any ACL behaviour for an incoming SMTP connection, by using -the \-bh-\ option to run a fake SMTP session with which you interact. - -For specifically testing for unwanted relaying, the host -\*relay-test.mail-abuse.org*\ provides a useful service. If you telnet to this -host from the host on which Exim is running, using the normal telnet port, you -will see a normal telnet connection message and then quite a long delay. Be -patient. The remote host is making an SMTP connection back to your host, and -trying a number of common probes to test for open relay vulnerability. The -results of the tests will eventually appear on your terminal. - - - - -. -. -. -. -. ============================================================================ -.chapter Content scanning -.set runningfoot "content scanning" -.rset CHAPexiscan "~~chapter" -.index content scanning -.em -The content-scanning extension of Exim, formerly known as `exiscan', was -originally implemented as a patch by Tom Kistner. The code was integrated into -the main source for Exim release 4.50, and Tom continues to maintain it. Most -of the wording of this chapter is taken from Tom's specification. - -If you want to include the content-scanning features when you compile Exim, you -need to arrange for \\WITH@_CONTENT@_SCAN\\ to be defined in your -\(Local/Makefile)\. When you do that, the Exim binary is built with: -.numberpars $. -An additional ACL (\acl@_smtp@_mime\) that is run for all MIME parts. -.nextp -Additional ACL conditions and modifiers: \decode\, \malware\, \mime@_regex\, -\regex\, and \spam\. These can be used in the ACL that is run at the end of -message reception (the \acl@_smtp@_data\ ACL). -.nextp -An additional control feature (`no@_mbox@_unspool') that saves spooled copies -of messages, or parts of messages, for debugging purposes. -.nextp -Additional expansion variables that are set in the new ACL and by the new -conditions. -.nextp -Two new main configuration options: \av@_scanner\ and \spamd@_address\. -.endp -There is another content-scanning configuration option for \(Local/Makefile)\, -called \\WITH@_OLD@_DEMIME\\. If this is set, the old, deprecated \demime\ ACL -condition is compiled, in addition to all the other content-scanning features. - -Content-scanning is continually evolving, and new features are still being -added. While such features are still unstable and liable to incompatible -changes, they are made available in Exim by setting options whose names begin -\\EXPERIMENTAL@_\\ in \(Local/Makefile)\. Such features are not documented in -this manual. You can find out about them by reading the file called -\(doc/experimental.txt)\. - -All the content-scanning facilites work on a MBOX copy of the message that is -temporarily created in a file called: -.display -<<spool@_directory>>/scan/<<message@_id>>/<<message@_id>>.eml -.endd -The \(.eml)\ extension is a friendly hint to virus scanners that they can -expect an MBOX-like structure inside that file. The file is created when the -first content scanning facility is called. Subsequent calls to content -scanning conditions open the same file again. The directory is recursively -removed when the \acl@_smtp@_data\ ACL has finished running, unless -.display asis -control = no_mbox_unspool -.endd -has been encountered. When the MIME ACL decodes files, they are put into the -same directory by default. - - -.section Scanning for viruses -.rset SECTscanvirus "~~chapter.~~section" -.index virus scanning -.index content scanning||for viruses -.index content scanning||the \malware\ condition -The \malware\ ACL condition lets you connect virus scanner software to Exim. It -supports a `generic' interface to scanners called via the shell, and -specialized interfaces for `daemon' type virus scanners, which are resident in -memory and thus are much faster. - -.index \av@_scanner\ -You can set the \av@_scanner\ option in first part of the Exim configuration -file to specify which scanner to use, together with any additional options that -are needed. The basic syntax is as follows: -.display -av@_scanner = <<scanner-type>>:<<option1>>:<<option2>>:[...] -.endd -If you do not set \av@_scanner\, it defaults to -.display asis -av_scanner = sophie:/var/run/sophie -.endd -If the value of \av@_scanner\ starts with dollar character, it is expanded -before use. - -The following scanner types are supported in this release: -.numberpars $. -.index virus scanners||Kaspersky -\aveserver\: This is the scanner daemon of Kaspersky Version 5. You can get a -trial version at \?http://www.kaspersky.com?\. This scanner type takes one -option, which is the path to the daemon's UNIX socket. The default is shown in -this example: -.display asis -av_scanner = aveserver:/var/run/aveserver -.endd - -.nextp -.index virus scanners||clamd -\clamd\: This daemon-type scanner is GPL and free. You can get it at -\?http://www.clamav.net/?\. Clamd does not seem to unpack MIME containers, so -it is recommended to unpack MIME attachments in the MIME ACL. It takes one -option: either the path and name of a UNIX socket file, or a hostname or IP -number, and a port, separated by space, as in the second of these examples: -.display asis -av_scanner = clamd:/opt/clamd/socket -av_scanner = clamd:192.168.2.100 1234 -.endd -If the option is unset, the default is \(/tmp/clamd)\. Thanks to David Saez for -contributing the code for this scanner. - -.nextp -.index virus scanners||command line interface -\cmdline\: This is the keyword for the generic command line scanner interface. -It can be used to attach virus scanners that are invoked from the shell. This -scanner type takes 3 mandatory options: -.numberpars -The full path and name of the scanner binary, with all command line options, -and a placeholder (%s) for the directory to scan. -.nextp -A regular expression to match against the STDOUT and STDERR output of the virus -scanner. If the expression matches, a virus was found. You must make absolutely -sure that this expression matches on `virus found'. This is called the -`trigger' expression. -.nextp -Another regular expression, containing exactly one pair of parentheses, to -match the name of the virus found in the scanners output. This is called the -`name' expression. -.endp -For example, Sophos Sweep reports a virus on a line like this: -.display asis -Virus 'W32/Magistr-B' found in file ./those.bat -.endd -For the trigger expression, we can just match the word `found'. For the name -expression, we want to extract the W32/Magistr-B string, so we can match for -the single quotes left and right of it. Altogether, this makes the -configuration setting: -.display asis -av_scanner = cmdline:\ - /path/to/sweep -all -rec -archive %s:\ - found:'(.+)' -.endd - -.nextp -.index virus scanners||DrWeb -\drweb\: The DrWeb daemon scanner (\?http://www.sald.com/?\) interface -takes one argument, either a full path to a UNIX socket, or an IP address and -port separated by whitespace, as in these examples: -.display asis -av_scanner = drweb:/var/run/drwebd.sock -av_scanner = drweb:192.168.2.20 31337 -.endd -If you omit the argument, the default path \(/usr/local/drweb/run/drwebd.sock)\ -is used. Thanks to Alex Miller for contributing the code for this scanner. - -.nextp -.index virus scanners||F-Secure -\fsecure\: The F-Secure daemon scanner (\?http://www.f-secure.com?\) takes one -argument which is the path to a UNIX socket. For example: -.display asis -av_scanner = fsecure:/path/to/.fsav -.endd -If no argument is given, the default is \(/var/run/.fsav)\. Thanks to Johan -Thelmen for contributing the code for this scanner. - -.nextp -.index virus scanners||Kaspersky -\kavdaemon\: This is the scanner daemon of Kaspersky Version 4. This version of -the Kaspersky scanner is outdated. Please upgrade (see \aveserver\ above). This -scanner type takes one option, which is the path to the daemon's UNIX socket. -For example: -.display asis -av_scanner = kavdaemon:/opt/AVP/AvpCtl -.endd -The default path is \(/var/run/AvpCtl)\. - -.nextp -.index virus scanners||mksd -\mksd\: This is a daemon type scanner that is aimed mainly at Polish users, -though some parts of documentation are now available in English. You can get it -at \?http://linux.mks.com.pl/?\. The only option for this scanner type is the -maximum number of processes used simultaneously to scan the attachments, -provided that the demime facility is employed and also provided that mksd has -been run with at least the same number of child processes. For example: -.display asis -av_scanner = mksd:2 -.endd -You can safely omit this option (the default value is 1). - -.nextp -.index virus scanners||Sophos and Sophie -\sophie\: Sophie is a daemon that uses Sophos' \libsavi\ library to scan for -viruses. You can get Sophie at \?http://www.vanja.com/tools/sophie/?\. The only -option for this scanner type is the path to the UNIX socket that Sophie uses -for client communication. For example: -.display asis -av_scanner = sophie:/tmp/sophie -.endd -The default path is \(/var/run/sophie)\, so if you are using this, you can omit -the option. -.endp - -When \av@_scanner\ is correctly set, you can use the \malware\ condition in the -\\DATA\\ ACL. The \av@_scanner\ option is expanded each time \malware\ is -called. This makes it possible to use different scanners. See further below for -an example. The \malware\ condition caches its results, so when you use it -multiple times for the same message, the actual scanning process is only -carried out once. However, using expandable items in \av@_scanner\ disables -this caching, in which case each use of the \malware\ condition causes a new -scan of the message. - -The \malware\ condition takes a right-hand argument that is expanded before -use. It can then be one of -.numberpars $. -`true', `*', or `1', in which case the message is scanned for viruses. The -condition succeeds if a virus was found, and fail otherwise. This is the -recommended usage. -.nextp -`false' or `0', in which case no scanning is done and the condition fails -immediately. -.nextp -A regular expression, in which case the message is scanned for viruses. The -condition succeeds if a virus is found and its name matches the regular -expression. This allows you to take special actions on certain types of virus. -.endp -You can append \"/defer@_ok"\ to the \malware\ condition to accept messages even -if there is a problem with the virus scanner. - -.index \$malware@_name$\ -When a virus is found, the condition sets up an expansion variable called -\$malware@_name$\ that contains the name of the virus. You can use it in a -\message\ modifier that specifies the error returned to the sender, and/or in -logging data. - -If your virus scanner cannot unpack MIME and TNEF containers itself, you should -use the \demime\ condition (see section ~~SECTdemimecond) before the \malware\ -condition. - -Here is a very simple scanning example: -.display asis -deny message = This message contains malware ($malware_name) - demime = * - malware = * -.endd -The next example accepts messages when there is a problem with the scanner: -.display asis -deny message = This message contains malware ($malware_name) - demime = * - malware = */defer_ok -.endd -The next example shows how to use an ACL variable to scan with both sophie and -aveserver. It assumes you have set: -.display asis -av_scanner = $acl_m0 -.endd -in the main Exim configuration. -.display asis -deny message = This message contains malware ($malware_name) - set acl_m0 = sophie - malware = * - -deny message = This message contains malware ($malware_name) - set acl_m0 = aveserver - malware = * -.endd - - -.section Scanning with SpamAssassin -.rset SECTscanspamass "~~chapter.~~section" -.index content scanning||for spam -.index spam scanning -.index SpamAssassin, scanning with -The \spam\ ACL condition calls SpamAssassin's \spamd\ daemon to get a spam -score and a report for the message. You can get SpamAssassin at -\?http://www.spamassassin.org?\, or, if you have a working Perl installation, -you can use CPAN by running: -.display asis -perl -MCPAN -e 'install Mail::SpamAssassin' -.endd -SpamAssassin has its own set of configuration files. Please review its -documentation to see how you can tweak it. The default installation should work -nicely, however. - -.index \spamd@_address\ -After having installed and configured SpamAssassin, start the \spamd\ daemon. -By default, it listens on 127.0.0.1, TCP port 783. If you use another host or -port for \spamd\, you must set the \spamd@_address\ option in the global part -of the Exim configuration as follows (example): -.display asis -spamd_address = 192.168.99.45 387 -.endd -You do not need to set this option if you use the default. As of version 2.60, -\spamd\ also supports communication over UNIX sockets. If you want to use -these, supply \spamd@_address\ with an absolute file name instead of a -address/port pair: -.display asis -spamd_address = /var/run/spamd_socket -.endd - -You can have multiple \spamd\ servers to improve scalability. These can reside -on other hardware reachable over the network. To specify multiple \spamd\ -servers, put multiple address/port pairs in the \spamd@_address\ option, -separated with colons: -.display asis -spamd_address = 192.168.2.10 783 : \ - 192.168.2.11 783 : \ - 192.168.2.12 783 -.endd -Up to 32 \spamd\ servers are supported. The servers are -queried in a random fashion. When a server fails to respond -to the connection attempt, all other servers are tried -until one succeeds. If no server responds, the \spam\ -condition defers. - -\**Warning**\: It is not possible to use the UNIX socket connection method with -multiple \spamd\ servers. - -The spamd_address variable is expanded before use if it starts with a dollar -sign. In this case, the expansion may return a string that is used as the -list so that multiple spamd servers can be the result of an expansion. - -Here is a simple example of the use of the \spam\ condition in a DATA ACL: -.display asis -deny message = This message was classified as SPAM - spam = joe -.endd -The right-hand side of the \spam\ condition specifies the username that -SpamAssassin should scan for. If you do not want to scan for a particular user, -but rather use the SpamAssassin system-wide default profile, you can scan for -an unknown user, or simply use `nobody'. However, you must put something on the -right-hand side. - -The username allows you to use per-domain or per-user antispam profiles. The -right-hand side is expanded before being used, so you can put lookups or -conditions there. When the right-hand side evaluates to `0' or `false', no -scanning is done and the condition fails immediately. - -The \spam\ condition returns true if the threshold specified in the user's -SpamAssassin profile has been matched or exceeded. If you want to use the -\spam\ condition for its side effects (see the variables below), you can make -it always return `true' by appending \":true"\ to the username. - -.index spam scanning||returned variables -When the \spam\ condition is run, it sets up the following expansion -variables: - -.push -.indent 2em - -.tempindent 0 -\$spam@_score$\: The spam score of the message, for example `3.4' or `30.5'. -This is useful for inclusion in log or reject messages. - -.tempindent 0 -\$spam@_score@_int$\: The spam score of the message, multiplied by ten, as an -integer value. For example `34' or `305'. This is useful for numeric -comparisons in conditions. This variable is special; it is saved with the -message, and written to Exim's spool file. This means that it can be used -during the whole life of the message on your Exim system, in particular, in -routers or transports during the later delivery phase. - -.tempindent 0 -\$spam@_bar$\: A string consisting of a number of `+' or `@-' characters, -representing the integer part of the spam score value. A spam score of 4.4 -would have a \$spam@_bar$\ value of `++++'. This is useful for inclusion in -warning headers, since MUAs can match on such strings. - -.tempindent 0 -\$spam@_report$\: A multiline text table, containing the full SpamAssassin -report for the message. Useful for inclusion in headers or reject messages. - -.pop - -The \spam\ condition caches its results unless expansion in spamd_address was -used. If you call it again with the same user name, it does not scan again, -but rather returns the same values as before. - -The \spam\ condition returns DEFER if there is any error while running the -message through SpamAssassin or if the expansion of spamd_address failed. If -you want to treat DEFER as FAIL (to pass on to the next ACL statement block), -append \"/defer_ok"\ to the right-hand side of the spam condition, like this: -.display asis -deny message = This message was classified as SPAM - spam = joe/defer_ok -.endd -This causes messages to be accepted even if there is a -problem with \spamd\. - -Here is a longer, commented example of the use of the \spam\ -condition: -.display asis -# put headers in all messages (no matter if spam or not) -warn message = X-Spam-Score: $spam_score ($spam_bar) - spam = nobody:true -warn message = X-Spam-Report: $spam_report - spam = nobody:true - -# add second subject line with *SPAM* marker when message -# is over threshold -warn message = Subject: *SPAM* $h_Subject: - spam = nobody - -# reject spam at high scores (> 12) -deny message = This message scored $spam_score spam points. - spam = nobody:true - condition = ${if >{$spam_score_int}{120}{1}{0}} -.endd - - - -.section Scanning MIME parts -.rset SECTscanmimepart "~~chapter.~~section" -.index content scanning||MIME parts -.index MIME content scanning -.index \acl@_smtp@_mime\ -The \acl@_smtp@_mime\ global option defines an ACL that is called once for each -MIME part of a message, including multipart types, in the sequence of their -position in the message. - -This ACL is called (possibly many times) just before the \acl@_smtp@_data\ ACL, -but only if the message has a ::MIME-Version:: header. When a call to the MIME -ACL does not yield `accept', ACL processing is aborted and the appropriate -result code is sent to the remote client. The \acl@_smtp@_data\ ACL is not -called in this circumstance. - -At the start of the MIME ACL, a number of variables are set from the header -information for the relevant MIME part. These are described below. The contents -of the MIME part are not by default decoded into a disk file except for MIME -parts whose content-type is `message/rfc822'. If you want to decode a MIME part -into a disk file, you can use the \decode\ modifier. The general syntax is: -.display -decode = [/<<path>>/]<<filename>> -.endd -The right hand side is expanded before use. After expansion, -the value can be: -.numberpars -`0' or `false', in which case no decoding is done. -.nextp -The string `default'. In that case, the file is put in the temporary `default' -directory \(<<spool@_directory>>/scan/<<message@_id>>/)\ with a sequential file -name consisting of the message id and a sequence number. The full path and name -is available in \$mime@_decoded@_filename$\ after decoding. -.nextp -A full path name starting with a slash. If the full name is an existing -directory, it is used as a replacement for the default directory. The filename -is then sequentially assigned. If the path does not exist, it is used as -the full path and file name. -.nextp -If the string does not start with a slash, it is used as the -filename, and the default path is then used. -.endp -You can easily decode a file with its original, proposed -filename using -.display asis -decode = $mime_filename -.endd -However, you should keep in mind that \$mime@_filename$\ might contain -anything. If you place files outside of the default path, they are not -automatically unlinked. - -For RFC822 attachments (these are messages attached to messages, with a -content-type of `message/rfc822'), the ACL is called again in the same manner -as for the primary message, only that the \$mime@_is@_rfc822$\ expansion -variable is set (see below). Attached messages are always decoded to disk -before being checked, and the files are unlinked once the check is done. - -The MIME ACL supports the \regex\ and \mime@_regex\ conditions. These can be -used to match regular expressions against raw and decoded MIME parts, -respectively. They are described in section ~~SECTscanregex. - -.index MIME content scanning||returned variables -The following list describes all expansion variables that are -available in the MIME ACL: - -.push -.indent 2em - -.tempindent 0 -\$mime@_boundary$\: -If the current part is a multipart (see \$mime@_is@_multipart$\) below, it -should have a boundary string, which is stored in this variable. If the current -part has no boundary parameter in the ::Content-Type:: header, this variable -contains the empty string. - -.tempindent 0 -\$mime@_charset$\: -This variable contains the character set identifier, if one was found in the -::Content-Type:: header. Examples for charset identifiers are: -.display asis -us-ascii -gb2312 (Chinese) -iso-8859-1 -.endd -Please note that this value is not normalized, so you should do matches -case-insensitively. - -.tempindent 0 -\$mime@_content@_description$\: -This variable contains the normalized content of the ::Content-Description:: -header. It can contain a human-readable description of the parts content. Some -implementations repeat the filename for attachments here, but they are -usually only used for display purposes. - -.tempindent 0 -\$mime@_content@_disposition$\: -This variable contains the normalized content of the ::Content-Disposition:: -header. You can expect strings like `attachment' or `inline' here. - -.tempindent 0 -\$mime@_content@_id$\: -This variable contains the normalized content of the ::Content-ID:: header. -This is a unique ID that can be used to reference a part from another part. - -.tempindent 0 -\$mime@_content@_size$\: -This variable is set only after the \decode\ modifier (see above) has been -successfully run. It contains the size of the decoded part in kilobytes. The -size is always rounded up to full kilobytes, so only a completely empty part -has a \$mime@_content@_size$\ of zero. - -.tempindent 0 -\$mime@_content@_transfer@_encoding$\: -This variable contains the normalized content of the -::Content-transfer-encoding:: header. This is a symbolic name for an encoding -type. Typical values are `base64' and `quoted-printable'. - -.tempindent 0 -\$mime@_content@_type$\: If the MIME part has a ::Content-Type:: header, this -variable contains its value, lowercased, and without any options (like `name' -or `charset'). Here are some examples of popular MIME types, as they may appear -in this variable: -.display asis -text/plain -text/html -application/octet-stream -image/jpeg -audio/midi -.endd -If the MIME part has no ::Content-Type:: header, this variable contains the -empty string. - -.tempindent 0 -\$mime@_decoded@_filename$\: -This variable is set only after the \decode\ modifier (see above) has been -successfully run. It contains the full path and file name of the file -containing the decoded data. - -.tempindent 0 -\$mime@_filename$\: This is perhaps the most important of the MIME variables. -It contains a proposed filename for an attachment, if one was found in either -the ::Content-Type:: or ::Content-Disposition:: headers. The filename will be -RFC2047 decoded, but no additional sanity checks are done. If no filename was -found, this variable contains the empty string. - -.tempindent 0 -\$mime@_is@_coverletter$\: -This variable attempts to differentiate the `cover letter' of an e-mail from -attached data. It can be used to clamp down on flashy or unneccessarily encoded -content in the cover letter, while not restricting attachments at all. - -The variable contains 1 (true) for a MIME part believed to be part of the -cover letter, and 0 (false) for an attachment. At present, the algorithm is as -follows: -.numberpars -The outermost MIME part of a message is always a cover letter. -.nextp -If a multipart/alternative or multipart/related MIME part is a cover letter, so -are all MIME subparts within that multipart. -.nextp -If any other multipart is a cover letter, the first subpart is a cover letter, -and the rest are attachments. -.nextp -All parts contained within an attachment multipart are attachments. -.endp - -As an example, the following will ban `HTML mail' (including that sent with -alternative plain text), while allowing HTML files to be attached. HTML -coverletter mail attached to non-HMTL coverletter mail will also be allowed: -.display asis -deny message = HTML mail is not accepted here - !condition = $mime_is_rfc822 - condition = $mime_is_coverletter - condition = ${if eq{$mime_content_type}{text/html}{1}{0}} -.endd - - -.tempindent 0 -\$mime@_is@_multipart$\: -This variable has the value 1 (true) when the current part has the main type -`multipart', for example `multipart/alternative' or `multipart/mixed'. Since -multipart entities only serve as containers for other parts, you may not want -to carry out specific actions on them. - -.tempindent 0 -\$mime@_is@_rfc822$\: -This variable has the value 1 (true) if the current part is not a part of the -checked message itself, but part of an attached message. Attached message -decoding is fully recursive. - -.tempindent 0 -\$mime@_part@_count$\: -This variable is a counter that is raised for each processed MIME part. It -starts at zero for the very first part (which is usually a multipart). The -counter is per-message, so it is reset when processing RFC822 attachments (see -\$mime@_is@_rfc822$\). The counter stays set after \acl@_smtp@_mime\ is -complete, so you can use it in the DATA ACL to determine the number of MIME -parts of a message. For non-MIME messages, this variable contains the value -1. - -.pop - - -.section Scanning with regular expressions -.rset SECTscanregex "~~chapter.~~section" -.index content scanning||with regular expressions -.index regular expressions||content scanning with -You can specify your own custom regular expression matches on the full body of -the message, or on individual MIME parts. - -The \regex\ condition takes one or more regular expressions as arguments and -matches them against the full message (when called in the DATA ACL) or a raw -MIME part (when called in the MIME ACL). The \regex\ condition matches -linewise, with a maximum line length of 32K characters. That means you cannot -have multiline matches with the \regex\ condition. - -The \mime@_regex\ condition can be called only in the MIME ACL. It matches up -to 32K of decoded content (the whole content at once, not linewise). If the -part has not been decoded with the \decode\ modifier earlier in the ACL, it is -decoded automatically when \mime@_regex\ is executed (using default path and -filename values). If the decoded data is larger than 32K, only the first 32K -characters are checked. - -The regular expressions are passed as a colon-separated list. To include a -literal colon, you must double it. Since the whole right-hand side string is -expanded before being used, you must also escape dollar signs and backslashes -with more backslashes, or use the \"@\N"\ facility to disable expansion. -Here is a simple example that contains two regular expressions: -.display asis -deny message = contains blacklisted regex ($regex_match_string) - regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL -.endd -The conditions returns true if any one of the regular expressions matches. The -\$regex@_match@_string$\ expansion variable is then set up and contains the -matching regular expression. - -\**Warning**\: With large messages, these conditions can be fairly -CPU-intensive. - - - -.section The demime condition -.rset SECTdemimecond "~~chapter.~~section" -.index content scanning||MIME checking -.index MIME content scanning -The \demime\ ACL condition provides MIME unpacking, sanity checking and file -extension blocking. It uses a simpler interface to MIME decoding than the MIME -ACL functionality, but provides no additional facilities. Please note that this -condition is deprecated and kept only for for backward compatibility. You must -set the \\WITH@_OLD@_DEMIME\\ option in \(Local/Makefile)\ at build time to be -able to use the \demime\ condition. - -The \demime\ condition unpacks MIME containers in the message. It detects -errors in MIME containers and can match file extensions found in the message -against a list. Using this facility produces files containing the unpacked MIME -parts of the message in the temporary scan directory. If you do antivirus -scanning, it is recommened that you use the \demime\ condition before the -antivirus (\malware\) condition. - -On the right-hand side of the \demime\ condition you can pass a colon-separated -list of file extensions that it should match against. For example: -.display asis -deny message = Found blacklisted file attachment - demime = vbs:com:bat:pif:prf:lnk -.endd -If one of the file extensions is found, the condition is true, otherwise it is -false. If there is a temporary error while demimeing (for example, `disk -full'), the condition defers, and the message is temporarily rejected (unless -the condition is on a \warn\ verb). - -The right-hand side is expanded before being treated as a list, so you can have -conditions and lookups there. If it expands to an empty string, `false', or -zero (`0'), no demimeing is done and the condition is false. - -The \demime\ condition set the following variables: - -.push -.indent 2em - -.tempindent 0 -\$demime@_errorlevel$\: When an error is detected in a MIME container, this -variable contains the severity of the error, as an integer number. The higher -the value, the more severe the error. If this variable is unset or zero, no -error occurred. - -.tempindent 0 -\$demime@_reason$\: When \$demime@_errorlevel$\ is greater than zero, this -variable contains a human-readable text string describing the MIME error that -occurred. - -.tempindent 0 -\$found@_extension$\: When the \demime\ condition is true, this variable -contains the file extension it found. - -.pop - -Both \$demime@_errorlevel$\ and \$demime@_reason$\ are set by the first call of -the \demime\ condition, and are not changed on subsequent calls. - -If you do not want to check for file extensions, but rather use the \demime\ -condition for unpacking or error checking purposes, pass `*' as the -right-hand side value. Here is a more elaborate example of how to use this -facility: -.display asis -# Reject messages with serious MIME container errors -deny message = Found MIME error ($demime_reason). - demime = * - condition = ${if >{$demime_errorlevel}{2}{1}{0}} - -# Reject known virus spreading file extensions. -# Accepting these is pretty much braindead. -deny message = contains $found_extension file (blacklisted). - demime = com:vbs:bat:pif:scr - -# Freeze .exe and .doc files. Postmaster can -# examine them and eventually thaw them. -deny log_message = Another $found_extension file. - demime = exe:doc - control = freeze -.endd - - -.nem - - - -. -. -. -. -. ============================================================================ -.chapter Adding a local scan function to Exim -.set runningfoot "local scan function" -.rset CHAPlocalscan "~~chapter" -.index \*local@_scan()*\ function||description of -.index customizing||input scan using C function -.index policy control||by local scan function - -In these days of email worms, viruses, and ever-increasing spam, some sites -want to apply a lot of checking to messages before accepting them. -.em -The content scanning extension (chapter ~~CHAPexiscan) has facilities for -passing messages to external virus and spam scanning software. You can also do -.nem -a certain amount in Exim itself through string expansions and the \condition\ -condition in the ACL that runs after the SMTP \\DATA\\ command or the ACL for -non-SMTP messages (see chapter ~~CHAPACL), but this has its limitations. - -To allow for further customization to a site's own requirements, there is the -possibility of linking Exim with a private message scanning function, written -in C. If you want to run code that is written in something other than C, you -can of course use a little C stub to call it. - -The local scan function is run once for every incoming message, at the point -when Exim is just about to accept the message. -It can therefore be used to control non-SMTP messages from local processes as -well as messages arriving via SMTP. - -Exim applies a timeout to calls of the local scan function, and there is an -option called \local@_scan@_timeout\ for setting it. The default is 5 minutes. -Zero means `no timeout'. -Exim also sets up signal handlers for SIGSEGV, SIGILL, SIGFPE, and SIGBUS -before calling the local scan function, so that the most common types of crash -are caught. If the timeout is exceeded or one of those signals is caught, the -incoming message is rejected with a temporary error if it is an SMTP message. -For a non-SMTP message, the message is dropped and Exim ends with a non-zero -code. The incident is logged on the main and reject logs. - - -.section Building Exim to use a local scan function -.index \*local@_scan()*\ function||building Exim to use -To make use of the local scan function feature, you must tell Exim where your -function is before building Exim, by setting \\LOCAL@_SCAN@_SOURCE\\ in your -\(Local/Makefile)\. A recommended place to put it is in the \(Local)\ -directory, so you might set -.display asis -LOCAL_SCAN_SOURCE=Local/local_scan.c -.endd -for example. The function must be called \*local@_scan()*\. It is called by -Exim after it has received a message, when the success return code is about to -be sent. This is after all the ACLs have been run. The return code from your -function controls whether the message is actually accepted or not. There is a -commented template function (that just accepts the message) in the file -\(src/local@_scan.c)\. - -If you want to make use of Exim's run time configuration file to set options -for your \*local@_scan()*\ function, you must also set -.display asis -LOCAL_SCAN_HAS_OPTIONS=yes -.endd -in \(Local/Makefile)\ (see section ~~SECTconoptloc below). - - - -.section API for local@_scan() -.rset SECTapiforloc "~~chapter.~~section" -.index \*local@_scan()*\ function||API description -You must include this line near the start of your code: -.display asis -#include "local_scan.h" -.endd -This header file defines a number of variables and other values, and the -prototype for the function itself. Exim is coded to use unsigned char values -almost exclusively, and one of the things this header defines is a shorthand -for \"unsigned char"\ called \"uschar"\. -It also contains the following macro definitions, to simplify casting character -strings and pointers to character strings: -.display asis -#define CS (char *) -#define CCS (const char *) -#define CSS (char **) -#define US (unsigned char *) -#define CUS (const unsigned char *) -#define USS (unsigned char **) -.endd - -The function prototype for \*local@_scan()*\ is: -.display asis -extern int local_scan(int fd, uschar **return_text); -.endd -The arguments are as follows: -.numberpars $. -\fd\ is a file descriptor for the file that contains the body of the message -(the -D file). -The file is open for reading and writing, but updating it is not recommended. -\**Warning**\: You must \*not*\ close this file descriptor. - -The descriptor is positioned at character 19 of the file, which is the first -character of the body itself, because the first 19 characters are the message -id followed by \"-D"\ and a newline. If you rewind the file, you should use the -macro \\SPOOL@_DATA@_START@_OFFSET\\ to reset to the start of the data, just in -case this changes in some future version. - -.nextp -\return@_text\ is an address which you can use to return a pointer to a text -string at the end of the function. The value it points to on entry is NULL. -.endp -The function must return an \int\ value which is one of the following macros: -.numberpars $. -\"LOCAL@_SCAN@_ACCEPT"\ - -The message is accepted. If you pass back a string of text, it is saved with -the message, and made available in the variable \$local@_scan@_data$\. No -newlines are permitted (if there are any, they are turned into spaces) and the -maximum length of text is 1000 characters. -.nextp -\"LOCAL@_SCAN@_ACCEPT@_FREEZE"\ - -This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is -queued without immediate delivery, and is frozen. -.nextp -\"LOCAL@_SCAN@_ACCEPT@_QUEUE"\ - -This behaves as \\LOCAL@_SCAN@_ACCEPT\\, except that the accepted message is -queued without immediate delivery. -.nextp -\"LOCAL@_SCAN@_REJECT"\ - -The message is rejected; the returned text is used as an error message which is -passed back to the sender and which is also logged. Newlines are permitted -- -they cause a multiline response for SMTP rejections, but are converted to -\"@\n"\ in log lines. -If no message is given, `Administrative prohibition' is used. -.nextp -\"LOCAL@_SCAN@_TEMPREJECT"\ - -The message is temporarily rejected; the returned text is used as an error -message as for \\LOCAL@_SCAN@_REJECT\\. If no message is given, `Temporary -local problem' is used. -.nextp -\"LOCAL@_SCAN@_REJECT@_NOLOGHDR"\ - -This behaves as \\LOCAL@_SCAN@_REJECT\\, except that the header of the rejected -message is not written to the reject log. It has the effect of unsetting the -\rejected@_header\ log selector for just this rejection. If \rejected@_header\ -is already unset (see the discussion of the \log@_selection\ option in section -~~SECTlogselector), this code is the same as \\LOCAL@_SCAN@_REJECT\\. - -.nextp -\"LOCAL@_SCAN@_TEMPREJECT@_NOLOGHDR"\ - -This code is a variation of \\LOCAL@_SCAN@_TEMPREJECT\\ in the same way that -\\LOCAL__SCAN__REJECT__NOLOGHDR\\ is a variation of \\LOCAL@_SCAN@_REJECT\\. -.endp - -If the message is not being received by interactive SMTP, rejections are -reported by writing to \stderr\ or by sending an email, as configured by the -\-oe-\ command line options. - - -.section Configuration options for local@_scan() -.rset SECTconoptloc "~~chapter.~~section" -.index \*local@_scan()*\ function||configuration options -It is possible to have option settings in the main configuration file -that set values in static variables in the \*local@_scan()*\ module. If you -want to do this, you must have the line -.display asis -LOCAL_SCAN_HAS_OPTIONS=yes -.endd -in your \(Local/Makefile)\ when you build Exim. (This line is in -\(OS/Makefile-Default)\, commented out). Then, in the \*local@_scan()*\ source -file, you must define static variables to hold the option values, and a table to -define them. - -The table must be a vector called \local@_scan@_options\, of type -\"optionlist"\. Each entry is a triplet, consisting of a name, an option type, -and a pointer to the variable that holds the value. The entries must appear in -alphabetical order. Following \local@_scan@_options\ you must also define a -variable called \local@_scan@_options@_count\ that contains the number of -entries in the table. Here is a short example, showing two kinds of option: -.display asis -static int my_integer_option = 42; -static uschar *my_string_option = US"a default string"; - -optionlist local_scan_options[] = { - { "my_integer", opt_int, &my_integer_option }, - { "my_string", opt_stringptr, &my_string_option } -}; -int local_scan_options_count = - sizeof(local_scan_options)/sizeof(optionlist); -.endd -The values of the variables can now be changed from Exim's runtime -configuration file by including a local scan section as in this example: -.display asis -begin local_scan -my_integer = 99 -my_string = some string of text... -.endd -The available types of option data are as follows: - -.startitems - -.item opt@_bool -This specifies a boolean (true/false) option. The address should point to -a variable of type \"BOOL"\, which will be set to \\TRUE\\ or \\FALSE\\, which -are macros that are defined as `1' and `0', respectively. If you want to detect -whether such a variable has been set at all, you can initialize it to -\\TRUE@_UNSET\\. (BOOL variables are integers underneath, so can hold more than -two values.) - -.item "opt@_fixed" -This specifies a fixed point number, such as is used for load averages. -The address should point to a variable of type \"int"\. The value is stored -multiplied by 1000, so, for example, 1.4142 is truncated and stored as 1414. - -.item "opt@_int" -This specifies an integer; the address should point to a variable of type -\"int"\. The value may be specified in any of the integer formats accepted by -Exim. - -.item "opt@_mkint" -This is the same as \opt@_int\, except that when such a value is output in a -\-bP-\ listing, if it is an exact number of kilobytes or megabytes, it is -printed with the suffix K or M. - -.item "opt@_octint" -This also specifies an integer, but the value is always interpeted as an -octal integer, whether or not it starts with the digit zero, and it is -always output in octal. - -.item "opt@_stringptr" -This specifies a string value; the address must be a pointer to a -variable that points to a string (for example, of type \"uschar $*$"\). - -.item "opt@_time" -This specifies a time interval value. The address must point to a variable of -type \"int"\. The value that is placed there is a number of seconds. - -.enditems - -If the \-bP-\ command line option is followed by \"local@_scan"\, Exim prints -out the values of all the \*local@_scan()*\ options. - - -.section Available Exim variables -.index \*local@_scan()*\ function||available Exim variables -The header \(local@_scan.h)\ gives you access to a number of C variables. -These are the only ones that are guaranteed to be maintained from release to -release. Note, however, that you can obtain the value of any Exim variable by -calling \*expand@_string()*\. The exported variables are as follows: - -.startitems - -.item "unsigned int debug@_selector" -This variable is set to zero when no debugging is taking place. Otherwise, it -is a bitmap of debugging selectors. Two bits are identified for use in -\*local@_scan()*\; they are defined as macros: -.numberpars $. -The \"D@_v"\ bit is set when \-v-\ was present on the command line. This is a -testing option that is not privileged -- any caller may set it. All the -other selector bits can be set only by admin users. -.nextp -The \"D@_local@_scan"\ bit is provided for use by \*local@_scan()*\; it is set -by the \"+local@_scan"\ debug selector. It is not included in the default set -of debugging bits. -.endp -Thus, to write to the debugging output only when \"+local@_scan"\ has been -selected, you should use code like this: -.display asis -if ((debug_selector & D_local_scan) != 0) - debug_printf("xxx", ...); -.endd - -.item "uschar *expand@_string@_message" -After a failing call to \*expand@_string()*\ (returned value NULL), the -variable \expand__string__message\ contains the error message, zero-terminated. - -.item "header@_line *header@_list" -A pointer to a chain of header lines. The \header@_line\ structure is discussed -below. - -.item "header@_line *header@_last" -A pointer to the last of the header lines. - -.item "uschar *headers@_charset" -The value of the \headers@_charset\ configuration option. - -.item "BOOL host@_checking" -This variable is TRUE during a host checking session that is initiated by the -\-bh-\ command line option. - -.item "uschar *interface@_address" -The IP address of the interface that received the message, as a string. This -is NULL for locally submitted messages. - -.item "int interface@_port" -The port on which this message was received. - -.item "uschar *message@_id" -This variable contains the message id for the incoming message as a -zero-terminated string. - - -.item "uschar *received@_protocol" -The name of the protocol by which the message was received. - -.item "int recipients@_count" -The number of accepted recipients. - -.item "recipient@_item *recipients@_list" -.index recipient||adding in local scan -.index recipient||removing in local scan -The list of accepted recipients, held in a vector of length -\recipients@_count\. The \recipient@_item\ structure is discussed below. You -can add additional recipients by calling \*receive@_add@_recipient()*\ (see -below). You can delete recipients by removing them from the vector and adusting -the value in \recipients@_count\. In particular, by setting \recipients@_count\ -to zero you remove all recipients. If you then return the value -\"LOCAL@_SCAN@_ACCEPT"\, the message is accepted, but immediately blackholed. -To replace the recipients, set \recipients@_count\ to zero and then call -\*receive@_add@_recipient()*\ as often as needed. - -.item "uschar *sender@_address" -The envelope sender address. For bounce messages this is the empty string. - -.item "uschar *sender@_host@_address" -The IP address of the sending host, as a string. This is NULL for -locally-submitted messages. - -.item "uschar *sender@_host@_authenticated" -The name of the authentication mechanism that was used, or NULL if the message -was not received over an authenticated SMTP connection. - -.item "uschar *sender@_host@_name" -The name of the sending host, if known. - -.item "int sender@_host@_port" -The port on the sending host. - -.item "BOOL smtp@_input" -This variable is TRUE for all SMTP input, including BSMTP. - -.item "BOOL smtp@_batched@_input" -This variable is TRUE for BSMTP input. - -.item "int store@_pool" -The contents of this variable control which pool of memory is used for new -requests. See section ~~SECTmemhanloc for details. - -.enditems - - -.section Structure of header lines -The \header@_line\ structure contains the members listed below. -You can add additional header lines by calling the \*header@_add()*\ function -(see below). You can cause header lines to be ignored (deleted) by setting -their type to $*$. - -.startitems - -.item "struct header@_line *next" -A pointer to the next header line, or NULL for the last line. - -.item "int type" -A code identifying certain headers that Exim recognizes. The codes are printing -characters, and are documented in chapter ~~CHAPspool of this manual. Notice in -particular that any header line whose type is $*$ is not transmitted with the -message. This flagging is used for header lines that have been rewritten, or -are to be removed (for example, ::Envelope-sender:: header lines.) Effectively, -$*$ means `deleted'. - -.item "int slen" -The number of characters in the header line, including the terminating and any -internal newlines. - -.item "uschar *text" -A pointer to the text of the header. It always ends with a newline, followed by -a zero byte. Internal newlines are preserved. - -.enditems - - - -.section Structure of recipient items -The \recipient@_item\ structure contains these members: - -.startitems - -.item "uschar *address" -This is a pointer to the recipient address as it was received. - -.item "int pno" -This is used in later Exim processing when top level addresses are created -by the \one@_time\ option. It is not relevant at the time \*local@_scan()*\ is -run and -must always contain -1 at this stage. - -.item "uschar *errors@_to" -If this value is not NULL, bounce messages caused by failing to deliver to the -recipient are sent to the address it contains. In other words, it overrides the -envelope sender for this one recipient. (Compare the \errors@_to\ generic -router option.) -If a \*local@_scan()*\ function sets an \errors@_to\ field to an unqualified -address, Exim qualifies it using the domain from \qualify@_recipient\. -When \*local@_scan()*\ is called, the \errors@_to\ field is NULL for all -recipients. -.enditems - - -.section Available Exim functions -.index \*local@_scan()*\ function||available Exim functions -The header \(local@_scan.h)\ gives you access to a number of Exim functions. -These are the only ones that are guaranteed to be maintained from release to -release: - -.startitems - -.item "pid@_t child@_open(uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, BOOL make@_leader)" -This function creates a child process that runs the command specified by -\argv\. The environment for the process is specified by \envp\, which can be -NULL if no environment variables are to be passed. A new umask is supplied for -the process in \newumask\. - -Pipes to the standard input and output of the new process are set up -and returned to the caller via the \infdptr\ and \outfdptr\ arguments. The -standard error is cloned to the standard output. If there are any file -descriptors `in the way' in the new process, they are closed. If the final -argument is TRUE, the new process is made into a process group leader. - -The function returns the pid of the new process, or -1 if things go wrong. - - -.item "int child@_close(pid@_t pid, int timeout)" -This function waits for a child process to terminate, or for a timeout (in -seconds) to expire. A timeout value of zero means wait as long as it takes. The -return value is as follows: -.numberpars $. ->= 0 - -The process terminated by a normal exit and the value is the process ending -status. -.nextp -< 0 and > --256 - -The process was terminated by a signal and the value is the negation of the -signal number. -.nextp ---256 - -The process timed out. -.nextp ---257 - -The was some other error in wait(); \errno\ is still set. -.endp - - -.item "pid@_t child@_open@_exim(int *fd)" -This function provide you with a means of submitting a new message to -Exim. (Of course, you can also call \(/usr/sbin/sendmail)\ yourself if you -want, but this packages it all up for you.) The function creates a pipe, -forks a subprocess that is running -.display asis -exim -t -oem -oi -f <> -.endd -and returns to you (via the \"int *"\ argument) a file descriptor for the pipe -that is connected to the standard input. The yield of the function is the PID -of the subprocess. You can then write a message to the file descriptor, with -recipients in ::To::, ::Cc::, and/or ::Bcc:: header lines. - -When you have finished, call \*child@_close()*\ to wait for the process to -finish and to collect its ending status. A timeout value of zero is usually -fine in this circumstance. Unless you have made a mistake with the recipient -addresses, you should get a return code of zero. - -.item "void debug@_printf(char *, ...)" -This is Exim's debugging function, with arguments as for \*(printf()*\. The -output is written to the standard error stream. If no debugging is selected, -calls to \*debug@_printf()*\ have no effect. Normally, you should make calls -conditional on the \"local@_scan"\ debug selector by coding like this: -.display asis -if ((debug_selector & D_local_scan) != 0) - debug_printf("xxx", ...); -.endd - -.item "uschar *expand@_string(uschar *string)" -This is an interface to Exim's string expansion code. The return value is the -expanded string, or NULL if there was an expansion failure. -The C variable \expand@_string@_message\ contains an error message after an -expansion failure. If expansion does not change the string, the return value is -the pointer to the input string. Otherwise, the return value points to a new -block of memory that was obtained by a call to \*store@_get()*\. See section -~~SECTmemhanloc below for a discussion of memory handling. - -.item "void header@_add(int type, char *format, ...)" -.em -This function allows you to an add additional header line at the end of the -existing ones. -.nem -The first argument is the type, and should normally be a space character. The -second argument is a format string and any number of substitution arguments as -for \*sprintf()*\. You may include internal newlines if you want, and you must -ensure that the string ends with a newline. - -.em -.item "void header@_add@_at@_position(BOOL after, uschar *name, BOOL topnot, int type, char *$nh{format}, ...)" -This function adds a new header line at a specified point in the header -chain. The header itself is specified as for \*header@_add()*\. - -If \name\ is NULL, the new header is added at the end of the chain if \after\ -is true, or at the start if \after\ is false. If \name\ is not NULL, the header -lines are searched for the first non-deleted header that matches the name. If -one is found, the new header is added before it if \after\ is false. If \after\ -is true, the new header is added after the found header and any adjacent -subsequent ones with the same name (even if marked `deleted'). If no matching -non-deleted header is found, the \topnot\ option controls where the header is -added. If it is true, addition is at the top; otherwise at the bottom. Thus, to -add a header after all the ::Received:: headers, or at the top if there are no -::Received:: headers, you could use -.display asis -header_add_at_position(TRUE, US"Received", TRUE, - ' ', "X-xxx: ..."); -.endd -Normally, there is always at least one non-deleted ::Received:: header, but -there may not be if \received@_header@_text\ expands to an empty string. - - -.item "void header@_remove(int occurrence, uschar *name)" -This function removes header lines. If \occurrence\ is zero or negative, all -occurrences of the header are removed. If occurrence is greater than zero, that -particular instance of the header is removed. If no header(s) can be found that -match the specification, the function does nothing. - - -.item "BOOL header@_testname(header@_line *hdr, uschar *name, int length, BOOL notdel)" -This function tests whether the given header has the given name. It is not just -a string comparison, because whitespace is permitted between the name and the -colon. If the \notdel\ argument is true, a false return is forced for all -`deleted' headers; otherwise they are not treated specially. For example: -.display asis -if (header_testname(h, US"X-Spam", 6, TRUE)) ... -.endd -.nem - - -.item "uschar *lss@_b64encode(uschar *cleartext, int length)" -.index base64 encoding||functions for \*local@_scan()*\ use -This function base64-encodes a string, which is passed by address and length. -The text may contain bytes of any value, including zero. The result is passed -back in dynamic memory that is obtained by calling \*store@_get()*\. It is -zero-terminated. - -.item "int lss@_b64decode(uschar *codetext, uschar **cleartext)" -This function decodes a base64-encoded string. Its arguments are a -zero-terminated base64-encoded string and the address of a variable that is set -to point to the result, which is in dynamic memory. The length of the -decoded string is the yield of the function. If the input is invalid base64 -data, the yield is -1. A zero byte is added to the end of the output string to -make it easy to interpret as a C string (assuming it contains no zeros of its -own). The added zero byte is not included in the returned count. - -.item "int lss@_match@_domain(uschar *domain, uschar *list)" -This function checks for a match in a domain list. Domains are always -matched caselessly. The return value is one of the following: -.display -OK $rm{match succeeded} -FAIL $rm{match failed} -DEFER $rm{match deferred} -.endd -DEFER is usually caused by some kind of lookup defer, such as the -inability to contact a database. - -.item "int lss@_match@_local@_part(uschar *localpart, uschar *list, BOOL caseless)" -This function checks for a match in a local part list. The third argument -controls case-sensitivity. The return values are as for -\*lss@_match@_domain()*\. - -.item "int lss@_match@_address(uschar *address, uschar *list, BOOL caseless)" -This function checks for a match in an address list. The third argument -controls the case-sensitivity of the local part match. The domain is always -matched caselessly. The return values are as for \*lss@_match@_domain()*\. - -.item "int lss@_match@_host(uschar *host@_name, uschar *host@_address, uschar *list)" -This function checks for a match in a host list. The most common usage is -expected to be -.display asis -lss_match_host(sender_host_name, sender_host_address, ...) -.endd -An empty address field matches an empty item in the host list. If the -host name is NULL, the name corresponding to \$sender@_host@_address$\ is -automatically looked up if a host name is required to match an item in the -list. The return values are as for \*lss@_match@_domain()*\, but in addition, -\*lss@_match@_host()*\ returns ERROR in the case when it had to look up a host -name, but the lookup failed. - -.item "void log@_write(unsigned int selector, int which, char *format, ...)" -This function writes to Exim's log files. The first argument should be zero (it -is concerned with \log@_selector\). The second argument can be \"LOG@_MAIN"\ or -\"LOG@_REJECT"\ or -\"LOG@_PANIC"\ or the inclusive `or' of any combination of them. It specifies -to which log or logs the message is written. -The remaining arguments are a format and relevant insertion arguments. The -string should not contain any newlines, not even at the end. - - -.item "void receive@_add@_recipient(uschar *address, int pno)" -This function adds an additional recipient to the message. The first argument -is the recipient address. If it is unqualified (has no domain), it is qualified -with the \qualify@_recipient\ domain. The second argument must always be -1. - -This function does not allow you to specify a private \errors@_to\ address (as -described with the structure of \recipient@_item\ above), because it pre-dates -the addition of that field to the structure. However, it is easy to add such a -value afterwards. For example: -.display asis -receive_add_recipient(US"monitor@mydom.example", -1); -recipients_list[recipients_count-1].errors_to = - US"postmaster@mydom.example"; -.endd - -.em -.item "BOOL receive@_remove@_recipient(uschar *recipient)" -This is a convenience function to remove a named recipient from the -list of recipients. It returns true if a recipient was removed, and -false if no matching recipient could be found. The argument must be a -complete email address. -.nem - - -.item "uschar *rfc2047@_decode(uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, uschar **error)" -This function decodes strings that are encoded according to RFC 2047. Typically -these are the contents of header lines. First, each encoded `word' is decoded -from the Q or B encoding into a byte-string. Then, if provided with the name of -a charset encoding, and if the \*iconv()*\ function is available, an attempt is -made to translate the result to the named character set. If this fails, the -binary string is returned with an error message. - -The first argument is the string to be decoded. If \lencheck\ is TRUE, the -maximum MIME word length is enforced. The third argument is the target -encoding, or NULL if no translation is wanted. - -.index binary zero||in RFC 2047 decoding -If a binary zero is encountered in the decoded string, it is replaced by the -contents of the \zeroval\ argument. For use with Exim headers, the value must -not be 0 because header lines are handled as zero-terminated strings. - -The function returns the result of processing the string, zero-terminated; if -\lenptr\ is not NULL, the length of the result is set in the variable to which -it points. When \zeroval\ is 0, \lenptr\ should not be NULL. - -If an error is encountered, the function returns NULL and uses the \error\ -argument to return an error message. The variable pointed to by \error\ is set -to NULL if there is no error; it may be set non-NULL even when the function -returns a non-NULL value if decoding was successful, but there was a problem -with translation. - - -.item "int smtp@_fflush(void)" -This function is used in conjunction with \*smtp@_printf()*\, as described -below. - -.item "void smtp@_printf(char *, ...)" -The arguments of this function are like \*printf()*\; it writes to the SMTP -output stream. You should use this function only when there is an SMTP output -stream, that is, when the incoming message is being received via interactive -SMTP. This is the case when \smtp@_input\ is TRUE and \smtp@_batched@_input\ is -FALSE. If you want to test for an incoming message from another host (as -opposed to a local process that used the \-bs-\ command line option), you can -test the value of \sender@_host@_address\, which is non-NULL when a remote host -is involved. - -If an SMTP TLS connection is established, \*smtp@_printf()*\ uses the TLS -output function, so it can be used for all forms of SMTP connection. - -Strings that are written by \*smtp@_printf()*\ from within \*local@_scan()*\ -must start with an appropriate response code: 550 if you are going to return -\\LOCAL@_SCAN@_REJECT\\, 451 if you are going to return -\\LOCAL@_SCAN@_TEMPREJECT\\, and 250 otherwise. Because you are writing the -initial lines of a multi-line response, the code must be followed by a hyphen -to indicate that the line is not the final response line. You must also ensure -that the lines you write terminate with CRLF. For example: -.display asis -smtp_printf("550-this is some extra info\r\n"); -return LOCAL_SCAN_REJECT; -.endd -Note that you can also create multi-line responses by including newlines in -the data returned via the \return@_text\ argument. The added value of using -\*smtp@_printf()*\ is that, for instance, you could introduce delays between -multiple output lines. - -The \*smtp@_printf()*\ function does not return any error indication, because it -does not automatically flush pending output, and therefore does not test -the state of the stream. (In the main code of Exim, flushing and error -detection is done when Exim is ready for the next SMTP input command.) If -you want to flush the output and check for an error (for example, the -dropping of a TCP/IP connection), you can call \*smtp@_fflush()*\, which has no -arguments. It flushes the output stream, and returns a non-zero value if there -is an error. - -.item "void *store@_get(int)" -This function accesses Exim's internal store (memory) manager. It gets a new -chunk of memory whose size is given by the argument. Exim bombs out if it ever -runs out of memory. See the next section for a discussion of memory handling. - -.item "void *store@_get@_perm(int)" -This function is like \*store@_get()*\, but it always gets memory from the -permanent pool. See the next section for a discussion of memory handling. - -.item "uschar *string@_copy(uschar *string)" -.item "uschar *string@_copyn(uschar *string, int length)" 0 -.item "uschar *string@_sprintf(char *format, ...)" 0 -These three functions create strings using Exim's dynamic memory facilities. -The first makes a copy of an entire string. The second copies up to a maximum -number of characters, indicated by the second argument. The third uses a format -and insertion arguments to create a new string. In each case, the result is a -pointer to a new string -in the current memory pool. See the next section for more discussion. - -.enditems - - - -.section More about Exim's memory handling -.rset SECTmemhanloc "~~chapter.~~section" -.index \*local@_scan()*\ function||memory handling -No function is provided for freeing memory, because that is never needed. -The dynamic memory that Exim uses when receiving a message is automatically -recycled if another message is received by the same process (this applies only -to incoming SMTP connections -- other input methods can supply only one message -at a time). After receiving the last message, a reception process terminates. - -Because it is recycled, the normal dynamic memory cannot be used for holding -data that must be preserved over a number of incoming messages on the same SMTP -connection. However, Exim in fact uses two pools of dynamic memory; the second -one is not recycled, and can be used for this purpose. - -If you want to allocate memory that remains available for subsequent messages -in the same SMTP connection, you should set -.display asis -store_pool = POOL_PERM -.endd -before calling the function that does the allocation. There is no need to -restore the value if you do not need to; however, if you do want to revert to -the normal pool, you can either restore the previous value of \store@_pool\ or -set it explicitly to \\POOL@_MAIN\\. - -The pool setting applies to all functions that get dynamic memory, including -\*expand@_string()*\, \*store@_get()*\, and the \*string@_xxx()*\ functions. -There is also a convenience function called \*store__get__perm()*\ that gets a -block of memory from the permanent pool while preserving the value of -\store@_pool\. - - - - - -. -. -. -. -. ============================================================================ -.chapter System-wide message filtering -.set runningfoot "system filtering" -.rset CHAPsystemfilter "~~chapter" -.index filter||system filter -.index filtering all mail -.index system filter -The previous chapters (on ACLs and the local scan function) describe checks -that can be applied to messages before they are accepted by a host. There is -also a mechanism for checking messages once they have been received, but before -they are delivered. This is called the $it{system filter}. - -The system filter operates in a similar manner to users' filter files, but it -is run just once per message (however many recipients the message has). -It should not normally be used as a substitute for routing, because \deliver\ -commands in a system router provide new envelope recipient addresses. -The system filter must be an Exim filter. It cannot be a Sieve filter. - -The system filter is run at the start of a delivery attempt, before any routing -is done. If a message fails to be completely delivered at the first attempt, -the system filter is run again at the start of every retry. -If you want your filter to do something only once per message, you can make use -of the \first@_delivery\ condition in an \if\ command in the filter to prevent -it happening on retries. - -\**Warning**\: Because the system filter runs just once, variables that are -specific to individual recipient addresses, such as \$local@_part$\ and -\$domain$\, are not set, and the `personal' condition is not meaningful. If you -want to run a centrally-specified filter for each recipient address -independently, you can do so by setting up a suitable \%redirect%\ router, as -described in section ~~SECTperaddfil below. - -.section Specifying a system filter -.index uid (user id)||system filter -.index gid (group id)||system filter -The name of the file that contains the system filter must be specified by -setting \system@_filter\. If you want the filter to run under a uid and gid -other than root, you must also set \system@_filter@_user\ and -\system@_filter@_group\ as appropriate. For example: -.display asis -system_filter = /etc/mail/exim.filter -system_filter_user = exim -.endd -If a system filter generates any deliveries directly to files or pipes (via the -\save\ or \pipe\ commands), transports to handle these deliveries must be -specified by setting \system@_filter@_file@_transport\ and -\system@_filter@_pipe@_transport\, respectively. Similarly, -\system@_filter@_reply@_transport\ must be set to handle any messages generated -by the \reply\ command. - -.section Testing a system filter -You can run simple tests of a system filter in the same way as for a user -filter, but you should use \-bF-\ rather than \-bf-\, so that features that -are permitted only in system filters are recognized. -.em -If you want to test the combined effect of a system filter and a user filter, -you can use both \-bF-\ and \-bf-\ on the same command line. -.nem - -.section Contents of a system filter -The language used to specify system filters is the same as for users' filter -files. It is described in the separate end-user document \*Exim's interface to -mail filtering*\. However, there are some additional features that are -available only in system filters; these are described in subsequent sections. -If they are encountered in a user's filter file or when testing with \-bf-\, -they cause errors. - -.index frozen messages||manual thaw, testing in filter -There are two special conditions which, though available in users' filter -files, are designed for use in system filters. The condition \first@_delivery\ -is true only for the first attempt at delivering a message, and -\manually@_thawed\ is true only if the message has been frozen, and -subsequently thawed by an admin user. An explicit forced delivery counts as a -manual thaw, but thawing as a result of the \auto__thaw\ setting does not. - -\**Warning**\: If a system filter uses the \first@_delivery\ condition to -specify an `unseen' (non-significant) delivery, and that delivery does not -succeed, it will not be tried again. -If you want Exim to retry an unseen delivery until it succeeds, you should -arrange to set it up every time the filter runs. - -When a system filter finishes running, the values of the variables \$n0$\ -- -\$n9$\ are copied into \$sn0$\ -- \$sn9$\ and are thereby made available to -users' filter files. Thus a system filter can, for example, set up `scores' to -which users' filter files can refer. - - -.section Additional variable for system filters -The expansion variable \$recipients$\, containing a list of all the recipients -of the message (separated by commas and white space), is available in system -filters. It is not available in users' filters for privacy reasons. - - -.section Defer, freeze, and fail commands for system filters -.index freezing messages -.index message||freezing -.index message||forced failure -.index \fail\||in system filter -.index \freeze\ in system filter -.index \defer\ in system filter -There are three extra commands (\defer\, \freeze\ and \fail\) which are always -available in system filters, but are not normally enabled in users' filters. -(See the \allow@_defer\, -\allow@_freeze\ and \allow@_fail\ options for the \%redirect%\ router.) These -commands can optionally be followed by the word \text\ and a string containing -an error message, for example: -.display asis -fail text "this message looks like spam to me" -.endd -The keyword \text\ is optional if the next character is a double quote. - -The \defer\ command defers delivery of the original recipients of the message. -The \fail\ command causes all the original recipients to be failed, and a -bounce message to be created. The \freeze\ command suspends all delivery -attempts for the original recipients. In all cases, any new deliveries that are -specified by the filter are attempted as normal after the filter has run. - -The \freeze\ command is ignored if the message has been manually unfrozen and -not manually frozen since. This means that automatic freezing by a system -filter can be used as a way of checking out suspicious messages. If a message -is found to be all right, manually unfreezing it allows it to be delivered. - -.index log||\fail\ command log line -.index \fail\||log line, reducing -The text given with a fail command is used as part of the bounce message as -well as being written to the log. If the message is quite long, this can fill -up a lot of log space when such failures are common. To reduce the size of the -log message, Exim interprets the text in a special way if it starts with the -two characters \"@<@<"\ and contains \"@>@>"\ later. The text between these two -strings is written to the log, and the rest of the text is used in the bounce -message. For example: -.display asis -fail "<<filter test 1>>Your message is rejected \ - because it contains attachments that we are \ - not prepared to receive." -.endd - -.index loop||caused by \fail\ -Take great care with the \fail\ command when basing the decision to fail on the -contents of the message, because the bounce message will of course include the -contents of the original message and will therefore trigger the \fail\ command -again (causing a mail loop) unless steps are taken to prevent this. Testing the -\error@_message\ condition is one way to prevent this. You could use, for -example -.display asis -if $message_body contains "this is spam" and not error_message - then fail text "spam is not wanted here" endif -.endd -though of course that might let through unwanted bounce messages. The -alternative is clever checking of the body and/or headers to detect bounces -generated by the filter. - -The interpretation of a system filter file ceases after a -\defer\, -\freeze\, or \fail\ command is obeyed. However, any deliveries that were set up -earlier in the filter file are honoured, so you can use a sequence such as -.display asis -mail ... -freeze -.endd -to send a specified message when the system filter is freezing (or deferring or -failing) a message. The normal deliveries for the message do not, of course, -take place. - - -.section Adding and removing headers in a system filter -.rset SECTaddremheasys "~~chapter.~~section" -.index header lines||adding, in system filter -.index header lines||removing, in system filter -.index filter||header lines, adding/removing -Two filter commands that are available only in system filters are: -.display -headers add <<string>> -headers remove <<string>> -.endd -The argument for the \headers add\ is a string that is expanded and then added -to the end of the message's headers. It is the responsibility of the filter -maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is -ignored, and if the string is otherwise empty, or if the expansion is forced to -fail, the command has no effect. - -You can use `@\n' within the string, followed by white space, to specify -continued header lines. More than one header may be added in one command by -including `@\n' within the string without any following white space. For -example: -.display asis -headers add "X-header-1: ....\n \ - continuation of X-header-1 ...\n\ - X-header-2: ...." -.endd -Note that the header line continuation white space after the first newline must -be placed before the backslash that continues the input string, because white -space after input continuations is ignored. - -The argument for \headers remove\ is a colon-separated list of header names. -This command applies only to those headers that are stored with the message; -those that are added at delivery time (such as ::Envelope-To:: and -::Return-Path::) cannot be removed by this means. If there is more than one -header with the same name, they are all removed. - -.em -The \headers\ command in a system filter makes an immediate change to the set -of header lines that was received with the message (with possible additions -from ACL processing). Subsequent commands in the system filter operate on the -modified set, which also forms the basis for subsequent message delivery. -Unless further modified during routing or transporting, this set of headers is -used for all recipients of the message. - -During routing and transporting, the variables that refer to the contents of -header lines refer only to those lines that are in this set. Thus, header lines -that are added by a system filter are visible to users' filter files and to all -routers and transports. This contrasts with the manipulation of header lines by -routers and transports, which is not immediate, but which instead is saved up -until the message is actually being written (see section ~~SECTheadersaddrem). - -If the message is not delivered at the first attempt, header lines that were -added by the system filter are stored with the message, and so are still -present at the next delivery attempt. Header lines that were removed are still -present, but marked `deleted' so that they are not transported with the -message. For this reason, it is usual to make the \headers\ command conditional -on \first@_delivery\ so that the set of header lines is not modified more than -once. - -Because header modification in a system filter acts immediately, you have to -use an indirect approach if you want to modify the contents of a header line. -For example: -.display asis -headers add "Old-Subject: $h_subject:" -headers remove "Subject" -headers add "Subject: new subject (was: $h_old-subject:)" -headers remove "Old-Subject" -.endd -.nem - - - -.section Setting an errors address in a system filter -.index envelope sender -In a system filter, if a \deliver\ command is followed by -.display -errors@_to <<some address>> -.endd -in order to change the envelope sender (and hence the error reporting) for that -delivery, any address may be specified. (In a user filter, only the current -user's address can be set.) For example, if some mail is being monitored, you -might use -.display asis -unseen deliver monitor@spying.example errors_to root@local.example -.endd -to take a copy which would not be sent back to the normal error reporting -address if its delivery failed. - - -.section Per-address filtering -.rset SECTperaddfil "~~chapter.~~section" -In contrast to the system filter, which is run just once per message for each -delivery attempt, it is also possible to set up a system-wide filtering -operation that runs once for each recipient address. In this case, variables -such as \$local@_part$\ and \$domain$\ can be used, and indeed, the choice of -filter file could be made dependent on them. This is an example of a router -which implements such a filter: -.display asis -central_filter: -.newline - check_local_user -.newline - driver = redirect - domains = +local_domains - file = /central/filters/$local_part - no_verify - allow_filter - allow_freeze -.endd -The filter is run in a separate process under its own uid. Therefore, either -\check@_local@_user\ must be set (as above), in which case the filter is run as -the local user, or the \user\ option must be used to specify which user to use. -If both are set, \user\ overrides. - -Care should be taken to ensure that none of the commands in the filter file -specify a significant delivery if the message is to go on to be delivered to -its intended recipient. The router will not then claim to have dealt with the -address, so it will be passed on to subsequent routers to be delivered in the -normal way. - - - - - - -. -. -. -. -. ============================================================================ -.chapter Message processing -.set runningfoot "message processing" -.rset CHAPmsgproc "~~chapter" -.index message||general processing -Exim performs various transformations on the sender and recipient addresses of -all messages that it handles, and also on the messages' header lines. Some of -these are optional and configurable, while others always take place. All of -this processing, except rewriting as a result of routing, and the addition or -removal of header lines while delivering, happens when a message is received, -before it is placed on Exim's queue. - -Some of the automatic processing takes place by default only for -`locally-originated' messages. This adjective is used to describe messages that -are not received over TCP/IP, but instead are passed to an Exim process on its -standard input. This includes the interactive `local SMTP' case that is set up -by the \-bs-\ command line option. - -\**Note**\: messages received over TCP/IP on the loopback interface (127.0.0.1 -or @:@:1) are not considered to be locally-originated. Exim does not treat the -loopback interface specially in any way. -.em -If you want the loopback interface to be treated specially, you must ensure -that there are appropriate entries in your ACLs. -.nem - - -.section Submission mode for non-local messages -.rset SECTsubmodnon "~~chapter.~~section" -.index message||submission -.index submission mode -.em -Processing that happens automatically for locally-originated messages can also -be requested for other messages. The term `submission mode' is used to describe -this state. Submisssion mode is set by the modifier -.display asis -control = submission -.endd -in a \\MAIL\\, \\RCPT\\, or pre-data ACL for an incoming SMTP message (see -sections ~~SECTACLmodi and ~~SECTcontrols). This makes Exim treat the message -as a local submission, and is normally used when the source of the message is -known to be an MUA running on a client host (as opposed to an MTA). For -example, to set submission mode for messages originating on the IPv4 loopback -interface, you could include the following in the \\MAIL\\ ACL: -.display asis -warn hosts = 127.0.0.1 - control = submission -.endd -There are some options that can be used when setting submission mode. A slash -is used to separate options. For example: -.display asis -control = submission/sender_retain -.endd -Specifying \sender@_retain\ has the effect of setting \local@_sender@_retain\ -true and \local@_from@_check\ false for the current incoming message. The first -of these allows an existing ::Sender:: header in the message to remain, and the -second suppresses the check to ensure that ::From:: matches the authenticated -sender. With this setting, Exim still fixes up messages by adding ::Date:: and -::Message-ID:: header lines if they are missing, but makes no attempt to check -sender authenticity in header lines. - -A submission mode setting may also specify a domain to be used when generating -a ::From:: or ::Sender:: header. For example: -.display asis -control = submission/domain=some.domain -.endd -The domain may be empty. How this value is used is described in sections -~~SECTthefrohea and ~~SECTthesenhea. -.nem - - - -.section Line endings -.rset SECTlineendings "~~chapter.~~section" -.index line endings -.index carriage return -.index linefeed -RFC 2821 specifies that CRLF (two characters: carriage-return, followed by -linefeed) is the line ending for messages transmitted over the Internet using -SMTP over TCP/IP. However, within individual operating systems, different -conventions are used. For example, Unix-like systems use just LF, but others -use CRLF or just CR. - -Exim was designed for Unix-like systems, and internally, it stores messages -using the system's convention of a single LF as a line terminator. When -receiving a message, all line endings are translated to this standard format. -Originally, it was thought that programs that passed messages directly to an -MTA within an operating system would use that system's convention. Experience -has shown that this is not the case; for example, there are Unix applications -that use CRLF in this circumstance. For this reason, and for compatibility with -other MTAs, the way Exim handles line endings for all messages is now as -follows: -.numberpars $. -LF not preceded by CR is treated as a line ending. -.nextp -CR is treated as a line ending; if it is immediately followed by LF, the LF -is ignored. -.nextp -The sequence `CR, dot, CR' does not terminate an incoming SMTP message, -nor a local message in the state where a line containing only a dot is a -terminator. -.nextp -If a bare CR is encountered within a header line, an extra space is added after -the line terminator so as not to end the header line. The reasoning behind this -is that bare CRs in header lines are most likely either to be mistakes, or -people trying to play silly games. -.nextp -If the first header line received in a message ends with CRLF, a subsequent -bare LF in a header line is treated in the same way as a bare CR in a header -line. -.endp - - - -.section Unqualified addresses -.index unqualified addresses -.index address||qualification -By default, Exim expects every envelope address it receives from an external -host to be fully qualified. Unqualified addresses cause negative responses to -SMTP commands. However, because SMTP is used as a means of transporting -messages from MUAs running on personal workstations, there is sometimes a -requirement to accept unqualified addresses from specific hosts or IP networks. - -Exim has two options that separately control which hosts may send unqualified -sender or receipient addresses in SMTP commands, namely -\sender__unqualified__hosts\ and \recipient__unqualified__hosts\. In both -cases, if an unqualified address is accepted, it is qualified by adding the -value of \qualify__domain\ or \qualify__recipient\, as appropriate. -.index \qualify@_domain\ -.index \qualify@_recipient\ - -.em -Unqualified addresses in header lines are automatically qualified for messages -that are locally originated, unless the \-bnq-\ option is given on the command -line. For messages received over SMTP, unqualified addresses in header lines -are qualified only if unqualified addresses are permitted in SMTP commands. In -other words, such qualification is also controlled by -\sender__unqualified__hosts\ and \recipient__unqualified__hosts\, -.nem - - -.section The UUCP From line -.index `From' line -.index UUCP||`From' line -.index sender||address -.index \uucp@_from@_pattern\ -.index \uucp@_from@_sender\ -.index envelope sender -.index Sendmail compatibility||`From' line -Messages that have come from UUCP (and some other applications) often begin -with a line containing the envelope sender and a timestamp, following the word -`From'. Examples of two common formats are: -.display asis -From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 -From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT -.endd -This line precedes the RFC 2822 header lines. For compatibility with Sendmail, -Exim recognizes such lines at the start of messages that are submitted to it -via the command line (that is, on the standard input). It does not recognize -such lines in incoming SMTP messages, unless the sending host matches -\ignore@_fromline@_hosts\ or the \-bs-\ option was used for a local message and -\ignore@_fromline@_local\ is set. The recognition is controlled by a regular -expression that is defined by the \uucp@_from@_pattern\ option, whose default -value matches the two common cases shown above and puts the address that -follows `From' into \$1$\. - -.index numerical variables (\$1$\, \$2$\, etc)||in `From ' line handling -When the caller of Exim for a non-SMTP message that contains a `From' line is a -trusted user, the message's sender address is constructed by expanding the -contents of \uucp@_sender@_address\, whose default value is `@$1'. This is then -parsed as an RFC 2822 address. If there is no domain, the local part is -qualified with \qualify@_domain\ unless it is the empty string. However, if the -command line \-f-\ option is used, it overrides the `From' line. - -If the caller of Exim is not trusted, the `From' line is recognized, but the -sender address is not changed. This is also the case for incoming SMTP messages -that are permitted to contain `From' lines. - -Only one `From' line is recognized. If there is more than one, the second is -treated as a data line that starts the body of the message, as it is not valid -as a header line. This also happens if a `From' line is present in an incoming -SMTP message from a source that is not permitted to send them. - - -.section Resent- header lines -.index \Resent@-\ header lines -RFC 2822 makes provision for sets of header lines starting with the string -\"Resent-"\ to be added to a message when it is resent by the original -recipient to somebody else. These headers are ::Resent-Date::, ::Resent-From::, -::Resent-Sender::, ::Resent-To::, ::Resent-Cc::, ::Resent-Bcc:: and -::Resent-Message-ID::. The RFC says: - -\*Resent fields are strictly informational. They MUST NOT be used in the normal -processing of replies or other such automatic actions on messages.*\ - -This leaves things a bit vague as far as other processing actions such as -address rewriting are concerned. Exim treats \Resent@-\ header lines as -follows: -.numberpars $. -A ::Resent-From:: line that just contains the login id of the submitting user -is automatically rewritten in the same way as ::From:: (see below). -.nextp -If there's a rewriting rule for a particular header line, it is also applied to -\Resent@-\ header lines of the same type. For example, a rule that rewrites -::From:: also rewrites ::Resent-From::. -.nextp -For local messages, if ::Sender:: is removed on input, ::Resent-Sender:: is also -removed. -.nextp -For a locally-submitted message, -if there are any \Resent@-\ header lines but no ::Resent-Date::, -::Resent-From::, or ::Resent-Message-Id::, they are added as necessary. It is -the contents of ::Resent-Message-Id:: (rather than ::Message-Id::) which are -included in log lines in this case. -.nextp -The logic for adding ::Sender:: is duplicated for ::Resent-Sender:: when any -\Resent@-\ header lines are present. -.endp - - -.section The Auto-Submitted: header line -Whenever Exim generates a bounce or a delay warning message, it includes the -header line -.display asis -Auto-Submitted: auto-generated -.endd - - -.section The Bcc: header line -.index ::Bcc:: header line -If Exim is called with the \-t-\ option, to take recipient addresses from a -message's header, it removes any ::Bcc:: header line that may exist (after -extracting its addresses). If \-t-\ is not present on the command line, any -existing ::Bcc:: is not removed. - -.section The Date: header line -.index ::Date:: header line -If a locally-generated -or submission-mode -message has no ::Date:: header line, Exim adds one, using the current date and -time. - -.section The Delivery-date: header line -.index ::Delivery-date:: header line -.index \delivery@_date@_remove\ -::Delivery-date:: header lines are not part of the standard RFC 2822 header -set. Exim can be configured to add them to the final delivery of messages. (See -the generic \delivery@_date@_add\ transport option.) They should not be present -in messages in transit. If the \delivery@_date@_remove\ configuration option is -set (the default), Exim removes ::Delivery-date:: header lines from incoming -messages. - -.section The Envelope-to: header line -.index ::Envelope-to:: header line -.index \envelope@_to@_remove\ -::Envelope-to:: header lines are not part of the standard RFC 2822 header set. -Exim can be configured to add them to the final delivery of messages. (See the -generic \envelope@_to@_add\ transport option.) They should not be present in -messages in transit. If the \envelope@_to@_remove\ configuration option is set -(the default), Exim removes ::Envelope-to:: header lines from incoming -messages. - -.section The From: header line -.rset SECTthefrohea "~~chapter.~~section" -.index ::From:: header line -.index Sendmail compatibility||`From' line -.index message||submission -.index submission mode -If a submission-mode message does not contain a ::From:: header line, Exim adds -one if either of the following conditions is true: -.numberpars $. -The envelope sender address is not empty (that is, this is not a bounce -message). The added header line copies the envelope sender address. -.nextp -The SMTP session is authenticated and \$authenticated@_id$\ is not empty. -.em -.numberpars alpha -If no domain is specified by the submission control, the local part is -\$authenticated@_id$\ and the domain is \$qualify@_domain$\. -.nextp -If a non-empty domain is specified by the submission control, the local part is -\$authenticated@_id$\, and the the domain is the specified domain. -.nextp -If an empty domain is specified by the submission control, -\$authenticated@_id$\ is assumed to be the complete address. -.endp -.nem -.endp -A non-empty envelope sender takes precedence. - -If a locally-generated incoming message does not contain a ::From:: header -line, Exim adds one containing the sender's address. The calling user's login -name and full name are used to construct the address, as described in section -~~SECTconstr. They are obtained from the password data by calling -\*getpwuid()*\ (but see the \unknown@_login\ configuration option). The address -is qualified with \qualify@_domain\. - -For compatibility with Sendmail, if an incoming, non-SMTP message has a -::From:: header line containing just the unqualified login name of the calling -user, this is replaced by an address containing the user's login name and full -name as described in section ~~SECTconstr. - -.section The Message-ID: header line -.index ::Message-ID:: header line -.index message||submission -If a locally-generated or submission-mode incoming message does not contain a -::Message-ID:: or ::Resent-Message-ID:: header line, Exim adds one to the -message. If there are any ::Resent-:: headers in the message, it creates -::Resent-Message-ID::. The id is constructed from Exim's internal message id, -preceded by the letter E to ensure it starts with a letter, and followed by @@ -and the primary host name. Additional information can be included in this -header line by setting the -.index \message@_id@_header@_text\ -\message@_id@_header@_text\ and/or \message__id__header__domain\ options. - - -.section The Received: header line -.index ::Received:: header line -A ::Received:: header line is added at the start of every message. The contents -are defined by the \received@_header@_text\ configuration option, and Exim -automatically adds a semicolon and a timestamp to the configured string. - -The ::Received:: header is generated as soon as the message's header lines have -been received. At this stage, the timestamp in the ::Received:: header line is -the time that the message started to be received. This is the value that is -seen by the \\DATA\\ ACL and by the \*local@_scan()*\ function. - -Once a message is accepted, the timestamp in the ::Received:: header line is -changed to the time of acceptance, which is (apart from a small delay while the --H spool file is written) the earliest time at which delivery could start. - - -.section The Return-path: header line -.index ::Return-path:: header line -.index \return@_path@_remove\ -::Return-path:: header lines are defined as something an MTA may insert when -it does the final delivery of messages. (See the generic \return@_path@_add\ -transport option.) Therefore, they should not be present in messages in -transit. If the \return@_path@_remove\ configuration option is set (the -default), Exim removes ::Return-path:: header lines from incoming messages. - - -.section The Sender: header line -.rset SECTthesenhea "~~chapter.~~section" -.index ::Sender:: header line -.index message||submission -For a locally-originated message from an untrusted user, Exim may remove an -existing ::Sender:: header line, and it may add a new one. You can modify these -actions by setting \local@_sender@_retain\ true or \local@_from@_check\ false. - -When a local message is received from an untrusted user and -\local@_from@_check\ is true (the default), a check is made to see if the -address given in the ::From:: header line is the correct (local) sender of the -message. The address that is expected has the login name as the local part and -the value of \qualify@_domain\ as the domain. Prefixes and suffixes for the -local part can be permitted by setting \local@_from@_prefix\ and -\local@_from@_suffix\ appropriately. If ::From:: does not contain the correct -sender, a ::Sender:: line is added to the message. - -If you set \local@_from@_check\ false, this checking does not occur. However, -the removal of an existing ::Sender:: line still happens, unless you also set -\local@_sender@_retain\ to be true. It is not possible to set both of these -options true at the same time. - -.em -.index submission mode -By default, no processing of ::Sender:: header lines is done for messages -received over TCP/IP or for messages submitted by trusted users. However, when -a message is received over TCP/IP in submission mode, and \sender@_retain\ is -not specified on the submission control, the following processing takes place: - -First, any existing ::Sender:: lines are removed. Then, if the SMTP session is -authenticated, and \$authenticated@_id$\ is not empty, a sender address is -created as follows: -.numberpars $. -If no domain is specified by the submission control, the local part is -\$authenticated@_id$\ and the domain is \$qualify@_domain$\. -.nextp -If a non-empty domain is specified by the submission control, the local part is -\$authenticated@_id$\, and the the domain is the specified domain. -.nextp -If an empty domain is specified by the submission control, -\$authenticated@_id$\ is assumed to be the complete address. -.endp -This address is compared with the address in the ::From:: header line. If they -are different, a ::Sender:: header line containing the created address is -added. Prefixes and suffixes for the local part in ::From:: can be permitted by -setting \local@_from@_prefix\ and \local@_from@_suffix\ appropriately. -.nem - - -.section Adding and removing header lines in routers and transports -.index header lines||adding, in router or transport -.index header lines||removing, in router or transport -.rset SECTheadersaddrem "~~chapter.~~section" -.em -When a message is delivered, the addition and removal of header lines can be -specified in a system filter, or on any of the routers and transports that -process the message. Section ~~SECTaddremheasys contains details about -modifying headers in a system filter. - -In contrast to what happens in a system filter, header modifications that are -specified on routers and transports apply only to the particular recipient -addresses that are being processed by those routers and transports. These -changes do not actually take place until a copy of the message is being -transported. Therefore, they do not affect the basic set of header lines, and -they do not affect the values of the variables that refer to header lines. - -For both routers and transports, the result of expanding a \headers@_add\ -option must be in the form of one or more RFC 2822 header lines, separated by -newlines (coded as `@\n'). For example: -.display asis -headers_add = X-added-header: added by $primary_hostname\n\ - X-added-second: another added header line -.endd -Exim does not check the syntax of these added header lines. - -The result of expanding \headers@_remove\ must consist of a colon-separated -list of header names. This is confusing, because header names themselves are -often terminated by colons. In this case, the colons are the list separators, -not part of the names. For example: -.display asis -headers_remove = return-receipt-to:acknowledge-to -.endd - -When \headers@_add\ or \headers@_remove\ is specified on a router, its value is -expanded at routing time, and then associated with all addresses that are -accepted by that router, and also with any new addresses that it generates. If -an address passes through several routers as a result of aliasing or -forwarding, the changes are cumulative. -.index \unseen\ option -However, this does not apply to multiple routers that result from the use of -the \unseen\ option. Any header modifications that were specified by the -`unseen' router or its predecessors apply only to the `unseen' delivery. - -Addresses that end up with different \headers@_add\ or \headers@_remove\ -settings cannot be delivered together in a batch, so a transport is always -dealing with a set of addresses that have the same header-processing -requirements. - -The transport starts by writing the original set of header lines that arrived -with the message, possibly modified by the system filter. As it writes out -these lines, it consults the list of header names that were attached to the -recipient address(es) by \headers@_remove\ options in routers, and it also -consults the transport's own \headers@_remove\ option. Header lines whose names -are on either of these lists are not written out. If there are multiple -instances of any listed header, they are all skipped. - -After the remaining original header lines have been written, new header -lines that were specified by routers' \headers@_add\ options are written, in -the order in which they were attached to the address. These are followed by any -header lines specified by the transport's \headers@_add\ option. - -This way of handling header line modifications in routers and transports has -the following consequences: -.numberpars $. -The original set of header lines, possibly modified by the system filter, -remains `visible', in the sense that the \$header@_$\\*xxx*\ variables refer to -it, at all times. -.nextp -Header lines that are added by a router's -\headers@_add\ option are not accessible by means of the \$header@_$\\*xxx*\ -expansion syntax in subsequent routers or the transport. -.nextp -Conversely, header lines that are specified for removal by \headers@_remove\ in -a router remain visible to subsequent routers and the transport. -.nextp -Headers added to an address by \headers@_add\ in a router cannot be removed by -a later router or by a transport. -.nextp -An added header can refer to the contents of an original header that is to be -removed, even it has the same name as the added header. For example: -.display asis -headers_remove = subject -headers_add = Subject: new subject (was: $h_subject:) -.endd -.endp - -\**Warning**\: The \headers@_add\ and \headers@_remove\ options cannot be used -for a \%redirect%\ router that has the \one@_time\ option set. -.nem - - - -.section Constructed addresses -.rset SECTconstr "~~chapter.~~section" -.index address||constructed -.index constructed address -When Exim constructs a sender address for a locally-generated message, it uses -the form -.display -<<user name>> <$$<<login>>@@<<qualify@_domain>>$$> -.endd -For example: -.display asis -Zaphod Beeblebrox <zaphod@end.univ.example> -.endd -The user name is obtained from the \-F-\ command line option if set, or -otherwise by looking up the calling user by \*getpwuid()*\ and extracting the -`gecos' field from the password entry. If the `gecos' field contains an -ampersand character, this is replaced by the login name with the first letter -upper cased, as is conventional in a number of operating systems. See the -\gecos@_name\ option for a way to tailor the handling of the `gecos' field. The -\unknown@_username\ option can be used to specify user names in cases when -there is no password file entry. - -In all cases, the user name is made to conform to RFC 2822 by quoting all or -parts of it if necessary. In addition, if it contains any non-printing -characters, it is encoded as described in RFC 2047, which defines a way of -including non-ASCII characters in header lines. -The value of the \headers@_charset\ option specifies the name of the encoding -that is used (the characters are assumed to be in this encoding). -The setting of \print@_topbitchars\ controls whether characters with the top -bit set (that is, with codes greater than 127) count as printing characters or -not. - - -.section Case of local parts -.index case of local parts -.index local part||case of -RFC 2822 states that the case of letters in the local parts of addresses cannot -be assumed to be non-significant. Exim preserves the case of local parts of -addresses, but by default it uses a lower-cased form when it is routing, -because on most Unix systems, usernames are in lower case and case-insensitive -routing is required. However, any particular router can be made to use the -original case for local parts by setting the \caseful@_local@_part\ generic -router option. - -.index mixed-case login names -If you must have mixed-case user names on your system, the best way to proceed, -assuming you want case-independent handling of incoming email, is to set up -your first router to convert incoming local parts in your domains to the -correct case by means of a file lookup. For example: -.display asis -correct_case: - driver = redirect - domains = +local_domains - data = ${lookup{$local_part}cdb\ - {/etc/usercased.cdb}{$value}fail}\ - @$domain -.endd -For this router, the local part is forced to lower case by the default action -(\caseful@_local@_part\ is not set). The lower-cased local part is used to look -up a new local part in the correct case. If you then set \caseful@_local@_part\ -on any subsequent routers which process your domains, they will operate on -local parts with the correct case in a case-sensitive manner. - - -.section Dots in local parts -.index dot||in local part -.index local part||dots in -RFC 2822 forbids empty components in local parts. That is, an unquoted local -part may not begin or end with a dot, nor have two consecutive dots in the -middle. However, it seems that many MTAs do not enforce this, so Exim permits -empty components for compatibility. - - -.section Rewriting addresses -.index rewriting||addresses -Rewriting of sender and recipient addresses, and addresses in headers, can -happen automatically, or as the result of configuration options, as described -in chapter ~~CHAPrewrite. The headers that may be affected by this are ::Bcc::, -::Cc::, ::From::, ::Reply-To::, ::Sender::, and ::To::. - -Automatic rewriting includes qualification, as mentioned above. The other case -in which it can happen is when an incomplete non-local domain is given. The -routing process may cause this to be expanded into the full domain name. For -example, a header such as -.display asis -To: hare@teaparty -.endd -might get rewritten as -.display asis -To: hare@teaparty.wonderland.fict.example -.endd -Rewriting as a result of routing is the one kind of message processing that -does not happen at input time, as it cannot be done until the address has -been routed. - -Strictly, one should not do $it{any} deliveries of a message until all its -addresses have been routed, in case any of the headers get changed as a -result of routing. However, doing this in practice would hold up many -deliveries for unreasonable amounts of time, just because one address could not -immediately be routed. Exim therefore does not delay other deliveries when -routing of one or more addresses is deferred. - - -. -. -. -. -. ============================================================================ -.chapter SMTP processing -.set runningfoot "smtp processing" -.rset CHAPSMTP ~~chapter -.index SMTP||processing details -.index LMTP||processing details -Exim supports a number of different ways of using the SMTP protocol, and its -LMTP variant, which is an interactive protocol for transferring messages into a -closed mail store application. This chapter contains details of how SMTP is -processed. For incoming mail, the following are available: -.numberpars $. -SMTP over TCP/IP (Exim daemon or \*inetd*\); -.nextp -SMTP over the standard input and output (the \-bs-\ option); -.nextp -Batched SMTP on the standard input (the \-bS-\ option). -.endp -For mail delivery, the following are available: -.numberpars $. -SMTP over TCP/IP (the \%smtp%\ transport); -.nextp -LMTP over TCP/IP (the \%smtp%\ transport with the \protocol\ option set to -`lmtp'); -.nextp -LMTP over a pipe to a process running in the local host (the \%lmtp%\ -transport); -.nextp -Batched SMTP to a file or pipe (the \%appendfile%\ and \%pipe%\ transports with -the \use@_bsmtp\ option set). -.endp -\*Batched SMTP*\ is the name for a process in which batches of messages are -stored in or read from files (or pipes), in a format in which SMTP commands are -used to contain the envelope information. - - -.section Outgoing SMTP and LMTP over TCP/IP -.rset SECToutSMTPTCP "~~chapter.~~section" -.index SMTP||outgoing over TCP/IP -.index outgoing SMTP over TCP/IP -.index LMTP||over TCP/IP -.index outgoing LMTP over TCP/IP -.index \\EHLO\\ -.index \\HELO\\ -.index \\SIZE\\ option on \\MAIL\\ command -Outgoing SMTP and LMTP over TCP/IP is implemented by the \%smtp%\ transport. -The \protocol\ option selects which protocol is to be used, but the actual -processing is the same in both cases. - -If, in response to its \\EHLO\\ command, Exim is told that the \\SIZE\\ -parameter is supported, it adds \\SIZE\\=<<n>> to each subsequent \\MAIL\\ -command. The value of <<n>> is the message size plus the value of the -\size@_addition\ option (default 1024) to allow for additions to the message -such as per-transport header lines, or changes made in a -.index transport||filter -.index filter||transport filter -transport filter. If \size@_addition\ is set negative, the use of \\SIZE\\ is -suppressed. - -If the remote server advertises support for \\PIPELINING\\, Exim uses the -pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets -required for the transaction. - -If the remote server advertises support for the \\STARTTLS\\ command, and Exim -was built to support TLS encryption, it tries to start a TLS session unless the -server matches \hosts@_avoid@_tls\. See chapter ~~CHAPTLS for more details. - -If the remote server advertises support for the \\AUTH\\ command, Exim scans -the authenticators configuration for any suitable client settings, as described -in chapter ~~CHAPSMTPAUTH. - -.index carriage return -.index linefeed -Responses from the remote host are supposed to be terminated by CR followed by -LF. However, there are known to be hosts that do not send CR characters, so in -order to be able to interwork with such hosts, Exim treats LF on its own as a -line terminator. - -If a message contains a number of different addresses, all those with the same -characteristics (for example, the same envelope sender) that resolve to the -same set of hosts, in the same order, are sent in a single SMTP transaction, -even if they are for different domains, unless there are more than the setting -of the \max@_rcpts\ option in the \%smtp%\ transport allows, in which case they -are split into groups containing no more than \max@_rcpts\ addresses each. If -\remote@_max@_parallel\ is greater than one, such groups may be sent in -parallel sessions. The order of hosts with identical MX values is not -significant when checking whether addresses can be batched in this way. - -When the \%smtp%\ transport suffers a temporary failure that is not -message-related, Exim updates its transport-specific database, which contains -records indexed by host name that remember which messages are waiting for each -particular host. It also updates the retry database with new retry times. -.index hints database||retry keys -Exim's retry hints are based on host name plus IP address, so if one address of -a multi-homed host is broken, it will soon be skipped most of the time. -See the next section for more detail about error handling. - -.index SMTP||passed connection -.index SMTP||batching over TCP/IP -When a message is successfully delivered over a TCP/IP SMTP connection, Exim -looks in the hints database for the transport to see if there are any queued -messages waiting for the host to which it is connected. If it finds one, it -creates a new Exim process using the \-MC-\ option (which can only be used by a -process running as root or the Exim user) and passes the TCP/IP socket to it so -that it can deliver another message using the same socket. The new process does -only those deliveries that are routed to the connected host, and may in turn -pass the socket on to a third process, and so on. - -The \connection@_max@_messages\ option of the \%smtp%\ transport can be used to -limit the number of messages sent down a single TCP/IP connection. -.index asterisk||after IP address -The second and subsequent messages delivered down an existing connection are -identified in the main log by the addition of an asterisk after the closing -square bracket of the IP address. - - - -.section Errors in outgoing SMTP -.rset SECToutSMTPerr "~~chapter.~~section" -.index error||in outgoing SMTP -.index SMTP||errors in outgoing -.index host||error -Three different kinds of error are recognized for outgoing SMTP: host errors, -message errors, and recipient errors. -.numberpars -A host error is not associated with a particular message or with a -particular recipient of a message. The host errors are: -.numberpars $. -Connection refused or timed out, -.nextp -Any error response code on connection, -.nextp -Any error response code to \\EHLO\\ or \\HELO\\, -.nextp -Loss of connection at any time, except after `.', -.nextp -I/O errors at any time, -.nextp -Timeouts during the session, other than in response to \\MAIL\\, \\RCPT\\ or -the `.' at the end of the data. -.endp -For a host error, a permanent error response on connection, or in response to -\\EHLO\\, causes all addresses routed to the host to be failed. Any other host -error causes all addresses to be deferred, and retry data to be created for the -host. It is not tried again, for any message, until its retry time arrives. If -the current set of addresses are not all delivered in this run (to some -alternative host), the message is added to the list of those waiting for this -host, so if it is still undelivered when a subsequent successful delivery is -made to the host, it will be sent down the same SMTP connection. -.nextp -.index message||error -A message error is associated with a particular message when sent to a -particular host, but not with a particular recipient of the message. The -message errors are: -.numberpars $. -Any error response code to \\MAIL\\, \\DATA\\, or the `.' that terminates -the data, -.nextp -Timeout after \\MAIL\\, -.nextp -Timeout -or loss of connection after the `.' that terminates the data. A timeout after -the \\DATA\\ command itself is treated as a host error, as is loss of -connection at any other time. -.endp -For a message error, a permanent error response (5$it{xx}) causes all addresses -to be failed, and a delivery error report to be returned to the sender. A -temporary error response (4$it{xx}), or one of the timeouts, causes all -addresses to be deferred. Retry data is not created for the host, but instead, -a retry record for the combination of host plus message id is created. The -message is not added to the list of those waiting for this host. This ensures -that the failing message will not be sent to this host again until the retry -time arrives. However, other messages that are routed to the host are not -affected, so if it is some property of the message that is causing the error, -it will not stop the delivery of other mail. - -If the remote host specified support for the \\SIZE\\ parameter in its response -to \\EHLO\\, Exim adds SIZE=$it{nnn} to the \\MAIL\\ command, so an -over-large message will cause a message error because the error arrives as a -response to \\MAIL\\. -.nextp -.index recipient||error -A recipient error is associated with a particular recipient of a message. The -recipient errors are: -.numberpars $. -Any error response to \\RCPT\\, -.nextp -Timeout after \\RCPT\\. -.endp -For a recipient error, a permanent error response (5$it{xx}) causes the -recipient address to be failed, and a bounce message to be returned to the -sender. A temporary error response (4$it{xx}) or a timeout causes the failing -address to be deferred, and routing retry data to be created for it. This is -used to delay processing of the address in subsequent queue runs, until its -routing retry time arrives. This applies to all messages, but because it -operates only in queue runs, one attempt will be made to deliver a new message -to the failing address before the delay starts to operate. This ensures that, -if the failure is really related to the message rather than the recipient -(`message too big for this recipient' is a possible example), other messages -have a chance of getting delivered. If a delivery to the address does succeed, -the retry information gets cleared, so all stuck messages get tried again, and -the retry clock is reset. - -The message is not added to the list of those waiting for this host. Use of the -host for other messages is unaffected, and except in the case of a timeout, -other recipients are processed independently, and may be successfully delivered -in the current SMTP session. After a timeout it is of course impossible to -proceed with the session, so all addresses get deferred. However, those other -than the one that failed do not suffer any subsequent retry delays. Therefore, -if one recipient is causing trouble, the others have a chance of getting -through when a subsequent delivery attempt occurs before the failing -recipient's retry time. -.endp - -In all cases, if there are other hosts (or IP addresses) available for the -current set of addresses (for example, from multiple MX records), they are -tried in this run for any undelivered addresses, subject of course to their -own retry data. In other words, recipient error retry data does not take effect -until the next delivery attempt. - -Some hosts have been observed to give temporary error responses to every -\\MAIL\\ command at certain times (`insufficient space' has been seen). It -would be nice if such circumstances could be recognized, and defer data for the -host itself created, but this is not possible within the current Exim design. -What actually happens is that retry data for every (host, message) combination -is created. - -The reason that timeouts after \\MAIL\\ and \\RCPT\\ are treated specially is -that these can sometimes arise as a result of the remote host's verification -procedures. Exim makes this assumption, and treats them as if a temporary error -response had been received. A timeout after `.' is treated specially because it -is known that some broken implementations fail to recognize the end of the -message if the last character of the last line is a binary zero. Thus, it is -helpful to treat this case as a message error. - -Timeouts at other times are treated as host errors, assuming a problem with the -host, or the connection to it. If a timeout after \\MAIL\\, \\RCPT\\, -or `.' is really a connection problem, the assumption is that at the next try -the timeout is likely to occur at some other point in the dialogue, causing it -then to be treated as a host error. - -There is experimental evidence that some MTAs drop the connection after the -terminating `.' if they do not like the contents of the message for some -reason, in contravention of the RFC, which indicates that a 5$it{xx} response -should be given. That is why Exim treats this case as a message rather than a -host error, in order not to delay other messages to the same host. - - - - -.section Variable Envelope Return Paths (VERP) -.index VERP -.index Variable Envelope Return Paths -.index envelope sender -Variable Envelope Return Paths -- see -\?ftp://koobera.math.uic.edu/www/proto/verp.txt?\ -- can be supported in Exim -by using the \return@_path\ generic transport option to rewrite the return path -at transport time. For example, the following could be used on an \%smtp%\ -transport: -.display asis -return_path = \ - ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ - {$1-request=$local_part%$domain@your.dom.example}fail} -.endd -This has the effect of rewriting the return path (envelope sender) on all -outgoing SMTP messages, if the local part of the original return path ends in -`-request', and the domain is \*your.dom.example*\. The rewriting inserts the -local part and domain of the recipient into the return path. Suppose, for -example, that a message whose return path has been set to -\*somelist-request@@your.dom.example*\ is sent to -\*subscriber@@other.dom.example*\. In the transport, the return path is -rewritten as -.display asis -somelist-request=subscriber%other.dom.example@your.dom.example -.endd -For this to work, you must arrange for outgoing messages that have `-request' -in their return paths to have just a single recipient. This can be done by -setting -.display asis -max_rcpt = 1 -.endd -in the \%smtp%\ transport. Otherwise a single copy of a message might be -addressed to several different recipients in the same domain, in which case -\$local@_part$\ is not available (because it is not unique). Of course, if you -do start sending out messages with this kind of return path, you must also -configure Exim to accept the bounce messages that come back to those paths. -Typically this would be done by setting an \local@_part@_suffix\ option for a -suitable router. - -The overhead incurred in using VERP depends very much on the size of the -message, the number of recipient addresses that resolve to the same remote -host, and the speed of the connection over which the message is being sent. If -a lot of addresses resolve to the same host and the connection is slow, sending -a separate copy of the message for each address may take substantially longer -than sending a single copy with many recipients (for which VERP cannot be -used). - - -.section Incoming SMTP messages over TCP/IP -.index SMTP||incoming over TCP/IP -.index incoming SMTP over TCP/IP -.index inetd -.index daemon -Incoming SMTP messages can be accepted in one of two ways: by running a -listening daemon, or by using \*inetd*\. In the latter case, the entry in -\(/etc/inetd.conf)\ should be like this: -.display asis -smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs -.endd -Exim distinguishes between this case and the case of a locally running user -agent using the \-bs-\ option by checking whether or not the standard input is -a socket. When it is, either the port must be privileged (less than 1024), or -the caller must be root or the Exim user. If any other user passes a socket -with an unprivileged port number, Exim prints a message on the standard error -stream and exits with an error code. - -By default, Exim does not make a log entry when a remote host connects or -disconnects (either via the daemon or \*inetd*\), unless the disconnection is -unexpected. It can be made to write such log entries by setting the -\smtp@_connection\ log selector. - -.index carriage return -.index linefeed -Commands from the remote host are supposed to be terminated by CR followed by -LF. However, there are known to be hosts that do not send CR characters. In -order to be able to interwork with such hosts, Exim treats LF on its own as a -line terminator. -Furthermore, because common code is used for receiving messages from all -sources, a CR on its own is also interpreted as a line terminator. However, the -sequence `CR, dot, CR' does not terminate incoming SMTP data. - -.index \\EHLO\\||invalid data -.index \\HELO\\||invalid data -One area that sometimes gives rise to problems concerns the \\EHLO\\ or -\\HELO\\ commands. Some clients send syntactically invalid versions of these -commands, which Exim rejects by default. (This is nothing to do with verifying -the data that is sent, so \helo@_verify@_hosts\ is not relevant.) You can tell -Exim not to apply a syntax check by setting \helo@_accept@_junk@_hosts\ to -match the broken hosts that send invalid commands. - -.index \\SIZE\\ option on \\MAIL\\ command -.index \\MAIL\\||\\SIZE\\ option -The amount of disk space available is checked whenever \\SIZE\\ is received on -a \\MAIL\\ command, independently of whether \message@_size@_limit\ or -\check@_spool@_space\ is configured, unless \smtp__check__spool__space\ is set -false. A temporary error is given if there is not enough space. If -\check@_spool@_space\ is set, the check is for that amount of space plus the -value given with \\SIZE\\, that is, it checks that the addition of the incoming -message will not reduce the space below the threshold. - -When a message is successfully received, Exim includes the local message id in -its response to the final `.' that terminates the data. If the remote host logs -this text it can help with tracing what has happened to a message. - -The Exim daemon can limit the number of simultaneous incoming connections it is -prepared to handle (see the \smtp@_accept@_max\ option). It can also limit the -number of simultaneous incoming connections from a single remote host (see the -\smtp@_accept@_max@_per@_host\ option). Additional connection attempts are -rejected using the SMTP temporary error code 421. - -The Exim daemon does not rely on the \\SIGCHLD\\ signal to detect when a -subprocess has finished, as this can get lost at busy times. Instead, it looks -for completed subprocesses every time it wakes up. Provided there are other -things happening (new incoming calls, starts of queue runs), completed -processes will be noticed and tidied away. On very quiet systems you may -sometimes see a `defunct' Exim process hanging about. This is not a problem; it -will be noticed when the daemon next wakes up. - -When running as a daemon, Exim can reserve some SMTP slots for specific hosts, -and can also be set up to reject SMTP calls from non-reserved hosts at times of -high system load -- for details see the \smtp@_accept@_reserve\, -\smtp@_load@_reserve\, and \smtp@_reserve@_hosts\ options. The load check -applies in both the daemon and \*inetd*\ cases. - -Exim normally starts a delivery process for each message received, though this -can be varied by means of the \-odq-\ command line option and the -\queue@_only\, \queue@_only@_file\, and \queue@_only@_load\ options. The number -of simultaneously running delivery processes started in this way from SMTP -input can be limited by the \smtp__accept__queue\ and -\smtp__accept__queue__per__connection\ options. When either limit is reached, -subsequently received messages are just put on the input queue without starting -a delivery process. - -The controls that involve counts of incoming SMTP calls (\smtp@_accept@_max\, -\smtp@_accept@_queue\, \smtp__accept__reserve\) are not available when Exim is -started up from the \*inetd*\ daemon, because in that case each connection is -handled by an entirely independent Exim process. Control by load average is, -however, available with \*inetd*\. - -Exim can be configured to verify addresses in incoming SMTP commands as they -are received. See chapter ~~CHAPACL for details. It can also be configured to -rewrite addresses at this time -- before any syntax checking is done. See -section ~~SECTrewriteS. - -Exim can also be configured to limit the rate at which a client host submits -\\MAIL\\ and \\RCPT\\ commands in a single SMTP session. See the -\smtp@_ratelimit@_hosts\ option. - - -.section Unrecognized SMTP commands -.index SMTP||unrecognized commands -If Exim receives more than \smtp@_max@_unknown@_commands\ unrecognized SMTP -commands during a single SMTP connection, it drops the connection after sending -the error response to the last command. The default value for -\smtp@_max@_unknown@_commands\ is 3. This is a defence against some kinds of -abuse that subvert web servers into making connections to SMTP ports; in these -circumstances, a number of non-SMTP lines are sent first. - -.section Syntax and protocol errors in SMTP commands -.index SMTP||syntax errors -.index SMTP||protocol errors -A syntax error is detected if an SMTP command is recognized, but there is -something syntactically wrong with its data, for example, a malformed email -address in a \\RCPT\\ command. Protocol errors include invalid command -sequencing such as \\RCPT\\ before \\MAIL\\. If Exim receives more than -\smtp@_max@_synprot@_errors\ such commands during a single SMTP connection, it -drops the connection after sending the error response to the last command. The -default value for \smtp__max__synprot__errors\ is 3. This is a defence against -broken clients that loop sending bad commands (yes, it has been seen). - - -.section Use of non-mail SMTP commands -.index SMTP||non-mail commands -The `non-mail' SMTP commands are those other than \\MAIL\\, \\RCPT\\, and -\\DATA\\. Exim counts such commands, and drops the connection if there are too -many of them in a single SMTP session. This action catches some -denial-of-service attempts and things like repeated failing \\AUTH\\s, or a mad -client looping sending \\EHLO\\. The global option \smtp@_accept@_max@_nonmail\ -defines what `too many' means. Its default value is 10. - -When a new message is expected, one occurrence of \\RSET\\ is not counted. This -allows a client to send one \\RSET\\ between messages (this is not necessary, -but some clients do it). Exim also allows one uncounted occurence of \\HELO\\ -or \\EHLO\\, and one occurrence of \\STARTTLS\\ between messages. After -starting up a TLS session, another \\EHLO\\ is expected, and so it too is not -counted. - -The first occurrence of \\AUTH\\ in a connection, or immediately following -\\STARTTLS\\ is also not counted. Otherwise, all commands other than \\MAIL\\, -\\RCPT\\, \\DATA\\, and \\QUIT\\ are counted. - -You can control which hosts are subject to the limit set by -\smtp@_accept@_max@_nonmail\ by setting -\smtp@_accept@_max@_nonmail@_hosts\. The default value is \"$*$"\, which makes -the limit apply to all hosts. This option means that you can exclude any -specific badly-behaved hosts that you have to live with. - - - -.section The \\VRFY\\ and \\EXPN\\ commands -When Exim receives a \\VRFY\\ or \\EXPN\\ command on a TCP/IP connection, it -runs the ACL specified by \acl@_smtp@_vrfy\ or \acl@_smtp@_expn\ (as -appropriate) in order to decide whether the command should be accepted or not. -If no ACL is defined, the command is rejected. - -.index \\VRFY\\||processing -When \\VRFY\\ is accepted, it runs exactly the same code as when Exim is -called with the \-bv-\ option. -.index \\EXPN\\||processing -When \\EXPN\\ is accepted, a single-level expansion of the address is done. -\\EXPN\\ is treated as an `address test' (similar to the \-bt-\ option) rather -than a verification (the \-bv-\ option). If an unqualified local part is given -as the argument to \\EXPN\\, it is qualified with \qualify@_domain\. Rejections -of \\VRFY\\ and \\EXPN\\ commands are logged on the main and reject logs, and -\\VRFY\\ verification failures are logged on the main log for consistency with -\\RCPT\\ failures. - - -.section The \\ETRN\\ command -.rset SECTETRN "~~chapter.~~section" -.index \\ETRN\\||processing -RFC 1985 describes an SMTP command called \\ETRN\\ that is designed to -overcome the security problems of the \\TURN\\ command (which has fallen into -disuse). When Exim receives an \\ETRN\\ command on a TCP/IP connection, it runs -the ACL specified by \acl@_smtp@_etrn\ in order to decide whether the command -should be accepted or not. If no ACL is defined, the command is rejected. - -The \\ETRN\\ command is concerned with `releasing' messages that are awaiting -delivery to certain hosts. As Exim does not organize its message queue by host, -the only form of \\ETRN\\ that is supported by default is the one where the -text starts with the `@#' prefix, in which case the remainder of the text is -specific to the SMTP server. A valid \\ETRN\\ command causes a run of Exim with -the \-R-\ option to happen, with the remainder of the \\ETRN\\ text as its -argument. For example, -.display asis -ETRN #brigadoon -.endd -runs the command -.display asis -exim -R brigadoon -.endd -which causes a delivery attempt on all messages with undelivered addresses -containing the text `brigadoon'. When \smtp@_etrn@_serialize\ is set (the -default), Exim prevents the simultaneous execution of more than one queue run -for the same argument string as a result of an \\ETRN\\ command. This stops -a misbehaving client from starting more than one queue runner at once. - -.index hints database||\\ETRN\\ serialization -Exim implements the serialization by means of a hints database in which a -record is written whenever a process is started by \\ETRN\\, and deleted when -the process completes. However, Exim does not keep the SMTP session waiting for -the \\ETRN\\ process to complete. Once \\ETRN\\ is accepted, the client is sent -a `success' return code. Obviously there is scope for hints records to get left -lying around if there is a system or program crash. To guard against this, Exim -ignores any records that are more than six hours old. - -.index \smtp@_etrn@_command\ -For more control over what \\ETRN\\ does, the \smtp@_etrn@_command\ option can -used. This specifies a command that is run whenever \\ETRN\\ is received, -whatever the form of its argument. For -example: -.display asis -smtp_etrn_command = /etc/etrn_command $domain $sender_host_address -.endd -The string is split up into arguments which are independently expanded. The -expansion variable \$domain$\ is set to the argument of the \\ETRN\\ command, -and no syntax checking is done on the contents of this argument. Exim does not -wait for the command to complete, so its status code is not checked. Exim runs -under its own uid and gid when receiving incoming SMTP, so it is not possible -for it to change them before running the command. - - -.section Incoming local SMTP -.index SMTP||local incoming -Some user agents use SMTP to pass messages to their local MTA using the -standard input and output, as opposed to passing the envelope on the command -line and writing the message to the standard input. This is supported by the -\-bs-\ option. This form of SMTP is handled in the same way as incoming -messages over TCP/IP (including the use of ACLs), except that the envelope -sender given in a \\MAIL\\ command is ignored unless the caller is trusted. In -an ACL you can detect this form of SMTP input by testing for an empty host -identification. It is common to have this as the first line in the ACL that -runs for \\RCPT\\ commands: -.display asis -accept hosts = : -.endd -This accepts SMTP messages from local processes without doing any other tests. - - -.section Outgoing batched SMTP -.rset SECTbatchSMTP "~~chapter.~~section" -.index SMTP||batched outgoing -.index batched SMTP output -Both the \%appendfile%\ and \%pipe%\ transports can be used for handling batched -SMTP. Each has an option called \use@_bsmtp\ which causes messages to be output -in BSMTP format. No SMTP responses are possible for this form of delivery. All -it is doing is using SMTP commands as a way of transmitting the envelope along -with the message. - -The message is written to the file or pipe preceded by the SMTP commands -\\MAIL\\ and \\RCPT\\, and followed by a line containing a single dot. Lines in -the message that start with a dot have an extra dot added. The SMTP command -\\HELO\\ is not normally used. If it is required, the \message@_prefix\ option -can be used to specify it. - -Because \%appendfile%\ and \%pipe%\ are both local transports, they accept only -one recipient address at a time by default. However, you can arrange for them -to handle several addresses at once by setting the \batch@_max\ option. When -this is done for BSMTP, messages may contain multiple \\RCPT\\ commands. See -chapter ~~CHAPbatching for more details. - -When one or more addresses are routed to a BSMTP transport by a router that -sets up a host list, the name of the first host on the list is available to the -transport in the variable \$host$\. Here is an example of such a transport and -router: -.display asis -begin routers -route_append: - driver = manualroute - transport = smtp_appendfile - route_list = domain.example batch.host.example - -begin transports -smtp_appendfile: - driver = appendfile - directory = /var/bsmtp/$host - batch_max = 1000 - use_bsmtp - user = exim -.endd -This causes messages addressed to \*domain.example*\ to be written in BSMTP -format to \(/var/bsmtp/batch.host.example)\, with only a single copy of each -message (unless there are more than 1000 recipients). - - -.section Incoming batched SMTP -.rset SECTincomingbatchedSMTP "~~chapter.~~section" -.index SMTP||batched incoming -.index batched SMTP input -The \-bS-\ command line option causes Exim to accept one or more messages by -reading SMTP on the standard input, but to generate no responses. If the caller -is trusted, the senders in the \\MAIL\\ commands are believed; otherwise the -sender is always the caller of Exim. Unqualified senders and receivers are not -rejected (there seems little point) but instead just get qualified. \\HELO\\ -and \\EHLO\\ act as \\RSET\\; \\VRFY\\, \\EXPN\\, \\ETRN\\ and \\HELP\\, act -as \\NOOP\\; \\QUIT\\ quits. - -No policy checking is done for BSMTP input. That is, no ACL is run at anytime. -In this respect it is like non-SMTP local input. - -If an error is detected while reading a message, including a missing `.' at -the end, Exim gives up immediately. It writes details of the error to the -standard output in a stylized way that the calling program should be able to -make some use of automatically, for example: -.display asis -554 Unexpected end of file -Transaction started in line 10 -Error detected in line 14 -.endd -It writes a more verbose version, for human consumption, to the standard error -file, for example: -.display asis -An error was detected while processing a file of BSMTP input. -The error message was: - - 501 '>' missing at end of address - -The SMTP transaction started in line 10. -The error was detected in line 12. -The SMTP command at fault was: - - rcpt to:<malformed@in.com.plete - -1 previous message was successfully processed. -The rest of the batch was abandoned. -.endd -The return code from Exim is zero only if there were no errors. It is 1 if some -messages were accepted before an error was detected, and 2 if no messages were -accepted. - - - -. -. -. -. -. ============================================================================ -.chapter Customizing bounce and warning messages -.set runningfoot "customizing messages" -.rset CHAPemsgcust "~~chapter" -When a message fails to be delivered, or remains on the queue for more than a -configured amount of time, Exim sends a message to the original sender, or -to an alternative configured address. The text of these messages is built into -the code of Exim, but it is possible to change it, either by adding a single -string, or by replacing each of the paragraphs by text supplied in a file. - -The ::From:: and ::To:: header lines are automatically generated; you can cause -a ::Reply-To:: line to be added by setting the \errors@_reply@_to\ option. Exim -also adds the line -.display asis -Auto-Submitted: auto-generated -.endd -to all warning and bounce messages, - -.section Customizing bounce messages -.index customizing||bounce message -.index bounce message||customizing -If \bounce@_message@_text\ is set, its contents are included in the default -message immediately after `This message was created automatically by mail -delivery software.' The string is not expanded. It is not used if -\bounce@_message@_file\ is set. - -When \bounce@_message@_file\ is set, it must point to a template file for -constructing error messages. The file consists of a series of text items, -separated by lines consisting of exactly four asterisks. If the file cannot be -opened, default text is used and a message is written to the main and panic -logs. If any text item in the file is empty, default text is used for that -item. - -Each item of text that is read from the file is expanded, and there are two -expansion variables which can be of use here: \$bounce@_recipient$\ is set to -the recipient of an error message while it is being created, and -\$return@_size@_limit$\ contains the value of the \return@_size@_limit\ option, -rounded to a whole number. - -The items must appear in the file in the following order: -.numberpars $. -The first item is included in the headers, and should include at least a -::Subject:: header. Exim does not check the syntax of these headers. -.nextp -The second item forms the start of the error message. After it, Exim lists the -failing addresses with their error messages. -.nextp -The third item is used to introduce any text from pipe transports that is to be -returned to the sender. It is omitted if there is no such text. -.nextp -The fourth item is used to introduce the copy of the message that is returned -as part of the error report. -.nextp -The fifth item is added after the fourth one if the returned message is -truncated because it is bigger than \return@_size@_limit\. -.nextp -The sixth item is added after the copy of the original message. -.endp -The default state (\bounce@_message@_file\ unset) is equivalent to the -following file, in which the sixth item is empty. The ::Subject:: line has been -split into two here in order to fit it on the page: -.if ~~sys.fancy -.display flow asis -.fontgroup 0 -.font 54 -.else -.rule -.display flow asis -.linelength 80em -.indent 0 -.fi -Subject: Mail delivery failed - ${if eq{$sender_address}{$bounce_recipient}{: returning message to sender}} -**** -This message was created automatically by mail delivery software. - -A message ${if eq{$sender_address}{$bounce_recipient}{that you sent }{sent by - - <$sender_address> - -}}could not be delivered to all of its recipients. -The following address(es) failed: -**** -The following text was generated during the delivery attempt(s): -**** ------- This is a copy of the message, including all the headers. ------ -**** ------- The body of the message is $message_size characters long; only the first ------- $return_size_limit or so are included here. -**** -.endd -.if !~~sys.fancy -.rule -.fi - -.section Customizing warning messages -.rset SECTcustwarn "~~chapter.~~section" -.index customizing||warning message -.index warning of delay||customizing the message -The option -\warn@_message@_file\ -can be pointed at a template file for use when -warnings about message delays are created. In this case there are only three -text sections: -.numberpars $. -The first item is included in the headers, and should include at least a -::Subject:: header. Exim does not check the syntax of these headers. -.nextp -The second item forms the start of the warning message. After it, Exim lists -the delayed addresses. -.nextp -The third item then ends the message. -.endp -The default state is equivalent to the following file, except that the line -starting `A message' has been split here, in order to fit it on the page: -.if ~~sys.fancy -.display asis -.fontgroup 0 -.font 54 -.else -.rule -.display asis -.linelength 80em -.indent 0 -.fi -.newline -Subject: Warning: message $message_id delayed $warn_message_delay -**** -This message was created automatically by mail delivery software. - -A message ${if eq{$sender_address}{$warn_message_recipients} - {that you sent }{sent by - - <$sender_address> - -}}has not been delivered to all of its recipients after -more than $warn_message_delay on the queue on $primary_hostname. -.newline - -The message identifier is: $message_id -The subject of the message is: $h_subject -The date of the message is: $h_date - -The following address(es) have not yet been delivered: -**** -No action is required on your part. Delivery attempts will continue for -some time, and this warning may be repeated at intervals if the message -remains undelivered. Eventually the mail delivery software will give up, -and when that happens, the message will be returned to you. -.endd -.if !~~sys.fancy -.rule -.fi -except that in the default state the subject and date lines are omitted if no -appropriate headers exist. During the expansion of this file, -\$warn@_message@_delay$\ -is set to the delay time in one of the forms `<<n>> minutes' -or `<<n>> hours', and -\$warn@_message@_recipients$\ -contains a list of recipients for the warning message. There may be more than -one if there are multiple addresses with different \errors@_to\ settings on the -routers that handled them. - - - - -. -. -. -. ============================================================================ -.chapter Some common configuration requirements -.set runningfoot "common configuration requirements" -.rset CHAPcomconreq "~~chapter" -This chapter discusses some configuration requirements that seem to be fairly -common. More examples and discussion can be found in the Exim book. - - -.section Sending mail to a smart host -.index smart host||example router -If you want to send all mail for non-local domains to a `smart host', you -should replace the default \%dnslookup%\ router with a router which does the -routing explicitly: -.display asis -send_to_smart_host: - driver = manualroute - route_list = !+local_domains smart.host.name - transport = remote_smtp -.endd -You can use the smart host's IP address instead of the name if you wish. -.em -If you are using Exim only to submit messages to a smart host, and not for -receiving incoming messages, you can arrange for it to do the submission -synchronously by setting the \mua@_wrapper\ option (see chapter -~~CHAPnonqueueing). -.nem - - -.section Using Exim to handle mailing lists -.rset SECTmailinglists "~~chapter.~~section" -.index mailing lists -Exim can be used to run simple mailing lists, but for large and/or complicated -requirements, the use of additional specialized mailing list software such as -Majordomo or Mailman is recommended. - -The \%redirect%\ router can be used to handle mailing lists where each list -is maintained in a separate file, which can therefore be managed by an -independent manager. The \domains\ router option can be used to run these -lists in a separate domain from normal mail. For example: -.display asis -lists: - driver = redirect - domains = lists.example - file = /usr/lists/$local_part - forbid_pipe - forbid_file - errors_to = $local_part-request@lists.example - no_more -.endd -This router is skipped for domains other than \*lists.example*\. For addresses -in that domain, it looks for a file that matches the local part. If there is no -such file, the router declines, but because \no@_more\ is set, no subsequent -routers are tried, and so the whole delivery fails. - -The \forbid@_pipe\ and \forbid@_file\ options prevent a local part from being -expanded into a file name or a pipe delivery, which is usually inappropriate in -a mailing list. - -.index \errors@_to\ -The \errors@_to\ option specifies that any delivery errors caused by addresses -taken from a mailing list are to be sent to the given address rather than the -original sender of the message. However, before acting on this, Exim verifies -the error address, and ignores it if verification fails. - -For example, using the configuration above, mail sent to -\*dicts@@lists.example*\ is passed on to those addresses contained in -\(/usr/lists/dicts)\, with error reports directed to -\*dicts-request@@lists.example*\, provided that this address can be verified. -There could be a file called \(/usr/lists/dicts-request)\ containing -the address(es) of this particular list's manager(s), but other approaches, -such as setting up an earlier router (possibly using the \local@_part@_prefix\ -or \local@_part@_suffix\ options) to handle addresses of the form \owner-xxx\ -or \xxx-request\, are also possible. - - -.section Syntax errors in mailing lists -.index mailing lists||syntax errors in -If an entry in redirection data contains a syntax error, Exim normally defers -delivery of the original address. That means that a syntax error in a mailing -list holds up all deliveries to the list. This may not be appropriate when a -list is being maintained automatically from data supplied by users, and the -addresses are not rigorously checked. - -If the \skip@_syntax@_errors\ option is set, the \%redirect%\ router just skips -entries that fail to parse, noting the incident in the log. If in addition -\syntax@_errors@_to\ is set to a verifiable address, a message is sent to it -whenever a broken address is skipped. It is usually appropriate to set -\syntax@_errors@_to\ to the same address as \errors@_to\. - - -.section Re-expansion of mailing lists -.index mailing lists||re-expansion of -Exim remembers every individual address to which a message has been delivered, -in order to avoid duplication, but it normally stores only the original -recipient addresses with a message. If all the deliveries to a mailing list -cannot be done at the first attempt, the mailing list is re-expanded when the -delivery is next tried. This means that alterations to the list are taken into -account at each delivery attempt, so addresses that have been added to -the list since the message arrived will therefore receive a copy of the -message, even though it pre-dates their subscription. - -If this behaviour is felt to be undesirable, the \one@_time\ option can be set -on the \%redirect%\ router. If this is done, any addresses generated by the -router that fail to deliver at the first attempt are added to the message as -`top level' addresses, and the parent address that generated them is marked -`delivered'. Thus, expansion of the mailing list does not happen again at the -subsequent delivery attempts. The disadvantage of this is that if any of the -failing addresses are incorrect, correcting them in the file has no effect on -pre-existing messages. - -The original top-level address is remembered with each of the generated -addresses, and is output in any log messages. However, any intermediate parent -addresses are not recorded. This makes a difference to the log only if the -\all@_parents\ selector is set, but for mailing lists there is normally only -one level of expansion anyway. - - -.section Closed mailing lists -.index mailing lists||closed -The examples so far have assumed open mailing lists, to which anybody may -send mail. It is also possible to set up closed lists, where mail is accepted -from specified senders only. This is done by making use of the generic -\senders\ option to restrict the router that handles the list. - -The following example uses the same file as a list of recipients and as a list -of permitted senders. It requires three routers: -.display asis -lists_request: - driver = redirect - domains = lists.example - local_part_suffix = -request - file = /usr/lists/$local_part$local_part_suffix - no_more - -lists_post: - driver = redirect - domains = lists.example - senders = ${if exists {/usr/lists/$local_part}\ - {lsearch;/usr/lists/$local_part}{*}} - file = /usr/lists/$local_part - forbid_pipe - forbid_file - errors_to = $local_part-request@lists.example - no_more - -lists_closed: - driver = redirect - domains = lists.example - allow_fail - data = :fail: $local_part@lists.example is a closed mailing list -.endd -All three routers have the same \domains\ setting, so for any other domains, -they are all skipped. The first router runs only if the local part ends in -\@-request\. It handles messages to the list manager(s) by means of an open -mailing list. - -The second router runs only if the \senders\ precondition is satisfied. It -checks for the existence of a list that corresponds to the local part, and then -checks that the sender is on the list by means of a linear search. It is -necessary to check for the existence of the file before trying to search it, -because otherwise Exim thinks there is a configuration error. If the file does -not exist, the expansion of \senders\ is $*$, which matches all senders. This -means that the router runs, but because there is no list, declines, and -\no@_more\ ensures that no further routers are run. The address fails with an -`unrouteable address' error. - -The third router runs only if the second router is skipped, which happens when -a mailing list exists, but the sender is not on it. This router forcibly fails -the address, giving a suitable error message. - - - -.section Virtual domains -.rset SECTvirtualdomains "~~chapter.~~section" -.index virtual domains -.index domain||virtual -The phrase \*virtual domain*\ is unfortunately used with two rather different -meanings: -.numberpars $. -A domain for which there are no real mailboxes; all valid local parts are -aliases for other email addresses. Common examples are organizational -top-level domains and `vanity' domains. -.nextp -One of a number of independent domains that are all handled by the same host, -with mailboxes on that host, but where the mailbox owners do not necessarily -have login accounts on that host. -.endp -The first usage is probably more common, and does seem more `virtual' than the -second. This kind of domain can be handled in Exim with a straightforward -aliasing router. One approach is to create a separate alias file for each -virtual domain. Exim can test for the existence of the alias file to determine -whether the domain exists. The \%dsearch%\ lookup type is useful here, leading -to a router of this form: -.display asis -virtual: - driver = redirect - domains = dsearch;/etc/mail/virtual - data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} - no_more -.endd -The \domains\ option specifies that the router is to be skipped, unless there -is a file in the \(/etc/mail/virtual)\ directory whose name is the same as the -domain that is being processed. When the router runs, it looks up the local -part in the file to find a new address (or list of addresses). The \no@_more\ -setting ensures that if the lookup fails (leading to \data\ being an empty -string), Exim gives up on the address without trying any subsequent routers. - -This one router can handle all the virtual domains because the alias file names -follow a fixed pattern. Permissions can be arranged so that appropriate people -can edit the different alias files. A successful aliasing operation results in -a new envelope recipient address, which is then routed from scratch. - -The other kind of `virtual' domain can also be handled in a straightforward -way. One approach is to create a file for each domain containing a list of -valid local parts, and use it in a router like this: -.display asis -my_domains: - driver = accept - domains = dsearch;/etc/mail/domains - local_parts = lsearch;/etc/mail/domains/$domain - transport = my_mailboxes -.endd -The address is accepted if there is a file for the domain, and the local part -can be found in the file. The \domains\ option is used to check for the file's -existence because \domains\ is tested before the \local@_parts\ option (see -section ~~SECTrouprecon). You can't use \require@_files\, because that option -is tested after \local@_parts\. The transport is as follows: -.display asis -my_mailboxes: - driver = appendfile - file = /var/mail/$domain/$local_part - user = mail -.endd -This uses a directory of mailboxes for each domain. The \user\ setting is -required, to specify which uid is to be used for writing to the mailboxes. - -The configuration shown here is just one example of how you might support this -requirement. There are many other ways this kind of configuration can be set -up, for example, by using a database instead of separate files to hold all the -information about the domains. - - -.section Multiple user mailboxes -.rset SECTmulbox "~~chapter.~~section" -.index multiple mailboxes -.index mailbox||multiple -.index local part||prefix -.index local part||suffix -Heavy email users often want to operate with multiple mailboxes, into which -incoming mail is automatically sorted. A popular way of handling this is to -allow users to use multiple sender addresses, so that replies can easily be -identified. Users are permitted to add prefixes or suffixes to their local -parts for this purpose. The wildcard facility of the generic router options -\local@_part@_prefix\ and \local@_part@_suffix\ can be used for this. For -example, consider this router: -.display asis -userforward: - driver = redirect - check_local_user - file = $home/.forward - local_part_suffix = -* - local_part_suffix_optional - allow_filter -.endd -It runs a user's \(.forward)\ file for all local parts of the form -\*username-$*$*\. Within the filter file the user can distinguish different -cases by testing the variable \$local@_part@_suffix$\. For example: -.display asis -if $local_part_suffix contains -special then - save /home/$local_part/Mail/special -endif -.endd -If the filter file does not exist, or does not deal with such addresses, they -fall through to subsequent routers, and, assuming no subsequent use of the -\local@_part@_suffix\ option is made, they presumably fail. Thus, users have -control over which suffixes are valid. - -Alternatively, a suffix can be used to trigger the use of a different -\(.forward)\ file -- which is the way a similar facility is implemented in -another MTA: -.display asis -userforward: - driver = redirect - check_local_user - file = $home/.forward$local_part_suffix - local_part_suffix = -* - local_part_suffix_optional - allow_filter -.endd -If there is no suffix, \(.forward)\ is used; if the suffix is \*-special*\, for -example, \(.forward-special)\ is used. Once again, if the appropriate file -does not exist, or does not deal with the address, it is passed on to -subsequent routers, which could, if required, look for an unqualified -\(.forward)\ file to use as a default. - - -.section Simplified vacation processing -.index vacation processing -The traditional way of running the \*vacation*\ program is for a user to set up -a pipe command in a \(.forward)\ file -(see section ~~SECTspecitredli for syntax details). -This is prone to error by inexperienced users. There are two features of Exim -that can be used to make this process simpler for users: -.numberpars $. -A local part prefix such as `vacation-' can be specified on a router which -can cause the message to be delivered directly to the \*vacation*\ program, or -alternatively can use Exim's \%autoreply%\ transport. The contents of a user's -\(.forward)\ file are then much simpler. For example: -.display asis -spqr, vacation-spqr -.endd -.nextp -The \require@_files\ generic router option can be used to trigger a -vacation delivery by checking for the existence of a certain file in the -user's home directory. The \unseen\ generic option should also be used, to -ensure that the original delivery also proceeds. In this case, all the user has -to do is to create a file called, say, \(.vacation)\, containing a vacation -message. -.endp -Another advantage of both these methods is that they both work even when the -use of arbitrary pipes by users is locked out. - - -.section Taking copies of mail -.index message||copying every -Some installations have policies that require archive copies of all messages to -be made. A single copy of each message can easily be taken by an appropriate -command in a system filter, which could, for example, use a different file for -each day's messages. - -There is also a shadow transport mechanism that can be used to take copies of -messages that are successfully delivered by local transports, one copy per -delivery. This could be used, $it{inter alia}, to implement automatic -notification of delivery by sites that insist on doing such things. - - -.section Intermittently connected hosts -.index intermittently connected hosts -It has become quite common (because it is cheaper) for hosts to connect to the -Internet periodically rather than remain connected all the time. The normal -arrangement is that mail for such hosts accumulates on a system that is -permanently connected. - -Exim was designed for use on permanently connected hosts, and so it is not -particularly well-suited to use in an intermittently connected environment. -Nevertheless there are some features that can be used. - -.section Exim on the upstream server host -It is tempting to arrange for incoming mail for the intermittently connected -host to remain on Exim's queue until the client connects. However, this -approach does not scale very well. Two different kinds of waiting message are -being mixed up in the same queue -- those that cannot be delivered because of -some temporary problem, and those that are waiting for their destination host -to connect. This makes it hard to manage the queue, as well as wasting -resources, because each queue runner scans the entire queue. - -A better approach is to separate off those messages that are waiting for an -intermittently connected host. This can be done by delivering these messages -into local files in batch SMTP, `mailstore', or other envelope-preserving -format, from where they are transmitted by other software when their -destination connects. This makes it easy to collect all the mail for one host -in a single directory, and to apply local timeout rules on a per-message basis -if required. - -On a very small scale, leaving the mail on Exim's queue can be made to work. If -you are doing this, you should configure Exim with a long retry period for the -intermittent host. For example: -.display -cheshire.wonderland.fict.example * F,5d,24h -.endd -This stops a lot of failed delivery attempts from occurring, but Exim remembers -which messages it has queued up for that host. Once the intermittent host comes -online, forcing delivery of one message (either by using the \-M-\ or \-R-\ -options, or by using the \\ETRN\\ SMTP command (see section ~~SECTETRN) -causes all the queued up messages to be delivered, often down a single SMTP -connection. While the host remains connected, any new messages get delivered -immediately. - -If the connecting hosts do not have fixed IP addresses, that is, if a host is -issued with a different IP address each time it connects, Exim's retry -mechanisms on the holding host get confused, because the IP address is normally -used as part of the key string for holding retry information. This can be -avoided by unsetting \retry__include__ip__address\ on the \%smtp%\ transport. -Since this has disadvantages for permanently connected hosts, it is best to -arrange a separate transport for the intermittently connected ones. - - -.section Exim on the intermittently connected client host -The value of \smtp@_accept@_queue@_per@_connection\ should probably be -increased, or even set to zero (that is, disabled) on the intermittently -connected host, so that all incoming messages down a single connection get -delivered immediately. - -.index SMTP||passed connection -.index SMTP||multiple deliveries -.index multiple SMTP deliveries -Mail waiting to be sent from an intermittently connected host will probably -not have been routed, because without a connection DNS lookups are not -possible. This means that if a normal queue run is done at connection time, -each message is likely to be sent in a separate SMTP session. This can be -avoided by starting the queue run with a command line option beginning with -\-qq-\ instead of \-q-\. In this case, the queue is scanned twice. In the first -pass, routing is done but no deliveries take place. The second pass is a normal -queue run; since all the messages have been previously routed, those destined -for the same host are likely to get sent as multiple deliveries in a single -SMTP connection. - - - -. -. -. -. -. ============================================================================ -.chapter Using Exim as a non-queueing client -.set runningfoot "non-queueing client" -.rset CHAPnonqueueing "~~chapter" -.index client, non-queueing -.index smart host||queueing, suppressing -.em -On a personal computer, it is a common requirement for all -email to be sent to a `smart host'. There are plenty of MUAs that can be -configured to operate that way, for all the popular operating systems. -However, there are some MUAs for Unix-like systems that cannot be so -configured: they submit messages using the command line interface of -\(/usr/sbin/sendmail)\. Furthermore, utility programs such as \*cron*\ submit -messages this way. - -If the personal computer runs continuously, there is no problem, because it can -run a conventional MTA that handles delivery to the smart host, and deal with -any delays via its queueing mechanism. However, if the computer does not run -continuously or runs different operating systems at different times, queueing -email is not desirable. - -There is therefore a requirement for something that can provide the -\(/usr/sbin/sendmail)\ interface but deliver messages to a smart host without -any queueing or retrying facilities. Furthermore, the delivery to the smart -host should be synchronous, so that if it fails, the sending MUA is immediately -informed. In other words, we want something that extends an MUA that submits -to a local MTA via the command line so that it behaves like one that submits -to a remote smart host using TCP/SMTP. - -There are a number of applications (for example, there is one called \*ssmtp*\) -that do this job. However, people have found them to be lacking in various -ways. For instance, you might want to allow aliasing and forwarding to be done -before sending a message to the smart host. - -Exim already had the necessary infrastructure for doing this job. Just a few -tweaks were needed to make it behave as required, though it is somewhat of an -overkill to use a fully-featured MTA for this purpose. - -.index \mua@_wrapper\ -There is a Boolean global option called \mua@_wrapper\, defaulting false. -Setting \mua@_wrapper\ true causes Exim to run in a special mode where it -assumes that it is being used to `wrap' a command-line MUA in the manner -just described. As well as setting \mua@_wrapper\, you also need to provide a -compatible router and transport configuration. Typically there will be just one -router and one transport, sending everything to a smart host. - -When run in MUA wrapping mode, the behaviour of Exim changes in the -following ways: -.numberpars alpha -A daemon cannot be run, nor will Exim accept incoming messages from \*inetd*\. -In other words, the only way to submit messages is via the command line. -.nextp -Each message is synchonously delivered as soon as it is received (\-odi-\ is -assumed). All queueing options (\queue@_only\, \queue@_smtp@_domains\, -\control\ in an ACL, etc.) are quietly ignored. The Exim reception process does -not finish until the delivery attempt is complete. If the delivery is -successful, a zero return code is given. -.nextp -Address redirection is permitted, but the final routing for all addresses must -be to the same remote transport, and to the same list of hosts. Furthermore, -the return address (envelope sender) must be the same for all recipients, as -must any added or deleted header lines. In other words, it must be possible to -deliver the message in a single SMTP transaction, however many recipients there -are. -.nextp -If these conditions are not met, or if routing any address results in a failure -or defer status, or if Exim is unable to deliver all the recipients -successfully to one of the smart hosts, delivery of the entire message fails. -.nextp -Because no queueing is allowed, all failures are treated as permanent; there is -no distinction between 4\*xx*\ and 5\*xx*\ SMTP response codes from the smart -host. Furthermore, because only a single yes/no response can be given to the -caller, it is not possible to deliver to some recipients and not others. If -there is an error (temporary or permanent) for any recipient, all are failed. -.nextp -If more than one smart host is listed, Exim will try another host after a -connection failure or a timeout, in the normal way. However, if this kind of -failure happens for all the hosts, the delivery fails. -.nextp -When delivery fails, an error message is written to the standard error stream -(as well as to Exim's log), and Exim exits to the caller with a return code -value 1. The message is expunged from Exim's spool files. No bounce messages -are ever generated. -.nextp -No retry data is maintained, and any retry rules are ignored. -.nextp -A number of Exim options are overridden: \deliver@_drop@_privilege\ is forced -true, \max@_rcpt\ in the smtp transport is forced to `unlimited', -\remote@_max@_parallel\ is forced to one, and fallback hosts are ignored. -.endp -The overall effect is that Exim makes a single synchronous attempt to deliver -the message, failing if there is any kind of problem. Because no local -deliveries are done and no daemon can be run, Exim does not need root -privilege. It should be possible to run it setuid to \*exim*\ instead of setuid -to \*root*\. See section ~~SECTrunexiwitpri for a general discussion about the -advantages and disadvantages of running without root privilege. -.nem - - - -. -. -. -. -. ============================================================================ -.chapter Log files -.set runningfoot "log files" -.rset CHAPlog "~~chapter" -.index log||types of -.index log||general description -Exim writes three different logs, referred to as the main log, the reject log, -and the panic log: -.numberpars $. -.index main log -The main log records the arrival of each message and each delivery in a single -line in each case. The format is as compact as possible, in an attempt to keep -down the size of log files. Two-character flag sequences make it easy to pick -out these lines. A number of other events are recorded in the main log. Some of -them are optional, in which case the \log@_selector\ option controls whether -they are included or not. A Perl script called \*eximstats*\, which does simple -analysis of main log files, is provided in the Exim distribution (see section -~~SECTmailstat). -.nextp -.index reject log -The reject log records information from messages that are rejected as a result -of a configuration option (that is, for policy reasons). -The first line of each rejection is a copy of the line that is also written to -the main log. Then, if the message's header has been read at the time the log -is written, its contents are written to this log. Only the original header -lines are available; header lines added by ACLs are not logged. You can use the -reject log to check that your policy controls are working correctly; on a busy -host this may be easier than scanning the main log for rejection messages. You -can suppress the writing of the reject log by setting \write@_rejectlog\ false. -.nextp -.index panic log -.index system log -When certain serious errors occur, Exim writes entries to its panic log. If the -error is sufficiently disastrous, Exim bombs out afterwards. Panic log entries -are usually written to the main log as well, but can get lost amid the mass of -other entries. The panic log should be empty under normal circumstances. It is -therefore a good idea to check it (or to have a \*cron*\ script check it) -regularly, in order to become aware of any problems. When Exim cannot open its -panic log, it tries as a last resort to write to the system log (syslog). This -is opened with LOG@_PID+LOG@_CONS and the facility code of LOG@_MAIL. The -message itself is written at priority LOG@_CRIT. -.endp -Every log line starts with a timestamp, in the format shown in this example: -.display asis -2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed by QUIT -.endd -By default, the timestamps are in the local timezone. There are two -ways of changing this: -.numberpars $. -You can set the \timezone\ option to a different time zone; in particular, if -you set -.display asis -timezone = UTC -.endd -the timestamps will be in UTC (aka GMT). -.nextp -If you set \log@_timezone\ true, the time zone is added to the timestamp, for -example: -.display asis -2003-04-25 11:17:07 +0100 Start queue run: pid=12762 -.endd -.endp - - - -.section Where the logs are written -.rset SECTwhelogwri "~~chapter.~~section" -.index log||destination -.index log||to file -.index log||to syslog -.index syslog -The logs may be written to local files, or to syslog, or both. However, it -should be noted that many syslog implementations use UDP as a transport, and -are therefore unreliable in the sense that messages are not guaranteed to -arrive at the loghost, nor is the ordering of messages necessarily maintained. -It has also been reported that on large log files (tens of megabytes) you may -need to tweak syslog to prevent it syncing the file with each write -- on Linux -this has been seen to make syslog take 90% plus of CPU time. - -The destination for Exim's logs is configured by setting \\LOG@_FILE@_PATH\\ in -\(Local/Makefile)\ or by setting \log@_file@_path\ in the run time -configuration. This latter string is expanded, so it can contain, for example, -references to the host name: -.display asis -log_file_path = /var/log/$primary_hostname/exim_%slog -.endd -It is generally advisable, however, to set the string in \(Local/Makefile)\ -rather than at run time, because then the setting is available right from the -start of Exim's execution. Otherwise, if there's something it wants to log -before it has read the configuration file (for example, an error in the -configuration file) it will not use the path you want, and may not be able to -log at all. - -The value of \\LOG@_FILE@_PATH\\ or \log@_file@_path\ is a colon-separated -list, currently limited to at most two items. This is one option where the -facility for changing a list separator may not be used. The list must always be -colon-separated. If an item in the list is `syslog' then syslog is used; -otherwise the item must either be an absolute path, containing \"%s"\ at the -point where `main', `reject', or `panic' is to be inserted, or be empty, -implying the use of a default path. - -When Exim encounters an empty item in the list, it searches the list defined by -\\LOG@_FILE@_PATH\\, and uses the first item it finds that is neither empty nor -`syslog'. This means that an empty item in \log@_file@_path\ can be used to -mean `use the path specified at build time'. It no such item exists, log files -are written in the \(log)\ subdirectory of the spool directory. This is -equivalent to the setting: -.display asis -log_file_path = $spool_directory/log/%slog -.endd -If you do not specify anything at build time or run time, that is where the -logs are written. - -A log file path may also contain \"%D"\ if datestamped log file names are in -use -- see section ~~SECTdatlogfil below. - -Here are some examples of possible settings: -.display -.tabs 42 -LOG@_FILE@_PATH=syslog $t $rm{syslog only} -LOG@_FILE@_PATH=:syslog $t $rm{syslog and default path} -LOG@_FILE@_PATH=syslog : /usr/log/exim@_%s $t $rm{syslog and specified path} -LOG@_FILE@_PATH=/usr/log/exim@_%s $t $rm{specified path only} -.endd -If there are more than two paths in the list, the first is used and a panic -error is logged. - - -.section Logging to local files that are periodically `cycled' -.index log||cycling local files -.index cycling logs -.index \*exicyclog*\ -.index log||local files, writing to -Some operating systems provide centralized and standardised methods for cycling -log files. For those that do not, a utility script called \*exicyclog*\ is -provided (see section ~~SECTcyclogfil). This renames and compresses the main -and reject logs each time it is called. The maximum number of old logs to keep -can be set. It is suggested this script is run as a daily \*cron*\ job. - -An Exim delivery process opens the main log when it first needs to write to it, -and it keeps the file open in case subsequent entries are required -- for -example, if a number of different deliveries are being done for the same -message. However, remote SMTP deliveries can take a long time, and this means -that the file may be kept open long after it is renamed if \*exicyclog*\ or -something similar is being used to rename log files on a regular basis. To -ensure that a switch of log files is noticed as soon as possible, Exim calls -\*stat()*\ on the main log's name before reusing an open file, and if the file -does not exist, or its inode has changed, the old file is closed and Exim -tries to open the main log from scratch. Thus, an old log file may remain open -for quite some time, but no Exim processes should write to it once it has been -renamed. - - -.section Datestamped log files -.rset SECTdatlogfil "~~chapter.~~section" -.index log||datestamped files -Instead of cycling the main and reject log files by renaming them -periodically, some sites like to use files whose names contain a datestamp, -for example, \(mainlog-20031225)\. The datestamp is in the form \(yyyymmdd)\. -Exim has support for this way of working. It is enabled by setting the -\log@_file@_path\ option to a path that includes \"%D"\ at the point where the -datestamp is required. For example: -.display asis -log_file_path = /var/spool/exim/log/%slog-%D -log_file_path = /var/log/exim-%s-%D.log -log_file_path = /var/spool/exim/log/%D-%slog -.endd -As before, \"%s"\ is replaced by `main' or `reject'; the following are examples -of names generated by the above examples: -.display asis -/var/spool/exim/log/mainlog-20021225 -/var/log/exim-reject-20021225.log -/var/spool/exim/log/20021225-mainlog -.endd -When this form of log file is specified, Exim automatically switches to new -files at midnight. It does not make any attempt to compress old logs; you -will need to write your own script if you require this. You should not -run \*exicyclog*\ with this form of logging. - -The location of the panic log is also determined by \log@_file@_path\, but it -is not datestamped, because rotation of the panic log does not make sense. -When generating the name of the panic log, \"%D"\ is removed from the string. -In addition, if it immediately follows a slash, a following non-alphanumeric -character is removed; otherwise a preceding non-alphanumeric character is -removed. Thus, the three examples above would give these panic log names: -.display asis -/var/spool/exim/log/paniclog -/var/log/exim-panic.log -/var/spool/exim/log/paniclog -.endd - - -.section Logging to syslog -.index log||syslog, writing to -The use of syslog does not change what Exim logs or the format of its messages, -except in one respect. If \syslog@_timestamp\ is set false, the timestamps on -Exim's log lines are omitted when these lines are sent to syslog. Apart from -that, the same strings are written to syslog as to log files. The syslog -`facility' is set to \\LOG@_MAIL\\, and the program name to `exim' -by default, but you can change these by setting the \syslog@_facility\ and -\syslog@_processname\ options, respectively. If Exim was compiled with -\\SYSLOG@_LOG@_PID\\ set in \(Local/Makefile)\ (this is the default in -\(src/EDITME)\), then, on systems that permit it (all except ULTRIX), the -\\LOG@_PID\\ flag is set so that the \*syslog()*\ call adds the pid as well as -the time and host name to each line. -The three log streams are mapped onto syslog priorities as follows: -.numberpars " " -\*mainlog*\ is mapped to \\LOG@_INFO\\ -.nextp -\*rejectlog*\ is mapped to \\LOG@_NOTICE\\ -.nextp -\*paniclog*\ is mapped to \\LOG@_ALERT\\ -.endp -Many log lines are written to both \*mainlog*\ and \*rejectlog*\, and some are -written to both \*mainlog*\ and \*paniclog*\, so there will be duplicates if -these are routed by syslog to the same place. You can suppress this duplication -by setting \syslog@_duplication\ false. - -Exim's log lines can sometimes be very long, and some of its \*rejectlog*\ -entries contain multiple lines when headers are included. To cope with both -these cases, entries written to syslog are split into separate \*syslog()*\ -calls at each internal newline, and also after a maximum of -870 data characters. (This allows for a total syslog line length of 1024, when -additions such as timestamps are added.) If you are running a syslog -replacement that can handle lines longer than the 1024 characters allowed by -RFC 3164, you should set -.display asis -SYSLOG_LONG_LINES=yes -.endd -in \(Local/Makefile)\ before building Exim. That stops Exim from splitting long -lines, but it still splits at internal newlines in \*reject*\ log entries. - -To make it easy to re-assemble split lines later, each component of a split -entry starts with a string of the form `[<<n>>/<<m>>]' or `[<<n>>@\<<m>>]' -where <<n>> is the component number and <<m>> is the total number of components -in the entry. The / delimiter is used when the line was split because it was -too long; if it was split because of an internal newline, the @\ delimiter is -used. For example, supposing the length limit to be 70 instead of 1000, the -following would be the result of a typical rejection message to \*mainlog*\ -(LOG@_INFO), each line in addition being preceded by the time, host name, and -pid as added by syslog: -.display -.indent 0 -$smc{[1/3] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): -[2/3] syntax error in 'From' header when scanning for sender: missing or ma -[3/3] lformed local part in "<>" (envelope sender is <ph10@@cam.example>)} -.endd -The same error might cause the following lines to be written to `rejectlog' -(LOG@_NOTICE): -.display flow -.indent 0 -$smc{[1/14] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from [127.0.0.1] (ph10): -[2/14] syntax error in 'From' header when scanning for sender: missing or ma -[3@\14] lformed local part in "@<@>" (envelope sender is <ph10@@cam.example>) -[4@\14] Recipients: ph10@@some.domain.cam.example -[5@\14] P Received: from [127.0.0.1] (ident=ph10) -[6@\14] by xxxxx.cam.example with smtp (Exim 4.00) -[7@\14] id 16RdAL-0006pc-00 -[8@\14] for ph10@@cam.example; Mon, 16 Sep 2002 16:09:43 +0100 -[9@\14] F From: @<@> -[10@\14] Subject: this is a test header -[11@\14] X-something: this is another header -[12@\14] I Message-Id: <E16RdAL-0006pc-00@@xxxxx.cam.example> -[13@\14] B Bcc: -[14/14] Date: Mon, 16 Sep 2002 16:09:43 +0100} -.endd -Log lines that are neither too long nor contain newlines are written to syslog -without modification. - -If only syslog is being used, the Exim monitor is unable to provide a log tail -display, unless syslog is routing \*mainlog*\ to a file on the local host and -the environment variable \\EXIMON@_LOG@_FILE@_PATH\\ is set to tell the monitor -where it is. - - -.section Log line flags -One line is written to the main log for each message received, and for each -successful, unsuccessful, and delayed delivery. These lines can readily be -picked out by the distinctive two-character flags that immediately follow the -timestamp. The flags are: -.display -.tabs 6 -<= $t $rm{message arrival} -=> $t $rm{normal message delivery} --> $t $rm{additional address in same delivery} -*> $t $rm{delivery suppressed by \-N-\} -** $t $rm{delivery failed; address bounced} -== $t $rm{delivery deferred; temporary problem} -.endd - - -.section Logging message reception -.index log||reception line -The format of the single-line entry in the main log that is written for every -message received is shown in the basic example below, which is split over -several lines in order to fit it on the page: -.display -.indent 0 -2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@@dwarf.fict.example - H=mailer.fict.example [192.168.123.123] U=exim - P=smtp S=5678 id=<<incoming message id>> -.endd -The address immediately following `<=' is the envelope sender address. A bounce -message is shown with the sender address `<>', and if it is locally generated, -this is followed by an item of the form -.display -R=<<message id>> -.endd -which is a reference to the message that caused the bounce to be sent. - -.index \\HELO\\ -.index \\EHLO\\ -For messages from other hosts, the H and U fields identify the remote host and -record the RFC 1413 identity of the user that sent the message, if one was -received. The number given in square brackets is the IP address of the sending -host. If there is a single, unparenthesized host name in the H field, as -above, it has been verified to correspond to the IP address (see the -\host@_lookup\ option). If the name is in parentheses, it was the name quoted -by the remote host in the SMTP \\HELO\\ or \\EHLO\\ command, and has not been -verified. If verification yields a different name to that given for \\HELO\\ or -\\EHLO\\, the verified name appears first, followed by the \\HELO\\ or \\EHLO\\ -name in parentheses. - -Misconfigured hosts (and mail forgers) sometimes put an IP address, with or -without brackets, in the \\HELO\\ or \\EHLO\\ command, leading to entries in -the log containing text like these examples: -.display -H=(10.21.32.43) [192.168.8.34] -H=([10.21.32.43]) [192.168.8.34] -.endd -This can be confusing. Only the final address in square brackets can be relied -on. - -For locally generated messages (that is, messages not received over TCP/IP), -the H field is omitted, and the U field contains the login name of the caller -of Exim. - -.index authentication||logging -.index \\AUTH\\||logging -For all messages, the P field specifies the protocol used to receive the -message. This is set to -.em -`esmtpa' -.nem -for messages received from hosts that have authenticated themselves using the -SMTP \\AUTH\\ command. In this case there is an additional item A= followed by -the name of the authenticator that was used. If an authenticated identification -was set up by the authenticator's \server@_set@_id\ option, this is logged too, -separated by a colon from the authenticator name. - -The id field records the existing message id, if present. -.index size||of message -The size of the received message is given by the S field. When the message is -delivered, headers may get removed or added, so that the size of delivered -copies of the message may not correspond with this value (and indeed may be -different to each other). - -The \log@_selector\ option can be used to request the logging of additional -data when a message is received. See section ~~SECTlogselector below. - - -.section Logging deliveries -.index log||delivery line -The format of the single-line entry in the main log that is written for every -delivery is shown in one of the examples below, for local and remote deliveries, -respectively. Each example has been split into two lines in order to fit -it on the page: -.display -.indent 0 -2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv <marv@@hitch.fict.example> - R=localuser T=local@_delivery -2002-10-31 09:00:10 16ZCW1-0005MB-00 => monk@@holistic.fict.example - R=dnslookup T=remote@_smtp H=holistic.fict.example [192.168.234.234] -.endd -For ordinary local deliveries, the original address is given in angle brackets -after the final delivery address, which might be a pipe or a file. If -intermediate address(es) exist between the original and the final address, the -last of these is given in parentheses after the final address. The R and T -fields record the router and transport that were used to process the address. - -If a shadow transport was run after a successful local delivery, the log line -for the successful delivery has an item added on the end, of the form -.display -ST=<<shadow transport name>> -.endd -If the shadow transport did not succeed, the error message is put in -parentheses afterwards. - -When more than one address is included in a single delivery (for example, two -SMTP \\RCPT\\ commands in one transaction) the second and subsequent -addresses are flagged with `$tt{@-@>}' instead of `$tt{@=@>}'. When two or more -messages are delivered down a single SMTP connection, an asterisk follows the -IP address in the log lines for the second and subsequent messages. - -The generation of a reply message by a filter file gets logged as a `delivery' -to the addressee, preceded by `>'. - -The \log@_selector\ option can be used to request the logging of additional -data when a message is delivered. See section ~~SECTlogselector below. - - -.section Discarded deliveries -.index discarded messages -.index message||discarded -.index delivery||discarded, logging -When a message is discarded as a result of the command `seen finish' being -obeyed in a filter file which generates no deliveries, a log entry of the form -.display -2002-12-10 00:50:49 16auJc-0001UB-00 => discarded - <low.club@@bridge.example> R=userforward -.endd -is written, to record why no deliveries are logged. When a message is discarded -because it is aliased to `:blackhole:' the log line is like this: -.display asis -1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: - <hole@nowhere.example> R=blackhole_router -.endd - - -.section Deferred deliveries -When a delivery is deferred, a line of the following form is logged: -.display -.indent 0 -2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@@endrest.example - R=dnslookup T=smtp defer (146): Connection refused -.endd -In the case of remote deliveries, the error is the one that was given for the -last IP address that was tried. Details of individual SMTP failures are also -written to the log, so the above line would be preceded by something like -.display -.indent 0 -2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to - mail1.endrest.example [192.168.239.239]: Connection refused -.endd -When a deferred address is skipped because its retry time has not been reached, -a message is written to the log, but this can be suppressed by setting an -appropriate value in \log@_selector\. - - -.section Delivery failures -.index delivery||failure, logging -If a delivery fails because an address cannot be routed, a line of the -following form is logged: -.display asis -.indent 0 -1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example - <jim@trek99.example>: unknown mail domain -.endd -If a delivery fails at transport time, the router and transport are shown, and -the response from the remote host is included, as in this example: -.display asis -.indent 0 -2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example R=dnslookup -.newline - T=remote_smtp: SMTP error from remote mailer after pipelined -.newline - RCPT TO:<ace400@pb.example>: host pbmail3.py.example - [192.168.63.111]: 553 5.3.0 <ace400@pb.example>... - Addressee unknown -.endd -The word `pipelined' indicates that the SMTP \\PIPELINING\\ extension was being -used. See \hosts@_avoid@_esmtp\ in the \%smtp%\ transport for a way of -disabling \\PIPELINING\\. - -The log lines for all forms of delivery failure are flagged with \"**"\. - - -.section Fake deliveries -.index delivery||fake, logging -If a delivery does not actually take place because the \-N-\ option has been -used to suppress it, a normal delivery line is written to the log, except that -`=>' is replaced by `$*$>'. - - -.section Completion -A line of the form -.display -2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed -.endd -is written to the main log when a message is about to be removed from the spool -at the end of its processing. - - - -.section Summary of Fields in Log Lines -.index log||summary of fields -A summary of the field identifiers that are used in log lines is shown in -the following table: -.display flow -.tabs 8 -A $t $rm{authenticator name (and optional id)} -C $t $rm{SMTP confirmation on delivery} -CV $t $rm{certificate verification status} -DN $t $rm{distinguished name from peer certificate} -.newline -.em -DT $t $rm{on \"=>"\ lines: time taken for a delivery} -.nem -.newline -F $t $rm{sender address (on delivery lines)} -H $t $rm{host name and IP address} -I $t $rm{local interface used} -id $t $rm{message id for incoming message} -P $t $rm{on \"<="\ lines: protocol used} -.newline -.em - $t $rm{on \"=>"\ and \"**"\ lines: return path} -QT $t $rm{on \"=>"\ lines: time spent on queue so far} - $t $rm{on `Completed' lines: time spent on queue} -.nem -.newline -R $t $rm{on \"<="\ lines: reference for local bounce} -.newline -.em - $t $rm{on \"=>"\ \"**"\ and \"=="\ lines: router name} -.nem -.newline -S $t $rm{size of message} -ST $t $rm{shadow transport name} -T $t $rm{on \"<="\ lines: message subject (topic)} -.newline -.em - $t $rm{on \"=>"\ \"**"\ and \"=="\ lines: transport name} -.nem -.newline -U $t $rm{local user or RFC 1413 identity} -X $t $rm{TLS cipher suite} -.endd - - -.section Other log entries -Various other types of log entry are written from time to time. Most should be -self-explanatory. Among the more common are: -.numberpars $. -.index retry||time not reached -\*retry time not reached*\##An address previously suffered a temporary error -during routing or local delivery, and the time to retry has not yet arrived. -This message is not written to an individual message log file unless it happens -during the first delivery attempt. -.nextp -\*retry time not reached for any host*\##An address previously suffered -temporary errors during remote delivery, and the retry time has not yet arrived -for any of the hosts to which it is routed. -.nextp -.index spool directory||file locked -\*spool file locked*\##An attempt to deliver a message cannot proceed because -some other Exim process is already working on the message. This can be quite -common if queue running processes are started at frequent intervals. The -\*exiwhat*\ utility script can be used to find out what Exim processes are -doing. -.nextp -.index error||ignored -\*error ignored*\##There are several circumstances that give rise to this -message: -.numberpars " " -Exim failed to deliver a bounce message whose age was greater than -\ignore__bounce__errors__after\. The bounce was discarded. -.nextp -A filter file set up a delivery using the `noerror' option, and the delivery -failed. The delivery was discarded. -.nextp -A delivery set up by a router configured with -.display asis -errors_to = <> -.endd -failed. The delivery was discarded. -.endp -.endp - - - -.section Reducing or increasing what is logged -.rset SECTlogselector "~~chapter.~~section" -.index log||selectors -By setting the \log@_selector\ global option, you can disable some of Exim's -default logging, or you can request additional logging. The value of -\log@_selector\ is made up of names preceded by plus or minus characters. For -example: -.display asis -log_selector = +arguments -retry_defer -.endd -The list of optional log items is in the following table, with the default -selection marked by asterisks: -.display flow -.tabs 32 - address@_rewrite $t $rm{address rewriting} - all@_parents $t $rm{all parents in => lines} - arguments $t $rm{command line arguments} -*connection@_reject $t $rm{connection rejections} -*delay@_delivery $t $rm{immediate delivery delayed} - deliver@_time $t $rm{time taken to perform delivery} - delivery@_size $t $rm{add S=nnn to => lines} -*dnslist@_defer $t $rm{defers of DNS list (aka RBL) lookups} -*etrn $t $rm{ETRN commands} -*host@_lookup@_failed $t $rm{as it says} - ident@_timeout $t $rm{timeout for ident connection} - incoming@_interface $t $rm{incoming interface on <= lines} - incoming@_port $t $rm{incoming port on <= lines} -*lost@_incoming@_connection $t $rm{as it says (includes timeouts)} - outgoing@_port $t $rm{add remote port to => lines} -*queue@_run $t $rm{start and end queue runs} -.newline -.em - queue@_time $t $rm{time on queue for one recipient} - queue@_time@_overall $t $rm{time on queue for whole message} -.nem -.newline - received@_recipients $t $rm{recipients on <= lines} - received@_sender $t $rm{sender on <= lines} -*rejected@_header $t $rm{header contents on reject log} -*retry@_defer $t $rm{`retry time not reached'} - return@_path@_on@_delivery $t $rm{put return path on => and ** lines} - sender@_on@_delivery $t $rm{add sender to => lines} -*size@_reject $t $rm{rejection because too big} -*skip@_delivery $t $rm{delivery skipped in a queue run} - smtp@_confirmation $t $rm{SMTP confirmation on => lines} - smtp@_connection $t $rm{SMTP connections} - smtp@_incomplete@_transaction $t $rm{incomplete SMTP transactions} - smtp@_protocol@_error $t $rm{SMTP protocol errors} - smtp@_syntax@_error $t $rm{SMTP syntax errors} - subject $t $rm{contents of ::Subject:: on <= lines} - tls@_certificate@_verified $t $rm{certificate verification status} -*tls@_cipher $t $rm{TLS cipher suite on <= and => lines} - tls@_peerdn $t $rm{TLS peer DN on <= and => lines} - - all $t $rm{all of the above} -.endd -More details on each of these items follows: -.numberpars $. -.index log||rewriting -.index rewriting||logging -\address@_rewrite\: This applies both to global rewrites and per-transport -rewrites, -but not to rewrites in filters run as an unprivileged user (because such users -cannot access the log). -.nextp -.index log||full parentage -\all@_parents\: Normally only the original and final addresses are logged on -delivery lines; with this selector, intermediate parents are given in -parentheses between them. -.nextp -.index log||Exim arguments -.index Exim arguments, logging -\arguments\: This causes Exim to write the arguments with which it was called -to the main log, -preceded by the current working directory. -This is a debugging feature, added to make it easier to find out how certain -MUAs call \(/usr/sbin/sendmail)\. The logging does not happen if Exim has given -up root privilege because it was called with the \-C-\ or \-D-\ options. -Arguments that are empty or that contain whitespace are quoted. Non-printing -characters are shown as escape sequences. -This facility cannot log unrecognized arguments, because the arguments are -checked before the configuration file is read. The only way to log such cases -is to interpose a script such as \(util/logargs.sh)\ between the caller and -Exim. -.nextp -.index log||connection rejections -\connection@_reject\: A log entry is written whenever an incoming SMTP -connection is rejected, for whatever reason. -.nextp -.index log||delayed delivery -.index delayed delivery, logging -\delay@_delivery\: A log entry is written whenever a delivery process is not -started for an incoming message because the load is too high or too many -messages were received on one connection. Logging does not occur if no delivery -process is started because \queue@_only\ is set or \-odq-\ was used. -.nextp -.index log||delivery duration -\deliver@_time\: For each delivery, the amount of real time it has taken to -perform the actual delivery is logged as DT=<<time>>, for example, \"DT=1s"\. -.nextp -.index log||message size on delivery -.index size||of message -\delivery@_size\: For each delivery, the size of message delivered is added to -the `=>' line, tagged with S=. -.nextp -.index log||dnslist defer -.index DNS list||logging defer -.index black list (DNS) -\dnslist@_defer\: A log entry is written if an attempt to look up a host in a -DNS black list suffers a temporary error. -.nextp -.index log||ETRN commands -.index \\ETRN\\||logging -\etrn\: Every legal ETRN command that is received is logged, before the ACL is -run to determine whether or not it is actually accepted. An invalid ETRN -command, or one received within a message transaction is not logged by this -selector (see \smtp@_syntax@_error\ and \smtp@_protocol@_error\). -.nextp -.index log||host lookup failure -\host@_lookup@_failed\: When a lookup of a host's IP addresses fails to find -any addresses, or when a lookup of an IP address fails to find a host name, a -log line is written. This logging does not apply to direct DNS lookups when -routing email addresses, but it does apply to `byname' lookups. -.nextp -.index log||ident timeout -.index RFC 1413||logging timeout -\ident@_timeout\: A log line is written whenever an attempt to connect to a -client's ident port times out. -.nextp -.index log||incoming interface -.index interface||logging -\incoming@_interface\: The interface on which a message was received is added -to the `<=' line as an IP address in square brackets, tagged by I= and followed -by a colon and the port number. -The local interface and port are also added to other SMTP log -lines, for example `SMTP connection from', and to rejection lines. -.nextp -.index log||incoming remote port -.index port||logging remote -.index TCP/IP||logging incoming remote port -\incoming@_port\: The remote port number from which a message was received is -added to log entries and ::Received:: header lines, following the IP address in -square brackets, and separated from it by a colon. This is implemented by -changing the value that is put in the \$sender@_fullhost$\ and -\$sender@_rcvhost$\ variables. Recording the remote port number has become more -important with the widening use of NAT (see RFC 2505). -.nextp -.index log||dropped connection -\lost@_incoming@_connection\: A log line is written when an incoming SMTP -connection is unexpectedly dropped. -.nextp -.index log||outgoing remote port -.index port||logging outgoint remote -.index TCP/IP||logging ougtoing remote port -\outgoing@_port\: The remote port number is added to delivery log lines (those -containing => tags) following the IP address. This option is not included in -the default setting, because for most ordinary configurations, the remote port -number is always 25 (the SMTP port). -.nextp -.index log||queue run -.index queue runner||logging -\queue@_run\: The start and end of every queue run are logged. -.nextp -.index log||queue time -\queue@_time\: The amount of time the message has been in the queue on the -local host is logged as QT=<<time>> -.em -on delivery (\"=>"\) lines, for example, \"QT=3m45s"\. The clock starts when -Exim starts to receive the message, so it includes reception time as well as -the delivery time for the current address. This means that it may be longer -than the difference between the arrival and delivery log line times, because -the arrival log line is not written until the message has been successfully -received. -.nem - -.nextp -.em -\queue@_time@_overall\: The amount of time the message has been in the queue on -the local host is logged as QT=<<time>> on `Completed' lines, for -example, \"QT=3m45s"\. The clock starts when Exim starts to receive the -message, so it includes reception time as well as the total delivery time. -.nem -.nextp -.index log||recipients -\received@_recipients\: The recipients of a message are listed in the main log -as soon as the message is received. The list appears at the end of the log line -that is written when a message is received, preceded by the word `for'. The -addresses are listed after they have been qualified, but before any rewriting -has taken place. -Recipients that were discarded by an ACL for \\MAIL\\ or \\RCPT\\ do not appear -in the list. -.nextp -.index log||sender reception -\received@_sender\: The unrewritten original sender of a message is added to -the end of the log line that records the message's arrival, after the word -`from' (before the recipients if \received@_recipients\ is also set). -.nextp -.index log||header lines for rejection -\rejected@_header\: If a message's header has been received at the time a -rejection is written to the reject log, the complete header is added to the -log. Header logging can be turned off individually for messages that are -rejected by the \*local@_scan()*\ function (see section ~~SECTapiforloc). -.nextp -.index log||retry defer -\retry@_defer\: A log line is written if a delivery is deferred because a retry -time has not yet been reached. However, this `retry time not reached' message -is always omitted from individual message logs after the first delivery -attempt. -.nextp -.index log||return path -\return@_path@_on@_delivery\: The return path that is being transmitted with -the message is included in delivery and bounce lines, using the tag P=. -.em -This is omitted if no delivery actually happens, for example, if routing fails, -or if delivery is to \(/dev/null)\ or to \":blackhole:"\. -.nem -.nextp -.index log||sender on delivery -\sender@_on@_delivery\: The message's sender address is added to every delivery -and bounce line, tagged by F= (for `from'). -This is the original sender that was received with the message; it is not -necessarily the same as the outgoing return path. -.nextp -.index log||size rejection -\size@_reject\: A log line is written whenever a message is rejected because it -is too big. -.nextp -.index log||frozen messages, skipped -.index frozen messages||logging skipping -\skip@_delivery\: A log line is written whenever a message is skipped during a -queue run because it is frozen or because another process is already delivering -it. -.em -.index `spool file is locked' -The message that is written is `spool file is locked'. -.nem -.nextp -.index log||smtp confirmation -.index SMTP||logging confirmation -\smtp@_confirmation\: The response to the final `.' in the SMTP dialogue for -outgoing messages is added to delivery log lines in the form `C="<<text>>"'. A -number of MTAs (including Exim) return an identifying string in this response. -.nextp -.index log||SMTP connections -.index SMTP||logging connections -\smtp@_connection\: A log line is written whenever an SMTP connection is -established or closed, -.em -unless the connection is from a host that matches \hosts@_connection@_nolog\. -.nem -(In contrast, \lost__incoming__connection\ applies only when the closure is -unexpected.) This applies to connections from local processes that use \-bs-\ -as well as to TCP/IP connections. If a connection is dropped in the middle of a -message, a log line is always written, whether or not this selector is set, but -otherwise nothing is written at the start and end of connections unless this -selector is enabled. - -For TCP/IP connections to an Exim daemon, the current number of connections is -included in the log message for each new connection, but note that the count is -reset if the daemon is restarted. -Also, because connections are closed (and the closure is logged) in -subprocesses, the count may not include connections that have been closed but -whose termination the daemon has not yet noticed. Thus, while it is possible to -match up the opening and closing of connections in the log, the value of the -logged counts may not be entirely accurate. -.nextp -.index log||SMTP transaction, incomplete -.index SMTP||logging incomplete transactions -\smtp@_incomplete@_transaction\: When a mail transaction is aborted by -\\RSET\\, \\QUIT\\, loss of connection, or otherwise, the incident is logged, -and the message sender plus any accepted recipients are included in the log -line. This can provide evidence of dictionary attacks. -.nextp -.index log||SMTP protocol error -.index SMTP||logging protocol error -\smtp@_protocol@_error\: A log line is written for every SMTP protocol error -encountered. -Exim does not have perfect detection of all protocol errors because of -transmission delays and the use of pipelining. If \\PIPELINING\\ has been -advertised to a client, an Exim server assumes that the client will use it, and -therefore it does not count `expected' errors (for example, \\RCPT\\ received -after rejecting \\MAIL\\) as protocol errors. -.nextp -.index SMTP||logging syntax errors -.index SMTP||syntax errors, logging -.index SMTP||unknown command, logging -.index log||unknown SMTP command -.index log||SMTP syntax error -\smtp@_syntax@_error\: A log line is written for every SMTP syntax error -encountered. An unrecognized command is treated as a syntax error. For an -external connection, the host identity is given; for an internal connection -using \-bs-\ the sender identification (normally the calling user) is given. -.nextp -.index log||subject -.index subject, logging -\subject\: The subject of the message is added to the arrival log line, -preceded by `T=' (T for `topic', since S is already used for `size'). -Any MIME `words' in the subject are decoded. The \print@_topbitchars\ option -specifies whether characters with values greater than 127 should be logged -unchanged, or whether they should be rendered as escape sequences. -.nextp -.index log||certificate verification -\tls@_certificate@_verified\: An extra item is added to <= and => log lines -when TLS is in use. The item is \"CV=yes"\ if the peer's certificate was -verified, and \"CV=no"\ if not. -.nextp -.index log||TLS cipher -.index TLS||logging cipher -\tls@_cipher\: When a message is sent or received over an encrypted connection, -the cipher suite used is added to the log line, preceded by X=. -.nextp -.index log||TLS peer DN -.index TLS||logging peer DN -\tls@_peerdn\: When a message is sent or received over an encrypted connection, -and a certificate is supplied by the remote host, the peer DN is added to the -log line, preceded by DN=. -.endp - -.section Message log -.index message||log file for -.index log||message log, description of -In addition to the general log files, Exim writes a log file for each message -that it handles. The names of these per-message logs are the message ids, and -.index \(msglog)\ directory -they are kept in the \(msglog)\ sub-directory of the spool directory. Each -message log contains copies of the log lines that apply to the message. This -makes it easier to inspect the status of an individual message without having -to search the main log. A message log is deleted when processing of the message -is complete, -.index \preserve@_message@_logs\ -unless \preserve__message__logs\ is set, but this should be used only with -great care because they can fill up your disk very quickly. - -On a heavily loaded system, it may be desirable to disable the use of -per-message logs, in order to reduce disk I/O. This can be done by setting the -\message@_logs\ option false. - - - -. -. -. -. ============================================================================ -.chapter Exim utilities -.set runningfoot "utilities" -.rset CHAPutils ~~chapter -.index utilities -A number of utility scripts and programs are supplied with Exim and are -described in this chapter. There is also the Exim Monitor, which is covered in -the next chapter. The utilities described here are: - -. This duplication seems to be the only way to arrange that the cross- -. references are omitted in the Texinfo version. They look horribly ugly. - -.if ~~texinfo -.display rm -.tabs 22 -\*exiwhat*\ $t $rm{list what Exim processes are doing} -.newline -\*exiqgrep*\ $t $rm{grep the queue} -.newline -\*exiqsumm*\ $t $rm{summarize the queue} -\*exigrep*\ $t $rm{search the main log} -\*exipick*\ $t $rm{select messages on various criteria} -\*exicyclog*\ $t $rm{cycle (rotate) log files} -\*eximstats*\ $t $rm{extract statistics from the log} -\*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} -\*exim@_dbmbuild*\ $t $rm{build a DBM file} -\*exinext*\ $t $rm{extract retry information} -\*exim@_dumpdb*\ $t $rm{dump a hints database} -\*exim@_tidydb*\ $t $rm{clean up a hints database} -\*exim@_fixdb*\ $t $rm{patch a hints database} -\*exim@_lock*\ $t $rm{lock a mailbox file} -.endd -. -.else -. -.display rm -.tabs 22 -~~SECTfinoutwha \*exiwhat*\ $t $rm{list what Exim processes are doing} -~~SECTgreptheque \*exiqgrep*\ $t $rm{grep the queue} -~~SECTsumtheque \*exiqsumm*\ $t $rm{summarize the queue} -~~SECTextspeinf \*exigrep*\ $t $rm{search the main log} -~~SECTexipick \*exipick*\ $t $rm{select messages on various criteria} -~~SECTcyclogfil \*exicyclog*\ $t $rm{cycle (rotate) log files} -~~SECTmailstat \*eximstats*\ $t $rm{extract statistics from the log} -~~SECTcheckaccess \*exim@_checkaccess*\ $t $rm{check address acceptance from given IP} -~~SECTdbmbuild \*exim@_dbmbuild*\ $t $rm{build a DBM file} -~~SECTfinindret \*exinext*\ $t $rm{extract retry information} -~~SECThindatmai \*exim@_dumpdb*\ $t $rm{dump a hints database} -~~SECThindatmai \*exim@_tidydb*\ $t $rm{clean up a hints database} -~~SECThindatmai \*exim@_fixdb*\ $t $rm{patch a hints database} -~~SECTmailboxmaint \*exim@_lock*\ $t $rm{lock a mailbox file} -.endd -.fi - -.section Finding out what Exim processes are doing (exiwhat) -.rset SECTfinoutwha "~~chapter.~~section" -.index \*exiwhat*\ -.index process, querying -.index \\SIGUSR1\\ -On operating systems that can restart a system call after receiving a signal -(most modern OS), an Exim process responds to the \\SIGUSR1\\ signal by writing -a line describing what it is doing to the file \(exim-process.info)\ in the -Exim spool directory. The \*exiwhat*\ script sends the signal to all Exim -processes it can find, having first emptied the file. It then waits for one -second to allow the Exim processes to react before displaying the results. In -order to run \*exiwhat*\ successfully you have to have sufficient privilege to -send the signal to the Exim processes, so it is normally run as root. - -.em -\**Warning**\: This is not an efficient process. It is intended for occasional -use by system administrators. It is not sensible, for example, to set up a -script that sends \\SIGUSR1\\ signals to Exim processes at short intervals. -.nem - -Unfortunately, the \*ps*\ command that \*exiwhat*\ uses to find Exim processes -varies in different operating systems. Not only are different options used, -but the format of the output is different. For this reason, there are some -system configuration options that configure exactly how \*exiwhat*\ works. If it -doesn't seem to be working for you, check the following compile-time options: -.display -EXIWHAT@_PS@_CMD $rm{the command for running \*ps*\} -EXIWHAT@_PS@_ARG $rm{the argument for \*ps*\} -EXIWHAT@_EGREP@_ARG $rm{the argument for \*egrep*\ to select from \*ps*\ output} -EXIWHAT@_KILL@_ARG $rm{the argument for the \*kill*\ command} -.endd -An example of typical output from \*exiwhat*\ is -.display -.indent 0 - 164 daemon: -q1h, listening on port 25 -10483 running queue: waiting for 0tAycK-0002ij-00 (10492) -10492 delivering 0tAycK-0002ij-00 to mail.ref.example [10.19.42.42] - (editor@@ref.example) -10592 handling incoming call from [192.168.243.242] -10628 accepting a local non-SMTP message -.endd -The first number in the output line is the process number. The third line has -been split here, in order to fit it on the page. - - -.section Selective queue listing (exiqgrep) -.rset SECTgreptheque "~~chapter.~~section" -.index \*exiqgrep*\ -.index queue||grepping -This utility is a Perl script contributed by Matt Hubbard. It runs -.display asis -exim -bpu -.endd -to obtain a queue listing with undelivered recipients only, and then greps the -output to select messages that match given criteria. The following selection -options are available: - -.startoptions - -.option f <<regex>> -Match the sender address. The field that is tested is enclosed in angle -brackets, so you can test for bounce messages with -.display asis -exiqgrep -f '^<>$' -.endd - -.option r <<regex>> -Match a recipient address. The field that is tested is not enclosed in angle -brackets. - -.option s <<regex>> -Match against the size field. - -.option y <<seconds>> -Match messages that are younger than the given time. - -.option o <<seconds>> -Match messages that are older than the given time. - -.option z -Match only frozen messages. - -.option x -Match only non-frozen messages. - -.endoptions - -The following options control the format of the output: - -.startoptions - -.option c -Display only the count of matching messages. - -.option l -Long format -- display the full message information as output by Exim. This is -the default. - -.option i -Display message ids only. - -.option b -Brief format -- one line per message. - -.option R -Display messages in reverse order. - -.endoptions - -There is one more option, \-h-\, which outputs a list of options. - - -.section Summarising the queue (exiqsumm) -.rset SECTsumtheque "~~chapter.~~section" -.index \*exiqsumm*\ -.index queue||summary -The \*exiqsumm*\ utility is a Perl script which reads the output of \*exim --bp*\ and produces a summary of the messages on the queue. Thus, you use it by -running a command such as -.display asis -exim -bp | exiqsumm -.endd -The output consists of one line for each domain that has messages waiting for -it, as in the following example: -.display asis - 3 2322 74m 66m msn.com.example -.endd -Each line lists the number of -pending deliveries for a domain, their total volume, and the length of time -that the oldest and the newest messages have been waiting. Note that the number -of pending deliveries is greater than the number of messages when messages -have more than one recipient. - -A summary line is output at the end. By default the output is sorted on the -domain name, but \*exiqsumm*\ has the options \-a-\ and \-c-\, which cause the -output to be sorted by oldest message and by count of messages, respectively. - -The output of \*exim -bp*\ contains the original addresses in the message, so -this also applies to the output from \*exiqsumm*\. No domains from addresses -generated by aliasing or forwarding are included (unless the \one@_time\ option -of the \%redirect%\ router has been used to convert them into `top level' -addresses). - - - -.section Extracting specific information from the log (exigrep) -.rset SECTextspeinf "~~chapter.~~section" -.index \*exigrep*\ -.index log||extracts, grepping for -The \*exigrep*\ utility is a Perl script that searches one or more main log -files for entries that match a given pattern. When it finds a match, it -extracts all the log entries for the relevant message, not just those that -match the pattern. Thus, \*exigrep*\ can extract complete log entries for a -given message, or all mail for a given user, or for a given host, for example. - -If a matching log line is not associated with a specific message, it is always -included in \*exigrep*\'s output. -The usage is: -.display asis -exigrep [-l] [-t<n>] <pattern> [<log file>] ... -.endd -The \-t-\ argument specifies a number of seconds. It adds an additional -condition for message selection. Messages that are complete are shown only if -they spent more than <<n>> seconds on the queue. - -The \-l-\ flag means `literal', that is, treat all characters in the -pattern as standing for themselves. Otherwise the pattern must be a Perl -regular expression. The pattern match is case-insensitive. If no file names are -given on the command line, the standard input is read. - -If the location of a \*zcat*\ command is known from the definition of -\\ZCAT@_COMMAND\\ in \(Local/Makefile)\, \*exigrep*\ automatically passes any -file whose name ends in \\COMPRESS@_SUFFIX\\ through \*zcat*\ as it searches -it. - -.section Selecting messages by various criteria (exipick) -.rset SECTexipick "~~chapter.~~section" -.index \*exipick*\ -John Jetmore's \*exipick*\ utility is included in the Exim distribution. It -lists messages from the queue according to a variety of criteria. For details, -run: -.display asis -exipick --help -.endd - - -.section Cycling log files (exicyclog) -.rset SECTcyclogfil "~~chapter.~~section" -.index log||cycling local files -.index cycling logs -.index \*exicyclog*\ -The \*exicyclog*\ script can be used to cycle (rotate) \*mainlog*\ and -\*rejectlog*\ files. This is not necessary if only syslog is being used, or if -you are using log files with datestamps in their names (see section -~~SECTdatlogfil). Some operating systems have their own standard mechanisms for -log cycling, and these can be used instead of \*exicyclog*\ if preferred. - -Each time \*exicyclog*\ is run the file names get `shuffled down' by one. If -the main log file name is \(mainlog)\ (the default) then when \*exicyclog*\ is -run \(mainlog)\ becomes \(mainlog.01)\, the previous \(mainlog.01)\ becomes -\(mainlog.02)\ and so on, up to a limit which is set in the script, and which -defaults to 10. -.em -Log files whose numbers exceed the limit are discarded. -.nem -Reject logs are handled similarly. - -.em -If the limit is greater than 99, the script uses 3-digit numbers such as -\(mainlog.001)\, \(mainlog.002)\, etc. If you change from a number less than 99 -to one that is greater, or \*vice versa*\, you will have to fix the names of -any existing log files. -.nem - -If no \(mainlog)\ file exists, the script does nothing. Files that `drop off' -the end are deleted. All files with numbers greater than 01 are compressed, -using a compression command which is configured by the \\COMPRESS@_COMMAND\\ -setting in \(Local/Makefile)\. It is usual to run \*exicyclog*\ daily from a -root \crontab\ entry of the form -.display -1 0 * * * su exim -c /usr/exim/bin/exicyclog -.endd -assuming you have used the name `exim' for the Exim user. You can run -\*exicyclog*\ as root if you wish, but there is no need. - - -.section Mail statistics (eximstats) -.rset SECTmailstat "~~chapter.~~section" -.index statistics -.index \*eximstats*\ -A Perl script called \*eximstats*\ is provided for extracting statistical -information from log files. The output is either plain text, or HTML. -Exim log files are also suported by the \*Lire*\ system produced by the -LogReport Foundation (\?http://www.logreport.org?\). - -The \*eximstats*\ script has been hacked about quite a bit over time. The -latest version is the result of some extensive revision by Steve Campbell. A -lot of information is given by default, but there are options for suppressing -various parts of it. Following any options, the arguments to the script are a -list of files, which should be main log files. For example: -.display asis -eximstats -nr /var/spool/exim/log/mainlog.01 -.endd -By default, \*eximstats*\ extracts information about the number and volume of -messages received from or delivered to various hosts. The information is sorted -both by message count and by volume, and the top fifty hosts in each category -are listed on the standard output. Similar information, based on email -addresses or domains instead of hosts can be requested by means of various -options. For messages delivered and received locally, similar statistics are -also produced per user. - -The output also includes total counts and statistics about delivery errors, and -histograms showing the number of messages received and deliveries made in each -hour of the day. A delivery with more than one address in its envelope (for -example, an SMTP transaction with more than one \\RCPT\\ command) is counted -as a single delivery by \*eximstats*\. - -Though normally more deliveries than receipts are reported (as messages may -have multiple recipients), it is possible for \*eximstats*\ to report more -messages received than delivered, even though the queue is empty at the start -and end of the period in question. If an incoming message contains no valid -recipients, no deliveries are recorded for it. A bounce message is handled as -an entirely separate message. - -\*eximstats*\ always outputs a grand total summary giving the volume and number -of messages received and deliveries made, and the number of hosts involved in -each case. It also outputs the number of messages that were delayed (that is, -not completely delivered at the first attempt), and the number that had at -least one address that failed. - -The remainder of the output is in sections that can be independently disabled -or modified by various options. It consists of a summary of deliveries by -transport, histograms of messages received and delivered per time interval -(default per hour), information about the time messages spent on the queue, -a list of relayed messages, lists of the top fifty sending hosts, local -senders, destination hosts, and destination local users by count and by volume, -and a list of delivery errors that occurred. - -The relay information lists messages that were actually relayed, that is, they -came from a remote host and were directly delivered to some other remote host, -without being processed (for example, for aliasing or forwarding) locally. - -The options for \*eximstats*\ are as follows: - -.startoptions -.index \*eximstats*\||options -.option bydomain -The `league tables' are computed on the basis of the superior domains of the -sending hosts instead of the sending and receiving hosts. This option may be -combined with \-byhost-\ and/or \-byemail-\. - -.option byedomain -This is a synonym for \-byemaildomain-\. - -.option byemail -The `league tables' are computed on the basis of complete email addresses, -instead of sending and receiving hosts. This option may be combined with -\-byhost-\ and/or \-bydomain-\. - -.option byemaildomain -The `league tables' are computed on the basis of the sender's email domain -instead of the sending and receiving hosts. This option may be combined with -\-byhost-\, \-bydomain-\, or \-byemail-\. - -.option byhost -The `league tables' are computed on the basis of sending and receiving hosts. -This is the default option. It may be combined with \-bydomain-\ and/or -\-byemail-\. - -.option cache -Cache results of \*timegm()*\ lookups. This results in a significant speedup -when processing hundreds of thousands of messages, at a cost of increasing the -memory utilisation. - -.option chartdir <<dir>> -When \-charts-\ is specified, create the charts in the directory <<dir>>. - -.option chartrel <<dir>> -When \-charts-\ is specified, this option specifies the relative directory for -the \"img src="\ tags from where to include the charts. - -.option charts -Create graphical charts to be displayed in HTML output. This requires the -\"GD"\, \"GDTextUtil"\, and \"GDGraph"\ Perl modules, which can be obtained -from \?http://www.cpan.org/modules/01modules.index.html?\. - -To install these, download and unpack them, then use the normal Perl -installation procedure: -.display asis -perl Makefile.PL -make -make test -make install -.endd - -.option d -This is a debug flag. It causes \*eximstats*\ to output the \*eval()*\'d parser -to the standard output, which makes it easier to trap errors in the eval -section. Remember to add one to the line numbers to allow for the title. - - -.option help -Show help information about \*eximstats*\' options. - -.option h <<n>> -This option controls the histograms of messages received and deliveries per -time interval. By default the time interval is one hour. If \-h0-\ is given, -the histograms are suppressed; otherwise the value of <<n>> gives the number of -divisions per hour. Valid values are 0, 1, 2, 3, 5, 10, 15, 20, 30 or 60, so -\-h2-\ sets an interval of 30 minutes, and the default is equivalent to \-h1-\. - -.option html -Output the results in HTML instead of plain text. - -.option merge -This option causes \*eximstats*\ to merge old reports into a combined report. -When this option is used, the input files must be outputs from previous calls -to \*eximstats*\, not raw log files. For example, you could produce a set of -daily reports and a weekly report by commands such as -.display asis -eximstats mainlog.sun > report.sun.txt -eximstats mainlog.mon > report.mon.txt -eximstats mainlog.tue > report.tue.txt -eximstats mainlog.wed > report.wed.txt -eximstats mainlog.thu > report.thu.txt -eximstats mainlog.fri > report.fri.txt -eximstats mainlog.sat > report.sat.txt -eximstats -merge -html report.*.txt > weekly_report.html -.endd -You can merge text or html reports and output the results as text or html. You -can use all the normal \*eximstats*\ output options, but only data included in -the original reports can be shown. When merging reports, some loss of accuracy -may occur in the `league tables', towards the ends of the lists. The order of -items in the `league tables' may vary when the data volumes round to the same -value. - -.option ne -Suppress the display of information about failed deliveries (errors). - -.option nr -Suppress information about messages relayed through this host. - -.option nr /pattern/ -Suppress information about relayed messages that match the pattern, which is -matched against a string of the following form (split over two lines here in -order to fit it on the page): -.display asis -H=<host> [<ip address>] A=<sender address> => - H=<host> A=<recipient address> -.endd -for example -.display asis -H=in.host [1.2.3.4] A=from@some.where.example => - H=out.host A=to@else.where.example -.endd -The sending host name appears in parentheses if it has not been verified as -matching the IP address. The mail addresses are taken from the envelope, not -the headers. This option allows you to screen out hosts whom you are happy to -have using your host as a relay. - -.option nt -Suppress the statistics about delivery by transport. - -.option nt/<<pattern>>/ -Suppress the statistics about delivery by any transport whose name matches the -pattern. If you are using one transport to send all messages to a scanning -mechanism before doing the real delivery, this feature can be used to omit that -transport from your normal statistics (on the grounds that it is of no -interest). - - -.option "pattern" "#<<description>>#/<<pattern>>/" -Count lines matching specified patterns and show them in -the results. For example: -.display asis --pattern 'Refused connections' '/refused connection/' -.endd -This option can be specified multiple times. - -.option q0 -Suppress information about times messages spend on the queue. - -.option q <<n1>>... -This option sets an alternative list of time intervals for the queueing -information. The values are separated by commas and are in seconds, but can -involve arithmetic multipliers, so for example you can set 3$*$60 to specify 3 -minutes. A setting such as -.display asis --q60,5*60,10*60 -.endd -causes \*eximstats*\ to give counts of messages that stayed on the queue for less -than one minute, less than five minutes, less than ten minutes, and over ten -minutes. - -.option t <<n>> -Sets the `top' count to <<n>>. This controls the listings of the `top <<n>>' -hosts and users by count and volume. The default is 50, and setting 0 -suppresses the output altogether. - -.option tnl -Omit local information from the `top' listings. - -.option t@_remote@_users -Include remote users in the `top' listings. - -.endoptions - - -.section Checking access policy (exim@_checkaccess) -.rset SECTcheckaccess "~~chapter.~~section" -.index \*exim@_checkaccess*\ -.index policy control||checking access -.index checking access -The \-bh-\ command line argument allows you to run a fake SMTP session with -debugging output, in order to check what Exim is doing when it is applying -policy controls to incoming SMTP mail. However, not everybody is sufficiently -familiar with the SMTP protocol to be able to make full use of \-bh-\, and -sometimes you just want to answer the question \*Does this address have -access?*\ without bothering with any further details. - -The \*exim@_checkaccess*\ utility is a `packaged' version of \-bh-\. It takes -two arguments, an IP address and an email address: -.display asis -exim_checkaccess 10.9.8.7 A.User@a.domain.example -.endd -The utility runs a call to Exim with the \-bh-\ option, to test whether the -given email address would be accepted in a \\RCPT\\ command in a TCP/IP -connection from the host with the given IP address. The output of the utility -is either the word `accepted', or the SMTP error response, for example: -.display asis -Rejected: - 550 Relay not permitted -.endd -When running this test, the utility uses \"<>"\ as the envelope sender address -for the \\MAIL\\ command, but you can change this by providing additional -options. These are passed directly to the Exim command. For example, to specify -that the test is to be run with the sender address \*himself@@there.example*\ -you can use: -.display asis -exim_checkaccess 10.9.8.7 A.User@a.domain.example \ - -f himself@there.example -.endd -Note that these additional Exim command line items must be given after the two -mandatory arguments. - -Because the \exim@_checkaccess\ uses \-bh-\, it does not perform callouts while -running its checks. You can run checks that include callouts by using \-bhc-\, -but this is not yet available in a `packaged' form. - - -.section Making DBM files (exim@_dbmbuild) -.rset SECTdbmbuild "~~chapter.~~section" -.index DBM||building dbm files -.index building DBM files -.index \*exim@_dbmbuild*\ -.index lower casing -.index binary zero||in lookup key -The \*exim@_dbmbuild*\ program reads an input file containing keys and data in -the format used by the \%lsearch%\ lookup (see section ~~SECTsinglekeylookups). -It writes a DBM file using the lower-cased alias names as keys and the -remainder of the information as data. The lower-casing can be prevented by -calling the program with the \-nolc-\ option. - -A terminating zero is included as part of the key string. This is expected by -the \%dbm%\ lookup type. However, if the option \-nozero-\ is given, -\*exim@_dbmbuild*\ creates files without terminating zeroes in either the key -strings or the data strings. The \%dbmnz%\ lookup type can be used with such -files. - -The program requires two arguments: the name of the input file (which can be a -single hyphen to indicate the standard input), and the name of the output file. -It creates the output under a temporary name, and then renames it if all went -well. -.index \\USE@_DB\\ -If the native DB interface is in use (\\USE@_DB\\ is set in a compile-time -configuration file -- this is common in free versions of Unix) the two file -names must be different, because in this mode the Berkeley DB functions create -a single output file using exactly the name given. For example, -.display asis -exim_dbmbuild /etc/aliases /etc/aliases.db -.endd -reads the system alias file and creates a DBM version of it in -\(/etc/aliases.db)\. - -In systems that use the \*ndbm*\ routines (mostly proprietary versions of Unix), -two files are used, with the suffixes \(.dir)\ and \(.pag)\. In this -environment, the suffixes are added to the second argument of -\*exim@_dbmbuild*\, so it can be the same as the first. This is also the case -when the Berkeley functions are used in compatibility mode (though this is not -recommended), because in that case it adds a \(.db)\ suffix to the file name. - -If a duplicate key is encountered, the program outputs a warning, and when it -finishes, its return code is 1 rather than zero, unless the \-noduperr-\ option -is used. By default, only the first of a set of duplicates is used -- this -makes it compatible with \%lsearch%\ lookups. There is an option \-lastdup-\ -which causes it to use the data for the last duplicate instead. There is also -an option \-nowarn-\, which stops it listing duplicate keys to \stderr\. For -other errors, where it doesn't actually make a new file, the return code is 2. - - - -.section Finding individual retry times (exinext) -.rset SECTfinindret "~~chapter.~~section" -.index retry||times -.index \*exinext*\ -A utility called \*exinext*\ (mostly a Perl script) provides the ability to fish -specific information out of the retry database. Given a mail domain (or a -complete address), it looks up the hosts for that domain, and outputs any retry -information for the hosts or for the domain. At present, the retry information -is obtained by running \*exim@_dumpdb*\ (see below) and post-processing the -output. For example: -.display asis -$ exinext piglet@milne.fict.example -kanga.milne.fict.example:192.168.8.1 error 146: Connection refused - first failed: 21-Feb-1996 14:57:34 - last tried: 21-Feb-1996 14:57:34 - next try at: 21-Feb-1996 15:02:34 -roo.milne.fict.example:192.168.8.3 error 146: Connection refused - first failed: 20-Jan-1996 13:12:08 - last tried: 21-Feb-1996 11:42:03 - next try at: 21-Feb-1996 19:42:03 - past final cutoff time -.endd -You can also give \*exinext*\ a local part, without a domain, and it -will give any retry information for that local part in your default domain. -A message id can be used to obtain retry information pertaining to a specific -message. This exists only when an attempt to deliver a message to a remote host -suffers a message-specific error (see section ~~SECToutSMTPerr). \*exinext*\ is -not particularly efficient, but then it isn't expected to be run very often. - -The \*exinext*\ utility calls Exim to find out information such as the location -of the spool directory. The utility has \-C-\ and \-D-\ options, which are -passed on to the \*exim*\ commands. The first specifies an alternate Exim -configuration file, and the second sets macros for use within the configuration -file. These features are mainly to help in testing, but might also be useful in -environments where more than one configuration file is in use. - - - -.section Hints database maintenance (exim@_dumpdb, exim@_fixdb, exim@_tidydb) -.rset SECThindatmai "~~chapter.~~section" -.index hints database||maintenance -.index maintaining Exim's hints database -Three utility programs are provided for maintaining the DBM files that Exim -uses to contain its delivery hint information. Each program requires two -arguments. The first specifies the name of Exim's spool directory, and the -second is the name of the database it is to operate on. These are as -follows: -.numberpars $. -\*retry*\: the database of retry information -.nextp -\*wait-*\<<transport name>>: databases of information about messages waiting -for remote hosts -.nextp -\*callout*\: the callout cache -.nextp -\*misc*\: other hints data -.endp -The \*misc*\ database is used for -.numberpars alpha -Serializing \\ETRN\\ runs (when \smtp@_etrn@_serialize\ is set) -.nextp -Serializing delivery to a specific host (when \serialize@_hosts\ is set in an -\%smtp%\ transport) -.endp - -.section exim@_dumpdb -.index \*exim@_dumpdb*\ -The entire contents of a database are written to the standard output by the -\*exim@_dumpdb*\ program, which has no options or arguments other than the -spool and database names. For example, to dump the retry database: -.display asis -exim_dumpdb /var/spool/exim retry -.endd -Two lines of output are produced for each entry: -.display - T:mail.ref.example:192.168.242.242 146 77 Connection refused -31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * -.endd -The first item on the first line is the key of the record. It starts with one -of the letters R, or T, depending on whether it refers to a routing or -transport retry. For a local delivery, the next part is the local address; for -a remote delivery it is the name of the remote host, followed by its failing IP -address (unless \no@_retry@_include@_ip@_address\ is set on the \%smtp%\ -transport). If the remote port is not the standard one (port 25), it is added -to the IP address. Then there follows an error code, an additional error code, -and a textual description of the error. - -The three times on the second line are the time of first failure, the time of -the last delivery attempt, and the computed time for the next attempt. The line -ends with an asterisk if the cutoff time for the last retry rule has been -exceeded. - -Each output line from \*exim@_dumpdb*\ for the \*wait-*\$it{xxx} databases -consists of a host name followed by a list of ids for messages that are or were -waiting to be delivered to that host. If there are a very large number for any -one host, continuation records, with a sequence number added to the host name, -may be seen. The data in these records is often out of date, because a message -may be routed to several alternative hosts, and Exim makes no effort to keep -cross-references. - - -.section exim@_tidydb -.index \*exim@_tidydb*\ -The \*exim@_tidydb*\ utility program is used to tidy up the contents of the -hints databases. If run with no options, it removes all records from a database -that are more than 30 days old. The cutoff date can be altered by means of the -\-t-\ option, which must be followed by a time. For example, to remove all -records older than a week from the retry database: -.display asis -exim_tidydb -t 7d /var/spool/exim retry -.endd -Both the \*wait-*\$it{xxx} and \*retry*\ databases contain items that involve -message ids. In the former these appear as data in records keyed by host -- -they were messages that were waiting for that host -- and in the latter they -are the keys for retry information for messages that have suffered certain -types of error. When \*exim@_tidydb*\ is run, a check is made to ensure that -message ids in database records are those of messages that are still on the -queue. Message ids for messages that no longer exist are removed from -\*wait-*\$it{xxx} records, and if this leaves any records empty, they are -deleted. For the \*retry*\ database, records whose keys are non-existent -message ids are removed. The \*exim@_tidydb*\ utility outputs comments on the -standard output whenever it removes information from the database. - -.em -Certain records are automatically removed by Exim when they are no longer -needed, but others are not. For example, if all the MX hosts for a domain are -down, a retry record is created for each one. If the primary MX host comes back -first, its record is removed when Exim successfully delivers to it, but the -records for the others remain because Exim has not tried to use those hosts. - -It is important, therefore, to run \*exim@_tidydb*\ periodically on all the -hints databases. You should do this at a quiet time of day, because it requires -a database to be locked (and therefore inaccessible to Exim) while it does its -work. Removing records from a DBM file does not normally make the file smaller, -but all the common DBM libraries are able to re-use the space that is released. -After an initial phase of increasing in size, the databases normally reach a -point at which they no longer get any bigger, as long as they are regularly -tidied. - -\**Warning**\: If you never run \*exim@_tidydb*\, the space used by the hints -databases is likely to keep on increasing. -.nem - - -.section exim@_fixdb -.index \*exim@_fixdb*\ -The \*exim@_fixdb*\ program is a utility for interactively modifying databases. -Its main use is for testing Exim, but it might also be occasionally useful for -getting round problems in a live system. It has no options, and its interface -is somewhat crude. On entry, it prompts for input with a right angle-bracket. A -key of a database record can then be entered, and the data for that record is -displayed. - -If `d' is typed at the next prompt, the entire record is deleted. For all -except the \*retry*\ database, that is the only operation that can be carried -out. For the \*retry*\ database, each field is output preceded by a number, and -data for individual fields can be changed by typing the field number followed -by new data, for example: -.display asis -> 4 951102:1000 -.endd -resets the time of the next delivery attempt. Time values are given as a -sequence of digit pairs for year, month, day, hour, and minute. Colons can be -used as optional separators. - - - -.section Mailbox maintenance (exim@_lock) -.rset SECTmailboxmaint "~~chapter.~~section" -.index mailbox||maintenance -.index \*exim@_lock*\ -.index locking mailboxes -The \*exim@_lock*\ utility locks a mailbox file using the same algorithm as -Exim. For a discussion of locking issues, see section ~~SECTopappend. -\*Exim@_lock*\ can be used to prevent any modification of a mailbox by Exim or -a user agent while investigating a problem. The utility requires the name of -the file as its first argument. If the locking is successful, the second -argument is run as a command (using C's \*system()*\ function); if there is no -second argument, the value of the SHELL environment variable is used; if this -is unset or empty, \(/bin/sh)\ is run. When the command finishes, the mailbox -is unlocked and the utility ends. The following options are available: - -.startoptions - -.option fcntl -Use \*fcntl()*\ locking on the open mailbox. - -.option flock -Use \*flock()*\ locking on the open mailbox, provided the operating system -supports it. - -.option interval -This must be followed by a number, which is a number of seconds; it sets the -interval to sleep between retries (default 3). - -.option lockfile -Create a lock file before opening the mailbox. - -.option mbx -Lock the mailbox using MBX rules. - -.option q -Suppress verification output. - -.option retries -This must be followed by a number; it sets the number of times to try to get -the lock (default 10). - -.option restore@_time -This option causes \exim@_lock\ to restore the modified and read times to the -locked file before exiting. This allows you to access a locked mailbox (for -example, to take a backup copy) without disturbing the times that the user -subsequently sees. - -.option timeout -This must be followed by a number, which is a number of seconds; it sets a -timeout to be used with a blocking \*fcntl()*\ lock. If it is not set (the -default), a non-blocking call is used. - -.option v -Generate verbose output. - -.endoptions - -If none of \-fcntl-\, -\-flock-\, -\-lockfile-\ or \-mbx-\ are given, the default is to create a lock file and -also to use \*fcntl()*\ locking on the mailbox, which is the same as Exim's -default. The use of -\-flock-\ -or \-fcntl-\ requires that the file be writeable; the use of -\-lockfile-\ requires that the directory containing the file be writeable. -Locking by lock file does not last for ever; Exim assumes that a lock file is -expired if it is more than 30 minutes old. - -The \-mbx-\ option can be used with either or both of \-fcntl-\ or \-flock-\. -It assumes \-fcntl-\ by default. -MBX locking causes a shared lock to be taken out on the open mailbox, and an -exclusive lock on the file \(/tmp/.$it{n}.$it{m})\ where $it{n} and $it{m} are -the device number and inode number of the mailbox file. When the locking is -released, if an exclusive lock can be obtained for the mailbox, the file in -\(/tmp)\ is deleted. - -The default output contains verification of the locking that takes place. The -\-v-\ option causes some additional information to be given. The \-q-\ option -suppresses all output except error messages. - -A command such as -.display asis -exim_lock /var/spool/mail/spqr -.endd -runs an interactive shell while the file is locked, whereas -.display -exim@_lock -q /var/spool/mail/spqr @<@<End -<<some commands>> -End -.endd -runs a specific non-interactive sequence of commands while the file is locked, -suppressing all verification output. A single command can be run by a command -such as -.display asis -exim_lock -q /var/spool/mail/spqr \ - "cp /var/spool/mail/spqr /some/where" -.endd -Note that if a command is supplied, it must be entirely contained within the -second argument -- hence the quotes. - - - -. -. -. -. -. ============================================================================ -.chapter The Exim monitor -.set runningfoot "monitor" -.rset CHAPeximon ~~chapter -.index monitor -.index Exim monitor -.index X-windows -.index \*eximon*\ -.index Local/eximon.conf -.index \(exim@_monitor/EDITME)\ -The Exim monitor is an application which displays in an X window information -about the state of Exim's queue and what Exim is doing. An admin user can -perform certain operations on messages from this GUI interface; however all -such facilities are also available from the command line, and indeed, the -monitor itself makes use of the command line to perform any actions requested. - - -.section Running the monitor -The monitor is started by running the script called \*eximon*\. This is a shell -script that sets up a number of environment variables, and then runs the -binary called \(eximon.bin)\. The default appearance of the monitor window can -be changed by editing the \(Local/eximon.conf)\ file created by editing -\(exim@_monitor/EDITME)\. Comments in that file describe what the various -parameters are for. - -The parameters that get built into the \*eximon*\ script can be overridden for a -particular invocation by setting up environment variables of the same names, -preceded by `$tt{EXIMON@_}'. For example, a shell command such as -.display asis -EXIMON_LOG_DEPTH=400 eximon -.endd -(in a Bourne-compatible shell) runs \*eximon*\ with an overriding setting of the -\\LOG@_DEPTH\\ parameter. If \\EXIMON@_LOG@_FILE@_PATH\\ is set in the -environment, it overrides the Exim log file configuration. This makes it -possible to have \*eximon*\ tailing log data that is written to syslog, provided -that MAIL.INFO syslog messages are routed to a file on the local host. - -X resources can be used to change the appearance of the window in the normal -way. For example, a resource setting of the form -.display asis -Eximon*background: gray94 -.endd -changes the colour of the background to light grey rather than white. The -stripcharts are drawn with both the data lines and the reference lines in -black. This means that the reference lines are not visible when on top of the -data. However, their colour can be changed by setting a resource called -`highlight' (an odd name, but that's what the Athena stripchart widget uses). -For example, if your X server is running Unix, you could set up lighter -reference lines in the stripcharts by obeying -.display asis -xrdb -merge <<End -Eximon*highlight: gray -End -.endd - -.index admin user -In order to see the contents of messages on the queue, and to operate on them, -\*eximon*\ must either be run as root or by an admin user. - -The monitor's window is divided into three parts. The first contains one or -more stripcharts and two action buttons, the second contains a `tail' of the -main log file, and the third is a display of the queue of messages awaiting -delivery, with two more action buttons. The following sections describe these -different parts of the display. - - - -.section The stripcharts -.index stripchart -The first stripchart is always a count of messages on the queue. Its name can -be configured by setting \\QUEUE@_STRIPCHART@_NAME\\ in the -\(Local/eximon.conf)\ file. The remaining stripcharts are defined in the -configuration script by regular expression matches on log file entries, making -it possible to display, for example, counts of messages delivered to certain -hosts or using certain transports. The supplied defaults display counts of -received and delivered messages, and of local and SMTP deliveries. The default -period between stripchart updates is one minute; this can be adjusted by a -parameter in the \(Local/eximon.conf)\ file. - -The stripchart displays rescale themselves automatically as the value they are -displaying changes. There are always 10 horizontal lines in each chart; the -title string indicates the value of each division when it is greater than one. -For example, `x2' means that each division represents a value of 2. - -It is also possible to have a stripchart which shows the percentage fullness of -a particular disk partition, which is useful when local deliveries are confined -to a single partition. -.index \statvfs\ function -This relies on the availability of the \*statvfs()*\ function or equivalent in -the operating system. Most, but not all versions of Unix that support Exim have -this. For this particular stripchart, the top of the chart always represents -100%, and the scale is given as `x10%'. This chart is configured by setting -\\SIZE@_STRIPCHART\\ and (optionally) \\SIZE@_STRIPCHART@_NAME\\ in the -\(Local/eximon.conf)\ file. - - - -.section Main action buttons -.index size||of monitor window -.index monitor window size -.index window size -Below the stripcharts there is an action button for quitting the monitor. Next -to this is another button marked `Size'. They are placed here so that shrinking -the window to its default minimum size leaves just the queue count stripchart -and these two buttons visible. Pressing the `Size' button causes the window to -expand to its maximum size, unless it is already at the maximum, in which case -it is reduced to its minimum. - -When expanding to the maximum, if the window cannot be fully seen where it -currently is, it is moved back to where it was the last time it was at full -size. When it is expanding from its minimum size, the old position is -remembered, and next time it is reduced to the minimum it is moved back there. - -The idea is that you can keep a reduced window just showing one or two -stripcharts at a convenient place on your screen, easily expand it to show -the full window when required, and just as easily put it back to what it was. -The idea is copied from what the \*twm*\ window manager does for its -\*f.fullzoom*\ action. The minimum size of the window can be changed by setting -the \\MIN@_HEIGHT\\ and \\MIN@_WIDTH\\ values in \(Local/eximon.conf)\. - -Normally, the monitor starts up with the window at its full size, but it can be -built so that it starts up with the window at its smallest size, by setting -\\START@_SMALL\\=yes in \(Local/eximon.conf)\. - - -.section The log display -.index log||tail of, in monitor -The second section of the window is an area in which a display of the tail of -the main log is maintained. -To save space on the screen, the timestamp on each log line is shortened by -removing the date and, if \log@_timezone\ is set, the timezone. -The log tail is not available when the only destination for logging data is -syslog, unless the syslog lines are routed to a local file whose name is passed -to \*eximon*\ via the \\EXIMON@_LOG@_FILE@_PATH\\ environment variable. - -The log sub-window has a scroll bar at its lefthand side which can be used to -move back to look at earlier text, and the up and down arrow keys also have a -scrolling effect. The amount of log that is kept depends on the setting of -\\LOG@_BUFFER\\ in \(Local/eximon.conf)\, which specifies the amount of memory -to use. When this is full, the earlier 50% of data is discarded -- this is much -more efficient than throwing it away line by line. The sub-window also has a -horizontal scroll bar for accessing the ends of long log lines. This is the -only means of horizontal scrolling; the right and left arrow keys are not -available. Text can be cut from this part of the window using the mouse in the -normal way. The size of this subwindow is controlled by parameters in the -configuration file \(Local/eximon.conf)\. - -Searches of the text in the log window can be carried out by means of the ^R -and ^S keystrokes, which default to a reverse and a forward search, -respectively. The search covers only the text that is displayed in the window. -It cannot go further back up the log. - -The point from which the search starts is indicated by a caret marker. This is -normally at the end of the text in the window, but can be positioned explicitly -by pointing and clicking with the left mouse button, and is moved automatically -by a successful search. If new text arrives in the window when it is scrolled -back, the caret remains where it is, but if the window is not scrolled back, -the caret is moved to the end of the new text. - -Pressing ^R or ^S pops up a window into which the search text can be typed. -There are buttons for selecting forward or reverse searching, for carrying out -the search, and for cancelling. If the `Search' button is pressed, the search -happens and the window remains so that further searches can be done. If the -`Return' key is pressed, a single search is done and the window is closed. If -^C is typed the search is cancelled. - -The searching facility is implemented using the facilities of the Athena text -widget. By default this pops up a window containing both `search' and `replace' -options. In order to suppress the unwanted `replace' portion for eximon, a -modified version of the \TextPop\ widget is distributed with Exim. However, the -linkers in BSDI and HP-UX seem unable to handle an externally provided version -of \TextPop\ when the remaining parts of the text widget come from the standard -libraries. The compile-time option \\EXIMON@_TEXTPOP\\ can be unset to cut out -the modified \TextPop\, making it possible to build Eximon on these systems, at -the expense of having unwanted items in the search popup window. - - -.section The queue display -.index queue||display in monitor -The bottom section of the monitor window contains a list of all messages that -are on the queue, which includes those currently being received or delivered, -as well as those awaiting delivery. The size of this subwindow is controlled by -parameters in the configuration file \(Local/eximon.conf)\, and the frequency -at which it is updated is controlled by another parameter in the same file -- -the default is 5 minutes, since queue scans can be quite expensive. However, -there is an `Update' action button just above the display which can be used to -force an update of the queue display at any time. - -When a host is down for some time, a lot of pending mail can build up for it, -and this can make it hard to deal with other messages on the queue. To help -with this situation there is a button next to `Update' called `Hide'. If -pressed, a dialogue box called `Hide addresses ending with' is put up. If you -type anything in here and press `Return', the text is added to a chain of such -texts, and if every undelivered address in a message matches at least one -of the texts, the message is not displayed. - -If there is an address that does not match any of the texts, all the addresses -are displayed as normal. The matching happens on the ends of addresses so, for -example, \*cam.ac.uk*\ specifies all addresses in Cambridge, while -\*xxx@@foo.com.example*\ specifies just one specific address. When any hiding -has been set up, a button called `Unhide' is displayed. If pressed, it cancels -all hiding. Also, to ensure that hidden messages do not get forgotten, a hide -request is automatically cancelled after one hour. - -While the dialogue box is displayed, you can't press any buttons or do anything -else to the monitor window. For this reason, if you want to cut text from the -queue display to use in the dialogue box, you have to do the cutting before -pressing the `Hide' button. - -The queue display contains, for each unhidden queued message, the length of -time it has been on the queue, the size of the message, the message id, the -message sender, and the first undelivered recipient, all on one line. If it is -a bounce message, the sender is shown as `<>'. If there is more than one -recipient to which the message has not yet been delivered, subsequent ones are -listed on additional lines, up to a maximum configured number, following which -an ellipsis is displayed. Recipients that have already received the message are -not shown. -.index frozen messages||display -If a message is frozen, an asterisk is displayed at the left-hand side. - -The queue display has a vertical scroll bar, and can also be scrolled by means -of the arrow keys. Text can be cut from it using the mouse in the normal way. -The text searching facilities, as described above for the log window, are also -available, but the caret is always moved to the end of the text when the queue -display is updated. - - -.section The queue menu -.index queue||menu in monitor -If the \shift\ key is held down and the left button is clicked when the mouse -pointer is over the text for any message, an action menu pops up, and the first -line of the queue display for the message is highlighted. This does not affect -any selected text. - -If you want to use some other event for popping up the menu, you can set the -\\MENU@_EVENT\\ parameter in \(Local/eximon.conf)\ to change the default, or -set \\EXIMON@_MENU@_EVENT\\ in the environment before starting the monitor. The -value set in this parameter is a standard X event description. For example, to -run eximon using \ctrl\ rather than \shift\ you could use -.display asis -EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon -.endd -The title of the menu is the message id, and it contains entries which act as -follows: -.numberpars $. -\*message log*\: The contents of the message log for the message are displayed in -a new text window. -.nextp -\*headers*\: Information from the spool file that contains the envelope -information and headers is displayed in a new text window. See chapter -~~CHAPspool for a description of the format of spool files. -.nextp -\*body*\: The contents of the spool file containing the body of the message are -displayed in a new text window. There is a default limit of 20,000 bytes to the -amount of data displayed. This can be changed by setting the \\BODY@_MAX\\ -option at compile time, or the \\EXIMON@_BODY@_MAX\\ option at run time. -.nextp -\*deliver message*\: A call to Exim is made using the \-M-\ option to request -delivery of the message. This causes an automatic thaw if the message is -frozen. The \-v-\ option is also set, and the output from Exim is displayed in -a new text window. The delivery is run in a separate process, to avoid holding -up the monitor while the delivery proceeds. -.nextp -\*freeze message*\: A call to Exim is made using the \-Mf-\ option to request -that the message be frozen. -.nextp -.index thawing messages -.index unfreezing messages -.index frozen messages||thawing -\*thaw message*\: A call to Exim is made using the \-Mt-\ option to request that -the message be thawed. -.nextp -.index delivery||forcing failure -\*give up on msg*\: A call to Exim is made using the \-Mg-\ option to request -that Exim gives up trying to deliver the message. A bounce message is generated -for any remaining undelivered addresses. -.nextp -\*remove message*\: A call to Exim is made using the \-Mrm-\ option to request -that the message be deleted from the system without generating a bounce -message. -.nextp -\*add recipient*\: A dialog box is displayed into which a recipient address can -be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter -is set in \(Local/eximon.conf)\, the address is qualified with that domain. -Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ -causes a call to Exim to be made using the \-Mar-\ option to request that an -additional recipient be added to the message, unless the entry box is empty, in -which case no action is taken. -.nextp -\*mark delivered*\: A dialog box is displayed into which a recipient address can -be typed. If the address is not qualified and the \\QUALIFY@_DOMAIN\\ parameter -is set in \(Local/eximon.conf)\, the address is qualified with that domain. -Otherwise it must be entered as a fully qualified address. Pressing \\RETURN\\ -causes a call to Exim to be made using the \-Mmd-\ option to mark the given -recipient address as already delivered, unless the entry box is empty, in which -case no action is taken. -.nextp -\*mark all delivered*\: A call to Exim is made using the \-Mmad-\ option to mark -all recipient addresses as already delivered. -.nextp -\*edit sender*\: A dialog box is displayed initialized with the current sender's -address. Pressing \\RETURN\\ causes a call to Exim to be made using the \-Mes-\ -option to replace the sender address, unless the entry box is empty, in which -case no action is taken. If you want to set an empty sender (as in bounce -messages), you must specify it as `<>'. Otherwise, if the address is not -qualified and the \\QUALIFY@_DOMAIN\\ parameter is set in -\(Local/eximon.conf)\, the address is qualified with that domain. -.endp -When a delivery is forced, a window showing the \-v-\ output is displayed. In -other cases when a call to Exim is made, if there is any output from Exim (in -particular, if the command fails) a window containing the command and the -output is displayed. Otherwise, the results of the action are normally apparent -from the log and queue displays. However, if you set \\ACTION@_OUTPUT\\=yes in -\(Local/eximon.conf)\, a window showing the Exim command is always opened, even -if no output is generated. - -The queue display is automatically updated for actions such as freezing and -thawing, unless \\ACTION@_QUEUE@_UPDATE\\=no has been set in -\(Local/eximon.conf)\. In this case the `Update' button has to be used to force -an update of the display after one of these actions. - -In any text window that is displayed as result of a menu action, the normal -cut-and-paste facility is available, and searching can be carried out using ^R -and ^S, as described above for the log tail window. - - - - - - -. -. -. -. -. ============================================================================ -.chapter Security considerations -.set runningfoot "security" -.rset CHAPsecurity ~~chapter -.index security -This chapter discusses a number of issues concerned with security, some of -which are also covered in other parts of this manual. - -For reasons that this author does not understand, some people have promoted -Exim as a `particularly secure' mailer. Perhaps it is because of the existence -of this chapter in the documentation. However, the intent of the chapter is -simply to describe the way Exim works in relation to certain security concerns, -not to make any specific claims about the effectiveness of its security as -compared with other MTAs. - -What follows is a description of the way Exim is supposed to be. Best efforts -have been made to try to ensure that the code agrees with the theory, but an -absence of bugs can never be guaranteed. Any that are reported will get fixed -as soon as possible. - -.section Building a more `hardened' Exim -.index security||build-time features -There are a number of build-time options that can be set in \(Local/Makefile)\ -to create Exim binaries that are `harder' to attack, in particular by a rogue -Exim administrator who does not have the root password, or by someone who has -penetrated the Exim (but not the root) account. These options are as follows: -.numberpars $. -\\ALT@_CONFIG@_PREFIX\\ can be set to a string that is required to match the -start of any file names used with the \-C-\ option. When it is set, these file -names are also not allowed to 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\. - -If the permitted configuration files are confined to a directory to -which only root has access, this guards against someone who has broken -into the Exim account from running a privileged Exim with an arbitrary -configuration file, and using it to break into other accounts. -.nextp -If \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined, root privilege is retained for \-C-\ -and \-D-\ only if the caller of Exim is root. Without it, the Exim user may -also use \-C-\ and \-D-\ and retain privilege. Setting this option 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. -\\ALT@_CONFIG@_ROOT@_ONLY\\ is not set by default. -.nextp -If \\DISABLE@_D@_OPTION\\ is defined, the use of the \-D-\ command line option -is disabled. -.nextp -\\FIXED@_NEVER@_USERS\\ can be set to a colon-separated list of users that are -never to be used for any deliveries. This is like the \never@_users\ runtime -option, but it cannot be overridden; the runtime option adds additional users -to the list. The default setting is `root'; this prevents a non-root user who -is permitted to modify the runtime file from using Exim as a way to get root. -.endp - - -.section Root privilege -.index setuid -.index root privilege -The Exim binary is normally setuid to root, which means that it gains root -privilege (runs as root) when it starts execution. In some special cases (for -example, when the daemon is not in use and there are no local deliveries), it -may be possible to run Exim setuid to some user other than root. This is -discussed in the next section. However, in most installations, root privilege -is required for two things: -.numberpars $. -To set up a socket connected to the standard SMTP port (25) when initialising -the listening daemon. If Exim is run from \*inetd*\, this privileged action is -not required. -.nextp -To be able to change uid and gid in order to read users' \(.forward)\ files and -perform local deliveries as the receiving user or as specified in the -configuration. -.endp -It is not necessary to be root to do any of the other things Exim does, such as -receiving messages and delivering them externally over SMTP, and it is -obviously more secure if Exim does not run as root except when necessary. -For this reason, a user and group for Exim to use must be defined in -\(Local/Makefile)\. These are known as `the Exim user' and `the Exim group'. -Their values can be changed by the run time configuration, though this is not -recommended. Often a user called \*exim*\ is used, but some sites use \*mail*\ -or another user name altogether. - -Exim uses \*setuid()*\ whenever it gives up root privilege. This is a permanent -abdication; the process cannot regain root afterwards. Prior to release 4.00, -\*seteuid()*\ was used in some circumstances, but this is no longer the case. - -After a new Exim process has interpreted its command line options, it changes -uid and gid in the following cases: -.numberpars $. -.index \-C-\ option -.index \-D-\ option -If the \-C-\ option is used to specify an alternate configuration file, or if -the \-D-\ option is used to define macro values for the configuration, and the -calling process is not running as root or the Exim user, the uid and gid are -changed to those of the calling process. -However, if \\ALT@_CONFIG@_ROOT@_ONLY\\ is defined in \(Local/Makefile)\, only -root callers may use \-C-\ and \-D-\ without losing privilege, and if -\\DISABLE@_D@_OPTION\\ is set, the \-D-\ option may not be used at all. -.nextp -.index \-be-\ option -.index \-bf-\ option -.index \-bF-\ option -If the expansion test option (\-be-\) or one of the filter testing options -(\-bf-\ or \-bF-\) are used, the uid and gid are changed to those of the -calling process. -.nextp -If the process is not a daemon process or a queue runner process or a delivery -process or a process for testing address routing (started with \-bt-\), the uid -and gid are changed to the Exim user and group. This means that Exim always -runs under its own uid and gid when receiving messages. This also applies when -testing address verification -.index \-bv-\ option -.index \-bh-\ option -(the \-bv-\ option) and testing incoming message policy controls (the \-bh-\ -option). -.nextp -For a daemon, queue runner, delivery, or address testing process, the uid -remains as root at this stage, but the gid is changed to the Exim group. -.endp -The processes that initially retain root privilege behave as follows: -.numberpars $. -A daemon process changes the gid to the Exim group and the uid to the Exim user -after setting up one or more listening sockets. The \*initgroups()*\ function -is called, so that if the Exim user is in any additional groups, they will be -used during message reception. -.nextp -A queue runner process retains root privilege throughout its execution. Its job -is to fork a controlled sequence of delivery processes. -.nextp -A delivery process retains root privilege throughout most of its execution, -but any actual deliveries (that is, the transports themselves) are run in -subprocesses which always change to a non-root uid and gid. For local -deliveries this is typically the uid and gid of the owner of the mailbox; for -remote deliveries, the Exim uid and gid are used. Once all the delivery -subprocesses have been run, a delivery process changes to the Exim uid and gid -while doing post-delivery tidying up such as updating the retry database and -generating bounce and warning messages. - -While the recipient addresses in a message are being routed, the delivery -process runs as root. However, if a user's filter file has to be processed, -this is done in a subprocess that runs under the individual user's uid and -gid. A system filter is run as root unless \system@_filter@_user\ is set. -.nextp -A process that is testing addresses (the \-bt-\ option) runs as root so that -the routing is done in the same environment as a message delivery. -.endp - - -.section Running Exim without privilege -.rset SECTrunexiwitpri "~~chapter.~~section" -.index privilege, running without -.index unprivileged running -.index root privilege||running without -Some installations like to run Exim in an unprivileged state for more of its -operation, for added security. Support for this mode of operation is provided -by the global option \deliver@_drop@_privilege\. When this is set, the uid and -gid are changed to the Exim user and group at the start of a delivery process -(and also queue runner and address testing processes). This means that address -routing is no longer run as root, and the deliveries themselves cannot change -to any other uid. - -Leaving the binary setuid to root, but setting \deliver@_drop@_privilege\ means -that the daemon can still be started in the usual way, and it can respond -correctly to SIGHUP because the re-invocation regains root privilege. - -An alternative approach is to make Exim setuid to the Exim user and also setgid -to the Exim group. -If you do this, the daemon must be started from a root process. (Calling -Exim from a root process makes it behave in the way it does when it is setuid -root.) However, the daemon cannot restart itself after a SIGHUP signal because -it cannot regain privilege. - -It is still useful to set \deliver@_drop@_privilege\ in this case, because it -stops Exim from trying to re-invoke itself to do a delivery after a message has -been received. Such a re-invocation is a waste of resources because it has no -effect. - -If restarting the daemon is not an issue (for example, if -.em -\mua@_wrapper\ is set, or -.nem -\*inetd*\ is being used instead of a daemon), having the binary setuid to the -Exim user seems a clean approach, but there is one complication: - -In this style of operation, Exim is running with the real uid and gid set to -those of the calling process, and the effective uid/gid set to Exim's values. -Ideally, any association with the calling process' uid/gid should be dropped, -that is, the real uid/gid should be reset to the effective values so as to -discard any privileges that the caller may have. While some operating systems -have a function that permits this action for a non-root effective uid, quite a -number of them do not. Because of this lack of standardization, Exim does not -address this problem at this time. - -For this reason, the recommended approach for `mostly unprivileged' running is -to keep the Exim binary setuid to root, and to set \deliver@_drop@_privilege\. -This also has the advantage of allowing a daemon to be used in the most -straightforward way. - -If you configure Exim not to run delivery processes as root, there are a -number of restrictions on what you can do: -.numberpars $. -You can deliver only as the Exim user/group. You should explicitly use the -\user\ and \group\ options to override routers or local transports that -normally deliver as the recipient. This makes sure that configurations that -work in this mode function the same way in normal mode. Any implicit or -explicit specification of another user causes an error. -.nextp -Use of \(.forward)\ files is severely restricted, such that it is usually -not worthwhile to include them in the configuration. -.nextp -Users who wish to use \(.forward)\ would have to make their home directory and -the file itself accessible to the Exim user. Pipe and append-to-file entries, -and their equivalents in Exim filters, cannot be used. While they could be -enabled in the Exim user's name, that would be insecure and not very useful. -.nextp -Unless the local user mailboxes are all owned by the Exim user (possible in -some POP3 or IMAP-only environments): -.numberpars $*$ -They must be owned by the Exim group and be writable by that group. This -implies you must set \mode\ in the appendfile configuration, as well as the -mode of the mailbox files themselves. -.nextp -You must set \no@_check@_owner\, since most or all of the files will not be -owned by the Exim user. -.nextp -You must set \file@_must@_exist\, because Exim cannot set the owner correctly -on a newly created mailbox when unprivileged. This also implies that new -mailboxes need to be created manually. -.endp -.endp -These restrictions severely restrict what can be done in local deliveries. -However, there are no restrictions on remote deliveries. If you are running a -gateway host that does no local deliveries, setting \deliver@_drop@_privilege\ -gives more security at essentially no cost. -.em -If you are using the \mua@_wrapper\ facility (see chapter ~~CHAPnonqueueing), -\deliver@_drop@_privilege\ is forced to be true. -.nem - - -.section Delivering to local files -Full details of the checks applied by \%appendfile%\ before it writes to a file -are given in chapter ~~CHAPappendfile. - - -.section IPv4 source routing -.index source routing||in IP packets -.index IP source routing -Many operating systems suppress IP source-routed packets in the kernel, but -some cannot be made to do this, so Exim does its own check. It logs incoming -IPv4 source-routed TCP calls, and then drops them. Things are all different in -IPv6. No special checking is currently done. - - -.section The VRFY, EXPN, and ETRN commands in SMTP -Support for these SMTP commands is disabled by default. If required, they can -be enabled by defining suitable ACLs. - - - -.section Privileged users -.index trusted user -.index admin user -.index privileged user -.index user||trusted -.index user||admin -Exim recognises two sets of users with special privileges. Trusted users are -able to submit new messages to Exim locally, but supply their own sender -addresses and information about a sending host. For other users submitting -local messages, Exim sets up the sender address from the uid, and doesn't -permit a remote host to be specified. - -.index \-f-\ option -However, an untrusted user is permitted to use the \-f-\ command line option in -the special form \-f @<@>-\ to indicate that a delivery failure for the message -should not cause an error report. This affects the message's envelope, but it -does not affect the ::Sender:: header. Untrusted users may also be permitted to -use specific forms of address with the \-f-\ option by setting the -\untrusted@_set@_sender\ option. - -Trusted users are used to run processes that receive mail messages from some -other mail domain and pass them on to Exim for delivery either locally, or over -the Internet. Exim trusts a caller that is running as root, as the Exim user, -as any user listed in the \trusted@_users\ configuration option, or under any -group listed in the \trusted@_groups\ option. - -Admin users are permitted to do things to the messages on Exim's queue. They -can freeze or thaw messages, cause them to be returned to their senders, remove -them entirely, or modify them in various ways. In addition, admin users can run -the Exim monitor and see all the information it is capable of providing, which -includes the contents of files on the spool. - -.index \-M-\ option -.index \-q-\ option -By default, the use of the \-M-\ and \-q-\ options to cause Exim to attempt -delivery of messages on its queue is restricted to admin users. This -restriction can be relaxed by setting the \no@_prod@_requires@_admin\ option. -Similarly, the use of \-bp-\ (and its variants) to list the contents of the -queue is also restricted to admin users. This restriction can be relaxed by -setting \no@_queue@_list@_requires@_admin\. - -Exim recognises an admin user if the calling process is running as root or as -the Exim user or if any of the groups associated with the calling process is -the Exim group. It is not necessary actually to be running under the Exim -group. However, if admin users who are not root or the Exim user are to access -the contents of files on the spool via the Exim monitor (which runs -unprivileged), Exim must be built to allow group read access to its spool -files. - - -.section Spool files -.index spool directory||files -Exim's spool directory and everything it contains is owned by the Exim user and -set to the Exim group. The mode for spool files is defined in the -\(Local/Makefile)\ configuration file, and defaults to 0640. This means that -any user who is a member of the Exim group can access these files. - - -.section Use of argv[0] -Exim examines the last component of \argv[0]\, and if it matches one of a set -of specific strings, Exim assumes certain options. For example, calling Exim -with the last component of \argv[0]\ set to `rsmtp' is exactly equivalent to -calling it with the option \-bS-\. There are no security implications in this. - - -.section Use of %f formatting -The only use made of `%f' by Exim is in formatting load average values. These -are actually stored in integer variables as 1000 times the load average. -Consequently, their range is limited and so therefore is the length of the -converted output. - - -.section Embedded Exim path -Exim uses its own path name, which is embedded in the code, only when it needs -to re-exec in order to regain root privilege. Therefore, it is not root when it -does so. If some bug allowed the path to get overwritten, it would lead to an -arbitrary program's being run as exim, not as root. - - -.section Use of sprintf() -.index \*sprintf()*\ -A large number of occurrences of `sprintf' in the code are actually calls to -\*string@_sprintf()*\, a function that returns the result in malloc'd store. -The intermediate formatting is done into a large fixed buffer by a function -that runs through the format string itself, and checks the length of each -conversion before performing it, thus preventing buffer overruns. - -The remaining uses of \*sprintf()*\ happen in controlled circumstances where -the output buffer is known to be sufficiently long to contain the converted -string. - - -.section Use of debug@_printf() and log@_write() -Arbitrary strings are passed to both these functions, but they do their -formatting by calling the function \*string@_vformat()*\, which runs through -the format string itself, and checks the length of each conversion. - - -.section Use of strcat() and strcpy() -These are used only in cases where the output buffer is known to be large -enough to hold the result. - - - - -. -. -. -. -. ============================================================================ -.chapter Format of spool files -.set runningfoot "spool file format" -.rset CHAPspool ~~chapter -.index format||spool files -.index spool directory||format of files -.index spool||files, format of -.index spool||files, editing -A message on Exim's queue consists of two files, whose names are the message id -followed by -D and -H, respectively. The data portion of the message is kept in -the -D file on its own. The message's envelope, status, and headers are all -kept in the -H file, whose format is described in this chapter. Each of these -two files contains the final component of its own name as its first line. This -is insurance against disk crashes where the directory is lost but the files -themselves are recoverable. - -Some people are tempted into editing -D files in order to modify messages. You -need to be extremely careful if you do this; it is not recommended and you are -on your own if you do it. Here are some of the pitfalls: -.numberpars $. -You must use the \*exim@_lock*\ utility to ensure that Exim does not try to -deliver the message while you are fiddling with it. The lock is implemented -by opening the -D file and taking out a write lock on it. If you update the -file in place, the lock will be retained. If you write a new file and rename -it, the lock will be lost at the instant of rename. -.nextp -If you change the number of lines in the file, the value of -\$body@_linecount$\, which is stored in the -H file, will be incorrect. -.nextp -If the message is in MIME format, you must take care not to break it. -.nextp -If the message is cryptographically signed, any change will invalidate the -signature. -.endp - -Files whose names end with -J may also be seen in the \(input)\ directory (or -its subdirectories when \split@_spool@_directory\ is set). These are journal -files, used to record addresses to which the message has been delivered during -the course of a delivery run. At the end of the run, the -H file is updated, -and the -J file is deleted. - -.section Format of the -H file -.index uid (user id)||in spool file -.index gid (group id)||in spool file -The second line of the -H file contains the login name for the uid of the -process that called Exim to read the message, followed by the numerical uid and -gid. For a locally generated message, this is normally the user who sent the -message. For a message received over TCP/IP, it is normally the Exim user. - -The third line of the file contains the address of the message's sender as -transmitted in the envelope, contained in angle brackets. The sender address is -empty for bounce messages. For incoming SMTP mail, the sender address is given -in the \\MAIL\\ command. For locally generated mail, the sender address is -created by Exim from the login name of the current user and the configured -\qualify@_domain\. However, this can be overridden by the \-f-\ option or a -leading `From' line if the caller is trusted, or if the supplied address is -`@<@>' or an address that matches \untrusted@_set@_senders\. - -The fourth line contains two numbers. The first is the time that the message -was received, in the conventional Unix form -- the number of seconds since the -start of the epoch. The second number is a count of the number of messages -warning of delayed delivery that have been sent to the sender. - -There follow a number of lines starting with a hyphen. These can appear in any -order, and are omitted when not relevant: -.numberpars $. -\-acl <<number>> <<length>>-\: A line of this form is present for every ACL -variable that is not empty. The number identifies the variable; the -\acl@_c\*x*\$$\ variables are numbered 0--9 and the \acl@_m\*x*\$$\ variables -are numbered 10--19. The length is the length of the data string for the -variable. The string itself starts at the beginning of the next line, and is -followed by a newline character. It may contain internal newlines. -.nextp -.em -\-active@_hostname <<hostname>>-\: This is present if, when the message was -received over SMTP, the value of \$smtp@_active@_hostname$\ was different to -the value of \$primary@_hostname$\. -.nem -.nextp -\-allow@_unqualified@_recipient-\: This is present if unqualified recipient -addresses are permitted in header lines (to stop such addresses from being -qualified if rewriting occurs at transport time). Local messages that were -input using \-bnq-\ and remote messages from hosts that match -\recipient@_unqualified@_hosts\ set this flag. -.nextp -\-allow@_unqualified@_sender-\: This is present if unqualified sender -addresses are permitted in header lines (to stop such addresses from being -qualified if rewriting occurs at transport time). Local messages that were -input using \-bnq-\ and remote messages from hosts that match -\sender@_unqualified@_hosts\ set this flag. -.nextp -\-auth@_id <<text>>-\: The id information for a message received on an -authenticated SMTP connection -- the value of the \$authenticated@_id$\ -variable. -.nextp -\-auth@_sender <<address>>-\: The address of an authenticated sender -- the -value of the \$authenticated@_sender$\ variable. -.nextp -\-body@_linecount <<number>>-\: This records the number of lines in the body of -the message, and is always present. -.nextp -.em -\-body@_zerocount <<number>>-\: This records the number of binary zero bytes in -the body of the message, and is present if the number is greater than zero. -.nem -.nextp -\-deliver@_firsttime-\: This is written when a new message is first added to -the spool. When the spool file is updated after a deferral, it is omitted. -.nextp -.index frozen messages||spool data -\-frozen <<time>>-\: The message is frozen, and the freezing happened at -<<time>>. -.nextp -\-helo@_name <<text>>-\: This records the host name as specified by a remote -host in a \\HELO\\ or \\EHLO\\ command. -.nextp -\-host@_address <<address>>.<<port>>-\: This records the IP address of the host -from which the message was received and the remote port number that was used. -It is omitted for locally generated messages. -.nextp -\-host@_auth <<text>>-\: If the message was received on an authenticated SMTP -connection, this records the name of the authenticator -- the value of the -\$sender@_host@_authenticated$\ variable. -.nextp -\-host@_lookup@_failed-\: This is present if an attempt to look up the sending -host's name from its IP address failed. It corresponds to the -\$host@_lookup@_failed$\ variable. -.nextp -.index DNS||reverse lookup -.index reverse DNS lookup -\-host@_name <<text>>-\: This records the name of the remote host from which -the message was received, if the host name was looked up from the IP address -when the message was being received. It is not present if no reverse lookup was -done. -.nextp -\-ident <<text>>-\: For locally submitted messages, this records the login of -the originating user, unless it was a trusted user and the \-oMt-\ option was -used to specify an ident value. For messages received over TCP/IP, this records -the ident string supplied by the remote host, if any. -.nextp -\-interface@_address <<address>>.<<port>>-\: This records the IP address of the -local interface and the port number through which a message was received from a -remote host. It is omitted for locally generated messages. -.nextp -\-local-\: The message is from a local sender. -.nextp -\-localerror-\: The message is a locally-generated bounce message. -.nextp -\-local@_scan <<string>>-\: This records the data string that was -returned by the \*local@_scan()*\ function when the message was received -- the -value of the \$local@_scan@_data$\ variable. It is omitted if no data was -returned. -.nextp -\-manual@_thaw-\: The message was frozen but has been thawed manually, that is, -by an explicit Exim command rather than via the auto-thaw process. -.nextp -\-N-\: A testing delivery process was started using the \-N-\ option to -suppress any actual deliveries, but delivery was deferred. At any further -delivery attempts, \-N-\ is assumed. -.nextp -\-received@_protocol-\: This records the value of the \$received@_protocol$\ -variable, which contains the name of the protocol by which the message was -received. -.nextp -\-sender@_set@_untrusted-\: The envelope sender of this message was set by an -untrusted local caller (used to ensure that the caller is displayed in queue -listings). -.nextp -.em -\-spam@_score@_int-\: If a message was scanned by SpamAssassin, this is -present. It records the value of \$spam@_score@_int$\. -.nem -.nextp -\-tls@_certificate@_verified-\: A TLS certificate was received from the client -that sent this message, and the certificate was verified by the server. -.nextp -\-tls@_cipher <<cipher name>>-\: When the message was received over an -encrypted connection, this records the name of the cipher suite that was used. -.nextp -\-tls@_peerdn <<peer DN>>-\: When the message was received over an encrypted -connection, and a certificate was received from the client, this records the -Distinguished Name from that certificate. -.endp - -Following the options there is a list of those addresses to which the message -is not to be delivered. This set of addresses is initialized from the command -line when the \-t-\ option is used and \extract__addresses__remove__arguments\ -is set; otherwise it starts out empty. Whenever a successful delivery is made, -the address is added to this set. The addresses are kept internally as a -balanced binary tree, and it is a representation of that tree which is written -to the spool file. If an address is expanded via an alias or forward file, the -original address is added to the tree when deliveries to all its child -addresses are complete. - -If the tree is empty, there is a single line in the spool file containing just -the text `XX'. Otherwise, each line consists of two letters, which are either Y -or N, followed by an address. The address is the value for the node of the -tree, and the letters indicate whether the node has a left branch and/or a -right branch attached to it, respectively. If branches exist, they immediately -follow. Here is an example of a three-node tree: -.display asis -YY darcy@austen.fict.example -NN alice@wonderland.fict.example -NN editor@thesaurus.ref.example -.endd -After the non-recipients tree, there is a list of the message's recipients. -This is a simple list, preceded by a count. It includes all the original -recipients of the message, including those to whom the message has already been -delivered. In the simplest case, the list contains one address per line. For -example: -.display asis -4 -editor@thesaurus.ref.example -darcy@austen.fict.example -rdo@foundation -alice@wonderland.fict.example -.endd -However, when a child address has been added to the top-level addresses as a -result of the use of the \one@_time\ option on a \%redirect%\ router, each line -is of the following form: -.display -<<top-level address>> <<errors@_to address>> <<length>>,<<parent number>>@#<<flag bits>> -.endd -The 01 flag bit indicates the presence of the three other fields that follow -the top-level address. Other bits may be used in future to support additional -fields. The <<parent number>> is the offset in the recipients list of the -original parent of the `one time' address. The first two fields are the -envelope sender that is associated with this address and its length. If the -length is zero, there is no special envelope sender (there are then two space -characters in the line). A non-empty field can arise from a \%redirect%\ router -that has an \errors@_to\ setting. - - -A blank line separates the envelope and status information from the headers -which follow. A header may occupy several lines of the file, and to save effort -when reading it in, each header is preceded by a number and an identifying -character. The number is the number of characters in the header, including any -embedded newlines and the terminating newline. The character is one of the -following: -.display -.tabs 9 -<<blank>> $t $rm{header in which Exim has no special interest} -#B $t $rm{::Bcc:: header} -#C $t $rm{::Cc:: header} -#F $t $rm{::From:: header} -#I $t $rm{::Message-id:: header} -#P $t $rm{::Received:: header -- P for `postmark'} -#R $t $rm{::Reply-To:: header} -#S $t $rm{::Sender:: header} -#T $t $rm{::To:: header} -#* $t $rm{replaced or deleted header} -.endd -Deleted or replaced (rewritten) headers remain in the spool file for debugging -purposes. They are not transmitted when the message is delivered. Here is a -typical set of headers: -.display asis -111P Received: by hobbit.fict.example with local (Exim 4.00) - id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 -049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> -038* X-rewrote-sender: bb@hobbit.fict.example -042* From: Bilbo Baggins <bb@hobbit.fict.example> -049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> -099* To: alice@wonderland.fict.example, rdo@foundation, - darcy@austen.fict.example, editor@thesaurus.ref.example -109T To: alice@wonderland.fict.example, rdo@foundation.fict.example, - darcy@austen.fict.example, editor@thesaurus.ref.example -038 Date: Fri, 11 May 2001 10:28:59 +0100 -.endd -The asterisked headers indicate that the envelope sender, ::From:: header, and -::To:: header have been rewritten, the last one because routing expanded the -unqualified domain \*foundation*\. - -. -. -. -. -. ============================================================================ -.chapter Adding new drivers or lookup types -.set runningfoot "adding drivers" -.index adding drivers -.index new drivers, adding -.index drivers||adding new -The following actions have to be taken in order to add a new router, transport, -authenticator, or lookup type to Exim: -.numberpars -Choose a name for the driver or lookup type that does not conflict with any -existing name; I will use `newdriver' in what follows. -.nextp -Add to \(src/EDITME)\ the line -.display -<<type>>@_NEWDRIVER=yes -.endd -where <<type>> is \\ROUTER\\, \\TRANSPORT\\, \\AUTH\\, or \\LOOKUP\\. If the -code is not to be included in the binary by default, comment this line out. You -should also add any relevant comments about the driver or lookup type. -.nextp -Add to \(src/config.h.defaults)\ the line -.display -@#define <<type>>@_NEWDRIVER -.endd -.nextp -Edit \(src/drtables.c)\, adding conditional code to pull in the private header -and create a table entry as is done for all the other drivers and lookup types. -.nextp -Edit \(Makefile)\ in the appropriate sub-directory (\(src/routers)\, -\(src/transports)\, \(src/auths)\, or \(src/lookups)\); add a line for the new -driver or lookup type and add it to the definition of OBJ. -.nextp -Create \(newdriver.h)\ and \(newdriver.c)\ in the appropriate sub-directory of -\(src)\. -.nextp -Edit \(scripts/MakeLinks)\ and add commands to link the \(.h)\ and \(.c)\ files -as for other drivers and lookups. -.endp -Then all you need to do is write the code! A good way to start is to make a -proforma by copying an existing module of the same type, globally changing all -occurrences of the name, and cutting out most of the code. Note that any -options you create must be listed in alphabetical order, because the tables are -searched using a binary chop procedure. - -There is a \(README)\ file in each of the sub-directories of \(src)\ describing -the interface that is expected. - -. -. -. -. -. ============================================================================ -. Fudge for the index page number. We want it to be on a right-hand page. -. -.set indexpage ~~sys.pagenumber + 1 -.if even ~~indexpage -.set indexpage ~~indexpage + 1 -.fi -.if ~~sgcal -.%index Index$e~~indexpage-- -.fi -. -. -. End of Exim specification |