.set I " "
.macro copyyear
-2019
+2020
.endmacro
. /////////////////////////////////////////////////////////////////////////////
by Exim in conjunction with the &%-MC%& option. It signifies that the
remote host supports the ESMTP &_DSN_& extension.
+.new
+.vitem &%-MCd%&
+.oindex "&%-MCd%&"
+This option is not intended for use by external callers. It is used internally
+by Exim in conjunction with the &%-d%& option
+to pass on an information string on the purpose of the process.
+.wen
+
.vitem &%-MCG%&&~<&'queue&~name'&>
.oindex "&%-MCG%&"
This option is not intended for use by external callers. It is used internally
The &'single-key'& type requires the specification of a file in which to look,
and a single key to search for. The key must be a non-empty string for the
lookup to succeed. The lookup type determines how the file is searched.
+.new
+.cindex "tainted data" "single-key lookups"
+The file string may not be tainted
+.wen
.next
.cindex "query-style lookup" "definition of"
The &'query-style'& type accepts a generalized database query. No particular
.next
.cindex "lookup" "dsearch"
.cindex "dsearch lookup type"
-&(dsearch)&: The given file must be a directory; this is searched for an entry
-whose name is the key by calling the &[lstat()]& function. The key may not
-contain any forward slash characters. If &[lstat()]& succeeds, the result of
-the lookup is the name of the entry, which may be a file, directory,
-symbolic link, or any other kind of directory entry.
+&(dsearch)&: The given file must be an
+.new
+absolute
+.wen
+directory path; this is searched for an entry
+whose name is the key by calling the &[lstat()]& function.
+The key may not
+contain any forward slash characters.
+If &[lstat()]& succeeds then so does the lookup.
.new
.cindex "tainted data" "dsearch result"
-It is regarded as untainted.
+The result is regarded as untainted.
+
+Options for the lookup can be given by appending them after the word "dsearch",
+separated by a comma. Options, if present, are a comma-separated list having
+each element starting with a tag name and an equals.
+
+Two options are supported, for the return value and for filtering match
+candidates.
+The "ret" option requests an alternate result value of
+the entire path for the entry. Example:
+.code
+${lookup {passwd} dsearch,ret=full {/etc}}
+.endd
+The default result is just the requested entry.
+The "filter" option requests that only directory entries of a given type
+are matched. The match value is one of "file", "dir" or "subdir" (the latter
+not matching "." or ".."). Example:
+.code
+${lookup {passwd} dsearch,filter=file {/etc}}
+.endd
+The default matching is for any entry type, including directories
+and symlinks.
.wen
+
An example of how this
lookup can be used to support virtual domains is given in section
&<<SECTvirtualdomains>>&.
.next
.cindex "sqlite lookup type"
.cindex "lookup" "sqlite"
-&(sqlite)&: The format of the query is a filename followed by an SQL statement
+&(sqlite)&: The format of the query is
+new
+an optional filename
+.wen
+followed by an SQL statement
that is passed to an SQLite database. See section &<<SECTsqlite>>&.
.next
or &%redis_servers%&
option (as appropriate) must be set to a colon-separated list of server
information.
+.oindex &%mysql_servers%&
+.oindex &%pgsql_servers%&
+.oindex &%oracle_servers%&
+.oindex &%ibase_servers%&
+.oindex &%redis_servers%&
(For MySQL and PostgreSQL, the global option need not be set if all
queries contain their own server information &-- see section
&<<SECTspeserque>>&.)
escapes whitespace and backslash characters with a backslash.
.section "Specifying the server in the query" "SECTspeserque"
+.new
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 starting the query with
+done by appending a comma-separated option to the query type:
.display
-&`servers=`&&'server1:server2:server3:...'&&`;`&
.endd
+&`,servers=`&&'server1:server2:server3:...'&
+.wen
Each item in the list may take one of two forms:
.olist
If it contains no slashes it is assumed to be just a host name. The appropriate
.endd
In an updating lookup, you could then write:
.code
-${lookup mysql{servers=master; UPDATE ...} }
+${lookup mysql,servers=master {UPDATE ...} }
.endd
That query would then be sent only to the master server. If, on the other hand,
the master is not to be used for reading, and so is not present in the global
option, you can still update it by a query of this form:
.code
-${lookup pgsql{servers=master/db/name/pw; UPDATE ...} }
+${lookup pgsql,servers=master/db/name/pw {UPDATE ...} }
.endd
+.new
+An older syntax places the servers speciification before the qury,
+semicolon separated:
+.code
+${lookup mysql{servers=master; UPDATE ...} }
+.endd
+The new version avoids potential issues with tainted
+arguments in the query, for explicit expansion.
+&*Note*&: server specifications in list-style lookups are still problematic.
+.wen
+
.section "Special MySQL features" "SECID73"
For MySQL, an empty host name or the use of &"localhost"& in &%mysql_servers%&
.cindex "sqlite lookup type"
SQLite is different to the other SQL lookups because a filename is required in
addition to the SQL query. An SQLite database is a single file, and there is no
-daemon as in the other SQL databases. The interface to Exim requires the name
-of the file, as an absolute path, to be given at the start of the query. It is
-separated from the query by white space. This means that the path name cannot
-contain white space. Here is a lookup expansion example:
+daemon as in the other SQL databases.
+
+.new
+.oindex &%sqlite_dbfile%&
+The preferred way of specifying the file is by using the
+&%sqlite_dbfile%& option, set to
+an absolute path.
+.wen
+A deprecated method is available, prefixing the query with the filename
+separated by white space.
+This means that the path name cannot contain white space.
+.cindex "tainted data" "sqlite file"
+It also means that the query cannot use any tainted values, as that taints
+the entire query including the filename - resulting in a refusal to open
+the file.
+
+.new
+Here is a lookup expansion example:
.code
-${lookup sqlite {/some/thing/sqlitedb \
- select name from aliases where id='userx';}}
+sqlite_dbfile = /some/thing/sqlitedb
+...
+${lookup sqlite {select name from aliases where id='userx';}}
.endd
In a list, the syntax is similar. For example:
.code
-domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \
+domainlist relay_to_domains = sqlite;\
select * from relays where ip='$sender_host_address';
.endd
+.wen
The only character affected by the &%quote_sqlite%& operator is a single
quote, which it doubles.
&%domains%& option on a router, the data is preserved in the &$domain_data$&
variable and can be referred to in other options.
.next
+.new
+If the pattern starts with the name of a lookup type
+of either kind (single-key or query-style) it may be
+followed by a command and options,
+The options are lookup-type specific and consist of a comma-separated list.
+Each item starts with a tag and and equals "=".
+.wen
+.next
.cindex "domain list" "matching literal domain name"
If none of the above cases apply, a caseless textual comparison is made
between the pattern and the domain.
.endd
The third argument is a list of options, of which the first element is the timeout
-and must be present if the argument is given.
+and must be present if any options are given.
Further elements are options of form &'name=value'&.
-Two option types is currently recognised: shutdown and tls.
-The first defines whether (the default)
-or not a shutdown is done on the connection after sending the request.
-Example, to not do so (preferred, eg. by some webservers):
+Example:
.code
${readsocket{/socket/name}{request string}{3s:shutdown=no}}
.endd
-The second, tls, controls the use of TLS on the connection. Example:
-.code
-${readsocket{/socket/name}{request string}{3s:tls=yes}}
-.endd
-The default is to not use TLS.
+
+.new
+The following option names are recognised:
+.ilist
+&*cache*&
+Defines if the result data can be cached for use by a later identical
+request in the same process.
+Values are &"yes"& or &"no"& (the default).
+If not, all cached results for this connection specification
+will be invalidated.
+
+.next
+&*shutdown*&
+Defines whether or not a write-shutdown is done on the connection after
+sending the request. Values are &"yes"& (the default) or &"no"&
+(preferred, eg. by some webservers).
+
+.next
+&*tls*&
+Controls the use of TLS on the connection.
+Values are &"yes"& or &"no"& (the default).
If it is enabled, a shutdown as descripbed above is never done.
+.endlist
+.wen
+
A fourth argument allows you to change any newlines that are in the data
that is read, in the same way as for &%readfile%& (see above). This example
.cindex "tainted data"
If the origin of the data is an incoming message,
the result of expanding this variable is tainted.
-See also &$domain_verified$&.
+When un untainted version is needed, one should be obtained from
+looking up the value in a local (therefore trusted) database.
+Often &$domain_data$& is usable in this role.
.wen
For virtual users, store a suitable pathname component in the database
which is used for account name validation, and use that retrieved value
rather than this variable.
+Often &$local_part_data$& is usable in this role.
If needed, use a router &%address_data%& or &%set%& option for
the retrieved data.
.wen
-.vindex "&$local_part_prefix$&"
-.vindex "&$local_part_prefix_v$&"
-.vindex "&$local_part_suffix$&"
-.vindex "&$local_part_suffix_v$&"
-.cindex affix variables
-If a local part prefix or suffix has been recognized, it is not included in the
-value of &$local_part$& during routing and subsequent delivery. The values of
-any prefix or suffix are in &$local_part_prefix$& and
-&$local_part_suffix$&, respectively.
-.new
-If the affix specification included a wildcard then the portion of
-the affix matched by the wildcard is in
-&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate.
-.wen
-
When a message is being delivered to a file, pipe, or autoreply transport as a
result of aliasing or forwarding, &$local_part$& is set to the local part of
the parent address, not to the filename or command (see &$address_file$& and
available during the rest of the ACL statement. In all other situations, this
variable expands to nothing.
-.vitem &$local_part_prefix$&
-.vindex "&$local_part_prefix$&"
+.vindex &$local_part_prefix$& &&&
+ &$local_part_prefix_v$& &&&
+ &$local_part_suffix$& &&&
+ &$local_part_suffix_v$&
.cindex affix variables
-When an address is being routed or delivered, and a
-specific prefix for the local part was recognized, it is available in this
-variable, having been removed from &$local_part$&.
-
-.new
-.vitem &$local_part_prefix_v$&
-.vindex "&$local_part_prefix_v$&"
-When &$local_part_prefix$& is valid and the prefix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
-
-.vitem &$local_part_suffix$&
-.vindex "&$local_part_suffix$&"
-When an address is being routed or delivered, and a
-specific suffix for the local part was recognized, it is available in this
-variable, having been removed from &$local_part$&.
-
+If a local part prefix or suffix has been recognized, it is not included in the
+value of &$local_part$& during routing and subsequent delivery. The values of
+any prefix or suffix are in &$local_part_prefix$& and
+&$local_part_suffix$&, respectively.
.new
-.vitem &$local_part_suffix_v$&
-.vindex "&$local_part_suffix_v$&"
-When &$local_part_suffix$& is valid and the suffix match used a wildcard,
-the portion matching the wildcard is available in this variable.
-.wen
+.cindex "tainted data"
+If the specification did not include a wildcard then
+the affix variable value is not tainted.
-.new
-.vitem &$local_part_verified$&
-.vindex "&$local_part_verified$&"
-If the router generic option &%check_local_part%& has run successfully,
-this variable has the user database version of &$local_part$&.
-Such values are not tainted and hence usable for building file names.
+If the affix specification included a wildcard then the portion of
+the affix matched by the wildcard is in
+&$local_part_prefix_v$& or &$local_part_suffix_v$& as appropriate,
+and both the whole and varying values are tainted.
.wen
.vitem &$local_scan_data$&
dns_dnssec_ok = 1
.endd
+.new
+In addition, on Linux with glibc 2.31 or newer the resolver library will
+default to stripping out a successful validation status.
+This will break a previously working Exim installation.
+Provided that you do trust the resolver (ie, is on localhost) you can tell
+glibc to pass through any successful validation with a new option in
+&_/etc/resolv.conf_&:
+.code
+options trust-ad
+.endd
+.wen
+
Exim does not perform DNSSEC validation itself, instead leaving that to a
validating resolver (e.g. unbound, or bind with suitable configuration).
.table2
.row &%dkim_verify_hashes%& "DKIM hash methods accepted for signatures"
.row &%dkim_verify_keytypes%& "DKIM key types accepted for signatures"
+.row &%dkim_verify_min_keysizes%& "DKIM key sizes accepted for signatures"
.row &%dkim_verify_signers%& "DKIM domains for which DKIM ACL is run"
.row &%host_lookup%& "host name looked up for these hosts"
.row &%host_lookup_order%& "order of DNS and local name lookups"
required, it must come from the &%-oA%& command line option.
-.option bounce_message_file main string unset
+.option bounce_message_file main string&!! unset
.cindex "bounce message" "customizing"
.cindex "customizing" "bounce message"
This option defines a template file containing paragraphs of text to be used
for constructing bounce messages. Details of the file's contents are given in
-chapter &<<CHAPemsgcust>>&. See also &%warn_message_file%&.
+chapter &<<CHAPemsgcust>>&.
+.new
+.cindex bounce_message_file "tainted data"
+The option is expanded to give the file path, which must be
+absolute and untainted.
+.wen
+See also &%warn_message_file%&.
.option bounce_message_text main string unset
and an order of processing.
Signatures with algorithms not in the list will be ignored.
+
+.new
+.option dkim_verify_min_keysizes main "string list" "rsa=1024 ed25519=250"
+This option gives a list of key sizes which are acceptable in signatures.
+The list is keyed by the algorithm type for the key; the values are in bits.
+Signatures with keys smaller than given by this option will fail verification.
+
+The default enforces the RFC 8301 minimum key size for RSA signatures.
+.wen
+
.option dkim_verify_minimal main boolean false
If set to true, verification of signatures will terminate after the
first success.
If the resolver library does not support DNSSEC then this option has no effect.
+.new
+On Linux with glibc 2.31 or newer this is insufficient, the resolver library
+will default to stripping out a successful validation status.
+This will break a previously working Exim installation.
+Provided that you do trust the resolver (ie, is on localhost) you can tell
+glibc to pass through any successful validation with a new option in
+&_/etc/resolv.conf_&:
+.code
+options trust-ad
+.endd
+.wen
+
.option dns_ipv4_lookup main "domain list&!!" unset
.cindex "IPv6" "DNS lookup for AAAA records"
${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\
by $primary_hostname \
${if def:received_protocol {with $received_protocol }}\
- ${if def:tls_ver { ($tls_ver)}}\
+ ${if def:tls_in_ver { ($tls_in_ver)}}\
${if def:tls_in_cipher_std { tls $tls_in_cipher_std\n\t}}\
(Exim $version_number)\n\t\
${if def:sender_address \
${if def:received_for {\n\tfor $received_for}}
.endd
-The reference to the TLS cipher is omitted when Exim is built without TLS
+The references to the TLS version and cipher are
+omitted when Exim is built without TLS
support. The use of conditional expansions ensures that this works for both
locally generated messages and messages received from remote hosts, giving
header lines such as the following:
See &%uucp_from_pattern%& above.
-.option warn_message_file main string unset
+.option warn_message_file main string&!! unset
.cindex "warning of delay" "customizing the message"
.cindex "customizing" "warning message"
This option defines a template file containing paragraphs of text to be used
for constructing the warning message which is sent by Exim when a message has
been in the queue for a specified amount of time, as specified by
&%delay_warning%&. Details of the file's contents are given in chapter
-&<<CHAPemsgcust>>&. See also &%bounce_message_file%&.
+&<<CHAPemsgcust>>&.
+.new
+.cindex warn_message_file "tainted data"
+The option is expanded to give the file path, which must be
+absolute and untainted.
+.wen
+See also &%bounce_message_file%&.
.option write_rejectlog main boolean true
used. For example:
.code
require_files = mail:/some/file
-require_files = $local_part:$home/.procmailrc
+require_files = $local_part_verified:$home/.procmailrc
.endd
If a user or group name in a &%require_files%& list does not exist, the
&%require_files%& condition fails.
# This transport overrides the group
group_delivery:
driver = appendfile
- file = /var/spool/mail/$local_part
+ file = /var/spool/mail/$local_part_verified
group = mail
.endd
If &%user%& is set for a transport, its value overrides what is set in the
way of handling this requirement:
.code
file = ${if eq{$address_file}{inbox} \
- {/var/mail/$local_part} \
+ {/var/mail/$local_part_verified} \
{${if eq{${substr_0_1:$address_file}}{/} \
{$address_file} \
{$home/mail/$address_file} \
path. The most common settings of this option are variations on one of these
examples:
.code
-file = /var/spool/mail/$local_part
-file = /home/$local_part/inbox
+file = /var/spool/mail/$local_part_verified
+file = /home/$local_part_verified/inbox
file = $home/inbox
.endd
.cindex "&""sticky""& bit"
folders. Consider this example:
.code
maildir_format = true
-directory = /var/mail/$local_part\
+directory = /var/mail/$local_part_verified\
${if eq{$local_part_suffix}{}{}\
{/.${substr_1:$local_part_suffix}}}
maildirfolder_create_regex = /\.[^/]+$
check_local_user
driver = redirect
domains = +local_domains
- file = /central/filters/$local_part
+ file = /central/filters/$local_part_verified
no_verify
allow_filter
allow_freeze
lists:
driver = redirect
domains = lists.example
- file = /usr/lists/$local_part
+ file = ${lookup {$local_part} dsearch,ret=full {/usr/lists}}
forbid_pipe
forbid_file
- errors_to = $local_part-request@lists.example
+ errors_to = ${quote_local_part:$local_part-request}@lists.example
no_more
.endd
This router is skipped for domains other than &'lists.example'&. For addresses
driver = redirect
domains = lists.example
local_part_suffix = -request
- file = /usr/lists/$local_part$local_part_suffix
+ local_parts = ${lookup {$local_part} dsearch,filter=file {/usr/lists}}
+ file = /usr/lists/${local_part_data}-request
no_more
lists_post:
domains = lists.example
senders = ${if exists {/usr/lists/$local_part}\
{lsearch;/usr/lists/$local_part}{*}}
- file = /usr/lists/$local_part
+ file = ${lookup {$local_part} dsearch,ret=full {/usr/lists}}
forbid_pipe
forbid_file
- errors_to = $local_part-request@lists.example
+ errors_to = ${quote_local_part:$local_part-request}@lists.example
no_more
lists_closed:
max_rcpt = 1
return_path = \
${if match {$return_path}{^(.+?)-request@your.dom.example\$}\
- {$1-request+$local_part=$domain@your.dom.example}fail}
+ {${quote_local_part:$1-request+$local_part=$domain}@your.dom.example}fail}
.endd
This has the effect of rewriting the return path (envelope sender) on outgoing
SMTP messages, if the local part of the original return path ends in
transport = remote_smtp
errors_to = \
${if match {$return_path}{^(.+?)-request@your.dom.example\$}}
- {$1-request+$local_part=$domain@your.dom.example}fail}
+ {${quote_local_part:$1-request+$local_part=$domain}@your.dom.example}fail}
no_more
.endd
Before you start sending out messages with VERPed return paths, you must also
.code
my_mailboxes:
driver = appendfile
- file = /var/mail/$domain/$local_part
+ file = /var/mail/$domain/$local_part_data
user = mail
.endd
This uses a directory of mailboxes for each domain. The &%user%& setting is
.option dkim_strict smtp string&!! unset
This option defines how Exim behaves when signing a message that
should be signed fails for some reason. When the expansion evaluates to
-either "1" or "true", Exim will defer. Otherwise Exim will send the message
+either &"1"& or &"true"&, Exim will defer. Otherwise Exim will send the message
unsigned. You can use the &%$dkim_domain%& and &%$dkim_selector%& expansion
variables here.
When unspecified, the header names listed in RFC4871 will be used,
whether or not each header is present in the message.
The default list is available for the expansion in the macro
-"_DKIM_SIGN_HEADERS".
+&"_DKIM_SIGN_HEADERS"&
+.new
+and an oversigning variant is in &"_DKIM_OVERSIGN_HEADERS"&.
+.wen
If a name is repeated, multiple headers by that name (or the absence thereof)
will be signed. The textually later headers in the headers part of the
message are signed first, if there are multiples.
-A name can be prefixed with either an '=' or a '+' character.
-If an '=' prefix is used, all headers that are present with this name
+A name can be prefixed with either an &"="& or a &"+"& character.
+If an &"="& prefix is used, all headers that are present with this name
will be signed.
-If a '+' prefix if used, all headers that are present with this name
+If a &"+"& prefix if used, all headers that are present with this name
will be signed, and one signature added for a missing header with the
name will be appended.
.vitem &%$dkim_key_length%&
Number of bits in the key.
+.new
+Valid only once the key is loaded, which is at the time the header signature
+is verified, which is after the body hash is.
+.wen
Note that RFC 8301 says:
.code
less than 1024 bits as valid signatures.
.endd
-To enforce this you must have a DKIM ACL which checks this variable
-and overwrites the &$dkim_verify_status$& variable as discussed above.
-As EC keys are much smaller, the check should only do this for RSA keys.
+This is enforced by the default setting for the &%dkim_verify_min_keysizes%&
+option.
.endlist
projects / exim.git / blobdiff