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

by Martin Orr <martin-amavis@walnut.methody.org>

There are two different ways of using amavisd-new with Courier.  In one of
these, the startup and shutdown of amavisd is controlled by courierfilter and in
the other it is done independently (probably through its own init script):  I
shall refer to these as the courierfilter and the manual startup/shutdown modes.
It is important to note however that even in manual startup/shutdown mode,
amavisd still talks to Courier using the courierfilter protocol.

COURIERFILTER STARTUP/SHUTDOWN MODE

This is probably the preferable mode of operation, but it alters the original
amavisd code more deeply and has not yet had as much testing as the manual
startup/shutdown mode.  In this mode amavisd (assuming it is enabled) will be
automatically started and stopped whenever Courier starts and stops, and you can
enable/disable it with
filterctl {start|stop} amavisd

If this mode is enabled in amavisd.conf, you must not start, restart or stop
amavisd other than through filterctl.
Also it may take up to 10 seconds after stopping courierfilter or using
"filterctl stop amavisd" before amavisd actually stops.  During this time you
cannot start amavisd again: this particularly annoying because it means that
"courierfilter restart" will not work, since it stops courierfilter and then
starts it again immediately (in fact it will appear to work but all messages
will be rejected with 432 Mail filters unavailable).

MANUAL STARTUP/SHUTDOWN MODE

In this mode you need to ensure that amavisd starts as soon as possible after
Courier, as mails which arrive after Courier starts but before amavisd will not
be filtered.  (This includes when Courier is restarted.)  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.

CONFIGURATION

In amavisd.conf:
1. If you are using courierfilter startup/shutdown mode:
        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.
    If you are using manual startup/shutdown mode:
        Set $daemon_user to whatever value you like.  Set $daemon_group to the
        same group Courier runs as (probably courier or daemon) so that Courier
        will be able to write to amavisd's socket.
2. Set $forward_method to undef and $notify_method to
   '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}'
   (one long line)
3. Set $courierfilter_shutdown to 1 if you are using courierfilter
   startup/shutdown mode, 0 if you are using manual startup/shutdown mode.
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. Set $protocol to 'COURIER'.
6. You must use D_REJECT instead of D_BOUNCE for $final_*_destiny settings.

If you are using manual startup/shutdown mode, in order to allow amavisd to
create its socket you must either start amavisd as root or make the filter
directory group-writable.

If you are using courierfilter startup/shutdown mode, 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).

Make sure that the enablefiltering file exists in your Courier configuration
directory (/etc/courier or equivalent) and contains "esmtp".

LIMITATIONS

All the courierfilter protocol allows is to simply accept or reject a message. 
It cannot modify the headers, rendering amavisd-new/courierfilter essentially
useless 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.

Also D_REJECT and D_PASS are the only useful message destinies since D_BOUNCE
requires the mail server to give up handling the message entirely and leave
responsibility to amavisd.  If you set the destiny to D_BOUNCE, you will instead
get amavisd-generated DSNs for viruses but the message containing the virus will
be delivered.  With D_REJECT, messages containing viruses will be rejected in
the original SMTP session with 550 5.7.1 Message content rejected.

Amavisd's own notification messages are passed to it for filtering as well as
other messages (I think this is a bug in Courier - see
http://sourceforge.net/mailarchive/message.php?msg_id=8749164 for details). 
This could be a problem if you simultaneously receive as many messages
containing viruses as you are running amavisd processes, as no process would be
available to filter the notification messages.  In order to prevent this hanging
the mail server, the $forward_method recommended above forks before sending the
notification so that the process responsible for sending it is freed up to
filter it.

=========
See also the PerlStalker's SysAdmin Notes and Tools: Courier+amavisd-new by
Randall B. Smith, http://perlstalker.amigo.net/courier/amavisd-new.phtml
It applies to the patch against the 20030616 release which was rather
different, but much of it is still useful
