The use of forbid_filter_existstest now also locks out ${stat:
[users/jgh/exim.git] / doc / doc-txt / NewStuff
index ba1c5afc47f08037a33d476d3234a984d78231d2..f358f7a4871ef5f6ff3ef1829a40c5b8ee2aeefc 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.44 2005/05/23 15:44:06 fanf2 Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.59 2005/08/01 15:01:12 ph10 Exp $
 
 New Features in Exim
 --------------------
@@ -8,6 +8,51 @@ but have not yet made it into the main manual (which is most conveniently
 updated when there is a relatively large batch of changes). The doc/ChangeLog
 file contains a listing of all changes, including bug fixes.
 
+Exim version 4.53
+-----------------
+
+TK/01 Added the "success_on_redirect" address verification option. When an
+      address generates new addresses during routing, Exim will abort
+      verification with "success" when more than one address has been
+      generated, but continue to verify a single new address. The latter
+      does not happen when the new "success_on_redirect" option is set, like
+
+      require verify = recipient/success_on_redirect/callout=10s
+
+      In that case, verification will succeed when a router generates a new
+      address.
+
+PH/01 Support for SQLite database lookups has been added. This is another
+      query-style lookup, but it is slightly different from the others because
+      a file name is required in addition to the SQL query. This is because an
+      SQLite database is a single file and there is no daemon as in other SQL
+      databases. The interface to Exim requires the name of the file, as an
+      absolute path, to be given at the start of the query. It is separated
+      from the query by white space. This means that the path name cannot
+      contain white space. Here is a lookup expansion example:
+
+        ${lookup sqlite {/some/thing/sqlitedb \
+          select name from aliases where id='ph10';}}
+
+      In a list, the syntax is similar. For example:
+
+        domainlist relay_domains = sqlite;/some/thing/sqlitedb \
+           select * from relays where ip='$sender_host_address';
+
+      The only character affected by the ${quote_sqlite: operator is a single
+      quote, which it doubles.
+
+      Note that you must set LOOKUP_SQLITE=yes in Local/Makefile in order to
+      obtain SQLite support, and you will also need to add -lsqlite3 to the
+      EXTRALIBS setting. And of course, you have to install SQLite on your
+      host first.
+
+PH/02 The variable $message_id is now deprecated, to be replaced by
+      $message_exim_id, which makes it clearer which ID is being referenced.
+
+PH/03 The use of forbid_filter_existstest now also locks out the use of the
+      ${stat: expansion item.
+
 
 Exim version 4.52
 -----------------
@@ -121,6 +166,290 @@ TF/03 The control = fakereject ACL modifier now has a fakedefer counterpart,
       to be duplicated when the sender retries. Therefore you should not use
       fakedefer if the message will be delivered normally.
 
+TF/04 There is a new ratelimit ACL condition which can be used to measure
+      and control the rate at which clients can send email. This is more
+      powerful than the existing smtp_ratelimit_* options, because those
+      options only control the rate of commands in a single SMTP session,
+      whereas the new ratelimit condition works across all connections
+      (concurrent and sequential) to the same host.
+
+      The syntax of the ratelimit condition is:
+
+        ratelimit = <m> / <p> / <options> / <key>
+
+      If the average client sending rate is less than m messages per time
+      period p then the condition is false, otherwise it is true.
+
+      The parameter p is the smoothing time constant, in the form of an Exim
+      time interval e.g. 8h for eight hours. A larger time constant means it
+      takes Exim longer to forget a client's past behaviour. The parameter m is
+      the maximum number of messages that a client can send 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 both small then messages must be
+      sent at an even rate.
+
+      The key is used to look up the data used to calcluate the client's
+      average sending rate. This data is stored in a database maintained by
+      Exim in its spool directory alongside the retry database etc. For
+      example, you can limit the sending rate of each authenticated user,
+      independent of the computer they are sending from, by setting the key
+      to $authenticated_id. The default key is $sender_host_address.
+      Internally, Exim includes the smoothing constant p and the options in
+      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 will effectively
+      forget their past behaviour.
+
+      Each ratelimit condition can have up to two options. The first option
+      specifies what Exim measures the rate of, and the second specifies how
+      Exim handles excessively fast clients.
+
+      The per_mail option means that it measures the client's rate of sending
+      messages. This is the default if none of the per_* options is specified.
+
+      The per_conn option means that it measures the client's connection rate.
+
+      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.
+
+      The per_cmd option means that Exim recomputes the rate every time the
+      condition is processed, which can be used to limit the SMTP command rate.
+      The alias per_rcpt is provided for use in the RCPT ACL instead of per_cmd
+      to make it clear that the effect is to limit the rate at which recipients
+      are accepted. Note that in this case the rate limiting engine will see a
+      message with many recipients as a large high-speed burst.
+
+      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 counter-measures (e.g. 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.
+
+      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. If the client is over the limit it will be subjected to
+      counter-measures until it slows down below the maximum rate.
+
+      The leaky 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 the maximum. If the client is over the limit it will
+      suffer some counter-measures, but it will still be able to send email
+      at the configured maximum rate, whatever the rate of its attempts.
+
+      As a side-effect, the ratelimit condition will set the expansion
+      variables $sender_rate containing the client's computed rate,
+      $sender_rate_limit containing the configured value of m, and
+      $sender_rate_period containing the configured value of p.
+
+      Exim's other ACL facilities are used to define what counter-measures
+      are taken when the rate limit is exceeded. This might be anything from
+      logging a warning (e.g. while measuring existing sending rates in order
+      to define our policy), through time delays to slow down fast senders,
+      up to rejecting the message. For example,
+
+        # Log all senders' rates
+        warn
+          ratelimit = 0 / 1h / strict
+          log_message = \
+            Sender rate $sender_rate > $sender_rate_limit / $sender_rate_period
+
+        # Slow down fast senders
+        warn
+          ratelimit = 100 / 1h / per_rcpt / strict
+          delay     = ${eval: 10 * ($sender_rate - $sender_rate_limit) }
+
+        # Keep authenticated users under control
+        deny
+          ratelimit = 100 / 1d / strict / $authenticated_id
+
+        # System-wide rate limit
+        defer
+          message = Sorry, too busy. Try again later.
+          ratelimit = 10 / 1s / $primary_hostname
+
+        # Restrict incoming rate from each host, with a default rate limit
+        # set using a macro and special cases looked up in a table.
+        defer
+          message = Sender rate $sender_rate exceeds \
+                    $sender_rate_limit messages per $sender_rate_period
+          ratelimit = ${lookup {$sender_host_address} \
+                        cdb {DB/ratelimits.cdb} \
+                        {$value} {RATELIMIT} }
+
+      Warning: if you have a busy server with a lot of ratelimit tests,
+      especially with the per_rcpt option, you may suffer from a performance
+      bottleneck caused by locking on the ratelimit hints database. Apart from
+      making your ACLs less complicated, you can reduce the problem by using a
+      RAM disk for Exim's hints directory, /var/spool/exim/db/. However this
+      means that Exim will lose its hints data after a reboot (including retry
+      hints, the callout cache, and ratelimit data).
+
+TK/01 Added an 'spf' lookup type that will return an SPF result for a given
+      email address (the key) and an IP address (the database):
+
+      ${lookup {tom@duncanthrax.net} spf{217.115.139.137}}
+
+      The lookup will return the same result strings as they can appear in
+      $spf_result (pass,fail,softfail,neutral,none,err_perm,err_temp). The
+      lookup is armored in EXPERIMENTAL_SPF. Currently, only IPv4 addresses
+      are supported.
+
+      Patch submitted by Chris Webb <chris@arachsys.com>.
+
+PH/02 There's a new verify callout option, "fullpostmaster", which first acts
+      as "postmaster" and checks the recipient <postmaster@domain>. If that
+      fails, it tries just <postmaster>, without a domain, in accordance with
+      the specification in RFC 2821.
+
+PH/03 The action of the auto_thaw option has been changed. It no longer applies
+      to frozen bounce messages.
+
+TK/02 There are two new expansion items to help with the implementation of
+      the BATV "prvs" scheme in an Exim configuration:
+
+
+      ${prvs {<ADDRESS>}{<KEY>}{[KEYNUM]}}
+
+      The "prvs" expansion item takes three arguments: A qualified RFC2821
+      email address, a key and an (optional) key number. All arguments are
+      expanded before being used, so it is easily possible to lookup a key
+      and key number using the address as the lookup key. The key number is
+      optional and defaults to "0". The item will expand to a "prvs"-signed
+      email address, to be typically used with the "return_path" option on
+      a smtp transport. The decision if BATV should be used with a given
+      sender/recipient pair should be done on router level, to avoid having
+      to set "max_rcpt = 1" on the transport.
+
+
+      ${prvscheck {<ADDRESS>}{<SECRET>}{<RETURN_STRING>}}
+
+      The "prvscheck" expansion item takes three arguments. Argument 1 is
+      expanded first. When the expansion does not yield a SYNTACTICALLY
+      valid "prvs"-scheme address, the whole "prvscheck" item expands to
+      the empty string. If <ADDRESS> is a "prvs"-encoded address after
+      expansion, two expansion variables are set up:
+
+        $prvscheck_address   Contains the "prvs"-decoded version of
+                             the address from argument 1.
+
+        $prvscheck_keynum    Contains the key number extracted from
+                             the "prvs"-address in argument 1.
+
+      These two variables can be used in the expansion code of argument 2
+      to retrieve the <SECRET>. The VALIDITY of the "prvs"-signed address
+      is then checked. The result is stored in yet another expansion
+      variable:
+
+        $prvscheck_result    Contains the result of a "prvscheck"
+                             expansion: Unset (the empty string) for
+                             failure, "1" for success.
+
+      The "prvscheck" expansion expands to the empty string if <ADDRESS>
+      is not a SYNTACTICALLY valid "prvs"-scheme address. Otherwise,
+      argument 3 defines what "prvscheck" expands to: If argument 3
+      is the empty string, "prvscheck" expands to the decoded version
+      of the address (no matter if it is CRYPTOGRAPHICALLY valid or not).
+      If argument 3 expands to a non-empty string, "prvscheck" expands
+      to that string.
+
+
+      Usage example
+      -------------
+
+      Macro:
+
+      PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs WHERE \
+                      sender='${quote_mysql:$prvscheck_address}'}{$value}}
+
+      RCPT ACL:
+
+      # Bounces: drop unsigned addresses for BATV senders
+      deny message = This address does not send an unsigned reverse path.
+           senders = :
+           recipients = +batv_recipients
+
+      # Bounces: In case of prvs-signed address, check signature.
+      deny message = Invalid reverse path signature.
+           senders = :
+           condition = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}{1}}
+           !condition = $prvscheck_result
+
+      Top-Level Router:
+
+      batv_redirect:
+        driver = redirect
+        data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}{}}
+
+      Transport (referenced by router that makes decision if
+      BATV is applicable):
+
+        external_smtp_batv:
+          driver = smtp
+          return_path = ${prvs {$return_path} \
+                               {${lookup mysql{SELECT \
+                               secret FROM batv_prvs WHERE \
+                               sender='${quote_mysql:$sender_address}'} \
+                           {$value}fail}}}
+
+PH/04 There are two new options that control the retrying done by the daemon
+      at startup when it cannot immediately bind a socket (typically because
+      the socket is already in use). The default values reproduce what were
+      built-in constants previously: daemon_startup_retries defines the number
+      of retries after the first failure (default 9); daemon_startup_sleep
+      defines the length of time to wait between retries (default 30s).
+
+PH/05 There is now a new ${if condition called "match_ip". It is similar to
+      match_domain, etc. 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 list that can match only an IP
+      address, not a host name. For example:
+
+        ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}}
+
+      The specific types of host list item that are permitted in the list are
+      shown below. Consult the manual section on host lists for further
+      details.
+
+      . An IP address, optionally with a CIDR mask.
+
+      . A single asterisk matches any IP address.
+
+      . An empty item matches only if the IP address is empty. This could be
+        useful for testing for a locally submitted message or one from specific
+        hosts in a single test such as
+
+          ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}}
+
+        where the first item in the list is the empty string.
+
+      . The item @[] matches any of the local host's interface addresses.
+
+      . Lookups are assumed to be "net-" style lookups, even if "net-" is not
+        specified. Thus, the following are equivalent:
+
+          ${if match_ip{$sender_host_address}{lsearch;/some/file}...
+          ${if match_ip{$sender_host_address}{net-lsearch;/some/file}...
+
+        You do need to specify the "net-" prefix if you want to specify a
+        specific address mask, for example, by using "net24-".
+
+PH/06 The "+all" debug selector used to set the flags for all possible output;
+      it is something that people tend to use semi-automatically when
+      generating debug output for me or for the list. However, by including
+      "+memory", an awful lot of output that is very rarely of interest was
+      generated. I have changed this so that "+all" no longer includes
+      "+memory". However, "-all" still turns everything off.
+
 
 Version 4.51
 ------------