Upgrading SpamAssassin? ----------------------- Please be sure to read the UPGRADE file for important changes that have been made since previous versions. In particular, 3.3.0 no longer includes a default ruleset. 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/Ubuntu: apt-get install spamassassin Gentoo: emerge mail-filter/spamassassin Fedora/CentOS/RedHat: yum install spamassassin Alternatively download the tarfile, zipfile, and/or build your own RPM from https://spamassassin.apache.org/. Building from tar/zip file is usually as simple as: [unzip/untar the archive] cd Mail-SpamAssassin-* perl Makefile.PL # add ENABLE_SSL=yes for SSL support make make install # as root After installing SpamAssassin, you need to download and install the SpamAssassin ruleset using "sa-update". See the "Installing Rules" section below. Please make sure to read this whole document before installing, especially the prerequisite information further down. To install as non-root, see the directions below. Note that you can upgrade SpamAssassin using these instructions, as long as you take care to read the caveats in the file UPGRADE. Upgrading will not delete your learnt Bayes data or local rule modifications. 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 https://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 information on available command line variables. 4. Install the SpamAssassin ruleset using "sa-update": $HOME/bin/sa-update See the "Installing Rules" section below if you do not wish to download the rules directly from the internet. NOTE: Because LWP does not support IPv6, sa-update as of 3.4.0 will use the binaries curl, wget or fetch to download rule updates with LWP used as a fallback if none of the binaries exist. 5. If you already use procmail, skip to step 7. If not, ensure procmail is installed using "which procmail" or install it from www.procmail.org. 6. Create a .forward file in your home directory containing the below lines: "|IFS=' ' && exec /usr/bin/procmail -f- || exit 75 #user" 7. 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 https://wiki.apache.org/spamassassin/UsedViaProcmail 8. 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: https://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 https://wiki.apache.org/spamassassin/ProcmailVsSmrsh for details. 9. You can now customize SpamAssassin. See README for more information. Installing Rules ---------------- Rules are normally installed by running a sa-update command. The version of sa-update program should match the version of SpamAssassin modules, so invoking sa-update should be performed only after installing or upgrading SpamAssassin code, not before. Installing rules from network is done with a single command: sa-update For security reasons, it should not be run as root, but as the user normally running SpamAssassin. You can run the initial setup once as root, to create necessary directories etc. Then you need to change ownership of LOCAL_STATE_DIR to that user (usually: chown -R user:user /var/lib/spamassassin), you can find out the default directory with sa-update --help (look for --updatedir). Same needs to be done for LOCAL_RULES_DIR/sa-update-keys (usually: chown -R user:user /etc/mail/spamassassin/sa-update-keys), the directory can be found with spamassassin --help (look for --siteconfigpath). If you wish to install rules from downloaded files, rather than "live" from the latest online ruleset, here is how to do it. Obtain all the following files from https://spamassassin.apache.org/downloads.cgi: Mail-SpamAssassin-rules-xxx.tgz Mail-SpamAssassin-rules-xxx.tgz.asc Mail-SpamAssassin-rules-xxx.tgz.sha512 (where xxx may look something like '4.0.0.r1900144') Save them all to the current directory. Obtain a rules-signing public key: curl -O https://spamassassin.apache.org/updates/GPG.KEY Import the signing key to the SpamAssassin gpg keyring, so that the rules files can be verified safely: sa-update --import GPG.KEY Install rules from a compressed tar archive: sa-update --install Mail-SpamAssassin-rules-xxx.tgz Note that the ".tgz", ".tgz.asc" and ".tgz.sha512" files all need to be in the same directory, otherwise sa-update will fail. If the intended rules destination directory differs from a default location as assumed by sa-update and SpamAssassin, such as when running a content filter within a Unix jail or on an unusual installation, please supply the rules destination directory to sa-update through its option --updatedir, such as: sa-update --updatedir /var/jail/var/db/spamassassin/3.003000 CPAN ---- Most of the modules listed below are available via the Comprehensive Perl Archive Network (CPAN, see https://www.cpan.org/ for more information). 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 CPAN and relevant module's documentation for more information. We can't provide documentation or installation support for third party modules. Additional information about the CPAN module is also available via "perldoc CPAN". Most Linux distributions also offer the CPAN modules in their own native formats (RPMs, Debian packages, etc.), so you should be able to find these through those mechanisms, too, if you prefer. Required Perl Interpreter ------------------------- Perl 5.14.0 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. You can get an immediate report on which of these modules you may need (or want) to upgrade, by running "perl build/check_dependencies" from the SpamAssassin build directory. The list of required modules that do not ship with Perl and must be installed: - Digest::SHA (from CPAN) Used as a cryptographic hash for some tests and the Bayes subsystem. It is also required by the DKIM plugin. - HTML::Parser >= 3.43 (from CPAN) HTML is used for an ever-increasing amount of email so this dependency is unavoidable. Run "perldoc -q html" for additional information. - Net::DNS >= 0.69 (from CPAN) Used for all DNS-based tests (SBL, XBL, SpamCop, DSBL, etc.), perform MX checks, used when manually reporting spam to SpamCop, and used by sa-update to gather version information. - NetAddr::IP >= 4.010 (from CPAN) Used to parse IP addresses and IP address ranges for "trusted_networks". Used in determining which DNS tests are to be done for each of the header's received fields. Used by AWL plugin for extracting network addresses. Used by DNSxL rules for assembling DNS queries. Avoid buggy versions 4.034-4.035 and 4.045-4.054. Examples of installing required modules on popular distributions: Debian/Ubuntu: apt-get install libdigest-sha-perl libhtml-parser-perl libnet-dns-perl libnetaddr-ip-perl Gentoo: emerge dev-perl/Digest-SHA dev-perl/HTML-Parser dev-perl/Net-DNS dev-perl/NetAddr-IP Fedora/CentOS/RedHat: yum install perl-Digest-SHA perl-HTML-Parser perl-Net-DNS perl-NetAddr-IP 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 may not warn you if these are installed, but the version is too low for them to be used. - MIME::Base64 (from CPAN) This module is highly recommended to increase the speed with which Base64 encoded messages/mail parts are decoded. - Encode::Detect::Detector (from CPAN) For proper detection of charsets and converting them into Unicode, you will need to install this module. - Net::LibIDN2 (from CPAN) - Net::LibIDN (from CPAN) Provides mapping between Internationalized Domain Names (IDN) in Unicode and ASCII-compatible encoding (ACE) for use in DNS and comparisions. The module is optional, but without it Unicode IDN names found in mail will not be suitable for DNS queries and welcome/blocklisting. Either module should work fine, but newer Net::LibIDN2 might not be available in all distributions. - Email::Address::XS Used to parse email addresses from header fields like To/From/cc, per RFC 5322. If installed, it may additionally be used by internal parser to process complex lists. - Mail::DKIM (from CPAN) If this module is installed, and you enable the DKIM plugin, SpamAssassin will perform DKIM lookups when a DKIM-Signature header is present in the message headers. Current versions of Mail::DKIM (0.20 or later) also perform Domain Key lookups on DomainKey-Signature headers, without requiring the Mail::DomainKeys module, which is now obsolete. Version 0.37 or later is preferred, the absolute minimal version is 0.31. - Mail::SPF (from CPAN) Used to check DNS Sender Policy Framework (SPF) records to fight email address forgery and make it easier to identify spams. - MaxMind::DB::Reader::XS (GeoIP2) (from CPAN) - MaxMind::DB::Reader (GeoIP2) (from CPAN) - IP::Country::DB_File (from CPAN) - Geo::IP (old deprecated GeoIP) (from CPAN) - IP::Country::Fast (deprecated) (from CPAN) Geolocation modules, choose one from the list (in recommended order). Used by the RelayCountry plugin (not enabled by default) to determine the domain country codes of each relay in the path of an email. Also used by the URILocalBL plugin (not enabled by default) to provide ISP and Country code based filtering. See: https://wiki.apache.org/spamassassin/RelayCountryPlugin - Mail::DMARC Used by the optional DMARC check plugin, which itself requires DKIM and SPF features working. - DB_File (from CPAN) Used to store data on-disk, for the Bayes-style logic, TxRep, and auto-welcomelist. *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 https://wiki.apache.org/spamassassin/DbFileSleepBug for details. - IO::Socket::IP (from CPAN) - IO::Socket::INET6 (from CPAN) Installing IO::Socket::IP is recommended if spamd is to listen on IPv6 sockets or if DNS queries should go to an IPv6 name server. If IO::Socket::IP is not available, using a deprecated module IO::Socket::INET6 will be attempted, and in its absence the support for IPv6 will not be available. Some plugins and underlying modules may also prefer IO::Socket::IP over IO::Socket::INET6. - 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 compatible spamc.) - Net::Patricia If this module is available, it will be used for IP address lookups in tables internal_networks, trusted_networks, and msa_networks. Recommended when a number of entries in these tables is hundred or more. However, in case of overlapping (or conflicting) networks in these tables, lookup results may differ as Net::Patricia finds a tightest-matching entry, while a sequential NetAddr::IP search finds a first-matching entry. So when overlapping network ranges are given, specifying more specific subnets (longest netmask) first, followed by wider subnets ensures predictable results. - 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 other storage, you will need to have these installed; both the basic DBI module and the driver for your database (for example DBD::MariaDB, DBD::mysql or DBD::Pg). - Archive::Zip - IO::String Required by the optional OLEVBMacro plugin. - Razor2 If you plan to use Vipul's Razor, note that versions up to and including version 2.82 include a bug that will slow down the entire perl interpreter. Version 2.83 or later fixes this. If you do not plan to use this plugin, be sure to comment out its loadplugin line in "/etc/mail/spamassassin/v310.pre". - Digest::SHA1 (from CPAN) An external perl module razor-agents-2.84 as used by a Razor2 plugin seems to be the only remaining component depending on Digest::SHA1 (note that a packager may ship a patched version of razor-agents which can use Digest::SHA instead) - LWP::UserAgent (aka libwww-perl) (from CPAN) Can be used by sa-update to retrieve update archives, as alternative to curl/wget/fetch. - Net::SMTP (from CPAN) Used when manually reporting spam to SpamCop. Examples of installing most recommended modules on popular distributions: Debian/Ubuntu: apt-get install libencode-detect-perl libnet-libidn-perl \ libemail-address-xs-perl libmail-dkim-perl libmail-spf-perl \ libio-socket-ip-perl Gentoo: emerge dev-perl/Encode-Detect dev-perl/Net-LibIDN \ dev-perl/Email-Address-XS dev-perl/Mail-DKIM dev-perl/Mail-SPF Fedora/CentOS/RedHat: yum install perl-MIME-Base64 perl-Encode-Detect perl-Net-LibIDN \ perl-Email-Address-XS perl-Mail-DKIM perl-Mail-SPF perl-IO-Socket-IP What Next? ---------- Take a look at the USAGE document for more information on how to use SpamAssassin. The SpamAssassin Wiki contains information on custom plugins, extensions, and other optional modules included with SpamAssassin. (end of INSTALL) // vim:tw=74: