Installing Maia Mailguard

1. Create a user and group for amavisd to run under, if necessary

The amavisd-maia process should be running under its own userid and group, as specified in your /etc/amavisd.conf file as:

$daemon_user = 'amavis';
$daemon_group = 'amavis';

Throughout this documentation we'll be assuming the username you're using for this purpose is <tt>amavis</tt>, and the group name is <tt>amavis</tt>; substitute your own values if you've chosen something different.

If you haven't already created this user and group, do so now, making sure to set a password for this user:

[root]# useradd amavis
[root]# passwd amavis
[root]# groupadd amavis

2. Create a new database for Maia Mailguard

Maia Mailguard supports a number of SQL databases. The documentationmay refer in places to MySQL, since this is a common database, but bearin mind that you should be able to get Maia Mailguard working withPostgreSQL as well.

To create a new database with MySQL, type the following (you canomit the "-p" if your MySQL installation allows root to login without apassword, but really, you should always have a password, especially for root!):

[root]# mysql -u root -p mysql

mysql> CREATE DATABASE maia;

The procedure for creating a database will vary from one database toanother; consult your database documentation to find the right way todo this for your database.

To create and stock the necessary database tables, use the definitions in the maia-mysql.sql file, i.e.:

[root]# mysql -u root -p maia < maia-mysql.sql

The SQL syntax in this file is designed for MySQL, and may need tobe modified slightly to accommodate other databases (e.g. your databasemay have different keywords for <tt>unsigned</tt> or <tt>auto_increment</tt>). The maia-pgsql.sql file contains the table definitions for use with PostgreSQL, for example.

Now you need to give the amavis user limited access to this database (in place of <tt>passwd</tt> be sure to use the password you set for the <tt>amavis</tt> user):

[root]# mysql -u root -p maia

mysql> GRANT CREATE, DROP, ALTER, SELECT, INSERT, UPDATE, DELETE ON maia.* TO amavis@localhost IDENTIFIED BY 'passwd';

Again, how you grant privileges to a database user will vary frompackage to package. Consult your database documentation for morespecific details.

If you're using MySQL, you'll also need to add (or increase) the <tt>max_allowed_packet</tt>setting in your my.cnf file. This setting determines the size of thelargest mail item you'll be able to process with Maia, so make sure toset this value large enough to accommodate your needs. (You'll be ableto tell Maia later on what to do with mail larger than this.) Note thatin MySQL version prior to 4.0.1, the maximum packet size is 16M; laterversions can accept packets as large as 1G.

MySQL versions prior to 4.0.2:
[mysql]
set-variable = max_allowed_packet=5M

MySQL 4.0.2 or later:
[mysql]
max_allowed_packet=5M

3. Install the Maintenance Scripts and Templates

Maia Mailguard comes with a collection of Perl scripts in thescripts subdirectory. Install these files in a place that your webserver can't access (i.e. outside of your document root), so that theycan't be triggered by web visitors. A good place for these is in asubdirectory of your amavisd directory, e.g. /var/amavisd/maia. Createtwo subdirectories there, one for scripts, the other for templates:

[root]# mkdir /var/amavisd/maia
[root]# mkdir /var/amavisd/maia/scripts
[root]# mkdir /var/amavisd/maia/templates

Now copy the contents of Maia's scripts subdirectory into/var/amavisd/maia/scripts, and put the contents of the templatessubdirectory into /var/amavisd/maia/templates.

Set the ownership of all of these files to the <tt>amavis</tt> user and group, and tighten up the permissions on these files so that they're accessible only to the <tt>amavis</tt> user:

[root]# chown -R amavis /var/amavisd/maia
[root]# chgrp -R amavis /var/amavisd/maia
[root]# chmod 640 /var/amavisd/maia/templates/*.tpl
[root]# chmod 750 /var/amavisd/maia/scripts/*.pl

Before any of the supplied scripts can be used, you need to copy the maia.conf.dist file to /etc/maia.confand edit it to provide some basic information about how to connect toyour database, and how the scripts themselves should behave. By storingthis information in the /etc/maia.conf file, you won't need to supply that information as command-line arguments when you run the scripts themselves.

[root]# cp maia.conf.dist /etc/maia.conf
[root]# chown amavis /etc/maia.conf
[root]# chgrp amavis /etc/maia.conf
[root]# chmod 640 /etc/maia.conf

The most important settings in the /etc/maia.conf file are the ones that determine how the scripts should connect to your Maia database.

For MySQL:

# Configure your Maia database DSN here
$dsn = "DBI:mysql:maia:localhost:3306";

# Your Maia database user's login name
$username = "amavis";

# Your Maia database user's password
$password = "passwd";

For PostgreSQL:

# Configure your Maia database DSN here
$dsn = "DBI:Pg:dbname=maia;host=localhost;port=5432";

# Your Maia database user's login name
$username = "amavis";

# Your Maia database user's password
$password = "passwd";

You'll also want to tell Maia where you installed the maintenance scripts:

# The directory where Maia's Perl scripts can be found.
$script_dir = "/var/amavisd/maia/scripts";

That's all you need to configure for now; you can read the separate documentation for the maintenance scripts later, before you use them.

4. Test your amavisd-maia and SpamAssassin configuration

SpamAssassinand amavisd-maia both rely on a number of Perl modules and systemutilities to function properly. Before going any further, you can usethe configtest.plscript to verify that you have all of the necessary modules andutilities installed, and that their versions are new enough to beuseful. You'll want to run this script on all of the machines where yourun SpamAssassin and amavisd-maia.

If the script tells you that you need to upgrade or install a Perlmodule or utility, do so now, and then re-run the script to make sure.The output should look something like this:

MAIA MAILGUARD CONFIGURATION TEST

This script checks for the presence of applications and Perl modules
required by amavisd-maia, SpamAssassin, and Maia Mailguard's maintenance
scripts. Version numbers are also checked, and if a newer version of
a component is recommended, you should consider upgrading to at least
the minimum recommended version.

If you have already configured your Maia Mailguard database, the script
will also test the connection to that database.

Remember also to run the configtest.php script on your web server to
perform similar tests of your web, PHP, and PEAR environment.

Application/Module Version Status
========================================================================
Perl : 5.8.3 : OK
file(1) : 4.16 : OK
Archive::Tar : 1.10 : OK
Archive::Zip : 1.16 : OK
BerkeleyDB : 0.26 : OK
Compress::Zlib : 1.41 : OK
Convert::TNEF : 0.17 : OK
Convert::UUlib : 1.06 : OK
Crypt::Blowfish : 2.09 : OK
Crypt::CBC : 2.12 : OK
Crypt::OpenSSL::RSA : 0.22 : OK
Data::UUID : 0.13 : OK
DB_File : 1.810 : OK
DBD::mysql : 3.0002 : OK
DBD::Pg : 1.31 : OK
DBI : 1.50 : OK
Digest::MD5 : 2.33 : OK
Digest::SHA1 : 2.07 : OK
File::Spec : 3.01 : OK
HTML::Parser : 3.35 : OK
HTTP::Date : 1.46 : OK
IO::Stringy : 2.109 : OK
IO::Zlib : 1.03 : OK
IP::Country : 2.20 : OK
LWP::UserAgent : 2.032 : OK
Mail::Address : 1.64 : OK
Mail::DomainKeys : 0.80 : OK
Mail::Internet : 1.64 : OK
Mail::SpamAssassin : 3.1.1 : OK
Mail::SPF::Query : 1.999.1 : OK
MIME::Base64 : 3.05 : OK
MIME::Parser : 5.420 : OK
MIME::QuotedPrint : 3.03 : OK
Net::CIDR::Lite : 0.15 : OK
Net::DNS : 0.57 : OK
Net::Server : 0.93 : OK
Net::SMTP : 2.29 : OK
Pod::Usage : 1.16 : OK
Template : 2.14 : OK
Time::HiRes : 1.61 : OK
Unix::Syslog : 0.99 : OK
URI : 1.31 : OK

Database DSN test : PASSED

If you're looking for a starting point for configuring amavisd, a sample amavisd.conf file is provided with the Maia Mailguard distribution. Similarly, a sample local.cf file is provided for SpamAssassin.

5. Load your SpamAssassin rules

Maia Mailguard needs to index all of the SpamAssassinrules you have installed on your system, so that these rules, theirdescriptions and scores can be loaded into a database table. To dothis, use one of the scripts in the scripts subdirectory called load-sa-rules.pl. Run it with the <tt>--debug</tt> flag the first time, to make sure it's working properly.

[root]# ./load-sa-rules.pl --debug

If all goes well, this script will scan your system for *.cf anduser_prefs files, reading any rule names, descriptions and scores itfinds and storing them in the Maia Mailguard database.

You can safely run this script anytime you add new SpamAssassin rules or update your SpamAssassinrule files with new scores. The script will not add the same ruletwice, but it will update the score value of a rule that it has seenbefore. If you use a scheduled job to fetch updated versions of popularSpamAssassin rule sets, e.g. RulesDuJour and/or sa-update, add this script to the end of your update job to make sure the changes are picked up by Maia Mailguard.

If you use the RulesDuJour script to automatically update your third-party SpamAssassinrules for you (highly recommended), you'll want to modify theSA_RESTART setting in the /etc/rulesdujour/config file to ensure thatit runs load-sa-rules.pl after it makes any rule changes:

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

If you use the sa-update script to update your core SpamAssassin rules (also highly recommended), you'll want to chain your commands so that load-sa-rules.pl gets called whenever a rules update takes places:

sa-update && /var/amavisd/maia/scripts/load-sa-rules.pl && /etc/init.d/amavisd restart

6. Install the PHP scripts

Decide where you want to install the PHP scripts. This should be asubdirectory somewhere within your web tree. For this example we'llassume a directory called <tt>maia</tt>,just off the document root of the web server (i.e. the relative path tothe folder would then be /mail, accessible to the outside world ashttp://www.example.com/maia). Copy the contents of the /phpsubdirectory of the Maia Mailguard distribution to this folder.

There should be several subdirectories beneath the directory withyour PHP scripts. Your directory tree in this example should looksomething like this:

<document_root>/maia


<document_root>/maia/admin

configtest and upgrade scripts

<document_root>/maia/images

various global images

<document_root>/maia/libs

include path for Smarty

<document_root>/maia/locale

language packs go here

<document_root>/maia/overlib

a popup library used for toolkits

<document_root>/maia/themes

HTML themes

Alternately, if you're packaging Maia Mailguard for redistribution,you may wish to install the PHP scripts in a standard location outsidethe web document tree, e.g. /usr/local/maia/php or somesuch. If you doso however, you'll also need to make that subdirectory visible to yourweb server and give it script execution permissions (e.g. a<Directory> entry in your httpd.conf file if you use apache).

The web server user needs to be able to write to the themedirectories in order to cache the pages. The best way to ensure thatyou get the permissions right is to follow these instructions.

7. Install the Smarty Template Engine

Download and install the Smarty template engine.You can install it system-wide (so that other applications on the webserver can make use of it as well), or simply for Maia's purposes:

For a system-wide installation:

cp -r {path_to_Smarty_files}/lib {php_include_path}/Smarty

For a Maia-only installation:

cp -r {path_to_Smarty_files}/lib {document_root}/maia/libs/Smarty

8. Configure Maia Mailguard: Database and Authentication

The config.php file contains a few basic configuration settings thatmust be adjusted for your site before you can configure the rest ofMaia Mailguard's settings. In particular, the language defaults,database connection information and user authentication parameters mustbe hard-coded here.

Language Defaults

<tt>$default_display_language</tt> is set by default to "en" (English).If you have other language files installed, you can change this settingto the ISO-639 two-letter language code (e.g. en, fr, ja, de, etc.)that corresponds to the language you wish to use. Note that users canoverride this on an individual basis, selecting from any installedlanguage. This is simply a default to use if no other language has beenselected.

<tt>$default_charset</tt> lets you set the default character set touse, if no other character set has been specified by the user. Thedefault of "ISO-8859-1" is fine for most Western languages.

Database Connection

<tt>$maia_sql_dsn</tt> is the database connection string that thePEAR::DB functions will use to try to connect to the Maia Mailguarddatabase. The supported database types include:

PEAR::DB Type

Database

<tt>mysql</tt>

MySQL

<tt>pgsql</tt>

PostgreSQL

The connection string syntax for a TCP-based connection generally looks like this:

$maia_sql_dsn = "dbtype://dbuser:passwd@tcp(hostname:port)/dbname";

In our case, with database type "mysql", database name "maia" anduser "amavis", a host of "localhost" and the standard MySQL port(3306), the connection string should end up looking something likethis:

$maia_sql_dsn = "mysql://amavis:passwd@tcp(localhost:3306)/maia";

A PostgreSQL example:

$maia_sql_dsn = "pgsql://amavis:passwd@tcp(localhost:5432)/maia";

There are many more variations on the connection string if thisdoesn't work for you, including options to use Unix sockets instead ofTCP, etc.. The syntax reference may help you if you get stuck.

Default Protection Levels

The <tt>$protection</tt> setting lets you define the defaultpolicy settings for each of four protection levels: "off", "low","medium", and "high". While users can manually tweak their filtersettings if they wish, many users prefer to useadministrator-recommended settings instead.

A policy array is a combination of 16 settings (from left to right):

Setting

amavisd-new equivalent

Value range

Pass viruses through?

<tt>virus_lover</tt>

'Y' or 'N'

Pass spam through?

<tt>spam_lover</tt>

'Y' or 'N'

Pass banned files through?

<tt>banned_files_lover</tt>

'Y' or 'N'

Pass mail with invalid headers through?

<tt>bad_header_lover</tt>

'Y' or 'N'

Disable virus scanning?

<tt>bypass_virus_checks</tt>

'Y' or 'N'

Disable spam checking?

<tt>bypass_spam_checks</tt>

'Y' or 'N'

Disable banned files checking?

<tt>bypass_banned_checks</tt>

'Y' or 'N'

Disable invalid header checking?

<tt>bypass_header_checks</tt>

'Y' or 'N'

Discard viruses?

<tt>discard_viruses</tt>

'Y' or 'N'

Discard spam?

<tt>discard_spam</tt>

'Y' or 'N'

Discard banned files?

<tt>discard_banned_files</tt>

'Y' or 'N'

Discard invalid mail headers?

<tt>discard_bad_headers</tt>

'Y' or 'N'

Add a prefix to spam subjects?

<tt>spam_modifies_subj</tt>

'Y' or 'N'

Add spam score headers when score is >=

<tt>spam_tag_level</tt>

-999.9 to 999.9

Consider mail spam when score is >=

<tt>spam_tag2_level</tt>

-999.9 to 999.9

Quarantine or discard spam when score is >=

<tt>spam_kill_level</tt>

-999.9 to 999.9

The initial defaults for the four protection levels are as follows:

The 'off' level offers no protection at all. All scanning isdisabled, so the filter is effectively transparent, letting everythingthrough:

'off' => array ('Y','Y','Y','Y','Y','Y','Y','Y','N','N','N','N','N','999','999','999'),

At the 'low' protection setting, only virus scanning is performed:

'low' => array ('N','Y','Y','Y','N','Y','Y','Y','N','N','N','N','N','999','999','999'),

The 'medium' protection setting adds spam scoring headers to themail when it scores 5.0 or higher, but does not quarantine or discardit. Banned file attachments and mail with invalid headers are passedthrough:

'medium' => array ('N','N','Y','Y','N','N','Y','Y','N','N','N','N','Y','5','999','999'),

The 'high' protection setting adds spam scoring headers to the mailwhen it scores 1.0 or higher, and quarantines spam that scores 5.0 orhigher, along with viruses, banned file attachments, and mail withinvalid headers:

'high' => array ('N','N','N','N','N','N','N','N','N','N','N','N','N','1','5','5')

These defaults, of course, are just suggestions. Feel free tointerpret 'low', 'medium', and 'high' in whatever way makes sense foryour organization, and adjust the settings to match.

Authentication

<tt>$auth_method</tt> determines which authentication method MaiaMailguard uses to verify the login credentials of its users. Thecurrently available options are:

<tt>$auth_method</tt>

Server Type

<tt>pop3</tt>

POP3 server

<tt>imap</tt>

IMAP server

<tt>ldap</tt>

LDAP server

<tt>exchange</tt>

Microsoft Exchange Server (experimental)

<tt>sql</tt>

SQL database server

<tt>internal</tt>

Internal SQL

<tt>external</tt>

External script or application

<tt>$address_rewriting_type</tt> and <tt>$routing_domain</tt> allow youto compensate for any rewriting that your upstream mail server performson e-mail addresses. To learn more about this issue and how toconfigure these settings (if necessary), see Virtual Hosts, Aliases, and E-mail Addresses.

Authenticating with a POP3 server

POP3 support is provided by the PEAR::Net_POP3 module. If you need SSL support, set <tt>$auth_pop3_port</tt> to 995 and prefix "ssl://" to <tt>$auth_pop3_host</tt>.

Authenticating with an IMAP server

IMAP support is provided by the PEAR::Net_IMAP module. If you need SSL support, set <tt>$auth_imap_port</tt> to 993 and prefix "ssl://" to <tt>$auth_imap_host</tt>.

Authenticating with an LDAP server

LDAP authentication is provided by client libraries from the OpenLDAP project, or the University of Michigan's ldap-3.3 package. One of these must be downloaded, compiled, and installed, and PHP must be rebuilt with the <tt>--with-ldap=/path/to/ldap</tt> flag.

<tt>$auth_ldap_server</tt> is the hostname or IP address of the LDAP server you want to authenticate with.

<tt>$auth_ldap_password</tt> is the password your LDAP server requiresin order to answer queries. This is not the password of the user youwant to authenticate.

<tt>$auth_ldap_query</tt> is the LDAP authentication query. The %%USER%% placeholder will be replaced with the username of the user to be authenticated.

<tt>$auth_ldap_bind_dn</tt> is the LDAP distinguished name for binding purposes, typically your organization's name and domain name.

<tt>$auth_ldap_base_dn</tt> is the base LDAP distinguished name, typically your domain name.

<tt>$auth_ldap_attribute</tt> is the name of the query attribute that will return the e-mail address associated with the user's LDAP account.

Authenticating with a Microsoft Exchange Server

Modern versions of Exchange Server are IMAP-compliant, and shouldwork fine using IMAP authentication, except that an additional "NTDomain" parameter may be required. See the IMAP section above for moreinformation about available option flags.

<tt>$auth_exchange_nt_domain</tt> is the default NT domain to use, if the user leaves the domain field empty.

<tt>$auth_exchange_only_one_domain</tt> can be set to true if all ofyour users are part of the same NT domain. If this is the case, there'sno need to prompt for a domain, the value in <tt>$auth_exchange_nt_domain</tt> will always be used.

<tt>$auth_exchange_params</tt> is essentially an IMAP connection string (see the IMAP section above), but two additional flags are available as placeholders:

Flag

Meaning

/%%NTDOMAIN%%

user-supplied NT domain, or <tt>$auth_exchange_nt_domain</tt>

/%%USER%%

Username

Authentication with an SQL database server

SQL authentication uses the Pear::DB library to look up a username andpassword against a database table, to return an e-mail address for theuser, if successful. The password may be stored in plain text, orhashed via crypt() or MD5.

<tt>$auth_sql_dsn</tt> is the database connection string to be used toaccess the authentication database. This may be a different databasefrom the one Maia Mailguard uses, however the connection string followsthe same format.

<tt>$auth_sql_table</tt> is the name of the table that contains the user's authentication information.

<tt>$auth_sql_username_column</tt> is the name of the column that contains the user's username.

<tt>$auth_sql_password_column</tt> is the name of the column that contains the user's password.

<tt>$auth_sql_email_column</tt> is the name of the column that contains the user's e-mail address.

<tt>$auth_sql_password_type</tt> indicates the way the user's password is encrypted in the database:

<tt>$auth_sql_password_type</tt>

Encryption Type

<tt>plaintext</tt>

No encryption

<tt>md5</tt>

MD5 hash

<tt>crypt</tt>

crypt() hash

Authenticating with Maia's Internal SQL Database

If you want Maia Mailguard to handle its own user database, rather than authenticate against an external source, select the <tt>internal</tt> method. With this method, Maia stores usernames and passwords in its own database.

When new accounts are created, Maia automatically sends the new useran e-mail containing a temporary username and password, which she canchange once she logs in (and at any time thereafter).

This authentication method is handy for situations where the otherexternal authentication methods would be impractical, such as hostingmail filtering services for other companies downstream, where therewould otherwise be many different sources to authenticate against.

Authenticating against an External Mechanism

If you have an external application you'd prefer to use to authenticate Maia users, you can specify it via the <tt>$auth_external</tt> setting. This application should accept a username and password on the command line, and return 0 if the login succeeds.

9. Test your PHP and database configuration

At this point, you'll want to verify that your web server has itsPHP correctly compiled, all the necessary PEAR modules installed, andthe database DSN correctly configured in config.php. You can do this byloading the admin/configtest.php page in your browser.

This script will verify that the prerequisites are properly installedon your web server, and that PHP scripts can successfully communicatewith your database server. It will point out any missing components oroutdated version numbers and offer some advice for fixing the problem.Fix any problems that get highlighted at this stage and reload thescript to verify that they've been properly fixed before proceeding.

10. Install amavisd-maia

The amavisd-maia file in the Maia Mailguard distribution is aspecially-patched version of amavisd-new 2.2.1. If you have used aprevious version of Maia Mailguard, you will be pleased to note thatpatching is no longer required. The patch itself (amavisd-maia.patch)for amavisd-new 2.2.1 is still provided in this distribution, but onlyfor reference purposes.

Install the amavisd-maia file wherever you'd typically install system binaries (e.g. /usr/sbin, /usr/local/sbin, etc.):

[root]# cp amavisd-maia /usr/local/sbin/
[root]# chown root /usr/local/sbin/amavisd-maia
[root]# chmod 755 /usr/local/sbin/amavisd-maia

You may also wish to create a symbolic link to this file, so thatany existing scripts looking for 'amavisd' can find it properly:

[root]# ln -s /usr/local/sbin/amavisd-maia /usr/local/sbin/amavisd

11. Generate your site's encryption key (optional)

Maia Mailguard can use strong encryption to protect the contents ofthe e-mail that it quarantines/caches, as a safeguard against pryingeyes with database access. It uses the Blowfish algorithm with a56-byte (448-bit) key, and chained-block cipher (CBC) mode to dotwo-way encryption of stored mail. This encryption is completelytransparent to the users, and does not require them to install anyspecial software. All encrypting and decrypting is done by MaiaMailguard.

To take advantage of this encryption feature, you first need to generate a random key for your site. The generate-key.pl script can do this for you, just redirect its output to a file:

[root]# generate-key.pl > /var/amavisd/blowfish.key

Put the key file in your amavisd directory, and be sure to keepanother copy of it in a safe place, preferably on another machineoffsite, and/or a backup disk/CD. If you suffer a disk crash and loseyour key file, you'll need this backup to be able to recover theencrypted contents of your Maia database.

You'll also need to copy this key file to your web server, so thatMaia can use it to properly decrypt the stored mail. You can put itanywhere you like on the web server, as long as you tell Maia where itis (using the System Configuration page).

You can safely enable encryption at any time, even after you'vealready got mail in your database. Maia is smart enough to detectencrypted vs. unencrypted mail, so if your database contains a mixtureof both types, it won't cause any problems.

12. Configure amavisd-maia

Install the amavisd.conffile from the Maia Mailguard distribution into /etc, and edit this fileto configure it for your installation, paying special attention to thefollowing particulars:

You'll probably want to turn up debugging output as much as possible to make sure everything is working the way it should:

$log_level = 5;

With quarantine management, you can safely set the final destiny of viruses and spam to <tt>D_DISCARD</tt>,since in a manner of speaking these items are being "delivered" to aplace where the recipients can review them (and recover them ifdesired). This avoids sending out a lot of noisy Delivery StatusNotifications (DSNs), most of which bounce anyway (and create stillmore noise).

$final_virus_destiny = D_DISCARD;
$final_spam_destiny = D_DISCARD;
$warnvirussender = 0;
$warnspamsender = 0;

You should also take a look at the other <tt>$final_*_destiny</tt> settings. Keep in mind that if you specify <tt>D_PASS</tt>as the final destiny for a type of mail, you effectively renderper-user settings in Maia Mailguard useless for that type of item. Forinstance, if you set <tt>$final_bad_header_destiny = D_PASS</tt> (the default setting), there's no point in offering users the ability to be a <tt>$bad_header_lover</tt> or to <tt>$bypass_header_checks</tt>, since these will not override <tt>D_PASS</tt>. To make these settings meaningful and give users control over these things, choose any other final destiny (e.g. <tt>D_BOUNCE</tt>, <tt>D_DISCARD</tt>, or <tt>D_REJECT</tt>).

The <tt>$QUARANTINEDIR</tt> setting is irrelevant to this versionof Maia Mailguard, since quarantining now takes place entirely withinthe database, and not on the filesystem. Similarly, you can ignore thevalues of <tt>$virus_quarantine_method</tt>, <tt>$spam_quarantine_method</tt>, <tt>$virus_quarantine_to</tt>, and <tt>$spam_quarantine_to</tt>, since amavisd-maia does not use these values.

Specify the information amavisd needs in order to connect to the database (where <tt>passwd</tt> is the <tt>amavis</tt> user's password):

@lookup_sql_dsn = ( ['DBI:mysql:maia:localhost', 'amavis', 'passwd'] );

Leave the <tt>$sql_select_policy</tt> and <tt>$sql_select_white_black_list</tt> variables commented out, since Maia takes care of these for you. Similarly, you probably want to comment out the <tt>$whitelist_sender_*</tt> and <tt>$blacklist_sender_*</tt> variables, since Maia uses a database table to store this information.

If you want to include support for Blowfish encryption of quarantined/cached e-mail, you'll have to add a new <tt>$key_file</tt> setting to amavisd.conf to tell it where to find your key file:

# Blowfish encryption key file (optional)
$key_file = "$MYHOME/blowfish.key";

The <tt>@local_domains_acl</tt>, <tt>%local_domains</tt>, and <tt>$local_domains_re</tt>settings are observed as usual, but these are not strictly necessarywith Maia Mailguard, since you can add domains to Maia using theadministration interface, which effectively causes such domains to betreated as "local" for amavisd's purposes. You will want to do this forall of the domains you process mail for, even if those domains aredownstream from your server.

13. (Re)start amavisd-maia

In case there's already an amavisd process running, you can make sure it's stopped and the new version started by typing:

[root]# /etc/rc.d/init.d/amavisd restart
or [root]# /etc/rc.d/init.d/amavisd stop
[root]# /etc/rc.d/init.d/amavisd start

Now amavisd should be connecting to your new database to look upuser settings and whitelist/blacklist configurations, as well aslogging quarantined items to the database. Check the amavisd logs tomake sure of this. If you see errors in the logs about failures toconnect to the database, double-check the <tt>@lookup_sql_dsn</tt> line in your /etc/amavisd.conf file.

If everything looks good in the log files, you can turn the <tt>$log_level</tt>back down to something less noisy (e.g. 0, 1, or 2). Reload (orrestart) amavisd again to make this change take effect. Set up the initscripts as needed to run this at startup.

14. Login and become the super-administrator

Since in our example we installed the Maia Mailguard scripts in/maia relative to the document root of our web server, the scriptsthemselves should now be accessible at:

www.example.com/maia/

This is where you (and your users) will go most of the time to loginto Maia Mailguard. This first time, however, you'll want to dosomething different in order to register yourself as the Maia Mailguardsuper-administrator. Do this by going to:

www.example.com/maia/login.php

You'll be presented to the login page as usual, but if you loginsuccessfully and no other user in the database currently has super-administrator privileges, you'll be assigned these privileges. You onlyhave to do this once; after that, you can login just like any otheruser, and your super-administrator privileges will be granted to youautomatically.

NOTE: If you selected the <tt>internal</tt>authentication method, you'll need to get yourself a temporary usernameand password to login with. You can get this by visiting theinternal-init.php page. This script will only run if there's nosuper-administrator defined yet:

www.example.com/maia/internal-init.php

The internal-init.php script will create an account for you, and youshould received an e-mail from Maia that contains your temporary logincredentials. Use these at this stage to login, and change them fromyour Settings Page.

As super-administrator, you have all the privileges ofadministrators (e.g. "impersonating" other users, and deleting users),but also the ability to grant administrator privileges to others (andrevoke them, if desired). Maia Mailguard only allows onesuper-administrator account, but there can be as many administrators asthe super-administrator wants. The super-administrator cannot bedeleted, and cannot have his privileges revoked by anyone else. Shouldthe super-administrator ever wish to give up his privileges, he has todo so by logging in at:

www.example.com/maia/login.php

NOTE: after a super-administrator "unregisters"himself, the system effectively has no super-administrator, so the nextuser to login with the ?super=register argument will become thesuper-administrator. My suggestion, then, is to ensure thatsuper-administrator privileges are handed off to someone elsequickly--have the current super-administrator "unregister" only whenthe new candidate is ready to "register".

15. Configure Maia Mailguard: System Configuration

Now that you've logged in successfully as the super-administrator,you can finish configuring Maia Mailguard by going to the [Admin] linkon the toolbar (the "key" icon in the default theme). The SystemConfiguration link from there is where you'll find the rest of thesystem-wide settings you'll want to adjust before Maia Mailguard "goeslive". The help file in the Administration Menu provides more detailedexplanations of all the configuration options available to you there.

16. Install any additional language packs

Maia Mailguard ships with an English language pack pre-installed,but other languages and character sets are supported as well. Theselanguage packs no longer ship with the distribution, however they willbe made available for download individually here as soon as they become available.

Note that translations are all based on the English language versions,and are contributed by members of the user community on a volunteerbasis. As such, Renaissoft can make no guarantees regarding theaccuracy or the completeness of a given non-English translation. Wecertainly appreciate the efforts of these volunteer translators, andcredit for their work is incorporated into each of their languagepacks. If you would like to contribute a translation, please contact Robert LeBlanc for more details.

17. Customise the help page

A stock help page for end-users is provided in the help.php file, whichdescribes the various settings and their implications, as well as howthe whitelist/blacklist settings work. If you wish to modify this fileto add some site-specific information, extra tips, etc., this is thetime and place to do it.

The text of the document itself can be found in the "localized"version of the help file (e.g. the English version is in./locale/en/help.php). You can edit the text there if you have minorchanges to make, but if you have major changes in mind, you cancompletely replace the help page itself without breaking anything.

18. Customise the e-mail templates

If you want to enable the sending of e-mail reminders to users whentheir quarantines/caches start to get large, you may also want to editthe reminder.tpl file or create your own new template, using some ofthese placeholders:

Placeholder

Expands To

<tt>%%VIRUSCOUNT%%</tt>

Number of viruses in quarantine

<tt>%%SPAMCOUNT%%</tt>

Number of suspected spam items in quarantine

<tt>%%BANNEDCOUNT%%</tt>

Number of items with banned file attachments in quarantine

<tt>%%HEADERCOUNT%%</tt>

Number of items with invalid mail headers in quarantine

<tt>%%VIRUSSIZE%%</tt>

Total size of all viruses in quarantine

<tt>%%SPAMSIZE%%</tt>

Total size of all suspected spam items in quarantine

<tt>%%BANNEDSIZE%%</tt>

Total size of all items with banned file attachments in quarantine

<tt>%%HEADERSIZE%%</tt>

Total size of all items with invalid mail headers in quarantine

<tt>%%MAIAURL%%</tt>

URL users should visit to login to Maia Mailguard

<tt>%%ADMINEMAIL%%</tt>

E-mail address of the mail administrator

<tt>%%EXPIRYPERIOD%%</tt>

Number of days items are allowed to live in quarantine

<tt>%%OLDESTITEMTTL%%</tt>

Number of days before the oldest quarantined item is deleted

<tt>%%OLDESTITEMAGE%%</tt>

Age (in days) of the oldest item in quarantine

If you're using the internal authentication method, you'll also wantto configure the newuser.tpl template, which Maia sends to new userswhen their accounts are created.

The newuser.tpl template is used to send a new user his temporary login credentials, and supports the following placeholders:

Placeholder

Expands To

<tt>%%LOGIN%%</tt>

The new user's temporary login name

<tt>%%PASSWORD%%</tt>

The new user's temporary password

<tt>%%LOGINURL%%</tt>

URL users should visit to login to Maia Mailguard

<tt>%%ADMINEMAIL%%</tt>

E-mail address of the mail administrator

19. Schedule the maintenance scripts

You'll want to schedule some of the provided maintenance scripts torun at regular intervals to do things like learn from (and optionallyreport) confirmed spam, as well as expiring old items from thequarantine and the ham cache, and sending e-mail reminders to userswhose quarantines/caches are overflowing.

It's important to note that these scripts must be run by the <tt>amavis</tt> user, due to the security precautions we took earlier, so these scheduled jobs should be added to the <tt>amavis</tt> user's crontab, and not <tt>root</tt>'s.

process-quarantine.pl should be run about once per hour, to train your Bayes database and report any spam your users have confirmed.

stats-snapshot.plshould be run at the beginning of every hour, to take a snapshot ofyour stats table and update certain counters that are used to generategraphical charts.

expire-quarantine-cache.pl should be run once per day, to expire unconfirmed spam and cached ham that has exceeded your specified age threshold.

send-quarantine-reminders.plshould be run once per week or so, to remind neglectful users to checktheir quarantines and ham caches if they exceed your size or item countthreshold.

send-quarantine-digests.plshould be run once every 5 or 10 minutes, to check to see whether anyusers have requested e-mail digests of their quarantine contents. Themore often you run this script, the more granularity you offer yourusers (e.g. running the script every minute offers a schedulingresolution of one minute, etc.), but at the cost of keeping the serverbusier.

20. Delete the admin subdirectory

The PHP scripts installed earlier included a number ofadministration scripts in the admin subdirectory. Once you've got MaiaMailguard up and running properly, you no longer need these scripts,and should delete that subdirectory and its contents as a securityprecaution, so that web visitors cannot access those scripts.