NAME¶
Courier::Filter - Purely Perl-based mail filter framework for the Courier MTA
VERSION¶
0.200
SYNOPSIS¶
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);
DESCRIPTION¶
For an architectural and administrative overview of the
Courier::Filter framework, see
Courier::Filter::Overview.
The
Courier::Filter class is the heart of the Courier::Filter framework.
To drive a
courierfilter filter process, create a
Courier::Filter object, passing the filter modules and loggers you want
to use to the constructor, and call the "run()" method.
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.
Constructor¶
The following constructor is provided:
- new(%options): returns Courier::Filter; throws
Courier::Error, Perl exceptions
- Creates a new "Courier::Filter" object. Also creates the
courierfilter socket in the right place in a safe manner.
%options is a list of key/value pairs representing any of the following
options:
- name
- The name of the filter process. Used to build the socket name. Defaults to
the base name of the process ($0).
- mandatory
- A boolean value controlling whether the filter process should act as a
mandatory courierfilter. If true, users will not be able to bypass
the filter modules in this filter process from their individual
localmailfilter filters. Technically, this controls whether the
courierfilter socket will be created in the "allfilters" (
true) or the "filters" ( false) directory in
Courier's run-time state directory (see "runtime_dir" in
Courier::Config). Defaults to true.
- logger
- A Courier::Filter::Logger 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.
- modules
- Required. A so-called filter module group structure. A
module group is a reference to an array that may contain filter module
objects (i.e. instances of sub-classes of Courier::Filter::Module),
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.
For instance, given the following filter module group:
[$m1, $m2, [$m3, [$m4, $m5]], $m6]
Courier::Filter queries the filter modules in ascending order from 1 to 6.
The acceptability result returned by each module determines how
Courier::Filter proceeds with considering the current message:
- •
- If a module states an explicit reject, Courier::Filter aborts the
consideration process and rejects the message.
- •
- If a module states an implicit accept, Courier::Filter just
proceeds to the next module in turn.
- •
- If a module states an explicit accept, 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.
For instance, take the nested filter module group from above:
[$m1, $m2, [$m3, [$m4, $m5]], $m6]
| | '---g3---'| |
| '----group 2----' |
'------------group 1-------------'
Let's assume Courier::Filter queries the filter module $m3. If $m3 states an
explicit reject, the consideration process is aborted and the current
message is rejected. If $m3 states an
implicit accept, Courier::Filter
proceeds to $m4. If $m3 states an
explicit accept, 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 $m6.
If no
explicit reject has occured when Courier::Filter reaches the end of
the main module group, or a module in the main group states an
explicit
accept, the message is accepted.
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.
- trusting
- A boolean value controlling whether the whole filter process should
not apply any filtering to trusted messages. For details on how the
trusted status is determined, see the description of the
"trusted" property in Courier::Message. In most MTA
configurations, this option can be used to white-list so-called outbound
messages. Defaults to false.
- testing
- A boolean value controlling whether the whole filter process should
run in "testing" mode. In testing mode, planned message
rejections will be logged as usual, but no messages will actually be
rejected. Defaults to false.
NOTE: You may also enable testing mode on individual filter module objects,
see "new" 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 final result, but still follows
the rules of the normal consideration process, e.g. aborting as soon as a
filter module states an explicit reject, etc. When an individual
filter module is in testing mode, its individual 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.
- debugging
- A boolean value controlling whether extra debugging information should be
logged by Courier::Filter. Defaults to false. You need to enable
debugging mode for filter modules separately.
Instance methods¶
The following instance methods are provided:
- 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.
- name: returns string
- Returns the name of the filter process, as set through the constructor's
"name" option.
- mandatory: returns boolean
- Returns a boolean value indicating whether the filter process is a
mandatory courierfilter, as set through the constructor's
"mandatory" option.
- logger: returns Courier::Filter::Logger
- logger($logger): returns Courier::Filter::Logger
- If $logger is specified, installs a new global logger. Returns the (newly)
configured global logger.
- modules: returns array-ref
- modules(\@modules): returns array-ref
- If "\@modules" is specified, installs a new filter module group
structure. Returns the (newly) configured filter modules group
structure.
- trusting: returns boolean
- Returns a boolean value indicating the trusting mode, as set through the
constructor's "trusting" option.
- testing: returns boolean
- Returns a boolean value indicating the global testing mode, as set through
the constructor's "testing" option.
- debugging: returns boolean
- debugging($debugging): returns boolean
- If $debugging is specified, sets the global debugging mode. Returns a
boolean value indicating the (newly) configured global debugging
mode.
SEE ALSO¶
courier-filter-perl, Courier::Filter::Overview, Courier::Filter::Module,
Courier::Filter::Logger
For AVAILABILITY, SUPPORT, and LICENSE information, see
Courier::Filter::Overview.
REFERENCES¶
- The courierfilter interface
- http://www.courier-mta.org/courierfilter.html
<http://www.courier-mta.org/courierfilter.html>
AUTHOR¶
Julian Mehnle <julian@mehnle.net>