aboutsummaryrefslogtreecommitdiff
path: root/doc/mailfromd.texi
diff options
context:
space:
mode:
authorSergey Poznyakoff <gray@gnu.org.ua>2009-05-04 23:45:51 +0300
committerSergey Poznyakoff <gray@gnu.org.ua>2009-05-04 23:45:51 +0300
commit2e9e8087eef5452299cfc839b7b4cc23bb2feb6c (patch)
treec6ad298fbc1fa8bded0d37b17dd190bebb31c4b3 /doc/mailfromd.texi
parent9503ac3090f1013ab501e863d56277cccf301a86 (diff)
downloadmailfromd-2e9e8087eef5452299cfc839b7b4cc23bb2feb6c.tar.gz
mailfromd-2e9e8087eef5452299cfc839b7b4cc23bb2feb6c.tar.bz2
Version 5.0.93
* NEWS, configure.ac: Raise patchlevel to 93. * doc/mailfromd.texi: Document new features. * mfd/tbf_rate.c (tbf_rate_format_struct): Change dbid to `tbf'.
Diffstat (limited to 'doc/mailfromd.texi')
-rw-r--r--doc/mailfromd.texi570
1 files changed, 461 insertions, 109 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 8a6d66b5..8276c6f9 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -125,14 +125,15 @@ Appendices
Preface
* History:: Short @command{mailfromd} history.
-* Conventions:: Typographical conventions.
* Acknowledgments:: Acknowledgments.
Introduction to @command{mailfromd}
+* Conventions:: Typographical conventions.
* Overview:: Mailfromd at a first glance
* SAV:: Principles of Sender Address Verification.
* Rate Limit:: Controlling Mail Sending Rate.
+* SPF:: Sender Policy Framework.
Sender Address Verification.
@@ -140,6 +141,7 @@ Sender Address Verification.
Building the Package
+* 500-510:: Upgrading from 5.0 to 5.1
* 440-500:: Upgrading from 4.4 to 5.0
* 43x-440:: Upgrading from 4.3.x to 4.4
* 420-43x:: Upgrading from 4.2 to 4.3.x
@@ -215,6 +217,8 @@ Comments
* database:: Pragma database.
* stacksize:: Pragma stacksize.
* regex:: Pragma regex.
+* dbprop:: Pragma dbprop.
+* greylist:: Pragma greylist.
Constants
@@ -251,6 +255,8 @@ Built-in and Library Functions
* System functions::
* Sieve Interface::
* Interfaces to Third-Party Programs::
+* Rate limiting functions::
+* Greylisting functions::
* Special test functions::
* Mail Sending Functions::
* NLS Functions::
@@ -309,8 +315,49 @@ Command Line Options.
Pmilter multiplexer program.
-* pmult invocation::
* pmult configuration::
+* pmult example::
+* pmult invocation::
+
+Pmult Configuration
+
+* pmult-conf:: Multiplexer Configuration.
+* pmult-macros:: Translating MeTA1 macros.
+* pmult-client:: Pmult Client Configuration.
+* pmult-debug:: Debugging Pmult.
+
+Pies -- a program execution supervisor.
+
+* Pies Configuration File::
+* Component Statement::
+* include-meta1::
+* Global Configuration::
+* Pies Debugging::
+* Configuration Example::
+* Command Line Usage::
+* Pies Invocation::
+
+Component Statement
+
+* Prerequisites::
+* Component Privileges::
+* Resources::
+* Actions Before Startup::
+* Exit Actions::
+* Output Redirectors::
+* Inetd-Style Components::
+* Meta1-Style Components::
+* Component Syntax Summary::
+
+Global Configuration
+
+* Less Useful Statements::
+
+Configuration Example
+
+* Simple Pies::
+* Hairy Pies::
+* Inetd Pies::
@end detailmenu
@end menu
@@ -358,7 +405,6 @@ Invoke external programs or other mail filters.
@menu
* History:: Short @command{mailfromd} history.
-* Conventions:: Typographical conventions.
* Acknowledgments:: Acknowledgments.
@end menu
@@ -427,43 +473,16 @@ future versions. Another new features in this release include
simulator designed for testing @command{mailfromd} scripts
(@pxref{mtasim}). The test suite in this version was made portable by
rewriting it in @i{Autotest}.
-
-@node Conventions
-@unnumberedsec Typographical conventions
-
-@cindex Texinfo
- This manual is written using Texinfo, the GNU documentation
-formatting language. The same set of Texinfo source files is used to
-produce both the printed and online versions of the documentation.
-@ifnotinfo
-Because of this, the typographical conventions
-may be slightly different than in other books you may have read.
-@end ifnotinfo
-@ifinfo
-This section briefly documents the typographical conventions used in
-this manual.
-@end ifinfo
-
- Examples you would type at the command line are preceded by the common
-shell primary prompt, @samp{$}. The command itself is printed @kbd{in
-this font}, and the output it produces @samp{in this font}, for
-example:
-@smallexample
-$ @kbd{mailfromd --version}
-mailfromd (mailfromd @value{VERSION})
-@end smallexample
-
-In the text, the command names are printed @command{like this},
-command line options are displayed in @option{this font}. Some
-notions are emphasized @emph{like this}, and if a point needs to be made
-strongly, it is done @strong{this way}. The first occurrence of
-a new term is usually its @dfn{definition} and appears in the same
-font as the previous occurrence of ``definition'' in this sentence.
-File names are indicated like this: @file{/path/to/ourfile}.
-
-The variable names are represented @var{like this}, keywords and
-fragments of program text are written in @code{this font}.
+ Another big leap forward was the 5.0 release, which appeared on
+December 26, 2008. It largely enriched a set of available functions
+(61 new functions were introduced, which amounts to 41% of all the
+available functions in 5.0 release) and introduced several
+improvements in the MFL itself. Among others, function aliases and
+optional arguments in user-defined functions were introduced in this
+release. The new ``run operation mode'' allowed to execute arbitrary
+MFL functions from the command line. This release also raised the
+Mailutils version requirements to at least 2.0.
@node Acknowledgments
@unnumberedsec Acknowledgments
@@ -503,6 +522,15 @@ comments. He offered invaluable help in debugging and testing
Sergey Afonin proposed many improvements and new ideas. He also
invested a lot of his time in finding bugs and testing bugfixes.
+@cindex John McEleney
+@cindex Ben McKeegan
+ John McEleney and Ben McKeegan contributed the token bucket filter
+implementation (@code{tbf_rate} function, @FIXME-pxref{}).
+
+@cindex Con Tassios
+ Con Tassios helped to find and fix various bugs and contributed the
+new implementation of the @code{greylist} function (@FIXME-pxref{}).
+
The following people (in alphabetical order) provided bug reports
and helpful comments for various versions of the program:
@cindex Alan Dobkin
@@ -530,12 +558,13 @@ interfaces with the @acronym{MTA} using @command{Milter} protocol.
The name @command{mailfromd} can be thought of as an abbreviation for
@samp{@emph{Mail} @emph{F}iltering and @emph{R}untime
-@emph{M}odification}, with an @samp{o} for itself. Historically, it
-stemmed from the fact that the original implementation was a simple
-filter implementing the @dfn{sender address verification} technique.
-Since then the program has changed dramatically, and now it is
-actually a language translator and run-time evaluator providing a set
-of built-in and library functions for filtering electronic mail.
+@emph{M}odification} @emph{D}aemon, with an @samp{o} for itself.
+Historically, it stemmed from the fact that the original
+implementation was a simple filter implementing the @dfn{sender
+address verification} technique. Since then the program has changed
+dramatically, and now it is actually a language translator and
+run-time evaluator providing a set of built-in and library functions
+for filtering electronic mail.
The first part of this manual is an overview, describing the features
@command{mailfromd} offers in general.
@@ -556,11 +585,50 @@ said about a specific topic.
@acronym{SMTP} protocol and @command{Sendmail} mail transport system.
@menu
+* Conventions:: Typographical conventions.
* Overview:: Mailfromd at a first glance
* SAV:: Principles of Sender Address Verification.
* Rate Limit:: Controlling Mail Sending Rate.
+* SPF:: Sender Policy Framework.
@end menu
+@node Conventions
+@section Typographical conventions
+
+@cindex Texinfo
+ This manual is written using Texinfo, the GNU documentation
+formatting language. The same set of Texinfo source files is used to
+produce both the printed and online versions of the documentation.
+@ifnotinfo
+Because of this, the typographical conventions
+may be slightly different than in other books you may have read.
+@end ifnotinfo
+@ifinfo
+This section briefly documents the typographical conventions used in
+this manual.
+@end ifinfo
+
+ Examples you would type at the command line are preceded by the common
+shell primary prompt, @samp{$}. The command itself is printed @kbd{in
+this font}, and the output it produces @samp{in this font}, for
+example:
+
+@smallexample
+$ @kbd{mailfromd --version}
+mailfromd (mailfromd @value{VERSION})
+@end smallexample
+
+In the text, the command names are printed @command{like this},
+command line options are displayed in @option{this font}. Some
+notions are emphasized @emph{like this}, and if a point needs to be made
+strongly, it is done @strong{this way}. The first occurrence of
+a new term is usually its @dfn{definition} and appears in the same
+font as the previous occurrence of ``definition'' in this sentence.
+File names are indicated like this: @file{/path/to/ourfile}.
+
+The variable names are represented @var{like this}, keywords and
+fragments of program text are written in @code{this font}.
+
@node Overview
@section Mailfromd at a first glance
@@ -731,12 +799,27 @@ doing the forwarding.
@cindex mail sending rate, explained
@cindex sending rate, explained
- @dfn{Mail Sending Rate} for a given identity is defined as number of
+ @dfn{Mail Sending Rate} for a given identity is defined as the number of
messages with this identity received within a predefined interval of
time.
- @acronym{MFL} offers a special function @code{rate} (@pxref{rate})
-that computes the sending rate for the given identity.
+ @acronym{MFL} offers a set of functions for limiting mail sending
+rate (@pxref{Rate limiting functions}), and for controlling broader
+rate aspects, such as data transfer rates (@pxref{TBF}).
+
+@node SPF
+@section SPF
+@cindex @acronym{SPF}
+@cindex Sender Policy Framework
+ @dfn{Sender Policy Framework}, or @acronym{SPF} for short, is an
+extension to @acronym{SMTP} protocol that allows to identify forged
+identities supplied with the @code{MAIL FROM} and @code{HELO}
+commands. The framework is explained in detail in @acronym{RFC} 4408
+(@uref{http://tools.ietf.org/html/rfc4408}) and on the
+@uref{http://www.openspf.org/, SPF Project Site}.
+
+ Mailfromd provides a set of functions (@pxref{SPF Functions}) for
+using @acronym{SPF} to control mail flow.
@node Building, Tutorial, Intro, Top
@chapter Building the Package
@@ -919,7 +1002,7 @@ expiration intervals: @code{DEFAULT_DNS_NEGATIVE_EXPIRE_INTERVAL} sets
expiration time for cached negative @acronym{DNS} answers (@pxref{DNS Cache
Management}) (default 3600 seconds) and
@code{DEFAULT_EXPIRE_RATES_INTERVAL} sets default expiration time for
-mail rate database (@pxref{rate}).
+mail rate database (@pxref{Rate limiting functions}).
Expiration settings can be changed at run time using
@samp{#pragma database} statement in the filter script file
@@ -1025,6 +1108,7 @@ the corresponding section below.
@end enumerate
@menu
+* 500-510:: Upgrading from 5.0 to 5.1
* 440-500:: Upgrading from 4.4 to 5.0
* 43x-440:: Upgrading from 4.3.x to 4.4
* 420-43x:: Upgrading from 4.2 to 4.3.x
@@ -1036,6 +1120,11 @@ the corresponding section below.
* 1x-2x:: Upgrading from 1.x to 2.x
@end menu
+@node 500-510
+@section Upgrading from 5.0 to 5.1
+@cindex Upgrading from 5.0 to 5.1
+@WRITEME
+
@node 440-500
@section Upgrading from 4.4 to 5.0
@cindex Upgrading from 4.4 to 5.0
@@ -1412,7 +1501,8 @@ done
@item
If your code contained any @code{rate} statements, convert them to
-function calls (@pxref{rate}), using the following scheme:
+function calls (@pxref{Rate limiting functions, rate}), using the
+following scheme:
@smallexample
@group
@@ -2362,30 +2452,48 @@ to use a conjunction @var{email}-@var{sender_ip} instead, so the
actual @var{email} owner won't be blocked by actions of some spammer
abusing his/her address.
- To control and update sending rates, the @code{rate} function is
-provided. It takes two mandatory arguments: @code{key}, whose meaning
-is described above, and @code{interval}, or the number of seconds, to
-which the actual sending rate value is converted. Remember, that it is
-stored internally as a floating point number, and thus cannot be used
-in @command{mailfromd} filters, which operate only on integer numbers.
-To use the rate value, it is first converted to messages per given
-interval, which is an integer number. For example, the rate
+ Two functions are provided to control and update sending rates. The
+@code{rateok} function takes three mandatory arguments:
+
+@smallexample
+ bool rateok(string @var{key}, number @var{interval}, number @var{threshold})
+@end smallexample
+
+The @var{key} meaning is described above. The @var{interval} is the
+sampling interval, or the number of seconds to which the actual
+sending rate value is converted. Remember that it is stored
+internally as a floating point number, and thus cannot be directly
+used in @command{mailfromd} filters, which operate only on integer
+numbers. To use the rate value, it is first converted to messages per
+given interval, which is an integer number. For example, the rate
@code{0.138888} brought to 1-hour interval gives @code{500}
(messages per hour).
- Wherever the @code{rate} function is called, it recomputes and
-updates the rate record for the given @var{key}, and returns its
-value, converted to messages per interval. For example, the following
-code limits the mail sending rate for each @samp{email
-address}-@samp{@acronym{IP}} combination to 180 per hour. If the
-actual rate value exceeds this limit, the sender is returned a
+ Wherever the @code{rateok} function is called, it recomputes the
+rate record for the given @var{key}. If the new rate value converted
+to messages per given @var{interval} is less than @var{threshold},
+the function updates the database and returns @code{True}. Otherwise it
+returns @code{False} and does not update the database.
+
+ This function must be @dfn{required} prior to use, by placing the
+following statement somewhere at the beginning of your script:
+
+@smallexample
+#require rateok
+@end smallexample
+
+For example, the following code limits the mail sending rate for each
+@samp{email address}-@samp{@acronym{IP}} combination to 180 per hour.
+If the actual rate value exceeds this limit, the sender is returned a
temporary failure response:
@smallexample
@group
+#require rateok
+
prog envfrom
do
- if rate($f "-" $@{client_addr@}, 3600) > 180
+ if not rateok($f "-" $@{client_addr@}, 3600, 180)
tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
fi
done
@@ -2396,33 +2504,117 @@ done
Notice argument concatenation, used to produce the key.
It is often inconvenient to specify intervals in seconds,
-therefore a special @code{interval} function is provided, which
+therefore a special @code{interval} function is provided. It
converts its argument, which is a textual string representing time
interval in English, to the corresponding number of seconds. Using
this function, the function invocation would be:
@smallexample
- rate($f "-" $@{client_addr@}, interval("1 hour"))
+ rateok($f "-" $@{client_addr@}, interval("1 hour"), 180)
@end smallexample
The @code{interval} function is described in @ref{interval}, and time
intervals are discussed in @ref{time interval specification}.
- The @code{rate} function begins returning non-zero value as soon as
-it has enough data to compute the rate. By default, it needs at least
-two mails. Since this may lead to a big number of false positives
+ The @code{rateok} function begins computing the rate
+as soon as it has collected enough data. By default, it needs at least
+four mails. Since this may lead to a big number of false positives
(i.e. overestimated rates) at the beginning of sampling interval,
-there is a way to specify a minimum number of samples @code{rate} must
-collect before starting to actually compute rates. This number of
-samples is given as the optional third argument to the function. For
-example, the following call will return 0 unless at least 10 mails
-with the given key value were detected:
+there is a way to specify a minimum number of samples @code{rateok}
+must collect before starting to actually compute rates. This number of
+samples is given as the optional fourth argument to the function. For
+example, the following call will always return @code{True} for the
+first 10 mails, no matter what the actual rate:
+
+@smallexample
+ rateok($f "-" $@{client_addr@}, interval("1 hour"), 180, 10)
+@end smallexample
+
+@anchor{TBF}
+ The @code{tbf_rate} function allows to exercise more control over
+the mail rates. This function implements a @dfn{token bucket filter}
+(@acronym{TBF}) algorithm.
+
+ The token bucket controls when the data can be transmitted based on
+the presence of abstract entities called @dfn{tokens} in a container
+called @dfn{bucket}. Each token represents some amount of data. The
+algorithm works as follows:
+
+@itemize @bullet
+@item A token is added to the bucket at a constant rate of 1 token per
+@var{t} microseconds.
+@item A bucket can hold at most @var{m} tokens. If a token arrives
+when the bucket is full, that token is discarded.
+@item When @var{n} items of data arrive (e.g. @var{n} mails), @var{n}
+tokens are removed from the bucket and the data are accepted.
+@item If fewer than @var{n} tokens are available, no tokens are
+removed from the bucket and the data are not accepted.
+@end itemize
+
+ This algorithm allows to keep the data traffic at a constant rate
+@var{t} with bursts of up to @var{m} data items. Such bursts occur
+when no data was being arrived for @var{m}*@var{t} or more
+microseconds.
+
+ @command{Mailfromd} keeps buckets in a database @samp{tbf}. Each
+bucket is identified by a unique @dfn{key}. The @code{tbf_rate}
+function is defined as follows:
@smallexample
- rate($f "-" $@{client_addr@}, interval("1 hour"), 10)
+ bool tbf_rate(string @var{key}, number @var{n}, number @var{t}, number @var{m})
@end smallexample
-For additional information about @code{rate} function, see @ref{rate}.
+The @var{key} identifies the bucket to operate upon. The rest of
+arguments is described above. The @code{tbf_rate} function returns
+@samp{True} if the algorithm allows to accept the data and
+@samp{False} otherwise.
+
+Depending on how the actual arguments are selected the @code{tbf_rate}
+function can be used to control various types of flow rates. For
+example, to control mail sending rate, assign the arguments as
+follows: @var{n} to the number of mails and @var{t} to the control
+interval in microseconds:
+
+@smallexample
+@group
+prog envfrom
+do
+ if not tbf_rate($f "-" $client_addr, 1, 10000000, 20)
+ tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
+ fi
+done
+@end group
+@end smallexample
+
+The example above permits to send at most one mail each 10 seconds.
+The burst size is set to 20.
+
+Another use for the @code{tbf_rate} function is to limit the total
+delivered mail size per given interval of time. To do so, the
+function must be used in @code{prog eom} handler, because it is the
+only handler where the entire size of the message is known. The
+@var{n} argument must contain the number of bytes in the email (or
+email bytes * number of recipients), and the @var{t} must be set to
+the number of bytes per microsecond a given user is allowed to send. The
+@var{m} argument must be large enough to accommodate a couple of
+large emails. E.g.:
+
+@smallexample
+@group
+ prog eom
+ do
+ if not tbf_rate($f "-" $client_addr,
+ message_size(current_message()),
+ 10240*1000000, # At most 10 kb/sec
+ 10*1024*1024)
+ tempfail 450 4.7.0 "Data sending rate exceeded. Try again later"
+ fi
+ done
+@end group
+@end smallexample
+
+@xref{Rate limiting functions}, for more information about
+@code{rateok} and @code{tbf_rate} functions.
@node Greylisting
@section Greylisting
@@ -2502,6 +2694,49 @@ addresses in your relayed domain. It can easily be done using the
techniques described in previous sections and is left as an exercise
to the reader.
+@anchor{greylisting types}
+@cindex greylisting types
+@cindex greylisting, traditional
+ @code{Mailfromd} provides two implementations of greylisting
+primitives, which differ in the information stored in the database.
+The one described above is called @dfn{traditional}. It keeps in the
+database the time when the greylisting was activated for the given
+key, so the @code{greylisting} function uses its second argument
+(@code{interval}) and the current timestamp to decide whether the key
+is still greylisted.
+
+@cindex greylisting, Con Tassios type
+@cindex Con Tassios greylisting type
+ The second implementation is called by the name of its inventor
+@dfn{Con Tassios}. This implementation stores in the database the
+time when the greylisting period is set to expire, computed by the
+@code{greylist} when it is first called for the given key, using the
+formula @samp{current_timestamp + interval}. Subsequent calls to
+@code{greylist} compare the current timestamp with the one stored in
+the database and ignore their second argument. This implementation is
+enabled by one of the following pragmas:
+
+@smallexample
+#pragma greylist con-tassios
+@end smallexample
+@noindent
+or
+@smallexample
+#pragma greylist ct
+@end smallexample
+
+ When Con Tassios implementation is used, yet another function
+becomes available. The function @code{is_greylisted} returns
+@samp{True} if its argument is greylisted and @samp{False} otherwise.
+It can be used to check for the greylisting status without actually
+updating the database:
+
+@smallexample
+ if is_greylisted($@{client_addr@} "-" $f "-" $@{rcpt_addr@})
+ @dots{}
+ fi
+@end smallexample
+
@anchor{whitelisting}
@cindex whitelisting
One special case is @dfn{whitelisting}, which is often used
@@ -2729,31 +2964,46 @@ period, applied to entries marked as @code{not_found}.
@cindex rate database
@item rate
The mail sending rate data, maintained by @code{rate} function
-(@pxref{rate}). A record consists of the following fields:
+(@pxref{Rate limiting functions}). A record consists of the following fields:
-@enumerate 1
-@item
-Timestamp. The time when the entry was entered into the database. It
-is used to check for expired entries.
+@table @asis
+@item timestamp
+The time when the entry was entered into the database.
-@item
+@item interval
Interval during which the rate was measured (seconds).
-@item
+@item count
Number of mails sent during this interval.
+@end table
-@item
-Actual mail sending rate.
+@cindex tbf database
+@item tbf
+This database is maintained by @code{tbf_rate} function (@pxref{TBF}).
+Each record represents a single bucket and consists of the following
+keys:
-@item
-Expected rate, i.e. the mail sending rate that would have been achieved if
-this sender had sent an email right now.
-@end enumerate
+@table @asis
+@item timestamp
+Timestamp of most recent token, as a 64-bit unsigned integer
+(microseconds resolution).
+
+@item expirytime
+Estimated time when this bucket expires (seconds since epoch).
+
+@item tokens
+Number of tokens in the bucket (@code{size_t}).
+@end table
@cindex greylist database
@item greylist
This database is maintained by @code{greylist} function
(@pxref{Greylisting}). Each record holds only the timestamp.
+Its semantics depends on the greylisting implementation in
+use (@pxref{greylisting types}). In traditional implementation, it
+is the time when the entry was entered into the database. In Con
+Tassios implementation, it is the time when the greylisting period
+expires.
@end table
@node Basic Database Operations
@@ -3803,7 +4053,7 @@ prior to using. Otherwise it is no more than a literal, and the whole
construct @samp{hostname($client_addr)} is regarded by @acronym{MFL}
compiler as a concatenation of the string @samp{hostname} and the
value of @samp{client_addr} Sendmail variable. It is easy to see
-using @option{--dump-tree} option:
+using the @option{--dump-tree} option:
@smallexample
$ @kbd{mailfromd --dump-tree test.mf}
@@ -3886,7 +4136,7 @@ done
@end smallexample
Does @code{%x} in @code{echo} refers to the variable or to the
-constant? The correct answer is @samp{to the constant}; when executed this
+constant? The correct answer is @samp{to the variable}. When executed this
code will print @samp{X is X}.
The reason for such a name clash is entirely artificial. Indeed, the
@@ -3902,6 +4152,7 @@ do
done
@end smallexample
+This is because @code{x} alone can refer only to constant.
Problems begin when we need to expand a constant in a
literal string. The only way to do so is by prefixing its name with a
@samp{%}, just as if it were variable, and that produces the
@@ -4115,6 +4366,7 @@ and @samp{#pragma regex} controls the compilation of regular expressions.
* stacksize:: Pragma stacksize.
* regex:: Pragma regex.
* dbprop:: Pragma dbprop.
+* greylist:: Pragma greylist.
@end menu
@node option
@@ -4672,6 +4924,35 @@ regex settings. E.g.:
This pragma configures properties for a @acronym{DBM} database.
@xref{Database functions}, for its detailed description.
+@node greylist
+@subsection Pragma greylist
+@cindex greylist, pragma
+@cindex #pragma greylist
+
+@smallexample
+#pragma greylist @var{type}
+@end smallexample
+
+ This pragma selects the greylisting implementation to use. Allowed
+values for @var{type} are:
+
+@table @asis
+@item traditional
+@itemx gray
+Use the traditional greylisting implementation. This is the default.
+
+@item con-tassios
+@itemx ct
+Use Con Tassios greylisting implementation.
+@end table
+
+@xref{greylisting types}, for a detailed description of available
+greylisting implementations.
+
+Notice, that this pragma can be used only once. Second use of this
+pragma constitutes an error, because you cannot use both greylisting
+implementations in the same program.
+
@node Data Types
@section Data Types
@@ -5826,7 +6107,7 @@ handlers. @FIXME{It could be a useful feature, though.}
@cindex @samp{end} and @code{tempfail}
@item The following Sendmail actions cannot be used in them:
@code{accept}, @code{continue}, @code{discard}, @code{reject},
-@code{tempfail}. They can, however, be used in @code{cache}
+@code{tempfail}. They can, however, be used in @code{catch}
statements, declared in @samp{begin} blocks (see example below).
@cindex @code{add} in @samp{begin}
@@ -5965,6 +6246,8 @@ in version @value{VERSION}.
* System functions::
* Sieve Interface::
* Interfaces to Third-Party Programs::
+* Rate limiting functions::
+* Greylisting functions::
* Special test functions::
* Mail Sending Functions::
* NLS Functions::
@@ -8095,14 +8378,82 @@ done
@end smallexample
@end deftypefn
-@node Special test functions
-@subsubsection Special Test Functions
+@node Rate limiting functions
+@subsubsection Rate limiting functions
-@deftypefn {Built-in Function} number greylist @
+@deftypefn {Built-in Function} number rate (string @var{key}, @
+ number @var{sample-interval}, @
+ [number @var{min-samples}, number @var{threshold}])
+
+ Returns the mail sending rate for @var{key} per
+@var{sample-interval}. Optional @var{min-samples}, if supplied,
+specifies the minimal number of mails needed to obtain the
+statistics. The default is 2. Optional @var{threshold}
+controls rate database updates. If the observed rate (per
+@var{sample-interval} seconds) is higher than the @var{threshold}, the
+hit counters for that key are not incremented and the database is not
+updated. Althouth the @var{threshold} argument is
+optional@footnote{It is made optional in order to provide backward
+compatibility with the releases of mailfromd prior to 5.0.93.}, its
+use is strongly encouraged. Normally, the value of @var{threshold} equals
+the value compared with the return from @var{rate}, as in:
+
+@smallexample
+@group
+ if rate($f "-" $client_addr, %rate_interval, 4, %maxrate) > %maxrate
+ tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
+ fi
+@end group
+@end smallexample
+
+This function is a low-level interface. Instead of using it directly,
+we advise to use the @code{rateok} function, described below.
+@end deftypefn
+
+@deftypefn {Library Function} boolean rateok (string @var{key}, @
+ number @var{sample-interval}, @
+ number @var{threshold},
+ [number @var{min-samples}])
+
+@flindex rateok.mf
+To use this function, require @file{rateok.mf} module
+(@pxref{Modules}), e.g.: @code{#require rateok}.
+
+The @code{rateok} function returns @samp{True} if the mail sending
+rate for @var{key}, computed for the interval of @var{sample-interval}
+seconds is less than the @var{threshold}. Optional @var{min-samples}
+parameter supplies the minimal number of mails needed to obtain the
+statistics. It defaults to 4.
+@end deftypefn
+
+@xref{Sending Rate}, for a detailed description of the @code{rateok} and
+its use. The @code{interval} function (@pxref{interval}) is often
+used in the second argument to @code{rateok} or @code{rate}.
+
+@deftypefn {Built-in Function} boolean tbf_rate (string @var{key}, @
+ number @var{cost}, number @var{sample-interval}, number @var{burst-size})
+
+ This function implements a classical token bucket filter algorithm.
+Tokens are added to the bucket identified by the @var{key} at constant
+rate of 1 token per @var{sample-interval} microseconds, to a maximum
+of @var{burst-size} tokens. If no bucket is found for the specified key, a
+new bucket is created and initialized to contain @var{burst-size}
+tokens. If the bucket contains @var{cost} or more tokens, @var{cost}
+tokens are removed from it and @code{tbf_rate} returns @samp{True}.
+Otherwise, the function returns @samp{False}.
+
+ For a detailed description of the Token Bucket Algorithm and its
+use to limit mail rates, see @ref{TBF}.
+@end deftypefn
+
+@node Greylisting functions
+@subsubsection Greylisting functions
+
+@deftypefn {Built-in Function} boolean greylist @
(string @var{key}, number @var{interval})
@cindex greylist_seconds_left, global variable
- Returns true if the @var{key} is found in the greylist database
+ Returns @samp{True} if the @var{key} is found in the greylist database
(controlled by @code{#pragma database greylist} pragma, @pxref{database}). The argument @var{interval} gives the greylisting
interval in seconds. The function stores the number of seconds left to the end
of greylisting period in the internal variable
@@ -8112,20 +8463,20 @@ explanation.
The function @code{greylist} can signal @code{e_dbfailure} exception.
@end deftypefn
-@deftypefn {Built-in Function} boolean listens (string @var{host}, [number @var{port}])
- Returns @code{true} if the @acronym{IP} address or host name given by
-@var{host} argument listens on the port number @var{port} (default 25).
+@deftypefn {Built-in Function} boolean is_greylisted (string @var{key}
+Returns @samp{True} if the @var{key} is still greylisted. This
+function is available only if Con Tassios implementation of
+greylisting is used. @xref{greylisting types}, for a discussion of
+available greylisting implementations. @xref{greylist}, for a
+way to switch to Con Tassios implementation.
@end deftypefn
-@anchor{rate}
-@deftypefn {Built-in Function} number rate (string @var{key}, @
- number @var{sample-interval}, [number @var{threshold}])
+@node Special test functions
+@subsubsection Special Test Functions
- Returns the mail sending rate for @var{key} per
-@var{sample-interval}. Optional @var{threshold}, if supplied,
-specifies the minimal number of mails needed to obtain the
-statistics. The default is 2. @xref{Sending Rate}, for a detailed
-discussion.
+@deftypefn {Built-in Function} boolean listens (string @var{host}, [number @var{port}])
+ Returns @code{true} if the @acronym{IP} address or host name given by
+@var{host} argument listens on the port number @var{port} (default 25).
@end deftypefn
@deftypefn {Built-in Function} boolean validuser (string @var{name})
@@ -11447,6 +11798,7 @@ required source modules:
@group
#include <status.mfh>
#require dns
+#require rateok
@end group
@end smallexample
@@ -11527,7 +11879,7 @@ not exceed allowed mail sending rate:
@smallexample
@group
- if rate($f "-" $client_addr, interval("1 hour 30 minutes")) > 100
+ if not rateok($f "-" $client_addr, interval("1 hour 30 minutes"), 100)
tempfail 450 4.7.0 "Mail sending rate exceeded. Try again later"
fi
done

Return to:

Send suggestions and report system problems to the System administrator.