The maiadbtool.pl script

The maiadbtool.pl script is a general-purpose utility script for manipulating the Maia database from the command-line, rather than from the web GUI. As such, it's something of a Swiss Army knife for Maia administrators who want to do things like add large batches of e-mail addresses or domains to Maia without having to do it one item at a time from a web page.

--add-address addr1,addr2,...      : add one or more user e-mail addresses
--add-addresses addr1,addr2,...    : same as --add-address
--delete-address addr1,addr2,...   : delete one or more user e-mail addresses
--del-address addr1,addr2,...      : same as --delete-address
--delete-addresses addr1,addr2,... : same as --delete-address
--del-addresses addr1,addr2,...    : same as --delete-address
--link-address addr1,addr2,...     : link one or more addresses to a user account
--link-addresses addr1,addr2,...   : same as --link-address
--link-account address             : address of user to whom addresses should be linked
--add-domain dom1,dom2,...         : add one or more domains
--add-domains dom1,dom2,...        : same as --add-domain
--delete-domain dom1,dom2,...      : delete one or more domains and all e-mail addresses in those domains
--del-domain dom1,dom2,...         : same as --delete-domain
--delete-domains dom1,dom2,...     : same as --delete-domain
--del-domains dom1,dom2,...        : same as --delete-domain
--add-from-file file               : add users and/or domains from a file
--delete-from-file file            : delete users and/or domains from a file
--del-from-file file               : same as --delete-from-file
--link-from-file file              : link addresses to user accounts from a file
--address-rewriting-type code      : address rewriting method [0..5] (see config.php)
--routing-domain domain            : routing domain (see config.php)
--auth-method method               : authentication method (see config.php)
--authentication-method method     : same as --auth-method
--clear-bayes                      : empty the Bayes database
--clear-awl                        : empty the AWL database
--expire-bayes                     : expire Bayes tokens
--prune-awl [min]                  : prune the AWL database, removing entries with less than [min] occurrences
--sa-learn path                    : path to your sa-learn script
--help                             : display this help text
--debug                            : display detailed debugging information
--quiet                            : display only error messages

The following settings in the /etc/maia.conf file affect how the process-quarantine.pl script behaves:

$sa_learn tells the script explicitly where your sa-learn script is located. Usually there's no need to specify this, as long as sa-learn is somewhere in your amavis/maia user's path.

# Location of your sa-learn script
$sa_learn = "/usr/bin/sa-learn";

$address_rewriting_type determines if and how email addresses are rewritten by your upstream MTA. This should be set to the same value found in your config.php script.

# Address rewriting type [0..5] (see config.php)
$address_rewriting_type = 0;

$routing_domain specifies the routing domain to append to rewritten email addresses. This should be set to the same value found in your config.php script.

# Routing domain (see config.php)
$routing_domain = '';

$auth_method tells the script which authentication method you're using. Valid values are "pop3", "imap", "ldap", "exchange", "sql", "internal", and "external". This should be set to the same value found in your config.php script.

# Authentication method (see config.php)
$auth_method = "internal";

Adding e-mail addresses

This script can be used to add new Maia user accounts and e-mail addresses, either one at a time, in small numbers, or in large batches, according to your needs. Whether you wish to add a new user account or just an e-mail address, it all begins the same way--with the creation of an e-mail address. When a new e-mail address is added, a new Maia user account is automatically created for it. If you want to link that address to a different account, you can thereafter use the --link-address feature to transfer the address to the other account.

Addresses can be added one at a time:

maiadbtool.pl --add-address larry@example.com

or as a comma-separated list on the command-line:

maiadbtool.pl --add-address larry@example.com,moe@example.com

or from a text file, with one address per line:

maiadbtool.pl --add-from-file /path/to/address-list.txt

Note: If the domain of an e-mail address is unknown to Maia, the domain will be automatically added, just as if you had used the --add-domain feature.

If you have not specified $address_rewriting_type, $routing_domain, or $auth_method in your maia.conf file, you can supply them on the command-line as arguments with the --add-address feature. e.g.

maiadbtool.pl --add-address larry@example.com --address-rewriting-type=0 --auth-method=pop3

Deleting e-mail addresses

You can use this script to delete one or more e-mail addresses as well. Deleting an e-mail address does not necessarily delete the user account that owns the address, however. If the user account owns no other e-mail addresses, the account will be deleted implicitly. If the account owns at least one other e-mail address however, it will remain intact.

Addresses can be deleted one at a time:

maiadbtool.pl --delete-address larry@example.com

or as a comma-separated list on the command-line:

maiadbtool.pl --delete-address larry@example.com,moe@example.com

or from a text file, with one address per line:

maiadbtool.pl --delete-from-file /path/to/address-list.txt

Adding domains

You can use this script to add domains to Maia as well. All domains added this way will inherit their initial settings from the system-default user (@.), so be sure that user's settings are the way you want them before adding your domains.

Domains can be added one at a time:

maiadbtool.pl --add-domain @example.com

or as a comma-separated list on the command-line:

maiadbtool.pl --add-domain example.com,example.net

or from a text file, with one domain per line:

maiadbtool.pl --add-from-file /path/to/domain-list.txt

Deleting domains

The script can delete one or more domains, as well. When a domain is deleted, all of the e-mail addresses in that domain are also deleted.

Domains can be deleted one at a time:

maiadbtool.pl --delete-domain example.com

or as a comma-separated list on the command-line:

maiadbtool.pl --delete-domain example.com,@example.net

or from a text file, with one domain per line:

maiadbtool.pl --delete-from-file /path/to/domain-list.txt

Linking e-mail addresses

The address-linking feature lets you link one or more e-mail addresses to a Maia account. The Maia account itself can be specified either by its username or by any of the e-mail addresses it already owns. If the addresses being linked don't already exist, they will be created implicitly.

maiadbtool.pl --link-account curly@example.com --link-address larry@example.com,moe@example.com

The batch-mode for address-linking allows you to perform linking on a much larger scale, with the associations read from a text file. Each line in the text file must start with the username or e-mail address of the account that should be linked to, followed by one or more addresses that should be linked to it, all separated by whitespace.

maiadbtool.pl --link-from-file /path/to/link-list.txt

Clearing the Bayes database

Should your Bayes database become so badly corrupted that you don't feel it would be practical to steer it back on course with some proper training, you can use this feature to wipe the slate clean and start fresh. Note that once you wipe the Bayes database, it won't be functional again until it has seen a minimum of 200 spam and 200 non-spam items, so in the short term your SpamAssassin scores may be a bit lower than usual.

maiadbtool.pl --clear-bayes

Expiring tokens from the Bayes database

If you've disabled SpamAssassin's auto-expiry mechanism (recommended), you'll want to schedule a cron job to expire Bayes tokens for you once per day at a convenient off-peak time. Note that SpamAssassin will refuse to expire tokens more frequently than once every 12 hours; once a day is generally sufficient.

maiadbtool.pl --expire-bayes

Clearing the Auto-Whitelist (AWL) database

This script can be used to wipe your AWL database clean, in the event it has been very badly corrupted by a lot of learning mistakes. If a lot of your legitimate senders (whose mail should be scored downward by the AWL) are receiving positive AWL scores, or conversely a lot of spam is arriving with negative AWL scores, you might want to wipe the AWL and start over. There's no point doing this until/unless you've figured out what caused the learning mistakes in the first place, however; otherwise you'll just end up in the same situation sooner or later.

maiadbtool.pl --clear-awl

Pruning the Auto-Whitelist database

Left to its own devices, the AWL database will just continue to grow, since SpamAssassin does not provide any mechanisms for expiring entries. Many of these entries will only appear in the AWL once--e.g. spam is not likely to be seen from a randomly-generated sender address more than once, so those one-off entries aren't useful for scoring purposes anyway. To keep your AWL database in good working order and prevent it from growing without bound, you can run this script to prune the one-off entries that have positive scores. Running this once a week is recommended.

maiadbtool.pl --prune-awl

By default, the script only deletes records that occur less than twice (i.e. items that appear at least twice are preserved). If you wish to supply a higher threshold, you can do so:

maiadbtool.pl --prune-awl 2