Installation instructions

MailWatch for MailScanner is developed on Debian 7-9 & Ubuntu 12.04-16.04, so these docs will reflect this and I will make note on anything that will be required to run on other distro’s or operating systems.

If you’re upgrading from a previous version, read upgrading instructions.

Before you start

You must have a working MailScanner set-up and have running copies of MySQL, Apache, PHP (with MySQL and GD support) and for MailScanner to be able to use a database you need Perl DBI and DBD::mysql; you also need Perl Encoding::FixLatin to deal with email subjects that contain characters in more than one encoding and Perl Digest::SHA1 for generation of view tokens.

Some PHP extensions and executable software are required to make MailWatch fully works:

  • MySQL extension (required to connect to database)
  • GD extension (required to generate graphs on reports)
  • MBstring extension (required to display non-ascii characters)
  • exec function not disabled in php.ini
  • Curl extension or fsockopen function enabled (needed to download GeoIP files)
  • Zlib extension or gunzip executable (needed to extract GeoIP files)
  • Ldap extension (needed if you are authenticating users on LDAP server or Active Directory)

Support

Please use the mailing-list mailwatch-users on Sourceforge. Note that you will get faster support if you use the mailing-list.

Notes for PHP configuration

PHP should have at least the following set in php.ini (possibly others too):

safe_mode = Off
register_globals = Off
magic_quotes_gpc = Off
magic_quotes_runtime = Off
session.auto_start = 0
date.timezone = '<your time zone>'

Installation

All commands below should be run as ‘root’ user.

Installing MailWatch

There are 2 methods to install MailWatch: zip install and git cloning.

In the following instructions /opt/mailwatch is used as base directory for MailWatch Install, if you prefer you can use another directory that you like.

Zip install

mkdir /opt/mailwatch
cd /opt/mailwatch
wget https://github.com/mailwatch/MailWatch/archive/v1.2.10.zip
unzip v1.2.10.zip -d /opt/mailwatch
rm v1.2.10.zip

Git cloning

mkdir /opt/mailwatch
cd /opt/mailwatch
git clone --depth=1 https://github.com/mailwatch/MailWatch.git --branch 1.2 --single-branch .

Create the database

 $ mysql < create.sql

NOTE: you will need to modify the above as necessary for your system if you have a root password for your MySQL database (which is highly recommended!).

Create a MySQL user and password & Set-up MailScanner for SQL logging

 $ mysql

mysql> GRANT ALL ON mailscanner.* TO mailwatch@localhost IDENTIFIED BY '<password>';
mysql> GRANT FILE ON *.* TO mailwatch@localhost IDENTIFIED BY '<password>';
mysql> FLUSH PRIVILEGES;
mysql> quit

Copy MailWatchConf.pm in MailScanner CustomFunctions directory and edit it to match your database settings. MailScanner CustomFunctions path depends on MailScanner version:

  • MailScanner V4: /usr/lib/MailScanner/MailScanner/CustomFunctions (this could be /opt/MailScanner/lib/MailScanner/MailScanner/CustomFunctions on non-RPM systems).
  • MailScanner V4.86.1 or V5: /usr/share/MailScanner/perl/custom

Symlink the others .pm files in the same MailScanner CustomFunctions directory:

 $ ln -s /opt/mailwatch/MailScanner_perl_scripts/MailWatch.pm /usr/share/MailScanner/perl/custom
 $ ln -s /opt/mailwatch/MailScanner_perl_scripts/SQLBlackWhiteList.pm /usr/share/MailScanner/perl/custom
 $ ln -s /opt/mailwatch/MailScanner_perl_scripts/SQLSpamSettings.pm /usr/share/MailScanner/perl/custom

Symlinking instead of copying assure a painless upgrade in the future.

Create a MailWatch web user

You need at minimum to create the administrator user ‘admin’ needed to access the MailWatch GUI and to handle default Spam Setting used by SQLSpamSettings.pm script.

 $ mysql mailscanner -u mailwatch -p

Enter password: ******
mysql> INSERT INTO users SET username = 'admin', password = MD5('<password>'), fullname = '<name>', type = 'A'

MD5 password hash will be updated automatically to a more secure hash on first login.

Install and Configure MailWatch

Checking permissions

The web server user needs write and read access to /opt/mailwatch/mailscanner/temp.

 $ chown root:apache temp
 $ chmod g+rw temp

Edit conf.php

Create conf.php by copying conf.php.example and edit the values to suit, you will need to set DB_USER and DB_PASS to the MySQL user and password that you created earlier and adjust any configuuration to your system, like MAILWATCH_HOME if it’s not the default one.

 $ cp conf.php.example conf.php

Note that MailWatch 1.0 and later can use the quarantine more effectively when used with MailScanner version 4.43 or later as MailScanner developers added some code for MailWatch to keep track of messages quarantined by using a flag in the maillog table.

This means that MailWatch 1.0 is much faster when you have a large quarantine directory. The new quarantine report requires the use of the new functionality - so you must upgrade if you want to run this. The new quarantine flag is used by default and you must disable the clean.quarantine script supplied by MailScanner and use the new quarantine_maint.php script in the tools directory instead.

To clean the quarantine - set QUARANTINE_DAYS_TO_KEEP in conf.php and run ./quarantine_maint --clean. This should then be run daily from cron. If you are still using MailScanner 4.42 or older, updating your installation is highly recommanded; if you can’t update you need to set the QUARANTINE_USE_FLAG to false in conf.php and use the clean.quarantine script supplied by MailScanner.

Run upgrade.php

After setting up your conf.php file you need to run the uprade script, which will take care of some optimization for your installation:

  • test DB connection
  • upgrade to full UTF-8 support if your MySQL installation support it (MySQL ≥ 5.5.3)
  • check MailScanner configuration and alert for missing mandatory configuration
  • check conf.php and alert for missing mandatory configuration
 $ php upgrade.php

upgrade.php accepts a couple of parameter that can be useful for you:

  • --skip-user-confirm: adding this parameter will bypass confirmation for running the upgrade script
  • /path/to/functions.php: you can pass a non standard path for functions.php file used by upgrade script

Configure webserver

It’s recommended to setup a virtualhost to manage MailWatch; this setup depends on your webserver of choice. Below you’ll find basic config example for apache and nginx, adapt them to your prefered setup (ssl, additional header, and so on).

nginx

server {
    listen 80 default_server;
    server_name mailwatch.example.org;

    access_log /var/log/nginx/mailwatch/access.log main_ext;
    error_log /var/log/nginx/mailwatch/error.log warn;

    root /opt/mailwatch/mailscanner;

    location / {
        index  index.php;
    }
    
    location ~* \.php$ {
        fastcgi_index   index.php;
        fastcgi_pass    unix:/var/run/php7-fpm.sock;
        include         fastcgi.conf;
        fastcgi_param   SCRIPT_FILENAME    $document_root$fastcgi_script_name;
        fastcgi_param   SCRIPT_NAME        $fastcgi_script_name;
    }
}

Apache

<virtualhost *:80>
    ServerName mailwatch.example.org
    DocumentRoot "/opt/mailwatch/mailscanner"
    ErrorLog "/var/log/apache/mailwatch/error.log"
    CustomLog "/var/log/apache/mailwatch/access.log" combined

    <Directory />
        # Apache 2.4
        Require all granted
        
        # Apache 2.2
        #Order allow,deny
        #Allow from all
    </Directory>

    AddType application/x-httpd-php .php
    DirectoryIndex index.php
</virtualhost>

Caddy 2

mailwatch.example.org {
    root * /opt/mailwatch/mailscanner
    file_server
    php_fastcgi 127.0.0.1:9000
}

Set-up MailScanner

Stop MailScanner

 $ service mailscanner stop

Next edit /etc/MailScanner/MailScanner.conf - you need to make sure that the following options are set:

Always Looked Up Last = &MailWatchLogging
Detailed Spam Report = yes
Quarantine Whole Message = yes
Quarantine Whole Messages As Queue Files = no
Include Scores In SpamAssassin Report = yes
Quarantine User = root
Quarantine Group = apache (this should be the same group as your web server)
Quarantine Permissions = 0660

If you are using Exim or Postfix you also have to adjust the following settings (replace Debian-exim with postfix when using postfix :

Run As User = Debian-exim
Run As Group = Debian-exim
Incoming Work User = Debian-exim
Incoming Work Group = mtagroup
Incoming Work Permissions = 0660
Quarantine User = Debian-exim
Quarantine Group = mtagroup
Quarantine Permissions = 0644

Additionally set permissions for the webserver to see the postfix queue with:


usermod -a -G mtagroup www-data
chgrp mtagroup /var/spool/postfix/incoming
chgrp mtagroup /var/spool/postfix/hold
chmod g+rx /var/spool/postfix/incoming
chmod g+rx /var/spool/postfix/hold

Spam Actions and High Scoring Spam Actions should also have ‘store’ as one of the keywords if you want to quarantine items for learning/viewing in MailWatch.

Move the Bayesian Databases and set-up permissions (skip this if you don’t use bayes).

Edit /etc/MailScanner/spamassassin.conf(MailScanner v5) or /etc/MailScanner/spam.assassin.prefs.conf(MailScanner v4) and set:

bayes_path /etc/MailScanner/bayes/bayes
bayes_file_mode 0660

Create the ‘new’ bayes directory, make the directory owned by the main group of the web server (eg. apache or www-data; a supplemental group won’t work) and the user your mailscanner is started with (eg. postfix/Debian-exim) and make the directory setgid:

 $ mkdir /etc/MailScanner/bayes
 $ chown root:www-data /etc/MailScanner/bayes
 $ chmod g+rws /etc/MailScanner/bayes

Copy the existing bayes databases …

 $ cp /root/.spamassassin/bayes_* /etc/MailScanner/bayes

… or just create new bayes databases …

$ sa-learn --sync

… and setup permissions

 $ chown root:www-data /etc/MailScanner/bayes/bayes_*
 $ chmod g+rw /etc/MailScanner/bayes/bayes_*

Test SpamAssassin to make sure that it is using the new databases correctly:

MailScanner v5:

 $ spamassassin -D -p /etc/MailScanner/spamassassin.conf --lint

Or for MailScanner v4:

 $ spamassassin -D -p /etc/MailScanner/spam.assassin.prefs.conf --lint

and you should see something like:

debug: using "/etc/MailScanner/spamassassin.conf" for user prefs file
debug: bayes: 28821 tie-ing to DB file R/O /etc/MailScanner/bayes/bayes_toks
debug: bayes: 28821 tie-ing to DB file R/O /etc/MailScanner/bayes/bayes_seen
debug: bayes: found bayes db version 2
debug: Score set 3 chosen.

Start MailScanner up again.

 $ service mailscanner start && tail -f /var/log/maillog

You should see something like:

Jun 13 12:18:23 hoshi MailScanner[26388]: MailScanner E-Mail Virus Scanner version 5.03-3 starting...
Jun 13 12:18:24 hoshi MailScanner[26388]: Config: calling custom init function MailWatchLogging
Jun 13 12:18:24 hoshi MailScanner[26388]: Initialising database connection
Jun 13 12:18:24 hoshi MailScanner[26388]: Finished initialising database connection

Congratulations - you now have MailScanner logging to MySQL.

If you want to see the output of MailScanner --lint in Tools/MailScanner Lint (Test) edit conf.php and set MS_EXECUTABLE_PATH, the follow instruction in tools/sudo/INSTALL

Database cleanup of maillog records

Copy tools/Cron_jobs/mailwatch to /etc/cron.daily/

 $ cp tools/Cron_jobs/mailwatch /etc/cron.daily/
 $ chmod +x /etc/cron.daily/mailwatch

You can edit /etc/cron.daily/mailwatch to fit your need.

Copy tools/Cron_jobs/mailwatch_db_clean.php to /usr/local/bin/ and make it executable:

 $ cp tools/Cron_jobs/mailwatch_db_clean.php /usr/local/bin/
 $ chmod +x /usr/local/bin/mailwatch_db_clean.php

You need to edit conf.php and change the RECORD_DAYS_TO_KEEP definition. You will need to edit the mailwatch_db_clean.php to reflect the location of the functions.php file.

Quarantine Maintenance

For MailScanner v4: remove the clean.quarantine cronjob configured with MailScanner.

For MailScanner v5: change the variable for Quarantine Retention to “q_days=0” in /etc/MailScanner/defaults.

Copy tools/Cron_jobs/mailwatch_quarantine_maint.php to /usr/local/bin/ and make it executable:

 $ cp tools/Cron_jobs/mailwatch_quarantine_maint.php /usr/local/bin/
 $ chmod +x /usr/local/bin/mailwatch_quarantine_maint.php

You will need to edit conf.php the QUARANTINE_DAYS_TO_KEEP definition.

You will need to edit the mailwatch_quarantine_report.php to reflect the location of the functions.php file.

Quarantine Reporting

Copy tools/Cron_jobs/mailwatch_quarantine_maint.php to /usr/local/bin/ and make it executable:

 $ cp tools/Cron_jobs/mailwatch_quarantine_report.php /usr/local/bin/
 $ chmod +x /usr/local/bin/mailwatch_quarantine_report.php

You will need to edit the mailwatch_quarantine_report.php to reflect the location of the functions.php file

Sudo file for MailWatch

Copy tools/sudo/mailwatch file in /etc/sudoers.d/

Edit /etc/sudoers.d/mailwatch file to match web server user (www-data, apache or other) and MTA Queue and change executable path if needed.

Set permission to 0440 (chmod 440 /etc/sudoers.d/mailwatch)

This instruction should work in Debian 6 and newer, Ubuntu 12.04 and newer, RHEL 5 and 6 and CentOS 5 and 6.

Test the MailWatch interface

Point your browser to http://your-mailwatch-virtualhost-address/ - you should be prompted for a username and password - enter the details of the MailWatch web user that you created earlier, and you should see a list of the last 50 messages processed by MailScanner.

  • Update the SpamAssassin Rules table MailWatch keeps a list of all the SpamAssassin rules and descriptions which are displayed on the ‘Message Detail’ page - to show the descriptions, you need to run the updater every time you add new rules or upgrade SpamAssassin. Click on the ‘Other’ menu and select ‘Update SpamAssassin Rule Descriptions’ and click ‘Run Now’.

  • Update the GeoIP database Click on the ‘Other’ menu and select ‘Update GeoIP database’ and click ‘Run Now’. To update GeoIP database you need to obtain a free License Key: you can get one by visiting www.maxmind.com .

FINISHED!! (Phew!)

Please open an issue on GitHub or report to the mailing-list mailwatch-users if you find any errors or omissions.

Thanks!