Cutthrough: option to use transport-defined mailfrom. Bug 3071

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 1938842274586d3896df4157f4fb58f7a266b3fa..1cf4562d2ac2aec13e726ab1b868041b0e7bb09e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1401,7 +1401,8 @@ check an address given in the SMTP EXPN command (see the &%expn%& option).
 If the &%domains%& option is set, the domain of the address must be in the set
 of domains that it defines.
 .cindex "tainted data" "de-tainting"
 If the &%domains%& option is set, the domain of the address must be in the set
 of domains that it defines.
 .cindex "tainted data" "de-tainting"

-.cindex "de-tainting" "using router domains option"
+.cindex de-tainting "using router domains option"
+.cindex de-tainting &$domains$&

 A match verifies the variable &$domain$& (which carries tainted data)
 and assigns an untainted value to the &$domain_data$& variable.
 Such an untainted value is often needed in the transport.
 A match verifies the variable &$domain$& (which carries tainted data)
 and assigns an untainted value to the &$domain_data$& variable.
 Such an untainted value is often needed in the transport.


@@ -1421,6 +1422,7 @@ rather than the generic &%condition%& option.
 If the &%local_parts%& option is set, the local part of the address must be in
 the set of local parts that it defines.
 A match verifies the variable &$local_part$& (which carries tainted data)
 If the &%local_parts%& option is set, the local part of the address must be in
 the set of local parts that it defines.
 A match verifies the variable &$local_part$& (which carries tainted data)

+.cindex de-tainting &$local_parts$&

 and assigns an untainted value to the &$local_part_data$& variable.
 Such an untainted value is often needed in the transport.
 For specifics of the matching operation and the resulting untainted value,
 and assigns an untainted value to the &$local_part_data$& variable.
 Such an untainted value is often needed in the transport.
 For specifics of the matching operation and the resulting untainted value,


@@ -5216,7 +5218,7 @@ This can then be used in a &(redirect)& router setting like this:
 data = ${lookup mysql{ALIAS_QUERY}}
 .endd
 In earlier versions of Exim macros were sometimes used for domain, host, or
 data = ${lookup mysql{ALIAS_QUERY}}
 .endd
 In earlier versions of Exim macros were sometimes used for domain, host, or

-address lists. In Exim 4 these are handled better by named lists &-- see
+address lists. In Exim version 4 these are handled better by named lists &-- see

 section &<<SECTnamedlists>>&.
 
 
 section &<<SECTnamedlists>>&.
 
 


@@ -9259,6 +9261,8 @@ does not match the list. This may not always be what you want to happen.
 To change Exim's behaviour, the special items &`+include_unknown`& or
 &`+ignore_unknown`& may appear in the list (at top level &-- they are
 not recognized in an indirected file).
 To change Exim's behaviour, the special items &`+include_unknown`& or
 &`+ignore_unknown`& may appear in the list (at top level &-- they are
 not recognized in an indirected file).

+The effects of these special items do not propagate into referenced
+named lists.

 
 .ilist
 If any item that follows &`+include_unknown`& requires information that
 
 .ilist
 If any item that follows &`+include_unknown`& requires information that


@@ -9625,6 +9629,7 @@ longer case-independent. This does not affect the domain, which remains in
 lower case. However, although independent matches on the domain alone are still
 performed caselessly, regular expressions that match against an entire address
 become case-sensitive after &"+caseful"& has been seen.
 lower case. However, although independent matches on the domain alone are still
 performed caselessly, regular expressions that match against an entire address
 become case-sensitive after &"+caseful"& has been seen.

+The effects of &"+caseful"& propagate into any referenced named lists.

 
 .new
 This string may not be tainted.
 
 .new
 This string may not be tainted.


@@ -15990,8 +15995,8 @@ See section &<<SECDKIMVFY>>&.
 
 
 .options dmarc_forensic_sender main string&!! unset &&&
 
 
 .options dmarc_forensic_sender main string&!! unset &&&

-         dmarc_history_file main string unset &&&
-         dmarc_tld_file main string unset
+         dmarc_history_file main string&!! unset &&&
+         dmarc_tld_file main string&!! unset

 .cindex DMARC "main section options"
 These options control DMARC processing.
 See section &<<SECDMARC>>& for details.
 .cindex DMARC "main section options"
 These options control DMARC processing.
 See section &<<SECDMARC>>& for details.


@@ -19478,11 +19483,15 @@ This applies to all of the SRV, MX, AAAA, A lookup sequence.
 .option domains routers&!? "domain list&!!" unset
 .cindex "router" "restricting to specific domains"
 .vindex "&$domain_data$&"
 .option domains routers&!? "domain list&!!" unset
 .cindex "router" "restricting to specific domains"
 .vindex "&$domain_data$&"

-If this option is set, the router is skipped unless the current domain matches
-the list.
+If this option is set,
+the argument is first expanded to give a list.
+The router is skipped unless the current domain matches the list.

 The data returned by the list check
 is placed in &$domain_data$& for use in string
 expansions of the driver's private options and in the transport.
 The data returned by the list check
 is placed in &$domain_data$& for use in string
 expansions of the driver's private options and in the transport.

+If the result of expansion is empty or a forced-fail,
+the router is skipped.
+

 See section &<<SECTrouprecon>>& for
 a list of the order in which preconditions are evaluated.
 
 See section &<<SECTrouprecon>>& for
 a list of the order in which preconditions are evaluated.
 


@@ -19852,7 +19861,11 @@ See &%local_part_suffix%& above.
 .option local_parts routers&!? "local part list&!!" unset
 .cindex "router" "restricting to specific local parts"
 .cindex "local part" "checking in router"
 .option local_parts routers&!? "local part list&!!" unset
 .cindex "router" "restricting to specific local parts"
 .cindex "local part" "checking in router"

+If this option is set, the argument is first expanded to give a list.

 The router is run only if the local part of the address matches the list.
 The router is run only if the local part of the address matches the list.

+If the result of expansion is empty or a forced-fail,
+the router is skipped.
+

 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
 are evaluated, and
 section &<<SECTlocparlis>>& for a discussion of local part lists. Because the
 See section &<<SECTrouprecon>>& for a list of the order in which preconditions
 are evaluated, and
 section &<<SECTlocparlis>>& for a discussion of local part lists. Because the


@@ -19862,7 +19875,7 @@ example:
 local_parts = dbm;/usr/local/specials/$domain_data
 .endd
 .vindex "&$local_part_data$&"
 local_parts = dbm;/usr/local/specials/$domain_data
 .endd
 .vindex "&$local_part_data$&"

-the data returned by the list check
+The data returned by the list check

 for the local part is placed in the variable &$local_part_data$& for use in
 expansions of the router's private options or in the transport.
 You might use this option, for
 for the local part is placed in the variable &$local_part_data$& for use in
 expansions of the router's private options or in the transport.
 You might use this option, for


@@ -32193,16 +32206,16 @@ is what is wanted for subsequent tests.
 .vitem &*control&~=&~cutthrough_delivery/*&<&'options'&>
 .cindex "&ACL;" "cutthrough routing"
 .cindex "cutthrough" "requesting"
 .vitem &*control&~=&~cutthrough_delivery/*&<&'options'&>
 .cindex "&ACL;" "cutthrough routing"
 .cindex "cutthrough" "requesting"

-This option requests delivery be attempted while the item is being received.
+This control requests delivery be attempted while the item is being received.

 
 

-The option is usable in the RCPT ACL.
+The control is usable in the RCPT ACL.

 If enabled for a message received via smtp and routed to an smtp transport,
 and only one transport, interface, destination host and port combination
 is used for all recipients of the message,
 then the delivery connection is made while the receiving connection is open
 and data is copied from one to the other.
 
 If enabled for a message received via smtp and routed to an smtp transport,
 and only one transport, interface, destination host and port combination
 is used for all recipients of the message,
 then the delivery connection is made while the receiving connection is open
 and data is copied from one to the other.
 

-An attempt to set this option for any recipient but the first
+An attempt to set this control for any recipient but the first

 for a mail will be quietly ignored.
 If a recipient-verify callout
 (with use_sender)
 for a mail will be quietly ignored.
 If a recipient-verify callout
 (with use_sender)


@@ -32229,9 +32242,8 @@ message body.
 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.
 Cutthrough delivery is not supported via transport-filters or when DKIM signing
 of outgoing messages is done, because it sends data to the ultimate destination
 before the entire message has been received from the source.

-It is not supported for messages received with the SMTP PRDR
-or CHUNKING
-options in use.
+It is not supported for messages received with the SMTP PRDR or CHUNKING
+modes in use.

 
 Should the ultimate destination system positively accept or reject the mail,
 a corresponding indication is given to the source system and nothing is queued.
 
 Should the ultimate destination system positively accept or reject the mail,
 a corresponding indication is given to the source system and nothing is queued.


@@ -32239,18 +32251,32 @@ If the item is successfully delivered in cutthrough mode
 the delivery log lines are tagged with ">>" rather than "=>" and appear
 before the acceptance "<=" line.
 
 the delivery log lines are tagged with ">>" rather than "=>" and appear
 before the acceptance "<=" line.
 

-If there is a temporary error the item is queued for later delivery in the
-usual fashion.
-This behaviour can be adjusted by appending the option &*defer=*&<&'value'&>
-to the control; the default value is &"spool"& and the alternate value
-&"pass"& copies an SMTP defer response from the target back to the initiator
-and does not queue the message.
-Note that this is independent of any recipient verify conditions in the ACL.
-

 Delivery in this mode avoids the generation of a bounce mail to a
 (possibly faked)
 sender when the destination system is doing content-scan based rejection.
 
 Delivery in this mode avoids the generation of a bounce mail to a
 (possibly faked)
 sender when the destination system is doing content-scan based rejection.
 

+.new
+Options for this control may be appended, separated by slash (&"/"&)
+characters.
+There are two possible options,
+both taking a value string prefixed by an equals (&"="&) character.
+
+The &*defer*& option controls the result of a temporary error
+of the cutthrough delivery.
+The default value &"spool"& queues the message in the normal way
+for later processing.
+A value of &"pass"& copies an SMTP defer response back to the initiator
+and does not queue the message.
+Note that this is independent of any recipient verify conditions in the ACL.
+
+The &*sender*& option controls the envelope-from used for the
+outbound connection.
+The default value of &"orig"& uses the address given for envelope-from
+in the inbound (originating) connection.
+A value of &"transport"& permits the transport used for the outbound
+connection to modify the envelope-from, via its &*return_path*& option.
+.wen
+

 
 .vitem &*control&~=&~debug/*&<&'options'&>
 .cindex "&ACL;" "enabling debug logging"
 
 .vitem &*control&~=&~debug/*&<&'options'&>
 .cindex "&ACL;" "enabling debug logging"


@@ -38188,7 +38214,7 @@ see chapter &<<CHID9>>&.
 .subsection "ODMR customer connection" SECTODMRCUST
 .cindex ODMR customer
 Exim supports the &"customer"& side of ODMR,
 .subsection "ODMR customer connection" SECTODMRCUST
 .cindex ODMR customer
 Exim supports the &"customer"& side of ODMR,

-with a command-line option &"-atrn"&& that requests a connection
+with a command-line option &"-atrn"& that requests a connection

 to a given host, issuance of an ATRN command then operation
 in SMTP server mode.
 The option must be followed by two arguments.
 to a given host, issuance of an ATRN command then operation
 in SMTP server mode.
 The option must be followed by two arguments.


@@ -38200,7 +38226,7 @@ of domains for which mail is to be requested.
 Interpretation of the list is up to the provider;
 an empty list is expected to result in some default being returned.
 
 Interpretation of the list is up to the provider;
 an empty list is expected to result in some default being returned.
 

-The provider host is placed in &$domain$" for routing;
+The provider host is placed in &$domain$& for routing;

 router and transport must be configured suitably to make the connection.
 For example:
 .code
 router and transport must be configured suitably to make the connection.
 For example:
 .code


@@ -43126,10 +43152,13 @@ the most current version can be downloaded
 from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
 See also the util/renew-opendmarc-tlds.sh script.
 The default for the option is unset.
 from a link at &url(https://publicsuffix.org/list/public_suffix_list.dat).
 See also the util/renew-opendmarc-tlds.sh script.
 The default for the option is unset.

-If not set, DMARC processing is disabled.
+.new
+It is expanded before use.
+If not set (or empty after expansion), DMARC processing is disabled.
+.wen

 
 
 
 

-The &%dmarc_history_file%& option, if set
+The &%dmarc_history_file%& option

 .oindex &%dmarc_history_file%&
 defines the location of a file to log results
 of dmarc verification on inbound emails. The
 .oindex &%dmarc_history_file%&
 defines the location of a file to log results
 of dmarc verification on inbound emails. The


@@ -43138,7 +43167,11 @@ which will manage the data, send out DMARC
 reports, and expire the data. Make sure the
 directory of this file is writable by the user
 exim runs as.
 reports, and expire the data. Make sure the
 directory of this file is writable by the user
 exim runs as.

-The default is unset.
+The default for the option is unset.
+.new
+It is expanded before use.
+If not set (or empty after expansion), no history is written.
+.wen

 
 The &%dmarc_forensic_sender%& option
 .oindex &%dmarc_forensic_sender%&
 
 The &%dmarc_forensic_sender%& option
 .oindex &%dmarc_forensic_sender%&