You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by km...@apache.org on 2014/02/11 18:26:52 UTC
svn commit: r1567225 [4/15] - in /spamassassin/site/full/3.4.x: ./ doc/
Added: spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.html?rev=1567225&view=auto
==============================================================================
--- spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.html (added)
+++ spamassassin/site/full/3.4.x/doc/Mail_SpamAssassin_Conf.html Tue Feb 11 17:26:49 2014
@@ -0,0 +1,2910 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Mail::SpamAssassin::Conf - SpamAssassin configuration file</title>
+<link rev="made" href="mailto:root@twm2005-dev.thoughtworthy.com" />
+</head>
+
+<body style="background-color: white">
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#file_format">FILE FORMAT</a></li>
+ <li><a href="#user_preferences">USER PREFERENCES</a></li>
+ <ul>
+
+ <li><a href="#scoring_options">SCORING OPTIONS</a></li>
+ <li><a href="#whitelist_and_blacklist_options">WHITELIST AND BLACKLIST OPTIONS</a></li>
+ <li><a href="#basic_message_tagging_options">BASIC MESSAGE TAGGING OPTIONS</a></li>
+ <li><a href="#language_options">LANGUAGE OPTIONS</a></li>
+ <li><a href="#network_test_options">NETWORK TEST OPTIONS</a></li>
+ <li><a href="#learning_options">LEARNING OPTIONS</a></li>
+ <li><a href="#miscellaneous_options">MISCELLANEOUS OPTIONS</a></li>
+ </ul>
+
+ <li><a href="#rule_definitions_and_privileged_settings">RULE DEFINITIONS AND PRIVILEGED SETTINGS</a></li>
+ <li><a href="#administrator_settings">ADMINISTRATOR SETTINGS</a></li>
+ <li><a href="#preprocessing_options">PREPROCESSING OPTIONS</a></li>
+ <li><a href="#template_tags">TEMPLATE TAGS</a></li>
+ <ul>
+
+ <li><a href="#hammytokens_spammytokens_tag_format">HAMMYTOKENS/SPAMMYTOKENS TAG FORMAT</a></li>
+ </ul>
+
+ <li><a href="#locali_sz_ation">LOCALI[SZ]ATION</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>Mail::SpamAssassin::Conf - SpamAssassin configuration file</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<pre>
+ # a comment</pre>
+<pre>
+ rewrite_header Subject *****SPAM*****</pre>
+<pre>
+ full PARA_A_2_C_OF_1618 /Paragraph .a.{0,10}2.{0,10}C. of S. 1618/i
+ describe PARA_A_2_C_OF_1618 Claims compliance with senate bill 1618</pre>
+<pre>
+ header FROM_HAS_MIXED_NUMS From =~ /\d+[a-z]+\d+\S*@/i
+ describe FROM_HAS_MIXED_NUMS From: contains numbers mixed in with letters</pre>
+<pre>
+ score A_HREF_TO_REMOVE 2.0</pre>
+<pre>
+ lang es describe FROM_FORGED_HOTMAIL Forzado From: simula ser de hotmail.com</pre>
+<pre>
+ lang pt_BR report O programa detetor de Spam ZOE [...]</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>SpamAssassin is configured using traditional UNIX-style configuration files,
+loaded from the <code>/usr/share/spamassassin</code> and <code>/etc/mail/spamassassin</code>
+directories.</p>
+<p>The following web page lists the most important configuration settings
+used to configure SpamAssassin; novices are encouraged to read it first:</p>
+<pre>
+ <a href="http://wiki.apache.org/spamassassin/ImportantInitialConfigItems">http://wiki.apache.org/spamassassin/ImportantInitialConfigItems</a></pre>
+<p>
+</p>
+<hr />
+<h1><a name="file_format">FILE FORMAT</a></h1>
+<p>The <code>#</code> character starts a comment, which continues until end of line.
+<strong>NOTE:</strong> if the <code>#</code> character is to be used as part of a rule or
+configuration option, it must be escaped with a backslash. i.e.: <code>\#</code></p>
+<p>Whitespace in the files is not significant, but please note that starting a
+line with whitespace is deprecated, as we reserve its use for multi-line rule
+definitions, at some point in the future.</p>
+<p>Currently, each rule or configuration setting must fit on one-line; multi-line
+settings are not supported yet.</p>
+<p>File and directory paths can use <code>~</code> to refer to the user's home
+directory, but no other shell-style path extensions such as globing or
+<code>~user/</code> are supported.</p>
+<p>Where appropriate below, default values are listed in parentheses.</p>
+<p>
+</p>
+<hr />
+<h1><a name="user_preferences">USER PREFERENCES</a></h1>
+<p>The following options can be used in both site-wide (<code>local.cf</code>) and
+user-specific (<code>user_prefs</code>) configuration files to customize how
+SpamAssassin handles incoming email messages.</p>
+<p>
+</p>
+<h2><a name="scoring_options">SCORING OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_nn">required_score n.nn (default: 5)</a></strong><br />
+</dt>
+<dd>
+Set the score required before a mail is considered spam. <code>n.nn</code> can
+be an integer or a real number. 5.0 is the default setting, and is
+quite aggressive; it would be suitable for a single-user setup, but if
+you're an ISP installing SpamAssassin, you should probably set the
+default to be more conservative, like 8.0 or 10.0. It is not
+recommended to automatically delete or discard messages marked as
+spam, as your users <strong>will</strong> complain, but if you choose to do so, only
+delete messages with an exceptionally high score such as 15.0 or
+higher. This option was previously known as <code>required_hits</code> and that
+name is still accepted, but is deprecated.
+</dd>
+<p></p>
+<dt><strong><a name="item_score_symbolic_test_name_n_2enn__5b_n_2enn_n_2enn_">score SYMBOLIC_TEST_NAME n.nn [ n.nn n.nn n.nn ]</a></strong><br />
+</dt>
+<dd>
+Assign scores (the number of points for a hit) to a given test.
+Scores can be positive or negative real numbers or integers.
+<a href="#item_symbolic_test_name"><code>SYMBOLIC_TEST_NAME</code></a> is the symbolic name used by SpamAssassin for
+that test; for example, 'FROM_ENDS_IN_NUMS'.
+</dd>
+<dd>
+<p>If only one valid score is listed, then that score is always used
+for a test.</p>
+</dd>
+<dd>
+<p>If four valid scores are listed, then the score that is used depends
+on how SpamAssassin is being used. The first score is used when
+both Bayes and network tests are disabled (score set 0). The second
+score is used when Bayes is disabled, but network tests are enabled
+(score set 1). The third score is used when Bayes is enabled and
+network tests are disabled (score set 2). The fourth score is used
+when Bayes is enabled and network tests are enabled (score set 3).</p>
+</dd>
+<dd>
+<p>Setting a rule's score to 0 will disable that rule from running.</p>
+</dd>
+<dd>
+<p>If any of the score values are surrounded by parenthesis '()', then
+all of the scores in the line are considered to be relative to the
+already set score. ie: '(3)' means increase the score for this
+rule by 3 points in all score sets. '(3) (0) (3) (0)' means increase
+the score for this rule by 3 in score sets 0 and 2 only.</p>
+</dd>
+<dd>
+<p>If no score is given for a test by the end of the configuration,
+a default score is assigned: a score of 1.0 is used for all tests,
+except those whose names begin with 'T_' (this is used to indicate a
+rule in testing) which receive 0.01.</p>
+</dd>
+<dd>
+<p>Note that test names which begin with '__' are indirect rules used
+to compose meta-match rules and can also act as prerequisites to
+other rules. They are not scored or listed in the 'tests hit'
+reports, but assigning a score of 0 to an indirect rule will disable
+it from running.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="whitelist_and_blacklist_options">WHITELIST AND BLACKLIST OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_whitelist_from_user_40example_2ecom">whitelist_from <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to whitelist sender addresses which send mail that is often tagged
+(incorrectly) as spam.
+</dd>
+<dd>
+<p>Use of this setting is not recommended, since it blindly trusts the message,
+which is routinely and easily forged by spammers and phish senders. The
+recommended solution is to instead use <code>whitelist_auth</code> or other authenticated
+whitelisting methods, or <code>whitelist_from_rcvd</code>.</p>
+</dd>
+<dd>
+<p>Whitelist and blacklist addresses are now file-glob-style patterns, so
+<code>friend@somewhere.com</code>, <code>*@isp.com</code>, or <code>*.domain.net</code> will all work.
+Specifically, <code>*</code> and <code>?</code> are allowed, but all other metacharacters
+are not. Regular expressions are not used for security reasons.
+Matching is case-insensitive.</p>
+</dd>
+<dd>
+<p>Multiple addresses per line, separated by spaces, is OK. Multiple
+<code>whitelist_from</code> lines are also OK.</p>
+</dd>
+<dd>
+<p>The headers checked for whitelist addresses are as follows: if <code>Resent-From</code>
+is set, use that; otherwise check all addresses taken from the following
+set of headers:</p>
+</dd>
+<dd>
+<pre>
+ Envelope-Sender
+ Resent-Sender
+ X-Envelope-From
+ From</pre>
+</dd>
+<dd>
+<p>In addition, the ``envelope sender'' data, taken from the SMTP envelope data
+where this is available, is looked up. See <code>envelope_sender_header</code>.</p>
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ whitelist_from joe@example.com fred@example.com
+ whitelist_from *@example.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_unwhitelist_from_user_40example_2ecom">unwhitelist_from <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to override a default whitelist_from entry, so for example a distribution
+whitelist_from can be overridden in a local.cf file, or an individual user can
+override a whitelist_from entry in their own <code>user_prefs</code> file.
+The specified email address has to match exactly (although case-insensitively)
+the address previously used in a whitelist_from line, which implies that a
+wildcard only matches literally the same wildcard (not 'any' address).
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ unwhitelist_from joe@example.com fred@example.com
+ unwhitelist_from *@example.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_whitelist_from_rcvd_addr_40lists_2esourceforge_2en">whitelist_from_rcvd <a href="mailto:addr@lists.sourceforge.net">addr@lists.sourceforge.net</a> sourceforge.net</a></strong><br />
+</dt>
+<dd>
+Works similarly to whitelist_from, except that in addition to matching
+a sender address, a relay's rDNS name or its IP address must match too
+for the whitelisting rule to fire. The first parameter is a sender's e-mail
+address to whitelist, and the second is a string to match the relay's rDNS,
+or its IP address. Matching is case-insensitive.
+</dd>
+<dd>
+<p>This second parameter is matched against the TCP-info information field as
+provided in a FROM clause of a trace information (i.e. the Received header
+field, see RFC 5321). Only the Received header fields inserted by trusted
+hosts are considered. This parameter can either be a full hostname, or the
+domain component of that hostname, or an IP address in square brackets.
+The reverse DNS lookup is done by a MTA, not by SpamAssassin.</p>
+</dd>
+<dd>
+<p>In case of an IPv4 address in brackets, it may be truncated on classful
+boundaries to cover whole subnets, e.g. <code>[10.1.2.3]</code>, <code>[10.1.2]</code>,
+<code>[10.1]</code>, <code>[10]</code>. CIDR notation is currently not supported, nor is
+IPv6. The matching on IP address is mainly provided to cover rare cases
+where whitelisting of a sending MTA is desired which does not have a
+correct reverse DNS configured.</p>
+</dd>
+<dd>
+<p>In other words, if the host that connected to your MX had an IP address
+192.0.2.123 that mapped to 'sendinghost.example.org', you should specify
+<code>sendinghost.example.org</code>, or <code>example.org</code>, or <code>[192.0.2.123]</code> or
+<code>[192.0.2]</code> here.</p>
+</dd>
+<dd>
+<p>Note that this requires that <code>internal_networks</code> be correct. For simple
+cases, it will be, but for a complex network you may get better results
+by setting that parameter.</p>
+</dd>
+<dd>
+<p>It also requires that your mail exchangers be configured to perform DNS
+reverse lookups on the connecting host's IP address, and to record the
+result in the generated Received header field according to RFC 5321.</p>
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ whitelist_from_rcvd joe@example.com example.com
+ whitelist_from_rcvd *@axkit.org sergeant.org
+ whitelist_from_rcvd *@axkit.org [192.0.2.123]</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_def_whitelist_from_rcvd_addr_40lists_2esourceforge">def_whitelist_from_rcvd <a href="mailto:addr@lists.sourceforge.net">addr@lists.sourceforge.net</a> sourceforge.net</a></strong><br />
+</dt>
+<dd>
+Same as <code>whitelist_from_rcvd</code>, but used for the default whitelist entries
+in the SpamAssassin distribution. The whitelist score is lower, because
+these are often targets for spammer spoofing.
+</dd>
+<p></p>
+<dt><strong><a name="item_whitelist_allows_relays_user_40example_2ecom">whitelist_allows_relays <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Specify addresses which are in <code>whitelist_from_rcvd</code> that sometimes
+send through a mail relay other than the listed ones. By default mail
+with a From address that is in <code>whitelist_from_rcvd</code> that does not match
+the relay will trigger a forgery rule. Including the address in
+<code>whitelist_allows_relay</code> prevents that.
+</dd>
+<dd>
+<p>Whitelist and blacklist addresses are now file-glob-style patterns, so
+<code>friend@somewhere.com</code>, <code>*@isp.com</code>, or <code>*.domain.net</code> will all work.
+Specifically, <code>*</code> and <code>?</code> are allowed, but all other metacharacters
+are not. Regular expressions are not used for security reasons.
+Matching is case-insensitive.</p>
+</dd>
+<dd>
+<p>Multiple addresses per line, separated by spaces, is OK. Multiple
+<code>whitelist_allows_relays</code> lines are also OK.</p>
+</dd>
+<dd>
+<p>The specified email address does not have to match exactly the address
+previously used in a whitelist_from_rcvd line as it is compared to the
+address in the header.</p>
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ whitelist_allows_relays joe@example.com fred@example.com
+ whitelist_allows_relays *@example.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_unwhitelist_from_rcvd_user_40example_2ecom">unwhitelist_from_rcvd <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to override a default whitelist_from_rcvd entry, so for example a
+distribution whitelist_from_rcvd can be overridden in a local.cf file,
+or an individual user can override a whitelist_from_rcvd entry in
+their own <code>user_prefs</code> file.
+</dd>
+<dd>
+<p>The specified email address has to match exactly the address previously
+used in a whitelist_from_rcvd line.</p>
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ unwhitelist_from_rcvd joe@example.com fred@example.com
+ unwhitelist_from_rcvd *@axkit.org</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_blacklist_from_user_40example_2ecom">blacklist_from <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to specify addresses which send mail that is often tagged (incorrectly) as
+non-spam, but which the user doesn't want. Same format as <code>whitelist_from</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_unblacklist_from_user_40example_2ecom">unblacklist_from <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to override a default blacklist_from entry, so for example a
+distribution blacklist_from can be overridden in a local.cf file, or
+an individual user can override a blacklist_from entry in their own
+<code>user_prefs</code> file. The specified email address has to match exactly
+the address previously used in a blacklist_from line.
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ unblacklist_from joe@example.com fred@example.com
+ unblacklist_from *@spammer.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_whitelist_to_user_40example_2ecom">whitelist_to <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+If the given address appears as a recipient in the message headers
+(Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
+be whitelisted. Useful if you're deploying SpamAssassin system-wide,
+and don't want some users to have their mail filtered. Same format
+as <code>whitelist_from</code>.
+</dd>
+<dd>
+<p>There are three levels of To-whitelisting, <code>whitelist_to</code>, <code>more_spam_to</code>
+and <code>all_spam_to</code>. Users in the first level may still get some spammish
+mails blocked, but users in <code>all_spam_to</code> should never get mail blocked.</p>
+</dd>
+<dd>
+<p>The headers checked for whitelist addresses are as follows: if <code>Resent-To</code> or
+<code>Resent-Cc</code> are set, use those; otherwise check all addresses taken from the
+following set of headers:</p>
+</dd>
+<dd>
+<pre>
+ To
+ Cc
+ Apparently-To
+ Delivered-To
+ Envelope-Recipients
+ Apparently-Resent-To
+ X-Envelope-To
+ Envelope-To
+ X-Delivered-To
+ X-Original-To
+ X-Rcpt-To
+ X-Real-To</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_more_spam_to_user_40example_2ecom">more_spam_to <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+See above.
+</dd>
+<p></p>
+<dt><strong><a name="item_all_spam_to_user_40example_2ecom">all_spam_to <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+See above.
+</dd>
+<p></p>
+<dt><strong><a name="item_blacklist_to_user_40example_2ecom">blacklist_to <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+If the given address appears as a recipient in the message headers
+(Resent-To, To, Cc, obvious envelope recipient, etc.) the mail will
+be blacklisted. Same format as <code>blacklist_from</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_whitelist_auth_user_40example_2ecom">whitelist_auth <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to specify addresses which send mail that is often tagged (incorrectly) as
+spam. This is different from <code>whitelist_from</code> and <code>whitelist_from_rcvd</code> in
+that it first verifies that the message was sent by an authorized sender for
+the address, before whitelisting.
+</dd>
+<dd>
+<p>Authorization is performed using one of the installed sender-authorization
+schemes: SPF (using <code>Mail::SpamAssassin::Plugin::SPF</code>), or DKIM (using
+<code>Mail::SpamAssassin::Plugin::DKIM</code>). Note that those plugins must be active,
+and working, for this to operate.</p>
+</dd>
+<dd>
+<p>Using <code>whitelist_auth</code> is roughly equivalent to specifying duplicate
+<code>whitelist_from_spf</code>, <code>whitelist_from_dk</code>, and <code>whitelist_from_dkim</code> lines
+for each of the addresses specified.</p>
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ whitelist_auth joe@example.com fred@example.com
+ whitelist_auth *@example.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_def_whitelist_auth_user_40example_2ecom">def_whitelist_auth <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Same as <code>whitelist_auth</code>, but used for the default whitelist entries
+in the SpamAssassin distribution. The whitelist score is lower, because
+these are often targets for spammer spoofing.
+</dd>
+<p></p>
+<dt><strong><a name="item_unwhitelist_auth_user_40example_2ecom">unwhitelist_auth <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Used to override a <code>whitelist_auth</code> entry. The specified email address has to
+match exactly the address previously used in a <code>whitelist_auth</code> line.
+</dd>
+<dd>
+<p>e.g.</p>
+</dd>
+<dd>
+<pre>
+ unwhitelist_auth joe@example.com fred@example.com
+ unwhitelist_auth *@example.com</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_enlist_uri_host">enlist_uri_host (listname) host ...</a></strong><br />
+</dt>
+<dd>
+Adds one or more host names or domain names to a named list of URI domains.
+The named list can then be consulted through a <code>check_uri_host_listed()</code>
+eval rule implemented by the WLBLEval plugin, which takes the list name as
+an argument. Parenthesis around a list name are literal - a required syntax.
+</dd>
+<dd>
+<p>Host names may optionally be prefixed by an exclamantion mark '!', which
+produces false as a result if this entry matches. This makes it easier
+to exclude some subdomains when their superdomain is listed, for example:</p>
+</dd>
+<dd>
+<pre>
+ enlist_uri_host (MYLIST) !sub1.example.com !sub2.example.com example.com</pre>
+</dd>
+<dd>
+<p>No wildcards are supported, but subdomains do match implicitly. Lists
+are independent. Search for each named list starts by looking up the
+full hostname first, then leading fields are progressively stripped off
+(e.g.: sub.example.com, example.com, com) until a match is found or we run
+out of fields. The first matching entry (the most specific) determines if a
+lookup yielded a true (no '!' prefix) or a false (with a '!' prefix) result.</p>
+</dd>
+<dd>
+<p>If an URL found in a message contains an IP address in place of a host name,
+the given list must specify the exact same IP address (instead of a host name)
+in order to match.</p>
+</dd>
+<dd>
+<p>Use the delist_uri_host directive to neutralize previous enlist_uri_host
+settings.</p>
+</dd>
+<dd>
+<p>Enlisting to lists named 'BLACK' and 'WHITE' have their shorthand directives
+blacklist_uri_host and whitelist_uri_host and corresponding default rules,
+but the names 'BLACK' and 'WHITE' are otherwise not special or reserved.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_delist_uri_host__5b__28listname_29__5d_host__2e_2e">delist_uri_host [ (listname) ] host ...</a></strong><br />
+</dt>
+<dd>
+Removes one or more specified host names from a named list of URI domains.
+Removing an unlisted name is ignored (is not an error). Listname is optional,
+if specified then just the named list is affected, otherwise hosts are
+removed from all URI host lists created so far. Parenthesis around a list
+name are a required syntax.
+</dd>
+<dd>
+<p>Note that directives in configuration files are processed in sequence,
+the delist_uri_host only applies to previously listed entries and has
+no effect on enlisted entries in yet-to-be-processed directives.</p>
+</dd>
+<dd>
+<p>For convenience (similarity to the enlist_uri_host directive) hostnames
+may be prefixed by a an exclamation mark, which is stripped off from each
+name and has no meaning here.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_blacklist_uri_host_host_2dor_2ddomain__2e_2e_2e">blacklist_uri_host host-or-domain ...</a></strong><br />
+</dt>
+<dd>
+Is a shorthand for a directive: enlist_uri_host (BLACK) host ...
+</dd>
+<dd>
+<p>Please see directives enlist_uri_host and delist_uri_host for details.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_whitelist_uri_host_host_2dor_2ddomain__2e_2e_2e">whitelist_uri_host host-or-domain ...</a></strong><br />
+</dt>
+<dd>
+Is a shorthand for a directive: enlist_uri_host (BLACK) host ...
+</dd>
+<dd>
+<p>Please see directives enlist_uri_host and delist_uri_host for details.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="basic_message_tagging_options">BASIC MESSAGE TAGGING OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_rewrite_header__7b_subject__7c_from__7c_to__7d_str">rewrite_header { subject | from | to } STRING</a></strong><br />
+</dt>
+<dd>
+By default, suspected spam messages will not have the <code>Subject</code>,
+<code>From</code> or <code>To</code> lines tagged to indicate spam. By setting this option,
+the header will be tagged with <code>STRING</code> to indicate that a message is
+spam. For the From or To headers, this will take the form of an RFC 2822
+comment following the address in parantheses. For the Subject header,
+this will be prepended to the original subject. Note that you should
+only use the _REQD_ and _SCORE_ tags when rewriting the Subject header
+if <a href="#item_report_safe"><code>report_safe</code></a> is 0. Otherwise, you may not be able to remove
+the SpamAssassin markup via the normal methods. More information
+about tags is explained below in the <strong>TEMPLATE TAGS</strong> section.
+</dd>
+<dd>
+<p>Parentheses are not permitted in STRING if rewriting the From or To headers.
+(They will be converted to square brackets.)</p>
+</dd>
+<dd>
+<p>If <code>rewrite_header subject</code> is used, but the message being rewritten
+does not already contain a <code>Subject</code> header, one will be created.</p>
+</dd>
+<dd>
+<p>A null value for <code>STRING</code> will remove any existing rewrite for the specified
+header.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_add_header__7b_spam__7c_ham__7c_all__7d_header_nam">add_header { spam | ham | all } header_name string</a></strong><br />
+</dt>
+<dd>
+Customized headers can be added to the specified type of messages (spam,
+ham, or ``all'' to add to either). All headers begin with <code>X-Spam-</code>
+(so a <code>header_name</code> Foo will generate a header called X-Spam-Foo).
+header_name is restricted to the character set [A-Za-z0-9_-].
+</dd>
+<dd>
+<p>The order of <code>add_header</code> configuration options is preserved, inserted
+headers will follow this order of declarations. When combining <code>add_header</code>
+with <a href="#item_clear_headers"><code>clear_headers</code></a> and <code>remove_header</code>, keep in mind that <code>add_header</code>
+appends a new header to the current list, after first removing any existing
+header fields of the same name. Note also that <code>add_header</code>, <a href="#item_clear_headers"><code>clear_headers</code></a>
+and <code>remove_header</code> may appear in multiple .cf files, which are interpreted
+in alphabetic order.</p>
+</dd>
+<dd>
+<p><code>string</code> can contain tags as explained below in the <strong>TEMPLATE TAGS</strong> section.
+You can also use <code>\n</code> and <code>\t</code> in the header to add newlines and tabulators
+as desired. A backslash has to be written as \\, any other escaped chars will
+be silently removed.</p>
+</dd>
+<dd>
+<p>All headers will be folded if fold_headers is set to <code>1</code>. Note: Manually
+adding newlines via <code>\n</code> disables any further automatic wrapping (ie:
+long header lines are possible). The lines will still be properly folded
+(marked as continuing) though.</p>
+</dd>
+<dd>
+<p>You can customize existing headers with <strong>add_header</strong> (only the specified
+subset of messages will be changed).</p>
+</dd>
+<dd>
+<p>See also <a href="#item_clear_headers"><code>clear_headers</code></a> and <code>remove_header</code> for removing headers.</p>
+</dd>
+<dd>
+<p>Here are some examples (these are the defaults, note that Checker-Version can
+not be changed or removed):</p>
+</dd>
+<dd>
+<pre>
+ add_header spam Flag _YESNOCAPS_
+ add_header all Status _YESNO_, score=_SCORE_ required=_REQD_ tests=_TESTS_ autolearn=_AUTOLEARN_ version=_VERSION_
+ add_header all Level _STARS(*)_
+ add_header all Checker-Version SpamAssassin _VERSION_ (_SUBVERSION_) on _HOSTNAME_</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_remove_header__7b_spam__7c_ham__7c_all__7d_header_">remove_header { spam | ham | all } header_name</a></strong><br />
+</dt>
+<dd>
+Headers can be removed from the specified type of messages (spam, ham,
+or ``all'' to remove from either). All headers begin with <code>X-Spam-</code>
+(so <code>header_name</code> will be appended to <code>X-Spam-</code>).
+</dd>
+<dd>
+<p>See also <a href="#item_clear_headers"><code>clear_headers</code></a> for removing all the headers at once.</p>
+</dd>
+<dd>
+<p>Note that <strong>X-Spam-Checker-Version</strong> is not removable because the version
+information is needed by mail administrators and developers to debug
+problems. Without at least one header, it might not even be possible to
+determine that SpamAssassin is running.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_headers">clear_headers</a></strong><br />
+</dt>
+<dd>
+Clear the list of headers to be added to messages. You may use this
+before any <strong>add_header</strong> options to prevent the default headers from being
+added to the message.
+</dd>
+<dd>
+<p><code>add_header</code>, <a href="#item_clear_headers"><code>clear_headers</code></a> and <code>remove_header</code> may appear in multiple
+.cf files, which are interpreted in alphabetic order, so <a href="#item_clear_headers"><code>clear_headers</code></a>
+in a later file will remove all added headers from previously interpreted
+configuration files, which may or may not be desired.</p>
+</dd>
+<dd>
+<p>Note that <strong>X-Spam-Checker-Version</strong> is not removable because the version
+information is needed by mail administrators and developers to debug
+problems. Without at least one header, it might not even be possible to
+determine that SpamAssassin is running.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_report_safe">report_safe ( 0 | 1 | 2 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+if this option is set to 1, if an incoming message is tagged as spam,
+instead of modifying the original message, SpamAssassin will create a
+new report message and attach the original message as a message/rfc822
+MIME part (ensuring the original message is completely preserved, not
+easily opened, and easier to recover).
+</dd>
+<dd>
+<p>If this option is set to 2, then original messages will be attached with
+a content type of text/plain instead of message/rfc822. This setting
+may be required for safety reasons on certain broken mail clients that
+automatically load attachments without any action by the user. This
+setting may also make it somewhat more difficult to extract or view the
+original message.</p>
+</dd>
+<dd>
+<p>If this option is set to 0, incoming spam is only modified by adding
+some <code>X-Spam-</code> headers and no changes will be made to the body. In
+addition, a header named <strong>X-Spam-Report</strong> will be added to spam. You
+can use the <strong>remove_header</strong> option to remove that header after setting
+<strong>report_safe</strong> to 0.</p>
+</dd>
+<dd>
+<p>See <strong>report_safe_copy_headers</strong> if you want to copy headers from
+the original mail into tagged messages.</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="language_options">LANGUAGE OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_ok_locales_xx__5b_yy_zz__2e_2e_2e__5d__28default_3">ok_locales xx [ yy zz ... ] (default: all)</a></strong><br />
+</dt>
+<dd>
+This option is used to specify which locales are considered OK for
+incoming mail. Mail using the <strong>character sets</strong> that are allowed by
+this option will not be marked as possibly being spam in a foreign
+language.
+</dd>
+<dd>
+<p>If you receive lots of spam in foreign languages, and never get any non-spam in
+these languages, this may help. Note that all ISO-8859-* character sets, and
+Windows code page character sets, are always permitted by default.</p>
+</dd>
+<dd>
+<p>Set this to <code>all</code> to allow all character sets. This is the default.</p>
+</dd>
+<dd>
+<p>The rules <code>CHARSET_FARAWAY</code>, <code>CHARSET_FARAWAY_BODY</code>, and
+<code>CHARSET_FARAWAY_HEADERS</code> are triggered based on how this is set.</p>
+</dd>
+<dd>
+<p>Examples:</p>
+</dd>
+<dd>
+<pre>
+ ok_locales all (allow all locales)
+ ok_locales en (only allow English)
+ ok_locales en ja zh (allow English, Japanese, and Chinese)</pre>
+</dd>
+<dd>
+<p>Note: if there are multiple ok_locales lines, only the last one is used.</p>
+</dd>
+<dd>
+<p>Select the locales to allow from the list below:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_en__2d_western_character_sets_in_general">en - Western character sets in general</a></strong><br />
+</dt>
+<dt><strong><a name="item_ja__2d_japanese_character_sets">ja - Japanese character sets</a></strong><br />
+</dt>
+<dt><strong><a name="item_ko__2d_korean_character_sets">ko - Korean character sets</a></strong><br />
+</dt>
+<dt><strong><a name="item_ru__2d_cyrillic_character_sets">ru - Cyrillic character sets</a></strong><br />
+</dt>
+<dt><strong><a name="item_th__2d_thai_character_sets">th - Thai character sets</a></strong><br />
+</dt>
+<dt><strong><a name="item_chinese">zh - Chinese (both simplified and traditional) character sets</a></strong><br />
+</dt>
+</dl>
+<dt><strong><a name="item_normalize_charset">normalize_charset ( 0 | 1) (default: 0)</a></strong><br />
+</dt>
+<dd>
+Whether to detect character sets and normalize message content to
+Unicode. Requires the Encode::Detect module, HTML::Parser version
+3.46 or later, and Perl 5.8.5 or later.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="network_test_options">NETWORK TEST OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_trusted_networks_ipaddress_5b_2fmasklen_5d__2e_2e_">trusted_networks IPaddress[/masklen] ... (default: none)</a></strong><br />
+</dt>
+<dd>
+What networks or hosts are 'trusted' in your setup. <strong>Trusted</strong> in this case
+means that relay hosts on these networks are considered to not be potentially
+operated by spammers, open relays, or open proxies. A trusted host could
+conceivably relay spam, but will not originate it, and will not forge header
+data. DNS blacklist checks will never query for hosts on these networks.
+</dd>
+<dd>
+<p>See <code>http://wiki.apache.org/spamassassin/TrustPath</code> for more information.</p>
+</dd>
+<dd>
+<p>MXes for your <code>domain(s)</code> and internal relays should <strong>also</strong> be specified using
+the <code>internal_networks</code> setting. When there are 'trusted' hosts that
+are not MXes or internal relays for your <code>domain(s)</code> they should <strong>only</strong> be
+specified in <code>trusted_networks</code>.</p>
+</dd>
+<dd>
+<p>The <code>IPaddress</code> can be an IPv4 address (in a dot-quad form), or an IPv6
+address optionally enclosed in square brackets. Scoped link-local IPv6
+addresses are syntactically recognized but the interface scope is currently
+ignored (e.g. [fe80::1234%eth0] ) and should be avoided.</p>
+</dd>
+<dd>
+<p>If a <code>/masklen</code> is specified, it is considered a CIDR-style 'netmask' length,
+specified in bits. If it is not specified, but less than 4 octets of an IPv4
+address are specified with a trailing dot, an implied netmask length covers
+all addresses in remaining octets (i.e. implied masklen is /8 or /16 or /24).
+If masklen is not specified, and there is not trailing dot, then just a single
+IP address specified is used, as if the masklen were <code>/32</code> with an IPv4
+address, or <code>/128</code> in case of an IPv6 address.</p>
+</dd>
+<dd>
+<p>If a network or host address is prefaced by a <code>!</code> the matching network or
+host will be excluded from the list even if a less specific (shorter netmask
+length) subnet is later specified in the list. This allows a subset of
+a wider network to be exempt. In case of specifying overlapping subnets,
+specify more specific subnets first (tighter matching, i.e. with a longer
+netmask length), followed by less specific (shorter netmask length) subnets
+to get predictable results regarless of the search algorithm used - when
+Net::Patricia module is installed the search finds the tightest matching
+entry in the list, while a sequential search as used in absence of the
+module Net::Patricia will find the first matching entry in the list.</p>
+</dd>
+<dd>
+<p>Note: 127.0.0.0/8 and ::1 are always included in trusted_networks, regardless
+of your config.</p>
+</dd>
+<dd>
+<p>Examples:</p>
+</dd>
+<dd>
+<pre>
+ trusted_networks 192.168.0.0/16 # all in 192.168.*.*
+ trusted_networks 192.168. # all in 192.168.*.*
+ trusted_networks 212.17.35.15 # just that host
+ trusted_networks !10.0.1.5 10.0.1/24 # all in 10.0.1.* but not 10.0.1.5
+ trusted_networks 2001:db8:1::1 !2001:db8:1::/64 2001:db8::/32
+ # 2001:db8::/32 and 2001:db8:1::1/128, except the rest of 2001:db8:1::/64</pre>
+</dd>
+<dd>
+<p>This operates additively, so a <code>trusted_networks</code> line after another one
+will append new entries to the list of trusted networks. To clear out the
+existing entries, use <a href="#item_clear_trusted_networks"><code>clear_trusted_networks</code></a>.</p>
+</dd>
+<dd>
+<p>If <code>trusted_networks</code> is not set and <code>internal_networks</code> is, the value
+of <code>internal_networks</code> will be used for this parameter.</p>
+</dd>
+<dd>
+<p>If neither <code>trusted_networks</code> or <code>internal_networks</code> is set, a basic
+inference algorithm is applied. This works as follows:</p>
+</dd>
+<ul>
+<li></li>
+If the 'from' host has an IP address in a private (RFC 1918) network range,
+then it's trusted
+<p></p>
+<li></li>
+If there are authentication tokens in the received header, and
+the previous host was trusted, then this host is also trusted
+<p></p>
+<li></li>
+Otherwise this host, and all further hosts, are consider untrusted.
+<p></p></ul>
+<dt><strong><a name="item_clear_trusted_networks">clear_trusted_networks</a></strong><br />
+</dt>
+<dd>
+Empty the list of trusted networks.
+</dd>
+<p></p>
+<dt><strong><a name="item_internal_networks_ipaddress_5b_2fmasklen_5d__2e_2e">internal_networks IPaddress[/masklen] ... (default: none)</a></strong><br />
+</dt>
+<dd>
+What networks or hosts are 'internal' in your setup. <strong>Internal</strong> means
+that relay hosts on these networks are considered to be MXes for your
+domain(s), or internal relays. This uses the same syntax as
+<code>trusted_networks</code>, above - see there for details.
+</dd>
+<dd>
+<p>This value is used when checking 'dial-up' or dynamic IP address
+blocklists, in order to detect direct-to-MX spamming.</p>
+</dd>
+<dd>
+<p>Trusted relays that accept mail directly from dial-up connections
+(i.e. are also performing a role of mail submission agents - MSA)
+should not be listed in <code>internal_networks</code>. List them only in
+<code>trusted_networks</code>.</p>
+</dd>
+<dd>
+<p>If <code>trusted_networks</code> is set and <code>internal_networks</code> is not, the value
+of <code>trusted_networks</code> will be used for this parameter.</p>
+</dd>
+<dd>
+<p>If neither <code>trusted_networks</code> nor <code>internal_networks</code> is set, no addresses
+will be considered local; in other words, any relays past the machine where
+SpamAssassin is running will be considered external.</p>
+</dd>
+<dd>
+<p>Every entry in <code>internal_networks</code> must appear in <code>trusted_networks</code>; in
+other words, <code>internal_networks</code> is always a subset of the trusted set.</p>
+</dd>
+<dd>
+<p>Note: 127/8 and ::1 are always included in internal_networks, regardless of
+your config.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_internal_networks">clear_internal_networks</a></strong><br />
+</dt>
+<dd>
+Empty the list of internal networks.
+</dd>
+<p></p>
+<dt><strong><a name="item_msa_networks_ipaddress_5b_2fmasklen_5d__2e_2e_2e__">msa_networks IPaddress[/masklen] ... (default: none)</a></strong><br />
+</dt>
+<dd>
+The networks or hosts which are acting as MSAs in your setup (but not also
+as MX relays). This uses the same syntax as <code>trusted_networks</code>, above - see
+there for details.
+</dd>
+<dd>
+<p><strong>MSA</strong> means that the relay hosts on these networks accept mail from your
+own users and authenticates them appropriately. These relays will never
+accept mail from hosts that aren't authenticated in some way. Examples of
+authentication include, IP lists, SMTP AUTH, POP-before-SMTP, etc.</p>
+</dd>
+<dd>
+<p>All relays found in the message headers after the MSA relay will take
+on the same trusted and internal classifications as the MSA relay itself,
+as defined by your <em>trusted_networks</em> and <em>internal_networks</em> configuration.</p>
+</dd>
+<dd>
+<p>For example, if the MSA relay is trusted and internal so will all of the
+relays that precede it.</p>
+</dd>
+<dd>
+<p>When using msa_networks to identify an MSA it is recommended that you treat
+that MSA as both trusted and internal. When an MSA is not included in
+msa_networks you should treat the MSA as trusted but not internal, however
+if the MSA is also acting as an MX or intermediate relay you must always
+treat it as both trusted and internal and ensure that the MSA includes
+visible auth tokens in its Received header to identify submission clients.</p>
+</dd>
+<dd>
+<p><strong>Warning:</strong> Never include an MSA that also acts as an MX (or is also an
+intermediate relay for an MX) or otherwise accepts mail from
+non-authenticated users in msa_networks. Doing so will result in unknown
+external relays being trusted.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_msa_networks">clear_msa_networks</a></strong><br />
+</dt>
+<dd>
+Empty the list of msa networks.
+</dd>
+<p></p>
+<dt><strong><a name="item_originating_ip_headers_header__2e_2e_2e__28default">originating_ip_headers header ... (default: X-Yahoo-Post-IP X-Originating-IP X-Apparently-From X-SenderIP)</a></strong><br />
+</dt>
+<dd>
+A list of header field names from which an originating IP address can
+be obtained. For example, webmail servers may record a client IP address
+in X-Originating-IP.
+</dd>
+<dd>
+<p>These IP addresses are virtually appended into the Received: chain, so they
+are used in RBL checks where appropriate.</p>
+</dd>
+<dd>
+<p>Currently the IP addresses are not added into X-Spam-Relays-* header fields,
+but they may be in the future.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_originating_ip_headers">clear_originating_ip_headers</a></strong><br />
+</dt>
+<dd>
+Empty the list of 'originating IP address' header field names.
+</dd>
+<p></p>
+<dt><strong><a name="item_always_trust_envelope_sender">always_trust_envelope_sender ( 0 | 1 ) (default: 0)</a></strong><br />
+</dt>
+<dd>
+Trust the envelope sender even if the message has been passed through one or
+more trusted relays. See also <code>envelope_sender_header</code>.
+</dd>
+<p></p>
+<dt><strong><a name="item_skip_rbl_checks">skip_rbl_checks ( 0 | 1 ) (default: 0)</a></strong><br />
+</dt>
+<dd>
+Turning on the skip_rbl_checks setting will disable the DNSEval plugin,
+which implements Real-time Block List (or: Blackhole List) (RBL) lookups.
+</dd>
+<dd>
+<p>By default, SpamAssassin will run RBL checks. Individual blocklists may
+be disabled selectively by setting a score of a corresponding rule to 0.</p>
+</dd>
+<dd>
+<p>See also a related configuration parameter skip_uribl_checks,
+which controls the URIDNSBL plugin (documented in the URIDNSBL man page).</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dns_available__7b_yes__7c_no__7c_test_5b_3a_domain">dns_available { yes | no | test[: domain1 domain2...] } (default: yes)</a></strong><br />
+</dt>
+<dd>
+Tells SpamAssassin whether DNS resolving is available or not. A value <em>yes</em>
+indicates DNS resolving is available, a value <em>no</em> indicates DNS resolving
+is not available - both of these values apply unconditionally and skip initial
+DNS tests, which can be slow or unreliable.
+</dd>
+<dd>
+<p>When the option value is a <em>test</em> (with or without arguments), SpamAssassin
+will query some domain names on the internet during initialization, attempting
+to determine if DNS resolving is working or not. A space-separated list
+of domain names may be specified explicitly, or left to a built-in default
+of a dozen or so domain names. From an explicit or a default list a subset
+of three domain names is picked randomly for checking. The test queries for
+NS records of these domain: if at least one query returns a success then
+SpamAssassin considers DNS resolving as available, otherwise not.</p>
+</dd>
+<dd>
+<p>The problem is that the test can introduce some startup delay if a network
+connection is down, and in some cases it can wrongly guess that DNS is
+unavailable because a test connection failed, what causes disabling several
+DNS-dependent tests.</p>
+</dd>
+<dd>
+<p>Please note, the DNS test queries for NS records, so specify domain names,
+not host names.</p>
+</dd>
+<dd>
+<p>Since version 3.4.0 of SpamAssassin a default setting for option
+<em>dns_available</em> is <em>yes</em>. A default in older versions was <em>test</em>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_port">dns_server ip-addr-port (default: entries provided by Net::DNS)</a></strong><br />
+</dt>
+<dd>
+Specifies an IP address of a DNS server, and optionally its port number.
+The <em>dns_server</em> directive may be specified multiple times, each entry
+adding to a list of available resolving name servers. The <em>ip-addr-port</em>
+argument can either be an IPv4 or IPv6 address, optionally enclosed in
+brackets, and optionally followed by a colon and a port number. In absence
+of a port number a standard port number 53 is assumed. When an IPv6 address
+is specified along with a port number, the address <strong>must</strong> be enclosed in
+brackets to avoid parsing ambiguity regarding a colon separator,
+</dd>
+<dd>
+<p>Examples :
+ dns_server 127.0.0.1
+ dns_server 127.0.0.1:53
+ dns_server [127.0.0.1]:53
+ dns_server [::1]:53</p>
+</dd>
+<dd>
+<p>In absence of <em>dns_server</em> directives, the list of name servers is provided
+by Net::DNS module, which typically obtains the list from /etc/resolv.conf,
+but this may be platform dependent. Please consult the Net::DNS::Resolver
+documentation for details.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_dns_servers">clear_dns_servers</a></strong><br />
+</dt>
+<dd>
+Empty the list of explicitly configured DNS servers through a <em>dns_server</em>
+directive, falling back to Net::DNS -supplied defaults.
+</dd>
+<p></p>
+<dt><strong><a name="item_dns_local_ports_permit_ranges_2e_2e_2e">dns_local_ports_permit ranges...</a></strong><br />
+</dt>
+<dd>
+Add the specified ports or ports ranges to the set of allowed port numbers
+that can be used as local port numbers when sending DNS queries to a resolver.
+</dd>
+<dd>
+<p>The argument is a whitespace-separated or a comma-separated list of
+single port numbers n, or port number pairs (i.e. m-n) delimited by a '-',
+representing a range. Allowed port numbers are between 1 and 65535.</p>
+</dd>
+<dd>
+<p>Directives <em>dns_local_ports_permit</em> and <em>dns_local_ports_avoid</em> are processed
+in order in which they appear in configuration files. Each directive adds
+(or subtracts) its subsets of ports to a current set of available ports.
+Whatever is left in the set by the end of configuration processing
+is made available to a DNS resolving client code.</p>
+</dd>
+<dd>
+<p>If the resulting set of port numbers is empty (see also the directive
+<em>dns_local_ports_none</em>), then SpamAssassin does not apply its ports
+randomization logic, but instead leaves the operating system to choose
+a suitable free local port number.</p>
+</dd>
+<dd>
+<p>The initial set consists of all port numbers in the range 1024-65535.
+Note that system config files already modify the set and remove all the
+IANA registered port numbers and some other ranges, so there is rarely
+a need to adjust the ranges by site-specific directives.</p>
+</dd>
+<dd>
+<p>See also directives <em>dns_local_ports_permit</em> and <em>dns_local_ports_none</em>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dns_local_ports_avoid_ranges_2e_2e_2e">dns_local_ports_avoid ranges...</a></strong><br />
+</dt>
+<dd>
+Remove specified ports or ports ranges from the set of allowed port numbers
+that can be used as local port numbers when sending DNS queries to a resolver.
+</dd>
+<dd>
+<p>Please see directive <em>dns_local_ports_permit</em> for details.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dns_local_ports_none">dns_local_ports_none</a></strong><br />
+</dt>
+<dd>
+Is a fast shorthand for:
+</dd>
+<dd>
+<pre>
+ dns_local_ports_avoid 1-65535</pre>
+</dd>
+<dd>
+<p>leaving the set of available DNS query local port numbers empty. In all
+respects (apart from speed) it is equivalent to the shown directive, and can
+be freely mixed with <em>dns_local_ports_permit</em> and <em>dns_local_ports_avoid</em>.</p>
+</dd>
+<dd>
+<p>If the resulting set of port numbers is empty, then SpamAssassin does not
+apply its ports randomization logic, but instead leaves the operating system
+to choose a suitable free local port number.</p>
+</dd>
+<dd>
+<p>See also directives <em>dns_local_ports_permit</em> and <em>dns_local_ports_avoid</em>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_n">dns_test_interval n (default: 600 seconds)</a></strong><br />
+</dt>
+<dd>
+If dns_available is set to <em>test</em>, the dns_test_interval time in number
+of seconds will tell SpamAssassin how often to retest for working DNS.
+A numeric value is optionally suffixed by a time unit (s, m, h, d, w,
+indicating seconds (default), minutes, hours, days, weeks).
+</dd>
+<p></p>
+<dt><strong><a name="item_opts">dns_options opts (default: norotate, nodns0x20, edns=4096)</a></strong><br />
+</dt>
+<dd>
+Provides a (whitespace or comma -separated) list of options applying
+to DNS resolving. Available options are: <em>rotate</em>, <em>dns0x20</em> and
+<em>edns</em> (or <em>edns0</em>). Option name may be negated by prepending a <em>no</em>
+(e.g. <em>norotate</em>, <em>NoEDNS</em>) to counteract a previously enabled option.
+Option names are not case-sensitive. The <em>dns_options</em> directive may
+appear in configuration files multiple times, the last setting prevails.
+</dd>
+<dd>
+<p>Option <em>edns</em> (or <em>edsn0</em>) may take a value which specifies a requestor's
+acceptable UDP payload size according to EDNS0 specifications (RFC 6891,
+ex RFC 2671) e.g. <em>edns=4096</em>. When EDNS0 is off (<em>noedns</em> or <em>edns=512</em>)
+a traditional implied UDP payload size is 512 bytes, which is also a minimum
+allowed value for this option. When the option is specified but a value
+is not provided, a conservative default of 1220 bytes is implied. It is
+recommended to keep <em>edns</em> enabled when using a local recursive DNS server
+which supports EDNS0 (like most modern DNS servers do), a suitable setting
+in this case is <em>edns=4096</em>, which is also a default. Allowing UDP payload
+size larger than 512 bytes can avoid truncation of resource records in large
+DNS responses (like in TXT records of some SPF and DKIM responses, or when
+an unreasonable number of A records is published by some domain). The option
+should be disabled when a recursive DNS server is only reachable through
+non- RFC 6891 compliant middleboxes (such as some old-fashioned firewall)
+which bans DNS UDP payload sizes larger than 512 bytes. A suitable value
+when a non-local recursive DNS server is used and a middlebox <strong>does</strong> allow
+EDNS0 but blocks fragmented IP packets is perhaps 1220 bytes, allowing a
+DNS UDP packet to fit within a single IP packet in most cases (a slightly
+less conservative range would be 1280-1410 bytes).</p>
+</dd>
+<dd>
+<p>Option <em>rotate</em> causes SpamAssassin to choose a DNS server at random
+from all servers listed in <code>/etc/resolv.conf</code> every <em>dns_test_interval</em>
+seconds, effectively spreading the load over all currently available DNS
+servers when there are many spamd workers.</p>
+</dd>
+<dd>
+<p>Option <em>dns0x20</em> enables randomization of letters in a DNS query label
+according to draft-vixie-dnsext-dns0x20, decreasing a chance of collisions
+of responses (by chance or by a malicious intent) by increasing spread
+as provided by a 16-bit query ID and up to 16 bits of a port number,
+with additional bits as encoded by flipping case (upper/lower) of letters
+in a query. The number of additional random bits corresponds to the number
+of letters in a query label. Should work reliably with all mainstream
+DNS servers - do not turn on if you see frequent info messages
+``dns: no callback for id:'' in the log, or if RBL or URIDNS lookups
+do not work for no apparent reason.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_dns_query_restriction">dns_query_restriction (allow|deny) domain1 domain2 ...</a></strong><br />
+</dt>
+<dd>
+Option allows disabling of rules which would result in a DNS query to one of
+the listed domains. The first argument must be a literal <code>allow</code> or <code>deny</code>,
+remaining arguments are domains names.
+</dd>
+<dd>
+<p>Most DNS queries (with some exceptions) are subject to dns_query_restriction.
+A domain to be queried is successively stripped-off of its leading labels
+(thus yielding a series of its parent domains), and on each iteration a
+check is made against an associative array generated by dns_query_restriction
+options. Search stops at the first match (i.e. the tightest match), and the
+matching entry with its <code>allow</code> or <code>deny</code> value then controls whether a
+DNS query is allowed to be launched.</p>
+</dd>
+<dd>
+<p>If no match is found an implicit default is to allow a query. The purpose of
+an explicit <code>allow</code> entry is to be able to override a previously configured
+<code>deny</code> on the same domain or to override an entry (possibly yet to be
+configured in subsequent config directives) on one of its parent domains.
+Thus an 'allow zen.spamhaus.org' with a 'deny spamhaus.org' would permit
+DNS queries on a specific DNS BL zone but deny queries to other zones under
+the same parent domain.</p>
+</dd>
+<dd>
+<p>Domains are matched case-insensitively, no wildcards are recognized,
+there should be no leading or trailing dot.</p>
+</dd>
+<dd>
+<p>Specifying a block on querying a domain name has a similar effect as setting
+a score of corresponding DNSBL and URIBL rules to zero, and can be a handy
+alternative to hunting for such rules when a site policy does not allow
+certain DNS block lists to be queried.</p>
+</dd>
+<dd>
+<p>Example:
+ dns_query_restriction deny dnswl.org surbl.org
+ dns_query_restriction allow zen.spamhaus.org
+ dns_query_restriction deny spamhaus.org mailspike.net spamcop.net</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_dns_query_restriction">clear_dns_query_restriction</a></strong><br />
+</dt>
+<dd>
+The option removes any entries entered by previous 'dns_query_restriction'
+options, leaving the list empty, i.e. allowing DNS queries for any domain
+(including any DNS BL zone).
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="learning_options">LEARNING OPTIONS</a></h2>
+<dl>
+<dt><strong><a name="item_use_learner">use_learner ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether to use any machine-learning classifiers with SpamAssassin, such as the
+default 'BAYES_*' rules. Setting this to 0 will disable use of any and all
+human-trained classifiers.
+</dd>
+<p></p>
+<dt><strong><a name="item_use_bayes">use_bayes ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether to use the naive-Bayesian-style classifier built into
+SpamAssassin. This is a master on/off switch for all Bayes-related
+operations.
+</dd>
+<p></p>
+<dt><strong><a name="item_use_bayes_rules">use_bayes_rules ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether to use rules using the naive-Bayesian-style classifier built
+into SpamAssassin. This allows you to disable the rules while leaving
+auto and manual learning enabled.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_auto_learn">bayes_auto_learn ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+Whether SpamAssassin should automatically feed high-scoring mails (or
+low-scoring mails, for non-spam) into its learning systems. The only
+learning system supported currently is a naive-Bayesian-style classifier.
+</dd>
+<dd>
+<p>See the documentation for the
+<code>Mail::SpamAssassin::Plugin::AutoLearnThreshold</code> plugin module
+for details on how Bayes auto-learning is implemented by default.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_ignore_header_header_name">bayes_ignore_header header_name</a></strong><br />
+</dt>
+<dd>
+If you receive mail filtered by upstream mail systems, like
+a spam-filtering ISP or mailing list, and that service adds
+new headers (as most of them do), these headers may provide
+inappropriate cues to the Bayesian classifier, allowing it
+to take a ``short cut''. To avoid this, list the headers using this
+setting. Example:
+</dd>
+<dd>
+<pre>
+ bayes_ignore_header X-Upstream-Spamfilter
+ bayes_ignore_header X-Upstream-SomethingElse</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_ignore_from_user_40example_2ecom">bayes_ignore_from <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Bayesian classification and autolearning will not be performed on mail
+from the listed addresses. Program <code>sa-learn</code> will also ignore the
+listed addresses if it is invoked using the <code>--use-ignores</code> option.
+One or more addresses can be listed, see <code>whitelist_from</code>.
+</dd>
+<dd>
+<p>Spam messages from certain senders may contain many words that
+frequently occur in ham. For example, one might read messages from a
+preferred bookstore but also get unwanted spam messages from other
+bookstores. If the unwanted messages are learned as spam then any
+messages discussing books, including the preferred bookstore and
+antiquarian messages would be in danger of being marked as spam. The
+addresses of the annoying bookstores would be listed. (Assuming they
+were halfway legitimate and didn't send you mail through myriad
+affiliates.)</p>
+</dd>
+<dd>
+<p>Those who have pieces of spam in legitimate messages or otherwise
+receive ham messages containing potentially spammy words might fear
+that some spam messages might be in danger of being marked as ham.
+The addresses of the spam mailing lists, correspondents, etc. would
+be listed.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_ignore_to_user_40example_2ecom">bayes_ignore_to <a href="mailto:user@example.com">user@example.com</a></a></strong><br />
+</dt>
+<dd>
+Bayesian classification and autolearning will not be performed on mail
+to the listed addresses. See <code>bayes_ignore_from</code> for details.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_min_ham_num">bayes_min_ham_num (Default: 200)</a></strong><br />
+</dt>
+<dt><strong><a name="item_bayes_min_spam_num">bayes_min_spam_num (Default: 200)</a></strong><br />
+</dt>
+<dd>
+To be accurate, the Bayes system does not activate until a certain number of
+ham (non-spam) and spam have been learned. The default is 200 of each ham and
+spam, but you can tune these up or down with these two settings.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_learn_during_report">bayes_learn_during_report (Default: 1)</a></strong><br />
+</dt>
+<dd>
+The Bayes system will, by default, learn any reported messages
+(<code>spamassassin -r</code>) as spam. If you do not want this to happen, set
+this option to 0.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_sql_override_username">bayes_sql_override_username</a></strong><br />
+</dt>
+<dd>
+Used by BayesStore::SQL storage implementation.
+</dd>
+<dd>
+<p>If this options is set the BayesStore::SQL module will override the set
+username with the value given. This could be useful for implementing global or
+group bayes databases.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_use_hapaxes">bayes_use_hapaxes (default: 1)</a></strong><br />
+</dt>
+<dd>
+Should the Bayesian classifier use hapaxes (words/tokens that occur only
+once) when classifying? This produces significantly better hit-rates.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_journal_max_size">bayes_journal_max_size (default: 102400)</a></strong><br />
+</dt>
+<dd>
+SpamAssassin will opportunistically sync the journal and the database.
+It will do so once a day, but will sync more often if the journal file
+size goes above this setting, in bytes. If set to 0, opportunistic
+syncing will not occur.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_expiry_max_db_size">bayes_expiry_max_db_size (default: 150000)</a></strong><br />
+</dt>
+<dd>
+What should be the maximum size of the Bayes tokens database? When expiry
+occurs, the Bayes system will keep either 75% of the maximum value, or
+100,000 tokens, whichever has a larger value. 150,000 tokens is roughly
+equivalent to a 8Mb database file.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_auto_expire">bayes_auto_expire (default: 1)</a></strong><br />
+</dt>
+<dd>
+If enabled, the Bayes system will try to automatically expire old tokens
+from the database. Auto-expiry occurs when the number of tokens in the
+database surpasses the bayes_expiry_max_db_size value. If a bayes datastore
+backend does not implement individual key/value expirations, the setting
+is silently ignored.
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_token_ttl">bayes_token_ttl (default: 3w, i.e. 3 weeks)</a></strong><br />
+</dt>
+<dd>
+Time-to-live / expiration time in seconds for tokens kept in a Bayes database.
+A numeric value is optionally suffixed by a time unit (s, m, h, d, w,
+indicating seconds (default), minutes, hours, days, weeks).
+</dd>
+<dd>
+<p>If bayes_auto_expire is true and a Bayes datastore backend supports it
+(currently only Redis), this setting controls deletion of expired tokens
+from a bayes database. The value is observed on a best-effort basis, exact
+timing promises are not necessarily kept. If a bayes datastore backend
+does not implement individual key/value expirations, the setting is silently
+ignored.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_seen_ttl">bayes_seen_ttl (default: 8d, i.e. 8 days)</a></strong><br />
+</dt>
+<dd>
+Time-to-live / expiration time in seconds for 'seen' entries
+(i.e. mail message digests with their status) kept in a Bayes database.
+A numeric value is optionally suffixed by a time unit (s, m, h, d, w,
+indicating seconds (default), minutes, hours, days, weeks).
+</dd>
+<dd>
+<p>If bayes_auto_expire is true and a Bayes datastore backend supports it
+(currently only Redis), this setting controls deletion of expired 'seen'
+entries from a bayes database. The value is observed on a best-effort basis,
+exact timing promises are not necessarily kept. If a bayes datastore backend
+does not implement individual key/value expirations, the setting is silently
+ignored.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_bayes_learn_to_journal">bayes_learn_to_journal (default: 0)</a></strong><br />
+</dt>
+<dd>
+If this option is set, whenever SpamAssassin does Bayes learning, it
+will put the information into the journal instead of directly into the
+database. This lowers contention for locking the database to execute
+an update, but will also cause more access to the journal and cause a
+delay before the updates are actually committed to the Bayes database.
+</dd>
+<p></p></dl>
+<p>
+</p>
+<h2><a name="miscellaneous_options">MISCELLANEOUS OPTIONS</a></h2>
+<dl>
+<dt><strong>time_limit n (default: 300)</strong><br />
+</dt>
+<dd>
+Specifies a limit on elapsed time in seconds that SpamAssassin is allowed
+to spend before providing a result. The value may be fractional and must
+not be negative, zero is interpreted as unlimited. The default is 300
+seconds for consistency with the spamd default setting of --timeout-child .
+</dd>
+<dd>
+<p>This is a best-effort advisory setting, processing will not be abruptly
+aborted at an arbitrary point in processing when the time limit is exceeded,
+but only on reaching one of locations in the program flow equipped with a
+time test. Currently equipped with the test are the main checking loop,
+asynchronous DNS lookups, plugins which are calling external programs.
+Rule evaluation is guarded by starting a timer (alarm) on each set of
+compiled rules.</p>
+</dd>
+<dd>
+<p>When a message is passed to Mail::SpamAssassin::parse, a deadline time
+is established as a sum of current time and the <code>time_limit</code> setting.</p>
+</dd>
+<dd>
+<p>This deadline may also be specified by a caller through an option
+'master_deadline' in $suppl_attrib on a call to parse(), possibly providing
+a more accurate deadline taking into account past and expected future
+processing of a message in a mail filtering setup. If both the config
+option as well as a 'master_deadline' option in a call are provided,
+the shorter time limit of the two is used (since version 3.3.2).
+Note that spamd (and possibly third-party callers of SpamAssassin) will
+supply the 'master_deadline' option in a call based on its --timeout-child
+option (or equivalent), unlike the command line <code>spamassassin</code>, which has
+no such command line option.</p>
+</dd>
+<dd>
+<p>When a time limit is exceeded, most of the remaining tests will be skipped,
+as well as auto-learning. Whatever tests fired so far will determine the
+final score. The behaviour is similar to short-circuiting with attribute 'on',
+as implemented by a Shortcircuit plugin. A synthetic hit on a rule named
+TIME_LIMIT_EXCEEDED with a near-zero default score is generated, so that
+the report will reflect the event. A score for TIME_LIMIT_EXCEEDED may
+be provided explicitly in a configuration file, for example to achieve
+whitelisting or blacklisting effect for messages with long processing times.</p>
+</dd>
+<dd>
+<p>The <code>time_limit</code> option is a useful protection against excessive processing
+time on certain degenerate or unusually long or complex mail messages, as well
+as against some DoS attacks. It is also needed in time-critical pre-queue
+filtering setups (e.g. milter, proxy, integration with MTA), where message
+processing must finish before a SMTP client times out. RFC 5321 prescribes
+in section 4.5.3.2.6 the 'DATA Termination' time limit of 10 minutes,
+although it is not unusual to see some SMTP clients abort sooner on waiting
+for a response. A sensible <code>time_limit</code> for a pre-queue filtering setup is
+maybe 50 seconds, assuming that clients are willing to wait at least a minute.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_lock_method_type">lock_method type</a></strong><br />
+</dt>
+<dd>
+Select the file-locking method used to protect database files on-disk. By
+default, SpamAssassin uses an NFS-safe locking method on UNIX; however, if you
+are sure that the database files you'll be using for Bayes and AWL storage will
+never be accessed over NFS, a non-NFS-safe locking system can be selected.
+</dd>
+<dd>
+<p>This will be quite a bit faster, but may risk file corruption if the files are
+ever accessed by multiple clients at once, and one or more of them is accessing
+them through an NFS filesystem.</p>
+</dd>
+<dd>
+<p>Note that different platforms require different locking systems.</p>
+</dd>
+<dd>
+<p>The supported locking systems for <code>type</code> are as follows:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_nfssafe__2d_an_nfs_2dsafe_locking_system"><em>nfssafe</em> - an NFS-safe locking system</a></strong><br />
+</dt>
+<dt><strong><a name="item_flock"><em>flock</em> - simple UNIX <code>flock()</code> locking</a></strong><br />
+</dt>
+<dt><strong><a name="item_sysopen"><em>win32</em> - Win32 locking using <code>sysopen (..., O_CREAT|O_EXCL)</code>.</a></strong><br />
+</dt>
+</dl>
+<p>nfssafe and flock are only available on UNIX, and win32 is only available
+on Windows. By default, SpamAssassin will choose either nfssafe or
+win32 depending on the platform in use.</p>
+<dt><strong><a name="item_fold_headers">fold_headers ( 0 | 1 ) (default: 1)</a></strong><br />
+</dt>
+<dd>
+By default, headers added by SpamAssassin will be whitespace folded.
+In other words, they will be broken up into multiple lines instead of
+one very long one and each continuation line will have a tabulator
+prepended to mark it as a continuation of the preceding one.
+</dd>
+<dd>
+<p>The automatic wrapping can be disabled here. Note that this can generate very
+long lines. RFC 2822 required that header lines do not exceed 998 characters
+(not counting the final CRLF).</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_report_safe_copy_headers_header_name__2e_2e_2e">report_safe_copy_headers header_name ...</a></strong><br />
+</dt>
+<dd>
+If using <a href="#item_report_safe"><code>report_safe</code></a>, a few of the headers from the original message
+are copied into the wrapper header (From, To, Cc, Subject, Date, etc.)
+If you want to have other headers copied as well, you can add them
+using this option. You can specify multiple headers on the same line,
+separated by spaces, or you can just use multiple lines.
+</dd>
+<p></p>
+<dt><strong><a name="item_envelope_sender_header_name_2dof_2dheader">envelope_sender_header Name-Of-Header</a></strong><br />
+</dt>
+<dd>
+SpamAssassin will attempt to discover the address used in the 'MAIL FROM:'
+phase of the SMTP transaction that delivered this message, if this data has
+been made available by the SMTP server. This is used in the <code>EnvelopeFrom</code>
+pseudo-header, and for various rules such as SPF checking.
+</dd>
+<dd>
+<p>By default, various MTAs will use different headers, such as the following:</p>
+</dd>
+<dd>
+<pre>
+ X-Envelope-From
+ Envelope-Sender
+ X-Sender
+ Return-Path</pre>
+</dd>
+<dd>
+<p>SpamAssassin will attempt to use these, if some heuristics (such as the header
+placement in the message, or the absence of fetchmail signatures) appear to
+indicate that they are safe to use. However, it may choose the wrong headers
+in some mailserver configurations. (More discussion of this can be found
+in bug 2142 and bug 4747 in the SpamAssassin BugZilla.)</p>
+</dd>
+<dd>
+<p>To avoid this heuristic failure, the <code>envelope_sender_header</code> setting may be
+helpful. Name the header that your MTA or MDA adds to messages containing the
+address used at the MAIL FROM step of the SMTP transaction.</p>
+</dd>
+<dd>
+<p>If the header in question contains <code><</code> or <code>></code> characters at the start
+and end of the email address in the right-hand side, as in the SMTP
+transaction, these will be stripped.</p>
+</dd>
+<dd>
+<p>If the header is not found in a message, or if it's value does not contain an
+<code>@</code> sign, SpamAssassin will issue a warning in the logs and fall back to its
+default heuristics.</p>
+</dd>
+<dd>
+<p>(Note for MTA developers: we would prefer if the use of a single header be
+avoided in future, since that precludes 'downstream' spam scanning.
+<code>http://wiki.apache.org/spamassassin/EnvelopeSenderInReceived</code> details a
+better proposal, storing the envelope sender at each hop in the <code>Received</code>
+header.)</p>
+</dd>
+<dd>
+<p>example:</p>
+</dd>
+<dd>
+<pre>
+ envelope_sender_header X-SA-Exim-Mail-From</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_describe_symbolic_test_name_description__2e_2e_2e">describe SYMBOLIC_TEST_NAME description ...</a></strong><br />
+</dt>
+<dd>
+Used to describe a test. This text is shown to users in the detailed report.
+</dd>
+<dd>
+<p>Note that test names which begin with '__' are reserved for meta-match
+sub-rules, and are not scored or listed in the 'tests hit' reports.</p>
+</dd>
+<dd>
+<p>Also note that by convention, rule descriptions should be limited in
+length to no more than 50 characters.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_charset">report_charset CHARSET (default: unset)</a></strong><br />
+</dt>
+<dd>
+Set the MIME Content-Type charset used for the text/plain report which
+is attached to spam mail messages.
+</dd>
+<p></p>
+<dt><strong><a name="item_report__2e_2e_2esome_text_for_a_report_2e_2e_2e">report ...some text for a report...</a></strong><br />
+</dt>
+<dd>
+Set the report template which is attached to spam mail messages. See the
+<code>10_default_prefs.cf</code> configuration file in <code>/usr/share/spamassassin</code> for an
+example.
+</dd>
+<dd>
+<p>If you change this, try to keep it under 78 columns. Each <code>report</code>
+line appends to the existing template, so use <a href="#item_clear_report_template"><code>clear_report_template</code></a>
+to restart.</p>
+</dd>
+<dd>
+<p>Tags can be included as explained above.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_report_template">clear_report_template</a></strong><br />
+</dt>
+<dd>
+Clear the report template.
+</dd>
+<p></p>
+<dt><strong><a name="item_report_contact__2e_2e_2etext_of_contact_address_2e">report_contact ...text of contact address...</a></strong><br />
+</dt>
+<dd>
+Set what _CONTACTADDRESS_ is replaced with in the above report text.
+By default, this is 'the administrator of that system', since the hostname
+of the system the scanner is running on is also included.
+</dd>
+<p></p>
+<dt><strong><a name="item_report_hostname__2e_2e_2ehostname_to_use_2e_2e_2e">report_hostname ...hostname to use...</a></strong><br />
+</dt>
+<dd>
+Set what _HOSTNAME_ is replaced with in the above report text.
+By default, this is determined dynamically as whatever the host running
+SpamAssassin calls itself.
+</dd>
+<p></p>
+<dt><strong><a name="item_unsafe_report__2e_2e_2esome_text_for_a_report_2e_2">unsafe_report ...some text for a report...</a></strong><br />
+</dt>
+<dd>
+Set the report template which is attached to spam mail messages which contain a
+non-text/plain part. See the <code>10_default_prefs.cf</code> configuration file in
+<code>/usr/share/spamassassin</code> for an example.
+</dd>
+<dd>
+<p>Each <code>unsafe-report</code> line appends to the existing template, so use
+<a href="#item_clear_unsafe_report_template"><code>clear_unsafe_report_template</code></a> to restart.</p>
+</dd>
+<dd>
+<p>Tags can be used in this template (see above for details).</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_clear_unsafe_report_template">clear_unsafe_report_template</a></strong><br />
+</dt>
+<dd>
+Clear the unsafe_report template.
+</dd>
+<p></p>
+<dt><strong><a name="item_mbox_format_from_regex">mbox_format_from_regex</a></strong><br />
+</dt>
+<dd>
+Set a specific regular expression to be used for mbox file From separators.
+</dd>
+<dd>
+<p>For example, this setting will allow sa-learn to process emails stored in
+a kmail 2 mbox:</p>
+</dd>
+<dd>
+<p>mbox_format_from_regex /^From \S+ ?[[:upper:]][[:lower:]]{2}(?:, \d\d [[:upper:]][[:lower:]]{2} \d{4} [0-2]\d:\d\d:\d\d [+-]\d{4}| [[:upper:]][[:lower:]]{2} [ 1-3]\d [ 0-2]\d:\d\d:\d\d \d{4})/</p>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="rule_definitions_and_privileged_settings">RULE DEFINITIONS AND PRIVILEGED SETTINGS</a></h1>
+<p>These settings differ from the ones above, in that they are considered
+'privileged'. Only users running <code>spamassassin</code> from their procmailrc's or
+forward files, or sysadmins editing a file in <code>/etc/mail/spamassassin</code>, can
+use them. <code>spamd</code> users cannot use them in their <code>user_prefs</code> files, for
+security and efficiency reasons, unless <a href="#item_allow_user_rules"><code>allow_user_rules</code></a> is enabled (and
+then, they may only add rules from below).</p>
+<dl>
+<dt><strong><a name="item_allow_user_rules">allow_user_rules ( 0 | 1 ) (default: 0)</a></strong><br />
+</dt>
+<dd>
+This setting allows users to create rules (and only rules) in their
+<code>user_prefs</code> files for use with <code>spamd</code>. It defaults to off, because
+this could be a severe security hole. It may be possible for users to
+gain root level access if <code>spamd</code> is run as root. It is NOT a good
+idea, unless you have some other way of ensuring that users' tests are
+safe. Don't use this unless you are certain you know what you are
+doing. Furthermore, this option causes spamassassin to recompile all
+the tests each time it processes a message for a user with a rule in
+his/her <code>user_prefs</code> file, which could have a significant effect on
+server load. It is not recommended.
+</dd>
+<dd>
+<p>Note that it is not currently possible to use <a href="#item_allow_user_rules"><code>allow_user_rules</code></a> to modify an
+existing system rule from a <code>user_prefs</code> file with <code>spamd</code>.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_redirector_pattern__2fpattern_2fmodifiers">redirector_pattern /pattern/modifiers</a></strong><br />
+</dt>
+<dd>
+A regex pattern that matches both the redirector site portion, and
+the target site portion of a URI.
+</dd>
+<dd>
+<p>Note: The target URI portion must be surrounded in parentheses and
+ no other part of the pattern may create a backreference.</p>
+</dd>
+<dd>
+<p>Example: <a href="http://chkpt.zdnet.com/chkpt/whatever/spammer.domain/yo/dude">http://chkpt.zdnet.com/chkpt/whatever/spammer.domain/yo/dude</a></p>
+</dd>
+<dd>
+<pre>
+ redirector_pattern /^https?:\/\/(?:opt\.)?chkpt\.zdnet\.com\/chkpt\/\w+\/(.*)$/i</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_header_symbolic_test_name_header_op__2fpattern_2fm">header SYMBOLIC_TEST_NAME header op /pattern/modifiers [if-unset: STRING]</a></strong><br />
+</dt>
+<dd>
+Define a test. <a href="#item_symbolic_test_name"><code>SYMBOLIC_TEST_NAME</code></a> is a symbolic test name, such as
+'FROM_ENDS_IN_NUMS'. <code>header</code> is the name of a mail header field,
+such as 'Subject', 'To', 'From', etc. Header field names are matched
+case-insensitively (conforming to RFC 5322 section 1.2.2), except for
+all-capitals metaheader fields such as ALL, MESSAGEID, ALL-TRUSTED.
+</dd>
+<dd>
+<p>Appending a modifier <code>:raw</code> to a header field name will inhibit decoding of
+quoted-printable or base-64 encoded strings, and will preserve all whitespace
+inside the header string. The <code>:raw</code> may also be applied to pseudo-headers
+e.g. <code>ALL:raw</code> will return a pristine (unmodified) header section.</p>
+</dd>
+<dd>
+<p>Appending a modifier <code>:addr</code> to a header field name will cause everything
+except the first email address to be removed from the header field. It is
+mainly applicable to header fields 'From', 'Sender', 'To', 'Cc' along with
+their 'Resent-*' counterparts, and the 'Return-Path'.</p>
+</dd>
+<dd>
+<p>Appending a modifier <code>:name</code> to a header field name will cause everything
+except the first display name to be removed from the header field. It is
+mainly applicable to header fields containing a single mail address: 'From',
+'Sender', along with their 'Resent-From' and 'Resent-Sender' counterparts.</p>
+</dd>
+<dd>
+<p>It is syntactically permitted to append more than one modifier to a header
+field name, although currently most combinations achieve no additional effect,
+for example <code>From:addr:raw</code> or <code>From:raw:addr</code> is currently the same as
+<code>From:addr</code> .</p>
+</dd>
+<dd>
+<p>For example, appending <code>:addr</code> to a header name will result in example@foo
+in all of the following cases:</p>
+</dd>
+<dl>
+<dt><strong><a name="item_example_40foo">example@foo</a></strong><br />
+</dt>
+<dt><strong><a name="item_foo">example@foo (Foo Blah)</a></strong><br />
+</dt>
+<dt><strong><a name="item_example_40foo_2c_example_40bar">example@foo, example@bar</a></strong><br />
+</dt>
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong><br />
+</dt>
+<dt><strong><a name="item_foo_blah__3cexample_40foo_3e">Foo Blah <example@foo></a></strong><br />
+</dt>
+<dt><strong><a name="item__22foo_blah_22__3cexample_40foo_3e">``Foo Blah'' <example@foo></a></strong><br />
+</dt>
+<dt><strong><a name="item__22_27foo_blah_27_22__3cexample_40foo_3e">``'Foo Blah''' <example@foo></a></strong><br />
+</dt>
+</dl>
+<p>For example, appending <code>:name</code> to a header name will result in ``Foo Blah''
+(without quotes) in all of the following cases:</p>
+<dl>
+<dt><strong>example@foo (Foo Blah)</strong><br />
+</dt>
+<dt><strong>example@foo (Foo Blah), example@bar</strong><br />
+</dt>
+<dt><strong>display: example@foo (Foo Blah), example@bar ;</strong><br />
+</dt>
+<dt><strong>Foo Blah <example@foo></strong><br />
+</dt>
+<dt><strong>``Foo Blah'' <example@foo></strong><br />
+</dt>
+<dt><strong>``'Foo Blah''' <example@foo></strong><br />
+</dt>
+</dl>
+<p>There are several special pseudo-headers that can be specified:</p>
+<dl>
+<dt><strong><a name="item_space"><code>ALL</code> can be used to mean the text of all the message's headers.
+Note that all whitespace inside the headers, at line folds, is currently
+compressed into a single space (' ') character. To obtain a pristine
+(unmodified) header section, use <code>ALL:raw</code> - the :raw modifier is documented
+above.</a></strong><br />
+</dt>
+<dt><strong><a name="item_tocc_can_be_used_to_mean_the_contents_of_both_the_"><code>ToCc</code> can be used to mean the contents of both the 'To' and 'Cc'
+headers.</a></strong><br />
+</dt>
+<dt><strong><a name="item_envelopefrom_is_the_address_used_in_the__27mail_fr"><code>EnvelopeFrom</code> is the address used in the 'MAIL FROM:' phase of the SMTP
+transaction that delivered this message, if this data has been made available
+by the SMTP server. See <code>envelope_sender_header</code> for more information
+on how to set this.</a></strong><br />
+</dt>
+<dt><strong><a name="item_messageid_is_a_symbol_meaning_all_message_2did_27s"><code>MESSAGEID</code> is a symbol meaning all Message-Id's found in the message;
+some mailing list software moves the real 'Message-Id' to 'Resent-Message-Id'
+or to 'X-Message-Id', then uses its own one in the 'Message-Id' header.
+The value returned for this symbol is the text from all 3 headers, separated
+by newlines.</a></strong><br />
+</dt>
+<dt><strong><a name="item_x_2dspam_2drelays_2duntrusted_2c_x_2dspam_2drelays"><code>X-Spam-Relays-Untrusted</code>, <code>X-Spam-Relays-Trusted</code>,
+<code>X-Spam-Relays-Internal</code> and <code>X-Spam-Relays-External</code> represent a portable,
+pre-parsed representation of the message's network path, as recorded in the
+Received headers, divided into 'trusted' vs 'untrusted' and 'internal' vs
+'external' sets. See <code>http://wiki.apache.org/spamassassin/TrustedRelays</code> for
+more details.</a></strong><br />
+</dt>
+</dl>
+<p><code>op</code> is either <code>=~</code> (contains regular expression) or <code>!~</code> (does not contain
+regular expression), and <code>pattern</code> is a valid Perl regular expression, with
+<code>modifiers</code> as regexp modifiers in the usual style. Note that multi-line
+rules are not supported, even if you use <code>x</code> as a modifier. Also note that
+the <code>#</code> character must be escaped (<code>\#</code>) or else it will be considered to be
+the start of a comment and not part of the regexp.</p>
+<p>If the <code>[if-unset: STRING]</code> tag is present, then <code>STRING</code> will
+be used if the header is not found in the mail message.</p>
+<p>Test names must not start with a number, and must contain only
+alphanumerics and underscores. It is suggested that lower-case characters
+not be used, and names have a length of no more than 22 characters,
+as an informal convention. Dashes are not allowed.</p>
+<p>Note that test names which begin with '__' are reserved for meta-match
+sub-rules, and are not scored or listed in the 'tests hit' reports.
+Test names which begin with 'T_' are reserved for tests which are
+undergoing QA, and these are given a very low score.</p>
+<p>If you add or modify a test, please be sure to run a sanity check afterwards
+by running <code>spamassassin --lint</code>. This will avoid confusing error
+messages, or other tests being skipped as a side-effect.</p>
+<dt><strong><a name="item_header_symbolic_test_name_exists_3aheader_field_na">header SYMBOLIC_TEST_NAME exists:header_field_name</a></strong><br />
+</dt>
+<dd>
+Define a header field existence test. <code>header_field_name</code> is the name
+of a header field to test for existence. Not to be confused with a
+test for a nonempty header field body, which can be implemented by a
+<code>header SYMBOLIC_TEST_NAME header =~ /\S/</code> rule as described above.
+</dd>
+<p></p>
+<dt><strong><a name="item_name_of_eval_method">header SYMBOLIC_TEST_NAME eval:name_of_eval_method([arguments])</a></strong><br />
+</dt>
+<dd>
+Define a header eval test. <a href="#item_name_of_eval_method"><code>name_of_eval_method</code></a> is the name of
+a method on the <code>Mail::SpamAssassin::EvalTests</code> object. <code>arguments</code>
+are optional arguments to the function call.
+</dd>
+<p></p>
+<dt><strong><a name="item_check_rbl">header SYMBOLIC_TEST_NAME eval:check_rbl('set', 'zone' [, 'sub-test'])</a></strong><br />
+</dt>
+<dd>
+Check a DNSBL (a DNS blacklist or whitelist). This will retrieve Received:
+headers from the message, extract the IP addresses, select which ones are
+'untrusted' based on the <code>trusted_networks</code> logic, and query that DNSBL
+zone. There's a few things to note:
+</dd>
+<dl>
+<dt><strong><a name="item_duplicated_or_private_ips">duplicated or private IPs</a></strong><br />
+</dt>
+<dd>
+Duplicated IPs are only queried once and reserved IPs are not queried.
+Private IPs are those listed in
+<http://www.iana.org/assignments/ipv4-address-space>,
+<http://duxcw.com/faq/network/privip.htm>,
+<http://duxcw.com/faq/network/autoip.htm>, or
+<http://tools.ietf.org/html/rfc5735> as private.
+</dd>
+<p></p>
+<dt><strong><a name="item_the__27set_27_argument">the 'set' argument</a></strong><br />
+</dt>
+<dd>
+This is used as a 'zone ID'. If you want to look up a multiple-meaning zone
+like SORBS, you can then query the results from that zone using it;
+but all <a href="#item_check_rbl_sub"><code>check_rbl_sub()</code></a> calls must use that zone ID.
+</dd>
+<dd>
+<p>Also, if more than one IP address gets a DNSBL hit for a particular rule, it
+does not affect the score because rules only trigger once per message.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_the__27zone_27_argument">the 'zone' argument</a></strong><br />
+</dt>
+<dd>
+This is the root zone of the DNSBL.
+</dd>
+<dd>
+<p>The domain name is considered to be a fully qualified domain name
+(i.e. not subject to DNS resolver's search or default domain options).
+No trailing period is needed, and will be removed if specified.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_the__27sub_2dtest_27_argument">the 'sub-test' argument</a></strong><br />
+</dt>
+<dd>
+This optional argument behaves the same as the sub-test argument in
+<a href="#item_check_rbl_sub"><code>check_rbl_sub()</code></a> below.
+</dd>
+<p></p>
+<dt><strong><a name="item_selecting_all_ips_except_for_the_originating_one">selecting all IPs except for the originating one</a></strong><br />
+</dt>
+<dd>
+This is accomplished by placing '-notfirsthop' at the end of the set name.
+This is useful for querying against DNS lists which list dialup IP
+addresses; the first hop may be a dialup, but as long as there is at least
+one more hop, via their outgoing SMTP server, that's legitimate, and so
+should not gain points. If there is only one hop, that will be queried
+anyway, as it should be relaying via its outgoing SMTP server instead of
+sending directly to your MX (mail exchange).
+</dd>
+<p></p>
+<dt><strong><a name="item_selecting_ips_by_whether_they_are_trusted">selecting IPs by whether they are trusted</a></strong><br />
+</dt>
+<dd>
+When checking a 'nice' DNSBL (a DNS whitelist), you cannot trust the IP
+addresses in Received headers that were not added by trusted relays. To
+test the first IP address that can be trusted, place '-firsttrusted' at the
+end of the set name. That should test the IP address of the relay that
+connected to the most remote trusted relay.
+</dd>
+<dd>
+<p>Note that this requires that SpamAssassin know which relays are trusted. For
+simple cases, SpamAssassin can make a good estimate. For complex cases, you
+may get better results by setting <code>trusted_networks</code> manually.</p>
+</dd>
+<dd>
+<p>In addition, you can test all untrusted IP addresses by placing '-untrusted'
+at the end of the set name. Important note -- this does NOT include the
+IP address from the most recent 'untrusted line', as used in '-firsttrusted'
+above. That's because we're talking about the trustworthiness of the
+IP address data, not the source header line, here; and in the case of
+the most recent header (the 'firsttrusted'), that data can be trusted.
+See the Wiki page at <code>http://wiki.apache.org/spamassassin/TrustedRelays</code>
+for more information on this.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_selecting_just_the_last_external_ip">Selecting just the last external IP</a></strong><br />
+</dt>
+<dd>
+By using '-lastexternal' at the end of the set name, you can select only
+the external host that connected to your internal network, or at least
+the last external host with a public IP.
+</dd>
+<p></p></dl>
[... 940 lines stripped ...]