Docs: indexing of retry final-cutoff

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index c84c9b4d119804dbbf898e6d3460c5431259277c..2363e7880fe198dd9ab2e2fec1d25038183a9f74 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -10032,7 +10032,7 @@ expansion items.
 
 .vitem &*$rheader_*&<&'header&~name'&>&*:*&&~or&~&*$rh_*&<&'header&~name'&>&*:*&
 This item inserts &"raw"& header lines. It is described with the &%header%&
-expansion item above.
+expansion item in section &<<SECTexpansionitems>>& above.
 
 .vitem "&*${run{*&<&'command'&>&*&~*&<&'args'&>&*}{*&<&'string1'&>&*}&&&
         {*&<&'string2'&>&*}}*&"
@@ -11991,6 +11991,7 @@ This is not strictly an expansion variable. It is expansion syntax for
 inserting the message header line with the given name. Note that the name must
 be terminated by colon or white space, because it may contain a wide variety of
 characters. Note also that braces must &'not'& be used.
+See the full description in section &<<SECTexpansionitems>>& above.
 
 .vitem &$headers_added$&
 .vindex "&$headers_added$&"
@@ -24111,6 +24112,8 @@ DKIM signing options.  For details see section &<<SECDKIMSIGN>>&.
 
 
 .option delay_after_cutoff smtp boolean true
+.cindex "final cutoff" "retries, controlling"
+.cindex retry "final cutoff"
 This option controls what happens when all remote IP addresses for a given
 domain have been inaccessible for so long that they have passed their retry
 cutoff times.
@@ -24569,10 +24572,17 @@ variable that contains an outgoing port.
 
 If the value of this option begins with a digit it is taken as a port number;
 otherwise it is looked up using &[getservbyname()]&. The default value is
-normally &"smtp"&, but if &%protocol%& is set to &"lmtp"&, the default is
-&"lmtp"&. If the expansion fails, or if a port number cannot be found, delivery
+normally &"smtp"&,
+but if &%protocol%& is set to &"lmtp"& the default is &"lmtp"&
+and if &%protocol%& is set to &"smtps"& the default is &"smtps"&.
+If the expansion fails, or if a port number cannot be found, delivery
 is deferred.
 
+.new
+Note that at least one Linux distribution has been seen failing
+to put &"smtps"& in its &"/etc/services"& file, resulting is such deferrals.
+.wen
+
 
 
 .option protocol smtp string smtp
@@ -24589,7 +24599,11 @@ over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
 If this option is set to &"smtps"&, the default value for the &%port%& option
 changes to &"smtps"&, and the transport initiates TLS immediately after
 connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade.
-The Internet standards bodies strongly discourage use of this mode.
+.new
+The Internet standards bodies used to strongly discourage use of this mode,
+but as of RFC 8314 it is perferred over STARTTLS for message submission
+(as distinct from MTA-MTA communication).
+.wen
 
 
 .option retry_include_ip_address smtp boolean&!! true
@@ -25855,10 +25869,13 @@ For local deliveries, one delivery attempt is always made for any subsequent
 messages. If this delivery fails, the address fails immediately. The
 post-cutoff retry time is not used.
 
+.cindex "final cutoff" "retries, controlling"
+.cindex retry "final cutoff"
 If the delivery is remote, there are two possibilities, controlled by the
 .oindex "&%delay_after_cutoff%&"
 &%delay_after_cutoff%& option of the &(smtp)& transport. The option is true by
-default. Until the post-cutoff retry time for one of the IP addresses is
+default. Until the post-cutoff retry time for one of the IP addresses,
+as set by the &%retry_data_expire%& option, is
 reached, the failing email address is bounced immediately, without a delivery
 attempt taking place. After that time, one new delivery attempt is made to
 those IP addresses that are past their retry times, and if that still fails,
@@ -36965,6 +36982,7 @@ immediately after the time and date.
 &%pipelining%&: A field is added to delivery and accept
 log lines when the ESMTP PIPELINING extension was used.
 The field is a single "L".
+
 On accept lines, where PIPELINING was offered but not used by the client,
 the field has a minus appended.
 .next