X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/c9433c53ad292c2f7ec05aa9d083767f95d07858..e8ca77c32e51000283df63e08d6247d7a432b262:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 540a9cbf8..36ed7ca09 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -766,17 +766,17 @@ the Exim documentation, &"spool"& is always used in the first sense. .chapter "Incorporated code" "CHID2" .cindex "incorporated code" .cindex "regular expressions" "library" -.cindex "PCRE" +.cindex "PCRE2" .cindex "OpenDMARC" A number of pieces of external code are included in the Exim distribution. .ilist Regular expressions are supported in the main Exim program and in the -Exim monitor using the freely-distributable PCRE library, copyright -© University of Cambridge. The source to PCRE is no longer shipped with -Exim, so you will need to use the version of PCRE shipped with your system, +Exim monitor using the freely-distributable PCRE2 library, copyright +© University of Cambridge. The source to PCRE2 is not longer shipped with +Exim, so you will need to use the version of PCRE2 shipped with your system, or obtain and install the full version of the library from -&url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre). +&url(https://github.com/PhilipHazel/pcre2/releases). .next .cindex "cdb" "acknowledgment" Support for the cdb (Constant DataBase) lookup method is provided by code @@ -1745,20 +1745,20 @@ overridden if necessary. A C99-capable compiler will be required for the build. -.section "PCRE library" "SECTpcre" -.cindex "PCRE library" -Exim no longer has an embedded PCRE library as the vast majority of -modern systems include PCRE as a system library, although you may need to -install the PCRE package or the PCRE development package for your operating -system. If your system has a normal PCRE installation the Exim build +.section "PCRE2 library" "SECTpcre" +.cindex "PCRE2 library" +Exim no longer has an embedded regular-expression library as the vast majority of +modern systems include PCRE2 as a system library, although you may need to +install the PCRE2 package or the PCRE2 development package for your operating +system. If your system has a normal PCRE2 installation the Exim build process will need no further configuration. If the library or the -headers are in an unusual location you will need to either set the PCRE_LIBS +headers are in an unusual location you will need to either set the PCRE2_LIBS and INCLUDE directives appropriately, -or set PCRE_CONFIG=yes to use the installed &(pcre-config)& command. +or set PCRE2_CONFIG=yes to use the installed &(pcre-config)& command. If your operating system has no -PCRE support then you will need to obtain and build the current PCRE -from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/). -More information on PCRE is available at &url(https://www.pcre.org/). +PCRE2 support then you will need to obtain and build the current PCRE2 +from &url(https://github.com/PhilipHazel/pcre2/releases). +More information on PCRE2 is available at &url(https://www.pcre.org/). .section "DBM libraries" "SECTdb" .cindex "DBM libraries" "discussion of" @@ -2587,6 +2587,25 @@ use of Exim's filtering capabilities, you should make the document entitled +.section "Running the daemon" SECTdaemonLaunch +The most common command line for launching the Exim daemon looks like +.code +exim -bd -q5m +.endd +This starts a daemon which +.ilist +listens for incoming smtp connections, launching handler processes for +each new one +.next +starts a queue-runner process every five minutes, to inspect queued messages +and run delivery attempts on any that have arrived at their retry time +.endlist +Should a queue run take longer than the time between queue-runner starts, +they will run in parallel. +Numbers of jobs of the various types are subject to policy controls +defined in the configuration. + + .section "Upgrading Exim" "SECID36" .cindex "upgrading Exim" If you are already running Exim on your host, building and installing a new @@ -6635,9 +6654,9 @@ Chapter &<>& covers both. .chapter "Regular expressions" "CHAPregexp" .cindex "regular expressions" "library" -.cindex "PCRE" +.cindex "PCRE2" Exim supports the use of regular expressions in many of its options. It -uses the PCRE regular expression library; this provides regular expression +uses the PCRE2 regular expression library; this provides regular expression matching that is compatible with Perl 5. The syntax and semantics of regular expressions is discussed in online Perl manpages, in @@ -6649,10 +6668,10 @@ O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)). . --- to the old URL for now. 2018-09-07. The documentation for the syntax and semantics of the regular expressions that -are supported by PCRE is included in the PCRE distribution, and no further -description is included here. The PCRE functions are called from Exim using -the default option settings (that is, with no PCRE options set), except that -the PCRE_CASELESS option is set when the matching is required to be +are supported by PCRE2 is included in the PCRE2 distribution, and no further +description is included here. The PCRE2 functions are called from Exim using +the default option settings (that is, with no PCRE2 options set), except that +the PCRE2_CASELESS option is set when the matching is required to be case-insensitive. In most cases, when a regular expression is required in an Exim configuration, @@ -6736,6 +6755,9 @@ domains = ${lookup{$sender_host_address}lsearch{/some/file}} domains = lsearch;/some/file .endd The first uses a string expansion, the result of which must be a domain list. +.new +The key for an expansion-style lookup must be given explicitly. +.wen No strings have been specified for a successful or a failing lookup; the defaults in this case are the looked-up data and an empty string, respectively. The expansion takes place before the string is processed as a list, and the @@ -6760,6 +6782,12 @@ domain2: Any data that follows the keys is not relevant when checking that the domain matches the list item. +.new +The key for a list-style lookup is implicit, from the lookup context, if +the lookup is a single-key type (see below). +For query-style lookup types the key must be given explicitly. +.wen + It is possible, though no doubt confusing, to use both kinds of lookup at once. Consider a file containing lines like this: .code @@ -6794,7 +6822,7 @@ The &'single-key'& type requires the specification of a file in which to look, and a single key to search for. The key must be a non-empty string for the lookup to succeed. The lookup type determines how the file is searched. .cindex "tainted data" "single-key lookups" -The file string may not be tainted +The file string may not be tainted. .cindex "tainted data" "de-tainting" All single-key lookups support the option &"ret=key"&. @@ -10556,7 +10584,7 @@ sending the request. Values are &"yes"& (the default) or &"no"& &*tls*& Controls the use of TLS on the connection. Values are &"yes"& or &"no"& (the default). -If it is enabled, a shutdown as descripbed above is never done. +If it is enabled, a shutdown as described above is never done. .endlist @@ -12079,8 +12107,9 @@ matched using &%match_ip%&. .cindex "&%pam%& expansion condition" &'Pluggable Authentication Modules'& (&url(https://mirrors.edge.kernel.org/pub/linux/libs/pam/)) are a facility that is -available in the latest releases of Solaris and in some GNU/Linux -distributions. The Exim support, which is intended for use in conjunction with +available in Solaris +and in some GNU/Linux distributions. +The Exim support, which is intended for use in conjunction with the SMTP AUTH command, is available only if Exim is compiled with .code SUPPORT_PAM=yes @@ -15854,8 +15883,8 @@ described in section &<>&. .cindex "ESMTP extensions" DSN DSN extensions (RFC3461) will be advertised in the EHLO message to, and accepted from, these hosts. -Hosts may use the NOTIFY and ENVID options on RCPT TO commands, -and RET and ORCPT options on MAIL FROM commands. +Hosts may use the NOTIFY and ORCPT options on RCPT TO commands, +and RET and ENVID options on MAIL FROM commands. A NOTIFY=SUCCESS option requests success-DSN messages. A NOTIFY= option with no argument requests that no delay or failure DSNs are sent. @@ -18410,12 +18439,7 @@ larger prime than requested. The value of this option is expanded and indicates the source of DH parameters to be used by Exim. -This option is ignored for GnuTLS version 3.6.0 and later. -The library manages parameter negotiation internally. - -&*Note: The Exim Maintainers strongly recommend, -for other TLS library versions, -using a filename with site-generated +&*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. @@ -18466,8 +18490,17 @@ 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 +they are still in Exim to avoid breaking unusual configurations, but are candidates for removal the next time we have backwards-incompatible changes. +.new +Two of them in particular (&`ike1`& and &`ike22`&) are called out by RFC 8247 +as MUST NOT use for IPSEC, and two more (&`ike23`& and &`ike24`&) as +SHOULD NOT. +Because of this, Exim regards them as deprecated; if either of the first pair +are used, warnings will be logged in the paniclog, and if any are used then +warnings will be logged in the mainlog. +All four will be removed in a future Exim release. +.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, @@ -18640,7 +18673,8 @@ either &%tls_verify_hosts%& or &%tls_try_verify_hosts%& is set and Any client that matches &%tls_verify_hosts%& is constrained by &%tls_verify_certificates%&. When the client initiates a TLS session, it must present one of the listed certificates. If it does not, the connection is -aborted. &*Warning*&: Including a host in &%tls_verify_hosts%& does not require +aborted. +&*Warning*&: Including a host in &%tls_verify_hosts%& does not require the host to use TLS. It can still send SMTP commands through unencrypted connections. Forcing a client to use TLS has to be done separately using an ACL to reject inappropriate commands when the connection is not encrypted. @@ -26095,6 +26129,10 @@ certificate verification must succeed. The &%tls_verify_certificates%& option must also be set. If both this option and &%tls_try_verify_hosts%& are unset operation is as if this option selected all hosts. +&*Warning*&: Including a host in &%tls_verify_hosts%& does not require +that connections use TLS. +Fallback to in-clear communication will be done unless restricted by +the &%hosts_require_tls%& option. .option utf8_downconvert smtp integer&!! -1 .cindex utf8 "address downconversion" @@ -30440,6 +30478,11 @@ accepted by an &%accept%& verb that has a &%message%& modifier, the contents of the message override the banner message that is otherwise specified by the &%smtp_banner%& option. +.new +For tls-on-connect connections, the ACL is run after the TLS connection +is accepted (however, &%host_reject_connection%& is tested before). +.wen + .section "The EHLO/HELO ACL" "SECID192" .cindex "EHLO" "ACL for" @@ -39808,7 +39851,8 @@ For example, to dump the retry database: .code exim_dumpdb /var/spool/exim retry .endd -Two lines of output are produced for each entry: +For the retry database +two lines of output are produced for each entry: .code T:mail.ref.example:192.168.242.242 146 77 Connection refused 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * @@ -40683,7 +40727,7 @@ Consider the use of the &%inlisti%& expansion condition instead. .cindex "security" "data sources" .cindex "security" "regular expressions" .cindex "regular expressions" "security" -.cindex "PCRE" "security" +.cindex "PCRE2" "security" If configuration data for Exim can come from untrustworthy sources, there are some issues to be aware of: @@ -40693,7 +40737,7 @@ Use of &%${expand...}%& may provide a path for shell injection attacks. Letting untrusted data provide a regular expression is unwise. .next Using &%${match...}%& to apply a fixed regular expression against untrusted -data may result in pathological behaviour within PCRE. Be aware of what +data may result in pathological behaviour within PCRE2. Be aware of what "backtracking" means and consider options for being more strict with a regular expression. Avenues to explore include limiting what can match (avoiding &`.`& when &`[a-z0-9]`& or other character class will do), use of atomic grouping and @@ -42574,6 +42618,7 @@ Events have names which correspond to the point in process at which they fire. The name is placed in the variable &$event_name$& and the event action expansion must check this, as it will be called for every possible event type. +.new The current list of events is: .display &`dane:fail after transport `& per connection @@ -42588,9 +42633,11 @@ The current list of events is: &`tcp:connect before transport `& per connection &`tcp:close after transport `& per connection &`tls:cert before both `& per certificate in verification chain +&`tls:fail:connect after main `& per connection &`smtp:connect after transport `& per connection &`smtp:ehlo after transport `& per connection .endd +.wen New event types may be added in future. The event name is a colon-separated list, defining the type of @@ -42616,6 +42663,7 @@ with the event type: &`msg:rcpt:host:defer `& error string &`msg:rcpt:defer `& error string &`tls:cert `& verification chain depth +&`tls:fail:connect `& error string &`smtp:connect `& smtp banner &`smtp:ehlo `& smtp ehlo response .endd