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

The SpamBouncer


This page contains instructions for users of previous major SpamBouncer releases (2.0 and earlier) who are upgrading to SpamBouncer 2.1.



New Features in SpamBouncer 2.1

SpamBouncer 2.1 represents a significant revision of the SpamBouncer code. The following changes and features are new with the 2.1 release:

Upgrading to SpamBouncer 2.1

The configuration process for 2.1 is similar to that for SpamBouncer 2.0, although some details differ. You should be able to install and use this release without too much difficulty. I recommend following this procedure to upgrade to SpamBouncer 2.1:

To upgrade from SpamBouncer 2.0 to SpamBouncer 2.1

  1. Create a new directory for the SpamBouncer 2.1 installation.
  2. This will prevent old files from becoming mixed in with the new program files.

  3. Retrieve the SpamBouncer 2.1 archive of your choice, put it in the new directory, and uncompress it.
  4. Uncompressing the archive will create new files and also a number of new subdirectories that contain data files and subroutines used by the SpamBouncer, auxiliary files that users might need (such as a sample Procmail configuration file), and documentation (such as there is). :)

    Note: You can safely delete the archive file after you've uncompressed the program files.

  5. Edit your .procmailrc file.
    1. If the following deprecated variables are in your .procmailrc, delete them from it:
    2. DEBUG=<your setting>
      DOMAIN=<your setting>
      FILTER=<your setting>
      SBDEBUG=<your setting>
      THISHOST=<your setting>

      Most of these variables should not appear in a SpamBouncer 2.0 configuration. If you were running in filter mode in SpamBouncer 1.9 or previous, for the FILTER=yes statement, substitute SBDELIVERY=FILTER. Instead of setting the DOMAIN or THISHOST variables, you should create a .localhostfile file and enter the IPs and/or FQDNs for all of your incoming mail servers, one per line.

      CAUTION! You should not run SpamBouncer 2.1 with SBCONFIG=Debug except for short periods during which you are actively monitoring your local server. This mode is extremely CPU intensive, and can slow any server that receives more than a few emails an hour to a crawl.

    3. Add the following variables to the variables section at the top of your .procmailrc file, before you call the SpamBouncer:

    5. Language Settings. If you receive email in any of the following languages, set the associated variable as shown below to tell the SpamBouncer not to treat email in that language as suspicious:
    6. If you do not want to filter out email in languages you do not speak, you can set LANGFILTER=no in your .procmailrc file to disable all language-based filtering. If you set LANGFILTER=no, it overrides all other language settings and no language filtering whatsoever is performed.

    7. Add the following variables to the variables section at the top of your .procmailrc file if you absolutely must avoid all false positives. This turns off blocking of email from bulk email senders, ISPs, and otherwise legitimate companies that spam, but that also send legitimate email:

    9. Whitelists. Enable any additional whitelists you want to use.
    10. The SpamBouncer by default whitelists bulk email from senders that use confirmed opt-in methods for all of their email. A sender that sends only COI email qualifies for a direct whitelisting in the SpamBouncer, and is listed if they request one, or a SpamBouncer user requests one for them. In addition, the SpamBouncer checks the Habeas Whitelist, the ISIPP IADB reputation service, and the Bonded Sender Plus whitelist. For a more complete description of exactly which email the SpamBouncer whitelists, see the SpamBouncer Whitelists Reference page.

      If you prefer to receive email only from senders that send COI email (as I do), you are set and do not need to do anything else. If you are willing to accept email from bulk email senders that do not confirm subscriptions, you can relax the setting for these whitelists. This will prevent bulk email announcements and other, usually wanted, email from being blocked. Set these variables as shown to modify the default settings:


      In my experience, although non-COI senders can send email to users who didn't ask for it on occasion, they do so rarely and quickly fix the problem when you complain to them. While I don't consider this the best situation, many companies refuse to confirm their bulk email lists, and in some cases you may want to get that email. <wry grin>

    11. Tell the SpamBouncer how to score email caught by a generic pattern matching filter, a filter that looks for spam of a particular general type (such as diploma mill, pill-pushers, porn, and stock pumping) instead of spam from a specific known spammer.
    12. Your options are:

      NOTE: SpamBouncer users upgrading from previous versions may already have PATTERNMATCHING enabled in their .procmailrc file, using one of the obsolete values of SILENT or NOTIFY. If you do, SpamBouncer 2.1 automatically resets your generic pattern matching to LOW. If you want to block on all generic pattern matches, you might want to edit your .procmailrc file to set it to MEDIUM or HIGH.

    13. If you want to see detailed headers on your email, showing exactly why the SpamBouncer classified particular spam as coming from a specific spammer, set the following variable in your .procmailrc file:

      With headers set to COMPLETE, the SpamBouncer adds detailed (sometimes irritatingly so) headers indicating exactly which server or IP was identified as belonging to a particular spammer. You probably won't want complete headers for long, but it's fun at first and sometimes helpful when debugging.

  6. To reduce CPU and memory load on your system, enter the email addresses of all people you correspond with regularly in your NOBOUNCE file.
  7. The SpamBouncer is a powerful program, and can be a CPU and memory hog if not configured carefully. Adding the addresses of your regular correspondents to your NOBOUNCE file significantly cuts the load the SpamBouncer places on your system because the SpamBouncer doesn't have to run most of its filters on email that it knows comes from a non-spam source.

    In addition, while in theory whitelisting your regular correspondents in the NOBOUNCE file should not be necessary to prevent false positives, in practice it often does.

    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.

  8. Enter the email addresses of all of your legitimate, solicited bulk email -- such as mailing lists, notices from your bank, regular mailings from companies you do business with -- in your LEGITLISTS file.
  9. This is extremely important, because legitimate bulk email often "looks" exactly like spam to the SpamBouncer or any filter. Remember, spam isn't defined by its content, but by whether the recipient consented to receive it. The only way the SpamBouncer can know for sure that you asked to get certain bulk email is if you tell the SpamBouncer about it by listing it in your LEGITLISTS file.

  10. Enter all of your own email addresses in your MYEMAIL file.
  11. By doing this, you enable the SpamBouncer both to recognize email you cc'd to yourself, and spam with your email address forged into the From: line.

  12. Change the name of your current SpamBouncer directory to an old name, such as sb-old.
  13. Change the name of your SpamBouncer 2.1 directory to the name of your default SpamBouncer directory.

You are now live with SpamBouncer 2.1.

As always, spam that the SpamBouncer misses should be forwarded to spamtrap@spambouncer.org. Bug reports and questions should be sent to bugs@spambouncer.org. (Any spam that a spammer sends to bugs@spambouncer.org will receive priority attention when I update the SpamBouncer.) :-)

NOTE: If you are knowledgeable about procmail, or interested in learning, feel free to browse the SpamBouncer program files. (I do comment my code.) I recommend that you not make changes to the SpamBouncer program files themselves, though, except for testing purposes. If you have a cool piece of new code, feel free to submit it to me at ariel@spambouncer.org.