Add some meaningful debug output
[exim.git] / doc / doc-txt / NewStuff
index 67901a28c7f4c9577aba3a4abc3f8604af6b0aed..583fe92f1b88cfa8ec7d7f65c0b4c96375d6a1f8 100644 (file)
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/NewStuff,v 1.123 2006/11/14 16:40:36 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/NewStuff,v 1.159 2008/10/16 07:57:01 nm4 Exp $
 
 New Features in Exim
 --------------------
@@ -8,6 +8,247 @@ 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.70
+------------
+
+ 1. Preliminary SPF Best Guess support.  Documentation for this is in
+    experimental-spec.txt.
+
+
+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 acl_smtp_notquit, 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
 ------------
@@ -15,232 +256,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
-    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
-    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
-    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.
 
- 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
-    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
-    -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
-    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
-    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.)
 
-12. The "message" modifier can now be used on acl verbs to vary the message
-    that is sent when an SMTP command. 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