Upgrading

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

New Features in SpamBouncer 2.0
Upgrading to SpamBouncer 2.0

New Features in SpamBouncer 2.0

SpamBouncer 2.0 represents a nearly complete rewriting of much of the SpamBouncer's underlying code. The following, in particular, has changed:

Rewritten header information extraction routines. The header information extraction routines were rewritten from the ground up. They're considerably more reliable and extract more information, allowing more sophisticated analysis of email headers. A lot of spam has header peculiarities that SpamBouncer 1.9 lacked the tools to spot. SpamBouncer 2.0 finds those spam signs.
New message body information extraction routines. The SpamBouncer now extracts IPs and hosts from the message body and generates IPs for the hosts in the message bodies of spam. That allows SpamBouncer 2.0 to check message body urls against appropriate blocklists, such as the SpamHaus SBL and SURBL lists, which catches more spam.
Rewritten code to test for specific spammers. The new code checks extracted header and body information against internal lists of IP ranges and domains that belong to known, prolific spammers. This catches a lot more spam.
Rewritten whitelist/blocklist support. The code used to test both DNS-based whitelists and DNS-based blocklists is brand new and considerably more robust, and works better than the old code did. Those of you who have had trouble getting the SpamBouncer's old blocklist support to work on your systems should find that 2.0 works properly.
SpamBouncer logging. The SpamBouncer now creates log entries in your Procmail log. At the default logging level of three (3), it saves approximately the same level of information seen in complete (as opposed to brief) headers. Users can set the logging level from zero (0), which does no logging whatsoever, to nine (9), which logs at a level suitable for debugging. Users can also tell the SpamBouncer to log to a different log file than the standard Procmail log file.

Upgrading to SpamBouncer 2.0

The configuration process for 2.0 is similar to that for SpamBouncer 1.9, 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.0:

To upgrade from SpamBouncer 1.9 to SpamBouncer 2.0

Create a new directory for the SpamBouncer 2.0 installation.

This will prevent old files from becoming mixed in with the new program files.

Retrieve the SpamBouncer 2.0 beta archive of your choice, put it in the new directory, and uncompress it.

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.

Edit your .procmailrc file.

If the following deprecated variables are in your .procmailrc, delete them from it:

DEBUG=<your setting>
DOMAIN=<your setting>
FILTER=<your setting>
SBDEBUG=<your setting>
THISHOST=<your setting>

If you are running in filter mode in SpamBouncer 1.9, for the FILTER=yes statement, substitute SBDELIVERY=FILTER. Instead of setting the DOMAIN or THISHOST variables, you should create a .localhostfile file and enter all of the domains hosted on your server, one domain per line.

NOTE: It is a good idea to enter the IP number(s) of your local SMTP server(s), as well. You enter an IP number in exactly the same way as a domain name, one per line.

You should not run SpamBouncer 2.0 in Debug mode except for short periods during which you are actively monitoring your server. Doing so with SpamBouncer 1.9 was not a great idea, but running SpamBouncer 2.0 in Debug mode for an extended period of time is like revving the engine of your car for an extended period of time -- you can bring your server to its knees. If you need to run SpamBouncer 2.0 in Debug mode for a brief period, you can do so by setting the SBCONFIG="Debug". But don't go away and forget about it afterwards!

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

BLOCKLEVEL=5
SPAMLEVEL=20
VIRUSFOLDER=/dev/null

SpamBouncer 2.0 is considerably better at spotting spam from known spammers than earlier versions have been, and the blocklisting code catches a lot more spam as well. Because of this, actual spam usually piles up quite a score. I find that setting the SPAMLEVEL at 20 with this release prevents false positives without significantly increasing the amount of actual spam missed. Your mileage may vary; start with these settings and increase or decrease them to meet your needs.

There are currently so many viruses pounding email servers that I recommend deleting virus emails outright -- unless you have a great deal of hard disk space that you don't need for better things.

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:

Arabic. Set ARABIC=yes.
Beylorussian, Bulgarian, Serbian, or Ukrainian.. Set CYRILLIC=yes and RUSSIAN=yes.
Chinese. Set CHINESE=yes.
Greek. Set GREEK=yes.
Hebrew. Set HEBREW=yes.
Japanese. Set JAPANESE=yes.
Korean. Set KOREAN=yes.
Russian. Set RUSSIAN=yes.
Spanish. Set SPANISH=yes.
Turkish. Set TURKISH=yes.

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.

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

MAINSLEAZE=NONE

Whitelists. Enable any additional whitelists you want to use.

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.

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 the IADB and enable the main Bonded Sender whitelist. This will prevent bulk email announcements and other, usually wanted, email from being blocked. Set these variables as shown to modify the default IADB setting, and enable the IBS:

IADBCHECK=OI
IBSCHECK=yes

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>

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:

SBHEADERS=COMPLETE

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.

To reduce CPU and memory load on your system, enter the email addresses of all people you correspond with regularly in your NOBOUNCE file.

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.

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.

This is extremely important, because legitimate bulk email often "looks" exactly like spam to the SpamBouncer or any filter. Remember -- it isn't about content, but consent; what makes one bulk email legitimate and another spam isn't what is in the email, but whether you asked to get that email from that sender. 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.

Enter all of your own email addresses in your MYEMAIL file.

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.

Change the name of your current SpamBouncer directory to an old name, such as sb-old.
Change the name of your SpamBouncer 2.0 beta directory to the name of your default SpamBouncer directory.

You are now live with SpamBouncer 2.0.

I need bug reports! Spam that this version misses should be forwarded to spamtrap@spambouncer.org, as always. 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.

Upgrading

Contents

New Features in SpamBouncer 2.0

Upgrading to SpamBouncer 2.0