. 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)"
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.
.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
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
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"
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
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:
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
.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,
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.
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.
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,
.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.
${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"
.endd
can be used for de-tainting.
Any previous &$value$& is restored after the if.
-.wen
.vitem &*isip&~{*&<&'string'&>&*}*& &&&
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"
.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.
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.
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"
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
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"
(described under &%transport_filter%& in chapter &<<CHAPtransportgeneric>>&).
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$&"
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$&
.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"
.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"
.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
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
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"
.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.
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
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
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
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.
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,
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
Exim, and each argument is separately expanded, as described in section
&<<SECThowcommandrun>>& above.
-.new
.cindex "tainted data"
No part of the resulting command may be tainted.
-.wen
.option environment pipe string&!! unset
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
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
.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.
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
See the &%dnssec_request_domains%& router and transport options.
See section &<<SECDANE>>&.
-.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
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.
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"
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,
non-SMTP ACLs. It causes the incoming message to be scanned for a match with
any of the regular expressions. For details, see chapter &<<CHAPexiscan>>&.
-.new
.vitem &*seen&~=&~*&<&'parameters'&>
.cindex "&%sseen%& 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 &<<SECTseen>>&.
-.wen
.vitem &*sender_domains&~=&~*&<&'domain&~list'&>
.cindex "&%sender_domains%& ACL condition"
.endd
-.new
.section "Previously seen user and hosts" "SECTseen"
.cindex "&%sseen%& ACL condition"
.cindex greylisting
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"
clients when the SMTP PIPELINING extension is in use. The flushing can be
disabled by using a &%control%& modifier to set &%no_callout_flush%&.
-.new
.cindex "tainted data" "de-tainting"
.cindex "de-tainting" "using receipient 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.
-.wen
.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
&"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
A log file path may also contain &`%D`& or &`%M`& if datestamped log filenames
are in use &-- see section &<<SECTdatlogfil>>& 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
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.
.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
.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
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
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.
The following word specifies a variable,
and the remainder of the item depends on the variable.
-.wen
.vlist
.vitem "&%-acl%&&~<&'number'&>&~<&'length'&>"
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,
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,
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
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:
.itable all 0 0 4 1pt left 1pt center 1pt center 1pt left
.irow dane:fail after transport "per connection"
.irow smtp:connect after transport "per connection"
.irow smtp:ehlo after transport "per connection"
.endtable
-.wen
New event types may be added in future.
The event name is a colon-separated list, defining the type of
git://git.exim.org / exim.git / blobdiff