Home
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