SpamfilterN_*_M action and verdict MTA options

From Messaging Server Technical Reference Wiki
Jump to: navigation, search

Spamfilter MTA options: spamfilterN_action_M (URL) spamfilterN_verdict_M (string)

Each pair of options spamfilterN_verdict_M and spamfilterN_action_M for particular values of N and M specifies the action that the MTA should take upon receiving the corresponding (M) verdict from the virus/spam filter package number N. N can range between 1 and 4 as of MS 6.2 and range between 1 and 8 as of MS 6.3; that is, up to four (as of MS 6.2) or eight (as of MS 6.3) virus/spam filter packages may be in use simultaneously. M can range between 0 and 7; that is, up to eight such pairs may be specified per virus/spam filter package.

In legacy configuration, the spamfilter_action_M and spamfilter_verdict_M MTA options were synonyms, respectively, for spamfilter1_action_M and spamfilter1_verdict_M MTA options; Unified Configuration does not support those old aliases other than for upgrade purposes.

Each spamfilterN_verdict_M MTA option specifies a possible verdict string from a virus/spam filter package such as Brightmail, with N corresponding to the N in spamfilterN_library and spamfilterN_config_file; that is, N specifies the (arbitrary) "number" identifying the particular virus/spam filter package. New in MS 6.2p1, the *_verdict_* MTA option value may contain wildcards and glob matches; the MTA will do pattern matching on the verdict string returned by a spam/virus filter package. See the table of Mapping pattern wildcards for the sorts of wildcards and globs that may be used in the *_verdict_* MTA option settings; (note that "saving" of wildcards or globs is disabled in this context, so in particular one may use more than ten wildcards or globs in such a value). New in MS 6.3, the length of string argument to each such option has been increased to 1024 characters (where previously the limit was 256 characters).

For each such option (verdict), a corresponding spamfilterN_action_M MTA option should also be set, specifying what action to take when the corresponding verdict is returned. The value of a spamfilterN_action_M MTA option should be a URL that resolves to a Sieve filter (where the Sieve filter specifies the action to take). The URLs can use MTA URL substitution sequences, as in Table of LDAP URL substitution sequences, though most such substitutions have no meaning or are irrelevant in this particular context, and in a few cases the meanings are different in this context. In particular:

spamfilterN_action_M MTA option values
Substitution sequence Description
$U The verdict name string
$A The address that this verdict is associated with
$M (New in MS 6.0) The detailed verdict string (if the spam/virus filter package provided one - not all do)

In MS 6.2, N can range between 1 and 4; that is, up to four virus/spam filter packages may be in use simultaneously. As of MS 6.3, N can range between 1 and 8; that is, up to eight virus/spam filter packages may be in use simultaneously. M can range between 0 and 9; that is, up to ten such pairs may be specified per virus/spam filter package.

For instance, if the spam/virus filter package configured in the MTA as package 1 might return as its "verdict" a string of either the form

spam...arbitrary-text...X-HEADER: SPAM...more-text...



then one might configure MTA options as follows in legacy configuration:

SPAMFILTER1_ACTION_1=data:, addheader "X-Header" "SPAM"; 
SPAMFILTER1_ACTION_2=data:, discard; 

or in Unified Configuration:

msconfig> set mta.spamfilter1_verdict_1 "spam*X-Header: SPAM*"
msconfig# set mta.spamfilter1_action_1 'data:, addheader "X-Header" "SPAM";'
msconfig# set mta.spamfilter1_verdict_2 spam*discard*
msconfig# set mta.spamfilter1_action_2" "data:, discard;"
msconfig# show spamfilter1*
role.mta.spamfilter1_action_1 = data:, addheader "X-Header" "SPAM";
role.mta.spamfilter1_verdict_1 = spam*X-Header: SPAM*
role.mta.spamfilter1_verdict_2 = spam*discard*
role.mta.spamfilter1_action_2 = data:, discard;

NoteThe special value "data:,$M" for a spamfilterN_action_M MTA option has some special, short-circuited handling, in that it causes the verdict to be used literally as a Sieve scriptlet itself, omitting the usual URL expansion processing. For "short" verdicts, this is a difference that makes no difference, but it avoids the length limitations imposed during URL expansion that could potentially become relevant for longer verdicts---such as those that milter likes to return. Note that other uses of $M in a setting still result in substitution of the original verdict string but with normal URL expansion (thus subject to length limits); it is only the special, literal setting "data:,$M" that gets the special, short-circuited handling.

Note: Brightmail has a concept of a "default" verdict, intended to mean merely "deliver normally". Brightmail is typically configured so that a Brightmail "clear of any virus or spam" result is set to a Brightmail "destination" (a "verdict" in the MTA's terminology) of "inbox", with "inbox" also being set to be the "default destination". In older Brightmail configuration, this Brightmail configuration of "default destination" would be something like:

blSWCClientDestinationdefault: inbox 

The MTA has support for Brightmail's default destination concept, implemented by the MTA checking whether a verdict that it has received from Brightmail is Brightmail's default destination and if so, the MTA forcibly performs a plain "keep" Sieve action (forces delivery to the Inbox) and does not apply any spamfilterN_verdict/spamfilterN_action processing. Thus to achieve some other result for Brightmail clear messages, that is, to get spamfilterN_verdict/spamfilterN_action processing to occur for "clear" messages (such as perhaps, adding a header line saying that the message was cleared by Brightmail as well as delivering to the Inbox), Brightmail must be configured differently: either configure Brightmail so that "inbox" is not Brightmail's "default destination", or configure Brightmail to return some destination (some verdict, in MTA terminology) of other than "inbox". Either way, the MTA must see a non-default (in Brightmail's opinion) destination/verdict in order for it to apply "normal" spamfilterN_verdict/spamfilterN_action processing.

In addition to the explicitly-specified-verdict/corresponding-action pairs discussed above, there are also two additional types of MTA option that specify the behavior of the MTA when other verdicts are returned: the spamfilterN_null_action options controlling behavior when a so-called "null" verdict is returned, and the spamfilterN_string_action options controlling behavior when an unrecognized verdict (a verdict without a matching spamfilterNverdict_M value) is returned.

See also: