How to use amavisd-new with Courier
***********************************

by Martin Orr <amavis@martinorr.name>


  There may be additional or more up-to-date information at:
    http://www.martinorr.name/amavisd-new

  WARNING:  This README applies to the current version of the Courier patch,
  and requires Net::Server version 0.90 or later. For older versions of
  Net::Server please use old courier patch and refer to README.courier-old.

The design of courierfilter means that amavisd-new must behave somewhat
differently from the ways in which it normally behaves.  This has two main
effects:
1. amavisd is started and stopped by courierfilter whenever Courier starts and
   stops.  You must not start, restart or stop it directly, but instead use
     filterctl {start|stop} amavisd
   (It is possible but not recommended to configure amavisd to be manually
   started and stopped; see below under manual startup/shutdown mode.)
2. It is not possible to modify the headers of messages.  This makes
   amavisd-new/courierfilter of limited use for spam checking.  If you want
   spam checking, you should run spamd separately and pass mail to it either
   using maildrop or from .courier files.

CONFIGURING AMAVISD

You will need to make a the following changes to amavisd.conf:
1. Comment out the lines setting $daemon_user, $daemon_group: amavisd will be
   started as whatever user Courier runs as (not root) so is unable to change
   to another user.
2. Set $forward_method to undef and $notify_method to
    'pipe:flags=q argv=/usr/sbin/sendmail -f ${sender} -- ${recipient}'
   If you wish to include "local" in your enablefiltering file, or you are using
   a version of Courier older than 0.49.0, then you must instead use
    'pipe:flags=q argv=perl -e $pid=fork();if($pid==-1){exit(75)}elsif($pid==0){exec(@ARGV)}else{exit(0)} /usr/sbin/sendmail -f ${sender} -- ${recipient}'
3. Set $courierfilter_shutdown to 1.
4. Set $unix_socketname to DIR/amavisd where DIR is the appropriate
   courierfilter directory.  You need to decide whether you want a mandatory
   filter, in which case all mail passing through your server will be filtered,
   or an optional filter, in which case only mail to local users will be
   filtered, and your users will have the option of overriding filtering (you
   will almost certainly want a mandatory filter).  You should see the
   courierfilter manpage for more details, and also for the correct directories
   on your system (on mine, they are /var/lib/courier/allfilters for mandatory
   filters and /var/lib/courier/filters for optional filters).
5. Replace any existing setting of $interface_policy{'SOCK'} with
     $interface_policy{'SOCK'} = 'AM-SOCK';
     $policy_bank{'AM-SOCK'} = { protocol => 'COURIER' };

CONFIGURING COURIER

Install amavisd or a link to it in /usr/lib/courier/filters (or whatever
directory is correct on your system - again, see the courierfilter manpage).
The name of this link must match the name of the socket in $unix_socketname.

Make sure that the enablefiltering file exists in your Courier configuration
directory (/etc/courier or equivalent) and contains "esmtp".  If you wish to
include "local", to filter mail sent through the sendmail command, then you
must use the long forking value of $notify_method in step 2 above.

MESSAGE DESTINIES

As of amavisd-new 2.4.0, it is possible to use all message destinies with
Courier.  D_REJECT is probably the best choice as the message (if infected of
course) is rejected in the original SMTP session, and never becomes your
responsibility to deliver or send a DSN.  The client MTA receives the response
"550 5.7.1 Message content rejected".

RELEASING ITEMS FROM QUARANTINE

If you wish to be able to release items from quarantine using the AM.PDP
protocol, you must set this to use a TCP port.  Include the following in
amavisd.conf:
$inet_socket_port = 9998;
$interface_policy{'9998'} = 'AM.PDP';
$policy_bank{'AM.PDP'} = {
  protocol => 'AM.PDP',
  inet_acl => [qw( 127.0.0.1 [::1] )]   # restrict access to these IP addresses
};

Modify the amavisd-release script to use $socketname = '127.0.0.1:9998'.

MANUAL STARTUP/SHUTDOWN MODE

You may prefer to start and stop amavisd independently of Courier (perhaps
through its own init script).  However this means that you are on your own in
ensuring that it is started at the right time, namely as soon as possible after
Courier is started (or restarted).  Messages which arrive after Courier starts
but before amavisd is ready will simply not be filtered.  However, starting
amavisd before Courier will unfortunately not work.  If you wish to disable
virus checking you must not only stop amavisd but also remove the socket -
Courier will refuse to accept mail while the socket exists but amavisd is not
running.

To use manual startup/shutdown mode, do not put a link to amavisd in
/usr/lib/courier/filters and set $courierfilter_shutdown to 0.

If you are using manual startup/shutdown mode, you do need to set the
$daemon_user and $daemon_group variables.  $daemon_user
can be whatever you like and $daemon_group must be the same group as Courier
runs as.  In order to allow amavisd to create its socket you must either start
amavisd as root or make the filter directory group-writable.