Overview | Quick Start | Preparation | Installation | Configuration | Troubleshooting | Bug Reports | Upgrading

The SpamBouncer

Configuring the SpamBouncer

The SpamBouncer is a highly configurable program with an often-bewildering number of options. If you are an individual user installing the SpamBouncer, however, you can safely accept the default configuration for most options when first installing the program. The default configuration is designed with safety first in mind. Even if it catches legitimate email, it will not delete it, allowing you to spot false positives and whitelist the senders.

Some configuration is required before you start, though, or the SpamBouncer will simply do nothing and pass your email to you unfiltered. In addition, to get the best use out of the SpamBouncer, you will need to understand more about configuring it so that you can enable options that will catch a lot more spam.

In particular, if you are a system administrator who will install and configure the SpamBouncer for unsophisticated users, or users who will have only POP access, you must make sure you understand how the SpamBouncer works before you implement it. The SpamBouncer was designed originally by a Unix geek for Unix geeks to use on Unix shell accounts. :-) I have added a number of featurs to make it possible to use the SpamBouncer on a system-wide basis and have users that successfully do this, but I am not a system administrator of a mail server myself. I cannot test various configurations of this type myself as a professional software company would. So please be careful, and give me lots of feedback!

Contents

 

How To Configure the Spambouncer

You configure the SpamBouncer by creating and editing these files:

Some users may also want or need to create and edit the following files:

The vast majority of the configuration you do will be by editing your .procmailrc file. You will do most of that editing at the top of the file, where you put the variable settings that tell Procmail and the SpamBouncer how you want various things handled. Examples of some common variable settings in Procmail are:

DEFAULT=/var/mail/login
BLOCKFOLDER=block.incoming
MAILDIR=${HOME}/Mail
LOGFILE=${MAILDIR}/procmail.log

In other words, Procmail variables consist of the variable name to the left, an equals sign, and the variable value to the right. (For those familiar with Unix shell scripts, Procmail variable syntax is identical to that of the Bourne shell family.) For more information about variables and the Procmail scripting language, see A Brief Introduction to Procmail.

Note: Procmail novices should use the sample .procmailrc file provided in the auxiliary directory of the SpamBouncer program distribution. More experienced Procmail users who are unsure how to set up the SpamBouncer might find answers to their questions by looking through this file, as well.

Return to Table of Contents

Basic Configuration

There are a few settings that every user must make when first installing the SpamBouncer, and a few more that you will want to set to make the SpamBouncer work in the most efficient manner. These settings are made in the .procmailrc file and in the SpamBouncer configuration files.

The .procmailrc File

All users must first set the following variables in their .procmailrc files:

Return to Table of Contents

The SpamBouncer Configuration Files

After you have set the variables above, you should next create four text files: .legitlists, .localhostfile, .myemail, and .nobounce. You can put them in your home directory, where the SpamBouncer looks for them by default, or in any other directory. If you put them in a directory other than your HOME directory, you must set the LEGITLISTS, LOCALHOSTFILE, MYEMAIL, and NOBOUNCE variables to point to the proper location and filename. For example, if you name your NOBOUNCE file my-friends and put it in ${HOME}/configfiles, put the statement NOBOUNCE=${HOME}/configfiles/my-friends in your .procmailrc file.

Each of these text files must be in Unix text format. That means that you must use a text editor to edit them. DO NOT USE a word processing program like Microsoft Word or Microsoft Wordpad! (Windows users should use Windows Notepad, if they do not have another text editor they prefer.) If you edit these files on a Windows- or Macintosh-based computer, you must upload them using ftp in ASCII mode or some other means that will create Unix, not DOS, text files.

In each file, you must include email addresses or domain names, one on each line of the file. Ensure that there are no blank lines in each of these files. To avoid problems on a few older Unix systems, you should ensure that the email addresses you list in these files are entirely in lower case letters.

Note: If your server is a Sun server running SunOS or Solaris, ensure that your NOBOUNCE file and other configuration text files do not have a blank line (double linefeed) at the end of the file. The fgrep utility program used by the SpamBouncer to search the NOBOUNCE, LEGITLISTS, GLOBALNOBOUNCE, MYEMAIL, and LOCALHOSTFILE files for matches behaves slightly differently on SunOS and Solaris than the same program does on most Unix systems.

Return to Table of Contents

The AlwaysBlock File

The .alwaysblock file functions exactly as the .nobounce file does, but in reverse. In it, you list the email addresses that you do not want to receive email from under any circumstances. It is formatted exactly as the .nobounce file is -- a plain Unix text file with one email address per line.

Caution! The .alwaysblock file is dangerous if misused, although email it catches is treated as blocked rather than as outright spam. It is especially dangerous if you list partial email addresses or entire domains, because it can cause all email that matches that pattern to be blocked. Please be careful!

Return to Table of Contents

The GlobalNoBounce File

The .globalnobounce file functions exactly as the .nobounce file does, except that it contains a master list of email addresses and domains to be whitelisted for all users on your mail server. In it, you list the email addresses that you never want blocked. Email from those addresses is filtered for viruses and dangerous content, but is then delivered to users without further filtering. The .globalnobounce file is formatted exactly as the .nobounce file is -- a plain Unix text file with one email address per line.

Return to Table of Contents

Filtering Options

After you have created the configuration files, you should choose one of the following three sections and do what is indicated in that section. The sections are Risk Averse or New Users, Ready to Fight Back, and I HATE SPAM AND WANT IT GONE NOW!. I've tried to make it easy to tell which section you want. :-)

Risk-Averse or New Users

Users who do not want to risk false positives should use this configuration. This is also the configuration you should start with, regardless of what you do after you become comfortable with Unix and the SpamBouncer.

New users should keep a sharp eye on their SPAMFOLDER and BLOCKFOLDER files for false positives. Any false positives found in the SPAMFOLDER are a sign of a configuration problem or a bug, and should be reported to the SpamBouncer development team at fp@spambouncer.org. Any false positives you find in your BLOCKFOLDER should be dealt with by putting the sender's email address in the appropriate whitelist.

Return to Table of Contents

Ready to Fight Back :-)

Users who are willing to accept a low false positive rate to catch more spam should set the following variables:

Return to Table of Contents

I HATE SPAM AND WANT IT GONE NOW!

If you feel this way, then you and I obviously have some common ancestors or early environmental influences in common. :-) Set the following variables if you want to filter aggressively and send notices users whose email is blocked by the SpamBouncer so that they can contact you:

In addition, look through the list of blocklists the SpamBouncer supports and enable those that look interesting. Many of them are somewhat redundant, but I find that one often catches what the other does not. For example, the AHBL blocklists are much better at catching spam from legitimate companies that spam (or mainsleaze spammers) than most of the other blocklists, probably because the operator strongly believes that spam is spam regardless of the source. Many other blocklists are hesitant to list large companies that spam because they also send a lot of legitimate email that many people want to get.

The SpamBouncer uses a weighted scoring system with blocklist matches, so you can safely enable more aggressive blocklists if you wish without seeing too many false positives.

Note: Do not overdo the blocklists, or you may significantly slow delivery of email, especially if a particular blocklist is down or responding slowly on a particular day. I recommend enabling no more than five or six in addition to the default blocklists.

Return to Table of Contents

Delivery Options

Next, you must configure your delivery options. You have two basic choices with the SpamBouncer -- you can let the SpamBouncer deliver email for you to a default set of folders, or you can tell the SpamBouncer to return all email to the Procmail stream after filtering and let you write your own delivery recipes. Which choices you should make, and how you should configure each, will depend on how experienced you are with procmail and spam filtering, how aggressively you configured your filtering options, and how you normally read email.

The instructions are organized in categories by email client program or access method. There are five sections -- Pop or IMAP Clients, Microsoft Outlook or Outlook Exprss (which requires special configuration), Unix Shell Clients, MH Mail (which requires special configuration), and Filter and Forward (which applies to users who filter email on one server, and then forward it to another server for delivery). Choose the section that describes how you read email.

Pop or IMAP Clients

If you have an email client that downloads your email from a remote server, you probably have a POP or IMAP client. Some common POP and IMAP clients are Microsoft Outlook, Microsoft Outlook Express, Mozilla Thunderbird, Netscape Navigator, and Qualcomm Eudora. There are many other such clients, as well. All but the most recent versions of Outlook and Outlook Express require special configuration and are discussed in the following section.

Using the SpamBouncer with a POP or IMAP client requires configuring both the SpamBouncer, and the POP or IMAP client.

To configure the SpamBouncer for POP or IMAP clients

  1. Set SBDELIVERY=FILTER in the variables section of your .procmailrc file.
  2. Tell the SpamBouncer what to do with the viruses it detects.
  3. Caution! DO NOT FORWARD VIRUSES to POP or IMAP clients if you read email on a computer running any version of the Microsoft Windows operating system! If you must keep viruses, save them to a file on your Unix server and examine them there, where the risk of infection is much less.

  4. Tell the SpamBouncer what to do with email it detects that contains dangerous content, such as executable programs and scripts, that might be a virus or trojan.
  5. Tell the SpamBouncer what to do with the spam it detects.

Next, you must configure your POP or IMAP client to recognize the SpamBouncer's headers when filtering incoming email. Most modern POP and IMAP clients can be configured to recognize and filter email based on any header name. The procedures for doing so differ for each email client, and I assume that anyone capable of installing and using the SpamBouncer can figure it out.

The SpamBouncer's X-SBClass headers are:

Return to Table of Contents

Microsoft Outlook and Outlook Express

Versions of Microsoft Outlook and Outlook Exprsss prior to Outlook 2003 or Outlook Express XP can unfortunately filter email based only on a few select headers. There are two ways to work around this problem.

First (and best), you can switch to another email client. In addition to their somewhat limited filtering capabilities, Outlook and Outlook Express have other, more serious drawbacks. The biggest is that they are the primary target of most email viruses and email-borne trojans. Although any Microsoft Windows user is at some risk of infection, an Outlook or Outlook Express user is at significantly greater risk of infection than a user of any other email program. A number of good POP email clients are free for the downloading, including my favorite -- Mozilla Thunderbird. Anyone with the skills and knowledge to use the SpamBouncer should have no problem whatsoever installing and configuring Thunderbird or any other POP or IMAP client.

Second, users who cannot switch to a different email client can set OUTLOOKTAGGING=yes in the variables section of their .procmailrc file. This causes the SpamBouncer to embed the X-SBClass: header in the Subject: header of incoming email if that email is classifed as spam or as blocked. The users can then use Outlook's filters to look for this string in the Subject: header, and filter all email with embedded X-SBClass: headers into the junk email folder.

Users of later versions of Outlook and Outlook Express should follow the instructions for POP and IMAP client users in the previous section. (Preferably after installing a better email client! ;-))

Return to Table of Contents

Unix Shell Clients

If you have an email client that lets you read your email via a shell account on the server where you installed the SpamBouncer, you have a Unix shell client. Some common Unix shell clients are elm, mail, MH Mail, mutt, and pine. MH Mail requires special configuration and is discussed in the following section.

The SpamBouncer was originally written for a user that read email on a unix shell -- me. :-) I still read my email on my shell account; it is the simplest way to avoid infection by email viruses, sneaky trojans and adware, and spam with SCREAMING LOUD POP-UPS AND GRAPHICS. <wry grin> Because the SpamBouncer was originally intended to be used in this configuration, it delivers email to Unix mail files by default and you do not need to set the SBDELIVERY variable.

You do, however, have to configure the delivery folder variables. All of these folders are stored in the directory you designated in your MAILDIR variable. They are:

Return to Table of Contents

MH Mail

If you read your email on a Unix shell account using MH Mail, you must do the following to ensure that your email is delivered properly to your MH Mail indexed directories, or folders. First, you must set SBDELIVERY=MH in the variables section of your .procmailrc file. Next, if the MH Mail package is not on your system path, you must set the MHDELIVER variable to the full path and filename of the MH Mail rcvstore program.

Third, you must ensure that your MAILDIR variable points to the main MH Mail indexed directory for your incoming email. Fourth, you must create any directories that do not already exist. Finally, you must configure the delivery folder variables to point to the appropriate MH Mail indexed directories.

Return to Table of Contents

Filter and Forward

Filter and forward refers to users who run the SpamBouncer on one server, and then after filtering their email, forward it to another server for delivery. It does not matter whether the email is delivered to a POP account, IMAP account, or Unix shell account -- the configuration is the same regardless.

To configure the SpamBouncer to "Filter and Forward"

  1. Set SBDELIVERY=FILTER in the variables section of your .procmailrc file.
  2. Tell the SpamBouncer what to do with the viruses it detects.
  3. Repeat the previous step, making appropriate changes, to tell the SpamBouncer what to do with the spam it detects.
  4. In the final line of your .procmailrc file, put the following recipe:
  5. :0
    ! <login@example.com>

    For <login@example.com>, substitute the email address to which you want to forward your email after filtering.

Return to Table of Contents

Logging and Reporting

The SpamBouncer has configurable logs and reports. You do not need to configure them, but you should know how they work and what you can do with them.

SpamBouncer Logging

By default, the SpamBouncer logs information for each email it filters to your designated Procmail log file. Your Procmail log file is the file you set the LOGFILE variable equal to in the variables section at the top of your .procmailrc file. The default logging level logs approximately the same amount of information as the SpamBouncer puts in complete (as opposed to brief) headers. Since the SBHEADERS and SpamBouncer logging variables are completely separate, you can log detailed information while adding minimal headers to incoming email.

Below is an example of a standard SpamBouncer log entry:

Dec 09 15:52:10 SpamBouncer[00000]: SpamBouncer: 2.1 (11/09/05)
Dec 09 15:52:10 SpamBouncer[00000]: Entering file: /usr/local/sb/sb.rc with SBLOGLEVEL=3 SBHEADERS=BRIEF
Dec 09 15:52:10 SpamBouncer[00000]: Processing Message-ID: <200412092256 16.C91541E91E6@smtp.example.com>
Dec 09 15:52:19 SpamBouncer[00000]: SBRule: Spammer Name (Received IP: 000.000.000.000)
Dec 09 15:52:19 SpamBouncer[00000]: SBRule: Spammer Name
Dec 09 15:52:29 SpamBouncer[00000]: SBRule: Received IP: 000.000.000.000 is in the SBL
Dec 09 15:52:30 SpamBouncer[00000]: SBScore: 20 (Spam Threshold: 20) (Block Threshold: 5)
Dec 09 15:52:30 SpamBouncer[00000]: SBClass: Spam
Dec 09 15:52:30 SpamBouncer[00000]: Leaving SpamBouncer: 2.0 (5/01/05)

You can control your SpamBouncer log settings by setting the SBLOGFILE and SBLOGLEVEL variables in the variables section of your .procmailrc file. To set the SpamBouncer log to a different file than the Procmail log, you set the SBLOGFILE variable to the log file name you want the SpamBouncer to use, as shown below:

SBLOGFILE=${MAILDIR}/sblog

You can designate any log file that Procmail can access and and modify.

To modify the amount of information that the SpamBouncer logs, you set the SBLOGLEVEL variable to any number between 0 and 9, as shown below:

SBLOGLEVEL=3

The default log level is three (3). If you set a log level of one (0), the SpamBouncer will log no information whatsoever. If you set a log level of nine (9), the SpamBouncer will log information at a level suitable for debugging.

CAUTION! If you set a log level of eight (8) or nine (9), your log files will grow very large, very fast. You must monitor your system closely when using any log level above seven (7).

Return to Table of Contents

SpamBouncer Spam Reporting

The SpamBouncer can report spam to Spamcop in one of two modes: Quick mode and Normal mode. Reporting is disabled by default; you must explicitly enable Spamcop reporting. If you want to report using your own personal Spamcop reporting address, you must sign up for a Spamcop reporting account first.

You can enable Spamcop by setting the SPAMCOPREPORT variable in the variables section at the top of your .procmailrc file as follows:

If you choose Normal or Mixed reports, you must also set the SPAMCOPEMAIL variable to your Spamcop reporting address in the variables section at the top of your .procmailrc file.

Return to Table of Contents

Finishing Your Configuration

After setting the variables in your .procmailrc, add this line to your .procmailrc file at the point where you want to filter your mail for spam:

INCLUDERC=${SBDIR}/sb.rc

This line should appear after recipes for mail you don't want to filter for spam and before recipes for mail you do want to filter for spam. Users of the sample procmail.rc that comes with the SpamBouncer will have the correct line in the correct location already, and will just need to uncomment it.

Return to Table of Contents