.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" 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" '' '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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" 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 3pm" .TH Courier::Filter 3pm "2013-05-30" "perl v5.14.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 \- Purely Perl\-based mail filter framework for the Courier MTA .SH "VERSION" .IX Header "VERSION" 0.200 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use Courier::Filter; \& use Courier::Filter::Logger::Moo; \& use Courier::Filter::Module::Foo; \& use Courier::Filter::Module::Bar; \& \& my $filter = Courier::Filter\->new( \& mandatory => 1, \& logger => Courier::Filter::Logger::Moo\->new( ... ), \& modules => [ \& Courier::Filter::Module::Foo\->new( ... ), \& Courier::Filter::Module::Bar\->new( ... ) \& ], \& testing => 0, \& debugging => 0 \& ); \& \& my $exit_code = $filter\->run() || 0; \& \& exit($exit_code); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBFor an architectural and administrative overview of the \fBCourier::Filter\fB framework, see Courier::Filter::Overview.\fR .PP The \fBCourier::Filter\fR class is the heart of the Courier::Filter framework. To drive a \fBcourierfilter\fR filter process, create a \fBCourier::Filter\fR object, passing the filter modules and loggers you want to use to the constructor, and call the \f(CW\*(C`run()\*(C'\fR method. .PP Courier::Filter will then take care of creating the courierfilter socket in the right place in a safe manner, listening for connections from Courier, asking filter modules for consideration of messages, notifying Courier of whether messages should be accepted or rejected, logging message rejections, catching and logging errors, and finally removing the socket when being terminated by Courier. .SS "Constructor" .IX Subsection "Constructor" The following constructor is provided: .IP "\fBnew(%options)\fR: returns \fICourier::Filter\fR; throws \fICourier::Error\fR, Perl exceptions" 4 .IX Item "new(%options): returns Courier::Filter; throws Courier::Error, Perl exceptions" Creates a new \f(CW\*(C`Courier::Filter\*(C'\fR object. Also creates the courierfilter socket in the right place in a safe manner. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP "\fBname\fR" 4 .IX Item "name" The name of the filter process. Used to build the socket name. Defaults to the base name of the process (\f(CW$0\fR). .IP "\fBmandatory\fR" 4 .IX Item "mandatory" A boolean value controlling whether the filter process should act as a mandatory courierfilter. If \fBtrue\fR, users will not be able to bypass the filter modules in this filter process from their individual \fBlocalmailfilter\fR filters. Technically, this controls whether the courierfilter socket will be created in the \f(CW\*(C`allfilters\*(C'\fR (\fBtrue\fR) or the \f(CW\*(C`filters\*(C'\fR (\fBfalse\fR) directory in Courier's run-time state directory (see \*(L"runtime_dir\*(R" in Courier::Config). Defaults to \fBtrue\fR. .IP "\fBlogger\fR" 4 .IX Item "logger" A \fBCourier::Filter::Logger\fR object that will be used for logging message rejections and error messages. You may override this for individual filter modules for which you do not want the global logger to be used. If no logger is specified, logging is disabled. .IP "\fBmodules\fR" 4 .IX Item "modules" \&\fIRequired\fR. A so-called \fBfilter module group\fR structure. A module group is a reference to an array that may contain filter module objects (i.e. instances of sub-classes of \fBCourier::Filter::Module\fR), as well as other module groups. Thus, a module group is essentially a tree structure with filter modules as its leaves. When considering messages, Courier::Filter walks the tree in a recursive-descent, depth-first order, asking every filter module for consideration of the message's acceptability. .Sp For instance, given the following filter module group: .Sp .Vb 1 \& [$m1, $m2, [$m3, [$m4, $m5]], $m6] .Ve .Sp Courier::Filter queries the filter modules in ascending order from 1 to 6. .Sp The acceptability result returned by each module determines how Courier::Filter proceeds with considering the current message: .RS 4 .IP "\(bu" 4 If a module states an \fBexplicit reject\fR, Courier::Filter aborts the consideration process and rejects the message. .IP "\(bu" 4 If a module states an \fBimplicit accept\fR, Courier::Filter just proceeds to the next module in turn. .IP "\(bu" 4 If a module states an \fBexplicit accept\fR, Courier::Filter skips the rest of the current module group and proceeds to the next item in the superordinate module group, assuming the whole group to be an implicit accept. .RE .RS 4 .Sp For instance, take the nested filter module group from above: .Sp .Vb 4 \& [$m1, $m2, [$m3, [$m4, $m5]], $m6] \& | | \*(Aq\-\-\-g3\-\-\-\*(Aq| | \& | \*(Aq\-\-\-\-group 2\-\-\-\-\*(Aq | \& \*(Aq\-\-\-\-\-\-\-\-\-\-\-\-group 1\-\-\-\-\-\-\-\-\-\-\-\-\-\*(Aq .Ve .Sp Let's assume Courier::Filter queries the filter module \f(CW$m3\fR. If \f(CW$m3\fR states an \&\fBexplicit reject\fR, the consideration process is aborted and the current message is rejected. If \f(CW$m3\fR states an \fBimplicit accept\fR, Courier::Filter proceeds to \f(CW$m4\fR. If \f(CW$m3\fR states an \fBexplicit accept\fR, the rest of group 2 (including all of group 3) is skipped and the acceptability result of group 2 is assumed an implicit accept, so Courier::Filter proceeds to \f(CW$m6\fR. .Sp If no \fBexplicit reject\fR has occured when Courier::Filter reaches the end of the main module group, or a module in the main group states an \fBexplicit accept\fR, the message is accepted. .Sp Using nested groups of filter modules with normal or inverse polarity, it should be possible to implement sufficiently complex filtering policies to satisfy very most needs. .RE .IP "\fBtrusting\fR" 4 .IX Item "trusting" A boolean value controlling whether the \fIwhole\fR filter process should \fInot\fR apply any filtering to trusted messages. For details on how the trusted status is determined, see the description of the \f(CW\*(C`trusted\*(C'\fR property in Courier::Message. In most \s-1MTA\s0 configurations, this option can be used to white-list so-called outbound messages. Defaults to \fBfalse\fR. .IP "\fBtesting\fR" 4 .IX Item "testing" A boolean value controlling whether the \fIwhole\fR filter process should run in \&\*(L"testing\*(R" mode. In testing mode, planned message rejections will be logged as usual, but no messages will actually be rejected. Defaults to \fBfalse\fR. .Sp \&\s-1NOTE:\s0 You may also enable testing mode on individual filter module objects, see \*(L"new\*(R" in Courier::Filter::Module. Enabling testing mode globally is not the same as individually enabling testing mode on all filter modules, though. When global testing mode is enabled, Courier::Filter only ignores the \fIfinal\fR result, but still follows the rules of the normal consideration process, e.g. aborting as soon as a filter module states an \fBexplicit reject\fR, etc. When an individual filter module is in testing mode, its \fIindividual\fR result is ignored, and the consideration process is continued with the next filter module. So individually enabling testing mode on all filter modules allows you to thoroughly test the correctness and performance of all installed filter modules, or even to gather stochastically indepent statistics on the hit/miss rates of your filter modules. .IP "\fBdebugging\fR" 4 .IX Item "debugging" A boolean value controlling whether extra debugging information should be logged by Courier::Filter. Defaults to \fBfalse\fR. You need to enable debugging mode for filter modules separately. .RE .RS 4 .RE .SS "Instance methods" .IX Subsection "Instance methods" The following instance methods are provided: .IP "\fBrun\fR: throws \fICourier::Error\fR, Perl exceptions" 4 .IX Item "run: throws Courier::Error, Perl exceptions" Runs the Courier::Filter. Listens for connections from Courier on the courierfilter socket, asks the configured filter modules for consideration of messages, notifies Courier of whether messages should be accepted or rejected, and logs message rejections. When Courier requests termination of the courierfilter, removes the socket and returns. .IP "\fBname\fR: returns \fIstring\fR" 4 .IX Item "name: returns string" Returns the name of the filter process, as set through the constructor's \&\f(CW\*(C`name\*(C'\fR option. .IP "\fBmandatory\fR: returns \fIboolean\fR" 4 .IX Item "mandatory: returns boolean" Returns a boolean value indicating whether the filter process is a mandatory courierfilter, as set through the constructor's \f(CW\*(C`mandatory\*(C'\fR option. .IP "\fBlogger\fR: returns \fICourier::Filter::Logger\fR" 4 .IX Item "logger: returns Courier::Filter::Logger" .PD 0 .IP "\fBlogger($logger)\fR: returns \fICourier::Filter::Logger\fR" 4 .IX Item "logger($logger): returns Courier::Filter::Logger" .PD If \f(CW$logger\fR is specified, installs a new global logger. Returns the (newly) configured global logger. .IP "\fBmodules\fR: returns \fIarray-ref\fR" 4 .IX Item "modules: returns array-ref" .PD 0 .IP "\fBmodules(\e@modules)\fR: returns \fIarray-ref\fR" 4 .IX Item "modules(@modules): returns array-ref" .PD If \f(CW\*(C`\e@modules\*(C'\fR is specified, installs a new filter module group structure. Returns the (newly) configured filter modules group structure. .IP "\fBtrusting\fR: returns \fIboolean\fR" 4 .IX Item "trusting: returns boolean" Returns a boolean value indicating the trusting mode, as set through the constructor's \f(CW\*(C`trusting\*(C'\fR option. .IP "\fBtesting\fR: returns \fIboolean\fR" 4 .IX Item "testing: returns boolean" Returns a boolean value indicating the global testing mode, as set through the constructor's \f(CW\*(C`testing\*(C'\fR option. .IP "\fBdebugging\fR: returns \fIboolean\fR" 4 .IX Item "debugging: returns boolean" .PD 0 .IP "\fBdebugging($debugging)\fR: returns \fIboolean\fR" 4 .IX Item "debugging($debugging): returns boolean" .PD If \f(CW$debugging\fR is specified, sets the global debugging mode. Returns a boolean value indicating the (newly) configured global debugging mode. .SH "SEE ALSO" .IX Header "SEE ALSO" courier-filter-perl, Courier::Filter::Overview, Courier::Filter::Module, Courier::Filter::Logger .PP For \s-1AVAILABILITY\s0, \s-1SUPPORT\s0, and \s-1LICENSE\s0 information, see Courier::Filter::Overview. .SH "REFERENCES" .IX Header "REFERENCES" .IP "The \fBcourierfilter\fR interface" 4 .IX Item "The courierfilter interface" http://www.courier\-mta.org/courierfilter.html .SH "AUTHOR" .IX Header "AUTHOR" Julian Mehnle