Installing Maia Mailguard on a Debian mail server

This is for Maia version 1.0.0 (and I consider it obsolete). For version 1.0.1, see:

Note: This document assumes you have installed version 20030616p10-5 of the Debian amavisd-new package. If you have not yet installed amavisd-new, please do not install a 'testing' (Etch) or 'unstable' (Sid) version (why?). You should have a 'stable' source listed in /etc/apt/sources.list and install from that using:
apt-get -t stable install amavisd-new
An example of a stable source would be:
deb stable main non-free contrib

You should be running Sarge or have 'stable' as your highest Pin-Priority or these instructions will most likely fail. See

This HOWTO is a quick and dirty guide to getting Maia Mailguard version 1.0.0 (or newer) installed on a Debian Sarge gateway email server that was originally built using or similar as a guide. This document is based on "Sarge Stable". This guide is designed to get someone past the initial brain damage of getting the right programs and files in the right place. You need to start with a fully functional amavisd-new installation per those (or similar) instructions. At the very least you need the Debian version of amavisd-new 20030616-p10 installed, configured, and functional (and preferably Postfix as your MTA). You cannot start this project using a copy of a version of amavisd.conf that comes with amavisd-new versions greater than 2.2.0. You can (and maybe should) use a copy of the amavisd.conf file supplied with the Debian version 20030616-p10 of amavisd-new. This file has settings specific to Debian. If you upgraded Debian amavisd-new to 2.2.1 per the instructions here, you should be able to use a copy of your 2.2.1 version of amavisd.conf provided you make a few changes. You would need to remove "$pax = 'pax';", "$ripole = 'ripole';" and the section that deals with using additional configuration files: "Want to execute additional configuration files from some directory?". Note that I have not actually tried using a modified copy of a 2.2.1 version of amavisd.conf. If you want users to connect to Maia using SSL (https://), you should use a different version of this document.

You must read so you will understand what we are trying to accomplish. Keep in mind that Maia will replace amavisd-new, and the version we install will be based on amavisd-new 2.2.0. This guide does not cover important configuration settings that need to be made once the software is in place. It just gets you to the point where you can log into Maia. This guide does not explain how to use Maia Mailguard, it merely gets it up and running. It uses many of the default settings, and it does not consider some security related issues. I don't use Maia myself, so I cannot be helpful regarding the configuration or use of the program. I also don't use Apache, and I am not skilled at MySQL. Absolutely no warranty. See the disclaimer at There is no support for this document, but you can contact me at 'mr88talent at yahoo dot com' if you have a correction or comment.

There is a 10MB .PDF available from that has some good tips for configuring and using Maia. This is a SuSE document, but the Maia stuff should give you a number of good ideas.

The first thing to do is backup our current amavisd-new. There is nearly no doubt you will make use of these backup files, so protect them well:
cp /etc/amavis/amavisd.conf /etc/amavis/amavisd.conf-debian
cp /etc/amavis/amavisd.conf /etc/amavis/amavisd.conf-debian-backup
cp /etc/amavis/amavisd.conf /etc/amavis/amavisd.conf-maia
cp /usr/sbin/amavisd-new /usr/sbin/amavisd-new-debian

We need to make a symbolic link because Maia will want to use /etc/amavisd.conf, not /etc/amavis/amavisd.conf:
ln -s /etc/amavis/amavisd.conf /etc/amavisd.conf

To insure Maia will work with MySQL 4.1, download the current SVN version of Maia. The last time I updated this guide, the most current revision was 1000. I advise you browse and make a note of the revision of the trunk you may choose to install today. You may also choose to install the last revision of 1.0.0 of Maia Mailguard by downloading SVN revision 962. You can of course pick a particular revision, but be aware that this document is based on revision 962. It appears this document is not accurate for versions higher than 962 (Maia 1.0.1). It is important that you have a version of Net::Server that is compatible with the version of Maia Mailguard you are going to install, see this. OK, let's get started:
apt-get update
apt-get install subversion

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

Choose the most current SVN version, or revision 962 (the last of the 1.0.0 revisions). Notice the last line of the download shows the version number you got. Keep this number handy:
svn checkout
(or to specify the exact version)
svn -r 962 checkout

Answer (p) if it asks...
If you ever use this method to download Maia again, you should first move the old downloaded files to another directory to avoid overwriting them. Read this thread. Now, install MySQL 4.1 (if you do not have MySQL installed):

apt-get install mysql-server-4.1

This one is optional. If you have problems with dependencies during installation you can skip this:
apt-get install libmysqlclient14-dev

Install more needed programs:
apt-get install libcrypt-blowfish-perl libcrypt-cbc-perl libossp-uuid-perl libtemplate-perl libwww-perl

All of these programs should already be installed, but you can run this just in case:
apt-get install libdigest-sha1-perl libnet-dns-perl libhtml-parser-perl libdbd-mysql-perl libdbi-perl libunix-syslog-perl libio-stringy-perl libnet-perl libnet-server-perl libmailtools-perl libmime-perl libconvert-uulib-perl libconvert-tnef-perl libcompress-zlib-perl libarchive-zip-perl libarchive-tar-perl

We install some others:
apt-get install cabextract libberkeleydb-perl libdigest-sha1-perl libdigest-hmac-perl libnet-dns-perl pax

Install Apache2 (unless you already have Apache, or another web server installed), PHP4, Pear and some additional Pear modules (you may have to pick and choose those that are not currently installed):
apt-get install php4 php4-pear php4-common php4-mysql php4-gd php4-sqlite smarty

pear install Mail_Mime
pear install Log
pear install DB_Pager
pear install Pager
pear install Image_Color
pear install Image_Graph-devel
pear install Numbers_Roman
pear install Auth_SASL
pear install Net_IMAP
pear install Net_POP3

Apache2 expects to find '/etc/php4/apache2/php.ini' but that file may not exist. We will create it if it does not. Please answer 'n' to 'Overwrite?' in case the file does exist:
mkdir /etc/php4/apache2
cp -i /etc/php4/apache/php.ini /etc/php4/apache2/php.ini

apt-get install apache2 libapache2-mod-php4

Change the firewall rules to allow access to port 80. Edit this to reflect your network (and any other custom modifications you made to the original version), or this will lock you out! Please see if this does not look familiar to you. It is quite likely you have your firewall set up using some other means, but the idea remains that you need to open up tcp port 80:

iptables -F
iptables -N FIREWALL
iptables -F FIREWALL
iptables -A INPUT -j FIREWALL
iptables -A FIREWALL -p tcp -m tcp --dport 25 --syn -j ACCEPT
iptables -A FIREWALL -p tcp -m tcp --dport 80 --syn -j ACCEPT
iptables -A FIREWALL -p tcp -m tcp -s --dport 22 --syn -j ACCEPT
iptables -A FIREWALL -i lo -j ACCEPT
iptables -A FIREWALL -p udp -m udp --sport 53 -j ACCEPT
iptables -A FIREWALL -p tcp -m tcp --sport 53 -j ACCEPT
iptables -A FIREWALL -p udp -m udp --dport 123 -j ACCEPT
iptables -A FIREWALL -p udp -m udp --sport 6277 -j ACCEPT
iptables -A FIREWALL -p udp -m udp --sport 24441 -j ACCEPT
iptables -A FIREWALL -p tcp -m tcp --syn -j REJECT
iptables -A FIREWALL -p udp -m udp -j REJECT
iptables-save > /etc/firewall-rules
iptables-restore < /etc/firewall-rules

You should now be able to open a browser and browse to the IP address of the spamfilter. I recommend adding the IP address and FQDN hostname of the spamfilter to your hosts file, so you can browse the server using the hostname instead of the IP address. Of course, eventually you will need to set up the host in DNS if you have not already done so. If this is a production server, obviously you already have.

We need to create some directories and copy some files per the INSTALL instructions:

mkdir /var/lib/amavis/maia
cp -r /usr/local/src/maia/branches/1.0/scripts /var/lib/amavis/maia/scripts
cp /var/lib/amavis/maia/scripts/database.cfg.dist /var/lib/amavis/maia/scripts/database.cfg
cp -r /usr/local/src/maia/branches/1.0/templates /var/lib/amavis/maia/templates
chown -R amavis:amavis /var/lib/amavis
chmod -R 750 /var/lib/amavis
chmod 640 /var/lib/amavis/maia/templates/*.tpl
chmod 640 /var/lib/amavis/maia/scripts/database.cfg

Now we need to edit these .pl scripts to reflect where some of our programs are installed, because our installation differs from the default. To preserve file ownership, edit these files as the amavis user. The use of the vi editor is only a suggestion, of course you can use whatever editor you please:
su amavis
cd /var/lib/amavis/maia/scripts

In these first four files, you need to (set|edit|change):
my $cfg = "/var/lib/amavis/maia/scripts/database.cfg";

In this next file, you need to (set|edit|change):
my $local_cf_dir = "/etc/spamassassin";
my $system_rules_dir = "/usr/share/spamassassin";
my $user_rules_dir = "/var/lib/amavis/.spamassassin";
my $cfg = "/var/lib/amavis/maia/scripts/database.cfg";

In this next file, you need to (set|edit|change):
my $subroutine = "/var/lib/amavis/maia/scripts/";
my $pid_file = "/var/lib/amavis/";

In this next file, you need to (set|edit|change):
my $cfg = "/var/lib/amavis/maia/scripts/database.cfg";
#my $key_file = "/var/lib/amavis/blowfish.key";

In this next file, you need to (set|edit|change) (use your actual host name in the url):
my $cfg = "/var/lib/amavis/maia/scripts/database.cfg";
my $base_url = "";
my $template_dir = "/var/lib/amavis/maia/templates/";

Now exit out of user 'amavis':

We need to log into MySQL and set the passwords for root (unless you have already done this). Note that I use the hostname 'sfa' in the example which you need to change to the actual hostname of your machine, and I also use 'Roots_Password' as a place holder for a real password that you supply:
mysql -u root
SET PASSWORD FOR 'root'@'localhost' = PASSWORD('Roots_Password');
SET PASSWORD FOR 'root'@'sfa' = PASSWORD('Roots_Password');

While you are still logged in to MySQL (if you are not, please do so), we now create the maia database:
USE maia;

Be careful that the next command points to the correct location of "maia-mysql.sql":
SOURCE /usr/local/src/maia/branches/1.0/maia-mysql.sql;

You should have seen a number of lines similar to "Query OK, 1 row affected (0.01 sec)" scroll by.
Now we create the amavis user (there are 2 commands here):



Let's see if our configuration looks OK so far:
cd /var/lib/amavis/maia/scripts/

This should result in something like:

file(1)              :     4.12 : OK
Archive::Tar         :     1.23 : OK
Archive::Zip         :     1.14 : OK
Compress::Zlib       :     1.34 : OK
Convert::TNEF        :     0.17 : OK
Convert::UUlib       :    1.051 : OK
MIME::Base64         :     3.04 : OK
MIME::QuotedPrint    :     3.03 : OK
MIME::Parser         :    5.417 : OK
Mail::Internet       :     1.62 : OK
Net::Server          :     0.87 : OK
Net::SMTP            :     2.29 : OK
Digest::MD5          :     2.33 : OK
Data::UUID           :     0.11 : OK
IO::Stringy          :    2.110 : OK
Time::HiRes          :     1.59 : OK
Unix::Syslog         :    0.100 : OK
DBI                  :     1.46 : OK
DBD::mysql           :   2.9006 : OK
DBD::Pg              :      N/A : NOT INSTALLED (required if you want to use PostgreSQL)


Mail::SpamAssassin   : 3.000003 : OK
File::Spec           :     0.87 : OK
Pod::Usage           :     1.16 : OK
HTML::Parser         :     3.45 : OK
DB_File              :    1.808 : 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
If (and only if) DB_File is missing, you may have to install it from CPAN:
perl -MCPAN -e shell
install DB_File

Now we copy SpamAssassin's rules to the MySQL database (make sure 'spamassassin --lint' does not return any errors; if it does, repair the errors before you continue):
spamassassin --lint
su amavis -c 'spamassassin --lint'

cd /var/lib/amavis/maia/scripts

You should have seen a bunch of rules get loaded; if not, then check that this script points to the correct directories (you edited it earlier). Now we will copy the web interface files to the web site. We also need to make 'themes' writable by the www-data user (and amavis):
mkdir /var/www/mail
cp -r /usr/local/src/maia/branches/1.0/php/* /var/www/mail
ln -s /usr/share/php/smarty/libs /usr/share/php/Smarty
cp /var/www/mail/config.php.dist /var/www/mail/config.php
chgrp amavis /var/www/mail/themes/*/compiled
chmod 775 /var/www/mail/themes/*/compiled
gpasswd -a www-data amavis

Stop and start Apache2:
/etc/init.d/apache2 stop
/etc/init.d/apache2 start

If you are running Postfix:
cp /etc/passwd /var/spool/postfix/etc/passwd
postfix reload

Now you browse to configtest.php to test the installation, for example:

The result should look something like this. Note that if you need the IMAP, LDAP or MCrypt libraries you are free to 'apt-get install' php4-imap, php4-ldap and php4-mcrypt (but only if needed).

We are going to copy (and rename) the maia version of amavisd-new:
cp /usr/local/src/maia/branches/1.0/amavisd-maia /usr/sbin/amavisd-new-maia

We created /etc/amavis/amavisd.conf-maia earlier, now we need to make it work with Maia:
vi /etc/amavis/amavisd.conf-maia

and place this setting somewhere convenient. Assuming you are not already using SQL in amavisd-new,
you could place this near (but not at) the top of amavisd.conf-maia:

@lookup_sql_dsn = ( ['DBI:mysql:maia:localhost', 'amavis', 'passwd'] );

I also suggest you place the SVN release number of Maia in a comment in this file. Note that you may also wish to temporarily set $log_level to 5 for when we send a few test messages through, examining /var/log/mail.log for signs of trouble. Also, please read section "12. Configure amavisd-maia" of the Maia installation instructions for other suggested amavisd-maia settings. Save and exit the file, and then make a backup copy:
cp /etc/amavis/amavisd.conf-maia /etc/amavis/amavisd.conf-maia-backup

Now, when you want to try Maia as your program, you first stop amavisd-new:
amavisd-new stop

Then you copy the Maia files on top of the amavisd-new files:
cp /usr/sbin/amavisd-new-maia /usr/sbin/amavisd-new
cp /etc/amavis/amavisd.conf-maia /etc/amavis/amavisd.conf

Then you start up amavisd-new (Maia) (actually, the first time you start it up it would be a good idea to do so with 'amavisd-new debug'):
amavisd-new start

You can keep an eye out for errors by using:
tail -f /var/log/mail.log

You should watch the log for at least 10 messages, then use [Ctrl]+c to return to the shell prompt. If you need to revert to using amavisd-new, first you would stop amavisd-new (I mean Maia), copy the Debian files on top of the Maia files, and start up amavisd-new, like this:
amavisd-new stop
cp /usr/sbin/amavisd-new-debian /usr/sbin/amavisd-new
cp /etc/amavis/amavisd.conf-debian /etc/amavis/amavisd.conf
amavisd-new start

You should prevent new versions of amavisd-new from installing:
echo "amavisd-new hold" | dpkg --set-selections

If you should need to reverse this, you would replace "amavisd-new hold" with "amavisd-new install".

To avoid losing configuration changes, you should always make configuration changes to amavisd.conf-debian or amavisd.conf-maia and then copy the one you are currently using to amavisd.conf.

At this point, nothing is set up in Maia, so If I am correct, all mail will simply pass. I believe the default behavior is to bypass all checks for recipients not in the database.

Continue on by going to and start reading from "14. Login and become the super-administrator". Since you are starting out using the "Internal" authentication method, run the   script before running the  script   My internal-init.php page looked similar to this. Don't forget you need to set up DNS (if you have not done so) so your users can use your server's FQDN to access Maia.

Now, please realize you need to read the Maia documentation, and set up some cron jobs to run the maintenance scripts:


Here is a hint if you would like to change the password used by amavis to access the MySQL database. The default MySQL password for the amavis user is 'passwd'.

Stop Apache2:

/etc/init.d/apache2 stop

Stop Maia (amavisd-new):
/etc/init.d/amavis stop

Locate and change the $maia_sql_dsn password in config.php:
vi /var/www/mail/config.php

Locate and change the @lookup_sql_dsn password in amavisd.conf:
vi /etc/amavis/amavisd.conf

Locate and change the @lookup_sql_dsn password in amavisd.conf-maia:
vi /etc/amavis/amavisd.conf-maia

Locate and change the password in database.cfg:
su amavis -c 'vi /var/lib/amavis/maia/scripts/database.cfg'

Log in to mysql and change the password there, obviously, replace NEW-passwd with the new password:
mysql -p
SET PASSWORD FOR 'amavis'@'localhost'= PASSWORD('NEW-passwd');

Run to make sure the "Database DSN test" passes:

Start Maia (amavisd-new):
/etc/init.d/amavis start

Start Apache2:
/etc/init.d/apache2 start

It would be a good idea to run configtest.php:

I'm tired, that's all I have to give on this project, you are on your own now... good luck.

Useful link:
You used 'subversion' (svn) to 'check out' the current version of Maia Mailguard.
To see what 'subversion' is capable of, see:

mr88talent at yahoo dot com