proxmox-mirrors/proxmox-spamassassin
1
0
Fork 0
mirror of https://git.proxmox.com/git/proxmox-spamassassin synced 2025-04-28 14:08:15 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity
ae52237fd8
proxmox-spamassassin/upstream/INSTALL
Stoiko Ivanov ae52237fd8 update SpamAssassin to 4.0.0 
generated by make update-upstream

Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
2023-03-13 21:13:17 +01:00

459 lines
16 KiB
Plaintext
Raw Blame History

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:
Reference in New Issue View Git Blame Copy Permalink