Maintenance Scripts

Maia Mailguard is mostly PHP-based, but it does rely on a few Perl scripts to run on the machine(s) where amavisd and SpamAssassin are installed.

Note: Before using any of these scripts, be sure to edit them to set a handful of configuration options at the beginning of each Perl script. No such edits are required for the PHP scripts.

SCRIPT: configtest.pl and configtest.php

The configtest.pl script checks to make sure that all of the prerequisite utilities and Perl modules have been installed on the machine, and that their version numbers are recent enough to be usable. It also tests your database DSN, to ensure that the Maia database can be reached by the rest of the Perl scripts and amavisd.

It should be run on every machine that will be hosting amavisd and SpamAssassin, and it's a convenient way to verify that everything is in order during the installation process.

The configtest.php script (found in the php/admin subdirectory) performs similar tests on your web server, verifying that you have the necessary PHP and PEAR prerequisites in place to host a Maia Mailguard installation. Load this page in a web browser to receive a summary diagnostic. If the script determines that you're missing something, it will also indicate whether that item is optional or mandatory, so you'll know whether you absolutely need to install the missing component before proceeding.

SCRIPT: upgrade.php

The upgrade.php script (in the php/admin subdirectory) is used to upgrade a Maia Mailguard RC5 installation to the latest 1.0.x version. More specifically, it upgrades the database schema to add new tables and columns required by the newer version. Note that it was not designed to upgrade databases from earlier versions than RC5, so results are not guaranteed for pre-RC5 databases.

As with any upgrade, you should back up your existing database before running this script. Its changes should be merely additive in nature, but in the event something goes wrong, you won't want to have lost your existing data irretrievably, so take a few minutes to do a proper backup first.

Once you have upgraded your database successfully and have Maia Mailguard up and running, you should remove the php/admin subdirectory and all of its contents as a security precaution, so that these scripts cannot be exploited by intruders.

SCRIPT: process-quarantine.pl and process-quarantine-sub.pl

When users "confirm" spam or ham using Maia Mailguard, the mail items are marked appropriately as such to await processing by this script.

With confirmed spam and ham distinguished in this way, you can use this script to post-process these items at regular intervals (using a scheduler like cron). At the very least you can use this to train the site-wide Bayes engine with specific examples of known spam and known ham. Optionally, if you have Razor2, DCC, and/or Pyzor configured in SpamAssassin, you can use this script to also report spam to these networks. Note that you must configure Razor2/DCC/Pyzor specifically for reporting, as these services often require reporters to be registered with them. See the Razor2/DCC/Pyzor documentation for more details about reporting spam.

When the script is done training the Bayes engine and reporting the spam items, the spam and ham items are deleted, which helps to keep the database from getting filled up.

This script should be scheduled to run on an hourly basis, to make sure that learning and reporting takes place frequently, since these are important steps in maintaining/improving the effectiveness of your spam filter.

As of Maia 1.0, the process-quarantine.pl script is now assisted by a worker script called process-quarantine-sub.pl. The main script calls the worker script in a loop until there are no further items left to be processed. To invoke the new process-quarantine.pl script, you must supply some command-line arguments:

--ham-only  : only process confirmed ham (non-spam) items
--spam-only : only process confirmed spam items
--learn     : train the Bayes database 
--report    : report spam to Razor2/DCC/Pyzor/SpamCop
--limit=n   : process items in batches of n at a time (default=5)
--help      : display this help text
--debug     : display detailed debugging information
--quiet     : display only error messages

Learning and reporting are separate actions, but you can combine both, of course, e.g.

process-quarantine.pl --learn --report

The --ham-only and --spam-only options allow you to process just one type of item in a given run, but for most purposes you should only need to worry about the --learn and --report options. Note that if you don't specify either --learn or --report, the script will simply delete the items it processes, which can be useful on occasion is you just want to purge your database without training your Bayes database or reporting spam.

SCRIPT: expire-quarantine-cache.pl

Maia Mailguard system encourages the end-users to manage their own quarantine areas and ham caches on a regular basis, to make sure no legitimate mail has been held up in quarantine, and so on. That said, not all users will be diligent about checking their quarantine areas in a timely manner, and if left untended, this can result in a lot of wasted storage space.

By setting the expiry period for quarantined items and cached ham from Maia Mailguard's System Configuration page, and running this script from a daily cron job, you can force the expiry of quarantined items that have not been dealt with in a certain amount of time, to make sure they don't sit in your database indefinitely.

Schedule this script to run once per day, preferably at an off-peak time. It will check the ages of all unconfirmed spam and ham in the quarantine/cache, and delete items that are older than your specified thresholds. The thresholds themselves are set by the superadministrator from the System Configuration page.

SCRIPT: send-quarantine-reminders.pl

If you set a reminder threshold count or size from Maia Mailguard's System Configuration page, you'll want to add this script to your cron schedule to ensure that reminder e-mails are sent out to users at regular intervals (e.g. once per week) when the number of items in their quarantine area exceeds this threshold count, or when the total size of the items in their quarantine area exceeds the threshold size. Users can individually opt out of these reminders, of course, and for some types of users (e.g. system accounts, spam-traps, etc.) you'll want to disable reminder notices, but for most regular users this setting should probably be enabled by default, to ensure that users are aware of Maia Mailguard and the status of their quarantine area.

SCRIPT: send-quarantine-digests.pl

The send-quarantine-digests.pl script allows you to send out an e-mail digest to your users, containing an HTML-formatted list of the contents of their Maia Mailguard quarantines, generated from a template. Users can then release items as necessary and confirm the status of the remaining items, all from within their e-mail clients, without having to login to the Maia web interface.

Each user can specify his or her own digest interval (in minutes) from within the Maia Mailguard web interface, and of course enable/disable the feature as desired. The administrator must be sure to run this script from a cron job at whatever minimum interval makes sense for the system's load. In a low-volume environment, it might be practical to run this script from a cron job every minute, offering users an effective granularity of one minute. It may be more practical in most environments to run this script every five minutes or ten minutes, though of course this will limit how frequently the users can receive their digests, obviously. A granularity of five minutes should probably be more than sufficient for most sites, however.

SCRIPT: load-sa-rules.pl

This script scans certain specified directories on your server, looking for SpamAssassin rules to add to the Maia Mailguard database. If it finds a rule it doesn't know about yet, the rule gets added to the database. If it finds a known rule, it updates the rule's score as necessary, in the event it may have changed. You should run this script as a "finishing step" every time you update your SpamAssassin rules, to ensure that Maia Mailguard always has the most up-to-date set of SpamAssassin rules and scores in its database.

In particular, if you use the rules_du_jour script to auto-update your SpamAssassin rules, you must remember to run the load-sa-rules.pl script afterward. The easiest way to do this is to chain this command to the SA_RESTART command in your my_rules_du_jour script:

# Command used to restart amavisd
SA_RESTART="/var/amavisd/maia/scripts/load-sa-rules.pl;/etc/init.d/amavisd restart";

SCRIPT: stats-snapshot.pl

This script takes a "snapshot" of your current Maia stats table, so that it can be stored and referenced later by scripts and processes that generate interval-based graphical charts. The data is recorded in the maia_stats_history table, with one row per hour, one row per day, one row per month, and one row per year. This script needs to be scheduled to run at the beginning of every hour.

SCRIPT: generate-key.pl

If you want to take advantage of Maia's Blowfish encryption features, you'll need to use this script to generate your site's encryption key. This is a one-time task, which you can do by running this script and redirecting the output to a file. Be sure to create a backup copy of the key file you generate, and keep it in a safe place in case you lose the original.