.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Courier::Filter::Module::SPFout 3pm" .TH Courier::Filter::Module::SPFout 3pm "2015-11-28" "perl v5.20.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" Courier::Filter::Module::SPFout \- Outbound SPF filter module for the Courier::Filter framework .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Courier::Filter::Module::SPFout; \& \& my $module = Courier::Filter::Module::SPFout\->new( \& match_on => [\*(Aqfail\*(Aq, \*(Aqpermerror\*(Aq, \*(Aqtemperror\*(Aq], \& default_response => $default_response_text, \& force_response => $force_response_text, \& outbound_ip_addresses \& => [\*(Aq129.257.16.1\*(Aq, \*(Aq2001:6ag:10e1::1\*(Aq], \& spf_options => { \& # any Mail::SPF::Server options \& }, \& \& logger => $logger, \& inverse => 0, \& trusting => 0, \& testing => 0, \& debugging => 0 \& ); \& \& my $filter = Courier::Filter\->new( \& ... \& modules => [ $module ], \& ... \& ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This class is a filter module for use with Courier::Filter. It matches a message if any of the receiving (local) machine's outbound \s-1IP\s0 addresses are \&\fInot\fR authorized to send mail from the envelope sender's (\s-1MAIL FROM\s0) domain according to that domain's \s-1DNS SPF \s0(Sender Policy Framework) record. This is \&\fIoutbound\fR \s-1SPF\s0 checking. .PP The point of inbound \s-1SPF\s0 checking is for message submission agents (MSAs, smarthosts) to protect \fIothers\fR against forged envelope sender addresses in messages submitted by the \s-1MSA\s0's users. .SS "Constructor" .IX Subsection "Constructor" The following constructor is provided: .IP "\fBnew(%options)\fR: returns \fICourier::Filter::Module::SPFout\fR" 4 .IX Item "new(%options): returns Courier::Filter::Module::SPFout" Creates a new \fBSPFout\fR filter module. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP "\fBtrusting\fR" 4 .IX Item "trusting" \&\fIDisabled\fR. Since \fIoutbound\fR \s-1SPF\s0 checking, as opposed to \fIinbound\fR \s-1SPF\s0 checking, is applied to trusted (authenticated) messages only, setting this module to be \fBtrusting\fR does not make sense. This property is thus locked to \&\fBfalse\fR. Also see the description of Courier::Message's \f(CW\*(C`trusted\*(C'\fR property . .IP "\fBmatch_on\fR" 4 .IX Item "match_on" A reference to an array containing the set of \s-1SPF\s0 result codes which should cause the filter module to match a message. Possible result codes are \f(CW\*(C`pass\*(C'\fR, \&\f(CW\*(C`fail\*(C'\fR, \f(CW\*(C`softfail\*(C'\fR, \f(CW\*(C`neutral\*(C'\fR, \f(CW\*(C`none\*(C'\fR, \f(CW\*(C`permerror\*(C'\fR, and \f(CW\*(C`temperror\*(C'\fR. See the \s-1SPF\s0 specification for details on the meaning of those. If \f(CW\*(C`temperror\*(C'\fR is listed, an \f(CW\*(C`temperror\*(C'\fR result will by definition never cause a \fIpermanent\fR rejection, but only a \fItemporary\fR one. Defaults to \fB['fail', 'permerror', \&'temperror']\fR. .Sp \&\fINote\fR: With early \s-1SPF\s0 specification drafts as well as the obsolete Mail::SPF::Query module, the \f(CW\*(C`permerror\*(C'\fR and \f(CW\*(C`temperror\*(C'\fR result codes were known as \f(CW\*(C`unknown\*(C'\fR and \f(CW\*(C`error\*(C'\fR, respectively; the old codes are now deprecated but still supported for the time being. .IP "\fBdefault_response\fR" 4 .IX Item "default_response" A string that is to be returned as the module's match result in case of a match, that is when the \f(CW\*(C`match_on\*(C'\fR option includes the result code of the \s-1SPF\s0 check (by default when a message fails the \s-1SPF\s0 check). However, this default response is used only if the (claimed) envelope sender domain does not provide an explicit response. See \*(L"default_authority_explanation\*(R" in Mail::SPF::Server for more information. .Sp \&\s-1SPF\s0 macro substitution is performed on the default response, just like on explanations provided by domain owners. If \fBundef\fR, Mail::SPF's default explanation will be used. Defaults to \fBundef\fR. .IP "\fBforce_response\fR" 4 .IX Item "force_response" Instead of merely specifying a default response for cases where the sender domain does not provide an explicit response, you can also specify a response to be used in \fIall\fR cases, even if the sender domain does provide one. This may be useful if you do not want to confuse your own users with \fI3rd\-party\fR provided explanations when in fact they are only dealing with \fIyour\fR server not wanting to relay their messages. Defaults to \fBundef\fR. .IP "\fBoutbound_ip_addresses\fR" 4 .IX Item "outbound_ip_addresses" A reference to an array containing the local system's set of outbound \s-1IP\s0 addresses that will be assumed as the sender \s-1IP\s0 address in outbound \s-1SPF\s0 checks. This set should include \fIall\fR public \s-1IP\s0 addresses that are used for relaying mail. By default, automatic discovery of one public \s-1IP\s0 address that is \*(L"en route\*(R" to \*(L"the internet\*(R" is attempted for each of IPv4 and IPv6. Auto-discovery does not work from behind NATs. .IP "\fBspf_options\fR" 4 .IX Item "spf_options" A hash-ref specifying options for the Mail::SPF server object used by this filter module. See \*(L"new\*(R" in Mail::SPF::Server for the supported options. .RE .RS 4 .Sp All options of the \fBCourier::Filter::Module\fR constructor (except for the \&\fBtrusting\fR option) are also supported. Please see \&\*(L"new\*(R" in Courier::Filter::Module for their descriptions. .RE .SS "Instance methods" .IX Subsection "Instance methods" See \*(L"Instance methods\*(R" in Courier::Filter::Module for a description of the provided instance methods. .SH "SEE ALSO" .IX Header "SEE ALSO" Courier::Filter::Module::SPF, Courier::Filter::Module, Courier::Filter::Overview, Mail::SPF. .PP For \s-1AVAILABILITY, SUPPORT,\s0 and \s-1LICENSE\s0 information, see Courier::Filter::Overview. .SH "REFERENCES" .IX Header "REFERENCES" .IP "\fB\s-1SPF\s0 website\fR (Sender Policy Framework)" 4 .IX Item "SPF website (Sender Policy Framework)" .IP "\fB\s-1SPF\s0 specification\fR" 4 .IX Item "SPF specification" .SH "AUTHOR" .IX Header "AUTHOR" Julian Mehnle