NAME

       Mail::Milter::Module::SPF - milter to use Sender Policy Framework for accept/reject

SYNOPSIS

           use Mail::Milter::Module::SPF;

           my $milter = new Mail::Milter::Module::SPF;

           my $milter2 = &SPF; # convenience

WARNING

       This module is known to have major problems.  It should NOT be used in a production
       environment at this time.

DESCRIPTION

       This milter module rejects any mail from a sender (in the MAIL FROM part of the SMTP
       transaction, not in the From: header) if that sender's domain publishes a Sender Policy
       Framework (SPF) record denying access to the connection host.

       The pass/fail result from SPF is configurable as to whether mail will be accepted or
       rejected immediately.  By default, this module will reject a sender whose SPF lookup
       returns "fail", and allow others to pass, setting a Received-SPF: header with the SPF
       lookup result.  See the methods below for knobs tunable for different situations.

       This module requires the Mail::SPF::Query module (version 1.996 or later) to be installed
       in order to fetch the SPF record.

       Be sure to read BUGS at the bottom of this documentation for a list of currently
       unsupported features.

METHODS

           new()

           Creates a SPF object.  There are no arguments to configure this module from the
           constructor; see the methods below for changeable options.

           add_header(HEADERNAME)

           Tell this module to append a header on messages which are not rejected, indicating the
           SPF result value and a comment explaining the result.  By default, this is enabled
           with the standard header name "Received-SPF".

           Note that this header is not appended if whitelist_pass(1) is in effect, and a sender
           is whitelisted by a SPF "pass" result.  This is because whitelisting skips all other
           mail processing, so this module cannot add headers at the end of processing.

           If HEADERNAME is undef, the header is disabled and will not be appended to any
           message.

           This method returns a reference to the object itself, allowing this method call to be
           chained.

           ignore_softfail(FLAG)

           If FLAG is 0, a SPF record resulting in "softfail" will be rejected as if the result
           were "fail".

           If FLAG is 1 (the default), a "softfail" is ignored, treated as if it returned
           "neutral".

           This method returns a reference to the object itself, allowing this method call to be
           chained.

           ignore_tempfail(FLAG)

           If FLAG is 0 (the default), a DNS lookup which fails the underlying DNS query (a SPF
           "error" result) will cause the milter to return a temporary failure result
           (SMFIS_TEMPFAIL).

           If FLAG is 1, a temporary DNS failure will be treated as if the lookup resulted in an
           empty record set (and thus a SPF "none" result).

           This method returns a reference to the object itself, allowing this method call to be
           chained.

           local_rules(RULETEXT)

           Add one or more SPF rules to try before a "-all" or "?all" record is encountered, in
           an attempt to validate the mail.  This is useful for enumerating secondary MX servers
           or non-SRS-compliant forwarding systems which send mail to this host.

           The rules must be contained in a single string, separated by spaces.

           This method returns a reference to the object itself, allowing this method call to be
           chained.

           set_message(MESSAGE)

           Sets the message used when rejecting messages.  This string may contain the substring
           %M, which will be replaced by the matching e-mail address, and/or %E, which will be
           replaced by the SPF explanatory URL and text.

           This method returns a reference to the object itself, allowing this method call to be
           chained.

           whitelist_pass(FLAG)

           If FLAG is 0 (the default), a SPF "pass" result will be treated like any other non-
           failure result, allowing the message to pass through without other special handling.

           If FLAG is 1, a SPF "pass" result will cause this module to return SMFIS_ACCEPT, a
           value that is used by the accept_break(1) behavior of Mail::Milter::Chain, to ignore
           the results of other modules in the chain.  Note that because SPF does not accept or
           reject until the MAIL FROM: stage, it may be necessary to embed a DeferToRCPT wrapper
           into the whitelisting chain.  For example,

               use Mail::Milter::Chain;
               use Mail::Milter::Module::SPF;
               use Mail::Milter::Wrapper::DeferToRCPT;

               my $spf_whitelisted_chain = new Mail::Milter::Chain(
                   &SPF->whitelist_pass(1),
                   &DeferToRCPT(new Mail::Milter::Chain(
                       $milter1, ...
                   ))
               )->accept_break(1);

           This method returns a reference to the object itself, allowing this method call to be
           chained.

BUGS

       Currently this module only handles IPv4 connecting hosts.  IPv6 hosts pass through without
       any SPF handling.

       This module does not currently support the "result2()" form of the SPF query for special
       secondary-MX handling.  Currently "local_rules()" must be used to set up SPF exceptions
       for those secondary MX hosts.

       The "best_guess()" and "trusted_forwarder()" special lookups are not yet supported.

AUTHOR

       Todd Vierling, <tv@duh.org> <tv@pobox.com>

SEE ALSO

       Mail::Milter::Object, Mail::SPF::Query

       the Sender Policy Framework Web site, http://spf.pobox.com/

POD ERRORS

       Hey! The above document had some coding errors, which are explained below:

       Around line 89:
           You can't have =items (as at line 101) unless the first thing after the =over is an
           =item