-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.88 2010/06/14 18:51:09 pdp Exp $
-.
. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the Exim Manual. It is an xfpt document that is
. converted into DocBook XML for subsequent conversion into printing and online
. /////////////////////////////////////////////////////////////////////////////
.set previousversion "4.75"
-.set version "4.76"
+.set version "4.77"
.set ACL "access control lists (ACLs)"
.set I " "
<author><firstname>Exim</firstname><surname>Maintainers</surname></author>
<authorinitials>EM</authorinitials>
<revhistory><revision>
- <revnumber>4.76</revnumber>
- <date>06 May 2011</date>
+ <revnumber>4.77</revnumber>
+ <date>10 Oct 2011</date>
<authorinitials>EM</authorinitials>
</revision></revhistory>
<copyright><year>2011</year><holder>University of Cambridge</holder></copyright>
The following Exim mailing lists exist:
.table2 140pt
+.row &'exim-announce@exim.org'& "Moderated, low volume announcements list"
.row &'exim-users@exim.org'& "General discussion list"
.row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc."
-.row &'exim-announce@exim.org'& "Moderated, low volume announcements list"
-.row &'exim-future@exim.org'& "Discussion of long-term development"
+.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS"
.endtable
You can subscribe to these lists, change your existing subscriptions, and view
TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto
TLS_INCLUDE=-I/usr/local/openssl/include/
.endd
+.new
+.cindex "pkg-config" "OpenSSL"
+If you have &'pkg-config'& available, then instead you can just use:
+.code
+SUPPORT_TLS=yes
+USE_OPENSSL_PC=openssl
+.endd
+.wen
.cindex "USE_GNUTLS"
If GnuTLS is installed, you should set
.code
TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt
TLS_INCLUDE=-I/usr/gnu/include
.endd
+.new
+.cindex "pkg-config" "GnuTLS"
+If you have &'pkg-config'& available, then instead you can just use:
+.code
+SUPPORT_TLS=yes
+USE_GNUTLS=yes
+USE_GNUTLS_PC=gnutls
+.endd
+.wen
+
You do not need to set TLS_INCLUDE if the relevant directory is already
specified in INCLUDE. Details of how to configure Exim to make use of TLS are
given in chapter &<<CHAPTLS>>&.
binary, attempts to configure Exim to use it cause run time configuration
errors.
+.new
+.cindex "pkg-config" "lookups"
+.cindex "pkg-config" "authenticators"
+Many systems now use a tool called &'pkg-config'& to encapsulate information
+about how to compile against a library; Exim has some initial support for
+being able to use pkg-config for lookups and authenticators. For any given
+makefile variable which starts &`LOOKUP_`& or &`AUTH_`&, you can add a new
+variable with the &`_PC`& suffix in the name and assign as the value the
+name of the package to be queried. The results of querying via the
+&'pkg-config'& command will be added to the appropriate Makefile variables
+with &`+=`& directives, so your version of &'make'& will need to support that
+syntax. For instance:
+.code
+LOOKUP_SQLITE=yes
+LOOKUP_SQLITE_PC=sqlite3
+AUTH_GSASL=yes
+AUTH_GSASL_PC=libgsasl
+AUTH_HEIMDAL_GSSAPI=yes
+AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi
+.endd
+.wen
+
.cindex "Perl" "including support for"
Exim can be linked with an embedded Perl interpreter, allowing Perl
subroutines to be called during string expansion. To enable this facility,
the DB_UNKNOWN option. This enables it to handle any of the types of database
that the library supports, and can be useful for accessing DBM files created by
other applications. (For earlier DB versions, DB_HASH is always used.)
+.new
+.next
+.cindex "lookup" "dbmjz"
+.cindex "lookup" "dbm &-- embedded NULs"
+.cindex "sasldb2"
+.cindex "dbmjz lookup type"
+&(dbmjz)&: This is the same as &(dbm)&, except that the lookup key is
+interpreted as an Exim list; the elements of the list are joined together with
+ASCII NUL characters to form the lookup key. An example usage would be to
+authenticate incoming SMTP calls using the passwords from Cyrus SASL's
+&_/etc/sasldb2_& file with the &(gsasl)& authenticator or Exim's own
+&(cram_md5)& authenticator.
+.wen
.next
.cindex "lookup" "dbmnz"
.cindex "lookup" "dbm &-- terminating zero"
.cindex "binary zero" "in lookup key"
.cindex "Courier"
.cindex "&_/etc/userdbshadow.dat_&"
-.cindex "dmbnz lookup type"
+.cindex "dbmnz lookup type"
&(dbmnz)&: This is the same as &(dbm)&, except that a terminating binary zero
is not included in the key that is passed to the DBM library. You may need this
if you want to look up data in files that are created by or shared with some
chapter &<<CHAPfdlookup>>&. For example:
.code
hold_domains = mysql;select domain from holdlist \
- where domain = '$domain';
+ where domain = '${quote_mysql:$domain}';
.endd
In most cases, the data that is looked up is not used (so for an SQL query, for
example, it doesn't matter what field you select). Exim is interested only in
below in section &<<SECTexpansionitems>>& onwards. Backslash is used as an
escape character, as described in the following section.
+Whether a string is expanded depends upon the context. Usually this is solely
+dependent upon the option for which a value is sought; in this documentation,
+options for which string expansion is performed are marked with † after
+the data type. ACL rules always expand strings. A couple of expansion
+conditions do not expand some of the brace-delimited branches, for security
+reasons.
+
.section "Literal text in expanded strings" "SECTlittext"
As a special case, the numerical value of an empty string is taken as
zero.
+In all cases, a relative comparator OP is testing if <&'string1'&> OP
+<&'string2'&>; the above example is checking if &$message_size$& is larger than
+10M, not if 10M is larger than &$message_size$&.
+
.vitem &*bool&~{*&<&'string'&>&*}*&
.cindex "expansion" "boolean parsing"
This condition turns a string holding a true or false representation into
a boolean state. It parses &"true"&, &"false"&, &"yes"& and &"no"&
(case-insensitively); also positive integer numbers map to true if non-zero,
-false if zero. Leading and trailing whitespace is ignored.
+false if zero.
+An empty string is treated as false.
+Leading and trailing whitespace is ignored;
+thus a string consisting only of whitespace is false.
All other string values will result in expansion failure.
When combined with ACL variables, this expansion condition will let you
includes the case of letters, whereas for &%gti%& the comparison is
case-independent.
+.new
+.vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
+ &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
+.cindex "string" "comparison"
+.cindex "list" "iterative conditions"
+Both strings are expanded; the second string is treated as a list of simple
+strings; if the first string is a member of the second, then the condition
+is true.
+
+These are simpler to use versions of the more powerful &*forany*& condition.
+Examples, and the &*forany*& equivalents:
+.code
+${if inlist{needle}{foo:needle:bar}}
+ ${if forany{foo:needle:bar}{eq{$item}{needle}}}
+${if inlisti{Needle}{fOo:NeeDLE:bAr}}
+ ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}}
+.endd
+.wen
+
.vitem &*isip&~{*&<&'string'&>&*}*& &&&
&*isip4&~{*&<&'string'&>&*}*& &&&
&*isip6&~{*&<&'string'&>&*}*&
.vitem &*match_ip&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
.cindex "&%match_ip%& expansion condition"
+.new
This condition matches an IP address to a list of IP address patterns. It must
be followed by two argument strings. The first (after expansion) must be an IP
-address or an empty string. The second (after expansion) is a restricted host
+address or an empty string. The second (not expanded) is a restricted host
list that can match only an IP address, not a host name. For example:
+.wen
.code
${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
.endd
.endd
.endlist ilist
+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+
Consult section &<<SECThoslispatip>>& for further details of these patterns.
.vitem &*match_local_part&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
have their local parts matched casefully. Domains are always matched
caselessly.
+.new
+Note that <&'string2'&> is not itself subject to string expansion, unless
+Exim was built with the EXPAND_LISTMATCH_RHS option.
+.wen
+
&*Note*&: Host lists are &'not'& supported in this way. This is because
hosts have two identities: a name and an IP address, and it is not clear
how to specify cleanly how such a test would work. However, IP addresses can be
negative response to an AUTH command, including (for example) an attempt to use
an undefined mechanism.
+.new
+.vitem &$av_failed$&
+.cindex "content scanning" "AV scanner failure"
+This variable is available when Exim is compiled with the content-scanning
+extension. It is set to &"0"& by default, but will be set to &"1"& if any
+problem occurs with the virus scanner (specified by &%av_scanner%&) during
+the ACL malware condition.
+.wen
+
.vitem &$body_linecount$&
.cindex "message body" "line count"
.cindex "body of message" "line count"
.cindex "binary zero" "in message body"
.vindex "&$body_zerocount$&"
When a message is being received or delivered, this variable contains the
-number of binary zero bytes in the message's body.
+number of binary zero bytes (ASCII NULs) in the message's body.
.vitem &$bounce_recipient$&
.vindex "&$bounce_recipient$&"
command, which can be found in the separate document entitled &'Exim's
interfaces to mail filtering'&.
+.new
+.vitem &$tls_bits$&
+.vindex "&$tls_bits$&"
+Contains an approximation of the TLS cipher's bit-strength; the meaning of
+this depends upon the TLS implementation used.
+If TLS has not been negotiated, the value will be 0.
+The value of this is automatically fed into the Cyrus SASL authenticator
+when acting as a server, to specify the "external SSF" (a SASL term).
+.wen
+
.vitem &$tls_certificate_verified$&
.vindex "&$tls_certificate_verified$&"
This variable is set to &"1"& if a TLS certificate was verified when the
This option defines the &"random"& local part that can be used as part of
callout verification. The default value is
.code
-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing
.endd
See section &<<CALLaddparcall>>& for details of how this value is used.
default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M,
some problems may result.
+A value of 0 will disable size limit checking; Exim will still advertise the
+SIZE extension in an EHLO response, but without a limit, so as to permit
+SMTP clients to still indicate the message size along with the MAIL verb.
+
.option move_frozen_messages main boolean false
.cindex "frozen messages" "moving"
section &<<SECTmaildirdelivery>>& below.
-.option maildir_use_size_file appendfile boolean false
+.new
+.option maildir_use_size_file appendfile&!! boolean false
.cindex "maildir format" "&_maildirsize_& file"
-Setting this option true enables support for &_maildirsize_& files. Exim
+The result of string expansion for this option must be a valid boolean value.
+If it is true, it enables support for &_maildirsize_& files. Exim
creates a &_maildirsize_& file in a maildir if one does not exist, taking the
quota from the &%quota%& option of the transport. If &%quota%& is unset, the
value is zero. See &%maildir_quota_directory_regex%& above and section
&<<SECTmaildirdelivery>>& below for further details.
+.wen
.option maildirfolder_create_regex appendfile string unset
.cindex "maildir format" "&_maildirfolder_& file"
.option protocol smtp string smtp
.cindex "LMTP" "over TCP/IP"
+.cindex "ssmtp protocol" "outbound"
+.cindex "TLS" "SSL-on-connect outbound"
+.vindex "&$port$&"
If this option is set to &"lmtp"& instead of &"smtp"&, the default value for
the &%port%& option changes to &"lmtp"&, and the transport operates the LMTP
protocol (RFC 2033) instead of SMTP. This protocol is sometimes used for local
deliveries into closed message stores. Exim also has support for running LMTP
over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
+.new
+If this option is set to &"smtps"&, the default vaule for the &%port%& option
+changes to &"smtps"&, and the transport initiates TLS immediately after
+connecting, as an outbound SSL-on-connect, instead of using STARTTLS to upgrade.
+The Internet standards bodies strongly discourage use of this mode.
+.wen
+
.option retry_include_ip_address smtp boolean true
Exim normally includes both the host name and the IP address in the key it
.code
AUTH_CRAM_MD5=yes
AUTH_CYRUS_SASL=yes
+.new
+AUTH_DOVECOT=yes
+AUTH_GSASL=yes
+AUTH_HEIMDAL_GSSAPI=yes
+.wen
AUTH_PLAINTEXT=yes
AUTH_SPA=yes
.endd
in &_Local/Makefile_&, respectively. The first of these supports the CRAM-MD5
authentication mechanism (RFC 2195), and the second provides an interface to
-the Cyrus SASL authentication library. The third can be configured to support
+the Cyrus SASL authentication library.
+.new
+The third is an interface to Dovecot's authentication system, delegating the
+work via a socket interface.
+The fourth provides an interface to the GNU SASL authentication library, which
+provides mechanisms but typically not data sources.
+The fifth provides direct access to Heimdal GSSAPI, geared for Kerberos, but
+supporting setting a server keytab.
+The sixth can be configured to support
the PLAIN authentication mechanism (RFC 2595) or the LOGIN mechanism, which is
-not formally documented, but used by several MUAs. The fourth authenticator
+not formally documented, but used by several MUAs. The seventh authenticator
supports Microsoft's &'Secure Password Authentication'& mechanism.
+.wen
The authenticators are configured using the same syntax as other drivers (see
section &<<SECTfordricon>>&). If no authenticators are required, no
authenticators, followed by general discussion of the way authentication works
in Exim.
+.new
+&*Beware:*& the meaning of &$auth1$&, &$auth2$&, ... varies on a per-driver and
+per-mechanism basis. Please read carefully to determine which variables hold
+account labels such as usercodes and which hold passwords or other
+authenticating data.
+
+Note that some mechanisms support two different identifiers for accounts: the
+&'authentication id'& and the &'authorization id'&. The contractions &'authn'&
+and &'authz'& are commonly encountered. The American spelling is standard here.
+Conceptually, authentication data such as passwords are tied to the identifier
+used to authenticate; servers may have rules to permit one user to act as a
+second user, so that after login the session is treated as though that second
+user had logged in. That second user is the &'authorization id'&. A robust
+configuration might confirm that the &'authz'& field is empty or matches the
+&'authn'& field. Often this is just ignored. The &'authn'& can be considered
+as verified data, the &'authz'& as an unverified request which the server might
+choose to honour.
+
+A &'realm'& is a text string, typically a domain name, presented by a server
+to a client to help it select an account and credentials to use. In some
+mechanisms, the client and server provably agree on the realm, but clients
+typically can not treat the realm as secure data to be blindly trusted.
+.wen
+
.section "Generic options for authenticators" "SECID168"
is used directly to control authentication. See section &<<SECTplainserver>>&
for details.
+.new
+For the &(gsasl)& authenticator, this option is required for various
+mechanisms; see chapter &<<CHAPgsasl>>& for details.
+.wen
+
For the other authenticators, &%server_condition%& can be used as an additional
authentication or authorization mechanism that is applied after the other
authenticator conditions succeed. If it is set, it is expanded when the
Note that this expansion explicitly forces failure if the lookup fails
because &$auth1$& contains an unknown user name.
+.new
+As another example, if you wish to re-use a Cyrus SASL sasldb2 file without
+using the relevant libraries, you need to know the realm to specify in the
+lookup and then ask for the &"userPassword"& attribute for that user in that
+realm, with:
+.code
+cyrusless_crammd5:
+ driver = cram_md5
+ public_name = CRAM-MD5
+ server_secret = ${lookup{$auth1:mail.example.org:userPassword}\
+ dbmjz{/etc/sasldb2}}
+ server_set_id = $auth1
+.endd
+.wen
.section "Using cram_md5 as a client" "SECID177"
.cindex "options" "&(cram_md5)& authenticator (client)"
Kerberos, note that because of limitations in the GSSAPI interface,
changing the server keytab might need to be communicated down to the Kerberos
layer independently. The mechanism for doing so is dependent upon the Kerberos
-implementation. For example, for Heimdal, the environment variable KRB5_KTNAME
+implementation.
+.new
+For example, for older releases of Heimdal, the environment variable KRB5_KTNAME
may be set to point to an alternative keytab file. Exim will pass this
variable through from its own inherited environment when started as root or the
Exim user. The keytab file needs to be readable by the Exim user.
+With newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the
+environment variable. In practice, for those releases, the Cyrus authenticator
+is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider
+the &(heimdal_gssapi)& authenticator, described in chapter &<<CHAPheimdalgss>>&
+.wen
.section "Using cyrus_sasl as a server" "SECID178"
server_set_id = $auth1
.endd
-.option server_realm cyrus_sasl string unset
+.new
+.option server_realm cyrus_sasl string&!! unset
This specifies the SASL realm that the server claims to be in.
+.wen
.option server_service cyrus_sasl string &`smtp`&
.ecindex IIDdcotauth2
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+.new
+.chapter "The gsasl authenticator" "CHAPgsasl"
+.scindex IIDgsaslauth1 "&(gsasl)& authenticator"
+.scindex IIDgsaslauth2 "authenticators" "&(gsasl)&"
+.cindex "authentication" "GNU SASL"
+.cindex "authentication" "SASL"
+.cindex "authentication" "EXTERNAL"
+.cindex "authentication" "ANONYMOUS"
+.cindex "authentication" "PLAIN"
+.cindex "authentication" "LOGIN"
+.cindex "authentication" "DIGEST-MD5"
+.cindex "authentication" "CRAM-MD5"
+.cindex "authentication" "SCRAM-SHA-1"
+The &(gsasl)& authenticator provides server integration for the GNU SASL
+library and the mechanisms it provides. This is new as of the 4.78 release
+and there are a few areas where the library does not let Exim smoothly
+scale to handle future authentication mechanisms, so no guarantee can be
+made that any particular new authentication mechanism will be supported
+without code changes in Exim.
+
+
+.option server_channelbinding gsasl bool false
+Some authentication mechanisms are able to use external context at both ends
+of the session to bind the authentication to that context, and fail the
+authentication process if that context differs. Specifically, some TLS
+ciphersuites can provide identifying information about the cryptographic
+context.
+
+This means that certificate identity and verification becomes a non-issue,
+as a man-in-the-middle attack will cause the correct client and server to
+see different identifiers and authentication will fail.
+
+This is currently only supported when using the GnuTLS library. This is
+only usable by mechanisms which support "channel binding"; at time of
+writing, that's the SCRAM family.
+
+This defaults off to ensure smooth upgrade across Exim releases, in case
+this option causes some clients to start failing. Some future release
+of Exim may switch the default to be true.
+
+
+.option server_hostname gsasl string&!! "see below"
+This option selects the hostname that is used when communicating with the
+library. The default value is &`$primary_hostname`&.
+Some mechanisms will use this data.
+
+
+.option server_mech gsasl string "see below"
+This option selects the authentication mechanism this driver should use. The
+default is the value of the generic &%public_name%& option. This option allows
+you to use a different underlying mechanism from the advertised name. For
+example:
+.code
+sasl:
+ driver = gsasl
+ public_name = X-ANYTHING
+ server_mech = CRAM-MD5
+ server_set_id = $auth1
+.endd
+
+
+.option server_password gsasl string&!! unset
+Various mechanisms need access to the cleartext password on the server, so
+that proof-of-possession can be demonstrated on the wire, without sending
+the password itself.
+
+The data available for lookup varies per mechanism.
+In all cases, &$auth1$& is set to the &'authentication id'&.
+The &$auth2$& variable will always be the &'authorization id'& (&'authz'&)
+if available, else the empty string.
+The &$auth3$& variable will always be the &'realm'& if available,
+else the empty string.
+
+A forced failure will cause authentication to defer.
+
+If using this option, it may make sense to set the &%server_condition%&
+option to be simply "true".
+
+
+.option server_realm gsasl string&!! unset
+This specifies the SASL realm that the server claims to be in.
+Some mechanisms will use this data.
+
+
+.option server_scram_iter gsasl string&!! unset
+This option provides data for the SCRAM family of mechanisms.
+&$auth1$& is not available at evaluation time.
+(This may change, as we receive feedback on use)
+
+
+.option server_scram_salt gsasl string&!! unset
+This option provides data for the SCRAM family of mechanisms.
+&$auth1$& is not available at evaluation time.
+(This may change, as we receive feedback on use)
+
+
+.option server_service gsasl string &`smtp`&
+This is the SASL service that the server claims to implement.
+Some mechanisms will use this data.
+
+
+.section "&(gsasl)& auth variables" "SECTgsaslauthvar"
+.vindex "&$auth1$&, &$auth2$&, etc"
+These may be set when evaluating specific options, as detailed above.
+They will also be set when evaluating &%server_condition%&.
+
+Unless otherwise stated below, the &(gsasl)& integration will use the following
+meanings for these variables:
+
+.ilist
+.vindex "&$auth1$&"
+&$auth1$&: the &'authentication id'&
+.next
+.vindex "&$auth2$&"
+&$auth2$&: the &'authorization id'&
+.next
+.vindex "&$auth3$&"
+&$auth3$&: the &'realm'&
+.endlist
+
+On a per-mechanism basis:
+
+.ilist
+.cindex "authentication" "EXTERNAL"
+EXTERNAL: only &$auth1$& is set, to the possibly empty &'authorization id'&;
+the &%server_condition%& option must be present.
+.next
+.cindex "authentication" "ANONYMOUS"
+ANONYMOUS: only &$auth1$& is set, to the possibly empty &'anonymous token'&;
+the &%server_condition%& option must be present.
+.next
+.cindex "authentication" "GSSAPI"
+GSSAPI: &$auth1$& will be set to the &'GSSAPI Display Name'&;
+&$auth2$& will be set to the &'authorization id'&,
+the &%server_condition%& option must be present.
+.endlist
+
+An &'anonymous token'& is something passed along as an unauthenticated
+identifier; this is analogous to FTP anonymous authentication passing an
+email address, or software-identifier@, as the "password".
+
+
+An example showing the password having the realm specified in the callback
+and demonstrating a Cyrus SASL to GSASL migration approach is:
+.code
+gsasl_cyrusless_crammd5:
+ driver = gsasl
+ public_name = CRAM-MD5
+ server_realm = imap.example.org
+ server_password = ${lookup{$auth1:$auth3:userPassword}\
+ dbmjz{/etc/sasldb2}{$value}fail}
+ server_set_id = ${quote:$auth1}
+ server_condition = yes
+.endd
+
+.wen
+
+. ////////////////////////////////////////////////////////////////////////////
+. ////////////////////////////////////////////////////////////////////////////
+
+.new
+.chapter "The heimdal_gssapi authenticator" "CHAPheimdalgss"
+.scindex IIDheimdalgssauth1 "&(heimdal_gssapi)& authenticator"
+.scindex IIDheimdalgssauth2 "authenticators" "&(heimdal_gssapi)&"
+.cindex "authentication" "GSSAPI"
+.cindex "authentication" "Kerberos"
+The &(heimdal_gssapi)& authenticator provides server integration for the
+Heimdal GSSAPI/Kerberos library, permitting Exim to set a keytab pathname
+reliably.
+
+.option server_hostname heimdal_gssapi string&!! "see below"
+This option selects the hostname that is used, with &%server_service%&,
+for constructing the GSS server name, as a &'GSS_C_NT_HOSTBASED_SERVICE'&
+identifier. The default value is &`$primary_hostname`&.
+
+.option server_keytab heimdal_gssapi string&!! unset
+If set, then Heimdal will not use the system default keytab (typically
+&_/etc/krb5.keytab_&) but instead the pathname given in this option.
+The value should be a pathname, with no &"file:"& prefix.
+
+.option server_service heimdal_gssapi string&!! "smtp"
+This option specifies the service identifier used, in conjunction with
+&%server_hostname%&, for building the identifer for finding credentials
+from the keytab.
+
+
+.section "&(heimdal_gssapi)& auth variables" "SECTheimdalgssauthvar"
+Beware that these variables will typically include a realm, thus will appear
+to be roughly like an email address already. The &'authzid'& in &$auth2$& is
+not verified, so a malicious client can set it to anything.
+
+The &$auth1$& field should be safely trustable as a value from the Key
+Distribution Center. Note that these are not quite email addresses.
+Each identifier is for a role, and so the left-hand-side may include a
+role suffix. For instance, &"joe/admin@EXAMPLE.ORG"&.
+
+.vindex "&$auth1$&, &$auth2$&, etc"
+.ilist
+.vindex "&$auth1$&"
+&$auth1$&: the &'authentication id'&, set to the GSS Display Name.
+.next
+.vindex "&$auth2$&"
+&$auth2$&: the &'authorization id'&, sent within SASL encapsulation after
+authentication. If that was empty, this will also be set to the
+GSS Display Name.
+.endlist
+
+.wen
+
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
For &%gnutls_require_mac%&, the recognized names are SHA (synonym SHA1), and
MD5. The default list contains SHA, MD5.
-For &%gnutls_require_protocols%&, the recognized names are TLS1 and SSL3.
-The default list contains TLS1, SSL3.
+.new
+For &%gnutls_require_protocols%&, the recognized names are TLS1.2, TLS1.1,
+TLS1.0, (TLS1) and SSL3.
+The default list contains TLS1.2, TLS1.1, TLS1.0, SSL3.
+TLS1 is an alias for TLS1.0, for backwards compatibility.
+For sufficiently old versions of the GnuTLS library, TLS1.2 or TLS1.1 might
+not be supported and will not be recognised by Exim.
+.wen
In a server, the order of items in these lists is unimportant. The server
advertises the availability of all the relevant cipher suites. However, in a
&`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT
ACL.
-Internally, Exim appends the smoothing constant &'p'& and the options onto the
-lookup key because they alter the meaning of the stored data. This is not true
-for the limit &'m'&, so you can alter the configured maximum rate and Exim will
-still remember clients' past behaviour, but if you alter the other ratelimit
-parameters Exim forgets past behaviour.
+Each &%ratelimit%& condition can have up to four options. A &%per_*%& option
+specifies what Exim measures the rate of, for example messages or recipients
+or bytes. You can adjust the measurement using the &%unique=%& and/or
+&%count=%& options. You can also control when Exim updates the recorded rate
+using a &%strict%&, &%leaky%&, or &%readonly%& option. The options are
+separated by a slash, like the other parameters. They may appear in any order.
+
+Internally, Exim appends the smoothing constant &'p'& onto the lookup key with
+any options that alter the meaning of the stored data. The limit &'m'& is not
+stored, so you can alter the configured maximum rate and Exim will still
+remember clients' past behaviour. If you change the &%per_*%& mode or add or
+remove the &%unique=%& option, the lookup key changes so Exim will forget past
+behaviour. The lookup key is not affected by changes to the update mode and
+the &%count=%& option.
-Each &%ratelimit%& condition can have up to three options. One option
-specifies what Exim measures the rate of, and the second specifies how Exim
-handles excessively fast clients. The third option can be &`noupdate`&, to
-disable updating of the ratelimiting database (see section &<<rearatdat>>&).
-The options are separated by a slash, like the other parameters. They may
-appear in any order.
.section "Ratelimit options for what is being measured" "ratoptmea"
-The &%per_conn%& option limits the client's connection rate.
+.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
+&%acl_not_smtp_start%& ACLs.
The &%per_mail%& option limits the client's rate of sending messages. This is
-the default if none of the &%per_*%& options is specified.
-
-The &%per_byte%& option limits the sender's email bandwidth. Note that it is
-best to use this option in the DATA ACL; if it is used in an earlier ACL it
-relies on the SIZE parameter specified by the client in its MAIL command,
-which may be inaccurate or completely missing. You can follow the limit &'m'&
-in the configuration with K, M, or G to specify limits in kilobytes,
-megabytes, or gigabytes, respectively.
-
-The &%per_rcpt%& option causes Exim to limit the rate at which
-recipients are accepted. To be effective, it would need to be used in
-either the &%acl_smtp_rcpt%& or the &%acl_not_smtp%& ACL. In the
-&%acl_smtp_rcpt%& ACL, the number of recipients is incremented by one.
-In the case of a locally submitted message in the &%acl_not_smtp%& ACL,
-the number of recipients is incremented by the &%$recipients_count%&
-for the entire message. Note that in either case the rate limiting
-engine will see a message with many recipients as a large high-speed
-burst.
+the default if none of the &%per_*%& options is specified. It can be used in
+&%acl_smtp_mail%&, &%acl_smtp_rcpt%&, &%acl_smtp_predata%&, &%acl_smtp_mime%&,
+&%acl_smtp_data%&, or &%acl_not_smtp%&.
+
+The &%per_byte%& option limits the sender's email bandwidth. It can be used in
+the same ACLs as the &%per_mail%& option, though it is best to use this option
+in the &%acl_smtp_mime%&, &%acl_smtp_data%& or &%acl_not_smtp%& ACLs; if it is
+used in an earlier ACL, Exim relies on the SIZE parameter given by the client
+in its MAIL command, which may be inaccurate or completely missing. You can
+follow the limit &'m'& in the configuration with K, M, or G to specify limits
+in kilobytes, megabytes, or gigabytes, respectively.
+
+The &%per_rcpt%& option causes Exim to limit the rate at which recipients are
+accepted. It can be used in the &%acl_smtp_rcpt%&, &%acl_smtp_predata%&,
+&%acl_smtp_mime%&, &%acl_smtp_data%&, or &%acl_smtp_rcpt%& ACLs. In
+&%acl_smtp_rcpt%& the rate is updated one recipient at a time; in the other
+ACLs the rate is updated with the total recipient count in one go. Note that
+in either case the rate limiting engine will see a message with many
+recipients as a large high-speed burst.
+
+The &%per_addr%& option is like the &%per_rcpt%& option, except it counts the
+number of different recipients that the client has sent messages to in the
+last time period. That is, if the client repeatedly sends messages to the same
+recipient, its measured rate is not increased. This option can only be used in
+&%acl_smtp_rcpt%&.
The &%per_cmd%& option causes Exim to recompute the rate every time the
-condition is processed. This can be used to limit the SMTP command rate.
-This command is essentially an alias of &%per_rcpt%& to make it clear
-that the effect is to limit the rate at which individual commands,
-rather than recipients, are accepted.
+condition is processed. This can be used to limit the rate of any SMTP
+command. If it is used in multiple ACLs it can limit the aggregate rate of
+multiple different commands.
+
+The &%count=%& option can be used to alter how much Exim adds to the client's
+measured rate. For example, the &%per_byte%& option is equivalent to
+&`per_mail/count=$message_size`&. If there is no &%count=%& option, Exim
+increases the measured rate by one (except for the &%per_rcpt%& option in ACLs
+other than &%acl_smtp_rcpt%&). The count does not have to be an integer.
+
+The &%unique=%& option is described in section &<<ratoptuniq>>& below.
+
+
+.section "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%&
+mode, and the next section describes the &%strict%& and &%leaky%& modes.
+
+If the &%ratelimit%& condition is used in &%readonly%& mode, Exim looks up a
+previously-computed rate to check against the limit.
+
+For example, you can test the client's sending rate and deny it access (when
+it is too fast) in the connect ACL. If the client passes this check then it
+can go on to send a message, in which case its recorded rate will be updated
+in the MAIL ACL. Subsequent connections from the same client will check this
+new rate.
+.code
+acl_check_connect:
+ deny ratelimit = 100 / 5m / readonly
+ log_message = RATE CHECK: $sender_rate/$sender_rate_period \
+ (max $sender_rate_limit)
+# ...
+acl_check_mail:
+ warn ratelimit = 100 / 5m / strict
+ log_message = RATE UPDATE: $sender_rate/$sender_rate_period \
+ (max $sender_rate_limit)
+.endd
-.section "Ratelimit options for handling fast clients" "ratophanfas"
+If Exim encounters multiple &%ratelimit%& conditions with the same key when
+processing a message then it may increase the client's measured rate more than
+it should. For example, this will happen if you check the &%per_rcpt%& option
+in both &%acl_smtp_rcpt%& and &%acl_smtp_data%&. However it's OK to check the
+same &%ratelimit%& condition multiple times in the same ACL. You can avoid any
+multiple update problems by using the &%readonly%& option on later ratelimit
+checks.
+
+The &%per_*%& options described above do not make sense in some ACLs. If you
+use a &%per_*%& option in an ACL where it is not normally permitted then the
+update mode defaults to &%readonly%& and you cannot specify the &%strict%& or
+&%leaky%& modes. In other ACLs the default update mode is &%leaky%& (see the
+next section) so you must specify the &%readonly%& option explicitly.
+
+
+.section "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
-&%strict%& or &%leaky%& options. This is independent of the other
+&%strict%& or &%leaky%& update modes. This is independent of the other
counter-measures (such as rejecting the message) that may be specified by the
-rest of the ACL. The default mode is leaky, which avoids a sender's
-over-aggressive retry rate preventing it from getting any email through.
+rest of the ACL.
-The &%strict%& option means that the client's recorded rate is always
-updated. The effect of this is that Exim measures the client's average rate
-of attempts to send email, which can be much higher than the maximum it is
-actually allowed. If the client is over the limit it may be subjected to
-counter-measures by the ACL until it slows down below the maximum rate. If
-the client stops attempting to send email for the time specified in the &'p'&
-parameter then its computed rate will decay exponentially to 37% of its peak
-value. You can work out the time (the number of smoothing periods) that a
-client is subjected to counter-measures after an over-limit burst with this
-formula:
-.code
- ln(peakrate/maxrate)
-.endd
The &%leaky%& (default) option means that the client's recorded rate is not
updated if it is above the limit. The effect of this is that Exim measures the
client's average rate of successfully sent email, which cannot be greater than
counter-measures (as specified in the ACL), but it will still be able to send
email at the configured maximum rate, whatever the rate of its attempts. This
is generally the better choice if you have clients that retry automatically.
+For example, it does not prevent a sender with an over-aggressive retry rate
+from getting any email through.
+
+The &%strict%& option means that the client's recorded rate is always
+updated. The effect of this is that Exim measures the client's average rate
+of attempts to send email, which can be much higher than the maximum it is
+actually allowed. If the client is over the limit it may be subjected to
+counter-measures by the ACL. It must slow down and allow sufficient time to
+pass that its computed rate falls below the maximum before it can send email
+again. The time (the number of smoothing periods) it must wait and not
+attempt to send mail can be calculated with this formula:
+.code
+ ln(peakrate/maxrate)
+.endd
+
+
+.section "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
+mechanism to count the number of different recipients that the client has
+sent messages to in the last time period; it is equivalent to
+&`per_rcpt/unique=$local_part@$domain`&. You could use this feature to
+measure the rate that a client uses different sender addresses with the
+options &`per_mail/unique=$sender_address`&.
+
+For each &%ratelimit%& key Exim stores the set of &%unique=%& values that it
+has seen for that key. The whole set is thrown away when it is older than the
+rate smoothing period &'p'&, so each different event is counted at most once
+per period. In the &%leaky%& update mode, an event that causes the client to
+go over the limit is not added to the set, in the same way that the client's
+recorded rate is not updated in the same situation.
+
+When you combine the &%unique=%& and &%readonly%& options, the specific
+&%unique=%& value is ignored, and Exim just retrieves the client's stored
+rate.
+
+The &%unique=%& mechanism needs more space in the ratelimit database than the
+other &%ratelimit%& options in order to store the event set. The number of
+unique values is potentially as large as the rate limit, so the extra space
+required increases with larger limits.
+
+The uniqueification is not perfect: there is a small probability that Exim
+will think a new event has happened before. If the sender's rate is less than
+the limit, Exim should be more than 99.9% correct. However in &%strict%& mode
+the measured rate can go above the limit, in which case Exim may under-count
+events by a significant margin. Fortunately, if the rate is high enough (2.7
+times the limit) that the false positive rate goes above 9%, then Exim will
+throw away the over-full event set before the measured rate falls below the
+limit. Therefore the only harm should be that exceptionally high sending rates
+are logged incorrectly; any countermeasures you configure will be as effective
+as intended.
+
.section "Using rate limiting" "useratlim"
Exim's other ACL facilities are used to define what counter-measures are taken
hints, the callout cache, and ratelimit data).
-.section "Reading ratelimit data without updating" "rearatdat"
-.cindex "rate limitint" "reading data without updating"
-If the &%noupdate%& option is present on a &%ratelimit%& ACL condition, Exim
-computes the rate and checks the limit as normal, but it does not update the
-saved data. This means that, in relevant ACLs, it is possible to lookup the
-existence of a specified (or auto-generated) ratelimit key without incrementing
-the ratelimit counter for that key. In order for this to be useful, another ACL
-entry must set the rate for the same key (otherwise it will always be zero).
-For example:
-.code
-acl_check_connect:
- deny ratelimit = 100 / 5m / strict / per_cmd / noupdate
- log_message = RATE: $sender_rate/$sender_rate_period \
- (max $sender_rate_limit)
-.endd
-.display
-&'... some other logic and tests...'&
-.endd
-.code
-acl_check_mail:
- warn ratelimit = 100 / 5m / strict / per_cmd
- condition = ${if le{$sender_rate}{$sender_rate_limit}}
- logwrite = RATE UPDATE: $sender_rate/$sender_rate_period \
- (max $sender_rate_limit)
-.endd
-In this example, the rate is tested and used to deny access (when it is too
-high) in the connect ACL, but the actual computation of the remembered rate
-happens later, on a per-command basis, in another ACL.
-
-
.section "Address verification" "SECTaddressverification"
.cindex "verifying address" "options for"
really random &-- it is defined by the expansion of the option
&%callout_random_local_part%&, which defaults to
.code
-$primary_host_name-$tod_epoch-testing
+$primary_hostname-$tod_epoch-testing
.endd
The idea here is to try to determine whether the remote host accepts all local
parts without checking. If it does, there is no point in doing callouts for
A colon-separated list of names of headers included in the signature.
.vitem &%$dkim_key_testing%&
"1" if the key record has the "testing" flag set, "0" if not.
-.vitem &%$dkim_key_nosubdomaining%&
+.vitem &%$nosubdomains%&
"1" if the key record forbids subdomaining, "0" otherwise.
.vitem &%$dkim_key_srvtype%&
Service type (tag s=) from the key record. Defaults to "*" if not specified
projects / exim.git / blobdiff