-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.27 2007/12/01 15:53:55 nm4 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.31 2008/01/29 17:08:54 fanf2 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.68"
-.set version "4.69"
+.set previousversion "4.69"
+.set version "4.70"
.set ACL "access control lists (ACLs)"
.set I " "
.cindex "distribution" "signing details"
.cindex "distribution" "public key"
.cindex "public key for signed distribution"
-The distributions are currently signed with Philip Hazel's GPG key. The
+The distributions are currently signed with Nigel Metheringham's GPG key. The
corresponding public key is available from a number of keyservers, and there is
-also a copy in the file &_Public-Key_&. The signatures for the tar bundles are
+also a copy in the file &_nigel-pubkey.asc_&. The signatures for the tar bundles are
in:
.display
-&_exim-n.nn.tar.gz.sig_&
-&_exim-n.nn.tar.bz2.sig_&
+&_exim-n.nn.tar.gz.asc_&
+&_exim-n.nn.tar.bz2.asc_&
.endd
For each released version, the log of changes is made separately available in a
separate file in the directory &_ChangeLogs_& so that it is possible to
A number of pieces of external code are included in the Exim distribution.
.ilist
-Regular expressions are supported in the main Exim program and in the Exim
-monitor using the freely-distributable PCRE library, copyright ©
-University of Cambridge. The source is distributed in the directory
-&_src/pcre_&. However, this is a cut-down version of PCRE. If you want to use
-the PCRE library in other programs, you should obtain and install the full
-version of the library from
+Regular expressions are supported in the main Exim program and in the
+Exim monitor using the freely-distributable PCRE library, copyright
+© University of Cambridge. The source to a cut down version of PCRE
+used to be distributed in the directory &_src/pcre_&. However, this is
+no longer the case and you will need to use a system PCRE library or
+obtain and install the full version of the library from
&url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
.next
.cindex "cdb" "acknowledgment"
overridden if necessary.
+.section "PCRE library" "SECTdb"
+.cindex "PCRE library"
+Exim no longer has an embedded PCRE library as the vast majority of
+modern systems include PCRE as a system library, although you may need
+to install the PCRE or PCRE development package for your operating
+system. If your system has a normal PCRE installation the Exim build
+process will need no further configuration. If the library or the
+headers are in an unusual location you will need to set the PCRE_LIBS
+and INCLUDE directives appropriately. If your operating system has no
+PCRE support then you will need to obtain and build the current PCRE
+from &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/).
+
.section "DBM libraries" "SECTdb"
.cindex "DBM libraries" "discussion of"
.cindex "hints database" "DBM files used for"
send in each time interval. It also specifies the number of messages permitted
in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'&
constant, you can allow a client to send more messages in a burst without
-changing its overall sending rate limit. Conversely, if &'m'& and &'p'& are
+changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are
both small, messages must be sent at an even rate.
There is a script in &_util/ratelimit.pl_& which extracts sending rates from
instructions when it is run with no arguments.
The key is used to look up the data for calculating the client's average
-sending rate. This data is stored in a database maintained by Exim in its spool
-directory, alongside the retry and other hints databases. The default key is
-&$sender_host_address$&, which applies the limit to each client host IP address.
+sending rate. This data is stored in Exim's spool directory, alongside the
+retry and other hints databases. The default key is &$sender_host_address$&,
+which means Exim computes the sending rate of each client host IP address.
By changing the key you can change how Exim identifies clients for the purpose
of ratelimiting. For example, to limit the sending rate of each authenticated
user, independent of the computer they are sending from, set the key to
&$authenticated_id$&. You must ensure that the lookup key is meaningful; for
example, &$authenticated_id$& is only meaningful if the client has
-authenticated, and you can check with the &%authenticated%& ACL condition.
+authenticated (which you can check with the &%authenticated%& ACL condition).
-If you want to limit the rate at which a recipient receives messages, you can
-use the key &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in
-a RCPT ACL.
+The lookup key does not have to identify clients: If you want to limit the
+rate at which a recipient receives messages, you can use the key
+&`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT
+ACL.
-Internally, Exim includes the smoothing constant &'p'& and the options in the
+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
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 on the 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.
+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.
.new
The &%per_rcpt%& option causes Exim to limit the rate at which
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 incremented is equal to &%$recipients_count%&
+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.
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.
-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 &new("it is actually
-allowed. If the client is over the limit it may be subjected to
-counter-measures in the ACL until it slows down below the maximum rate.") The
-smoothing period determines the time it takes for a high sending rate to decay
-exponentially to 37% of its peak value, which means that 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:
+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
&*Warning*&: It is not possible to use the UNIX socket connection method with
multiple &%spamd%& servers.
+The &%spamd_address%& variable is expanded before use if it starts with
+a dollar sign. In this case, the expansion may return a string that is
+used as the list so that multiple spamd servers can be the result of an
+expansion.
.section "Calling SpamAssassin from an Exim ACL" "SECID206"
Here is a simple example of the use of the &%spam%& condition in a DATA ACL:
.vitem &$spam_score_int$&
The spam score of the message, multiplied by ten, as an integer value. For
-example &"34"& or &"305"&. This is useful for numeric comparisons in
+example &"34"& or &"305"&. It may appear to disagree with &$spam_score$&
+because &$spam_score$& is rounded and &$spam_score_int$& is truncated.
+The integer value is useful for numeric comparisons in
conditions. This variable is special; its value is saved with the message, and
written to Exim's spool file. This means that it can be used during the whole
life of the message on your Exim system, in particular, in routers or
message. Useful for inclusion in headers or reject messages.
.endlist
-The &%spam%& condition caches its results. If you call it again with the same
-user name, it does not scan again, but rather returns the same values as
-before.
+The &%spam%& condition caches its results unless expansion in
+spamd_address was used. If you call it again with the same user name, it
+does not scan again, but rather returns the same values as before.
-The &%spam%& condition returns DEFER if there is any error while running the
-message through SpamAssassin. If you want to treat DEFER as FAIL (to pass on to
-the next ACL statement block), append &`/defer_ok`& to the right-hand side of
-the spam condition, like this:
+The &%spam%& condition returns DEFER if there is any error while running
+the message through SpamAssassin or if the expansion of spamd_address
+failed. If you want to treat DEFER as FAIL (to pass on to the next ACL
+statement block), append &`/defer_ok`& to the right-hand side of the
+spam condition, like this:
.code
deny message = This message was classified as SPAM
spam = joe/defer_ok