| 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 <https://wiki.apache.org/spamassassin/> contains |
| information on custom plugins, extensions, and other optional modules |
| included with SpamAssassin. |
| |
| |
| (end of INSTALL) |
| |
| // vim:tw=74: |