How to use amavisd-new with Courier
***********************************
by Martin Orr <amavis@martinorr.name>
WARNING: This README applies to the older version of the Courier patch
which can be used with versions of Net::Server older than 0.90.
If you have Net::Server 0.90 or later, please see README.courier
and use the newer amavisd-new-courier.patch.
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. 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=/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 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. Replace any existing setting of $interface_policy{'SOCK'} with
$interface_policy{'SOCK'} = 'AM-SOCK';
$policy_bank{'AM-SOCK'} = { protocol => 'COURIER' };
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). 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.
The patch also places the MTA queue ID into a %Q macro which you can use
in log templates to get the Courier queue ID of the message. This is now
in the default log template.
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'.
LIMITATIONS
All the courierfilter protocol allows is to simply accept or reject a message.
In addition it is possible by bypassing the protocol itself to add or remove
recipients (thanks to Gordon Messmer for the original implementation of this in
courier-pythonfilter).
However it cannot modify the headers, rendering 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.
In this version of the patch, it is now possible to use D_BOUNCE and D_DISCARD
as message destinies, as well as D_REJECT or D_PASS. D_REJECT is probably still
a good choice however as the message is rejected in the original SMTP session.
The client MTA receives the response "550 5.7.1 Message content rejected" and it
is the client, not Courier, who is responsible for any DSN.
=========
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 20040701 release since which time the Courier patch has been
completely rewritten. It still contains much useful information, but must be
read in conjunction with this README.
