1Upgrading SpamAssassin? 2----------------------- 3 4Please be sure to read the UPGRADE file for important changes that 5have been made since previous versions. In particular, 3.3.0 no 6longer includes a default ruleset. 7 8 9Installing or Upgrading SpamAssassin 10------------------------------------ 11 12Using CPAN via CPAN.pm: 13 14 perl -MCPAN -e shell [as root] 15 o conf prerequisites_policy ask 16 install Mail::SpamAssassin 17 quit 18 19Using Linux: 20 21 Debian unstable: apt-get install spamassassin 22 Gentoo: emerge mail-filter/spamassassin 23 Fedora: yum install spamassassin 24 25Alternatively download the tarfile, zipfile, and/or build your own RPM 26from https://spamassassin.apache.org/. Building from tar/zip file is 27usually as simple as: 28 29 [unzip/untar the archive] 30 cd Mail-SpamAssassin-* 31 perl Makefile.PL 32 [option: add -DSPAMC_SSL to $CFLAGS to build an SSL-enabled spamc] 33 make 34 make install [as root] 35 36After installing SpamAssassin, you need to download and install the 37SpamAssassin ruleset using "sa-update". See the "Installing Rules" 38section below. 39 40Please make sure to read this whole document before installing, especially 41the prerequisite information further down. 42 43To install as non-root, see the directions below. 44 45If you are running AFS, you may also need to specify INSTALLSITELIB and 46SITELIBEXP. 47 48Note that you can upgrade SpamAssassin using these instructions, as long 49as you take care to read the caveats in the file UPGRADE. Upgrading 50will not delete your learnt Bayes data or local rule modifications. 51 52If you're using SunOS 4.1.x, see 53http://wiki.spamassassin.org/w/BuildingOnSunOS4 for build tips. 54 55 56Installing SpamAssassin for Personal Use (Not System-Wide) 57---------------------------------------------------------- 58 59These steps assume the following, so substitute as necessary: 60 - Your UNIX login is "user" 61 - Your home directory is /home/user 62 - The location of the procmail executable is /usr/bin/procmail 63 64Many more details of this process are at 65http://wiki.apache.org/spamassassin/SingleUserUnixInstall 66 671. Uncompress and extract the SpamAssassin archive, using "unzip" or 68 "tar xvfz", in a temporary directory. 69 702. change directory into it: 71 72 cd Mail-SpamAssassin-* 73 743. Make SpamAssassin as normal, but using your home directory as the 75 target: 76 77 perl Makefile.PL PREFIX=$HOME 78 make 79 make install 80 81 Please see the file PACKAGING, sections "Changing paths in the Makefile" 82 and "Setting further options on the command line" for more information 83 on available command line variables. 84 854. Install the SpamAssassin ruleset using "sa-update": 86 87 $HOME/bin/sa-update 88 89 See the "Installing Rules" section below if you do not wish to download 90 the rules directly from the internet. 91 92 NOTE: Because LWP does not support IPv6, sa-update as of 3.4.0 will use 93 the binaries curl, wget or fetch to download rule updates with LWP used 94 as a fallback if none of the binaries exist. 95 965. If you already use procmail, skip to step 7. If not, ensure procmail 97 is installed using "which procmail" or install it from www.procmail.org. 98 996. Create a .forward file in your home directory containing the below 100 lines: 101 102"|IFS=' ' && exec /usr/bin/procmail -f- || exit 75 #user" 103 1047. Edit or create a .procmailrc file in your home directory containing the 105 below lines. If you already have a .procmailrc file, add the lines to 106 the top of your .procmailrc file: 107 108:0fw: spamassassin.lock 109| /home/user/bin/spamassassin 110 111 The above line filters all incoming mail through SpamAssassin and tags 112 probable spam with a unique header. If you would prefer to have spam 113 blocked and saved to a file called "caughtspam" in your home directory, 114 instead of passed through and tagged, append this directly below the above 115 lines: 116 117:0: 118* ^X-Spam-Status: Yes 119caughtspam 120 121Also, see the file procmailrc.example and 122http://wiki.apache.org/spamassassin/UsedViaProcmail 123 1248. Now, you should be ready to send some test emails and ensure everything 125 works as expected. First, send yourself a test email that doesn't 126 contain anything suspicious. You should receive it normally, but there 127 will be a header containing "X-Spam-Status: No". If you are only 128 tagging your spam, send yourself a copy of the GTUBE test string to 129 check to be sure it is marked as spam. GTUBE is located in the 130 sample-spam.txt message distributed with SpamAssassin and also at: 131 132 https://spamassassin.apache.org/gtube/ 133 134 If your test emails don't get through to you, immediately rename your 135 .forward file until you figure out cause of the the problem, so you 136 don't lose incoming email. 137 138 Note: one possible cause for this is the use of smrsh on the MTA system; 139 see http://wiki.spamassassin.org/w/ProcmailVsSmrsh for details. 140 1419. You can now customize SpamAssassin. See README for more information. 142 143 144Installing Rules 145---------------- 146 147Rules are normally installed by running a sa-update command. 148The version of sa-update program should match the version of SpamAssassin 149modules, so invoking sa-update should be performed only after installing 150or upgrading SpamAssassin code, not before. 151 152Installing rules from network is done with a single command: 153 154 sa-update 155 156This is normally run as root. 157 158If you wish to install rules from downloaded files, rather than "live" from 159the latest online ruleset, here is how to do it. 160 161Obtain all the following files: 162 163 Mail-SpamAssassin-rules-xxx.tgz 164 Mail-SpamAssassin-rules-xxx.tgz.asc 165 Mail-SpamAssassin-rules-xxx.tgz.md5 166 Mail-SpamAssassin-rules-xxx.tgz.sha1 167 (where xxx may look something like '3.3.0-rc1.r893295') 168 169Save them all to the current directory. 170Obtain a rules-signing public key: 171 172 curl -O https://spamassassin.apache.org/updates/GPG.KEY 173 174Import the signing key to the SpamAssassin gpg keyring, so that the rules 175files can be verified safely: 176 177 sa-update --import GPG.KEY 178 179Install rules from a compressed tar archive: 180 181 sa-update --install Mail-SpamAssassin-rules-xxx.tgz 182 183Note that the ".tgz.asc", ".tgz.md5" and ".tgz.sha1" files all need to 184be in the same directory, otherwise sa-update will fail. 185 186 187If the intended rules destination directory differs from a default location 188as assumed by sa-update and SpamAssassin, such as when running a content 189filter within a Unix jail or on an unusual installation, please supply the 190rules destination directory to sa-update through its option --updatedir, 191such as: 192 193 sa-update --updatedir /var/jail/var/db/spamassassin/3.003000 194 195 196CPAN 197---- 198 199Most of the modules listed below are available via the Comprehensive Perl 200Archive Network (CPAN, see http://www.cpan.org/ for more information). 201While each module is different, most can be installed via a few simple 202commands such as: 203 204 $ perl -MCPAN -e shell 205 cpan> o conf prerequisites_policy ask 206 cpan> install Module::Name 207 cpan> quit 208 209If there are problems or questions regarding the installation any of the 210modules, please see the CPAN and relevant module's documentation for more 211information. We can't provide documentation or installation support for 212third party modules. 213 214Additional information about the CPAN module is also available via 215"perldoc CPAN". 216 217Most Linux distributions also offer the CPAN modules in their own native 218formats (RPMs, Debian packages, etc.), so you should be able to find these 219through those mechanisms, too, if you prefer. 220 221 222Required Perl Interpreter 223------------------------- 224 225Perl 5.8.1 or a later version is required. 226Preferred versions are 5.8.8, or 5.10.1 or later. 227 228Most of the functions might still work with Perl 5.6.1 or 5.6.2, 229but 5.6.* is no longer a supported version. 230 231 232Required Perl Modules 233--------------------- 234 235In addition to the modules associated with Perl, some additional modules 236need to be installed or upgraded depending on the version of Perl that you 237are running. 238 239You can get an immediate report on which of these modules you may need (or 240want) to upgrade, by running "perl build/check_dependencies" from the 241SpamAssassin build directory. 242 243The list of required modules that do not ship with Perl and must be 244installed: 245 246 - Digest::SHA1 (from CPAN), 247 or the newer Digest::SHA which is a perl base module since Perl 5.10.0 248 249 The Digest::SHA1 module is used as a cryptographic hash for some 250 tests and the Bayes subsystem if Digest::SHA module is not available. 251 252 An external perl module razor-agents-2.84 as used by a Razor2 plugin 253 seems to be the only remaining component depending on Digest::SHA1 254 (note that a packager may ship a patched version of razor-agents which 255 can use Digest::SHA instead) 256 257 Debian: apt-get install libdigest-sha1-perl 258 Gentoo: emerge dev-perl/Digest-SHA1 259 Fedora: yum install perl-Digest-SHA1 260 261 - HTML::Parser >= 3.43 (from CPAN) 262 263 HTML is used for an ever-increasing amount of email so this dependency 264 is unavoidable. Run "perldoc -q html" for additional information. 265 266 Debian: apt-get install libhtml-parser-perl 267 Gentoo: emerge dev-perl/HTML-Parser 268 Fedora: yum install perl-HTML-Parser 269 270 - Net::DNS (from CPAN) 271 272 Used for all DNS-based tests (SBL, XBL, SpamCop, DSBL, etc.), 273 perform MX checks, used when manually reporting spam to SpamCop, 274 and used by sa-update to gather version information. 275 276 You need to make sure the Net::DNS version is sufficiently up-to-date: 277 278 - version 0.34 or higher on Unix systems 279 - version 0.46 or higher on Windows systems 280 281 Debian/Ubuntu: apt-get install libnet-dns-perl 282 Fedora: yum install perl-Net-DNS 283 284 - NetAddr::IP (from CPAN) 285 286 Used to parse IP addresses and IP address ranges for 287 "trusted_networks". 288 289 Debian/Ubuntu: apt-get install libnetaddr-ip-perl 290 Fedora: yum install perl-NetAddr-IP 291 292 - Time::HiRes (from CPAN) 293 294 Used by asynchronous DNS lookups to operate timeouts with subsecond 295 precision and to report processing times accurately. 296 297 - LWP (aka libwww-perl) (from CPAN) 298 299 This set of modules will include both the LWP::UserAgent and 300 HTTP::Date modules, used by sa-update to retrieve update archives. 301 302 Fedora: yum install perl-libwww-perl 303 304 - HTTP::Date (from CPAN) 305 306 Used by sa-update to deal with certain Date requests. 307 308 - IO::Zlib (from CPAN) 309 310 Used by sa-update to uncompress update archives. 311 Version 1.04 or later is required. 312 313 Fedora: yum install perl-IO-Zlib 314 315 - Archive::Tar (from CPAN) 316 317 Used by sa-update to expand update archives. 318 Version 1.23 or later is required. 319 320 Fedora: yum install perl-Archive-Tar 321 322 323Optional Modules 324---------------- 325 326In addition, the following modules will be used for some checks, if 327available and the version is high enough. If they are not available or if 328their version is too low, SpamAssassin will still work, just not as 329effectively because some of the spam-detection tests will have to be 330skipped. 331 332Note: SpamAssassin will not warn you if these are installed, but the 333version is too low for them to be used. 334 335 - MIME::Base64 336 337 This module is highly recommended to increase the speed with which 338 Base64 encoded messages/mail parts are decoded. 339 340 341 - DB_File (from CPAN, included in many distributions) 342 343 Used to store data on-disk, for the Bayes-style logic, TxRep, and 344 auto-whitelist. *Much* more efficient than the other standard Perl 345 database packages. Strongly recommended. 346 347 There seems to be a bug in libdb 4.1.25, which is 348 distributed by default on some versions of Linux. See 349 http://wiki.apache.org/spamassassin/DbFileSleepBug for details. 350 351 352 - Net::SMTP (from CPAN) 353 354 Used when manually reporting spam to SpamCop. 355 356 357 - Mail::SPF (from CPAN) 358 359 Used to check DNS Sender Policy Framework (SPF) records to fight email 360 address forgery and make it easier to identify spams. This module 361 makes Mail::SPF::Query obsolete. 362 363 Net::DNS version 0.58 or higher is required. 364 365 Note that NetAddr::IP (required by Mail::SPF) versions up to and 366 including version 4.006 include a bug that will slow down the entire 367 perl interpreter. NetAddr::IP version 4.007 or later fixes this. 368 369 370 - Geo::IP (from CPAN) 371 372 Used by the RelayCountry plugin (not enabled by default) to determine 373 the domain country codes of each relay in the path of an email. 374 375 IP::Country::Fast is used as alternative if Geo::IP is not installed. 376 This is not recommended as it's obsolete. 377 378 379 - Net::Ident (from CPAN) 380 381 If you plan to use the --auth-ident option to spamd, you will need 382 to install this module. 383 384 385 - IO::Socket::INET6 (from CPAN) 386 387 This is required if the first nameserver listed in your IP 388 configuration or /etc/resolv.conf file is available only via an IPv6 389 address. 390 391 Fedora: yum install perl-IO-Socket-INET6 392 393 394 - IO::Socket::SSL (from CPAN) 395 396 If you wish to use SSL encryption to communicate between spamc and 397 spamd (the --ssl option to spamd), you need to install this 398 module. (You will need the OpenSSL libraries and use the 399 ENABLE_SSL="yes" argument to Makefile.PL to build and run an SSL 400 compatible spamc.) 401 402 Fedora: yum install perl-IO-Socket-SSL 403 404 405 - Compress::Zlib (from CPAN) 406 407 If you wish to use the optional zlib compression for communication 408 between spamc and spamd (the -z option to spamc), useful for 409 long-distance use of spamc over the internet, you need to install 410 this module. 411 412 Fedora: yum install perl-Compress-Zlib 413 414 415 - Mail::DKIM (from CPAN) 416 417 If this module is installed, and you enable the DKIM plugin, 418 SpamAssassin will perform DKIM lookups when a DKIM-Signature header is 419 present in the message headers. Current versions of Mail::DKIM (0.20 420 or later) also perform Domain Key lookups on DomainKey-Signature headers, 421 without requiring the Mail::DomainKeys module, which is now obsolete. 422 Version 0.37 or later is preferred, the absolute minimal version is 0.31. 423 424 Note that the Mail::DKIM module in turn requires the Digest::SHA module 425 and OpenSSL libraries. 426 427 428 - DBI *and* DBD driver/modules for your database (from CPAN) 429 430 If you intend to use SpamAssassin with an SQL database backend for 431 user configuration data, Bayes storage, or other storage, you will need 432 to have these installed; both the basic DBI module and the driver for 433 your database. 434 435 436 - Encode::Detect (from CPAN) 437 438 If you plan to use the normalize_charset config setting to detect 439 charsets and convert them into Unicode, you will need to install 440 this module. 441 442 443 - Apache::Test (from CPAN) 444 445 If you plan to run the Apache2 version of spamd in the 446 "spamd-apache2" directory, you will need to install this 447 module. 448 449 450 - Apache 2 and mod_perl 451 452 If you plan to run the Apache2 version of spamd in the "spamd-apache2" 453 directory, you will need to ensure these are installed. 454 455 Ubuntu: sudo apt-get install apache2 libapache2-mod-perl2 456 457 458 - Razor2 459 460 If you plan to use Vipul's Razor, note that versions up to and 461 including version 2.82 include a bug that will slow down the entire 462 perl interpreter. Version 2.83 or later fixes this. 463 464 If you do not plan to use this plugin, be sure to comment out 465 its loadplugin line in "/etc/mail/spamassassin/v310.pre". 466 467 468What Next? 469---------- 470 471Take a look at the USAGE document for more information on how to use 472SpamAssassin. 473 474The SpamAssassin Wiki <http://wiki.spamassassin.org/> contains 475information on custom plugins, extensions, and other optional modules 476included with SpamAssassin. 477 478 479(end of INSTALL) 480 481// vim:tw=74: 482