Add /noupdate as a ratelimit option.
[exim.git] / doc / doc-txt / NewStuff
index f5b8bd949edc9939ddb75e63f573c526f8603824..f6cbf54c3f5b6d7b49808591ff403d6a6aab7361 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.131 2007/01/30 11:45:20 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.151 2007/06/20 14:13:39 ph10 Exp $
 
 New Features in Exim
 --------------------
@@ -8,200 +8,145 @@ Before a formal release, there may be quite a lot of detail so that people can
 test from the snapshots or the CVS before the documentation is updated. Once
 the documentation is updated, this file is reduced to a short list.
 
-Version 4.67
+Version 4.68
 ------------
 
- 1. There is a new log selector called smtp_no_mail, which is not included in
-    the default setting. When it is set, a line is written to the main log
-    whenever an accepted SMTP connection terminates without having issued a
-    MAIL command. This includes both the case when the connection is dropped,
-    and the case when QUIT is used. Note that it does not include cases where
-    the connection is rejected right at the start (by an ACL, or because there
-    are too many connections, or whatever). These cases already have their own
-    log lines.
-
-    The log line that is written contains the identity of the client in the
-    usual way, followed by D= and a time, which records the duration of the
-    connection. If the connection was authenticated, this fact is logged
-    exactly as it is for an incoming message, with an A= item. If the
-    connection was encrypted, CV=, DN=, and X= items may appear as they do for
-    an incoming message, controlled by the same logging options.
-
-    Finally, if any SMTP commands were issued during the connection, a C= item
-    is added to the line, listing the commands that were used. For example,
-
-      C=EHLO,QUIT
-
-    shows that the client issued QUIT straight after EHLO. If there were fewer
-    than 20 commands, they are all listed. If there were more than 20 commands,
-    the last 20 are listed, preceded by "...". However, with the default
-    setting of 10 for smtp_accep_max_nonmail, the connection will in any case
-    be aborted before 20 non-mail commands are processed.
+ 1. The body_linecount and body_zerocount C variables are now exported in the
+    local_scan API.
 
- 2. When an item in a dnslists list is followed by = and & and a list of IP
-    addresses, in order to restrict the match to specific results from the DNS
-    lookup, the behaviour was not clear when the lookup returned more than one
-    IP address. For example, consider the condition
+ 2. When a dnslists lookup succeeds, the key that was looked up is now placed
+    in $dnslist_matched. When the key is an IP address, it is not reversed in
+    this variable (though it is, of course, in the actual lookup). In simple
+    cases, for example:
 
-      dnslists = a.b.c=127.0.0.1
+      deny dnslists = spamhaus.example
 
-    What happens if the DNS lookup for the incoming IP address yields both
-    127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the
-    condition true because at least one given value was found, or is it false
-    because at least one of the found values was not listed? And how does this
-    affect negated conditions?
+    the key is also available in another variable (in this case,
+    $sender_host_address). In more complicated cases, however, this is not
+    true. For example, using a data lookup might generate a dnslists lookup
+    like this:
 
-    The behaviour of = and & has not been changed; however, the text below
-    documents it more clearly. In addition, two new additional conditions (==
-    and =&) have been added, to permit the "other" behaviour to be configured.
+      deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
 
-    A DNS lookup may yield more than one record. Thus, the result of the lookup
-    for a dnslists check may yield more than one IP address. The question then
-    arises as to whether all the looked up addresses must be listed, or whether
-    just one is good enough. Both possibilities are provided for:
+    If this condition succeeds, the value in $dnslist_matched might be
+    192.168.6.7 (for example).
 
-    . If = or & is used, the condition is true if any one of the looked up
-      IP addresses matches one of the listed addresses. Consider:
+ 3. Authenticators now have a client_condition option. When Exim is running as
+    a client, it skips an authenticator whose client_condition expansion yields
+    "0", "no", or "false". This can be used, for example, to skip plain text
+    authenticators when the connection is not encrypted by a setting such as:
 
-        dnslists = a.b.c=127.0.0.1
+      client_condition = ${if !eq{$tls_cipher}{}}
 
-      If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
-      true because 127.0.0.1 matches.
+    Note that the 4.67 documentation states that $tls_cipher contains the
+    cipher used for incoming messages. In fact, during SMTP delivery, it
+    contains the cipher used for the delivery. The same is true for
+    $tls_peerdn.
 
-    . If == or =& is used, the condition is true only if every one of the
-      looked up IP addresses matches one of the listed addresses. Consider:
+ 4. There is now a -Mvc <message-id> option, which outputs a copy of the
+    message to the standard output, in RFC 2822 format. The option can be used
+    only by an admin user.
 
-        dnslists = a.b.c==127.0.0.1
+ 5. There is now a /noupdate option for the ratelimit ACL condition. It
+    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.
 
-      If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
-      false because 127.0.0.2 is not listed. You would need to have
+    In order for this to be useful, another ACL entry must set the rate
+    for the same key somewhere (otherwise it will always be zero).
 
-        dnslists = a.b.c==127.0.0.1,127.0.0.2
+    Example:
 
-      for the condition to be true.
+    acl_check_connect:
+      # Read the rate; if it doesn't exist or is below the maximum
+      # we update it below
+      deny ratelimit = 100 / 5m / strict / noupdate
+           log_message = RATE: $sender_rate / $sender_rate_period \
+                         (max $sender_rate_limit)
 
-    When ! is used to negate IP address matching, it inverts the result, giving
-    the precise opposite of the behaviour above. Thus:
+      [... some other logic and tests...]
 
-    . If != or !& is used, the condition is true if none of the looked up IP
-      addresses matches one of the listed addresses. Consider:
+      warn ratelimit = 100 / 5m / strict / per_cmd
+           log_message = RATE UPDATE: $sender_rate / $sender_rate_period \
+                         (max $sender_rate_limit)
+           condition = ${if le{$sender_rate}{$sender_rate_limit}}
 
-        dnslists = a.b.c!&0.0.0.1
+      accept
 
-      If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
-      false because 127.0.0.1 matches.
 
-    . If !== or !=& is used, the condition is true there is at least one looked
-      up IP address that does not match. Consider:
+Version 4.67
+------------
 
-        dnslists = a.b.c!=&0.0.0.1
+ 1. There is a new log selector called smtp_no_mail, which is not included in
+    the default setting. When it is set, a line is written to the main log
+    whenever an accepted SMTP connection terminates without having issued a
+    MAIL command.
 
-      If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is
-      true, because 127.0.0.2 does not match. You would need to have
+ 2. When an item in a dnslists list is followed by = and & and a list of IP
+    addresses, the behaviour was not clear when the lookup returned more than
+    one IP address. This has been solved by the addition of == and =& for "all"
+    rather than the default "any" matching.
 
-        dnslists = a.b.c!=&0.0.0.1,0.0.0.2
+ 3. Up till now, the only control over which cipher suites GnuTLS uses has been
+    for the cipher algorithms. New options have been added to allow some of the
+    other parameters to be varied.
 
-      for the condition to be false.
+ 4. There is a new compile-time option called ENABLE_DISABLE_FSYNC. When it is
+    set, Exim compiles a runtime option called disable_fsync.
 
-    When the DNS lookup yields only a single IP address, there is no difference
-    between = and == and between & and =&.
+ 5. There is a new variable called $smtp_count_at_connection_start.
 
- 3. Up till now, the only control over which cipher suites GnuTLS uses has been
-    for the cipher algorithms. New options have been added to allow some of the
-    other parameters to be varied. Here is complete documentation for the
-    available features:
-
-    GnuTLS allows the caller to specify separate lists of permitted key
-    exchange methods, main cipher algorithms, and MAC algorithms. These may be
-    used in any combination to form a specific cipher suite. This is unlike
-    OpenSSL, where complete cipher names can be passed to its control function.
-    GnuTLS also allows a list of acceptable protocols to be supplied.
-
-    For compatibility with OpenSSL, the tls_require_ciphers option can be set
-    to complete cipher suite names such as RSA_ARCFOUR_SHA, but for GnuTLS this
-    option controls only the cipher algorithms. Exim searches each item in the
-    list for the name of an available algorithm. For example, if the list
-    contains RSA_AES_SHA, then AES is recognized, and the behaviour is exactly
-    the same as if just AES were given.
-
-    There are additional options called gnutls_require_kx, gnutls_require_mac,
-    and gnutls_require_protocols that can be used to restrict the key exchange
-    methods, MAC algorithms, and protocols, respectively. These options are
-    ignored if OpenSSL is in use.
-
-    All four options are available as global options, controlling how Exim
-    behaves as a server, and also as options of the smtp transport, controlling
-    how Exim behaves as a client. All the values are string expanded. After
-    expansion, the values must be colon-separated lists, though the separator
-    can be changed in the usual way.
-
-    Each of the four lists starts out with a default set of algorithms. If the
-    first item in one of the "require" options does _not_ start with an
-    exclamation mark, all the default items are deleted. In this case, only
-    those that are explicitly specified can be used. If the first item in one
-    of the "require" items _does_ start with an exclamation mark, the defaults
-    are left on the list.
-
-    Then, any item that starts with an exclamation mark causes the relevant
-    entry to be removed from the list, and any item that does not start with an
-    exclamation mark causes a new entry to be added to the list. Unrecognized
-    items in the list are ignored. Thus:
-
-      tls_require_ciphers = !ARCFOUR
-
-    allows all the defaults except ARCFOUR, whereas
-
-      tls_require_ciphers = AES : 3DES
-
-    allows only cipher suites that use AES or 3DES. For tls_require_ciphers
-    the recognized names are AES_256, AES_128, AES (both of the preceding),
-    3DES, ARCFOUR_128, ARCFOUR_40, and ARCFOUR (both of the preceding). The
-    default list does not contain all of these; it just has AES_256, AES_128,
-    3DES, and ARCFOUR_128.
-
-    For gnutls_require_kx, the recognized names are DHE_RSA, RSA (which
-    includes DHE_RSA), DHE_DSS, and DHE (which includes both DHE_RSA and
-    DHE_DSS). The default list contains RSA, DHE_DSS, DHE_RSA.
-
-    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.
-
-    In a server, the order of items in these lists is unimportant. The server
-    will advertise the availability of all the relevant cipher suites. However,
-    in a client, the order in the tls_require_ciphers list specifies a
-    preference order for the cipher algorithms. The first one in the client's
-    list that is also advertised by the server is tried first.
-
- 4. There is a new compile-time option called ENABLE_DISABLE_FSYNC. You must
-    not set this option unless you really, really, really understand what you
-    are doing. No pre-compiled distributions of Exim should ever set this
-    option. When it is set, Exim compiles a runtime option called
-    disable_fsync. If this is set true, Exim no longer calls fsync() to force
-    updated files' data to be written to disc. Unexpected events such as
-    crashes and power outages may cause data to be lost or scrambled. Beware.
-
-    When ENABLE_DISABLE_FSYNC is not set, a reference to disable_fsync in a
-    runtime configuration generates an "unknown option" error.
-
- 5. There is a new variable called $smtp_count_at_connection_start. The name
-    is deliberately long, in order to emphasize what the contents are. This
-    variable is set greater than zero only in processes spawned by the Exim
-    daemon for handling incoming SMTP connections. When the daemon accepts a
-    new connection, it increments this variable. A copy of the variable is
-    passed to the child process that handles the connection, but its value is
-    fixed, and never changes. It is only an approximation of how many incoming
-    connections there actually are, because many other connections may come and
-    go while a single connection is being processed. When a child process
-    terminates, the daemon decrements the variable.
-
- 6. There's a new control called no_pipelining, which does what its name
-    suggests. It turns off the advertising of the PIPELINING extension to SMTP.
-    To be useful, this control must be obeyed before Exim sends its response to
-    an EHLO command. Therefore, it should normally appear in an ACL controlled
-    by acl_smtp_connect or acl_smtp_helo.
+ 6. There's a new control called no_pipelining.
+
+ 7. There are two new variables called $sending_ip_address and $sending_port.
+    These are set whenever an SMTP connection to another host has been set up.
+
+ 8. The expansion of the helo_data option in the smtp transport now happens
+    after the connection to the server has been made.
+
+ 9. There is a new expansion operator ${rfc2047d: that decodes strings that
+    are encoded as per RFC 2047.
+
+10. There is a new log selector called "pid", which causes the current process
+    id to be added to every log line, in square brackets, immediately after the
+    time and date.
+
+11. Exim has been modified so that it flushes SMTP output before implementing
+    a delay in an ACL. It also flushes the output before performing a callout,
+    as this can take a substantial time. These behaviours can be disabled by
+    obeying control = no_delay_flush or control = no_callout_flush,
+    respectively, at some earlier stage of the connection.
+
+12. There are two new expansion conditions that iterate over a list. They are
+    called forany and forall.
+
+13. There's a new global option called dsn_from that can be used to vary the
+    contents of From: lines in bounces and other automatically generated
+    messages ("delivery status notifications" - hence the name of the option).
+
+14. The smtp transport has a new option called hosts_avoid_pipelining.
+
+15. By default, exigrep does case-insensitive matches. There is now a -I option
+    that makes it case-sensitive.
+
+16. A number of new features ("addresses", "map", "filter", and "reduce") have
+    been added to string expansions to make it easier to process lists of
+    items, typically addresses.
+
+17. There's a new ACL modifier called "continue". It does nothing of itself,
+    and processing of the ACL always continues with the next condition or
+    modifier. It is provided so that the side effects of expanding its argument
+    can be used.
+
+18. It is now possible to use newline and other control characters (those with
+    values less than 32, plus DEL) as separators in lists.
+
+19. The exigrep utility now has a -v option, which inverts the matching
+    condition.
+
+20. The host_find_failed option in the manualroute router can now be set to
+    "ignore".
 
 
 Version 4.66