NAME
    Mail::SpamAssassin::Conf - SpamAssassin configuration file

SYNOPSIS
      # a comment

      rewrite_subject                 1

      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

      header FROM_HAS_MIXED_NUMS      From =~ /\d+[a-z]+\d+\S*@/i
      describe FROM_HAS_MIXED_NUMS    From: contains numbers mixed in with letters

      score A_HREF_TO_REMOVE          2.0

      lang es describe FROM_FORGED_HOTMAIL Forzado From: simula ser de hotmail.com

DESCRIPTION
    SpamAssassin is configured using some traditional UNIX-style
    configuration files, loaded from the /usr/share/spamassassin and
    /etc/mail/spamassassin directories.

    The "#" character starts a comment, which continues until end of line,
    and whitespace in the files is not significant.

    Paths can use "~" to refer to the user's home directory.

    Where appropriate, default values are listed in parentheses.

USER PREFERENCES
    whitelist_from add@ress.com
        Used to specify addresses which send mail that is often tagged
        (incorrectly) as spam; it also helps if they are addresses of big
        companies with lots of lawyers. This way, if spammers impersonate
        them, they'll get into big trouble, so it doesn't provide a shortcut
        around SpamAssassin.

        Whitelist and blacklist addresses are now file-glob-style patterns,
        so "friend@somewhere.com", "*@isp.com", or "*.domain.net" will all
        work. Regular expressions are not used for security reasons.

        Multiple addresses per line is OK. Multiple "whitelist_from" lines
        is also OK.

    blacklist_from add@ress.com
        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 "whitelist_from".

    whitelist_to add@ress.com
        If the given address appears in the "To:" or "Cc:" headers, 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 "whitelist_from".

        There are three levels of To-whitelisting, "whitelist_to",
        "more_spam_to" and "all_spam_to". Users in the first level may still
        get some spammish mails blocked, but users in "all_spam_to" should
        never get mail blocked.

    more_spam_to add@ress.com
        See above.

    all_spam_to add@ress.com
        See above.

    required_hits n.nn (default: 5)
        Set the number of hits required before a mail is considered spam.
        "n.nn" can be an integer or a real number.

    auto_report_threshold n.nn (default: 30)
        How many hits before a mail is automatically reported to
        blacklisting services like Razor. Be very careful with this; you
        really should manually verify the spamminess of a mail before
        reporting it.

    score SYMBOLIC_TEST_NAME n.nn
        Assign a score to a given test. Scores can be positive or negative
        real numbers or integers. "SYMBOLIC_TEST_NAME" is the symbolic name
        used by SpamAssassin as a handle for that test; for example,
        'FROM_ENDS_IN_NUMS'.

    rewrite_subject { 0 | 1 } (default: 1)
        By default, the subject lines of suspected spam will be tagged. This
        can be disabled here.

    spam_level_stars { 0 | 1 } (default: 1)
        By default, a header field called "X-Spam-Level" will be added to
        the message, with its value set to a number of asterisks equal to
        the score of the message. In other words, for a message scoring 7.2
        points:

        X-Spam-Level: *******

        This can be useful for MUA rule creation.

    subject_tag STRING ... (default: *****SPAM*****)
        Text added to the "Subject:" line of mails that are considered spam,
        if "rewrite_subject" is 1. _HITS_ in the tag will be replace with
        the calculated score for this message. _REQD_ will be replaced with
        the threshold.

    report_header { 0 | 1 } (default: 0)
        By default, SpamAssassin will include its report in the body of
        suspected spam. Enabling this causes the report to go in the headers
        instead. Using 'use_terse_report' with this is recommended.

    use_terse_report { 0 | 1 } (default: 0)
        By default, SpamAssassin uses a fairly long report format. Enabling
        this uses a shorter format which includes all the information in the
        normal one, but without the superfluous explanations.

    defang_mime { 0 | 1 } (default: 1)
        By default, SpamAssassin will change the Content-type: header of
        suspected spam to "text/plain". This is a safety feature. If you
        prefer to leave the Content-type header alone, set this to 0.

    skip_rbl_checks { 0 | 1 } (default: 0)
        By default, SpamAssassin will run RBL checks. If your ISP already
        does this for you, set this to 1.

    check_mx_attempts n (default: 3)
        By default, SpamAssassin checks the From: address for a valid MX
        three times, waiting 5 seconds each time.

    check_mx_delay n (default 5)
        How many seconds to wait before retrying an MX check.

    ok_locales xx [ yy zz ... ] (default: en)
        Which locales (country codes) are considered OK to receive mail
        from. Mail using character sets used by languages in these
        countries, will not be marked as possibly being spam in a foreign
        language.

        SpamAssassin will try to determine the local locale, in order to
        determine which charsets should be allowed by default, but on some
        OSes it may not be able to do this effectively, requiring
        customisation.

        All ISO-8859-* character sets, and Windows code page character sets,
        are already permitted by default.

        The following locales use additional character sets, and are
        supported:

        ja  Japanese

        ko  Korea

        ru  Cyrillic charsets

        th  Thai

        zh  Chinese (both simplified and traditional)

        So to simply allow all character sets through without giving them
        points, use

                ok_locales      ja ko ru th zh

    auto_whitelist_factor n (default: 0.5, range [0..1])
        How much towards the long-term mean for the sender to regress a
        message. Basically, the algorithm is to track the long-term mean
        score of messages for the sender ("mean"), and then once we have
        otherwise fully calculated the score for this message ("score"), we
        calculate the final score for the message as:

        "finalscore" = "score" + ("mean" - "score") * "factor"

        So if "factor" = 0.5, then we'll move to half way between the
        calculated score and the mean. If "factor" = 0.3, then we'll move
        about 1/3 of the way from the score toward the mean. "factor" = 1
        means just use the long-term mean; "factor" = 0 mean just use the
        calculated score.

    describe SYMBOLIC_TEST_NAME description ...
        Used to describe a test. This text is shown to users in the detailed
        report.

    report ...some text for a report...
        Set the report template which is attached to spam mail messages. See
        the "10_misc.cf" configuration file in "/usr/share/spamassassin" for
        an example.

        If you change this, try to keep it under 76 columns (inside the the
        dots below). Bear in mind that EVERY line will be prefixed with
        "SPAM: " in order to make it clear what's been added, and allow
        other filters to remove spamfilter modifications, so you lose 6
        columns right there. Each "report" line appends to the existing
        template, so use "clear-report-template" to restart.

        The following template items are supported, and will be filled out
        by SpamAssassin:

        _HITS_: the number of hits the message triggered
        _REQD_: the required hits to be considered spam
        _SUMMARY_: the full details of what hits were triggered
        _VER_: SpamAssassin version
        _HOME_: SpamAssassin home URL
    clear_report_template
        Clear the report template.

    terse_report ...some text for a report...
        Set the report template which is attached to spam mail messages, for
        the terse-report format. See the "10_misc.cf" configuration file in
        "/usr/share/spamassassin" for an example.

    clear-terse-report-template
        Clear the terse-report template.

    spamtrap ...some text for spamtrap reply mail...
        A template for spam-trap responses. If the first few lines begin
        with "Xxxxxx: yyy" where Xxxxxx is a header and yyy is some text,
        they'll be used as headers. See the "10_misc.cf" configuration file
        in "/usr/share/spamassassin" for an example.

    clear_spamtrap_template
        Clear the spamtrap template.

SETTINGS
    These settings differ from the ones above, in that they are considered
    'privileged'. Only users running "spamassassin" from their procmailrc's
    or forward files, or sysadmins editing a file in
    "/etc/mail/spamassassin", can use them. "spamd" users cannot use them in
    their "user_prefs" files, for security and efficiency reasons, unless
    allow_user_rules is enabled (and then, they may only add rules from
    below).

    allow_user_rules { 0 | 1 } (default: 0)
        This setting allows users to create rules (and only rules) in their
        "user_prefs" files for use with "spamd". It defaults to off, because
        this could be a severe security hole. It may be possible for users
        to gain root level access if "spamd" 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.

    header SYMBOLIC_TEST_NAME header op /pattern/modifiers [if-unset:
    STRING]
        Define a test. "SYMBOLIC_TEST_NAME" is a symbolic test name, such as
        'FROM_ENDS_IN_NUMS'. "header" is the name of a mail header, such as
        'Subject', 'To', etc. 'ALL' can be used to mean the text of all the
        message's headers.

        "op" is either "=~" (contains regular expression) or "!~" (does not
        contain regular expression), and "pattern" is a valid Perl regular
        expression, with "modifiers" as regexp modifiers in the usual style.

        If the "[if-unset: STRING]" tag is present, then "STRING" will be
        used if the header is not found in the mail message.

    header SYMBOLIC_TEST_NAME eval:name_of_eval_method([arguments])
        Define a header eval test. "name_of_eval_method" is the name of a
        method on the "Mail::SpamAssassin::EvalTests" object. "arguments"
        are optional arguments to the function call.

    body SYMBOLIC_TEST_NAME /pattern/modifiers
        Define a body pattern test. "pattern" is a Perl regular expression.

        The 'body' in this case is the textual parts of the message body;
        any non-text MIME parts are stripped, and the message decoded from
        Quoted-Printable or Base-64-encoded format if necessary. All HTML
        tags and line breaks will be removed before matching.

    body SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
        Define a body eval test. See above.

    uri SYMBOLIC_TEST_NAME /pattern/modifiers
        Define a uri pattern test. "pattern" is a Perl regular expression.

        The 'uri' in this case is a list of all the URIs in the body of the
        email, and the test will be run on each and every one of those URIs,
        adjusting the score if a match is found. Use this test instead of
        one of the body tests when you need to match a URI, as it is more
        accurately bound to the start/end points of the URI, and will also
        be faster.

    rawbody SYMBOLIC_TEST_NAME /pattern/modifiers
        Define a raw-body pattern test. "pattern" is a Perl regular
        expression.

        The 'raw body' of a message is the text, including all textual
        parts. The text will be decoded from base64 or quoted-printable
        encoding, but HTML tags and line breaks will still be present.

    rawbody SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
        Define a raw-body eval test. See above.

    full SYMBOLIC_TEST_NAME /pattern/modifiers
        Define a full-body pattern test. "pattern" is a Perl regular
        expression.

        The 'full body' of a message is the un-decoded text, including all
        parts (including images or other attachments). SpamAssassin no
        longer tests full tests against decoded text; use "rawbody" for
        that.

    full SYMBOLIC_TEST_NAME eval:name_of_eval_method([args])
        Define a full-body eval test. See above.

    test SYMBOLIC_TEST_NAME (ok|fail) Some string to test against
        Define a regression testing string. You can have more than one
        regression test string per symbolic test name. Simply specify a
        string that you wish the test to match.

        These tests are only run as part of the test suite - they should not
        affect the general running of SpamAssassin.

    razor_config filename
        Define the filename used to store Razor's configuration settings.
        Currently this is the same value Razor itself uses: "~/razor.conf".

    auto_whitelist_path /path/to/file (default:
    ~/.spamassassin/auto-whitelist)
        Automatic-whitelist directory or file. By default, each user has
        their own, in their "~/.spamassassin" directory with mode 0700, but
        for system-wide SpamAssassin use, you may want to share this across
        all users.

    auto_whitelist_file_mode (default: 0700)
        The file mode bits used for the automatic-whitelist directory or
        file. Make sure this has the relevant execute-bits set (--x),
        otherwise things will go wrong.

    user-scores-dsn DBI:databasetype:databasename:hostname:port
        If you load user scores from an SQL database, this will set the DSN
        used to connect. Example: "DBI:mysql:spamassassin:localhost"

    user_scores_sql_username username
        The authorized username to connect to the above DSN.

    user_scores_sql_password password
        The password for the database username, for the above DSN.

    spamphrase score phrase ...
        A 2-word spam phrase, for the FREQ_SPAM_PHRASE test.

    spamphrase-highest-score nnnnn
        The highest score of any of the spamphrases. Used for scaling.

LOCALI[SZ]ATION
    A line starting with the text "lang xx" will only be interpreted if the
    user is in that locale, allowing test descriptions and templates to be
    set for that language.

SEE ALSO
    "Mail::SpamAssassin" "spamassassin" "spamd"

