Quick Start Guide

Below is a quick-start procedure for people who are installing the SpamBouncer on a standard Unix server, understand Unix shells, are at least somewhat familiar with Procmail, and do not need a lot of hand-holding. These instructions explain how to install the SpamBouncer in a safe, conservative configuration for new users.

To install and configure SpamBouncer 2.1

Log on as the user that will filter your incoming email, and gather the following information:

Operating System and Version. On most Unix-based systems, you can get this information by typing uname -rs at your shell prompt.
Procmail Version. You can find this out by typing procmail -v at your shell prompt.

Create the directories to hold the SpamBouncer and your filtered email.

Create a directory for the SpamBouncer 2.1 installation.

I recommend ${HOME}/sb, but you can put the directory anywhere you like and name it anything you want, as long as the user account that will run Procmail, and the SpamBouncer, on your incoming email has read access to that directory.

Create a directory for your filtered email.

This directory will hold any email that your filtering setup does not return to your inbox. I recommend ${HOME}/Mail unless you use a Unix shell email program that prefers to have the mail directory in a different location. In that case, use the email program's preferred mail directory.

Create a directory for backups of incoming email.

This directory will hold unfiltered, backup copies of the last 1,000 incoming emails. I recommend ${HOME}/Mail/backup, unless you use a Unix shell email program that prefers to have the mail directory in a different location. In that case, create a subdirectory named backup in the email program's preferred mail directory.

Retrieve the appropriate SpamBouncer 2.1 archive from the links provided below or from the SpamBouncer FTP server at ftp.spambouncer.org, and put it in the SpamBouncer directory you created.

Your choices are:

Standard version. If you have any version of Procmail other than 3.22, use this version.

sb.tar.gz The standard version, as a tar.gz archive.
sb.tar.Z The standard version, as a tar.Z archive.
sb.zip The standard version, as a .zip archive.

Procmail 3.22 Fix version. If you have Procmail 3.22 and are not absolutely certain that your system's Procmail 3.22 build has the recipe header flag bug fixed, use this version. (If you are absolutely sure that your Procmail 3.22 has this bug fixed, you should use the standard version.)

sb-322fix.tar.gz The Procmail 3.22 fix version, as a tar.gz archive.
sb-322fix.tar.Z The Procmail 3.22 fix version, as a tar.Z archive.
sb-322fix.zip The Procmail 3.22 fix version, as a .zip archive.

Uncompress the archive in the SpamBouncer directory.

Uncompressing the archive will create a number of 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). It will also create program files in the main SpamBouncer directory.

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

Edit your .procmailrc file and add the necessary SpamBouncer configuration.

If the .procmailrc does not already exist in your HOME directory, you must create it there.

NOTE: If you are not experienced with Procmail, use the sample Procmail configuration file, called procmail.rc, provided with your SpamBouncer distribution as the basis for your own .procmailrc file. You can retrieve it here, or from the auxiliary subdirectory in your SpamBouncer directory. (Even experienced Procmail users may find it helpful to look at that file.)

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

SHELL=/bin/sh
PATH=/bin:/usr/bin:/usr/local/bin:/sbin:/usr/sbin
FORMAIL=/usr/bin/formail
SENDMAIL=/usr/bin/sendmail

Modify the paths and filenames to the right ones for your Unix server. In particular, ensure that the PATH variable contains only directories that exist, and contains all directories where basic Unix system utilities are installed on your server.

Add the following Procmail configuration variables to the variables section at the top of your .procmailrc file:

DEFAULT=/var/mail/${USER}
MAILDIR=${HOME}/Mail
LOGFILE=${MAILDIR}/log
SBDIR=${HOME}/.sb
BACKUP=${MAILDIR}/backup

Modify the paths and other details to point to the correct values for your system. Set the DEFAULT variable to point to the inbox for this user. Set the MAILDIR variable to point to the directory you created to hold filtered email. Set the LOGFILE variable to point to the path and filename for your Procmail log. Set the SBDIR variable to point to the directory you created to hold the SpamBouncer program files. Set the BACKUP variable to point to the directory you created to hold email backups.

Add the following SpamBouncer configuration variables to the variables section at the top of your .procmailrc file:

BLOCKFOLDER=${MAILDIR}/block.incoming
PATTERNMATCHING=LOW
SPAMFOLDER=${MAILDIR}/spam.incoming
SPAMLEVEL=20
VIRUSFOLDER=/dev/null

Set the BLOCKFOLDER variable to the name of the folder where you want to store email that the SpamBouncer classifies as Blocked (suspicious, but not definitely spam). Set the SPAMFOLDER variable to the name of the folder where you want to store email that the SpamBouncer classifies as outright spam. (DO NOT set this equal to /dev/null until the SpamBouncer has been installed for a few weeks and you've tweaked the configuration to fix any problems.) Set all other variables exactly as shown.

If your server is a Sun server running SunOS or Solaris, add SBSYSCHECK=SunOS or SBSYSCHECK=Solaris (as appropriate) to the variables section at the top of your .procmailrc file.
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.

Create the SpamBouncer configuration files.

Each of these files is a plain text file that contains one email address, domain name, FQDN (fully-qualified domain name), or IP per line. You create these files using your favorite text editor.

Note: If your server is a Sun server running SunOS or Solaris, ensure that your configuration text files do not have a blank line (double linefeed) at the end of the file.

.legitlists. Create a file named .legitlists in your HOME directory, and 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 that file.

A sample .legitlists file is shown below:

intouch@alumni.berkeley.edu
newsletter@newswire.microsoft.com
outback@yahoogroups.com
spam-l@peach.ease.lsoft.com

This is important because legitimate, solicited bulk email often looks exactly like unsolicited bulk email (spam) to the SpamBouncer or any other filter. The only way the SpamBouncer can know for sure that you asked to get particular bulk email is if you tell the SpamBouncer about it by listing it here.

.localhostfile. Create a file named .localhostfile in your HOME directory, and enter the FQDNs and/or IPs of the local server itself and of all mailservers that receive email for your account.

A sample .localhostfile file for an account at the non-existent domain example.com, including IP addresses, is shown below:

192.168.67.10
192.168.67.11
192.168.67.12
malta.example.com
corfu.example.com
rhodes.example.com

If you are not sure what the FQDNs and/or IPs for all of your local mailservers are, ask your system administrator. You can also look at the Received: headers on a few incoming emails to determine which servers handle email on your system. If you forward email from another site to the account where you are installing the SpamBouncer, you should also include the FQDNs and/or IPs of mailservers at that site. This allows the SpamBouncer to determine which Received: header in an incoming email was generated when the original sending mail server connected your local mail server.

CAUTION! Do not skip this step, and ensure that you add the names of *ALL* mailservers that accept email for any of your email addresses/accounts. The SpamBouncer relies on this information heavily; if you misconfigure it here, you can cause both false negatives and false positives.

.myemail. Create a file named .myemail in your HOME directory, and enter all of your own email addresses in your MYEMAIL file.

A sample .myemail file is shown below:

myemail@example.com
myotheremail@example.net
myreallyotheremail@example.org

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.

.nobounce. Create a file named .nobounce in your HOME directory, and enter the email addresses of all people you correspond with regularly in that file.

A sample .nobounce file is shown below:

mom@users.example.com
sister@example.net
friend@users.example.org
coworker@mycompany.example.com

You are now live with SpamBouncer 2.1. After filtering, your email will be sent to the following locations:

Non-Spam. Delivered to the incoming mailbox you designated in the DEFAULT variable.
Blocked. Saved to the folder you designated in the BLOCKFOLDER variable.
Spam. Saved to the folder you designated in the SPAMFOLDER variable.
Viruses. Deleted outright, unless you changed VIRUSFOLDER=/dev/null to point to a file instead of the system trashcan.

For the first couple of weeks after installation, you should review the contents of the BLOCKFOLDER and SPAMFOLDER regularly. If you find non-spam in the SPAMFOLDER, please report the false positive immediately to fp@spambouncer.org, describing what happened and including the headers of the email. In addition, add the email addresses of these senders to your .nobounce file if they were sending personal email, or to your .legitlists file if they were sending bulk email that you asked to receive.

After you have observed the SpamBouncer in this safe, default configuration, do yourself a favor and read the rest of the pages in this section. These pages contain a lot of useful information about Procmail and the SpamBouncer that will enable you to make much fuller use of the program. There are a number of things you can do to tweak your SpamBouncer configuration and make it do exactly what you want it to do. Many of those options and different types of configurations are discussed there.

As you observe how the SpamBouncer handles your email over the first few days and weeks that you use it, you can change what it does until it is handling your email exactly as you want it to.