Testsuite: honour the "build" environment variable

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index a6d477680d800d57dfab9cd83095a70fa67112cd..ce64fd405ce3293f73b1612c1c5e7b1c299c8fbc 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -5033,6 +5033,27 @@ address lists. In Exim 4 these are handled better by named lists &-- see
 section &<<SECTnamedlists>>&.
 
 
 section &<<SECTnamedlists>>&.
 
 

+.new
+.section "Builtin macros" "SECTbuiltinmacros"
+Exim defines some macros depending on facilities available, which may
+differ due to build-time definitions and from one release to another.
+All of these macros start with an underscore.
+They can be used to conditionally include parts of a configuration
+(see below).
+
+The following classes of macros are defined:
+.display
+&` _HAVE_                     `&  build-time defines
+&` _DRVR_AUTH_                `&  authenticator drivers
+&` _DRVR_RTR_                 `&  router drivers
+&` _DRVR_TPT_                 `&  transport drivers
+&` _OPT_                      `&  configuration option support
+.endd
+
+Use an &"exim -bP macros"& command to get the list of macros.
+.wen
+
+

 .section "Conditional skips in the configuration file" "SECID46"
 .cindex "configuration file" "conditional skips"
 .cindex "&`.ifdef`&"
 .section "Conditional skips in the configuration file" "SECID46"
 .cindex "configuration file" "conditional skips"
 .cindex "&`.ifdef`&"


@@ -13572,6 +13593,7 @@ listed in more than one group.
 .row &%slow_lookup_log%&             "control logging of slow DNS lookups"
 .row &%syslog_duplication%&          "controls duplicate log lines on syslog"
 .row &%syslog_facility%&             "set syslog &""facility""& field"
 .row &%slow_lookup_log%&             "control logging of slow DNS lookups"
 .row &%syslog_duplication%&          "controls duplicate log lines on syslog"
 .row &%syslog_facility%&             "set syslog &""facility""& field"

+.row &%syslog_pid%&                  "pid in syslog lines"

 .row &%syslog_processname%&          "set syslog &""ident""& field"
 .row &%syslog_timestamp%&            "timestamp syslog lines"
 .row &%write_rejectlog%&             "control use of message log"
 .row &%syslog_processname%&          "set syslog &""ident""& field"
 .row &%syslog_timestamp%&            "timestamp syslog lines"
 .row &%write_rejectlog%&             "control use of message log"


@@ -14438,6 +14460,7 @@ See &%daemon_startup_retries%&.
 .option delay_warning main "time list" 24h
 .cindex "warning of delay"
 .cindex "delay warning, specifying"
 .option delay_warning main "time list" 24h
 .cindex "warning of delay"
 .cindex "delay warning, specifying"

+.cindex "queue" "delay warning"

 When a message is delayed, Exim sends a warning message to the sender at
 intervals specified by this option. The data is a colon-separated list of times
 after which to send warning messages. If the value of the option is an empty
 When a message is delayed, Exim sends a warning message to the sender at
 intervals specified by this option. The data is a colon-separated list of times
 after which to send warning messages. If the value of the option is an empty


@@ -16834,6 +16857,15 @@ If this option is unset, &"mail"& is used. See chapter &<<CHAPlog>>& for
 details of Exim's logging.
 
 
 details of Exim's logging.
 
 

+.option syslog_pid main boolean true
+.cindex "syslog" "pid"
+If &%syslog_pid%& is set false, the PID on Exim's log lines are
+omitted when these lines are sent to syslog. (Syslog normally prefixes
+the log lines with the PID of the logging process automatically.) You need
+to enable the &`+pid`& log selector item, if you want Exim to write it's PID
+into the logs.) See chapter &<<CHAPlog>>& for details of Exim's logging.
+
+

 
 .option syslog_processname main string &`exim`&
 .cindex "syslog" "process name; setting"
 
 .option syslog_processname main string &`exim`&
 .cindex "syslog" "process name; setting"


@@ -17033,7 +17065,15 @@ larger prime than requested.
 The value of this option is expanded and indicates the source of DH parameters
 to be used by Exim.
 
 The value of this option is expanded and indicates the source of DH parameters
 to be used by Exim.
 

-If it is a filename starting with a &`/`&, then it names a file from which DH
+.new
+&*Note: The Exim Maintainers strongly recommend using a filename with site-generated
+local DH parameters*&, which has been supported across all versions of Exim.  The
+other specific constants available are a fallback so that even when
+"unconfigured", Exim can offer Perfect Forward Secrecy in older ciphersuites in TLS.
+.wen
+
+If &%tls_dhparam%& is a filename starting with a &`/`&,
+then it names a file from which DH

 parameters should be loaded.  If the file exists, it should hold a PEM-encoded
 PKCS#3 representation of the DH prime.  If the file does not exist, for
 OpenSSL it is an error.  For GnuTLS, Exim will attempt to create the file and
 parameters should be loaded.  If the file exists, it should hold a PEM-encoded
 PKCS#3 representation of the DH prime.  If the file does not exist, for
 OpenSSL it is an error.  For GnuTLS, Exim will attempt to create the file and


@@ -17049,23 +17089,39 @@ Exim will attempt to load a file from inside the spool directory.  If the file
 does not exist, Exim will attempt to create it.
 See section &<<SECTgnutlsparam>>& for further details.
 
 does not exist, Exim will attempt to create it.
 See section &<<SECTgnutlsparam>>& for further details.
 

+.new

 If Exim is using OpenSSL and this option is empty or unset, then Exim will load
 If Exim is using OpenSSL and this option is empty or unset, then Exim will load

-a default DH prime; the default is the 2048 bit prime described in section
+a default DH prime; the default is Exim-specific but lacks verifiable provenance.
+
+In older versions of Exim the default was the 2048 bit prime described in section

 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which
 in IKE is assigned number 23.
 
 Otherwise, the option must expand to the name used by Exim for any of a number
 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order Subgroup", which
 in IKE is assigned number 23.
 
 Otherwise, the option must expand to the name used by Exim for any of a number

-of DH primes specified in RFC 2409, RFC 3526 and RFC 5114.  As names, Exim uses
-"ike" followed by the number used by IKE, or "default" which corresponds to
-"ike23".
+of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other
+sources.  As names, Exim uses a standard specified name, else "ike" followed by
+the number used by IKE, or "default" which corresponds to
+&`exim.dev.20160529.3`&.

 
 

-The available primes are:
+The available standard primes are:
+&`ffdhe2048`&, &`ffdhe3072`&, &`ffdhe4096`&, &`ffdhe6144`&, &`ffdhe8192`&,

 &`ike1`&, &`ike2`&, &`ike5`&,
 &`ike14`&, &`ike15`&, &`ike16`&, &`ike17`&, &`ike18`&,
 &`ike1`&, &`ike2`&, &`ike5`&,
 &`ike14`&, &`ike15`&, &`ike16`&, &`ike17`&, &`ike18`&,

-&`ike22`&, &`ike23`& (aka &`default`&) and &`ike24`&.
+&`ike22`&, &`ike23`& and &`ike24`&.
+
+The available additional primes are:
+&`exim.dev.20160529.1`&, &`exim.dev.20160529.2`& and &`exim.dev.20160529.3`&.

 
 Some of these will be too small to be accepted by clients.
 Some may be too large to be accepted by clients.
 
 Some of these will be too small to be accepted by clients.
 Some may be too large to be accepted by clients.

+The open cryptographic community has suspicions about the integrity of some
+of the later IKE values, which led into RFC7919 providing new fixed constants
+(the "ffdhe" identifiers).
+
+At this point, all of the "ike" values should be considered obsolete;
+they're still in Exim to avoid breaking unusual configurations, but are
+candidates for removal the next time we have backwards-incompatible changes.
+.wen

 
 The TLS protocol does not negotiate an acceptable size for this; clients tend
 to hard-drop connections if what is offered by the server is unacceptable,
 
 The TLS protocol does not negotiate an acceptable size for this; clients tend
 to hard-drop connections if what is offered by the server is unacceptable,


@@ -17083,17 +17139,19 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum
 acceptable bound from 1024 to 2048.
 
 
 acceptable bound from 1024 to 2048.
 
 

-.option tls_eccurve main string&!! prime256v1
+.option tls_eccurve main string&!! &`auto`&

 .cindex TLS "EC cryptography"
 .cindex TLS "EC cryptography"

-If built with a recent-enough version of OpenSSL,
-this option selects a EC curve for use by Exim.
+This option selects a EC curve for use by Exim.
+
+After expansion it must contain a valid EC curve parameter, such as
+&`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual
+for valid selections.

 
 

-Curve names of the form &'prime256v1'& are accepted.
-For even more-recent library versions, names of the form &'P-512'&
-are also accepted, plus the special value &'auto'&
-which tells the library to choose.
+For OpenSSL versions before (and not including) 1.0.2, the string
+&`auto`& selects &`prime256v1`&. For more recent OpenSSL versions
+&`auto`& tells the library to choose.

 
 

-If the option is set to an empty string, no EC curves will be enabled.
+If the option expands to an empty string, no EC curves will be enabled.

 
 
 .option tls_ocsp_file main string&!! unset
 
 
 .option tls_ocsp_file main string&!! unset


@@ -23940,11 +23998,30 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter
 .cindex CHUNKING "enabling, in client"
 .cindex BDAT "SMTP command"
 .cindex "RFC 3030" "CHUNKING"
 .cindex CHUNKING "enabling, in client"
 .cindex BDAT "SMTP command"
 .cindex "RFC 3030" "CHUNKING"

-This option provides a list of server to which, provided they announce
+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 conjuction with a transport filter.
 .wen
 
 CHUNKING support, Exim will attempt to use BDAT commands rather than DATA.
 BDAT will not be used in conjuction with a transport filter.
 .wen
 

+.new
+.option hosts_try_fastopen smtp "host list!!" unset
+.option "fast open, TCP" "enabling, in client"
+.option "TCP Fast Open" "enabling, in client"
+.option "RFC 7413" "TCP Fast Open"
+This option provides a list of servers to which, provided
+the facility is supported by this system, Exim will attempt to
+perform a TCP Fast Open.
+No data is sent on the SYN segment but, if the remote server also
+supports the facility, it can send its SMTP banner immediately after
+the SYN,ACK segment.  This can save up to one round-trip time.
+
+The facility is only active for previously-contacted servers,
+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.
+.wen
+

 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"
 This option provides a list of servers to which, provided they announce
 .option hosts_try_prdr smtp "host list&!!" *
 .cindex "PRDR" "enabling, optional in client"
 This option provides a list of servers to which, provided they announce


@@ -27491,8 +27568,13 @@ during TLS session handshake, to permit alternative values to be chosen:
 
 Great care should be taken to deal with matters of case, various injection
 attacks in the string (&`../`& or SQL), and ensuring that a valid filename
 
 Great care should be taken to deal with matters of case, various injection
 attacks in the string (&`../`& or SQL), and ensuring that a valid filename

-can always be referenced; it is important to remember that &$tls_sni$& is
+can always be referenced; it is important to remember that &$tls_in_sni$& is

 arbitrary unverified data provided prior to authentication.
 arbitrary unverified data provided prior to authentication.

+.new
+Further, the initial cerificate is loaded before SNI is arrived, so
+an expansion for &%tls_certificate%& must have a default which is used
+when &$tls_in_sni$& is empty.
+.wen

 
 The Exim developers are proceeding cautiously and so far no other TLS options
 are re-expanded.
 
 The Exim developers are proceeding cautiously and so far no other TLS options
 are re-expanded.


@@ -31588,6 +31670,15 @@ configuration as follows (example):
 .code
 spamd_address = 192.168.99.45 387
 .endd
 .code
 spamd_address = 192.168.99.45 387
 .endd

+The SpamAssassin protocol relies on a TCP half-close from the client.
+If your SpamAssassin client side is running a Linux system with an
+iptables firewall, consider setting
+&%net.netfilter.nf_conntrack_tcp_timeout_close_wait%& to at least the
+timeout, Exim uses when waiting for a response from the SpamAssassin
+server (currently defaulting to 120s).  With a lower value the Linux
+connection tracking may consider your half-closed connection as dead too
+soon.
+

 
 To use Rspamd (which by default listens on all local addresses
 on TCP port 11333)
 
 To use Rspamd (which by default listens on all local addresses
 on TCP port 11333)