Installing Maia Mailguard 1.0.2 on a Debian etch mail server


Absolutely no warranty, use entirely at your own risk. See the disclaimer at http://verchick.com/mecham/public_html/spam/. Note: This document assumes you have installed amavisd-new (from source) per one of the documents at http://verchick.com/mecham/public_html/spam/. It also assumes you have installed and configured spamassassin, clamav clamav-daemon and Postfix. (Hint, after installing clamav-daemon, run 'gpasswd -a clamav amavis' to add the clamav user to the amavis group). If you have not yet installed amavisd-new, please do not install a Debian 'testing' (etch) or 'unstable' (sid) version (why?). If you have installed one of these Debian packages, it must be removed (and at least the initscript replaced with the 20030616p10-5 version). Here is a procedure that will remove the Debian 2.4.x amavisd-new, replace the init scrip with a version that appears to be compatible with both the Debian version of amavisd-new and Maia, and then puts the Debian version of amavisd-new back together so it still works:

First test that when you remove amavisd-new, only amavisd-new will be removed:
apt-get -s remove amavisd-new

If it is the only thing that will be removed, continue on:

mkdir /etc/ambackup
cp /etc/init.d/amavis /etc/ambackup/amavis-init
cp -R /etc/amavis/ /etc/ambackup/amavis-backup
cp -R /usr/share/amavis/conf.d /usr/share/amavis/conf.d-temp
cp /usr/sbin/amavisd-new /usr/sbin/amavisd-new-temp
cp /usr/share/perl5/JpegTester.pm /usr/share/perl5/JpegTester.pm-temp
amavisd-new stop
apt-get remove amavisd-new

cd /etc/init.d
wget http://verchick.com/mecham/public_html/debian/amavis-init-20030616
mv amavis-init-20030616 amavis
chmod +x amavis
cp /usr/sbin/amavisd-new-temp /usr/sbin/amavisd-new
cp -R /usr/share/amavis/conf.d-temp /usr/share/amavis/conf.d
cp /usr/share/perl5/JpegTester.pm-temp /usr/share/perl5/JpegTester.pm
/etc/init.d/amavis start


This HOWTO is a quick and dirty guide to getting Maia Mailguard version 1.0.2 installed on a Debian etch gateway email server that was originally built using http://verchick.com/mecham/public_html/spam/spamfilter20061118.html or similar as a guide. This document is based on "etch testing". 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. We will replace amavisd.conf with one specific to Maia http://verchick.com/mecham/public_html/amavisd.conf.maia. This file has been modified for use with Debian.

You must read https://www.maiamailguard.com/maia/wiki/Install 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.1. 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. 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 http://www.novell.com/coolsolutions/feature/16093.html 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

Download the current revision of Maia 1.0.x. The last time I updated this guide, the most current revision was 1160 (which I believe is the bundled version of 1.0.2). I advise you browse https://www.maiamailguard.com/svn/branches/1.0 and make a note of the revision of the trunk you may choose to install today. You can of course pick a particular revision, but be aware that this document is based on revision 1160. 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 1160. Notice the last line of the download shows the version number you got. Keep this number handy:
svn checkout https://www.maiamailguard.com/svn/branches/1.0
(or to specify the exact version)
svn -r 1160 checkout https://www.maiamailguard.com/svn/branches/1.0

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.

If you picked a version less than 1184, you need to apply a security patch:
cd 1.0/php
cp xlogin.php xlogin.php~
cp login.php login.php~
cp internal-init.php internal-init.php~
wget http://verchick.com/mecham/public_html/spam/maiasecuritypatch1184.txt
patch -p0 < maiasecuritypatch1184.txt

If the patch was applied successfully:
rm -f xlogin.php~
rm -f login.php~
rm -f internal-init.php~

Now, install MySQL 4.1 (if you do not have MySQL installed):
apt-get install mysql-server

This one is optional but recommended. If you have problems with dependencies during installation you can skip this:
apt-get install libmysqlclient15-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 libhtml-parser-perl libdbd-mysql-perl libdbi-perl libunix-syslog-perl libio-stringy-perl libnet-server-perl libmailtools-perl libmime-perl libconvert-uulib-perl libconvert-tnef-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 PHP5, Pear and some additional Pear modules. This may also install/upgrade x11-common.
Be forewarned you may get this warning. This should not be an issue if you are not using a GUI.
apt-get install php5 php-pear php5-common php5-mysql php5-gd php5-sqlite smarty

pear install Mail_Mime-1.3.1
pear install Log-1.9.9
pear install Pager-2.4.2

pear install Image_Color-1.0.2
pear install Image_Canvas-0.3.0
pear install Image_Graph-0.7.2
pear install Numbers_Roman-0.2.0
pear install Numbers_Words-0.14.0

pear install Auth_SASL-1.0.1
pear install Net_Socket-1.0.6
pear install Net_IMAP-1.0.3
pear install Net_POP3-1.3.6
pear install Net_SMTP-1.2.8
pear install DB-1.7.6

 There is a bug in Pie.php provided with Image_Graph-0.7.2. If you have installed this version of Image_Graph, grab a file from me to fix the bug:
cd /usr/share/php/Image/Graph/Plot/
mv Pie.php Pie.php.orig
wget http://verchick.com/mecham/public_html/Pie.php.txt
mv Pie.php.txt Pie.php

We also need to apply a PHP5 specific patch to a Net_IMAP file:
cd /usr/share/php/Net/
cp IMAPProtocol.php IMAPProtocol-orig.php
wget http://verchick.com/mecham/public_html/spam/IMAPProtocol.php.patch.txt
patch IMAPProtocol.php < IMAPProtocol.php.patch.txt
cd

When the time comes you want to view Pie charts, enable them with Settings->Miscellaneous Settings->Display graphic charts?

Install Apache2
apt-get install apache2 libapache2-mod-php5

To avoid redirecting the root of the web server pages, edit this file:
vi /etc/apache2/sites-available/default

and comment out this line:
RedirectMatch ^/$ /apache2-default/

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 http://verchick.com/mecham/public_html/spam/debian-smtp-firewall.html 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 FORWARD -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 222.222.222.222/24 --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. We use 'sed' to change /var/amavisd to /var/lib/amavisd in a few files:

mkdir /var/lib/amavis/db
mkdir /var/lib/amavis/maia
mkdir /var/lib/amavis/maia/scripts
cd /var/lib/amavis/maia/scripts
cp /usr/local/src/maia/1.0/scripts/* .
cp load-sa-rules.pl 1
cp process-quarantine.pl 2
cp send-quarantine-digests.pl 3
sed 's/var\/amavisd/var\/lib\/amavis/g' 1 > load-sa-rules.pl
sed 's/var\/amavisd/var\/lib\/amavis/g' 2 > process-quarantine.pl
sed 's/var\/amavisd/var\/lib\/amavis/g' 3 > send-quarantine-digests.pl
rm 1 2 3
test -e /etc/maia.conf && cp /etc/maia.conf /etc/maia.conf-backup
cp /usr/local/src/maia/1.0/maia.conf.dist /etc/maia.temp
sed 's/var\/amavisd/var\/lib\/amavis/g' /etc/maia.temp > /etc/maia.conf
cp -r /usr/local/src/maia/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

Now we need to edit maia.conf to reflect what our URL will be. We are going to place our files in a /mail/ directory. The use of the vi editor is only a suggestion, of course you can use whatever editor you please:
vi /etc/maia.conf

$base_url = "http://sfa.example.com/mail/";

Save and exit the file. We need to log into MySQL and set the passwords for root (unless you have already set the password, in which case log in with 'mysql -p'.). 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:
CREATE DATABASE maia;
USE maia;

Be careful that the next command points to the correct location of "maia-mysql.sql":
SOURCE /usr/local/src/maia/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 and then quit (there are 3 commands here). Literally use the password of 'passwd' here:
GRANT CREATE, DROP, ALTER, SELECT, INSERT, UPDATE, DELETE ON maia.* TO amavis@localhost IDENTIFIED BY 'passwd';

FLUSH PRIVILEGES;
quit

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

 This should result in something like:
Perl                 :    5.8.4 : OK
file(1)              :     4.12 : OK
Archive::Tar         :     1.23 : OK
Archive::Zip         :     1.14 : OK
BerkeleyDB           :     0.26 : OK
Compress::Zlib       :     1.34 : UPGRADE RECOMMENDED (minimum version ...
Convert::TNEF        :     0.17 : OK
Convert::UUlib       :    1.051 : UPGRADE RECOMMENDED (minimum version ...
Crypt::Blowfish      :     2.09 : OK
Crypt::CBC           :     2.12 : OK
Crypt::OpenSSL::RSA  :      N/A : NOT INSTALLED (SpamAssassin's optional...
Data::UUID           :     0.11 : OK
DB_File              :    1.808 : OK
DBD::mysql           :   2.9006 : OK
DBD::Pg              :      N/A : NOT INSTALLED (required if you use Postgre...
DBI                  :     1.46 : OK
Digest::MD5          :     2.33 : OK
Digest::SHA1         :     2.10 : OK
File::Spec           :     0.87 : OK
HTML::Parser         :     3.45 : OK
HTTP::Date           :     1.46 : OK
IO::Stringy          :    2.110 : OK
IO::Zlib             :     1.04 : OK
IP::Country          :      N/A : NOT INSTALLED (SpamAssassin's optional ...
LWP::UserAgent       :    2.033 : OK
Mail::Address        :     1.62 : OK
Mail::DomainKeys     :      N/A : NOT INSTALLED (SpamAssassin's optional ...
Mail::Internet       :     1.62 : OK
Mail::SpamAssassin   :    3.0.3 : OK
Mail::SPF::Query     :      N/A : NOT INSTALLED (SpamAssassin's optional SPF ...
MIME::Base64         :     3.04 : OK
MIME::Parser         :    5.417 : UPGRADE RECOMMENDED (minimum version 5.420)
MIME::QuotedPrint    :     3.03 : OK
Net::CIDR::Lite      :      N/A : NOT INSTALLED (SpamAssassin's optional SPF ...
Net::DNS             :     0.48 : OK
Net::Server          :     0.87 : UPGRADE RECOMMENDED (minimum version 0.93)
Net::SMTP            :     2.29 : OK
Pod::Usage           :     1.16 : OK
Template             :     2.14 : OK
Time::HiRes          :     1.59 : OK
Unix::Syslog         :    0.100 : OK
URI                  :     1.35 : OK

Database DSN test    : PASSED
We are using Debian stable which means some of our programs will be a little old, but most of these upgrade recommendations are based on security issues which have been patched in the Debian packages. Other modules are only recommendations. Hopefully you are familiar with the Debian naming convention of Perl packages. For example, Mail::SPF::Query would be libmail-spf-query-perl (which is probably a good one to have). Not all of the Perl modules are this easy to find however as many of them are included in packages that contain a number of modules. You can also upgrade to newer versions of some Perl modules using CPAN if desired, but if you do, the Debian package of the same program will be ignored from now on.

If (and only if) DB_File is missing, you may have to install it from CPAN:
perl -MCPAN -e shell
install DB_File
quit

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'

Since we are using SpamAssassin 3.1.1 or greater we can use the new sa-update feature.
If you want to run sa-update without using GPG, run:
sa-update --nogpg

Optionally, you may first import the gpg key:
cd /etc/spamassassin
wget http://spamassassin.apache.org/released/GPG-SIGNING-KEY
gpg --import GPG-SIGNING-KEY

Then simply run:
sa-update

cd /var/lib/amavis/maia/scripts
./load-sa-rules.pl

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

 Enable mysql and gd graphics in php.ini:
vi /etc/php5/apache2/php.ini

and uncomment these two lines (remove the semicolons)
;extension=mysql.so
;extension=gd.so

Save and exit the file, then 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:
http://192.168.1.222/mail/admin/configtest.php
(or)
http://sfa.example.com/mail/admin/configtest.php

The result should look something like this. Note: if you need the IMAP, LDAP or MCrypt libraries you are free to
apt-get install php5-imap php5-ldap php5-mcrypt (but only as needed). Also note: we have already applied the patches to Image_Graph and Net_IMAP. Also, remember to stop and start apache2 if you make changes.

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

 We will start off with a configuration file specific to Maia. I have modified such a file for use with Debian:
cd /etc/amavis
wget http://verchick.com/mecham/public_html/amavisd.conf.maia
mv amavisd.conf.maia amavisd.conf-maia

We need to make a few changes to amavisd.conf-maia:
vi /etc/amavis/amavisd.conf-maia

I suggest you place the SVN release number of Maia in a comment in this file. If you have not configured this amavisd.conf in the past, at the very least you need to set $mydomain. 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 had amavisd-new installed and need to revert to it, 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

If you have 20030616-p10 installed, you should prevent new versions of amavisd-new from installing during an 'apt-get upgrade':
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 so you will quickly want to add and configure your users and/or domains.

Continue on by going to https://www.maiamailguard.com/maia/wiki/Install and start reading from "14. Login and become the super-administrator". Since you are starting out using the "Internal" authentication method, run the
http://sfa.example.com/mail/internal-init.php   script before running the
http://sfa.example.com/mail/login.php?super=register  script.   My internal-init.php page looked similar to this example. If all goes well, you will get a "250 Ok" response on the screen and your password in a message in your inbox. Place your email address in the "E-mail address your login credentials should be mailed to" box. Run the super-register script shown above next. 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: https://www.maiamailguard.com/maia/wiki/MaintenanceScripts. The SQL based Bayes and AWL tables have also been created for you. You can enable them by placing this in /etc/spamassassin/local.cf:
bayes_store_module              Mail::SpamAssassin::BayesStore::SQL
bayes_sql_dsn                   DBI:mysql:maia:localhost
bayes_sql_username              amavis
bayes_sql_password              passwd

# change ::SQL to ::MySQL if SpamAssassin >= 3.1.0 and MySQL >= 4.1

bayes_sql_override_username         amavis

auto_whitelist_factory          Mail::SpamAssassin::SQLBasedAddrList
user_awl_dsn                    DBI:mysql:maia:localhost
user_awl_sql_username           amavis
user_awl_sql_password           passwd
If you have not used SQL based Bayes before (you are currently using the default BDB based Bayes) and you need to migrate Bayes data or AWL data to SQL, see http://verchick.com/mecham/public_html/spam/debian-maia-spamassassin-sql.html

# Suggested reading (settings like innodb_buffer_pool_size go in the [mysqld] section of /etc/my.cnf):
# run   find /usr/share/doc -name my-*.cn*   for samples
http://verchick.com/mecham/public_html/spam/mysqlspeed.txt
http://www.mysqlperformanceblog.com/2006/09/29/what-to-tune-in-mysql-server-after-installation/
http://www.mysql.com/news-and-events/newsletter/2003-11/a0000000269.html

******************************************************************************************************

PS:
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 /etc/maia.conf:
vi /etc/maia.conf

Locate and change the password in /etc/spamassassin/local.cf:
vi /etc/spamassassin/local.cf

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');
FLUSH PRIVILEGES;
quit

 Run configtest.pl to make sure the "Database DSN test" passes:
/var/lib/amavis/maia/scripts/configtest.pl

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:
http://sfa.example.com/mail/admin/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: http://svnbook.red-bean.com/

mr88talent at yahoo dot com
07 JAN 07