X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/4f5788623ab3e8456ad254883b6cc018079aab96..2b1c6e3a3a41b680dcefcb87d6c373431f718607:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index a23aab3de..04c00d9f5 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -1,4 +1,4 @@ -. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.2 2006/04/04 14:03:49 ph10 Exp $ +. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.12 2006/07/31 14:19:31 ph10 Exp $ . . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is @@ -18,8 +18,8 @@ . ///////////////////////////////////////////////////////////////////////////// .set ACL "access control lists (ACLs)" -.set previousversion "4.60" -.set version "4.61" +.set previousversion "4.62" +.set version "4.63" . ///////////////////////////////////////////////////////////////////////////// @@ -51,7 +51,7 @@ . --- is suitable for the many tables at the start of the main options chapter; . --- the small number of other 2-column tables override it. -.macro table2 190pt 260pt +.macro table2 196pt 254pt .itable none 0 0 2 $1 left $2 left .endmacro @@ -106,14 +106,14 @@ Specification of the Exim Mail Transfer Agent The Exim MTA -22 March 2006 +27 July 2006 PhilipHazel PH University of Cambridge Computing Service
New Museums Site, Pembroke Street, Cambridge CB2 3QH, England
- 4.61 - 22 March 2006 + 4.63 + 27 July 2006 PH 2006University of Cambridge @@ -410,11 +410,19 @@ The following are the three main Exim mailing lists: .row &'exim-announce@exim.org'& "moderated, low volume announcements list" .endtable +.new You can subscribe to these lists, change your existing subscriptions, and view or search the archives via the mailing lists link on the Exim home page. .cindex "Debian" "mailing list for" If you are using a Debian distribution of Exim, you may wish to subscribe to -the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'&. +the Debian-specific mailing list &'pkg-exim4-users@lists.alioth.debian.org'& +via this web page: +.display +&url(http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users) +.endd +Please ask Debian-specific questions on this list and not on the general Exim +lists. +.wen .section "Exim training" .cindex "training courses" @@ -502,10 +510,12 @@ often the most convenient way of finding your way around. .section "Wish list" .cindex "wish list" +.new A wish list is maintained, containing ideas for new features that have been -submitted. From time to time the file is exported to the ftp site into the file -&_exim4/WishList_&. Items are removed from the list if they get implemented. - +submitted. This used to be a single file that from time to time was exported to +the ftp site into the file &_exim4/WishList_&. However, it has now been +imported into Exim's Bugzilla data. +.wen .section "Contributed material" @@ -1032,10 +1042,13 @@ file containing the envelope and header, and &`-D`& for the data file. .cindex "spool directory" "&_input_& sub-directory" By default all these message files are held in a single directory called &_input_& inside the general Exim spool directory. Some operating systems do -not perform very well if the number of files in a directory gets very large; to +not perform very well if the number of files in a directory gets large; to improve performance in such cases, the &%split_spool_directory%& option can be used. This causes Exim to split up the input files into 62 sub-directories -whose names are single letters or digits. +whose names are single letters or digits. When this is done, the queue is +processed one sub-directory at a time instead of all at once, which can improve +overall performance even when there are not enough files in each directory to +affect file system performance. The envelope information consists of the address of the message's sender and the addresses of the recipients. This information is entirely separate from @@ -1272,9 +1285,13 @@ facility for this purpose. .section "Duplicate addresses" .cindex "case of local parts" .cindex "address duplicate" "discarding" +.cindex "duplicate addresses" Once routing is complete, Exim scans the addresses that are assigned to local and remote transports, and discards any duplicates that it finds. During this -check, local parts are treated as case-sensitive. +check, local parts are treated as case-sensitive. &new("This happens only when +actually delivering a message; when testing routers with &%-bt%&, all the +routed addresses are shown.") + .section "Router preconditions" "SECTrouprecon" @@ -2510,7 +2527,15 @@ getting root. There is further discussion of this issue at the start of chapter .section "Command line options" -The command options are described in alphabetical order below. +.new +Exim's command line options are described in alphabetical order below. If none +of the options that specifies a specific action (such as starting the daemon or +a queue runner, or testing an address, or receiving a message in a specific +format, or listing the queue) are present, and there is at least one argument +on the command line, &%-bm%& (accept a local message on the standard input, +with the arguments specifying the recipients) is assumed. Otherwise, Exim +outputs a brief message about itself and exits. +.wen . //////////////////////////////////////////////////////////////////////////// . Insert a stylized XML comment here, to identify the start of the command line @@ -2727,18 +2752,25 @@ test your relay controls using &%-bh%&. &*Warning 1*&: .cindex "RFC 1413" -You cannot test features of the configuration that rely on -ident (RFC 1413) callouts. These cannot be done when testing using -&%-bh%& because there is no incoming SMTP connection. +.new +You can test features of the configuration that rely on ident (RFC 1413) +information by using the &%-oMt%& option. However, Exim cannot actually perform +an ident callout when testing using &%-bh%& because there is no incoming SMTP +connection. +.wen &*Warning 2*&: Address verification callouts (see section &<>&) are also skipped when testing using &%-bh%&. If you want these callouts to occur, use &%-bhc%& instead. +.new Messages supplied during the testing session are discarded, and nothing is written to any of the real log files. There may be pauses when DNS (and other) lookups are taking place, and of course these may time out. The &%-oMi%& option -can be used to specify a specific IP interface and port if this is important. +can be used to specify a specific IP interface and port if this is important, +and &%-oMaa%& and &%-oMai%& can be used to set parameters as if the SMTP +session were authenticated. +.wen The &'exim_checkaccess'& utility is a &"packaged"& version of &%-bh%& whose output just states whether a given recipient address from a given host is @@ -2980,7 +3012,6 @@ and to write it to the standard output. For example: exim -brt bach.comp.mus.example Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; .endd -.new See chapter &<>& for a description of Exim's retry rules. The first argument, which is required, can be a complete address in the form &'local_part@domain'&, or it can be just a domain name. If the second argument @@ -2994,7 +3025,6 @@ used in setting up retry rules, can be given. For example: exim -brt haydn.comp.mus.example quota_3d Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m .endd -.wen .vitem &%-brw%& .oindex "&%-brw%&" @@ -3099,6 +3129,14 @@ return code is 2 if any address failed outright; it is 1 if no address failed outright but at least one could not be resolved for some reason. Return code 0 is given only when all addresses succeed. +.new +.cindex "duplicate addresses" +&*Note*&: When actually delivering a message, Exim removes duplicate recipient +addresses after routing is complete, so that only one delivery takes place. +This does not happen when testing with &%-bt%&; the full results of routing are +always shown. +.wen + &*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, @@ -3131,11 +3169,14 @@ dynamic testing facilities. .oindex "&%-bv%&" .cindex "verifying address" "using &%-bv%&" .cindex "address" "verification" +.new This option runs Exim in address verification mode, in which each argument is -taken as an address to be verified. During normal operation, verification -happens mostly as a consequence processing a &%verify%& condition in an ACL -(see chapter &<>&). If you want to test an entire ACL, see the &%-bh%& -option. +taken as an address to be verified by the routers. (This does not involve any +verification callouts). During normal operation, verification happens mostly as +a consequence processing a &%verify%& condition in an ACL (see chapter +&<>&). If you want to test an entire ACL, possibly including callouts, +see the &%-bh%& and &%-bhc%& options. +.wen If verification fails, and the caller is not an admin user, no details of the failure are output, because these might contain sensitive information such as @@ -3837,7 +3878,9 @@ followed by a colon and the port number: exim -bs -oMa [10.9.8.7]:1234 .endd The IP address is placed in the &$sender_host_address$& variable, and the -port, if present, in &$sender_host_port$&. +port, if present, in &$sender_host_port$&. &new("If both &%-oMa%& and &%-bh%& +are present on the command line, the sender host IP address is taken from +whichever one is last.") .vitem &%-oMaa%&&~<&'name'&> .oindex "&%-oMaa%&" @@ -3845,24 +3888,32 @@ port, if present, in &$sender_host_port$&. See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMaa%& option sets the value of &$sender_host_authenticated$& (the authenticator name). See chapter &<>& for a discussion of SMTP authentication. +&new("This option can be used with &%-bh%& and &%-bs%& to set up an +authenticated SMTP session without actually using the SMTP AUTH command.") .vitem &%-oMai%&&~<&'string'&> .oindex "&%-oMai%&" .cindex "authentication id" "specifying for local message" +.new See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMai%& option sets the value of &$authenticated_id$& (the id that was authenticated). -This overrides the default value (the caller's login id) for messages from -local sources. See chapter &<>& for a discussion of authenticated -ids. +This overrides the default value (the caller's login id, except with &%-bh%&, +where there is no default) for messages from local sources. See chapter +&<>& for a discussion of authenticated ids. +.wen .vitem &%-oMas%&&~<&'address'&> .oindex "&%-oMas%&" .cindex "authentication sender" "specifying for local message" +.new See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMas%& option sets the authenticated sender value in &$authenticated_sender$&. It overrides the sender address that is created from the caller's login id for -messages from local sources. See chapter &<>& for a discussion of -authenticated senders. +messages from local sources, except when &%-bh%& is used, when there is no +default. For both &%-bh%& and &%-bs%&, an authenticated sender that is +specified on a MAIL command overrides this value. See chapter +&<>& for a discussion of authenticated senders. +.wen .vitem &%-oMi%&&~<&'interface&~address'&> .oindex "&%-oMi%&" @@ -3876,13 +3927,16 @@ using the same syntax as for &%-oMa%&. The interface address is placed in .oindex "&%-oMr%&" .cindex "protocol" "incoming &-- specifying for local message" .cindex "&$received_protocol$&" +.new See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMr%& option sets the received protocol value that is stored in -&$received_protocol$&. However, this applies only when &%-bs%& is not used. For -interactive SMTP input (&%-bs%&), the protocol is always &"local-"& followed by -one of the standard SMTP protocol names (see the description of -&$received_protocol$& in section &<>&). For &%-bS%& (batch SMTP) -however, the protocol can be set by &%-oMr%&. +&$received_protocol$&. However, it does not apply (and is ignored) when &%-bh%& +or &%-bs%& is used. For &%-bh%&, the protocol is forced to one of the standard +SMTP protocol names (see the description of &$received_protocol$& in section +&<>&). For &%-bs%&, the protocol is always &"local-"& followed by +one of those same names. For &%-bS%& (batched SMTP) however, the protocol can +be set by &%-oMr%&. +.wen .vitem &%-oMs%&&~<&'host&~name'&> .oindex "&%-oMs%&" @@ -3895,9 +3949,12 @@ uses the name it is given. .vitem &%-oMt%&&~<&'ident&~string'&> .oindex "&%-oMt%&" .cindex "sender ident string" "specifying for local message" +.new See &%-oMa%& above for general remarks about the &%-oM%& options. The &%-oMt%& option sets the sender ident value in &$sender_ident$&. The default setting for -local callers is the login id of the calling process. +local callers is the login id of the calling process, except when &%-bh%& is +used, when there is no default. +.wen .vitem &%-om%& .oindex "&%-om%&" @@ -4463,12 +4520,10 @@ using this syntax: &`.include`& <&'file name'&> &`.include_if_exists`& <&'file name'&> .endd -.new 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. In all cases, an absolute file name is required. -.wen Includes may be nested to any depth, but remember that Exim reads its configuration file often, so it is a good idea to keep them to a minimum. @@ -4959,7 +5014,7 @@ mentioned at all in the default configuration. -.section "Main configuration settings" +.section "Main configuration settings" "SECTdefconfmain" The main (global) configuration option settings must always come first in the file. The first thing you'll see in the file, after some initial comments, is the line @@ -5035,6 +5090,44 @@ content-scanning extension. The first specifies the interface to the virus scanner, and the second specifies the interface to SpamAssassin. Further details are given in chapter &<>&. +.new +Three more commented-out option settings follow: +.code +# tls_advertise_hosts = * +# tls_certificate = /etc/ssl/exim.crt +# tls_privatekey = /etc/ssl/exim.pem +.endd +These are example settings that can be used when Exim is compiled with +support for TLS (aka SSL) as described in section &<>&. The +first one specifies the list of clients that are allowed to use TLS when +connecting to this server; in this case the wildcard means all clients. The +other options specify where Exim should find its TLS certificate and private +key, which together prove the server's identity to any clients that connect. +More details are given in chapter &<>&. + +Another two commented-out option settings follow: +.code +# daemon_smtp_ports = 25 : 465 : 587 +# tls_on_connect_ports = 465 +.endd +.cindex "port" "465 and 587" +.cindex "port" "for message submission" +.cindex "message" "submission, ports for" +.cindex "ssmtp protocol" +.cindex "smtps protocol" +.cindex "SMTP" "ssmtp protocol" +.cindex "SMTP" "smtps protocol" +These options provide better support for roaming users who wish to use this +server for message submission. They are not much use unless you have turned on +TLS (as described in the previous paragraph) and authentication (about which +more in section &<>&). The usual SMTP port 25 is often blocked +on end-user networks, so RFC 4409 specifies that message submission should use +port 587 instead. However some software (notably Microsoft Outlook) cannot be +configured to use port 587 correctly, so these settings also enable the +non-standard &"smtps"& (aka &"ssmtp"&) port 465 (see section +&<>&). +.wen + Two more commented-out options settings follow: .code # qualify_domain = @@ -5092,7 +5185,7 @@ The next two lines are concerned with &'ident'& callbacks, as defined by RFC 1413 (hence their names): .code rfc1413_hosts = * -rfc1413_query_timeout = 30s +rfc1413_query_timeout = 5s .endd These settings cause Exim to make ident callbacks for all incoming SMTP calls. You can limit the hosts to which these calls are made, or change the timeout @@ -5274,51 +5367,48 @@ accept authenticated = * This statement accepts the address if the client host has authenticated itself. Submission mode is again specified, on the grounds that such messages are most likely to come from MUAs. The default configuration does not define any -authenticators, which means that no client can in fact authenticate. You will -need to add authenticator definitions if you want to make use of this ACL -statement. +authenticators, though it does include some nearly complete commented-out +examples described in &<>&. This means that no client can in +fact authenticate until you complete the authenticator definitions. +.new +.code +require message = relay not permitted + domains = +local_domains : +relay_domains +.endd +This statement rejects the address if its domain is neither a local domain nor +one of the domains for which this host is a relay. +.code +require verify = recipient +.endd +This statement requires the recipient address to be verified; if verification +fails, the address is rejected. .code # deny message = rejected because $sender_host_address \ # is in a black list at $dnslist_domain\n\ # $dnslist_text # dnslists = black.list.example # -# warn message = X-Warning: $sender_host_address is \ -# in a black list at $dnslist_domain +# warn dnslists = black.list.example +# add_header = X-Warning: $sender_host_address is in \ +# a black list at $dnslist_domain # log_message = found in $dnslist_domain -# dnslists = black.list.example .endd These commented-out lines are examples of how you could configure Exim to check sending hosts against a DNS black list. The first statement rejects messages -from blacklisted hosts, whereas the second merely inserts a warning header +from blacklisted hosts, whereas the second just inserts a warning header line. .code -accept domains = +local_domains - endpass - verify = recipient -.endd -This statement accepts the incoming recipient address if its domain is one of -the local domains, but only if the address can be verified. Verification of -local addresses normally checks both the local part and the domain. The -&%endpass%& line needs some explanation: if the condition above &%endpass%& -fails, that is, if the address is not in a local domain, control is passed to -the next ACL statement. However, if the condition below &%endpass%& fails, that -is, if a recipient in a local domain cannot be verified, access is denied and -the recipient is rejected. -.code -accept domains = +relay_to_domains - endpass - verify = recipient +# require verify = csa .endd -This statement accepts the incoming recipient address if its domain is one of -the domains for which this host is a relay, but again, only if the address can -be verified. +This commented-out line is an example of how you could turn on client SMTP +authorization (CSA) checking. Such checks do DNS lookups for special SRV +records. .code -deny message = relay not permitted +accept .endd -The final statement denies access, giving a specific error message. Reaching -the end of the ACL also causes access to be denied, but with the generic -message &"administrative prohibition"&. +The final statement in the first ACL unconditionally accepts any recipient +address that has successfully passed all the previous tests. +.wen .code acl_check_data: .endd @@ -5623,14 +5713,52 @@ rewriting rules in the default configuration file. -.section "Authenticators configuration" +.section "Authenticators configuration" "SECTdefconfauth" .cindex "AUTH" "configuration" The authenticators section of the configuration, introduced by .code begin authenticators .endd -defines mechanisms for the use of the SMTP AUTH command. No authenticators -are specified in the default configuration file. +defines mechanisms for the use of the SMTP AUTH command. The default +configuration file contains two commented-out example authenticators +which support plaintext username/password authentication using the +standard PLAIN mechanism and the traditional but non-standard LOGIN +mechanism, with Exim acting as the server. PLAIN and LOGIN are enough +to support most MUA software. + +The example PLAIN authenticator looks like this: +.code +#PLAIN: +# driver = plaintext +# server_set_id = $auth2 +# server_prompts = : +# server_condition = Authentication is not yet configured +# server_advertise_condition = ${if def:tls_cipher } +.endd +And the example LOGIN authenticator looks like this: +.code +#LOGIN: +# driver = plaintext +# server_set_id = $auth1 +# server_prompts = <| Username: | Password: +# server_condition = Authentication is not yet configured +# server_advertise_condition = ${if def:tls_cipher } +.endd + +The &%server_set_id%& option makes Exim remember the authenticated username +in &$authenticated_id$&, which can be used later in ACLs or routers. The +&%server_prompts%& option configures the &(plaintext)& authenticator so +that it implements the details of the specific authentication mechanism, +i.e. PLAIN or LOGIN. The &%server_advertise_condition%& setting controls +when Exim offers authentication to clients; in the examples, this is only +when TLS or SSL has been started, so to enable the authenticators you also +need to add support for TLS as described in &<>&. + +The &%server_condition%& setting defines how to verify that the username and +password are correct. In the examples it just produces an error message. +To make the authenticators work, you can use a string expansion +expression like one of the examples in &<>&. + .ecindex IIDconfiwal @@ -5932,16 +6060,21 @@ lookup types support only literal keys. &*Warning 2*&: In a host list, you must always use &(net-iplsearch)& so that the implicit key is the host's IP address rather than its name (see section &<>&). - .next +.new .cindex "linear search" .cindex "lookup" "lsearch" .cindex "lsearch lookup type" +.cindex "case sensitivity" "in lsearch lookup" &(lsearch)&: The given file is a text file that is searched linearly for a line beginning with the search key, terminated by a colon or white space or the -end of the line. The first occurrence that is found in the file is used. White -space between the key and the colon is permitted. The remainder of the line, -with leading and trailing white space removed, is the data. This can be +end of the line. The search is case-insensitive; that is, upper and lower case +letters are treated as the same. The first occurrence of the key that is found +in the file is used. +.wen + +White space between the key and the colon is permitted. The remainder of the +line, with leading and trailing white space removed, is the data. This can be continued onto subsequent lines by starting them with any amount of white space, but only a single space character is included in the data at such a junction. If the data begins with a colon, the key must be terminated by a @@ -5985,8 +6118,12 @@ the file may be wildcarded. The difference between these two lookup types is that for &(wildlsearch)&, each key in the file is string-expanded before being used, whereas for &(nwildlsearch)&, no expansion takes place. -Like &(lsearch)&, the testing is done case-insensitively. The following forms -of wildcard are recognized: +.new +.cindex "case sensitivity" "in (n)wildlsearch lookup" +Like &(lsearch)&, the testing is done case-insensitively. However, keys in the +file that are regular expressions can be made case-sensitive by the use of +&`(-i)`& within the pattern. The following forms of wildcard are recognized: +.wen . ==== As this is a nested list, any displays it contains must be indented . ==== as otherwise they are too far to the left. @@ -6009,6 +6146,15 @@ string-expanded, the equivalent entry is: .code ^\d+\.a\.b data for .a.b .endd +.new +The case-insensitive flag is set at the start of compiling the regular +expression, but it can be turned off by using &`(-i)`& at an appropriate point. +For example, to make the entire pattern case-sensitive: +.code + ^(?-i)\d+\.a\.b data for .a.b +.endd +.wen + If the regular expression contains white space or colon characters, you must either quote it (see &(lsearch)& above), or represent these characters in other ways. For example, &`\s`& can be used for white space and &`\x3A`& for a @@ -6055,9 +6201,9 @@ many of them are given in later sections. are given in the supplied query. The resulting data is the contents of the records. See section &<>&. .next -.cindex "Interbase lookup type" -.cindex "lookup" "Interbase" -&(ibase)&: This does a lookup in an Interbase database. +.cindex "InterBase lookup type" +.cindex "lookup" "InterBase" +&(ibase)&: This does a lookup in an InterBase database. .next .cindex "LDAP" "lookup type" .cindex "lookup" "LDAP" @@ -6357,9 +6503,9 @@ an expansion string could contain: ${lookup dnsdb{mx=a.b.example}{$value}fail} .endd If the lookup succeeds, the result is placed in &$value$&, which in this case -is used on its own as the result. If the lookup succeeds, the &`fail`& keyword -causes a &'forced expansion failure'& &-- see section &<>& for -an explanation of what this means. +is used on its own as the result. If the lookup &new("does not succeed,") the +&`fail`& keyword causes a &'forced expansion failure'& &-- see section +&<>& for an explanation of what this means. 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 @@ -6674,16 +6820,21 @@ be preceded by any number of <&'name'&>=<&'value'&> settings, separated by spaces. If a value contains spaces it must be enclosed in double quotes, and when double quotes are used, backslash is interpreted in the usual way inside them. The following names are recognized: +.new .display &`DEREFERENCE`& set the dereferencing parameter &`NETTIME `& set a timeout for a network operation &`USER `& set the DN, for authenticating the LDAP bind &`PASS `& set the password, likewise +&`REFERRALS `& set the referrals parameter &`SIZE `& set the limit for the number of entries returned &`TIME `& set the maximum waiting time for a query .endd The value of the DEREFERENCE parameter must be one of the words &"never"&, -&"searching"&, &"finding"&, or &"always"&. +&"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter +must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP +library from trying to follow referrals issued by the LDAP server. +.wen The name CONNECT is an obsolete name for NETTIME, retained for backwards compatibility. This timeout (specified as a number of seconds) is @@ -6829,7 +6980,7 @@ operator is to double any quote characters within the text. .section "SQL lookups" "SECTsql" .cindex "SQL lookup types" -Exim can support lookups in Interbase, MySQL, Oracle, PostgreSQL, and SQLite +Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, and SQLite databases. Queries for these databases contain SQL statements, so an example might be .code @@ -6856,16 +7007,16 @@ If the result of the query yields more than one row, it is all concatenated, with a newline between the data for each row. -.section "More about MySQL, PostgreSQL, Oracle, and Interbase" +.section "More about MySQL, PostgreSQL, Oracle, and InterBase" .cindex "MySQL" "lookup type" .cindex "PostgreSQL lookup type" .cindex "lookup" "MySQL" .cindex "lookup" "PostgreSQL" .cindex "Oracle" "lookup type" .cindex "lookup" "Oracle" -.cindex "Interbase lookup type" -.cindex "lookup" "Interbase" -If any MySQL, PostgreSQL, Oracle, or Interbase lookups are used, the +.cindex "InterBase lookup type" +.cindex "lookup" "InterBase" +If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%& option (as appropriate) must be set to a colon-separated list of server information. Each item in the list is a slash-separated list of four items: @@ -7102,9 +7253,12 @@ 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. +.new 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. +in the previous section. You could also use the &(wildlsearch)& or +&(nwildlsearch)&, but there is no advantage in doing this. +.wen @@ -7692,11 +7846,9 @@ Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same list. The effect of each one lasts until the next, or until the end of the list. -.new &*Note*&: This section applies to permanent lookup failures. It does &'not'& apply to temporary DNS errors. They always cause a defer action (except when &%dns_again_means_nonexist%& converts them into permanent errors). -.wen @@ -7802,7 +7954,6 @@ data, the list is empty and matches nothing. The empty sender can also be detected by a regular expression that matches an empty string, and by a query-style lookup that succeeds when &$sender_address$& is empty. -.new Non-empty items in an address list can be straightforward email addresses. For example: .code @@ -7854,7 +8005,6 @@ deny senders = \N^.*this.*@example\.com$\N : \ .endd The &`\N`& sequences are removed by the expansion, so these items do indeed start with &"^"& by the time they are being interpreted as address patterns. -.wen .next .cindex "address list" "lookup for complete address" @@ -8645,23 +8795,36 @@ locks out the use of this expansion item in filter files. .cindex "expansion" "inserting from a socket" .cindex "socket" "use of in expansion" .cindex "&%readsocket%& expansion item" -This item inserts data that is read from a Unix domain socket into the expanded -string. The minimal way of using it uses just two arguments: +This item inserts data from a Unix domain or Internet socket into the expanded +string. The minimal way of using it uses just two arguments, as in these +examples: .code ${readsocket{/socket/name}{request string}} +${readsocket{inet:some.host:1234}{request string}} .endd -Exim connects to the socket, writes the request string (unless it is an -empty string) and reads from the socket until an end-of-file is read. A timeout -of 5 seconds is applied. Additional, optional arguments extend what can be -done. Firstly, you can vary the timeout. For example: +For a Unix domain socket, the first substring must be the path to the socket. +For an Internet socket, the first substring must contain &`inet:`& followed by +a host name or IP address, followed by a colon and a port, which can be a +number or the name of a TCP port in &_/etc/services_&. An IP address may +optionally be enclosed in square brackets. This is best for IPv6 addresses. For +example: +.code +${readsocket{inet:[::1]:1234}{request string}} +.endd +Only a single host name may be given, but if looking it up yields more than +one IP address, they are each tried in turn until a connection is made. For +both kinds of socket, Exim makes a connection, writes the request string +(unless it is an empty string) and reads from the socket until an end-of-file +is read. A timeout of 5 seconds is applied. Additional, optional arguments +extend what can be done. Firstly, you can vary the timeout. For example: .code -${readsocket{/socket/name}{request-string}{3s}} +${readsocket{/socket/name}{request string}{3s}} .endd A fourth argument allows you to change any newlines that are in the data that is read, in the same way as for &%readfile%& (see above). This example turns them into spaces: .code -${readsocket{/socket/name}{request-string}{3s}{ }} +${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }} .endd As with all expansions, the substrings are expanded before the processing happens. Errors in these sub-expansions cause the expansion to fail. In @@ -8672,7 +8835,7 @@ Failure to create a socket file descriptor; .next Failure to connect the socket; .next -Failure to write the request-string; +Failure to write the request string; .next Timeout on reading from the socket. .endlist @@ -8681,14 +8844,14 @@ By default, any of these errors causes the expansion to fail. However, if you supply a fifth substring, it is expanded and used when any of the above errors occurs. For example: .code -${readsocket{/socket/name}{request-string}{3s}{\n}\ +${readsocket{/socket/name}{request string}{3s}{\n}\ {socket failure}} .endd -You can test for the existence of the socket by wrapping this expansion in -&`${if exists`&, but there is a race condition between that test and the -actual opening of the socket, so it is safer to use the fifth argument if you -want to be absolutely sure of avoiding an expansion error for a non-existent -socket. +You can test for the existence of a Unix domain socket by wrapping this +expansion in &`${if exists`&, but there is a race condition between that test +and the actual opening of the socket, so it is safer to use the fifth argument +if you want to be absolutely sure of avoiding an expansion error for a +non-existent Unix domain socket, or a failure to connect to an Internet socket. The &(redirect)& router has an option called &%forbid_filter_readsocket%& which locks out the use of this expansion item in filter files. @@ -8902,11 +9065,13 @@ All operations are carried out using integer arithmetic. Plus and minus have a lower priority than times, divide, and remainder; operators with the same priority are evaluated from left to right. +.new 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. +decimal, even if they start with a leading zero; hexadecimal numbers are not +permitted. This can be useful when processing numbers extracted from dates or +times, which often do have leading zeros. +.wen 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 @@ -9116,15 +9281,6 @@ For single-key lookup types, no quoting is ever necessary and this operator yields an unchanged string. -.vitem &*${rxquote:*&<&'string'&>&*}*& -.cindex "quoting" "in regular expressions" -.cindex "regular expressions" "quoting" -.cindex "&%rxquote%& expansion item" -The &%rxquote%& operator inserts a backslash before any non-alphanumeric -characters in its argument. This is useful when substituting the values of -variables or headers inside regular expressions. - - .vitem &*${rfc2047:*&<&'string'&>&*}*& .cindex "expansion" "RFC 2047" .cindex "RFC 2047" "expansion operator" @@ -9144,6 +9300,15 @@ characters. +.vitem &*${rxquote:*&<&'string'&>&*}*& +.cindex "quoting" "in regular expressions" +.cindex "regular expressions" "quoting" +.cindex "&%rxquote%& expansion item" +The &%rxquote%& operator inserts a backslash before any non-alphanumeric +characters in its argument. This is useful when substituting the values of +variables or headers inside regular expressions. + + .vitem &*${sha1:*&<&'string'&>&*}*& .cindex "SHA-1 hash" .cindex "expansion" "SHA-1 hashing" @@ -9199,13 +9364,11 @@ ${substr{}{}{}} See the description of the general &%substr%& item above for details. The abbreviation &%s%& can be used when &%substr%& is used as an operator. -.new .vitem &*${time_eval:*&<&'string'&>&*}*& .cindex "&%time_eval%& expansion item" .cindex "time interval" "decoding" This item converts an Exim time interval such as &`2d4h5m`& into a number of seconds. -.wen .vitem &*${time_interval:*&<&'string'&>&*}*& .cindex "&%time_interval%& expansion item" @@ -9561,8 +9724,15 @@ specified. Thus, the following are equivalent: ${if match_ip{$sender_host_address}{lsearch;/some/file}... ${if match_ip{$sender_host_address}{net-lsearch;/some/file}... .endd +.new You do need to specify the &`net-`& prefix if you want to specify a -specific address mask, for example, by using &`net24-`&. +specific address mask, for example, by using &`net24-`&. However, unless you +are combining a &%match_ip%& condition with others, it is usually neater to use +an expansion lookup such as: +.code + ${lookup{${mask:$sender_host_address/24}}lsearch{/some/file}... +.endd +.wen .endlist ilist Consult section &<>& for further details of these patterns. @@ -9627,13 +9797,15 @@ characters. In the usual way, these have to be doubled to avoid being taken as separators. If the data is being inserted from a variable, the &%sg%& expansion item can be used to double any existing colons. For example, the configuration of a LOGIN authenticator might contain this setting: +.new .code -server_condition = ${if pam{$1:${sg{$2}{:}{::}}}{yes}{no}} +server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}} .endd For a PLAIN authenticator you could use: .code -server_condition = ${if pam{$2:${sg{$3}{:}{::}}}{yes}{no}} +server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}} .endd +.wen In some operating systems, PAM authentication can be done only from a process running as root. Since Exim is running as the Exim user when receiving messages, this means that PAM cannot be used directly in those systems. @@ -9668,9 +9840,11 @@ access to the &_/var/pwcheck_& directory. The &%pwcheck%& condition takes one argument, which must be the user name and password, separated by a colon. For example, in a LOGIN authenticator configuration, you might have this: +.new .code -server_condition = ${if pwcheck{$1:$2}{1}{0}} +server_condition = ${if pwcheck{$auth1:$auth2}} .endd +.wen .vitem &*queue_running*& .cindex "queue runner" "detecting when delivering from" .cindex "expansion" "queue runner test" @@ -9707,7 +9881,7 @@ 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: .code -server_condition = ${if radius{}{yes}{no}} +server_condition = ${if radius{}} .endd @@ -9734,9 +9908,11 @@ from the Cyrus SASL library. Up to four arguments can be supplied to the &%saslauthd%& condition, but only two are mandatory. For example: +.new .code -server_condition = ${if saslauthd{{$1}{$2}}{1}{0}} +server_condition = ${if saslauthd{{$auth1}{$auth2}}} .endd +.wen The service and the realm are optional (which is why the arguments are enclosed in their own set of braces). For details of the meaning of the service and realm, and how to run the daemon, consult the Cyrus documentation. @@ -9800,9 +9976,9 @@ condition. .vitem "&$acl_c0$& &-- &$acl_c19$&" Values can be placed in these variables by the &%set%& modifier in an ACL. The values persist throughout the lifetime of an SMTP connection. They can be used -to pass information between ACLs and different invocations of the same ACL. -When a message is received, the values of these variables are saved with the -message, and can be accessed by filters, routers, and transports during +to pass information between ACLs and between different invocations of the same +ACL. When a message is received, the values of these variables are saved with +the message, and can be accessed by filters, routers, and transports during subsequent delivery. .vitem "&$acl_m0$& &-- &$acl_m19$&" @@ -9873,12 +10049,10 @@ to the relevant file. When, as a result of aliasing or forwarding, a message is directed to a pipe, this variable holds the pipe command when the transport is running. -.new .vitem "&$auth1$& &-- &$auth3$&" .cindex "&$auth1$&, &$auth2$&, etc" These variables are used in SMTP authenticators (see chapters &<>&&--&<>&). Elsewhere, they are empty. -.wen .vitem &$authenticated_id$& .cindex "authentication" "id" @@ -9888,9 +10062,14 @@ preserve some of the authentication information in the variable &$authenticated_id$& (see chapter &<>&). For example, a user/password authenticator configuration might preserve the user name for use in the routers. Note that this is not the same information that is saved in -&$sender_host_authenticated$&. When a message is submitted locally (that is, -not over a TCP connection), the value of &$authenticated_id$& is the login name -of the calling process. +&$sender_host_authenticated$&. +&new("When a message is submitted locally (that is, not over a TCP connection) +the value of &$authenticated_id$& is normally the login name of the calling +process. However, a trusted user can override this by means of the &%-oMai%& +command line option.") + + + .vitem &$authenticated_sender$& .cindex "sender" "authenticated" @@ -9904,10 +10083,13 @@ described in section &<>&. Unless the data is the string available during delivery in the &$authenticated_sender$& variable. If the sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the data. +.new .cindex "&$qualify_domain$&" When a message is submitted locally (that is, not over a TCP connection), the value of &$authenticated_sender$& is an address constructed from the login -name of the calling process and &$qualify_domain$&. +name of the calling process and &$qualify_domain$&, except that a trusted user +can override this by means of the &%-oMas%& command line option. +.wen .vitem &$authentication_failed$& @@ -10110,19 +10292,27 @@ When running a filter test via the &%-bf%& option, &$home$& is set to the value of the environment variable HOME. .vitem &$host$& +.new .cindex "&$host$&" -When the &(smtp)& transport is expanding its options for encryption using TLS, -&$host$& contains the name of the host to which it is connected. Likewise, when -used in the client part of an authenticator configuration (see chapter -&<>&), &$host$& contains the name of the server to which the -client is connected. +If a router assigns an address to a transport (any transport), and passes a +list of hosts with the address, the value of &$host$& when the transport starts +to run is the name of the first host on the list. Note that this applies both +to local and remote transports. .cindex "transport" "filter" .cindex "filter" "transport filter" -When used in a transport filter (see chapter &<>&) -&$host$& refers to the host involved in the current connection. When a local -transport is run as a result of a router that sets up a host list, &$host$& -contains the name of the first host. +For the &(smtp)& transport, if there is more than one host, the value of +&$host$& changes as the transport works its way through the list. In +particular, when the &(smtp)& transport is expanding its options for encryption +using TLS, or for specifying a transport filter (see chapter +&<>&), &$host$& contains the name of the host to which it +is connected. + +When used in the client part of an authenticator configuration (see chapter +&<>&), &$host$& contains the name of the server to which the +client is connected. +.wen + .vitem &$host_address$& .cindex "&$host_address$&" @@ -10513,7 +10703,7 @@ This variable contains the current process id. .cindex "transport" "filter" .cindex "&$pipe_addresses$&" This is not an expansion variable, but is mentioned here because the string -&"$pipe_addresses"& is handled specially in the command specification for the +&`$pipe_addresses`& is handled specially in the command specification for the &(pipe)& transport (chapter &<>&) and in transport filters (described under &%transport_filter%& in chapter &<>&). It cannot be used in general expansion strings, and provokes an &"unknown @@ -10662,8 +10852,12 @@ in these two cases: .olist In a system filter file. .next -In the ACLs associated with the DATA command, that is, the ACLs defined by -&%acl_smtp_predata%& and &%acl_smtp_data%&. +.new +In the ACLs associated with the DATA command and with non-SMTP messages, that +is, the ACLs defined by &%acl_smtp_predata%&, &%acl_smtp_data%&, +&%acl_smtp_mime%&, &%acl_not_smtp_start%&, &%acl_not_smtp%&, and +&%acl_not_smtp_mime%&. +.wen .endlist @@ -10674,13 +10868,22 @@ envelope recipients that came with the message. Duplicates are not excluded from the count. While a message is being received over SMTP, the number increases for each accepted recipient. It can be referenced in an ACL. + +.new +.vitem &$regex_match_string$& +.cindex "&$regex_match_string$&" +This variable is set to contain the matching regular expression after a +&%regex%& ACL condition has matched (see section &<>&). +.wen + + .vitem &$reply_address$& .cindex "&$reply_address$&" When a message is being processed, this variable contains the contents of the &'Reply-To:'& header line if one exists and it is not empty, or otherwise the -contents of the &'From:'& header line. &new("Apart from the removal of leading +contents of the &'From:'& header line. Apart from the removal of leading white space, the value is not processed in any way. In particular, no RFC 2047 -decoding or character code translation takes place.") +decoding or character code translation takes place. .vitem &$return_path$& .cindex "&$return_path$&" @@ -10771,7 +10974,7 @@ the argument of a HELO or EHLO command. This is omitted if it is identical to the verified host name or to the host's IP address in square brackets. .vitem &$sender_helo_name$& -.cindex "&$sender_hslo_name$&" +.cindex "&$sender_helo_name$&" When a message is received from a remote host that has issued a HELO or EHLO command, the argument of that command is placed in this variable. It is also set if HELO or EHLO is used when a message is received using SMTP locally via @@ -10808,10 +11011,12 @@ 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"&. +.new 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$& +in the same Exim process, but it does try again if &$host_lookup_deferred$& is set to &"1"&. +.wen Exim does not automatically look up every calling host's name. If you want maximum efficiency, you should arrange your configuration so that it avoids @@ -11380,7 +11585,6 @@ instead of &[getaddrinfo()]&. (Before version 4.14, it always used this function.) Of course, this means that the additional functionality of &[getaddrinfo()]& &-- recognizing scoped addresses &-- is lost. -.new .section "Disabling IPv6" .cindex "IPv6" "disabling" Sometimes it happens that an Exim binary that was compiled with IPv6 support is @@ -11399,7 +11603,6 @@ disable it for certain hosts or domains. You can use the &%dns_ipv4_lookup%& option to globally suppress the lookup of AAAA records for specified domains, and you can use the &%ignore_target_hosts%& generic router option to ignore IPv6 addresses in an individual router. -.wen @@ -11660,6 +11863,9 @@ listed in more than one group. .table2 .row &%acl_not_smtp%& "ACL for non-SMTP messages" .row &%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" +.new +.row &%acl_not_smtp_start%& "ACL for start of non-SMTP message" +.wen .row &%acl_smtp_auth%& "ACL for AUTH" .row &%acl_smtp_connect%& "ACL for connection" .row &%acl_smtp_data%& "ACL for DATA" @@ -11825,7 +12031,7 @@ See also the &'Policy controls'& section above. .row &%check_rfc2047_length%& "check length of RFC 2047 &""encoded &&& words""&" .row &%delivery_date_remove%& "from incoming messages" -.row &%envelope_to_remote%& "from incoming messages" +.row &%envelope_to_remove%& "from incoming messages" .row &%extract_addresses_remove_arguments%& "affects &%-t%& processing" .row &%headers_charset%& "default for translations" .row &%qualify_domain%& "default for senders" @@ -11913,14 +12119,23 @@ Consequently, this option is turned off by default. .option acl_not_smtp main string&!! unset .cindex "&ACL;" "for non-SMTP messages" .cindex "non-SMTP messages" "ACLs for" -This option defines the ACL that is run when a non-SMTP message is on the point -of being accepted. See chapter &<>& for further details. +This option defines the ACL that is run when a non-SMTP message has been +read and is on the point of being accepted. See chapter &<>& for +further details. .option acl_not_smtp_mime main string&!! unset This option defines the ACL that is run for individual MIME parts of non-SMTP messages. It operates in exactly the same way as &%acl_smtp_mime%& operates for SMTP messages. +.new +.option acl_not_smtp_start main string&!! unset +.cindex "&ACL;" "at start of non-SMTP message" +.cindex "non-SMTP messages" "ACLs for" +This option defines the ACL that is run before Exim starts reading a +non-SMTP message. See chapter &<>& for further details. +.wen + .option acl_smtp_auth main string&!! unset .cindex "&ACL;" "setting up for SMTP commands" .cindex "AUTH" "ACL for" @@ -12137,7 +12352,6 @@ delivery software."& It is not used if &%bounce_message_file%& is set. .option bounce_return_body main boolean true .cindex "bounce message" "including body" -.new This option controls whether the body of an incoming message is included in a bounce message when &%bounce_return_message%& is true. The default setting causes the entire message, both header and body, to be returned (subject to the @@ -12146,14 +12360,11 @@ message header is included. In the case of a non-SMTP message containing an error that is detected during reception, only those header lines preceding the point at which the error was detected are returned. .cindex "bounce message" "including original" -.wen .option bounce_return_message main boolean true -.new If this option is set false, none of the original message is included in bounce messages generated by Exim. See also &%bounce_return_size_limit%& and &%bounce_return_body%&. -.wen .option bounce_return_size_limit main integer 100K @@ -12344,13 +12555,20 @@ deferred addresses have the same domain, it is set in &$domain$& during the expansion. Otherwise &$domain$& is empty. If the result of the expansion is a forced failure, an empty string, or a string matching any of &"0"&, &"no"& or &"false"& (the comparison being done caselessly) then the warning message is -not sent. The default is +not sent. The default is: +.new .code -delay_warning_condition = \ - ${if match{$h_precedence:}{(?i)bulk|list|junk}{no}{yes}} +delay_warning_condition = ${if or {\ + { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\ + { match{$h_precedence:}{(?i)bulk|list|junk} }\ + { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\ + } {no}{yes}} .endd -which suppresses the sending of warnings about messages that have &"bulk"&, -&"list"& or &"junk"& in a &'Precedence:'& header. +This suppresses the sending of warnings for messages that contain &'List-ID:'&, +&'List-Post:'&, or &'List-Subscribe:'& headers, or have &"bulk"&, &"list"& or +&"junk"& in a &'Precedence:'& header, or have &"auto-generated"& or +&"auto-replied"& in an &'Auto-Submitted:'& header. +.wen .option deliver_drop_privilege main boolean false .cindex "unprivileged delivery" @@ -12380,7 +12598,6 @@ removed at the time the message is received, to avoid any problems that might occur when a delivered message is subsequently sent on to some other recipient. -.new .option disable_ipv6 main boolean false .cindex "IPv6" "disabling" If this option is set true, even if the Exim binary has IPv6 support, no IPv6 @@ -12388,7 +12605,6 @@ activities take place. AAAA records are never looked up, and any IPv6 addresses that are listed in &%local_interfaces%&, data for the &%manualroute%& router, etc. are ignored. If IP literals are enabled, the &(ipliteral)& router declines to handle IPv6 literal addresses. -.wen .option dns_again_means_nonexist main "domain list&!!" unset @@ -12404,18 +12620,15 @@ by a setting such as this: .code dns_again_means_nonexist = *.in-addr.arpa .endd -.new This option applies to all DNS lookups that Exim does. It also applies when the &[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors, since these are most likely to be caused by DNS lookup problems. 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 this global option. -.wen .option dns_check_names_pattern main string "see below" .cindex "DNS" "pre-check of name syntax" -.new When this option is set to a non-empty string, it causes Exim to check domain names for characters that are not allowed in host names before handing them to the DNS resolver, because some resolvers give temporary errors for names that @@ -12433,7 +12646,6 @@ permitted in host names, but they are found in certain NS records (which can be accessed in Exim by using a &%dnsdb%& lookup). If you set &%allow_utf8_domains%&, you must modify this pattern, or set the option to an empty string. -.wen .option dns_csa_search_limit main integer 5 This option controls the depth of parental searching for CSA SRV records in the @@ -12447,7 +12659,6 @@ section &<>&. .option dns_ipv4_lookup main "domain list&!!" unset .cindex "IPv6" "DNS lookup for AAAA records" .cindex "DNS" "IPv6 lookup for AAAA records" -.new When Exim is compiled with IPv6 support and &%disable_ipv6%& is not set, it looks for IPv6 address records (AAAA records) as well as IPv4 address records (A records) when trying to find IP addresses for hosts, unless the host's @@ -12456,7 +12667,6 @@ domain matches this list. This is a fudge to help with name servers that give big delays or otherwise do not work for the AAAA record type. In due course, when the world's name servers have all been upgraded, there should be no need for this option. -.wen .option dns_retrans main time 0s @@ -12524,7 +12734,6 @@ variables &$0$&, &$1$&, etc. are set in the normal way. .option errors_reply_to main string unset .cindex "bounce message" "&'Reply-to:'& in" -.new By default, Exim's bounce and delivery warning messages contain the header line .display &`From: Mail Delivery System `& @@ -12546,7 +12755,6 @@ address. However, if a warning message that is generated by the &%quota_warn_message%& option in an &(appendfile)& transport contain its own &'Reply-To:'& header line, the value of the &%errors_reply_to%& option is not used. -.wen .option exim_group main string "compile-time configured" @@ -13369,6 +13577,13 @@ sequences, primarily to avoid messing up the layout. If &%print_topbitchars%& is set, code values of 128 and above are also considered to be printing characters. +This option also affects the header syntax checks performed by the +&(autoreply)& transport, and whether Exim uses RFC 2047 encoding of +the user's full name when constructing From: and Sender: addresses (as +described in section &<>&). Setting this option can cause +Exim to generate eight bit message headers that do not conform to the +standards. + .option process_log_path main string unset .cindex "process log path" @@ -13489,16 +13704,14 @@ to override; they are accepted, but ignored. If this option is set, queue runs happen in order of message arrival instead of in an arbitrary order. For this to happen, a complete list of the entire queue must be set up before the deliveries start. When the queue is all held in a -single directory (the default), - -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. +single directory (the default), 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. @@ -13696,13 +13909,11 @@ past failures. .option retry_interval_max main time 24h .cindex "retry" "limit on interval" .cindex "limit" "on retry interval" -.new Chapter &<>& describes Exim's mechanisms for controlling the intervals between delivery attempts for messages that cannot be delivered straight away. This option sets an overall limit to the length of time between retries. It cannot be set greater than 24 hours; any attempt to do so forces the default value. -.wen .option return_path_remove main boolean true @@ -13727,9 +13938,7 @@ This option is an obsolete synonym for &%bounce_return_size_limit%&. RFC 1413 identification calls are made to any client host which matches an item in the list. -.new .option rfc1413_query_timeout main time 5s -.wen .cindex "RFC 1413" "query timeout" .cindex "timeout" "for RFC 1413 call" This sets the timeout on RFC 1413 identification calls. If it is set to zero, @@ -14419,13 +14628,11 @@ further details, see section &<>&. .option tls_privatekey main string&!! unset .cindex "TLS" "server private key; location of" -.new The value of this option is expanded, and must then be the absolute path to a file which contains the server's private key. If this option is unset, or if the expansion is forced to fail, or the result is an empty string, the private key is assumed to be in the same file as the server's certificates. See chapter &<>& for further details. -.wen .option tls_remember_esmtp main boolean false @@ -15379,12 +15586,10 @@ are evaluated.) While the router is running, &%router_home_directory%& overrides the value of &$home$& that came from &%check_local_user%&. -.new When a router accepts an address and assigns it to a local transport (including the cases when a &(redirect)& router generates a pipe, file, or autoreply delivery), the home directory setting for the transport is taken from the first of these values that is set: -.wen .ilist The &%home_directory%& option on the transport; @@ -15973,7 +16178,6 @@ router handles the address .code root@[192.168.1.1] .endd -.new by setting up delivery to the host with that IP address. IPv4 domain literals consist of an IPv4 address enclosed in square brackets. IPv6 domain literals are similar, but the address is preceded by &`ipv6:`&. For example: @@ -15982,7 +16186,6 @@ postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678] .endd Exim allows &`ipv4:`& before IPv4 addresses, for consistency, and on the grounds that sooner or later somebody will try it. -.wen .cindex "&%self%& option" "in &(ipliteral)& router" If the IP address matches something in &%ignore_target_hosts%&, the router @@ -16620,17 +16823,14 @@ expanded separately (exactly as for a &(pipe)& transport, described in chapter .option command_group queryprogram string unset .cindex "gid (group id)" "in &(queryprogram)& router" -.new This option specifies a gid to be set when running the command while routing an address for deliver. It must be set if &%command_user%& specifies a numerical uid. If it begins with a digit, it is interpreted as the numerical value of the gid. Otherwise it is looked up using &[getgrnam()]&. -.wen .option command_user queryprogram string unset .cindex "uid (user id)" "for &(queryprogram)&" -.new This option must be set. It specifies the uid which is set when running the command while routing an address for delivery. If the value begins with a digit, it is interpreted as the numerical value of the uid. Otherwise, it is looked up @@ -16644,7 +16844,6 @@ usually running as the Exim user, not as root. If the &(queryprogram)& router is called from a non-root process, Exim cannot change uid or gid before running the command. In this circumstance the command runs under the current uid and gid. -.wen .option current_directory queryprogram string / @@ -16806,12 +17005,9 @@ It is usual to set &%no_verify%& on &(redirect)& routers which handle users' .ilist When Exim is receiving an incoming SMTP message from a remote host, it is -running under the Exim uid, not as root. -No additional groups are set up, even if the Exim uid is a member of other -groups (that is, the &[initgroups()]& function is not run). -Exim is unable to change uid to read the file as the user, and it may not be -able to read it as the Exim user. So in practice the router may not be able to -operate. +running under the Exim uid, not as root. Exim is unable to change uid to read +the file as the user, and it may not be able to read it as the Exim user. So in +practice the router may not be able to operate. .next However, even when the router can operate, the existence of a &_.forward_& file is unimportant when verifying an address. What should be checked is whether the @@ -17054,20 +17250,32 @@ text associated with the failure. For example, an alias file might contain: .code X.Employee: :fail: Gone away, no forwarding address .endd +.new In the case of an address that is being verified from an ACL or as the subject of a .cindex "VRFY error text" "display of" VRFY command, the text is included in the SMTP error response by default. .cindex "EXPN error text" "display of" -The text is not included in the response to an EXPN command. +The text is not included in the response to an EXPN command. In non-SMTP cases +the text is included in the error message that Exim generates. + +.cindex "SMTP" "error codes" +By default, Exim sends a 451 SMTP code for a &':defer:'&, and 550 for +&':fail:'&. However, if the message starts with three digits followed by a +space, optionally followed by an extended code of the form &'n.n.n'&, also +followed by a space, and the very first digit is the same as the default error +code, the code from the message is used instead. If the very first digit is +incorrect, a panic error is logged, and the default code is used. You can +suppress the use of the supplied code in a redirect router by setting the +&%forbid_smtp_code%& option true. In this case, any SMTP code is quietly +ignored. .cindex "&$acl_verify_message$&" 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. +therefore be included in a custom message if this is desired. +.wen Normally the error text is the rest of the redirection list &-- a comma does not terminate it &-- but a newline does act as a terminator. Newlines are not @@ -17288,6 +17496,15 @@ configured transport. This should normally be an &(appendfile)& transport. When it is running, the file name is in &$address_file$&. +.new +.option filter_prepend_home redirect boolean true +When this option is true, if a &(save)& command in an Exim filter specifies a +relative path, and &$home$& is defined, it is automatically prepended to the +relative path. If this option is set false, this action does not happen. The +relative path is then passed to the transport unmodified. +.wen + + .option forbid_blackhole redirect boolean false If this option is true, the &':blackhole:'& item may not appear in a redirection list. @@ -17382,6 +17599,15 @@ If this option is set true, only Exim filters are permitted when &%allow_filter%& is true. +.new +.cindex "SMTP" "error codes" +.option forbid_smtp_code redirect boolean false +If this option is set true, any SMTP error codes that are present at the start +of messages specified for &`:defer:`& or &`:fail:`& are quietly ignored, and +the default codes (451 and 550, respectively) are always used. +.wen + + .option hide_child_in_errmsg redirect boolean false @@ -17495,7 +17721,6 @@ When the transport is run, the pipe command is in &$address_pipe$&. .option qualify_domain redirect string&!! unset .cindex "&$qualify_recipient$&" -.new If this option is set, and an unqualified address (one without a domain) is generated, and that address would normally be qualified by the global setting in &%qualify_recipient%&, it is instead qualified with the domain specified by @@ -17507,20 +17732,17 @@ This option applies to all unqualified addresses generated by Exim filters, but for traditional &_.forward_& files, it applies only to addresses that are not preceded by a backslash. Sieve filters cannot generate unqualified addresses. -.wen .option qualify_preserve_domain redirect boolean false .cindex "domain" "in redirection; preserving" .cindex "preserving domain in redirection" .cindex "address redirection" "domain; preserving" -.new If this option is set, the router's local &%qualify_domain%& option must not be set (a configuration error occurs if it is). If an unqualified address (one without a domain) is generated, it is qualified with the domain of the parent address (the immediately preceding ancestor) instead of the global &%qualify_recipient%& value. In the case of a traditional &_.forward_& file, this applies whether or not the address is preceded by a backslash. -.wen .option repeat_use redirect boolean true @@ -17985,7 +18207,7 @@ change envelope recipients at this time. .option home_directory transports string&!! unset .cindex "transport" "home directory for" .cindex "&$home$&" -This option specifies a home directory setting for &new("a local") transport, +This option specifies a home directory setting for a local transport, overriding any value that may be set by the router. The home directory is placed in &$home$& while expanding the transport's private options. It is also used as the current directory if no current directory is set by the @@ -18077,6 +18299,11 @@ SMTP MAIL command. If you set &%return_path%& for a local transport, the only effect is to change the address that is placed in the &'Return-path:'& header line, if one is added to the message (see the next option). +.new +&*Note:*& A changed return path is not logged unless you add +&%return_path_on_delivery%& to the log selector. +.wen + .cindex "&$return_path$&" The expansion can refer to the existing value via &$return_path$&. This is either the message's envelope sender, or an address set by the @@ -18085,13 +18312,11 @@ replacement occurs; if it fails for another reason, delivery is deferred. This option can be used to support VERP (Variable Envelope Return Paths) &-- see section &<>&. -.new &*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. It is sent to the previously set errors address. This defaults to the incoming sender address, but can be changed by setting &%errors_to%& in a router. -.wen @@ -18213,7 +18438,6 @@ transport_filter = /some/directory/transport-filter.pl \ $host $host_address $sender_address $pipe_addresses .endd -.new Two problems arise if you want to use more complicated expansion items to generate transport filter commands, both of which due to the fact that the command is split up &'before'& expansion. @@ -18246,7 +18470,6 @@ transport_filter = /bin/sh -c ${lookup{$host}lsearch{/some/file}\ {$value}{/bin/cat}} .endd .endlist -.wen 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. The command should @@ -18332,16 +18555,16 @@ to some other delivery mechanism such as UUCP, multiple recipients may be acceptable. .endlist -The three local transports (&(appendfile)&, &(lmtp)&, and &(pipe)&) all have -the same options for controlling multiple (&"batched"&) deliveries, namely -&%batch_max%& and &%batch_id%&. To save repeating the information for each -transport, these options are described here. +These three local transports all have the same options for controlling multiple +(&"batched"&) deliveries, namely &%batch_max%& and &%batch_id%&. To save +repeating the information for each transport, these options are described here. The &%batch_max%& option specifies the maximum number of addresses that can be -delivered together in a single run of the transport. Its default value is one. -When more than one address is routed to a transport that has a &%batch_max%& -value greater than one, the addresses are delivered in a batch (that is, in a -single run of the transport), subject to certain conditions: +delivered together in a single run of the transport. Its default value is one +(no batching). When more than one address is routed to a transport that has a +&%batch_max%& value greater than one, the addresses are delivered in a batch +(that is, in a single run of the transport with multiple recipients), subject +to certain conditions: .ilist .cindex "&$local_part$&" @@ -18355,9 +18578,9 @@ addresses with the same domain are batched. .cindex "customizing" "batching condition" If &%batch_id%& is set, it is expanded for each address, and only those addresses with the same expanded value are batched. This allows you to specify -customized batching conditions. -Failure of the expansion for any reason, including forced failure, disables -batching, but it does not stop the delivery from taking place. +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. .next Batched addresses must also have the same errors address (where to send delivery errors), the same header additions and removals, the same user and @@ -18365,15 +18588,13 @@ group for the transport, and if a host list is present, the first host must be the same. .endlist -.cindex "&'Envelope-to:'& header line" -If the generic &%envelope_to_add%& option is set for the transport, the -&'Envelope-to:'& header that is added to the message contains all the addresses -that are batched together. - -The &(appendfile)& and &(pipe)& transports have an option called &%use_bsmtp%&, -which causes them to deliver the message in &"batched SMTP"& format, with the -envelope represented as SMTP commands. The &%check_string%& and -&%escape_string%& options are forced to the values +In the case of the &(appendfile)& and &(pipe)& transports, batching applies +both when the file or pipe command is specified in the transport, and when it +is specified by a &(redirect)& router, but all the batched addresses must of +course be routed to the same file or pipe command. These two transports have an +option called &%use_bsmtp%&, which causes them to deliver the message in +&"batched SMTP"& format, with the envelope represented as SMTP commands. The +&%check_string%& and &%escape_string%& options are forced to the values .code check_string = "." escape_string = ".." @@ -18382,18 +18603,23 @@ when batched SMTP is in use. A full description of the batch SMTP mechanism is given in section &<>&. The &(lmtp)& transport does not have a &%use_bsmtp%& option, because it always delivers using the SMTP protocol. +.cindex "&'Envelope-to:'& header line" +If the generic &%envelope_to_add%& option is set for a batching transport, the +&'Envelope-to:'& header that is added to the message contains all the addresses +that are being processed together. 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. + .cindex "&(pipe)& transport" "with multiple addresses" .cindex "&$pipe_addresses$&" -If you are not using BSMTP, but are using a &(pipe)& transport, you can include -&$pipe_addresses$& as part of the command. This is not a true variable; it is -a bit of magic that causes each of the recipient addresses to be inserted into -the command as a separate argument. This provides a way of accessing all the -addresses that are being delivered in the batch. +If you are using a &(pipe)& transport without BSMTP, and setting the +transport's &%command%& option, 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. &*Note:*& This is not possible for pipe commands that +are specififed by a &(redirect)& router. -If you are using a batching &(appendfile)& transport without &%use_bsmtp%&, the -only way to preserve the recipient addresses is to set the &%envelope_to_add%& -option. This causes an &'Envelope-to:'& header line to be added to the message, -containing all the recipients. @@ -18708,9 +18934,11 @@ delivery is deferred. .option file_must_exist appendfile boolean false -If this option is true, the file specified by the &%file%& option must exist, -and an error occurs if it does not. Otherwise, it is created if it does not -exist. +.new +If this option is true, the file specified by the &%file%& option must exist. +A temporary error occurs if it does not, causing delivery to be deferred. +If this option is false, the file is created if it does not exist. +.wen .option lock_fcntl_timeout appendfile time 0s @@ -18765,7 +18993,7 @@ is treated as 1. See below for details of locking. .option lockfile_mode appendfile "octal integer" 0600 This specifies the mode of the created lock file, when a lock file is being -used (see &%use_lockfile%&). +used (see &%use_lockfile%& and &%use_mbx_lock%&). .option lockfile_timeout appendfile time 30m @@ -18811,12 +19039,13 @@ SUPPORT_MAILDIR is present in &_Local/Makefile_&. See section .cindex "maildir format" "quota; directories included in" .cindex "quota" "maildir; directories included in" This option is relevant only when &%maildir_use_size_file%& is set. It defines -a regular expression for specifying directories that should be included in the -quota calculation. The default value is +a regular expression for specifying directories, relative to the quota +directory (see &%quota_directory%&), that should be included in the quota +calculation. The default value is: .code maildir_quota_directory_regex = ^(?:cur|new|\..*)$ .endd -which includes the &_cur_& and &_new_& directories, and any maildir++ folders +This includes the &_cur_& and &_new_& directories, and any maildir++ folders (directories whose names begin with a dot). If you want to exclude the &_Trash_& folder from the count (as some sites do), you need to change this setting to @@ -18824,7 +19053,9 @@ folder from the count (as some sites do), you need to change this setting to 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_&. +directory whose name is &_.Trash_&. When a directory is excluded from quota +calculations, quota processing is bypassed for any messages that are delivered +directly into that directory. .option maildir_retries appendfile integer 10 @@ -18842,7 +19073,19 @@ section &<>& below. Setting this option true enables support for &_maildirsize_& files. Exim creates a &_maildirsize_& file in a maildir if one does not exist, taking the quota from the &%quota%& option of the transport. If &%quota%& is unset, the -value is zero. See section &<>& below for further details. +value is zero. See &%maildir_quota_directory_regex%& above and section +&<>& below for further details. + +.option maildirfolder_create_regex appendfile string unset +.cindex "maildir format" "&_maildirfolder_& file" +.cindex "&_maildirfolder_&, creating" +The value of this option is a regular expression. If it is unset, it has no +effect. Otherwise, before a maildir delivery takes place place, the pattern is +matched against the name of the maildir directory, that is, the directory +containing the &_new_& and &_tmp_& subdirectories that will be used for the +delivery. If there is a match, Exim checks for the existence of a file called +&_maildirfolder_& in the directory, and creates it if it does not exist. +See section &<>& for more details. .option mailstore_format appendfile boolean false @@ -18995,13 +19238,11 @@ delivery directory. .option quota_filecount appendfile string&!! 0 -.new This option applies when the &%directory%& option is set. It limits the total number of files in the directory (compare the inode limit in system quotas). It can only be used if &%quota%& is also set. The value is expanded; an expansion failure causes delivery to be deferred. A value of zero is interpreted as &"no quota"&. -.wen .option quota_is_inclusive appendfile boolean true @@ -19065,7 +19306,6 @@ quota_warn_threshold = 75% If &%quota%& is not set, a setting of &%quota_warn_threshold%& that ends with a percent sign is ignored. -.new The warning message itself is specified by the &%quota_warn_message%& option, and it must start with a &'To:'& header line containing the recipient(s) of the warning message. These do not necessarily have to include the recipient(s) of @@ -19078,7 +19318,6 @@ From: Mail Delivery System .oindex &%errors_reply_to%& If you supply a &'Reply-To:'& line, it overrides the global &%errors_reply_to%& option. -.wen The &%quota%& option does not have to be set in order to use this option; they are independent of one another except when the threshold is specified as a @@ -19297,7 +19536,8 @@ file, and an exclusive lock on the file whose name is /tmp/.. .endd using the device and inode numbers of the open mailbox file, in accordance with -the MBX locking rules. +the MBX locking rules. This file is created with a mode that is specified by +the &%lockfile_mode%& option. If Exim fails to lock the file, there are two possible courses of action, depending on the value of the locking timeout. This is obtained from @@ -19370,7 +19610,8 @@ deferred. .cindex "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/.HP._& in the -given directory. If the delivery is successful, the file is renamed into the +directory that is defined by the &%directory%& option (the &"delivery +directory"&). If the delivery is successful, the file is renamed into the &_new_& subdirectory. In the file name, <&'stime'&> is the current time of day in seconds, and @@ -19381,6 +19622,42 @@ file name. However, as a precaution, Exim calls &[stat()]& for the file before opening it. If any response other than ENOENT (does not exist) is given, Exim waits 2 seconds and tries again, up to &%maildir_retries%& times. +Before Exim carries out a maildir delivery, it ensures that subdirectories +called &_new_&, &_cur_&, and &_tmp_& exist in the delivery directory. If they +do not exist, Exim tries to create them and any superior directories in their +path, subject to the &%create_directory%& and &%create_file%& options. If the +&%maildirfolder_create_regex%& option is set, and the regular expression it +contains matches the delivery directory, Exim also ensures that a file called +&_maildirfolder_& exists in the delivery directory. If a missing directory or +&_maildirfolder_& file cannot be created, delivery is deferred. + +These features make it possible to use Exim to create all the necessary files +and directories in a maildir mailbox, including subdirectories for maildir++ +folders. Consider this example: +.code +maildir_format = true +directory = /var/mail/$local_part\ + ${if eq{$local_part_suffix}{}{}\ + {/.${substr_1:$local_part_suffix}}} +maildirfolder_create_regex = /\.[^/]+$ +.endd +If &$local_part_suffix$& is empty (there was no suffix for the local part), +delivery is into a toplevel maildir with a name like &_/var/mail/pimbo_& (for +the user called &'pimbo'&). The pattern in &%maildirfolder_create_regex%& does +not match this name, so Exim will not look for or create the file +&_/var/mail/pimbo/maildirfolder_&, though it will create +&_/var/mail/pimbo/{cur,new,tmp}_& if necessary. + +However, if &$local_part_suffix$& contains &`-eximusers`& (for example), +delivery is into the maildir++ folder &_/var/mail/pimbo/.eximusers_&, which +does match &%maildirfolder_create_regex%&. In this case, Exim will create +&_/var/mail/pimbo/.eximusers/maildirfolder_& as well as the three maildir +directories &_/var/mail/pimbo/.eximusers/{cur,new,tmp}_&. + +&*Warning:*& Take care when setting &%maildirfolder_create_regex%& that it does +not inadvertently match the toplevel maildir directory, because a +&_maildirfolder_& file at top level would completely break quota calculations. + .cindex "quota" "in maildir delivery" .cindex "maildir++" If Exim is required to check a &%quota%& setting before a maildir delivery, and @@ -19426,10 +19703,10 @@ colon is inserted. .cindex "maildir format" "&_maildirsize_& file" If &%maildir_use_size_file%& is true, Exim implements the maildir++ rules for storing quota and message size information in a file called &_maildirsize_& -within the maildir directory. If this file does not exist, Exim creates it, -setting the quota from the &%quota%& option of the transport. If the maildir -directory itself does not exist, it is created before any attempt to write a -&_maildirsize_& file. +within the toplevel maildir directory. If this file does not exist, Exim +creates it, setting the quota from the &%quota%& option of the transport. If +the maildir directory itself does not exist, it is created before any attempt +to write a &_maildirsize_& file. The &_maildirsize_& file is used to hold information about the sizes of messages in the maildir, thus speeding up quota calculations. The quota value @@ -19442,9 +19719,9 @@ If the &%quota%& option in the transport is unset or zero, the &_maildirsize_& file is maintained (with a zero quota setting), but no quota is imposed. A regular expression is available for controlling which directories in the -maildir participate in quota calculations. See the description of the -&%maildir_quota_directory_regex%& option above for details. - +maildir participate in quota calculations when a &_maildirsizefile_& is in use. +See the description of the &%maildir_quota_directory_regex%& option above for +details. .section "Mailstore delivery" @@ -19501,13 +19778,11 @@ expanding the contents of the &%directory_file%& option. .chapter "The autoreply transport" .scindex IIDauttra1 "transports" "&(autoreply)&" .scindex IIDauttra2 "&(autoreply)& transport" -.new The &(autoreply)& transport is not a true transport in that it does not cause the message to be transmitted. Instead, it generates a new mail message as an automatic reply to the incoming message. &'References:'& and &'Auto-Submitted:'& header lines are included. These are constructed according to the rules in RFCs 2822 and 3834, respectively. -.wen 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 @@ -19621,7 +19896,8 @@ used. .option never_mail autoreply "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. +discarded, no message is created. This applies both when the recipients are +generated by a filter and when they are specified in the transport. @@ -19798,18 +20074,20 @@ contains the local part of the address (as usual), and the command that is run is specified by the &%command%& option on the transport. .next .cindex "&$pipe_addresses$&" -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 -&<>& below) contains all the addresses that are being -handled. +If the &%batch_max%& option is set greater than 1 (the default is 1), the +transport can handle more than one address in a single run. In this case, when +more than one address is routed to the transport, &$local_part$& is not set +(because it is not unique). However, the pseudo-variable &$pipe_addresses$& +(described in section &<>& below) contains all the addresses +that are routed to the transport. .next .cindex "&$address_pipe$&" A router redirects an address directly to a pipe command (for example, from an -alias or forward file). In this case, &$local_part$& contains the local part -that was redirected, and &$address_pipe$& contains the text of the pipe -command itself. The &%command%& option on the transport is ignored. +alias or forward file). In this case, &$address_pipe$& contains the text of the +pipe command, and the &%command%& option on the transport is ignored. If only +one address is being transported (&%batch_max%& is not greater than one, or +only one address was redirected to this pipe command), &$local_part$& contains +the local part that was redirected. .endlist @@ -19822,8 +20100,8 @@ In the case when &(pipe)& is run as a consequence of an entry in a local user's other cases, the uid and gid have to be specified explicitly, either on the transport or on the router that handles the address. Current and &"home"& directories are also controllable. See chapter &<>& for -details of the local delivery environment. - +details of the local delivery environment and chapter &<>& +for a discussion of local delivery batching. .section "Concurrent delivery" @@ -19890,7 +20168,6 @@ arguments. You have to write .code command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" .endd -.new to ensure that it is all in one argument. The expansion is done in this way, argument by argument, so that the number of arguments cannot be changed as a result of expansion, and quotes or backslashes in inserted variables do not @@ -19901,7 +20178,6 @@ example: .code command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} .endd -.wen .cindex "transport" "filter" .cindex "filter" "transport filter" @@ -20215,7 +20491,6 @@ commands. If you want to include a leading HELO command with such messages, you can do so by setting the &%message_prefix%& option. See section &<>& for details of batch SMTP. -.new .option use_classresources pipe boolean false .cindex "class resources (BSD)" This option is available only when Exim is running on FreeBSD, NetBSD, or @@ -20223,7 +20498,6 @@ BSD/OS. If it is set true, the &[setclassresources()]& function is used to set resource limits when a &(pipe)& transport is run to perform a delivery. The limits for the uid under which the pipe is to run are obtained from the login class database. -.wen .option use_crlf pipe boolean false @@ -20404,7 +20678,6 @@ configured Exim is listening on the port to which the message is sent). .option authenticated_sender smtp string&!! unset .cindex "Cyrus" -.new When Exim has authenticated as a client, or if &%authenticated_sender_force%& is true, this option sets a value for the AUTH= item on outgoing MAIL commands, overriding any existing authenticated sender value. If the string expansion is @@ -20416,7 +20689,6 @@ If the SMTP session is not authenticated, the expansion of &%authenticated_sender%& still happens (and can cause the delivery to be deferred if it fails), but no AUTH= item is added to MAIL commands unless &%authenticated_sender_force%& is true. -.wen This option allows you to use the &(smtp)& transport in LMTP mode to deliver mail to Cyrus IMAP and provide the proper local part as the @@ -20432,12 +20704,10 @@ domain is involved), there is no checking on the syntax of the provided value. -.new .option authenticated_sender_force smtp boolean false If this option is set true, the &%authenticated_sender%& option's value is used for the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as a client. -.wen .option command_timeout smtp time 5m @@ -20560,10 +20830,11 @@ it may also consult other sources of information such as &_/etc/hosts_&. .option helo_data smtp string&!! &`$primary_hostname`& .cindex "HELO argument" "setting" .cindex "EHLO argument" "setting" -The value of this option is expanded, and used as the argument for the EHLO or -HELO command that starts the outgoing SMTP session. The variables &$host$& and -&$host_address$& are set to the identity of the remote host, and can be used to -generate different values for different servers. +.cindex "LHLO argument" "setting" +The value of this option is expanded, and used as the argument for the EHLO, +HELO, or LHLO command that starts the outgoing SMTP or LMTP session. The +variables &$host$& and &$host_address$& are set to the identity of the remote +host, and can be used to generate different values for different servers. .option hosts smtp "string list&!!" unset Hosts are associated with an address by a router such as &(dnslookup)&, which @@ -20863,7 +21134,6 @@ be the name of a file that contains a CRL in PEM format. .cindex "TLS client private key" "location of" .cindex "&$host$&" .cindex "&$host_address$&" -.new The value of this option must be the absolute path to a file which contains the client's private key. This is used when sending a message over an encrypted connection using a client certificate. The values of &$host$& and @@ -20871,7 +21141,6 @@ connection using a client certificate. The values of &$host$& and expansion. If this option is unset, or the expansion is forced to fail, or the result is an empty string, the private key is assumed to be in the same file as the certificate. See chapter &<>& for details of TLS. -.wen .option tls_require_ciphers smtp string&!! unset @@ -21033,12 +21302,21 @@ configuration file are applied to addresses in incoming messages, both envelope addresses and addresses in header lines. Each rule specifies the types of address to which it applies. -Rewriting of addresses in header lines applies only to those headers that -were received with the message, and, in the case of transport rewriting, those -that were added by a system filter. That is, it applies only to those headers -that are common to all copies of the message. Header lines that are added by -individual routers or transports (and which are therefore specific to -individual recipient addresses) are not rewritten. +.new +Whether or not addresses in header lines are rewritten depends on the origin of +the headers and the type of rewriting. Global rewriting, that is, rewriting +rules from the rewrite section of the configuration file, is applied only to +those headers that were received with the message. Header lines that are added +by ACLs or by a system filter or by individual routers or transports (which +are specific to individual recipient addresses) are not rewritten by the global +rules. + +Rewriting at transport time, by means of the &%headers_rewrite%& option, +applies all headers except those added by routers and transports. That is, as +well as the headers that were received with the message, it also applies to +headers that were added by an ACL or a system filter. +.wen + In general, rewriting addresses from your own system or domain has some legitimacy. Rewriting other addresses should be done only with great care and @@ -21089,20 +21367,17 @@ value of &$local_part$& and &$domain$& after verification are always the same as they were before (that is, they contain the unrewritten &-- except for SMTP-time rewriting &-- address). -.new As soon as 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). This happens before adding any header lines that were specified in MAIL or RCPT ACLs, and .cindex "&[local_scan()]& function" "address rewriting; timing of" before the DATA ACL and &[local_scan()]& functions are run. -.wen 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. -.new .cindex "envelope sender" "rewriting at transport time" .cindex "rewriting" "at transport time" .cindex "header lines" "rewriting at transport time" @@ -21116,7 +21391,6 @@ applied to header lines that are added by routers or the transport. The outgoing envelope sender can be rewritten by means of the &%return_path%& transport option. However, it is not possible to rewrite envelope recipients at transport time. -.wen @@ -21485,9 +21759,24 @@ suffers a temporary failure, the retry data is updated as normal, and subsequent delivery attempts from queue runs occur only when the retry time for the local address is reached. +.new +.section "Changing retry rules" +If you change the retry rules in your configuration, you should consider +whether or not to delete the retry data that is stored in Exim's spool area in +files with names like &_db/retry_&. Deleting any of Exim's hints files is +always safe; that is why they are called &"hints"&. + +The hints retry data contains suggested retry times based on the previous +rules. In the case of a long-running problem with a remote host, it might +record the fact that the host has timed out. If your new rules increase the +timeout time for such a host, you should definitely remove the old retry data +and let Exim recreate it, based on the new rules. Otherwise Exim might bounce +messages that it should now be retaining. +.wen + -.section "Retry rules" +.section "Format of retry rules" .cindex "retry" "rules" 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 @@ -21501,9 +21790,10 @@ message's sender, respectively. The pattern is any single item that may appear in an address list (see section &<>&). It is in fact processed as a one-item address list, which means that it is expanded before being tested against the address that -has been delayed. Address list processing treats a plain domain name as if it -were preceded by &"*@"&, which makes it possible for many retry rules to start -with just a domain. For example, +has been delayed. &new("A negated address list item is permitted.") Address +list processing treats a plain domain name as if it were preceded by &"*@"&, +which makes it possible for many retry rules to start with just a domain. For +example, .code lookingglass.fict.example * F,24h,30m; .endd @@ -21542,12 +21832,10 @@ 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). -.new However, when Exim is looking for a retry rule after a remote delivery attempt suffers an address error (a 4&'xx'& SMTP response for a recipient address), the whole address is always used as the key when searching the retry rules. The rule that is found is used to create a retry time for the failing address. -.wen .section "Choosing which retry rule to use for host and message errors" @@ -21598,7 +21886,6 @@ asterisk, which matches any error. The errors that can be tested for are: Authentication failed when trying to send to a host in the &%hosts_require_auth%& list in an &(smtp)& transport. -.new .vitem &%data_4xx%& A 4&'xx'& error was received for an outgoing DATA command, either immediately after the command, or after sending the message's data. @@ -21620,15 +21907,12 @@ the.domain.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). -.wen .vlist -.new .vitem &%lost_connection%& A server unexpectedly closed the SMTP connection. There may, of course, legitimate reasons for this (host died, network died), but if it repeats a lot for the same host, it indicates something odd. -.wen .vitem &%refused_MX%& A connection to a host obtained from an MX record was refused. @@ -21659,12 +21943,10 @@ obtained from an MX record. .vitem &%timeout%& There was a timeout while connecting or during an SMTP session. -.new .vitem &%tls_required%& The server was required to use TLS (it matched &%hosts_require_tls%& in the &(smtp)& transport), but either did not offer TLS, or it responded with 4&'xx'& to STARTTLS, or there was a problem setting up the TLS connection. -.wen .vitem &%quota%& A mailbox quota was exceeded in a local delivery by the &(appendfile)& @@ -21723,14 +22005,12 @@ The retry timings themselves are then the fourth item. For example: .code * rcpt_4xx senders=: F,1h,30m .endd -.new matches recipient 4&'xx'& errors for bounce messages sent to any address at any host. If the address list contains white space, it must be enclosed in quotes. For example: .code a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5 .endd -.wen &*Warning*&: This facility can be unhelpful if it is used for host errors (which do not depend on the recipient). The reason is that the sender is used only to match the retry rule. Once the rule has been found for a host error, @@ -21795,8 +22075,8 @@ interval is found. The main configuration variable .cindex "limit" "retry interval" .cindex "retry interval" "maximum" .cindex "&%retry_interval_max%&" -&%retry_interval_max%& limits the maximum interval between retries. &new("It -cannot be set greater than &`24h`&, which is its default value.") +&%retry_interval_max%& limits the maximum interval between retries. It +cannot be set greater than &`24h`&, which is its default value. A single remote domain may have a number of hosts associated with it, and each host may have more than one IP address. Retry algorithms are selected on the @@ -21939,33 +22219,33 @@ If there is a continuous stream of messages for the failing domains, setting deliver to permanently failing IP addresses than when &%delay_after_cutoff%& is true. -.new .section "Deliveries that work intermittently" .cindex "retry" "intermittently working deliveries" Some additional logic is needed to cope with cases where a host is intermittently available, or when a message has some attribute that prevents its delivery when others to the same address get through. In this situation, because some messages are successfully delivered, the &"retry clock"& for the -host or address keeps getting restarted, and so a message could remain on the -queue for ever because the cutoff time is never reached. - -Two exceptional actions are applied to prevent this happening. Firstly, if a -message's arrival time is earlier than the &"first failed"& time for a host or -address, the earlier time is used when scanning the retry rules. - -Secondly, if a message has been on the queue for longer than the cutoff time of -any applicable retry rule for a given address, a delivery is attempted for that -address, even if it is not yet time, and if this delivery fails, the address is -timed out. A new retry time is not computed in this case, so that other -messages for the same address are considered immediately. - -These two actions are probably equivalent; the fact that they both exist is a -a historical accident. The second was implemented first, and was left in place -when the first was added on the grounds that this was harmless, whereas -removing it might have broken something in this rather tricky area. +host or address keeps getting reset by the successful deliveries, and so +failing messages remain on the queue for ever because the cutoff time is never +reached. + +Two exceptional actions are applied to prevent this happening. The first +applies to errors that are related to a message rather than a remote host. +Section &<>& has a discussion of the different kinds of error; +examples of message-related errors are 4&'xx'& responses to MAIL or DATA +commands, and quota failures. For this type of error, if a message's arrival +time is earlier than the &"first failed"& time for the error, the earlier time +is used when scanning the retry rules to decide when to try next and when to +time out the address. + +The exceptional second action applies in all cases. If a message has been on +the queue for longer than the cutoff time of any applicable retry rule for a +given address, a delivery is attempted for that address, even if it is not yet +time, and if this delivery fails, the address is timed out. A new retry time is +not computed in this case, so that other messages for the same address are +considered immediately. .ecindex IIDretconf1 .ecindex IIDregconf2 -.wen @@ -22380,7 +22660,6 @@ the authenticated sender that was received with the message. .chapter "The plaintext authenticator" "CHAPplaintext" .scindex IIDplaiauth1 "&(plaintext)& authenticator" .scindex IIDplaiauth2 "authenticators" "&(plaintext)&" -.new The &(plaintext)& authenticator can be configured to support the PLAIN and LOGIN authentication mechanisms, both of which transfer authentication data as plain (unencrypted) text (though base64 encoded). The use of plain text is a @@ -22388,7 +22667,6 @@ security risk; you are strongly advised to insist on the use of SMTP encryption (see chapter &<>&) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted plain text, you should not use the same passwords for SMTP connections as you do for login accounts. -.wen .section "Using plaintext in a server" .cindex "options" "&(plaintext)& authenticator (server)" @@ -22410,7 +22688,6 @@ is described below. "in &(plaintext)& authenticator" .cindex "&$auth1$&, &$auth2$&, etc" .cindex "base64 encoding" "in &(plaintext)& authenticator" -.new The data sent by the client with the AUTH command, or in response to subsequent prompts, is base64 encoded, and so may contain any byte values when decoded. If any data is supplied with the command, it is treated as a @@ -22422,7 +22699,6 @@ For compatibility with previous releases of Exim, the values are also placed in the expansion variables &$1$&, &$2$&, and &$3$&. However, the use of these variables for this purpose is now deprecated, as it can lead to confusion in string expansions that also use them for other things. -.wen If there are more strings in &%server_prompts%& than the number of strings supplied with the AUTH command, the remaining prompts are used to obtain more @@ -22457,17 +22733,22 @@ subsequently in response to an empty prompt from the server. The second and third strings are a user name and a corresponding password. Using a single fixed user name and password as an example, this could be configured as follows: -.new .code fixed_plain: driver = plaintext public_name = PLAIN server_prompts = : server_condition = \ - ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}\ - {yes}{no}} + ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}} server_set_id = $auth2 .endd +.new +Note that the default result strings from &%if%& (&"true"& or an empty string) +are exactly what we want here, so they need not be specified. Obviously, if the +password contains expansion-significant characters such as dollar, backslash, +or closing brace, they have to be escaped. +.wen + The &%server_prompts%& setting specifies a single, empty prompt (empty items at the end of a string list are ignored). If all the data comes as part of the AUTH command, as is commonly the case, the prompt is not used. This @@ -22497,16 +22778,17 @@ Having just one fixed user name and password, as in this example, is not very realistic, though for a small organization with only a handful of authenticating clients it could make sense. -.new A more sophisticated instance of this authenticator could use the user name in &$auth2$& to look up a password in a file or database, and maybe do an encrypted comparison (see &%crypteq%& in chapter &<>&). Here is a example of this approach, where the passwords are looked up in a DBM file. &*Warning*&: This is an incorrect example: +.new .code server_condition = \ - ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}{yes}{no}} + ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}} .endd +.wen The expansion uses the user name (&$auth2$&) as the key to look up a password, which it then compares to the supplied password (&$auth3$&). Why is this example incorrect? It works fine for existing users, but consider what happens if a @@ -22514,17 +22796,17 @@ non-existent user name is given. The lookup fails, but as no success/failure strings are given for the lookup, it yields an empty string. Thus, to defeat the authentication, all a client has to do is to supply a non-existent user name and an empty password. The correct way of writing this test is: +.new .code server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\ - {${if eq{$value}{$auth3}{yes}{no}}}{no}} + {${if eq{$value}{$auth3}}} {false}} .endd -.wen In this case, if the lookup succeeds, the result is checked; if the lookup -fails, authentication fails. If &%crypteq%& is being used instead of &%eq%&, -the first example is in fact safe, because &%crypteq%& always fails if its -second argument is empty. However, the second way of writing the test makes the -logic clearer. - +fails, &"false"& is returned and authentication fails. If &%crypteq%& is being +used instead of &%eq%&, the first example is in fact safe, because &%crypteq%& +always fails if its second argument is empty. However, the second way of +writing the test makes the logic clearer. +.wen .section "The LOGIN authentication mechanism" @@ -22534,18 +22816,15 @@ The LOGIN authentication mechanism is not documented in any RFC, but is in use in a number of programs. No data is sent with the AUTH command. Instead, a user name and password are supplied separately, in response to prompts. The plaintext authenticator can be configured to support this as in this example: -.new .code fixed_login: driver = plaintext public_name = LOGIN server_prompts = User Name : Password server_condition = \ - ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}\ - {yes}{no}} + ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}} server_set_id = $auth1 .endd -.wen Because of the way plaintext operates, this authenticator accepts data supplied with the AUTH command (in contravention of the specification of LOGIN), but if the client does not supply it (as is the case for LOGIN clients), the prompt @@ -22556,7 +22835,6 @@ example, Outlook Express is reported to recognize only &"Username:"& and &"Password:"&. Here is an example of a LOGIN authenticator that uses those strings. It uses the &%ldapauth%& expansion condition to check the user name and password by binding to an LDAP server: -.new .code login: driver = plaintext @@ -22565,10 +22843,9 @@ login: server_condition = ${if ldapauth \ {user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \ pass=${quote:$auth2} \ - ldap://ldap.example.org/}{yes}{no}} + ldap://ldap.example.org/}} server_set_id = uid=$auth1,ou=people,o=example.org .endd -.wen Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for authentication. However, the basic &%quote%& operator, rather than any of the LDAP quoting operators, is the correct one to use for the password, because @@ -22591,16 +22868,13 @@ Radius, &%ldapauth%&, &'pwcheck'&, and &'saslauthd'&. For details see section .cindex "options" "&(plaintext)& authenticator (client)" The &(plaintext)& authenticator has two client options: -.new .option client_ignore_invalid_base64 plaintext boolean false If the client receives a server prompt that is not a valid base64 string, authentication is abandoned by default. However, if this option is set true, the error in the challenge is ignored and the client sends the response as usual. -.wen .option client_send plaintext string&!! unset -.new The string is a colon-separated list of authentication data strings. Each string is independently expanded before being sent to the server. The first string is sent with the AUTH command; any more strings are sent in response @@ -22612,7 +22886,6 @@ way. Thus, the prompt that is received in response to sending the first string so on. If an invalid base64 string is received when &%client_ignore_invalid_base64%& is set, an empty string is put in the &$auth$&<&'n'&> variable. -.wen &*Note*&: You cannot use expansion to create multiple strings, because splitting takes priority and happens first. @@ -22674,24 +22947,21 @@ authenticator as a server: .option server_secret cram_md5 string&!! unset .cindex "numerical variables (&$1$& &$2$& etc)" "in &(cram_md5)& authenticator" When the server receives the client's response, the user name is placed in -the expansion variable &new("&$auth1$&"), and &%server_secret%& is expanded to +the expansion variable &$auth1$&, and &%server_secret%& is expanded to obtain the password for that user. The server then computes the CRAM-MD5 digest that the client should have sent, and checks that it received the correct string. If the expansion of &%server_secret%& is forced to fail, authentication fails. If the expansion fails for some other reason, a temporary error code is returned to the client. -.new For compatibility with previous releases of Exim, the user name is also placed in &$1$&. However, the use of this variables for this purpose is now deprecated, as it can lead to confusion in string expansions that also use numeric variables for other things. -.wen For example, the following authenticator checks that the user name given by the client is &"ph10"&, and if so, uses &"secret"& as the password. For any other user name, authentication fails. -.new .code fixed_cram: driver = cram_md5 @@ -22699,12 +22969,10 @@ fixed_cram: server_secret = ${if eq{$auth1}{ph10}{secret}fail} server_set_id = $auth1 .endd -.wen .cindex "&$authenticated_id$&" If authentication succeeds, the setting of &%server_set_id%& preserves the user name in &$authenticated_id$&. A more tyical configuration might look up the secret string in a file, using the user name as the key. For example: -.new .code lookup_cram: driver = cram_md5 @@ -22712,7 +22980,6 @@ lookup_cram: server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}{$value}fail} server_set_id = $auth1 .endd -.wen Note that this expansion explicitly forces failure if the lookup fails because &$1$& contains an unknown user name. @@ -22785,14 +23052,12 @@ depending on the driver you are using. .section "Using cyrus_sasl as a server" -.new The &(cyrus_sasl)& authenticator has four private options. It puts the username (on a successful authentication) into &$auth1$&. For compatibility with previous releases of Exim, the username is also placed in &$1$&. However, the use of this variable for this purpose is now deprecated, as it can lead to confusion in string expansions that also use numeric variables for other things. -.wen .option server_hostname cyrus_sasl string&!! &`$primary_hostname`& @@ -22805,7 +23070,6 @@ this data. This option selects the authentication mechanism this driver should use. It allows you to use a different underlying mechanism from the advertised name. For example: -.new .code sasl: driver = cyrus_sasl @@ -22813,7 +23077,6 @@ sasl: server_mech = CRAM-MD5 server_set_id = $auth1 .endd -.wen .option server_realm cyrus_sasl string unset This specifies the SASL realm that the server claims to be in. @@ -22827,7 +23090,6 @@ For straightforward cases, you do not need to set any of the authenticator's private options. All you need to do is to specify an appropriate mechanism as the public name. Thus, if you have a SASL library that supports CRAM-MD5 and PLAIN, you could have two authenticators as follows: -.new .code sasl_cram_md5: driver = cyrus_sasl @@ -22839,7 +23101,6 @@ sasl_plain: public_name = PLAIN server_set_id = $auth1 .endd -.wen Cyrus SASL does implement the LOGIN authentication method, even though it is not a standard method. It is disabled by default in the source distribution, but it is present in many binary distributions. @@ -22887,7 +23148,6 @@ The &(spa)& authenticator has just one server option: .option server_password spa string&!! unset .cindex "numerical variables (&$1$& &$2$& etc)" "in &(spa)& authenticator" -.new This option is expanded, and the result must be the cleartext password for the authenticating user, whose name is at this point in &$auth1$&. For compatibility with previous releases of Exim, the user name is also placed in @@ -22901,7 +23161,6 @@ spa: server_password = \ ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail} .endd -.wen If the expansion is forced to fail, authentication fails. Any other expansion failure causes a temporary error code to be returned. @@ -23220,7 +23479,6 @@ encryption. To make this work you need to set, in the server, tls_certificate = /some/file/name tls_privatekey = /some/file/name .endd -.new These options are, in fact, expanded strings, so you can make them depend on the identity of the client that is connected if you wish. The first file contains the server's X509 certificate, and the second contains the private key @@ -23231,13 +23489,11 @@ set, or if its expansion is forced to fail or results in an empty string, this is assumed to be the case. The certificate file may also contain intermediate certificates that need to be sent to the client to enable it to authenticate the server's certificate. -.wen If you do not understand about certificates and keys, please try to find a source of this background information, which is not Exim-specific. (There are a few comments below in section &<>&.) -.new &*Note*&: These options do not apply when Exim is operating as a client &-- they apply only in the case of a server. If you need to use a certificate in an Exim client, you must set the options of the same names in an &(smtp)& @@ -23246,7 +23502,6 @@ transport. With just these options, an Exim server will be able to use TLS. It does not require the client to have a certificate (but see below for how to insist on this). There is one other option that may be needed in other situations. If -.wen .code tls_dhparam = /some/file/name .endd @@ -23572,10 +23827,15 @@ options in the main part of the configuration. These options are: .cindex "STARTTLS" "ACL for" .cindex "VRFY" "ACL for" .cindex "SMTP connection" "ACL for" -.cindex "non-smtp message" "ACL for" +.cindex "non-smtp message" "ACLs for" +.cindex "MIME parts" "ACL for" .table2 140pt .row &~&%acl_not_smtp%& "ACL for non-SMTP messages" +.new +.row &~&%acl_not_smtp_mime%& "ACL for non-SMTP MIME parts" +.row &~&%acl_not_smtp_start%& "ACL at start of non-SMTP message" +.wen .row &~&%acl_smtp_auth%& "ACL for AUTH" .row &~&%acl_smtp_connect%& "ACL for start of SMTP connection" .row &~&%acl_smtp_data%& "ACL after DATA is complete" @@ -23605,22 +23865,46 @@ trying to deliver the message. It is therefore recommended that you do as much testing as possible at RCPT time. -.section "The non-SMTP ACL" -.cindex "non-smtp message" "ACL for" -The non-SMTP ACL applies to all non-interactive incoming messages, that is, it -applies to batch SMTP as well as to non-SMTP messages. (Batch SMTP is not -really SMTP.) This ACL is run just before the &[local_scan()]& function. Any +.new +.section "The non-SMTP ACLs" +.cindex "non-smtp message" "ACLs for" +The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they +apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not +really SMTP.) Many of the ACL conditions (for example, host tests, and tests on +the state of the SMTP connection such as encryption and authentication) are not +relevant and are forbidden in these ACLs. However, the sender and recipients +are known, so the &%senders%& and &%sender_domains%& conditions and the +&$sender_address$& and &$recipients$& variables can be used. Variables such as +&$authenticated_sender$& are also available. You can specify added header lines +in any of these ACLs. + +The &%acl_not_smtp_start%& ACL is run right at the start of receiving a +non-SMTP message, before any of the message has been read. (This is the +analogue of the &%acl_smtp_predata%& ACL for SMTP input.) The result of this +ACL is ignored; it cannot be used to reject a message. If you really need to, +you could set a value in an ACL variable here and reject based on that in the +&%acl_not_smtp%& ACL. However, this ACL can be used to set controls, and in +particular, it can be used to set +.code +control = suppress_local_fixups +.endd +This cannot be used in the other non-SMTP ACLs because by the time they are +run, it is too late. + +The &%acl_not_smtp_mime%& ACL is available only when Exim is compiled with the +content-scanning extension. For details, see chapter &<>&. + +The &%acl_not_smtp%& ACL is run just before the &[local_scan()]& function. Any kind of rejection is treated as permanent, because there is no way of sending a -temporary error for these kinds of message. Many of the ACL conditions (for -example, host tests, and tests on the state of the SMTP connection such as -encryption and authentication) are not relevant and are forbidden in this ACL. +temporary error for these kinds of message. -.section "The connect ACL" +.section "The SMTP connect ACL" .cindex "SMTP connection" "ACL for" -The ACL test specified by &%acl_smtp_connect%& happens after the test specified -by &%host_reject_connection%& (which is now an anomaly) and any TCP Wrappers -testing (if configured). +The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP +session, after the test specified by &%host_reject_connection%& (which is now +an anomaly) and any TCP Wrappers testing (if configured). +.wen .section "The DATA ACLs" @@ -23649,7 +23933,7 @@ and try again later, but that is their problem, though it does waste some of your resources. -.section "The MIME ACL" +.section "The SMTP MIME ACL" The &%acl_smtp_mime%& option is available only when Exim is compiled with the content-scanning extension. For details, see chapter &<>&. @@ -23683,10 +23967,21 @@ connection is closed. In these special cases, the QUIT ACL does not run. .section "Finding an ACL to use" .cindex "&ACL;" "finding which to use" -The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so you can -use different ACLs in different circumstances. The resulting string does not -have to be the name of an ACL in the configuration file; there are other -possibilities. Having expanded the string, Exim searches for an ACL as follows: +The value of an &%acl_smtp_%&&'xxx'& option is expanded before use, so +you can use different ACLs in different circumstances. For example, +.code +acl_smtp_rcpt = ${if ={25}{$interface_port} \ + {acl_check_rcpt} {acl_check_rcpt_submit} } +.endd +In the default configuration file there are some example settings for +providing an RFC 4409 message submission service on port 587 and a +non-standard &"smtps"& service on port 465. You can use a string +expansion like this to choose an ACL for MUAs on these ports which is +more appropriate for this purpose than the default ACL on port 25. + +The expanded string does not have to be the name of an ACL in the +configuration file; there are other possibilities. Having expanded the +string, Exim searches for an ACL as follows: .ilist If the string begins with a slash, Exim uses it as a file name, and reads its @@ -23764,10 +24059,16 @@ all the same. &*Note*&: These defaults apply only when the relevant ACL is not defined at all. For any defined ACL, the default action when control reaches the end of the ACL statements is &"deny"&. +.new +For &%acl_smtp_quit%& and &%acl_not_smtp_start%& there is no default because +these two are ACLs that are used only for their side effects. They cannot be +used to accept or reject anything. +.wen + For &%acl_not_smtp%&, &%acl_smtp_auth%&, &%acl_smtp_connect%&, &%acl_smtp_data%&, &%acl_smtp_helo%&, &%acl_smtp_mail%&, &%acl_smtp_mailauth%&, -&%acl_smtp_mime%&, &%acl_smtp_predata%&, &%acl_smtp_quit%&, and -&%acl_smtp_starttls%&, the action when the ACL is not defined is &"accept"&. +&%acl_smtp_mime%&, &%acl_smtp_predata%&, and &%acl_smtp_starttls%&, the action +when the ACL is not defined is &"accept"&. For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&, and &%acl_smtp_vrfy%&), the action when the ACL is not defined is &"deny"&. @@ -23942,29 +24243,27 @@ passes control to subsequent statements only if the message's sender can be verified. Otherwise, it rejects the command. .next +.new .cindex "&%warn%&" "ACL verb" -&%warn%&: If all the conditions are met, a header line is added to an incoming -message and/or a line is written to Exim's main log. In all cases, control -passes to the next ACL statement. The text of the added header line and the log -line are specified by modifiers; if they are not present, a &%warn%& verb just -checks its conditions and obeys any &"immediate"& modifiers such as &%set%& and -&%logwrite%&. There is more about adding header lines in section -&<>&. +&%warn%&: If all the conditions are true, a line specified by the +&%log_message%& modifier is written to Exim's main log. Control always passes +to the next ACL statement. If any condition is false, the log line is not +written. If an identical log line is requested several times in the same +message, only one copy is actually written to the log. If you want to force +duplicates to be written, use the &%logwrite%& modifier instead. + +If &%log_message%& is not present, a &%warn%& verb just checks its conditions +and obeys any &"immediate"& modifiers (such as &%control%&, &%set%&, +&%logwrite%&, and &%add_header%&) that appear before any failing conditions. +There is more about adding header lines in section &<>&. If any condition on a &%warn%& statement cannot be completed (that is, there is -some sort of defer), no header lines are added and the configured log line is -not written. No further conditions or modifiers in the &%warn%& statement are -processed. The incident is logged, but the ACL continues to be processed, from -the next statement onwards. - -If a &%message%& modifier is present on a &%warn%& verb in an ACL that is not -testing an incoming message, it is ignored, and the incident is logged. +some sort of defer), the log line specified by &%log_message%& is not written. +No further conditions or modifiers in the &%warn%& statement are processed. The +incident is logged, and the ACL continues to be processed, from the next +statement onwards. +.wen -A &%warn%& statement may use the &%log_message%& modifier to cause a line to be -written to the main log when the statement's conditions are true. -If an identical log line is requested several times in the same message, only -one copy is actually written to the log. If you want to force duplicates to be -written, use the &%logwrite%& modifier instead. .cindex "&$acl_verify_message$&" When one of the &%warn%& conditions is an address verification that fails, the @@ -23995,19 +24294,19 @@ transports, and filters that are used to deliver a message. There are two sets of these variables: .ilist -The values of &$acl_c0$& to &new(&$acl_c19$&) persist throughout an SMTP +The values of &$acl_c0$& to &$acl_c19$& persist throughout an SMTP connection. They are never reset. Thus, a value that is set while receiving one message is still available when receiving the next message on the same SMTP connection. .next -The values of &$acl_m0$& to &new(&$acl_m19$&) persist only while a message is +The values of &$acl_m0$& to &$acl_m19$& persist only while a message is being received. They are reset afterwards. They are also reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session. .endlist When a message is accepted, the current values of all the ACL variables are preserved with the message and are subsequently made available at delivery -time. The ACL variables are set by modifier called &%set%&. For example: +time. The ACL variables are set by a modifier called &%set%&. For example: .code accept hosts = whatever set acl_m4 = some value @@ -24097,12 +24396,10 @@ by which time Exim has set up the message. The ACL modifiers are as follows: .vlist -.new .vitem &*add_header*&&~=&~<&'text'&> -This modifier specifies one of more header lines that are to be added to an +This modifier specifies one or more header lines that are to be added to an incoming message, assuming, of course, that the message is ultimately accepted. For details, see section &<>&. -.wen .vitem &*control*&&~=&~<&'text'&> .cindex "&%control%&" "ACL modifier" @@ -24266,6 +24563,16 @@ it processes &%message%&. If the expansion fails, or generates an empty string, the modifier is ignored. For ACLs that are triggered by SMTP commands, the message is returned as part of the SMTP error response. +.new +.cindex "SMTP" "error codes" +By default, Exim uses a 550 SMTP code when it denies access. However, if the +message starts with three digits followed by a space, optionally followed by an +extended code of the form &'n.n.n'&, also followed by a space, and the very +first digit is the same as the default error code, the code from the message is +used instead. If the very first digit is incorrect, a panic error is logged, +and the default code is used. +.wen + The text is literal; any quotes are taken as literals, but because the string is expanded, backslash escapes are processed anyway. If the message contains newlines, this gives rise to a multi-line SMTP response. Like &%log_message%&, @@ -24281,7 +24588,6 @@ wish. In particular, if you want the text from &%:fail:%& items in &(redirect)& routers to be passed back as part of the SMTP response, you should either not use a &%message%& modifier, or make use of &$acl_verify_message$&. -.new For compatibility with previous releases of Exim, a &%message%& modifier that is used with a &%warn%& verb behaves in a similar way to the &%add_header%& modifier, but this usage is now deprecated. However, &%message%& acts only when @@ -24289,7 +24595,6 @@ all the conditions are true, wherever it appears in an ACL command, whereas &%add_header%& acts as soon as it is encountered. If &%message%& is used with &%warn%& in an ACL that is not concerned with receiving a message, it has no effect. -.wen .vitem &*set*&&~<&'acl_name'&>&~=&~<&'value'&> .cindex "&%set%&" "ACL modifier" @@ -24306,7 +24611,6 @@ This modifier puts a value into one of the ACL variables (see section The &%control%& modifier supports the following settings: .vlist -.new .vitem &*control&~=&~allow_auth_unadvertised*& This modifier allows a client host to use the SMTP AUTH command even when it has not been advertised in response to EHLO. Furthermore, because there are @@ -24323,7 +24627,6 @@ the authentication mechanism that is given in the command to ensure that it matches an advertised mechanism. When this control is set, the check that a mechanism has been advertised is bypassed. Any configured mechanism can be used by the client. This control is permitted only in the connection and HELO ACLs. -.wen .vitem &*control&~=&~caseful_local_part*& @@ -24417,12 +24720,10 @@ it is placed on Exim's queue and frozen. The control applies only to the current message, not to any subsequent ones that may be received in the same SMTP connection. -.new This modifier can optionally be followed by &`/no_tell`&. If the global option &%freeze_tell%& is set, it is ignored for the current message (that is, nobody is told about the freezing), provided all the &*control=freeze*& modifiers that are obeyed for the current message have the &`/no_tell`& option. -.wen .vitem &*control&~=&~no_mbox_unspool*& @@ -24503,8 +24804,13 @@ No &'Message-ID:'&, &'From:'&, or &'Date:'& header lines are added. There is no check that &'From:'& corresponds to the actual sender. .endlist ilist -This feature may be useful when a remotely-originated message is accepted, -passed to some scanning program, and then re-submitted for delivery. +.new +This control may be useful when a remotely-originated message is accepted, +passed to some scanning program, and then re-submitted for delivery. It can be +used only in the &%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, +and &%acl_not_smtp_start%& ACLs, because it has to be set before the message's +data is read. +.wen .endlist vlist All four possibilities for message fixups can be specified: @@ -24522,7 +24828,6 @@ Remotely submitted, fixups applied: use &`control`& &`=`& &`submission`&. -.new .section "Adding header lines in ACLs" "SECTaddheadacl" .cindex "header lines" "adding in an ACL" .cindex "header lines" "position of added lines" @@ -24554,9 +24859,9 @@ during the DATA and MIME ACLs, after which they are added to the message, again with duplicates suppressed. Thus, it is possible to add two identical header lines to an SMTP message, but only if one is added before DATA and one after. In the case of non-SMTP messages, new headers are accumulated during the -non-SMTP ACL, and added to the message at the end. If a message is rejected -after DATA or by the non-SMTP ACL, all added header lines are included in the -entry that is written to the reject log. +non-SMTP ACLs, and are added to the message after all the ACLs have run. If a +message is rejected after DATA or by the non-SMTP ACL, all added header lines +are included in the entry that is written to the reject log. .cindex "header lines" "added; visibility of" Header lines are not visible in string expansions until they are added to the @@ -24614,7 +24919,6 @@ up in reverse order. &*Warning*&: This facility currently applies only to header lines that are added in an ACL. It does NOT work for header lines that are added in a system filter or in a router or transport. -.wen @@ -24678,8 +24982,10 @@ This feature allows you to make up custom conditions. If the result of expanding the string is an empty string, the number zero, or one of the strings &"no"& or &"false"&, the condition is false. If the result is any non-zero number, or one of the strings &"yes"& or &"true"&, the condition is true. For -any other values, some error is assumed to have occurred, and the ACL returns -&"defer"&. +any other value, some error is assumed to have occurred, and the ACL returns +&"defer"&. &new("However, if the expansion is forced to fail, the condition is +ignored. The effect is to treat it as true, whether it is positive or +negative.") .vitem &*decode&~=&~*&<&'location'&> .cindex "&%decode%&" "ACL condition" @@ -25439,35 +25745,30 @@ policy), through time delays to slow down fast senders, up to rejecting the message. For example: .code # Log all senders' rates -warn - ratelimit = 0 / 1h / strict - log_message = Sender rate $sender_rate / $sender_rate_period +warn ratelimit = 0 / 1h / strict + log_message = Sender rate $sender_rate / $sender_rate_period # Slow down fast senders; note the need to truncate $sender_rate # at the decimal point. -warn - ratelimit = 100 / 1h / per_rcpt / strict - delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ - $sender_rate_limit }s +warn ratelimit = 100 / 1h / per_rcpt / strict + delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ + $sender_rate_limit }s # Keep authenticated users under control -deny - authenticated = * - ratelimit = 100 / 1d / strict / $authenticated_id +deny authenticated = * + ratelimit = 100 / 1d / strict / $authenticated_id # System-wide rate limit -defer - message = Sorry, too busy. Try again later. - ratelimit = 10 / 1s / $primary_hostname +defer message = Sorry, too busy. Try again later. + ratelimit = 10 / 1s / $primary_hostname # Restrict incoming rate from each host, with a default # set using a macro and special cases looked up in a table. -defer - message = Sender rate exceeds $sender_rate_limit \ - messages per $sender_rate_period - ratelimit = ${lookup {$sender_host_address} \ - cdb {DB/ratelimits.cdb} \ - {$value} {RATELIMIT} } +defer message = Sender rate exceeds $sender_rate_limit \ + messages per $sender_rate_period + ratelimit = ${lookup {$sender_host_address} \ + cdb {DB/ratelimits.cdb} \ + {$value} {RATELIMIT} } .endd &*Warning*&: If you have a busy server with a lot of &%ratelimit%& tests, especially with the &%per_rcpt%& option, you may suffer from a performance @@ -25996,10 +26297,10 @@ spam"&), because the recipients of such messages do not include valid tags. There are two expansion items to help with the implementation of the BATV &"prvs"& (private signature) scheme in an Exim configuration. This scheme signs -the original envelope sender address by using a simple shared key to add a hash -of the address and some time-based randomizing information. The &%prvs%& -expansion item creates a signed address, and the &%prvscheck%& expansion item -checks one. The syntax of these expansion items is described in section +the original envelope sender address by using a simple key to add a hash of the +address and some time-based randomizing information. The &%prvs%& expansion +item creates a signed address, and the &%prvscheck%& expansion item checks one. +The syntax of these expansion items is described in section &<>&. As an example, suppose the secret per-address keys are stored in an MySQL @@ -26040,7 +26341,6 @@ the third string (in this case &"1"&), whether or not the cryptographic and timeout checks succeed. The &$prvscheck_result$& variable contains the result of the checks (empty for failure, &"1"& for success). -.new There are two more issues you must consider when implementing prvs-signing. Firstly, you need to ensure that prvs-signed addresses are not blocked by your ACLs. A prvs-signed address contains a slash character, but the default Exim @@ -26052,7 +26352,6 @@ deny message = Restricted characters in address .endd This is a conservative rule that blocks local parts that contain slashes. You should remove the slash in the last line. -.wen Secondly, you have to ensure that the routers accept prvs-signed addresses and deliver them correctly. The easiest way to handle this is to use a &(redirect)& @@ -26363,11 +26662,13 @@ av_scanner = mksd:2 You can safely omit this option (the default value is 1). .vitem &%sophie%& +.new .cindex "virus scanners" "Sophos and Sophie" Sophie is a daemon that uses Sophos' &%libsavi%& library to scan for viruses. -You can get Sophie at &url(http://www.vanja.com/tools/sophie/). The only -option for this scanner type is the path to the UNIX socket that Sophie uses -for client communication. For example: +You can get Sophie at &url(http://www.clanfield.info/sophie/). The only option +for this scanner type is the path to the UNIX socket that Sophie uses for +client communication. For example: +.wen .code av_scanner = sophie:/tmp/sophie .endd @@ -26395,16 +26696,21 @@ use. It can then be one of The condition succeeds if a virus was found, and fail otherwise. This is the recommended usage. .next -&"false"& or &"0"&, in which case no scanning is done and the condition fails -immediately. +.new +&"false"& or &"0"& or an empty string, in which case no scanning is done and +the condition fails immediately. +.wen .next A regular expression, in which case the message is scanned for viruses. The condition succeeds if a virus is found and its name matches the regular expression. This allows you to take special actions on certain types of virus. .endlist +.new You can append &`/defer_ok`& to the &%malware%& condition to accept messages -even if there is a problem with the virus scanner. +even if there is a problem with the virus scanner. Otherwise, such a problem +causes the ACL to defer. +.wen .cindex "&$malware_name$&" When a virus is found, the condition sets up an expansion variable called @@ -26526,8 +26832,10 @@ SpamAssassin profile has been matched or exceeded. If you want to use the it always return &"true"& by appending &`:true`& to the username. .cindex "spam scanning" "returned variables" -When the &%spam%& condition is run, it sets up the following expansion -variables: +When the &%spam%& condition is run, it sets up a number of expansion +variables. With the exception of &$spam_score_int$&, these are usable only +within ACLs; their values are not retained with the message and so cannot be +used at delivery time. .vlist .vitem &$spam_score$& @@ -26537,10 +26845,10 @@ for inclusion in log or reject messages. .vitem &$spam_score_int$& The spam score of the message, multiplied by ten, as an integer value. For example &"34"& or &"305"&. This is useful for numeric comparisons in -conditions. This variable is special; it is saved with the message, and written -to Exim's spool file. This means that it can be used during the whole life of -the message on your Exim system, in particular, in routers or transports during -the later delivery phase. +conditions. This variable is special; its value is saved with the message, and +written to Exim's spool file. This means that it can be used during the whole +life of the message on your Exim system, in particular, in routers or +transports during the later delivery phase. .vitem &$spam_bar$& A string consisting of a number of &"+"& or &"-"& characters, representing the @@ -26569,23 +26877,24 @@ This causes messages to be accepted even if there is a problem with &%spamd%&. Here is a longer, commented example of the use of the &%spam%& condition: +.new .code # put headers in all messages (no matter if spam or not) -warn message = X-Spam-Score: $spam_score ($spam_bar) - spam = nobody:true -warn message = X-Spam-Report: $spam_report - spam = nobody:true +warn spam = nobody:true + add_header = X-Spam-Score: $spam_score ($spam_bar) + add_header = X-Spam-Report: $spam_report # add second subject line with *SPAM* marker when message # is over threshold -warn message = Subject: *SPAM* $h_Subject: - spam = nobody +warn spam = nobody + add_header = Subject: *SPAM* $h_Subject: # reject spam at high scores (> 12) deny message = This message scored $spam_score spam points. spam = nobody:true condition = ${if >{$spam_score_int}{120}{1}{0}} .endd +.wen @@ -26593,6 +26902,7 @@ deny message = This message scored $spam_score spam points. .cindex "content scanning" "MIME parts" .cindex "MIME content scanning" .cindex "&%acl_smtp_mime%&" +.cindex "&%acl_not_smtp_mime%&" The &%acl_smtp_mime%& global option specifies an ACL that is called once for each MIME part of an SMTP message, including multipart types, in the sequence of their position in the message. Similarly, the &%acl_not_smtp_mime%& option @@ -26600,13 +26910,13 @@ specifies an ACL that is used for the MIME parts of non-SMTP messages. These options may both refer to the same ACL if you want the same processing in both cases. -These ACLs are called (possibly many times) just before the &%acl_smtp_data%& -ACL in the case of an SMTP message, or just before a non-SMTP message is -accepted. However, a MIME ACL is called only if the message contains a -&'MIME-Version:'& header line. When a call to a MIME ACL does not yield -&"accept"&, ACL processing is aborted and the appropriate result code is sent -to the client. In the case of an SMTP message, the &%acl_smtp_data%& ACL is not -called when this happens. +&new("These ACLs are called (possibly many times) just before the +&%acl_smtp_data%& ACL in the case of an SMTP message, or just before the +&%acl_not_smtp%& ACL in the case of a non-SMTP message.") However, a MIME ACL +is called only if the message contains a &'MIME-Version:'& header line. When a +call to a MIME ACL does not yield &"accept"&, ACL processing is aborted and the +appropriate result code is sent to the client. In the case of an SMTP message, +the &%acl_smtp_data%& ACL is not called when this happens. You cannot use the &%malware%& or &%spam%& conditions in a MIME ACL; these can only be used in the DATA or non-SMTP ACLs. However, you can use the &%regex%& @@ -27384,7 +27694,6 @@ fine in this circumstance. Unless you have made a mistake with the recipient addresses, you should get a return code of zero. -.new .vitem &*pid_t&~child_open_exim2(int&~*fd,&~uschar&~*sender,&~uschar&~&&& *sender_authentication)*& This function is a more sophisticated version of &'child_open()'&. The command @@ -27393,7 +27702,6 @@ that it runs is: &`exim -t -oem -oi -f `&&'sender'&&` -oMas `&&'sender_authentication'& .endd The third argument may be NULL, in which case the &%-oMas%& option is omitted. -.wen .vitem &*void&~debug_printf(char&~*,&~...)*& @@ -27535,9 +27843,9 @@ described with the structure of &%recipient_item%& above), because it pre-dates the addition of that field to the structure. However, it is easy to add such a value afterwards. For example: .code -receive_add_recipient(US"monitor@mydom.example", -1); -recipients_list[recipients_count-1].errors_to = -US"postmaster@mydom.example"; + receive_add_recipient(US"monitor@mydom.example", -1); + recipients_list[recipients_count-1].errors_to = + US"postmaster@mydom.example"; .endd .vitem &*BOOL&~receive_remove_recipient(uschar&~*recipient)*& @@ -28240,10 +28548,8 @@ The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any .section "The Auto-Submitted: header line" -.new Whenever Exim generates an autoreply, a bounce, or a delay warning message, it includes the header line: -.wen .code Auto-Submitted: auto-replied .endd @@ -28358,7 +28664,6 @@ changed to the time of acceptance, which is (apart from a small delay while the -H spool file is written) the earliest time at which delivery could start. -.new .section "The References: header line" .cindex "&'References:'& header line" Messages created by the &(autoreply)& transport include a &'References:'& @@ -28370,7 +28675,6 @@ processing software does not cope well with very long header lines, no more than 12 message IDs are copied from the &'References:'& header line in the incoming message. If there are more than 12, the first one and then the final 11 are copied, before adding the message ID of the incoming message. -.wen @@ -29585,7 +29889,6 @@ the address, giving a suitable error message. -.new .section "Variable Envelope Return Paths (VERP)" "SECTverp" .cindex "VERP" .cindex "Variable Envelope Return Paths" @@ -29625,17 +29928,19 @@ rewritten as .code somelist-request=subscriber%other.dom.example@your.dom.example .endd +.new .cindex "&$local_part$&" -For this to work, you must also arrange for outgoing messages that have -&"-request"& in their return paths to have just a single recipient. That is +For this to work, you must tell Exim to send multiple copies of messages that +have more than one recipient, so that each copy has just one recipient. This is achieved by setting &%max_rcpt%& to 1. Without this, a single copy of a message might be sent to several different recipients in the same domain, in which case &$local_part$& is not available in the transport, because it is not unique. Unless your host is doing nothing but mailing list deliveries, you should probably use a separate transport for the VERP deliveries, so as not to use -extra resources for the others. This can easily be done by expanding the -&%transport%& option in the router: +extra resources in making one-per-recipient copies for other deliveries. This +can easily be done by expanding the &%transport%& option in the router: +.wen .code dnslookup: driver = dnslookup @@ -29679,7 +29984,6 @@ a lot of addresses resolve to the same host and the connection is slow, sending a separate copy of the message for each address may take substantially longer than sending a single copy with many recipients (for which VERP cannot be used). -.wen @@ -30644,7 +30948,7 @@ selection marked by asterisks: &` received_sender `& sender on <= lines &`*rejected_header `& header contents on reject log &`*retry_defer `& &"retry time not reached"& -&` return_path_on_delivery `& put return path on => and *\ lines +&` return_path_on_delivery `& put return path on => and ** lines &` sender_on_delivery `& add sender to => lines &`*sender_verify_fail `& sender verification failures &`*size_reject `& rejection because too big @@ -30826,13 +31130,11 @@ and bounce line, tagged by F= (for &"from"&). This is the original sender that was received with the message; it is not necessarily the same as the outgoing return path. .next -.new .cindex "log" "sender verify failure" -&%sender_verify_failure%&: If this selector is unset, the separate log line -that gives details of a sender verification failure is not written. Log lines -for the rejection of SMTP commands contain just &"sender verify failed"&, so -some detail is lost. -.wen +&%sender_verify_fail%&: If this selector is unset, the separate log line that +gives details of a sender verification failure is not written. Log lines for +the rejection of SMTP commands contain just &"sender verify failed"&, so some +detail is lost. .next .cindex "log" "size rejection" &%size_reject%&: A log line is written whenever a message is rejected because @@ -31160,14 +31462,13 @@ whose name ends in COMPRESS_SUFFIX through &'zcat'& as it searches it. .cindex "&'exipick'&" John Jetmore's &'exipick'& utility is included in the Exim distribution. It lists messages from the queue according to a variety of criteria. For details, -run: +visit &url(http://www.exim.org/eximwiki/ToolExipickManPage) or run: .code exipick --help .endd .section "Cycling log files (exicyclog)" "SECTcyclogfil" -.new .cindex "log" "cycling local files" .cindex "cycling logs" .cindex "&'exicyclog'&" @@ -31193,7 +31494,6 @@ run &_mainlog_& becomes &_mainlog.01_&, the previous &_mainlog.01_& becomes &_mainlog.02_& and so on, up to the limit that is set in the script or by the &%-k%& option. Log files whose numbers exceed the limit are discarded. Reject logs are handled similarly. -.wen If the limit is greater than 99, the script uses 3-digit numbers such as &_mainlog.001_&, &_mainlog.002_&, etc. If you change from a number less than 99 @@ -32452,7 +32752,6 @@ order, and are omitted when not relevant: .vlist .vitem "&%-acl%& <&'number'&> <&'length'&>" -.new This item is obsolete, and is not generated from Exim release 4.61 onwards; &%-aclc%& and &%-aclm%& are used instead. However, &%-acl%& is still recognized, to provide backward compatibility. In the old format, a line of @@ -32474,7 +32773,6 @@ A line of this form is present for every ACL message variable that is not empty. The number identifies the variable. The length is the length of the data string for the variable. The string itself starts at the beginning of the next line, and is followed by a newline character. It may contain internal newlines. -.wen .vitem "&%-active_hostname%& <&'hostname'&>" This is present if, when the message was received over SMTP, the value of