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 http://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
55 The following options can be used in both site-wide ("local.cf") and
56 user-specific ("user_prefs") configuration files to customize how
57 SpamAssassin handles incoming email messages.
58 SCORING OPTIONS
60 required_score n.nn (default: 5)
61 Set the score required before a mail is considered spam. "n.nn"
62 can be an integer or a real number. 5.0 is the default setting,
63 and is quite aggressive; it would be suitable for a single-user
64 setup, but if you're an ISP installing SpamAssassin, you should
65 probably set the default to be more conservative, like 8.0 or 10.0.
66 It is not recommended to automatically delete or discard messages
67 marked as spam, as your users will complain, but if you choose to
68 do so, only delete messages with an exceptionally high score such
69 as 15.0 or higher. This option was previously known as
70 "required_hits" and that name is still accepted, but is deprecated.
71 score SYMBOLIC_TEST_NAME n.nn [ n.nn n.nn n.nn ]
73 Assign scores (the number of points for a hit) to a given test.
74 Scores can be positive or negative real numbers or integers.
75 "SYMBOLIC_TEST_NAME" is the symbolic name used by SpamAssassin for
76 that test; for example, 'FROM_ENDS_IN_NUMS'.
77 If only one valid score is listed, then that score is always used
79 for a test.
80 If four valid scores are listed, then the score that is used
82 depends on how SpamAssassin is being used. The first score is used
83 when both Bayes and network tests are disabled (score set 0). The
84 second score is used when Bayes is disabled, but network tests are
85 enabled (score set 1). The third score is used when Bayes is
86 enabled and network tests are disabled (score set 2). The fourth
87 score is used when Bayes is enabled and network tests are enabled
88 (score set 3).
89 Setting a rule's score to 0 will disable that rule from running.
91 If any of the score values are surrounded by parenthesis '()', then
93 all of the scores in the line are considered to be relative to the
94 already set score. ie: '(3)' means increase the score for this
95 rule by 3 points in all score sets. '(3) (0) (3) (0)' means
96 increase the score for this rule by 3 in score sets 0 and 2 only.
97 If no score is given for a test by the end of the configuration, a
99 default score is assigned: a score of 1.0 is used for all tests,
100 except those whose names begin with 'T_' (this is used to indicate
101 a rule in testing) which receive 0.01.
102 Note that test names which begin with '__' are indirect rules used
104 to compose meta-match rules and can also act as prerequisites to
105 other rules. They are not scored or listed in the 'tests hit'
106 reports, but assigning a score of 0 to an indirect rule will
107 disable it from running.
108 WHITELIST AND BLACKLIST OPTIONS
110 whitelist_from user@example.com
111 Used to whitelist sender addresses which send mail that is often
112 tagged (incorrectly) as spam.
113 Use of this setting is not recommended, since it blindly trusts the
115 message, which is routinely and easily forged by spammers and phish
116 senders. The recommended solution is to instead use
117 "whitelist_auth" or other authenticated whitelisting methods, or
118 "whitelist_from_rcvd".
119 Whitelist and blacklist addresses are now file-glob-style patterns,
121 so "friend@somewhere.com", "*@isp.com", or "*.domain.net" will all
122 work. Specifically, "*" and "?" are allowed, but all other
123 metacharacters are not. Regular expressions are not used for
124 security reasons. Matching is case-insensitive.
125 Multiple addresses per line, separated by spaces, is OK. Multiple
127 "whitelist_from" lines are also OK.
128 The headers checked for whitelist addresses are as follows: if
130 "Resent-From" is set, use that; otherwise check all addresses taken
131 from the following set of headers:
132 Envelope-Sender
134 Resent-Sender
135 X-Envelope-From
136 From
137 In addition, the "envelope sender" data, taken from the SMTP
139 envelope data where this is available, is looked up. See
140 "envelope_sender_header".
141 e.g.
143 whitelist_from joe@example.com fred@example.com
145 whitelist_from *@example.com
146 unwhitelist_from user@example.com
148 Used to override a default whitelist_from entry, so for example a
149 distribution whitelist_from can be overridden in a local.cf file,
150 or an individual user can override a whitelist_from entry in their
151 own "user_prefs" file. The specified email address has to match
152 exactly (although case-insensitively) the address previously used
153 in a whitelist_from line, which implies that a wildcard only
154 matches literally the same wildcard (not 'any' address).
155 e.g.
157 unwhitelist_from joe@example.com fred@example.com
159 unwhitelist_from *@example.com
160 whitelist_from_rcvd addr@lists.sourceforge.net sourceforge.net
162 Works similarly to whitelist_from, except that in addition to
163 matching a sender address, a relay's rDNS name or its IP address
164 must match too for the whitelisting rule to fire. The first
165 parameter is a sender's e-mail address to whitelist, and the second
166 is a string to match the relay's rDNS, or its IP address. Matching
167 is case-insensitive.
168 This second parameter is matched against the TCP-info information
170 field as provided in a FROM clause of a trace information (i.e. the
171 Received header field, see RFC 5321). Only the Received header
172 fields inserted by trusted hosts are considered. This parameter can
173 either be a full hostname, or the domain component of that
174 hostname, or an IP address in square brackets. The reverse DNS
175 lookup is done by a MTA, not by SpamAssassin.
176 In case of an IPv4 address in brackets, it may be truncated on
178 classful boundaries to cover whole subnets, e.g. "[10.1.2.3]",
179 "[10.1.2]", "[10.1]", "[10]". CIDR notation is currently not
180 supported, nor is IPv6. The matching on IP address is mainly
181 provided to cover rare cases where whitelisting of a sending MTA is
182 desired which does not have a correct reverse DNS configured.
183 In other words, if the host that connected to your MX had an IP
185 address 192.0.2.123 that mapped to 'sendinghost.example.org', you
186 should specify "sendinghost.example.org", or "example.org", or
187 "[192.0.2.123]" or "[192.0.2]" here.
188 Note that this requires that "internal_networks" be correct. For
190 simple cases, it will be, but for a complex network you may get
191 better results by setting that parameter.
192 It also requires that your mail exchangers be configured to perform
194 DNS reverse lookups on the connecting host's IP address, and to
195 record the result in the generated Received header field according
196 to RFC 5321.
197 e.g.
199 whitelist_from_rcvd joe@example.com example.com
201 whitelist_from_rcvd *@axkit.org sergeant.org
202 whitelist_from_rcvd *@axkit.org [192.0.2.123]
203 def_whitelist_from_rcvd addr@lists.sourceforge.net sourceforge.net
205 Same as "whitelist_from_rcvd", but used for the default whitelist
206 entries in the SpamAssassin distribution. The whitelist score is
207 lower, because these are often targets for spammer spoofing.
208 whitelist_allows_relays user@example.com
210 Specify addresses which are in "whitelist_from_rcvd" that sometimes
211 send through a mail relay other than the listed ones. By default
212 mail with a From address that is in "whitelist_from_rcvd" that does
213 not match the relay will trigger a forgery rule. Including the
214 address in "whitelist_allows_relay" prevents that.
215 Whitelist and blacklist addresses are now file-glob-style patterns,
217 so "friend@somewhere.com", "*@isp.com", or "*.domain.net" will all
218 work. Specifically, "*" and "?" are allowed, but all other
219 metacharacters are not. Regular expressions are not used for
220 security reasons. Matching is case-insensitive.
221 Multiple addresses per line, separated by spaces, is OK. Multiple
223 "whitelist_allows_relays" lines are also OK.
224 The specified email address does not have to match exactly the
226 address previously used in a whitelist_from_rcvd line as it is
227 compared to the address in the header.
228 e.g.
230 whitelist_allows_relays joe@example.com fred@example.com
232 whitelist_allows_relays *@example.com
233 unwhitelist_from_rcvd user@example.com
235 Used to override a default whitelist_from_rcvd entry, so for
236 example a distribution whitelist_from_rcvd can be overridden in a
237 local.cf file, or an individual user can override a
238 whitelist_from_rcvd entry in their own "user_prefs" file.
239 The specified email address has to match exactly the address
241 previously used in a whitelist_from_rcvd line.
242 e.g.
244 unwhitelist_from_rcvd joe@example.com fred@example.com
246 unwhitelist_from_rcvd *@axkit.org
247 blacklist_from user@example.com
249 Used to specify addresses which send mail that is often tagged
250 (incorrectly) as non-spam, but which the user doesn't want. Same
251 format as "whitelist_from".
252 unblacklist_from user@example.com
254 Used to override a default blacklist_from entry, so for example a
255 distribution blacklist_from can be overridden in a local.cf file,
256 or an individual user can override a blacklist_from entry in their
257 own "user_prefs" file. The specified email address has to match
258 exactly the address previously used in a blacklist_from line.
259 e.g.
261 unblacklist_from joe@example.com fred@example.com
263 unblacklist_from *@spammer.com
264 whitelist_to user@example.com
266 If the given address appears as a recipient in the message headers
267 (Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
268 be whitelisted. Useful if you're deploying SpamAssassin system-
269 wide, and don't want some users to have their mail filtered. Same
270 format as "whitelist_from".
271 There are three levels of To-whitelisting, "whitelist_to",
273 "more_spam_to" and "all_spam_to". Users in the first level may
274 still get some spammish mails blocked, but users in "all_spam_to"
275 should never get mail blocked.
276 The headers checked for whitelist addresses are as follows: if
278 "Resent-To" or "Resent-Cc" are set, use those; otherwise check all
279 addresses taken from the following set of headers:
280 To
282 Cc
283 Apparently-To
284 Delivered-To
285 Envelope-Recipients
286 Apparently-Resent-To
287 X-Envelope-To
288 Envelope-To
289 X-Delivered-To
290 X-Original-To
291 X-Rcpt-To
292 X-Real-To
293 more_spam_to user@example.com
295 See above.
296 all_spam_to user@example.com
298 See above.
299 blacklist_to user@example.com
301 If the given address appears as a recipient in the message headers
302 (Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
303 be blacklisted. Same format as "blacklist_from".
304 whitelist_auth user@example.com
306 Used to specify addresses which send mail that is often tagged
307 (incorrectly) as spam. This is different from "whitelist_from" and
308 "whitelist_from_rcvd" in that it first verifies that the message
309 was sent by an authorized sender for the address, before
310 whitelisting.
311 Authorization is performed using one of the installed sender-
313 authorization schemes: SPF (using
314 "Mail::SpamAssassin::Plugin::SPF"), or DKIM (using
315 "Mail::SpamAssassin::Plugin::DKIM"). Note that those plugins must
316 be active, and working, for this to operate.
317 Using "whitelist_auth" is roughly equivalent to specifying
319 duplicate "whitelist_from_spf", "whitelist_from_dk", and
320 "whitelist_from_dkim" lines for each of the addresses specified.
321 e.g.
323 whitelist_auth joe@example.com fred@example.com
325 whitelist_auth *@example.com
326 def_whitelist_auth user@example.com
328 Same as "whitelist_auth", but used for the default whitelist
329 entries in the SpamAssassin distribution. The whitelist score is
330 lower, because these are often targets for spammer spoofing.
331 unwhitelist_auth user@example.com
333 Used to override a "whitelist_auth" entry. The specified email
334 address has to match exactly the address previously used in a
335 "whitelist_auth" line.
336 e.g.
338 unwhitelist_auth joe@example.com fred@example.com
340 unwhitelist_auth *@example.com
341 enlist_uri_host (listname) host ...
343 Adds one or more host names or domain names to a named list of URI
344 domains. The named list can then be consulted through a
345 check_uri_host_listed() eval rule implemented by the WLBLEval
346 plugin, which takes the list name as an argument. Parenthesis
347 around a list name are literal - a required syntax.
348 Host names may optionally be prefixed by an exclamantion mark '!',
350 which produces false as a result if this entry matches. This makes
351 it easier to exclude some subdomains when their superdomain is
352 listed, for example:
353 enlist_uri_host (MYLIST) !sub1.example.com !sub2.example.com example.com
355 No wildcards are supported, but subdomains do match implicitly.
357 Lists are independent. Search for each named list starts by looking
358 up the full hostname first, then leading fields are progressively
359 stripped off (e.g.: sub.example.com, example.com, com) until a
360 match is found or we run out of fields. The first matching entry
361 (the most specific) determines if a lookup yielded a true (no '!'
362 prefix) or a false (with a '!' prefix) result.
363 If an URL found in a message contains an IP address in place of a
365 host name, the given list must specify the exact same IP address
366 (instead of a host name) in order to match.
367 Use the delist_uri_host directive to neutralize previous
369 enlist_uri_host settings.
370 Enlisting to lists named 'BLACK' and 'WHITE' have their shorthand
372 directives blacklist_uri_host and whitelist_uri_host and
373 corresponding default rules, but the names 'BLACK' and 'WHITE' are
374 otherwise not special or reserved.
375 delist_uri_host [ (listname) ] host ...
377 Removes one or more specified host names from a named list of URI
378 domains. Removing an unlisted name is ignored (is not an error).
379 Listname is optional, if specified then just the named list is
380 affected, otherwise hosts are removed from all URI host lists
381 created so far. Parenthesis around a list name are a required
382 syntax.
383 Note that directives in configuration files are processed in
385 sequence, the delist_uri_host only applies to previously listed
386 entries and has no effect on enlisted entries in yet-to-be-
387 processed directives.
388 For convenience (similarity to the enlist_uri_host directive)
390 hostnames may be prefixed by a an exclamation mark, which is
391 stripped off from each name and has no meaning here.
392 blacklist_uri_host host-or-domain ...
394 Is a shorthand for a directive: enlist_uri_host (BLACK) host ...
395 Please see directives enlist_uri_host and delist_uri_host for
397 details.
398 whitelist_uri_host host-or-domain ...
400 Is a shorthand for a directive: enlist_uri_host (BLACK) host ...
401 Please see directives enlist_uri_host and delist_uri_host for
403 details.
404 BASIC MESSAGE TAGGING OPTIONS
406 rewrite_header { subject | from | to } STRING
407 By default, suspected spam messages will not have the "Subject",
408 "From" or "To" lines tagged to indicate spam. By setting this
409 option, the header will be tagged with "STRING" to indicate that a
410 message is spam. For the From or To headers, this will take the
411 form of an RFC 2822 comment following the address in parantheses.
412 For the Subject header, this will be prepended to the original
413 subject. Note that you should only use the _REQD_ and _SCORE_ tags
414 when rewriting the Subject header if "report_safe" is 0. Otherwise,
415 you may not be able to remove the SpamAssassin markup via the
416 normal methods. More information about tags is explained below in
417 the TEMPLATE TAGS section.
418 Parentheses are not permitted in STRING if rewriting the From or To
420 headers. (They will be converted to square brackets.)
421 If "rewrite_header subject" is used, but the message being
423 rewritten does not already contain a "Subject" header, one will be
424 created.
425 A null value for "STRING" will remove any existing rewrite for the
427 specified header.
428 add_header { spam | ham | all } header_name string
430 Customized headers can be added to the specified type of messages
431 (spam, ham, or "all" to add to either). All headers begin with
432 "X-Spam-" (so a "header_name" Foo will generate a header called
433 X-Spam-Foo). header_name is restricted to the character set
434 [A-Za-z0-9_-].
435 The order of "add_header" configuration options is preserved,
437 inserted headers will follow this order of declarations. When
438 combining "add_header" with "clear_headers" and "remove_header",
439 keep in mind that "add_header" appends a new header to the current
440 list, after first removing any existing header fields of the same
441 name. Note also that "add_header", "clear_headers" and
442 "remove_header" may appear in multiple .cf files, which are
443 interpreted in alphabetic order.
444 "string" can contain tags as explained below in the TEMPLATE TAGS
446 section. You can also use "\n" and "\t" in the header to add
447 newlines and tabulators as desired. A backslash has to be written
448 as \\, any other escaped chars will be silently removed.
449 All headers will be folded if fold_headers is set to 1. Note:
451 Manually adding newlines via "\n" disables any further automatic
452 wrapping (ie: long header lines are possible). The lines will still
453 be properly folded (marked as continuing) though.
454 You can customize existing headers with add_header (only the
456 specified subset of messages will be changed).
457 See also "clear_headers" and "remove_header" for removing headers.
459 Here are some examples (these are the defaults, note that Checker-
461 Version can not be changed or removed):
462 add_header spam Flag _YESNOCAPS_
464 add_header all Status _YESNO_, score=_SCORE_ required=_REQD_ tests=_TESTS_ autolearn=_AUTOLEARN_ version=_VERSION_
465 add_header all Level _STARS(*)_
466 add_header all Checker-Version SpamAssassin _VERSION_ (_SUBVERSION_) on _HOSTNAME_
467 remove_header { spam | ham | all } header_name
469 Headers can be removed from the specified type of messages (spam,
470 ham, or "all" to remove from either). All headers begin with
471 "X-Spam-" (so "header_name" will be appended to "X-Spam-").
472 See also "clear_headers" for removing all the headers at once.
474 Note that X-Spam-Checker-Version is not removable because the
476 version information is needed by mail administrators and developers
477 to debug problems. Without at least one header, it might not even
478 be possible to determine that SpamAssassin is running.
479 clear_headers
481 Clear the list of headers to be added to messages. You may use
482 this before any add_header options to prevent the default headers
483 from being added to the message.
484 "add_header", "clear_headers" and "remove_header" may appear in
486 multiple .cf files, which are interpreted in alphabetic order, so
487 "clear_headers" in a later file will remove all added headers from
488 previously interpreted configuration files, which may or may not be
489 desired.
490 Note that X-Spam-Checker-Version is not removable because the
492 version information is needed by mail administrators and developers
493 to debug problems. Without at least one header, it might not even
494 be possible to determine that SpamAssassin is running.
495 report_safe ( 0 | 1 | 2 ) (default: 1)
497 if this option is set to 1, if an incoming message is tagged as
498 spam, instead of modifying the original message, SpamAssassin will
499 create a new report message and attach the original message as a
500 message/rfc822 MIME part (ensuring the original message is
501 completely preserved, not easily opened, and easier to recover).
502 If this option is set to 2, then original messages will be attached
504 with a content type of text/plain instead of message/rfc822. This
505 setting may be required for safety reasons on certain broken mail
506 clients that automatically load attachments without any action by
507 the user. This setting may also make it somewhat more difficult to
508 extract or view the original message.
509 If this option is set to 0, incoming spam is only modified by
511 adding some "X-Spam-" headers and no changes will be made to the
512 body. In addition, a header named X-Spam-Report will be added to
513 spam. You can use the remove_header option to remove that header
514 after setting report_safe to 0.
515 See report_safe_copy_headers if you want to copy headers from the
517 original mail into tagged messages.
518 LANGUAGE OPTIONS
520 ok_locales xx [ yy zz ... ] (default: all)
521 This option is used to specify which locales are considered OK for
522 incoming mail. Mail using the character sets that are allowed by
523 this option will not be marked as possibly being spam in a foreign
524 language.
525 If you receive lots of spam in foreign languages, and never get any
527 non-spam in these languages, this may help. Note that all
528 ISO-8859-* character sets, and Windows code page character sets,
529 are always permitted by default.
530 Set this to "all" to allow all character sets. This is the
532 default.
533 The rules "CHARSET_FARAWAY", "CHARSET_FARAWAY_BODY", and
535 "CHARSET_FARAWAY_HEADERS" are triggered based on how this is set.
536 Examples:
538 ok_locales all (allow all locales)
540 ok_locales en (only allow English)
541 ok_locales en ja zh (allow English, Japanese, and Chinese)
542 Note: if there are multiple ok_locales lines, only the last one is
544 used.
545 Select the locales to allow from the list below:
547 en - Western character sets in general
549 ja - Japanese character sets
550 ko - Korean character sets
551 ru - Cyrillic character sets
552 th - Thai character sets
553 zh - Chinese (both simplified and traditional) character sets
554 normalize_charset ( 0 | 1) (default: 0)
555 Whether to detect character sets and normalize message content to
556 Unicode. Requires the Encode::Detect module, HTML::Parser version
557 3.46 or later, and Perl 5.8.5 or later.
558 NETWORK TEST OPTIONS
560 trusted_networks IPaddress[/masklen] ... (default: none)
561 What networks or hosts are 'trusted' in your setup. Trusted in
562 this case means that relay hosts on these networks are considered
563 to not be potentially operated by spammers, open relays, or open
564 proxies. A trusted host could conceivably relay spam, but will not
565 originate it, and will not forge header data. DNS blacklist checks
566 will never query for hosts on these networks.
567 See "http://wiki.apache.org/spamassassin/TrustPath" for more
569 information.
570 MXes for your domain(s) and internal relays should also be
572 specified using the "internal_networks" setting. When there are
573 'trusted' hosts that are not MXes or internal relays for your
574 domain(s) they should only be specified in "trusted_networks".
575 The "IPaddress" can be an IPv4 address (in a dot-quad form), or an
577 IPv6 address optionally enclosed in square brackets. Scoped link-
578 local IPv6 addresses are syntactically recognized but the interface
579 scope is currently ignored (e.g. [fe80::1234%eth0] ) and should be
580 avoided.
581 If a "/masklen" is specified, it is considered a CIDR-style
583 'netmask' length, specified in bits. If it is not specified, but
584 less than 4 octets of an IPv4 address are specified with a trailing
585 dot, an implied netmask length covers all addresses in remaining
586 octets (i.e. implied masklen is /8 or /16 or /24). If masklen is
587 not specified, and there is not trailing dot, then just a single IP
588 address specified is used, as if the masklen were "/32" with an
589 IPv4 address, or "/128" in case of an IPv6 address.
590 If a network or host address is prefaced by a "!" the matching
592 network or host will be excluded from the list even if a less
593 specific (shorter netmask length) subnet is later specified in the
594 list. This allows a subset of a wider network to be exempt. In case
595 of specifying overlapping subnets, specify more specific subnets
596 first (tighter matching, i.e. with a longer netmask length),
597 followed by less specific (shorter netmask length) subnets to get
598 predictable results regarless of the search algorithm used - when
599 Net::Patricia module is installed the search finds the tightest
600 matching entry in the list, while a sequential search as used in
601 absence of the module Net::Patricia will find the first matching
602 entry in the list.
603 Note: 127.0.0.0/8 and ::1 are always included in trusted_networks,
605 regardless of your config.
606 Examples:
608 trusted_networks 192.168.0.0/16 # all in 192.168.*.*
610 trusted_networks 192.168. # all in 192.168.*.*
611 trusted_networks 212.17.35.15 # just that host
612 trusted_networks !10.0.1.5 10.0.1/24 # all in 10.0.1.* but not 10.0.1.5
613 trusted_networks 2001:db8:1::1 !2001:db8:1::/64 2001:db8::/32
614 # 2001:db8::/32 and 2001:db8:1::1/128, except the rest of 2001:db8:1::/64
615 This operates additively, so a "trusted_networks" line after
617 another one will append new entries to the list of trusted
618 networks. To clear out the existing entries, use
619 "clear_trusted_networks".
620 If "trusted_networks" is not set and "internal_networks" is, the
622 value of "internal_networks" will be used for this parameter.
623 If neither "trusted_networks" or "internal_networks" is set, a
625 basic inference algorithm is applied. This works as follows:
626 · If the 'from' host has an IP address in a private (RFC 1918)
628 network range, then it's trusted
629 · If there are authentication tokens in the received header, and
631 the previous host was trusted, then this host is also trusted
632 · Otherwise this host, and all further hosts, are consider
634 untrusted.
635 clear_trusted_networks
637 Empty the list of trusted networks.
638 internal_networks IPaddress[/masklen] ... (default: none)
640 What networks or hosts are 'internal' in your setup. Internal
641 means that relay hosts on these networks are considered to be MXes
642 for your domain(s), or internal relays. This uses the same syntax
643 as "trusted_networks", above - see there for details.
644 This value is used when checking 'dial-up' or dynamic IP address
646 blocklists, in order to detect direct-to-MX spamming.
647 Trusted relays that accept mail directly from dial-up connections
649 (i.e. are also performing a role of mail submission agents - MSA)
650 should not be listed in "internal_networks". List them only in
651 "trusted_networks".
652 If "trusted_networks" is set and "internal_networks" is not, the
654 value of "trusted_networks" will be used for this parameter.
655 If neither "trusted_networks" nor "internal_networks" is set, no
657 addresses will be considered local; in other words, any relays past
658 the machine where SpamAssassin is running will be considered
659 external.
660 Every entry in "internal_networks" must appear in
662 "trusted_networks"; in other words, "internal_networks" is always a
663 subset of the trusted set.
664 Note: 127/8 and ::1 are always included in internal_networks,
666 regardless of your config.
667 clear_internal_networks
669 Empty the list of internal networks.
670 msa_networks IPaddress[/masklen] ... (default: none)
672 The networks or hosts which are acting as MSAs in your setup (but
673 not also as MX relays). This uses the same syntax as
674 "trusted_networks", above - see there for details.
675 MSA means that the relay hosts on these networks accept mail from
677 your own users and authenticates them appropriately. These relays
678 will never accept mail from hosts that aren't authenticated in some
679 way. Examples of authentication include, IP lists, SMTP AUTH, POP-
680 before-SMTP, etc.
681 All relays found in the message headers after the MSA relay will
683 take on the same trusted and internal classifications as the MSA
684 relay itself, as defined by your trusted_networks and
685 internal_networks configuration.
686 For example, if the MSA relay is trusted and internal so will all
688 of the relays that precede it.
689 When using msa_networks to identify an MSA it is recommended that
691 you treat that MSA as both trusted and internal. When an MSA is
692 not included in msa_networks you should treat the MSA as trusted
693 but not internal, however if the MSA is also acting as an MX or
694 intermediate relay you must always treat it as both trusted and
695 internal and ensure that the MSA includes visible auth tokens in
696 its Received header to identify submission clients.
697 Warning: Never include an MSA that also acts as an MX (or is also
699 an intermediate relay for an MX) or otherwise accepts mail from
700 non-authenticated users in msa_networks. Doing so will result in
701 unknown external relays being trusted.
702 clear_msa_networks
704 Empty the list of msa networks.
705 originating_ip_headers header ... (default: X-Yahoo-Post-IP
707 X-Originating-IP X-Apparently-From X-SenderIP)
708 A list of header field names from which an originating IP address
709 can be obtained. For example, webmail servers may record a client
710 IP address in X-Originating-IP.
711 These IP addresses are virtually appended into the Received: chain,
713 so they are used in RBL checks where appropriate.
714 Currently the IP addresses are not added into X-Spam-Relays-*
716 header fields, but they may be in the future.
717 clear_originating_ip_headers
719 Empty the list of 'originating IP address' header field names.
720 always_trust_envelope_sender ( 0 | 1 ) (default: 0)
722 Trust the envelope sender even if the message has been passed
723 through one or more trusted relays. See also
724 "envelope_sender_header".
725 skip_rbl_checks ( 0 | 1 ) (default: 0)
727 Turning on the skip_rbl_checks setting will disable the DNSEval
728 plugin, which implements Real-time Block List (or: Blackhole List)
729 (RBL) lookups.
730 By default, SpamAssassin will run RBL checks. Individual blocklists
732 may be disabled selectively by setting a score of a corresponding
733 rule to 0.
734 See also a related configuration parameter skip_uribl_checks, which
736 controls the URIDNSBL plugin (documented in the URIDNSBL man page).
737 dns_available { yes | no | test[: domain1 domain2...] } (default:
739 yes)
740 Tells SpamAssassin whether DNS resolving is available or not. A
741 value yes indicates DNS resolving is available, a value no
742 indicates DNS resolving is not available - both of these values
743 apply unconditionally and skip initial DNS tests, which can be slow
744 or unreliable.
745 When the option value is a test (with or without arguments),
747 SpamAssassin will query some domain names on the internet during
748 initialization, attempting to determine if DNS resolving is working
749 or not. A space-separated list of domain names may be specified
750 explicitly, or left to a built-in default of a dozen or so domain
751 names. From an explicit or a default list a subset of three domain
752 names is picked randomly for checking. The test queries for NS
753 records of these domain: if at least one query returns a success
754 then SpamAssassin considers DNS resolving as available, otherwise
755 not.
756 The problem is that the test can introduce some startup delay if a
758 network connection is down, and in some cases it can wrongly guess
759 that DNS is unavailable because a test connection failed, what
760 causes disabling several DNS-dependent tests.
761 Please note, the DNS test queries for NS records, so specify domain
763 names, not host names.
764 Since version 3.4.0 of SpamAssassin a default setting for option
766 dns_available is yes. A default in older versions was test.
767 dns_server ip-addr-port (default: entries provided by Net::DNS)
769 Specifies an IP address of a DNS server, and optionally its port
770 number. The dns_server directive may be specified multiple times,
771 each entry adding to a list of available resolving name servers.
772 The ip-addr-port argument can either be an IPv4 or IPv6 address,
773 optionally enclosed in brackets, and optionally followed by a colon
774 and a port number. In absence of a port number a standard port
775 number 53 is assumed. When an IPv6 address is specified along with
776 a port number, the address must be enclosed in brackets to avoid
777 parsing ambiguity regarding a colon separator,
778 Examples :
780 dns_server 127.0.0.1
781 dns_server 127.0.0.1:53
782 dns_server [127.0.0.1]:53
783 dns_server [::1]:53
784 In absence of dns_server directives, the list of name servers is
786 provided by Net::DNS module, which typically obtains the list from
787 /etc/resolv.conf, but this may be platform dependent. Please
788 consult the Net::DNS::Resolver documentation for details.
789 clear_dns_servers
791 Empty the list of explicitly configured DNS servers through a
792 dns_server directive, falling back to Net::DNS -supplied defaults.
793 dns_local_ports_permit ranges...
795 Add the specified ports or ports ranges to the set of allowed port
796 numbers that can be used as local port numbers when sending DNS
797 queries to a resolver.
798 The argument is a whitespace-separated or a comma-separated list of
800 single port numbers n, or port number pairs (i.e. m-n) delimited by
801 a '-', representing a range. Allowed port numbers are between 1 and
802 65535.
803 Directives dns_local_ports_permit and dns_local_ports_avoid are
805 processed in order in which they appear in configuration files.
806 Each directive adds (or subtracts) its subsets of ports to a
807 current set of available ports. Whatever is left in the set by the
808 end of configuration processing is made available to a DNS
809 resolving client code.
810 If the resulting set of port numbers is empty (see also the
812 directive dns_local_ports_none), then SpamAssassin does not apply
813 its ports randomization logic, but instead leaves the operating
814 system to choose a suitable free local port number.
815 The initial set consists of all port numbers in the range
817 1024-65535. Note that system config files already modify the set
818 and remove all the IANA registered port numbers and some other
819 ranges, so there is rarely a need to adjust the ranges by site-
820 specific directives.
821 See also directives dns_local_ports_permit and
823 dns_local_ports_none.
824 dns_local_ports_avoid ranges...
826 Remove specified ports or ports ranges from the set of allowed port
827 numbers that can be used as local port numbers when sending DNS
828 queries to a resolver.
829 Please see directive dns_local_ports_permit for details.
831 dns_local_ports_none
833 Is a fast shorthand for:
834 dns_local_ports_avoid 1-65535
836 leaving the set of available DNS query local port numbers empty. In
838 all respects (apart from speed) it is equivalent to the shown
839 directive, and can be freely mixed with dns_local_ports_permit and
840 dns_local_ports_avoid.
841 If the resulting set of port numbers is empty, then SpamAssassin
843 does not apply its ports randomization logic, but instead leaves
844 the operating system to choose a suitable free local port number.
845 See also directives dns_local_ports_permit and
847 dns_local_ports_avoid.
848 dns_test_interval n (default: 600 seconds)
850 If dns_available is set to test, the dns_test_interval time in
851 number of seconds will tell SpamAssassin how often to retest for
852 working DNS. A numeric value is optionally suffixed by a time unit
853 (s, m, h, d, w, indicating seconds (default), minutes, hours, days,
854 weeks).
855 dns_options opts (default: norotate, nodns0x20, edns=4096)
857 Provides a (whitespace or comma -separated) list of options
858 applying to DNS resolving. Available options are: rotate, dns0x20
859 and edns (or edns0). Option name may be negated by prepending a no
860 (e.g. norotate, NoEDNS) to counteract a previously enabled option.
861 Option names are not case-sensitive. The dns_options directive may
862 appear in configuration files multiple times, the last setting
863 prevails.
864 Option edns (or edsn0) may take a value which specifies a
866 requestor's acceptable UDP payload size according to EDNS0
867 specifications (RFC 6891, ex RFC 2671) e.g. edns=4096. When EDNS0
868 is off (noedns or edns=512) a traditional implied UDP payload size
869 is 512 bytes, which is also a minimum allowed value for this
870 option. When the option is specified but a value is not provided, a
871 conservative default of 1220 bytes is implied. It is recommended to
872 keep edns enabled when using a local recursive DNS server which
873 supports EDNS0 (like most modern DNS servers do), a suitable
874 setting in this case is edns=4096, which is also a default.
875 Allowing UDP payload size larger than 512 bytes can avoid
876 truncation of resource records in large DNS responses (like in TXT
877 records of some SPF and DKIM responses, or when an unreasonable
878 number of A records is published by some domain). The option should
879 be disabled when a recursive DNS server is only reachable through
880 non- RFC 6891 compliant middleboxes (such as some old-fashioned
881 firewall) which bans DNS UDP payload sizes larger than 512 bytes. A
882 suitable value when a non-local recursive DNS server is used and a
883 middlebox does allow EDNS0 but blocks fragmented IP packets is
884 perhaps 1220 bytes, allowing a DNS UDP packet to fit within a
885 single IP packet in most cases (a slightly less conservative range
886 would be 1280-1410 bytes).
887 Option rotate causes SpamAssassin to choose a DNS server at random
889 from all servers listed in "/etc/resolv.conf" every
890 dns_test_interval seconds, effectively spreading the load over all
891 currently available DNS servers when there are many spamd workers.
892 Option dns0x20 enables randomization of letters in a DNS query
894 label according to draft-vixie-dnsext-dns0x20, decreasing a chance
895 of collisions of responses (by chance or by a malicious intent) by
896 increasing spread as provided by a 16-bit query ID and up to 16
897 bits of a port number, with additional bits as encoded by flipping
898 case (upper/lower) of letters in a query. The number of additional
899 random bits corresponds to the number of letters in a query label.
900 Should work reliably with all mainstream DNS servers - do not turn
901 on if you see frequent info messages "dns: no callback for id:" in
902 the log, or if RBL or URIDNS lookups do not work for no apparent
903 reason.
904 dns_query_restriction (allow|deny) domain1 domain2 ...
906 Option allows disabling of rules which would result in a DNS query
907 to one of the listed domains. The first argument must be a literal
908 "allow" or "deny", remaining arguments are domains names.
909 Most DNS queries (with some exceptions) are subject to
911 dns_query_restriction. A domain to be queried is successively
912 stripped-off of its leading labels (thus yielding a series of its
913 parent domains), and on each iteration a check is made against an
914 associative array generated by dns_query_restriction options.
915 Search stops at the first match (i.e. the tightest match), and the
916 matching entry with its "allow" or "deny" value then controls
917 whether a DNS query is allowed to be launched.
918 If no match is found an implicit default is to allow a query. The
920 purpose of an explicit "allow" entry is to be able to override a
921 previously configured "deny" on the same domain or to override an
922 entry (possibly yet to be configured in subsequent config
923 directives) on one of its parent domains. Thus an 'allow
924 zen.spamhaus.org' with a 'deny spamhaus.org' would permit DNS
925 queries on a specific DNS BL zone but deny queries to other zones
926 under the same parent domain.
927 Domains are matched case-insensitively, no wildcards are
929 recognized, there should be no leading or trailing dot.
930 Specifying a block on querying a domain name has a similar effect
932 as setting a score of corresponding DNSBL and URIBL rules to zero,
933 and can be a handy alternative to hunting for such rules when a
934 site policy does not allow certain DNS block lists to be queried.
935 Example:
937 dns_query_restriction deny dnswl.org surbl.org
938 dns_query_restriction allow zen.spamhaus.org
939 dns_query_restriction deny spamhaus.org mailspike.net
940 spamcop.net
941 clear_dns_query_restriction
943 The option removes any entries entered by previous
944 'dns_query_restriction' options, leaving the list empty, i.e.
945 allowing DNS queries for any domain (including any DNS BL zone).
946 LEARNING OPTIONS
948 use_learner ( 0 | 1 ) (default: 1)
949 Whether to use any machine-learning classifiers with SpamAssassin,
950 such as the default 'BAYES_*' rules. Setting this to 0 will
951 disable use of any and all human-trained classifiers.
952 use_bayes ( 0 | 1 ) (default: 1)
954 Whether to use the naive-Bayesian-style classifier built into
955 SpamAssassin. This is a master on/off switch for all Bayes-related
956 operations.
957 use_bayes_rules ( 0 | 1 ) (default: 1)
959 Whether to use rules using the naive-Bayesian-style classifier
960 built into SpamAssassin. This allows you to disable the rules
961 while leaving auto and manual learning enabled.
962 bayes_auto_learn ( 0 | 1 ) (default: 1)
964 Whether SpamAssassin should automatically feed high-scoring mails
965 (or low-scoring mails, for non-spam) into its learning systems.
966 The only learning system supported currently is a naive-Bayesian-
967 style classifier.
968 See the documentation for the
970 "Mail::SpamAssassin::Plugin::AutoLearnThreshold" plugin module for
971 details on how Bayes auto-learning is implemented by default.
972 bayes_ignore_header header_name
974 If you receive mail filtered by upstream mail systems, like a spam-
975 filtering ISP or mailing list, and that service adds new headers
976 (as most of them do), these headers may provide inappropriate cues
977 to the Bayesian classifier, allowing it to take a "short cut". To
978 avoid this, list the headers using this setting. Example:
979 bayes_ignore_header X-Upstream-Spamfilter
981 bayes_ignore_header X-Upstream-SomethingElse
982 bayes_ignore_from user@example.com
984 Bayesian classification and autolearning will not be performed on
985 mail from the listed addresses. Program "sa-learn" will also
986 ignore the listed addresses if it is invoked using the
987 "--use-ignores" option. One or more addresses can be listed, see
988 "whitelist_from".
989 Spam messages from certain senders may contain many words that
991 frequently occur in ham. For example, one might read messages from
992 a preferred bookstore but also get unwanted spam messages from
993 other bookstores. If the unwanted messages are learned as spam
994 then any messages discussing books, including the preferred
995 bookstore and antiquarian messages would be in danger of being
996 marked as spam. The addresses of the annoying bookstores would be
997 listed. (Assuming they were halfway legitimate and didn't send you
998 mail through myriad affiliates.)
999 Those who have pieces of spam in legitimate messages or otherwise
1001 receive ham messages containing potentially spammy words might fear
1002 that some spam messages might be in danger of being marked as ham.
1003 The addresses of the spam mailing lists, correspondents, etc.
1004 would be listed.
1005 bayes_ignore_to user@example.com
1007 Bayesian classification and autolearning will not be performed on
1008 mail to the listed addresses. See "bayes_ignore_from" for details.
1009 bayes_min_ham_num (Default: 200)
1011 bayes_min_spam_num (Default: 200)
1012 To be accurate, the Bayes system does not activate until a certain
1013 number of ham (non-spam) and spam have been learned. The default
1014 is 200 of each ham and spam, but you can tune these up or down with
1015 these two settings.
1016 bayes_learn_during_report (Default: 1)
1018 The Bayes system will, by default, learn any reported messages
1019 ("spamassassin -r") as spam. If you do not want this to happen,
1020 set this option to 0.
1021 bayes_sql_override_username
1023 Used by BayesStore::SQL storage implementation.
1024 If this options is set the BayesStore::SQL module will override the
1026 set username with the value given. This could be useful for
1027 implementing global or group bayes databases.
1028 bayes_use_hapaxes (default: 1)
1030 Should the Bayesian classifier use hapaxes (words/tokens that occur
1031 only once) when classifying? This produces significantly better
1032 hit-rates.
1033 bayes_journal_max_size (default: 102400)
1035 SpamAssassin will opportunistically sync the journal and the
1036 database. It will do so once a day, but will sync more often if
1037 the journal file size goes above this setting, in bytes. If set to
1038 0, opportunistic syncing will not occur.
1039 bayes_expiry_max_db_size (default: 150000)
1041 What should be the maximum size of the Bayes tokens database? When
1042 expiry occurs, the Bayes system will keep either 75% of the maximum
1043 value, or 100,000 tokens, whichever has a larger value. 150,000
1044 tokens is roughly equivalent to a 8Mb database file.
1045 bayes_auto_expire (default: 1)
1047 If enabled, the Bayes system will try to automatically expire old
1048 tokens from the database. Auto-expiry occurs when the number of
1049 tokens in the database surpasses the bayes_expiry_max_db_size
1050 value. If a bayes datastore backend does not implement individual
1051 key/value expirations, the setting is silently ignored.
1052 bayes_token_ttl (default: 3w, i.e. 3 weeks)
1054 Time-to-live / expiration time in seconds for tokens kept in a
1055 Bayes database. A numeric value is optionally suffixed by a time
1056 unit (s, m, h, d, w, indicating seconds (default), minutes, hours,
1057 days, weeks).
1058 If bayes_auto_expire is true and a Bayes datastore backend supports
1060 it (currently only Redis), this setting controls deletion of
1061 expired tokens from a bayes database. The value is observed on a
1062 best-effort basis, exact timing promises are not necessarily kept.
1063 If a bayes datastore backend does not implement individual
1064 key/value expirations, the setting is silently ignored.
1065 bayes_seen_ttl (default: 8d, i.e. 8 days)
1067 Time-to-live / expiration time in seconds for 'seen' entries (i.e.
1068 mail message digests with their status) kept in a Bayes database.
1069 A numeric value is optionally suffixed by a time unit (s, m, h, d,
1070 w, indicating seconds (default), minutes, hours, days, weeks).
1071 If bayes_auto_expire is true and a Bayes datastore backend supports
1073 it (currently only Redis), this setting controls deletion of
1074 expired 'seen' entries from a bayes database. The value is observed
1075 on a best-effort basis, exact timing promises are not necessarily
1076 kept. If a bayes datastore backend does not implement individual
1077 key/value expirations, the setting is silently ignored.
1078 bayes_learn_to_journal (default: 0)
1080 If this option is set, whenever SpamAssassin does Bayes learning,
1081 it will put the information into the journal instead of directly
1082 into the database. This lowers contention for locking the database
1083 to execute an update, but will also cause more access to the
1084 journal and cause a delay before the updates are actually committed
1085 to the Bayes database.
1086 MISCELLANEOUS OPTIONS
1088 time_limit n (default: 300)
1089 Specifies a limit on elapsed time in seconds that SpamAssassin is
1090 allowed to spend before providing a result. The value may be
1091 fractional and must not be negative, zero is interpreted as
1092 unlimited. The default is 300 seconds for consistency with the
1093 spamd default setting of --timeout-child .
1094 This is a best-effort advisory setting, processing will not be
1096 abruptly aborted at an arbitrary point in processing when the time
1097 limit is exceeded, but only on reaching one of locations in the
1098 program flow equipped with a time test. Currently equipped with the
1099 test are the main checking loop, asynchronous DNS lookups, plugins
1100 which are calling external programs. Rule evaluation is guarded by
1101 starting a timer (alarm) on each set of compiled rules.
1102 When a message is passed to Mail::SpamAssassin::parse, a deadline
1104 time is established as a sum of current time and the "time_limit"
1105 setting.
1106 This deadline may also be specified by a caller through an option
1108 'master_deadline' in $suppl_attrib on a call to parse(), possibly
1109 providing a more accurate deadline taking into account past and
1110 expected future processing of a message in a mail filtering setup.
1111 If both the config option as well as a 'master_deadline' option in
1112 a call are provided, the shorter time limit of the two is used
1113 (since version 3.3.2). Note that spamd (and possibly third-party
1114 callers of SpamAssassin) will supply the 'master_deadline' option
1115 in a call based on its --timeout-child option (or equivalent),
1116 unlike the command line "spamassassin", which has no such command
1117 line option.
1118 When a time limit is exceeded, most of the remaining tests will be
1120 skipped, as well as auto-learning. Whatever tests fired so far will
1121 determine the final score. The behaviour is similar to short-
1122 circuiting with attribute 'on', as implemented by a Shortcircuit
1123 plugin. A synthetic hit on a rule named TIME_LIMIT_EXCEEDED with a
1124 near-zero default score is generated, so that the report will
1125 reflect the event. A score for TIME_LIMIT_EXCEEDED may be provided
1126 explicitly in a configuration file, for example to achieve
1127 whitelisting or blacklisting effect for messages with long
1128 processing times.
1129 The "time_limit" option is a useful protection against excessive
1131 processing time on certain degenerate or unusually long or complex
1132 mail messages, as well as against some DoS attacks. It is also
1133 needed in time-critical pre-queue filtering setups (e.g. milter,
1134 proxy, integration with MTA), where message processing must finish
1135 before a SMTP client times out. RFC 5321 prescribes in section
1136 4.5.3.2.6 the 'DATA Termination' time limit of 10 minutes, although
1137 it is not unusual to see some SMTP clients abort sooner on waiting
1138 for a response. A sensible "time_limit" for a pre-queue filtering
1139 setup is maybe 50 seconds, assuming that clients are willing to
1140 wait at least a minute.
1141 lock_method type
1143 Select the file-locking method used to protect database files on-
1144 disk. By default, SpamAssassin uses an NFS-safe locking method on
1145 UNIX; however, if you are sure that the database files you'll be
1146 using for Bayes and AWL storage will never be accessed over NFS, a
1147 non-NFS-safe locking system can be selected.
1148 This will be quite a bit faster, but may risk file corruption if
1150 the files are ever accessed by multiple clients at once, and one or
1151 more of them is accessing them through an NFS filesystem.
1152 Note that different platforms require different locking systems.
1154 The supported locking systems for "type" are as follows:
1156 nfssafe - an NFS-safe locking system
1158 flock - simple UNIX "flock()" locking
1159 win32 - Win32 locking using "sysopen (..., O_CREAT|O_EXCL)".
1160 nfssafe and flock are only available on UNIX, and win32 is only
1162 available on Windows. By default, SpamAssassin will choose either
1163 nfssafe or win32 depending on the platform in use.
1164 fold_headers ( 0 | 1 ) (default: 1)
1166 By default, headers added by SpamAssassin will be whitespace
1167 folded. In other words, they will be broken up into multiple lines
1168 instead of one very long one and each continuation line will have a
1169 tabulator prepended to mark it as a continuation of the preceding
1170 one.
1171 The automatic wrapping can be disabled here. Note that this can
1173 generate very long lines. RFC 2822 required that header lines do
1174 not exceed 998 characters (not counting the final CRLF).
1175 report_safe_copy_headers header_name ...
1177 If using "report_safe", a few of the headers from the original
1178 message are copied into the wrapper header (From, To, Cc, Subject,
1179 Date, etc.) If you want to have other headers copied as well, you
1180 can add them using this option. You can specify multiple headers
1181 on the same line, separated by spaces, or you can just use multiple
1182 lines.
1183 envelope_sender_header Name-Of-Header
1185 SpamAssassin will attempt to discover the address used in the 'MAIL
1186 FROM:' phase of the SMTP transaction that delivered this message,
1187 if this data has been made available by the SMTP server. This is
1188 used in the "EnvelopeFrom" pseudo-header, and for various rules
1189 such as SPF checking.
1190 By default, various MTAs will use different headers, such as the
1192 following:
1193 X-Envelope-From
1195 Envelope-Sender
1196 X-Sender
1197 Return-Path
1198 SpamAssassin will attempt to use these, if some heuristics (such as
1200 the header placement in the message, or the absence of fetchmail
1201 signatures) appear to indicate that they are safe to use. However,
1202 it may choose the wrong headers in some mailserver configurations.
1203 (More discussion of this can be found in bug 2142 and bug 4747 in
1204 the SpamAssassin BugZilla.)
1205 To avoid this heuristic failure, the "envelope_sender_header"
1207 setting may be helpful. Name the header that your MTA or MDA adds
1208 to messages containing the address used at the MAIL FROM step of
1209 the SMTP transaction.
1210 If the header in question contains "<" or ">" characters at the
1212 start and end of the email address in the right-hand side, as in
1213 the SMTP transaction, these will be stripped.
1214 If the header is not found in a message, or if it's value does not
1216 contain an "@" sign, SpamAssassin will issue a warning in the logs
1217 and fall back to its default heuristics.
1218 (Note for MTA developers: we would prefer if the use of a single
1220 header be avoided in future, since that precludes 'downstream' spam
1221 scanning.
1222 "http://wiki.apache.org/spamassassin/EnvelopeSenderInReceived"
1223 details a better proposal, storing the envelope sender at each hop
1224 in the "Received" header.)
1225 example:
1227 envelope_sender_header X-SA-Exim-Mail-From
1229 describe SYMBOLIC_TEST_NAME description ...
1231 Used to describe a test. This text is shown to users in the
1232 detailed report.
1233 Note that test names which begin with '__' are reserved for meta-
1235 match sub-rules, and are not scored or listed in the 'tests hit'
1236 reports.
1237 Also note that by convention, rule descriptions should be limited
1239 in length to no more than 50 characters.
1240 report_charset CHARSET (default: unset)
1242 Set the MIME Content-Type charset used for the text/plain report
1243 which is attached to spam mail messages.
1244 report ...some text for a report...
1246 Set the report template which is attached to spam mail messages.
1247 See the "10_default_prefs.cf" configuration file in
1248 "/usr/share/spamassassin" for an example.
1249 If you change this, try to keep it under 78 columns. Each "report"
1251 line appends to the existing template, so use
1252 "clear_report_template" to restart.
1253 Tags can be included as explained above.
1255 clear_report_template
1257 Clear the report template.
1258 report_contact ...text of contact address...
1260 Set what _CONTACTADDRESS_ is replaced with in the above report
1261 text. By default, this is 'the administrator of that system',
1262 since the hostname of the system the scanner is running on is also
1263 included.
1264 report_hostname ...hostname to use...
1266 Set what _HOSTNAME_ is replaced with in the above report text. By
1267 default, this is determined dynamically as whatever the host
1268 running SpamAssassin calls itself.
1269 unsafe_report ...some text for a report...
1271 Set the report template which is attached to spam mail messages
1272 which contain a non-text/plain part. See the "10_default_prefs.cf"
1273 configuration file in "/usr/share/spamassassin" for an example.
1274 Each "unsafe-report" line appends to the existing template, so use
1276 "clear_unsafe_report_template" to restart.
1277 Tags can be used in this template (see above for details).
1279 clear_unsafe_report_template
1281 Clear the unsafe_report template.
1282 mbox_format_from_regex
1284 Set a specific regular expression to be used for mbox file From
1285 separators.
1286 For example, this setting will allow sa-learn to process emails
1288 stored in a kmail 2 mbox:
1289 mbox_format_from_regex /^From \S+ ?[[:upper:]][[:lower:]]{2}(?:,
1291 \d\d [[:upper:]][[:lower:]]{2} \d{4} [0-2]\d:\d\d:\d\d [+-]\d{4}|
1292 [[:upper:]][[:lower:]]{2} [ 1-3]\d [ 0-2]\d:\d\d:\d\d \d{4})/
1293
1295 These settings differ from the ones above, in that they are considered
1296 'privileged'. Only users running "spamassassin" from their
1297 procmailrc's or forward files, or sysadmins editing a file in
1298 "/etc/mail/spamassassin", can use them. "spamd" users cannot use them
1299 in their "user_prefs" files, for security and efficiency reasons,
1300 unless "allow_user_rules" is enabled (and then, they may only add rules
1301 from below).
1302 allow_user_rules ( 0 | 1 ) (default: 0)
1304 This setting allows users to create rules (and only rules) in their
1305 "user_prefs" files for use with "spamd". It defaults to off,
1306 because this could be a severe security hole. It may be possible
1307 for users to gain root level access if "spamd" is run as root. It
1308 is NOT a good idea, unless you have some other way of ensuring that
1309 users' tests are safe. Don't use this unless you are certain you
1310 know what you are doing. Furthermore, this option causes
1311 spamassassin to recompile all the tests each time it processes a
1312 message for a user with a rule in his/her "user_prefs" file, which
1313 could have a significant effect on server load. It is not
1314 recommended.
1315 Note that it is not currently possible to use "allow_user_rules" to
1317 modify an existing system rule from a "user_prefs" file with
1318 "spamd".
1319 redirector_pattern /pattern/modifiers
1321 A regex pattern that matches both the redirector site portion, and
1322 the target site portion of a URI.
1323 Note: The target URI portion must be surrounded in parentheses and
1325 no other part of the pattern may create a backreference.
1326 Example:
1328 http://chkpt.zdnet.com/chkpt/whatever/spammer.domain/yo/dude
1329 redirector_pattern /^https?:\/\/(?:opt\.)?chkpt\.zdnet\.com\/chkpt\/\w+\/(.*)$/i
1331 header SYMBOLIC_TEST_NAME header op /pattern/modifiers [if-unset:
1333 STRING]
1334 Define a test. "SYMBOLIC_TEST_NAME" is a symbolic test name, such
1335 as 'FROM_ENDS_IN_NUMS'. "header" is the name of a mail header
1336 field, such as 'Subject', 'To', 'From', etc. Header field names
1337 are matched case-insensitively (conforming to RFC 5322 section
1338 1.2.2), except for all-capitals metaheader fields such as ALL,
1339 MESSAGEID, ALL-TRUSTED.
1340 Appending a modifier ":raw" to a header field name will inhibit
1342 decoding of quoted-printable or base-64 encoded strings, and will
1343 preserve all whitespace inside the header string. The ":raw" may
1344 also be applied to pseudo-headers e.g. "ALL:raw" will return a
1345 pristine (unmodified) header section.
1346 Appending a modifier ":addr" to a header field name will cause
1348 everything except the first email address to be removed from the
1349 header field. It is mainly applicable to header fields 'From',
1350 'Sender', 'To', 'Cc' along with their 'Resent-*' counterparts, and
1351 the 'Return-Path'.
1352 Appending a modifier ":name" to a header field name will cause
1354 everything except the first display name to be removed from the
1355 header field. It is mainly applicable to header fields containing a
1356 single mail address: 'From', 'Sender', along with their
1357 'Resent-From' and 'Resent-Sender' counterparts.
1358 It is syntactically permitted to append more than one modifier to a
1360 header field name, although currently most combinations achieve no
1361 additional effect, for example "From:addr:raw" or "From:raw:addr"
1362 is currently the same as "From:addr" .
1363 For example, appending ":addr" to a header name will result in
1365 example@foo in all of the following cases:
1366 example@foo
1368 example@foo (Foo Blah)
1369 example@foo, example@bar
1370 display: example@foo (Foo Blah), example@bar ;
1371 Foo Blah <example@foo>
1372 "Foo Blah" <example@foo>
1373 "'Foo Blah'" <example@foo>
1374 For example, appending ":name" to a header name will result in "Foo
1376 Blah" (without quotes) in all of the following cases:
1377 example@foo (Foo Blah)
1379 example@foo (Foo Blah), example@bar
1380 display: example@foo (Foo Blah), example@bar ;
1381 Foo Blah <example@foo>
1382 "Foo Blah" <example@foo>
1383 "'Foo Blah'" <example@foo>
1384 There are several special pseudo-headers that can be specified:
1386 "ALL" can be used to mean the text of all the message's headers.
1388 Note that all whitespace inside the headers, at line folds, is
1389 currently compressed into a single space (' ') character. To obtain
1390 a pristine (unmodified) header section, use "ALL:raw" - the :raw
1391 modifier is documented above.
1392 "ToCc" can be used to mean the contents of both the 'To' and 'Cc'
1393 headers.
1394 "EnvelopeFrom" is the address used in the 'MAIL FROM:' phase of the
1395 SMTP transaction that delivered this message, if this data has been
1396 made available by the SMTP server. See "envelope_sender_header"
1397 for more information on how to set this.
1398 "MESSAGEID" is a symbol meaning all Message-Id's found in the
1399 message; some mailing list software moves the real 'Message-Id' to
1400 'Resent-Message-Id' or to 'X-Message-Id', then uses its own one in
1401 the 'Message-Id' header. The value returned for this symbol is the
1402 text from all 3 headers, separated by newlines.
1403 "X-Spam-Relays-Untrusted", "X-Spam-Relays-Trusted",
1404 "X-Spam-Relays-Internal" and "X-Spam-Relays-External" represent a
1405 portable, pre-parsed representation of the message's network path,
1406 as recorded in the Received headers, divided into 'trusted' vs
1407 'untrusted' and 'internal' vs 'external' sets. See
1408 "http://wiki.apache.org/spamassassin/TrustedRelays" for more
1409 details.
1410 "op" is either "=~" (contains regular expression) or "!~" (does not
1412 contain regular expression), and "pattern" is a valid Perl regular
1413 expression, with "modifiers" as regexp modifiers in the usual
1414 style. Note that multi-line rules are not supported, even if you
1415 use "x" as a modifier. Also note that the "#" character must be
1416 escaped ("\#") or else it will be considered to be the start of a
1417 comment and not part of the regexp.
1418 If the "[if-unset: STRING]" tag is present, then "STRING" will be
1420 used if the header is not found in the mail message.
1421 Test names must not start with a number, and must contain only
1423 alphanumerics and underscores. It is suggested that lower-case
1424 characters not be used, and names have a length of no more than 22
1425 characters, as an informal convention. Dashes are not allowed.
1426 Note that test names which begin with '__' are reserved for meta-
1428 match sub-rules, and are not scored or listed in the 'tests hit'
1429 reports. Test names which begin with 'T_' are reserved for tests
1430 which are undergoing QA, and these are given a very low score.
1431 If you add or modify a test, please be sure to run a sanity check
1433 afterwards by running "spamassassin --lint". This will avoid
1434 confusing error messages, or other tests being skipped as a side-
1435 effect.
1436 header SYMBOLIC_TEST_NAME exists:header_field_name
1438 Define a header field existence test. "header_field_name" is the
1439 name of a header field to test for existence. Not to be confused
1440 with a test for a nonempty header field body, which can be
1441 implemented by a "header SYMBOLIC_TEST_NAME header =~ /\S/" rule as
1442 described above.
1443 header SYMBOLIC_TEST_NAME eval:name_of_eval_method([arguments])
1445 Define a header eval test. "name_of_eval_method" is the name of a
1446 method on the "Mail::SpamAssassin::EvalTests" object. "arguments"
1447 are optional arguments to the function call.
1448 header SYMBOLIC_TEST_NAME eval:check_rbl('set', 'zone' [, 'sub-test'])
1450 Check a DNSBL (a DNS blacklist or whitelist). This will retrieve
1451 Received: headers from the message, extract the IP addresses,
1452 select which ones are 'untrusted' based on the "trusted_networks"
1453 logic, and query that DNSBL zone. There's a few things to note:
1454 duplicated or private IPs
1456 Duplicated IPs are only queried once and reserved IPs are not
1457 queried. Private IPs are those listed in
1458 <http://www.iana.org/assignments/ipv4-address-space>,
1459 <http://duxcw.com/faq/network/privip.htm>,
1460 <http://duxcw.com/faq/network/autoip.htm>, or
1461 <http://tools.ietf.org/html/rfc5735> as private.
1462 the 'set' argument
1464 This is used as a 'zone ID'. If you want to look up a
1465 multiple-meaning zone like SORBS, you can then query the
1466 results from that zone using it; but all check_rbl_sub() calls
1467 must use that zone ID.
1468 Also, if more than one IP address gets a DNSBL hit for a
1470 particular rule, it does not affect the score because rules
1471 only trigger once per message.
1472 the 'zone' argument
1474 This is the root zone of the DNSBL.
1475 The domain name is considered to be a fully qualified domain
1477 name (i.e. not subject to DNS resolver's search or default
1478 domain options). No trailing period is needed, and will be
1479 removed if specified.
1480 the 'sub-test' argument
1482 This optional argument behaves the same as the sub-test
1483 argument in "check_rbl_sub()" below.
1484 selecting all IPs except for the originating one
1486 This is accomplished by placing '-notfirsthop' at the end of
1487 the set name. This is useful for querying against DNS lists
1488 which list dialup IP addresses; the first hop may be a dialup,
1489 but as long as there is at least one more hop, via their
1490 outgoing SMTP server, that's legitimate, and so should not gain
1491 points. If there is only one hop, that will be queried anyway,
1492 as it should be relaying via its outgoing SMTP server instead
1493 of sending directly to your MX (mail exchange).
1494 selecting IPs by whether they are trusted
1496 When checking a 'nice' DNSBL (a DNS whitelist), you cannot
1497 trust the IP addresses in Received headers that were not added
1498 by trusted relays. To test the first IP address that can be
1499 trusted, place '-firsttrusted' at the end of the set name.
1500 That should test the IP address of the relay that connected to
1501 the most remote trusted relay.
1502 Note that this requires that SpamAssassin know which relays are
1504 trusted. For simple cases, SpamAssassin can make a good
1505 estimate. For complex cases, you may get better results by
1506 setting "trusted_networks" manually.
1507 In addition, you can test all untrusted IP addresses by placing
1509 '-untrusted' at the end of the set name. Important note --
1510 this does NOT include the IP address from the most recent
1511 'untrusted line', as used in '-firsttrusted' above. That's
1512 because we're talking about the trustworthiness of the IP
1513 address data, not the source header line, here; and in the case
1514 of the most recent header (the 'firsttrusted'), that data can
1515 be trusted. See the Wiki page at
1516 "http://wiki.apache.org/spamassassin/TrustedRelays" for more
1517 information on this.
1518 Selecting just the last external IP
1520 By using '-lastexternal' at the end of the set name, you can
1521 select only the external host that connected to your internal
1522 network, or at least the last external host with a public IP.
1523 header SYMBOLIC_TEST_NAME eval:check_rbl_txt('set', 'zone')
1525 Same as check_rbl(), except querying using IN TXT instead of IN A
1526 records. If the zone supports it, it will result in a line of text
1527 describing why the IP is listed, typically a hyperlink to a
1528 database entry.
1529 header SYMBOLIC_TEST_NAME eval:check_rbl_sub('set', 'sub-test')
1531 Create a sub-test for 'set'. If you want to look up a multi-
1532 meaning zone like relays.osirusoft.com, you can then query the
1533 results from that zone using the zone ID from the original query.
1534 The sub-test may either be an IPv4 dotted address for RBLs that
1535 return multiple A records or a non-negative decimal number to
1536 specify a bitmask for RBLs that return a single A record containing
1537 a bitmask of results, a SenderBase test beginning with "sb:", or
1538 (if none of the preceding options seem to fit) a regular
1539 expression.
1540 Note: the set name must be exactly the same for as the main query
1542 rule, including selections like '-notfirsthop' appearing at the end
1543 of the set name.
1544 body SYMBOLIC_TEST_NAME /pattern/modifiers
1546 Define a body pattern test. "pattern" is a Perl regular
1547 expression. Note: as per the header tests, "#" must be escaped
1548 ("\#") or else it is considered the beginning of a comment.
1549 The 'body' in this case is the textual parts of the message body;
1551 any non-text MIME parts are stripped, and the message decoded from
1552 Quoted-Printable or Base-64-encoded format if necessary. The
1553 message Subject header is considered part of the body and becomes
1554 the first paragraph when running the rules. All HTML tags and line
1555 breaks will be removed before matching.
1556 body SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1558 Define a body eval test. See above.
1559 uri SYMBOLIC_TEST_NAME /pattern/modifiers
1561 Define a uri pattern test. "pattern" is a Perl regular expression.
1562 Note: as per the header tests, "#" must be escaped ("\#") or else
1563 it is considered the beginning of a comment.
1564 The 'uri' in this case is a list of all the URIs in the body of the
1566 email, and the test will be run on each and every one of those
1567 URIs, adjusting the score if a match is found. Use this test
1568 instead of one of the body tests when you need to match a URI, as
1569 it is more accurately bound to the start/end points of the URI, and
1570 will also be faster.
1571 rawbody SYMBOLIC_TEST_NAME /pattern/modifiers
1573 Define a raw-body pattern test. "pattern" is a Perl regular
1574 expression. Note: as per the header tests, "#" must be escaped
1575 ("\#") or else it is considered the beginning of a comment.
1576 The 'raw body' of a message is the raw data inside all textual
1578 parts. The text will be decoded from base64 or quoted-printable
1579 encoding, but HTML tags and line breaks will still be present.
1580 Multiline expressions will need to be used to match strings that
1581 are broken by line breaks. Note: the text is split into 1 kB - 2kB
1582 chunks so your expressions may unexpectedly stop matching where
1583 they should.
1584 rawbody SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1586 Define a raw-body eval test. See above.
1587 full SYMBOLIC_TEST_NAME /pattern/modifiers
1589 Define a full message pattern test. "pattern" is a Perl regular
1590 expression. Note: as per the header tests, "#" must be escaped
1591 ("\#") or else it is considered the beginning of a comment.
1592 The full message is the pristine message headers plus the pristine
1594 message body, including all MIME data such as images, other
1595 attachments, MIME boundaries, etc.
1596 full SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
1598 Define a full message eval test. See above.
1599 meta SYMBOLIC_TEST_NAME boolean expression
1601 Define a boolean expression test in terms of other tests that have
1602 been hit or not hit. For example:
1603 meta META1 TEST1 && !(TEST2 || TEST3)
1605 Note that English language operators ("and", "or") will be treated
1607 as rule names, and that there is no "XOR" operator.
1608 meta SYMBOLIC_TEST_NAME boolean arithmetic expression
1610 Can also define an arithmetic expression in terms of other tests,
1611 with an unhit test having the value "0" and a hit test having a
1612 nonzero value. The value of a hit meta test is that of its
1613 arithmetic expression. The value of a hit eval test is that
1614 returned by its method. The value of a hit header, body, rawbody,
1615 uri, or full test which has the "multiple" tflag is the number of
1616 times the test hit. The value of any other type of hit test is
1617 "1".
1618 For example:
1620 meta META2 (3 * TEST1 - 2 * TEST2) > 0
1622 Note that Perl builtins and functions, like "abs()", can't be used,
1624 and will be treated as rule names.
1625 If you want to define a meta-rule, but do not want its individual
1627 sub-rules to count towards the final score unless the entire meta-
1628 rule matches, give the sub-rules names that start with '__' (two
1629 underscores). SpamAssassin will ignore these for scoring.
1630 reuse SYMBOLIC_TEST_NAME [ OLD_SYMBOLIC_TEST_NAME_1 ... ]
1632 Defines the name of a test that should be "reused" during the
1633 scoring process. If a message has an X-Spam-Status header that
1634 shows a hit for this rule or any of the old rule names given, a hit
1635 will be added for this rule when mass-check --reuse is used.
1636 Examples:
1637 "reuse SPF_PASS"
1639 "reuse MY_NET_RULE_V2 MY_NET_RULE_V1"
1641 The actual logic for reuse tests is done by
1643 Mail::SpamAssassin::Plugin::Reuse.
1644 tflags SYMBOLIC_TEST_NAME flags
1646 Used to set flags on a test. Parameter is a space-separated list of
1647 flag names or flag name = value pairs. These flags are used in the
1648 score-determination back end system for details of the test's
1649 behaviour. Please see "bayes_auto_learn" for more information
1650 about tflag interaction with those systems. The following flags can
1651 be set:
1652 net The test is a network test, and will not be run in the mass
1654 checking system or if -L is used, therefore its score should
1655 not be modified.
1656 nice
1658 The test is intended to compensate for common false positives,
1659 and should be assigned a negative score.
1660 userconf
1662 The test requires user configuration before it can be used
1663 (like language-specific tests).
1664 learn
1666 The test requires training before it can be used.
1667 noautolearn
1669 The test will explicitly be ignored when calculating the score
1670 for learning systems.
1671 autolearn_force
1673 The test will be subject to less stringent autolearn
1674 thresholds.
1675 Normally, SpamAssassin will require 3 points from the header
1677 and 3 points from the body to be auto-learned as spam. This
1678 option keeps the threshold at 6 points total but changes it to
1679 have no regard to the source of the points.
1680 multiple
1682 The test will be evaluated multiple times, for use with meta
1683 rules. Only affects header, body, rawbody, uri, and full
1684 tests.
1685 maxhits=N
1687 If multiple is specified, limit the number of hits found to N.
1688 If the rule is used in a meta that counts the hits (e.g.
1689 __RULENAME > 5), this is a way to avoid wasted extra work (use
1690 "tflags multiple maxhits=6").
1691 For example:
1693 uri __KAM_COUNT_URIS /^./
1695 tflags __KAM_COUNT_URIS multiple maxhits=16
1696 describe __KAM_COUNT_URIS A multiple match used to count URIs in a message
1697 meta __KAM_HAS_0_URIS (__KAM_COUNT_URIS == 0)
1699 meta __KAM_HAS_1_URIS (__KAM_COUNT_URIS >= 1)
1700 meta __KAM_HAS_2_URIS (__KAM_COUNT_URIS >= 2)
1701 meta __KAM_HAS_3_URIS (__KAM_COUNT_URIS >= 3)
1702 meta __KAM_HAS_4_URIS (__KAM_COUNT_URIS >= 4)
1703 meta __KAM_HAS_5_URIS (__KAM_COUNT_URIS >= 5)
1704 meta __KAM_HAS_10_URIS (__KAM_COUNT_URIS >= 10)
1705 meta __KAM_HAS_15_URIS (__KAM_COUNT_URIS >= 15)
1706 ips_only
1708 This flag is specific to rules invoking an URIDNSBL plugin, it
1709 is documented there.
1710 domains_only
1712 This flag is specific to rules invoking an URIDNSBL plugin, it
1713 is documented there.
1714 ns This flag is specific to rules invoking an URIDNSBL plugin, it
1716 is documented there.
1717 a This flag is specific to rules invoking an URIDNSBL plugin, it
1719 is documented there.
1720 priority SYMBOLIC_TEST_NAME n
1722 Assign a specific priority to a test. All tests, except for DNS
1723 and Meta tests, are run in increasing priority value order
1724 (negative priority values are run before positive priority values).
1725 The default test priority is 0 (zero).
1726 The values <-99999999999999> and <-99999999999998> have a special
1728 meaning internally, and should not be used.
1729
1731 These settings differ from the ones above, in that they are considered
1732 'more privileged' -- even more than the ones in the PRIVILEGED SETTINGS
1733 section. No matter what "allow_user_rules" is set to, these can never
1734 be set from a user's "user_prefs" file when spamc/spamd is being used.
1735 However, all settings can be used by local programs run directly by the
1736 user.
1737 version_tag string
1739 This tag is appended to the SA version in the X-Spam-Status header.
1740 You should include it when modify your ruleset, especially if you
1741 plan to distribute it. A good choice for string is your last name
1742 or your initials followed by a number which you increase with each
1743 change.
1744 The version_tag will be lowercased, and any non-alphanumeric or
1746 period character will be replaced by an underscore.
1747 e.g.
1749 version_tag myrules1 # version=2.41-myrules1
1751 test SYMBOLIC_TEST_NAME (ok|fail) Some string to test against
1753 Define a regression testing string. You can have more than one
1754 regression test string per symbolic test name. Simply specify a
1755 string that you wish the test to match.
1756 These tests are only run as part of the test suite - they should
1758 not affect the general running of SpamAssassin.
1759 rbl_timeout t [t_min] [zone] (default: 15 3)
1761 All DNS queries are made at the beginning of a check and we try to
1762 read the results at the end. This value specifies the maximum
1763 period of time (in seconds) to wait for a DNS query. If most of
1764 the DNS queries have succeeded for a particular message, then
1765 SpamAssassin will not wait for the full period to avoid wasting
1766 time on unresponsive server(s), but will shrink the timeout
1767 according to a percentage of queries already completed. As the
1768 number of queries remaining approaches 0, the timeout value will
1769 gradually approach a t_min value, which is an optional second
1770 parameter and defaults to 0.2 * t. If t is smaller than t_min, the
1771 initial timeout is set to t_min. Here is a chart of queries
1772 remaining versus the timeout in seconds, for the default 15 second
1773 / 3 second timeout setting:
1774 queries left 100% 90% 80% 70% 60% 50% 40% 30% 20% 10% 0%
1776 timeout 15 14.9 14.5 13.9 13.1 12.0 10.7 9.1 7.3 5.3 3
1777 For example, if 20 queries are made at the beginning of a message
1779 check and 16 queries have returned (leaving 20%), the remaining 4
1780 queries should finish within 7.3 seconds since their query started
1781 or they will be timed out. Note that timed out queries are only
1782 aborted when there is nothing else left for SpamAssassin to do -
1783 long evaluation of other rules may grant queries additional time.
1784 If a parameter 'zone' is specified (it must end with a letter,
1786 which distinguishes it from other numeric parametrs), then the
1787 setting only applies to DNS queries against the specified DNS
1788 domain (host, domain or RBL (sub)zone). Matching is case-
1789 insensitive, the actual domain may be a subdomain of the specified
1790 zone.
1791 util_rb_tld tld1 tld2 ...
1793 This option allows the addition of new TLDs to the
1794 RegistrarBoundaries code. Updates to the list usually happen when
1795 new versions of SpamAssassin are released, but sometimes it's
1796 necessary to add in new TLDs faster than a release can occur. TLDs
1797 include things like com, net, org, etc.
1798 util_rb_2tld 2tld-1.tld 2tld-2.tld ...
1800 This option allows the addition of new 2nd-level TLDs (2TLD) to the
1801 RegistrarBoundaries code. Updates to the list usually happen when
1802 new versions of SpamAssassin are released, but sometimes it's
1803 necessary to add in new 2TLDs faster than a release can occur.
1804 2TLDs include things like co.uk, fed.us, etc.
1805 util_rb_3tld 3tld1.some.tld 3tld2.other.tld ...
1807 This option allows the addition of new 3rd-level TLDs (3TLD) to the
1808 RegistrarBoundaries code. Updates to the list usually happen when
1809 new versions of SpamAssassin are released, but sometimes it's
1810 necessary to add in new 3TLDs faster than a release can occur.
1811 3TLDs include things like demon.co.uk, plc.co.im, etc.
1812 bayes_path /path/filename (default: ~/.spamassassin/bayes)
1814 This is the directory and filename for Bayes databases. Several
1815 databases will be created, with this as the base directory and
1816 filename, with "_toks", "_seen", etc. appended to the base. The
1817 default setting results in files called
1818 "~/.spamassassin/bayes_seen", "~/.spamassassin/bayes_toks", etc.
1819 By default, each user has their own in their "~/.spamassassin"
1821 directory with mode 0700/0600. For system-wide SpamAssassin use,
1822 you may want to reduce disk space usage by sharing this across all
1823 users. However, Bayes appears to be more effective with individual
1824 user databases.
1825 bayes_file_mode (default: 0700)
1827 The file mode bits used for the Bayesian filtering database files.
1828 Make sure you specify this using the 'x' mode bits set, as it may
1830 also be used to create directories. However, if a file is created,
1831 the resulting file will not have any execute bits set (the umask is
1832 set to 111). The argument is a string of octal digits, it is
1833 converted to a numeric value internally.
1834 bayes_store_module Name::Of::BayesStore::Module
1836 If this option is set, the module given will be used as an
1837 alternate to the default bayes storage mechanism. It must conform
1838 to the published storage specification (see
1839 Mail::SpamAssassin::BayesStore). For example, set this to
1840 Mail::SpamAssassin::BayesStore::SQL to use the generic SQL storage
1841 module.
1842 bayes_sql_dsn DBI::databasetype:databasename:hostname:port
1844 Used for BayesStore::SQL storage implementation.
1845 This option give the connect string used to connect to the SQL
1847 based Bayes storage.
1848 bayes_sql_username
1850 Used by BayesStore::SQL storage implementation.
1851 This option gives the username used by the above DSN.
1853 bayes_sql_password
1855 Used by BayesStore::SQL storage implementation.
1856 This option gives the password used by the above DSN.
1858 bayes_sql_username_authorized ( 0 | 1 ) (default: 0)
1860 Whether to call the services_authorized_for_username plugin hook in
1861 BayesSQL. If the hook does not determine that the user is allowed
1862 to use bayes or is invalid then then database will not be
1863 initialized.
1864 NOTE: By default the user is considered invalid until a plugin
1866 returns a true value. If you enable this, but do not have a proper
1867 plugin loaded, all users will turn up as invalid.
1868 The username passed into the plugin can be affected by the
1870 bayes_sql_override_username config option.
1871 user_scores_dsn DBI:databasetype:databasename:hostname:port
1873 If you load user scores from an SQL database, this will set the DSN
1874 used to connect. Example: "DBI:mysql:spamassassin:localhost"
1875 If you load user scores from an LDAP directory, this will set the
1877 DSN used to connect. You have to write the DSN as an LDAP URL, the
1878 components being the host and port to connect to, the base DN for
1879 the search, the scope of the search (base, one or sub), the single
1880 attribute being the multivalued attribute used to hold the
1881 configuration data (space separated pairs of key and value, just as
1882 in a file) and finally the filter being the expression used to
1883 filter out the wanted username. Note that the filter expression is
1884 being used in a sprintf statement with the username as the only
1885 parameter, thus is can hold a single __USERNAME__ expression. This
1886 will be replaced with the username.
1887 Example:
1889 "ldap://localhost:389/dc=koehntopp,dc=de?saconfig?uid=__USERNAME__"
1890 user_scores_sql_username username
1892 The authorized username to connect to the above DSN.
1893 user_scores_sql_password password
1895 The password for the database username, for the above DSN.
1896 user_scores_sql_custom_query query
1898 This option gives you the ability to create a custom SQL query to
1899 retrieve user scores and preferences. In order to work correctly
1900 your query should return two values, the preference name and value,
1901 in that order. In addition, there are several "variables" that you
1902 can use as part of your query, these variables will be substituted
1903 for the current values right before the query is run. The current
1904 allowed variables are:
1905 _TABLE_
1907 The name of the table where user scores and preferences are
1908 stored. Currently hardcoded to userpref, to change this value
1909 you need to create a new custom query with the new table name.
1910 _USERNAME_
1912 The current user's username.
1913 _MAILBOX_
1915 The portion before the @ as derived from the current user's
1916 username.
1917 _DOMAIN_
1919 The portion after the @ as derived from the current user's
1920 username, this value may be null.
1921 The query must be one continuous line in order to parse correctly.
1923 Here are several example queries, please note that these are broken
1925 up for easy reading, in your config it should be one continuous
1926 line.
1927 Current default query:
1929 "SELECT preference, value FROM _TABLE_ WHERE username =
1930 _USERNAME_ OR username = '@GLOBAL' ORDER BY username ASC"
1931 Use global and then domain level defaults:
1933 "SELECT preference, value FROM _TABLE_ WHERE username =
1934 _USERNAME_ OR username = '@GLOBAL' OR username = '@~'||_DOMAIN_
1935 ORDER BY username ASC"
1936 Maybe global prefs should override user prefs:
1938 "SELECT preference, value FROM _TABLE_ WHERE username =
1939 _USERNAME_ OR username = '@GLOBAL' ORDER BY username DESC"
1940 user_scores_ldap_username
1942 This is the Bind DN used to connect to the LDAP server. It
1943 defaults to the empty string (""), allowing anonymous binding to
1944 work.
1945 Example: "cn=master,dc=koehntopp,dc=de"
1947 user_scores_ldap_password
1949 This is the password used to connect to the LDAP server. It
1950 defaults to the empty string ("").
1951 user_scores_fallback_to_global (default: 1)
1953 Fall back to global scores and settings if userprefs can't be
1954 loaded from SQL or LDAP, instead of passing the message through
1955 unprocessed.
1956 loadplugin PluginModuleName [/path/module.pm]
1958 Load a SpamAssassin plugin module. The "PluginModuleName" is the
1959 perl module name, used to create the plugin object itself.
1960 "/path/to/module.pm" is the file to load, containing the module's
1962 perl code; if it's specified as a relative path, it's considered to
1963 be relative to the current configuration file. If it is omitted,
1964 the module will be loaded using perl's search path (the @INC
1965 array).
1966 See "Mail::SpamAssassin::Plugin" for more details on writing
1968 plugins.
1969 tryplugin PluginModuleName [/path/module.pm]
1971 Same as "loadplugin", but silently ignored if the .pm file cannot
1972 be found in the filesystem.
1973 ignore_always_matching_regexps (Default: 0)
1975 Ignore any rule which contains a regexp which always matches.
1976 Currently only catches regexps which contain '||', or which begin
1977 or end with a '|'. Also ignore rules with "some" combinatorial
1978 explosions.
1979
1981 include filename
1982 Include configuration lines from "filename". Relative paths are
1983 considered relative to the current configuration file or user
1984 preferences file.
1985 if (boolean perl expression)
1987 Used to support conditional interpretation of the configuration
1988 file. Lines between this and a corresponding "else" or "endif" line
1989 will be ignored unless the expression evaluates as true (in the
1990 perl sense; that is, defined and non-0 and non-empty string).
1991 The conditional accepts a limited subset of perl for security --
1993 just enough to perform basic arithmetic comparisons. The following
1994 input is accepted:
1995 numbers, whitespace, arithmetic operations and grouping
1997 Namely these characters and ranges:
1998 ( ) - + * / _ . , < = > ! ~ 0-9 whitespace
2000 version
2002 This will be replaced with the version number of the currently-
2003 running SpamAssassin engine. Note: The version used is in the
2004 internal SpamAssassin version format which is "x.yyyzzz", where
2005 x is major version, y is minor version, and z is maintenance
2006 version. So 3.0.0 is 3.000000, and 3.4.80 is 3.004080.
2007 plugin(Name::Of::Plugin)
2009 This is a function call that returns 1 if the plugin named
2010 "Name::Of::Plugin" is loaded, or "undef" otherwise.
2011 has(Name::Of::Package::function_name)
2013 This is a function call that returns 1 if the perl package
2014 named "Name::Of::Package" includes a function called
2015 "function_name", or "undef" otherwise. Note that packages can
2016 be SpamAssassin plugins or built-in classes, there's no
2017 difference in this respect. Internally this invokes
2018 UNIVERSAL::can.
2019 can(Name::Of::Package::function_name)
2021 This is a function call that returns 1 if the perl package
2022 named "Name::Of::Package" includes a function called
2023 "function_name" and that function returns a true value when
2024 called with no arguments, otherwise "undef" is returned.
2025 Is similar to "has", except that it also calls the named
2027 function, testing its return value (unlike the perl function
2028 UNIVERSAL::can). This makes it possible for a 'feature'
2029 function to determine its result value at run time.
2030 If the end of a configuration file is reached while still inside a
2032 "if" scope, a warning will be issued, but parsing will restart on
2033 the next file.
2034 For example:
2036 if (version > 3.000000)
2038 header MY_FOO ...
2039 endif
2040 loadplugin MyPlugin plugintest.pm
2042 if plugin (MyPlugin)
2044 header MY_PLUGIN_FOO eval:check_for_foo()
2045 score MY_PLUGIN_FOO 0.1
2046 endif
2047 ifplugin PluginModuleName
2049 An alias for "if plugin(PluginModuleName)".
2050 else
2052 Used to support conditional interpretation of the configuration
2053 file. Lines between this and a corresponding "endif" line, will be
2054 ignored unless the conditional expression evaluates as false (in
2055 the perl sense; that is, not defined and not 0 and non-empty
2056 string).
2057 require_version n.nnnnnn
2059 Indicates that the entire file, from this line on, requires a
2060 certain version of SpamAssassin to run. If a different (older or
2061 newer) version of SpamAssassin tries to read the configuration from
2062 this file, it will output a warning instead, and ignore it.
2063 Note: The version used is in the internal SpamAssassin version
2065 format which is "x.yyyzzz", where x is major version, y is minor
2066 version, and z is maintenance version. So 3.0.0 is 3.000000, and
2067 3.4.80 is 3.004080.
2068
2070 The following "tags" can be used as placeholders in certain options.
2071 They will be replaced by the corresponding value when they are used.
2072 Some tags can take an argument (in parentheses). The argument is
2074 optional, and the default is shown below.
2075 _YESNO_ "Yes" for spam, "No" for nonspam (=ham)
2077 _YESNO(spam_str,ham_str)_ returns the first argument ("Yes" if missing)
2078 for spam, and the second argument ("No" if missing) for ham
2079 _YESNOCAPS_ "YES" for spam, "NO" for nonspam (=ham)
2080 _YESNOCAPS(spam_str,ham_str)_ same as _YESNO(...)_, but uppercased
2081 _SCORE(PAD)_ message score, if PAD is included and is either spaces or
2082 zeroes, then pad scores with that many spaces or zeroes
2083 (default, none) ie: _SCORE(0)_ makes 2.4 become 02.4,
2084 _SCORE(00)_ is 002.4. 12.3 would be 12.3 and 012.3
2085 respectively.
2086 _REQD_ message threshold
2087 _VERSION_ version (eg. 3.0.0 or 3.1.0-r26142-foo1)
2088 _SUBVERSION_ sub-version/code revision date (eg. 2004-01-10)
2089 _RULESVERSION_ comma-separated list of rules versions, retrieved from
2090 an '# UPDATE version' comment in rules files; if there is
2091 more than one set of rules (update channels) the order
2092 is unspecified (currently sorted by names of files);
2093 _HOSTNAME_ hostname of the machine the mail was processed on
2094 _REMOTEHOSTNAME_ hostname of the machine the mail was sent from, only
2095 available with spamd
2096 _REMOTEHOSTADDR_ ip address of the machine the mail was sent from, only
2097 available with spamd
2098 _BAYES_ bayes score
2099 _TOKENSUMMARY_ number of new, neutral, spammy, and hammy tokens found
2100 _BAYESTC_ number of new tokens found
2101 _BAYESTCLEARNED_ number of seen tokens found
2102 _BAYESTCSPAMMY_ number of spammy tokens found
2103 _BAYESTCHAMMY_ number of hammy tokens found
2104 _HAMMYTOKENS(N)_ the N most significant hammy tokens (default, 5)
2105 _SPAMMYTOKENS(N)_ the N most significant spammy tokens (default, 5)
2106 _DATE_ rfc-2822 date of scan
2107 _STARS(*)_ one "*" (use any character) for each full score point
2108 (note: limited to 50 'stars')
2109 _RELAYSTRUSTED_ relays used and deemed to be trusted (see the
2110 'X-Spam-Relays-Trusted' pseudo-header)
2111 _RELAYSUNTRUSTED_ relays used that can not be trusted (see the
2112 'X-Spam-Relays-Untrusted' pseudo-header)
2113 _RELAYSINTERNAL_ relays used and deemed to be internal (see the
2114 'X-Spam-Relays-Internal' pseudo-header)
2115 _RELAYSEXTERNAL_ relays used and deemed to be external (see the
2116 'X-Spam-Relays-External' pseudo-header)
2117 _LASTEXTERNALIP_ IP address of client in the external-to-internal
2118 SMTP handover
2119 _LASTEXTERNALRDNS_ reverse-DNS of client in the external-to-internal
2120 SMTP handover
2121 _LASTEXTERNALHELO_ HELO string used by client in the external-to-internal
2122 SMTP handover
2123 _AUTOLEARN_ autolearn status ("ham", "no", "spam", "disabled",
2124 "failed", "unavailable")
2125 _AUTOLEARNSCORE_ portion of message score used by autolearn
2126 _TESTS(,)_ tests hit separated by "," (or other separator)
2127 _TESTSSCORES(,)_ as above, except with scores appended (eg. AWL=-3.0,...)
2128 _SUBTESTS(,)_ subtests (start with "__") hit separated by ","
2129 (or other separator)
2130 _DCCB_ DCC's "Brand"
2131 _DCCR_ DCC's results
2132 _PYZOR_ Pyzor results
2133 _RBL_ full results for positive RBL queries in DNS URI format
2134 _LANGUAGES_ possible languages of mail
2135 _PREVIEW_ content preview
2136 _REPORT_ terse report of tests hit (for header reports)
2137 _SUMMARY_ summary of tests hit for standard report (for body reports)
2138 _CONTACTADDRESS_ contents of the 'report_contact' setting
2139 _HEADER(NAME)_ includes the value of a message header. value is the same
2140 as is found for header rules (see elsewhere in this doc)
2141 _TIMING_ timing breakdown report
2142 _ADDEDHEADERHAM_ resulting header fields as requested by add_header for spam
2143 _ADDEDHEADERSPAM_ resulting header fields as requested by add_header for ham
2144 _ADDEDHEADER_ same as ADDEDHEADERHAM for ham or ADDEDHEADERSPAM for spam
2145 If a tag reference uses the name of a tag which is not in this list or
2147 defined by a loaded plugin, the reference will be left intact and not
2148 replaced by any value.
2149 The "HAMMYTOKENS" and "SPAMMYTOKENS" tags have an optional second
2151 argument which specifies a format. See the HAMMYTOKENS/SPAMMYTOKENS
2152 TAG FORMAT section, below, for details.
2153 HAMMYTOKENS/SPAMMYTOKENS TAG FORMAT
2155 The "HAMMYTOKENS" and "SPAMMYTOKENS" tags have an optional second
2156 argument which specifies a format: "_SPAMMYTOKENS(N,FMT)_",
2157 "_HAMMYTOKENS(N,FMT)_" The following formats are available:
2158 short
2160 Only the tokens themselves are listed. For example, preference
2161 file entry:
2162 "add_header all Spammy _SPAMMYTOKENS(2,short)_"
2164 Results in message header:
2166 "X-Spam-Spammy: remove.php, UD:jpg"
2168 Indicating that the top two spammy tokens found are "remove.php"
2170 and "UD:jpg". (The token itself follows the last colon, the text
2171 before the colon indicates something about the token. "UD" means
2172 the token looks like it might be part of a domain name.)
2173 compact
2175 The token probability, an abbreviated declassification distance
2176 (see example), and the token are listed. For example, preference
2177 file entry:
2178 "add_header all Spammy _SPAMMYTOKENS(2,compact)_"
2180 Results in message header:
2182 "0.989-6--remove.php, 0.988-+--UD:jpg"
2184 Indicating that the probabilities of the top two tokens are 0.989
2186 and 0.988, respectively. The first token has a declassification
2187 distance of 6, meaning that if the token had appeared in at least 6
2188 more ham messages it would not be considered spammy. The "+" for
2189 the second token indicates a declassification distance greater than
2190 9.
2191 long
2193 Probability, declassification distance, number of times seen in a
2194 ham message, number of times seen in a spam message, age and the
2195 token are listed.
2196 For example, preference file entry:
2198 "add_header all Spammy _SPAMMYTOKENS(2,long)_"
2200 Results in message header:
2202 "X-Spam-Spammy: 0.989-6--0h-4s--4d--remove.php,
2204 0.988-33--2h-25s--1d--UD:jpg"
2205 In addition to the information provided by the compact option, the
2207 long option shows that the first token appeared in zero ham
2208 messages and four spam messages, and that it was last seen four
2209 days ago. The second token appeared in two ham messages, 25 spam
2210 messages and was last seen one day ago. (Unlike the "compact"
2211 option, the long option shows declassification distances that are
2212 greater than 9.)
2213
2215 A line starting with the text "lang xx" will only be interpreted if the
2216 user is in that locale, allowing test descriptions and templates to be
2217 set for that language.
2218 The locales string should specify either both the language and country,
2220 e.g. "lang pt_BR", or just the language, e.g. "lang de".
2221
2223 "Mail::SpamAssassin" "spamassassin" "spamd"
2224perl v5.16.3 2018-10-15 Mail::SpamAssassin::Conf(3)