Appending by:

MailWatch for MailScanner is developed on RedHat 9 & RHEL 3.0, so these docs will reflect this and I will make note on anything that will be required to run on other distros or operating systems.

For a Debian install try this (beta)


You must have a working MailScanner set-up and running copies of MySQL, Apache, and PHP (with MySQL and GD support). You must also have the Perl DBD-MySQL package installed for the Perl portions of MailScanner to utilize the MySQL database.


If you need help please use the mailing-list or the forums on Sourceforge. NOTE: You will likely get faster support from the mailing list than from the forum.


PHP should have the following set in php.ini (possibly others too….)

  • short_open_tag = On
  • safe_mode = Off
  • register_globals = Off
  • magic_quotes_gpc = On
  • magic_quotes_runtime = Off
  • session.auto_start = 0

Special consideration for RHEL 4.x / Centos 4.x users. The PHP GD support has been moved into a different module. You need to ensure that PHP-GD is installed. On Centos 4.1 the command is:

    yum install php-gd


All commands below should be run as root.

Create the database
    # mysql -p < 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 (recommended!) - RH9 is blank by default.

Create a MySQL user and password & Set-up MailScanner for SQL logging
    # mysql
    mysql> GRANT ALL ON mailscanner.* TO mailwatch@localhost IDENTIFIED BY '<password>';
Edit and copy

Edit and change the $db_user and $db_pass values accordingly and move to /usr/lib/MailScanner/MailScanner/CustomFunctions (this could be /opt/MailScanner/lib/MailScanner/MailScanner/CustomFunctions on non-RPM systems).

Create a MailWatch web user
    # mysql mailscanner -u mailwatch -p
    Enter password: ******
    mysql> INSERT INTO users VALUES ('<username>',md5('<password>'),'<name>','A','0','0','0','0','0');

*** remove the < and > around the username/password/name (It seems silly to have to say it, but some don't get it).

Install & Configure MailWatch

From within the unpacked mailwatch directory move the directory called 'mailscanner' to the web server's root.

    # mv mailscanner /var/www/html/

Check the permissions of /var/www/html/mailscanner/images and /var/www/html/images/cache - they should be ug+rwx and owned by root and in the same group as the web server user (apache on RedHat 9).

    # chown root:apache images
    # chmod ug+rwx images
    # chown root:apache images/cache
    # chmod ug+rwx images/cache

In the newly installed/moved html/mailscanner directory, 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.

Note that MailWatch 1.0 can use the quarantine more effectively when used with MailScanner version 4.43 or later as Julian added some code for me 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 not used by default - if you have MailScanner verions 4.43 or later, you can activate the new functionality by setting QUARANTINE_USE_FLAG to true in conf.php - if you do this, you must disable the clean.quarantine script supplied by MailScanner and use the new quarantine_maint.php script in the tools directory instead.

To disable the clean.quarantine script edit /pathtomailmailscanner/bin/cron/clean.quarantine.cron and change

    $disabled = 0;


    $disabled = 1;

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: you can do this by running

    echo "/pathtomailwatch/tools/quarantine_maint.php --clean" > /etc/cron.daily/
    chmod +x /etc/cron.daily/

To keep the MySQL database clean from old records, you should run tools/db_clean.php daily (as a cron job). Be sure the first line is

    #!/usr/bin/php -q

instead of

    #!/usr/bin/php -qn
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:

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

Spam Actions and High Scoring Spam Actions should also have 'store' as one of the keywords if you want to quarantine those items for bayes learning or viewing from within MailWatch.

Integrate SQL Blacklist/Whitelist (optional)

If you would like to manage the MailScanner whitelist and blacklist from within the MailWatch web interface perform the following steps.

1. Edit the MySQL connection values within the CreateList subroutine of to match the values you entered previous into Both files should contain the same values. (Look for the following lines in and enter your own data.)

    my($db_user) = '<username>';
    my($db_pass) = '<password>';

2. Copy to /usr/lib/MailScanner/MailScanner/CustomFunctions/

3. Edit MailScanner.conf and set:

  • Is Definitely Not Spam = &SQLWhitelist
  • Is Definitely Spam = &SQLBlacklist
Move the Bayesian Databases and set-up permissions (skip this if you don't use bayes)

Edit /etc/MailScanner/spam.assassin.prefs.conf and set:

  • bayes_path /etc/MailScanner/bayes/bayes
  • bayes_file_mode 0660

Create the 'new' bayes directory, make the directory owned by the same group as the web server user and make the directory setgid:

    # mkdir /etc/MailScanner/bayes
    # chown root:apache /etc/MailScanner/bayes
    # chmod g+rws /etc/MailScanner/bayes

Copy the existing bayes databases and set the permissions:

    # cp /root/.spamassassin/bayes_* /etc/MailScanner/bayes
    # chown root:apache /etc/MailScanner/bayes/bayes_*
    # chmod g+rw /etc/MailScanner/bayes/bayes_*

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

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

and you should see something like:

    debug: using "/etc/MailScanner/spam.assassin.prefs.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 4.20-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.

Test the MailWatch interface

Point your browser to


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 'Tools/Links' menu and select 'Update SpamAssassin Rule Descriptions' and click 'Run Now'.

Update the GeoIP database

Make Sure you have allow_url_fopen = On in your php.ini set.

    mkdir yourwwwroot/mailscanner/temp
    chown (your www server user and group) yourwwwroot/mailscanner/temp
    chmod gu+wr yourwwwroot/mailscanner/temp

Click on the 'Tools/Links' menu and select 'Update GeoIP database' and click 'Run Now'.

Setup the Mail Queue watcher (optional)

You can get MailWatch to watch and display your sendmail or exim queue directories - all you need to do is copy mailq.php (from the root of the mailwatch tarball - not from the mailscanner directory - they are different!) to /usr/local/bin and set-up a cron-job to run it.

Edit mailq.php first to change the require line to point to the location of functions.php, then:

    # cp mailq.php /usr/local/bin
    # crontab -e
    0-59 * * * *    /usr/local/bin/mailq.php

Note: mailq.php re-creates all entries on each run, so for busy sites you will probably want to change this to run every 5 minutes or greater.

Setup the Sendmail Relay Log watcher (optional)

You can get MailWatch to watch your sendmail logs and store all message relay information which is then displayed on the 'Message Detail' page which helps debugging and makes it easy for a Helpdesk to actually see where a message was delivered to by the MTA and what the response back was (e.g. the remote queue id etc.).

    # cp tools/sendmail_relay.php /usr/local/bin
    # nohup /usr/local/bin/sendmail_relay.php 2>&1 > /dev/null &

FINISHED!! (Phew!)

Please send any errors or omissions to the mailing-list or directly to me.

Thanks! Steve.

– If you find MailWatch useful then consider buying something from my wishlist at - you can find my list using my e-mail address


mailwatch/documentation/install.txt · Last modified: 2014/03/15 16:27 by crees
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
Recent changes RSS feed Donate Powered by PHP Valid XHTML 1.0 Valid CSS Driven by DokuWiki Get 
MailWatch for MailScanner at Fast, secure and Free Open Source software downloads