.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Mail::Milter::Module::SPF 3pm"
.TH Mail::Milter::Module::SPF 3pm "2016-06-21" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Milter::Module::SPF \- milter to use Sender Policy Framework for accept/reject
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Mail::Milter::Module::SPF;
\&
\&    my $milter = new Mail::Milter::Module::SPF;
\&
\&    my $milter2 = &SPF; # convenience
.Ve
.SH "WARNING"
.IX Header "WARNING"
This module is known to have major problems.  It should \s-1NOT\s0 be used in a
production environment at this time.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This milter module rejects any mail from a sender (in the \s-1MAIL FROM\s0 part of 
the \s-1SMTP\s0 transaction, not in the From: header) if that sender's domain 
publishes a Sender Policy Framework (\s-1SPF\s0) record denying access to the 
connection host.
.PP
The pass/fail result from \s-1SPF\s0 is configurable as to whether mail will be 
accepted or rejected immediately.  By default, this module will reject a 
sender whose \s-1SPF\s0 lookup returns \*(L"fail\*(R", and allow others to pass, setting a 
Received-SPF: header with the \s-1SPF\s0 lookup result.  See the methods below for 
knobs tunable for different situations.
.PP
This module requires the Mail::SPF::Query module (version 1.996 or later) to 
be installed in order to fetch the \s-1SPF\s0 record.
.PP
Be sure to read \s-1BUGS\s0 at the bottom of this documentation for a list of 
currently unsupported features.
.SH "METHODS"
.IX Header "METHODS"
.RS 4
\&\fInew()\fR
.Sp
Creates a \s-1SPF\s0 object.  There are no arguments to configure this module from 
the constructor; see the methods below for changeable options.
.Sp
add_header(\s-1HEADERNAME\s0)
.Sp
Tell this module to append a header on messages which are not rejected, 
indicating the \s-1SPF\s0 result value and a comment explaining the result.  By 
default, this is enabled with the standard header name \f(CW\*(C`Received\-SPF\*(C'\fR.
.Sp
Note that this header is not appended if \f(CWwhitelist_pass(1)\fR is in effect, 
and a sender is whitelisted by a \s-1SPF \s0\*(L"pass\*(R" result.  This is because 
whitelisting skips all other mail processing, so this module cannot add 
headers at the end of processing.
.Sp
If \s-1HEADERNAME\s0 is undef, the header is disabled and will not be appended to 
any message.
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.Sp
ignore_softfail(\s-1FLAG\s0)
.Sp
If \s-1FLAG\s0 is 0, a \s-1SPF\s0 record resulting in \*(L"softfail\*(R" will be rejected as if 
the result were \*(L"fail\*(R".
.Sp
If \s-1FLAG\s0 is 1 (the default), a \*(L"softfail\*(R" is ignored, treated as if it 
returned \*(L"neutral\*(R".
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.Sp
ignore_tempfail(\s-1FLAG\s0)
.Sp
If \s-1FLAG\s0 is 0 (the default), a \s-1DNS\s0 lookup which fails the underlying \s-1DNS \s0
query (a \s-1SPF \s0\*(L"error\*(R" result) will cause the milter to return a temporary 
failure result (\s-1SMFIS_TEMPFAIL\s0).
.Sp
If \s-1FLAG\s0 is 1, a temporary \s-1DNS\s0 failure will be treated as if the lookup 
resulted in an empty record set (and thus a \s-1SPF \s0\*(L"none\*(R" result).
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.Sp
local_rules(\s-1RULETEXT\s0)
.Sp
Add one or more \s-1SPF\s0 rules to try before a \*(L"\-all\*(R" or \*(L"?all\*(R" record is 
encountered, in an attempt to validate the mail.  This is useful for 
enumerating secondary \s-1MX\s0 servers or non-SRS-compliant forwarding systems 
which send mail to this host.
.Sp
The rules must be contained in a single string, separated by spaces.
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.Sp
set_message(\s-1MESSAGE\s0)
.Sp
Sets the message used when rejecting messages.  This string may contain the 
substring \f(CW%M\fR, which will be replaced by the matching e\-mail address, 
and/or \f(CW%E\fR, which will be replaced by the \s-1SPF\s0 explanatory \s-1URL\s0 and text.
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.Sp
whitelist_pass(\s-1FLAG\s0)
.Sp
If \s-1FLAG\s0 is 0 (the default), a \s-1SPF \s0\*(L"pass\*(R" result will be treated like any 
other non-failure result, allowing the message to pass through without other 
special handling.
.Sp
If \s-1FLAG\s0 is 1, a \s-1SPF \s0\*(L"pass\*(R" result will cause this module to return 
\&\s-1SMFIS_ACCEPT,\s0 a value that is used by the \fIaccept_break\fR\|(1) behavior of 
Mail::Milter::Chain, to ignore the results of other modules in the chain.  
Note that because \s-1SPF\s0 does not accept or reject until the \s-1MAIL FROM:\s0 stage, 
it may be necessary to embed a DeferToRCPT wrapper into the whitelisting 
chain.  For example,
.Sp
.Vb 3
\&    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);
.Ve
.Sp
This method returns a reference to the object itself, allowing this method 
call to be chained.
.RE
.SH "BUGS"
.IX Header "BUGS"
Currently this module only handles IPv4 connecting hosts.  IPv6 hosts pass 
through without any \s-1SPF\s0 handling.
.PP
This module does not currently support the \f(CW\*(C`result2()\*(C'\fR form of the \s-1SPF \s0
query for special secondary-MX handling.  Currently \f(CW\*(C`local_rules()\*(C'\fR must be 
used to set up \s-1SPF\s0 exceptions for those secondary \s-1MX\s0 hosts.
.PP
The \f(CW\*(C`best_guess()\*(C'\fR and \f(CW\*(C`trusted_forwarder()\*(C'\fR special lookups are not yet 
supported.
.SH "AUTHOR"
.IX Header "AUTHOR"
Todd Vierling, <tv@duh.org> <tv@pobox.com>
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::Milter::Object, Mail::SPF::Query
.PP
the Sender Policy Framework Web site, http://spf.pobox.com/
.SH "POD ERRORS"
.IX Header "POD ERRORS"
Hey! \fBThe above document had some coding errors, which are explained below:\fR
.IP "Around line 89:" 4
.IX Item "Around line 89:"
You can't have =items (as at line 101) unless the first thing after the =over is an =item