X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/509a8839d50d1e688b794975378214cc201a9697..7a97480c2bb86d9385597680ec2d4461e1656193:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index ef8fc6836..935a78a39 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -45,7 +45,7 @@ . Update the Copyright year (only) when changing content. . ///////////////////////////////////////////////////////////////////////////// -.set previousversion "4.95" +.set previousversion "4.96" .include ./local_params .set ACL "access control lists (ACLs)" @@ -214,142 +214,63 @@ . ///////////////////////////////////////////////////////////////////////////// -. This chunk of literal XML implements index entries of the form "x, see y" and -. "x, see also y". However, the DocBook DTD doesn't allow entries +. These implement index entries of the form "x, see y" and "x, see also y". +. However, the DocBook DTD doesn't allow entries . at the top level, so we have to put the .chapter directive first. - -. These do not turn up in the HTML output, unfortunately. The PDF does get them. . ///////////////////////////////////////////////////////////////////////////// .chapter "Introduction" "CHID1" -.literal xml - - $1, $2, etc. - numerical variables - - - address - rewriting - rewriting - - - Bounce Address Tag Validation - BATV - - - Client SMTP Authorization - CSA - - - CR character - carriage return - - - CRL - certificate revocation list - - - delivery - failure report - bounce message - - - dialup - intermittently connected hosts - - - exiscan - content scanning - - - failover - fallback - - - fallover - fallback - - - filter - Sieve - Sieve filter - - - ident - RFC 1413 - - - LF character - linefeed - - - maximum - limit - - - monitor - Exim monitor - - - no_xxx - entry for xxx - - - NUL - binary zero - - - passwd file - /etc/passwd - - - process id - pid - - - RBL - DNS list - - - redirection - address redirection - - - return path - envelope sender - - - scanning - content scanning - - - SSL - TLS - - - string - expansion - expansion - - - top bit - 8-bit characters - - - variables - expansion, variables - - - zero, binary - binary zero - - - headers - header lines +.macro seeother +.literal xml + + $3 +.arg 5 + $5 +.endarg + <$1>$4 - .literal off +.endmacro + +. NB: for the 4-arg variant the ordering is awkward +.macro see +.seeother see "$1" "$2" "$3" "$4" +.endmacro +.macro seealso +.seeother seealso "$1" "$2" "$3" "$4" +.endmacro + +.see variable "$1, $2, etc." "numerical variables" +.see concept address rewriting rewriting +.see concept "Bounce Address Tag Validation" BATV +.see concept "Client SMTP Authorization" CSA +.see concept "CR character" "carriage return" +.see concept CRL "certificate revocation list" +.seealso concept de-tainting "tainted data" +.see concept delivery "bounce message" "failure report" +.see concept dialup "intermittently connected hosts" +.see concept exiscan "content scanning" +.see concept fallover fallback +.see concept filter "Sieve filter" Sieve +.see concept headers "header lines" +.see concept ident "RFC 1413" +.see concept "LF character" "linefeed" +.seealso concept maximum limit +.see concept monitor "Exim monitor" +.see concept "no_xxx" "entry for xxx" +.see concept NUL "binary zero" +.see concept "passwd file" "/etc/passwd" +.see concept "process id" pid +.see concept RBL "DNS list" +.see concept redirection "address redirection" +.see concept "return path" "envelope sender" +.see concept scanning "content scanning" +.see concept SSL TLS +.see concept string expansion expansion +.see concept "top bit" "8-bit characters" +.see concept variables "expansion, variables" +.see concept "zero, binary" "binary zero" . ///////////////////////////////////////////////////////////////////////////// @@ -1393,7 +1314,7 @@ The preconditions that are tested for each router are listed below, in the order in which they are tested. The individual configuration options are described in more detail in chapter &<>&. -.ilist +.olist .cindex affix "router precondition" The &%local_part_prefix%& and &%local_part_suffix%& options can specify that the local parts handled by the router may or must have certain prefixes and/or @@ -1520,7 +1441,7 @@ example, &_.procmailrc_&). .cindex "delivery" "in detail" When a message is to be delivered, the sequence of events is as follows: -.ilist +.olist If a system-wide filter file is specified, the message is passed to it. The filter may add recipients to the message, replace the recipients, discard the message, cause a new message to be generated, or cause the message delivery to @@ -1631,7 +1552,7 @@ as permanent. -.section "Temporary delivery failure" "SECID20" +.subsection "Temporary delivery failure" SECID20 .cindex "delivery" "temporary failure" There are many reasons why a message may not be immediately deliverable to a particular address. Failure to connect to a remote machine (because it, or the @@ -1655,7 +1576,7 @@ one connection. -.section "Permanent delivery failure" "SECID21" +.subsection "Permanent delivery failure" SECID21 .cindex "delivery" "permanent failure" .cindex "bounce message" "when generated" When a message cannot be delivered to some or all of its intended recipients, a @@ -1683,7 +1604,7 @@ of the list. -.section "Failures to deliver bounce messages" "SECID22" +.subsection "Failures to deliver bounce messages" SECID22 .cindex "bounce message" "failure to deliver" If a bounce message (either locally generated or received from a remote host) itself suffers a permanent delivery failure, the message is left in the queue, @@ -1820,11 +1741,9 @@ the traditional &'ndbm'& interface. To complicate things further, there are several very different versions of the Berkeley DB package. Version 1.85 was stable for a very long time, releases 2.&'x'& and 3.&'x'& were current for a while, -.new but the latest versions when Exim last revamped support were numbered 5.&'x'&. Maintenance of some of the earlier releases has ceased, and Exim no longer supports versions before 3.&'x'&. -.wen All versions of Berkeley DB could be obtained from &url(http://www.sleepycat.com/), which is now a redirect to their new owner's page with far newer versions listed. @@ -1849,9 +1768,7 @@ USE_DB=yes .endd Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is diagnosed if you set more than one of these. -.new You can set USE_NDBM if needed to override an operating system default. -.wen At the lowest level, the build-time configuration sets none of these options, thereby assuming an interface of type (1). However, some operating system @@ -1868,9 +1785,7 @@ DBMLIB = -ldb DBMLIB = -ltdb DBMLIB = -lgdbm -lgdbm_compat .endd -.new The last of those was for a Linux having GDBM provide emulated NDBM facilities. -.wen Settings like that will work if the DBM library is installed in the standard place. Sometimes it is not, and the library's header file may also not be in the default path. You may need to set INCLUDE to specify where the header @@ -2919,6 +2834,12 @@ defined and macros will be expanded. Because macros in the config file are often used for secrets, those are only available to admin users. +.new +The word &"set"& at the start of a line, followed by a single space, +is recognised specially as defining a value for a variable. +The syntax is otherwise the same as the ACL modifier &"set ="&. +.wen + .vitem &%-bem%&&~<&'filename'&> .oindex "&%-bem%&" .cindex "testing" "string expansion" @@ -3708,41 +3629,41 @@ of debugging data, respectively. For example, &%-d+filter%& adds filter debugging, whereas &%-d-all+filter%& selects only filter debugging. Note that no spaces are allowed in the debug setting. The available debugging categories are: -.display -&`acl `& ACL interpretation -&`auth `& authenticators -&`deliver `& general delivery logic -&`dns `& DNS lookups (see also resolver) -&`dnsbl `& DNS black list (aka RBL) code -&`exec `& arguments for &[execv()]& calls -&`expand `& detailed debugging for string expansions -&`filter `& filter handling -&`hints_lookup `& hints data lookups -&`host_lookup `& all types of name-to-IP address handling -&`ident `& ident lookup -&`interface `& lists of local interfaces -&`lists `& matching things in lists -&`load `& system load checks -&`local_scan `& can be used by &[local_scan()]& (see chapter &&& - &<>&) -&`lookup `& general lookup code and all lookups -&`memory `& memory handling -&`noutf8 `& modifier: avoid UTF-8 line-drawing -&`pid `& modifier: add pid to debug output lines -&`process_info `& setting info for the process log -&`queue_run `& queue runs -&`receive `& general message reception logic -&`resolver `& turn on the DNS resolver's debugging output -&`retry `& retry handling -&`rewrite `& address rewriting -&`route `& address routing -&`timestamp `& modifier: add timestamp to debug output lines -&`tls `& TLS logic -&`transport `& transports -&`uid `& changes of uid/gid and looking up uid/gid -&`verify `& address verification logic -&`all `& almost all of the above (see below), and also &%-v%& -.endd +.itable none 0 0 2 20* left 80* left +.irow acl "ACL interpretation" +.irow auth "authenticators" +.irow deliver "general delivery logic" +.irow dns "DNS lookups (see also resolver)" +.irow dnsbl "DNS black list (aka RBL) code" +.irow exec "arguments for &[execv()]& calls" +.irow expand "detailed debugging for string expansions" +.irow filter "filter handling" +.irow hints_lookup "hints data lookups" +.irow host_lookup "all types of name-to-IP address handling" +.irow ident "ident lookup" +.irow interface "lists of local interfaces" +.irow lists "matching things in lists" +.irow load "system load checks" +.irow local_scan "can be used by &[local_scan()]& (see chapter &&& + &<>&)" +.irow lookup "general lookup code and all lookups" +.irow memory "memory handling" +.irow noutf8 "modifier: avoid UTF-8 line-drawing" +.irow pid "modifier: add pid to debug output lines" +.irow process_info "setting info for the process log" +.irow queue_run "queue runs" +.irow receive "general message reception logic" +.irow resolver "turn on the DNS resolver's debugging output" +.irow retry "retry handling" +.irow rewrite "address rewriting"" +.irow route "address routing" +.irow timestamp "modifier: add timestamp to debug output lines" +.irow tls "TLS logic" +.irow transport "transports" +.irow uid "changes of uid/gid and looking up uid/gid" +.irow verify "address verification logic" +.irow all "almost all of the above (see below), and also &%-v%&" +.endtable The &`all`& option excludes &`memory`& when used as &`+all`&, but includes it for &`-all`&. The reason for this is that &`+all`& is something that people tend to use when generating debug output for Exim maintainers. If &`+memory`& @@ -6774,9 +6695,7 @@ 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 @@ -6802,11 +6721,9 @@ 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: @@ -6857,11 +6774,9 @@ The &'query-style'& type accepts a generalized database query. No particular key value is assumed by Exim for query-style lookups. You can use whichever Exim variables you need to construct the database query. .cindex "tainted data" "quoting for lookups" -.new If tainted data is used in the query then it should be quuted by using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator appropriate for the lookup. -.wen .endlist The code for each lookup type is in a separate source file that is included in @@ -7579,7 +7494,7 @@ specified. ${lookup dnsdb{>:,; soa=a.b.example.com}} .endd -.section "Dnsdb lookup modifiers" "SECTdnsdb_mod" +.subsection "Dnsdb lookup modifiers" SECTdnsdb_mod .cindex "dnsdb modifiers" .cindex "modifiers" "dnsdb" .cindex "options" "dnsdb" @@ -7637,7 +7552,7 @@ The cache entry lifetime is limited to the smallest time-to-live (TTL) value of the set of returned DNS records. -.section "Pseudo dnsdb record types" "SECID66" +.subsection "Pseudo dnsdb record types" SECID66 .cindex "MX record" "in &(dnsdb)& lookup" By default, both the preference value and the host name are returned for each MX record, separated by a space. If you want only host names, you can use @@ -7693,7 +7608,7 @@ ${lookup dnsdb {>; a+=$sender_helo_name}} .endd -.section "Multiple dnsdb lookups" "SECID67" +.subsection "Multiple dnsdb lookups" SECID67 In the previous sections, &(dnsdb)& lookups for a single domain are described. However, you can specify a list of domains or IP addresses in a single &(dnsdb)& lookup. The list is specified in the normal Exim way, with colon as @@ -7758,7 +7673,7 @@ the data returned by a successful lookup is described in the next section. First we explain how LDAP queries are coded. -.section "Format of LDAP queries" "SECTforldaque" +.subsection "Format of LDAP queries" SECTforldaque .cindex "LDAP" "query format" An LDAP query takes the form of a URL as defined in RFC 2255. For example, in the configuration of a &(redirect)& router one might have this setting: @@ -7787,7 +7702,7 @@ methods become optional, only taking effect if not specifically set in &_exim.conf_&. -.section "LDAP quoting" "SECID68" +.subsection "LDAP quoting" SECID68 .cindex "LDAP" "quoting" Two levels of quoting are required in LDAP queries, the first for LDAP itself and the second because the LDAP query is represented as a URL. Furthermore, @@ -7844,7 +7759,7 @@ There are some further comments about quoting in the section on LDAP authentication below. -.section "LDAP connections" "SECID69" +.subsection "LDAP connections" SECID69 .cindex "LDAP" "connections" The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP is in use, via a Unix domain socket. The example given above does not specify @@ -7918,7 +7833,7 @@ Using &`ldapi`& with no host or path in the query, and no setting of -.section "LDAP authentication and control information" "SECID70" +.subsection "LDAP authentication and control information" SECID70 .cindex "LDAP" "authentication" The LDAP URL syntax provides no way of passing authentication and other control information to the server. To make this possible, the URL in an LDAP query may @@ -7926,16 +7841,16 @@ be preceded by any number of <&'name'&>=<&'value'&> settings, separated by spaces. If a value contains spaces it must be enclosed in double quotes, and when double quotes are used, backslash is interpreted in the usual way inside them. The following names are recognized: -.display -&`DEREFERENCE`& set the dereferencing parameter -&`NETTIME `& set a timeout for a network operation -&`USER `& set the DN, for authenticating the LDAP bind -&`PASS `& set the password, likewise -&`REFERRALS `& set the referrals parameter -&`SERVERS `& set alternate server list for this query only -&`SIZE `& set the limit for the number of entries returned -&`TIME `& set the maximum waiting time for a query -.endd +.itable none 0 0 2 20* left 80* left +.irow DEREFERENCE "set the dereferencing parameter" +.irow NETTIME "set a timeout for a network operation" +.irow USER "set the DN, for authenticating the LDAP bind" +.irow PASS "set the password, likewise" +.irow REFERRALS "set the referrals parameter" +.irow SERVERS "set alternate server list for this query only" +.irow SIZE "set the limit for the number of entries returned" +.irow TIME "set the maximum waiting time for a query" +.endtable The value of the DEREFERENCE parameter must be one of the words &"never"&, &"searching"&, &"finding"&, or &"always"&. The value of the REFERRALS parameter must be &"follow"& (the default) or &"nofollow"&. The latter stops the LDAP @@ -8012,7 +7927,7 @@ SMTP authentication. See the &%ldapauth%& expansion string condition in chapter -.section "Format of data returned by LDAP" "SECID71" +.subsection "Format of data returned by LDAP" SECID71 .cindex "LDAP" "returned data formats" The &(ldapdn)& lookup type returns the Distinguished Name from a single entry as a sequence of values, for example @@ -8146,7 +8061,7 @@ If the result of the query yields more than one row, it is all concatenated, with a newline between the data for each row. -.section "More about MySQL, PostgreSQL, Oracle, InterBase, and Redis" "SECID72" +.subsection "More about MySQL, PostgreSQL, Oracle, InterBase, and Redis" SECID72 .cindex "MySQL" "lookup type" .cindex "PostgreSQL lookup type" .cindex "lookup" "MySQL" @@ -8216,7 +8131,7 @@ itself are escaped with backslashes. The &%quote_redis%& expansion operator escapes whitespace and backslash characters with a backslash. -.section "Specifying the server in the query" "SECTspeserque" +.subsection "Specifying the server in the query" SECTspeserque For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and InterBase), it is possible to specify a list of servers with an individual query. This is done by appending a comma-separated option to the query type: @@ -8266,7 +8181,7 @@ arguments in the query, for explicit expansion. &*Note*&: server specifications in list-style lookups are still problematic. -.section "Special MySQL features" "SECID73" +.subsection "Special MySQL features" SECID73 For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%& causes a connection to the server on the local host by means of a Unix domain socket. An alternate socket can be specified in parentheses. @@ -8291,7 +8206,7 @@ anything (for example, setting a field to the value it already has), the result is zero because no rows are affected. -.section "Special PostgreSQL features" "SECID74" +.subsection "Special PostgreSQL features" SECID74 PostgreSQL lookups can also use Unix domain socket connections to the database. This is usually faster and costs less CPU time than a TCP/IP connection. However it can be used only if the mail server runs on the same machine as the @@ -8308,7 +8223,7 @@ If a PostgreSQL query is issued that does not request any data (an insert, update, or delete command), the result of the lookup is the number of rows affected. -.section "More about SQLite" "SECTsqlite" +.subsection "More about SQLite" SECTsqlite .cindex "lookup" "SQLite" .cindex "sqlite lookup type" SQLite is different to the other SQL lookups because a filename is required in @@ -8359,7 +8274,7 @@ waits for the lock to be released. In Exim, the default timeout is set to 5 seconds, but it can be changed by means of the &%sqlite_lock_timeout%& option. -.section "More about Redis" "SECTredis" +.subsection "More about Redis" SECTredis .cindex "lookup" "Redis" .cindex "redis lookup type" Redis is a non-SQL database. Commands are simple get and set. @@ -8408,6 +8323,34 @@ domain, host, address and local part lists. +.section "Results of list checking" SECTlistresults +The primary result of doing a list check is a truth value. +In some contexts additional information is stored +about the list element that matched: +.vlist +.vitem hosts +A &%hosts%& ACL condition +will store a result in the &$host_data$& variable. +.vitem local_parts +A &%local_parts%& router option or &%local_parts%& ACL condition +will store a result in the &$local_part_data$& variable. +.vitem domains +A &%domains%& router option or &%domains%& ACL condition +will store a result in the &$domain_data$& variable. +.vitem senders +A &%senders%& router option or &%senders%& ACL condition +will store a result in the &$sender_data$& variable. +.vitem recipients +A &%recipients%& ACL condition +will store a result in the &$recipient_data$& variable. +.endlist + +The detail of the additional information depends on the +type of match and is given below as the &*value*& information. + + + + .section "Expansion of lists" "SECTlistexpand" .cindex "expansion" "of lists" Each list is expanded as a single string before it is used. @@ -8443,7 +8386,7 @@ senders based on the receiving domain. -.section "Negated items in lists" "SECID76" +.subsection "Negated items in lists" SECID76 .cindex "list" "negation" .cindex "negation" "in lists" Items in a list may be positive or negative. Negative items are indicated by a @@ -8476,7 +8419,7 @@ item. -.section "File names in lists" "SECTfilnamlis" +.subsection "File names in lists" SECTfilnamlis .cindex "list" "filename in" If an item in a domain, host, address, or local part list is an absolute filename (beginning with a slash character), each line of the file is read and @@ -8518,7 +8461,7 @@ any domain matching &`*.b.c`& is not. -.section "An lsearch file is not an out-of-line list" "SECID77" +.subsection "An lsearch file is not an out-of-line list" SECID77 As will be described in the sections that follow, lookups can be used in lists to provide indexed methods of checking list membership. There has been some confusion about the way &(lsearch)& lookups work in lists. Because @@ -8535,35 +8478,7 @@ in the previous section. You could also use the &(wildlsearch)& or -.section "Results of list checking" SECTlistresults -The primary result of doing a list check is a truth value. -In some contexts additional information is stored -about the list element that matched: -.vlist -.vitem hosts -A &%hosts%& ACL condition -will store a result in the &$host_data$& variable. -.vitem local_parts -A &%local_parts%& router option or &%local_parts%& ACL condition -will store a result in the &$local_part_data$& variable. -.vitem domains -A &%domains%& router option or &%domains%& ACL condition -will store a result in the &$domain_data$& variable. -.vitem senders -A &%senders%& router option or &%senders%& ACL condition -will store a result in the &$sender_data$& variable. -.vitem recipients -A &%recipients%& ACL condition -will store a result in the &$recipient_data$& variable. -.endlist - -The detail of the additional information depends on the -type of match and is given below as the &*value*& information. - - - - -.section "Named lists" "SECTnamedlists" +.subsection "Named lists" SECTnamedlists .cindex "named lists" .cindex "list" "named" A list of domains, hosts, email addresses, or local parts can be given a name @@ -8652,7 +8567,7 @@ hosts. The default configuration is set up like this. -.section "Named lists compared with macros" "SECID78" +.subsection "Named lists compared with macros" SECID78 .cindex "list" "named compared with macro" .cindex "macro" "compared with named list" At first sight, named lists might seem to be no different from macros in the @@ -8678,7 +8593,7 @@ auth_advertise_hosts = !host1 : !host2 .endd -.section "Named list caching" "SECID79" +.subsection "Named list caching" SECID79 .cindex "list" "caching of named" .cindex "caching" "named lists" While processing a message, Exim caches the result of checking a named list if @@ -8953,7 +8868,7 @@ You need to be particularly careful with this when single-key lookups are involved, to ensure that the right value is being used as the key. -.section "Special host list patterns" "SECID80" +.subsection "Special host list patterns" SECID80 .cindex "empty item in hosts list" .cindex "host list" "empty string in" If a host list item is the empty string, it matches only when no remote host is @@ -8967,7 +8882,7 @@ the IP address nor the name is actually inspected. -.section "Host list patterns that match by IP address" "SECThoslispatip" +.subsection "Host list patterns that match by IP address" SECThoslispatip .cindex "host list" "matching IP addresses" If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, the incoming address actually appears in the IPv6 host as @@ -9070,8 +8985,8 @@ list. -.section "Host list patterns for single-key lookups by host address" &&& - "SECThoslispatsikey" +.subsection "Host list patterns for single-key lookups by host address" &&& + SECThoslispatsikey .cindex "host list" "lookup of IP address" When a host is to be identified by a single-key lookup of its complete IP address, the pattern takes this form: @@ -9130,7 +9045,7 @@ case the IP address is used on its own. -.section "Host list patterns that match by host name" "SECThoslispatnam" +.subsection "Host list patterns that match by host name" SECThoslispatnam .cindex "host" "lookup failures" .cindex "unknown host name" .cindex "host list" "matching host name" @@ -9205,7 +9120,7 @@ required. -.section "Behaviour when an IP address or name cannot be found" "SECTbehipnot" +.subsection "Behaviour when an IP address or name cannot be found" SECTbehipnot .cindex "host" "lookup failures, permanent" While processing a host list, Exim may need to look up an IP address from a name (see section &<>&), or it may need to look up a host name @@ -9251,8 +9166,8 @@ Both &`+include_unknown`& and &`+ignore_unknown`& may appear in the same list. The effect of each one lasts until the next, or until the end of the list. -.section "Mixing wildcarded host names and addresses in host lists" &&& - "SECTmixwilhos" +.subsection "Mixing wildcarded host names and addresses in host lists" &&& + SECTmixwilhos .cindex "host list" "mixing names and addresses in" This section explains the host/ip processing logic with the same concepts @@ -9288,8 +9203,8 @@ this section. .endlist -.section "Temporary DNS errors when looking up host information" &&& - "SECTtemdnserr" +.subsection "Temporary DNS errors when looking up host information" &&& + SECTtemdnserr .cindex "host" "lookup failures, temporary" .cindex "&`+include_defer`&" .cindex "&`+ignore_defer`&" @@ -9302,8 +9217,8 @@ host lists such as whitelists. -.section "Host list patterns for single-key lookups by host name" &&& - "SECThoslispatnamsk" +.subsection "Host list patterns for single-key lookups by host name" &&& + SECThoslispatnamsk .cindex "unknown host name" .cindex "host list" "matching host name" If a pattern is of the form @@ -9327,7 +9242,7 @@ lookup, both using the same file. -.section "Host list patterns for query-style lookups" "SECID81" +.subsection "Host list patterns for query-style lookups" SECID81 If a pattern is of the form .display <&'query-style-search-type'&>;<&'query'&> @@ -9559,7 +9474,7 @@ example it is a named domain list. -.section "Case of letters in address lists" "SECTcasletadd" +.subsection "Case of letters in address lists" SECTcasletadd .cindex "case of local parts" .cindex "address list" "case forcing" .cindex "case forcing in address lists" @@ -9706,6 +9621,17 @@ value. Nevertheless the &%-be%& option can be useful for checking out file and database lookups, and the use of expansion operators such as &%sg%&, &%substr%& and &%nhash%&. +.new +When reading lines from the standard input, +macros can be defined and ACL variables can be set. +For example: +.code +MY_MACRO = foo +set acl_m_myvar = bar +.endd +Such macros and variables can then be used in later input lines. +.wen + Exim gives up its root privilege when it is called with the &%-be%& option, and instead runs under the uid and gid it was called with, to prevent users from using &%-be%& for reading files to which they do not have access. @@ -10687,7 +10613,6 @@ expansion item in section &<>& above. .cindex "expansion" "running a command" .cindex "&%run%& expansion item" This item runs an external command, as a subprocess. -.new One option is supported after the word &'run'&, comma-separated. If the option &'preexpand'& is not used, @@ -10704,7 +10629,6 @@ potential attacker; a careful assessment for security vulnerabilities should be done. If the option &'preexpand'& is used, -.wen the command and its arguments are first expanded as one string. The result is split apart into individual arguments by spaces, and then the command is run as above. @@ -10718,9 +10642,7 @@ in a string containing quotes, because it would interfere with the quotes around the command arguments. A possible guard against this is to wrap the variable in the &%sg%& operator to change any quote marks to some other character. -.new Neither the command nor any argument may be tainted. -.wen The standard input for the command exists, but is empty. The standard output and standard error are set to the same file descriptor. @@ -11286,9 +11208,7 @@ returns the string &"10.111.131.192/28"&. Since this operation is expected to be mostly used for looking up masked addresses in files, the -.new normal -.wen result for an IPv6 address uses dots to separate components instead of colons, because colon terminates a key string in lsearch files. So, for example, @@ -11299,10 +11219,8 @@ returns the string .code 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 .endd -.new If the optional form &*mask_n*& is used, IPv6 address result are instead returned in normailsed form, using colons and with zero-compression. -.wen Letters in IPv6 addresses are always output in lower case. @@ -11634,14 +11552,14 @@ condition. .cindex "expansion" "numeric comparison" There are a number of symbolic operators for doing numeric comparisons. They are: -.display -&`= `& equal -&`== `& equal -&`> `& greater -&`>= `& greater or equal -&`< `& less -&`<= `& less or equal -.endd +.itable none 0 0 2 10* left 90* left +.irow "= " "equal" +.irow "== " "equal" +.irow "> " "greater" +.irow ">= " "greater or equal" +.irow "< " "less" +.irow "<= " "less or equal" +.endtable For example: .code ${if >{$message_size}{10M} ... @@ -11940,7 +11858,6 @@ ${if inlisti{Needle}{fOo:NeeDLE:bAr}} ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}} .endd -.new The variable &$value$& will be set for a successful match and can be used in the success clause of an &%if%& expansion item using the condition. .cindex "tainted data" "de-tainting" @@ -11951,7 +11868,6 @@ ${if inlist {$h_mycode:} {0 : 1 : 42} {$value}} .endd can be used for de-tainting. Any previous &$value$& is restored after the if. -.wen .vitem &*isip&~{*&<&'string'&>&*}*& &&& @@ -12150,7 +12066,6 @@ item can be used, as in all address lists, to cause subsequent items to have their local parts matched casefully. Domains are always matched caselessly. -.new The variable &$value$& will be set for a successful match and can be used in the success clause of an &%if%& expansion item using the condition. .cindex "tainted data" "de-tainting" @@ -12161,7 +12076,6 @@ ${if match_local_part {$local_part} {alice : bill : charlotte : dave} {$value}} .endd can be used for de-tainting. Any previous &$value$& is restored after the if. -.wen Note that <&'string2'&> is not itself subject to string expansion, unless Exim was built with the EXPAND_LISTMATCH_RHS option. @@ -12358,7 +12272,6 @@ parsed but not evaluated. This section contains an alphabetical list of all the expansion variables. Some of them are available only when Exim is compiled with specific options such as support for TLS or the content scanning extension. -.new .cindex "tainted data" Variables marked as &'tainted'& are likely to carry data supplied by a potential attacker. @@ -12367,7 +12280,6 @@ values are created. Such variables should not be further expanded, used as filenames or used as command-line arguments for external commands. -.wen .vlist .vitem "&$0$&, &$1$&, etc" @@ -12382,9 +12294,7 @@ variables may also be set externally by some other matching process which precedes the expansion of the string. For example, the commands available in Exim filter files include an &%if%& command with its own regular expression matching condition. -.new If the subject string was tainted then any captured substring will also be. -.wen .vitem "&$acl_arg1$&, &$acl_arg2$&, etc" Within an acl condition, expansion condition or expansion item @@ -12536,9 +12446,10 @@ command that does not succeed. Otherwise it is set to &"0"&. This makes it possible to distinguish between &"did not try to authenticate"& (&$sender_host_authenticated$& is empty and &$authentication_failed$& is set to &"0"&) and &"tried to authenticate but failed"& (&$sender_host_authenticated$& -is empty and &$authentication_failed$& is set to &"1"&). Failure includes any -negative response to an AUTH command, including (for example) an attempt to use -an undefined mechanism. +is empty and &$authentication_failed$& is set to &"1"&). +Failure includes cancellation of a authentication attempt, +and any negative response to an AUTH command, +(including, for example, an attempt to use an undefined mechanism). .vitem &$av_failed$& .cindex "content scanning" "AV scanner failure" @@ -13289,11 +13200,9 @@ This is not an expansion variable, but is mentioned here because the string (described under &%transport_filter%& in chapter &<>&). It cannot be used in general expansion strings, and provokes an &"unknown variable"& error if encountered. -.new &*Note*&: This value permits data supplied by a potential attacker to be used in the command for a &(pipe)& transport. Such configurations should be carefully assessed for security vulnerbilities. -.wen .vitem &$primary_hostname$& .vindex "&$primary_hostname$&" @@ -13512,9 +13421,7 @@ This variable is set to contain the matching regular expression after a When a &%regex%& or &%mime_regex%& ACL condition succeeds, these variables contain the captured substrings identified by the regular expression. -.new If the subject string was tainted then so will any captured substring. -.wen .tvar &$reply_address$& @@ -14725,6 +14632,7 @@ listed in more than one group. .row &%log_timezone%& "add timezone to log lines" .row &%message_logs%& "create per-message logs" .row &%preserve_message_logs%& "after message completion" +.row &%panic_coredump%& "request coredump on fatal errors" .row &%process_log_path%& "for SIGUSR1 and &'exiwhat'&" .row &%slow_lookup_log%& "control logging of slow DNS lookups" .row &%syslog_duplication%& "controls duplicate log lines on syslog" @@ -14897,6 +14805,7 @@ listed in more than one group. .row &%gnutls_compat_mode%& "use GnuTLS compatibility mode" .row &%gnutls_allow_auto_pkcs11%& "allow GnuTLS to autoload PKCS11 modules" .row &%hosts_require_alpn%& "mandatory ALPN" +.row &%hosts_require_helo%& "mandatory HELO/EHLO" .row &%openssl_options%& "adjust OpenSSL compatibility options" .row &%tls_advertise_hosts%& "advertise TLS to these hosts" .row &%tls_alpn%& "acceptable protocol names" @@ -16384,7 +16293,10 @@ local processes, you must create a host list with an empty item. For example: .code hosts_connection_nolog = : .endd -If the &%smtp_connection%& log selector is not set, this option has no effect. +.new +The hosts affected by this option also do not log "no MAIL in SMTP connection" +lines, as may commonly be produced by a monitoring system. +.wen .option hosts_require_alpn main "host list&!!" unset @@ -16400,6 +16312,12 @@ See also the &%tls_alpn%& option. managed by this option, and should be done separately. +.option hosts_require_helo main "host list&!!" * +.cindex "HELO/EHLO" requiring +Exim will require an accepted HELO or EHLO command from a host matching +this list, before accepting a MAIL command. + + .option hosts_proxy main "host list&!!" unset .cindex proxy "proxy protocol" This option enables use of Proxy Protocol proxies for incoming @@ -17054,6 +16972,19 @@ to be used in conjunction with &(oracle)& lookups (see section &<>&). The option is available only if Exim has been built with Oracle support. +.new +.option panic_coredump main boolean false +This option is rarely needed but can help for some debugging investigations. +If set, when an internal error is detected by Exim which is sufficient +to terminate the process +(all such are logged in the paniclog) +then a coredump is requested. + +Note that most systems require additional administrative configuration +to permit write a core file for a setuid program, which is Exim's +common installed configuration. +.wen + .option percent_hack_domains main "domain list&!!" unset .cindex "&""percent hack""&" .cindex "source routing" "in email address" @@ -17128,9 +17059,9 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&). .option pipelining_connect_advertise_hosts main "host list&!!" * .cindex "pipelining" "early connection" -.cindex "pipelining" PIPE_CONNECT -.cindex "ESMTP extensions" PIPE_CONNECT -If Exim is built with the SUPPORT_PIPE_CONNECT build option +.cindex "pipelining" PIPECONNECT +.cindex "ESMTP extensions" PIPECONNECT +If Exim is built without the DISABLE_PIPE_CONNECT build option this option controls which hosts the facility is advertised to and from which pipeline early-connection (before MAIL) SMTP commands are acceptable. @@ -17138,7 +17069,11 @@ When used, the pipelining saves on roundtrip times. See also the &%hosts_pipe_connect%& smtp transport option. -The SMTP service extension keyword advertised is &"PIPE_CONNECT"&. +The SMTP service extension keyword advertised is &"PIPECONNECT"&; +it permits the client to pipeline +TCP connection and hello command (inclear phase), +or TLS-establishment and hello command (encrypted phase), +on later connections to the same host. .option prdr_enable main boolean false @@ -17260,7 +17195,7 @@ domains that do not match are processed. All other deliveries wait until the next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&. -.option queue_fast_ramp main boolean false +.option queue_fast_ramp main boolean true .cindex "queue runner" "two phase" .cindex "queue" "double scanning" If set to true, two-phase queue runs, initiated using &%-qq%& on the @@ -17504,7 +17439,7 @@ initial set of recipients. The remote server should then re-send the message for the remaining recipients at a later time. -.option remote_max_parallel main integer 2 +.option remote_max_parallel main integer 4 .cindex "delivery" "parallelism for remote" This option controls parallel delivery of one message to a number of remote hosts. If the value is less than 2, parallel delivery is disabled, and Exim @@ -18553,7 +18488,6 @@ of the later IKE values, which led into RFC7919 providing new fixed constants At this point, all of the "ike" values should be considered obsolete; 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. @@ -18561,7 +18495,6 @@ 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, @@ -24748,11 +24681,9 @@ This list is a compromise for maximum compatibility with other MTAs. Note that the &%environment%& option can be used to add additional variables to this environment. The environment for the &(pipe)& transport is not subject to the &%add_environment%& and &%keep_environment%& main config options. -.new &*Note*&: Using enviroment variables loses track of tainted data. Writers of &(pipe)& transport commands should be wary of data supplied by potential attackers. -.wen .display &`DOMAIN `& the domain of the address &`HOME `& the home directory, if set @@ -24844,10 +24775,8 @@ the &%path%& option below). The command is split up into separate arguments by Exim, and each argument is separately expanded, as described in section &<>& above. -.new .cindex "tainted data" No part of the resulting command may be tainted. -.wen .option environment pipe string&!! unset @@ -25556,7 +25485,6 @@ helo_data = ${lookup dnsdb{ptr=$sending_ip_address} \ The use of &%helo_data%& applies both to sending messages and when doing callouts. -.new .option host_name_extract smtp "string list&!!" "see below" .cindex "load balancer" "hosts behind" .cindex TLS resumption @@ -25586,7 +25514,6 @@ of other destination sites operating load-balancers, and develop a suitable expression for this option. The smtp:ehlo event and the &$tls_out_resumption$& variable will be useful for such work. -.wen .option hosts smtp "string list&!!" unset Hosts are associated with an address by a router such as &(dnslookup)&, which @@ -25641,7 +25568,7 @@ that matches this list, even if the server host advertises PIPELINING support. .option hosts_pipe_connect smtp "host list&!!" unset .cindex "pipelining" "early connection" -.cindex "pipelining" PIPE_CONNECT +.cindex "pipelining" PIPECONNECT If Exim is built with the SUPPORT_PIPE_CONNECT build option this option controls which to hosts the facility watched for and recorded, and used for subsequent connections. @@ -25655,10 +25582,8 @@ so combines well with TCP Fast Open. See also the &%pipelining_connect_advertise_hosts%& main option. Note: -.new When the facility is used, if the transport &%interface%& option is unset the &%helo_data%& option -.wen will be expanded before the &$sending_ip_address$& variable is filled in. A check is made for the use of that variable, without the @@ -25791,11 +25716,6 @@ There will be no fallback to in-clear communication. See the &%dnssec_request_domains%& router and transport options. See section &<>&. -.option hosts_require_helo smtp "host list&!!" * -.cindex "HELO/EHLO" requiring -Exim will require an accepted HELO or EHLO command from a host matching -this list, before accepting a MAIL command. - .option hosts_require_ocsp smtp "host list&!!" unset .cindex "TLS" "requiring for certain servers" Exim will request, and check for a valid Certificate Status being given, on a @@ -26419,7 +26339,7 @@ message's processing. .vindex "&$sender_address$&" At the start of an ACL for MAIL, the sender address may have been rewritten -by a special SMTP-time rewrite rule (see section &<>&), but no +by a special SMTP-time rewrite rule (see section &<>&), but no ordinary rewrite rules have yet been applied. If, however, the sender address is verified in the ACL, it is rewritten before verification, and remains rewritten thereafter. The subsequent value of &$sender_address$& is the @@ -26626,7 +26546,7 @@ entry written to the panic log. -.section "Rewriting flags" "SECID153" +.subsection "Rewriting flags" "SSECID153" There are three different kinds of flag that may appear on rewriting rules: .ilist @@ -26643,11 +26563,11 @@ E, F, T, and S are not permitted. -.section "Flags specifying which headers and envelope addresses to rewrite" &&& - "SECID154" -.cindex "rewriting" "flags" +.subsection "Flags specifying which headers and envelope addresses to rewrite" &&& + "SSECID154" +.cindex rewriting flags If none of the following flag letters, nor the &"S"& flag (see section -&<>&) are present, a main rewriting rule applies to all headers +&<>&) are present, a main rewriting rule applies to all headers and to both the sender and recipient fields of the envelope, whereas a transport-time rewriting rule just applies to all headers. Otherwise, the rewriting rule is skipped unless the relevant addresses are being processed. @@ -26671,10 +26591,10 @@ You should be particularly careful about rewriting &'Sender:'& headers, and restrict this to special known cases in your own domains. -.section "The SMTP-time rewriting flag" "SECTrewriteS" -.cindex "SMTP" "rewriting malformed addresses" -.cindex "RCPT" "rewriting argument of" -.cindex "MAIL" "rewriting argument of" +.subsection "The SMTP-time rewriting flag" SSECTrewriteS +.cindex SMTP "rewriting malformed addresses" +.cindex RCPT "rewriting argument of" +.cindex MAIL "rewriting argument of" The rewrite flag &"S"& specifies a rewrite of incoming envelope addresses at SMTP time, as soon as an address is received in a MAIL or RCPT command, and before any other processing; even before syntax checking. The pattern is @@ -26691,7 +26611,7 @@ expansion of the replacement string. The result of rewriting replaces the original address in the MAIL or RCPT command. -.section "Flags controlling the rewriting process" "SECID155" +.subsection "Flags controlling the rewriting process" SSECID155 There are four flags which control the way the rewriting process works. These take effect only when a rule is invoked, that is, when the address is of the correct type (matches the flags) and matches the pattern: @@ -27371,7 +27291,7 @@ it is enforced. .cindex "ESMTP extensions" AUTH Very briefly, the way SMTP authentication works is as follows: -.ilist +.olist The server advertises a number of authentication &'mechanisms'& in response to the client's EHLO command. .next @@ -27727,7 +27647,16 @@ no successful authentication. Successful authentication sets up information used by the &%authresults%& expansion item. - +.new +.cindex authentication "failure event" +If an authenticator is run and does not succeed, +an event (see &<>&) of type "auth:fail" is raised. +While the event is being processed the variables +&$sender_host_authenticated$& (with the authenticator name) +and &$authenticated_fail_id$& (as set by the suthenticator &%server_set_id%& option) +will be valid. +See <> for details on events. +.wen .section "Testing server authentication" "SECID169" @@ -29539,7 +29468,7 @@ For outgoing SMTP deliveries, &$tls_out_cipher$& is used and logged (again depending on the &%tls_cipher%& log selector). -.section "Requesting and verifying client certificates" "SECID183" +.subsection "Requesting and verifying client certificates" SECID183 .cindex "certificate" "verification of client" .cindex "TLS" "client certificate verification" If you want an Exim server to request a certificate when negotiating a TLS @@ -29845,7 +29774,7 @@ outgoing connection. -.section "Caching of static client configuration items" "SECTclientTLScache" +.subsection "Caching of static client configuration items" SECTclientTLScache .cindex certificate caching .cindex privatekey caching .cindex crl caching @@ -29934,10 +29863,8 @@ nothing more to it. Choosing a sensible value not derived insecurely is the only point of caution. The &$tls_out_sni$& variable will be set to this string for the lifetime of the client connection (including during authentication). -.new If DANE validated the connection attempt then the value of the &%tls_sni%& option is forced to the name of the destination host, after any MX- or CNAME-following. -.wen Except during SMTP client sessions, if &$tls_in_sni$& is set then it is a string received from a client. @@ -30078,7 +30005,7 @@ Ivan is the author of the popular TLS testing tools at &url(https://www.ssllabs.com/). -.section "Certificate chains" "SECID186" +.subsection "Certificate chains" SECID186 A file named by &%tls_certificate%& may contain more than one certificate. This is useful in the case where the certificate that is being sent is validated by an intermediate certificate which the other end does @@ -30099,7 +30026,7 @@ diagnostics in such a case can be frustratingly vague. -.section "Self-signed certificates" "SECID187" +.subsection "Self-signed certificates" SECID187 .cindex "certificate" "self-signed" You can create a self-signed certificate using the &'req'& command provided with OpenSSL, like this: @@ -30548,7 +30475,7 @@ trying to deliver the message. It is therefore recommended that you do as much testing as possible at RCPT time. -.section "The non-SMTP ACLs" "SECID190" +.subsection "The non-SMTP ACLs" SECID190 .cindex "non-SMTP messages" "ACLs for" The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not @@ -30582,7 +30509,7 @@ kind of rejection is treated as permanent, because there is no way of sending a temporary error for these kinds of message. -.section "The SMTP connect ACL" "SECID191" +.subsection "The SMTP connect ACL" SECID191 .cindex "SMTP" "connection, ACL for" .oindex &%smtp_banner%& The ACL test specified by &%acl_smtp_connect%& happens at the start of an SMTP @@ -30592,13 +30519,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" +.subsection "The EHLO/HELO ACL" SECID192 .cindex "EHLO" "ACL for" .cindex "HELO" "ACL for" The ACL test specified by &%acl_smtp_helo%& happens when the client issues an @@ -30619,7 +30544,7 @@ affect the EHLO options that are listed on the second and subsequent lines of an EHLO response. -.section "The DATA ACLs" "SECID193" +.subsection "The DATA ACLs" SECID193 .cindex "DATA" "ACLs for" Two ACLs are associated with the DATA command, because it is two-stage command, with two responses being sent to the client. @@ -30658,7 +30583,7 @@ the &%acl_smtp_data_prdr%&, the &%acl_smtp_dkim%& and the &%acl_smtp_mime%& ACLs. -.section "The SMTP DKIM ACL" "SECTDKIMACL" +.subsection "The SMTP DKIM ACL" SECTDKIMACL The &%acl_smtp_dkim%& ACL is available only when Exim is compiled with DKIM support enabled (which is the default). @@ -30671,14 +30596,14 @@ This ACL is evaluated before &%acl_smtp_mime%& and &%acl_smtp_data%&. For details on the operation of DKIM, see section &<>&. -.section "The SMTP MIME ACL" "SECID194" +.subsection "The SMTP MIME ACL" SECID194 The &%acl_smtp_mime%& option is available only when Exim is compiled with the content-scanning extension. For details, see chapter &<>&. This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&. -.section "The SMTP PRDR ACL" "SECTPRDRACL" +.subsection "The SMTP PRDR ACL" SECTPRDRACL .cindex "PRDR" "ACL for" .oindex "&%prdr_enable%&" The &%acl_smtp_data_prdr%& ACL is available only when Exim is compiled @@ -30712,7 +30637,7 @@ This ACL is evaluated after &%acl_smtp_dkim%& but before &%acl_smtp_data%&. If the ACL is not defined, processing completes as if the feature was not requested by the client. -.section "The QUIT ACL" "SECTQUITACL" +.subsection "The QUIT ACL" SECTQUITACL .cindex "QUIT, ACL for" The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL does not affect the response code to QUIT, which is always 221. Thus, the ACL @@ -30739,7 +30664,7 @@ client are given temporary error responses until QUIT is received or the connection is closed. In these special cases, the QUIT ACL does not run. -.section "The not-QUIT ACL" "SECTNOTQUITACL" +.subsection "The not-QUIT ACL" SECTNOTQUITACL .vindex &$acl_smtp_notquit$& The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when an SMTP session ends without sending QUIT. However, when Exim itself is in bad @@ -31715,12 +31640,12 @@ This control turns on debug logging, almost as though Exim had been invoked with &`-d`&, with the output going to a new logfile in the usual logs directory, by default called &'debuglog'&. -.new +Logging set up by the control will be maintained across spool residency. + Options are a slash-separated list. If an option takes an argument, the option name and argument are separated by an equals character. Several options are supported: -.wen .display tag=<&'suffix'&> The filename can be adjusted with thise option. The argument, which may access any variables already defined, @@ -32278,7 +32203,7 @@ different variants of this condition to describe briefly here. See sections .cindex "domain" "ACL checking" .cindex "&ACL;" "testing a recipient domain" .vindex "&$domain_data$&" -This condition is relevant only after a RCPT command. It checks that the domain +This condition is relevant only in a RCPT ACL. It checks that the domain of the recipient address is in the domain list. If percent-hack processing is enabled, it is done before this test is done. If the check succeeds with a lookup, the result of the lookup is placed in &$domain_data$& until the next @@ -32346,7 +32271,7 @@ which gives a custom error message for each denied host. .cindex "local part" "ACL checking" .cindex "&ACL;" "testing a local part" .vindex "&$local_part_data$&" -This condition is relevant only after a RCPT command. It checks that the local +This condition is relevant only in a RCPT ACL. It checks that the local part of the recipient address is in the list. If percent-hack processing is enabled, it is done before this test. If the check succeeds with a lookup, the result of the lookup is placed in &$local_part_data$&, which remains set until @@ -32380,7 +32305,7 @@ messages. Details are given in section &<>&. .cindex "&%recipients%& ACL condition" .cindex "recipient" "ACL checking" .cindex "&ACL;" "testing a recipient" -This condition is relevant only after a RCPT command. It checks the entire +This condition is relevant only in a RCPT ACL. It checks the entire recipient address against a list of recipients. .vitem &*regex&~=&~*&<&'list&~of&~regular&~expressions'&> @@ -32391,13 +32316,11 @@ content-scanning extension, and is available only in the DATA, MIME, and non-SMTP ACLs. It causes the incoming message to be scanned for a match with any of the regular expressions. For details, see chapter &<>&. -.new .vitem &*seen&~=&~*&<&'parameters'&> -.cindex "&%sseen%& ACL condition" +.cindex "&%seen%& ACL condition" This condition can be used to test if a situation has been previously met, for example for greylisting. Details are given in section &<>&. -.wen .vitem &*sender_domains&~=&~*&<&'domain&~list'&> .cindex "&%sender_domains%& ACL condition" @@ -32657,11 +32580,11 @@ This is usually the required action when &%dnslists%& is used with &%deny%& (which is the most common usage), because it prevents a DNS failure from blocking mail. However, you can change this behaviour by putting one of the following special items in the list: -.display -&`+include_unknown `& behave as if the item is on the list -&`+exclude_unknown `& behave as if the item is not on the list (default) -&`+defer_unknown `& give a temporary error -.endd +.itable none 0 0 2 25* left 75* left +.irow "+include_unknown" "behave as if the item is on the list" +.irow "+exclude_unknown" "behave as if the item is not on the list (default)" +.irow "+defer_unknown " "give a temporary error" +.endtable .cindex "&`+include_unknown`&" .cindex "&`+exclude_unknown`&" .cindex "&`+defer_unknown`&" @@ -32691,7 +32614,7 @@ or free for small deployments. An overview can be found at -.section "Specifying the IP address for a DNS list lookup" "SECID201" +.subsection "Specifying the IP address for a DNS list lookup" SECID201 .cindex "DNS list" "keyed by explicit IP address" By default, the IP address that is used in a DNS list lookup is the IP address of the calling host. However, you can specify another IP address by listing it @@ -32707,7 +32630,7 @@ MX hosts or nameservers of an email sender address. For an example, see section -.section "DNS lists keyed on domain names" "SECID202" +.subsection "DNS lists keyed on domain names" SECID202 .cindex "DNS list" "keyed by domain name" There are some lists that are keyed on domain names rather than inverted IP addresses (see, e.g., the &'domain based zones'& link at @@ -32737,7 +32660,7 @@ name. The whole condition is true if either of the DNS lookups succeeds. -.section "Multiple explicit keys for a DNS list" "SECTmulkeyfor" +.subsection "Multiple explicit keys for a DNS list" SECTmulkeyfor .cindex "DNS list" "multiple keys for" The syntax described above for looking up explicitly-defined values (either names or IP addresses) in a DNS blacklist is a simplification. After the domain @@ -32804,21 +32727,21 @@ The key that was used for a successful DNS list lookup is put into the variable -.section "Data returned by DNS lists" "SECID203" +.subsection "Data returned by DNS lists" SECID203 .cindex "DNS list" "data returned from" DNS lists are constructed using address records in the DNS. The original RBL just used the address 127.0.0.1 on the right hand side of each record, but the RBL+ list and some other lists use a number of values with different meanings. The values used on the RBL+ list are: -.display -127.1.0.1 RBL -127.1.0.2 DUL -127.1.0.3 DUL and RBL -127.1.0.4 RSS -127.1.0.5 RSS and RBL -127.1.0.6 RSS and DUL -127.1.0.7 RSS and DUL and RBL -.endd +.itable none 0 0 2 20* left 80* left +.irow 127.1.0.1 "RBL" +.irow 127.1.0.2 "DUL" +.irow 127.1.0.3 "DUL and RBL" +.irow 127.1.0.4 "RSS" +.irow 127.1.0.5 "RSS and RBL" +.irow 127.1.0.6 "RSS and DUL" +.irow 127.1.0.7 "RSS and DUL and RBL" +.endtable Section &<>& below describes how you can distinguish between different values. Some DNS lists may return more than one address record; see section &<>& for details of how they are checked. @@ -32829,7 +32752,7 @@ may start returning other addresses. Because of this, Exim now ignores returned values outside the 127/8 region. -.section "Variables set from DNS lists" "SECID204" +.subsection "Variables set from DNS lists" SECID204 .cindex "expansion" "variables, set from DNS list" .cindex "DNS list" "variables set from" .vindex "&$dnslist_domain$&" @@ -32875,7 +32798,7 @@ deny hosts = !+local_networks -.section "Additional matching conditions for DNS lists" "SECTaddmatcon" +.subsection "Additional matching conditions for DNS lists" SECTaddmatcon .cindex "DNS list" "matching specific returned data" You can add an equals sign and an IP address after a &%dnslists%& domain name in order to restrict its action to DNS records with a matching right hand side. @@ -32921,7 +32844,7 @@ an odd number. -.section "Negated DNS matching conditions" "SECID205" +.subsection "Negated DNS matching conditions" SECID205 You can supply a negative list of IP addresses as part of a &%dnslists%& condition. Whereas .code @@ -32975,7 +32898,7 @@ deny dnslists = zen.spamhaus.org!&0.255.255.0 -.section "Handling multiple DNS records from a DNS list" "SECThanmuldnsrec" +.subsection "Handling multiple DNS records from a DNS list" SECThanmuldnsrec A DNS lookup for a &%dnslists%& condition may return more than one DNS record, thereby providing more than one IP address. When an item in a &%dnslists%& list is followed by &`=`& or &`&&`& and a list of IP addresses, in order to restrict @@ -33039,7 +32962,7 @@ between &`=`& and &`==`& and between &`&&`& and &`=&&`&. -.section "Detailed information from merged DNS lists" "SECTmordetinf" +.subsection "Detailed information from merged DNS lists" SECTmordetinf .cindex "DNS list" "information from merged" When the facility for restricting the matching IP values in a DNS list is used, the text from the TXT record that is set in &$dnslist_text$& may not reflect @@ -33088,7 +33011,7 @@ done. Only if there is a match is one of the more specific lists consulted. -.section "DNS lists and IPv6" "SECTmorednslistslast" +.subsection "DNS lists and IPv6" SECTmorednslistslast .cindex "IPv6" "DNS black lists" .cindex "DNS list" "IPv6 usage" If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it @@ -33122,9 +33045,8 @@ address you should specify alternate list separators for both the outer .endd -.new .section "Previously seen user and hosts" "SECTseen" -.cindex "&%sseen%& ACL condition" +.cindex "&%een%& ACL condition" .cindex greylisting The &%seen%& ACL condition can be used to test whether a situation has been previously met. @@ -33175,7 +33097,6 @@ An explicit interval can be set using a Note that &"seen"& should be added to the list of hints databases for maintenance if this ACL condition is used. -.wen .section "Rate limiting incoming messages" "SECTratelimiting" @@ -33246,7 +33167,7 @@ behaviour. The lookup key is not affected by changes to the update mode and the &%count=%& option. -.section "Ratelimit options for what is being measured" "ratoptmea" +.subsection "Ratelimit options for what is being measured" ratoptmea .cindex "rate limiting" "per_* options" The &%per_conn%& option limits the client's connection rate. It is not normally used in the &%acl_not_smtp%&, &%acl_not_smtp_mime%&, or @@ -33293,7 +33214,7 @@ other than &%acl_smtp_rcpt%&). The count does not have to be an integer. The &%unique=%& option is described in section &<>& below. -.section "Ratelimit update modes" "ratoptupd" +.subsection "Ratelimit update modes" ratoptupd .cindex "rate limiting" "reading data without updating" You can specify one of three options with the &%ratelimit%& condition to control when its database is updated. This section describes the &%readonly%& @@ -33334,7 +33255,7 @@ update mode defaults to &%readonly%& and you cannot specify the &%strict%& or next section) so you must specify the &%readonly%& option explicitly. -.section "Ratelimit options for handling fast clients" "ratoptfast" +.subsection "Ratelimit options for handling fast clients" ratoptfast .cindex "rate limiting" "strict and leaky modes" If a client's average rate is greater than the maximum, the rate limiting engine can react in two possible ways, depending on the presence of the @@ -33365,7 +33286,7 @@ attempt to send mail can be calculated with this formula: .endd -.section "Limiting the rate of different events" "ratoptuniq" +.subsection "Limiting the rate of different events" ratoptuniq .cindex "rate limiting" "counting unique events" The &%ratelimit%& &%unique=%& option controls a mechanism for counting the rate of different events. For example, the &%per_addr%& option uses this @@ -33403,7 +33324,7 @@ are logged incorrectly; any countermeasures you configure will be as effective as intended. -.section "Using rate limiting" "useratlim" +.subsection "Using rate limiting" useratlim Exim's other ACL facilities are used to define what counter-measures are taken when the rate limit is exceeded. This might be anything from logging a warning (for example, while measuring existing sending rates in order to define @@ -33620,10 +33541,17 @@ output before performing a callout in an ACL, to avoid unexpected timeouts in clients when the SMTP PIPELINING extension is in use. The flushing can be disabled by using a &%control%& modifier to set &%no_callout_flush%&. +.cindex "tainted data" "de-tainting" +.cindex "de-tainting" "using recipient verify" +A recipient callout which gets a 2&'xx'& code +will assign untainted values to the +&$domain_data$& and &$local_part_data$& variables, +corresponding to the domain and local parts of the recipient address. + -.section "Additional parameters for callouts" "CALLaddparcall" +.subsection "Additional parameters for callouts" CALLaddparcall .cindex "callout" "additional parameters for" The &%callout%& option can be followed by an equals sign and a number of optional parameters, separated by commas. For example: @@ -33811,7 +33739,7 @@ actual callouts are performed than when an empty sender or postmaster is used. -.section "Callout caching" "SECTcallvercache" +.subsection "Callout caching" SECTcallvercache .cindex "hints database" "callout cache" .cindex "callout" "cache, description of" .cindex "caching" "callout" @@ -35446,10 +35374,8 @@ discussed below. .vitem &*header_line&~*header_last*& A pointer to the last of the header lines. -.new .vitem &*const&~uschar&~*headers_charset*& The value of the &%headers_charset%& configuration option. -.wen .vitem &*BOOL&~host_checking*& This variable is TRUE during a host checking session that is initiated by the @@ -35733,11 +35659,11 @@ added zero byte is not included in the returned count. .vitem &*int&~lss_match_domain(uschar&~*domain,&~uschar&~*list)*& This function checks for a match in a domain list. Domains are always matched caselessly. The return value is one of the following: -.display -&`OK `& match succeeded -&`FAIL `& match failed -&`DEFER `& match deferred -.endd +.itable none 0 0 2 15* left 85* left +.irow &`OK`& "match succeeded" +.irow &`FAIL`& "match failed" +.irow &`DEFER`& "match deferred" +.endtable DEFER is usually caused by some kind of lookup defer, such as the inability to contact a database. @@ -36468,7 +36394,8 @@ incoming SMTP message from a source that is not permitted to send them. -.section "Resent- header lines" "SECID220" +.section "Header lines" +.subsection "Resent- header lines" SECID220 .chindex Resent- RFC 2822 makes provision for sets of header lines starting with the string &`Resent-`& to be added to a message when it is resent by the original @@ -36509,14 +36436,14 @@ The logic for adding &'Sender:'& is duplicated for &'Resent-Sender:'& when any -.section "The Auto-Submitted: header line" "SECID221" +.subsection Auto-Submitted: SECID221 Whenever Exim generates an autoreply, a bounce, or a delay warning message, it includes the header line: .code Auto-Submitted: auto-replied .endd -.section "The Bcc: header line" "SECID222" +.subsection Bcc: SECID222 .cindex "&'Bcc:'& header line" If Exim is called with the &%-t%& option, to take recipient addresses from a message's header, it removes any &'Bcc:'& header line that may exist (after @@ -36524,13 +36451,13 @@ extracting its addresses). If &%-t%& is not present on the command line, any existing &'Bcc:'& is not removed. -.section "The Date: header line" "SECID223" +.subsection Date: SECID223 .cindex Date: If a locally-generated or submission-mode message has no &'Date:'& header line, Exim adds one, using the current date and time, unless the &%suppress_local_fixups%& control has been specified. -.section "The Delivery-date: header line" "SECID224" +.subsection Delivery-date: SECID224 .cindex "&'Delivery-date:'& header line" .oindex "&%delivery_date_remove%&" &'Delivery-date:'& header lines are not part of the standard RFC 2822 header @@ -36541,7 +36468,7 @@ set (the default), Exim removes &'Delivery-date:'& header lines from incoming messages. -.section "The Envelope-to: header line" "SECID225" +.subsection Envelope-to: SECID225 .chindex Envelope-to: .oindex "&%envelope_to_remove%&" &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set. @@ -36552,7 +36479,7 @@ messages in transit. If the &%envelope_to_remove%& configuration option is set messages. -.section "The From: header line" "SECTthefrohea" +.subsection From: SECTthefrohea .chindex From: .cindex "Sendmail compatibility" "&""From""& line" .cindex "message" "submission" @@ -36595,7 +36522,7 @@ user, this is replaced by an address containing the user's login name and full name as described in section &<>&. -.section "The Message-ID: header line" "SECID226" +.subsection Message-ID: SECID226 .chindex Message-ID: .cindex "message" "submission" .oindex "&%message_id_header_text%&" @@ -36610,7 +36537,7 @@ in this header line by setting the &%message_id_header_text%& and/or &%message_id_header_domain%& options. -.section "The Received: header line" "SECID227" +.subsection Received: SECID227 .chindex Received: A &'Received:'& header line is added at the start of every message. The contents are defined by the &%received_header_text%& configuration option, and @@ -36626,7 +36553,7 @@ changed to the time of acceptance, which is (apart from a small delay while the -H spool file is written) the earliest time at which delivery could start. -.section "The References: header line" "SECID228" +.subsection References: SECID228 .chindex References: Messages created by the &(autoreply)& transport include a &'References:'& header line. This is constructed according to the rules that are described in @@ -36640,7 +36567,7 @@ incoming message. If there are more than 12, the first one and then the final -.section "The Return-path: header line" "SECID229" +.subsection Return-path: SECID229 .chindex Return-path: .oindex "&%return_path_remove%&" &'Return-path:'& header lines are defined as something an MTA may insert when @@ -36651,7 +36578,7 @@ default), Exim removes &'Return-path:'& header lines from incoming messages. -.section "The Sender: header line" "SECTthesenhea" +.subsection Sender: SECTthesenhea .cindex "&'Sender:'& header line" .cindex "message" "submission" .chindex Sender: @@ -37056,7 +36983,7 @@ square bracket of the IP address. -.section "Errors in outgoing SMTP" "SECToutSMTPerr" +.subsection "Errors in outgoing SMTP" SECToutSMTPerr .cindex "error" "in outgoing SMTP" .cindex "SMTP" "errors in outgoing" .cindex "host" "error" @@ -37291,7 +37218,7 @@ however, available with &'inetd'&. Exim can be configured to verify addresses in incoming SMTP commands as they are received. See chapter &<>& for details. It can also be configured to rewrite addresses at this time &-- before any syntax checking is done. See -section &<>&. +section &<>&. Exim can also be configured to limit the rate at which a client host submits MAIL and RCPT commands in a single SMTP session. See the @@ -37299,7 +37226,7 @@ MAIL and RCPT commands in a single SMTP session. See the -.section "Unrecognized SMTP commands" "SECID234" +.subsection "Unrecognized SMTP commands" SECID234 .cindex "SMTP" "unrecognized commands" If Exim receives more than &%smtp_max_unknown_commands%& unrecognized SMTP commands during a single SMTP connection, it drops the connection after sending @@ -37309,7 +37236,7 @@ abuse that subvert web servers into making connections to SMTP ports; in these circumstances, a number of non-SMTP lines are sent first. -.section "Syntax and protocol errors in SMTP commands" "SECID235" +.subsection "Syntax and protocol errors in SMTP commands" SECID235 .cindex "SMTP" "syntax errors" .cindex "SMTP" "protocol errors" A syntax error is detected if an SMTP command is recognized, but there is @@ -37323,7 +37250,7 @@ broken clients that loop sending bad commands (yes, it has been seen). -.section "Use of non-mail SMTP commands" "SECID236" +.subsection "Use of non-mail SMTP commands" SECID236 .cindex "SMTP" "non-mail commands" The &"non-mail"& SMTP commands are those other than MAIL, RCPT, and DATA. Exim counts such commands, and drops the connection if there are too @@ -37352,7 +37279,7 @@ specific badly-behaved hosts that you have to live with. -.section "The VRFY and EXPN commands" "SECID237" +.subsection "The VRFY and EXPN commands" SECID237 When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the ACL specified by &%acl_smtp_vrfy%& or &%acl_smtp_expn%& (as appropriate) in order to decide whether the command should be accepted or not. @@ -37373,12 +37300,12 @@ EXPN is treated as an &"address test"& (similar to the &%-bt%& option) rather than a verification (the &%-bv%& option). If an unqualified local part is given as the argument to EXPN, it is qualified with &%qualify_domain%&. Rejections of VRFY and EXPN commands are logged on the main and reject logs, and -VRFY verification failures are logged on the main log for consistency with +VRFY verification failures are logged in the main log for consistency with RCPT failures. -.section "The ETRN command" "SECTETRN" +.subsection "The ETRN command" SECTETRN .cindex "ETRN" "processing" .cindex "ESMTP extensions" ETRN RFC 1985 describes an ESMTP command called ETRN that is designed to @@ -38444,7 +38371,7 @@ LOG_FILE_PATH, and uses the first item it finds that is neither empty nor &"syslog"&. This means that an empty item in &%log_file_path%& can be used to mean &"use the path specified at build time"&. If no such item exists, log files are written in the &_log_& subdirectory of the spool directory. This is -equivalent to the setting: +equivalent to the configuration file setting: .code log_file_path = $spool_directory/log/%slog .endd @@ -38455,7 +38382,7 @@ that is where the logs are written. A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames are in use &-- see section &<>& below. -Here are some examples of possible settings: +Here are some examples of possible Makefile settings: .display &`LOG_FILE_PATH=syslog `& syslog only &`LOG_FILE_PATH=:syslog `& syslog and default path @@ -38630,16 +38557,16 @@ One line is written to the main log for each message received, and for each successful, unsuccessful, and delayed delivery. These lines can readily be picked out by the distinctive two-character flags that immediately follow the timestamp. The flags are: -.display -&`<=`& message arrival -&`(=`& message fakereject -&`=>`& normal message delivery -&`->`& additional address in same delivery -&`>>`& cutthrough message delivery -&`*>`& delivery suppressed by &%-N%& -&`**`& delivery failed; address bounced -&`==`& delivery deferred; temporary problem -.endd +.itable none 0 0 2 10* left 90* left +.irow &%<=%& "message arrival" +.irow &%(=%& "message fakereject" +.irow &%=>%& "normal message delivery" +.irow &%->%& "additional address in same delivery" +.irow &%>>%& "cutthrough message delivery" +.irow &%*>%& "delivery suppressed by &%-N%&" +.irow &%**%& "delivery failed; address bounced" +.irow &%==%& "delivery deferred; temporary problem" +.endtable .section "Logging message reception" "SECID251" @@ -38958,65 +38885,64 @@ log_selector = +arguments -retry_defer .endd The list of optional log items is in the following table, with the default selection marked by asterisks: -.display -&` 8bitmime `& received 8BITMIME status -&`*acl_warn_skipped `& skipped &%warn%& statement in ACL -&` address_rewrite `& address rewriting -&` all_parents `& all parents in => lines -&` arguments `& command line arguments -&`*connection_reject `& connection rejections -&`*delay_delivery `& immediate delivery delayed -&` deliver_time `& time taken to attempt delivery -&` delivery_size `& add &`S=`&&'nnn'& to => lines -&`*dkim `& DKIM verified domain on <= lines -&` dkim_verbose `& separate full DKIM verification result line, per signature -&`*dnslist_defer `& defers of DNS list (aka RBL) lookups -&` dnssec `& DNSSEC secured lookups -&`*etrn `& ETRN commands -&`*host_lookup_failed `& as it says -&` ident_timeout `& timeout for ident connection -&` incoming_interface `& local interface on <= and => lines -&` incoming_port `& remote port on <= lines -&`*lost_incoming_connection `& as it says (includes timeouts) -&` millisec `& millisecond timestamps and RT,QT,DT,D times -&`*msg_id `& on <= lines, Message-ID: header value -&` msg_id_created `& on <= lines, Message-ID: header value when one had to be added -&` outgoing_interface `& local interface on => lines -&` outgoing_port `& add remote port to => lines -&`*queue_run `& start and end queue runs -&` queue_time `& time on queue for one recipient -&`*queue_time_exclusive `& exclude recieve time from QT times -&` queue_time_overall `& time on queue for whole message -&` pid `& Exim process id -&` pipelining `& PIPELINING use, on <= and => lines -&` proxy `& proxy address on <= and => lines -&` receive_time `& time taken to receive message -&` received_recipients `& recipients on <= lines -&` received_sender `& sender on <= lines -&`*rejected_header `& header contents on reject log -&`*retry_defer `& &"retry time not reached"& -&` return_path_on_delivery `& put return path on => and ** lines -&` sender_on_delivery `& add sender to => lines -&`*sender_verify_fail `& sender verification failures -&`*size_reject `& rejection because too big -&`*skip_delivery `& delivery skipped in a queue run -&`*smtp_confirmation `& SMTP confirmation on => lines -&` smtp_connection `& incoming SMTP connections -&` smtp_incomplete_transaction`& incomplete SMTP transactions -&` smtp_mailauth `& AUTH argument to MAIL commands -&` smtp_no_mail `& session with no MAIL commands -&` smtp_protocol_error `& SMTP protocol errors -&` smtp_syntax_error `& SMTP syntax errors -&` subject `& contents of &'Subject:'& on <= lines -&`*tls_certificate_verified `& certificate verification status -&`*tls_cipher `& TLS cipher suite on <= and => lines -&` tls_peerdn `& TLS peer DN on <= and => lines -&` tls_resumption `& append * to cipher field -&` tls_sni `& TLS SNI on <= lines -&` unknown_in_list `& DNS lookup failed in list match - -&` all `& all of the above -.endd +.itable none 0 0 3 2.8in left 10pt center 3in left +.irow &`8bitmime`&   "received 8BITMIME status" +.irow &`acl_warn_skipped`& * "skipped &%warn%& statement in ACL" +.irow &`address_rewrite`&   "address rewriting" +.irow &`all_parents`&   "all parents in => lines" +.irow &`arguments`&   "command line arguments" +.irow &`connection_reject`& * "connection rejections" +.irow &`delay_delivery`& * "immediate delivery delayed" +.irow &`deliver_time`&   "time taken to attempt delivery" +.irow &`delivery_size`&   "add &`S=`&&'nnn'& to => lines" +.irow &`dkim`& * "DKIM verified domain on <= lines" +.irow &`dkim_verbose`&   "separate full DKIM verification result line, per signature" +.irow &`dnslist_defer`& * "defers of DNS list (aka RBL) lookups" +.irow &`dnssec`&   "DNSSEC secured lookups" +.irow &`etrn`& * "ETRN commands" +.irow &`host_lookup_failed`& * "as it says" +.irow &`ident_timeout`&   "timeout for ident connection" +.irow &`incoming_interface`&   "local interface on <= and => lines" +.irow &`incoming_port`&   "remote port on <= lines" +.irow &`lost_incoming_connection`& * "as it says (includes timeouts)" +.irow &`millisec`&   "millisecond timestamps and RT,QT,DT,D times" +.irow &`msg_id`& * "on <= lines, Message-ID: header value" +.irow &`msg_id_created`&   "on <= lines, Message-ID: header value when one had to be added" +.irow &`outgoing_interface`&   "local interface on => lines" +.irow &`outgoing_port`&   "add remote port to => lines" +.irow &`queue_run`& * "start and end queue runs" +.irow &`queue_time`&   "time on queue for one recipient" +.irow &`queue_time_exclusive`&   "exclude recieve time from QT times" +.irow &`queue_time_overall`&   "time on queue for whole message" +.irow &`pid`&   "Exim process id" +.irow &`pipelining`&   "PIPELINING use, on <= and => lines" +.irow &`proxy`&   "proxy address on <= and => lines" +.irow &`receive_time`&   "time taken to receive message" +.irow &`received_recipients`&   "recipients on <= lines" +.irow &`received_sender`&   "sender on <= lines" +.irow &`rejected_header`& * "header contents on reject log" +.irow &`retry_defer`& * "&&retry time not reached&&" +.irow &`return_path_on_delivery`&   "put return path on => and ** lines" +.irow &`sender_on_delivery`&   "add sender to => lines" +.irow &`sender_verify_fail`& * "sender verification failures" +.irow &`size_reject`& * "rejection because too big" +.irow &`skip_delivery`& * "delivery skipped in a queue run" +.irow &`smtp_confirmation`& * "SMTP confirmation on => lines" +.irow &`smtp_connection`&   "incoming SMTP connections" +.irow &`smtp_incomplete_transaction`&   "incomplete SMTP transactions" +.irow &`smtp_mailauth`&   "AUTH argument to MAIL commands" +.irow &`smtp_no_mail`&   "session with no MAIL commands" +.irow &`smtp_protocol_error`&   "SMTP protocol errors" +.irow &`smtp_syntax_error`&   "SMTP syntax errors" +.irow &`subject`&   "contents of &'Subject:'& on <= lines" +.irow &`tls_certificate_verified`& * "certificate verification status" +.irow &`tls_cipher`& * "TLS cipher suite on <= and => lines" +.irow &`tls_peerdn`&   "TLS peer DN on <= and => lines" +.irow &`tls_resumption`&   "append * to cipher field" +.irow &`tls_sni`&   "TLS SNI on <= lines" +.irow &`unknown_in_list`&   "DNS lookup failed in list match" +.irow &`all`&   "&*all of the above*&" +.endtable See also the &%slow_lookup_log%& main configuration option, section &<>& @@ -39212,7 +39138,7 @@ On accept lines, where PIPELINING was offered but not used by the client, the field has a minus appended. .cindex "pipelining" "early connection" -If Exim is built with the SUPPORT_PIPE_CONNECT build option +If Exim is built without the DISABLE_PIPE_CONNECT build option accept "L" fields have a period appended if the feature was offered but not used, or an asterisk appended if used. Delivery "L" fields have an asterisk appended if used. @@ -39514,12 +39440,12 @@ but the format of the output is different. For this reason, there are some system configuration options that configure exactly how &'exiwhat'& works. If it doesn't seem to be working for you, check the following compile-time options: -.display -&`EXIWHAT_PS_CMD `& the command for running &'ps'& -&`EXIWHAT_PS_ARG `& the argument for &'ps'& -&`EXIWHAT_EGREP_ARG `& the argument for &'egrep'& to select from &'ps'& output -&`EXIWHAT_KILL_ARG `& the argument for the &'kill'& command -.endd +.itable none 0 0 2 30* left 70* left +.irow &`EXIWHAT_PS_CMD`& "the command for running &'ps'&" +.irow &`EXIWHAT_PS_ARG`& "the argument for &'ps'&" +.irow &`EXIWHAT_EGREP_ARG`& "the argument for &'egrep'& to select from &'ps'& output" +.irow &`EXIWHAT_KILL_ARG`& "the argument for the &'kill'& command" +.endtable An example of typical output from &'exiwhat'& is .code 164 daemon: -q1h, listening on port 25 @@ -39614,9 +39540,7 @@ overriding the built-in one. .endlist There is one more option, &%-h%&, which outputs a list of options. -.new At least one selection option, or either the &*-c*& or &*-h*& option, must be given. -.wen @@ -39999,12 +39923,10 @@ in a transport) .cindex "&'exim_dumpdb'&" The entire contents of a database are written to the standard output by the &'exim_dumpdb'& program, -.new taking as arguments the spool and database names. An option &'-z'& may be given to request times in UTC; otherwise times are in the local timezone. An option &'-k'& may be given to dump only the record keys. -.wen For example, to dump the retry database: .code exim_dumpdb /var/spool/exim retry @@ -40109,11 +40031,9 @@ resets the time of the next delivery attempt. Time values are given as a sequence of digit pairs for year, month, day, hour, and minute. Colons can be used as optional separators. -.new Both displayed and input times are in the local timezone by default. If an option &'-z'& is used on the command line, displayed times are in UTC. -.wen @@ -41136,7 +41056,6 @@ was received, in the conventional Unix form &-- the number of seconds since the start of the epoch. The second number is a count of the number of messages warning of delayed delivery that have been sent to the sender. -.new There follow a number of lines starting with a hyphen. These contain variables, can appear in any order, and are omitted when not relevant. @@ -41147,7 +41066,6 @@ If there is a value in parentheses, the data is quoted for a lookup. The following word specifies a variable, and the remainder of the item depends on the variable. -.wen .vlist .vitem "&%-acl%&&~<&'number'&>&~<&'length'&>" @@ -41466,8 +41384,8 @@ where you accept mail from relay sources (internal hosts or authenticated senders). -.section "Signing outgoing messages" "SECDKIMSIGN" -.cindex "DKIM" "signing" +.subsection "Signing outgoing messages" SECDKIMSIGN +.cindex DKIM signing For signing to be usable you must have published a DKIM record in DNS. Note that RFC 8301 (which does not cover EC keys) says: @@ -41492,6 +41410,7 @@ The domain(s) you want to sign with. After expansion, this can be a list. Each element in turn, lowercased, +.vindex "&$dkim_domain$&" is put into the &%$dkim_domain%& expansion variable while expanding the remaining signing options. If it is empty after expansion, DKIM signing is not done, @@ -41501,6 +41420,7 @@ and no error will result even if &%dkim_strict%& is set. This sets the key selector string. After expansion, which can use &$dkim_domain$&, this can be a list. Each element in turn is put in the expansion +.vindex "&$dkim_selector$&" variable &%$dkim_selector%& which may be used in the &%dkim_private_key%& option along with &%$dkim_domain%&. If the option is empty after expansion, DKIM signing is not done for this domain, @@ -41648,8 +41568,8 @@ both creation (t=) and expiry (x=) tags will be included. RFC 6376 lists these tags as RECOMMENDED. -.section "Verifying DKIM signatures in incoming mail" "SECDKIMVFY" -.cindex "DKIM" "verification" +.subsection "Verifying DKIM signatures in incoming mail" SECDKIMVFY +.cindex DKIM verification Verification of DKIM signatures in SMTP incoming email is done for all messages for which an ACL control &%dkim_disable_verify%& has not been set. @@ -42118,7 +42038,7 @@ The lookup will return the same result strings as can appear in -.section "SRS (Sender Rewriting Scheme)" SECTSRS +.subsection "SRS (Sender Rewriting Scheme)" SECTSRS .cindex SRS "sender rewriting scheme" SRS can be used to modify sender addresses when forwarding so that @@ -42154,6 +42074,7 @@ There is no need to periodically change this key; a timestamp is also encoded. The second argument should be given as the envelope sender address before this encoding operation. +If this value is empty the the expansion result will be empty. The third argument should be the recipient domain of the message when it arrived at this system. .endlist @@ -42239,7 +42160,8 @@ This description assumes that headers will be in /usr/local/include, and that the libraries are in /usr/local/lib. -. subsection +.subsection Configuration SSECDMARCCONFIG +.cindex DMARC configuration There are three main-configuration options: .cindex DMARC "configuration options" @@ -42280,9 +42202,9 @@ If not set (the default), the From: header is expanded from the dsn_from option, and <> is used for the envelope from. -. I wish we had subsections... - +.subsection Controls SSECDMARCCONTROLS .cindex DMARC controls + By default, the DMARC processing will run for any remote, non-authenticated user. It makes sense to only verify DMARC status of messages coming from remote, untrusted sources. You can @@ -42313,7 +42235,8 @@ send them.) There are no options to either control. Both must appear before the DATA acl. -. subsection +.subsection ACL SSECDMARCACL +.cindex DMARC "ACL condition" DMARC checks cam be run on incoming SMTP messages by using the &"dmarc_status"& ACL condition in the DATA ACL. You are required to @@ -42327,16 +42250,16 @@ The &"dmarc_status"& condition takes a list of strings on its right-hand side. These strings describe recommended action based on the DMARC check. To understand what the policy recommendations mean, refer to the DMARC website above. Valid strings are: -.display -&'accept '& The DMARC check passed and the library recommends accepting the email. -&'reject '& The DMARC check failed and the library recommends rejecting the email. -&'quarantine '& The DMARC check failed and the library recommends keeping it for further inspection. -&'none '& The DMARC check passed and the library recommends no specific action, neutral. -&'norecord '& No policy section in the DMARC record for this RFC5322.From field -&'nofrom '& Unable to determine the domain of the sender. -&'temperror '& Library error or dns error. -&'off '& The DMARC check was disabled for this email. -.endd +.itable none 0 0 2 20* left 80* left +.irow &'accept'& "The DMARC check passed and the library recommends accepting the email" +.irow &'reject'& "The DMARC check failed and the library recommends rejecting the email" +.irow &'quarantine'& "The DMARC check failed and the library recommends keeping it for further inspection" +.irow &'none'& "The DMARC check passed and the library recommends no specific action, neutral" +.irow &'norecord'& "No policy section in the DMARC record for this RFC5322.From field" +.irow &'nofrom'& "Unable to determine the domain of the sender" +.irow &'temperror'& "Library error or dns error" +.irow &'off'& "The DMARC check was disabled for this email" +.endtable You can prefix each string with an exclamation mark to invert its meaning, for example "!accept" will match all results but "accept". The string list is evaluated left-to-right in a @@ -42381,7 +42304,8 @@ are "none", "reject" and "quarantine". It is blank when there is any error, including no DMARC record. .endlist -. subsection +.subsection Logging SSECDMARCLOGGING +.cindex DMARC logging By default, Exim's DMARC configuration is intended to be non-intrusive and conservative. To facilitate this, Exim will not @@ -42408,7 +42332,8 @@ Configure, somewhere before the DATA ACL, the control option to enable sending DMARC forensic reports .endlist -. subsection +.subsection Example SSECDMARCEXAMPLE +.cindex DMARC example Example usage: .code @@ -42502,13 +42427,13 @@ within &%proxy_protocol_timeout%&, which defaults to 3s. The following expansion variables are usable (&"internal"& and &"external"& here refer to the interfaces of the proxy): -.display -&'proxy_external_address '& IP of host being proxied or IP of remote interface of proxy -&'proxy_external_port '& Port of host being proxied or Port on remote interface of proxy -&'proxy_local_address '& IP of proxy server inbound or IP of local interface of proxy -&'proxy_local_port '& Port of proxy server inbound or Port on local interface of proxy -&'proxy_session '& boolean: SMTP connection via proxy -.endd +.itable none 0 0 2 30* left 70* left +.irow $proxy_external_address "IP of host being proxied or IP of remote interface of proxy" +.irow $proxy_external_port "Port of host being proxied or Port on remote interface of proxy" +.irow $proxy_local_address "IP of proxy server inbound or IP of local interface of proxy" +.irow $proxy_local_port "Port of proxy server inbound or Port on local interface of proxy" +.irow $proxy_session "boolean: SMTP connection via proxy" +.endtable If &$proxy_session$& is set but &$proxy_external_address$& is empty there was a protocol error. The variables &$sender_host_address$& and &$sender_host_port$& @@ -42555,15 +42480,15 @@ is an IP address and any subsequent elements are options. Options are a string =. The list of options is in the following table: -.display -&'auth '& authentication method -&'name '& authentication username -&'pass '& authentication password -&'port '& tcp port -&'tmo '& connection timeout -&'pri '& priority -&'weight '& selection bias -.endd +.itable none 0 0 2 10* left 90* left +.irow &'auth'& "authentication method" +.irow &'name'& "authentication username" +.irow &'pass'& "authentication password" +.irow &'port'& "tcp port" +.irow &'tmo'& "connection timeout" +.irow &'pri'& "priority" +.irow &'weight'& "selection bias" +.endtable More details on each of these options follows: @@ -42679,11 +42604,11 @@ This is usually for use in a Message Submission Agent context, but could be used for any message. If a value is appended it may be: -.display -&`1 `& mandatory downconversion -&`0 `& no downconversion -&`-1 `& if SMTPUTF8 not supported by destination host -.endd +.itable none 0 0 2 5* right 95* left +.irow &`1`& "mandatory downconversion" +.irow &`0`& "no downconversion" +.irow &`-1`& "if SMTPUTF8 not supported by destination host" +.endtable If no value is given, 1 is used. If mua_wrapper is set, the utf8_downconvert control @@ -42783,26 +42708,25 @@ 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 -&`msg:complete after main `& per message -&`msg:defer after transport `& per message per delivery try -&`msg:delivery after transport `& per recipient -&`msg:rcpt:host:defer after transport `& per recipient per host -&`msg:rcpt:defer after transport `& per recipient -&`msg:host:defer after transport `& per host per delivery try; host errors -&`msg:fail:delivery after transport `& per recipient -&`msg:fail:internal after main `& per recipient -&`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 +.itable all 0 0 4 25* left 10* center 15* center 50* left +.row auth:fail after main "per driver per authentication attempt" +.row dane:fail after transport "per connection" +.row msg:complete after main "per message" +.row msg:defer after transport "per message per delivery try" +.row msg:delivery after transport "per recipient" +.row msg:rcpt:host:defer after transport "per recipient per host" +.row msg:rcpt:defer after transport "per recipient" +.row msg:host:defer after transport "per host per delivery try; host errors" +.row msg:fail:delivery after transport "per recipient" +.row msg:fail:internal after main "per recipient" +.row tcp:connect before transport "per connection" +.row tcp:close after transport "per connection" +.row tls:cert before both "per certificate in verification chain" +.row tls:fail:connect after main "per connection" +.row smtp:connect after transport "per connection" +.row smtp:ehlo after transport "per connection" +.endtable New event types may be added in future. The event name is a colon-separated list, defining the type of @@ -42818,24 +42742,25 @@ should define the event action. An additional variable, &$event_data$&, is filled with information varying with the event type: -.display -&`dane:fail `& failure reason -&`msg:defer `& error string -&`msg:delivery `& smtp confirmation message -&`msg:fail:internal `& failure reason -&`msg:fail:delivery `& smtp error message -&`msg:host:defer `& error string -&`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 +.itable all 0 0 2 20* left 80* left +.row auth:fail "smtp response" +.row dane:fail "failure reason" +.row msg:defer "error string" +.row msg:delivery "smtp confirmation message" +.row msg:fail:internal "failure reason" +.row msg:fail:delivery "smtp error message" +.row msg:host:defer "error string" +.row msg:rcpt:host:defer "error string" +.row msg:rcpt:defer "error string" +.row tls:cert "verification chain depth" +.row tls:fail:connect "error string" +.row smtp:connect "smtp banner" +.row smtp:ehlo "smtp ehlo response" +.endtable The :defer events populate one extra variable: &$event_defer_errno$&. -For complex operations an ACL expansion can be used in &%event_action%& +For complex operations an ACL expansion can be used in &%event_action%&, however due to the multiple contexts that Exim operates in during the course of its processing: .ilist @@ -42851,11 +42776,11 @@ a useful way of writing to the main log. The expansion of the event_action option should normally return an empty string. Should it return anything else the following will be forced: -.display -&`tcp:connect `& do not connect -&`tls:cert `& refuse verification -&`smtp:connect `& close connection -.endd +.itable all 0 0 2 20* left 80* left +.row tcp:connect "do not connect" +.row tls:cert "refuse verification" +.row smtp:connect "close connection" +.endtable All other message types ignore the result string, and no other use is made of it.