ACL: patterns for remove_headers. Bug 2985

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 1708430ae30ab73771ea75a8f7ef0b1b68e07836..08a197bd707c4dd0fa002fbb5ed23b6964395155 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -3272,6 +3272,12 @@ to the standard output. It is restricted to admin users, unless
 &%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
@@ -3281,6 +3287,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 -bpri
+This option is a combination of &%-bpr%& and &%-bpi%&.
+
 .cmdopt -bpru
 This option is a combination of &%-bpr%& and &%-bpu%&.
 
@@ -10486,6 +10495,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).
 
+.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.
@@ -11060,6 +11074,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"
@@ -32102,8 +32134,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
-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
@@ -32112,14 +32160,14 @@ warn   hosts           = +internal_hosts
 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
-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.
@@ -42212,8 +42260,9 @@ Example usage:
   # one, plus the max_rcpt and return_path options
   remote_forwarded_smtp:
     driver =              smtp
-    # modify the envelope from, for mails that we forward
+    # single-recipient so that $original_domain is valid
     max_rcpt =            1
+    # modify the envelope from, for mails that we forward
     return_path =         ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
 .endd