Installing Maia Mailguard On Debian Squeeze (Virtual Users/Domains With Postfix/MySQL)

Version 1.0
Authors: Falko Timme, Dominik Najberg

This guide explains how to install Maia Mailguard, a spam and virus management system, on a Debian Squeeze mailserver. Maia Mailguard is a web-based interface and management system based on the popular amavisd-new email scanner and SpamAssassin. Written in Perl and PHP, Maia Mailguard gives end-users control over how their mail is processed by virus scanners and spam filters, while giving mail administrators the power to configure site-wide defaults and limits.

I do not issue any guarantee that this will work for you!

1 Preliminary Note

This tutorial is based on Virtual Users And Domains With Postfix, Courier, MySQL And SquirrelMail (Debian Squeeze), so you should have this set up already. If your mail setup is different, this tutorial might not work out for you, or you might have to make some adjustments.

My server has the hostname mail.example.com and the IP address 192.168.0.1. I will install Maia's web interface in Debian's default lighttpd document root, /var/www, and I will use www.example.com to access the web interface. You will have to adjust this if your document root and your domain differ.

2 Downloading Maia Mailguard

Maia Mailguard can be downloaded from SVN only, so we have to install Subversion first:

aptitude install subversion

I want to download the sources to /usr/src/maia:

mkdir /usr/src/maia
cd /usr/src/maia

Open a browser and go to https://www.maiamailguard.com/svn/branches/1.0 to find out what the latest revision is - in my case it was 1578. Then start the download as follows:

svn -r 1578 checkout https://www.maiamailguard.com/svn/branches/1.0

(Make sure you replace 1578 with the latest revision.)

3 Creating A Database For Maia Mailguard

Next log into MySQL...

mysql -u root -p

... and create a database called maia:

CREATE DATABASE maia;

Leave the MySQL shell afterwards:

quit;

Import Maia's SQL dump into the empty maia database:

cd /usr/src/maia/1.0/
mysql -u root -p maia < maia-mysql.sql

Then log into MySQL again...

mysql -u root -p maia

... and create a MySQL user called amavis:

GRANT CREATE, DROP, ALTER, SELECT, INSERT, UPDATE, DELETE ON maia.* TO amavis@localhost IDENTIFIED BY 'amavismysqlpasswd';

FLUSH PRIVILEGES;

Fix Unknown column 'discard_ham' problem that prevents emails from being sent anywhere:

ALTER TABLE users ADD COLUMN discard_ham char(1) NOT NULL default 'N'

Exit MySQL:

quit;

(You can replace amavismysqlpasswd with a password of your choice, but keep in mind that you have to use that password later on in the Maia configuration!)

Next make sure you have a big enough value for max_allowed_packet in your /etc/mysql/my.cnf (in the [mysqld] section). 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.

nano /etc/mysql/my.cnf

[...]
[mysqld]
[...]
max_allowed_packet      = 16M
[...]

Restart MySQL if you have changed the value of max_allowed_packet:

/etc/init.d/mysql restart

4 Installing Maia's Scripts And Templates

The home directory of the amavis user on Debian Squeeze is /var/lib/amavis, and that's where we create a subdirectory called maia. In that subdirectory we will place Maia's scripts and templates:

mkdir /var/lib/amavis/maia
mkdir /var/lib/amavis/maia/scripts
mkdir /var/lib/amavis/maia/templates

cp -pfr /usr/src/maia/1.0/scripts/* /var/lib/amavis/maia/scripts
cp -pfr /usr/src/maia/1.0/templates/* /var/lib/amavis/maia/templates

chown -R amavis /var/lib/amavis/maia
chgrp -R amavis /var/lib/amavis/maia
chmod 640 /var/lib/amavis/maia/templates/*.tpl
chmod 750 /var/lib/amavis/maia/scripts/*.pl

5 Configuring Maia

Next we rename /usr/src/maia/1.0/maia.conf.dist to /etc/maia/maia.conf:

mkdir /etc/maia/
cp /usr/src/maia/1.0/maia.conf.dist /etc/maia/maia.conf
chown amavis /etc/maia/maia.conf
chgrp amavis /etc/maia/maia.conf
chmod 640 /etc/maia/maia.conf

Open /etc/maia/maia.conf and adjust the following settings:

nano /etc/maia/maia.conf

[...]
# 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 = "amavismysqlpasswd";
# The directory where Maia's Perl scripts can be found.
$script_dir = "/var/lib/amavis/maia/scripts";
[...]
# Location to write the lock/PID files (must be writeable by your
# amavis user)
$pid_dir = "/var/lib/amavis/";
[...]
# Base URL to Maia's PHP scripts
$base_url = "http://www.example.com/";
# Template directory
$template_dir = "/var/lib/amavis/maia/templates/";
[...]

Make sure you fill in the correct password for the MySQL user amavis in the $password line. Also fill in the correct URL in the $base_url line.