SPAMbaffle 4.0 Users Guide
SPAMbaffle Homepage| Features| System Requirements| Downloading & Registration| Installation| Configuration| Advanced Topics| Troubleshooting

SPAMbaffle 4.0 Configuration

Test mode
When you first install SPAMbaffle, and any time you make significant changes to your filtering rules, it may be wise to run in test mode for a short time. In test mode, all messages are delivered to you rather than being bounced or dropped. After reviewing your logs to make sure your new filtering rules aren't rejecting messages that you wish to receive, turn off test mode.

To turn test mode on or off:

  1. Load EditSPAMbaffle.cgi in your browser
  2. Enter the name of your filtering rules file and click "Load settings"
  3. Check or uncheck the "Test Mode" checkbox
  4. Click "Save settings"

Logging
SPAMbaffle's logging feature allows you to review information about messages that are bounced or dropped to help ensure that you are not filtering out messages that you wish to receive. You may turn logging on or off for each filtering test individually using a checkbox in the test editing window. You may also turn all logging off by doing the following:

  1. Load EditSPAMbaffle.cgi in your web browser
  2. Enter the name of your filtering rules file and click "Load settings"
  3. Select "No logging" from the Logging popup list
  4. Click "Save settings"

Setting up filtering rules
NOTE: For the latest in SPAM blocking techniques, we recommend using the filtering rule setup assistant on the SPAMbaffle homepage. Once you've used this tool to generate a filtering rules file, use the following steps to make any desired changes.

Use the following process to set up your filtering rules:

  1. Load EditSPAMbaffle.cgi in your web browser.
  2. Enter the name of your filtering rules file and click "Load settings".
  3. In the "Actions" section, click "Edit". This will open 2 windows on the page--one where you specify whether to bounce, drop or accept messages, and one where you specify a list of tests to perform for that action. If no new windows are displayed, then your web browser is not compatible with the CSS and DOM standards required to use EditSPAMbaffle.cgi. You will need to edit your settings from a different web browser.
  4. If the popup lists that are covered by the windows are displayed through the items on top of them, select the checkbox just above "Global settings and defaults" to compensate for a bug in your web browser.
  5. Select the desired action from the top popup list.
  6. If the action is "bounce", you may specify the message to be displayed in the bounced message.
    NOTE: At any point, you may click "Save settings", without closing all the popup windows, to save your current changes.
  7. In the "Tests" window, click "Edit". Another window will open where you may specify the details of a filtering test.
  8. Specify the filtering test as described in the table below.
  9. Click "close".
  10. Enter some descriptive text for that test in the "Description" field.
  11. If you wish to add another test to trigger this same action, click "Save settings", and then click "Edit" for the same action again. A new, blank item will appear in the "Tests" window where you can add a new test.
  12. When you've finished specifying tests for that action, click "Close" at the bottom of the "Tests" window.
  13. In the "Actions" list, enter some text to describe that action in the "Description" field.
  14. Click "Save settings" to save your changes.
  15. Repeat from step 3 to add as many actions and tests as you need. Each time you click "Save settings" a blank line will be added as needed so that you may add more actions and/or tests.
  16. When you are finished, copy your filtering rules file from the SPAMbaffle folder in your home directory to your home directory (which is where SPAMbaffle will look for it, unless you have specified a different location in your .qmail file--see "Advanced Topics" for more about that), and set the access permissions for it so that only you can modify it, but anyone can read it (644). This is the default arrangement for security purposes.

The following describes your various options in setting up filtering tests:

Item: Notes:
"Create a log entry when this test matches" If the test matches, a log file has been specified, and the global logging setting is on, create a log entry whenever this test matches.
"Do this action" If the test matches, do the action specified in the top popup window that you see after clicking "close"
"Do the default action" If the test matches, do the action specified in the "Global settings and defaults" section.
"Continue to the next action" If the test matches, skip the rest of the tests for this action and continue to the next action. (If this is the last action, this will do the default action.)
"the sender's address" For this test, check any values in the "From:, "Sender", "x-Sender", "Reply-To" and "Return-Path" email headers.
"the recipient's address" For this test, check any values in the "To", "CC", and "BCC" email headers.
"the subject" For this test, check the value in the "Subject" email header (the subject line of the email).
"the email header named below" Use this option to check any of the headers not named above, or to check a single header from the "To" or "From" lists without checking the others. Enter the header name in the "Header name or part type" field. This must be the exact header name, not a "regular expression" pattern. The header name is not case sensitive.
"the filename of any attachment"

Test against the "name" field of the "Content-Disposition" header, or the "filename" field of the "Content-Type" header.

NOTE: If there are no attachments in a particular message, this test will simply be skipped.
"a part of a type specified below"

Search in the body of the email, in a part of a specified "MIME" type. Enter the MIME type, or a regular expression to match multiple types (usually, you will enter "text/" to check all text portions of the email) in the "Header name or part type" field.

NOTE: If the specified part type does not exist in a particular email, this test will simply be skipped. If you do not wish this behavior, use a "a part does/doesn't exist whose type" test in conjunction with this test to obtain the desired behavior.
"a part does/doesn't exist whose type"

Check for the existance of a message part of a particular "MIME" type. Enter the MIME type or a regular expression to match multiple types in the large pattern field.

NOTE: For this test, the "does/doesn't" popup refers to whether a part matching the pattern does or doesn't exist, not whether the part types do or don't contain/begin with/end with/equal the patterns.
"does" or "doesn't" Self explanitory
"contain", "equal", "begin with", or "end with" Self explanitory
"the following patterns"

A list of "regular expression" patterns to look for.

See the "Advanced Topics" page for more on specifying patterns.
"Header name or part type" Explain above in the sections for "the email header named below" and "a part of a type specified below".

Filtering hints

Issue: Notes:
Order of actions When setting up your filtering rules, it is important to put them in the right order. Here is the general sequence I've settled on at present:
  1. Drop anything that is being bounced back to me, but was sent by a SPAMmer. This happens if SPAMmers enter your email address as the sender's address in an attempt to disguise themselves. You may get hundreds of bounced messages or complaints from people who received the SPAM.
  2. Accept any email from domains or specific addresses that you want to be sure never to miss anything from accidentally. Also accept any email with the exact subject line (or other header) that a form on your website generates when sending a message to you.
  3. Bounce anything that looks like SPAM, based on whatever criteria you wish to specify. Specify header tests first, and body or attachment filenames later for best performance. Also specify "does match" before "doesn't match" for best performance.
  4. Drop anything that looks like a worm, or bounce it with a message that will help the recipient of the bounce discover that they're infected.
Common patterns in SPAM Here are a few patterns I've found to be common in the subject lines of SPAM:
  • Anything starting with "adv:". They may be following the rules, but I still don't want to read it. Specify "adv\:" to catch this.
  • Lots of spaces, exclamation points, "at" signs or dollar signs in a row. Patterns for catching these could include "\s{4}", "!{4}", "\@\@", and "\${3}".
  • Finally, just add the subject line of any SPAM you recieve more than 2 or 3 times.
Filenames The filenames of attached files sometimes have extra characters added to them during emailing which are removed before you see the file. For example, "badfile.exe" may be named "badfile.exe.hqx" if it is being transferred in "BinHex" format. Because of this, a filter looking for files ending with \.exe would not catch it. To catch this file whether it was named "badfile.exe" or "badfile.exe.hqx", you could check for filenames that contain the pattern \.exe\b (".exe" followed by a word boundary).
Email addresses

Email address headers don't always end immediately after the ".com" part of the name, but are sometimes followed by ">" or other characters. Because of this, you need to ensure that if you are using an "ends with" setting, you specify your pattern in a way that will catch the other cases. For example, @spammer\.com[>\s]* would catch cases where "@spammer.com" was followed by ">" or whitespace (\s).

Similarly, email address headers may begin with something other than the beginning of the actual email address.

Finally, when checking for empty email address headers, simply using a period (as explained on the "Advanced Topics" page) may not work, because sometimes an address header will not be empty, but not contain an email address. For example, they may look like this: "Joe Smith ()" or "() Joe Smith". I have found it useful to reject messages where the senders address either begins or ends with (), which is specified by the pattern \(\).