1Welcome to Apache SpamAssassin!
2-------------------------------
3
4What is Apache SpamAssassin
5---------------------------
6
7Apache SpamAssassin is the #1 Open Source anti-spam platform giving
8system administrators a filter to classify email and block "spam"
9(unsolicited bulk email). It uses a robust scoring framework and plug-ins
10to integrate a wide range of advanced heuristic and statistical analysis
11tests on email headers and body text including text analysis, Bayesian
12filtering, DNS blocklists, and collaborative filtering databases.
13
14Apache SpamAssassin is a project of the Apache Software Foundation (ASF).
15
16
17What Apache SpamAssassin is Not
18-------------------------------
19
20Apache SpamAssassin is not a program to delete spam, route spam and ham to
21separate mailboxes or folders, or send bounces when you receive spam.
22Those are mail routing functions, and Apache SpamAssassin is not a mail
23router. Apache SpamAssassin is a mail filter or classifier. It will examine
24each message presented to it, and assign a score indicating the
25likelihood that the mail is spam. An external program must then
26examine this score and do any routing the user wants done. There are
27many programs that will easily perform these functions after examining
28the score assigned by Apache SpamAssassin.
29
30
31How Apache SpamAssassin Works
32-----------------------------
33
34Apache SpamAssassin uses a wide range of heuristic tests on mail headers and
35body text to identify "spam", also known as unsolicited commercial
36email.
37
38Once identified, the mail can then be optionally tagged as spam for
39later filtering using the user's own mail user-agent application.
40
41Apache SpamAssassin typically differentiates successfully between spam and
42non-spam in between 95% and 100% of cases, depending on what kind of mail
43you get and your training of its Bayesian filter. Specifically,
44Apache SpamAssassin has been shown to produce around 1.5% false negatives (spam
45that was missed) and around 0.06% false positives (ham incorrectly marked
46as spam). See the rules/STATISTICS*.txt files for more information.
47
48Apache SpamAssassin also includes plugins to support reporting spam messages
49automatically or manually to collaborative filtering databases such as
50Pyzor, DCC, and Vipul's Razor.
51
52The distribution provides "spamassassin", a command line tool to
53perform filtering, along with the "Mail::SpamAssassin" module set
54which allows Apache SpamAssassin to be used in spam-protection proxy SMTP or
55POP/IMAP server, or a variety of different spam-blocking scenarios.
56
57In addition, "spamd", a daemonized version of Apache SpamAssassin which
58runs persistently, is available. Using its counterpart, "spamc",
59a lightweight client written in C, an MTA can process large volumes of
60mail through Apache SpamAssassin without having to fork/exec a perl interpreter
61for each message.
62
63
64Questions? Need Help?
65---------------------
66
67If you have questions about Apache SpamAssassin, please check the Wiki[1] to
68see if someone has already posted an answer to your question. (The
69Wiki doubles as a FAQ.) Failing that, post a message to the
70spamassassin-users mailing list[2]. If you've found a bug (and you're
71sure it's a bug after checking the Wiki), please file a report in our
72Bugzilla[3].
73
74 [1]: http://wiki.apache.org/spamassassin/
75 [2]: http://wiki.apache.org/spamassassin/MailingLists
76 [3]: http://issues.apache.org/SpamAssassin/
77
78Please also be sure to read the man pages.
79
80
81Upgrading Apache SpamAssassin
82-----------------------------
83
84IMPORTANT: If you are upgrading from a previous major version of Apache
85SpamAssassin, please be sure to read the notes in UPGRADE to find out
86what has changed in a non- backward compatible way.
87
88
89Installing Apache SpamAssassin
90------------------------------
91
92See the INSTALL file.
93
94
95Customizing Apache SpamAssassin
96-------------------------------
97
98These are the configuration files installed by Apache SpamAssassin. The commands
99that can be used therein are listed in the POD documentation for the
100Mail::SpamAssassin::Conf class (run the following command to read it:
101"perldoc Mail::SpamAssassin::Conf"). Note: The following directories are
102the standard defaults that people use. There is an explanation of all the
103default locations that Apache SpamAssassin will look at the end.
104
105 - /usr/share/spamassassin/*.cf:
106
107 Distributed configuration files, with all defaults. Do not modify
108 these, as they are overwritten when you upgrade.
109
110 - /var/lib/spamassassin/*/*.cf:
111
112 Local state directory; updated rulesets, overriding the
113 distributed configuration files, downloaded using "sa-update". Do
114 not modify these, as they are overwritten when you run
115 "sa-update".
116
117 - /etc/mail/spamassassin/*.cf:
118
119 Site config files, for system admins to create, modify, and
120 add local rules and scores to. Modifications here will be
121 appended to the config loaded from the above directory.
122
123 - /etc/mail/spamassassin/*.pre:
124
125 Plugin control files, installed from the distribution. These are
126 used to control what plugins are loaded. Modifications here will
127 be loaded before any configuration loaded from the above
128 directories.
129
130 You want to modify these files if you want to load additional
131 plugins, or inhibit loading a plugin that is enabled by default.
132 If the files exist in /etc/mail/spamassassin, they will not
133 be overwritten during future installs.
134
135 - /usr/share/spamassassin/user_prefs.template:
136
137 Distributed default user preferences. Do not modify this, as it is
138 overwritten when you upgrade.
139
140 - /etc/mail/spamassassin/user_prefs.template:
141
142 Default user preferences, for system admins to create, modify, and
143 set defaults for users' preferences files. Takes precedence over
144 the above prefs file, if it exists.
145
146 Do not put system-wide settings in here; put them in a file in the
147 "/etc/mail/spamassassin" directory ending in ".cf". This file is
148 just a template, which will be copied to a user's home directory
149 for them to change.
150
151 - $USER_HOME/.spamassassin:
152
153 User state directory. Used to hold spamassassin state, such
154 as a per-user automatic whitelist, and the user's preferences
155 file.
156
157 - $USER_HOME/.spamassassin/user_prefs:
158
159 User preferences file. If it does not exist, one of the
160 default prefs file from above will be copied here for the
161 user to edit later, if they wish.
162
163 Unless you're using spamd, there is no difference in
164 interpretation between the rules file and the preferences file, so
165 users can add new rules for their own use in the
166 "~/.spamassassin/user_prefs" file, if they like. (spamd disables
167 this for security and increased speed.)
168
169 - $USER_HOME/.spamassassin/bayes*
170
171 Statistics databases used for Bayesian filtering. If they do
172 not exist, they will be created by Apache SpamAssassin.
173
174 Spamd users may wish to create a shared set of bayes databases;
175 the "bayes_path" and "bayes_file_mode" configuration settings
176 can be used to do this.
177
178 See "perldoc sa-learn" for more documentation on how
179 to train this.
180
181File Locations:
182
183Apache SpamAssassin will look in a number of areas to find the default
184configuration files that are used. The "__*__" text are variables
185whose value you can see by looking at the first several lines of the
186"spamassassin" or "spamd" scripts.
187
188They are set on install time and can be overridden with the Makefile.PL
189command line options DATADIR (for __def_rules_dir__) and CONFDIR (for
190__local_rules_dir__). If none of these options were given, FHS-compliant
191locations based on the PREFIX (which becomes __prefix__) are chosen.
192These are:
193
194 __prefix__ __def_rules_dir__ __local_rules_dir__
195 -------------------------------------------------------------------------
196 /usr /usr/share/spamassassin /etc/mail/spamassassin
197 /usr/local /usr/local/share/spamassassin /etc/mail/spamassassin
198 /opt/$DIR /opt/$DIR/share/spamassassin /etc/opt/mail/spamassassin
199 $DIR $DIR/share/spamassassin $DIR/etc/mail/spamassassin
200
201The files themselves are then looked for in these paths:
202
203 - Distributed Configuration Files
204 '__def_rules_dir__'
205 '__prefix__/share/spamassassin'
206 '/usr/local/share/spamassassin'
207 '/usr/share/spamassassin'
208
209 - Site Configuration Files
210 '__local_rules_dir__'
211 '__prefix__/etc/mail/spamassassin'
212 '__prefix__/etc/spamassassin'
213 '/usr/local/etc/spamassassin'
214 '/usr/pkg/etc/spamassassin'
215 '/usr/etc/spamassassin'
216 '/etc/mail/spamassassin'
217 '/etc/spamassassin'
218
219 - Default User Preferences File
220 '__local_rules_dir__/user_prefs.template'
221 '__prefix__/etc/mail/spamassassin/user_prefs.template'
222 '__prefix__/share/spamassassin/user_prefs.template'
223 '/etc/spamassassin/user_prefs.template'
224 '/etc/mail/spamassassin/user_prefs.template'
225 '/usr/local/share/spamassassin/user_prefs.template'
226 '/usr/share/spamassassin/user_prefs.template'
227
228
229In addition, the "Distributed Configuration Files" location is overridden
230by a "Local State Directory", used to store an updated copy of the
231ruleset:
232
233 __prefix__ __local_state_dir__
234 -------------------------------------------------------------------------
235 /usr /var/lib/spamassassin/__version__
236 /usr/local /var/lib/spamassassin/__version__
237 /opt/$DIR /var/opt/spamassassin/__version__
238 $DIR $DIR/var/spamassassin/__version__
239
240This is normally written to by the "sa-update" script. "__version__" is
241replaced by a representation of the version number, so that multiple
242versions of Apache SpamAssassin will not interfere with each other's rulesets.
243
244
245After installation, try "perldoc Mail::SpamAssassin::Conf" to see what
246can be set. Common first-time tweaks include:
247
248 - required_score
249
250 Set this higher to make Apache SpamAssassin less sensitive.
251 If you are installing Apache SpamAssassin system-wide, this is
252 **strongly** recommended!
253
254 Statistics on how many false positives to expect at various
255 different thresholds are available in the "STATISTICS.txt" file in
256 the "rules" directory.
257
258 - rewrite_header, add_header
259
260 These options affect the way messages are tagged as spam or
261 non-spam. This makes it easy to identify incoming mail.
262
263 - ok_locales
264
265 If you expect to receive mail in non-ISO-8859 character sets (ie.
266 Chinese, Cyrillic, Japanese, Korean, or Thai) then set this.
267
268
269Learning
270--------
271
272Apache SpamAssassin includes a Bayesian learning filter, so it is worthwhile
273training Apache SpamAssassin with your collection of non-spam and spam,
274if possible. This will make it more accurate for your incoming mail.
275Do this using the "sa-learn" tools, like so:
276
277 sa-learn --spam ~/Mail/saved-spam-folder
278 sa-learn --ham ~/Mail/inbox
279 sa-learn --ham ~/Mail/other-nonspam-folder
280
281
282If these are mail folders in mbox format, use the --mbox switch, for
283Maildirs use a trailing slash, like Maildir/cur/.
284
285Use as many mailboxes as you like. Note that Apache SpamAssassin will remember
286what mails it has learnt from, so you can re-run this as often as you like.
287
288
289Localization
290------------
291
292All text displayed to users is taken from the configuration files. This
293means that you can translate messages, test descriptions, and templates
294into other languages.
295
296If you do so, we would *really* appreciate it if you could contribute
297these translations, so that they can be added to the
298distribution. Please file a bug in our Bugzilla[4], and attach your
299translations. You will, of course, be credited for this work!
300
301 [4]: http://issues.apache.org/SpamAssassin/
302
303
304Disabled code
305-------------
306
307There are some tests and code in Apache SpamAssassin that are turned off by
308default: experimental code, slow code, or code that depends on
309non-open-source software or services that are not always free. These
310disabled tests include:
311
312 - DCC: depends on non-open-source software (disabled in init.pre)
313 - MAPS: commercial service (disabled in 50_scores.cf)
314 - TextCat: slow (disabled in init.pre)
315 - various optional plugins, disabled for speed (disabled in *.pre)
316
317To turn on tests disabled in 50_scores.cf, simply assign them a non-zero
318score, e.g. by adding score lines to your ~/.spamassassin/user_prefs file.
319
320To turn on tests disabled by commenting out the required plugin in
321init.pre, you need to uncomment the loadplugin line and make sure the
322prerequisites for proper operation of the plugin are present.
323
324
325Automatic Reputation System
326--------------------------
327
328Apache SpamAssassin includes an automatic reputation system. The way it works is
329by tracking for each sender address a rolling average score of messages
330so far seen from there. Then, it combines this long-term average score
331for the sender with the score for the particular message being evaluated,
332after all other rules have been applied.
333
334This functionality can be enabled or disabled with the
335"use_txrep" option.
336
337For more information, read sql/README.txrep
338
339(end of README)
340
341// vim:tw=74:
342