Allow the message "All relevant MX records point to non-existent hosts"
[users/jgh/exim.git] / doc / doc-txt / NewStuff
index ba1c5afc47f08037a33d476d3234a984d78231d2..65b0fc6782e1cf888e45ee28578d0964b537b927 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.50 2005/06/16 20:03:43 tom Exp $
 
 New Features in Exim
 --------------------
@@ -121,6 +121,228 @@ 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.
+
+      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} }
+
+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}}}
+
+
 
 Version 4.51
 ------------