Version 5.1, 2009-05-13

* Milter v6.

The version 6 of Milter protocol is implemented, which is compatible
with Sendmail 8.14.0 and newer.  While being backward compatible with
the earlier versions, it allows you to use the new `prog data'
handler.  It also supports macro negotiation, a feature that enables
Mailfromd to ask the MTA to export the macros it needs for each
particular handler.  This means that if you are using Sendmail 8.14.0
or higher (or Postfix 2.5 or higher), you no longer need to worry about
exporting macro names in sendmail.cf file.

The same feature is also implemented on the server side, in mtasim and
pmult.  Consequently, using `define-macros' in pmult configuration file
is not strictly necessary.  However, keep in mind that due to the
specifics of MeTA1, the number of symbols that may be exported for
each stage is limited (Mailfromd manual, section 11.1.2).

* Reject and tempfail actions: Functional notation

The reply actions `reject' and `tempfail' allow functional notation,
i.e. their arguments can be supplied as to a function:

  reject(550, 5.7.7, "IP address does not resolve")

An important feature of this notation is that all three arguments are
MFL expressions, which means that you can now compute the reply codes
at run time:

  reject(550 + %n, "5.7." %x, "Transaction rejected")

An argument can be omitted, in which case the default value is used, e.g.:

  reject(550 + %n, , "Transaction rejected")

* New functions

A set of new functions is added that allow to access the headers
from the current message in a uniform fashion.  These functions are
available in the following handlers: eoh, body, eom.

- number current_header_count([string name])

Return number of headers in the current message.  With an argument -
return number of headers that have this name.

- string current_header_nth_name(number n)

Return the name of the nth header.  N is 1-based.

- string current_header_nth_value(number n)

Return the value of the nth header.  N is 1-based.

- string current_header(string name[, number index])

Return the value of the named header, e.g.:

  set s current_header("Subject")

Optional second argument specifies the header instance, if there are
more than 1 header of the same name, e.g.:

  set s current_header("Received", 2)

Index is 1-based.

All current_header functions raise the e_not_found exception if the
requested header is not found.

New system information functions are added:

- string gethostname ()

Return the host name of this machine.

- string getdomainname ()

Return the domain name of this machine.

- string uname (string format)

Return system information formatted according to the format specification.

* New pragma `dbprop'

This pragma defines user database properties.  It takes two or three
arguments:

 #pragma dbprop <pattern> <null> <mode>

where <pattern> is the name of the database or a shell globbing
pattern, <null> is the word "null" if the terminating null byte
is included in the key length, and <mode> is the database file
mode, either in octal or in usual `ls' notation (e.g. rw-r-----).
Either of <null> or <mode> may be omitted.  If both are given, they
may appear in any order.

* Token Bucket Filter

The new function is provided:

  bool tbf_rate(string key, number cost, number interval, number burst_size)

It implements a classical token bucket filter algorithm.  Tokens are
added to the bucket identified by the `key' at constant rate of 1
token per `interval' microseconds, to a maximum of `burst_size' tokens.
If no bucket is found for the specified key, a new bucket is created
and initialized to contain `burst_size' tokens.

For example:

  if not tbf_rate($f "-" ${client_addr}, 1, 10000000, 20)
    tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
  fi

This adds a token every 10 seconds with a burst size of 20 and a
cost of 1.  In other words, it allows to sent up to 20 emails within
the first 10 seconds after sending the very first email from the given
email/host address pair.  After that, that pair is allowed to send
at most 1 message per 10 seconds.

One of possible implementations for this function is to limit
the total size of messages tranferred per given amount of time.
To do so, the tbf_rate must be used in `prog eom'.  The `cost'
value must contain the number of bytes in an email (or email bytes
* number of recipients), the `interval' must be set to the number of
bytes per microsecond a given user is allowed to send, and the
`burst_size' must be large enough to accommodate a couple of large
emails.  E.g.:

  prog eom
  do
    if not tbf_rate($f "-" ${client_addr},
                    message_size(current_message()),
                    10240,   # At most 10 Kb/ms
		    2000000)
      tempfail 450 4.7.0 "Data sending rate exceeded. Try again later"
    fi
  done

The `tbf_rate' implementation is contributed by John McEleney and
Ben McKeegan.

* Greylisting

A new implementation of the `greylist' function is provided.  In the
contrast to the traditional implementation, which keeps in the
database the time when the greylisting was activated for the given
key, the new one stores the time when the greylisting period is set to
expire.  This implementation allowed to implement the `is_greylisted'
function:

  bool is_greylisted(string key)

which returns True if the `key' is currently greylisted, and False
otherwise.  This implementation is based on the patch by Con
Tassios.

By default, the traditional implementation is used, which ensures
backward compatibility with the previous versions.  To switch to
the new implementation, use the following pragmatic comment at the
beginning of your script:

  #pragma greylist con-tassios
or
  #pragma greylist ct

* The rate builtin

The rate builtin function now takes an optional `threshold' argument:

  number rate(string key, number interval, [number mincnt, number threshold])

If the observed rate (per interval seconds) is higher than the
threshold, the rate function does not increment the hit counters for
that key.  That way messages that were not accepted do not affect the
calculated rate.

Normally, the threshold argument should be equal to the value used in
the right side of comparison operator, e.g.:

  if rate($f "-" ${client_addr}, %rate_interval, 4, %maxrate) > %maxrate
    tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
  fi

The threshold argument is made optional in order to provide backward
compatibility with the prior releases of mailfromd.  Nevertheless, its
use is strongly encouraged.  To simplify the task, the new function
`rateok' is provided (see below).

* The rateok function

A new library function is provided:

  bool rateok(string key, number sample_span, number threshold; number mincnt)

This is a higher-level interface to the rate function.  This function
returns True if the mail sending rate for `key', computed for the
interval of `sample_span' seconds is less than the `threshold'.
Optional `mincnt' parameter supplies the minimal number of mails
needed to obtain the statistics.  It defaults to 4.

An example of rateok usage follows:

prog envfrom
do
  if not rateok($f "-" ${client_addr}, interval("1 minute"), 40)
    tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
  fi
done

This example limits the rate to 40 mails per minute.

* Rate expiration

In addition to the usual expiration algorithm, the rate records are
also expired if no mails were received during a time span greater than
the value of the 2nd argument to the rate (or rateok) function.

* The __statedir__ built-in constant.

The __statedir__ built-in constant is now expanded to the current
value of the program state directory.  In prior releases it used to
expand to the default program state directory.  A new built-in
constant __defstatedir__ is introduced, which expands to the value of
the default program state directory.

* The __preproc__ built-in constant.

Similarly, the __preproc__ built-in constant, which used to signify
the default preprocessor command line, now expands to its current
value.  The new constant __defpreproc__ expands to the default
preprocessor command line.

* Bugfixes
** Second argument to envfrom and envrcpt
** write without third argument
** sa_format_report_header: fix formatting
** Limit use of file descriptors by message capturing eom functions
** fix implementation of `restex' instruction.
** fix inconsistencies in message capturing code.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.7 (GNU/Linux)

iD8DBQBKCwv4NgKwf1XQxzIRAtdyAKCOkYT0PJjpLg2UmOocYEhFUaz7CwCdFlG8
wJyEHqCcU87eMegbdiCsfVw=
=XEuO
-----END PGP SIGNATURE-----