I would like to attempt to describe how some of the most critical amavisd-new settings work (in versions 2.0 and above). But first, a brief overall view of what amavisd-new does. By itself, and with the help of SpamAssassin, virus scanners, and other external programs, amavisd-new has the ability to detect spam, viruses, mail with attachments we would like to ban and mail with malformed headers. Once undesirable mail is found, amavisd-new has the ability to quarantine, discard and/or allow the undesirable mail to pass. Amavisd-new can place useful information in the header of an email, notify people of its actions and also "defang" mail we deem undesirable. When amavisd-new defangs mail, the original mail is encapsulated into an attachment. That attachment is sent along with a notice that the contents of the email inside the attachment may contain something undesirable. If the attachment contains an email which in turn contains a virus, this virus can still infect your system.

The critical decision we have to make when we configure amavisd-new is to decide what action should be taken when an undesirable message is found. To eliminate confusion, I am going to discuss an amavisd-new configuration that filters email for a single domain and all the users in that domain use the same settings. This is obviously a "site wide" scenario that would be typical of a system run by a single administrator at a small business. Let me say that in a system where certain individuals desire their personal settings to differ from the site wide settings, amavisd-new can accommodate them. In addition to many per-user and per-domain settings, certain settings can be configured to let individuals or domains "opt out" of certain tests, or at least receive messages they would normally not get if they remained in the majority of recipients. Those settings are:
@bypass_virus_checks_maps =
@bypass_banned_checks_maps =
@bypass_header_checks_maps =
@bypass_spam_checks_maps =

@virus_lovers_maps =
@banned_files_lovers_maps =
@bad_header_lovers_maps =
@spam_lovers_maps =

There are a LOT more settings we could discuss regarding individual settings, but for our "site wide" scenario, we will completely ignore these.
I am going to divide the remaining discussion into two groups. The first group will discuss settings that deal with viruses, banned attachments, and bad headers. These are grouped together because the settings we use to determine what happens to email that contain these undesirable items are parallel to each other. The critical settings are:
$final_virus_destiny =
$final_banned_destiny =
$final_bad_header_destiny =

$virus_quarantine_to =
$banned_quarantine_to =
$bad_header_quarantine_to =

There are four possible settings for the $final_*_destiny variables. They are D_PASS, D_BOUNCE, D_REJECT and D_DISCARD. For the sake of our discussion, we only need to consider two possible settings for the $*_quarantine_to variables: these variables can either be configured, or undefined. In other words, the $*_quarantine_to variables can have a value assigned to them that (partially) defines where the quarantined items will be stored, or they can be assigned an empty value which would mean "we do not have a place for quarantined items to go". When an undesirable email is found, let me explain what action will be taken by amavisd-new by the four possible settings of the $final_*_destiny variables. Remember, we are discussing mail we consider undesirable:

D_PASS    Mail will pass to recipients, regardless of bad contents. If a quarantine is configured, a copy of the mail will go there, if not, at least the recipient received the mail. Note that including a recipient in a @*_lovers_maps is functionally equivalent to setting $final_*_destiny = D_PASS; for that recipient.

D_BOUNCE    Mail will not be delivered to its recipients. A non-delivery notification (bounce) will be created by amavisd-new and sent to the sender by amavisd-new. Exceptions: bounce (DSN) will not be sent if a virus name matches @viruses_that_fake_sender_maps , or to messages from mailing lists (Precedence: bulk|list|junk), or for spam level that exceeds the $sa_dsn_cutoff_level. If a quarantine is configured, a copy of the mail will go there. If not, we have lost the mail, but if the mail was legitimate, the sender should receive notification of the disposition of the message.

D_REJECT    Mail will not be delivered to its recipients. Amavisd-new will send the typical 550 (or 554) reject response to the upstream MTA and that MTA may create a reject notice (bounce) and return it to the sender. This notice is not as informative as the one amavisd-new would create if you were using D_BOUNCE, so usually D_BOUNCE is preferred over D_REJECT. One case where D_BOUNCE is not preferred over D_REJECT is when amavisd-new is used as a before-queue proxy filter, but this is neither recommended nor supported. Personally, I prefer D_DISCARD for spam or viruses, as creating a DSN is usually (but not always) a bad idea for several reasons, among them the fact that if the mail is malware, the sender's address is probably undeliverable; or worse, it is a real address that has been forged. If a quarantine is configured, a copy of the mail will go there. If not, we have lost the mail, but the sender should be notified their message was rejected.

D_DISCARD    Mail will not be delivered to its recipients and the sender normally will NOT be notified. If a quarantine is configured, a copy of the mail will go there. If not, we have lost the mail. Note that there are additional settings available that can send notifications to persons that normally may not be notified when an undesirable message is found, so it is possible to notify the sender even when using D_DISCARD.

Here are some practical examples of how a system might be configured:

$final_virus_destiny = D_DISCARD;
$virus_quarantine_to = undef;
When a virus is detected, the mail will be discarded.

$final_banned_destiny = D_BOUNCE;
$banned_quarantine_to = "banned\@$mydomain";
Here, if a message containing a banned file is received, the sender may (or may not) be sent a notification, and the message will be quarantined to the email address listed here. Typically it is up to the system administrator to review what is in this mailbox, and either forward the message to the recipient, or delete the message. Note that in amavisd.conf, we have set $mydomain = 'example.com'; so the actual address translates to banned@example.com.

$final_bad_header_destiny = D_PASS;
$bad_header_quarantine_to = 'bad-header-quarantine';
If a message is received that contains a malformed header, the message will be sent to the recipient, and a copy will be sent to a quarantine area on the local machine. This copy can be examined by the administrator and a determination made whether there should be any further action to prevent similar email from entering the system. Malformed headers, while annoying, are typically not a security risk.

The second group only applies to spam. Spam is different than the other types of undesirable mail because in addition to "quarantine, discard and/or allow the mail to pass", there are 2 more actions that can occur: we have the ability to rewrite the Subject line in the email that is passed to the recipient(s) (to notify them that the message is possible spam) and we can include spam related information in the header of the mail. We also must decide what we consider spam to be. SpamAssassin's only goal in life is to come up with a numerical score. Very low scores and negative scores may be considered 'ham' (non spam) and higher scores may be considered spam. The SpamAssassin developers have chosen to use a score of 5.0 as the target delineation point between ham and spam, but unfortunately legitimate mail does on occasion score higher - and spam lower. It is completely up to you to decide what score will be the delineation point between ham and spam. If you set this point at a low value, you run a big risk of calling legitimate mail spam. Set this at a high value, and of course, the recipients may receive an increased quantity of spam mixed in with their legitimate mail.

$final_spam_destiny =
$spam_quarantine_to =
These work exactly the same as described above in the first group. In other words, these two spam settings are parallel to the settings of the other three types of undesirable mail.
Now on to the settings that are unique to spam:
$sa_tag_level_deflt =
$sa_tag2_level_deflt =
$sa_kill_level_deflt =

All three of these settings are assigned numeric values by you. These numeric values are compared to the score that SpamAssassin produces. Note that amavisd-new also provides a method of manually adjusting the SpamAssassin score based on the sender (soft white/black list and/or pen-pals).

The first setting:   $sa_tag_level_deflt   is a 'no brainer' for me personally. This setting decides at which score the X-Spam-Status, X-Spam-Score and X-Spam-Level headers are added. I set this to undef or -9999 therefore every message that is considered local will have these informative headers added, spam or not. The domain the mail is addressed to must match an entry in @local_domains_maps (or other lookup table that provides the same functionality) to be considered local. Note that for this particular setting, undef means 'lower than any possible score' (undef is only a valid setting here in 2.x and newer).

$sa_tag2_level_deflt   This is the level at which the Subject line of the email will be prepended with whatever is assigned to the $sa_spam_subject_tag variable (assuming $sa_spam_modifies_subj is true). For example, let's say $sa_spam_subject_tag = 'Spam> ';. If the subject of the email was 'Get a free laptop', it will now say 'Spam> Get a free laptop'. This is done for mail that (once again) is considered local and will actually reach a recipient. The X-Spam-Status extra header will change from "No" to "Yes" and a new 'X-Spam-Flag: YES' header will be added. 'Plus addressing' may also occur if mail is passed to a recipient. I don't expound any further on ' plus addressing' in this document.

$sa_kill_level_deflt   I consider this to be the single most important spam setting. This is the point at which some firm action is taken with the spam. Once an email scores at the level we set here, whichever one one of the four possible $final_spam_destiny settings (D_PASS, D_BOUNCE, D_REJECT or D_DISCARD) we have chosen will occur. The results of these actions are exactly the same as we described above in the first group. If you simply want spam tagged, then passed, an additional way to allow spam to pass is to set this at a very high level (e.g. 9999). At this level, it is unlikely a spam message would ever score high enough for any firm action to be taken. $sa_kill_level_deflt also triggers quarantining of the spam (if a quarantine is configured).

Once again, let me give you practical examples from a real system:

$final_spam_destiny = D_DISCARD;
$spam_quarantine_to = "spams\@$mydomain";
Once a message reaches the score we set in $sa_kill_level_deflt:
the message will not be delivered to its recipient(s), sender will not be notified. A copy of the mail will go to the email address we configured here. This "spams" mailbox is our quarantine area for spam.

$sa_tag_level_deflt = undef;   Any message that is addressed to a recipient that is considered local will have X-Spam-Status, X-Spam-Score and X-Spam-Level headers added. As I said, for this particular setting, undef is programmed to mean 'lower than any possible score'.

$sa_tag2_level_deflt = 5.0;   Mail that scores at 5.0 or above will have 'Spam> ' prepended the the Subject line. This will only happen if the mail is considered local and is passed to a recipient (and $sa_spam_modifies_subj is true). We set $sa_spam_subject_tag = 'Spam> '; earlier. The X-Spam-Status extra header will change from "No" to "Yes" and a new 'X-Spam-Flag: YES' header will be added.

$sa_kill_level_deflt = 8.0;   This is the level that triggers the D_DISCARD action we have assigned to $final_spam_destiny and is also the level at which quarantining occurs (if a quarantine is configured).

To recap, the net effect of our five settings will deliver mail that scores up to 7.999, will quarantine spam that scores at 8.0 or higher, and will prefix 'Spam> ' to the subject line for spam that the recipient receives (scores at 5.0 or higher). It will also write X-Spam-Status, X-Spam-Score and X-Spam-Level headers for all mail, and will add a "X-Spam-Flag: YES" header if the mail scores at 5.0 or higher. I have assumed the domain is a 'local' domain.

Here I describe two additional spam related settings:

$sa_dsn_cutoff_level = 12.0;   Since we are using D_DISCARD, this setting will serve no purpose in our example, but if you were using D_BOUNCE, you can use this to set a level at which the sender will no longer be notified. For example, any mail that scores at 12 or higher will effectively turn D_BOUNCE into D_DISCARD. If you use D_BOUNCE (and actually do want to send bounce notices), I strongly suggest you configure this setting. It appears that if you don't, some older versions of amavisd-new may assume that $sa_dsn_cutoff_level = 0; which will effectively turn D_BOUNCE into D_DISCARD.

$sa_quarantine_cutoff_level = 20;    If you have version 2.3.0 or newer, a new $sa_quarantine_cutoff_level setting was introduced. If you quarantine spam, but you would like to delete high scoring spam (therefore reducing the number of items in the quarantine) this setting allows you to discard quarantined spam at this level and above.

It only makes sense to maintain the relationship:
sa_tag_level <= sa_tag2_level <= sa_kill_level < sa_dsn_cutoff <= sa_quarantine_cutoff_level

Gary V, mr88talent at yahoo dot com
10 DEC 2005