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.14.0 or a later version is required. 226 227 228Required Perl Modules 229--------------------- 230 231In addition to the modules associated with Perl, some additional modules 232need to be installed or upgraded depending on the version of Perl that you 233are running. 234 235You can get an immediate report on which of these modules you may need (or 236want) to upgrade, by running "perl build/check_dependencies" from the 237SpamAssassin build directory. 238 239The list of required modules that do not ship with Perl and must be 240installed: 241 242 - Digest::SHA1 (from CPAN) 243 244 An external perl module razor-agents-2.84 as used by a Razor2 plugin 245 seems to be the only remaining component depending on Digest::SHA1 246 (note that a packager may ship a patched version of razor-agents which 247 can use Digest::SHA instead) 248 249 Debian: apt-get install libdigest-sha1-perl 250 Gentoo: emerge dev-perl/Digest-SHA1 251 Fedora: yum install perl-Digest-SHA1 252 253 - HTML::Parser >= 3.43 (from CPAN) 254 255 HTML is used for an ever-increasing amount of email so this dependency 256 is unavoidable. Run "perldoc -q html" for additional information. 257 258 Debian: apt-get install libhtml-parser-perl 259 Gentoo: emerge dev-perl/HTML-Parser 260 Fedora: yum install perl-HTML-Parser 261 262 - Net::DNS (from CPAN) 263 264 Used for all DNS-based tests (SBL, XBL, SpamCop, DSBL, etc.), 265 perform MX checks, used when manually reporting spam to SpamCop, 266 and used by sa-update to gather version information. 267 268 You need to make sure the Net::DNS version is sufficiently up-to-date: 269 270 - version 0.34 or higher on Unix systems 271 - version 0.46 or higher on Windows systems 272 273 Debian/Ubuntu: apt-get install libnet-dns-perl 274 Fedora: yum install perl-Net-DNS 275 276 - NetAddr::IP (from CPAN) 277 278 Used to parse IP addresses and IP address ranges for 279 "trusted_networks". 280 281 Debian/Ubuntu: apt-get install libnetaddr-ip-perl 282 Fedora: yum install perl-NetAddr-IP 283 284 - LWP (aka libwww-perl) (from CPAN) 285 286 This set of modules will include both the LWP::UserAgent and 287 HTTP::Date modules, used by sa-update to retrieve update archives. 288 289 Fedora: yum install perl-libwww-perl 290 291 - HTTP::Date (from CPAN) 292 293 Used by sa-update to deal with certain Date requests. 294 295 296 297Optional Modules 298---------------- 299 300In addition, the following modules will be used for some checks, if 301available and the version is high enough. If they are not available or if 302their version is too low, SpamAssassin will still work, just not as 303effectively because some of the spam-detection tests will have to be 304skipped. 305 306Note: SpamAssassin will not warn you if these are installed, but the 307version is too low for them to be used. 308 309 - MIME::Base64 310 311 This module is highly recommended to increase the speed with which 312 Base64 encoded messages/mail parts are decoded. 313 314 315 - DB_File (from CPAN, included in many distributions) 316 317 Used to store data on-disk, for the Bayes-style logic, TxRep, and 318 auto-whitelist. *Much* more efficient than the other standard Perl 319 database packages. Strongly recommended. 320 321 There seems to be a bug in libdb 4.1.25, which is 322 distributed by default on some versions of Linux. See 323 http://wiki.apache.org/spamassassin/DbFileSleepBug for details. 324 325 326 - Net::SMTP (from CPAN) 327 328 Used when manually reporting spam to SpamCop. 329 330 331 - Mail::SPF (from CPAN) 332 333 Used to check DNS Sender Policy Framework (SPF) records to fight email 334 address forgery and make it easier to identify spams. 335 336 Net::DNS version 0.58 or higher is required. 337 338 Note that NetAddr::IP (required by Mail::SPF) versions up to and 339 including version 4.006 include a bug that will slow down the entire 340 perl interpreter. NetAddr::IP version 4.007 or later fixes this. 341 342 343 - Geo::IP (from CPAN) 344 345 Used by the RelayCountry plugin (not enabled by default) to determine 346 the domain country codes of each relay in the path of an email. 347 348 IP::Country::Fast is used as alternative if Geo::IP is not installed. 349 This is not recommended as it's obsolete. 350 351 352 - Net::Ident (from CPAN) 353 354 If you plan to use the --auth-ident option to spamd, you will need 355 to install this module. 356 357 358 - IO::Socket::INET6 (from CPAN) 359 360 This is required if the first nameserver listed in your IP 361 configuration or /etc/resolv.conf file is available only via an IPv6 362 address. 363 364 Fedora: yum install perl-IO-Socket-INET6 365 366 367 - IO::Socket::SSL (from CPAN) 368 369 If you wish to use SSL encryption to communicate between spamc and 370 spamd (the --ssl option to spamd), you need to install this 371 module. (You will need the OpenSSL libraries and use the 372 ENABLE_SSL="yes" argument to Makefile.PL to build and run an SSL 373 compatible spamc.) 374 375 Fedora: yum install perl-IO-Socket-SSL 376 377 378 - Compress::Zlib (from CPAN) 379 380 If you wish to use the optional zlib compression for communication 381 between spamc and spamd (the -z option to spamc), useful for 382 long-distance use of spamc over the internet, you need to install 383 this module. 384 385 Fedora: yum install perl-Compress-Zlib 386 387 388 - Mail::DKIM (from CPAN) 389 390 If this module is installed, and you enable the DKIM plugin, 391 SpamAssassin will perform DKIM lookups when a DKIM-Signature header is 392 present in the message headers. Current versions of Mail::DKIM (0.20 393 or later) also perform Domain Key lookups on DomainKey-Signature headers, 394 without requiring the Mail::DomainKeys module, which is now obsolete. 395 Version 0.37 or later is preferred, the absolute minimal version is 0.31. 396 397 Note that the Mail::DKIM module in turn requires the Digest::SHA module 398 and OpenSSL libraries. 399 400 401 - DBI *and* DBD driver/modules for your database (from CPAN) 402 403 If you intend to use SpamAssassin with an SQL database backend for 404 user configuration data, Bayes storage, or other storage, you will need 405 to have these installed; both the basic DBI module and the driver for 406 your database. 407 408 409 - Encode::Detect (from CPAN) 410 411 If you plan to use the normalize_charset config setting to detect 412 charsets and convert them into Unicode, you will need to install 413 this module. 414 415 416 - Apache::Test (from CPAN) 417 418 If you plan to run the Apache2 version of spamd in the 419 "spamd-apache2" directory, you will need to install this 420 module. 421 422 423 - Apache 2 and mod_perl 424 425 If you plan to run the Apache2 version of spamd in the "spamd-apache2" 426 directory, you will need to ensure these are installed. 427 428 Ubuntu: sudo apt-get install apache2 libapache2-mod-perl2 429 430 431 - Razor2 432 433 If you plan to use Vipul's Razor, note that versions up to and 434 including version 2.82 include a bug that will slow down the entire 435 perl interpreter. Version 2.83 or later fixes this. 436 437 If you do not plan to use this plugin, be sure to comment out 438 its loadplugin line in "/etc/mail/spamassassin/v310.pre". 439 440 441What Next? 442---------- 443 444Take a look at the USAGE document for more information on how to use 445SpamAssassin. 446 447The SpamAssassin Wiki <http://wiki.spamassassin.org/> contains 448information on custom plugins, extensions, and other optional modules 449included with SpamAssassin. 450 451 452(end of INSTALL) 453 454// vim:tw=74: 455