diff options
Diffstat (limited to 'doc/upgrade.texi')
-rw-r--r-- | doc/upgrade.texi | 474 |
1 files changed, 474 insertions, 0 deletions
diff --git a/doc/upgrade.texi b/doc/upgrade.texi new file mode 100644 index 00000000..43663499 --- /dev/null +++ b/doc/upgrade.texi @@ -0,0 +1,474 @@ +@c Copyright (C) 2005, 2006, 2009 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. + + +The following sections describe procedures for upgrading +between the consequtive Mailfromd releases. + +@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 +@appendixsec Upgrading from 5.0 to 5.1 +@cindex Upgrading from 5.0 to 5.1 + + Upgrading from 5.0 to 5.1 does not require any changes in your +filter scripts. Notice, however, the following important points: + +@itemize @bullet +@item The semantics of @code{__preproc__} and @code{__statedir__} +built-in constant is slightly different from what it used to be in +5.0. These constants now refer to the @emph{current} values of the +preprocessor command line and program state directory, +correspondingly. This should not affect your script, unless you +redefine the default values on run time. If your script needs to +access default values, use @code{__defpreproc__} and +@code{__defstatedir__}, correspondingly (@pxref{Built-in constants}). +The following example explains the difference between these: + +@smallexample +$ cat pval.mf +prog envfrom +do + echo "Default value: " __defstatedir__ + echo "Current value: " __statedir__ +done +$ mailfromd --state-directory=/var/mfd --test pval.mf +Default value: /usr/local/var/mailfromd +Current value: /var/mfd +@end smallexample + +@item If your filter uses the @code{rate} function, +you might consider using the new function @code{rateok} or +@code{tbf_rate} instead. For a detailed discussion of these functions, +see @ref{Sending Rate}. + +@item If your script extensively uses database access functions, you +might be interested in the new @code{#pragma dbprop} (@pxref{dbprop}). +@end itemize + +@node 440-500 +@appendixsec 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 +@appendixsec 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_} prefix: 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 +@appendixsec 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}. + +@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 + +@node 410-420 +@appendixsec 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 +@appendixsec 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 +@appendixsec 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 +@appendixsec 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 +@appendixsec 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 +@appendixsec 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 + |