INSTALL - spamassassin - Git at Google

 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
 	Fedora: yum install spamassassin

 Alternatively download the tarfile, zipfile, and/or build your own RPM
 from http://spamassassin.apache.org/.  Building from tar/zip file is
 usually as simple as:

 	[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]

 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.

 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 UPGRADE.   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.


 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.

 8. You can now customize SpamAssassin.  See README for more information.


 CPAN
 ----

 Most of the modules listed below are available via the Comprehensive Perl
 Archive Network (CPAN, see http://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.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.

 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::SHA1 (from CPAN)

     The Digest::SHA1 module is used as a cryptographic hash for some
     tests and the Bayes subsystem.

     Debian: apt-get install libdigest-sha1-perl
     Gentoo: emerge dev-perl/Digest-SHA1
     Fedora: yum install perl-Digest-SHA1

   - 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.

     Debian: apt-get install libhtml-parser-perl
     Gentoo: emerge dev-perl/HTML-Parser
     Fedora: yum install perl-HTML-Parser

   - Net::DNS (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.

     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

     Debian/Ubuntu: apt-get install libnet-dns-perl
     Fedora: yum install perl-Net-DNS

   - NetAddr::IP (from CPAN)

     Used to parse IP addresses and IP address ranges for
     "trusted_networks".

     Debian/Ubuntu: apt-get install libnetaddr-ip-perl
     Fedora: yum install perl-NetAddr-IP

   - LWP (aka libwww-perl) (from CPAN)

     This set of modules will include both the LWP::UserAgent and
     HTTP::Date modules, used by sa-update to retrieve update archives.

     Fedora: yum install perl-libwww-perl

   - HTTP::Date (from CPAN)

     Used by sa-update to deal with certain Date requests.

   - IO::Zlib (from CPAN)

     Used by sa-update to uncompress update archives.
     Version 1.04 or later is required.

     Fedora: yum install perl-IO-Zlib

   - Archive::Tar (from CPAN)

     Used by sa-update to expand update archives.
     Version 1.23 or later is required.

     Fedora: yum install perl-Archive-Tar


 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::SMTP (from CPAN)

     Used when manually reporting spam to SpamCop.


   - Mail::SPF (from CPAN) or 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.

     Either of Mail::SPF or Mail::SPF::Query can be used but Mail::SPF is
     preferred as it is the current reference implementation for RFC 4408.

     Net::DNS version 0.58 or higher is required to use Mail::SPF.
     Net::DNS version 0.34 or higher is required to use Mail::SPF::Query.

     If using Mail::SPF note that NetAddr::IP (required by Mail::SPF)
     versions up to and including version 4.006 include a bug that will
     slow down the entire perl interpreter.  NetAddr::IP version 4.007 or
     later fixes this.


   - 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.


   - Net::Ident (from CPAN)

     If you plan to use the --auth-ident option to spamd, you will need
     to install this module.


   - IO::Socket::INET6 (from CPAN)

     This is required if the first nameserver listed in your IP
     configuration or /etc/resolv.conf file is available only via an IPv6
     address.

     Fedora: yum install perl-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
     compatibile spamc.)

     Fedora: yum install perl-IO-Socket-SSL


   - Compress::Zlib (from CPAN)

     If you wish to use the optional zlib compression for communication
     between spamc and spamd (the -z option to spamc), useful for
     long-distance use of spamc over the internet, you need to install
     this module.

     Fedora: yum install perl-Compress-Zlib


   - Time::HiRes (from CPAN)

     If this module is installed, the processing times are logged/reported
     more precisely.


   - 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.  If Mail::DKIM version 0.20 or later
     is installed, this will also perform Domain Key lookups on
     DomainKey-Signature headers, without requiring the Mail::DomainKeys
     module.

     Note that the Mail::DKIM module in turn requres the OpenSSL libraries.


   - Mail::DomainKeys (from CPAN)

     If this module is installed, and you enable the DomainKeys plugin,
     SpamAssassin will perform Domain Key lookups when Domain Key
     information is present in the message headers.

     Note that Mail::DKIM version 0.20 or later will perform Domain Key
     lookups, so this may be redundant.

     Note that the Mail::DomainKeys module in turn requres the OpenSSL
     libraries and the CPAN module Crypt::OpenSSL::Bignum.


   - 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.


   - Encode::Detect (from CPAN)

     If you plan to use the normalize_charset config setting to detect
     charsets and convert them into Unicode, you will need to install
     this module.


   - Apache::Test (from CPAN)

     If you plan to run the Apache2 version of spamd in the
     "spamd-apache2" directory, you will need to install this
     module.


   - Apache 2 and mod_perl

     If you plan to run the Apache2 version of spamd in the "spamd-apache2"
     directory, you will need to ensure these are installed.

     Ubuntu: sudo apt-get install apache2 libapache2-mod-perl2


   - 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".


 What Next?
 ----------

 Take a look at the USAGE document for more information on how to use
 SpamAssassin.

 The SpamAssassin Wiki <http://wiki.spamassassin.org/> contains
 information on custom plugins, extensions, and other optional modules
 included with SpamAssassin.


 (end of INSTALL)

 // vim:tw=74:
	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
	Fedora: yum install spamassassin

	Alternatively download the tarfile, zipfile, and/or build your own RPM
	from http://spamassassin.apache.org/. Building from tar/zip file is
	usually as simple as:

	[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]

	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.

	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 UPGRADE. 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.


	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.

	8. You can now customize SpamAssassin. See README for more information.


	CPAN
	----

	Most of the modules listed below are available via the Comprehensive Perl
	Archive Network (CPAN, see http://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.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.

	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::SHA1 (from CPAN)

	The Digest::SHA1 module is used as a cryptographic hash for some
	tests and the Bayes subsystem.

	Debian: apt-get install libdigest-sha1-perl
	Gentoo: emerge dev-perl/Digest-SHA1
	Fedora: yum install perl-Digest-SHA1

	- 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.

	Debian: apt-get install libhtml-parser-perl
	Gentoo: emerge dev-perl/HTML-Parser
	Fedora: yum install perl-HTML-Parser

	- Net::DNS (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.

	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

	Debian/Ubuntu: apt-get install libnet-dns-perl
	Fedora: yum install perl-Net-DNS

	- NetAddr::IP (from CPAN)

	Used to parse IP addresses and IP address ranges for
	"trusted_networks".

	Debian/Ubuntu: apt-get install libnetaddr-ip-perl
	Fedora: yum install perl-NetAddr-IP

	- LWP (aka libwww-perl) (from CPAN)

	This set of modules will include both the LWP::UserAgent and
	HTTP::Date modules, used by sa-update to retrieve update archives.

	Fedora: yum install perl-libwww-perl

	- HTTP::Date (from CPAN)

	Used by sa-update to deal with certain Date requests.

	- IO::Zlib (from CPAN)

	Used by sa-update to uncompress update archives.
	Version 1.04 or later is required.

	Fedora: yum install perl-IO-Zlib

	- Archive::Tar (from CPAN)

	Used by sa-update to expand update archives.
	Version 1.23 or later is required.

	Fedora: yum install perl-Archive-Tar


	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::SMTP (from CPAN)

	Used when manually reporting spam to SpamCop.


	- Mail::SPF (from CPAN) or 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.

	Either of Mail::SPF or Mail::SPF::Query can be used but Mail::SPF is
	preferred as it is the current reference implementation for RFC 4408.

	Net::DNS version 0.58 or higher is required to use Mail::SPF.
	Net::DNS version 0.34 or higher is required to use Mail::SPF::Query.

	If using Mail::SPF note that NetAddr::IP (required by Mail::SPF)
	versions up to and including version 4.006 include a bug that will
	slow down the entire perl interpreter. NetAddr::IP version 4.007 or
	later fixes this.


	- 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.


	- Net::Ident (from CPAN)

	If you plan to use the --auth-ident option to spamd, you will need
	to install this module.


	- IO::Socket::INET6 (from CPAN)

	This is required if the first nameserver listed in your IP
	configuration or /etc/resolv.conf file is available only via an IPv6
	address.

	Fedora: yum install perl-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
	compatibile spamc.)

	Fedora: yum install perl-IO-Socket-SSL


	- Compress::Zlib (from CPAN)

	If you wish to use the optional zlib compression for communication
	between spamc and spamd (the -z option to spamc), useful for
	long-distance use of spamc over the internet, you need to install
	this module.

	Fedora: yum install perl-Compress-Zlib


	- Time::HiRes (from CPAN)

	If this module is installed, the processing times are logged/reported
	more precisely.


	- 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. If Mail::DKIM version 0.20 or later
	is installed, this will also perform Domain Key lookups on
	DomainKey-Signature headers, without requiring the Mail::DomainKeys
	module.

	Note that the Mail::DKIM module in turn requres the OpenSSL libraries.


	- Mail::DomainKeys (from CPAN)

	If this module is installed, and you enable the DomainKeys plugin,
	SpamAssassin will perform Domain Key lookups when Domain Key
	information is present in the message headers.

	Note that Mail::DKIM version 0.20 or later will perform Domain Key
	lookups, so this may be redundant.

	Note that the Mail::DomainKeys module in turn requres the OpenSSL
	libraries and the CPAN module Crypt::OpenSSL::Bignum.


	- 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.


	- Encode::Detect (from CPAN)

	If you plan to use the normalize_charset config setting to detect
	charsets and convert them into Unicode, you will need to install
	this module.


	- Apache::Test (from CPAN)

	If you plan to run the Apache2 version of spamd in the
	"spamd-apache2" directory, you will need to install this
	module.


	- Apache 2 and mod_perl

	If you plan to run the Apache2 version of spamd in the "spamd-apache2"
	directory, you will need to ensure these are installed.

	Ubuntu: sudo apt-get install apache2 libapache2-mod-perl2


	- 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".


	What Next?
	----------

	Take a look at the USAGE document for more information on how to use
	SpamAssassin.

	The SpamAssassin Wiki <http://wiki.spamassassin.org/> contains
	information on custom plugins, extensions, and other optional modules
	included with SpamAssassin.


	(end of INSTALL)

	// vim:tw=74: