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 @@ | |||
1 | @c Copyright (C) 2005, 2006, 2009 Sergey Poznyakoff | ||
2 | @c Permission is granted to copy, distribute and/or modify this document | ||
3 | @c under the terms of the GNU Free Documentation License, Version 1.2 or | ||
4 | @c any later version published by the Free Software Foundation; with no | ||
5 | @c Invariant Sections, with the Front-Cover texts being ``Mailfromd Manual'', | ||
6 | @c and with the Back-Cover Texts at your option. | ||
7 | |||
8 | |||
9 | The following sections describe procedures for upgrading | ||
10 | between the consequtive Mailfromd releases. | ||
11 | |||
12 | @menu | ||
13 | * 500-510:: Upgrading from 5.0 to 5.1 | ||
14 | * 440-500:: Upgrading from 4.4 to 5.0 | ||
15 | * 43x-440:: Upgrading from 4.3.x to 4.4 | ||
16 | * 420-43x:: Upgrading from 4.2 to 4.3.x | ||
17 | * 410-420:: Upgrading from 4.1 to 4.2 | ||
18 | * 400-410:: Upgrading from 4.0 to 4.1 | ||
19 | * 31x-400:: Upgrading from 3.1.x to 4.0 | ||
20 | * 30x-31x:: Upgrading from 3.0.x to 3.1 | ||
21 | * 2x-30x:: Upgrading from 2.x to 3.0.x | ||
22 | * 1x-2x:: Upgrading from 1.x to 2.x | ||
23 | @end menu | ||
24 | |||
25 | @node 500-510 | ||
26 | @appendixsec Upgrading from 5.0 to 5.1 | ||
27 | @cindex Upgrading from 5.0 to 5.1 | ||
28 | |||
29 | Upgrading from 5.0 to 5.1 does not require any changes in your | ||
30 | filter scripts. Notice, however, the following important points: | ||
31 | |||
32 | @itemize @bullet | ||
33 | @item The semantics of @code{__preproc__} and @code{__statedir__} | ||
34 | built-in constant is slightly different from what it used to be in | ||
35 | 5.0. These constants now refer to the @emph{current} values of the | ||
36 | preprocessor command line and program state directory, | ||
37 | correspondingly. This should not affect your script, unless you | ||
38 | redefine the default values on run time. If your script needs to | ||
39 | access default values, use @code{__defpreproc__} and | ||
40 | @code{__defstatedir__}, correspondingly (@pxref{Built-in constants}). | ||
41 | The following example explains the difference between these: | ||
42 | |||
43 | @smallexample | ||
44 | $ cat pval.mf | ||
45 | prog envfrom | ||
46 | do | ||
47 | echo "Default value: " __defstatedir__ | ||
48 | echo "Current value: " __statedir__ | ||
49 | done | ||
50 | $ mailfromd --state-directory=/var/mfd --test pval.mf | ||
51 | Default value: /usr/local/var/mailfromd | ||
52 | Current value: /var/mfd | ||
53 | @end smallexample | ||
54 | |||
55 | @item If your filter uses the @code{rate} function, | ||
56 | you might consider using the new function @code{rateok} or | ||
57 | @code{tbf_rate} instead. For a detailed discussion of these functions, | ||
58 | see @ref{Sending Rate}. | ||
59 | |||
60 | @item If your script extensively uses database access functions, you | ||
61 | might be interested in the new @code{#pragma dbprop} (@pxref{dbprop}). | ||
62 | @end itemize | ||
63 | |||
64 | @node 440-500 | ||
65 | @appendixsec Upgrading from 4.4 to 5.0 | ||
66 | @cindex Upgrading from 4.4 to 5.0 | ||
67 | |||
68 | This version of Mailfromd requires | ||
69 | @uref{http://www.gnu.org/software/mailutils, GNU mailutils} version | ||
70 | 2.0 or later. | ||
71 | |||
72 | Upgrading from version 4.4 to 5.0 requires no additional | ||
73 | changes. The major differences between these two versions are | ||
74 | summarized below: | ||
75 | |||
76 | @enumerate 1 | ||
77 | @item Support for @samp{MeTA1}. | ||
78 | |||
79 | @item New @samp{Mailutils} configuration file. | ||
80 | |||
81 | @item New @acronym{MFL} functions. | ||
82 | |||
83 | @enumerate a | ||
84 | @item Message functions. @xref{Message functions}. | ||
85 | @item Mailbox functions. @xref{Mailbox functions}. | ||
86 | @item Mail body functions. @xref{Mail body functions}. | ||
87 | @item Header modification functions. @xref{Header modification functions}. | ||
88 | @item Envelope modification functions. @xref{Envelope modification functions}. | ||
89 | @item Quarantine functions. @xref{Quarantine functions}. | ||
90 | @item @code{getopt} and @code{varptr}. @xref{getopt}. | ||
91 | @item Macro access functions. @xref{Macro access}. | ||
92 | @item Character type functions. @xref{Character Type}. | ||
93 | @item New string functions (@pxref{String manipulation}): | ||
94 | @code{verp_extract_user}, @code{sa_format_report_header}, | ||
95 | @code{sa_format_score}. | ||
96 | @item Sequential access to DBM files. @xref{dbm-seq}. | ||
97 | @end enumerate | ||
98 | |||
99 | @item Changes in @acronym{MFL} | ||
100 | |||
101 | @enumerate 1 | ||
102 | @item @xref{variadic functions}. | ||
103 | @item @xref{function alias}. | ||
104 | @end enumerate | ||
105 | |||
106 | @item New operation mode: @xref{Run Mode}. | ||
107 | |||
108 | @item Improved stack growth technique. | ||
109 | |||
110 | The stack can be grown either by fixed size blocks, or | ||
111 | exponentially. Upper limit can be specified. @xref{stacksize}. | ||
112 | |||
113 | @item Milter ports can be specified using @acronym{URL} notation. | ||
114 | |||
115 | @item Removed deprecated features. | ||
116 | |||
117 | Support for some deprecated features has been withdrawn. These are: | ||
118 | |||
119 | @enumerate a | ||
120 | @item Command line options @option{--ehlo}, | ||
121 | @option{--postmaster-email}, and @option{--mailfrom}. | ||
122 | These became deprecated in version 4.0. @xref{31x-400}. | ||
123 | @end enumerate | ||
124 | |||
125 | @end enumerate | ||
126 | |||
127 | @node 43x-440 | ||
128 | @appendixsec Upgrading from 4.3.x to 4.4 | ||
129 | @cindex Upgrading from 4.3.x to 4.4 | ||
130 | |||
131 | The deprecated @option{--domain} command line option has been | ||
132 | withdrawn. The short option @option{-D} now defines a preprocessor | ||
133 | symbol (@pxref{Preprocessor Options}). | ||
134 | |||
135 | This version correctly handles name clashes between constants and | ||
136 | variables, which remained unnoticed in previous releases. | ||
137 | @xref{variable--constant shadowing}, for a detailed description of it. | ||
138 | |||
139 | To minimize chances of name clashes, all symbolic exception codes has | ||
140 | been renamed by prefixing them with the @samp{e_}, thus, e.g. @code{divzero} | ||
141 | became @code{e_divzero}, etc. The @code{ioerr} exception code is renamed to | ||
142 | @code{e_io}. @xref{status.mfh}, for a full list of the new exception codes. | ||
143 | |||
144 | @cindex @code{OLD_EXCEPTION_CODES}, preprocessor symbol | ||
145 | For consistency, the following most often used codes are available without | ||
146 | the @samp{e_} prefix: success, not_found, failure, temp_failure. This | ||
147 | makes most existing user scripts suitable for use with version 4.4 | ||
148 | without any modification. If your script refers to any exception | ||
149 | codes other than these four, you can still use it by defining a | ||
150 | preprocessor symbol @code{OLD_EXCEPTION_CODES}, for example: | ||
151 | |||
152 | @smallexample | ||
153 | $ mailfromd -DOLD_EXCEPTION_CODES | ||
154 | @end smallexample | ||
155 | |||
156 | @node 420-43x | ||
157 | @appendixsec Upgrading from 4.2 to 4.3.x | ||
158 | @cindex Upgrading from 4.2 to 4.3.x | ||
159 | @cindex @code{DEFAULT_SYSLOG_ASYNC}, @command{configure} variable | ||
160 | |||
161 | Upgrading from 4.2 to 4.3 or 4.3.1 does not require any changes to | ||
162 | your configuration and scripts. The only notable change in these | ||
163 | versions is the following: | ||
164 | |||
165 | The asynchronous syslog implementation was reported to malfunction | ||
166 | on some systems (notably on Solaris), so this release does not enable | ||
167 | it by default. The previous meaning of the @option{--enable-syslog-async} | ||
168 | configuration option is also restored. Use this option in order to | ||
169 | enable asynchronous syslog feature. To set default syslog | ||
170 | implementation, use @code{DEFAULT_SYSLOG_ASYNC} configuration variable | ||
171 | (@pxref{syslog-async}). | ||
172 | |||
173 | The following deprecated features are removed: | ||
174 | |||
175 | @enumerate | ||
176 | @item @code{#pragma option ehlo} statement. | ||
177 | |||
178 | It became deprecated in version 4.0. @xref{pragma-option-ehlo}. | ||
179 | |||
180 | @item @code{#pragma option mailfrom} statement. | ||
181 | |||
182 | It became deprecated in version 4.0. @xref{pragma-option-ehlo}. | ||
183 | |||
184 | @item The @option{--config-file} command line option. | ||
185 | |||
186 | It became deprecated in version 3.1. @xref{30x-31x}. | ||
187 | |||
188 | @item Built-in exception codes in catch statements. | ||
189 | |||
190 | They are deprecated since version 4.0. @xref{31x-400}. | ||
191 | @end enumerate | ||
192 | |||
193 | @node 410-420 | ||
194 | @appendixsec Upgrading from 4.1 to 4.2 | ||
195 | @cindex Upgrading from 4.1 to 4.2 | ||
196 | Upgrading to this version does not require any special efforts. You | ||
197 | can use your configuration files and filter scripts without any | ||
198 | changes. The only difference worth noticing is that starting from this | ||
199 | version @command{mailfromd} is always compiled with asynchronous | ||
200 | syslog implementation. The @option{--enable-syslog-async} | ||
201 | configuration file option is still available, but its meaning has | ||
202 | changed: it sets the @emph{default} syslog implementation to use | ||
203 | (@pxref{syslog-async}). Thus, it can be used the same way it was in | ||
204 | previous versions. You can also select the syslog implementation at | ||
205 | run time, see @ref{Logging and Debugging, --syslog-async option}, for | ||
206 | more detailed information. | ||
207 | |||
208 | @node 400-410 | ||
209 | @appendixsec Upgrading from 4.0 to 4.1 | ||
210 | @cindex Upgrading from 4.0 to 4.1 | ||
211 | |||
212 | Upgrading to this version does not require any special efforts. You | ||
213 | can use your configuration files and filter scripts without any changes. | ||
214 | Notice only the following major differences between 4.1 and 4.0: | ||
215 | |||
216 | @itemize @bullet | ||
217 | @item Input files are preprocessed before compilation. | ||
218 | @xref{Preprocessor}, for more information. | ||
219 | |||
220 | @item There is a way to discern between a not-supplied optional | ||
221 | parameter, and a supplied one, having null value (@pxref{defined}). | ||
222 | |||
223 | @item The version 4.1 implements @code{sprintf} function | ||
224 | (@pxref{String formatting}) and @code{printf} macro | ||
225 | (@pxref{Preprocessor, printf}). | ||
226 | |||
227 | @item Support for some obsolete features is withdrawn. These include: | ||
228 | |||
229 | @enumerate 1 | ||
230 | @item | ||