1. Overview =========== myAmavis (licensed under the GPL) started as a very small private project to be able to change the behaviour of amavisd-new with very little effort. The current version includes everything I needed at that time, so I don't guarantee that it fits your needs ;-) myAmavis is more or less a web frontend for the SQL database that can be used by amavisd-new for policy lookup and storage. Following a (probably incomplete) list of features: * multiple configuration policies per user possible, easy switching of used policy per recipient address. * separate configuration settings for virus scanning, spam checking, banned files checking and bad header checks possible: - completely enable/disable check - enable/disable quarantining for matching mails - quarantining to file-system or to another email-address - admin notification when a mail matches - enable/disable delivery of matching mails to final recipient - enable/disable notification of final recipient when a matching mail has been hold in quarantine - configuration of access extensions for final delivery of matching mails * per user quarantine management (list files currently in quarantine, release and delete files from quarantine). * hard and soft white-/black-listing of sender addresses (entries are managed per recipient address). * powerful statistics module. * webfrontend uses JavaScript/AJAX, so your browser must support this. * online-help included in the web-frontend. 2. Installation =============== * You must have installed amavisd-new, and your amavisd-new installation must be correctly configured and running. Configuring amavisd-new is out of scope of this README. * Make sure you have enabled SQL storage and SQL lookup in your amavisd-new configuration. Currently you can use either MySQL or PostgreSQL as database backend with myAmavis. See documentation of amavisd-new on how to configure SQL lookup / storage. * If you have users with more than one email address (e.g. john.doe@example.com and jd@example.com), and if you want to be able to distinguish between these email addresses (for instance for policy management, statistics etc.), you have to make sure your MTA does not rewrite recipient addresses before giving mail to amavisd-new. If your MTA is postfix, this means, you have to use a modified version of the cleanup service for the before-filter-SMTP daemon and for the pickup service. See amavisd-new documentation for details on this. * Make sure you have a webserver with PHP support. PHP needs support for PostgreSQL or MySQL (depending on your database system). * Put the contents of the "htdocs" directory somewhere below your webroot (e.g. into /var/www/localhost/htdocs/myAmavis). * Modify the file ".htaccess" according to your needs. The version included with this archive authenticates users against an IMAP server running on the same machine, but you may change this if you want to (this configuration requires apache module mod_auth_imap, which is not part of a standard apache installation). Please be aware, that you MUST use Basic Authentication to access myAmavis, because myAmavis uses the supplied username to determine "your" email addresses and configuration policies. * Modify the content of "config.php" according to your database setup. * Store the files from the "scripts" directory into /usr/local/sbin (path currently hardcoded into myAmavis). Modify those scripts according to your environment (maybe you have to change some paths - they are very very short and easy ;-). * Add the two lines from the file install/sudoers_addon to your sudo configuration. Maybe you have to modify them a little bit (e.g. name of the user running apache and/or some paths). 2.1 Required settings in amavisd-new ------------------------------------ Here is a list of settings needed in amavisd.conf to make sure myAmavis can be used as expected. This list does not include all directives required to run amavisd-new - this list only contains settings relevant for use with myAmavis. To enable SQL lookup and storage you need something like this: @lookup_sql_dsn = (['DBI:Pg:database=amavis', 'amavis', 'amavis']); @storage_sql_dsn = @lookup_sql_dsn; Of course you have to replace the database configuration settings with your real values (probably the same you set in config.php). To make sure "amavisd-release" (the tool for releasing mail from file-system quarantine) works: $unix_socketname = "$MYHOME/amavisd.sock"; $policy_bank{'AM.PDP-SOCK'} = { protocol => 'AM.PDP', auth_required_release => 0, }; $interface_policy{'SOCK'} = 'AM.PDP-SOCK'; To be able to enable/disable delivery of mails to final recipients, all the *_final_destiny settings (spam, virus, banned, bad_header) must NOT be D_PASS (in my configuration they all are set to D_DISCARD). IF you set for instance "spam_final_destiny" to D_PASS, you can NOT disable delivery of spam to final recipients, because D_PASS has a higher priority. Furthermore you should use something like this as fallback values in amavisd.conf to make sure no mail will get lost until explicitly overwritten in an SQL policy configuration: @virus_lovers_maps = (1); @spam_lovers_maps = (1); @bad_header_lovers_maps = (1); @banned_files_lovers_maps = (1); To summarize this step: You have configured that all spam, virus, bad header and banned mails have to be discarded (*_final_destiny = D_DISCARD). At the same time you said all recipients are spam-, virus-, banned- and bad-header-lovers, so all recipients will nevertheless receive such mails. All this (apparently stupid) settings are necessary to be able to control the final delivery to certain recipients by appropriate database entries and still not loose any mail for recipients without entries in the policy database. To be able to use the quarantine settings and the quarantine manager of myAmavis, you need something like this: $QUARANTINEDIR = "$MYHOME/quarantine"; $spam_quarantine_method = 'local:spam-%m.gz'; $bad_header_quarantine_method = 'local:badh-%m'; $virus_quarantine_method = 'local:virus-%m'; $banned_files_quarantine_method = 'local:banned-%m'; This makes sure, that quarantine settings in the myAmavis policy configurations work as expected. The format of the filenames used for quarantined mails is irrelevant (i.e. you could replace "spam-%m.gz" by another filename template). The important point is using the "local:" quarantine method and having set a QUARANTINEDIR. To make address extensions work: $recipient_delimiter = '+'; (or any other valid address extension character recognized by your MTA). Please remember for all policy settings that you can change using myAmavis: if amavisd-new does not find a policy configuration for the recipient address of an email in the database, it falls back from SQL lookup to all the lookup tables defined in amavisd.conf, so make sure you configure sensible default values there. 2.2 Required changes to the SQL database ---------------------------------------- These modification do NOT introduce any incompatibilities with amavisd-new, the database will only be EXTENDED by new tables and some optional indices. At first, create some new helper tables and a new view using the SQL script install/prepare_database_X.sql (use the one matching your database system). Optionally also execute install/create_indices_X.sql to add some more indices to speed up the statistics module. Next, you have to add some entries to the tables "policy", "users" and "userauth". Let me explain this with an example: You want one of your users, Bob, being able to modify the behaviour of amavisd-new for his two email addresses bob@domain.com and bob@domain.net. Let's assume the Bobs login name will be "bob". At first, create a default policy configuration for Bob in the "policy" table. You can set any policy configuration settings you want as default for Bob. The only thing you MUST do: The column "policy_name" must contain 'bob_default' (i.e. the user id plus '_default'). Remember the primary key value (column "id") of the created policy entry. [ You can use the helper script tools/add_policy_for_user_X.sh to create the default policy for a given login name. For this to work there must be a policy with policy_name='default' in the database, which will be copied to create the default policy for the given login name. ] For each of Bobs email addresses create an appropriate entry in the "users" table pointing to the policy 'bob_default'. I.e. the column "email" has to contain 'bob@domain.com' respective 'bob@domain.net' and the "policy_id" has to be set to the primary key value of Bob's default policy entry. Now you have created a default policy for Bob and assigned both of Bobs email addresses to this policy. Remember the primary key values (column "id") of these two new entries in the users table. [ Just to make sure you are aware of this: With this step (adding records to the "users" table) you have changed the behaviour of amavisd-new when it receives mail for bob@domain.com or bob@domain.net. Such emails will be handled using the policy 'bob_default' which may specify behaviour different from the default one configured by the content of amavisd.conf. ] Now, when Bob logs in into myAmavis using his login name "bob", myAmavis needs to know which email addresses can be configured by Bob. For this, you have to create two entries in the table "userauth". Fill column "userid" with the login name Bob will use in the HTTP Authentication (in this case: 'bob'), and column "email_id" with the primary key values of the created entries in the "users" table. [ If you want to add an email address to the "users" table and assign this email address to a given login name (the last two steps described above), you can use the helper script tools/add_email_address_X.sh for this. This script receives an email address and a login name via command line. It creates an appropriate entry in the "users" table (the email address will be assigned to the users default policy), and it creates an appropriate entry in the table "userauth" which assigns the email address to the given login name. ] Here all this in short form: INSERT INTO policy(policy_name, virus_lover, ...) VALUES ('bob_default', 'Y', ...); -- new policy entry has primary key id=20 INSERT INTO users(priority, policy_id, email, local) VALUES (10, 20, 'bob@domain.com', 'Y'), (10, 20, 'bob@domain.net', 'Y'); -- new users entries have primary keys id=98 and id=99 INSERT INTO userauth(userid, email_id) VALUES ('bob', 98), ('bob', 99); Alternative way using the helper scripts: # create a copy of the 'default' policy for bob # (the policy 'default' must already exist!) > tools/add_policy_for_user_X.sh bob # add email addresses for bob (emails sent to these # addresses will be handled by policy 'bob_default'): > tools/add_email_address_X.sh 'bob@domain.com' bob > tools/add_email_address_X.sh 'bob@domain.net' bob Now, when Bob logs in into myAmavis, myAmavis will use table "userauth" to know which email addresses can be managed by Bob. Table "users" tells myAmavis (and amavisd-new), which policy to be used for each email address. When Bob creates a new policy using myAmavis, this new policy will initially be a copy of the policy "bob_default", so you ALWAYS need a policy named "LOGINNAME_default" for each user of myAmavis. If you need a user who can see ALL entries (i.e. ALL policies, ALL customizable email addresses etc.), just put this username into the table "adminusers". When a user logs in with this username, the frontend will be run in "admin mode", where ALL existing email addresses, policies, quarantine files and statistics will be visible (and not only those belonging to the user currently logged in). IF you add an admin user, and IF you want this admin user to be able to create new policies (e.g. a default policy for a new user), you also need a policy with name 'default', because this one will be copied when a new policy is created when the frontend is in admin mode. 3. Upgrading ============ Upgrading from 0.2 to 0.3.3 --------------------------- * Take a look at install/prepare_database_X.sql and verify that your database structure contains the tables, fields and constraints mentioned there. * Remove the view "mailsflat" from your database and recreate it using the statement in install/prepare_database_X.sql. The definition of the view has changed since the last version, so this step is absolutely necessary to be able to use the statistics module. * Copy all files from the htdocs/ directory to the location where your webserver expects them. * Modify config.php. There are some more settings in this file now, so you can't use the old config.php. But of course you can copy the settings from the old config file (namely the DB*-variables) into the new config.php. * Check install/create_indices_X.sql to create some more column indexes (or indices?). You can safely execute the whole SQL script and ignore the warnings concerning already existing indexes. * If you want the statistics calculations to be somewhat faster you have to create a table with the "flattened data" at regular intervals (see comments on the variable "$MAILSVIEW" in config.php). * If you receive a lot of mail you may want to cleanup the database at regular intervals. Using the script tools/cleanup_amavis_storage_X.sh as a daily cron job you can remove all mail statistics older than (by default) 180 days from the amavis database. Upgrading from 0.1alpha to 0.2 ------------------------------ * There is an additional table "adminusers" needed in the SQL database. Look into install/prepare_database.sql for the SQL code to create this table. After creating this table, fill it with all usernames you want to be able to use myAmavis in "admin mode" (i.e. access to ALL per-user policies, statistics will include ALL configured email addresses etc.) 4. Usage ======== 4.1 Configuring a policy ------------------------ TODO 4.2 Assigning policies to email addresses ----------------------------------------- TODO 4.3 White-/Black-Listing ------------------------ TODO 4.4 Quarantine management ------------------------- TODO 4.5 Statistics -------------- TODO 5. Bugs ======= Since I prefer PostgreSQL as database system, most of the small helper apps in the tools/ directory and the SQL scripts from the install/ directory are written for PostgreSQL. If you want to use these for MySQL you have to modify them accordingly (and maybe you even send me a copy to be included in the next release of myAmavis ;-) If something does not work as expected (e.g. database entries are not created, statistics are "wrong" or not even working), try to enable debug mode ($DEBUG=1 in config.php). This will make myAmavis print some of the executed SQL statements directly into the web page. Try to execute these statements in a database console (e.g. psql/mysql command line tool) and look for any errors (and report such errors to me ;-) There are a lot of things that could be more nice, more convenient, more colorful, more configurable, ... ------------------------------------------------------------------- mailto: myamavis@kapott.org bugs: https://bugzilla.kapott.org/enter_bug.cgi?product=myAmavis