aboutsummaryrefslogtreecommitdiff
path: root/doc/upgrade.texi
blob: bb00aabf7ed7a5c92eabf15cd2269bf9f1f4a445 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
@c Copyright (C) 2005-2006, 2009-2011, 2015-2016 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.3 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 consecutive Mailfromd releases. 

@menu
* 700-800::  Upgrading from 7.0 to 8.0
* 600-700::  Upgrading from 6.0 to 7.0
* 5x0-600::  Upgrading from 5.x to 6.0
* 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 700-800
@appendixsec Upgrading from 7.0 to 8.0
@cindex Upgrading from 7.0 to 8.0
@WRITEME

@node 600-700
@appendixsec Upgrading from 6.0 to 7.0
@cindex Upgrading from 6.0 to 7.0

  The release 7.0 removes the features which were declared as obsolete
in 6.0 and introduces important new features, both syntactical, at the
@acronym{MFL} level, and operational.

  Unless your filter used any deprecated features, it should work
correctly after upgrade to this version.  It will, however, issue
warning messages regarding the deprecated features (e.g. the use
of @samp{%} in front of identifiers, as described below).  To
fix these, follow the upgrade procedure described in @ref{upgrade
procedure}.

  The removed features are:

@itemize @bullet
@item Old-style functional notation
@item The use of functional operators
@item Implicit concatenations
@item #pragma option
@item #pragma database
@end itemize

  The @acronym{MFL} syntax has changed: it is no longer necessary to
use @samp{%} in front of a variable to get its value.  To reference a
variable, simply use its name, e.g.: 

@smallexample
set x var + z
@end smallexample

  The old syntax is still supported, so the following statement
will also work:

@smallexample
set x %var + %z
@end smallexample

  It will, however, generate a warning message.   

  Of course, the use of @samp{%} to reference variables within a string
literal remains mandatory.

  Another important changes to @acronym{MFL} are user-defined
exceptions (@pxref{User-defined Exceptions}) and the @dfn{try--catch}
construct (@pxref{Catch and Throw,try--catch}).

  Several existing @acronym{MFL} functions have been improved.  In
particular, it is worth noticing that the @code{open} function, when
opening a pipe to or from a command, provides a way to control where
the command's standard error would go (@pxref{open, standard error}).

  The @code{accept} function (or action) issues a warning if its use would
cancel any modifications to the message applied by, e.g.,
@code{header_add} and similar functions.  @xref{Message modification
queue}, for a detailed discussion of this feature.

  The most important change in @command{mailfromd} operation is that
the version 7.0 is able to run several servers (@pxref{conf-server}).
Dedicated @dfn{callout servers} make it possible to run sender
verifications in background, using a set of long timeouts, as
prescribed by RFC 2822 (@pxref{SMTP Timeouts}).  This diminishes
the number of false positives, allows for coping with servers showing
large delays and also reduces the number of callouts performed for
such servers.

  This release no longer includes the @command{smap} utility.  It was
moved into a self-standing project, which by now provides much more
functionality and is way more flexible than this utility was.  If you
are interested in using @command{smap}, visit
@uref{http://www.gnu.org.ua/software/smap}, for a detailed
information, including pointers to file downloads.

@node 5x0-600
@appendixsec Upgrading from 5.x to 6.0
@cindex Upgrading from 5.x to 6.0

  The 6.0 release is aimed to fix several logical inconsistencies that
affected the previous versions.  The most important one is that until
version 5.2, the filter script file contained both the actual filter
script, and the run-time configuration for @command{mailfromd} (in
form of @samp{#pragma option} and @samp{#pragma database} statements).
The new version separates run-time configuration from the
filter script by introducing a special configuration file
@file{mailfromd.conf} (@pxref{Mailfromd Configuration}).

  Consequently, the @samp{#pragma option} and @samp{#pragma database}
statements become deprecated.  Furthermore, the following deprecated
pragmas are removed: @samp{#pragma option ehlo}, @samp{#pragma option mailfrom}.
These pragmas became deprecated in version 4.0 (@pxref{31x-400}).

  The second problem was that the default filter script file had
@samp{.rc} suffix, which usually marks a configuration file, not
the source.  In version 6.0 the script file is renamed to
@file{mailfromd.mf}.  In the absence of this file, the legacy file
@file{mailfromd.rc} is recognized and parsed.  This ensures backward
compatibility.

  This release also fixes various inconsistencies and dubious features
in the @acronym{MFL} language.    
 
  The support for unquoted literals is discontinued.  This feature
was marked as deprecated in version 3.0.

@anchor{deprecated-6.0}
  The following features are deprecated: @samp{#pragma option}
(@histref{6,pragma_002doption,pragma-option} and @samp{#pragma database}
(@histref{6,pragma_002ddatabase,pragma-database}) directives, the
legacy style of function declarations
(@histref{6,old_002dstyle-function-declarations, 
old-style function declarations}), calls to
functions of one argument without parentheses
(@histref{6,implicit-concatenation, operational
notation}), the @samp{#require} statement (@xref{import}, for the
new syntax) and implicit concatenation
(@histref{6,implicit-concatenation, implicit concatenation}).  See @histref{6,Deprecated-Features,Deprecated Features}, for more information
about these.

  This release also introduces important new features, which are
summarized in the table below:

@multitable @columnfractions .50 .50
@headitem Feature            @tab Reference
@item Configuration          @tab @xref{Mailfromd Configuration}.
@item Module system          @tab @xref{Modules}.
@item Explicit type casts    @tab @xref{explicit type casts}.
@item Concatenation operator @tab @xref{Concatenation}.
@item Scope of visibility    @tab @xref{scope of visibility}.
@item Precious variables     @tab @xref{rset}.
@end multitable

  @command{Mailfromd} version @samp{6.0} will work with unchanged
scripts from @samp{5.x}.  When started, it will verbosely warn you
about any deprecated constructs that are used in your filter sources
and will create a script for upgrading them.

@anchor{upgrade procedure}
  To upgrade your filter scripts, follow the steps below:

@enumerate 1
@item
Run @samp{mailfromd --lint}.  You will see a list of warnings similar
to this:

@smallexample
mailfromd: Warning: using legacy script file
 /usr/local/etc/mailfromd.rc
mailfromd: Warning: rename it to /usr/local/etc/mailfromd.mf
 or use script-file statement in /usr/local/etc/mailfromd.conf
 to disable this warning
mailfromd: /usr/local/etc/mailfromd.rc:19: warning: this pragma is
 deprecated: use relayed-domain-file configuration statement instead
mailfromd: /usr/local/etc/mailfromd.rc:23: warning: this pragma is
 deprecated: use io-timeout configuration statement instead
mailfromd: Info: run script /tmp/mailfromd-newconf.sh
 to fix the above warnings
@dots{} 
@end smallexample

@item
  At the end of the run @command{mailfromd} will create a shell script
@file{/tmp/mailfromd-newconf.sh} for fixing these warnings.  Run it:

@smallexample
$ sh /tmp/mailfromd-newconf.sh
@end smallexample


@item
  When the script finishes, run @command{mailfromd --lint} again.  If
it shows no more deprecation warnings, the conversion went correctly.
Now you can remove the upgrade script:

@smallexample
$ rm /tmp/mailfromd-newconf.sh
@end smallexample
@end enumerate

  Notice, that the conversion script attempts to fix only deprecation
warnings.  It will not try to correct any other type of warnings or
errors.  For example, you may get warning messages similar to:

@smallexample
mailfromd: /etc/mailfromd.mf:7: warning: including a module file is unreliable and may cause subtle errors
mailfromd: /etc/mailfromd.mf:7: warning: use `require dns' instead
@end smallexample

This means that you use @samp{#include} where you should have used
@samp{require}.  You will have to fix such warnings manually, as
suggested in the warning message.

  If, for some reason, you cannot upgrade your scripts right now, you
may suppress deprecation warnings by setting the environment variable
@env{MAILFROMD_DEPRECATION} to @samp{no} before starting
@command{mailfromd}.  Nonetheless, I recommend to upgrade as soon as
possible, because the deprecated features will be removed in version
@samp{6.1}.

@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 Starting from this release @command{mailfromd} supports Milter
protocol version 6, which is compatible with Sendmail 8.14.0 and
newer.  While being backward compatible with earlier Sendmail
releases, it allows you to use the new @samp{prog data} handler
(@pxref{Handlers, data}).  It also supports macro negotiation, a
feature that enables Mailfromd to ask @acronym{MTA} to export the
macros it needs for each particular handler.  This means that if you
are using Sendmail 8.14.0 or higher (or Postfix 2.5 or higher), you no
longer need to worry about exporting macro names in @file{sendmail.cf}
file.

The same feature is also implemented on the server side, in
@code{mtasim} and @code{pmult}.  Consequently, using
@code{define-macros} in @code{pmult} configuration file 
is not strictly necessary.  However, keep in mind that due to the
specifics of @acronym{MeTA1}, the number of symbols that may be
exported for each stage is limited (@pxref{pmult-macros}).

@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.mf}, 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.mf}).

  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

Return to:

Send suggestions and report system problems to the System administrator.