Contents
INTEGRATION
INTEGRATION OVERVIEW
As previously mentioned, there are three popular ways to implement DSPAM:
As a delivery proxy
The default approach integrates DSPAM directly with the mail server and filters spam as mail comes in. Please see the appropriate instructions in the MTA Specific Integration section or the files in doc/ pertaining to your MTA.
As a POP3 proxy
This alternative approach implements a POP3 proxy where users connect to the proxy to check their email, and email is filtered when being downloaded. The POP3 proxy is a much easier approach, as it requires much less integration work with the mail server (and is ideal for implementing DSPAM on Exchange, etcetera). Please see the INTEGRATION/POP3 Filter section or the file doc/pop3filter.txt.
As an SMTP Relay
DSPAM can be configured as an SMTP relay, a.k.a appliance. You can set it up to sit in front of your real mail server and then point your MX records at it. DSPAM will then pass along the good mail to your real SMTP server. See the INTEGRATION/Relay section or doc/relay.txt for more information. The example provided uses Postfix and MySQL.
Trusted users and the MTA
If you are using an MTA that changes its userid to match the destination user before calling DSPAM, you won't be able to provide pass-thru arguments to DSPAM (these are the commandline arguments that DSPAM in turn passed to the local delivery agent, in such a configuration). You will need to pre-configure the "default" pass-thru arguments in DSPAM. This can be done by declaring an untrusted delivery agent in dspam.conf. When DSPAM is called by an untrusted user, it will automatically force their DSPAM user id and passthru delivery agent arguments specified in dspam.conf.
This information will override any passthru commandline parameters specified by the user. For example:
UntrustedDeliveryAgent "/bin/mail -d $u"
The variable $u informs DSPAM that you would like the destination username to be used in the position $u is specified, so when DSPAM calls your LDA for user 'bob', it will call it with:
/bin/mail -d bob
ALIASES
There are essentially two different ways a user might train DSPAM. The first is by using the Web UI, which allows them to retrain via the "History" tab. This works quite well, as users must visit the Web UI occasionally to review their quarantine anyway (and reverse any false positives). We'll discuss this shortly in section 1.1.8.
The more common approach to training, discussed here, is to allow users to simply forward their spam to an email address where DSPAM can analyze and learn it. DSPAM uses a signature-based system, where a serial number of sorts is appended to each email processed by DSPAM. DSPAM reads this serial number when the user forwards (or bounced) a message to what is called their "spam email address". The serial number points to temporary information stored on the server (for 14 days by default) containing all of the information necessary for DSPAM to relearn the message. This is necessary in order to relearn the *exact* message DSPAM originally processed.
Note:
If you are using an IMAP based system, Web-based email, or other form of email management where the original messages are stored on the server in pristine format, you can turn this signature feature off by setting "TrainPristine on" in dspam.conf. DSPAM will then use the message itself that you provide it to train, which MUST be identical to the original message in order to retrain properly.
Because DSPAM learns each user's specific email behavior, it's necessary to identify the user in order to program their specific filtering database. This can be done in one of three ways:
The Simple Way
If you are using the MySQL or PgSQL storage drivers, the original numeric user id can be embedded in the signature, requiring only one central spam alias to be necessary for the entire system. To configure this, uncomment the appropriate UIDInSignature option in dspam.conf:
# MySQLUIDInSignature on # PgSQLUIDInSignature on
Now all you'll need is a single system-wide alias, and DSPAM will train the appropriate user when it sees the signature. An example of an alias might look like:
spam:"|/usr/local/bin/dspam --user root --class=spam --source=error"
Similarly, you may also wish to have a false-positive alias for users who prefer to tag spam rather than quarantine it:
notspam:"|/usr/local/bin/dspam --user root --class=innocent --source=error"
Note:
The 'root' user represents any active dspam user. It is necessary to supply a username on the commandline or DSPAM will bail on an error, however the user will be changed internally once the signature is read.
The Kind-of-Simple Way
If you're not using one of the above storage drivers, the next easiest way to configure aliases is to have DSPAM parse the 'To:' header of the message and use a catch-all subdomain to direct all mail into DSPAM for retraining. You can then instruct your users to email addresses like '[email protected]'. The ParseToHeaders option (available in dspam.conf) will parse the To: header of forwarded messages and set the username to either 'bob' or '[email protected]', depending on how it is configured. DSPAM can also set the training mode to either "learn spam" or "learn notspam" depending on whether the user specified a spam- or notspam- address in the To: header.
This is ideal if you don't want to set up a separate alias for each user on your system (The Hard Way). If you're fortunate enough to have a mail server that can perform regular expression matching, you can set up your system without a subdomain, and just use addresses like [email protected]. For the rest of us, it will be necessary to set up a subdomain catch-all directly into DSPAM. For example:
@relearn.domain.tld "|/usr/local/bin/dspam"
Don't forget to set the appropriate ParseToHeaders and related options in dspam.conf as well. More specific instructions can be found in dspam.conf itself. In most cases, the following will suffice:
ParseToHeaders on ChangeUserOnParse user ChangeModeOnParse on
The Old Way (A.K.A. The Hard Way)
If neither of the easy ways are possible, you're stuck with doing it the hard way. This means you'll need a separate spam alias (and notspam alias, if users are tagging mail) for each user. To do this, you will need to create an email address for each user, so that DSPAM can analyze and learn for that specific user. For example:
spam-bob: "|/usr/local/bin/dspam --user bob --class=spam --source=error"
You will end up having one alias per mail user on the system, two if you do not use DSPAM's CGI quarantine (an additional one using notspam-). Be sure the aliases are unique and each username matches the name after the --user flag. A tool has been provided called dspam_genaliases. This tool will read the /etc/passwd file and write out a dspam aliases file that can be included in your master aliases table.
To report spam, the user should be instructed to forward each spam to spam-user@yourhost
It doesn't really matter what you name these aliases, so long as the flags being passed to dspam are correct for each user. It might be a good idea to create an alias custom to your network, so that spammers don't forward spam into it. For example, notspam-yourcompany-bob or something.
Note About Security:
You might be wondering if a user can forward a spam to another user's address, or whether a spammer can forward a spam to another user's notspam address. The answer is "no". The key to all mail-based retraining is the signature embedded in each email. The signature is stored with each user's own user id, and so not only does the incoming message have to bear a valid signature, but it also has to be stored on the system with the correct user id. This prevents any kind of alias abuse.
MTA SPECIFIC INTEGRATION