• Preferences Attributes

DSPAM Preferences Attributes

Author: FrankLuithle

Note: As of version 3.6.4-STABLE, the README of the DSPAM distribution contains a description of the user preferences.

This is not to be considered official. I have examined the source code of version 3.6.2 to find all possible attributes and applied common sense and the understanding I have about DSPAM to figure out the meaning of the undocumented properties.

If you are using an SQL backend with DSPAM, it is recommended that you build DSPAM with --enable-preferences-extension. That way DSPAM will store the user preferences in the database, for easy access through a maintenance tool (or by hand).

Where DSPAM looks for preferences

DSPAM sets preferences in the following order (later stages overwrite previous stages if new values are found):

1. Compiled-in defaults

2. Any values set using Preference directives in the agent config file 'dspam.conf'.

3. Any default preferences. These are normal preferences stored with special UID 0 in the preferences table. The attributes can be set directly in the table or changed using dspam_admin with 'default' as the user name.

4. Any values from the user preferences table for the current user. Values for untrusted users are only used if the respective attribute is listed using an AllowOverride directive in the agent config file.

Value types used

Currently supported attributes use one of the following types for their value:

• Boolean: the string "on" (in lowercase) designates a true value, any other non-empty string designates a false value.

• Integer: a string that will be converted to an integer using the atoi() C library function.

• String: a free-form string value

• String enumeration: a string value that has to be one of several possible values. Case is ignored when comparing values.

DSPAM is generally quite strict about these and doesn't do much error reporting if the values are malformed. Consider this if you build a custom administration tool.

List of the attributes

The attribute names are case sensitive.

enableBNR (boolean): "on" enables Bayesian Noise Reduction

enableWhitelist (boolean): "on" enables automatic whitelisting (see also whitelistThreshold below)

fallbackDomain (boolean): (citing the RELEASE file) "Fallback domain support can be used by systems where a user's full email address is provided as the username, and allows nonexistent users to fall back to @domain.tld as the username. Ideal for configuring pass-thru." Setting this to "on" obviously enables this behaviour.

ignoreGroups (boolean): "on" will ignore any shared/merged/global/inoculation groups for the current user.

localStore (String): (from the official README) "Overrides the directory name used for the user's dspam data directory. This is useful when using recipient addresses as usernames, as it will allow all addresses belonging to a specific user to be written to a single webui directory. (default:username)"

makeCorpus (boolean): "on" will automatically build a spam corpus in $DSPAM_HOME/data/<userdir>/<username>.corpus/{spam,nonspam}/. Messages are saved as single files with names <signature>.msg (<signature> is replaced with the DSPAM signature of the message). This is especially useful with spam trap users whose mail you don't want to keep in a proper mailbox.

optIn and optOut (boolean): Opt in and out of spam filtering, respectively, if this is permitted via dspam.conf.

optOutClamAV (boolean): "on" disables DSPAM's built in ClamAV virus checking

processorBias (boolean): same as ProcessorBias in the config file

showFactors (boolean): "on" will add a header to each processed mail, listing token factors. Quite useless except for tuning purposes. Should be set to "off" for normal users, since it inflates message headers quite heavily.

signatureLocation (string enum: "message" or "headers"): where DSPAM adds the signature string used for re-training. "headers" leaves the message body untouched, but since the headers are lost when forwarding the message, this is only an option if your users retrain by moving the messages via IMAP or if the messages are bounced. In a pure webmail/IMAP setting, "headers" is the preferred option.

spamAction (string enum: "quarantine", "deliver" or "tag"): what happens to a message if DSPAM thinks it is spam:

• "quarantine" quarantines the message

  "deliver" delivers the message to the user. The user has to filter herself using the headers added by DSPAM.

  "tag" tags the message subject using the string "[SPAM]" or any other user supplied string (see "spamSubject" below).

spamSubject (string, maximum length 15 characters): string added to the subject if the "spamAction" is "tag" and the message is deemed to be spam.

statisticalSedation (integer, default: 5): a bias to avoid false positives if DSPAM hasn't seen enough legitimate messages yet. Search for "training_buffer" in the source code if you want to find out how it works exactly. I think higher values mean a stronger bias away from generating false positives.

storeFragments (boolean): store 1024 byte fragments of each message in $DSPAM_HOME/data/<userdir>/<username>.frag/ with names <signature>.frag (<signature> being replaced with the DSPAM signature of the message). This directory has to be purged externally. The RELEASE file says: "DSPAM can now be configured via a user preference to store 1K of each message processed on the server. This can be used by some GUIs (such as the DSPAM Appliance UI) to display message fragments from history."

trainPristine (boolean): same as TrainPristine in the config file.

trainingMode (string enum: "TEFT", "TOE", "TUM" or "NOTRAIN"): same as TrainingMode in the config file.

whitelistThreshold (integer, default: 10): the number of innocent messages per sender needed so that this sender becomes auto-whitelisted.