Version 2 (modified by rjl, 9 years ago)

--

Upgrading from 1.0.x

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 the new amavisd-maia

Install the amavisd-maia file in place of your existing amavisd file, or wherever you'd typically install system binaries (e.g. /usr/sbin, /usr/local/sbin, etc.):

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

You may also wish to create a symbolic link to this file, so that any existing scripts looking for 'amavisd' can find it properly:

[root]# ln -sf /usr/local/sbin/amavisd-maia /usr/local/sbin/amavisd

3. Install and configure the maintenance scripts

The various Perl scripts need to be installed, of course, replacing your old versions. Be sure to read the documentation for the new maintenance scripts, as the command-line syntax has changed for some of these since 1.0.0. The old $database.cfg file is no longer needed, and there's no longer any need to configure settings at the tops of each of the scripts--this is now done via the /etc/maia.conf file.

Before any of the supplied scripts can be used, you need to copy the maia.conf.dist file to /etc/maia.conf and edit it to provide some basic information about how to connect to your database, and how the scripts themselves should behave. By storing this information in the /etc/maia.conf file, you won't need to supply that information as command-line arguments when you run the scripts themselves.

[root]# cp maia.conf.dist /etc/maia.conf
[root]# chown amavis /etc/maia.conf
[root]# chgrp amavis /etc/maia.conf
[root]# chmod 640 /etc/maia.conf

The most important settings in the /etc/maia.conf file are the ones that determine how the scripts should connect to your Maia database.

For MySQL:

# Configure your Maia database DSN here
$dsn = "DBI:mysql:maia:localhost:3306";

# Your Maia database user's login name
$username = "amavis";

# Your Maia database user's password
$password = "passwd";

For PostgreSQL:

# Configure your Maia database DSN here
$dsn = "DBI:Pg:dbname=maia;host=localhost;port=5432";

# Your Maia database user's login name
$username = "amavis";

# Your Maia database user's password
$password = "passwd";

You'll also want to tell Maia where you installed the maintenance scripts:

# The directory where Maia's Perl scripts can be found.
$script_dir = "/var/amavisd/maia/scripts";

That's all you need to configure for now; you can read the separate documentation for the maintenance scripts later, before you use them.

4. 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. Even if you're sure your system has what it needs, you should run the latest version of configtest.pl, since it has up-to-date information about versions of components known to be vulnerable to published exploits.

5. Install the new PHP scripts

The PHP scripts in the new distribution replace the ones from your 1.0.x installation, so you'll want to copy them to the same place your existing files are. You may wish to backup your existing files first, particularly if you've made any edits or customisations to them.

There should be several subdirectories beneath the directory with your PHP scripts. Your directory tree in this example should look something like this:

<document_root>/maia
<document_root>/maia/adminconfigtest and upgrade scripts
<document_root>/maia/imagesvarious global images
<document_root>/maia/libsinclude path for Smarty
<document_root>/maia/localelanguage packs go here
<document_root>/maia/overliba popup library used for toolkits
<document_root>/maia/themesHTML themes

Alternately, if you're packaging Maia Mailguard for redistribution, you may wish to install the PHP scripts in a standard location outside the web document tree, e.g. /usr/local/maia/php or somesuch. If you do so however, you'll also need to make that subdirectory visible to your web server and give it script execution permissions (e.g. a <Directory> entry in your httpd.conf file if you use apache).

The web server user needs to be able to write to the theme directories in order to cache the pages. The best way to ensure that you get the permissions right is to follow these instructions.

6. Backup your existing database

In the next step, changes will be made to the structure of your Maia database. As a precaution, make a backup of your existing database, so that you don't risk losing any existing data if something should go wrong.

7. Run the admin/upgrade.php script

The admin/upgrade.php script will make any necessary changes to your Maia database, adding any missing tables, columns, and indices.

8. Run the admin/configtest.php script

On your web server, load the new admin/configtest.php 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.

9. Start the new amavisd-maia

Start amavisd-maia 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.

10. Delete the admin subdirectory

Once everything is working properly, you'll want to delete the admin subdirectory and its contents from your web server, so that they can no longer be accessed from the web. Those administrative scripts are no longer required at this point, and present a potential security risk if left in place.


Back to FAQ