Add macro support to -be expansion test mode. Bug 1623

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 4a8e1d06e39b4f5945d6e23bd634c13984fd729f..13fcad7244359f9ac7be40b59b0d87be08527688 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -2791,6 +2791,13 @@ files or databases you are using, you must exit and restart Exim before trying
 the same lookup again. Otherwise, because each Exim process caches the results
 of lookups, you will just get the same result as before.
 
 the same lookup again. Otherwise, because each Exim process caches the results
 of lookups, you will just get the same result as before.
 

+.new
+Macro processing is done on lines before string-expansion: new macros can be
+defined and macros will be expanded.
+Because macros in the config file are often used for secrets, those are only
+available to admin users.
+.wen
+

 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"
 .vitem &%-bem%&&~<&'filename'&>
 .oindex "&%-bem%&"
 .cindex "testing" "string expansion"


@@ -9967,7 +9974,7 @@ a regular expression, and a substitution string. For example:
 ${sg{abcdefabcdef}{abc}{xyz}}
 .endd
 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,
 ${sg{abcdefabcdef}{abc}{xyz}}
 .endd
 yields &"xyzdefxyzdef"&. Because all three arguments are expanded before use,

-if any $ or \ characters are required in the regular expression or in the
+if any $, } or \ characters are required in the regular expression or in the

 substitution string, they have to be escaped. For example:
 .code
 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}
 substitution string, they have to be escaped. For example:
 .code
 ${sg{abcdef}{^(...)(...)\$}{\$2\$1}}


@@ -10118,7 +10125,15 @@ character. For example:
 .code
 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
 .endd
 .code
 ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)}
 .endd

-expands to &`ceo@up.stairs&&sec@base.ment`&. Compare the &*address*& (singular)
+expands to &`ceo@up.stairs&&sec@base.ment`&. The string is expanded
+first, so if the expanded string starts with >, it may change the output
+separator unintentionally. This can be avoided by setting the output
+separator explicitly:
+.code
+${addresses:>:$h_from:}
+.endd
+
+Compare the &*address*& (singular)

 expansion item, which extracts the working address from a single RFC2822
 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
 processing lists.
 expansion item, which extracts the working address from a single RFC2822
 address. See the &*filter*&, &*map*&, and &*reduce*& items for ways of
 processing lists.


@@ -23798,7 +23813,7 @@ of the message. Its value must not be zero. See also &%final_timeout%&.
 .option dkim_private_key smtp string&!! unset
 .option dkim_canon smtp string&!! unset
 .option dkim_strict smtp string&!! unset
 .option dkim_private_key smtp string&!! unset
 .option dkim_canon smtp string&!! unset
 .option dkim_strict smtp string&!! unset

-.option dkim_sign_headers smtp string&!! unset
+.option dkim_sign_headers smtp string&!! "per RFC"

 .option dkim_hash smtp string&!! sha256
 .option dkim_identity smtp string&!! unset
 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 .option dkim_hash smtp string&!! sha256
 .option dkim_identity smtp string&!! unset
 DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.


@@ -24139,7 +24154,7 @@ This option provides a list of servers to which, provided they announce
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjunction with a transport filter.
 

-.option hosts_try_fastopen smtp "host list!!" unset
+.option hosts_try_fastopen smtp "host list&!!" unset

 .cindex "fast open, TCP" "enabling, in client"
 .cindex "TCP Fast Open" "enabling, in client"
 .cindex "RFC 7413" "TCP Fast Open"
 .cindex "fast open, TCP" "enabling, in client"
 .cindex "TCP Fast Open" "enabling, in client"
 .cindex "RFC 7413" "TCP Fast Open"


@@ -24155,6 +24170,9 @@ as the initiator must present a cookie in the SYN segment.
 
 On (at least some) current Linux distributions the facility must be enabled
 in the kernel by the sysadmin before the support is usable.
 
 On (at least some) current Linux distributions the facility must be enabled
 in the kernel by the sysadmin before the support is usable.

+There is no option for control of the server side; if the system supports
+it it is always enebled.  Note that legthy operations in the connect ACL,
+such as DNSBL lookups, will still delay the emission of the SMTP banner.

 
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"
 
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"


@@ -38580,11 +38598,17 @@ either "1" or "true", Exim will defer. Otherwise Exim will send the message
 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 
 unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
 variables here.
 

-.option dkim_sign_headers smtp string&!! unset
-If set, this option must expand to (or be specified as) a colon-separated
-list of header names. Headers with these names will be included in the message
-signature.
-When unspecified, the header names recommended in RFC4871 will be used.
+.option dkim_sign_headers smtp string&!! "see below"
+If set, this option must expand to a colon-separated
+list of header names.
+.new
+Headers with these names, or the absence or such a header, will be included
+in the message signature.
+When unspecified, the header names listed in RFC4871 will be used,
+whether or not each header is present in the message.
+The default list is available for the expansion in the macro
+"_DKIM_SIGN_HEADERS".
+.wen

 
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"
 
 
 .section "Verifying DKIM signatures in incoming mail" "SECID514"