correct SPF references and example (bugzilla 520) - thanks to Robert Millan
[exim.git] / doc / doc-txt / NewStuff
index 9d0e93993a9b44b4abe4d291d78574aae6a0e146..e18d215aac21a0df22d56fee9f9c3fc4fbd5af88 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.124 2006/12/05 11:35:28 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.157 2007/08/23 11:01:49 ph10 Exp $
 
 New Features in Exim
 --------------------
 
 New Features in Exim
 --------------------
@@ -8,6 +8,240 @@ 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.
 
 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.68
+------------
+
+ 1. The body_linecount and body_zerocount C variables are now exported in the
+    local_scan API.
+
+ 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:
+
+      deny dnslists = spamhaus.example
+
+    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:
+
+      deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|...
+
+    If this condition succeeds, the value in $dnslist_matched might be
+    192.168.6.7 (for example).
+
+ 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:
+
+      client_condition = ${if !eq{$tls_cipher}{}}
+
+    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.
+
+ 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.
+
+ 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.
+
+    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).
+
+    Example:
+
+    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)
+
+      [... some other logic and tests...]
+
+      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}}
+
+      accept
+
+ 6. The variable $max_received_linelength contains the number of bytes in the
+    longest line that was received as part of the message, not counting the
+    line termination character(s).
+
+ 7. Host lists can now include +ignore_defer and +include_defer, analagous to
+    +ignore_unknown and +include_unknown. These options should be used with
+    care, probably only in non-critical host lists such as whitelists.
+
+ 8. There's a new option called queue_only_load_latch, which defaults true.
+    If set false when queue_only_load is greater than zero, Exim re-evaluates
+    the load for each incoming message in an SMTP session. Otherwise, once one
+    message is queued, the remainder are also.
+
+ 9. There is a new ACL, specified by smtp_notquit_acl, which is run in most
+    cases when an SMTP session ends without sending QUIT. However, when Exim
+    itself is is bad trouble, such as being unable to write to its log files,
+    this ACL is not run, because it might try to do things (such as write to
+    log files) that make the situation even worse.
+
+    Like the QUIT ACL, this new ACL is provided to make it possible to gather
+    statistics. Whatever it returns (accept or deny) is immaterial. The "delay"
+    modifier is forbidden in this ACL.
+
+    When the NOTQUIT ACL is running, the variable $smtp_notquit_reason is set
+    to a string that indicates the reason for the termination of the SMTP
+    connection. The possible values are:
+
+      acl-drop                 Another ACL issued a "drop" command
+      bad-commands             Too many unknown or non-mail commands
+      command-timeout          Timeout while reading SMTP commands
+      connection-lost          The SMTP connection has been lost
+      data-timeout             Timeout while reading message data
+      local-scan-error         The local_scan() function crashed
+      local-scan-timeout       The local_scan() function timed out
+      signal-exit              SIGTERM or SIGINT
+      synchronization-error    SMTP synchronization error
+      tls-failed               TLS failed to start
+
+    In most cases when an SMTP connection is closed without having received
+    QUIT, Exim sends an SMTP response message before actually closing the
+    connection. With the exception of acl-drop, the default message can be
+    overridden by the "message" modifier in the NOTQUIT ACL. In the case of a
+    "drop" verb in another ACL, it is the message from the other ACL that is
+    used.
+
+10. For MySQL and PostgreSQL lookups, it is now possible to specify a list of
+    servers with individual queries. This is done by starting the query with
+    "servers=x:y:z;", where each item in the list may take one of two forms:
+
+    (1) If it is just a host name, the appropriate global option (mysql_servers
+        or pgsql_servers) is searched for a host of the same name, and the
+        remaining parameters (database, user, password) are taken from there.
+
+    (2) If it contains any slashes, it is taken as a complete parameter set.
+
+    The list of servers is used in exactly the same was as the global list.
+    Once a connection to a server has happened and a query has been
+    successfully executed, processing of the lookup ceases.
+
+    This feature is intended for use in master/slave situations where updates
+    are occurring, and one wants to update a master rather than a slave. If the
+    masters are in the list for reading, you might have:
+
+      mysql_servers = slave1/db/name/pw:slave2/db/name/pw:master/db/name/pw
+
+    In an updating lookup, you could then write
+
+      ${lookup mysql{servers=master; UPDATE ...}
+
+    If, on the other hand, the master is not to be used for reading lookups:
+
+      pgsql_servers = slave1/db/name/pw:slave2/db/name/pw
+
+    you can still update the master by
+
+      ${lookup pgsql{servers=master/db/name/pw; UPDATE ...}
+
+11. The message_body_newlines option (default FALSE, for backwards
+    compatibility) can be used to control whether newlines are present in
+    $message_body and $message_body_end. If it is FALSE, they are replaced by
+    spaces.
+
+
+Version 4.67
+------------
+
+ 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.
+
+ 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.
+
+ 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.
+
+ 4. There is a new compile-time option called ENABLE_DISABLE_FSYNC. When it is
+    set, Exim compiles a runtime option called disable_fsync.
+
+ 5. There is a new variable called $smtp_count_at_connection_start.
+
+ 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
+------------
+
+No new features were added to 4.66.
+
+
+Version 4.65
+------------
+
+No new features were added to 4.65.
+
 
 Version 4.64
 ------------
 
 Version 4.64
 ------------
@@ -15,232 +249,49 @@ Version 4.64
  1. ACL variables can now be given arbitrary names, as long as they start with
     "acl_c" or "acl_m" (for connection variables and message variables), are at
     least six characters long, with the sixth character being either a digit or
  1. ACL variables can now be given arbitrary names, as long as they start with
     "acl_c" or "acl_m" (for connection variables and message variables), are at
     least six characters long, with the sixth character being either a digit or
-    an underscore. The rest of the name can contain alphanumeric characters and
-    underscores. This is a compatible change because the old set of variables
-    such as acl_m12 are a subset of the allowed names. There may now be any
-    number of ACL variables. For example:
-
-      set acl_c13   = value for original ACL variable
-      set acl_c13b  = whatever
-      set acl_m_foo = something
-
-    What happens if a syntactically valid but undefined ACL variable is
-    referenced depends on the setting of the strict_acl_vars option. If it is
-    false (the default), an empty string is substituted; if it is true, an
-    error is generated. This affects all ACL variables, including the "old"
-    ones such as acl_c4. (Previously there wasn't the concept of an undefined
-    ACL variable.)
-
-    The implementation has been done in such a way that spool files containing
-    ACL variable settings written by previous releases of Exim are compatible
-    and can be read by the new release. If only the original numeric names are
-    used, spool files written by the new release can be read by earlier
-    releases.
+    an underscore.
 
  2. There is a new ACL modifier called log_reject_target. It makes it possible
 
  2. There is a new ACL modifier called log_reject_target. It makes it possible
-    to specify which logs are used for messages about ACL rejections. Its
-    argument is a list of words which can be "main", "reject", or "panic". The
-    default is "main:reject". The list may be empty, in which case a rejection
-    is not logged at all. For example, this ACL fragment writes no logging
-    information when access is denied:
-
-      deny <some conditions>
-           log_reject_target =
-
-    The modifier can be used in SMTP and non-SMTP ACLs. It applies to both
-    permanent and temporary rejections.
+    to specify which logs are used for messages about ACL rejections.
 
  3. There is a new authenticator called "dovecot". This is an interface to the
     authentication facility of the Dovecot POP/IMAP server, which can support a
 
  3. There is a new authenticator called "dovecot". This is an interface to the
     authentication facility of the Dovecot POP/IMAP server, which can support a
-    number of authentication methods. If you are using Dovecot to authenticate
-    POP/IMAP clients, it might be helpful to use the same mechanisms for SMTP
-    authentication. This is a server authenticator only. The only option is
-    server_socket, which must specify the socket which is the interface to
-    Dovecot authentication. The public_name option must specify an
-    authentication mechanism that Dovecot is configured to support. You can
-    have several authenticators for different mechanisms. For example:
-
-      dovecot_plain:
-        driver = dovecot
-        public_name = PLAIN
-        server_name = /var/run/dovecot/auth-client
-        server_setid = $auth1
-
-      dovecot_ntlm:
-        driver = dovecot
-        public_name = NTLM
-        server_name = /var/run/dovecot/auth-client
-        server_setid = $auth1
-
-    If the SMTP connection is encrypted, or if $sender_host_address is equal to
-    $interface_address (that is, the connection is local), the "secured" option
-    is passed in the Dovecot authentication command. If, for a TLS connection,
-    a client certificate has been verified, the "valid-client-cert" option is
-    passed.
+    number of authentication methods.
 
  4. The variable $message_headers_raw provides a concatenation of all the
     messages's headers without any decoding. This is in contrast to
     $message_headers, which does RFC2047 decoding on the header contents.
 
 
  4. The variable $message_headers_raw provides a concatenation of all the
     messages's headers without any decoding. This is in contrast to
     $message_headers, which does RFC2047 decoding on the header contents.
 
- 5. In a DNS black list, when the facility for restricting the matching IP
-    values is used, the text from the TXT record that is set in $dnslist_text
-    may not reflect the true reason for rejection. This happens when lists are
-    merged and the IP address in the A record is used to distinguish them;
-    unfortunately there is only one TXT record. One way round this is not to
-    use merged lists, but that can be inefficient because it requires multiple
-    DNS lookups where one would do in the vast majority of cases when the host
-    of interest is not on any of the lists.
-
-    A less inefficient way of solving this problem has now been implemented. If
-    two domain names, comma-separated, are given, the second is used first to
-    do an initial check, making use of any IP value restrictions that are set.
-    If there is a match, the first domain is used, without any IP value
-    restrictions, to get the TXT record. As a byproduct of this, there is also
-    a check that the IP being tested is indeed on the first list. The first
-    domain is the one that is put in $dnslist_domain. For example:
-
-      reject message  = rejected because $sender_ip_address is blacklisted \
-                        at $dnslist_domain\n$dnslist_text
-             dnslists = sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \
-                        dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
-
-    For the first blacklist item, this starts by doing a lookup in
-    sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a
-    match, it then looks in sbl.spamhaus.org, without checking the return
-    value, and as long as something is found, it looks for the corresponding
-    TXT record. If there is no match in sbl-xbl.spamhaus.org, nothing more is
-    done. The second blacklist item is processed similarly.
-
-    If you are interested in more than one merged list, the same list must be
-    given several times, but because the results of the DNS lookups are cached,
-    the DNS calls themselves are not repeated. For example:
-
-      reject dnslists = http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \
-                       socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \
-                        misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \
-                         dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10
-
-    In this case there is a lookup in dnsbl.sorbs.net, and if none of the IP
-    values matches (or if no record is found), this is the only lookup that is
-    done. Only if there is a match is one of the more specific lists consulted.
-
- 6. All authenticators now have a server_condition option. Previously, only
-    plaintext had this, and this has not changed: it must be set to the
-    authenticator as a server. For the others, if server_condition is set, it
-    is expanded if authentication is successful, and treated exactly as it is
-    in plaintext. This can serve as a means of adding authorization to an
-    authenticator.
+ 5. In a DNS black list, if two domain names, comma-separated, are given, the
+    second is used first to do an initial check, making use of any IP value
+    restrictions that are set. If there is a match, the first domain is used,
+    without any IP value restrictions, to get the TXT record.
+
+ 6. All authenticators now have a server_condition option.
 
  7. There is a new command-line option called -Mset. It is useful only in
     conjunction with -be (that is, when testing string expansions). It must be
     followed by a message id; Exim loads the given message from its spool
 
  7. There is a new command-line option called -Mset. It is useful only in
     conjunction with -be (that is, when testing string expansions). It must be
     followed by a message id; Exim loads the given message from its spool
-    before doing the expansions, thus setting message-specific variables such
-    as $message_size and the header variables. The $recipients variable is
-    available. This feature is provided to make it easier to test expansions
-    that make use of these variables. However, Exim must be called by an admin
-    user when -Mset is used.
+    before doing the expansions.
 
  8. Another similar new command-line option is called -bem. It operates like
 
  8. Another similar new command-line option is called -bem. It operates like
-    -be except that it must be followed by the name of a file. For example:
-
-      exim -bem /tmp/testmessage
-
-    The file is read as a message (as if receiving a locally-submitted non-SMTP
-    message) before any of the test expansions are done. Thus, message-specific
-    variables such as $message_size and $h_from: are available. However, no
-    Received: header is added to the message. If the -t option is set,
-    recipients are read from the headers in the normal way, and are shown in
-    the $recipients variable. Note that recipients cannot be given on the
-    command line, because further arguments are taken as strings to expand
-    (just like -be).
+    -be except that it must be followed by the name of a file that contains a
+    message.
 
  9. When an address is delayed because of a 4xx response to a RCPT command, it
     is now the combination of sender and recipient that is delayed in
 
  9. When an address is delayed because of a 4xx response to a RCPT command, it
     is now the combination of sender and recipient that is delayed in
-    subsequent queue runs until its retry time is reached. You can revert to
-    the previous behavious, that is, delay the recipient independent of the
-    sender, by setting address_retry_include_sender=false in the smtp
-    transport. However, this can lead to problems with servers that regularly
-    issue 4xx responses to RCPT commands.
+    subsequent queue runs until its retry time is reached.
 
 10. Unary negation and the bitwise logical operators and, or, xor, not, and
 
 10. Unary negation and the bitwise logical operators and, or, xor, not, and
-    shift, have been added to the eval: and eval10: expansion items. These
-    items may now contain arithmetic operators (plus, minus, times, divide,
-    remainder, negate), bitwise operators (and, or, xor, not, shift), and
-    parentheses. All operations are carried out using signed integer
-    arithmetic. Operator priorities are as in C, namely:
-
-      (highest) not, negate
-                times, divide, remainder
-                plus, minus
-                shift-left, shift-right
-                and
-                xor
-      (lowest)  or
-
-    Binary operators with the same priority are evaluated from left to right.
-    For example:
-
-      ${eval:1+1}            yields 2
-      ${eval:1+2*3}          yields 7
-      ${eval:(1+2)*3}        yields 9
-      ${eval:2+42%5}         yields 4
-      ${eval:0xc&5}          yields 4
-      ${eval:0xc|5}          yields 13
-      ${eval:0xc^5}          yields 9
-      ${eval:0xc>>1}         yields 6
-      ${eval:0xc<<1}         yields 24
-      ${eval:~255&0x1234}    yields 4608
-      ${eval:-(~255&0x1234)} yields -4608
+    shift, have been added to the eval: and eval10: expansion items.
 
 11. The variables $interface_address and $interface_port have been renamed
     as $received_ip_address and $received_port, to make it clear that they
     relate to message reception rather than delivery. (The old names remain
     available for compatibility.)
 
 
 11. The variables $interface_address and $interface_port have been renamed
     as $received_ip_address and $received_port, to make it clear that they
     relate to message reception rather than delivery. (The old names remain
     available for compatibility.)
 
-12. The "message" modifier can now be used on acl verbs to vary the message
-    that is sent when an SMTP command is accepted. For example, in a RCPT ACL
-    you could have:
-
-      accept  <some conditions>
-              message = OK, I'll allow you through today
-
-    Previously, this message modifier would have had no effect whatsoever.
-
-    IMPORTANT: The new behaviour applies to "accept" (and "discard") only if
-    there is no occurrence of "endpass" in the statement. If "endpass" is
-    present, the behaviour reverts to the old case, where "message" applies to
-    rejection. This is for backwards compatibility.
-
-    It is always possible to rewrite ACL statements so that "endpass" is not
-    needed (and indeed it is no longer used in the default configuration, and
-    is somewhat not recommended nowadays because it causes confusion.)
-
-    It is now generally true that the "message" modifier sets up a text string
-    that is expanded and used as a response message if the current statement
-    terminates the ACL. The expansion happens at the time Exim decides that the
-    ACL is to end, not at the time it processes "message". If the expansion
-    fails, or generates an empty string, the modifier is ignored.
-
-    For ACLs that are triggered by SMTP commands, the message is returned as
-    part of the SMTP response. In this situation, the message may begin with an
-    overriding SMTP response code, optionally followed by an "extended response
-    code". However, the first digit of the supplied response code must be the
-    same as would be sent by default. A panic occurs if it is not. For the
-    predata ACL, note that the default success code is 354, not 2xx.
-
-    However, notwithstanding the previous paragraph, for the QUIT ACL, unlike
-    the others, the message modifier cannot override the 221 response code.
-
-    In the case of the "connect" ACL, accepting with a message modifier
-    overrides the value of smtp_banner.
-
-    The ACL test specified by acl_smtp_helo happens when the client issues the
-    HELO or EHLO commands, after the tests specified by helo_accept_junk_hosts,
-    helo_allow_chars and helo(_try)_verify_hosts. An acceptance message
-    modifier for EHLO/HELO may not contain more than one line (it will be
-    truncated at the first newline and a panic logged), and it cannot affect
-    the EHLO options.
-
+12. The "message" modifier can now be used on "accept" and "discard" acl verbs
+    to vary the message that is sent when an SMTP command is accepted.
 
 
 Version 4.63
 
 
 Version 4.63