X-Git-Url: https://git.exim.org/users/heiko/exim.git/blobdiff_plain/495ae4b01f36d0d8bb0e34a1d7263c2b8224aa4a..75fa1910b6e49a953492766459e6b052f9b6b88e:/doc/doc-src/spec.src diff --git a/doc/doc-src/spec.src b/doc/doc-src/spec.src index 41a2ba13b..dd7685689 100644 --- a/doc/doc-src/spec.src +++ b/doc/doc-src/spec.src @@ -1,9 +1,9 @@ -. $Cambridge: exim/doc/doc-src/spec.src,v 1.1 2004/10/07 15:04:35 ph10 Exp $ +. $Cambridge: exim/doc/doc-src/spec.src,v 1.8 2005/02/17 11:58:25 ph10 Exp $ . -.set version "4.40" -.set previousversion "4.30" -.set versionmonth "July" -.set versionyear "2004" +.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 @@ -138,7 +138,8 @@ .blank .endm -.macro startconf +.macro startconf "" +.set confsection "~~1" .newline .push .if ~~sys.fancy @@ -166,8 +167,13 @@ .else .index \~~1\ option .fi +.if "~~confsection" == "" +.set inssect "" +.else +.set inssect "$rm{Use:} $it{~~confsection}###" +.fi .tempindent 0 -\**~~1**\ $c $rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} +\**~~1**\ $c ~~inssect$rm{Type:} $it{~~2} $e $rm{Default:} $it{~~3} .blank .endm @@ -181,6 +187,7 @@ .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} @@ -188,10 +195,12 @@ .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} @@ -303,9 +312,9 @@ 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. +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 @@ -333,6 +342,7 @@ 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 @@ -360,7 +370,7 @@ introductory, and tutorial material can be found in a book entitled [(A HREF="http://www.uit.co.uk/exim-book/")] $it{The Exim SMTP Mail Server}, [(/A)] -published by UIT Cambridge. +published by UIT Cambridge. .else $it{The Exim SMTP Mail Server}, published by UIT Cambridge (\?http://www.uit.co.uk/exim-book/?\). @@ -376,11 +386,19 @@ published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) .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. However, -specifications of new features that are not yet in this manual are placed in -the file \(doc/NewStuff)\ in the Exim distribution. All changes to the program -(whether new features, bug fixes, or other kinds of change) are noted briefly -in the file called \(doc/ChangeLog)\. +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 @@ -391,6 +409,11 @@ directory are: \(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} @@ -402,16 +425,34 @@ 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, and mailing list +.section FTP and web sites .index web site .index FTP site -The primary distribution site for Exim is an FTP site, whose contents are -described in \*Where to find the Exim distribution*\ below. In addition, -there is a web site at \?http://www.exim.org?\ by courtesy of Energis Squared, -formerly Planet Online Ltd, who are situated in the UK. The site is mirrored in -a number of other countries; links to the mirrors are listed on the home page. -The web site contains the Exim distribution, and you can also find the -documentation and the +.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")] @@ -420,15 +461,31 @@ FAQ .if ~~html [(/A)] .fi -online there, as well as other relevant material. +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 -Energis Squared also provide resources for the following mailing lists: +.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 @@ -463,6 +520,7 @@ 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 @@ -474,18 +532,23 @@ The master ftp site for the Exim distribution is .fi \?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim?\ .endd -Within that directory there are subdirectories called \(exim3)\ (for previous -Exim 3 distributions), \(exim4)\ (for the latest Exim 4 distributions), and -\(Testing)\ for occasional testing versions. Those mirror sites that I know -about are listed in the file +This is mirrored by .display rm .if ! ~~sys.fancy .indent 0 .fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Mirrors?\ +\?ftp://ftp.exim.org/pub/exim?\ .endd -In the \(exim4)\ subdirectory, the current release can always be found in -files called +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)\ @@ -496,33 +559,17 @@ 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 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: -.display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/Public-Key?\ -.endd -The signatures for the tar bundles are in: +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 - -When there is only a small amount of change from one release to the next, a -patch file may be provided, with a final component name of the form -.display rm -\(exim-patch-$it{n.nn}-$it{m.mm}.gz)\ -.endd -For each released version, the log of changes is made separately available in -the directory -.display rm -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/ChangeLogs?\ -.endd -so that it is possible to find out what has changed without having to download -the entire distribution. +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 @@ -538,13 +585,10 @@ 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 from +The FAQ is available for downloading in two different formats in these files: .display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.txt.gz?\ -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/FAQ.html.tar.gz?\ +\(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 @@ -555,32 +599,17 @@ 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: -.display rm -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/WishList?\ -.endd -Items are removed from the list if they get implemented. +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 -.display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/Contrib/?\ -.endd -which contains miscellaneous files contributed to the Exim community by Exim -users. There is also a collection of contributed configuration examples in -.display rm -.if ! ~~sys.fancy -.indent 0 -.fi -\?ftp://ftp.csx.cam.ac.uk/pub/software/email/exim/exim4/config.samples.tar.gz?\ -.endd -These samples are referenced from the FAQ. - +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 @@ -615,9 +644,13 @@ 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 -Although Exim does have some 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. +.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 @@ -658,11 +691,12 @@ 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. 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. +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 @@ -745,18 +779,18 @@ the Exim documentation, `spool' is always used in the first sense. 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) 2003 -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?\. +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 Planet Online Ltd. which contains the -following statements: +contributed by Nigel Metheringham of (at the time he contributed it) Planet +Online Ltd. which contains the following statements: .rule .push .if ~~sgcal @@ -786,7 +820,7 @@ It does not link against an external cdb library. .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 +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. @@ -848,7 +882,7 @@ $it{This product includes software developed by Computing Services at Carnegie Mellon University (\?http://www.cmu.edu/computing/?\).} .newline .pop -.endp +.endp .if ~~sgcal .cancelflag $npbracket .flag $npbracket "(" ")" @@ -904,6 +938,13 @@ 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 @@ -936,23 +977,37 @@ specifying policy controls on incoming mail: .numberpars $. .index ~~ACL||introduction Exim 4 (unlike previous versions of Exim) implements policy controls on -incoming SMTP mail by means of \*Access Control Lists*\ (ACLs). Each list is a +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. 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 +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. @@ -961,10 +1016,10 @@ at the start of every delivery process. .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 +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 @@ -974,10 +1029,10 @@ needed to support this, and the separate document entitled .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 +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 +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. @@ -996,8 +1051,8 @@ 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 +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. @@ -1005,8 +1060,8 @@ not case-sensitive. 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 +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 @@ -1081,11 +1136,11 @@ 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 +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. @@ -1169,7 +1224,7 @@ 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 +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. @@ -1203,12 +1258,12 @@ 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 +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 +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. @@ -1236,7 +1291,7 @@ routers that are configured in various ways. .if ~~sys.fancy .figure "Routing an address" rm .indent 0 -.call aspic +.call aspic -sgcal -nv centre ~~sys.linelength; magnify 0.8; boundingbox 30; @@ -1348,7 +1403,7 @@ 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 +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 @@ -1362,19 +1417,19 @@ 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 +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 +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 +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. @@ -1392,7 +1447,7 @@ 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, +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, @@ -1436,15 +1491,15 @@ 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 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' +when the relevant conditions are met. The \%redirect%\ router has a `fail' facility for this purpose. @@ -1464,18 +1519,18 @@ 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 +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 +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 +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 @@ -1498,14 +1553,14 @@ that uses the variables \$local@_part$\, \$local@_part@_prefix$\, and .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 +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 +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 @@ -1586,10 +1641,8 @@ 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. -.em -The order in which deliveries are done is not defined, except that all local +The order in which deliveries are done is not defined, except that all local deliveries happen before any remote deliveries. -.nem .nextp .index queue runner When it encounters a local delivery during a queue run, Exim checks its retry @@ -1661,7 +1714,7 @@ 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, +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 @@ -1727,7 +1780,7 @@ creates a directory with the name of the current release (for example, .if !~~sys.fancy && ~~sgcal .tabs 16 .else -.tabs 22 +.tabs 22 .fi \(ACKNOWLEDGMENTS)\ $t contains some acknowledgments .newline @@ -1861,10 +1914,10 @@ in one of these lines: DBMLIB = -ldb DBMLIB = -ltdb .endd -Settings like that will work if the DBM library is installed in the standard +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 +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 @@ -1903,6 +1956,18 @@ 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 @@ -1921,11 +1986,11 @@ 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 +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. @@ -1933,10 +1998,10 @@ 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 +all. After installing \libiconv\, you should add .display asis -HAVE_ICONV=yes -.endd +HAVE_ICONV=yes +.endd to your \(Local/Makefile)\ and rebuild Exim. @@ -1948,11 +2013,12 @@ to your \(Local/Makefile)\ and rebuild Exim. .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-\ command line option). +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 +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. @@ -1980,12 +2046,12 @@ 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 +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 +specified in \\INCLUDE\\. Details of how to configure Exim to make use of TLS are given in chapter ~~CHAPTLS. @@ -2027,13 +2093,16 @@ 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. -IPv6 is still changing rapidly. Two different types of DNS record for handling -IPv6 addresses have been defined. AAAA records are already in use, and are -currently seen as the `mainstream', but another record type called A6 is being -argued about. Its status is currently `experimental'. Exim has support for A6 -records, but this is included only if you set \\SUPPORT@_A6=YES\\ in -\(Local/Makefile)\. - +.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 @@ -2045,10 +2114,8 @@ For example, on a Sun system running Solaris 8, the directory .index symbolic link||to source files Symbolic links to relevant source files are installed in the build directory. -.em -\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the +\**Warning**\: The \-j-\ (parallel) flag must not be used with \*make*\; the building process fails if it is set. -.nem 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 @@ -2118,22 +2185,22 @@ 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-<>)\, or to add any new definitions, you do not +or in \(OS/Makefile-<>)\, 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 +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 +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 +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 @@ -2256,7 +2323,7 @@ variables of the same name, preceded by \\EXIMON@_\\. For example, setting 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)\. +\(Local/Makefile)\. Exim's run time configuration file is named by the \\CONFIGURE@_FILE\\ setting .index \\CONFIGURE@_FILE\\ @@ -2304,10 +2371,10 @@ 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 +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, +For backwards compatibility, \\ROOT\\ is used if \\DESTDIR\\ is not set, but this usage is deprecated. .index installing Exim||what is not installed @@ -2355,8 +2422,8 @@ installed binary. 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, +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 @@ -2395,7 +2462,7 @@ 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 +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, @@ -2538,8 +2605,8 @@ 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 +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. @@ -2564,8 +2631,8 @@ 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 +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 @@ -2653,9 +2720,9 @@ 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 +\**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. @@ -2673,7 +2740,7 @@ 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 +The same output is generated if the Exim binary is called with no options and no arguments. .option B <> @@ -2715,7 +2782,7 @@ 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 +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. @@ -2730,15 +2797,22 @@ the controlling terminal, even when no debugging is specified. 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. Long 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. +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 -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. +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 #<> .index system filter||testing @@ -2753,18 +2827,28 @@ system filters are recognized. .index forward file||testing .index testing||forward file .index Sieve filter||testing -This option runs Exim in 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. If a -system filter file is being tested, \-bF-\ should be used instead of \-bf-\. If -the test file does not begin with -one of the special lines +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 > $t $rm{default is the qualify domain} -\-bfl-\ $t <> $t $rm{default is the logged in user} -\-bfp-\ $t <> $t $rm{default is null} -\-bfs-\ $t <> $t $rm{default is null} -.endd -The local part should always be set to the incoming address with any prefix or +be set by means of additional command line options (see the next four options). + +.em +.option bfd #<> +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 #<> +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 #<> +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 #<> +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 #<> .index testing||incoming SMTP .index SMTP||testing incoming @@ -2809,10 +2903,16 @@ after a full stop. For example: 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 +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 @@ -2821,7 +2921,7 @@ 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, +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 @@ -2834,9 +2934,9 @@ output just states whether a given recipient address from a given host is acceptable or not. See section ~~SECTcheckaccess. .option bhc #<> -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. +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 @@ -2870,7 +2970,7 @@ 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 +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 @@ -2891,7 +2991,7 @@ From sender Fri, 5 Jan 97 12:55:01 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. +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 @@ -2903,8 +3003,8 @@ trusted user for the sender of a message to be set in this way. 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 +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 @@ -2937,7 +3037,7 @@ mysql_servers = .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 +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) @@ -3107,7 +3207,7 @@ More details of input using batched SMTP are given in section .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. +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. @@ -3122,10 +3222,10 @@ 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 +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 @@ -3133,18 +3233,24 @@ the listening daemon. .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. +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. 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. +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 @@ -3153,7 +3259,7 @@ 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, +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 @@ -3170,6 +3276,17 @@ 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 @@ -3183,11 +3300,18 @@ 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. 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. +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 @@ -3222,20 +3346,25 @@ 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. -This option is not set by default. +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 +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 @@ -3243,7 +3372,7 @@ 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 +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 @@ -3261,20 +3390,20 @@ specified by this option. .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. +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 +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 +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' ... @@ -3315,7 +3444,7 @@ 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)} +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} @@ -3334,14 +3463,12 @@ verify $t $rm{address verification logic} all $t $rm{all of the above, and also \-v-\} .endd -.em .index resolver, debugging output .index DNS||resolver, debugging output -The \"resolver"\ option produces output only if the DNS resolver was compiled +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. -.nem The default (\-d-\ with no argument) omits \"expand"\, \"filter"\, \"interface"\, \"load"\, \"memory"\, \"pid"\, \"resolver"\, and \"timestamp"\. @@ -3357,9 +3484,17 @@ 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 <> +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 +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. @@ -3397,15 +3532,20 @@ between \-F-\ and the <> is optional. 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. In the absence of \-f-\, or if the caller is not allowed to -use it, the sender of a local message is set to the caller's login name at the -default qualify domain. +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, 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: +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 @@ -3451,7 +3591,7 @@ command in Solaris 2.4 uses it. See also \-ti-\. 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. +\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 @@ -3486,8 +3626,8 @@ 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 +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 #<> <> @@ -3550,7 +3690,7 @@ user. .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. +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. @@ -3642,7 +3782,7 @@ This option is interpreted by Sendmail to mean `no aliasing'. It is ignored by Exim. .option O #<> -This option is interpreted by Sendmail to mean `set option`. It is ignored by +This option is interpreted by Sendmail to mean `set option`. It is ignored by Exim. .option oA #<> @@ -3664,10 +3804,15 @@ transport. If <> is omitted, the limit is set to 1. .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 delivery -process for each message received, but does not wait for the delivery process -to complete. This is the default action if none of the \-od-\ options are -present. +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-\ @@ -3681,9 +3826,21 @@ 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. -However, like \-odb-\, this option has no effect if \queue@_only@_override\ is +.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. @@ -3703,7 +3860,7 @@ 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-\. +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. @@ -3758,10 +3915,8 @@ effect as \-oem-\. .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. -.em -Otherwise, a single dot does terminate, though Exim does no special processing +Otherwise, a single dot does terminate, though Exim does no special processing for other lines that start with a dot. -.nem This option is set by default if Exim is called as \*rmail*\. See also \-ti-\. .option oitrue @@ -3772,7 +3927,7 @@ This option is treated as synonymous with \-oi-\. 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-\, +\-bh-\, \-be-\, \-bf-\, \-bF-\, \-bt-\, or \-bv-\ testing options. In other circumstances, they are ignored unless the caller is trusted. @@ -3799,7 +3954,7 @@ name). See chapter ~~CHAPSMTPAUTH for a discussion of SMTP authentication. .option oMai #<> .index authentication||id, specifying for local message See \-oMa-\ above for general remarks about the \-oM-\ options. The \-oMai-\ -option sets the +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 @@ -3809,7 +3964,7 @@ ids. .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$\. +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. @@ -3819,31 +3974,33 @@ authenticated senders. 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, +The interface address is placed in \$interface@_address$\ and the port number, if present, in \$interface@_port$\. .option oMr #<> .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 -in \$received@_protocol$\. -However, this applies only when \-bs-\ is not used. For interactive SMTP input, -the protocol is determined by whether \\EHLO\\ or \\HELO\\ is used, and is -always either `local-esmtp' or `local-smtp'. For \-bS-\ (batch SMTP) however, -the protocol can be set by \-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 #<> .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 +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 #<> .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$\. +in \$sender@_ident$\. The default setting for local callers is the login id of the calling process. .option om @@ -3860,7 +4017,7 @@ that means. .option oP #<> .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 +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, @@ -3906,11 +4063,10 @@ 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. -.em .option p<>:<> For compatibility with Sendmail, this option is equivalent to -.display +.display -oMr <> -oMs <> .endd It sets the incoming protocol and host name (for trusted callers). The @@ -3918,7 +4074,6 @@ 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). -.nem .option q .index queue runner||starting manually @@ -3966,7 +4121,7 @@ appear in the correct order. Each flag is described in a separate item below. 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. +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 @@ -3988,7 +4143,7 @@ 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 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 @@ -4041,7 +4196,7 @@ daemon at system boot time is to use a command such as 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 +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 <>#<> @@ -4098,13 +4253,11 @@ 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. -.em .option Tqt#<> 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. -.nem +of explicit `queue times' so that various warning/retry features can be +tested. .option t .index recipient||extracting from header lines @@ -4135,10 +4288,10 @@ 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 +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 +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 @@ -4152,24 +4305,18 @@ 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 +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. It makes it -possible to support legacy clients that do not support the \\STARTTLS\\ -command, but instead expect to start up a TLS session as soon as a connection -to the server is established. These clients use a special port (usually called -the `ssmtp' port) instead of the normal SMTP port 25. The \-tls-on-connect-\ -option can be used to run Exim in this way from \*inetd*\, and it can also be -used to run a special daemon that operates in this manner (use \-oX-\ to -specify the port). However, although it is possible to run one daemon that -listens on several ports, it is not possible to have some of them operate one -way and some the other. With only a few clients that need the legacy support, a -convenient approach is to use a daemon for normal SMTP (with or without -\\STARTTLS\\) and \*inetd*\ with \-tls-on-connect-\ for the legacy clients. +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 @@ -4208,11 +4355,24 @@ option. .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 +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 @@ -4221,38 +4381,31 @@ 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, +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 user that is specified at compile time by the \\CONFIGURE@_OWNER\\ -option (if set). +or by the \\CONFIGURE@_GROUP\\ option. .nem -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. -\**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 +\**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. - -.index configuration file||errors in -.index error||in configuration file -.index return code||for bad configuration -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. +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 @@ -4260,7 +4413,7 @@ The message is also written to the panic log. 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 +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-\. @@ -4272,7 +4425,7 @@ 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 +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 @@ -4282,7 +4435,7 @@ 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 +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 @@ -4293,7 +4446,7 @@ 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 +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 @@ -4334,17 +4487,26 @@ 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 +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. Trailing -white space after the backslash is ignored, and leading white space at the -start of continuation lines is also ignored. +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. @@ -4373,8 +4535,8 @@ or .display @.include@_if@_exists <> .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 +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 @@ -4389,8 +4551,8 @@ for example: hosts_lookup = a.b.c \ .include /some/file .endd -Include processing happens -after +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. @@ -4455,9 +4617,9 @@ by root or the Exim user. .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). +\".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 @@ -4546,7 +4708,7 @@ 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 +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. @@ -4582,7 +4744,7 @@ the following letters, with no intervening white space: .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 +Exim does not restrict the values; it is perfectly acceptable, for example, to specify `90m' instead of `1h30m'. @@ -4655,12 +4817,12 @@ either consist entirely of digits, or be a name that can be looked up using the .index format||list item in configuration .index string list, definition .rset SECTlistconstruct "~~chapter.~~section" -The data for some configuration options is a colon-separated list of items. -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. +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 @@ -4673,15 +4835,14 @@ example, the list local_interfaces = 127.0.0.1 : ::::1 .endd contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address -@:@:1. IPv6 addresses are going to become more and more common as the new -protocol gets more widely deployed. +@:@:1. .index list||separator, changing .index IPv6||addresses in lists -Doubling their colons 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: +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 @@ -4690,6 +4851,33 @@ This facility applies to all lists, with the exception of the list in 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 @@ -4711,7 +4899,7 @@ localuser: check_local_user transport = local_delivery .endd -For each driver instance, you specify which Exim code module it uses -- by the +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 @@ -4824,7 +5012,7 @@ 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. +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 @@ -4854,7 +5042,7 @@ The next configuration line is a genuine option setting: 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 +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 @@ -4880,14 +5068,12 @@ addresses of the form \*user@@[10.11.12.13]*\ that is, with a `domain literal' .display asis # allow_domain_literals .endd -.em 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 +people believe there are circumstances (for example, messages addressed to \*postmaster*\) where domain literals are still useful. -.nem The next configuration line is a kind of trigger guard: .display asis @@ -4899,7 +5085,7 @@ 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 +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 @@ -4912,7 +5098,7 @@ 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, +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. @@ -5009,8 +5195,8 @@ deny domains = +local_domains deny domains = !+local_domains local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ -.endd -These statements are concerned with local parts that contain any of the +.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 @@ -5073,8 +5259,8 @@ require verify = sender 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 +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 @@ -5198,8 +5384,8 @@ 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 +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 @@ -5211,7 +5397,7 @@ 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 +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 @@ -5234,8 +5420,8 @@ 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 +\(/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. @@ -5259,7 +5445,7 @@ 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 +\(.forward)\ are interpreted as redirection data (see chapter ~~CHAPredirect for more details). .index Sieve filter||enabling in default router @@ -5272,15 +5458,15 @@ 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. +command. There are two reasons for doing this: .numberpars -Whether or not a local user has a \(.forward)\ file is not really relevant when +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. +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. @@ -5439,7 +5625,7 @@ $it{Mastering Regular Expressions} .fi (O'Reilly, ISBN 0-596-00289-0). -The documentation for the syntax and semantics of the regular expressions that +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 @@ -5456,9 +5642,8 @@ 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. -.em -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 +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 @@ -5472,26 +5657,25 @@ 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 +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, +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*\. +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.) -.nem .section Testing regular expressions @@ -5552,8 +5736,8 @@ 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. +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 @@ -5563,7 +5747,7 @@ 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. +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}} @@ -5577,31 +5761,31 @@ like this: 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 +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 +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: +domain1: domain2: .endd -Any data that follows the keys is not relevant when checking that the domain +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 +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 +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 +above. The syntax requirements for the two cases are described in chapters ~~CHAPexpand and ~~CHAPdomhosaddlists, respectively. .section Lookup types @@ -5610,8 +5794,11 @@ above. The syntax requirements for the two cases are described in chapters 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. The lookup type determines how the file is -searched. +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. @@ -5664,11 +5851,11 @@ 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 +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 +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 @@ -5697,7 +5884,6 @@ this lookup can be used to support virtual domains is given in section .nextp .index lookup||iplsearch .index iplsearch lookup type -.em \%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 @@ -5712,17 +5898,16 @@ being interpreted as a key terminator. For example: 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 +`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 +\**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). -.nem .nextp .index linear search @@ -5746,16 +5931,14 @@ that the keys in an \%lsearch%\ file are literal strings. There is no wildcarding of any kind. .index lookup||lsearch, colons in keys -In most \%lsearch%\ files, keys are not required to contain colons -.em -or @# characters, or -.nem -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. +.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 @@ -5773,13 +5956,13 @@ aliases; the full map names must be used. \%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, +\%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 `begins with'. For example: +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 @@ -5790,8 +5973,8 @@ example, for \%wildlsearch%\: .display asis ^\N\d+\.a\.b\N data for .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 +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 .a.b @@ -5804,8 +5987,8 @@ 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%\ +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 @@ -5825,14 +6008,17 @@ lookup types support only literal keys. .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 +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 a record whose domain name is the supplied -query. The resulting data is the contents of the record. See section -~~SECTdnsdb. +\%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 @@ -5863,6 +6049,7 @@ 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%\ @@ -5936,16 +6123,16 @@ 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 +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 +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. @@ -5970,14 +6157,14 @@ then when partial matching is enabled this is matched by (amongst others) 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 +\**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 +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. @@ -6003,11 +6190,11 @@ the minimum number of non-$*$ components is two: *.fict.example .endd As soon as one key in the sequence is successfully looked up, the lookup -finishes. +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 +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: @@ -6015,7 +6202,7 @@ parentheses instead of the hyphen after `partial'. For example: 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 +\"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 @@ -6034,7 +6221,7 @@ 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 +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. @@ -6057,20 +6244,24 @@ subject key is always followed by a dot. .section Lookup caching -.index lookup||caching +.index lookup||caching .index caching||lookup data -An Exim process -caches the most recent lookup result on a per-file basis for single-key -lookup types, and keeps the relevant files open. 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. - -For query-style lookups, a single data cache per lookup type is kept. The files -are closed and the caches flushed at strategic points during delivery -- for -example, after all routing is complete. +.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 @@ -6109,36 +6300,111 @@ lookups, since no quoting is ever needed in their key strings. .index dnsdb lookup .index lookup||dnsdb .index DNS||as a lookup type -The \%dnsdb%\ lookup type uses the DNS as its database. A query consists of a -record type and a domain name, separated by an equals sign. For example, an -expansion string could contain: +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 supported record types are A, CNAME, MX, NS, PTR, SRV, and TXT, -.nem -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, the -address should be given as normal; it is converted to the necessary inverted -format internally. For example: +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 MX record||in \%dnsdb%\ lookup -For MX records, both the preference value and the host name are returned, -separated by a space. -.em .index SRV record||in \%dnsdb%\ lookup -For SRV records, the priority, weight, port, and host name are returned, -separated by spaces. For any record type, -.nem -if multiple records are found (or, for A6 lookups, if a single record leads to -multiple addresses), the data is returned as a concatenation, separated by -newlines. The order, of course, depends on the DNS resolver. +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 @@ -6201,7 +6467,7 @@ encrypted TLS connection is used. .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 +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 @@ -6241,7 +6507,7 @@ 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; } +${quote_ldap_dn: a(bc)*, a; } .endd yields .display asis @@ -6251,7 +6517,7 @@ Removing the URL quoting, this is (with a trailing space): .display asis \ a(bc)*\, a\\;\ .endd -There are some further comments about quoting in the section on LDAP +There are some further comments about quoting in the section on LDAP authentication below. .section LDAP connections @@ -6318,7 +6584,7 @@ specified, an error is diagnosed. However, if there are more items in 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. +Using \"ldapi"\ with a host name causes an error. .endp Using \"ldapi"\ with no host or path in the query, and no setting of @@ -6332,21 +6598,37 @@ information to the server. To make this possible, the URL in an LDAP query may be preceded by any number of `<>=<>' 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: +them. The following names are recognized: .display -CONNECT $rm{set a connection timeout} -.newline 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', +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 @@ -6365,11 +6647,6 @@ 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. -The time limit for connection is given in seconds; zero means use the default. -This facility is available in Netscape SDK 4.1; it may not be available in -other LDAP implementations. Exim uses the given value if -\\LDAP@_X@_OPT@_CONNECT@_TIMEOUT\\ is defined in the LDAP headers. - 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 @@ -6378,7 +6655,7 @@ quoting has two advantages: 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. +It permits spaces inside \\USER=\\ DNs. .endp For example, a setting such as .display asis @@ -6386,9 +6663,9 @@ 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 +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} @@ -6408,10 +6685,10 @@ 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 +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 @@ -6563,7 +6840,11 @@ 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 @@ -6608,10 +6889,18 @@ general facilities that apply to all four kinds of list. .section Expansion of lists .index expansion||of lists -Each list is expanded as a single string before it is used. If the 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. +.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 @@ -6626,9 +6915,6 @@ 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. -After expansion, the list is split up into separate items for matching. -Normally, colon is used as the separator character, but this can be varied if -necessary, as described in section ~~SECTlistconstruct. .section Negated items in lists @@ -6658,9 +6944,9 @@ 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. +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 @@ -6712,7 +6998,7 @@ 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 +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. @@ -6775,7 +7061,7 @@ 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 +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 @@ -6785,7 +7071,7 @@ lists. So, if you have a setting such as domains = +local_domains .endd on several of your routers -or in several ACL statements, +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 @@ -6823,7 +7109,6 @@ auth_advertise_hosts = !host1 : !host2 .endd -.em .section Named list caching .index list||caching of named .index caching||named lists @@ -6850,7 +7135,6 @@ 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. -.nem .section Domain lists @@ -6861,7 +7145,7 @@ 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 host||name, matched in domain list .index \primary@_hostname\ .index domain list||matching primary host name .index @@ in a domain list @@ -6875,10 +7159,8 @@ in their names. .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. -.em +domain literal. In today's Internet, the use of domain literals is controversial. -.nem .nextp .index @@mx@_any .index @@mx@_primary @@ -6893,17 +7175,16 @@ 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. -.em -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\ +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=<>"\, where <> is a list of IP addresses. These addresses are -ignored when processing the pattern (compare the \ignore@_target@_hosts\ option +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 @@ -6911,8 +7192,8 @@ domains = @mx_any/ignore=127.0.0.1 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 +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 @@ -6928,7 +7209,6 @@ involved, it is easiest to change the delimiter for the main list as well: domains = > style of item can also be used with a query-style -lookup, but in this case, the chaining facility is not available. The lookup +The @@@@<> 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 -.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, follwed 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 -For a single-key lookup type, Exim uses the complete address as the key. -Partial matching (section ~~SECTpartiallookup) cannot be used, and is ignored -if specified, with an entry being written to the panic log. - -.index @*@@ with single-key lookup -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 the next paragraph. -.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: +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:\ @@ -7543,12 +7838,15 @@ 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 pattern which -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. +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 @@ -7632,7 +7930,7 @@ 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 +below in section ~~SECTexpansionitems onwards. Backslash is used as an escape character, as described in the following section. @@ -7688,6 +7986,23 @@ 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 @@ -7725,8 +8040,8 @@ string easier to understand. .item "@$@{extract@{<>@}@{<>@}@{<>@}@{<>@}@}" .index expansion||extracting substrings by key -The key and <> are first expanded separately. -Leading and trailing whitespace is removed from the key (but not from any of +The key and <> 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 <> must be of the form: @@ -7756,19 +8071,14 @@ for example: .display @$@{extract@{Z@}@{A=... B=...@}@{@$value@} fail @} .endd -@{<>@} must be present for `fail' to be recognized. When this syntax -is used, if the extraction fails, the entire string expansion fails in a way -that can be detected by the code in Exim which 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 which is expanded. +This forces an expansion failure (see section ~~SECTforexpfai); @{<>@} +must be present for `fail' to be recognized. .item "@$@{extract@{<>@}@{<>@}@{<>@}@{<>@}@{<>@}@}" .index expansion||extracting substrings by number The <> argument must consist entirely of decimal digits, -apart from leading and trailing whitespace, which is ignored. +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 <> the field whose number is given as the first @@ -7797,12 +8107,12 @@ empty (for example, the fifth field above). .item "@$@{hash@{<>@}@{<>@}@{<>@}@}" .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 +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 <> and -<>. If you are using fixed values for these numbers, that is, if <> +The first two strings, after expansion, must be numbers. Call them <> and +<>. If you are using fixed values for these numbers, that is, if <> and <> do not change when they are expanded, you can use the simpler operator notation that avoids some of the braces: .display @@ -7810,7 +8120,7 @@ simpler operator notation that avoids some of the braces: .endd The second number is optional (in both notations). -If <> is greater than or equal to the length of the string, the expansion +If <> 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 <> by applying a hashing function to the string. The new string consists of characters taken from the first <> characters of the string @@ -7820,9 +8130,9 @@ abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 If <> 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"\ +@$@{hash@{3@}@{monty@}@} $rm{yields} \"jmg"\ +@$@{hash@{5@}@{monty@}@} $rm{yields} \"monty"\ +@$@{hash@{4@}@{62@}@{monty python@}@} $rm{yields} \"fbWx"\ .endd @@ -7842,11 +8152,12 @@ $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. +lines) may be present. -The difference between \rheader\, \bheader\, and \header\ is in the way the -data in the header line is interpreted. +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 @@ -7854,7 +8165,7 @@ processing at all, and without the removal of leading and trailing whitespace. \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. +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 @@ -7887,7 +8198,7 @@ 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 +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. @@ -7905,7 +8216,7 @@ 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.) +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 @@ -7920,10 +8231,10 @@ for the \rheader\ expansion. .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. +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 +\"@$@{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: @@ -7948,31 +8259,44 @@ headers_add = \ {${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 +::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 <> @{<>@}@{<>@}@}" .index expansion||conditional If <> is true, <> is expanded and replaces the whole item; -otherwise <> is used. For example, +otherwise <> 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. The -available conditions are described in section ~~SECTexpcond below. +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@{<>@}@{<>@}@}" .index expansion||string truncation -The \length\ item is used to extract the initial portion of a string. Both +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, <>, say. If you are using a fixed value for the number, that is, if <> does not change when expanded, you can use the simpler operator notation that avoids some of @@ -7981,7 +8305,7 @@ the braces: @$@{length@_<>:<>@} .endd The result of this item is either the first <> characters or the whole -of <>, whichever is the shorter. Do not confuse \length\ with +of <>, whichever is the shorter. Do not confuse \length\ with \strlen\, which gives the length of a string. @@ -8006,10 +8330,10 @@ If the lookup succeeds, <> 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, <> is expanded and replaces -the entire item. If @{<>@} is omitted, the replacement is null on -failure. Alternatively, <> can itself be a nested lookup, thus -providing a mechanism for looking up a default value when the original lookup -fails. +the entire item. If @{<>@} is omitted, the replacement is the empty +string on failure. If <> 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 <>, \$value$\ contains the data for the outer lookup while the parameters of the second lookup are expanded, @@ -8017,9 +8341,10 @@ and also while <> of the second lookup is expanded, should the second lookup fail. Instead of @{<>@} the word `fail' can appear, and in this case, if the -lookup fails, the entire expansion is forced to fail. If both @{<>@} -and @{<>@} are omitted, the result is the looked up value in the case -of a successful lookup, and nothing in the case of failure. +lookup fails, the entire expansion is forced to fail (see section +~~SECTforexpfai). If both @{<>@} and @{<>@} 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 @@ -8070,13 +8395,13 @@ returns the string `6/33'. 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 +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 +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. @@ -8095,8 +8420,8 @@ 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 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 @@ -8154,7 +8479,7 @@ The \%redirect%\ router has an option called \forbid@_filter@_readsocket\ which locks out the use of this expansion item in filter files. .item "@$rheader@_<
>:#$rm{or}#@$rh@_<
>:" -This item inserts `raw' header lines. It is described with the \header\ +This item inserts `raw' header lines. It is described with the \header\ expansion item above. @@ -8183,12 +8508,12 @@ if "${run{x y z}{}}$runrc" is 1 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 +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$\ +\**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 @@ -8216,7 +8541,7 @@ yields `defabc', and ${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 +Note the use of \"@\N"\ to protect the contents of the regular expression from string expansion. @@ -8233,6 +8558,10 @@ the simpler operator notation that avoids some of the braces: @$@{substr@_<>@_<>:<>@} .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, <>, is a starting offset, and <> is the length @@ -8263,10 +8592,15 @@ ${substr{-3}{2}{12}} .endd yields `1'. -If the second number is omitted from \substr\, the remainder of the string is -taken if the offset was positive. If it was negative, all characters in the +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 yields all but the last character of the string. +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'. @@ -8312,13 +8646,11 @@ 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. -.em .item "@$@{base62d:<>@}" .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. -.nem .item "@$@{domain:<>@}" @@ -8336,7 +8668,6 @@ significant bit set (so-called `8-bit characters') count as printing or not is controlled by the \print@_topbitchars\ option. -.em .item "@$@{eval:<>@}" .item "@$@{eval10:<>@}" .index expansion||expression evaluation @@ -8346,13 +8677,12 @@ 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. +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. -.nem 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 @@ -8403,18 +8733,18 @@ 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 +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 +single-byte encoding (but thereby limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1 straightforward. .item "@$@{hash@_<>@_<>:<>@}" .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 +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@{<>@}@{<>@}@{<>@}@} @@ -8427,7 +8757,7 @@ abbreviation \h\ can be used when \hash\ is used as an operator. .item "@$@{hex2b64:<>@}" .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 +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. @@ -8450,7 +8780,7 @@ changes when expanded). The effect is the same as .display @$@{length@{<>@}@{<>@}@} .endd -See the description of the general \length\ item above for details. Note that +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. @@ -8512,7 +8842,7 @@ See the description of the general \nhash\ item above for details. .item "@$@{quote:<>@}" .index quoting||in string expansions .index expansion||quoting -The \quote\ operator puts its argument into double quotes if it +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. @@ -8529,8 +8859,8 @@ The place where this is useful is when the argument is a substitution from a variable or a message header. .item "@$@{quote@_local@_part:<>@}" -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 +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. @@ -8544,7 +8874,7 @@ the lookups in chapter ~~CHAPfdlookup. For example, .display asis ${quote_ldap:two * two} .endd -returns +returns .display asis two%20%5C2A%20two .endd @@ -8565,14 +8895,16 @@ variables or headers inside regular expressions. 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 +\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, as a single -`coded word'. +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:<>@}" @@ -8588,7 +8920,7 @@ as a 40-digit hexadecimal number, in which any letters are in upper case. 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 <>=<> pairs, where the values are all numerical, +series of <>=<> 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', @@ -8597,10 +8929,18 @@ 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:<>@}" +.index expansion||base64 encoding +.index base64 encoding||in string expansion +This operator converts a string into one that is base64 encoded. +.nem + + .item "@$@{strlen:<>@}" .index expansion||string length .index string||length in expansion -The item is replace by the length of the expanded string, expressed as a +The item is replace by the length of the expanded string, expressed as a decimal number. \**Note**\: Do not confuse \strlen\ with \length\. @@ -8617,7 +8957,6 @@ change when expanded). The effect is the same as See the description of the general \substr\ item above for details. The abbreviation \s\ can be used when \substr\ is used as an operator. -.em .item "@$@{time@_interval:<>@}" .index \time@_interval\ .index time interval||formatting @@ -8625,7 +8964,6 @@ 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"\. -.nem .item "@$@{uc:<>@}" .index case forcing in strings @@ -8700,7 +9038,7 @@ 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 +The following encryption types (whose names are matched case-independently) are supported: .numberpars $. @@ -8714,25 +9052,33 @@ 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 +\@{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, which uses only the first eight -characters of the password. +\@{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 uses up to 16 characters of the password. +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 +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, @@ -8774,7 +9120,7 @@ follow. .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 +resulting strings are identical: for \eq\ the comparison includes the case of letters, whereas for \eqi\ the comparison is case-independent. .item "exists @{<>@}" @@ -8792,7 +9138,6 @@ users' filter files may be locked out by the system administrator. This condition, which has no data, is true during a message's first delivery attempt. It is false during any subsequent delivery attempts. -.em .item "ge @{<>@}@{<>@}" .item "gei @{<>@}@{<>@}" .index string||comparison @@ -8810,18 +9155,17 @@ 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. -.nem .item "isip @{<>@}" 8 .item "isip4 @{<>@}" .item "isip6 @{<>@}" .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 +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 +.display asis ${if isip4{$sender_host_address}... .endd to test which version of IP an incoming SMTP connection is using. @@ -8835,14 +9179,13 @@ 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 +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. -.em .item "le @{<>@}@{<>@}" .item "lei @{<>@}@{<>@}" .index string||comparison @@ -8860,7 +9203,6 @@ 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. -.nem .item "match @{<>@}@{<>@}" @@ -8880,14 +9222,12 @@ ${if match {$local_part}{\N^\d{3}\N} ... 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. -.em -The regular expression is not required to begin with a circumflex +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 \"@$"\ +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. -.nem .index numerical variables (\$1$\, \$2$\, etc)||in \if\ expansion At the start of an \if\ expansion the values of the numeric variable @@ -8898,7 +9238,6 @@ 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. -.em .item "match@_domain @{<>@}@{<>@}" .item "match@_address @{<>@}@{<>@}" .item "match@_local@_part @{<>@}@{<>@}" @@ -8928,7 +9267,6 @@ caselessly. 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. -.nem .item "pam {<>:<>:...@}" .index PAM authentication @@ -8948,7 +9286,7 @@ 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. +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 (<>). The @@ -9019,9 +9357,19 @@ initiated by queue runner processes, and false otherwise. 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. +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 @@ -9103,12 +9451,16 @@ parsed but not evaluated. .rset SECTexpvar "~~chapter.~~section" .index expansion||variables, list of -The variables that are available for use in expansion strings are: +.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 -.tempindent 0 .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\ @@ -9118,12 +9470,12 @@ 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 +\$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. +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 +message, and can be accessed by filters, routers, and transports during subsequent delivery. .tempindent 0 @@ -9137,7 +9489,7 @@ subsequent delivery. .tempindent 0 -\$acl@_verify@_message$\: During the expansion of the \message\ and +\$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. @@ -9147,14 +9499,26 @@ overridden by the expanded string. 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. +chapter ~~CHAProutergeneric for more details. \**Note**\: the contents of +\$address@_data$\ are visible in user filter files. -If \$address@_data$\ is set when the routers are called to verify an address -from an ACL, the final value remains available in subsequent conditions in the -ACL statement. If routing the address caused it to be redirected to a single -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. +.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 @@ -9168,8 +9532,8 @@ file containing 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 +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. @@ -9193,10 +9557,8 @@ calling process. .index \\AUTH\\||on \\MAIL\\ command .tempindent 0 \$authenticated@_sender$\: -.em When acting as a server, Exim takes note of the \\AUTH=\\ parameter on an incoming SMTP \\MAIL\\ command -.nem 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 @@ -9210,7 +9572,7 @@ name of the calling process and \$qualify@_domain$\. .index authentication||failure .tempindent 0 -\$authentication@_failed$\: +\$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' @@ -9232,11 +9594,9 @@ number of lines in the message's body. .index body of message||binary zero count .index binary zero||in message body .tempindent 0 -.em \$body@_zerocount$\: When a message is being received or delivered, this variable contains the number of binary zero bytes in the message's body. -.nem .tempindent 0 \$bounce@_recipient$\: @@ -9252,10 +9612,8 @@ useful when a customized error message text file is in use (see chapter .index gid (group id)||caller .tempindent 0 -\$caller@_gid$\: The -.em -real -.nem +\$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 @@ -9263,10 +9621,8 @@ incarnation normally contains the Exim gid. .index uid (user id)||caller .tempindent 0 -\$caller@_uid$\: The -.em +\$caller@_uid$\: The real -.nem 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 @@ -9280,6 +9636,18 @@ incarnation normally contains the Exim uid. 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, @@ -9293,7 +9661,7 @@ 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 +If there are multiple records, all the addresses are included, comma-space separated. .tempindent 0 @@ -9319,8 +9687,8 @@ 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\\ +\**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$\ @@ -9347,14 +9715,13 @@ 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. +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 +\$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. -.em .tempindent 0 \$exim@_gid$\: This variable contains the numerical value of the Exim group id. @@ -9363,6 +9730,12 @@ to nothing. .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 @@ -9401,6 +9774,10 @@ name of the first host. \$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$\: @@ -9412,19 +9789,35 @@ deny hosts = net-lsearch;/some/file message = $host_data .endd +.em .index host||name lookup, failure of .tempindent 0 -\$host@_lookup@_failed$\: -This variable contains `1' if the message came from a remote host and there was -an attempt to look up the host's name from its IP address, but the attempt -failed. Otherwise the value of the variable is `0'. -.em -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. +\$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 @@ -9438,27 +9831,26 @@ a unique name for the file. \$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 +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 +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 +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 +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 @@ -9505,11 +9897,9 @@ 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 -.em -\**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 +\**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). -.nem .tempindent 0 \$local@_part@_data$\: @@ -9551,20 +9941,41 @@ 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 +\$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 @@ -9593,10 +10004,11 @@ body while it is being delivered. The format and maximum size are as for .index body of message||size .index message||body, size .tempindent 0 -\$message@_body@_size$\: When a message is being processed, this variable +\$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$\ and \$body@_linecount$\. +included in the count. See also \$message@_size$\, \$body@_linecount$\, and +\$body@_zerocount$\. .tempindent 0 \$message@_headers$\: @@ -9605,21 +10017,19 @@ is being processed, except for lines added by routers or transports. The header lines are separated by newline characters. .tempindent 0 -\$message@_id$\: +\$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 +An id is not created for a message until after its header has been successfully received. -.em -\**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: +\**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"\. -.nem .index size||of message .index message||size .tempindent 0 -\$message@_size$\: +\$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 @@ -9627,14 +10037,21 @@ 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$\ and \$body@_linecount$\. +\$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 +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. @@ -9655,15 +10072,16 @@ 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, in which case \$original@_local@_part$\ -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. +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 @@ -9713,9 +10131,7 @@ provokes an `unknown variable' error if encountered. \*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. -.em See also \$smtp@_active@_hostname$\. -.nem .tempindent 0 \$qualify@_domain$\: The value set for this option in the configuration file. @@ -9725,13 +10141,13 @@ See also \$smtp@_active@_hostname$\. or if not set, the value of \$qualify@_domain$\. .tempindent 0 -\$rcpt@_count$\: When a message is being received by SMTP, this variable +\$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 +\$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. @@ -9750,17 +10166,32 @@ while routing and delivering. \$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. -.em The value is copied after recipient rewriting has happened, but before the \*local@_scan()*\ function is run. -.nem .tempindent 0 \$received@_protocol$\: When a message is being processed, this variable -contains the name of the protocol by which it was received. See also the -\-oMr-\ option. - +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 @@ -9770,10 +10201,32 @@ like this: 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 +\**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 @@ -9781,11 +10234,14 @@ expansion that all such lists undergo before being interpreted. 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 -In the \\DATA\\ or non-SMTP ACL, that is, in the final ACL for accepting a -message. +.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 @@ -9804,14 +10260,14 @@ 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, +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 +In other words, \$sender@_address$\ contains the incoming envelope sender, and \$return@_path$\ contains the outgoing envelope sender. .tempindent 0 @@ -9822,14 +10278,14 @@ In other words, \$sender@_address$\ contains the incoming envelope sender, and .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$\ +\**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 +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 @@ -9842,15 +10298,23 @@ 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$\. -.em .tempindent 0 -\$sender@_data$\: This variable is set after a lookup success in an ACL +\$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: @@ -9858,11 +10322,10 @@ can do things like this: 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 +\**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. -.nem .tempindent 0 \$sender@_fullhost$\: When a message is received from a remote host, this @@ -9897,17 +10360,28 @@ 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. +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). -.em +\$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, or if -the forward lookup does not yield 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 @@ -9917,7 +10391,7 @@ 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 +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 @@ -9925,16 +10399,16 @@ 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 +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 +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 +which causes a lookup if a remote host (incorrectly) gives the server's name or IP address in an \\EHLO\\ or \\HELO\\ command. .endp @@ -9966,6 +10440,19 @@ 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 @@ -9982,9 +10469,37 @@ 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 @@ -9998,14 +10513,14 @@ 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 +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, +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. @@ -10021,7 +10536,7 @@ 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 +UTC, with positive values used for timezones that are ahead (east) of UTC, and negative values for those that are behind (west). .tempindent 0 @@ -10083,6 +10598,7 @@ 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 @@ -10118,6 +10634,7 @@ overriding the setting of \perl@_at@_start\. 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 @@ -10135,11 +10652,12 @@ 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 fails 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\. +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 @@ -10164,6 +10682,32 @@ must supply it. \*Exim@:@:log@_write(<>)*\ 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 . @@ -10213,7 +10757,7 @@ 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 +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. @@ -10242,23 +10786,23 @@ local_interfaces = <; 127.0.0.1 ; \ 192.168.23.65 ; \ ::1 ; \ 3ffe:ffff:836f::fe86:a061 -.endd +.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 +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 +.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 +.endd .endp When a port is not specified, the value of \daemon@_smtp@_ports\ is used. The default setting contains just one port: @@ -10272,7 +10816,7 @@ specified listens on all of them. Ports that are listed in IP addresses in \local@_interfaces\, only numbers (not names) can be used. -.section Special IP listening addresses +.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' @@ -10315,6 +10859,33 @@ overrides \local@_interfaces\, leaving \daemon@_smtp@_ports\ unchanged. 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 @@ -10323,7 +10894,7 @@ 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 -3ffe:2101:12:1:a00:20ff:fe86:a061%eth0 +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()*\ @@ -10344,7 +10915,7 @@ function.) Of course, this means that the additional functionality of .section Examples of starting a listening daemon The default case in an IPv6 environment is .display asis -daemon_smtp_port = smtp +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. @@ -10370,7 +10941,7 @@ To specify listening on the default port on specific interfaces only: .display asis local_interfaces = 192.168.34.67 : 192.168.34.67 .endd -\**Note**\: such a setting excludes listening on the loopback interfaces. +\**Warning**\: such a setting excludes listening on the loopback interfaces. .section Recognising the local host @@ -10403,8 +10974,8 @@ 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 +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 @@ -10423,7 +10994,6 @@ description of the smtp transport in chapter ~~CHAPsmtptrans for more details. - . . . @@ -10452,8 +11022,8 @@ 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. +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 @@ -10465,6 +11035,11 @@ Some options are listed in more than one group. \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 @@ -10499,21 +11074,23 @@ Some options are listed in more than one group. .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{in another directory after message completion} +\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 -.em \write@_rejectlog\ $t$rm{control use of message log} .newline -.nem .endd .section Frozen messages @@ -10557,7 +11134,7 @@ Some options are listed in more than one group. \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 number of simultaneous queue runners} +\queue@_run@_max\ $t$rm{maximum simultaneous queue runners} .endd .section Resource control @@ -10569,7 +11146,7 @@ Some options are listed in more than one group. \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 number of simultaneous queue runners} +\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} @@ -10597,9 +11174,21 @@ Some options are listed in more than one group. \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} @@ -10614,6 +11203,11 @@ Some options are listed in more than one group. \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 @@ -10631,25 +11225,22 @@ Some options are listed in more than one group. .tabs 31 \tls@_advertise@_hosts\ $t$rm{advertise TLS to these hosts} \tls@_certificate\ $t$rm{location of server certificate} -.newline -.em \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 -\tls@_dhparam\ $t$rm{DH parameters for server} +.newline \tls@_privatekey\ $t$rm{location of server private key} \tls@_remember@_esmtp\ $t$rm{don't reset after starting TLS} -.newline -.em \tls@_require@_ciphers\ $t$rm{specify acceptable cipers} -.newline -.nem \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 +.section Local user handling .display flow rm .tabs 31 \finduser@_retries\ $t$rm{useful in NIS environments} @@ -10704,10 +11295,8 @@ See also the \*Policy controls*\ section above. \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 -.em \smtp@_active@_hostname\ $t$rm{host name to use in messages} .newline -.nem \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} @@ -10783,7 +11372,7 @@ See also the \*Policy controls*\ section above. \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, not overall)} +\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} @@ -10814,7 +11403,7 @@ See also the \*Policy controls*\ section above. Those options that undergo string expansion before use are marked with $**$. .fi -.startconf +.startconf main .index \\8BITMIME\\ .index 8-bit characters @@ -10828,20 +11417,20 @@ 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 +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||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 ~~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 @@ -10871,10 +11460,28 @@ 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 +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 @@ -10906,12 +11513,12 @@ 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 +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 @@ -10929,7 +11536,7 @@ when you have no other choice. .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 +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 @@ -10954,10 +11561,10 @@ That is, set the option to an empty string so that no check is done. 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 +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 +\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 @@ -10974,8 +11581,8 @@ 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 +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 @@ -10988,6 +11595,17 @@ 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 @@ -11009,8 +11627,8 @@ 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 +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 @@ -11075,7 +11693,7 @@ 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 +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 @@ -11096,13 +11714,22 @@ See \check@_spool@_space\ below. .index disk space, checking .index spool directory||checking space The four \check@_...\ options allow for checking of disk resources before a -message is accepted. \check@_spool@_space\ and \check@_spool@_inodes\ check the -spool partition if either value is greater than zero, for example: +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 which contains the directory defined by +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. @@ -11128,24 +11755,28 @@ it obviously cannot send an error message of any kind. .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 +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. If it is set to a zero, no warnings are -sent. The data is a colon-separated list of times after which to send warning -messages. 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 +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 +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 @@ -11205,11 +11836,15 @@ 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. -.em 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 @@ -11226,7 +11861,7 @@ dns_check_names_pattern = \ .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 +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 @@ -11260,8 +11895,8 @@ to set in them. 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 +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 @@ -11297,7 +11932,7 @@ errors_copy = spqr@mydomain postmaster@mydomain.example :\ 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\ +.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 @@ -11306,7 +11941,7 @@ Exim's bounce and delivery warning messages contain the header line .display From: Mail Delivery System @>@> .endd -where <> is the value of the \qualify@_domain\ option. +where <> 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: @@ -11333,9 +11968,9 @@ 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 +\**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" @@ -11352,9 +11987,9 @@ 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 +.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 @@ -11367,7 +12002,7 @@ 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 +\extract__addresses__remove__arguments\ is true (the default), Exim subtracts argument headers. If it is set false, Exim adds rather than removes argument addresses. @@ -11381,6 +12016,13 @@ 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, @@ -11388,14 +12030,14 @@ 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 +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. +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 +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 @@ -11412,7 +12054,7 @@ 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\ +.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: @@ -11437,11 +12079,11 @@ insertions in section ~~SECTexpansionitems. .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 +\(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 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 @@ -11458,7 +12100,7 @@ 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 +See also \helo@_allow@_chars\ for a way of extending the permitted character set. .conf helo@_allow@_chars string unset @@ -11503,7 +12145,7 @@ calling host address, or 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 +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 @@ -11517,8 +12159,8 @@ 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 +received before \\EHLO\\ or \\HELO\\, it is rejected with a +503 error. .conf hold@_domains "domain list$**$" unset @@ -11566,13 +12208,13 @@ 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 +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 +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. @@ -11580,7 +12222,7 @@ 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. +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. @@ -11591,6 +12233,22 @@ 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 @@ -11605,15 +12263,15 @@ This option also applies when Exim is matching the special items 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 +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 +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, @@ -11674,11 +12332,19 @@ has been built with LDAP support. .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 the login of the calling user. 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. +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 @@ -11689,7 +12355,12 @@ and no ::Sender:: header is ever added. If, in addition, you want to retain 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. -Section ~~SECTthesenhea has more details about ::Sender:: processing. + +.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 @@ -11715,11 +12386,15 @@ qualify domain. 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 \extra@_local@_interfaces\ and \hosts@_treat@_as@_local\. The default -value for \local@_interfaces\ is +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 @@ -11873,7 +12548,7 @@ which is not affected by this option. .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 +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 @@ -11900,6 +12575,13 @@ 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 @@ -11911,11 +12593,11 @@ 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 + +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 @@ -11979,8 +12661,8 @@ 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 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$**$" $*$ @@ -11989,11 +12671,9 @@ 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. -.em 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 +of order' commands that are `expected' do not count as protocol errors (see \smtp@_max@_synprot@_errors\). -.nem .conf preserve@_message@_logs boolean false .index message logs, preserving @@ -12007,22 +12687,18 @@ volume of mail. Use with care! .index name||of local host .index host||name of local .index local host||name of -.em 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), -.nem 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. -.em 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\. -.nem .conf print@_topbitchars boolean false .index printing characters @@ -12036,7 +12712,7 @@ characters. .conf process@_log@_path string unset .index process log path -.index log||process log +.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 @@ -12056,26 +12732,31 @@ admin user unless \prod@_requires@_admin\ is set false. See also .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 sender addresses -that do not have a domain qualification. It also applies to recipient addresses -if \qualify@_recipient\ is not set. Such addresses are accepted by default only -for locally-generated messages. 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 addresses. -If \qualify@_domain\ is not set, it defaults to the \primary@_hostname\ value. +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" -This specifies the domain name that is added to any recipient addresses that do -not have a domain qualification. Such addresses are accepted by default only -for locally-generated messages. Messages from external sources must always -contain fully qualified recipient addresses, unless the sending host matches -\recipient@_unqualified@_hosts\, -in which case incoming recipient addresses are qualified with -\qualify@_recipient\. -If \qualify@_recipient\ is not set, it defaults to the \qualify@_domain\ value. +.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 @@ -12143,13 +12824,18 @@ override; they are accepted, but ignored. .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 in a single -directory (the default), this happens anyway, but if \split@_spool@_directory\ -is set it does not -- for delivery in random order, the sub-directories are -processed one at a time (in random order), to avoid setting up one huge list. -Thus, setting \queue@_run@_in@_order\ with \split@_spool@_directory\ may -degrade performance when the queue is large. In most situations, -\queue@_run@_in@_order\ should not be set. +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 @@ -12218,12 +12904,10 @@ Received: from scrooge.carol.example ([192.168.12.25] ident=root) Received: by scrooge.carol.example with local (Exim 4.00) id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 .endd -.em -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 +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. -.nem .conf received@_headers@_max integer 30 .index loop||prevention @@ -12243,14 +12927,12 @@ 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\, -.em or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ option was not set. -.nem .conf recipients@_max integer 0 .index limit||number of recipients -.index recipient||maximum number +.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 @@ -12301,10 +12983,10 @@ 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\ -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. +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 @@ -12366,10 +13048,8 @@ sender addresses. The addresses are made fully qualified by the addition of 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\, -.em or if the message was submitted locally (not using TCP/IP), and the \-bnq-\ option was not set. -.nem .conf smtp@_accept@_keepalive boolean true .index keepalive||on incoming connection @@ -12402,7 +13082,7 @@ either \smtp@_accept@_max@_per@_host\ or \smtp@_accept@_queue\ is set. See also 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 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 @@ -12491,7 +13171,6 @@ 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\. -.em .conf smtp@_active@_hostname string$**$ unset .index host||name in SMTP responses .index SMTP||host name in responses @@ -12499,19 +13178,24 @@ 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. 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: +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 -If you set \smtp@_active@_hostname\, you probably also want to set -\smtp@_banner\, since its default value references \$primary@_hostname$\. -.nem .conf smtp@_banner string$**$ "see below" .index SMTP||welcome banner @@ -12521,8 +13205,10 @@ If you set \smtp@_active@_hostname\, you probably also want to set 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 -smtp_banner = $primary_hostname ESMTP Exim $version_number \ - $tod_full +.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 @@ -12559,16 +13245,21 @@ attacks by SYN flooding. 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. The check can be -disabled by setting \smtp@_enforce@_sync\ false. +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 -See also \pipelining@_advertise@_hosts\. +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 @@ -12608,7 +13299,7 @@ systems on which Exim cannot determine the load average. See also .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 +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: @@ -12619,25 +13310,21 @@ 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. -.em .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 +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. -.nem .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 -.em -clients -.nem +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. @@ -12675,7 +13362,7 @@ 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 +It is also possible to configure delays explicitly in ACLs. See section ~~SECTACLmodi for details. @@ -12691,13 +13378,13 @@ See \smtp@_ratelimit@_hosts\ above. 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. +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 +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. @@ -12727,6 +13414,13 @@ example, instead of `Administrative prohibition', it might give: 550 failing address in "From" header is: {$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 options below are common special cases that could in fact be -specified using \condition\. -Note that \condition\ is the last precondition to be evaluated (see -section ~~SECTrouprecon). +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 +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\ @@ -13326,11 +14054,9 @@ 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 -.em 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. -.nem .conf domains "domain list$**$ (precondition)" unset .index router||restricting to specific domains @@ -13338,7 +14064,7 @@ 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 +See section ~~SECTrouprecon for a list of the order in which preconditions are evaluated. @@ -13354,8 +14080,8 @@ 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 +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 @@ -13400,8 +14126,8 @@ setting \return@_path\. 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 +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 @@ -13442,8 +14168,8 @@ the \fallback@_hosts\ option of the \%smtp%\ transport for further details. .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 +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 @@ -13453,68 +14179,41 @@ 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 processed by the router -when delivering a message. This option has no effect when an address is just -being verified. +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. The expanded string 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. If an address -passes through several routers as a result of aliasing or forwarding -operations, any \headers@_add\ or \headers@_remove\ specifications are -cumulative. This does not apply for multiple routers that result from the use -of `unseen'. +\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. -At transport time, all the original headers listed in \headers__remove\ are -removed. If there are multiple instances of any listed header, they are all -removed. -Then the new headers specified by \headers@_add\ are added, in the order in -which they were attached to the address. Finally, any additional headers -specified by the transport are added. It is not possible to remove headers -added to an address by \headers@_add\. - -Because the addition does not happen until transport time, header lines that -are added by \headers@_add\ are not accessible by means of the \$header@_xxx$\ -expansion syntax. Conversely, header lines that are removed by -\headers@_remove\ remain visible. - -Addresses with different \headers@_add\ or \headers@_remove\ settings cannot be -delivered together in a batch. The \headers@_add\ option cannot be used for a -\%redirect%\ router that has the \one@_time\ option set. +\**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 -The string is expanded at routing time and is then associated with any -addresses that are processed by the router when delivering a message. This -option has no effect when an address is being verified. 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. - .em -After expansion, the string 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. +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 -For example: -.display asis -headers_remove = return-receipt-to:acknowledge-to -.endd -The list is used at transport time as described under \headers@_add\ above. The -\headers@_remove\ option cannot be used for a \%redirect%\ router that has the -\one@_time\ option set. + .conf ignore@_target@_hosts "host list$**$" unset .index IP address||discarding @@ -13531,21 +14230,22 @@ by setting .display asis ignore_target_hosts = 127.0.0.1 .endd -on the relevant router. -.em -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 then normally provoke the `unrouteable domain' error, and an -attempt to verify an address in the domain would fail. +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. -.nem 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 @@ -13584,9 +14284,9 @@ 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 +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 @@ -13629,7 +14329,7 @@ See \local@_part@_suffix\ above. .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 +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 @@ -13724,11 +14424,11 @@ which it is set does not generate new addresses. 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. +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 +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 @@ -13752,7 +14452,7 @@ 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. +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: @@ -13779,22 +14479,28 @@ 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 on an NFS directory that is mounted +\**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. -In both cases, -the default action is to consider this a configuration error, 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: +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\ +handles users' \(.forward)\ files), another solution is to set the \verify\ option false so that the router is skipped when verifying. @@ -13815,11 +14521,9 @@ 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. -.em -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 +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. -.nem .conf router@_home@_directory string$**$ unset @@ -13834,7 +14538,7 @@ 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. +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 @@ -13862,7 +14566,7 @@ router, but not for the transport. .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. +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 @@ -13930,8 +14634,8 @@ different configuration file that handles the domain in another way. .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 +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 @@ -13957,7 +14661,7 @@ code to support this option is not included in the Exim binary unless 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. +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 @@ -13980,11 +14684,10 @@ 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. +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 @@ -14020,7 +14723,7 @@ 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. +is set; if not, no home directory is set for the transport. See chapter ~~CHAPenvironment for further details of the local delivery environment. @@ -14037,21 +14740,21 @@ 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 +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 +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 +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 @@ -14067,7 +14770,7 @@ previous routers is passed on. Setting this option has a similar effect to the .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 +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, @@ -14091,21 +14794,21 @@ 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 +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 +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 +See section ~~SECTrouprecon for a list of the order in which preconditions are evaluated. .endconf @@ -14156,12 +14859,11 @@ address for the \%local@_delivery%\ transport. .set runningfoot "dnslookup router" .index \%dnslookup%\ router .index routers||\%dnslookup%\ -The \%dnslookup%\ router looks up the hosts that handle mail for the given -domain in the DNS. A transport must always be set for this router, unless -\verify@_only\ is set. +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. -.em -If SRV support is configured (see \check@_srv\ below), Exim first searches for +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. @@ -14176,7 +14878,6 @@ 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. -.nem .index MX record||pointing to local host .index local host||MX pointing to @@ -14185,11 +14886,33 @@ 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. -There are a number of private options that can be used to vary the way the DNS -lookup is handled. +.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 -.startconf .index options||\%dnslookup%\ router .conf check@_secondary@_mx boolean false .index MX record||checking for secondary @@ -14199,10 +14922,9 @@ 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. -.em .conf check@_srv string$**$ unset .index SRV record||enabling use of -The dnslookup router supports the use of SRV records (see RFC 2782) in +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, @@ -14217,30 +14939,31 @@ 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 the -host name \"."\ 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. - -However, 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. +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 -.em 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.) -.nem 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: @@ -14251,6 +14974,14 @@ 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 @@ -14303,10 +15034,10 @@ 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 +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 router did not change the address in any way, for example, by `widening' the domain. .endp @@ -14326,6 +15057,15 @@ 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 @@ -14342,9 +15082,8 @@ the DNS resolver. .endconf -.em .section Effect of qualify@_single and search@_parents -When a domain from an envelope recipient is changed by the resolver as a result +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. @@ -14357,7 +15096,6 @@ 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. -.nem @@ -14375,7 +15113,7 @@ 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 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 @@ -14385,15 +15123,13 @@ 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. +by setting up delivery to the host with that IP address. -.em -If the IP address matches something in \ignore@_target@_hosts\, the router +If the IP address matches something in \ignore@_target@_hosts\, the router declines. -.nem .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. +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 @@ -14412,8 +15148,9 @@ Exim will not recognize the domain literal syntax in addresses. .index \%iplookup%\ router .index routers||\%iplookup%\ The \%iplookup%\ router was written to fulfil a specific requirement in -Cambridge University. For this reason, it is not included in the binary of Exim -by default. If you want to include it, you must set +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 @@ -14443,12 +15180,12 @@ 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 +.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()*\ +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\. @@ -14550,7 +15287,7 @@ following the list of private options. The private options for the \%manualroute%\ router are as follows: -.startconf +.startconf manualroute .index options||\%manualroute%\ router .conf host@_find@_failed string "freeze" @@ -14650,12 +15387,12 @@ 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 +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), +~~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 @@ -14714,9 +15451,8 @@ looked up is available in the expansion variable \$value$\. .endp -.em .section How the list of hosts is used -When an address is routed to an \%smtp%\ transport by \%manualroute%\, each of +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 @@ -14730,11 +15466,11 @@ records in the DNS. For example: 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 +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 +happens is controlled by the .index \self\ option||in \%manualroute%\ router \self\ option of the router. @@ -14745,7 +15481,6 @@ 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. -.nem 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 @@ -14764,10 +15499,8 @@ 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. -.em The generic \ignore@_target@_hosts\ option applies to all hosts in the list, whether obtained from an MX lookup or not. -.nem .section How the options are used @@ -14779,7 +15512,7 @@ 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 +\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, @@ -14790,8 +15523,8 @@ 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. +no address records are found. If there is a temporary DNS error (such as a +timeout), delivery is deferred. .endp For example: .display asis @@ -14979,7 +15712,7 @@ 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 +.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 @@ -15014,8 +15747,12 @@ timeout. 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. The first field is one -of the following words (case-insensitive): +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). @@ -15053,12 +15790,12 @@ 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. +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 +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 @@ -15069,8 +15806,8 @@ 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, with a host list containing two -hosts. When the transport runs, the string `rule1' is in \$address@_data$\. +routes the address to the default transport, passing a list of two hosts. When +the transport runs, the string `rule1' is in \$address@_data$\. @@ -15124,12 +15861,10 @@ system_aliases: driver = redirect data = ${lookup{$local_part}lsearch{/etc/aliases}} .endd -.em -If the lookup fails, the expanded string in this example is empty. When the +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. -.nem A configuration using \file\ is commonly used for handling users' \(.forward)\ files, like this: @@ -15153,8 +15888,8 @@ 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 +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 @@ -15185,10 +15920,10 @@ document is intended for use by end users. 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 +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. @@ -15214,11 +15949,11 @@ 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 +\**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 @@ -15233,9 +15968,7 @@ data = ${quote:$local_part}@newdomain.example 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 -.em -is the same as the current address and was processed by the current router. -.nem +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. @@ -15261,23 +15994,21 @@ 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. -.em +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 +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, -.nem +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 @@ -15298,11 +16029,9 @@ lists (that is, in non-filter redirection data): .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. -.em +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. -.nem 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 @@ -15334,14 +16063,12 @@ 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. -.em 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. -.nem .nextp .index included address list .index address redirection||included external list @@ -15350,8 +16077,8 @@ If an item is of the form :include:<> .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 +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 @@ -15378,10 +16105,10 @@ 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 +\**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 @@ -15405,12 +16132,20 @@ text associated with the failure. For example, an alias file might contain: 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 \\VRFY\\ command, the text is included in the SMTP error response by -default. 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. +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. @@ -15487,7 +16222,7 @@ deferred. See also \syntax@_errors@_to\. The private options for the \%redirect%\ router are as follows: -.startconf +.startconf redirect .index options||\%redirect%\ router .conf allow@_defer boolean false @@ -15506,12 +16241,17 @@ and the \fail\ command may be used in a filter file. 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. 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. +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 @@ -15529,14 +16269,12 @@ 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. -.em 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 +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: -.nem .display @\Joe.Bloggs, <> .endd @@ -15612,7 +16350,7 @@ not, the router declines. 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. +configured transport. This should normally be an \%appendfile%\ transport. When it is running, the file name is in \$address@_file$\. @@ -15620,6 +16358,13 @@ When it is running, the file name is in \$address@_file$\. 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 @@ -15660,9 +16405,11 @@ 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 filter files, not -from traditional forward files or Sieve filters. This option is forced to be -true if \one@_time\ is set. +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 @@ -15681,6 +16428,13 @@ 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 @@ -15727,8 +16481,8 @@ This specifies mode bits which must not be set for a file specified by the .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 +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 @@ -15770,33 +16524,29 @@ 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. -.em -.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$\. -.nem - .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. +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 -.em +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. -.nem .conf repeat@_use boolean true If this option is set false, the router is skipped for a child address that has @@ -15809,7 +16559,7 @@ only when the ancestor is the same as the current address. See also 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 +This should normally be an \%autoreply%\ transport. Other transports are unlikely to do anything sensible or useful. .conf rewrite boolean true @@ -15818,6 +16568,17 @@ 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 @@ -15845,8 +16606,11 @@ 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 -Currently, any syntax errors in a Sieve filter file cause the `keep' action to -occur. The values of \skip@_syntax@_errors\, \syntax@_errors@_to\, and +.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 @@ -15917,7 +16681,7 @@ 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 which sets up environment variables; see section +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 @@ -15926,6 +16690,31 @@ 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 @@ -15941,7 +16730,7 @@ group (set by the transport). For example: local_users: driver = accept check_local_user - transport = group_delivery + transport = group_delivery # Transports ... # This transport overrides the group @@ -16027,7 +16816,7 @@ domain, and \$original@_domain$\ is never set. .index transport||generic options for The following generic options apply to all transports: -.startconf +.startconf transports .conf body@_only boolean false .index transport||body only .index message||transporting body only @@ -16045,10 +16834,8 @@ 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 -.em -deliveries by the transport or for any -.nem +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. @@ -16056,8 +16843,8 @@ what you are doing. .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 +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\ @@ -16097,22 +16884,14 @@ value that the router supplies, and also overriding any value associated with .conf headers@_add string$**$ unset .index header lines||adding in transport .index transport||header lines, adding -This option specifies a string of text which is expanded and added to the -header portion of a message as it is transported. 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. The expanded string should 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: this is a header added at $tod_log\n\ - X-added: this is another -.endd -Exim does not check the syntax of these added header lines. They are added at -the end of the existing header lines. If you include a blank line within the -string, you can subvert this facility into adding text at the start of the -message's body. This is not recommended. Additional header lines can also be -specified by routers. See chapter ~~CHAProutergeneric and section -~~SECTheadersaddrem. +.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 @@ -16126,22 +16905,14 @@ checked, since this option does not automatically suppress them. .conf headers@_remove string$**$ unset .index header lines||removing .index transport||header lines, removing -This option is expanded; the result must consist of a colon-separated list of -header names, not including the terminating colon, for example: -.display asis -headers_remove = return-receipt-to:acknowledge-to -.endd -Any existing headers matching those names are not included in any message that -is transmitted by the transport. -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 +.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. - -If there are multiple instances of a header, they are all removed. However, -added headers may have these names. Thus it is possible to replace a header by -specifying it in \headers@_remove\ and supplying the replacement in -\headers@_add\. Headers to be removed can also be specified by routers. See -chapter ~~CHAProutergeneric and section ~~SECTheadersaddrem. +.nem .conf headers@_rewrite string unset .index transport||header lines, rewriting @@ -16192,7 +16963,7 @@ to ensure that any additional groups associated with the uid are set up. 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 +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 @@ -16261,12 +17032,10 @@ 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, -.em +\**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). -.nem .conf return@_path@_add boolean false @@ -16295,7 +17064,7 @@ 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 +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 @@ -16329,12 +17098,20 @@ 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. -The filter's standard output is read and written to the message's destination. +.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 @@ -16351,14 +17128,14 @@ 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 option is the command string for starting up 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.) +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$\ @@ -16371,6 +17148,12 @@ transport_filter = /some/directory/transport-filter.pl \ .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 @@ -16378,8 +17161,8 @@ 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 +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. @@ -16392,11 +17175,9 @@ 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. -.em 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. -.nem .index hints database||access by remote transport For remote transports, you should leave this option unset unless you really are @@ -16438,8 +17219,8 @@ recipients saves space. 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 +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 @@ -16464,8 +17245,8 @@ addresses with the same domain are batched. 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. +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 @@ -16490,15 +17271,15 @@ 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 +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, +option. This causes an ::Envelope-to:: header line to be added to the message, containing all the recipients. @@ -16547,13 +17328,13 @@ 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). +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 \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. @@ -16566,16 +17347,16 @@ 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 +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 +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. +contents of \$address@_file$\ are used in some way in the string expansion. .endp .index Sieve filter||configuring \%appendfile%\ @@ -16588,13 +17369,13 @@ save folder23 .endd or Sieve filter commands of the form: .display asis -require "fileinto"; +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 +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} \ @@ -16605,7 +17386,7 @@ file = ${if eq{$address_file}{inbox} \ }} \ } .endd -With this setting of \file\, \*inbox*\ refers to the standard mailbox location, +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. @@ -16624,7 +17405,7 @@ the \file\ or \directory\ option is still used if it is set. .section Private options for appendfile .index options||\%appendfile%\ transport -.startconf +.startconf appendfile .conf allow@_fifo boolean false .index fifo (named pipe) @@ -16645,8 +17426,8 @@ 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 +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 @@ -16674,7 +17455,7 @@ 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 +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 @@ -16695,6 +17476,13 @@ message_suffix = "\1\1\1\1\n" 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 @@ -16847,6 +17635,25 @@ 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 @@ -16858,7 +17665,6 @@ 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. -.em .conf maildir@_quota@_directory@_regex string "See below" .index maildir format||quota, directories included in .index quota||maildir, directories included in @@ -16869,7 +17675,7 @@ quota calculation. The default value is 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 +(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 @@ -16877,7 +17683,6 @@ 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)\. -.nem .conf maildir@_retries integer 10 This option specifies the number of times to retry when writing a file in @@ -16922,7 +17727,7 @@ 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 +empty when using MBX format, so this option almost always appears in this combination: .display asis mbx_format = true @@ -16988,15 +17793,13 @@ 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. -.em +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. -.nem 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. @@ -17013,9 +17816,7 @@ 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. -.em -\**Note**\: A value of zero is interpreted as `no quota'. -.nem +\**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 @@ -17059,8 +17860,8 @@ the file length to the file name. For example: 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 +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" @@ -17119,7 +17920,7 @@ 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 +with a single linefeed, so they must be changed to end with \"@\r@\n"\ if \use@_crlf\ is set. @@ -17286,7 +18087,7 @@ If opening fails with any other error, defer delivery. .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. +\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 @@ -17323,11 +18124,11 @@ and/or \*flock()*\ locks) and then deletes the lock file if one was created. .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 +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 @@ -17338,9 +18139,9 @@ 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 +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. @@ -17366,7 +18167,7 @@ option is not set when creation is required, delivery is deferred. .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/<>.H<>P<>.<>)\ in the -given directory. If the delivery is successful, the file is renamed into the +given directory. If the delivery is successful, the file is renamed into the \(new)\ subdirectory. In the file name, <> is the current time of day in seconds, and @@ -17387,16 +18188,25 @@ 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. +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. +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\ +\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 @@ -17406,7 +18216,6 @@ empty, it is ignored. If it starts with an alphanumeric character, a leading colon is inserted. -.em .section Using a maildirsize file .index quota||in maildir delivery .index maildir format||\(maildirsize)\ file @@ -17428,9 +18237,8 @@ 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 participate in quota calculations. See the description of the \maildir@_quota@_directory@_regex\ option above for details. -.nem .section Mailstore delivery @@ -17486,17 +18294,25 @@ expanding the contents of the \directory@_file\ option. .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 another mail message. It -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 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 +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 @@ -17520,7 +18336,7 @@ 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, +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. @@ -17539,7 +18355,7 @@ problems. They are just discarded. .section Private options for autoreply -.startconf +.startconf autoreply .index options||\%autoreply%\ transport .conf bcc string$**$ unset This specifies the addresses that are to receive `blind carbon copies' of the @@ -17578,8 +18394,15 @@ 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 +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 @@ -17619,6 +18442,18 @@ 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 @@ -17661,7 +18496,7 @@ included in the Exim binary. The private options of the \%lmtp%\ transport are as follows: -.startconf +.startconf lmtp .index options||\%lmtp%\ transport .conf batch@_id string$**$ unset @@ -17682,12 +18517,12 @@ 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 +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 +The transport is aborted if the created process or Unix domain socket does not respond to LMTP commands or message input within this timeout. @@ -17717,14 +18552,27 @@ necessary, running as the user \*exim*\. .index transports||\%pipe%\ .index \%pipe%\ transport The \%pipe%\ transport is used to deliver messages via a pipe to a command -running in another process. This can happen in one of two ways: +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 an address to a transport in the normal way, and the transport +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 address (as usual), and the command which is run is specified by the -\command\ option on the transport. An example of this is the use of \%pipe%\ as -a pseudo-remote transport for passing messages to some other delivery mechanism -(such as UUCP). +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 @@ -17732,8 +18580,8 @@ 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 +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 @@ -17743,6 +18591,16 @@ 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 @@ -17757,9 +18615,9 @@ 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 +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 @@ -17881,7 +18739,8 @@ user's home directory if \check@_local@_user\ is set. .section Private options for pipe .index options||\%pipe%\ transport -.startconf + +.startconf pipe .conf allow@_commands "string list$**$" unset .index \%pipe%\ transport||permitted commands @@ -17949,7 +18808,7 @@ 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 +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 @@ -17966,10 +18825,18 @@ 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 @@ -18010,7 +18877,7 @@ message_suffix = 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 +\**Warning**\: This does not apply to a command specified as a transport filter. .conf pipe@_as@_creator boolean false @@ -18034,6 +18901,10 @@ 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 @@ -18042,14 +18913,16 @@ 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 -.em +asterisk. If \ignore@_status\ is false and \return@_output\ is not set, -.nem 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 @@ -18240,7 +19113,7 @@ that are in force when the \helo@_data\, \hosts@_try@_auth\, \interface\, The private options of the \%smtp%\ transport are as follows: .index options||\%smtp%\ transport -.startconf +.startconf smtp .conf allow@_localhost boolean false .index local host||sending to .index fallback||hosts specified on transport @@ -18372,7 +19245,7 @@ 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()*\ +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)\. @@ -18428,12 +19301,15 @@ matches this list. See chapter ~~CHAPTLS for details of TLS. .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 +delivery in cases where there are temporary delivery errors. Section +~~SECTvalhosmax describes in detail how the value of this option is used. + .em -in cases where there are temporary delivery errors. +.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 -Section ~~SECTvalhosmax describes in detail how the value of this option is -used. .conf hosts@_nopass@_tls "host list$**$" unset .index TLS||passing connection @@ -18486,7 +19362,7 @@ hard failure if required. See also \hosts@_try@_auth\, and chapter .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 +\**Note**\: This option affects outgoing mail only. To insist on TLS for incoming messages, use an appropriate ACL. .index authentication||optional in client @@ -18504,11 +19380,9 @@ 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, -.em +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. -.nem For example: .display asis interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 @@ -18552,7 +19426,7 @@ 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 +If the expansion fails, or if a port number cannot be found, delivery is deferred. @@ -18625,26 +19499,24 @@ 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 +\**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. -.em .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. -.nem .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 +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. @@ -18652,18 +19524,18 @@ See chapter ~~CHAPTLS for details of TLS. .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 +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 -outgoing encrypted connection. (There is a global option of the same name for -controlling incoming connections.) +For GnuTLS, the order of the ciphers is a preference order. .nem -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 section -~~SECTreqciphsslgnu). .conf tls@_tempfail@_tryclear boolean true -When the server host is not in \hosts@_require@_tls\, and there is a problem in +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 @@ -18688,13 +19560,19 @@ expansion of this option. See chapter ~~CHAPTLS for details of TLS. .endconf -.section How the value of hosts@_max@_try is used +.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 +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 @@ -18704,7 +19582,7 @@ 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 +\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 @@ -18712,15 +19590,16 @@ 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. +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 used 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: +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 +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 @@ -18732,14 +19611,26 @@ 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 mentioned about, the higher MX hosts would never -be tried at all because the lower MX hosts are never all past their retry -times. - -With the special check, Exim tries least one address from each MX value, even -if the \hosts@_max@_try\ limit has already been reached. - - +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 @@ -18769,7 +19660,7 @@ 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 @@ -18779,12 +19670,10 @@ 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. -.em 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. -.nem 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 @@ -18812,14 +19701,13 @@ 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 -.em .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. +message's processing. -At the start of an ACL for \\MAIL\\, the sender address may have been rewritten +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 @@ -18834,10 +19722,10 @@ 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 +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 +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 @@ -18847,7 +19735,6 @@ Thus, all the rewriting is completed before the \\DATA\\ ACL and 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. -.nem .index envelope sender, rewriting .index rewriting||at transport time @@ -18936,8 +19823,8 @@ 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 +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 @@ -19211,11 +20098,15 @@ the local address is reached. .section Retry rules .index retry||rules -Each retry rule occupies one line and consists of three parts, separated by -white space: a pattern, an error name, and a list of retry parameters. The -pattern must be enclosed in double quotes if it contains white space. The rules -are searched in order until one is found whose pattern matches the failing host -or address. +.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 @@ -19232,13 +20123,13 @@ whereas 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 +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, it must match -a complete address, not just a domain, because that is how regular expressions -work in address lists. +\**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\ @@ -19261,15 +20152,13 @@ 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). -.em 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 +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, -.nem (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 @@ -19301,69 +20190,140 @@ routing to \*a.b.c.example*\ suffers a temporary failure. .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: -.numberpars " " -\*auth@_failed*\: authentication failed when trying to send to a host in the -\hosts@_require@_auth\ list in an \%smtp%\ transport -.nextp -\*refused@_MX*\: connection refused from a host obtained from an MX record -.nextp -\*refused@_A*\: connection refused from a host not obtained from an MX record -.nextp -\*refused*\: any connection refusal -.nextp -\*timeout@_connect@_MX*\: connection timeout from a host obtained from an MX -record -.nextp -\*timeout@_connect@_A*\: connection timeout from a host not obtained from an MX -record -.nextp -\*timeout@_connect*\: any connection timeout -.nextp -\*timeout@_MX*\: any timeout from a host obtained from an MX -record -.nextp -\*timeout@_A*\: any timeout from a host not obtained from an MX -record -.nextp -\*timeout*\: any timeout -.nextp -\*quota*\: quota exceeded in local delivery by \%appendfile%\ -.nextp +.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 -\*quota@_*\<