seems there is no "-a" parameter to "cp" in non-gnu "cp". Use "-p" instead.

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d3a1f758e362cb10435875244020979b5aec66dd..6162739d87d721938814ae1ffc5d37bf6a4cfd37 100644 (file)
--- 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.30 2008/01/28 18:30:29 fanf2 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.39 2008/03/26 15:37:37 fanf2 Exp $

 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is


@@ -367,6 +367,7 @@ contributors.
 
 
 .section "Exim documentation" "SECID1"
 
 
 .section "Exim documentation" "SECID1"

+. Keep this example change bar when updating the documentation!

 .new
 .cindex "documentation"
 This edition of the Exim specification applies to version &version; of Exim.
 .new
 .cindex "documentation"
 This edition of the Exim specification applies to version &version; of Exim.


@@ -430,8 +431,6 @@ directory are:
 .row &_exim.8_&              "a man page of Exim's command line options"
 .row &_experimental.txt_&    "documentation of experimental features"
 .row &_filter.txt_&          "specification of the filter language"
 .row &_exim.8_&              "a man page of Exim's command line options"
 .row &_experimental.txt_&    "documentation of experimental features"
 .row &_filter.txt_&          "specification of the filter language"

-.row &_pcrepattern.txt_&     "specification of PCRE regular expressions"
-.row &_pcretest.txt_&        "specification of the PCRE testing program"

 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
 .endtable
 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
 .endtable


@@ -456,12 +455,12 @@ Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge.
 .cindex "FAQ"
 As well as Exim distribution tar files, the Exim web site contains a number of
 differently formatted versions of the documentation. A recent addition to the
 .cindex "FAQ"
 As well as Exim distribution tar files, the Exim web site contains a number of
 differently formatted versions of the documentation. A recent addition to the

-online information is the Exim wiki &new("(&url(http://wiki.exim.org))"),
+online information is the Exim wiki (&url(http://wiki.exim.org)),

 which contains what used to be a separate FAQ, as well as various other
 examples, tips, and know-how that have been contributed by Exim users.
 
 .cindex Bugzilla
 which contains what used to be a separate FAQ, as well as various other
 examples, tips, and know-how that have been contributed by Exim users.
 
 .cindex Bugzilla

-An Exim Bugzilla exists at &new("&url(http://bugs.exim.org)"). You can use
+An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use

 this to report bugs, and also to add items to the wish list. Please search
 first to check that you are not duplicating a previous entry.
 
 this to report bugs, and also to add items to the wish list. Please search
 first to check that you are not duplicating a previous entry.
 


@@ -500,8 +499,8 @@ information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/).
 .section "Bug reports" "SECID5"
 .cindex "bug reports"
 .cindex "reporting bugs"
 .section "Bug reports" "SECID5"
 .cindex "bug reports"
 .cindex "reporting bugs"

-Reports of obvious bugs &new("can be emailed to &'bugs@exim.org'& or reported
-via the Bugzilla (&url(http://bugs.exim.org)).") However, if you are unsure
+Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported
+via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure

 whether some behaviour is a bug or not, the best thing to do is to post a
 message to the &'exim-dev'& mailing list and have it discussed.
 
 whether some behaviour is a bug or not, the best thing to do is to post a
 message to the &'exim-dev'& mailing list and have it discussed.
 


@@ -731,10 +730,9 @@ A number of pieces of external code are included in the Exim distribution.
 .ilist
 Regular expressions are supported in the main Exim program and in the
 Exim monitor using the freely-distributable PCRE library, copyright
 .ilist
 Regular expressions are supported in the main Exim program and in the
 Exim monitor using the freely-distributable PCRE library, copyright

-© University of Cambridge. The source to a cut down version of PCRE
-used to be distributed in the directory &_src/pcre_&. However, this is
-no longer the case and you will need to use a system PCRE library or
-obtain and install the full version of the library from
+© University of Cambridge. The source to PCRE is no longer shipped with
+Exim, so you will need to use the version of PCRE shipped with your system,
+or obtain and install the full version of the library from

 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
 .next
 .cindex "cdb" "acknowledgment"
 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
 .next
 .cindex "cdb" "acknowledgment"


@@ -1654,7 +1652,7 @@ architecture and operating system for itself, but the defaults can be
 overridden if necessary.
 
 
 overridden if necessary.
 
 

-.section "PCRE library" "SECTdb"
+.section "PCRE library" "SECTpcre"

 .cindex "PCRE library"
 Exim no longer has an embedded PCRE library as the vast majority of
 modern systems include PCRE as a system library, although you may need
 .cindex "PCRE library"
 Exim no longer has an embedded PCRE library as the vast majority of
 modern systems include PCRE as a system library, although you may need


@@ -2225,9 +2223,8 @@ but this usage is deprecated.
 
 .cindex "installing Exim" "what is not installed"
 Running &'make install'& does not copy the Exim 4 conversion script
 
 .cindex "installing Exim" "what is not installed"
 Running &'make install'& does not copy the Exim 4 conversion script

-&'convert4r4'&, or the &'pcretest'& test program. You will probably run the
-first of these only once (if you are upgrading from Exim 3), and the second
-isn't really part of Exim. None of the documentation files in the &_doc_&
+&'convert4r4'&. You will probably run this only once if you are
+upgrading from Exim 3. None of the documentation files in the &_doc_&

 directory are copied, except for the info files when you have set
 INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
 
 directory are copied, except for the info files when you have set
 INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
 


@@ -5907,13 +5904,11 @@ Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by
 O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)).
 
 The documentation for the syntax and semantics of the regular expressions that
 O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)).
 
 The documentation for the syntax and semantics of the regular expressions that

-are supported by PCRE is included in plain text in the file
-&_doc/pcrepattern.txt_& in the Exim distribution, and also in the HTML
-tarbundle of Exim documentation. It describes in detail the features of the
-regular expressions that PCRE supports, so no further description is included
-here. The PCRE functions are called from Exim using the default option settings
-(that is, with no PCRE options set), except that the PCRE_CASELESS option is
-set when the matching is required to be case-insensitive.
+are supported by PCRE is included in the PCRE distribution, and no further
+description is included here. The PCRE functions are called from Exim using
+the default option settings (that is, with no PCRE options set), except that
+the PCRE_CASELESS option is set when the matching is required to be
+case-insensitive.

 
 In most cases, when a regular expression is required in an Exim configuration,
 it has to start with a circumflex, in order to distinguish it from plain text
 
 In most cases, when a regular expression is required in an Exim configuration,
 it has to start with a circumflex, in order to distinguish it from plain text


@@ -5952,47 +5947,6 @@ $ is needed because string expansion also interprets dollar characters.
 
 
 
 
 
 

-.section "Testing regular expressions" "SECID59"
-.cindex "testing" "regular expressions"
-.cindex "regular expressions" "testing"
-.cindex "&'pcretest'&"
-A program called &'pcretest'& forms part of the PCRE distribution and is built
-with PCRE during the process of building Exim. It is primarily intended for
-testing PCRE itself, but it can also be used for experimenting with regular
-expressions. After building Exim, the binary can be found in the build
-directory (it is not installed anywhere automatically). There is documentation
-of various options in &_doc/pcretest.txt_&, but for simple testing, none are
-needed. This is the output of a sample run of &'pcretest'&:
-.display
-&`  re> `&&*&`/^([@]+)@.+\.(ac|edu)\.(?!kr)[a-z]{2}$/`&*&
-&`data> `&&*&`x@y.ac.uk`&*&
-&` 0: x@y.ac.uk`&
-&` 1: x`&
-&` 2: ac`&
-&`data> `&&*&`x@y.ac.kr`&*&
-&`No match`&
-&`data> `&&*&`x@y.edu.com`&*&
-&`No match`&
-&`data> `&&*&`x@y.edu.co`&*&
-&` 0: x@y.edu.co`&
-&` 1: x`&
-&` 2: edu`&
-.endd
-Input typed by the user is shown in bold face. After the &"re>"& prompt, a
-regular expression enclosed in delimiters is expected. If this compiles without
-error, &"data>"& prompts are given for strings against which the expression is
-matched. An empty data line causes a new regular expression to be read. If the
-match is successful, the captured substring values (that is, what would be in
-the variables &$0$&, &$1$&, &$2$&, etc.) are shown. The above example tests for
-an email address whose domain ends with either &"ac"& or &"edu"& followed by a
-two-character top-level domain that is not &"kr"&. The local part is captured
-in &$1$& and the &"ac"& or &"edu"& in &$2$&.
-
-
-
-
-
-

 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 


@@ -7156,9 +7110,9 @@ 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.
 &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%&
 option (as appropriate) must be set to a colon-separated list of server
 information.

-&new("(For MySQL and PostgreSQL only, the global option need not be set if all
+(For MySQL and PostgreSQL only, the global option need not be set if all

 queries contain their own server information &-- see section
 queries contain their own server information &-- see section

-&<<SECTspeserque>>&.)") Each item in the list is a slash-separated list of four
+&<<SECTspeserque>>&.) Each item in the list is a slash-separated list of four

 items: host name, database name, user name, and password. In the case of
 Oracle, the host name field is used for the &"service name"&, and the database
 name field is not used and should be empty. For example:
 items: host name, database name, user name, and password. In the case of
 Oracle, the host name field is used for the &"service name"&, and the database
 name field is not used and should be empty. For example:


@@ -10762,7 +10716,7 @@ This is an obsolete name for &$received_port$&.
 .vitem &$item$&
 .vindex "&$item$&"
 This variable is used during the expansion of &*forall*& and &*forany*&
 .vitem &$item$&
 .vindex "&$item$&"
 This variable is used during the expansion of &*forall*& and &*forany*&

-conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*man*&, and
+conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*map*&, and

 &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is
 empty.
 
 &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is
 empty.
 


@@ -11641,9 +11595,9 @@ details of the &(smtp)& transport.
 When a message is received from a remote host over an encrypted SMTP
 connection, and Exim is configured to request a certificate from the client,
 the value of the Distinguished Name of the certificate is made available in the
 When a message is received from a remote host over an encrypted SMTP
 connection, and Exim is configured to request a certificate from the client,
 the value of the Distinguished Name of the certificate is made available in the

-&$tls_peerdn$& during subsequent processing. &new("Like &$tls_cipher$&, the
+&$tls_peerdn$& during subsequent processing. Like &$tls_cipher$&, the

 value is retained during message delivery, except during outbound SMTP
 value is retained during message delivery, except during outbound SMTP

-deliveries.")
+deliveries.

 
 .vitem &$tod_bsdinbox$&
 .vindex "&$tod_bsdinbox$&"
 
 .vitem &$tod_bsdinbox$&
 .vindex "&$tod_bsdinbox$&"


@@ -12186,7 +12140,7 @@ listed in more than one group.
 .row &%disable_ipv6%&                "do no IPv6 processing"
 .row &%keep_malformed%&              "for broken files &-- should not happen"
 .row &%localhost_number%&            "for unique message ids in clusters"
 .row &%disable_ipv6%&                "do no IPv6 processing"
 .row &%keep_malformed%&              "for broken files &-- should not happen"
 .row &%localhost_number%&            "for unique message ids in clusters"

-.row &new(&%message_body_newlines%&) "retain newlines in &$message_body$&"
+.row &%message_body_newlines%&       "retain newlines in &$message_body$&"

 .row &%message_body_visible%&        "how much to show in &$message_body$&"
 .row &%mua_wrapper%&                 "run in &""MUA wrapper""& mode"
 .row &%print_topbitchars%&           "top-bit characters are printing"
 .row &%message_body_visible%&        "how much to show in &$message_body$&"
 .row &%mua_wrapper%&                 "run in &""MUA wrapper""& mode"
 .row &%print_topbitchars%&           "top-bit characters are printing"


@@ -12253,13 +12207,13 @@ listed in more than one group.
 
 .section "Data lookups" "SECID101"
 .table2
 
 .section "Data lookups" "SECID101"
 .table2

-.row &new(&%ibase_servers%&)         "InterBase servers"
+.row &%ibase_servers%&               "InterBase servers"

 .row &%ldap_default_servers%&        "used if no server in query"
 .row &%ldap_version%&                "set protocol version"
 .row &%lookup_open_max%&             "lookup files held open"
 .row &%ldap_default_servers%&        "used if no server in query"
 .row &%ldap_version%&                "set protocol version"
 .row &%lookup_open_max%&             "lookup files held open"

-.row &new(&%mysql_servers%&)               "default MySQL servers"
-.row &new(&%oracle_servers%&)              "Oracle servers"
-.row &new(&%pgsql_servers%&)               "default PostgreSQL servers"
+.row &%mysql_servers%&               "default MySQL servers"
+.row &%oracle_servers%&              "Oracle servers"
+.row &%pgsql_servers%&               "default PostgreSQL servers"

 .row &%sqlite_lock_timeout%&         "as it says"
 .endtable
 
 .row &%sqlite_lock_timeout%&         "as it says"
 .endtable
 


@@ -12302,7 +12256,7 @@ listed in more than one group.
 .row &%check_spool_space%&           "before accepting a message"
 .row &%deliver_queue_load_max%&      "no queue deliveries if load high"
 .row &%queue_only_load%&             "queue incoming if load high"
 .row &%check_spool_space%&           "before accepting a message"
 .row &%deliver_queue_load_max%&      "no queue deliveries if load high"
 .row &%queue_only_load%&             "queue incoming if load high"

-.row &new(&%queue_only_load_latch%&) "don't re-evaluate load for each message"
+.row &%queue_only_load_latch%&       "don't re-evaluate load for each message"

 .row &%queue_run_max%&               "maximum simultaneous queue runners"
 .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
 .row &%smtp_accept_max%&             "simultaneous incoming connections"
 .row &%queue_run_max%&               "maximum simultaneous queue runners"
 .row &%remote_max_parallel%&         "parallel SMTP delivery per message"
 .row &%smtp_accept_max%&             "simultaneous incoming connections"


@@ -12537,7 +12491,7 @@ See also the &'Policy controls'& section above.
 .row &%queue_only%&                  "no immediate delivery at all"
 .row &%queue_only_file%&             "no immediate delivery if file exists"
 .row &%queue_only_load%&             "no immediate delivery if load is high"
 .row &%queue_only%&                  "no immediate delivery at all"
 .row &%queue_only_file%&             "no immediate delivery if file exists"
 .row &%queue_only_load%&             "no immediate delivery if load is high"

-.row &new(&%queue_only_load_latch%&) "don't re-evaluate load for each message"
+.row &%queue_only_load_latch%&       "don't re-evaluate load for each message"

 .row &%queue_only_override%&         "allow command line to override"
 .row &%queue_run_in_order%&          "order of arrival"
 .row &%queue_run_max%&               "of simultaneous queue runners"
 .row &%queue_only_override%&         "allow command line to override"
 .row &%queue_run_in_order%&          "order of arrival"
 .row &%queue_run_max%&               "of simultaneous queue runners"


@@ -13118,7 +13072,7 @@ dns_check_names_pattern = \
   (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
 .endd
 which permits only letters, digits, slashes, and hyphens in components, but
   (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$
 .endd
 which permits only letters, digits, slashes, and hyphens in components, but

-they must start and end with a letter or digit. &new(Slashes) are not, in fact,
+they must start and end with a letter or digit. Slashes are not, in fact,

 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
 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


@@ -20651,8 +20605,8 @@ delivers the message to it using the LMTP protocol.
 
 .option timeout lmtp time 5m
 The transport is aborted if the created process or Unix domain socket does not
 
 .option timeout lmtp time 5m
 The transport is aborted if the created process or Unix domain socket does not

-respond to LMTP commands or message input within this timeout. &new("Delivery
-is deferred, and will be tried again later.") Here is an example of a typical
+respond to LMTP commands or message input within this timeout. Delivery
+is deferred, and will be tried again later. Here is an example of a typical

 LMTP transport:
 .code
 lmtp:
 LMTP transport:
 .code
 lmtp:


@@ -21655,8 +21609,8 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter
 .vindex "&$host$&"
 .vindex "&$host_address$&"
 This option specifies which interface to bind to when making an outgoing SMTP
 .vindex "&$host$&"
 .vindex "&$host_address$&"
 This option specifies which interface to bind to when making an outgoing SMTP

-call. &new("The value is an IP address, not an interface name such as
-&`eth0`&.") Do not confuse this with the interface address that was used when a
+call. The value is an IP address, not an interface name such as
+&`eth0`&. Do not confuse this with the interface address that was used when a

 message was received, which is in &$received_ip_address$&, formerly known as
 &$interface_address$&. The name was changed to minimize confusion with the
 outgoing interface address. There is no variable that contains an outgoing
 message was received, which is in &$received_ip_address$&, formerly known as
 &$interface_address$&. The name was changed to minimize confusion with the
 outgoing interface address. There is no variable that contains an outgoing


@@ -22282,11 +22236,9 @@ rewriting rule is skipped unless the relevant addresses are being processed.
 &`s`&       rewrite the &'Sender:'& header
 &`t`&       rewrite the &'To:'& header
 .endd
 &`s`&       rewrite the &'Sender:'& header
 &`t`&       rewrite the &'To:'& header
 .endd

-.new

 "All headers" means all of the headers listed above that can be selected
 individually, plus their &'Resent-'& versions. It does not include
 other headers such as &'Subject:'& etc.
 "All headers" means all of the headers listed above that can be selected
 individually, plus their &'Resent-'& versions. It does not include
 other headers such as &'Subject:'& etc.

-.wen

 
 You should be particularly careful about rewriting &'Sender:'& headers, and
 restrict this to special known cases in your own domains.
 
 You should be particularly careful about rewriting &'Sender:'& headers, and
 restrict this to special known cases in your own domains.


@@ -23572,17 +23524,20 @@ login:
   driver = plaintext
   public_name = LOGIN
   server_prompts = Username:: : Password::
   driver = plaintext
   public_name = LOGIN
   server_prompts = Username:: : Password::

-  server_condition = ${if ldapauth \
-    {user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
-    pass=${quote:$auth2} \
-    ldap://ldap.example.org/}}
+  server_condition = ${if and{{
+    !eq{}{$auth1} }{ \
+    ldapauth{user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
+             pass=${quote:$auth2} \
+             ldap://ldap.example.org/} }} }

   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd
   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd

-Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for
-authentication. However, the basic &%quote%& operator, rather than any of the
-LDAP quoting operators, is the correct one to use for the password, because
-quoting is needed only to make the password conform to the Exim syntax. At the
-LDAP level, the password is an uninterpreted string.
+We have to check that the username is not empty before using it, because LDAP
+does not permit empty DN components. We must also use the &%quote_ldap_dn%&
+operator to correctly quote the DN for authentication. However, the basic
+&%quote%& operator, rather than any of the LDAP quoting operators, is the
+correct one to use for the password, because quoting is needed only to make
+the password conform to the Exim syntax. At the LDAP level, the password is an
+uninterpreted string.

 
 
 
 
 
 


@@ -24351,8 +24306,8 @@ incoming message (by default &-- you can, of course, change this), and it is
 also included in the log line that records a message's arrival, keyed by
 &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%&
 condition can be used to test for specific cipher suites in ACLs.
 also included in the log line that records a message's arrival, keyed by
 &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%&
 condition can be used to test for specific cipher suites in ACLs.

-&new("(For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section
-&<<SECID185>>&.)")
+(For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section
+&<<SECID185>>&.)

 
 Once TLS has been established, the ACLs that run for subsequent SMTP commands
 can check the name of the cipher suite and vary their actions accordingly. The
 
 Once TLS has been established, the ACLs that run for subsequent SMTP commands
 can check the name of the cipher suite and vary their actions accordingly. The


@@ -24672,7 +24627,7 @@ options in the main part of the configuration. These options are:
 .irow &%acl_smtp_mail%&        "ACL for MAIL"
 .irow &%acl_smtp_mailauth%&    "ACL for the AUTH parameter of MAIL"
 .irow &%acl_smtp_mime%&        "ACL for content-scanning MIME parts"
 .irow &%acl_smtp_mail%&        "ACL for MAIL"
 .irow &%acl_smtp_mailauth%&    "ACL for the AUTH parameter of MAIL"
 .irow &%acl_smtp_mime%&        "ACL for content-scanning MIME parts"

-.irow &new(&%acl_smtp_notquit%&)  "ACL for non-QUIT terminations"
+.irow &%acl_smtp_notquit%&     "ACL for non-QUIT terminations"

 .irow &%acl_smtp_predata%&     "ACL at start of DATA command"
 .irow &%acl_smtp_quit%&        "ACL for QUIT"
 .irow &%acl_smtp_rcpt%&        "ACL for RCPT"
 .irow &%acl_smtp_predata%&     "ACL at start of DATA command"
 .irow &%acl_smtp_quit%&        "ACL for QUIT"
 .irow &%acl_smtp_rcpt%&        "ACL for RCPT"


@@ -26362,7 +26317,9 @@ verified as a sender.
 .cindex "&ACL;" "testing a DNS list"
 In its simplest form, the &%dnslists%& condition tests whether the calling host
 is on at least one of a number of DNS lists by looking up the inverted IP
 .cindex "&ACL;" "testing a DNS list"
 In its simplest form, the &%dnslists%& condition tests whether the calling host
 is on at least one of a number of DNS lists by looking up the inverted IP

-address in one or more DNS domains. For example, if the calling host's IP
+address in one or more DNS domains. (Note that DNS list domains are not mail
+domains, so the &`+`& syntax for named lists doesn't work - it is used for
+special options instead.) For example, if the calling host's IP

 address is 192.168.62.43, and the ACL statement is
 .code
 deny dnslists = blackholes.mail-abuse.org : \
 address is 192.168.62.43, and the ACL statement is
 .code
 deny dnslists = blackholes.mail-abuse.org : \


@@ -26854,7 +26811,7 @@ parameter &'m'& is the maximum number of messages that a client is permitted to
 send in each time interval. It also specifies the number of messages permitted
 in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'&
 constant, you can allow a client to send more messages in a burst without
 send in each time interval. It also specifies the number of messages permitted
 in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'&
 constant, you can allow a client to send more messages in a burst without

-changing its overall sending rate limit. Conversely, if &'m'& and &'p'& are
+changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are

 both small, messages must be sent at an even rate.
 
 There is a script in &_util/ratelimit.pl_& which extracts sending rates from
 both small, messages must be sent at an even rate.
 
 There is a script in &_util/ratelimit.pl_& which extracts sending rates from


@@ -26863,21 +26820,22 @@ when deploying the &%ratelimit%& ACL condition. The script prints usage
 instructions when it is run with no arguments.
 
 The key is used to look up the data for calculating the client's average
 instructions when it is run with no arguments.
 
 The key is used to look up the data for calculating the client's average

-sending rate. This data is stored in a database maintained by Exim in its spool
-directory, alongside the retry and other hints databases. The default key is
-&$sender_host_address$&, which applies the limit to each client host IP address.
+sending rate. This data is stored in Exim's spool directory, alongside the
+retry and other hints databases. The default key is &$sender_host_address$&,
+which means Exim computes the sending rate of each client host IP address.

 By changing the key you can change how Exim identifies clients for the purpose
 of ratelimiting. For example, to limit the sending rate of each authenticated
 user, independent of the computer they are sending from, set the key to
 &$authenticated_id$&. You must ensure that the lookup key is meaningful; for
 example, &$authenticated_id$& is only meaningful if the client has
 By changing the key you can change how Exim identifies clients for the purpose
 of ratelimiting. For example, to limit the sending rate of each authenticated
 user, independent of the computer they are sending from, set the key to
 &$authenticated_id$&. You must ensure that the lookup key is meaningful; for
 example, &$authenticated_id$& is only meaningful if the client has

-authenticated, and you can check with the &%authenticated%& ACL condition.
+authenticated (which you can check with the &%authenticated%& ACL condition).

 
 

-If you want to limit the rate at which a recipient receives messages, you can
-use the key &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in
-a RCPT ACL.
+The lookup key does not have to identify clients: If you want to limit the
+rate at which a recipient receives messages, you can use the key
+&`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT
+ACL.

 
 

-Internally, Exim includes the smoothing constant &'p'& and the options in the
+Internally, Exim appends the smoothing constant &'p'& and the options onto the

 lookup key because they alter the meaning of the stored data. This is not true
 for the limit &'m'&, so you can alter the configured maximum rate and Exim will
 still remember clients' past behaviour, but if you alter the other ratelimit
 lookup key because they alter the meaning of the stored data. This is not true
 for the limit &'m'&, so you can alter the configured maximum rate and Exim will
 still remember clients' past behaviour, but if you alter the other ratelimit


@@ -26898,17 +26856,17 @@ the default if none of the &%per_*%& options is specified.
 
 The &%per_byte%& option limits the sender's email bandwidth. Note that it is
 best to use this option in the DATA ACL; if it is used in an earlier ACL it
 
 The &%per_byte%& option limits the sender's email bandwidth. Note that it is
 best to use this option in the DATA ACL; if it is used in an earlier ACL it

-relies on the SIZE parameter on the MAIL command, which may be inaccurate or
-completely missing. You can follow the limit &'m'& in the configuration with K,
-M, or G to specify limits in kilobytes, megabytes, or gigabytes, respectively.
+relies on the SIZE parameter specified by the client in its MAIL command,
+which may be inaccurate or completely missing. You can follow the limit &'m'&
+in the configuration with K, M, or G to specify limits in kilobytes,
+megabytes, or gigabytes, respectively.

 
 

-.new

 The &%per_rcpt%& option causes Exim to limit the rate at which
 recipients are accepted. To be effective, it would need to be used in
 either the &%acl_smtp_rcpt%& or the &%acl_not_smtp%& ACL. In the
 &%acl_smtp_rcpt%& ACL, the number of recipients is incremented by one.
 In the case of a locally submitted message in the &%acl_not_smtp%& ACL,
 The &%per_rcpt%& option causes Exim to limit the rate at which
 recipients are accepted. To be effective, it would need to be used in
 either the &%acl_smtp_rcpt%& or the &%acl_not_smtp%& ACL. In the
 &%acl_smtp_rcpt%& ACL, the number of recipients is incremented by one.
 In the case of a locally submitted message in the &%acl_not_smtp%& ACL,

-the number of recipients incremented is equal to &%$recipients_count%&
+the number of recipients is incremented by the &%$recipients_count%&

 for the entire message. Note that in either case the rate limiting
 engine will see a message with many recipients as a large high-speed
 burst.
 for the entire message. Note that in either case the rate limiting
 engine will see a message with many recipients as a large high-speed
 burst.


@@ -26918,7 +26876,6 @@ condition is processed. This can be used to limit the SMTP command rate.
 This command is essentially an alias of &%per_rcpt%& to make it clear
 that the effect is to limit the rate at which individual commands,
 rather than recipients, are accepted.
 This command is essentially an alias of &%per_rcpt%& to make it clear
 that the effect is to limit the rate at which individual commands,
 rather than recipients, are accepted.

-.wen

 
 .section "Ratelimit options for handling fast clients" "ratophanfas"
 If a client's average rate is greater than the maximum, the rate limiting
 
 .section "Ratelimit options for handling fast clients" "ratophanfas"
 If a client's average rate is greater than the maximum, the rate limiting


@@ -26928,17 +26885,18 @@ counter-measures (such as rejecting the message) that may be specified by the
 rest of the ACL. The default mode is leaky, which avoids a sender's
 over-aggressive retry rate preventing it from getting any email through.
 
 rest of the ACL. The default mode is leaky, which avoids a sender's
 over-aggressive retry rate preventing it from getting any email through.
 

-The &%strict%& option means that the client's recorded rate is always updated.
-The effect of this is that Exim measures the client's average rate of attempts
-to send email, which can be much higher than the maximum &new("it is actually
-allowed. If the client is over the limit it may be subjected to
-counter-measures in the ACL until it slows down below the maximum rate.") The
-smoothing period determines the time it takes for a high sending rate to decay
-exponentially to 37% of its peak value, which means that you can work out the
-time (the number of smoothing periods) that a client is subjected to
-counter-measures after an over-limit burst with this formula:
+The &%strict%& option means that the client's recorded rate is always
+updated. The effect of this is that Exim measures the client's average rate
+of attempts to send email, which can be much higher than the maximum it is
+actually allowed. If the client is over the limit it may be subjected to
+counter-measures by the ACL until it slows down below the maximum rate. If
+the client stops attempting to send email for the time specified in the &'p'&
+parameter then its computed rate will decay exponentially to 37% of its peak
+value. You can work out the time (the number of smoothing periods) that a
+client is subjected to counter-measures after an over-limit burst with this
+formula:

 .code
 .code

-ln(peakrate/maxrate)
+        ln(peakrate/maxrate)

 .endd
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the
 .endd
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the


@@ -28174,7 +28132,7 @@ 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 the &%acl_not_smtp%& ACL in
 the case of a non-SMTP message. However, a MIME ACL is called only if the
 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 &new(&'Content-Type:'&) header line. When a call to a MIME
+message contains a &'Content-Type:'& 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.
 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.