(Note: A current version of this document can always be found (in more
readable HTML form) at http://www.renaissoft.com/maia/upgrade.php)

Upgrading from Maia Mailguard RC3 or RC4


1. Stop your amavisd process

You need to stop any amavisd processes that may be running, before
proceeding with the upgrade. This is because the upgrade process involves
making changes to the structure of the database tables, and these changes
will break the old version of amavisd-maia.


2. Install and configure the maintenance scripts

The various Perl scripts and templates need to be installed, of course,
replacing your old versions. Be sure to configure the handful of items at
the tops of these scripts, and customise the templates to your liking.


3. Run the configtest.pl script

On the machine(s) where you have amavisd and SpamAssassin installed, run
the new configtest.pl script, to make sure that you have all of the
required prerequisites installed, and that your versions are all up to
date. Make any necessary upgrades or installations, then run this script
again to verify that the problems have been fixed.


4. Configure Maia Mailguard

A few aspects of the config.php file have changed in this version, most
notably the addition of the $address_rewriting_type and $routing_domain
settings, which replace the older $auth_[pop3|imap]_address_type and
$auth_[pop3|imap]_routing_domain settings. These new settings work
essentially the same way the old ones did, but they're not specific to
the authentication type anymore. A new rewriting type (5) has been added.
For full details, see Virtual Hosts, Aliases, and E-mail Addresses
(http://www.renaissoft.com/maia/addresses.php).

The config.php.dist that ships with the new version can be used as a
guide, should you wish to see the new configuration options and suggested
defaults.


5. Run the configtest.php script

On your web server, load the new configtest.php script, to make sure that
you have all of the required prerequisites installed, and that your
versions are all up to date. This script will also make any necessary
changes to your Maia database, adding any missing tables or columns and
removing those that have become obsolete in this new version. Make any
necessary upgrades or installations, then run this script again to verify
that the problems have been fixed.


6. Generate your site's encryption key (optional)

Maia Mailguard can use strong encryption to protect the contents of the
e-mail that it quarantines/caches, as a safeguard against prying eyes
with database access. It uses the Blowfish algorithm with a 56-byte
(448-bit) key, and chained-block cipher (CBC) mode to do two-way
encryption of stored mail. This encryption is completely transparent to
the users, and does not require them to install any special software.
All encrypting and decrypting is done by Maia Mailguard.

To take advantage of this encryption feature, you first need to generate
a random key for your site. The generate-key.pl script can do this for
you, just redirect its output to a file:

[root]# generate-key.pl > /var/amavisd/blowfish.key

Put the key file in your amavisd directory, and be sure to keep another
copy of it in a safe place, preferably on another machine offsite, and/or
a backup disk/CD. If you suffer a disk crash and lose your key file,
you'll need this backup to be able to recover the encrypted contents of
your Maia database.

You'll also need to copy this key file to your web server, so that Maia
can use it to properly decrypt the stored mail.  You can put it anywhere
you like on the web server, as long as you tell Maia where it is (using the
System Configuration page).

You can safely enable encryption at any time, even after you've already
got mail in your database. Maia is smart enough to detect encrypted vs.
unencrypted mail, so if your database contains a mixture of both types,
it won't cause any problems.


7. Patch amavisd-new

As with all Maia upgrades, you have to apply the new amavisd-maia.patch
patch to a clean amavisd-new-20030616-p10.

Place the amavisd-maia.patch file in the same directory as your
freshly-unpacked 20030616-p10 distribution, cd to that directory and
type:

[root]# patch -b amavisd < amavisd-maia.patch

Now you can install the amavisd file wherever you'd typically install
system binaries (e.g. /usr/sbin, /usr/local/sbin, etc.):

[root]# cp amavisd /usr/local/sbin/
[root]# chown root /usr/local/sbin/amavisd
[root]# chmod 755 /usr/local/sbin/amavisd


8. Configure amavisd

Edit your /etc/amavisd.conf file to configure it for your installation
as usual, with the following particulars:

You'll probably want to turn up debugging output as much as possible to
make sure everything is working the way it should:

$log_level = 5;

If you want to include support for Blowfish encryption of quarantined/cached
e-mail, you'll have to add a new $key_file setting to amavisd.conf to tell
it where to find your key file:

# Blowfish encryption key file (optional)
$key_file = "$MYHOME/blowfish.key";

The @local_domains_acl, %local_domains, and $local_domains_re settings are
observed as usual, but these are not strictly necessary with Maia Mailguard,
since you can add domains to Maia using the administration interface, which
effectively causes such domains to be treated as "local" for amavisd's
purposes. You will want to do this for all of the domains you process mail
for, even if those domains are downstream from your server.


9. Start the new amavisd

Start amavisd and keep an eye on its log file as it processes a few test
e-mails, to make sure that all is well. If there are problems, setting the
$log_level to 3 or higher will display Maia's diagnostics.