Docs: update description of Sieve filter facilities

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 1367cc6f2eb4ad4e5ef25c784db3e0490475d095..9eb0b6b564eb3be5fe396b880b4be4453114dc54 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -444,10 +444,11 @@ Please do not ask for configuration help in the bug-tracker.
 The following Exim mailing lists exist:
 
 .table2 140pt
 The following Exim mailing lists exist:
 
 .table2 140pt

-.row &'exim-announce@exim.org'&   "Moderated, low volume announcements list"
-.row &'exim-users@exim.org'&      "General discussion list"
-.row &'exim-dev@exim.org'&        "Discussion of bugs, enhancements, etc."
-.row &'exim-cvs@exim.org'&        "Automated commit messages from the VCS"
+.row &'exim-announce@lists.exim.org'&   "Moderated, low volume announcements list"
+.row &'exim-users@lists.exim.org'&      "General discussion list"
+.row &'exim-users-de@lists.exim.org'&   "General discussion list in German language"
+.row &'exim-dev@lists.exim.org'&        "Discussion of bugs, enhancements, etc."
+.row &'exim-cvs@lists.exim.org'&        "Automated commit messages from the VCS"

 .endtable
 
 You can subscribe to these lists, change your existing subscriptions, and view
 .endtable
 
 You can subscribe to these lists, change your existing subscriptions, and view


@@ -952,7 +953,7 @@ User filters are run as part of the routing process, described below.
 .cindex "exim_msgdate"
 Every message handled by Exim is given a &'message id'& which is sixteen
 characters long. It is divided into three parts, separated by hyphens, for
 .cindex "exim_msgdate"
 Every message handled by Exim is given a &'message id'& which is sixteen
 characters long. It is divided into three parts, separated by hyphens, for

-example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits,
+example &`16VDhn-000000001bo-D342`&. Each part is a sequence of letters and digits,

 normally encoding numbers in base 62. However, in the Darwin operating
 system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
 (avoiding the use of lower case letters) is used instead, because the message
 normally encoding numbers in base 62. However, in the Darwin operating
 system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
 (avoiding the use of lower case letters) is used instead, because the message


@@ -973,21 +974,29 @@ started to be received, to a granularity of one second. That is, this field
 contains the number of seconds since the start of the epoch (the normal Unix
 way of representing the date and time of day).
 .next
 contains the number of seconds since the start of the epoch (the normal Unix
 way of representing the date and time of day).
 .next

-After the first hyphen, the next six characters are the id of the process that
-received the message.
+After the first hyphen, the next
+.new
+eleven
+.wen
+characters are the id of the process that received the message.

 .next
 .next

-There are two different possibilities for the final two characters:
+.new
+There are two different possibilities for the final four characters:

 .olist
 .oindex "&%localhost_number%&"
 If &%localhost_number%& is not set, this value is the fractional part of the
 .olist
 .oindex "&%localhost_number%&"
 If &%localhost_number%& is not set, this value is the fractional part of the

-time of reception, normally in units of 1/2000 of a second, but for systems
+time of reception, normally in units of
+microseconds.
+but for systems

 that must use base 36 instead of base 62 (because of case-insensitive file
 that must use base 36 instead of base 62 (because of case-insensitive file

-systems), the units are 1/1000 of a second.
+systems), the units are
+2 us.

 .next
 .next

-If &%localhost_number%& is set, it is multiplied by 200 (100) and added to
-the fractional part of the time, which in this case is in units of 1/200
-(1/100) of a second.
+If &%localhost_number%& is set, it is multiplied by
+500000 (250000) and added to
+the fractional part of the time, which in this case is in units of 2 us (4 us).

 .endlist
 .endlist

+.wen

 .endlist
 
 After a message has been received, Exim waits for the clock to tick at the
 .endlist
 
 After a message has been received, Exim waits for the clock to tick at the


@@ -3272,6 +3281,12 @@ to the standard output. It is restricted to admin users, unless
 &%queue_list_requires_admin%& is set false.
 
 
 &%queue_list_requires_admin%& is set false.
 
 

+.cmdopt -bpi
+.cindex queue "list of message IDs"
+This option operates like &%-bp%&, but only outputs message ids
+(one per line).
+
+

 .cmdopt -bpr
 This option operates like &%-bp%&, but the output is not sorted into
 chronological order of message arrival. This can speed it up when there are
 .cmdopt -bpr
 This option operates like &%-bp%&, but the output is not sorted into
 chronological order of message arrival. This can speed it up when there are


@@ -3281,6 +3296,9 @@ going to be post-processed in a way that doesn't need the sorting.
 .cmdopt -bpra
 This option is a combination of &%-bpr%& and &%-bpa%&.
 
 .cmdopt -bpra
 This option is a combination of &%-bpr%& and &%-bpa%&.
 

+.cmdopt -bpri
+This option is a combination of &%-bpr%& and &%-bpi%&.
+

 .cmdopt -bpru
 This option is a combination of &%-bpr%& and &%-bpu%&.
 
 .cmdopt -bpru
 This option is a combination of &%-bpr%& and &%-bpu%&.
 


@@ -6714,6 +6732,12 @@ version of the lookup key.
 The &'query-style'& type accepts a generalized database query. No particular
 key value is assumed by Exim for query-style lookups. You can use whichever
 Exim variables you need to construct the database query.
 The &'query-style'& type accepts a generalized database query. No particular
 key value is assumed by Exim for query-style lookups. You can use whichever
 Exim variables you need to construct the database query.

+
+For the string-expansion kind of lookups, the query is given in the first
+bracketed argument of the &${lookup ...}$& expansion.
+For the list-argument kind of lookup the quury is given by the remainder of the
+list item after the first semicolon.
+

 .cindex "tainted data" "quoting for lookups"
 If tainted data is used in the query then it should be quuted by
 using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
 .cindex "tainted data" "quoting for lookups"
 If tainted data is used in the query then it should be quuted by
 using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator


@@ -9953,7 +9977,7 @@ leading and trailing quotes are removed from the returned value.
 After expansion, <&'string'&> is interpreted as a list, colon-separated by
 default, but the separator can be changed in the usual way (&<<SECTlistsepchange>>&).
 For each item
 After expansion, <&'string'&> is interpreted as a list, colon-separated by
 default, but the separator can be changed in the usual way (&<<SECTlistsepchange>>&).
 For each item

-in this list, its value is place in &$item$&, and then the condition is
+in this list, its value is placed in &$item$&, and then the condition is

 evaluated.
 .new
 Any modification of &$value$& by this evaluation is discarded.
 evaluated.
 .new
 Any modification of &$value$& by this evaluation is discarded.


@@ -10486,6 +10510,11 @@ Defines whether or not a write-shutdown is done on the connection after
 sending the request. Values are &"yes"& (the default) or &"no"&
 (preferred, eg. by some webservers).
 
 sending the request. Values are &"yes"& (the default) or &"no"&
 (preferred, eg. by some webservers).
 

+.next
+&*sni*&
+Controls the use of Server Name Identification on the connection.
+Any nonempty value will be the SNI sent; TLS will be forced.
+

 .next
 &*tls*&
 Controls the use of TLS on the connection.
 .next
 &*tls*&
 Controls the use of TLS on the connection.


@@ -10573,12 +10602,13 @@ expansion items.
 This item inserts &"raw"& header lines. It is described with the &%header%&
 expansion item in section &<<SECTexpansionitems>>& above.
 
 This item inserts &"raw"& header lines. It is described with the &%header%&
 expansion item in section &<<SECTexpansionitems>>& above.
 

-.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
+.vitem "&*${run<&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&

         {*&<&'string2'&>&*}}*&"
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
 This item runs an external command, as a subprocess.
         {*&<&'string2'&>&*}}*&"
 .cindex "expansion" "running a command"
 .cindex "&%run%& expansion item"
 This item runs an external command, as a subprocess.

-One option is supported after the word &'run'&, comma-separated.
+One option is supported after the word &'run'&, comma-separated
+and without whitespace.

 
 If the option &'preexpand'& is not used,
 the command string is split into individual arguments by spaces
 
 If the option &'preexpand'& is not used,
 the command string is split into individual arguments by spaces


@@ -11060,6 +11090,24 @@ abbreviation &%h%& can be used when &%hash%& is used as an operator.
 
 
 
 
 
 

+.new
+.vitem &*${headerwrap_*&<&'cols'&>&*_*&<&'limit'&>&*:*&<&'string'&>&*}*&
+.cindex header "wrapping operator"
+.cindex expansion "header wrapping"
+This operator line-wraps its argument in a way useful for headers.
+The &'cols'& value gives the column number to wrap after,
+the &'limit'& gives a limit number of result characters to truncate at.
+Either just the &'limit'& and the preceding underbar, or both, can be omitted;
+the defaults are 80 and 998.
+Wrapping will be inserted at a space if possible before the
+column number is reached.
+Whitespace at a chosen wrap point is removed.
+A line-wrap consists of a newline followed by a tab,
+and the tab is counted as 8 columns.
+.wen
+
+
+

 .vitem &*${hex2b64:*&<&'hexstring'&>&*}*&
 .cindex "base64 encoding" "conversion from hex"
 .cindex "expansion" "hex to base64"
 .vitem &*${hex2b64:*&<&'hexstring'&>&*}*&
 .cindex "base64 encoding" "conversion from hex"
 .cindex "expansion" "hex to base64"


@@ -13418,7 +13466,8 @@ This is an obsolete name for &$bounce_return_size_limit$&.
 .cindex "router" "name"
 .cindex "name" "of router"
 .vindex "&$router_name$&"
 .cindex "router" "name"
 .cindex "name" "of router"
 .vindex "&$router_name$&"

-During the running of a router this variable contains its name.
+During the running of a router, or a transport called,
+this variable contains the router name.

 
 .vitem &$runrc$&
 .cindex "return code" "from &%run%& expansion"
 
 .vitem &$runrc$&
 .cindex "return code" "from &%run%& expansion"


@@ -13709,6 +13758,11 @@ there actually are, because many other connections may come and go while a
 single connection is being processed. When a child process terminates, the
 daemon decrements its copy of the variable.
 
 single connection is being processed. When a child process terminates, the
 daemon decrements its copy of the variable.
 

+.vitem &$smtp_notquit_reason$&
+.vindex "&$smtp_notquit_reason$&"
+When the not-QUIT ACL is running, this variable is set to a string
+that indicates the reason for the termination of the SMTP connection.
+

 .vitem "&$sn0$& &-- &$sn9$&"
 These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators
 that were current at the end of the system filter file. This allows a system
 .vitem "&$sn0$& &-- &$sn9$&"
 These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators
 that were current at the end of the system filter file. This allows a system


@@ -16005,6 +16059,7 @@ search the file multiple times for non-existent users, and also cause delay.
 
 .option freeze_tell main "string list, comma separated" unset
 .cindex "freezing messages" "sending a message when freezing"
 
 .option freeze_tell main "string list, comma separated" unset
 .cindex "freezing messages" "sending a message when freezing"

+.cindex "frozen messages" "sending a message when freezing"

 On encountering certain errors, or when configured to do so in a system filter,
 ACL, or special router, Exim freezes a message. This means that no further
 delivery attempts take place until an administrator thaws the message, or the
 On encountering certain errors, or when configured to do so in a system filter,
 ACL, or special router, Exim freezes a message. This means that no further
 delivery attempts take place until an administrator thaws the message, or the


@@ -22812,7 +22867,17 @@ example:
 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
 .endd
 This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and
 transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
 .endd
 This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and

-&(/bin/cmd2)& otherwise. If double quotes had been used, they would have been
+&(/bin/cmd2)& otherwise.
+
+Option strings in general have any fully-surrounding double quote wrapping
+removed early in parsing (see &<<SECTstrings>>&).
+Then, for this option, quotes protect against whitespace being
+regarded as a separator while splitting into the command argument vector.
+Either double or single quotes can be used here;
+the former interprets backlash-quoted charachters
+and the latter does not.
+
+If double quotes had been used in this example, they would have been

 stripped by Exim when it read the option's value. When the value is used, if
 the single quotes were missing, the line would be split into two items,
 &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when
 stripped by Exim when it read the option's value. When the value is used, if
 the single quotes were missing, the line would be split into two items,
 &`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when


@@ -26117,7 +26182,8 @@ This option give a list of hosts for which,
 while verifying the server certificate,
 checks will be included on the host name
 (note that this will generally be the result of a DNS MX lookup)
 while verifying the server certificate,
 checks will be included on the host name
 (note that this will generally be the result of a DNS MX lookup)

-versus Subject and Subject-Alternate-Name fields.  Wildcard names are permitted
+versus the Subject-Alternate-Name (or, if none, Subject-Name) fields.
+Wildcard names are permitted,

 limited to being the initial component of a 3-or-more component FQDN.
 
 There is no equivalent checking on client certificates.
 limited to being the initial component of a 3-or-more component FQDN.
 
 There is no equivalent checking on client certificates.


@@ -28935,9 +29001,10 @@ for which it must have been requested via the
 (see &<<CHAPTLS>>&).
 
 If an authenticator of this type is configured it is
 (see &<<CHAPTLS>>&).
 
 If an authenticator of this type is configured it is

-run before any SMTP-level communication is done,
+run immediately after a TLS connection being negotiated
+(due to either STARTTLS or TLS-on-connect)

 and can authenticate the connection.
 and can authenticate the connection.

-If it does, SMTP authentication is not offered.
+If it does, SMTP authentication is not subsequently offered.

 
 A maximum of one authenticator of this type may be present.
 
 
 A maximum of one authenticator of this type may be present.
 


@@ -31497,8 +31564,11 @@ the message modifier cannot override the 221 response code.
 
 The text in a &%message%& modifier is literal; any quotes are taken as
 literals, but because the string is expanded, backslash escapes are processed
 
 The text in a &%message%& modifier 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
+anyway.
+If the message contains newlines, this gives rise to a multi-line SMTP

 response.
 response.

+A long message line will also be split into multi-line SMTP responses,
+on word boundaries if possible.

 
 .vindex "&$acl_verify_message$&"
 While the text is being expanded, the &$acl_verify_message$& variable
 
 .vindex "&$acl_verify_message$&"
 While the text is being expanded, the &$acl_verify_message$& variable


@@ -31792,6 +31862,7 @@ work with.
 .vitem &*control&~=&~fakedefer/*&<&'message'&>
 .cindex "fake defer"
 .cindex "defer, fake"
 .vitem &*control&~=&~fakedefer/*&<&'message'&>
 .cindex "fake defer"
 .cindex "defer, fake"

+.cindex fakedefer

 This control works in exactly the same way as &%fakereject%& (described below)
 except that it causes an SMTP 450 response after the message data instead of a
 550 response. You must take care when using &%fakedefer%& because it causes the
 This control works in exactly the same way as &%fakereject%& (described below)
 except that it causes an SMTP 450 response after the message data instead of a
 550 response. You must take care when using &%fakedefer%& because it causes the


@@ -31801,6 +31872,7 @@ use &%fakedefer%& if the message is to be delivered normally.
 .vitem &*control&~=&~fakereject/*&<&'message'&>
 .cindex "fake rejection"
 .cindex "rejection, fake"
 .vitem &*control&~=&~fakereject/*&<&'message'&>
 .cindex "fake rejection"
 .cindex "rejection, fake"

+.cindex fakereject

 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
 words, only when an SMTP message is being received. If Exim accepts the
 message, instead the final 250 response, a 550 rejection message is sent.
 This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
 words, only when an SMTP message is being received. If Exim accepts the
 message, instead the final 250 response, a 550 rejection message is sent.


@@ -32102,8 +32174,24 @@ Headers will not be removed from the message if the modifier is used in
 DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
 
 More than one header can be removed at the same time by using a colon separated
 DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
 
 More than one header can be removed at the same time by using a colon separated

-list of header names. The header matching is case insensitive. Wildcards are
-not permitted, nor is list expansion performed, so you cannot use hostlists to
+list of header specifiers.
+.new
+If a specifier does not start with a circumflex (^)
+then it is treated as a header name.
+The header name matching is case insensitive.
+If it does, then it is treated as a (front-anchored)
+regular expression applied to the whole header.
+
+&*Note*&: The colon terminating a header name will need to be doubled
+if used in an RE, and there can legitimately be whitepace before it.
+
+Example:
+.code
+remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N
+.endd
+.wen
+
+List expansion is not performed, so you cannot use hostlists to

 create a list of headers, however both connection and message variable expansion
 are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example:
 .code
 create a list of headers, however both connection and message variable expansion
 are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example:
 .code


@@ -32112,14 +32200,14 @@ warn   hosts           = +internal_hosts
 warn   message         = Remove internal headers
        remove_header   = $acl_c_ihdrs
 .endd
 warn   message         = Remove internal headers
        remove_header   = $acl_c_ihdrs
 .endd

-Header names for removal are accumulated during the MAIL, RCPT, and predata ACLs.
+Header specifiers for removal are accumulated during the MAIL, RCPT, and predata ACLs.

 Matching header lines are removed from the message before processing the DATA and MIME ACLs.
 If multiple header lines match, all are removed.
 There is no harm in attempting to remove the same header twice nor in removing
 Matching header lines are removed from the message before processing the DATA and MIME ACLs.
 If multiple header lines match, all are removed.
 There is no harm in attempting to remove the same header twice nor in removing

-a non-existent header. Further header lines to be removed may be accumulated
-during the DATA and MIME ACLs, after which they are removed from the message,
-if present. In the case of non-SMTP messages, headers to be removed are
-accumulated during the non-SMTP ACLs, and are removed from the message after
+a non-existent header. Further header specifiers for removal may be accumulated
+during the DATA and MIME ACLs, after which matching headers are removed
+if present. In the case of non-SMTP messages, remove speifiers are
+accumulated during the non-SMTP ACLs, and are acted on after

 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
 ACL, there really is no effect because there is no logging of what headers
 would have been removed.
 all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
 ACL, there really is no effect because there is no logging of what headers
 would have been removed.


@@ -38951,7 +39039,7 @@ logging and the message has a DKIM signature header.
 .section "Reducing or increasing what is logged" "SECTlogselector"
 .cindex "log" "selectors"
 By setting the &%log_selector%& global option, you can disable some of Exim's
 .section "Reducing or increasing what is logged" "SECTlogselector"
 .cindex "log" "selectors"
 By setting the &%log_selector%& global option, you can disable some of Exim's

-default logging, or you can request additional logging. The value of
+default logging to the main log, or you can request additional logging. The value of

 &%log_selector%& is made up of names preceded by plus or minus characters. For
 example:
 .code
 &%log_selector%& is made up of names preceded by plus or minus characters. For
 example:
 .code