Ubuntu Manpage: Courier::Filter - Purely Perl-based mail filter framework for the Courier MTA

Provided by: courier-filter-perl_0.200+ds-4_all

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:

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.

REFERENCES

       The courierfilter interface
           <http://www.courier-mta.org/courierfilter.html>

AUTHOR