INSTALL

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 comparisons. 
    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::Geolocation::MMDB (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

    Required by the optional OLEVBMacro plugin, and by the optional
    Archive handler (see v403.pre) to open zip attachments.

  - 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


Optional External Programs
--------------------------

Some optional plugins and MIME-part handlers shell out to external
programs.  None of these are required to install or run SpamAssassin, and
the plugins and handlers that use them are not enabled by default; each is
needed only if you enable the corresponding feature.  Several of them have
substantial recursive dependencies, so review what your package manager
would pull in before installing them.

  - gpg

    Used by "sa-update" to verify the signatures on rule updates.  See
    "sa-update --no-gpg" if you prefer to skip verification.

  - curl, wget or fetch

    Used by "sa-update" to download rule updates.  Only one is needed;
    LWP::UserAgent is used as a fallback if none is found.

  - re2c

    Used by "sa-compile" to compile rules into a faster regexp matcher.

  - tesseract, and heif-dec (from libheif)

    Used by the optional Image handler (see v403.pre) to OCR text out of
    image attachments.  tesseract is required by that handler; heif-dec is
    needed only for HEIF/HEIC images, and without it those are skipped
    while every other image type is still OCR'd.  heif-dec was named
    heif-convert before libheif 1.18; both names are recognised, and the
    path to either can be set with image_heif_dec_path.

  - pdftotext (from poppler)

    Used by the optional PDF handler (see v403.pre) to extract text from
    PDF attachments; the PDF metadata checks are pure Perl and work
    without it.  Also usable from the ExtractText plugin.

  - unrar

    Used by the optional Archive handler (see v403.pre) to open rar
    attachments.


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: