
Installation instructions for MailZu
=======================================

MailZu, a quarantine management interface for amavisd-new. It allows users
and administrators to view quarantined messages and release, request, or
delete them. 

MailZu need not reside on the same host as amavisd-new. MailZu also supports
environments with multiple amavisd-new instances (as long as all instances
report to the same SQL database). MailZu is only suitable for amavisd-new
version 2.3.0 or greater.


Requirements
===============

MailZu requires that amavisd-new has SQL reporting enabled. If you want
users to be able to view more than just the simple message headers, quarantining
to SQL should be enabled.

The requirements for running MailZu is as follows:

1) Amavisd-new 2.3.0 or greater
2) A PHP-compatible web server
3) PHP 4.x or greater with socket support ( --enable-sockets )
4) PEAR::DB 
5) PEAR::Mail_Mime

For the included and optional database cleanup script
(scripts/mz_db_clean.pl):

1) Perl 5.6 
2) Perl DBI with respective database driver

MailZu utilizes the recommended values for the SQL field msgrcpt.rs as
stated in the README_FILES/README.sql that comes with the amavisd-new
distribution. The cleanup script performs database purging based on old
records and those messages marked for deletion 'D'. If you already have a
script which performs database maintenance, it is recommeneded to quickly
look through the queries in the provided script and merge them. 


Unpacking the distribution
============================

Fetch the latest tarball from http://www.mailzu.org. The file has a format
of mailzu-x.y.tar.gz where 'x' is the version and 'y' is the revision.

Extract the archive with:

	# tar xvfz mailzu-x.y.tar.gz      
	# cd mailzu-x.y
          

Overview
================
The amavisd, SQL, and MailZu services act together to offer a complete 
quarantine management interface. The relationship is as follows:

-- Amavisd-new populates the SQL database with basic information about every
   message processed and optionally quarantining malware to the database
-- MailZu reads from the basic information from the SQL database to give a
   webmail like view of quarantined items. If the item was quarantined to the
   database, MailZu can also allow viewing of the complete email.
-- MailZu requests the release of email by opening a TCP/IP socket to the 
   responsible amavisd-new instance. Amavisd-new itself then queries the 
   database for the message information and releases the email to the user.

These services may reside on one particular hosts or a seperate host for each 
application. MailZu cannot communicate to Amavisd-new through a unix socket.


Configuration
================

In order to use MailZu, amavisd-new must be configured to store message
information in an SQL database. 


Amavisd-new Configuration
---------------------------

All configuration variables mentioned in this subsection are meant for
amavisd-new.

MailZu is not required to reside on the same host amavisd-new does, but
MailZu must be able to communicate with all instances of amavisd-new in your
environment to release messages.

Since MailZu can support multiple amavisd-new instances it
is important that the mechanism for communication is TCP/IP, not unix
sockets. 

Information about every message processed by amavisd-new can be stored in
SQL by setting the amavisd-new configuration variable @storage_sql_dsn.

  # Example setting:
  @storage_sql_dsn =
    ( ['DBI:mysql:database=mail;host=127.0.0.1;port=3306', 'user',
       'passwd']);

or:

  @storage_sql_dsn = @lookup_sql_dsn; # If you plan to use the same database
				      # as the SQL lookups

Specify the ports that amavisd-new should bind to.

  $inet_socket_bind = undef; 	      # Bind on all interfaces
				      # or check amavisd.conf-sample for
				      # more specific examples

  $inet_socket_port = [10024,9998];   # listen on this local TCP port(s)
     				        (see $protocol)

Specify an arbitrary policy name tied for this port. 'AM.PDP' is recommended
for clarity.

  $interface_policy{'9998'} = 'AM.PDP';

Associate a policy bank to that port where the protocol is 'AM.PDP' and
restrict access to that port to the host that MailZu is configured and any
additional hosts you desire.

  $policy_bank{'AM.PDP'} = {
    protocol => 'AM.PDP',
    inet_acl => [qw( 127.0.0.1 [::1] <IP of MailZu host> )],
  };

The configuration settings above is the minimal setting required by MailZu. 

This allows MailZu to give an index of all messages that were considered spam
or banned. The index displays the To (admins only), From, Subject, Date, and 
spam Score, for each message.

If you want users to be able to view the body of their spam messages via MailZu,
you must configure amavisd-new to quarantine messages to SQL. This can be done
with

  $banned_files_quarantine_method = 'sql:';
  $spam_quarantine_method         = 'sql:';

This optional setting has no impact on MailZu's capability to release or
request mail.

Reload amavisd-new and try initiating a telnet session from the MailZu host to
the AM.PDP port

  # telnet <Amavisd-new Host> 9998

If a connection is made than configuration of amavisd-new was successful.
Repeat this configuration procedure for every amavisd-new instance.


MailZu Configuration
----------------------

The configuration file for MailZu resides in config/config.php. The settings in
this file determines the authentication mechanism, the administrators, the
AM.PDP port used in your amavisd-new configuration, and other miscellaneous
settings.

The configuration file is populated with helpful comments that explain every
variable and their possible settings. Only the most important settings will be
discussed here.

Amavisd-new related settings
-------------------------------

For MailZu to display message indices and perform actions on the message in
question, it must be able to communicate with the amavisd-new instances and the
database which stores message information. MailZu requires the same read/write
credentials as amavisd-new in order to mark mail read or for deletion.

First specify the port where the AM.PDP protocols listens on. This is the same
port we specified earlier in "Amavisd-new Configuration". 

  // Amavisd-new AM.PDP port 
  // Since the port number can not be stored in the database
  // all instances of amavisd-new must use the same AM.PDP port
  $conf['amavisd']['spam_release_port'] = '9998';

All amavisd-new instances must use the same port number, but not necessarily
9998. Now we must configure MailZu to query the same database that amavisd-new
is populating.

  $conf['db']['dbType'] = 'mysql';
  $conf['db']['dbUser'] = 'user';
  $conf['db']['dbPass'] = 'pass';
  $conf['db']['dbName'] = 'dbname';
  $conf['db']['hostSpec'] = 'hostname.example.com:port';

These settings should correspond to the credentials entered for the amavisd-new
configuration. The 'dbType' can be any PEAR DB compatible database. Please see
the config/config.php file for more information.


Autentication settings
-------------------------------

Authentication is one of those important settings. You can have a user
authenticate to one of three backends. Either LDAP, MS Active Directory, or an
SQL backend.

  // Set an authentication method: 'ldap','ad', or 'sql'
  $conf['auth']['serverType'] = 'ldap';

Each seperate authentication method have related configuration variables that
must be set. Please see the appropriate (MECH)_README for more information.

Regardless of which method you choose, it is important to understand that there
will always be three attributes ( or fields for SQL ) that is critical for a
successful login. 

The first of the three is the user password. For LDAP and AD, this need not be
specified, for the authentication is handled by the binding process. But for
SQL, the field of where the password is stored is required. 

The second attribute is the login format. For LDAP it is usually the 'uid'
attribute, or if you want a fully qualified email address as the login, it
could be 'mail'. Active Directory has similar attributes. 

This setting controls whether the user would use the login 'user', or if the 
configuration variable was set to the 'mail' attribute, the login would be 
'user@example.com'. 

These two attributes are enough to be authenticated to the MailZu interface,
but the third attribute is what determines which messages the authenticated
user is permitted to view. This attribute is the final recipient address. It is
the email address that amavisd-new reports as the envelope recipient. 

For example, if the login used was 'user', than there must be an attribute or
field that determines the email address associated with this user. Even if the
login was 'user@example.com' the third attribute may or may not be the same.
The address might have been aliased to an internal address 'user@internal.example.com'.

To get a description on how to set up these critical configuration variables for
your authentication, please see the appropriate (MECH)_README file in docs/.
