1Mail::SpamAssassin::ConUfs(e3r)Contributed Perl DocumentMaatiilo:n:SpamAssassin::Conf(3)
2
6 Mail::SpamAssassin::Conf - SpamAssassin configuration file
7
9 # a comment
10 rewrite_header Subject *****SPAM*****
12 full PARA_A_2_C_OF_1618 /Paragraph .a.{0,10}2.{0,10}C. of S. 1618/i
14 describe PARA_A_2_C_OF_1618 Claims compliance with senate bill 1618
15 header FROM_HAS_MIXED_NUMS From =~ /\d+[a-z]+\d+\S*@/i
17 describe FROM_HAS_MIXED_NUMS From: contains numbers mixed in with letters
18 score A_HREF_TO_REMOVE 2.0
20 lang es describe FROM_FORGED_HOTMAIL Forzado From: simula ser de hotmail.com
22 lang pt_BR report O programa detetor de Spam ZOE [...]
24
26 SpamAssassin is configured using traditional UNIX-style configuration
27 files, loaded from the "/usr/share/spamassassin" and
28 "/etc/mail/spamassassin" directories.
29 The following web page lists the most important configuration settings
31 used to configure SpamAssassin; novices are encouraged to read it
32 first:
33 https://wiki.apache.org/spamassassin/ImportantInitialConfigItems
35
37 The "#" character starts a comment, which continues until end of line.
38 NOTE: if the "#" character is to be used as part of a rule or
39 configuration option, it must be escaped with a backslash. i.e.: "\#"
40 Whitespace in the files is not significant, but please note that
42 starting a line with whitespace is deprecated, as we reserve its use
43 for multi-line rule definitions, at some point in the future.
44 Currently, each rule or configuration setting must fit on one-line;
46 multi-line settings are not supported yet.
47 File and directory paths can use "~" to refer to the user's home
49 directory, but no other shell-style path extensions such as globing or
50 "~user/" are supported.
51 Where appropriate below, default values are listed in parentheses.
53 Test names ("SYMBOLIC_TEST_NAME") can only contain
55 alphanumerics/underscores, can not start with digit, and must be less
56 than 128 characters.
57
59 The following options can be used in both site-wide ("local.cf") and
60 user-specific ("user_prefs") configuration files to customize how
61 SpamAssassin handles incoming email messages.
62 SCORING OPTIONS
64 required_score n.nn (default: 5)
65 Set the score required before a mail is considered spam. "n.nn"
66 can be an integer or a real number. 5.0 is the default setting,
67 and is quite aggressive; it would be suitable for a single-user
68 setup, but if you're an ISP installing SpamAssassin, you should
69 probably set the default to be more conservative, like 8.0 or 10.0.
70 It is not recommended to automatically delete or discard messages
71 marked as spam, as your users will complain, but if you choose to
72 do so, only delete messages with an exceptionally high score such
73 as 15.0 or higher. This option was previously known as
74 "required_hits" and that name is still accepted, but is deprecated.
75 score SYMBOLIC_TEST_NAME n.nn [ n.nn n.nn n.nn ]
77 Assign scores (the number of points for a hit) to a given test.
78 Scores can be positive or negative real numbers or integers.
79 "SYMBOLIC_TEST_NAME" is the symbolic name used by SpamAssassin for
80 that test; for example, 'FROM_ENDS_IN_NUMS'.
81 If only one valid score is listed, then that score is always used
83 for a test.
84 If four valid scores are listed, then the score that is used
86 depends on how SpamAssassin is being used. The first score is used
87 when both Bayes and network tests are disabled (score set 0). The
88 second score is used when Bayes is disabled, but network tests are
89 enabled (score set 1). The third score is used when Bayes is
90 enabled and network tests are disabled (score set 2). The fourth
91 score is used when Bayes is enabled and network tests are enabled
92 (score set 3).
93 Setting a rule's score to 0 will disable that rule from running.
95 If any of the score values are surrounded by parenthesis '()', then
97 all of the scores in the line are considered to be relative to the
98 already set score. ie: '(3)' means increase the score for this
99 rule by 3 points in all score sets. '(3) (0) (3) (0)' means
100 increase the score for this rule by 3 in score sets 0 and 2 only.
101 If no score is given for a test by the end of the configuration, a
103 default score is assigned: a score of 1.0 is used for all tests,
104 except those whose names begin with 'T_' (this is used to indicate
105 a rule in testing) which receive 0.01.
106 Note that test names which begin with '__' are indirect rules used
108 to compose meta-match rules and can also act as prerequisites to
109 other rules. They are not scored or listed in the 'tests hit'
110 reports, but assigning a score of 0 to an indirect rule will
111 disable it from running.
112 WELCOMELIST AND BLOCKLIST OPTIONS
114 welcomelist_from user@example.com
115 Previously whitelist_from which will work interchangeably until
116 4.1.
117 Used to welcomelist sender addresses which send mail that is often
119 tagged (incorrectly) as spam.
120 Use of this setting is not recommended, since it blindly trusts the
122 message, which is routinely and easily forged by spammers and phish
123 senders. The recommended solution is to instead use
124 "welcomelist_auth" or other authenticated welcomelisting methods,
125 or "welcomelist_from_rcvd".
126 Welcomelist and blocklist addresses are now file-glob-style
128 patterns, so "friend@somewhere.com", "*@isp.com", or "*.domain.net"
129 will all work. Specifically, "*" and "?" are allowed, but all
130 other metacharacters are not. Regular expressions are not used for
131 security reasons. Matching is case-insensitive.
132 Multiple addresses per line, separated by spaces, is OK. Multiple
134 "welcomelist_from" lines are also OK.
135 The headers checked for welcomelist addresses are as follows: if
137 "Resent-From" is set, use that; otherwise check all addresses taken
138 from the following set of headers:
139 Envelope-Sender
141 Resent-Sender
142 X-Envelope-From
143 From
144 In addition, the "envelope sender" data, taken from the SMTP
146 envelope data where this is available, is looked up. See
147 "envelope_sender_header".
148 e.g.
150 welcomelist_from joe@example.com fred@example.com
152 welcomelist_from *@example.com
153 unwelcomelist_from user@example.com
155 Previously unwelcomelist_from which will work interchangeably until
156 4.1.
157 Used to remove a default welcomelist_from entry, so for example a
159 distribution welcomelist_from can be overridden in a local.cf file,
160 or an individual user can override a welcomelist_from entry in
161 their own "user_prefs" file. The specified email address has to
162 match exactly (although case-insensitively) the address previously
163 used in a welcomelist_from line, which implies that a wildcard only
164 matches literally the same wildcard (not 'any' address).
165 e.g.
167 unwelcomelist_from joe@example.com fred@example.com
169 unwelcomelist_from *@example.com
170 welcomelist_from_rcvd addr@lists.sourceforge.net sourceforge.net
172 Previously whitelist_from_rcvd which will work interchangeably
173 until 4.1.
174 Works similarly to welcomelist_from, except that in addition to
176 matching a sender address, a relay's rDNS name or its IP address
177 must match too for the welcomelisting rule to fire. The first
178 parameter is a sender's e-mail address to welcomelist, and the
179 second is a string to match the relay's rDNS, or its IP address.
180 Matching is case-insensitive.
181 This second parameter is matched against a TCP-info information
183 field as provided in a FROM clause of a trace information (i.e. in
184 a Received header field, see RFC 5321). Only the Received header
185 fields inserted by trusted hosts are considered. This parameter can
186 either be a full hostname, or a domain component of that hostname,
187 or an IP address (optionally followed by a slash and a prefix
188 length) in square brackets. The address prefix (mask) length with a
189 slash may stand within brackets along with an address, or may
190 follow the bracketed address. Reverse DNS lookup is done by an MTA,
191 not by SpamAssassin.
192 For backward compatibility as an alternative to a CIDR notation, an
194 IPv4 address in brackets may be truncated on classful boundaries to
195 cover whole subnets, e.g. "[10.1.2.3]", "[10.1.2]", "[10.1]",
196 "[10]".
197 In other words, if the host that connected to your MX had an IP
199 address 192.0.2.123 that mapped to 'sendinghost.example.org', you
200 should specify "sendinghost.example.org", or "example.org", or
201 "[192.0.2.123]", or "[192.0.2.0/24]", or "[192.0.2]" here.
202 Note that this requires that "internal_networks" be correct. For
204 simple cases, it will be, but for a complex network you may get
205 better results by setting that parameter.
206 It also requires that your mail exchangers be configured to perform
208 DNS reverse lookups on the connecting host's IP address, and to
209 record the result in the generated Received header field according
210 to RFC 5321.
211 e.g.
213 welcomelist_from_rcvd joe@example.com example.com
215 welcomelist_from_rcvd *@* mail.example.org
216 welcomelist_from_rcvd *@axkit.org [192.0.2.123]
217 welcomelist_from_rcvd *@axkit.org [192.0.2.0/24]
218 welcomelist_from_rcvd *@axkit.org [192.0.2.0]/24
219 welcomelist_from_rcvd *@axkit.org [2001:db8:1234::/48]
220 welcomelist_from_rcvd *@axkit.org [2001:db8:1234::]/48
221 def_welcomelist_from_rcvd addr@lists.sourceforge.net sourceforge.net
223 Previously def_whitelist_from_rcvd which will work interchangeably
224 until 4.1.
225 Same as "welcomelist_from_rcvd", but used for the default
227 welcomelist entries in the SpamAssassin distribution. The
228 welcomelist score is lower, because these are often targets for
229 spammer spoofing.
230 welcomelist_allows_relays user@example.com
232 Previously whitelist_allows_relays which will work interchangeably
233 until 4.1.
234 Specify addresses which are in "welcomelist_from_rcvd" that
236 sometimes send through a mail relay other than the listed ones. By
237 default mail with a From address that is in "welcomelist_from_rcvd"
238 that does not match the relay will trigger a forgery rule.
239 Including the address in "welcomelist_allows_relay" prevents that.
240 Welcomelist and blocklist addresses are now file-glob-style
242 patterns, so "friend@somewhere.com", "*@isp.com", or "*.domain.net"
243 will all work. Specifically, "*" and "?" are allowed, but all
244 other metacharacters are not. Regular expressions are not used for
245 security reasons. Matching is case-insensitive.
246 Multiple addresses per line, separated by spaces, is OK. Multiple
248 "welcomelist_allows_relays" lines are also OK.
249 The specified email address does not have to match exactly the
251 address previously used in a welcomelist_from_rcvd line as it is
252 compared to the address in the header.
253 e.g.
255 welcomelist_allows_relays joe@example.com fred@example.com
257 welcomelist_allows_relays *@example.com
258 unwelcomelist_from_rcvd user@example.com
260 Previously unwhitelist_from_rcvd which will work interchangeably
261 until 4.1.
262 Used to remove a default welcomelist_from_rcvd or
264 def_welcomelist_from_rcvd entry, so for example a distribution
265 welcomelist_from_rcvd can be overridden in a local.cf file, or an
266 individual user can override a welcomelist_from_rcvd entry in their
267 own "user_prefs" file.
268 The specified email address has to match exactly the address
270 previously used in a welcomelist_from_rcvd line.
271 e.g.
273 unwelcomelist_from_rcvd joe@example.com fred@example.com
275 unwelcomelist_from_rcvd *@axkit.org
276 blocklist_from user@example.com
278 Used to specify addresses which send mail that is often tagged
279 (incorrectly) as non-spam, but which the user doesn't want. Same
280 format as "welcomelist_from".
281 unblocklist_from user@example.com
283 Previously unblacklist_from which will work interchangeably until
284 4.1.
285 Used to remove a default blocklist_from entry, so for example a
287 distribution blocklist_from can be overridden in a local.cf file,
288 or an individual user can override a blocklist_from entry in their
289 own "user_prefs" file. The specified email address has to match
290 exactly the address previously used in a blocklist_from line.
291 e.g.
293 unblocklist_from joe@example.com fred@example.com
295 unblocklist_from *@spammer.com
296 welcomelist_to user@example.com
298 Previously whitelist_to which will work interchangeably until 4.1.
299 If the given address appears as a recipient in the message headers
301 (Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
302 be listed as allowed. Useful if you're deploying SpamAssassin
303 system-wide, and don't want some users to have their mail filtered.
304 Same format as "welcomelist_from".
305 There are three levels of To-welcomelisting, "welcomelist_to",
307 "more_spam_to" and "all_spam_to". Users in the first level may
308 still get some spammish mails blocked, but users in "all_spam_to"
309 should never get mail blocked.
310 The headers checked for welcomelist addresses are as follows: if
312 "Resent-To" or "Resent-Cc" are set, use those; otherwise check all
313 addresses taken from the following set of headers:
314 To
316 Cc
317 Apparently-To
318 Delivered-To
319 Envelope-Recipients
320 Apparently-Resent-To
321 X-Envelope-To
322 Envelope-To
323 X-Delivered-To
324 X-Original-To
325 X-Rcpt-To
326 X-Real-To
327 more_spam_to user@example.com
329 See above.
330 all_spam_to user@example.com
332 See above.
333 blocklist_to user@example.com
335 Previously blacklist_auth which will work interchangeably until
336 4.1.
337 If the given address appears as a recipient in the message headers
339 (Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
340 be blocklisted. Same format as "blocklist_from".
341 welcomelist_auth user@example.com
343 Previously whitelist_auth which will work interchangeably until
344 4.1.
345 Used to specify addresses which send mail that is often tagged
347 (incorrectly) as spam. This is different from "welcomelist_from"
348 and "welcomelist_from_rcvd" in that it first verifies that the
349 message was sent by an authorized sender for the address, before
350 welcomelisting.
351 Authorization is performed using one of the installed sender-
353 authorization schemes: SPF (using
354 "Mail::SpamAssassin::Plugin::SPF"), or DKIM (using
355 "Mail::SpamAssassin::Plugin::DKIM"). Note that those plugins must
356 be active, and working, for this to operate.
357 Using "welcomelist_auth" is roughly equivalent to specifying
359 duplicate "welcomelist_from_spf", "welcomelist_from_dk", and
360 "welcomelist_from_dkim" lines for each of the addresses specified.
361 e.g.
363 welcomelist_auth joe@example.com fred@example.com
365 welcomelist_auth *@example.com
366 def_welcomelist_auth user@example.com
368 Previously def_whitelist_auth which will work interchangeably until
369 4.1.
370 Same as "welcomelist_auth", but used for the default welcomelist
372 entries in the SpamAssassin distribution. The welcomelist score is
373 lower, because these are often targets for spammer spoofing.
374 unwelcomelist_auth user@example.com
376 Previously unwhitelist_auth which will work interchangeably until
377 4.1.
378 Used to remove a "welcomelist_auth" or "def_welcomelist_auth"
380 entry. The specified email address has to match exactly the address
381 previously used.
382 e.g.
384 unwelcomelist_auth joe@example.com fred@example.com
386 unwelcomelist_auth *@example.com
387 enlist_uri_host (listname) host ...
389 Adds one or more host names or domain names to a named list of URI
390 domains. The named list can then be consulted through a
391 check_uri_host_listed() eval rule implemented by the WLBLEval
392 plugin, which takes the list name as an argument. Parenthesis
393 around a list name are literal - a required syntax.
394 Host names may optionally be prefixed by an exclamation mark '!',
396 which produces false as a result if this entry matches. This makes
397 it easier to exclude some subdomains when their superdomain is
398 listed, for example:
399 enlist_uri_host (MYLIST) !sub1.example.com !sub2.example.com example.com
401 No wildcards are supported, but subdomains do match implicitly.
403 Lists are independent. Search for each named list starts by looking
404 up the full hostname first, then leading fields are progressively
405 stripped off (e.g.: sub.example.com, example.com, com) until a
406 match is found or we run out of fields. The first matching entry
407 (the most specific) determines if a lookup yielded a true (no '!'
408 prefix) or a false (with a '!' prefix) result.
409 If an URL found in a message contains an IP address in place of a
411 host name, the given list must specify the exact same IP address
412 (instead of a host name) in order to match.
413 Use the delist_uri_host directive to neutralize previous
415 enlist_uri_host settings.
416 Enlisting to lists named 'BLOCK' and 'WELCOME' have their shorthand
418 directives blocklist_uri_host and welcomelist_uri_host and
419 corresponding default rules, but the names 'BLOCK' and 'WELCOME'
420 are otherwise not special or reserved.
421 delist_uri_host [ (listname) ] host ...
423 Removes one or more specified host names from a named list of URI
424 domains. Removing an unlisted name is ignored (is not an error).
425 Listname is optional, if specified then just the named list is
426 affected, otherwise hosts are removed from all URI host lists
427 created so far. Parenthesis around a list name are a required
428 syntax.
429 Note that directives in configuration files are processed in
431 sequence, the delist_uri_host only applies to previously listed
432 entries and has no effect on enlisted entries in yet-to-be-
433 processed directives.
434 For convenience (similarity to the enlist_uri_host directive)
436 hostnames may be prefixed by a an exclamation mark, which is
437 stripped off from each name and has no meaning here.
438 enlist_addrlist (listname) user@example.com
440 Adds one or more addresses to a named list of addresses. The named
441 list can then be consulted through a check_from_in_list() or a
442 check_to_in_list() eval rule implemented by the WLBLEval plugin,
443 which takes the list name as an argument. Parenthesis around a list
444 name are literal - a required syntax.
445 Listed addresses are file-glob-style patterns, so
447 "friend@somewhere.com", "*@isp.com", or "*.domain.net" will all
448 work. Specifically, "*" and "?" are allowed, but all other
449 metacharacters are not. Regular expressions are not used for
450 security reasons. Matching is case-insensitive.
451 Multiple addresses per line, separated by spaces, is OK. Multiple
453 "enlist_addrlist" lines are also OK.
454 Enlisting an address to the list named blocklist_to is synonymous
456 to using the directive blocklist_to.
457 Enlisting an address to the list named blocklist_from is synonymous
459 to using the directive blocklist_from.
460 Enlisting an address to the list named welcomelist_to is synonymous
462 to using the directive welcomelist_to.
463 Enlisting an address to the list named welcomelist_from is
465 synonymous to using the directive welcomelist_from.
466 e.g.
468 enlist_addrlist (PAYPAL_ADDRESS) service@paypal.com
470 enlist_addrlist (PAYPAL_ADDRESS) *@paypal.co.uk
471 blocklist_uri_host host-or-domain ...
473 Previously blacklist_uri_host which will work interchangeably until
474 4.1.
475 Is a shorthand for a directive: enlist_uri_host (BLOCK) host ...
477 Please see directives enlist_uri_host and delist_uri_host for
479 details.
480 welcomelist_uri_host host-or-domain ...
482 Previously whitelist_uri_host which will work interchangeably until
483 4.1.
484 Is a shorthand for a directive: enlist_uri_host (WELCOME) host ...
486 Please see directives enlist_uri_host and delist_uri_host for
488 details.
489 BASIC MESSAGE TAGGING OPTIONS
491 rewrite_header { subject | from | to } STRING
492 By default, suspected spam messages will not have the "Subject",
493 "From" or "To" lines tagged to indicate spam. By setting this
494 option, the header will be tagged with "STRING" to indicate that a
495 message is spam. For the From or To headers, this will take the
496 form of an RFC 2822 comment following the address in parentheses.
497 For the Subject header, this will be prepended to the original
498 subject. Note that you should only use the _REQD_ and _SCORE_ tags
499 when rewriting the Subject header if "report_safe" is 0. Otherwise,
500 you may not be able to remove the SpamAssassin markup via the
501 normal methods. More information about tags is explained below in
502 the TEMPLATE TAGS section.
503 Parentheses are not permitted in STRING if rewriting the From or To
505 headers. (They will be converted to square brackets.)
506 If "rewrite_header subject" is used, but the message being
508 rewritten does not already contain a "Subject" header, one will be
509 created.
510 A null value for "STRING" will remove any existing rewrite for the
512 specified header.
513 subjprefix
515 Add a prefix in emails Subject if a rule is matched. To enable
516 this option "rewrite_header Subject" config option must be enabled
517 as well.
518 The check "if can(Mail::SpamAssassin::Conf::feature_subjprefix)"
520 should be used to silence warnings in previous SpamAssassin
521 versions.
522 To be able to use this feature a "add_header all Subjprefix
524 _SUBJPREFIX_" configuration line could be needed when the glue
525 between the MTA and SpamAssassin rewrites the email content.
526 Here is an example on how to use this feature:
528 rewrite_header Subject *****SPAM*****
530 add_header all Subjprefix _SUBJPREFIX_
531 body OLEMACRO_MALICE eval:check_olemacro_malice()
532 describe OLEMACRO_MALICE Dangerous Office Macro
533 score OLEMACRO_MALICE 5.0
534 if can(Mail::SpamAssassin::Conf::feature_subjprefix)
535 subjprefix OLEMACRO_MALICE [VIRUS]
536 endif
537 add_header { spam | ham | all } header_name string
539 Customized headers can be added to the specified type of messages
540 (spam, ham, or "all" to add to either). All headers begin with
541 "X-Spam-" (so a "header_name" Foo will generate a header called
542 X-Spam-Foo). header_name is restricted to the character set
543 [A-Za-z0-9_-].
544 The order of "add_header" configuration options is preserved,
546 inserted headers will follow this order of declarations. When
547 combining "add_header" with "clear_headers" and "remove_header",
548 keep in mind that "add_header" appends a new header to the current
549 list, after first removing any existing header fields of the same
550 name. Note also that "add_header", "clear_headers" and
551 "remove_header" may appear in multiple .cf files, which are
552 interpreted in alphabetic order.
553 "string" can contain tags as explained below in the TEMPLATE TAGS
555 section. You can also use "\n" and "\t" in the header to add
556 newlines and tabulators as desired. A backslash has to be written
557 as \\, any other escaped chars will be silently removed.
558 All headers will be folded if fold_headers is set to 1. Note:
560 Manually adding newlines via "\n" disables any further automatic
561 wrapping (ie: long header lines are possible). The lines will still
562 be properly folded (marked as continuing) though.
563 You can customize existing headers with add_header (only the
565 specified subset of messages will be changed).
566 See also "clear_headers" and "remove_header" for removing headers.
568 Here are some examples (these are the defaults, note that Checker-
570 Version can not be changed or removed):
571 add_header spam Flag _YESNOCAPS_
573 add_header all Status _YESNO_, score=_SCORE_ required=_REQD_ tests=_TESTS_ autolearn=_AUTOLEARN_ version=_VERSION_
574 add_header all Level _STARS(*)_
575 add_header all Checker-Version SpamAssassin _VERSION_ (_SUBVERSION_) on _HOSTNAME_
576 remove_header { spam | ham | all } header_name
578 Headers can be removed from the specified type of messages (spam,
579 ham, or "all" to remove from either). All headers begin with
580 "X-Spam-" (so "header_name" will be appended to "X-Spam-").
581 See also "clear_headers" for removing all the headers at once.
583 Note that X-Spam-Checker-Version is not removable because the
585 version information is needed by mail administrators and developers
586 to debug problems. Without at least one header, it might not even
587 be possible to determine that SpamAssassin is running.
588 clear_headers
590 Clear the list of headers to be added to messages. You may use
591 this before any add_header options to prevent the default headers
592 from being added to the message.
593 "add_header", "clear_headers" and "remove_header" may appear in
595 multiple .cf files, which are interpreted in alphabetic order, so
596 "clear_headers" in a later file will remove all added headers from
597 previously interpreted configuration files, which may or may not be
598 desired.
599 Note that X-Spam-Checker-Version is not removable because the
601 version information is needed by mail administrators and developers
602 to debug problems. Without at least one header, it might not even
603 be possible to determine that SpamAssassin is running.
604 report_safe ( 0 | 1 | 2 ) (default: 1)
606 if this option is set to 1, if an incoming message is tagged as
607 spam, instead of modifying the original message, SpamAssassin will
608 create a new report message and attach the original message as a
609 message/rfc822 MIME part (ensuring the original message is
610 completely preserved, not easily opened, and easier to recover).
611 If this option is set to 2, then original messages will be attached
613 with a content type of text/plain instead of message/rfc822. This
614 setting may be required for safety reasons on certain broken mail
615 clients that automatically load attachments without any action by
616 the user. This setting may also make it somewhat more difficult to
617 extract or view the original message.
618 If this option is set to 0, incoming spam is only modified by
620 adding some "X-Spam-" headers and no changes will be made to the
621 body. In addition, a header named X-Spam-Report will be added to
622 spam. You can use the remove_header option to remove that header
623 after setting report_safe to 0.
624 See report_safe_copy_headers if you want to copy headers from the
626 original mail into tagged messages.
627 report_wrap_width (default: 75)
629 This option sets the wrap width for description lines in the
630 X-Spam-Report header, not accounting for tab width.
631 LANGUAGE OPTIONS
633 ok_locales xx [ yy zz ... ] (default: all)
634 This option is used to specify which locales are considered OK for
635 incoming mail. Mail using the character sets that are allowed by
636 this option will not be marked as possibly being spam in a foreign
637 language.
638 If you receive lots of spam in foreign languages, and never get any
640 non-spam in these languages, this may help. Note that all
641 ISO-8859-* character sets, and Windows code page character sets,
642 are always permitted by default.
643 Set this to "all" to allow all character sets. This is the
645 default.
646 The rules "CHARSET_FARAWAY", "CHARSET_FARAWAY_BODY", and
648 "CHARSET_FARAWAY_HEADERS" are triggered based on how this is set.
649 Examples:
651 ok_locales all (allow all locales)
653 ok_locales en (only allow English)
654 ok_locales en ja zh (allow English, Japanese, and Chinese)
655 Note: if there are multiple ok_locales lines, only the last one is
657 used.
658 Select the locales to allow from the list below:
660 en - Western character sets in general
662 ja - Japanese character sets
663 ko - Korean character sets
664 ru - Cyrillic character sets
665 th - Thai character sets
666 zh - Chinese (both simplified and traditional) character sets
667 normalize_charset ( 0 | 1 ) (default: 1)
668 Whether to decode non- UTF-8 and non-ASCII textual parts and recode
669 them to UTF-8 before the text is given over to rules processing.
670 The character set used for attempted decoding is primarily based on
671 a declared character set in a Content-Type header, but if the
672 decoding attempt fails a module Encode::Detect::Detector is
673 consulted (if available) to provide a guess based on the actual
674 text, and decoding is re-attempted. Even if the option is enabled
675 no unnecessary decoding and re-encoding work is done when possible
676 (like with an all-ASCII text with a US-ASCII or extended ASCII
677 character set declaration, e.g. UTF-8 or ISO-8859-nn or Windows-
678 nnnn).
679 Unicode support in old versions of perl or in a core module Encode
681 is likely to be buggy in places, so if the normalize_charset
682 function is enabled it is advised to stick to more recent versions
683 of perl (preferably 5.12 or later). The module
684 Encode::Detect::Detector is optional, when necessary it will be
685 used if it is available.
686 NETWORK TEST OPTIONS
688 trusted_networks IPaddress[/masklen] ... (default: none)
689 What networks or hosts are 'trusted' in your setup. Trusted in
690 this case means that relay hosts on these networks are considered
691 to not be potentially operated by spammers, open relays, or open
692 proxies. A trusted host could conceivably relay spam, but will not
693 originate it, and will not forge header data. DNS blocklist checks
694 will never query for hosts on these networks.
695 See "https://wiki.apache.org/spamassassin/TrustPath" for more
697 information.
698 MXes for your domain(s) and internal relays should also be
700 specified using the "internal_networks" setting. When there are
701 'trusted' hosts that are not MXes or internal relays for your
702 domain(s) they should only be specified in "trusted_networks".
703 The "IPaddress" can be an IPv4 address (in a dot-quad form), or an
705 IPv6 address optionally enclosed in square brackets. Scoped link-
706 local IPv6 addresses are syntactically recognized but the interface
707 scope is currently ignored (e.g. [fe80::1234%eth0] ) and should be
708 avoided.
709 If a "/masklen" is specified, it is considered a CIDR-style
711 'netmask' length, specified in bits. If it is not specified, but
712 less than 4 octets of an IPv4 address are specified with a trailing
713 dot, an implied netmask length covers all addresses in remaining
714 octets (i.e. implied masklen is /8 or /16 or /24). If masklen is
715 not specified, and there is not trailing dot, then just a single IP
716 address specified is used, as if the masklen were "/32" with an
717 IPv4 address, or "/128" in case of an IPv6 address.
718 If module Net::CIDR::Lite is installed, it's also possible to use
720 dash separated IP range format (e.g. 192.168.1.1-192.168.255.255).
721 If a network or host address is prefaced by a "!" the matching
723 network or host will be excluded from the list even if a less
724 specific (shorter netmask length) subnet is later specified in the
725 list. This allows a subset of a wider network to be exempt. In case
726 of specifying overlapping subnets, specify more specific subnets
727 first (tighter matching, i.e. with a longer netmask length),
728 followed by less specific (shorter netmask length) subnets to get
729 predictable results regardless of the search algorithm used - when
730 Net::Patricia module is installed the search finds the tightest
731 matching entry in the list, while a sequential search as used in
732 absence of the module Net::Patricia will find the first matching
733 entry in the list.
734 Note: 127.0.0.0/8 and ::1 are always included in trusted_networks,
736 regardless of your config.
737 Examples:
739 trusted_networks 192.168.0.0/16 # all in 192.168.*.*
741 trusted_networks 192.168. # all in 192.168.*.*
742 trusted_networks 212.17.35.15 # just that host
743 trusted_networks !10.0.1.5 10.0.1/24 # all in 10.0.1.* but not 10.0.1.5
744 trusted_networks 2001:db8:1::1 !2001:db8:1::/64 2001:db8::/32
745 # 2001:db8::/32 and 2001:db8:1::1/128, except the rest of 2001:db8:1::/64
746 This operates additively, so a "trusted_networks" line after
748 another one will append new entries to the list of trusted
749 networks. To clear out the existing entries, use
750 "clear_trusted_networks".
751 If "trusted_networks" is not set and "internal_networks" is, the
753 value of "internal_networks" will be used for this parameter.
754 If neither "trusted_networks" or "internal_networks" is set, a
756 basic inference algorithm is applied. This works as follows:
757 • If the 'from' host has an IP address in a private (RFC 1918)
759 network range, then it's trusted
760 • If there are authentication tokens in the received header, and
762 the previous host was trusted, then this host is also trusted
763 • Otherwise this host, and all further hosts, are consider
765 untrusted.
766 clear_trusted_networks
768 Empty the list of trusted networks.
769 internal_networks IPaddress[/masklen] ... (default: none)
771 What networks or hosts are 'internal' in your setup. Internal
772 means that relay hosts on these networks are considered to be MXes
773 for your domain(s), or internal relays. This uses the same syntax
774 as "trusted_networks", above - see there for details.
775 This value is used when checking 'dial-up' or dynamic IP address
777 blocklists, in order to detect direct-to-MX spamming.
778 Trusted relays that accept mail directly from dial-up connections
780 (i.e. are also performing a role of mail submission agents - MSA)
781 should not be listed in "internal_networks". List them only in
782 "trusted_networks".
783 If "trusted_networks" is set and "internal_networks" is not, the
785 value of "trusted_networks" will be used for this parameter.
786 If neither "trusted_networks" nor "internal_networks" is set, no
788 addresses will be considered local; in other words, any relays past
789 the machine where SpamAssassin is running will be considered
790 external.
791 Every entry in "internal_networks" must appear in
793 "trusted_networks"; in other words, "internal_networks" is always a
794 subset of the trusted set.
795 Note: 127/8 and ::1 are always included in internal_networks,
797 regardless of your config.
798 clear_internal_networks
800 Empty the list of internal networks.
801 msa_networks IPaddress[/masklen] ... (default: none)
803 The networks or hosts which are acting as MSAs in your setup (but
804 not also as MX relays). This uses the same syntax as
805 "trusted_networks", above - see there for details.
806 MSA means that the relay hosts on these networks accept mail from
808 your own users and authenticates them appropriately. These relays
809 will never accept mail from hosts that aren't authenticated in some
810 way. Examples of authentication include, IP lists, SMTP AUTH, POP-
811 before-SMTP, etc.
812 All relays found in the message headers after the MSA relay will
814 take on the same trusted and internal classifications as the MSA
815 relay itself, as defined by your trusted_networks and
816 internal_networks configuration.
817 For example, if the MSA relay is trusted and internal so will all
819 of the relays that precede it.
820 When using msa_networks to identify an MSA it is recommended that
822 you treat that MSA as both trusted and internal. When an MSA is
823 not included in msa_networks you should treat the MSA as trusted
824 but not internal, however if the MSA is also acting as an MX or
825 intermediate relay you must always treat it as both trusted and
826 internal and ensure that the MSA includes visible auth tokens in
827 its Received header to identify submission clients.
828 Warning: Never include an MSA that also acts as an MX (or is also
830 an intermediate relay for an MX) or otherwise accepts mail from
831 non-authenticated users in msa_networks. Doing so will result in
832 unknown external relays being trusted.
833 clear_msa_networks
835 Empty the list of msa networks.
836 originating_ip_headers header ... (default: X-Yahoo-Post-IP
838 X-Originating-IP X-Apparently-From X-SenderIP)
839 A list of header field names from which an originating IP address
840 can be obtained. For example, webmail servers may record a client
841 IP address in X-Originating-IP.
842 These IP addresses are virtually appended into the Received: chain,
844 so they are used in RBL checks where appropriate.
845 Currently the IP addresses are not added into X-Spam-Relays-*
847 header fields, but they may be in the future.
848 clear_originating_ip_headers
850 Empty the list of 'originating IP address' header field names.
851 always_trust_envelope_sender ( 0 | 1 ) (default: 0)
853 Trust the envelope sender even if the message has been passed
854 through one or more trusted relays. See also
855 "envelope_sender_header".
856 skip_rbl_checks ( 0 | 1 ) (default: 0)
858 Turning on the skip_rbl_checks setting will disable the DNSEval
859 plugin, which implements Real-time Block List (or: Blockhole List)
860 (RBL) lookups.
861 By default, SpamAssassin will run RBL checks. Individual blocklists
863 may be disabled selectively by setting a score of a corresponding
864 rule to 0.
865 See also a related configuration parameter skip_uribl_checks, which
867 controls the URIDNSBL plugin (documented in the URIDNSBL man page).
868 dns_available { yes | no | test[: domain1 domain2...] } (default:
870 yes)
871 Tells SpamAssassin whether DNS resolving is available or not. A
872 value yes indicates DNS resolving is available, a value no
873 indicates DNS resolving is not available - both of these values
874 apply unconditionally and skip initial DNS tests, which can be slow
875 or unreliable.
876 When the option value is a test (with or without arguments),
878 SpamAssassin will query some domain names on the internet during
879 initialization, attempting to determine if DNS resolving is working
880 or not. A space-separated list of domain names may be specified
881 explicitly, or left to a built-in default of a dozen or so domain
882 names. From an explicit or a default list a subset of three domain
883 names is picked randomly for checking. The test queries for NS
884 records of these domain: if at least one query returns a success
885 then SpamAssassin considers DNS resolving as available, otherwise
886 not.
887 The problem is that the test can introduce some startup delay if a
889 network connection is down, and in some cases it can wrongly guess
890 that DNS is unavailable because a test connection failed, what
891 causes disabling several DNS-dependent tests.
892 Please note, the DNS test queries for NS records, so specify domain
894 names, not host names.
895 Since version 3.4.0 of SpamAssassin a default setting for option
897 dns_available is yes. A default in older versions was test.
898 dns_server ip-addr-port (default: entries provided by Net::DNS)
900 Specifies an IP address of a DNS server, and optionally its port
901 number. The dns_server directive may be specified multiple times,
902 each entry adding to a list of available resolving name servers.
903 The ip-addr-port argument can either be an IPv4 or IPv6 address,
904 optionally enclosed in brackets, and optionally followed by a colon
905 and a port number. In absence of a port number a standard port
906 number 53 is assumed. When an IPv6 address is specified along with
907 a port number, the address must be enclosed in brackets to avoid
908 parsing ambiguity regarding a colon separator. A scoped link-local
909 IP address is allowed (assuming underlying modules allow it).
910 Examples :
912 dns_server 127.0.0.1
913 dns_server 127.0.0.1:53
914 dns_server [127.0.0.1]:53
915 dns_server [::1]:53
916 dns_server fe80::1%lo0
917 dns_server [fe80::1%lo0]:53
918 In absence of dns_server directives, the list of name servers is
920 provided by Net::DNS module, which typically obtains the list from
921 /etc/resolv.conf, but this may be platform dependent. Please
922 consult the Net::DNS::Resolver documentation for details.
923 clear_dns_servers
925 Empty the list of explicitly configured DNS servers through a
926 dns_server directive, falling back to Net::DNS -supplied defaults.
927 dns_local_ports_permit ranges...
929 Add the specified ports or ports ranges to the set of allowed port
930 numbers that can be used as local port numbers when sending DNS
931 queries to a resolver.
932 The argument is a whitespace-separated or a comma-separated list of
934 single port numbers n, or port number pairs (i.e. m-n) delimited by
935 a '-', representing a range. Allowed port numbers are between 1 and
936 65535.
937 Directives dns_local_ports_permit and dns_local_ports_avoid are
939 processed in order in which they appear in configuration files.
940 Each directive adds (or subtracts) its subsets of ports to a
941 current set of available ports. Whatever is left in the set by the
942 end of configuration processing is made available to a DNS
943 resolving client code.
944 If the resulting set of port numbers is empty (see also the
946 directive dns_local_ports_none), then SpamAssassin does not apply
947 its ports randomization logic, but instead leaves the operating
948 system to choose a suitable free local port number.
949 The initial set consists of all port numbers in the range
951 1024-65535. Note that system config files already modify the set
952 and remove all the IANA registered port numbers and some other
953 ranges, so there is rarely a need to adjust the ranges by site-
954 specific directives.
955 See also directives dns_local_ports_permit and
957 dns_local_ports_none.
958 dns_local_ports_avoid ranges...
960 Remove specified ports or ports ranges from the set of allowed port
961 numbers that can be used as local port numbers when sending DNS
962 queries to a resolver.
963 Please see directive dns_local_ports_permit for details.
965 dns_local_ports_none
967 Is a fast shorthand for:
968 dns_local_ports_avoid 1-65535
970 leaving the set of available DNS query local port numbers empty. In
972 all respects (apart from speed) it is equivalent to the shown
973 directive, and can be freely mixed with dns_local_ports_permit and
974 dns_local_ports_avoid.
975 If the resulting set of port numbers is empty, then SpamAssassin
977 does not apply its ports randomization logic, but instead leaves
978 the operating system to choose a suitable free local port number.
979 See also directives dns_local_ports_permit and
981 dns_local_ports_avoid.
982 dns_test_interval n (default: 600 seconds)
984 If dns_available is set to test, the dns_test_interval time in
985 number of seconds will tell SpamAssassin how often to retest for
986 working DNS. A numeric value is optionally suffixed by a time unit
987 (s, m, h, d, w, indicating seconds (default), minutes, hours, days,
988 weeks).
989 dns_options opts (default: v4, v6, norotate, nodns0x20, edns=4096)
991 Provides a (whitespace or comma -separated) list of options
992 applying to DNS resolving. Available options are: v4, v6, rotate,
993 dns0x20 and edns (or edns0). Option name may be negated by
994 prepending a no (e.g. norotate, NoEDNS) to counteract a previously
995 enabled option. Option names are not case-sensitive. The
996 dns_options directive may appear in configuration files multiple
997 times, the last setting prevails.
998 Option v4 declares resolver capable of returning IPv4 (A) records.
1000 Option v6 declares resolver capable of returning IPv6 (AAAA)
1001 records. One would set nov6 if the resolver is filtering AAAA
1002 responses. NOTE: these options only refer to resolving capabilies,
1003 there is no other meaning like whether the IP address of resolver
1004 itself is IPv4 or IPv6.
1005 Option edns (or edns0) may take a value which specifies a
1007 requestor's acceptable UDP payload size according to EDNS0
1008 specifications (RFC 6891, ex RFC 2671) e.g. edns=4096. When EDNS0
1009 is off (noedns or edns=512) a traditional implied UDP payload size
1010 is 512 bytes, which is also a minimum allowed value for this
1011 option. When the option is specified but a value is not provided, a
1012 conservative default of 1220 bytes is implied. It is recommended to
1013 keep edns enabled when using a local recursive DNS server which
1014 supports EDNS0 (like most modern DNS servers do), a suitable
1015 setting in this case is edns=4096, which is also a default.
1016 Allowing UDP payload size larger than 512 bytes can avoid
1017 truncation of resource records in large DNS responses (like in TXT
1018 records of some SPF and DKIM responses, or when an unreasonable
1019 number of A records is published by some domain). The option should
1020 be disabled when a recursive DNS server is only reachable through
1021 non- RFC 6891 compliant middleboxes (such as some old-fashioned
1022 firewall) which bans DNS UDP payload sizes larger than 512 bytes. A
1023 suitable value when a non-local recursive DNS server is used and a
1024 middlebox does allow EDNS0 but blocks fragmented IP packets is
1025 perhaps 1220 bytes, allowing a DNS UDP packet to fit within a
1026 single IP packet in most cases (a slightly less conservative range
1027 would be 1280-1410 bytes).
1028 Option rotate causes SpamAssassin to choose a DNS server at random
1030 from all servers listed in "/etc/resolv.conf" every
1031 dns_test_interval seconds, effectively spreading the load over all
1032 currently available DNS servers when there are many spamd workers.
1033 Option dns0x20 enables randomization of letters in a DNS query
1035 label according to draft-vixie-dnsext-dns0x20, decreasing a chance
1036 of collisions of responses (by chance or by a malicious intent) by
1037 increasing spread as provided by a 16-bit query ID and up to 16
1038 bits of a port number, with additional bits as encoded by flipping
1039 case (upper/lower) of letters in a query. The number of additional
1040 random bits corresponds to the number of letters in a query label.
1041 Should work reliably with all mainstream DNS servers - do not turn
1042 on if you see frequent info messages "dns: no callback for id:" in
1043 the log, or if RBL or URIDNS lookups do not work for no apparent
1044 reason.
1045 dns_query_restriction (allow|deny) domain1 domain2 ...
1047 Option allows disabling of rules which would result in a DNS query
1048 to one of the listed domains. The first argument must be a literal
1049 "allow" or "deny", remaining arguments are domains names.
1050 Most DNS queries (with some exceptions) are subject to
1052 dns_query_restriction. A domain to be queried is successively
1053 stripped-off of its leading labels (thus yielding a series of its
1054 parent domains), and on each iteration a check is made against an
1055 associative array generated by dns_query_restriction options.
1056 Search stops at the first match (i.e. the tightest match), and the
1057 matching entry with its "allow" or "deny" value then controls
1058 whether a DNS query is allowed to be launched.
1059 If no match is found an implicit default is to allow a query. The
1061 purpose of an explicit "allow" entry is to be able to override a
1062 previously configured "deny" on the same domain or to override an
1063 entry (possibly yet to be configured in subsequent config
1064 directives) on one of its parent domains. Thus an 'allow
1065 zen.spamhaus.org' with a 'deny spamhaus.org' would permit DNS
1066 queries on a specific DNS BL zone but deny queries to other zones
1067 under the same parent domain.
1068 Domains are matched case-insensitively, no wildcards are
1070 recognized, there should be no leading or trailing dot.
1071 Specifying a block on querying a domain name has a similar effect
1073 as setting a score of corresponding DNSBL and URIBL rules to zero,
1074 and can be a handy alternative to hunting for such rules when a
1075 site policy does not allow certain DNS block lists to be queried.
1076 Special wildcard "dns_query_restriction deny *" is supported to
1078 block all queries except allowed ones.
1079 Example:
1081 dns_query_restriction deny dnswl.org surbl.org
1082 dns_query_restriction allow zen.spamhaus.org
1083 dns_query_restriction deny spamhaus.org mailspike.net
1084 spamcop.net
1085 clear_dns_query_restriction
1087 The option removes any entries entered by previous
1088 'dns_query_restriction' options, leaving the list empty, i.e.
1089 allowing DNS queries for any domain (including any DNS BL zone).
1090 dns_block_rule RULE domain
1092 If rule named RULE is hit, DNS queries to specified domain are
1093 temporarily blocked. Intended to be used with rules that check RBL
1094 return codes for specific blocked status. For example:
1095 urirhssub URIBL_BLOCKED multi.uribl.com. A 1
1097 dns_block_rule URIBL_BLOCKED multi.uribl.com
1098 Block status is maintained across all processes by empty statefile
1100 named "dnsblock_multi.uribl.com" in global state dir:
1101 home_dir_for_helpers/.spamassassin, $HOME/.spamassassin,
1102 /var/lib/spamassassin (localstate), depending which is found and
1103 writable.
1104 dns_block_time (default: 300)
1106 dns_block_rule query blockage will last this many seconds.
1107 LEARNING OPTIONS
1109 use_learner ( 0 | 1 ) (default: 1)
1110 Whether to use any machine-learning classifiers with SpamAssassin,
1111 such as the default 'BAYES_*' rules. Setting this to 0 will
1112 disable use of any and all human-trained classifiers.
1113 use_bayes ( 0 | 1 ) (default: 1)
1115 Whether to use the naive-Bayesian-style classifier built into
1116 SpamAssassin. This is a master on/off switch for all Bayes-related
1117 operations.
1118 use_bayes_rules ( 0 | 1 ) (default: 1)
1120 Whether to use rules using the naive-Bayesian-style classifier
1121 built into SpamAssassin. This allows you to disable the rules
1122 while leaving auto and manual learning enabled.
1123 bayes_auto_learn ( 0 | 1 ) (default: 1)
1125 Whether SpamAssassin should automatically feed high-scoring mails
1126 (or low-scoring mails, for non-spam) into its learning systems.
1127 The only learning system supported currently is a naive-Bayesian-
1128 style classifier.
1129 See the documentation for the
1131 "Mail::SpamAssassin::Plugin::AutoLearnThreshold" plugin module for
1132 details on how Bayes auto-learning is implemented by default.
1133 bayes_token_sources (default: header visible invisible uri)
1135 Controls which sources in a mail message can contribute tokens
1136 (e.g. words, phrases, etc.) to a Bayes classifier. The argument is
1137 a space-separated list of keywords: header, visible, invisible,
1138 uri, mimepart), each of which may be prefixed by a no to indicate
1139 its exclusion. Additionally two reserved keywords are allowed: all
1140 and none (or: noall). The list of keywords is processed
1141 sequentially: a keyword all adds all available keywords to a set
1142 being built, a none or noall clears the set, other non-negated
1143 keywords are added to the set, and negated keywords are removed
1144 from the set. Keywords are case-insensitive.
1145 The default set is: header visible invisible uri, which is
1147 equivalent for example to: All NoMIMEpart. The reason why mimepart
1148 is not currently in a default set is that it is a newer source
1149 (introduced with SpamAssassin version 3.4.1) and not much
1150 experience has yet been gathered regarding its usefulness.
1151 See also option "bayes_ignore_header" for a fine-grained control on
1153 individual header fields under the umbrella of a more general
1154 keyword header here.
1155 Keywords imply the following data sources:
1157 header - tokens collected from a message header section
1159 visible - words from visible text (plain or HTML) in a message body
1160 invisible - hidden/invisible text in HTML parts of a message body
1161 uri - URIs collected from a message body
1162 mimepart - digests (hashes) of all MIME parts (textual or non-
1163 textual) of a message, computed after Base64 and quoted-printable
1164 decoding, suffixed by their Content-Type
1165 all - adds all the above keywords to the set being assembled
1166 none or noall - removes all keywords from the set
1167 The "bayes_token_sources" directive may appear multiple times, its
1169 keywords are interpreted sequentially, adding or removing items
1170 from the final set as they appear in their order in
1171 "bayes_token_sources" directive(s).
1172 bayes_ignore_header header_name
1174 If you receive mail filtered by upstream mail systems, like a spam-
1175 filtering ISP or mailing list, and that service adds new headers
1176 (as most of them do), these headers may provide inappropriate cues
1177 to the Bayesian classifier, allowing it to take a "short cut". To
1178 avoid this, list the headers using this setting. Header matching is
1179 case-insensitive. Example:
1180 bayes_ignore_header X-Upstream-Spamfilter
1182 bayes_ignore_header X-Upstream-SomethingElse
1183 bayes_ignore_from user@example.com
1185 Bayesian classification and autolearning will not be performed on
1186 mail from the listed addresses. Program "sa-learn" will also
1187 ignore the listed addresses if it is invoked using the
1188 "--use-ignores" option. One or more addresses can be listed, see
1189 "welcomelist_from".
1190 Spam messages from certain senders may contain many words that
1192 frequently occur in ham. For example, one might read messages from
1193 a preferred bookstore but also get unwanted spam messages from
1194 other bookstores. If the unwanted messages are learned as spam
1195 then any messages discussing books, including the preferred
1196 bookstore and antiquarian messages would be in danger of being
1197 marked as spam. The addresses of the annoying bookstores would be
1198 listed. (Assuming they were halfway legitimate and didn't send you
1199 mail through myriad affiliates.)
1200 Those who have pieces of spam in legitimate messages or otherwise
1202 receive ham messages containing potentially spammy words might fear
1203 that some spam messages might be in danger of being marked as ham.
1204 The addresses of the spam mailing lists, correspondents, etc.
1205 would be listed.
1206 bayes_ignore_to user@example.com
1208 Bayesian classification and autolearning will not be performed on
1209 mail to the listed addresses. See "bayes_ignore_from" for details.
1210 bayes_min_ham_num (Default: 200)
1212 bayes_min_spam_num (Default: 200)
1213 To be accurate, the Bayes system does not activate until a certain
1214 number of ham (non-spam) and spam have been learned. The default
1215 is 200 of each ham and spam, but you can tune these up or down with
1216 these two settings.
1217 bayes_learn_during_report (Default: 1)
1219 The Bayes system will, by default, learn any reported messages
1220 ("spamassassin -r") as spam. If you do not want this to happen,
1221 set this option to 0.
1222 bayes_sql_override_username
1224 Used by BayesStore::SQL storage implementation.
1225 If this options is set the BayesStore::SQL module will override the
1227 set username with the value given. This could be useful for
1228 implementing global or group bayes databases.
1229 bayes_use_hapaxes (default: 1)
1231 Should the Bayesian classifier use hapaxes (words/tokens that occur
1232 only once) when classifying? This produces significantly better
1233 hit-rates.
1234 bayes_journal_max_size (default: 102400)
1236 SpamAssassin will opportunistically sync the journal and the
1237 database. It will do so once a day, but will sync more often if
1238 the journal file size goes above this setting, in bytes. If set to
1239 0, opportunistic syncing will not occur.
1240 bayes_expiry_max_db_size (default: 150000)
1242 What should be the maximum size of the Bayes tokens database? When
1243 expiry occurs, the Bayes system will keep either 75% of the maximum
1244 value, or 100,000 tokens, whichever has a larger value. 150,000
1245 tokens is roughly equivalent to a 8Mb database file.
1246 bayes_auto_expire (default: 1)
1248 If enabled, the Bayes system will try to automatically expire old
1249 tokens from the database. Auto-expiry occurs when the number of
1250 tokens in the database surpasses the bayes_expiry_max_db_size
1251 value. If a bayes datastore backend does not implement individual
1252 key/value expirations, the setting is silently ignored.
1253 bayes_token_ttl (default: 3w, i.e. 3 weeks)
1255 Time-to-live / expiration time in seconds for tokens kept in a
1256 Bayes database. A numeric value is optionally suffixed by a time
1257 unit (s, m, h, d, w, indicating seconds (default), minutes, hours,
1258 days, weeks).
1259 If bayes_auto_expire is true and a Bayes datastore backend supports
1261 it (currently only Redis), this setting controls deletion of
1262 expired tokens from a bayes database. The value is observed on a
1263 best-effort basis, exact timing promises are not necessarily kept.
1264 If a bayes datastore backend does not implement individual
1265 key/value expirations, the setting is silently ignored.
1266 bayes_seen_ttl (default: 8d, i.e. 8 days)
1268 Time-to-live / expiration time in seconds for 'seen' entries (i.e.
1269 mail message digests with their status) kept in a Bayes database.
1270 A numeric value is optionally suffixed by a time unit (s, m, h, d,
1271 w, indicating seconds (default), minutes, hours, days, weeks).
1272 If bayes_auto_expire is true and a Bayes datastore backend supports
1274 it (currently only Redis), this setting controls deletion of
1275 expired 'seen' entries from a bayes database. The value is observed
1276 on a best-effort basis, exact timing promises are not necessarily
1277 kept. If a bayes datastore backend does not implement individual
1278 key/value expirations, the setting is silently ignored.
1279 bayes_learn_to_journal (default: 0)
1281 If this option is set, whenever SpamAssassin does Bayes learning,
1282 it will put the information into the journal instead of directly
1283 into the database. This lowers contention for locking the database
1284 to execute an update, but will also cause more access to the
1285 journal and cause a delay before the updates are actually committed
1286 to the Bayes database.
1287 MISCELLANEOUS OPTIONS
1289 time_limit n (default: 300)
1290 Specifies a limit on elapsed time in seconds that SpamAssassin is
1291 allowed to spend before providing a result. The value may be
1292 fractional and must not be negative, zero is interpreted as
1293 unlimited. The default is 300 seconds for consistency with the
1294 spamd default setting of --timeout-child .
1295 This is a best-effort advisory setting, processing will not be
1297 abruptly aborted at an arbitrary point in processing when the time
1298 limit is exceeded, but only on reaching one of locations in the
1299 program flow equipped with a time test. Currently equipped with the
1300 test are the main checking loop, asynchronous DNS lookups, plugins
1301 which are calling external programs. Rule evaluation is guarded by
1302 starting a timer (alarm) on each set of compiled rules.
1303 When a message is passed to Mail::SpamAssassin::parse, a deadline
1305 time is established as a sum of current time and the "time_limit"
1306 setting.
1307 This deadline may also be specified by a caller through an option
1309 'master_deadline' in $suppl_attrib on a call to parse(), possibly
1310 providing a more accurate deadline taking into account past and
1311 expected future processing of a message in a mail filtering setup.
1312 If both the config option as well as a 'master_deadline' option in
1313 a call are provided, the shorter time limit of the two is used
1314 (since version 3.3.2). Note that spamd (and possibly third-party
1315 callers of SpamAssassin) will supply the 'master_deadline' option
1316 in a call based on its --timeout-child option (or equivalent),
1317 unlike the command line "spamassassin", which has no such command
1318 line option.
1319 When a time limit is exceeded, most of the remaining tests will be
1321 skipped, as well as auto-learning. Whatever tests fired so far will
1322 determine the final score. The behaviour is similar to short-
1323 circuiting with attribute 'on', as implemented by a Shortcircuit
1324 plugin. A synthetic hit on a rule named TIME_LIMIT_EXCEEDED with a
1325 near-zero default score is generated, so that the report will
1326 reflect the event. A score for TIME_LIMIT_EXCEEDED may be provided
1327 explicitly in a configuration file, for example to achieve
1328 welcomelisting or blocklisting effect for messages with long
1329 processing times.
1330 The "time_limit" option is a useful protection against excessive
1332 processing time on certain degenerate or unusually long or complex
1333 mail messages, as well as against some DoS attacks. It is also
1334 needed in time-critical pre-queue filtering setups (e.g. milter,
1335 proxy, integration with MTA), where message processing must finish
1336 before a SMTP client times out. RFC 5321 prescribes in section
1337 4.5.3.2.6 the 'DATA Termination' time limit of 10 minutes, although
1338 it is not unusual to see some SMTP clients abort sooner on waiting
1339 for a response. A sensible "time_limit" for a pre-queue filtering
1340 setup is maybe 50 seconds, assuming that clients are willing to
1341 wait at least a minute.
1342 lock_method type
1344 Select the file-locking method used to protect database files on-
1345 disk. By default, SpamAssassin uses an NFS-safe locking method on
1346 UNIX; however, if you are sure that the database files you'll be
1347 using for Bayes and AWL storage will never be accessed over NFS, a
1348 non-NFS-safe locking system can be selected.
1349 This will be quite a bit faster, but may risk file corruption if
1351 the files are ever accessed by multiple clients at once, and one or
1352 more of them is accessing them through an NFS filesystem.
1353 Note that different platforms require different locking systems.
1355 The supported locking systems for "type" are as follows:
1357 nfssafe - an NFS-safe locking system
1359 flock - simple UNIX flock() locking
1360 win32 - Win32 locking using "sysopen (..., O_CREAT|O_EXCL)".
1361 nfssafe and flock are only available on UNIX, and win32 is only
1363 available on Windows. By default, SpamAssassin will choose either
1364 nfssafe or win32 depending on the platform in use.
1365 fold_headers ( 0 | 1 ) (default: 1)
1367 By default, headers added by SpamAssassin will be whitespace
1368 folded. In other words, they will be broken up into multiple lines
1369 instead of one very long one and each continuation line will have a
1370 tabulator prepended to mark it as a continuation of the preceding
1371 one.
1372 The automatic wrapping can be disabled here. Note that this can
1374 generate very long lines. RFC 2822 required that header lines do
1375 not exceed 998 characters (not counting the final CRLF).
1376 report_safe_copy_headers header_name ...
1378 If using "report_safe", a few of the headers from the original
1379 message are copied into the wrapper header (From, To, Cc, Subject,
1380 Date, etc.) If you want to have other headers copied as well, you
1381 can add them using this option. You can specify multiple headers
1382 on the same line, separated by spaces, or you can just use multiple
1383 lines.
1384 envelope_sender_header Name-Of-Header
1386 SpamAssassin will attempt to discover the address used in the 'MAIL
1387 FROM:' phase of the SMTP transaction that delivered this message,
1388 if this data has been made available by the SMTP server. This is
1389 used in the "EnvelopeFrom" pseudo-header, and for various rules
1390 such as SPF checking.
1391 By default, various MTAs will use different headers, such as the
1393 following:
1394 X-Envelope-From
1396 Envelope-Sender
1397 X-Sender
1398 Return-Path
1399 SpamAssassin will attempt to use these, if some heuristics (such as
1401 the header placement in the message, or the absence of fetchmail
1402 signatures) appear to indicate that they are safe to use. However,
1403 it may choose the wrong headers in some mailserver configurations.
1404 (More discussion of this can be found in bug 2142 and bug 4747 in
1405 the SpamAssassin BugZilla.)
1406 To avoid this heuristic failure, the "envelope_sender_header"
1408 setting may be helpful. Name the header that your MTA or MDA adds
1409 to messages containing the address used at the MAIL FROM step of
1410 the SMTP transaction.
1411 If the header in question contains "<" or ">" characters at the
1413 start and end of the email address in the right-hand side, as in
1414 the SMTP transaction, these will be stripped.
1415 If the header is not found in a message, or if it's value does not
1417 contain an "@" sign, SpamAssassin will issue a warning in the logs
1418 and fall back to its default heuristics.
1419 (Note for MTA developers: we would prefer if the use of a single
1421 header be avoided in future, since that precludes 'downstream' spam
1422 scanning.
1423 "https://wiki.apache.org/spamassassin/EnvelopeSenderInReceived"
1424 details a better proposal, storing the envelope sender at each hop
1425 in the "Received" header.)
1426 example:
1428 envelope_sender_header X-SA-Exim-Mail-From
1430 describe SYMBOLIC_TEST_NAME description ...
1432 Used to describe a test. This text is shown to users in the
1433 detailed report.
1434 Note that test names which begin with '__' are reserved for meta-
1436 match sub-rules, and are not scored or listed in the 'tests hit'
1437 reports.
1438 Also note that by convention, rule descriptions should be limited
1440 in length to no more than 50 characters.
1441 report_charset CHARSET (default: UTF-8)
1443 Set the MIME Content-Type charset used for the text/plain report
1444 which is attached to spam mail messages.
1445 report ...some text for a report...
1447 Set the report template which is attached to spam mail messages.
1448 See the "10_default_prefs.cf" configuration file in
1449 "/usr/share/spamassassin" for an example.
1450 If you change this, try to keep it under 78 columns. Each "report"
1452 line appends to the existing template, so use
1453 "clear_report_template" to restart.
1454 Tags can be included as explained above.
1456 clear_report_template
1458 Clear the report template.
1459 report_contact ...text of contact address...
1461 Set what _CONTACTADDRESS_ is replaced with in the above report
1462 text. By default, this is 'the administrator of that system',
1463 since the hostname of the system the scanner is running on is also
1464 included.
1465 report_hostname ...hostname to use...
1467 Set what _HOSTNAME_ is replaced with in the above report text. By
1468 default, this is determined dynamically as whatever the host
1469 running SpamAssassin calls itself.
1470 unsafe_report ...some text for a report...
1472 Set the report template which is attached to spam mail messages
1473 which contain a non-text/plain part. See the "10_default_prefs.cf"
1474 configuration file in "/usr/share/spamassassin" for an example.
1475 Each "unsafe-report" line appends to the existing template, so use
1477 "clear_unsafe_report_template" to restart.
1478 Tags can be used in this template (see above for details).
1480 clear_unsafe_report_template
1482 Clear the unsafe_report template.
1483 mbox_format_from_regex
1485 Set a specific regular expression to be used for mbox file From
1486 separators.
1487 For example, this setting will allow sa-learn to process emails
1489 stored in a kmail 2 mbox:
1490 mbox_format_from_regex /^From \S+ ?[[:upper:]][[:lower:]]{2}(?:,
1492 \d\d [[:upper:]][[:lower:]]{2} \d{4} [0-2]\d:\d\d:\d\d [+-]\d{4}|
1493 [[:upper:]][[:lower:]]{2} [ 1-3]\d [ 0-2]\d:\d\d:\d\d \d{4})/
1494 parse_dkim_uris ( 0 | 1 ) (default: 1)
1496 If this option is set to 1 and the message contains DKIM headers,
1497 the headers will be parsed for URIs to process alongside URIs found
1498 in the body with some rules and modules (ex. URIDNSBL)
1499
1501 These settings differ from the ones above, in that they are considered
1502 'privileged'. Only users running "spamassassin" from their
1503 procmailrc's or forward files, or sysadmins editing a file in
1504 "/etc/mail/spamassassin", can use them. "spamd" users cannot use them
1505 in their "user_prefs" files, for security and efficiency reasons,
1506 unless "allow_user_rules" is enabled (and then, they may only add rules
1507 from below).
1508 allow_user_rules ( 0 | 1 ) (default: 0)
1510 This setting allows users to create rules (and only rules) in their
1511 "user_prefs" files for use with "spamd". It defaults to off,
1512 because this could be a severe security hole. It may be possible
1513 for users to gain root level access if "spamd" is run as root. It
1514 is NOT a good idea, unless you have some other way of ensuring that
1515 users' tests are safe. Don't use this unless you are certain you
1516 know what you are doing. Furthermore, this option causes
1517 spamassassin to recompile all the tests each time it processes a
1518 message for a user with a rule in his/her "user_prefs" file, which
1519 could have a significant effect on server load. It is not
1520 recommended.
1521 Note that it is not currently possible to use "allow_user_rules" to
1523 modify an existing system rule from a "user_prefs" file with
1524 "spamd".
1525 redirector_pattern /pattern/modifiers
1527 A regex pattern that matches both the redirector site portion, and
1528 the target site portion of a URI.
1529 Note: The target URI portion must be surrounded in parentheses and
1531 no other part of the pattern may create a backreference.
1532 Example:
1534 http://chkpt.zdnet.com/chkpt/whatever/spammer.domain/yo/dude
1535 redirector_pattern /^https?:\/\/(?:opt\.)?chkpt\.zdnet\.com\/chkpt\/\w+\/(.*)$/i
1537 header SYMBOLIC_TEST_NAME header op /pattern/modifiers [if-unset:
1539 STRING]
1540 Define a test. "SYMBOLIC_TEST_NAME" is a symbolic test name, such
1541 as 'FROM_ENDS_IN_NUMS'. "header" is the name of a mail header
1542 field, such as 'Subject', 'To', 'From', etc. Header field names
1543 are matched case-insensitively (conforming to RFC 5322 section
1544 1.2.2), except for all-capitals metaheader fields such as ALL,
1545 MESSAGEID, ALL-TRUSTED.
1546 Appending a modifier ":raw" to a header field name will inhibit
1548 decoding of quoted-printable or base-64 encoded strings, and will
1549 preserve all whitespace inside the header string. The ":raw" may
1550 also be applied to pseudo-headers e.g. "ALL:raw" will return a
1551 pristine (unmodified) header section.
1552 Appending a modifier ":addr" to a header field name will cause
1554 everything except the first email address to be removed from the
1555 header field. It is mainly applicable to header fields 'From',
1556 'Sender', 'To', 'Cc' along with their 'Resent-*' counterparts, and
1557 the 'Return-Path'.
1558 Appending a modifier ":name" to a header field name will cause
1560 everything except the first display name to be removed from the
1561 header field. It is mainly applicable to header fields containing a
1562 single mail address: 'From', 'Sender', along with their
1563 'Resent-From' and 'Resent-Sender' counterparts.
1564 It is syntactically permitted to append more than one modifier to a
1566 header field name, although currently most combinations achieve no
1567 additional effect, for example "From:addr:raw" or "From:raw:addr"
1568 is currently the same as "From:addr" .
1569 For example, appending ":addr" to a header name will result in
1571 example@foo in all of the following cases:
1572 example@foo
1574 example@foo (Foo Blah)
1575 example@foo, example@bar
1576 display: example@foo (Foo Blah), example@bar ;
1577 Foo Blah <example@foo>
1578 "Foo Blah" <example@foo>
1579 "'Foo Blah'" <example@foo>
1580 For example, appending ":name" to a header name will result in "Foo
1582 Blah" (without quotes) in all of the following cases:
1583 example@foo (Foo Blah)
1585 example@foo (Foo Blah), example@bar
1586 display: example@foo (Foo Blah), example@bar ;
1587 Foo Blah <example@foo>
1588 "Foo Blah" <example@foo>
1589 "'Foo Blah'" <example@foo>
1590 There are several special pseudo-headers that can be specified:
1592 "ALL" can be used to mean the text of all the message's headers.
1594 Note that all whitespace inside the headers, at line folds, is
1595 currently compressed into a single space (' ') character. To obtain
1596 a pristine (unmodified) header section, use "ALL:raw" - the :raw
1597 modifier is documented above. Also similar that return headers
1598 added by specific relays: ALL-TRUSTED, ALL-INTERNAL, ALL-UNTRUSTED,
1599 ALL-EXTERNAL.
1600 "ToCc" can be used to mean the contents of both the 'To' and 'Cc'
1601 headers.
1602 "EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the
1603 SMTP transaction that delivered this message, if this data has been
1604 made available by the SMTP server. See "envelope_sender_header"
1605 for more information on how to set this.
1606 "MESSAGEID" is a symbol meaning all Message-Id's found in the
1607 message; some mailing list software moves the real 'Message-Id' to
1608 'Resent-Message-Id' or to 'X-Message-Id', then uses its own one in
1609 the 'Message-Id' header. The value returned for this symbol is the
1610 text from all 3 headers, separated by newlines.
1611 "X-Spam-Relays-Untrusted", "X-Spam-Relays-Trusted",
1612 "X-Spam-Relays-Internal" and "X-Spam-Relays-External" represent a
1613 portable, pre-parsed representation of the message's network path,
1614 as recorded in the Received headers, divided into 'trusted' vs
1615 'untrusted' and 'internal' vs 'external' sets. See
1616 "https://wiki.apache.org/spamassassin/TrustedRelays" for more
1617 details.
1618 "op" is either "=~" (contains regular expression) or "!~" (does not
1620 contain regular expression), and "pattern" is a valid Perl regular
1621 expression, with "modifiers" as regexp modifiers in the usual
1622 style. Note that multi-line rules are not supported, even if you
1623 use "x" as a modifier. Also note that the "#" character must be
1624 escaped ("\#") or else it will be considered to be the start of a
1625 comment and not part of the regexp.
1626 If the header specified matches multiple headers, their text will
1628 be concatenated with embedded \n's. Therefore you may wish to use
1629 "/m" if you use "^" or "$" in your regular expression.
1630 If the "[if-unset: STRING]" tag is present, then "STRING" will be
1632 used if the header is not found in the mail message.
1633 Test names must not start with a number, and must contain only
1635 alphanumerics and underscores. It is suggested that lower-case
1636 characters not be used, and names have a length of no more than 22
1637 characters, as an informal convention. Dashes are not allowed.
1638 Note that test names which begin with '__' are reserved for meta-
1640 match sub-rules, and are not scored or listed in the 'tests hit'
1641 reports. Test names which begin with 'T_' are reserved for tests
1642 which are undergoing QA, and these are given a very low score.
1643 If you add or modify a test, please be sure to run a sanity check
1645 afterwards by running "spamassassin --lint". This will avoid
1646 confusing error messages, or other tests being skipped as a side-
1647 effect.
1648 header SYMBOLIC_TEST_NAME exists:header_field_name
1650 Define a header field existence test. "header_field_name" is the
1651 name of a header field to test for existence. Not to be confused
1652 with a test for a nonempty header field body, which can be
1653 implemented by a "header SYMBOLIC_TEST_NAME header =~ /\S/" rule as
1654 described above.
1655 header SYMBOLIC_TEST_NAME eval:name_of_eval_method([arguments])
1657 Define a header eval test. "name_of_eval_method" is the name of a
1658 method registered by a "Mail::SpamAssassin::Plugin" object.
1659 "arguments" are optional arguments to the function call.
1660 header SYMBOLIC_TEST_NAME eval:check_rbl('set', 'zone' [, 'sub-test'])
1662 Check a DNSBL (a DNS blocklist or welcomelist). This will retrieve
1663 Received: headers from the message, extract the IP addresses,
1664 select which ones are 'untrusted' based on the "trusted_networks"
1665 logic, and query that DNSBL zone. There's a few things to note:
1666 duplicated or private IPs
1668 Duplicated IPs are only queried once and reserved IPs are not
1669 queried. Private IPs are those listed in
1670 "https://www.iana.org/assignments/ipv4-address-space", or
1671 "https://tools.ietf.org/html/rfc5735" as private.
1672 the 'set' argument
1674 This is used as a 'zone ID'. If you want to look up a
1675 multiple-meaning zone like SORBS, you can then query the
1676 results from that zone using it; but all check_rbl_sub() calls
1677 must use that zone ID.
1678 Also, if more than one IP address gets a DNSBL hit for a
1680 particular rule, it does not affect the score because rules
1681 only trigger once per message.
1682 the 'zone' argument
1684 This is the root zone of the DNSBL.
1685 The domain name is considered to be a fully qualified domain
1687 name (i.e. not subject to DNS resolver's search or default
1688 domain options). No trailing period is needed, and will be
1689 removed if specified.
1690 the 'sub-test' argument
1692 This optional argument behaves the same as the sub-test
1693 argument in check_rbl_sub() below.
1694 selecting all IPs except for the originating one
1696 This is accomplished by placing '-notfirsthop' at the end of
1697 the set name. This is useful for querying against DNS lists
1698 which list dialup IP addresses; the first hop may be a dialup,
1699 but as long as there is at least one more hop, via their
1700 outgoing SMTP server, that's legitimate, and so should not gain
1701 points. If there is only one hop, that will be queried anyway,
1702 as it should be relaying via its outgoing SMTP server instead
1703 of sending directly to your MX (mail exchange).
1704 selecting IPs by whether they are trusted
1706 When checking a 'nice' DNSBL (a DNS welcomelist), you cannot
1707 trust the IP addresses in Received headers that were not added
1708 by trusted relays. To test the first IP address that can be
1709 trusted, place '-firsttrusted' at the end of the set name.
1710 That should test the IP address of the relay that connected to
1711 the most remote trusted relay.
1712 Note that this requires that SpamAssassin know which relays are
1714 trusted. For simple cases, SpamAssassin can make a good
1715 estimate. For complex cases, you may get better results by
1716 setting "trusted_networks" manually.
1717 In addition, you can test all untrusted IP addresses by placing
1719 '-untrusted' at the end of the set name. Important note --
1720 this does NOT include the IP address from the most recent
1721 'untrusted line', as used in '-firsttrusted' above. That's
1722 because we're talking about the trustworthiness of the IP
1723 address data, not the source header line, here; and in the case
1724 of the most recent header (the 'firsttrusted'), that data can
1725 be trusted. See the Wiki page at
1726 "https://wiki.apache.org/spamassassin/TrustedRelays" for more
1727 information on this.
1728 Selecting just the last external IP
1730 By using '-lastexternal' at the end of the set name, you can
1731 select only the external host that connected to your internal
1732 network, or at least the last external host with a public IP.
1733 header SYMBOLIC_TEST_NAME eval:check_rbl_txt('set', 'zone')
1735 Same as check_rbl(), except querying using IN TXT instead of IN A
1736 records. If the zone supports it, it will result in a line of text
1737 describing why the IP is listed, typically a hyperlink to a
1738 database entry.
1739 header SYMBOLIC_TEST_NAME eval:check_rbl_sub('set', 'sub-test')
1741 Create a sub-test for 'set'. If you want to look up a multi-
1742 meaning zone like relays.osirusoft.com, you can then query the
1743 results from that zone using the zone ID from the original query.
1744 The sub-test may either be an IPv4 dotted address for RBLs that
1745 return multiple A records, or a non-negative decimal number to
1746 specify a bitmask for RBLs that return a single A record containing
1747 a bitmask of results, or a regular expression.
1748 Note: the set name must be exactly the same for as the main query
1750 rule, including selections like '-notfirsthop' appearing at the end
1751 of the set name.
1752 body SYMBOLIC_TEST_NAME /pattern/modifiers
1754 Define a body pattern test. "pattern" is a Perl regular
1755 expression. Note: as per the header tests, "#" must be escaped
1756 ("\#") or else it is considered the beginning of a comment.
1757 The 'body' in this case is the textual parts of the message body;
1759 any non-text MIME parts are stripped, and the message decoded from
1760 Quoted-Printable or Base-64-encoded format if necessary. Parts
1761 declared as text/html will be rendered from HTML to text.
1762 Body is processed as a raw byte string, which means Unicode-
1764 specific regex features like \p{} can NOT be used for matching.
1765 The normalize_charset setting will also affect how raw bytes are
1766 presented. Rules in .cf files should be written portably - to
1767 match "a with umlaut" character, look for both LATIN1 and UTF8 raw
1768 byte variants: /(?:\xE4|\xC3\xA4)/
1769 All body paragraphs (double-newline-separated blocks text) are
1771 turned into a linebreaks-removed, whitespace-normalized, single
1772 line. Any lines longer than 2kB are split into shorter separate
1773 lines (from a boundary when possible), this may unexpectedly
1774 prevent pattern from matching. Patterns are matched independently
1775 against each of these lines.
1776 Note that by default the message Subject header is considered part
1778 of the body and becomes the first line when running the rules. If
1779 you don't want to match Subject along with body text, use "tflags
1780 RULENAME nosubject".
1781 See "https://wiki.apache.org/SpamAssassin/WritingRules" for more
1783 information.
1784 body SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1786 Define a body eval test. See above.
1787 uri SYMBOLIC_TEST_NAME /pattern/modifiers
1789 Define a uri pattern test. "pattern" is a Perl regular expression.
1790 Note: as per the header tests, "#" must be escaped ("\#") or else
1791 it is considered the beginning of a comment.
1792 The 'uri' in this case is a list of all the URIs in the body of the
1794 email, and the test will be run on each and every one of those
1795 URIs, adjusting the score if a match is found. Use this test
1796 instead of one of the body tests when you need to match a URI, as
1797 it is more accurately bound to the start/end points of the URI, and
1798 will also be faster.
1799 rawbody SYMBOLIC_TEST_NAME /pattern/modifiers
1801 Define a raw-body pattern test. "pattern" is a Perl regular
1802 expression. Note: as per the header tests, "#" must be escaped
1803 ("\#") or else it is considered the beginning of a comment.
1804 The 'raw body' of a message is the raw data inside all textual
1806 parts. The text will be decoded from base64 or quoted-printable
1807 encoding, but HTML tags and line breaks will still be present.
1808 Multiline expressions will need to be used to match strings that
1809 are broken by line breaks.
1810 Note that the text is split into 2-4kB chunks (from a word boundary
1812 when possible), this may unexpectedly prevent pattern from
1813 matching. Patterns are matched independently against each of these
1814 chunks.
1815 rawbody SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1817 Define a raw-body eval test. See above.
1818 full SYMBOLIC_TEST_NAME /pattern/modifiers
1820 Define a full message pattern test. "pattern" is a Perl regular
1821 expression. Note: as per the header tests, "#" must be escaped
1822 ("\#") or else it is considered the beginning of a comment.
1823 The full message is the pristine message headers plus the pristine
1825 message body, including all MIME data such as images, other
1826 attachments, MIME boundaries, etc.
1827 Note that CRLF/LF line endings are matched as the original message
1829 has them. For any full rules that match newlines, it's recommended
1830 to use \r?$ instead of plain $, so it works on all systems.
1831 full SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1833 Define a full message eval test. See above.
1834 meta SYMBOLIC_TEST_NAME boolean expression
1836 Define a boolean expression test in terms of other tests that have
1837 been hit or not hit. For example:
1838 meta META1 TEST1 && !(TEST2 || TEST3)
1840 Note that English language operators ("and", "or") will be treated
1842 as rule names, and that there is no "XOR" operator.
1843 meta SYMBOLIC_TEST_NAME boolean arithmetic expression
1845 Can also define an arithmetic expression in terms of other tests,
1846 with an unhit test having the value "0" and a hit test having a
1847 nonzero value. The value of a hit meta test is that of its
1848 arithmetic expression. The value of a hit eval test is that
1849 returned by its method. The value of a hit header, body, rawbody,
1850 uri, or full test which has the "multiple" tflag is the number of
1851 times the test hit. The value of any other type of hit test is
1852 "1".
1853 For example:
1855 meta META2 (3 * TEST1 - 2 * TEST2) > 0
1857 Note that Perl builtins and functions, like abs(), can't be used,
1859 and will be treated as rule names.
1860 If you want to define a meta-rule, but do not want its individual
1862 sub-rules to count towards the final score unless the entire meta-
1863 rule matches, give the sub-rules names that start with '__' (two
1864 underscores). SpamAssassin will ignore these for scoring.
1865 meta SYMBOLIC_TEST_NAME ... rules_matching(RULEGLOB) ...
1867 Special function that will expand to list of matching rulenames.
1868 Can be used anywhere in expressions. Argument supports glob style
1869 rulename matching (* = anything, ? = one character). Matching is
1870 case-sensitive.
1871 For example, this will hit if at least two __FOO_* rule hits:
1873 body __FOO_1 /xxx/
1875 body __FOO_2 /yyy/
1876 body __FOO_3 /zzz/
1877 meta FOO_META rules_matching(__FOO_*) >= 2
1878 Which would be the same as:
1880 meta FOO_META (__FOO_1 + __FOO_2 + __FOO_3) >= 2
1882 reuse SYMBOLIC_TEST_NAME [ OLD_SYMBOLIC_TEST_NAME_1 ... ]
1884 Defines the name of a test that should be "reused" during the
1885 scoring process. If a message has an X-Spam-Status header that
1886 shows a hit for this rule or any of the old rule names given, a hit
1887 will be added for this rule when mass-check --reuse is used.
1888 Examples:
1889 "reuse SPF_PASS"
1891 "reuse MY_NET_RULE_V2 MY_NET_RULE_V1"
1893 The actual logic for reuse tests is done by
1895 Mail::SpamAssassin::Plugin::Reuse.
1896 tflags SYMBOLIC_TEST_NAME flags
1898 Used to set flags on a test. Parameter is a space-separated list of
1899 flag names or flag name = value pairs. These flags are used in the
1900 score-determination back end system for details of the test's
1901 behaviour. Please see "bayes_auto_learn" for more information
1902 about tflag interaction with those systems. The following flags can
1903 be set:
1904 net The test is a network test, and will not be run in the mass
1906 checking system or if -L is used, therefore its score should
1907 not be modified.
1908 nice
1910 The test is intended to compensate for common false positives,
1911 and should be assigned a negative score.
1912 userconf
1914 The test requires user configuration before it can be used
1915 (like language-specific tests).
1916 learn
1918 The test requires training before it can be used.
1919 noautolearn
1921 The test will explicitly be ignored when calculating the score
1922 for learning systems.
1923 autolearn_force
1925 The test will be subject to less stringent autolearn
1926 thresholds.
1927 Normally, SpamAssassin will require 3 points from the header
1929 and 3 points from the body to be auto-learned as spam. This
1930 option keeps the threshold at 6 points total but changes it to
1931 have no regard to the source of the points.
1932 noawl
1934 This flag is specific when using AWL plugin.
1935 Normally, AWL plugin normalizes scores via auto-welcomelist. In
1937 some scenarios it works against the system administrator when
1938 trying to add some rules to correct miss-classified email. When
1939 AWL plugin searches the email and finds the noawl flag it will
1940 exit without normalizing the score nor storing the value in db.
1941 multiple
1943 The test will be evaluated multiple times, for use with meta
1944 rules. Only affects header, body, rawbody, uri, and full
1945 tests.
1946 maxhits=N
1948 If multiple is specified, limit the number of hits found to N.
1949 If the rule is used in a meta that counts the hits (e.g.
1950 __RULENAME > 5), this is a way to avoid wasted extra work (use
1951 "tflags multiple maxhits=6").
1952 For example:
1954 uri __KAM_COUNT_URIS /^./
1956 tflags __KAM_COUNT_URIS multiple maxhits=16
1957 describe __KAM_COUNT_URIS A multiple match used to count URIs in a message
1958 meta __KAM_HAS_0_URIS (__KAM_COUNT_URIS == 0)
1960 meta __KAM_HAS_1_URIS (__KAM_COUNT_URIS >= 1)
1961 meta __KAM_HAS_2_URIS (__KAM_COUNT_URIS >= 2)
1962 meta __KAM_HAS_3_URIS (__KAM_COUNT_URIS >= 3)
1963 meta __KAM_HAS_4_URIS (__KAM_COUNT_URIS >= 4)
1964 meta __KAM_HAS_5_URIS (__KAM_COUNT_URIS >= 5)
1965 meta __KAM_HAS_10_URIS (__KAM_COUNT_URIS >= 10)
1966 meta __KAM_HAS_15_URIS (__KAM_COUNT_URIS >= 15)
1967 nosubject
1969 Used only for body rules. If specified, Subject header will
1970 not be a part of the matched body text. See body for more
1971 info.
1972 ips_only
1974 This flag is specific to rules invoking an URIDNSBL plugin, it
1975 is documented there.
1976 domains_only
1978 This flag is specific to rules invoking an URIDNSBL plugin, it
1979 is documented there.
1980 ns This flag is specific to rules invoking an URIDNSBL plugin, it
1982 is documented there.
1983 a This flag is specific to rules invoking an URIDNSBL plugin, it
1985 is documented there.
1986 notrim
1988 This flag is specific to rules invoking an URIDNSBL plugin, it
1989 is documented there.
1990 nolog
1992 This flag will hide (sensitive) rule informations from reports
1993 priority SYMBOLIC_TEST_NAME n
1995 Assign a specific priority to a test. All tests, except for DNS
1996 and Meta tests, are run in increasing priority value order
1997 (negative priority values are run before positive priority values).
1998 The default test priority is 0 (zero).
1999 The values -99999999999999 and -99999999999998 have a special
2001 meaning internally, and should not be used.
2002 CAPTURING TAGS USING REGEX NAMED CAPTURE GROUPS
2004 SpamAssassin 4.0 supports capturing template tags from regex rules.
2005 The captured tags, along with other standard template tags, can be used
2006 in other rules as a matching string. See TEMPLATE TAGS section for
2007 more info on tags.
2008 Capturing can be done in any body/rawbody/header/uri/full rule that
2010 uses a regex for matching (not eval rules). Standard Perl named
2011 capture group format "(?<NAME>pattern)" must be used, as described in
2012 <https://perldoc.perl.org/perlre#(?%3CNAME%3Epattern)>.
2013 Example, capturing a tag named "BODY_HELLO_NAME":
2015 body __HELLO_NAME /\bHello, (?<BODY_HELLO_NAME>\w+)\b/
2017 The tag can then be used in another rule for matching, using a
2019 %{TAGNAME} template. This would search the captured name in From-
2020 header:
2021 header HELLO_NAME_IN_FROM From =~ /\b%{BODY_HELLO_NAME}\b/i
2023 If any tag that a rule depends on is not found, then the rule is not
2025 run at all. To prevent a literal %{NAME} string from being parsed as a
2026 template, it can be escaped with a backslash: \%{NAME}.
2027 Captured tags can also be used in reports and in other plugins like
2029 AskDNS, with the standard "_BODY_HELLO_NAME_" notation.
2030 Note that at this time there is no automatic dependency tracking for
2032 rule running order. All rules that use named capture groups are
2033 automatically set to priority -10000, so that the tags should always be
2034 ready for any normal rules to use. When rule depends on a tag that
2035 might be set at later stage by a plugin for example, it's priority
2036 should be set manually to a higher value.
2037
2039 These settings differ from the ones above, in that they are considered
2040 'more privileged' -- even more than the ones in the PRIVILEGED SETTINGS
2041 section. No matter what "allow_user_rules" is set to, these can never
2042 be set from a user's "user_prefs" file when spamc/spamd is being used.
2043 However, all settings can be used by local programs run directly by the
2044 user.
2045 version_tag string
2047 This tag is appended to the SA version in the X-Spam-Status header.
2048 You should include it when you modify your ruleset, especially if
2049 you plan to distribute it. A good choice for string is your last
2050 name or your initials followed by a number which you increase with
2051 each change.
2052 The version_tag will be lowercased, and any non-alphanumeric or
2054 period character will be replaced by an underscore.
2055 e.g.
2057 version_tag myrules1 # version=2.41-myrules1
2059 test SYMBOLIC_TEST_NAME (ok|fail) Some string to test against
2061 Define a regression testing string. You can have more than one
2062 regression test string per symbolic test name. Simply specify a
2063 string that you wish the test to match.
2064 These tests are only run as part of the test suite - they should
2066 not affect the general running of SpamAssassin.
2067 body_part_scan_size (default: 50000)
2069 Per mime-part scan size limit in bytes for "body" type rules. The
2070 decoded/stripped mime-part is truncated approx to this size. Helps
2071 scanning large messages safely, so it's not necessary to skip them
2072 completely. Disabled with 0.
2073 rawbody_part_scan_size (default: 500000)
2075 Like body_part_scan_size, for "rawbody" type rules.
2076 rbl_timeout t [t_min] [zone] (default: 15 3)
2078 All DNS queries are made at the beginning of a check and we try to
2079 read the results at the end. This value specifies the maximum
2080 period of time (in seconds) to wait for a DNS query. If most of
2081 the DNS queries have succeeded for a particular message, then
2082 SpamAssassin will not wait for the full period to avoid wasting
2083 time on unresponsive server(s), but will shrink the timeout
2084 according to a percentage of queries already completed. As the
2085 number of queries remaining approaches 0, the timeout value will
2086 gradually approach a t_min value, which is an optional second
2087 parameter and defaults to 0.2 * t. If t is smaller than t_min, the
2088 initial timeout is set to t_min. Here is a chart of queries
2089 remaining versus the timeout in seconds, for the default 15 second
2090 / 3 second timeout setting:
2091 queries left 100% 90% 80% 70% 60% 50% 40% 30% 20% 10% 0%
2093 timeout 15 14.9 14.5 13.9 13.1 12.0 10.7 9.1 7.3 5.3 3
2094 For example, if 20 queries are made at the beginning of a message
2096 check and 16 queries have returned (leaving 20%), the remaining 4
2097 queries should finish within 7.3 seconds since their query started
2098 or they will be timed out. Note that timed out queries are only
2099 aborted when there is nothing else left for SpamAssassin to do -
2100 long evaluation of other rules may grant queries additional time.
2101 If a parameter 'zone' is specified (it must end with a letter,
2103 which distinguishes it from other numeric parametrs), then the
2104 setting only applies to DNS queries against the specified DNS
2105 domain (host, domain or RBL (sub)zone). Matching is case-
2106 insensitive, the actual domain may be a subdomain of the specified
2107 zone.
2108 util_rb_tld tld1 tld2 ...
2110 This option maintains a list of valid TLDs in the
2111 RegistryBoundaries code. Top level domains (TLD) include things
2112 like com, net, org, xn--p1ai, рф, ... International domain names
2113 may be specified in ASCII-compatible encoding (ACE), e.g. xn--p1ai,
2114 xn--qxam, or with Unicode labels encoded as UTF-8 octets, e.g. рф,
2115 ελ.
2116 util_rb_2tld 2tld-1.tld 2tld-2.tld ...
2118 This option maintains list of valid 2nd-level TLDs in the
2119 RegistryBoundaries code. 2TLDs include things like co.uk, fed.us,
2120 etc. International domain names may be specified in ASCII-
2121 compatible encoding (ACE), or with Unicode labels encoded as UTF-8
2122 octets.
2123 util_rb_3tld 3tld1.some.tld 3tld2.other.tld ...
2125 This option maintains list of valid 3rd-level TLDs in the
2126 RegistryBoundaries code. 3TLDs include things like demon.co.uk,
2127 plc.co.im, etc. International domain names may be specified in
2128 ASCII-compatible encoding (ACE), or with Unicode labels encoded as
2129 UTF-8 octets.
2130 clear_util_rb
2132 Empty internal list of valid TLDs (including 2nd and 3rd level)
2133 which RegistryBoundaries code uses. Only useful if you want to
2134 override the standard lists supplied by sa-update.
2135 bayes_path /path/filename (default: ~/.spamassassin/bayes)
2137 This is the directory and filename for Bayes databases. Several
2138 databases will be created, with this as the base directory and
2139 filename, with "_toks", "_seen", etc. appended to the base. The
2140 default setting results in files called
2141 "~/.spamassassin/bayes_seen", "~/.spamassassin/bayes_toks", etc.
2142 By default, each user has their own in their "~/.spamassassin"
2144 directory with mode 0700/0600. For system-wide SpamAssassin use,
2145 you may want to reduce disk space usage by sharing this across all
2146 users. However, Bayes appears to be more effective with individual
2147 user databases.
2148 bayes_file_mode (default: 0700)
2150 The file mode bits used for the Bayesian filtering database files.
2151 Make sure you specify this using the 'x' mode bits set, as it may
2153 also be used to create directories. However, if a file is created,
2154 the resulting file will not have any execute bits set (the umask is
2155 set to 111). The argument is a string of octal digits, it is
2156 converted to a numeric value internally.
2157 bayes_store_module Name::Of::BayesStore::Module
2159 If this option is set, the module given will be used as an
2160 alternate to the default bayes storage mechanism. It must conform
2161 to the published storage specification (see
2162 Mail::SpamAssassin::BayesStore). For example, set this to
2163 Mail::SpamAssassin::BayesStore::SQL to use the generic SQL storage
2164 module.
2165 bayes_sql_dsn DBI::databasetype:databasename:hostname:port
2167 Used for BayesStore::SQL storage implementation.
2168 This option give the connect string used to connect to the SQL
2170 based Bayes storage.
2171 bayes_sql_username
2173 Used by BayesStore::SQL storage implementation.
2174 This option gives the username used by the above DSN.
2176 bayes_sql_password
2178 Used by BayesStore::SQL storage implementation.
2179 This option gives the password used by the above DSN.
2181 bayes_sql_username_authorized ( 0 | 1 ) (default: 0)
2183 Whether to call the services_authorized_for_username plugin hook in
2184 BayesSQL. If the hook does not determine that the user is allowed
2185 to use bayes or is invalid then then database will not be
2186 initialized.
2187 NOTE: By default the user is considered invalid until a plugin
2189 returns a true value. If you enable this, but do not have a proper
2190 plugin loaded, all users will turn up as invalid.
2191 The username passed into the plugin can be affected by the
2193 bayes_sql_override_username config option.
2194 user_scores_dsn DBI:databasetype:databasename:hostname:port
2196 If you load user scores from an SQL database, this will set the DSN
2197 used to connect. Example: "DBI:mysql:spamassassin:localhost"
2198 If you load user scores from an LDAP directory, this will set the
2200 DSN used to connect. You have to write the DSN as an LDAP URL, the
2201 components being the host and port to connect to, the base DN for
2202 the search, the scope of the search (base, one or sub), the single
2203 attribute being the multivalued attribute used to hold the
2204 configuration data (space separated pairs of key and value, just as
2205 in a file) and finally the filter being the expression used to
2206 filter out the wanted username. Note that the filter expression is
2207 being used in a sprintf statement with the username as the only
2208 parameter, thus is can hold a single __USERNAME__ expression. This
2209 will be replaced with the username.
2210 Example:
2212 "ldap://localhost:389/dc=koehntopp,dc=de?saconfig?uid=__USERNAME__"
2213 user_scores_sql_username username
2215 The authorized username to connect to the above DSN.
2216 user_scores_sql_password password
2218 The password for the database username, for the above DSN.
2219 user_scores_sql_custom_query query
2221 This option gives you the ability to create a custom SQL query to
2222 retrieve user scores and preferences. In order to work correctly
2223 your query should return two values, the preference name and value,
2224 in that order. In addition, there are several "variables" that you
2225 can use as part of your query, these variables will be substituted
2226 for the current values right before the query is run. The current
2227 allowed variables are:
2228 _TABLE_
2230 The name of the table where user scores and preferences are
2231 stored. Currently hardcoded to userpref, to change this value
2232 you need to create a new custom query with the new table name.
2233 _USERNAME_
2235 The current user's username.
2236 _MAILBOX_
2238 The portion before the @ as derived from the current user's
2239 username.
2240 _DOMAIN_
2242 The portion after the @ as derived from the current user's
2243 username, this value may be null.
2244 The query must be one continuous line in order to parse correctly.
2246 Here are several example queries, please note that these are broken
2248 up for easy reading, in your config it should be one continuous
2249 line.
2250 Current default query:
2252 "SELECT preference, value FROM _TABLE_ WHERE username =
2253 _USERNAME_ OR username = '@GLOBAL' ORDER BY username ASC"
2254 Use global and then domain level defaults:
2256 "SELECT preference, value FROM _TABLE_ WHERE username =
2257 _USERNAME_ OR username = '@GLOBAL' OR username = '@~'||_DOMAIN_
2258 ORDER BY username ASC"
2259 Maybe global prefs should override user prefs:
2261 "SELECT preference, value FROM _TABLE_ WHERE username =
2262 _USERNAME_ OR username = '@GLOBAL' ORDER BY username DESC"
2263 user_scores_ldap_username
2265 This is the Bind DN used to connect to the LDAP server. It
2266 defaults to the empty string (""), allowing anonymous binding to
2267 work.
2268 Example: "cn=master,dc=koehntopp,dc=de"
2270 user_scores_ldap_password
2272 This is the password used to connect to the LDAP server. It
2273 defaults to the empty string ("").
2274 user_scores_fallback_to_global (default: 1)
2276 Fall back to global scores and settings if userprefs can't be
2277 loaded from SQL or LDAP, instead of passing the message through
2278 unprocessed.
2279 loadplugin [Mail::SpamAssassin::Plugin::]ModuleName [/path/module.pm]
2281 Load a SpamAssassin plugin module. The "ModuleName" is the perl
2282 module name, used to create the plugin object itself.
2283 Module naming is strict, name must only contain alphanumeric
2285 characters or underscores. File must have .pm extension.
2286 "/path/module.pm" is the file to load, containing the module's perl
2288 code; if it's specified as a relative path, it's considered to be
2289 relative to the current configuration file. If it is omitted, the
2290 module will be loaded using perl's search path (the @INC array).
2291 See "Mail::SpamAssassin::Plugin" for more details on writing
2293 plugins.
2294 tryplugin ModuleName [/path/module.pm]
2296 Same as "loadplugin", but silently ignored if the .pm file cannot
2297 be found in the filesystem.
2298 ignore_always_matching_regexps (Default: 0)
2300 Ignore any rule which contains a regexp which always matches.
2301 Currently only catches regexps which contain '||', or which begin
2302 or end with a '|'. Also ignore rules with "some" combinatorial
2303 explosions.
2304 geodb_module STRING
2306 This option tells SpamAssassin which geolocation module to use. If
2307 not specified, all supported ones are tried in this order:
2308 Plugins can override this internally if required.
2310 MaxMind::DB::Reader (same as GeoIP2::Database::Reader)
2312 Geo::IP
2313 IP::Country::DB_File (not used unless geodb_options path set)
2314 IP::Country::Fast
2315 geodb_options dbtype:/path/to/db ...
2317 Supported dbtypes:
2318 city - use City database country - use Country database isp - try
2320 loading ISP database asn - try loading ASN database
2321 Append full database path with colon, for example:
2323 isp:/opt/geoip/isp.mmdb
2324 Plugins can internally request all types they require,
2326 geodb_options is only needed if the default location search
2327 (described below) does not work.
2328 GeoIP/GeoIP2 searches these files/directories:
2330 country:
2332 GeoIP2-Country.mmdb, GeoLite2-Country.mmdb
2333 GeoIP.dat (and v6 version)
2334 city:
2335 GeoIP2-City.mmdb, GeoLite2-City.mmdb
2336 GeoIPCity.dat, GeoLiteCity.dat (and v6 versions)
2337 isp:
2338 GeoIP2-ISP.mmdb
2339 GeoIPISP.dat, GeoLiteISP.dat (and v6 versions)
2340 directories:
2341 /usr/local/share/GeoIP
2342 /usr/share/GeoIP
2343 /var/lib/GeoIP
2344 /opt/share/GeoIP
2345 geodb_search_path /path/to/GeoIP ...
2347 Alternative to geodb_options. Overrides the default list of
2348 directories to search for default filenames.
2349
2351 include filename
2352 Include configuration lines from "filename". Relative paths are
2353 considered relative to the current configuration file or user
2354 preferences file.
2355 if (boolean perl expression)
2357 Used to support conditional interpretation of the configuration
2358 file. Lines between this and a corresponding "else" or "endif" line
2359 will be ignored unless the expression evaluates as true (in the
2360 perl sense; that is, defined and non-0 and non-empty string).
2361 The conditional accepts a limited subset of perl for security --
2363 just enough to perform basic arithmetic comparisons. The following
2364 input is accepted:
2365 numbers, whitespace, arithmetic operations and grouping
2367 Namely these characters and ranges:
2368 ( ) - + * / _ . , < = > ! ~ 0-9 whitespace
2370 version
2372 This will be replaced with the version number of the currently-
2373 running SpamAssassin engine. Note: The version used is in the
2374 internal SpamAssassin version format which is "x.yyyzzz", where
2375 x is major version, y is minor version, and z is maintenance
2376 version. So 3.0.0 is 3.000000, and 3.4.80 is 3.004080.
2377 perl_version
2379 (Introduced in 3.4.1) This will be replaced with the version
2380 number of the currently-running perl engine. Note: The version
2381 used is in the $] version format which is "x.yyyzzz", where x
2382 is major version, y is minor version, and z is maintenance
2383 version. So 5.8.8 is 5.008008, and 5.10.0 is 5.010000. Use to
2384 protect rules that incorporate RE syntax elements introduced in
2385 later versions of perl, such as the "++" non-backtracking match
2386 introduced in perl 5.10. For example:
2387 # Avoid lint error on older perl installs
2389 # Check SA version first to avoid warnings on checking perl_version on older SA
2390 if version > 3.004001 && perl_version >= 5.018000
2391 body INVALID_RE_SYNTAX_IN_PERL_BEFORE_5_18 /(?[ \p{Thai} & \p{Digit} ])/
2392 endif
2393 Note that the above will still generate a warning on perl older
2395 than 5.10.0; to avoid that warning do this instead:
2396 # Avoid lint error on older perl installs
2398 if can(Mail::SpamAssassin::Conf::perl_min_version_5010000)
2399 body INVALID_RE_SYNTAX_IN_PERL_5_8 /\w++/
2400 endif
2401 Warning: a can() test is only defined for perl 5.10.0!
2403 plugin(Name::Of::Plugin)
2405 This is a function call that returns 1 if the plugin named
2406 "Name::Of::Plugin" is loaded, or "undef" otherwise.
2407 has(Name::Of::Package::function_name)
2409 This is a function call that returns 1 if the perl package
2410 named "Name::Of::Package" includes a function called
2411 "function_name", or "undef" otherwise. Note that packages can
2412 be SpamAssassin plugins or built-in classes, there's no
2413 difference in this respect. Internally this invokes
2414 UNIVERSAL::can.
2415 can(Name::Of::Package::function_name)
2417 This is a function call that returns 1 if the perl package
2418 named "Name::Of::Package" includes a function called
2419 "function_name" and that function returns a true value when
2420 called with no arguments, otherwise "undef" is returned.
2421 Is similar to "has", except that it also calls the named
2423 function, testing its return value (unlike the perl function
2424 UNIVERSAL::can). This makes it possible for a 'feature'
2425 function to determine its result value at run time.
2426 If the end of a configuration file is reached while still inside a
2428 "if" scope, a warning will be issued, but parsing will restart on
2429 the next file.
2430 For example:
2432 if (version > 3.000000)
2434 header MY_FOO ...
2435 endif
2436 loadplugin MyPlugin plugintest.pm
2438 if plugin (MyPlugin)
2440 header MY_PLUGIN_FOO eval:check_for_foo()
2441 score MY_PLUGIN_FOO 0.1
2442 endif
2443 ifplugin PluginModuleName
2445 An alias for "if plugin(PluginModuleName)".
2446 else
2448 Used to support conditional interpretation of the configuration
2449 file. Lines between this and a corresponding "endif" line, will be
2450 ignored unless the conditional expression evaluates as false (in
2451 the perl sense; that is, not defined and not 0 and non-empty
2452 string).
2453 require_version n.nnnnnn
2455 Indicates that the entire file, from this line on, requires a
2456 certain version of SpamAssassin to run. If a different (older or
2457 newer) version of SpamAssassin tries to read the configuration from
2458 this file, it will output a warning instead, and ignore it.
2459 Note: The version used is in the internal SpamAssassin version
2461 format which is "x.yyyzzz", where x is major version, y is minor
2462 version, and z is maintenance version. So 3.0.0 is 3.000000, and
2463 3.4.80 is 3.004080.
2464 enable_compat xxxxxx
2466 Define a version compatibility flag.
2467 This creates a function named
2469 "Mail::SpamAssassin::Conf::compat_xxxxxx", which returns true. It
2470 can be used for example in cf-files, similarly as existing
2471 "feature_" checks:
2472 if can(Mail::SpamAssassin::Conf::compat_xxxxxx)
2474 Name can only consist of [a-zA-Z0-9_] characters.
2476 Mainly used by SpamAssassin distribution to handle backwards
2478 compatibility issues.
2479
2481 The following "tags" can be used as placeholders in certain options.
2482 They will be replaced by the corresponding value when they are used.
2483 Some tags can take an argument (in parentheses). The argument is
2485 optional, and the default is shown below.
2486 _YESNO_ "Yes" for spam, "No" for nonspam (=ham)
2488 _YESNO(spam_str,ham_str)_ returns the first argument ("Yes" if missing)
2489 for spam, and the second argument ("No" if missing) for ham
2490 _YESNOCAPS_ "YES" for spam, "NO" for nonspam (=ham)
2491 _YESNOCAPS(spam_str,ham_str)_ same as _YESNO(...)_, but uppercased
2492 _SCORE(PAD)_ message score, if PAD is included and is either spaces or
2493 zeroes, then pad scores with that many spaces or zeroes
2494 (default, none) ie: _SCORE(0)_ makes 2.4 become 02.4,
2495 _SCORE(00)_ is 002.4. 12.3 would be 12.3 and 012.3
2496 respectively.
2497 _REQD_ message threshold
2498 _VERSION_ version (eg. 3.0.0 or 3.1.0-r26142-foo1)
2499 _SUBVERSION_ sub-version/code revision date (eg. 2004-01-10)
2500 _RULESVERSION_ comma-separated list of rules versions, retrieved from
2501 an '# UPDATE version' comment in rules files; if there is
2502 more than one set of rules (update channels) the order
2503 is unspecified (currently sorted by names of files);
2504 _HOSTNAME_ hostname of the machine the mail was processed on
2505 _REMOTEHOSTNAME_ hostname of the machine the mail was sent from, only
2506 available with spamd
2507 _REMOTEHOSTADDR_ ip address of the machine the mail was sent from, only
2508 available with spamd
2509 _BAYES_ bayes score
2510 _TOKENSUMMARY_ number of new, neutral, spammy, and hammy tokens found
2511 _BAYESTC_ number of new tokens found
2512 _BAYESTCLEARNED_ number of seen tokens found
2513 _BAYESTCSPAMMY_ number of spammy tokens found
2514 _BAYESTCHAMMY_ number of hammy tokens found
2515 _HAMMYTOKENS(N)_ the N most significant hammy tokens (default, 5)
2516 _SPAMMYTOKENS(N)_ the N most significant spammy tokens (default, 5)
2517 _DATE_ rfc-2822 date of scan
2518 _STARS(*)_ one "*" (use any character) for each full score point
2519 (note: limited to 50 'stars')
2520 _SENDERDOMAIN_ a domain name of the envelope sender address, lowercased
2521 _AUTHORDOMAIN_ a domain name of the author address (the From header
2522 field), lowercased; note that RFC 5322 allows a mail
2523 message to have multiple authors - currently only the
2524 domain name of the first email address is returned
2525 _RELAYSTRUSTED_ relays used and deemed to be trusted (see the
2526 'X-Spam-Relays-Trusted' pseudo-header)
2527 _RELAYSUNTRUSTED_ relays used that can not be trusted (see the
2528 'X-Spam-Relays-Untrusted' pseudo-header)
2529 _RELAYSINTERNAL_ relays used and deemed to be internal (see the
2530 'X-Spam-Relays-Internal' pseudo-header)
2531 _RELAYSEXTERNAL_ relays used and deemed to be external (see the
2532 'X-Spam-Relays-External' pseudo-header)
2533 _FIRSTTRUSTEDIP_ IP address of first trusted client (see RELAYSTRUSTED)
2534 _FIRSTTRUSTEDREVIP_ IP address of first trusted client (in reversed
2535 format suitable for RBL queries)
2536 _LASTEXTERNALIP_ IP address of client in the external-to-internal
2537 SMTP handover
2538 _LASTEXTERNALREVIP_ IP address of client in the external-to-internal
2539 SMTP handover (in reversed format suitable for RBL
2540 queries)
2541 _LASTEXTERNALRDNS_ reverse-DNS of client in the external-to-internal
2542 SMTP handover
2543 _LASTEXTERNALHELO_ HELO string used by client in the external-to-internal
2544 SMTP handover
2545 _AUTOLEARN_ autolearn status ("ham", "no", "spam", "disabled",
2546 "failed", "unavailable")
2547 _AUTOLEARNSCORE_ portion of message score used by autolearn
2548 _TESTS(,)_ tests hit separated by "," (or other separator)
2549 _TESTSSCORES(,)_ as above, except with scores appended (eg. AWL=-3.0,...)
2550 _SUBTESTS(,)_ subtests (start with "__") hit separated by ","
2551 (or other separator)
2552 _SUBTESTSCOLLAPSED(,)_ subtests (start with "__") hit separated by ","
2553 (or other separator) with duplicated rules collapsed
2554 _DCCB_ DCC's "Brand"
2555 _DCCR_ DCC's results
2556 _PYZOR_ Pyzor results
2557 _RBL_ full results for positive RBL queries in DNS URI format
2558 _LANGUAGES_ possible languages of mail
2559 _PREVIEW_ content preview
2560 _REPORT_ terse report of tests hit (for header reports)
2561 _SUBJPREFIX_ subject prefix based on rules, to be prepended to Subject
2562 header by SpamAssassin caller
2563 _SUMMARY_ summary of tests hit for standard report (for body reports)
2564 _CONTACTADDRESS_ contents of the 'report_contact' setting
2565 _HEADER(NAME)_ includes the value of a message header. value is the same
2566 as is found for header rules (see elsewhere in this doc)
2567 _TIMING_ timing breakdown report
2568 _ADDEDHEADERHAM_ resulting header fields as requested by add_header for spam
2569 _ADDEDHEADERSPAM_ resulting header fields as requested by add_header for ham
2570 _ADDEDHEADER_ same as ADDEDHEADERHAM for ham or ADDEDHEADERSPAM for spam
2571 If a tag reference uses the name of a tag which is not in this list or
2573 defined by a loaded plugin, the reference will be left intact and not
2574 replaced by any value.
2575 All template tag names must consist of only uppercase character set
2577 [A-Z0-9_] and not contain consecutive underscores (__).
2578 Additional, plugin specific, template tags can be found in the
2580 documentation for the following plugins:
2581 L<Mail::SpamAssassin::Plugin::ASN>
2583 L<Mail::SpamAssassin::Plugin::AWL>
2584 L<Mail::SpamAssassin::Plugin::TxRep>
2585 The "HAMMYTOKENS" and "SPAMMYTOKENS" tags have an optional second
2587 argument which specifies a format. See the HAMMYTOKENS/SPAMMYTOKENS
2588 TAG FORMAT section, below, for details.
2589 HAMMYTOKENS/SPAMMYTOKENS TAG FORMAT
2591 The "HAMMYTOKENS" and "SPAMMYTOKENS" tags have an optional second
2592 argument which specifies a format: "_SPAMMYTOKENS(N,FMT)_",
2593 "_HAMMYTOKENS(N,FMT)_" The following formats are available:
2594 short
2596 Only the tokens themselves are listed. For example, preference
2597 file entry:
2598 "add_header all Spammy _SPAMMYTOKENS(2,short)_"
2600 Results in message header:
2602 "X-Spam-Spammy: remove.php, UD:jpg"
2604 Indicating that the top two spammy tokens found are "remove.php"
2606 and "UD:jpg". (The token itself follows the last colon, the text
2607 before the colon indicates something about the token. "UD" means
2608 the token looks like it might be part of a domain name.)
2609 compact
2611 The token probability, an abbreviated declassification distance
2612 (see example), and the token are listed. For example, preference
2613 file entry:
2614 "add_header all Spammy _SPAMMYTOKENS(2,compact)_"
2616 Results in message header:
2618 "0.989-6--remove.php, 0.988-+--UD:jpg"
2620 Indicating that the probabilities of the top two tokens are 0.989
2622 and 0.988, respectively. The first token has a declassification
2623 distance of 6, meaning that if the token had appeared in at least 6
2624 more ham messages it would not be considered spammy. The "+" for
2625 the second token indicates a declassification distance greater than
2626 9.
2627 long
2629 Probability, declassification distance, number of times seen in a
2630 ham message, number of times seen in a spam message, age and the
2631 token are listed.
2632 For example, preference file entry:
2634 "add_header all Spammy _SPAMMYTOKENS(2,long)_"
2636 Results in message header:
2638 "X-Spam-Spammy: 0.989-6--0h-4s--4d--remove.php,
2640 0.988-33--2h-25s--1d--UD:jpg"
2641 In addition to the information provided by the compact option, the
2643 long option shows that the first token appeared in zero ham
2644 messages and four spam messages, and that it was last seen four
2645 days ago. The second token appeared in two ham messages, 25 spam
2646 messages and was last seen one day ago. (Unlike the "compact"
2647 option, the long option shows declassification distances that are
2648 greater than 9.)
2649
2651 A line starting with the text "lang xx" will only be interpreted if
2652 SpamAssassin is running in that locale, allowing test descriptions and
2653 templates to be set for that language.
2654 Current locale is determined from LANGUAGE, LC_ALL, LC_MESSAGES or LANG
2656 environment variables, first found is used.
2657 The locales string should specify either both the language and country,
2659 e.g. "lang pt_BR", or just the language, e.g. "lang de".
2660 Example:
2662 lang de describe EXAMPLE_RULE Beispielregel
2664
2666 Mail::SpamAssassin(3) spamassassin(1) spamd(1)
2667perl v5.38.0 2023-07-22 Mail::SpamAssassin::Conf(3)