X-Git-Url: https://vcs.fsf.org/?p=exim.git;a=blobdiff_plain;f=doc%2Fdoc-docbook%2Fspec.xfpt;h=0598eccc8fb093a2c528ad8768ca4876958dd6b8;hp=b3f97e1eaea045cc2dd8c34939d0f3d5af5c70db;hb=142622b3f385bfcc36eae176763a7225c2e49b3c;hpb=2ef40f49c81890cd1fdac572290e1631762a03f1 diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index b3f97e1ea..0598eccc8 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -5033,6 +5033,33 @@ address lists. In Exim 4 these are handled better by named lists &-- see section &<>&. +.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 +&` _DRIVER_ROUTER_* `& router drivers +&` _DRIVER_TRANSPORT_* `& transport drivers +&` _DRIVER_AUTHENTICATOR_* `& authenticator drivers +&` _OPT_MAIN_* `& main config options +&` _OPT_ROUTERS_* `& generic router options +&` _OPT_TRANSPORTS_* `& generic transport options +&` _OPT_AUTHENTICATORS_* `& generic authenticator options +&` _OPT_ROUTER_*_* `& private router options +&` _OPT_TRANSPORT_*_* `& private transport options +&` _OPT_AUTHENTICATOR_*_* `& private authenticator options +.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`&" @@ -13572,6 +13599,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 &%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" @@ -16835,6 +16863,15 @@ If this option is unset, &"mail"& is used. See chapter &<>& for 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 &<>& for details of Exim's logging. + + .option syslog_processname main string &`exim`& .cindex "syslog" "process name; setting" @@ -17034,7 +17071,15 @@ larger prime than requested. 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 @@ -17050,23 +17095,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 &<>& for further details. +.new 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 -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`&, -&`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. +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, @@ -17084,17 +17145,19 @@ prior to the 4.80 release, as Debian used to patch Exim to raise the minimum acceptable bound from 1024 to 2048. -.option tls_eccurve main string&!! prime256v1 +.option tls_eccurve main string&!! &`auto`& .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. -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. +After expansion it must contain a valid EC curve parameter, such as +&`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual +for valid selections. -If the option is set to an empty string, no EC curves will be enabled. +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 expands to an empty string, no EC curves will be enabled. .option tls_ocsp_file main string&!! unset @@ -23941,11 +24004,30 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter .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 +.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 @@ -26730,7 +26812,7 @@ tls: .endd This accepts a client certificate that is verifiable against any of your configured trust-anchors -which usually means the full set of public CAs) +(which usually means the full set of public CAs) and which has a SAN with a good account name. Note that the client cert is on the wire in-clear, including the SAN, whereas a plaintext SMTP AUTH done inside TLS is not. @@ -27492,8 +27574,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 -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. +.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. @@ -31589,6 +31676,15 @@ configuration as follows (example): .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) @@ -38700,7 +38796,7 @@ must be representable in UTF-16. .cindex events The events mechanism in Exim can be used to intercept processing at a number -of points. It was originally invented to giave a way to do customised logging +of points. It was originally invented to give a way to do customised logging actions (for example, to a database) but can also be used to modify some processing actions. @@ -38770,7 +38866,7 @@ with the event type: The :defer events populate one extra variable: &$event_defer_errno$&. For complex operations an ACL expansion can be used in &%event_action%& -however due to the multiple contextx that Exim operates in during +however due to the multiple contexts that Exim operates in during the course of its processing: .ilist variables set in transport events will not be visible outside that