Upgrading from 1.0.0 RC5

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 and templates need to be installed, of course, replacing your old versions. Be sure to customise the templates to your liking, and read the documentation for the new maintenance scripts, as the command-line syntax has changed for some of these since RC5. 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 script

On the machine(s) where you have amavisd and SpamAssassin installed, run the new 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, 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 RC5 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/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. Install the Smarty Template Engine

Download and install the Smarty template engine. You can install it system-wide (so that other applications on the web server can make use of it as well), or simply for Maia's purposes:

For a system-wide installation:

cp -r {path_to_Smarty_files}/lib {php_include_path}/Smarty

For a Maia-only installation:

cp -r {path_to_Smarty_files}/lib {document_root}/maia/libs/Smarty

7. 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.

If you used POP3 or IMAP authentication before, you'll also need to adjust the $auth_pop3_host/$auth_pop3_port settings, or the $auth_imap_host/$auth_imap_port settings.

The new $protection setting lets you define the default policy settings for each of four protection levels: "off", "low", "medium", and "high". While users can manually tweak their filter settings if they wish, many users prefer to use administrator-recommended settings instead.

A policy array is a combination of 16 settings (from left to right):

Settingamavisd-new equivalentValue range
Pass viruses through?virus_lover'Y' or 'N'
Pass spam through?spam_lover'Y' or 'N'
Pass banned files through?banned_files_lover'Y' or 'N'
Pass mail with invalid headers through?bad_header_lover'Y' or 'N'
Disable virus scanning?bypass_virus_checks'Y' or 'N'
Disable spam checking?bypass_spam_checks'Y' or 'N'
Disable banned files checking?bypass_banned_checks'Y' or 'N'
Disable invalid header checking?bypass_header_checks'Y' or 'N'
Discard viruses?discard_viruses'Y' or 'N'
Discard spam?discard_spam'Y' or 'N'
Discard banned files?discard_banned_files'Y' or 'N'
Discard invalid mail headers?discard_bad_headers'Y' or 'N'
Add a prefix to spam subjects?spam_modifies_subj'Y' or 'N'
Add spam score headers when score is >spam_tag_level-999.9 to 999.9
Consider mail spam when score is >spam_tag2_level-999.9 to 999.9
Quarantine or discard spam when score is >spam_kill_level-999.9 to 999.9

The initial defaults for the four protection levels are as follows:

The 'off' level offers no protection at all. All scanning is disabled, so the filter is effectively transparent, letting everything through:

'off' => array ('Y','Y','Y','Y','Y','Y','Y','Y','N','N','N','N','N','999','999','999'),

At the 'low' protection setting, only virus scanning is performed:

'low' => array ('N','Y','Y','Y','N','Y','Y','Y','N','N','N','N','N','999','999','999'),

The 'medium' protection setting adds spam scoring headers to the mail when it scores 5.0 or higher, but does not quarantine or discard it. Banned file attachments and mail with invalid headers are passed through:

'medium' => array ('N','N','Y','Y','N','N','Y','Y','N','N','N','N','Y','5','999','999'),

The 'high' protection setting adds spam scoring headers to the mail when it scores 1.0 or higher, and quarantines spam that scores 5.0 or higher, along with viruses, banned file attachments, and mail with invalid headers:

'high' => array ('N','N','N','N','N','N','N','N','N','N','N','N','N','1','5','5')

These defaults, of course, are just suggestions. Feel free to interpret 'low', 'medium', and 'high' in whatever way makes sense for your organization, and adjust the settings to match.

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.

8. Install any additional language packs

Maia Mailguard ships with an English language pack pre-installed, but other languages and character sets are supported as well. These language packs no longer ship with the distribution, however they will be made available for download individually here as soon as they become available.

Note that translations are all based on the English language versions, and are contributed by members of the user community on a volunteer basis. As such, Renaissoft can make no guarantees regarding the accuracy or the completeness of a given non-English translation. We certainly appreciate the efforts of these volunteer translators, and credit for their work is incorporated into each of their language packs. If you would like to contribute a translation, please contact Robert LeBlanc for more details.

9. 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.

10. Run the admin/upgrade.php script

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

Postgresql Warning Postgresql < 8.0 cannot alter tables; a new table must be made, data copied, old table deleted, and the new table renamed. See ticket #269 for more information. At this point, we recommend not using postgresql < 8.0; This recommendation appears to agree with the postgresql community.

11. 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.

12. Configure amavisd-maia

Your existing /etc/amavisd.conf file may work fine with this new version of Maia Mailguard with just a few edits. On the other hand, if you wish to start from a clean template, the amavisd.conf.dist file that accompanies this new distribution is a good starting point.

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/maia.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.

13. 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.

14. 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

Last modified 16 years ago Last modified on Nov 21, 2006, 7:53:38 PM