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

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>

AUTHOR

       Julian Mehnle <julian@mehnle.net>