-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.55 2009/10/14 14:48:40 nm4 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.79 2010/06/05 23:50:18 pdp Exp $
.
. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the Exim Manual. It is an xfpt document that is
. the <bookinfo> element must also be updated for each new edition.
. /////////////////////////////////////////////////////////////////////////////
-.set previousversion "4.69"
-.set version "4.70"
+.set previousversion "4.71"
+.set version "4.72"
.set ACL "access control lists (ACLs)"
.set I " "
<bookinfo>
<title>Specification of the Exim Mail Transfer Agent</title>
<titleabbrev>The Exim MTA</titleabbrev>
-<date>09 June 2009</date>
-<author><firstname>Philip</firstname><surname>Hazel</surname></author>
-<authorinitials>PH</authorinitials>
-<affiliation><orgname>University of Cambridge Computing Service</orgname></affiliation>
-<address>New Museums Site, Pembroke Street, Cambridge CB2 3QH, England</address>
+<date>29 May 2010</date>
+<author><firstname>Exim</firstname><surname>Maintainers</surname></author>
+<authorinitials>EM</authorinitials>
<revhistory><revision>
- <revnumber>4.70</revnumber>
- <date>10 June 2009</date>
- <authorinitials>PH</authorinitials>
+ <revnumber>4.72</revnumber>
+ <date>29 May 2010</date>
+ <authorinitials>EM</authorinitials>
</revision></revhistory>
<copyright><year>2009</year><holder>University of Cambridge</holder></copyright>
</bookinfo>
.cindex "options" "router &-- extracting"
.cindex "options" "transport &-- extracting"
+.cindex "options" "authenticator &-- extracting"
If one of the words &%router%&, &%transport%&, or &%authenticator%& is given,
followed by the name of an appropriate driver instance, the option settings for
that driver are output. For example:
settings can be obtained by using &%routers%&, &%transports%&, or
&%authenticators%&.
+.cindex "options" "macro &-- extracting"
+If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%&
+are available, similarly to the drivers. Because macros are sometimes used
+for storing passwords, this option is restricted.
+The output format is one item per line.
.vitem &%-bp%&
.oindex "&%-bp%&"
Exim behaves in exactly the same way as it does when receiving a message via
the listening daemon.
+.vitem &%-bmalware%&&~<&'filename'&>
+.oindex "&%-bmalware%&"
+.cindex "testing", "malware"
+.cindex "malware scan test"
+This debugging option causes Exim to scan the given file,
+using the malware scanning framework. The option of av_scanner influences
+this option, so if av_scanner's value is dependent upon an expansion then
+the expansion should have defaults which apply to this invocation. Exim will
+have changed working directory before resolving the filename, so using fully
+qualified pathnames is advisable. This option requires admin privileges.
+
.vitem &%-bt%&
.oindex "&%-bt%&"
.cindex "testing" "addresses"
.vitem &%-Mvc%&&~<&'message&~id'&>
.oindex "&%-Mvc%&"
.cindex "message" "listing in RFC 2822 format"
-.cindex "listing" "message in RFC 2922 format"
+.cindex "listing" "message in RFC 2822 format"
This option causes a copy of the complete message (header lines plus body) to
be written to the standard output in RFC 2822 format. This option can be used
only by an admin user.
To make the authenticators work, you can use a string expansion
expression like one of the examples in &<<CHAPplaintext>>&.
+Beware that the sequence of the parameters to PLAIN and LOGIN differ; the
+usercode and password are in different positions. &<<CHAPplaintext>>&
+covers both.
+
.ecindex IIDconfiwal
being interpreted as a key terminator. For example:
.code
1.2.3.4: data for 1.2.3.4
-192.168.0.0/16 data for 192.168.0.0/16
+192.168.0.0/16: data for 192.168.0.0/16
"abcd::cdab": data for abcd::cdab
"abcd:abcd::/32" data for abcd:abcd::/32
.endd
It is permitted to specify a space as the separator character. Further
white space is ignored.
+.new
+.cindex "TXT record" "in &(dnsdb)& lookup"
+For TXT records with multiple items of data, only the first item is returned,
+unless a separator for them is specified using a comma after the separator
+character followed immediately by the TXT record item separator. To concatenate
+items without a separator, use a semicolon instead.
+.code
+${lookup dnsdb{>\n,: txt=a.b.example}}
+${lookup dnsdb{>\n; txt=a.b.example}}
+.endd
+It is permitted to specify a space as the separator character. Further
+white space is ignored.
+.wen
+
.section "Pseudo dnsdb record types" "SECID66"
.cindex "MX record" "in &(dnsdb)& lookup"
By default, both the preference value and the host name are returned for
yields an unchanged string.
+.vitem &*${randint:*&<&'n'&>&*}*&
+.cindex "random number"
+This operator returns a somewhat random number which is less than the
+supplied number and is at least 0. The quality of this randomness depends
+on how Exim was built; the values are not suitable for keying material.
+If Exim is linked against OpenSSL then RAND_pseudo_bytes() is used.
+Otherwise, the implementation may be arc4random(), random() seeded by
+srandomdev() or srandom(), or a custom implementation even weaker than
+random().
+
+
+.vitem &*${reverse_ip:*&<&'ipaddr'&>&*}*&
+.cindex "expansion" "IP address"
+This operator reverses an IP address; for IPv4 addresses, the result is in
+dotted-quad decimal form, while for IPv6 addreses the result is in
+dotted-nibble hexadecimal form. In both cases, this is the "natural" form
+for DNS. For example,
+.code
+${reverse_ip:192.0.2.4} and ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.3}
+.endd
+returns
+.code
+4.2.0.192 and 3.0.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2
+.endd
+
+
.vitem &*${rfc2047:*&<&'string'&>&*}*&
.cindex "expansion" "RFC 2047"
.cindex "RFC 2047" "expansion operator"
.code
server_condition = ${if pwcheck{$auth1:$auth2}}
.endd
+Again, for a PLAIN authenticator configuration, this would be:
+.code
+server_condition = ${if pwcheck{$auth2:$auth3}}
+.endd
.vitem &*queue_running*&
.cindex "queue runner" "detecting when delivering from"
.cindex "expansion" "queue runner test"
&$message_body_size$&, &$body_linecount$&, and &$body_zerocount$&.
.cindex "RCPT" "value of &$message_size$&"
-While running an ACL at the time of an SMTP RCPT command, &$message_size$&
+While running a per message ACL (mail/rcpt/predata), &$message_size$&
contains the size supplied on the MAIL command, or -1 if no size was given. The
value may not, of course, be truthful.
.row &%gnutls_require_kx%& "control GnuTLS key exchanges"
.row &%gnutls_require_mac%& "control GnuTLS MAC algorithms"
.row &%gnutls_require_protocols%& "control GnuTLS protocols"
+.row &%gnutls_compat_mode%& "use GnuTLS compatibility mode"
+.row &%openssl_options%& "adjust OpenSSL compatibility options"
.row &%tls_advertise_hosts%& "advertise TLS to these hosts"
.row &%tls_certificate%& "location of server certificate"
.row &%tls_crl%& "certificate revocation list"
This option controls the protocols when GnuTLS is used in an Exim
server. For details, see section &<<SECTreqciphgnu>>&.
+.option gnutls_compat_mode main boolean unset
+This option controls whether GnuTLS is used in compatibility mode in an Exim
+server. This reduces security slightly, but improves interworking with older
+implementations of TLS.
.option headers_charset main string "see below"
This option sets a default character set for translating from encoded MIME
By default, Exim just checks the syntax of HELO and EHLO commands (see
&%helo_accept_junk_hosts%& and &%helo_allow_chars%&). However, some sites like
to do more extensive checking of the data supplied by these commands. The ACL
-condition &`verify`& &`=`& &`helo`& is provided to make this possible.
+condition &`verify = helo`& is provided to make this possible.
Formerly, it was necessary also to set this option (&%helo_try_verify_hosts%&)
to force the check to occur. From release 4.53 onwards, this is no longer
-necessary. If the check has not been done before &`verify`& &`=`& &`helo`& is
+necessary. If the check has not been done before &`verify = helo`& is
encountered, it is done at that time. Consequently, this option is obsolete.
Its specification is retained here for backwards compatibility.
However, the EHLO or HELO command is not rejected if any of the checks
fail. Processing continues, but the result of the check is remembered, and can
-be detected later in an ACL by the &`verify`& &`=`& &`helo`& condition.
+be detected later in an ACL by the &`verify = helo`& condition.
.option helo_verify_hosts main "host list&!!" unset
.cindex "HELO verifying" "mandatory"
.vindex "&$sender_host_name$&"
After any kind of failure, the host name (in &$sender_host_name$&) remains
unset, and &$host_lookup_failed$& is set to the string &"1"&. See also
-&%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and &`verify`& &`=`&
-&`reverse_host_lookup`& in ACLs.
+&%dns_again_means_nonexist%&, &%helo_lookup_domains%&, and
+&`verify = reverse_host_lookup`& in ACLs.
.option host_lookup_order main "string list" &`bydns:byaddr`&
the generic transport option &%message_size_limit%&, which limits the size of
message that an individual transport can process.
+If you use a virus-scanner and set this option to to a value larger than the
+maximum size that your virus-scanner is configured to support, you may get
+failures triggered by large mails. The right size to configure for the
+virus-scanner depends upon what data is passed and the options in use but it's
+probably safest to just set it to a little larger than this value. Eg, with a
+default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
+some problems may result.
+
.option move_frozen_messages main boolean false
.cindex "frozen messages" "moving"
transport driver.
+.option openssl_options main "string list" +dont_insert_empty_fragments
+.cindex "OpenSSL "compatibility options"
+This option allows an administrator to adjust the SSL options applied
+by OpenSSL to connections. It is given as a space-separated list of items,
+each one to be +added or -subtracted from the current value. The default
+value is one option which happens to have been set historically. You can
+remove all options with:
+.code
+openssl_options = -all
+.endd
+This option is only available if Exim is built against OpenSSL. The values
+available for this option vary according to the age of your OpenSSL install.
+The &"all"& value controls a subset of flags which are available, typically
+the bug workaround options. The &'SSL_CTX_set_options'& man page will
+list the values known on your system and Exim should support all the
+&"bug workaround"& options and many of the &"modifying"& options. The Exim
+names lose the leading &"SSL_OP_"& and are lower-cased.
+
+Note that adjusting the options can have severe impact upon the security of
+SSL as used by Exim. It is possible to disable safety checks and shoot
+yourself in the foot in various unpleasant ways. This option should not be
+adjusted lightly. An unrecognised item will be detected at by invoking Exim
+with the &%-bV%& flag.
+
+An example:
+.code
+openssl_options = -all +microsoft_big_sslv3_buffer
+.endd
+
+
.option oracle_servers main "string list" unset
.cindex "Oracle" "server list"
This option provides a list of Oracle servers and associated connection data,
:defer:
:fail:
.endd
-respectively. When a redirection list contains such an item, it applies to the
-entire redirection; any other items in the list are ignored (&':blackhole:'& is
-different). Any text following &':fail:'& or &':defer:'& is placed in the error
-text associated with the failure. For example, an alias file might contain:
+respectively. When a redirection list contains such an item, it applies
+to the entire redirection; any other items in the list are ignored. Any
+text following &':fail:'& or &':defer:'& is placed in the error text
+associated with the failure. For example, an alias file might contain:
.code
X.Employee: :fail: Gone away, no forwarding address
.endd
apply to a command specified as a transport filter.
+.option permit_coredump pipe boolean false
+Normally Exim inhibits core-dumps during delivery. If you have a need to get
+a core-dump of a pipe command, enable this command. This enables core-dumps
+during delivery and affects both the Exim binary and the pipe command run.
+It is recommended that this option remain off unless and until you have a need
+for it and that this only be enabled when needed, as the risk of excessive
+resource consumption can be quite high. Note also that Exim is typically
+installed as a setuid binary and most operating systems will inhibit coredumps
+of these by default, so further OS-specific action may be required.
+
+
.option pipe_as_creator pipe boolean false
.cindex "uid (user id)" "local delivery"
If the generic &%user%& option is not set and this option is true, the delivery
envelope_to_add
check_string = "From "
escape_string = ">From "
+ umask = 077
user = $local_part
group = mail
instead of using the DNS. Of course, that function may in fact use the DNS, but
it may also consult other sources of information such as &_/etc/hosts_&.
-.option gnutls_require_kx main string unset
+.option gnutls_require_kx smtp string unset
This option controls the key exchange mechanisms when GnuTLS is used in an Exim
client. For details, see section &<<SECTreqciphgnu>>&.
-.option gnutls_require_mac main string unset
+.option gnutls_require_mac smtp string unset
This option controls the MAC algorithms when GnuTLS is used in an Exim
client. For details, see section &<<SECTreqciphgnu>>&.
-.option gnutls_require_protocols main string unset
+.option gnutls_require_protocols smtp string unset
This option controls the protocols when GnuTLS is used in an Exim
client. For details, see section &<<SECTreqciphgnu>>&.
+.option gnutls_compat_mode smtp boolean unset
+This option controls whether GnuTLS is used in compatibility mode in an Exim
+server. This reduces security slightly, but improves interworking with older
+implementations of TLS.
+
.option helo_data smtp string&!! "see below"
.cindex "HELO" "argument, setting"
.cindex "EHLO" "argument, setting"
uninterpreted string.
-
.section "Support for different kinds of authentication" "SECID174"
A number of string expansion features are provided for the purpose of
interfacing to different ways of user authentication. These include checking
sasl_plain:
driver = cyrus_sasl
public_name = PLAIN
- server_set_id = $auth1
+ server_set_id = $auth2
.endd
Cyrus SASL does implement the LOGIN authentication method, even though it is
not a standard method. It is disabled by default in the source distribution,
driver = dovecot
public_name = PLAIN
server_socket = /var/run/dovecot/auth-client
- server_set_id = $auth1
+ server_set_id = $auth2
dovecot_ntlm:
driver = dovecot
The &%tls_certificate%& and &%tls_privatekey%& options of the &(smtp)&
transport provide the client with a certificate, which is passed to the server
if it requests it. If the server is Exim, it will request a certificate only if
-&%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client. &*Note*&:
-These options must be set in the &(smtp)& transport for Exim to use TLS when it
-is operating as a client. Exim does not assume that a server certificate (set
-by the global options of the same name) should also be used when operating as a
-client.
+&%tls_verify_hosts%& or &%tls_try_verify_hosts%& matches the client.
-If &%tls_verify_certificates%& is set, it must name a file or,
+If the &%tls_verify_certificates%& option is set on the &(smtp)& transport, it
+must name a file or,
for OpenSSL only (not GnuTLS), a directory, that contains a collection of
expected server certificates. The client verifies the server's certificate
against this collection, taking into account any revoked certificates that are
the current host is abandoned, and the &(smtp)& transport tries to deliver to
alternative hosts, if any.
+ &*Note*&:
+These options must be set in the &(smtp)& transport for Exim to use TLS when it
+is operating as a client. Exim does not assume that a server certificate (set
+by the global options of the same name) should also be used when operating as a
+client.
+
.vindex "&$host$&"
.vindex "&$host_address$&"
All the TLS options in the &(smtp)& transport are expanded before use, with
connection is closed. In these special cases, the QUIT ACL does not run.
-
.section "The not-QUIT ACL" "SECTNOTQUITACL"
.vindex &$acl_smtp_notquit$&
The not-QUIT ACL, specified by &%acl_smtp_notquit%&, is run in most cases when
latter is the one defined by &%acl_smtp_predata%&). Setting it tells Exim that
the current message is a submission from a local MUA. In this case, Exim
operates in &"submission mode"&, and applies certain fixups to the message if
-necessary. For example, it add a &'Date:'& header line if one is not present.
+necessary. For example, it adds a &'Date:'& header line if one is not present.
This control is not permitted in the &%acl_smtp_data%& ACL, because that is too
late (the message has already been created).
.vitem &*control&~=&~suppress_local_fixups*&
.cindex "submission fixups, suppressing"
This control applies to locally submitted (non TCP/IP) messages, and is the
-complement of &`control`& &`=`& &`submission`&. It disables the fixups that are
+complement of &`control = submission`&. It disables the fixups that are
normally applied to locally-submitted messages. Specifically:
.ilist
.ilist
Locally submitted, fixups applied: the default.
.next
-Locally submitted, no fixups applied: use &`control`& &`=`&
-&`suppress_local_fixups`&.
+Locally submitted, no fixups applied: use
+&`control = suppress_local_fixups`&.
.next
Remotely submitted, no fixups applied: the default.
.next
-Remotely submitted, fixups applied: use &`control`& &`=`& &`submission`&.
+Remotely submitted, fixups applied: use &`control = submission`&.
.endlist
For example:
.code
acl_check_connect:
- deny ratelimit = 100 / 5m / strict / noupdate
+ deny ratelimit = 100 / 5m / strict / per_cmd / noupdate
log_message = RATE: $sender_rate/$sender_rate_period \
(max $sender_rate_limit)
.endd
number, and a port, separated by space, as in the second of these examples:
.code
av_scanner = clamd:/opt/clamd/socket
-av_scanner = clamd:192.168.2.100 1234
-.endd
+av_scanner = clamd:192.0.2.3 1234
+av_scanner = clamd:192.0.2.3 1234:local
+.endd
+If the value of av_scanner points to a UNIX socket file or contains the local
+keyword, then the ClamAV interface will pass a filename containing the data
+to be scanned, which will should normally result in less I/O happening and be
+more efficient. Normally in the TCP case, the data is streamed to ClamAV as
+Exim does not assume that there is a common filesystem with the remote host.
+There is an option WITH_OLD_CLAMAV_STREAM in &_src/EDITME_& available, should
+you be running a version of ClamAV prior to 0.95.
If the option is unset, the default is &_/tmp/clamd_&. Thanks to David Saez for
contributing the code for this scanner.
use the &%demime%& condition (see section &<<SECTdemimecond>>&) before the
&%malware%& condition.
+Beware the interaction of Exim's &%message_size_limit%& with any size limits
+imposed by your anti-virus scanner.
+
Here is a very simple scanning example:
.code
deny message = This message contains malware ($malware_name)
characteristics (for example, the same envelope sender) that resolve to the
same set of hosts, in the same order, are sent in a single SMTP transaction,
even if they are for different domains, unless there are more than the setting
-of the &%max_rcpts%& option in the &(smtp)& transport allows, in which case
-they are split into groups containing no more than &%max_rcpts%& addresses
+of the &%max_rcpt%&s option in the &(smtp)& transport allows, in which case
+they are split into groups containing no more than &%max_rcpt%&s addresses
each. If &%remote_max_parallel%& is greater than one, such groups may be sent
in parallel sessions. The order of hosts with identical MX values is not
significant when checking whether addresses can be batched in this way.
Calling the ACL only for existing signatures is not sufficient to build
more advanced policies. For that reason, the global option
&%dkim_verify_signers%&, and a global expansion variable
-&%$dkim_signing_domains%& exist.
+&%$dkim_signers%& exist.
The global option &%dkim_verify_signers%& can be set to a colon-separated
list of DKIM domains or identities for which the ACL &%acl_smtp_dkim%& is
called. It is expanded when the message has been received. At this point,
-the expansion variable &%$dkim_signing_domains%& already contains a colon-
-separated list of signer domains for the message. When &%dkim_verify_signers%&
-is not specified in the main configuration, it defaults as:
+the expansion variable &%$dkim_signers%& already contains a colon-
+separated list of signer domains and identities for the message. When
+&%dkim_verify_signers%& is not specified in the main configuration,
+it defaults as:
.code
-dkim_verify_signers = $dkim_signing_domains
+dkim_verify_signers = $dkim_signers
.endd
This leads to the default behaviour of calling &%acl_smtp_dkim%& for each
DKIM signature in the message. Current DKIM verifiers may want to explicitly
call the ACL for known domains or identities. This would be achieved as follows:
.code
-dkim_verify_signers = paypal.com:ebay.com:$dkim_signing_domains
+dkim_verify_signers = paypal.com:ebay.com:$dkim_signers
.endd
This would result in &%acl_smtp_dkim%& always being called for "paypal.com"
-and "ebay.com", plus all domains that have signatures in the message. You can
-also be more creative in constructing your policy. Example:
+and "ebay.com", plus all domains and identities that have signatures in the message.
+You can also be more creative in constructing your policy. Example:
.code
-dkim_verify_signers = $sender_address_domain:$dkim_signing_domains
+dkim_verify_signers = $sender_address_domain:$dkim_signers
.endd
+If a domain or identity is listed several times in the (expanded) value of
+&%dkim_verify_signers%&, the ACL is only called once for that domain or identity.
+
+
Inside the &%acl_smtp_dkim%&, the following expansion variables are
available (from most to least important):
.vlist
+.vitem &%$dkim_cur_signer%&
+The signer that is being evaluated in this ACL run. This can be domain or
+an identity. This is one of the list items from the expanded main option
+&%dkim_verify_signers%& (see above).
.vitem &%$dkim_verify_status%&
A string describing the general status of the signature. One of
.ilist
&%none%&: There is no signature in the message for the current domain or
-identity.
+identity (as reflected by &%$dkim_cur_signer%&).
.next
&%invalid%&: The signature could not be verified due to a processing error.
More detail is available in &%$dkim_verify_reason%&.
.endlist
.vitem &%$dkim_domain%&
The signing domain. IMPORTANT: This variable is only populated if there is
-ab actual signature in the message. It does NOT neccessarily carry the
-domain that is currently being evaluated. Please use the &%dkim_signers%& ACL
-condition for that.
+an actual signature in the message for the current domain or identity (as
+reflected by &%$dkim_cur_signer%&).
.vitem &%$dkim_identity%&
-The signing identity. IMPORTANT: This variable is only populated if there is
-ab actual signature in the message. It does NOT neccessarily carry the
-identity that is currently being evaluated. Please use the &%dkim_signers%& ACL
-condition for that.
+The signing identity, if present. IMPORTANT: This variable is only populated
+if there is an actual signature in the message for the current domain or
+identity (as reflected by &%$dkim_cur_signer%&).
.vitem &%$dkim_selector%&
The key record selector string
.vitem &%$dkim_algo%&
.vlist
.vitem &%dkim_signers%&
ACL condition that checks a colon-separated list of domains or identities
-for a match against the domain or identity that the ACL is currently verifying.
-This is typically used to restrict an ACL verb to a group of domains or identities, like:
+for a match against the domain or identity that the ACL is currently verifying
+(reflected by &%$dkim_cur_signer%&). This is typically used to restrict an ACL
+verb to a group of domains or identities, like:
.code
# Warn when message apparently from GMail has no signature at all
for more information of what they mean.
.endlist
-
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
projects / exim.git / blobdiff