diff options
-rw-r--r-- | NEWS | 17 | ||||
-rw-r--r-- | doc/Makefile.am | 1 | ||||
-rw-r--r-- | doc/fdl.texi | 1 | ||||
-rw-r--r-- | doc/gacopyz.texi | 1 | ||||
-rw-r--r-- | doc/mailfromd.texi | 664 | ||||
-rw-r--r-- | doc/strftime.texi | 1 | ||||
-rw-r--r-- | doc/upgrade.texi | 474 | ||||
-rw-r--r-- | etc/mailfromd.rc | 25 | ||||
-rw-r--r-- | mfd/lex.l | 14 |
9 files changed, 666 insertions, 532 deletions
@@ -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 +(@acronym{ASCII} 10. To obtain actual message length as seen by the +@acronym{MTA}, add the number of lines in the message: + +@smallexample + set actual_length message_size(%nmsg) + message_lines(%nmsg) +@end smallexample + @end deftypefn @deftypefn {Built-in Function} number message_body_size (number @var{nmsg}) -Return the size, in bytes, of the body of message @var{nmsg}. +Return the size, in bytes, of the body of message @var{nmsg}. See the +note to the @code{message_size}, above. @end deftypefn |