Upgrading SpamAssassin? ----------------------- Please be sure to read the UPGRADE file for important changes that have been made since previous versions. Installing or Upgrading SpamAssassin ------------------------------------ Using CPAN via CPAN.pm: perl -MCPAN -e shell [as root] o conf prerequisites_policy ask install Mail::SpamAssassin quit Using Linux: Debian unstable: apt-get install spamassassin Gentoo: emerge mail-filter/spamassassin Alternatively download the tarfile, zipfile, or Fedora Core RPM from http://spamassassin.apache.org/ and install that, like so: [unzip/untar the archive] cd Mail-SpamAssassin-* perl Makefile.PL [option: add -DSPAMC_SSL to $CFLAGS to build an SSL-enabled spamc] make make install [as root] To install as non-root, see the directions below. If you are running AFS, you may also need to specify INSTALLSITELIB and SITELIBEXP. Note that you can upgrade SpamAssassin using these instructions, as long as you take care to read the caveats in the file UPGRADES. Upgrading will not delete your learnt Bayes data or local rule modifications. If you're using SunOS 4.1.x, see http://wiki.spamassassin.org/w/BuildingOnSunOS4 for build tips. Note for Perl 5.8 Users (incl Red Hat 8) ---------------------------------------- Perl 5.8 now uses Unicode internally by default, which causes trouble for SpamAssassin (and almost all other reasonably complex pieces of perl code!). We've worked around this in most places, as far as we know, but there may still be some issues. In addition, there is a speed hit, which it would be nice to avoid. Setting the LANG environment variable before any invocation of SpamAssassin sometimes seems to help fix it, like so: export LANG=en_US Notably, the LANG setting must not include "utf8". However, some folks have reported that this makes no difference. ;) Installing SpamAssassin for Personal Use (Not System-Wide) ---------------------------------------------------------- These steps assume the following, so substitute as necessary: - Your UNIX login is "user" - Your home directory is /home/user - The location of the procmail executable is /usr/bin/procmail Many more details of this process are at http://wiki.apache.org/spamassassin/SingleUserUnixInstall 1. Uncompress and extract the SpamAssassin archive, using "unzip" or "tar xvfz", in a temporary directory. 2. change directory into it: cd Mail-SpamAssassin-* 3. Make SpamAssassin as normal, but using your home directory as the target: perl Makefile.PL PREFIX=$HOME make make install Please see the file PACKAGING, sections "Changing paths in the Makefile" and "Setting further options on the command line" for more informations on available command line variables. 4. If you already use procmail, skip to step 6. If not, ensure procmail is installed using "which procmail" or install it from www.procmail.org. 5. Create a .forward file in your home directory containing the below lines: "|IFS=' ' && exec /usr/bin/procmail -f- || exit 75 #user" 6. Edit or create a .procmailrc file in your home directory containing the below lines. If you already have a .procmailrc file, add the lines to the top of your .procmailrc file: :0fw: spamassassin.lock | /home/user/bin/spamassassin The above line filters all incoming mail through SpamAssassin and tags probable spam with a unique header. If you would prefer to have spam blocked and saved to a file called "caughtspam" in your home directory, instead of passed through and tagged, append this directly below the above lines: :0: * ^X-Spam-Status: Yes caughtspam Also, see the file procmailrc.example and http://wiki.apache.org/spamassassin/UsedViaProcmail 7. Now, you should be ready to send some test emails and ensure everything works as expected. First, send yourself a test email that doesn't contain anything suspicious. You should receive it normally, but there will be a header containing "X-Spam-Status: No". If you are only tagging your spam, send yourself a copy of the GTUBE test string to check to be sure it is marked as spam. GTUBE is located in the sample-spam.txt message distributed with SpamAssassin and also at: http://spamassassin.apache.org/gtube/ If your test emails don't get through to you, immediately rename your .forward file until you figure out cause of the the problem, so you don't lose incoming email. Note: one possible cause for this is the use of smrsh on the MTA system; see http://wiki.spamassassin.org/w/ProcmailVsSmrsh for details. CPAN ---- Most of the modules listed below are available via the Comprehensive Perl Archive Network (CPAN, http://www.cpan.org/). While each module is different, most can be installed via a few simple commands such as: $ perl -MCPAN -e shell cpan> o conf prerequisites_policy ask cpan> install Module::Name cpan> quit If there are problems or questions regarding the installation any of the modules, please see the module's documentation for more information. We can't provide documentation or installation support for third party modules. Also, more information about the CPAN module is available via "perldoc CPAN". Most Linux distributions also offer the CPAN modules in their own native formats (RPMs, as apt-gettable packages, etc.), so you should be able to find these through those mechanisms, too, if you prefer. Required Perl Interpreter ------------------------- Perl 5.6.1 or a later version is required. Required Perl Modules --------------------- In addition to the modules associated with Perl, some additional modules need to be installed or upgraded depending on the version of Perl that you are running. The list of required modules that do not ship with Perl and must be installed: - Digest::SHA1 (from CPAN) The Digest::SHA1 module is used as a cryptographic hash for some tests and the Bayes subsystem. It is also used by Razor2. Debian: apt-get install libdigest-sha1-perl Gentoo: emerge dev-perl/Digest-SHA1 - HTML::Parser >= 3.24 (from CPAN) Version 3.31 or later is recommended. HTML is used for an ever-increasing amount of email so this dependency is unavoidable. Run "perldoc -q html" for additional information. Debian: apt-get install libhtml-parser-perl Gentoo: emerge dev-perl/HTML-Parser - Storable (from CPAN) This is a required module if you use spamd and allow children to handle more than one client connection before quitting. Third party utilities may also require this module for the same functionality. Storable is used to shift configuration when a spamd process switches between users. Debian: apt-get install libstorable-perl Gentoo: emerge dev-perl/Storable Optional Modules ---------------- In addition, the following modules will be used for some checks, if available and the version is high enough. If they are not available or if their version is too low, SpamAssassin will still work, just not as effectively because some of the spam-detection tests will have to be skipped. Note: SpamAssassin will not warn you if these are installed, but the version is too low for them to be used. - MIME::Base64 This module is highly recommended to increase the speed with which Base64 encoded messages/mail parts are decoded. - DB_File (from CPAN, included in many distributions) Used to store data on-disk, for the Bayes-style logic and auto-whitelist. *Much* more efficient than the other standard Perl database packages. Strongly recommended. There seems to be a bug in libdb 4.1.25, which is distributed by default on some versions of Linux. See http://wiki.apache.org/spamassassin/DbFileSleepBug for details. - Net::DNS (from CPAN) Used for all DNS-based tests (SBL, XBL, SpamCop, DSBL, etc.), perform MX checks, and is also used when manually reporting spam to SpamCop. Recommended. If this is installed and you are using network tests of any variety (which is the default), then you need to make sure the Net::DNS version is sufficiently up-to-date: - version 0.34 or higher on Unix systems - version 0.46 or higher on Windows systems - Net::SMTP (from CPAN) Used when manually reporting spam to SpamCop. - Mail::SPF::Query (from CPAN) Used to check DNS Sender Policy Framework (SPF) records to fight email address forgery and make it easier to identify spams. Net::DNS version 0.34 or higher is required to use Mail::SPF::Query. - IP::Country::Fast (from CPAN) Used by the RelayCountry plugin (not enabled by default) to determine the domain country codes of each relay in the path of an email. - Razor (from http://razor.sourceforge.net/) Used to check message signatures against Vipul's Razor collaborative filtering network. Razor is not available from CPAN -- you have to download it from the URL above. Razor has a large number of dependencies on CPAN modules. Feel free to skip installing it, if this makes you nervous; SpamAssassin will still work well without it. Note that Razor support does not seem to work on Windows systems. Win32 users should disable the Razor tests using "score RAZOR2_CHECK 0". You (and any users who use Razor) will need to register an account to do so, like this: razor-client [creates symbolic links] razor-admin -create [creates the razor home] razor-admin -register [registers an account] To use Razor with SpamAssassin, you will need to be using v2.40 or higher. v2.61 or higher is recommended. More info is at http://wiki.apache.org/spamassassin/UsingRazor - Net::Ident (from CPAN) If you plan to use the --auth-ident option to spamd, you will need to install this module. - IO::Socket::SSL (from CPAN) If you wish to use SSL encryption to communicate between spamc and spamd (the --ssl option to spamd), you need to install this module. (You will need the OpenSSL libraries and use the ENABLE_SSL="yes" argument to Makefile.PL to build and run an SSL compatibile spamc.) - Time::HiRes (from CPAN) If this module is installed, the processing times are logged/reported more precisely. - DBI *and* DBD driver/modules for your database (from CPAN) If you intend to use SpamAssassin with an SQL database backend for user configuration data, Bayes storage, or AWL storage, you will need to have these installed; both the basic DBI module and the driver for your database. Optional Programs ----------------- These are non-Perl programs that can increase the overall effectiveness of SpamAssassin if they are installed. - DCC (from http://www.rhyolite.com/anti-spam/dcc/) DCC (Distributed Checksum Clearinghouse) is a system similar to Razor. It supports fuzzy checksums and therefore detects some more spams than Razor does at the moment. To install it, perform the following steps: wget http://www.dcc-servers.net/dcc/source/dcc-dccproc.tar.Z tar xfvz dcc-dccproc.tar.Z cd dcc-dccproc-* ./configure && make && make install You might want to replace the configure call with something like this to get an FHS compliant install: ./configure \ --bindir=$(PREFIX)/bin \ --libexecdir=$(PREFIX)/lib/dcc \ --mandir=$(PREFIX)/man \ --homedir=/var/lib/dcc Finally call cdcc: cdcc info The last command will give some output. The output should contain lines like this: dcc1.dcc-servers.net,- RTT+0 ms anon dcc2.dcc-servers.net,- RTT+0 ms anon ... There should be *at least one*, preferably more than half a dozen, of the public DCC servers listed. If this is not the case, a likely cause is an interfering firewall (see below). Note that MIMEDefang users may need to set the 'dcc_path' configuration setting, since MIMEDefang does not set a PATH by default. See also 'perldoc Mail::SpamAssassin::Conf'. Also note that DCC requires that you open your firewall for DCC reply packets on UDP port 6277. DCC uses UDP packets when replying, which are blocked by most firewalls by default. As a result, it requires that you open your firewall for DCC reply packets on UDP port 6277. Here's sample firewall rules required: allow udp local gt 1023 to remote 6277 allow udp remote 6277 to local gt 1023 If you're running a large site, processing upwards of tens of thousands of messages a day, the DCC maintainers have requested that you consider setting up your own DCC server as described in dccd(8), and arrange to peer with the rest of the public servers, to reduce their load. More info is at http://wiki.apache.org/spamassassin/UsingDcc - Pyzor (from http://pyzor.sourceforge.net/) Used to check message signatures against the Pyzor collaborative filtering network. Pyzor was initially "a Python implementation of Razor", but now also uses its own (free) server architecture and is "based upon a new, lighter, more language-independent protocol." Pyzor requires at least Python 2.2.1 which can be found at http://www.python.org/ . To install Pyzor, download the latest revision from https://sourceforge.net/project/showfiles.php?group_id=50000 and perform the following steps: tar xvfj pyzor-*.tar.bz2 cd pyzor-* python setup.py build python setup.py install For a single user installation, change the last line to python setup.py install --home=$HOME Note that your system might install the modules and scripts with non-world-readable permissions. Correct this with a command such as: chmod -R a+rX /usr/share/doc/pyzor \ /usr/lib/python2.2/site-packages/pyzor \ /usr/bin/pyzor /usr/bin/pyzord Read the INSTALL document if you want to setup your own Pyzor server and signature store. Otherwise, you can just use the public servers. Note that MIMEDefang users may need to set the 'pyzor_path' configuration setting, since MIMEDefang does not set a PATH by default. More info is at http://wiki.apache.org/spamassassin/UsingPyzor What Next? ---------- Take a look at the USAGE document for more information on how to use SpamAssassin. (end of INSTALL) // vim:tw=74: