Frequently Asked Questions (FAQ)

How to resolve primary virus scanner (auto) error?

You may find you get an error like:

Unable to select a regular expression for your primary virus scanner (auto) - please see the examples in functions.php to create one.

This happens when you are using newer versions of MailScanner and have the auto setting turned on in your MailScanner.conf file. Edit the configuration and set the string for your virus scanners instead of using the auto setting like:

#Virus Scanners = auto
Virus Scanners = clamav

Why are messages quarantined again when I release them in MailWatch?

This is because you need to bypass certain checks for messages from to allow the released messages to pass through MailScanner without being quarantined again.

Set the following in /etc/Mailscanner/Mailscanner.conf:

Filename Rules = %etc-dir%/filename.rules
Filetype Rules = %etc-dir%/filetype.rules
Dangerous Content Scanning = %rules-dir%/content.scanning.rules
Is Definitely Not Spam = %rules-dir%/spam.whitelist.rules

Then the following files should be set-up as follows:


From:       /etc/MailScanner/filename.rules.allowall.conf
FromOrTo:      default         /etc/MailScanner/filename.rules.conf


From:       /etc/MailScanner/filetype.rules.allowall.conf
FromOrTo:      default         /etc/MailScanner/filetype.rules.conf

Edit the following files in /etc/MailScanner/rules:


From:       no
FromOrTo:       default        yes


From:       yes
FromOrTo:       default        no

Create the following files in /etc/MailScanner:


allow   .*      -       -


allow   .*      -       -

Can I use wildcards when using the Blacklist/Whitelist (SQLBlackWhiteList)?

No - the Blacklist/Whitelist work on an exact first match only basis.

For Example: if the message is to and from and the connecting server address is, the checks are performed in the following order and the first to match returns true (the message is either whitelist or blacklisted depending on the lookup being performed):

To From default default

I can’t get MailWatch to ‘see’ my Quarantined e-mail

This is almost always caused by either setting MailScanner to quarantine messages as Queue files or because the Web Server cannot access the quarantine directory or the files within.

Okay - here’s a list of things that you need to check:

  • SELinux is either disabled or in permissive mode (until someone would like to help add SELinux support to MailScanner & MailWatch)
  • Make sure that ‘Quarantine Whole Message As Queue Files = no’ in MailScanner.conf.
  • Make sure that ‘Quarantine Group = ' and 'Quarantine Permissions = 0660' in MailScanner.conf.
  • Make sure that ‘Quarantine Dir’ and all subdirectories have the correct permissions (e.g. drwxrwx— and is owned by the same group as ‘Quarantine Group’.)
  • Make sure that no part of ‘Quarantine Dir’ is a symlink. Apache typically won’t follow symlinks.
  • Check your Apache error log for any obvious errors.

MailWatch can also use the quarantine in two ways:

  • Look for the files on the filesystem (original pre-1.0.3 behaviour and slower)
  • Store the quarantined state in an indexed field in the database (faster)

This behaviour is governed by the setting QUARANTINE_USE_FLAG in conf.php – if true then the new behaviour is used.

To use the new behaviour correctly – you must disable the MailScanner clean.quarantine script if it is enabled and use the quarantine_maint.php script supplied with MailWatch. This is used to reconcile the quarantine with the database and to remove old files from the quarantine and to update the database to reflect the changes.

MailScanner won’t log to my MailWatch database

This is usually because the ‘Storable’ or other Perl module is missing. Run the following command:

perl -MStorable -MDBI -MDBD::mysql -e 'print "OK\n";'

If you get anything other than ‘OK’ returned, then you are missing one of the Perl modules and need to install it.

I get a fatal error “Cannot redeclare _PEAR_call_destructors()”

MailWatch uses some modified PEAR libraries which conflict with system installed PEAR packages, do not install these pear libraries with your distribution package manager:

  • PEAR
  • Mail
  • Mail_mime
  • Mail_mimeDecode
  • Pager
  • Net_Smtp
  • Net_Socket

Remove them if present

I get “DBD::mysql::st execute failed: Incorrect string value” error in logs

If you see perl error in log that looks like the following

May 6 14:13:58 mailsecurity MailScanner[64217]: Could not use Custom Function code MailScanner::CustomConfig::InitMailWatchLogging, it could not be "eval"ed. Make sure the module is correct with perl -wc (Error: DBD::mysql::st execute failed: Incorrect string value: '\xF0\x9F\x92\x9F O...' for column 'subject' at row 1 at /usr/share/MailScanner/perl/custom/ line 189, line 76.

it is highly probable that your version of DBD::mysql is outdated and doesn’t support full UTF-8 encoding of email subject, please follow upgrading DBD::mysql instructions to fix this error.

PHP Notices for session_start()

If see messages like this in your web server log Notice: session_start(): ps_files_cleanup_dir: opendir(/var/lib/php5/sessions) failed: Permission denied (13) in /var/www/html/mailscanner/login.php on line 37 you probably have defined a separated session.save_path for your in the VirtualHost of your apache webserver where your mailwatch instance runs in.

To fix this you have to make sure that the user your webserver is running at has write permissions for that folder (here /var/lib/php5/sessions).

I get “XML-RPC Error: Client is not authorized to connect" when trying to use RPC calls

If want to use RPC you have to make sure that all communicating servers are mentioned in RPC_ALLOWED_CLIENTS in the conf.php files. Eg. if you have server1 ( which should be able to make RPC calls to server2 ( you must have this in the conf.php on both servers: define('RPC_ALLOWED_CLIENTS', '');

If you want to use hostnames instead of ip addresses you have to make sure that that hostname is also set as ServerAlias in your WebServer/VirtualHost config.

Apache access permissions

To apply restrictive access permissions for files in the web folder you should set AllowOverride Options AuthConfig in your virtualhost config so that the .htaccess files can be applied. In the default .htaccess files shipped with MailWatch contain the options for apache 2.4 config. If you have apache 2.2 you need to comment out Require all denied (change it to #Require all denied) and remove the # in the lines Order Allow,Deny and Deny from all. If you don’t apply to this you will get an error like the following in your apache log file:

[...]/.htaccess: Invalid command 'Order', perhaps misspelled or defined by a module not included in the server configuration
[...]/.htaccess: Invalid command 'Require', perhaps misspelled or defined by a module not included in the server configuration

The following files need to be adjusted:

  • mailscanner/temp/.htaccess
  • mailscanner/lib/.htaccess
  • mailscanner/js/Chart.js/.htaccess
  • mailscanner/.htaccess

A license key from is needed to download GeoLite2 data

MaxMind now requires a free license key to obtain GeoLite2 data.

Visit to create an account and generate a license key.
MaxMind will ask questions to generate a key, any choice will work. Once you have generated a key, place the key in conf.php for MAXMIND_LICENSE_KEY.