Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki — Fri, 07 Mar 2008 10:53:32 GMT

Initial conversion from Docbook

New page

{{SpamAssassin/TOC}}
Postfix is a mail transport agent written by security researcher Wietse Venema. Not surprisingly, Postfix is designed from the ground up to be a highly secure system. It consists of several components, each of which runs with least privilege and none of which trust data from the other without validating it themselves. Despite the extensive security emphasis in the system's architecture, Postfix is capable of very good performance in normal conditions; because of architectural decisions, it is also fault tolerant and capable of good performance under adverse conditions such as resource starvation. It has become a popular replacement for sendmail because it provides a compatible command-line interface.

This chapter explains how to integrate SpamAssassin into a Postfix-based mail server to perform spam-checking for local recipients or to create a spam-checking mail gateway.

<div class="warning">
'''Warning'''

Postfix is a complex piece of software, and, like most MTAs, offers scores of configuration options. This chapter assumes that you are running Postfix 1.1 or 2.x (recommended) and does not cover how to securely install, configure, or operate Postfix itself. For that information, see the Postfix documentation and the book ''Postfix: The Definitive Guide'' by Kyle D. Dent (O'Reilly).
</div>

== Postfix Architecture ==

Several different Postfix components play roles in receiving messages from the Internet. The <tt>master</tt> daemon is responsible for the coordination of the components. Messages from the Internet typically enter the mail server via the <tt>smtpd</tt> daemon, which listens on port 25 and conducts the SMTP transaction with the remote sender. <tt>smtpd</tt> passes each message to the <tt>cleanup</tt> daemon, which performs sanity checks, fixes missing headers, and (with the help of the trivial-rewrite program) rewrites addresses. <tt>cleanup</tt> then deposits each message in the incoming mail queue and alerts the <tt>qmgr</tt> daemon. <tt>qmgr</tt> moves messages from the incoming queue to the active queue, and then calls <tt>local</tt> for delivery to local recipients (or <tt>smtp</tt> for relaying to remote recipients by SMTP). [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-FIG-1|Figure 6-1]] illustrates the flow of email through Postfix components.

<div id="spamassassin-CHP-6-FIG-1">
'''Figure 6-1. The Postfix architecture during message receipt'''

[[Image:SpamAssassin_I_6_tt91.png|The Postfix architecture during message receipt]]
</div>

Most systems keep Postfix's configuration files in ''/etc/postfix''. The most important files are ''main.cf'', which contains nearly all of the configuration directives for Postfix, and ''master.cf'', which configures the <tt>master</tt> daemon and determines how the various Postfix components will be run. After you make changes to either of these files, you should issue the <tt>postfix reload</tt> command to cause Postfix to re-read the files.

== Spam-Checking During Local Delivery ==

The easiest way to add SpamAssassin to a Postfix system is to configure Postfix to use procmail as its local delivery agent, rather than the Postfix <tt>local</tt> program. Then add a procmail recipe for spam-tagging to ''/etc/procmailrc''.

The advantages of this approach are:

* It's very easy to set up.
* You can run <tt>spamd</tt>, and the procmail recipe can use <tt>spamc</tt> for faster spam-checking.
* User preference files, autowhitelists, and Bayesian databases can be used.

However, Postfix runs a local delivery agent only for email destined for a local recipient. You cannot create a spam-checking gateway with this approach.

Instructions for configuring procmail for spam-checking can be found in [[SpamAssassin/SpamAssassin Basics#spamassassin-CHP-2-EX-6|Example 2-6]] in [[SpamAssassin/SpamAssassin Basics|Chapter 2]]. To configure Postfix to use procmail as the local delivery agent, use the <tt>mailbox_command</tt> directive in ''main.cf'':

mailbox_command = procmail -a "$EXTENSION"

<div class="warning">
'''Warning'''

If you configure Postfix to use procmail as the local delivery agent, you must be sure that you have an alias for ''root'' in your ''aliases'' file (typically in ''/etc'' or ''/etx/postfix''). The alias should point to another local user. Without such an alias, Postfix may be unable to deliver mail to ''root'' using procmail.
</div>

== Spam-Checking All Incoming Mail ==

If you want to set up a spam-checking gateway for all recipients, local or not, you need a way to perform spam-checking as mail is received, before final delivery. Postfix provides a general-purpose filtering directive called <tt>content_filter</tt>.

The <tt>content_filter</tt> directive specifies a mail transport that Postfix will invoke after receiving a message. The mail transport hands the message to a filtering program. The filter checks the message and then either refuses it (which will cause Postfix to generate a bounce message), discards it, or reinjects the (possibly modified) message into Postfix for further delivery. Messages that pass the filter are reinjected so that Postfix can operate on them almost as if they were new messages; this allows Postfix to behave properly if the content filter rewrites message headers. You can use the <tt>content_filter</tt> directive in ''main.cf'', in which case the directive will be used by both <tt>smtpd</tt> (for email received via SMTP) and <tt>pickup</tt> (for email received locally). You can also specify <tt>content_filter</tt> as an invocation option to <tt>smtpd</tt> or <tt>pickup</tt>, which is useful when you only want to filter email received from outside (or inside) the system.

Content filters can be programs that are invoked for each message. They read a message on standard input and reinject filtered messages via the <tt>sendmail</tt> program. They can also be daemons that listen on a local TCP port, receiving messages via SMTP or LMTP (Local Mail Transfer Protocol), and reinjecting filtered messages via SMTP by communicating with a second instance of <tt>smtpd</tt> listening on a local port.

<div class="tip">
'''Tip'''

Don't confuse Postfix's <tt>sendmail</tt> program with sendmail. sendmail is an entirely different MTA that also uses an executable named <tt>sendmail</tt> to perform nearly all of its functions. Postfix's <tt>sendmail</tt> program is much more limited but is designed to serve as a replacement for sendmail's to facilitate converting systems from sendmail to Postfix.
</div>

SpamAssassin itself is not suitable for use as a content filter, because it doesn't know how to reinject a tagged message. However, SpamAssassin can be invoked by a content filter in several ways.

=== Using a Program as a Content Filter ===

The simplest content filters are programs that accept messages on standard input, perform spam-checking, and either exit with an error status code or reinject the message to Postfix. When you use a program as a content filter, you do not need to run any additional daemons—Postfix invokes the program for each message. If your system receives a lot of mail, you are likely to get better performance by using a daemonized content filter, which is discussed in the next section.

To use a program as a content filter requires a series of steps:

<ol>
<li><div>Create a new system user that Postfix will use to run the filter program or shell script. SpamAssassin will use this user's SpamAssassin preferences (in the ''.spamassassin/user_prefs'' file in their home directory) when checking messages that have multiple recipients. In the following steps, assume the user is named ''spamfilt''.
</div></li>

<li><div>Create a program (or shell script) that can accept an email message on standard input, perform filtering, and pass the modified message to <tt>sendmail</tt>'s standard input. The filter should also return an appropriate status code, usually the exit code from <tt>sendmail</tt>, which Postfix will understand. Your program (or shell script) should expect to receive command-line arguments consisting of the sender's email address and a space-separated list of recipient email addresses.

Here's an example of a filter script called <tt>pf-spamfilt</tt> that calls SpamAssassin using <tt>spamc</tt>. If the message being checked has only a single recipient, <tt>spamc</tt>'s <tt>-u</tt> option is used to load the per-user preferences. When the message has multiple recipients, the script runs <tt>spamc</tt> without <tt>-u</tt>, and, because the script will be running as the ''spamfilt'' user, <tt>spamc</tt> will use ''spamfilt'''s preferences file.

#!/bin/sh
#
# pf-spamfilt: An example spam filtering script for postfix
#
sender=$1
shift
recip="$@"
if [ "$#" -eq 1 ]; then
/usr/bin/spamc -u $recip
else
/usr/bin/spamc
fi | /usr/sbin/sendmail -i -f $sender -- $recip
exit $?

Because this filter uses the <tt>spamc</tt> client, you must be running a <tt>spamd</tt> server. Save the filter somewhere publicly accessible (e.g., ''/usr/local/bin/pf-spamfilt'') and set its permissions to allow anyone to read and execute it.
</div></li>

<li><div>Define a new mail transport in ''master.cf'' that invokes the filter you created in step 2. The following example shows how you add a transport called <tt>spamcheck</tt>, defined as a Unix service. By defining the transport as shown, you specify that the mail transport will use Postfix's <tt>pipe</tt> command to run ''/usr/local/bin/pf-spamfilt'' as user ''spamfilt'', and will pass the email address of the sender and the email addresses of recipients as command-line arguments to ''pf-spamfilt''. The flag argument includes the <tt>R</tt> flag (add a ''Return-Path'' header) and the <tt>q</tt> flag (quote the sender and recipient addresses for use in the command line).

# =========================================================================
# service type private unpriv chroot wakeup maxproc command + args
# (yes) (yes) (yes) (never) (50)
# =========================================================================
spamcheck unix - n n - - pipe
flags=Rq user=spamfilt argv=/usr/local/bin/pf-spamfilt ${sender} ${recipient}
</div></li>

<li><div>Direct Postfix to use the new mail transport as a content filter for the <tt>smtpd</tt> daemon. Replace this line in ''master.cf'':

smtp inet n - - - - smtpd

with these two lines:

smtp inet n - - - - smtpd
-o content_filter=spamcheck:
</div></li>

<li><div>If you always want to use per-user preferences, instruct Postfix to call the <tt>spamcheck</tt> transport with only a single recipient per message by adding this line to ''main.cf'':

spamcheck_destination_recipient_limit = 1
</div></li>

<li><div>Run <tt>postfix reload</tt> to re-read the configuration files. Test the system by sending an email from the Internet and see whether SpamAssassin is called to check the message.
</div></li>

</ol>

=== Using a Daemon as a Content Filter ===

Although it's more complicated to run a daemonized content filter, most larger sites will want to do so in order to avoid the overhead associated with starting the content filter for each email and running <tt>sendmail</tt> for reinjection. In the daemonized approach, the filter listens on a TCP port bound to the loopback address (127.0.0.1). On receiving a message from the Internet, Postfix connects to the filter daemon and relays the message using the SMTP or LMTP protocol.

The daemon can reject the message during the SMTP/LMTP transaction, which will cause Postfix to bounce the message, or the daemon can accept the message, modify it, and reinject it by SMTP. To prevent mail loops, Postfix must run a second <tt>smtpd</tt> daemon, bound to another TCP port on the loopback address. The second <tt>smtpd</tt> is configured to accept messages without rerunning the filter (or performing the checks that would normally be performed on a message received from the Internet).

To use a daemon as a content filter requires five steps:

<ol>
<li><div>Install a daemon that performs content-filtering in the fashion that Postfix expects. [[SpamAssassin/Integrating SpamAssassinwith Postfix#Building a Spam-Checking Gateway|Section 6.4]] provides an example. Typically, you will need to know or configure:

* The port on which the daemon accepts incoming messages to check (e.g., 10024).
* The protocol (SMTP or LMTP) by which the daemon expects to receive an incoming message.
* The port to which the daemon will connect to reinject a message to Postfix (e.g., 10025).
* The user that will run the daemon. Ideally, you should run daemons under a single-purpose, non-''root'' user.
</div></li>

<li><div>Define a new mail transport in ''master.cf'' that sends mail to the daemon. In the following example, the transport is called <tt>spamcheck</tt> and is defined as a Unix service that will use Postfix's <tt>smtp</tt> command. You can use the <tt>disable_dns_lookups</tt> option to save overhead, as you know that the transport will be configured to relay mail to your loopback IP address, so the daemon will never need to perform a DNS MX lookup. The example uses the maxproc feature in ''master.cf'' to limit the number of messages that can use this mail transport at one time to two.

# =========================================================================
# service type private unpriv chroot wakeup maxproc command + args
# (yes) (yes) (yes) (never) (50)
# =========================================================================
spamcheck unix - - n - 2 smtp
-o disable_dns_lookups=yes

<div class="tip">
'''Tip'''

If you are using Postfix 2.0 or later, you can define the <tt>spamcheck</tt> transport to use Postfix's <tt>lmtp</tt> command instead of <tt>smtp</tt>. The LMTP protocol has some advantages over SMTP—notably, LMTP servers (including <tt>amavisd</tt>) can return individual accept/refuse codes for each message recipient during an LMTP transaction. Postfix's <tt>lmtp</tt> client can also cache connections to an LMTP server for greater performance. Bugs in the <tt>lmtp</tt> client existed in Postfix versions earlier than 2.0 so using <tt>smtp</tt> is recommended with these versions.
</div>
</div></li>

<li><div>Define a new mail transport that receives mail from the daemon in ''master.cf.'' This transport will use Postfix's <tt>smtpd</tt> daemon and is defined by the IP address and port number on which it will listen (127.0.0.1 and 10025, respectively). <tt>smtpd</tt> is an <tt>inet</tt> service, and many option parameters are provided to prevent further filtering and to restrict access to this mail transport to the local host only. Here is an example of such a definition in ''master.cf'':

# =========================================================================
# service type private unpriv chroot wakeup maxproc command + args
# (yes) (yes) (yes) (never) (50)
# =========================================================================
127.0.0.1:10025 inet n - n - - smtpd
-o content_filter=
-o myhostname=localhost.''yourdomain''
-o local_recipient_maps=
-o relay_recipient_maps=
-o smtpd_restriction_classes=
-o smtpd_client_restrictions=
-o smtpd_helo_restrictions=
-o smtpd_sender_restrictions=
-o smtpd_recipient_restrictions=permit_mynetworks,reject
-o mynetworks=127.0.0.0/8
-o strict_rfc821_envelopes=yes
-o smtpd_error_sleep_time=0
-o smtpd_soft_error_limit=1001
-o smtpd_hard_error_limit=1000

<div class="warning">
'''Warning'''

The <tt>-o myhostname=localhost</tt>.<tt>''yourdomain''</tt> option is important if the content filter issues the SMTP HELO command with the same hostname that it originally received from Postfix. If Postfix sees a HELO from itself, it rejects the connection to avoid a mail loop. By telling the new <tt>smtpd</tt> that its hostname is something else, you prevent this problem.
</div>
</div></li>

<li><div>Direct Postfix to the use the daemon's mail transport as a content filter for mail received by the primary <tt>smtpd</tt> daemon. Replace this line in ''master.cf'':

smtp inet n - - - - smtpd

with these two lines:

smtp inet n - - - 2 smtpd
-o content_filter=spamcheck:[127.0.0.1]:10024

The primary <tt>smtpd</tt> daemon will filter incoming messages by passing them to the <tt>spamcheck</tt> mail transport that is listening on port 10024 of the loopback address 127.0.0.1.
</div></li>

<li><div>Run <tt>postfix reload</tt> to re-read the configuration files. Test the system by sending email from the Internet.
</div></li>

</ol>

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-FIG-2|Figure 6-2]] illustrates this configuration.

<div id="spamassassin-CHP-6-FIG-2">
'''Figure 6-2. Postfix with a daemonized content filter'''

[[Image:SpamAssassin_I_6_tt102.png|Postfix with a daemonized content filter]]
</div>

=== Filtering Before Address-Rewriting ===

The Postfix queue manager invokes content filters once it has queued a message. A potential problem with the simple content-filtering approaches outlined earlier is that the messages to be filtered have passed through the <tt>cleanup</tt> service on their way to the queue, and <tt>cleanup</tt> performs virtual address lookups and address canonicalization—that is, <tt>cleanup</tt> may rewrite addresses in message headers. Accordingly, the message that Postfix sends to the content filter (and thus to SpamAssassin) to check is not exactly the same as the message that Postfix received. The changes to addresses may rob SpamAssassin's rules (or the Bayesian classifier) of useful determinants of spam.

If you are running Postfix 2.0 or later, you can fix this problem by setting up a separate, <tt>pre-cleanup</tt> service that does not perform address canonicalization. Messages received by Postfix's <tt>smtpd</tt> and <tt>pickup</tt> can be routed through the <tt>pre-cleanup</tt> and then to the queue. Filter-checked messages received by the second <tt>smtpd</tt> instance can then be routed through the standard <tt>cleanup</tt> service for address-rewriting before returning to the queue for further delivery processing.

To use a two-cleanup design, set up a daemonized filter configuration as described in the previous section and then make the following configuration changes:

<ol>
<li><div>Add a new <tt>pre-cleanup</tt> service to ''/etc/postfix/master.cf'' that calls the <tt>cleanup</tt> daemon but turns off address canonicalization:

pre-cleanup unix n - n - 0 cleanup
-o canonical_maps=
-o sender_canonical_maps=
-o recipient_canonical_maps=
-o masquerade_domains=
-o virtual_alias_maps=
</div></li>

<li><div>Configure <tt>smtpd</tt> and <tt>pickup</tt> to use the <tt>pre-cleanup</tt> service in ''/etc/postfix/master.cf'' by changing their entries from

smtp inet n - - - - smtpd
pickup fifo n - - 60 1 pickup

to

smtp inet n - - - - smtpd
-o cleanup_service_name=pre-cleanup
pickup fifo n - - 60 1 pickup
-o cleanup_service_name=pre-cleanup
</div></li>

<li><div>To improve performance, modify the entry for <tt>cleanup</tt> so that it does not perform some of the message checks that will have already been handled by <tt>pre-cleanup</tt>. You can turn off any checks that would have already been performed on message headers (via the Postfix <tt>header_checks</tt>, <tt>mime_header_checks</tt>, or <tt>nested_header_checks</tt> options) or bodies (via the Postfix <tt>body_checks</tt> options) by defining each option to be empty:

cleanup unix n - n - 0 cleanup
-o header_checks=
-o mime_header_checks=
-o nested_header_checks=
-o body_checks=
</div></li>

</ol>

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-FIG-3|Figure 6-3]] illustrates this configuration.

<div id="spamassassin-CHP-6-FIG-3">
'''Figure 6-3. Postfix with a daemonized content filter and two cleanup services'''

[[Image:SpamAssassin_I_6_tt107.png|Postfix with a daemonized content filter and two cleanup services]]
</div>

== Building a Spam-Checking Gateway ==

Several content-filtering daemons that call SpamAssassin are available for Postfix. This section provides a complete sample installation of amavisd-new, a particularly efficient filter that supports both spam-checking and virus-checking. amavisd-new is written in Perl and available at ''http://www.ijs.si/software/amavisd/''. The version used in this chapter's example is 20030616-p9, which supports both SpamAssassin 2.63 and SpamAssassin 3.0.

amavisd-new is based on amavis, another virus-scanning package that is also actively developed and widely used. Although amavisd-new's most important program is also named <tt>amavisd</tt>, amavisd-new has developed separately and is a significantly different package. Some of amavisd-new's features include:

* avisd-new was specifically developed and tested for Postfix as a daemonized content filter.
* Messages can be rejected based on MIME type or extensions of attached filenames.
* Messages can be checked with multiple virus scanners, and messages carrying viruses can be refused, discarded, or quarantined.
* SpamAssassin can be invoked on a message, and spam can be refused, discarded, quarantined, or tagged.
* Per-user configuration of amavisd-new is possible through an SQL or LDAP database.

The rest of this chapter details the installation, configuration, and operation of amavisd-new as an example of a full-scale, daemonized, content filter approach to using SpamAssassin with Postfix. amavisd-new's other functions, such as virus-checking, are mentioned but not covered in detail; read the documentation to learn more about these other amavisd-new features.

=== Installing amavisd-new ===

amavisd-new is written in Perl, and invokes SpamAssassin through the ''Mail::SpamAssassin'' Perl modules. Because amavisd-new itself is a daemon, you do not need to run <tt>spamd</tt>. It's easiest to install SpamAssassin (and your antivirus software) first, and then install amavisd-new. amavisd-new also requires several other Perl modules, including: ''Archive::Tar'', ''Archive::Zip'', ''Compress::Zlib'', ''Convert::TNEF'', ''Convert::UUlib'', ''MIME::Base64'', ''MIME::Tools'', ''Mail::Internet'', ''Net::Server'', ''Net::SMTP'', ''Digest::MD5'', ''IO::Stringy'', ''Time::Hires'', and ''Unix::Syslog''. If you plan to do per-user configuration of amavisd-new through SQL or LDAP, you'll need appropriate Perl modules for database access (''DBI'' and a ''DBD::'' module for SQL, or ''Net::LDAP'' for LDAP). You can install most of these Perl modules using CPAN as described in [[SpamAssassin/SpamAssassin Basics|Chapter 2]].

<div class="warning">
'''Warning'''

The standard version of ''MIME::Tools'' 5.411a has bugs. Install ''MIME::Tools'' 6 or later from ''http://search.cpan.org/dist/MIME-tools''.
</div>

Begin the install process by creating a new user account and group for running amavisd-new; the usual name for both the user and group is ''amavis''. This user will own amavisd-new's files, and the user (or group) must have access to SpamAssassin's configuration and database files as well. The user's home directory is traditionally ''/var/amavis'', but you can create it anywhere that fits your system's needs.

amavisd-new uses several important directories. It keeps two files in its home directory, one containing its current process ID, and the other used for locking. It uses a working directory for unpacking email messages and scanning them; by default, this is the home directory or the ''tmp'' subdirectory of the home directory. For optimal performance, this directory should be on a fast disk—even a RAM disk if your operating system supports it and you have enough memory to spare. amavisd-new stores quarantined email messages in ''/var/virusmails'' by default, but you can select any directory for this purpose. Speed is not so critical with this directory, and it should never be located on a RAM disk because you will often want to be sure that you can access quarantined files. If you plan to physically locate these directories somewhere unusual (e.g., to mount new disk partitions or a RAM disk as ''/var/amavis/tmp''), you should do so before you install amavisd-new. The directories should be owned by user and group ''amavis'' and should not be world-readable or world-searchable.

Next, download the amavisd-new source code from ''http://www.ijs.si/software/amavisd/'' and unpack it. As ''root'', copy the <tt>amavisd</tt> script to a suitable directory for executable daemons (e.g., ''/usr/bin'', ''/usr/local/sbin'', etc.), <tt>chown</tt> it to ''root'', and use <tt>chmod</tt> to set its permissions to 0755 (readable and executable by all users, writable only by ''root'').

Copy the ''amavisd.conf'' file to a suitable directory for configuration files (e.g., ''/etc'', ''/etc/amavis'', ''/usr/local/etc'', etc.). By default, <tt>amavisd</tt> expects to find this file in ''/etc'', and if you locate it anywhere else, you will have to add an extra command-line option (<tt>-c</tt> <tt>''filename''</tt>) when invoking <tt>amavisd</tt> to tell it the new location. The ''amavisd.conf'' file should also be owned by ''root'' and should have permissions 0644 (readable by all, writable only by ''root'').

=== Configuring amavisd-new ===

amavisd-new is configured through the ''amavisd.conf'' file. ''amavisd.conf'' is parsed as a Perl script and can contain any legal Perl code. Because it is parsed as Perl, you must escape any at sign (@), question mark ($), or backslash (\) characters that appear in double-quoted strings by prepending a backslash. For example:

$some_email = "sample\@example.com";

Email addresses must be specified without surrounding brackets and without RFC 2821 quoting.

Edit ''amavisd.conf'' to set the (many) available configuration options to control <tt>amavisd</tt>. The file is organized in logical sections; the most important options are in Section I, but you'll need to read through the entire file to customize the system completely. The following sections explain commonly modified portions of the configuration file in the order that you'll encounter them.

==== Essential options ====

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-1|Example 6-1]] shows the first portion of the configuration file and the settings of the essential options. Set <tt>$MYHOME</tt> to the ''amavis'' user's home directory. Set <tt>$mydomain</tt> to your domain name. Set <tt>$daemon_user</tt> and <tt>$daemon_group</tt> to name of the ''amavis'' user and group. Set <tt>$TEMPBASE</tt> to the directory to use for unpacking messages; for improved performance, this directory should be a mounted RAM disk.

<div id="spamassassin-CHP-6-EX-1">
'''Example 6-1. Essential settings in amavisd.conf'''

# Section I - Essential daemon and MTA settings
#

# $MYHOME serves as a quick default for some other configuration settings.
# More refined control is available with each individual setting further down.
# $MYHOME is not used directly by the program. No trailing slash!
'''$MYHOME = '/var/amavis'; # (default is '/var/amavis')'''

# $mydomain serves as a quick default for some other configuration settings.
# More refined control is available with each individual setting further down.
# $mydomain is never used directly by the program.
'''$mydomain = 'example.com'; # (no useful default)'''

# Set the user and group to which the daemon will change if started as root
# (otherwise just keeps the UID unchanged, and these settings have no effect):
'''$daemon_user = 'amavis'; # (no default; customary: vscan or amavis)'''
'''$daemon_group = 'amavis'; # (no default; customary: vscan or amavis)'''

# Runtime working directory (cwd), and a place where
# temporary directories for unpacking mail are created.
# (no trailing slash, may be a scratch file system)
#$TEMPBASE = $MYHOME; # (must be set if other config vars use is)
'''$TEMPBASE = "$MYHOME/tmp"; # prefer to keep home dir /var/amavis clean?'''

</div>

==== MTA options ====

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-2|Example 6-2]] shows the settings of the MTA options. Set <tt>$forward_method</tt> to the method you will use to reinject checked mail to the MTA. For Postfix, this method should be of the form <tt>smtp</tt>:<tt>''ipaddress''</tt>:<tt>''portnumber''</tt>, where <tt>''ipaddress''</tt> is the IP address of the Postfix system (usually 127.0.0.1) and <tt>''portnumber''</tt> is the TCP port number on which the second <tt>smtpd</tt> instance is running. Because amavisd-new was designed with Postfix in mind, you may not need to change this section at all.

<div id="spamassassin-CHP-6-EX-2">
'''Example 6-2. MTA options in amavisd.conf'''

# MTA SETTINGS, UNCOMMENT AS APPROPRIATE,
# both $forward_method and $notify_method default to 'smtp:127.0.0.1:10025'

# POSTFIX, or SENDMAIL in dual-MTA setup, or EXIM V4
# (set host and port number as required; host can be specified
# as IP address or DNS name (A or CNAME, but MX is ignored)
'''$forward_method = 'smtp:127.0.0.1:10025'; # where to forward checked mail'''
$notify_method = $forward_method; # where to submit notifications
</div>

==== Daemon process options ====

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-3|Example 6-3]] shows the daemon process settings. The most important setting is <tt>$max_servers</tt>, which you should set to the same number of <tt>smtp</tt> processes you have configured Postfix to use concurrently to send messages to amavisd-new.

<div id="spamassassin-CHP-6-EX-3">
'''Example 6-3. Daemon process settings in amavisd.conf'''

# Net::Server pre-forking settings
# You may want $max_servers to match the width of your MTA pipe
# feeding amavisd, e.g. with Postfix the 'Max procs' field in the
# master.cf file, like the '2' in the: smtp-amavis unix - - n - 2 smtp
#
'''$max_servers = 2; # number of pre-forked children (default 2)'''

</div>

==== Distinguishing local domains ====

amavisd-new distinguishes local domains from remote domains. Recipients at local domains can take advantage of several per-user features that are not directly available to remote recipients, including local customization of SpamAssassin settings. [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-4|Example 6-4]] shows that part of ''amavisd.conf''that bears on per-user customization.

You can provide your local domain information in several ways. You can set the <tt>@local_domains_acl</tt> array to a list of domain names that should be considered local. You can set the <tt>%local_domains</tt> hash instead, providing local domain names as keys and 1 as their values, or use the <tt>read_hash</tt> function to read in a list of local domain names from an external file. Finally, you can define local domain names by invoking the <tt>new_RE</tt> function with a regular expression that matches the local domain names and assigning the result to <tt>$local_domains_re</tt>. No matter which method you use, adding a period (.) to the beginning of a domain name means that the domain and any subdomains should all be considered local.

[[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-4|Example 6-4]] shows this section of the configuration file, using the <tt>@local_domains_acl</tt> variable to define local domains.

<div id="spamassassin-CHP-6-EX-4">
'''Example 6-4. Setting local domains in amavisd.conf'''

# Lookup list of local domains (see README.lookups for syntax details)
#
# NOTE:
# For backwards compatibility the variable names @local_domains (old) and
# @local_domains_acl (new) are synonyms. For consistency with other lookups
# the name @local_domains_acl is now preferred. It also makes it more
# obviously distinct from the new %local_domains hash lookup table.
#
# local_domains* lookup tables are used in deciding whether a recipient
# is local or not, or in other words, if the message is outgoing or not.
# This affects inserting spam-related headers for local recipients,
# limiting recipient virus notifications (if enabled) to local recipients,
# in deciding if address extension may be appended, and in SQL lookups
# for non-fqdn addresses. Set it up correctly if you need features
# that rely on this setting (or just leave empty otherwise).
#
# With Postfix (2.0) a quick reminder on what local domains normally are:
# a union of domains specified in: $mydestination, $virtual_alias_domains,
# $virtual_mailbox_domains, and $relay_domains.
#
#@local_domains_acl = ( ".$mydomain" ); # $mydomain and its subdomains
# @local_domains_acl = qw( ); # default is empty, no recipient treated as local
# @local_domains_acl = qw( .example.com );
# @local_domains_acl = qw( .example.com !host.sub.example.net .sub.example.net );
# @local_domains_acl = ( ".$mydomain", '.example.com', 'sub.example.net' );
'''@local_domains_acl = qw/'''
'''example.com'''
'''example.net'''
'''example.org'''
'''/;'''

# or alternatively(A), using a Perl hash lookup table, which may be assigned
# directly, or read from a file, one domain per line; comments and empty lines
# are ignored, a dot before a domain name implies its subdomains:
#
#read_hash(\%local_domains, '/var/amavis/local_domains');

#or alternatively(B), using a list of regular expressions:
# $local_domains_re = new_RE( qr'[@.]example\.com$'i );
</div>

==== Postfix-specific options ====

Section II of ''amavsid.conf'' specifies options that differ by MTA and is shown in [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-5|Example 6-5]]. Because amavisd-new was designed with Postfix in mind, you need to modify relatively few options. Set the <tt>$inet_socket_port</tt> variable to the TCP port number on which <tt>amavisd</tt> should listen for SMTP connections from Postfix. To prevent this port from being accessed by remote hosts, set <tt>$inet_socket_bind</tt> to '<tt>127.0.0.1</tt>', which will cause <tt>amavisd</tt> to listen only on the loopback interface and not on other network interfaces. If you want to allow access by a set of remote hosts (if, for example, you want to run <tt>amavisd</tt> on a different host than your Postfix MTA), don't set <tt>$inet_socket_bind</tt> but do set <tt>@inet_acl</tt> to a list of IP addresses for hosts that should be permitted to connect. This list is checked in order; the first match wins. You may specify these IP addresses as single addresses or as CIDR-style <tt>''address''</tt> <tt>/</tt> <tt>''netmask''</tt> (e.g., <tt>192.168.1/255.255.255.0</tt>) or <tt>''address''</tt> <tt>/</tt> <tt>''bits''</tt> (e.g., <tt>192.168.1/24</tt>) ranges.<ref>"CIDR" stands for Classless Interdomain Routing.</ref> You may prepend an IP address with an exclamation point (<tt>!)</tt> to disallow connections from that address, even if a larger range that contains the address is permitted (e.g., <tt>!192.168.0/24 192.168/16</tt> to allow all 192.168.*.* addresses except 192.168.0.* addresses).

<div id="spamassassin-CHP-6-EX-5">
'''Example 6-5. Postfix-specific options in amavisd.conf'''

# SMTP SERVER (INPUT) PROTOCOL SETTINGS (e.g. with Postfix, Exim v4, ...)
# (used when MTA is configured to pass mail to amavisd via SMTP or LMTP)
'''$inet_socket_port = 10024;''' # accept SMTP on this local TCP port
# (default is undef, i.e. disabled)
# multiple ports may be provided: $inet_socket_port = [10024, 10026, 10028];

# SMTP SERVER (INPUT) access control
# - do not allow free access to the amavisd SMTP port !!!
#
# when MTA is at the same host, use the following (one or the other or both):
'''$inet_socket_bind = '127.0.0.1';''' # limit socket bind to loopback interface
# (default is '127.0.0.1')
'''@inet_acl = qw( 127.0.0.1 );''' # allow SMTP access only from localhost IP
# (default is qw( 127.0.0.1 ) )
</div>

==== Logging options ====

Section III of ''amavisd.conf'' deals with logging and is shown in [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-6|Example 6-6]]. <tt>amavisd</tt> can log using ''syslog'', or it can log to a file. Set <tt>$DO_SYSLOG</tt> to 1 to instruct <tt>amavisd</tt> to use ''syslog'' for logging; you can change the ''syslog'' facility and priority using the <tt>$SYSLOG_LEVEL</tt> variable. Set <tt>$DO_SYSLOG</tt> to 0 to instruct <tt>amavisd</tt> to log to a file; set <tt>$LOGFILE</tt> to specify the filename. The log file must be in a directory the ''amavis'' user can write to.

The <tt>$log_level</tt> variable controls the amount of detail that <tt>amavisd</tt> logs. A log level of 0 results in minimal logging; a log level of 5 produces highly verbose logging.

<div id="spamassassin-CHP-6-EX-6">
'''Example 6-6. Logging options'''

# Section III - Logging
#

# true (e.g. 1) => syslog; false (e.g. 0) => logging to file
'''$DO_SYSLOG = 1;''' # (defaults to false)
'''#$SYSLOG_LEVEL = 'user.info';''' # (defaults to 'mail.info')

# Log file (if not using syslog)
$LOGFILE = "$MYHOME/amavis.log"; # (defaults to empty, no log)

#NOTE: levels are not strictly observed and are somewhat arbitrary
# 0: startup/exit/failure messages, viruses detected
# 1: args passed from client, some more interesting messages
# 2: virus scanner output, timing
# 3: server, client
# 4: decompose parts
# 5: more debug details
'''$log_level = 1;''' # (defaults to 0)
</div>

==== Spam-handling options ====

Most of Section IV of ''amavisd.conf'' focuses on detailed configuration of how <tt>amavisd</tt> will handle detected viruses and spam. Only those options related to spam handling are discussed in detail here.

When <tt>amavisd</tt> detects a spam email, it logs a message to its log file by default. It can also quarantine the email and/or notify an administrator. It can then generate a bounce message to the sender. Finally, it can either accept and deliver the message, or discard the message. Many different configuration variables are involved in these decisions. Unfortunately, the order of the variables in the file is largely the reverse of the order in which they are checked during the spam-handling process.

Enable a spam quarantine by setting the following two variables:

;<tt>$QUARANTINEDIR</tt>
: Set this variable to the directory or mailbox file in which to store the quarantined messages.
;<tt>$spam_quarantine_method</tt>
: Set this variable to "<tt>local:spam-%b-%i-%n</tt>", to specify the filename format for quarantined spam messages. In that format, <tt>%b</tt> expands to a digest of the message body, <tt>%i</tt> expands to the date and time, and <tt>%n</tt> expands to the <tt>amavisd</tt> message identifier.

To control the spam quarantine on a per-recipient basis, set the <tt>$spam_quarantine_to</tt> variable to a reference to a hash, keyed by the recipient's address, like this:

$local_delivery_aliases{'sam-spam'} = '/home/sam/mail/spam';

$spam_quarantine_to =
{ 'example.net' => undef
'jane@example.com' => 'spam@jane.example.com',
'sam@example.com' => 'sam-spam',
'example.com' => 'spam-quarantine',
};

If the hash value is undefined or empty, spam is not quarantined. In this example, spam sent to ''example.net'' will not be quarantined at all. If the hash value contains an asterisk (<tt>@)</tt>, spam will be forwarded. Spam sent to ''jane@example.com'' will be forwarded to ''spam@jane.example.com''. Otherwise, the hash value is looked up in the <tt>%local_delivery_aliases</tt> hash, and the spam is quarantined in the file or directory returned from that lookup. If the lookup fails, <tt>amavisd</tt> logs a warning and doesn't quarantine the message. Several default local delivery aliases are defined in <tt>amavisd</tt>, including <tt>spam-quarantine</tt>, which quarantines a message in <tt>$QUARANTINEDIR</tt>. In the preceding example, spam to ''sam@example.com'' will be quarantined in the ''/home/sam/mail/spam'' mailbox (or mail directory), and other spam to ''example.com'' will be quarantined in the default directory.

You can also write your <tt>$spam_quarantine_to</tt> policies with regular expressions:

$spam_quarantine_to = new_RE(
[qr/^sam@example\.com$/i => 'sam-spam'],
[qr/^jane@example\.com$/i => 'spam@jane.example.com'],
[qr/@example\.com$/i => 'spam-quarantine'],
[qr/@example\.net$/i => undef]
);

Because regular expressions are matched in the order that you list them, you must put the most specific matches first (<tt>/^sam@example\.com/</tt> before <tt>/@example\.com/</tt>). Because regular expression matches are case sensitive, you should generally include the <tt>i</tt> (case-insensitive) modifier to the <tt>qr//</tt> operator.

Spam to recipients that don't match any entry in <tt>$spam_quarantine_to</tt> will not be quarantined, so if you want to quarantine all spam by default, you should either provide a rule for each domain you receive mail for, or use the regular expression approach and include a rule for the regular expression <tt>qr/.*/</tt> at the end.

amavisd-new is smart about per-recipient policies like <tt>$spam_quarantine_to</tt>. If some message recipients choose to quarantine spam and some do not, amavisd-new will honor those preferences. If multiple recipients choose the same quarantine destination, a message sent to two or more of those recipients is written only once to the quarantine destination .

You can also make quarantine decisions based on a spam's sender in an analogous way using <tt>$spam_quarantine_bysender_to</tt>, but this alternative is rarely useful, as spammers often falsify their sending addresses or use throwaway accounts.

To notify an administrator when spam is received, set <tt>$spam_admin</tt> to the address of the administrator. These notifications are disabled by default. Consider carefully before setting <tt>$spam_admin</tt> to the email address of a real person; given the amount of spam on the Internet today, it's easy to get hundreds of notifications or more, and difficult to know what to do about them. An alternative that might be useful for service providers is to set <tt>$spam_admin</tt> to a reference to a hash based on the spam sender's address, in order to detect outgoing spam from customers. For example, to notify the security staff about spam being sent from the ''example.com'' domain but nowhere else, use:

$spam_admin =
{ '.example.com' => 'security@example.com',
'.' => undef
};

The <tt>$final_spam_destiny</tt> variable controls the final disposition of spam recognized by <tt>amavisd</tt>. Although this variable appears first in this section of the configuration file, it is consulted last during spam-handling. When using amavisd-new with Postfix, there are three useful settings for <tt>$final_spam_destiny</tt>:

* Set <tt>$final_spam_destiny</tt> to <tt>D_PASS</tt> to accept and deliver all spam. Use this strategy when your goal is simply to tag spam and let clients do their own filtering. If you set <tt>$warnspamsender</tt> to 1, you will also generate a bounce message to the sender. I don't recommend this, however, as spammers often falsify return addresses.
* Set <tt>$final_spam_destiny</tt> to <tt>D_DISCARD</tt> to discard spam that scores above a "kill level" (specified in Section VII of ''amavisd.conf''); spam below the kill level will be tagged and accepted. Use this strategy when your goal is to reduce bandwidth or storage space by dropping messages that are very likely to be spam and tagging others.
* Set <tt>$final_spam_destiny</tt> to <tt>D_BOUNCE</tt> to generate a bounce message to the sender and then discard the message. Because spammers often falsify their return addresses, you will rarely want to use this setting.

==== Recipient whitelists ====

Section V of the ''amavisd.conf'' file focuses on spam policy controls for individual recipients or recipient domains. Its function is analogous to SpamAssassin's <tt>whitelist_to</tt> feature. You can prevent any spam-checking at all, or you can continue to perform spam-checking but prevent spam-handling actions for detected spam.

To prevent any spam-checking at all for email sent to a recipient, set the <tt>@bypass_spam_checks_acl</tt>, <tt>%bypass_spam_checks</tt>, or <tt>$bypass_spam_checks_re</tt> variables. You may use domain names instead of recipient addresses to whitelist all mail sent to a given domain. Here's how you'd set the <tt>@bypass_spam_checks_acl</tt> array to a list of recipients that want to opt out of spam-checking:

@bypass_spam_checks_acl = qw( chris@example.com robin@example.com);

To use the <tt>%bypass_spam_checks</tt> hash instead, provide recipient addresses as keys and 1 as their values. You might prefer this approach to using <tt>@bypass_spam_checks_acl</tt> if you have a very long list of recipients, because searching a hash is much faster than searching a long list. You can also use the <tt>read_hash</tt> function to read in a list of recipients from an external file and assign them to <tt>%bypass_spam_checks</tt>. This is useful when you want to keep a long list of recipients separate from the ''amavisd.conf'' file. For example:

read_hash(\%bypass_spam_checks, '/var/amavis/bypass_spam');

Finally, you can define recipients to opt out by providing a list of regular expressions that match recipient addresses to the <tt>new_RE</tt> function and assigning the result to <tt>$bypass_spam_checks</tt>. This method is useful when you can parsimoniously specify your whitelisted recipients with a regular expression or two. For example:

$bypass_spam_checks = new_RE(qr'^(chris|robin)@example\.com'i);

<div class="tip">
'''Tip'''

Spam checks are bypassed only if all of the recipients of a message have been added to one of these variables. If even one recipient is not listed, spam-checking will still be performed. To ensure that spam is still delivered to whitelisted recipients in such cases, use the "spam_lovers" features discussed next.

If spam checks are bypassed, SpamAssassin's Bayesian classifier will not have an opportunity to learn from a message, whether or not it is spam.
</div>

To prevent spam-handling (e.g., tagging or quarantine) from being performed for a recipient when a message has been checked and designated as spam, set the <tt>@spam_lovers_acl</tt>, <tt>%spam_lovers</tt>, or <tt>$spam_lovers_re</tt> variables. These variables are set analogously to the <tt>@bypass_spam_checks_acl</tt>, <tt>%bypass_spam_checks</tt>, and <tt>$bypass_spam_checks_re</tt> variables.

In [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-7|Example 6-7]], ''jane@example.com'' always receives every message, spam or not, and spam-tagging is skipped when messages are addressed to her alone. In addition, if a message is destined for a domain other than ''example.com'' (i.e., it's outgoing mail from our domain), spam-tagging is skipped. ''postmaster@example.com'' also receives every message, but spam-checking is still performed.

<div id="spamassassin-CHP-6-EX-7">
'''Example 6-7. Whitelisting by recipient'''

# Avoid running a spam check if jane is the only recipient, or if
# all recipients are outside of ''example.com''
@bypass_spam_checks_acl = ('jane@example.com', '!.example.com');

# Even if we run a check, don't act on the results for jane or postmaster
@spam_lovers_acl = ('jane@example.com', 'postmaster@example.com');
</div>

==== Sender whitelists and blacklists ====

<tt>amavisd</tt> can maintain whitelists and blacklists of message senders. It uses a message's envelope address (the one provided in the SMTP MAIL FROM command) as the sender address. Whitelisting ensures that <tt>amavisd</tt> will allow mail from a whitelisted sender to continue to its intended recipients; blacklisting ensures that <tt>amavisd</tt> will treat mail from a blacklisted sender as spam.

<div class="tip">
'''Tip'''

<tt>amavisd</tt>'s whitelist and blacklist features do not interact in the same manner as SpamAssassin's. For example, if an address is both whitelisted and blacklisted in SpamAssassin, neither takes effect. If an address is both whitelist and blacklisted in <tt>amavisd</tt>, both take effect—the message is marked as spam and also allowed to pass to the recipient.
</div>

As with other <tt>amavisd</tt> address-matching features, you can specify addresses to globally whitelist by an array, keys of a hash, or by a set of regular expressions. Set the <tt>@whitelist_sender_acl</tt> array to a list of sender addresses to whitelist. To use the <tt>%whitelist_sender</tt> hash instead, provide sender addresses as keys and 1 as their values, or use the <tt>read_hash</tt> function to read in a list of senders from an external file. Finally, you can specify senders to whitelist by providing a list of regular expressions that match the sender addresses to the <tt>new_RE</tt> function and assigning the result to <tt>$whitelist_sender_re</tt>. You may use domain names instead of sender addresses to whitelist all mail sent from a given domain.

You can use a similar set of variables for globally blacklisting senders. The array is <tt>@blacklist_sender_acl</tt>, the hash is <tt>%blacklist_sender</tt>, and the regular expression version is <tt>$blacklist_sender_re</tt>.

The default ''amavisd.conf'' defines <tt>$blacklist_sender_re</tt> and <tt>%whitelist_sender</tt> as shown in [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-8|Example 6-8]]. Many username patterns typical of spammers are blacklisted, such as ''investments''; many addresses of well-known security and vendor mailing lists are whitelisted. You can modify these definitions or use one of the other variables to add additional sender addresses to the whitelist or blacklist.

<div id="spamassassin-CHP-6-EX-8">
'''Example 6-8. Default blacklist and whitelist entries in amavisd.conf'''

$blacklist_sender_re = new_RE(
qr'^(bulkmail|offers|cheapbenefits|earnmoney|foryou|greatcasino)@'i,
qr'^(investments|lose_weight_today|market.alert|money2you|MyGreenCard)@'i,
qr'^(new\.tld\.registry|opt-out|opt-in|optin|saveonlsmoking2002k)@'i,
qr'^(specialoffer|specialoffers|stockalert|stopsnoring|wantsome)@'i,
qr'^(workathome|yesitsfree|your_friend|greatoffers)@'i,
qr'^(inkjetplanet|marketopt|MakeMoney)\d*@'i,
);

map { $whitelist_sender{lc($_)}=1 } (qw(
cert-advisory-owner@cert.org
owner-alert@iss.net
slashdot@slashdot.org
bugtraq@securityfocus.com
NTBUGTRAQ@LISTSERV.NTBUGTRAQ.COM
security-alerts@linuxsecurity.com
amavis-user-admin@lists.sourceforge.net
notification-return@lists.sophos.com
mailman-announce-admin@python.org
owner-postfix-users@postfix.org
owner-postfix-announce@postfix.org
owner-sendmail-announce@Lists.Sendmail.ORG
owner-technews@postel.ACM.ORG
lvs-users-admin@LinuxVirtualServer.org
ietf-123-owner@loki.ietf.org
cvs-commits-list-admin@gnome.org
rt-users-admin@lists.fsck.com
clp-request@comp.nus.edu.sg
surveys-errors@lists.nua.ie
emailNews@genomeweb.com
owner-textbreakingnews@CNNIMAIL12.CNN.COM
spamassassin-talk-admin@lists.sourceforge.net
yahoo-dev-null@yahoo-inc.com
returns.groups.yahoo.com
));
</div>

amavisd-new also supports per-recipient blacklists and whitelists of senders. Per-recipient lists override the global lists. Use the <tt>$per_recip_blacklist_sender_lookup_tables</tt> and <tt>$per_recip_whitelist_sender_lookup_tables</tt> variables to specify these lists. Each variable is a reference to a hash keyed by the recipient's address (or domain). The hash value should be a reference to an array of sender addresses, a reference to a hash keyed on sender addresses (with hash values of 1), a call to the <tt>read_hash</tt> function to read the addresses from a file, or a call to <tt>new_RE</tt> with a list of regular expressions to match sender addresses against. For example, you could add the following code to ''amavisd.conf'' to maintain a list of whitelisted senders for ''jane@example.com'' in the file ''/etc/mail/jane-whitelist'':

$per_recip_whitelist_sender_lookup_tables =
{ 'jane@example.com' => read_hash('/etc/mail/jane-whitelist')
};

==== SpamAssassin settings ====

Several variables in ''amavisd.conf'' affect the way that <tt>amavisd</tt> invokes SpamAssassin or the actions it takes based on a message's score from SpamAssassin:

;<tt>$sa_local_tests_only</tt>
: Set this variable to 1 if you want SpamAssassin to skip network-based tests. It defaults to 0 (perform network-based tests).
;<tt>$sa_auto_whitelist</tt>
: Set <tt>this variable</tt> to 1 to enable SpamAssassin's autowhitelist feature. It defaults to (no autowhitelist). Specify the location of the autowhitelist database in SpamAssassin's sitewide configuration file, ''local.cf''. Be sure that the ''amavis'' user has permission to read from and write to the database.
;<tt>$sa_mail_body_size_limit</tt>
: If you set this variable to a size (in bytes), messages larger than the given size will not be checked for spam. This conserves system resources, as SpamAssassin can take a long time to check large messages, and large messages are rarely spam. The variable is undefined by default, which implies no limit. A reasonable value might be 65536 (64Kb) or 102400 (100Kb).

<dl>
<dt><tt>$sa_tag_level_deflt</tt>
<dd>This variable determines the spam score at or above which ''X-Spam-Status'' and ''X-Spam-Level'' headers will be added to the message to show the spam status and level of the message. The default is 3, which is suitable for seeing which tests are and are not being triggered for suspicious messages. If you like to see the spam status of all messages, set this value to -10 or so.

This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag level as the hash value.
</dl>
<dl>
<dt><tt>$sa_tag2_level_deflt</tt>
<dd>This variable determines the spam score at or above which <tt>amavisd</tt> adds an ''X-Spam-Flag: YES'' header and an ''X-Spam-Report'' header to the message. It may also modify the ''Subject'' header to tag the message as spam. The default is 6.3.

This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag2_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag2 level as the hash value.
</dl>
<dl>
<dt><tt>$sa_kill_level_deflt</tt>
<dd>This variable determines the spam score at or above which <tt>amavisd</tt> will perform spam-handling on the message, such as quarantining the message, discarding it, notifying administrators, etc. By default, this variable is set to the value of <tt>$sa_tag2_level_deflt</tt> so spam-handling is performed on all spam detected. If you want to discard messages that are extremely likely to be spam and tag messages that are less likely to be spam, set this variable to a higher score (e.g., 12), and only messages above that level will be subject to special handling.

The variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_kill_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the kill level as the hash value.
</dl>;<tt>$sa_spam_modifies_subj</tt>
: If this variable is set to 1, <tt>amavisd</tt> may modify the ''Subject'' header of messages with spam scores above the <tt>$sa_tag2_level_dflt</tt> setting. You can also set this variable to a reference to a list of recipients who should have their ''Subject'' headers modified, a reference to a hash table keyed on recipients who should have their headers modified (with hash values of 1), or the return value of a <tt>new_RE( )</tt> call on a list of regular expressions to match against recipients who should have their headers modified. This variable is not defined by default.
;<tt>$sa_spam_subject_tag</tt>
: Set this variable to the string to prepend to the ''Subject'' header of spam messages when <tt>$sa_spam_modifies_subj</tt> is true. If you do not define this, ''Subject'' headers will never be modified. It is not defined by default; a common definition would be '<tt>*****SPAM*****</tt>'.

==== Storing recipient preferences in external databases ====

It's possible to store amavisd-new recipient preferences in an SQL or LDAP database. This can be useful if you want to permit users to modify their own preferences, particularly if you already use an SQL- or LDAP-based user directory. SQL and LDAP lookups override variables defined in ''amavisd.conf''.

Database entries indicate user preferences, including whether a user has opted out of spam-checking, whether <tt>amavisd</tt> should modify the ''Subject'' of spam messages, and user spam tag levels (tag, tag2, kill). Database entries may also specify sender addresses that the recipient wants to blacklist or whitelist.

To enable SQL lookups, define the variable <tt>@lookup_sql_dsn</tt> in ''amavisd.conf''. This variable should contain a list of references to three-element arrays that represent database connections. The first element of each array is a Perl ''DBI'' DSN that defines the database driver to use, the database name, and the name of the database server host. The second element is a database username that <tt>amavisd</tt> will provide for identification to the database server, and the third element is the associated password for authentication. The distributed ''amavisd.conf'' file provides the following commented-out example:

# @lookup_sql_dsn =
# ( ['DBI:mysql:database=mail;host=127.0.0.1;port=3306', 'user1', 'passwd1'],
# ['DBI:mysql:database=mail;host=host2', 'username2', 'password2'] );

In this example, <tt>amavisd</tt> will first attempt to connect to the MySQL database server on port 3306 of the local host in order to access the ''mail'' database. It will log into the database server as <tt>''user1''</tt> with password <tt>''passwd1''</tt>. If this connection fails, <tt>amavisd</tt> will try the next database server, a MySQL server running on <tt>''host2''</tt>, using user <tt>''username2''</tt> and password <tt>''password2''</tt>.

The file ''README_FILES/README.lookups'' in the amavisd-new source code provides definitions for a set of SQL tables that are suitable for configuring user policies and whitelists and blacklists in <tt>amavisd</tt>. You can add these tables to your SQL database and follow the instructions in ''README.lookups'' to add appropriate database queries to ''amavisd.conf''.

<div class="tip">
'''Tip'''

amavisd-new's SQL support should not be confused with SpamAssassin's SQL support. Each controls different aspects of mail-processing.
</div>

The amavisd-new source code includes an LDAP schema for an auxiliary class (amavisAccount) that can be added to user accounts. The class defines attributes that determine whether a user has opted out of spam-checking, whether <tt>amavisd</tt> should modify the ''Subject'' of spam messages, a user's desired spam tag levels (tag, tag2, kill), and sender addresses to blacklist or whitelist for a user.

To enable LDAP lookups, set the <tt>$enable_ldap</tt> variable in ''amavisd.conf'' to 1, and provide LDAP server information in the <tt>$default_ldap</tt> variable as a reference to a hash:

$default_ldap = {
hostname => '''ldap-server-hostname''',
tls => ''1'',
base => '''base DN for ldap searches''',
query_filter => '(&(objectClass=amavisAccount)(mail=%m))'}
};

For each preference for which <tt>amavisd</tt> can perform an LDAP query, you must define additional query parameters to specify (at minimum) the result attribute to be returned from the LDAP database to <tt>amavisd</tt>. Parameters left undefined will prevent LDAP queries from being performed for that preference. The <tt>amavisd</tt> source code provides the examples in [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-9|Example 6-9]].

<div id="spamassassin-CHP-6-EX-9">
'''Example 6-9. Defining LDAP query parameters for user preferences'''

$bypass_spam_checks_ldap = {res_attr => 'amavisBypassSpamChecks'};
$spam_tag_level_ldap = {res_attr => 'amavisSpamTagLevel'};
$spam_kill_level_ldap = {res_attr => 'amavisSpamKillLevel'};
$spam_whitelist_sender_ldap = {
query_filter => '(&(objectClass=amavisAccount)(mail=%m)
(amavisWhitelistSender=%s))',
res_filter => 'OK'};
$spam_blacklist_sender_ldap = {
query_filter => '(&(objectClass=amavisAccount)(mail=%m)
(amavisBlacklistSender=%s))',
res_filter => 'OK'};
</div>

See the file ''README_FILES/README.lookups'' in the source code for more information.

=== Basic Operations ===

Once you've configured the options in ''amavisd.conf'', you're ready to test <tt>amavisd</tt>. Start <tt>amavisd</tt> either as the ''amavis'' user or as ''root'' (in which case it will change its UID and GID to that of ''amavis'' during startup).

During your first test, start <tt>amavisd</tt> with the <tt>debug</tt> argument. This causes <tt>amavisd</tt> to run in the foreground and produce debugging information that you can watch to be sure that it's working correctly. [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-EX-10|Example 6-10]] shows a debug startup for a properly functioning configuration:

<div id="spamassassin-CHP-6-EX-10">
'''Example 6-10. Starting amavisd with the debug arguments'''

# '''amavisd debug'''
Feb 7 16:58:16 tala amavisd[924]: starting. amavisd at tala amavisd-new-20030616-p7
Feb 7 16:58:16 tala amavisd[924]: Perl version 5.006001
Feb 7 16:58:16 tala amavisd[924]: Module Amavis::Conf 1.15
Feb 7 16:58:16 tala amavisd[924]: Module Archive::Tar 1.08
Feb 7 16:58:16 tala amavisd[924]: Module Archive::Zip 1.09
Feb 7 16:58:16 tala amavisd[924]: Module Compress::Zlib 1.32
Feb 7 16:58:16 tala amavisd[924]: Module Convert::TNEF 0.17
Feb 7 16:58:16 tala amavisd[924]: Module Convert::UUlib 1.0
Feb 7 16:58:16 tala amavisd[924]: Module MIME::Entity 6.109
Feb 7 16:58:16 tala amavisd[924]: Module MIME::Parser 6.108
Feb 7 16:58:16 tala amavisd[924]: Module MIME::Tools 6.110
Feb 7 16:58:16 tala amavisd[924]: Module Mail::Header 1.60
Feb 7 16:58:16 tala amavisd[924]: Module Mail::Internet 1.60
Feb 7 16:58:16 tala amavisd[924]: Module Mail::SpamAssassin 2.63
Feb 7 16:58:16 tala amavisd[924]: Module Net::Cmd 2.24
Feb 7 16:58:16 tala amavisd[924]: Module Net::DNS 0.45
Feb 7 16:58:16 tala amavisd[924]: Module Net::SMTP 2.26
Feb 7 16:58:16 tala amavisd[924]: Module Net::Server 0.86
Feb 7 16:58:16 tala amavisd[924]: Module Time::HiRes 1.54
Feb 7 16:58:16 tala amavisd[924]: Module Unix::Syslog 0.99
Feb 7 16:58:16 tala amavisd[924]: Found myself: /usr/local/sbin/amavisd -c /etc/amavisd.
conf
Feb 7 16:58:16 tala amavisd[924]: Lookup::SQL code NOT loaded
Feb 7 16:58:16 tala amavisd[924]: Lookup::LDAP code NOT loaded
Feb 7 16:58:16 tala amavisd[924]: AMCL-in protocol code NOT loaded
Feb 7 16:58:16 tala amavisd[924]: SMTP-in protocol code loaded
Feb 7 16:58:16 tala amavisd[924]: ANTI-VIRUS code loaded
Feb 7 16:58:16 tala amavisd[924]: ANTI-SPAM code loaded
Feb 7 16:58:16 tala amavisd[924]: Net::Server: 2004/02/07-16:58:16 Amavis (type Net::
Server::PreForkSimple) starting! pid(924)
Feb 7 16:58:16 tala amavisd[924]: Net::Server: Binding to TCP port 10024 on host 127.0.
0.1
Feb 7 16:58:16 tala amavisd[924]: Net::Server: Setting gid to "110 110"
Feb 7 16:58:16 tala amavisd[924]: Net::Server: Setting uid to "2013"
Feb 7 16:58:16 tala amavisd[924]: Net::Server: Setting up serialization via flock
Feb 7 16:58:16 tala amavisd[924]: Found $file at /usr/bin/file
Feb 7 16:58:16 tala amavisd[924]: No $arc, not using it
Feb 7 16:58:16 tala amavisd[924]: Found $gzip at /bin/gzip
Feb 7 16:58:16 tala amavisd[924]: Found $bzip2 at /usr/bin/bzip2
Feb 7 16:58:16 tala amavisd[924]: Found $lzop at /bin/lzop
Feb 7 16:58:16 tala amavisd[924]: Found $lha at /usr/bin/lha
Feb 7 16:58:16 tala amavisd[924]: Found $unarj at /usr/bin/arj
Feb 7 16:58:16 tala amavisd[924]: Found $uncompress at /bin/uncompress
Feb 7 16:58:16 tala amavisd[924]: No $unfreeze, not using it
Feb 7 16:58:16 tala amavisd[924]: Found $unrar at /usr/bin/unrar
Feb 7 16:58:16 tala amavisd[924]: Found $zoo at /usr/bin/zoo
Feb 7 16:58:16 tala amavisd[924]: Found $cpio at /bin/cpio
Feb 7 16:58:16 tala amavisd[924]: Using internal av scanner code for (primary) Clam
Antivirus-clamd
Feb 7 16:58:16 tala amavisd[924]: No primary av scanner: KasperskyLab AVP - aveclient
...many other messages about detecting av scanners...
Feb 7 16:58:16 tala amavisd[924]: SpamControl: initializing Mail::SpamAssassin
Feb 7 16:58:16 tala amavisd[924]: SpamControl: turning on SA auto-whitelisting
Feb 7 16:58:23 tala amavisd[924]: SpamControl: done
Feb 7 16:58:23 tala amavisd[924]: Net::Server: Beginning prefork (2 processes)
Feb 7 16:58:23 tala amavisd[924]: Net::Server: Starting "2" children
Feb 7 16:58:23 tala amavisd[924]: Net::Server: Parent ready for children.
Feb 7 16:58:23 tala amavisd[929]: Net::Server: Child Preforked (929)
Feb 7 16:58:23 tala amavisd[930]: Net::Server: Child Preforked (930)
</div>

After the startup messages, you should begin to see <tt>amavisd</tt> processing incoming messages (which will produce a copious amount of debugging information). When you are satisfied that messages are being properly delivered back to Postfix, hit Ctrl-C to stop <tt>amavisd debug</tt> and run <tt>amavisd</tt> with no arguments to start the daemon in the background.

<div class="tip">
'''Tip'''

If you've chosen to locate your configuration file somewhere other than ''/etc'', you should either make a symbolic link to ''/etc/amavisd.conf'' or use the <tt>-c</tt> <tt>''/path/to/amavisd.conf''</tt> command-line option to <tt>amavisd</tt>.
</div>

Once <tt>amavisd</tt> is running and you confirm that ordinary email is being delivered correctly, test the SpamAssassin functions by sending a copy of the GTUBE string to yourself from a remote system. Because SpamAssassin assigns GTUBE a spam score of 1000, which should be higher than your spam kill level, you should see the message handled by <tt>amavisd</tt>'s spam-handling options.

If <tt>amavisd</tt> appears to work, but SpamAssassin does not, you can enable SpamAssassin debugging by editing ''amavisd.conf'' and setting the <tt>$sa_debug</tt> variable to 1. This variable appears at the end of ''amavisd.conf''. You must stop <tt>amavisd</tt> and restart it with the <tt>debug</tt> argument for SpamAssassin debugging to be performed.

<div class="tip">
'''Tip'''

Anytime you make a change to ''amavisd.conf'', you must inform <tt>amavisd</tt> by issuing the command <tt>amavisd reload</tt> (or stopping and restarting the daemon).
</div>

The amavisd-new distribution includes a script named <tt>amavisd_init.sh</tt> that you can use as a boot script for systems based on RedHat Linux. With a little modification, it makes a suitable boot script for other Unix systems to automatically start and stop <tt>amavisd</tt>.

=== Adding Sitewide Bayesian Filtering ===

You can easily add sitewide Bayesian filtering to amavisd-new. Use the usual SpamAssassin <tt>use_bayes</tt> and <tt>bayes_path</tt> directives in ''local.cf'', and ensure that the ''amavis'' user has permission to create the databases in the directory named in <tt>bayes_path</tt>. One way to do this is to use a directory for the databases that is owned by ''amavis'', such as ''/var/amavis''. Another option is to locate the databases in a directory owned by another user but to create them ahead of time and <tt>chown</tt> them to ''amavis.''If local users need to have access to the databases (e.g., they will be running <tt>sa-learn)</tt>, you might have to make the databases readable or writable by a group other than ''amavis'' and adjust the <tt>bayes_file_mode</tt>, or make them world readable or writable. Doing so, however, puts the integrity of your spam-checking at the mercy of the good intentions and comprehension of your users.

If users have shell accounts on the system, you can use per-user Bayesian filtering with amavisd-new instead. Configure SpamAssassin for per-user databases as usual, but ensure that each user's databases are group-owned by the ''amavis'' group and have group read/write permissions so that amavisd-new can use them. Doing so allows users to run <tt>sa-learn</tt> themselves to train their databases, while still permitting amavisd-new to access them. With SpamAssassin 3.0, you could also store per-user Bayesian data in an SQL database.

=== Adding Sitewide Autowhitelisting ===

amavisd knows how to use autowhitelisting (see the discussion of <tt>$sa_auto_whitelist</tt> earlier in this chapter). Just add the usual SpamAssassin <tt>auto_whitelist_path</tt> and <tt>auto_whitelist_file_mode</tt> directives to ''local.cf''. As with the Bayesian databases, the ''amavis'' user must have permission to create the autowhitelist database and read and write to it.

=== Routing Email Through the Gateway ===

Once Postfix and amavisd-new are receiving messages for the local host and performing SpamAssassin checks on them, you can start accepting email for your domain and routing it to an internal mail server after spam-checking. [[SpamAssassin/Integrating SpamAssassinwith Postfix#spamassassin-CHP-6-FIG-4|Figure 6-4]] illustrates this topology.

<div id="spamassassin-CHP-6-FIG-4">
'''Figure 6-4. Spam-checking gateway topology'''

[[Image:SpamAssassin_I_6_tt118.png|Spam-checking gateway topology]]
</div>

==== Postfix changes ====

To configure Postfix to relay incoming mail for ''example.com'' to ''internal.example.com'', add the following line to ''/etc/postfix/main.cf'':

transport_maps=hash:/etc/postfix/transport

Then, create the ''/etc/postfix/transport'' file, and add either:

example.com smtp:internal.example.com

or, if ''mail.example.com'' cannot resolve the name ''internal.example.com'', you could use

example.com smtp:[129.168.10.55]

Run the command <tt>postmap /etc/postfix/transport</tt> to build the transport map from ''/etc/postfix/transport'', and run <tt>postfix reload</tt> to reload Postfix's configuration.

==== Routing changes ====

Mail from the Internet for ''example.com'' should be sent to the spam-checking gateway ''mail.example.com''. Add a DNS MX record for the ''example.com'' domain that points to ''mail.example.com''.

Once received by ''mail.example.com'', messages will be spam-checked and should then be relayed to ''internal.example.com'' by Postfix. No DNS records for ''internal.example.com'' need be published to the Internet, but it's useful if ''mail.example.com'' can resolve ''internal.example.com''.

==== Internal server configuration ====

Once the external mail gateway is in place, you can configure the internal mail server to accept SMTP connections only from the gateway (for incoming Internet mail). If you don't have a separate server for outgoing mail, the internal mail server should also accept SMTP connections from hosts on the internal network. These restrictions are usually enforced by limiting access to TCP port 25 using a host-based firewall or a packet-filtering router.
== Notes ==

<references/>

←Older revision		Revision as of 10:56, 7 March 2008
Line 648:		Line 648:
	This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag level as the hash value.		This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag level as the hash value.
	</dl>		</dl>
		+
	<dl>		<dl>
	<dt><tt>$sa_tag2_level_deflt</tt>		<dt><tt>$sa_tag2_level_deflt</tt>
Line 654:		Line 655:
	This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag2_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag2 level as the hash value.		This variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_tag2_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the tag2 level as the hash value.
	</dl>		</dl>
		+
	<dl>		<dl>
	<dt><tt>$sa_kill_level_deflt</tt>		<dt><tt>$sa_kill_level_deflt</tt>
Line 659:		Line 661:

	The variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_kill_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the kill level as the hash value.		The variable can be defined on a per-recipient basis much like <tt>$per_recip_blacklist_sender_lookup_tables</tt>. Set <tt>$sa_kill_level_deflt</tt> to a reference to a hash keyed on recipient addresses, with the kill level as the hash value.
-	</dl>;<tt>$sa_spam_modifies_subj</tt>	+	</dl>
		+	;<tt>$sa_spam_modifies_subj</tt>
	: If this variable is set to 1, <tt>amavisd</tt> may modify the ''Subject'' header of messages with spam scores above the <tt>$sa_tag2_level_dflt</tt> setting. You can also set this variable to a reference to a list of recipients who should have their ''Subject'' headers modified, a reference to a hash table keyed on recipients who should have their headers modified (with hash values of 1), or the return value of a <tt>new_RE( )</tt> call on a list of regular expressions to match against recipients who should have their headers modified. This variable is not defined by default.		: If this variable is set to 1, <tt>amavisd</tt> may modify the ''Subject'' header of messages with spam scores above the <tt>$sa_tag2_level_dflt</tt> setting. You can also set this variable to a reference to a list of recipients who should have their ''Subject'' headers modified, a reference to a hash table keyed on recipients who should have their headers modified (with hash values of 1), or the return value of a <tt>new_RE( )</tt> call on a list of regular expressions to match against recipients who should have their headers modified. This variable is not defined by default.
	;<tt>$sa_spam_subject_tag</tt>		;<tt>$sa_spam_subject_tag</tt>

SpamAssassin/Integrating SpamAssassinwith Postfix - Revision history

Docbook2Wiki: Initial conversion from Docbook

Docbook2Wiki: Initial conversion from Docbook