aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--NEWS17
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/fdl.texi1
-rw-r--r--doc/gacopyz.texi1
-rw-r--r--doc/mailfromd.texi664
-rw-r--r--doc/strftime.texi1
-rw-r--r--doc/upgrade.texi474
-rw-r--r--etc/mailfromd.rc25
-rw-r--r--mfd/lex.l14
9 files changed, 666 insertions, 532 deletions
diff --git a/NEWS b/NEWS
index ba959685..9c838261 100644
--- a/NEWS
+++ b/NEWS
@@ -1,7 +1,7 @@
-Mailfromd NEWS -- history of user-visible changes. 2009-05-04
+Mailfromd NEWS -- history of user-visible changes. 2009-05-06
Copyright (C) 2005, 2006, 2007, 2008, 2009 Sergey Poznyakoff
See the end of file for copying conditions.
Please send Mailfromd bug reports to <bug-mailfromd@gnu.org.ua>
@@ -142,12 +142,27 @@ 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.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8003e824..c10bb0b1 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -22,12 +22,13 @@ mailfromd_TEXINFOS=\
mtasim.texi\
pies.texi\
pmult.texi\
rendition.texi\
smap.texi\
strftime.texi\
+ upgrade.texi\
values.texi
EXTRA_DIST = \
check-docs.sh\
gendocs_template\
mastermenu.el\
diff --git a/doc/fdl.texi b/doc/fdl.texi
index a3c8c6fa..7da87389 100644
--- a/doc/fdl.texi
+++ b/doc/fdl.texi
@@ -1,8 +1,7 @@
@setfilename fdl.info
-@appendix GNU Free Documentation License
@cindex FDL, GNU Free Documentation License
@center Version 1.2, November 2002
@display
Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
diff --git a/doc/gacopyz.texi b/doc/gacopyz.texi
index 5eecc6f2..7354db6c 100644
--- a/doc/gacopyz.texi
+++ b/doc/gacopyz.texi
@@ -1,13 +1,12 @@
@c Copyright (C) 2005, 2006 Sergey Poznyakoff
@c Permission is granted to copy, distribute and/or modify this document
@c under the terms of the GNU Free Documentation License, Version 1.2 or
@c any later version published by the Free Software Foundation; with no
@c Invariant Sections, with the Front-Cover texts being ``Mailfromd Manual'',
@c and with the Back-Cover Texts at your option.
-@appendix Gacopyz
@ifhtml
@quotation
Gacopyz, panie, to mówią ze to mysa... Ze to tako
mysa co świeckę w kościele zjadła i wniebowstąpienia
dostąpiła. A to nie je mysa, ino gacopyz! To nadprzyrodzłyne,
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi
index 8276c6f9..8ac9d7bb 100644
--- a/doc/mailfromd.texi
+++ b/doc/mailfromd.texi
@@ -84,19 +84,19 @@ Software Foundation raise funds for GNU development.''
@page
@summarycontents
@page
@contents
-@node Top, Preface, (dir), (dir)
+@ifnottex
+@node Top
+@top Mailfromd
-@ifinfo
-@chapter Mailfromd
This edition of the @cite{Mailfromd Manual}, last updated @value{UPDATED},
documents @command{mailfromd} Version @value{VERSION}.
-@end ifinfo
+@end ifnottex
@menu
* Preface:: Short description of this manual; brief
history and acknowledgments.
* Intro:: Introduction to Mailfromd.
* Building:: Building the Package.
@@ -113,12 +113,13 @@ documents @command{mailfromd} Version @value{VERSION}.
* Reporting Bugs:: How to Report a Bug.
Appendices
* Gacopyz::
* Time and Date Formats::
+* Upgrading::
* Copying This Manual:: The GNU Free Documentation License.
* Concept Index:: Index of Concepts.
@detailmenu
--- The Detailed Node Listing ---
@@ -136,25 +137,12 @@ Introduction to @command{mailfromd}
* SPF:: Sender Policy Framework.
Sender Address Verification.
* Limitations::
-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
-* 410-420:: Upgrading from 4.1 to 4.2
-* 400-410:: Upgrading from 4.0 to 4.1
-* 31x-400:: Upgrading from 3.1.x to 4.0
-* 30x-31x:: Upgrading from 3.0.x to 3.1
-* 2x-30x:: Upgrading from 2.x to 3.0.x
-* 1x-2x:: Upgrading from 1.x to 2.x
-
Tutorial
* Start Up::
* Simplest Configurations::
* Conditional Execution::
* Functions and Modules::
@@ -356,16 +344,29 @@ Global Configuration
Configuration Example
* Simple Pies::
* Hairy Pies::
* Inetd Pies::
+Upgrading
+
+* 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
+* 410-420:: Upgrading from 4.1 to 4.2
+* 400-410:: Upgrading from 4.0 to 4.1
+* 31x-400:: Upgrading from 3.1.x to 4.0
+* 30x-31x:: Upgrading from 3.0.x to 3.1
+* 2x-30x:: Upgrading from 2.x to 3.0.x
+* 1x-2x:: Upgrading from 1.x to 2.x
+
@end detailmenu
@end menu
-@node Preface, Intro, Top, Top
+@node Preface
@unnumbered Preface
Simple Mail Transfer Protocol (@acronym{SMTP}) which is the standard
for e-mail transmissions across the internet was designed in the
good old days when nobody could even think of the
possibility of e-mail being abused to send tons of unsolicited
@@ -522,17 +523,18 @@ 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{}).
+implementation (@pxref{TBF}).
@cindex Con Tassios
Con Tassios helped to find and fix various bugs and contributed the
-new implementation of the @code{greylist} function (@FIXME-pxref{}).
+new implementation of the @code{greylist} function (@pxref{greylisting
+types}).
The following people (in alphabetical order) provided bug reports
and helpful comments for various versions of the program:
@cindex Alan Dobkin
@cindex Brent Spencer
@cindex Jeff Ballard
@@ -540,13 +542,13 @@ and helpful comments for various versions of the program:
@cindex Phil Miller
@cindex Simon Christian
@cindex Thomas Lynch
Alan Dobkin, Brent Spencer, Jeff Ballard, Nacho Gonz@'alez L@'opez,
Phil Miller, Simon Christian, Thomas Lynch.
-@node Intro, Building, Preface, Top
+@node Intro
@chapter Introduction to @command{mailfromd}
@command{Mailfromd} is a general-purpose mail filtering daemon and a
suite of accompanying utilities for @command{Sendmail}@footnote{See
@uref{http://www.sendmail.org}}, @command{MeTA1}@footnote{See
@uref{http://www.meta1.org}}, @command{Postfix}@footnote{See
@@ -818,13 +820,13 @@ 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
+@node Building
@chapter Building the Package
@cindex building @command{mailfromd}
@cindex @command{mailfromd}, building
This chapter contains a detailed list of steps you need to
undertake in order to configure and build the package.
@@ -1099,459 +1101,34 @@ reconfigure the package with the right options.
@item Run @command{make} install.
@item Make sure @file{@var{localstatedir}/mailfromd} has the right owner
and mode.
@item Examine filter script file
-(@file{@var{sysconfdir}/mailfromd.etc}) and edit it, if necessary. If
-you are upgrading from an older version of @command{mailfromd}, see
-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
-* 410-420:: Upgrading from 4.1 to 4.2
-* 400-410:: Upgrading from 4.0 to 4.1
-* 31x-400:: Upgrading from 3.1.x to 4.0
-* 30x-31x:: Upgrading from 3.0.x to 3.1
-* 2x-30x:: Upgrading from 2.x to 3.0.x
-* 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
-
- This version of Mailfromd requires
-@uref{http://www.gnu.org/software/mailutils, GNU mailutils} version
-2.0 or later.
-
- Upgrading from version 4.4 to 5.0 requires no additional
-changes. The major differences between these two versions are
-summarized below:
-
-@enumerate 1
-@item Support for @samp{MeTA1}.
-
-@item New @samp{Mailutils} configuration file.
-
-@item New @acronym{MFL} functions.
-
-@enumerate a
-@item Message functions. @xref{Message functions}.
-@item Mailbox functions. @xref{Mailbox functions}.
-@item Mail body functions. @xref{Mail body functions}.
-@item Header modification functions. @xref{Header modification functions}.
-@item Envelope modification functions. @xref{Envelope modification functions}.
-@item Quarantine functions. @xref{Quarantine functions}.
-@item @code{getopt} and @code{varptr}. @xref{getopt}.
-@item Macro access functions. @xref{Macro access}.
-@item Character type functions. @xref{Character Type}.
-@item New string functions (@pxref{String manipulation}):
-@code{verp_extract_user}, @code{sa_format_report_header},
-@code{sa_format_score}.
-@item Sequential access to DBM files. @xref{dbm-seq}.
-@end enumerate
-
-@item Changes in @acronym{MFL}
-
-@enumerate 1
-@item @xref{variadic functions}.
-@item @xref{function alias}.
-@end enumerate
-
-@item New operation mode: @xref{Run Mode}.
-
-@item Improved stack growth technique.
-
-The stack can be grown either by fixed size blocks, or
-exponentially. Upper limit can be specified. @xref{stacksize}.
-
-@item Milter ports can be specified using @acronym{URL} notation.
-
-@item Removed deprecated features.
-
-Support for some deprecated features has been withdrawn. These are:
-
-@enumerate a
-@item Command line options @option{--ehlo},
-@option{--postmaster-email}, and @option{--mailfrom}.
-These became deprecated in version 4.0. @xref{31x-400}.
-@end enumerate
-
-@end enumerate
-
-@node 43x-440
-@section Upgrading from 4.3.x to 4.4
-@cindex Upgrading from 4.3.x to 4.4
-
- The deprecated @option{--domain} command line option has been
-withdrawn. The short option @option{-D} now defines a preprocessor
-symbol (@pxref{Preprocessor Options}).
-
- This version correctly handles name clashes between constants and
-variables, which remained unnoticed in previous releases.
-@xref{variable--constant shadowing}, for a detailed description of it.
-
- To minimize chances of name clashes, all symbolic exception codes has
-been renamed by prefixing them with the @samp{e_}, thus, e.g. @code{divzero}
-became @code{e_divzero}, etc. The @code{ioerr} exception code is renamed to
-@code{e_io}. @xref{status.mfh}, for a full list of the new exception codes.
-
-@cindex @code{OLD_EXCEPTION_CODES}, preprocessor symbol
- For consistency, the following most often used codes are available without
-the @samp{e_} previx: success, not_found, failure, temp_failure. This
-makes most existing user scripts suitable for use with version 4.4
-without any modification. If your script refers to any exception
-codes other than these four, you can still use it by defining a
-preprocessor symbol @code{OLD_EXCEPTION_CODES}, for example:
-
-@smallexample
-$ mailfromd -DOLD_EXCEPTION_CODES
-@end smallexample
-
-@node 420-43x
-@section Upgrading from 4.2 to 4.3.x
-@cindex Upgrading from 4.2 to 4.3.x
-@cindex @code{DEFAULT_SYSLOG_ASYNC}, @command{configure} variable
-
- Upgrading from 4.2 to 4.3 or 4.3.1 does not require any changes to
-your configuration and scripts. The only notable change in these
-versions is the following:
-
- The asynchronous syslog implementation was reported to malfunction
-on some systems (notably on Solaris), so this release does not enable
-it by default. The previous meaning of the @option{--enable-syslog-async}
-configuration option is also restored. Use this option in order to
-enable asynchronous syslog feature. To set default syslog
-implementation, use @code{DEFAULT_SYSLOG_ASYNC} configuration variable
-(@pxref{syslog-async}).
-
-The following deprecated features are removed:
-
-@enumerate
-@item @code{#pragma option ehlo} statement.
-
-It became deprecated in version 4.0. @xref{pragma-option-ehlo}.
-
-@item @code{#pragma option mailfrom} statement.
-
-It became deprecated in version 4.0. @xref{pragma-option-ehlo}.
+(@file{@var{sysconfdir}/mailfromd.etc}) and edit it, if necessary.
-@item The @option{--config-file} command line option.
-
-It became deprecated in version 3.1. @xref{30x-31x}.
-
-@item Built-in exception codes in catch statements.
-
-They are deprecated since version 4.0. @xref{31x-400}.
-@end enumerate
+@item Upgrading
+If you are upgrading from an earlier release of Mailfromd, refer to
+@ref{Upgrading}, for detailed instructions.
-@node 410-420
-@section Upgrading from 4.1 to 4.2
-@cindex Upgrading from 4.1 to 4.2
- Upgrading to this version does not require any special efforts. You
-can use your configuration files and filter scripts without any
-changes. The only difference worth noticing is that starting from this
-version @command{mailfromd} is always compiled with asynchronous
-syslog implementation. The @option{--enable-syslog-async}
-configuration file option is still available, but its meaning has
-changed: it sets the @emph{default} syslog implementation to use
-(@pxref{syslog-async}). Thus, it can be used the same way it was in
-previous versions. You can also select the syslog implementation at
-run time, see @ref{Logging and Debugging, --syslog-async option}, for
-more detailed information.
-
-@node 400-410
-@section Upgrading from 4.0 to 4.1
-@cindex Upgrading from 4.0 to 4.1
-
- Upgrading to this version does not require any special efforts. You
-can use your configuration files and filter scripts without any changes.
-Notice only the following major differences between 4.1 and 4.0:
-
-@itemize @bullet
-@item Input files are preprocessed before compilation.
-@xref{Preprocessor}, for more information.
-
-@item There is a way to discern between a not-supplied optional
-parameter, and a supplied one, having null value (@pxref{defined}).
-
-@item The version 4.1 implements @code{sprintf} function
-(@pxref{String formatting}) and @code{printf} macro
-(@pxref{Preprocessor, printf}).
-
-@item Support for some obsolete features is withdrawn. These include:
-
-@enumerate 1
-@item
-Using @samp{&@var{code}} to specify exception codes
-@item
-Pragma options: @code{retry}, @code{io-retry}, and
-@code{connect-retry}.
@end enumerate
-@end itemize
-
-@node 31x-400
-@section Upgrading from 3.1.x to 4.0
-@cindex upgrading from 3.1.x to 4.0
-
- Before building this version, please re-read the chapter
-@xref{Building}, especially the section @ref{syslog-async, Using
-non-blocking syslog}.
-
- Starting from the version 4.0, @acronym{MFL} no longer uses the
-predefined symbolic names for exception codes (previous versions used
-the @samp{&} prefix to dereference them). Instead, it relies on
-constants defined in the include file @file{status.mfh}
-(@pxref{status.mfh}).
-
- However, the script files from 3.1 series will still work, but
-the following warning messages will be displayed:
-
-@smallexample
-Warning: obsolete constant form used: &failure
-Warning: remove leading '&' and include <status.mfh>
-
-Warning: Using built-in exception codes is deprecated
-Warning: Please include <status.mfh>
-@end smallexample
-
-@anchor{pragma-option-ehlo}
- Another important difference is that pragmatic options @samp{ehlo}
-and @samp{mailfromd} are now deprecated, as well as their command line
-equivalents @option{--ehlo} and @option{--domain}. These options
-became superfluous after the introduction of @code{mailfrom_address}
-and @code{ehlo_domain} built-in variables. For compatibility with the
-previous versions, they are still supported by @command{mailfromd}
-4.0, but a warning message is issued if they are used:
-
-@smallexample
-@group
-warning: `#pragma option ehlo' is deprecated,
- consider using `set ehlo_domain "domain.name"' instead
-@end group
-@end smallexample
-
- To update your startup scripts for the new version follow these
-steps:
-
-@enumerate 1
-@item
- Change @code{#pragma option mailfrom @var{value}} to
-@code{set mailfrom_address @var{value}}. Refer to
-@ref{mailfrom_address}, for a detailed discussion of this variable.
-
-@item
- Change @code{#pragma option ehlo @var{value}} to
-@code{set ehlo_domain @var{value}}. Refer to
-@ref{ehlo_domain}, for a detailed discussion of this variable.
-@item
- Include @file{status.mfh}. Add the following line to the top of
-your startup file:
-
-@smallexample
-#include_once <status.mfh>
-@end smallexample
-
-@item
- Remove all instances of @samp{&} in front of the constants. You can
-use the following @command{sed} expression: @samp{s/&\([a-z]\)/\1/g}.
-
-@item
- If your code uses any of the following functions: @code{hostname},
-@code{resolve}, @code{hasmx} or @code{ismx}, add the following line
-to the top of your script:
-
-@smallexample
-#require dns
-@end smallexample
-
-@xref{Modules}, for a detailed description of the module system.
-
-@item
- Replace all occurrences of @code{next} with @code{pass}.
-
-@item
- If your code uses function @code{match_cidr}, add the following line
-to the top of your script:
-
-@smallexample
-#require match_cidr
-@end smallexample
-
-@xref{Modules}, for a description of @acronym{MFL} module system.
-
-@end enumerate
-
-@node 30x-31x
-@section Upgrading from 3.0.x to 3.1
-@cindex upgrading from 3.0.x to 3.1
-
-@enumerate 1
-@item
- The @command{mailfromd} binary no longer supports
-@option{--config-file} (@option{-c}) option. To use an alternative
-script file, give it as an argument, i.e. instead of:
-
-@smallexample
-$ @kbd{mailfromd --config-file @var{file.rc}}
-@end smallexample
-
-@noindent
-write:
-@smallexample
-$ @kbd{mailfromd @var{file.rc}}
-@end smallexample
-
- For backward compatibility, the old style invocation still works but
-produces a warning message. However, if @command{mailfromd}
-encounters the @option{-c} option it will print a diagnostic message
-and exit immediately. This is because the semantics of this option
-will change in the future releases.
-
-@item
- If a variable is declared implicitly within a function, it is
-created as automatic. This differs from the previous versions, where
-all variables were global. It is a common practice to use global
-variables to pass additional information between handlers (@xref{HELO
-Domain}, for an example of this approach). If your filter uses it,
-make sure the variable is declared as global. For example, this code:
-
-@float Figure, old-code
-@caption{Implicit declaration, old style}
-@smallexample
-prog helo
-do
- # @r{Save the host name for further use}
- set helohost $s
-done
-@end smallexample
-@end float
-
-@noindent
-has to be rewritten as follows:
-
-@float Figure, new-code
-@caption{Implicit declaration, new style}
-@smallexample
-set helohost ""
-
-prog helo
-do
- # @r{Save the host name for further use}
- set helohost $s
-done
-@end smallexample
-@end float
-
-@item
- Starting from version 3.1 the function @code{dbmap} takes an
-optional third argument indicating whether or not to count the
-terminating null character in key (@pxref{dbmap}). If your startup
-script contained any calls to @code{dbmap}, change them as follows:
-
-@multitable @columnfractions 0.5 0.5
-@headitem in 3.0.x @tab in 3.1
-@item dbmap(@var{db}, @var{key}) @tab dbmap(@var{db}, @var{key}, 1)
-@end multitable
-
-@end enumerate
-
-
-@node 2x-30x
-@section Upgrading from 2.x to 3.0.x
-@cindex upgrading from 2.x to 3.0.x
- Update your startup scripts and/or crontab entries. The
-@command{mailfromd} binary is now installed in @file{$@{prefix@}/sbin}.
-
- We also encourage you to update the startup script (run
-@kbd{cp etc/rc.mailfromd /wherever-your-startup-lives}), since the new
-version contains lots of enhancements.
-
-@node 1x-2x
-@section Upgrading from 1.x to 2.x
-@cindex upgrading from 1.x to 2.x
- If you are upgrading from version 1.x to 2.0, you will have to do
-the following:
-
-@enumerate 1
-@item
-Edit your script file and enclose the entire code section into:
-
-@smallexample
-@group
-prog envfrom
-do
- @dots{}
-done
-@end group
-@end smallexample
-
-@noindent
-@xref{Handlers}, for more information about the @code{prog} statement.
-
-@item
-If your code contained any @code{rate} statements, convert them to
-function calls (@pxref{Rate limiting functions, rate}), using the
-following scheme:
-
-@smallexample
-@group
-Old statement: if rate @var{key} @var{limit} / @var{expr}
-New statement: if rate(@var{key}, interval("@var{expr}")) > @var{limit}
-@end group
-@end smallexample
-
-For example,
-@smallexample
- rate $f 180 / 1 hour 25 minutes
-@end smallexample
-@noindent
-should become
-@smallexample
- rate($f, interval("1 hour 25 minutes")) > 180
-@end smallexample
-
-@item
-Rebuild your databases using the following command:
-
-@smallexample
-mailfromd --compact --all
-@end smallexample
-
-@noindent
-This is necessary since the format of @command{mailfromd} databases
-has changed in version 2.0: the key field now includes the trailing
-@samp{NUL} character, which is also reflected in its length. This
-allows for empty (zero-length) keys. @xref{Database Maintenance}, for
-more information about the database compaction.
-@end enumerate
-
-@node Tutorial, MFL, Building, Top
+@node Tutorial
@chapter Tutorial
This chapter contains a tutorial introduction, guiding you
through various @command{mailfromd} configurations, starting from the
simplest ones and proceeding up to more advanced forms. It omits
most complicated details, concentrating mainly on the
common practical tasks.
If you are familiar to @command{mailfromd}, you can skip this
-chapter and go directly to the next one, that contains detailed
-discussion of the configuration language and @command{mailfromd}
-interaction with the Mail Transport Agent.
+chapter and go directly to the next one (@pxref{Mail Filtering
+Language}), which contains detailed discussion of the mail filtering
+language and @command{mailfromd} interaction with the Mail Transport
+Agent.
@menu
* Start Up::
* Simplest Configurations::
* Conditional Execution::
* Functions and Modules::
@@ -2794,34 +2371,36 @@ the name in question or the list is exhausted. In the former case, the
account is local, in the latter it is not. This concept is
discussed in detail in @pxref{authentication, Authentication,
Authorization and Authentication Principles, mailutils, GNU Mailutils
Manual}). Here we will give only some practical advices for
implementing it in @command{mailfromd} filters.
- The actual list of authorization module available depends on your
+ The actual list of available authorization modules depends on your
@command{mailutils} installation. Usually it includes, apart from
traditional @acronym{UNIX} @file{passwd} database, the functions for verifying
@acronym{PAM}, @acronym{RADIUS} and @acronym{SQL} database accounts.
-Each of the authorization
-methods is configured using special command line options. Run
-@command{mailfromd --help} and you will get the listing of those under
-@samp{Authentication options} section. For the exact meaning of each
-particular option, refer to @ref{auth, auth, Authentication and
-Authorization Options, mailutils, GNU Mailutils Manual}. It is often
-inconvenient to specify all required options in the command line, so you are
-advised to use @dfn{mailutils system configuration file}.
-@xref{configuration, Mailutils Configuration File, Mailutils
-Configuration File, mailutils, GNU Mailutils Manual}, for its
-description. Its use boils down to placing in it all
-the necessary authorization options, prefixed by the label
-@code{:mailfromd}. For example, the following @file{mailutils.rc} statement:
+Each of the authorization methods is configured using special
+configuration file statements. For the description of the Mailutils
+configuration files, @xref{configuration, Mailutils Configuration
+File, Mailutils Configuration File, mailutils, GNU Mailutils Manual}.
+You can obtain the template for @command{mailfromd} configuration by
+running @command{mailfromd --config-help}.
+
+ For example, the following @file{mailutils.rc} file:
@smallexample
@group
-:mailfromd --authorization=pam:system \
- --pam-service=mailfromd
+program mailfromd @{
+ auth @{
+ authorization pam:system;
+ @}
+
+ pam @{
+ service mailfromd;
+ @}
+@}
@end group
@end smallexample
@noindent
sets up the authorization using @acronym{PAM} and system @file{passwd}
database. The name of @acronym{PAM} service to use is @samp{mailfromd}.
@@ -2859,13 +2438,13 @@ and is assigned several pieces of information for its maintenance: the
database @dfn{file name} and the @dfn{expiration period}, i.e. the
time after which a record is considered expired.
@xopindex{show-defaults, introduced}
To obtain the list of available databases along with their
preconfigured settings, run @kbd{mailfromd --show-defaults}. You will
-see a similar output:
+see an output similar to this:
@smallexample
@group
version: @value{VERSION}
script file: /etc/mailfromd.rc
user: mail
@@ -4164,13 +3743,13 @@ same name as a previously defined constant or vice versa. The
resolution of such name clashes is described in detail in
@xref{variable--constant shadowing}.
Future versions of the program will provide a non-ambiguous way of
referring to variables and constants from literal strings.
-@node MFL, Using MFL Mode, Tutorial, Top
+@node MFL
@chapter Mail Filtering Language
@cindex MFL
@cindex mail filtering language
The @dfn{mail filtering language}, or @acronym{MFL}, is a special
language designed for writing filter scripts. It has a simple syntax,
@@ -5351,34 +4930,46 @@ Expands to the package name (@samp{mailfromd})
@deftypevr {Built-in constant} number __patch__
For alpha versions and maintenance releases expands to the version
patch level. For stable versions, expands to @samp{0}.
@end deftypevr
-@deftypevr {Built-in constant} string __preproc__
- Expands to the external preprocessor command line, if the
-preprocessor is used, or to an empty string if it cannot, e.g.:
+@deftypevr {Built-in constant} string __defpreproc__
+ Expands to the default external preprocessor command line, if the
+preprocessor is used, or to an empty string if it is not, e.g.:
@smallexample
-__preproc__ @result{} "/usr/bin/m4 -s"
+__defpreproc__ @result{} "/usr/bin/m4 -s"
@end smallexample
@xref{Preprocessor}, for information on preprocessor and its
features.
@end deftypevr
+@deftypevr {Built-in constant} string __preproc__
+ Expands to the current external preprocessor command line, if the
+preprocessor is used, or to an empty string if it is not. Notice,
+that it equals @code{__defpreproc__}, unless the preprocessor was
+redefined using @option{--preprocessor} command line option
+(@pxref{Preprocessor, --preprocessor}).
+@end deftypevr
+
@deftypevr {Built-in constant} string __version__
Expands to the textual representation of the program version
(e.g. @samp{3.0.90})
@end deftypevr
-@deftypevr {Built-in constant} string __statedir__
+@deftypevr {Built-in constant} string __defstatedir__
Expands to the default state directory (@pxref{statedir}).
-@FIXME{Should have a way to determine the current value of statedir,
-as set by state-directory pragma, or, better yet, have a variable
-reflecting it (r/w).}
+@end deftypevr
+
+@deftypevr {Built-in constant} string __statedir__
+Expands to the current value of the program state directory
+(@pxref{statedir}). Notice, that it is the same as
+@code{__defstatedir__} unless the state directory was redefined at run
+time.
@end deftypevr
Built-in constants can be used as variables, this allows to expand them
within strings or here-documents. The following example illustrates
the common practice used for debugging configuration scripts:
@@ -6207,15 +5798,14 @@ that are implemented in the @command{mailfromd} binary, and
@dfn{user-defined} functions, that are written in @acronym{MFL}. The
invocation syntax is the same for both groups.
@command{Mailfromd} is shipped with a rich set of @dfn{library
functions}. In addition to these you can define your own functions.
- @FIXME{In subsequent sections we will discuss the library and built-in
-functions first, and then we will explain how to write your
-functions}.
+ In subsequent sections we will discuss the library and built-in
+functions, and then we will explain how to write new functions.
@menu
* Built-in:: Built-in and Library Functions
* User-defined:: Syntax for defining user functions
@end menu
@@ -6804,13 +6394,24 @@ do
fi
done
@end smallexample
@node Header modification functions
@subsubsection Header Modification Functions
-@UNREVISED{}
+@cindex header modification
+
+ There are two ways to modify message headers in a @acronym{MFL}
+script. First is to use header actions, described in @ref{Actions},
+and the second way is to use message modification functions. Compared
+with the actions, the functions offer a series of advantages. For
+example, using functions you can construct the name of the header to
+operate upon (e.g. by concatenating several arguments), something
+which is impossible when using actions. Moreover, apart from three
+basic operations (add, modify and remove), as supported by header
+actions, header functions allow to insert a new header into a
+particular place.
@deftypefn {Built-in Function} void header_add (string @var{name}, @
string @var{value} [, number @var{idx}])
Adds a header @samp{@var{name}: @var{value}} to the message. If
@var{idx} is given, it specifies a 0-based index in the header list
where to insert this header.
@@ -6829,13 +6430,13 @@ i.e. it inserts a header @samp{@var{name}: @samp{value}} at
@var{idx}th header position in the message.
@end deftypefn
@deftypefn {Built-in Function} void header_delete (string @var{name} @
[, number @var{index}])
Delete header @var{name} from the envelope. If @var{index} is given,
-delete @var{index}th instance of header @var{name}.
+delete @var{index}th instance of the header @var{name}.
Notice the differences between this function and the @code{delete}
action:
@enumerate 1
@item It allows to construct the header name, whereas @code{delete}
@@ -6981,13 +6582,13 @@ This function can be used in @code{eom} handlers only. It returns a
message descriptor referring to the current message. @xref{Message
functions}, for a description of functions for accessing messages.
@end deftypefn
@node Mailbox functions
@subsubsection Mailbox Functions
-@UNREVISED{}
+@cindex mailbox functions
A set of functions is provided for accessing mailboxes and messages
within them. In this subsection we describe the functions for
accessing mailboxes.
A mailbox is opened using @code{mailbox_open} function:
@@ -7045,24 +6646,44 @@ descriptior @var{nsmg} must be obtained from a previous call to
@code{mailbox_get_message} or @code{current_message}
(@pxref{current_message}).
@end deftypefn
@node Message functions
@subsubsection Message Functions
-@UNREVISED{}
-
+@cindex message functions
+ The functions described below retrieve information from RFC822
+messages. The message to operate upon is identified by its
+@dfn{descriptor}, an integer number returned by the previous call to
+@code{mailbox_get_message} (@pxref{Mailbox functions,
+mailbox_get_message}) or @code{current_message}
+(@pxref{current_message}) function.
+
@deftypefn {Built-in Function} number message_size (number @var{nmsg})
-Return the size of the message @var{nmsg}, in bytes.
+Return the size of the message @var{nmsg}, in bytes. @emph{Notice},
+that if @var{nmsg} refers to current message
+(@pxref{current_message}), the returned value is less than the size
+seen by the @acronym{MTA}, because @command{mailfromd} recodes
+@acronym{CR-LF} sequences to @acronym{LF}, i.e. removes carriage
+returns (@acronym{ASCII} 13) ocurring before line feeds