Version 17 (modified by dnauck, 16 years ago) (diff)
  1. Install the PHP scripts

Installing Maia Mailguard

English | Deutsch | other languages

Table of Contents

  • 1. Create a user and group for amavisd to run under, if necessary
  • 2. Download lastest stable version of Maia Mailguard
    • 2.1 Download from subversion repository
    • 2.2 Download as tarball
  • 3. Create a new database for amavis and Maia Mailguard
  • 4. Install the Maintenance Scripts and Templates
  • 5. Install needed Perl Modules and Software
  • 6. Configure SpamAssassin 3.x
  • 7. Load your SpamAssassin Rules
  • 8. Generate your encryption key (optional)
  • 9. Install the PHP scripts
  • 10. Configure the PHP scripts
  • 11. Install and configure amavisd-new

1. Create a user and group for amavisd to run under, if necessary

The amavisd-new process should be running under its own userid and group. If you haven't already created this user and group, do so now, making sure to set a password for this user:

[root]# groupadd amavis
[root]# useradd amavis -g amavis -d /var/amavisd
[root]# passwd amavis
[root]# mkdir /var/amavisd
[root]# chown amavis:amavis /var/amavisd

2. Download lastest stable version of Maia Mailguard

2.1 Download from subversion repository

Login as amavis and checkout the code:

[root]# su amavis
[amavis]# cd ~
[amavis]# mkdir svn
[amavis]# cd svn
[amavis]# svn checkout

You need a subversion client with SSL enable. Replace V1_0_0_RC5_2 with the lastest stable version.

2.2 Download as tarball

Goto and download the lastest stable source tarball.

[root]# su amavis
[amavis]# cd ~
[amavis]# mkdir download
[amavis]# cd download
[amavis]# wget
[amavis]# tar -xzf maia-1.0.0-rc5-2.tar.gz

3. Create a new database for amavis and Maia Mailguard

Maia Mailguard supports a number of SQL databases. This documentations prefer MySQL 4.x, but bear in mind that you should be able to get Maia Mailguard working with PostgreSQL as well.

First login to the databaseserver as root:

[amavis]# mysql -u root -p

To create a new database, type the following:

mysql> CREATE DATABASE maia;

The procedure for creating a database will vary from one database to another; consult your database documentation to find the right way to do this for your database.

To create and fill the database tables, use the definitions in the maia-mysql.sql file:

mysql> use maia;
mysql> source /var/amavisd/download/maia/maia-mysql.sql;

The SQL syntax in this file is designed for MySQL 4.x, and may need to be modified slightly to accommodate other databases (e.g. your database may have different keywords for unsigned or auto_increment). The maia-pgsql.sql file contains the table definitions for use with PostgreSQL, for example.

Now you need to give the amavis user limited access to this database (in place of passwd be sure to use the password you set for the amavis user):


Again, how you grant privileges to a database user will vary from package to package. Consult your database documentation for more specific details.

To exit the mysql client simply type:

mysql> quit;

If you're using MySQL, you'll also need to add (or increase) the max_allowed_packet setting in your my.cnf file. This setting determines the size of the largest mail item you'll be able to process with Maia, so make sure to set this value large enough to accommodate your needs. (You'll be able to tell Maia Mailguard later on what to do with mail larger than this.) Note that in MySQL version prior to 4.0.1, the maximum packet size is 16MByte. Later versions can accept packets as large as 1GByte.

Example for /etc/mysql/my.cnf

#MySQL versions prior to 4.0.2:
set-variable = max_allowed_packet = 10M

#MySQL 4.0.2 or later:
max_allowed_packet = 10M

4. Install the Maintenance Scripts and Templates

Maia Mailguard comes with a collection of Perl scripts in the /scripts subdirectory. Install these files in a place that your web server can't access (i.e. outside of your DocumentRoot?), so that they can't be triggered by web visitors. A good place for these is in a subdirectory of your amavisd-new homedirectory, e.g. /var/amavisd/maia. Create two subdirectories there, one for scripts, the other for templates:

[root]# mkdir /var/amavisd/maia

[root]# mkdir /var/amavisd/maia/scripts
[root]# mkdir /var/amavisd/maia/templates

Now copy the contents of Maia Mailguard's /scripts subdirectory into /var/amavisd/maia/scripts, and put the contents of the /templates subdirectory into /var/amavisd/maia/templates.

[root]# cp /var/amavisd/download/maia/templates/*.tpl /var/amavisd/maia/templates/
[root]# cp /var/amavisd/download/maia/scripts/*.pl /var/amavisd/maia/scripts/
[root]# cp /var/amavisd/download/maia/scripts/database.cfg.dist /var/amavisd/maia/scripts/database.cfg

Set the ownership of all of these files to the amavis user and group, and tighten up the permissions on these files so that they're accessible only to the amavis user:

[root]# chown -R amavis:amavis /var/amavisd/maia
[root]# chmod 640 /var/amavisd/maia/templates/*.tpl
[root]# chmod 750 /var/amavisd/maia/scripts/*.pl
[root]# chmod 640 /var/amavisd/maia/scripts/database.cfg

Before any of the supplied scripts can be used, you need to edit the database.cfg file in the scripts subdirectory that you just installed. This is a simple file with just three items to configure. The username, password, and connection string that Perl needs in order to access the Maia Mailguard database. For example:

# Database configuration for Maia Mailguard perl scripts

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

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

# Your database user's password
password = "passwd"

Finally, you'll want to edit the Perl scripts themselves to make sure they know where to find the database.cfg file, since they rely on it to be able to connect to the Maia Mailguard database. You'll find the configurable portion of the scripts near the top of each file. For example:

# CONFIGURE THIS: Location of your database.cfg file
my $cfg = "/var/amavisd/maia/scripts/database.cfg";

5. Install needed Perl Modules and Software

First you have to check for needed perl modules. Use for this

[root]# /var/amavisd/maia/scripts/


file(1)              :     3.37 : UPGRADE RECOMMENDED (
Archive::Tar         :     1.10 : OK
Archive::Zip         :     1.12 : OK
Compress::Zlib       :     1.33 : OK
Convert::TNEF        :     0.17 : OK
Convert::UUlib       :     1.03 : OK
MIME::Base64         :     3.01 : OK
MIME::Parser         :    5.406 : UPGRADE RECOMMENDED
Mail::Internet       :     1.64 : OK
Net::Server          :     0.87 : OK
Net::SMTP            :     2.29 : OK
Digest::MD5          :     2.33 : OK
IO::Stringy          :    2.109 : OK
Time::HiRes          :      1.6 : OK
Unix::Syslog         :     0.99 : OK
DBI                  :     1.43 : OK
DBD::mysql           :   2.9004 : OK
DBD::Pg              :      N/A : NOT INSTALLED (required if you want to use PostgreSQL)


Mail::SpamAssassin   :     2.64 : OK
File::Spec           :     0.88 : OK
Pod::Usage           :     1.14 : OK
HTML::Parser         :     3.36 : OK
DB_File              :     1.75 : OK
Net::DNS             :     0.48 : OK
Digest::SHA1         :     2.10 : OK

Maia Mailguard:

Crypt::Blowfish      :     2.09 : OK
Crypt::CBC           :     2.12 : OK

Database DSN test    : PASSED

Install the needed perl modules with CPAN, for example:

[root]# perl -MCPAN -e shell
cpan> install Mail::SpamAssassin
cpan> quit

Optional software to enhance spamdetection:

Free Virus Scanners:

6. Configure SpamAssassin 3.x

Download the table definitions for the SQL based bayesian storage:

[root]# su amavis
[amavis]# cd ~/download
[amavis]# wget
[amavis]# wget
[amavis]# mysql -u amavis -p
mysql> use maia;
mysql> source /var/amavisd/download/awl_mysql.sql;
mysql> source /var/amavisd/download/bayes_mysql.sql;
mysql> quit;

Note: If you are using MySQL 4.x, I would advise you to change the tables from type MyISAM to InnoDB to improve the locking speed.

Edit /etc/mail/spamassassin/ with your favorit texteditor, e.g. vim, to setup the SQL based bayesian storage:
(in place of passwd be sure to use the password you set for the amavis user)

# How many hits before a message is considered spam.
required_hits           5.0

# Whether to change the subject of suspected spam
rewrite_subject         0

# Text to prepend to subject if rewrite_subject is used
subject_tag             *****SPAM*****

# Encapsulate spam in an attachment
report_safe             1

# Use terse version of the spam report
use_terse_report        0

# Enable the Bayes system
use_bayes               1

# Bayes SQL storage config
bayes_store_module                Mail::SpamAssassin::BayesStore::SQL
bayes_sql_dsn                     DBI:mysql:maia
bayes_sql_username                amavis
bayes_sql_password                passwd
auto_whitelist_factory            Mail::SpamAssassin::SQLBasedAddrList
user_awl_dsn                      DBI:mysql:maia
user_awl_sql_username             amavis
user_awl_sql_password             passwd

# Enable Bayes auto-learning
auto_learn              1

# Enable or disable network checks
skip_rbl_checks         0
use_razor2              1
use_dcc                 1
use_pyzor               1

# Mail using languages used in these country codes will not be marked
# as being possibly spam in a foreign language.
# - english german 
ok_languages            en de 

# Mail using locales used in these country codes will not be marked
# as being possibly spam in a foreign language.
ok_locales              en de

7. Load your SpamAssassin Rules

Maia Mailguard needs to index all of the SpamAssassin rules you have installed on your system, so that these rules, their descriptions and scores can be loaded into a database table. To do this, use one of the scripts in the scripts subdirectory called

Before you run this script, edit it to make sure that the SpamAssassin rule directories are set properly, e.g.:

# CONFIGURE THIS: SpamAssassin directories to search for rules files (*.cf and user_prefs)
my $local_cf_dir = "/etc/mail/spamassassin";
my $system_rules_dir = "/usr/local/share/spamassassin";
my $user_rules_dir = "/var/amavisd/.spamassassin";

$local_cf_dir should be set to the directory that contains your site's file.
$system_rules_dir should be set to the directory that contains SpamAssassin's own *.cf files.
$user_rules_dir should be set to the amavis user's SpamAssassin directory, where its (optional) user_prefs file may be found.

Run it without arguments, e.g.

[root]# /var/amavisd/maia/scripts/

If all goes well, this script will scan the three specified subdirectories for *.cf and user_prefs files, reading any rule names, descriptions and scores it finds and storing them in the Maia Mailguard database

You can safely run this script anytime you add new SpamAssassin rules or update your SpamAssassin rule files with new scores. The script will not add the same rule twice, but it will update the score value of a rule that it has seen before. If you use a scheduled job to fetch updated versions of popular SpamAssassin rule sets, for example, add this script to the end of your update job to make sure the changes are picked up by Maia Mailguard.

8. Generate your 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 script can do this for you, just redirect its output to a file:

[root]# su amavis
[amavis]# /var/amavisd/maia/scripts/ > /var/amavisd/blowfish.key

Put the key file in your amavisd homedirectory, 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.

Note: 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, see 9. and 10.).

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.

9. Install the PHP scripts

Decide where you want to install the PHP scripts. This should be a subdirectory somewhere within your web tree or a new webuser. For this example we'll assume a directory called mail, just off the document root of the web server (i.e. the relative path to the folder would then be /mail, accessible to the outside world as Copy the contents of the /php subdirectory of the Maia Mailguard distribution to this folder.

Note: Your webserver needs writeaccess on the maia_html/themes/*/compiled subdirectorys. (a secure way is to use suPHP instead of mod_php)

Please consult your webserver documentation.

Example for the Apache Webserver on Debian:

[root]# adduser --shell /bin/false web001
[root]# mkdir /home/web001/maia_html
[root]# cp -r /var/amavisd/download/maia/php/* /home/web001/maia_html/
[root]# chown -R web001:www-data /home/web001
[root]# chmod 770 /home/web001/
[root]# chmod 770 /home/web001/maia_html/
[root]# chmod 770 /home/web001/maia_html/themes/*/compiled/

This add a new webuser to the system, set write permission to the Apache systemuser www-data on maia_html/themes/*/compiled subdirectorys.

Now you've to edit your httpd.conf, e.g.:

<VirtualHost *>
DocumentRoot /home/web001/maia_html
ErrorLog /home/web001/logs/error.log
CustomLog /home/web001/logs/access.log "combined"

10. Configure the PHP scripts

11. Install and configure amavisd-new