Provided by: courier-filter-perl_0.200+ds-4_all 
NAME
Courier::Filter::Overview - Architectural and administrative overview of Courier::Filter
DESCRIPTION
Courier::Filter is a purely Perl-based mail filter framework for the Courier MTA.
The Courier MTA's courierfilter interface
Courier offers an interface for daemon-style processes to act as mail filters, called
courierfilters. For every incoming mail message, right after the DATA command in the SMTP
transaction phase has completed, Courier calls every registered mail filter through a UNIX
domain socket the filter is listening on, and feeds it the file names of the incoming
message and one or more control files. The mail filter processes the message and its
control file(s), and returns an SMTP-style status response. If the status response is a
positive ("2xx") one, Courier accepts the message. Otherwise, Courier rejects the message
using the returned response code and text. For details about the courierfilter interface,
see courierfilter.
About Courier::Filter
Courier::Filter implements the courierfilter interface as a framework for mail filter
modules that frees modules from the duties of creating and handling the UNIX domain
sockets, waiting for connections from Courier, and reading and parsing message and control
files. Thus, authors of filter modules can concentrate on writing the actual filter logic
without having to care about things that can easily be abstracted and can be performed by
the framework.
Courier::Filter allows multiple filter modules to be installed, and filter modules can be
stacked and grouped hierarchically, and even a module's polarity can be reversed, so some
modules can be used for explicitly accepting messages while others are used in the
traditional way for rejecting messages.
Courier::Filter compared to other courierfilter implementations
There are some alternative implementations of the courierfilter interface:
Writing your own standalone courierfilter
If you need an ultra-high performance mail filter, writing a standalone courierfilter
in C/C++ is a good choice. You will have maximum freedom for optimizing your filter
for performance and resource consumption. But regardless of which language you use,
you will have to implement all the UNIX domain socket and connection handling and
message and control file processing yourself. And you don't get the modularity and
module grouping capabilities for free either.
courierperlfilter
Courier brings a sample Perl-based courierfilter called courierperlfilter. It is a C
executable that employs Perl embedding (see perlembed) to execute a Perl script for
every incoming message, which is about as performant as the purely Perl-based
Courier::Filter. But for every Perl-based courierfilter you want to run, you have to
use a separate instance of courierperlfilter, or implement your own modularity and
module grouping. Also, the included template Perl script is not very modular in
itself, and Courier::Filter's message and control file parsing features are missing.
pythonfilter
pythonfilter by Gordon Messmer is a purely Python-based, modular, threaded
courierfilter framework, similar to Courier::Filter. If you primarily speak Python,
this is clearly your choice. pythonfilter also provides infrastructure to filter
modules for modifying messages, even with versions of Courier prior to 0.57.1, which
did not directly allow global mail filters to modify messages. As of version 1.1,
pythonfilter supports only a linear topology in the configuration of its filter
modules.
Using Courier::Filter
First, Courier::Filter (of course) and the filter modules that you plan to use for
filtering your incoming mail need to be installed somewhere in your Perl include path (see
the last lines of `perl -V`). You may also need to adjust the Courier::Config class (in
"Courier/Config.pm") to reflect your system's paths. As for the filter modules, you can
either use prepared ones (see "Bundled Courier::Filter modules" for a list of modules that
come with Courier::Filter), or you can write your own (see "How filter modules work").
Second, you need to create a configuration file for Courier::Filter. Courier::Filter
usually seeks for it at "/etc/courier/filters/courier-filter-perl.conf" (see
Courier::Config on how to configure that). This file is a Perl snippet that must "use"
the filter modules you want to use, and then fill in the $options global variable with the
desired configuration options, instantiating filter modules and loggers as required.
If you plan to use non-ASCII string literals in your configuration file, it should be
encoded in UTF-8 (which is the native internal character encoding of Perl 5.8+ and
Courier::Filter), and if it is, it must do "use utf8". (It is possible for the
configuration file to be encoded differently, but you still must explicitly specify the
used encoding, see encoding for how to do that.)
For example, this is how a simple configuration file could look like:
use utf8;
use Courier::Filter::Logger::File;
use Courier::Filter::Module::Header;
$options = {
logger => Courier::Filter::Logger::File->new(
file_name => '/var/log/courier-filter-perl.log',
timestamp => 1
},
modules => [
Courier::Filter::Module::Header->new(
fields => {
subject => qr/fuzzybuzzy/
},
response => 'No fuzzybuzzy, please!'
)
]
};
These options will be used when creating the "Courier::Filter" object. For a detailed
explanation of supported configuration options and how filter modules can be grouped, even
hierarchically, see "new()" in Courier::Filter.
Third, you need to make Courier aware of Courier::Filter by installing a symlink in
"/etc/courier/filters/active/" pointing to the "courier-filter-perl" executable (which is
used for bootstrapping Courier::Filter):
$ ln -s $PATH_TO/courier-filter-perl /etc/courier/filters/active/
Finally, you may start (or restart) Courier::Filter (including any other installed
courierfilters; Courier must of course already be running):
$ sudo courierfilter restart
In syslog, you should see the following message and no further error messages:
Jan 24 01:42:15 yourhost courierfilter: Starting courier-filter-perl
Any errors occurring while Courier::Filter is running will appear in syslog as well. A
broken filter module will not crash Courier::Filter, but will record any Perl error
messages in syslog, and reject incoming mail messages with a temporary status code, so as
not to enable attackers to circumvent the configured Courier::Filter mail filtering.
How filter modules work
Filter modules are Perl classes that are derived from the class Courier::Filter::Module.
See perlobj for an explanation of Perl's object orientation features.
Filter modules are to be instantiated in the "courier-filter-perl.conf" configuration
file, with either normal polarity (the default) or inverse polarity. Then, for every
incoming mail message, Courier::Filter asks each configured filter module in turn for
consideration of the message's acceptability.
Every module tries to match its filter criteria against the current message, yielding a
so-called match result, which can be either an explicit match, an implicit mismatch, or an
explicit mismatch. (Filter modules usually never return an explicit mismatch, but only an
implicit one; see "Writing filter modules" if you want to know why.)
According to the filter module's polarity, the match result is then translated into a so-
called acceptability result, which can be either an explicit reject, an implicit accept,
or an explicit accept.
This is how match results are translated into acceptability results under normal and
inverse polarity:
polarity | match result | acceptability result
----------+-------------------+----------------------
| explicit match | explicit reject
normal | implicit mismatch | implicit accept
| explicit mismatch | explicit accept
----------+-------------------+----------------------
| explicit match | explicit accept
inverse | implicit mismatch | implicit accept
| explicit mismatch | explicit reject
Generally, Courier::Filter interprets the acceptability result as follows:
• If a module states an explicit reject for the current message, Courier::Filter aborts
the consideration process and rejects the message.
• If a module states an implicit accept, Courier::Filter continues the consideration
process with the next module in turn.
• If a module states an explicit accept, Courier::Filter skips the rest of the group of
modules and assumes the whole group to be an implicit accept.
If no explicit reject has occured when Courier::Filter finishes asking all filter modules,
the message is accepted.
(For details on how to use advanced filter module grouping, see the description of the
"modules" option in "new()" in Courier::Filter.)
Abstracting the concept of a "match" from the concept of "acceptance" makes it possible to
use filter modules with normal polarity for "black-listing" certain message
characteristics, and filter modules with inverse polarity for "white-listing", while still
allowing all modules to be written in a uniform sense of logic. That is, there are no
dedicated "accepting" and "rejecting" modules, but only "matching" modules. (E.g. there
are no "HeaderAccept" and "HeaderReject" modules, but only a "Header" module.)
Writing filter modules
The main objective of Courier::Filter is to make it very easy to write new filter modules,
so while the previous section described how filter modules work in general, we will now
look at the details of writing your own filter modules. From here on you really should
know what you are doing, so if you are not familiar with Perl's object orientation
features, now is the time to read perlobj plus any documents referenced from there.
As already mentioned, filter modules are Perl classes derived from the class
Courier::Filter::Module, which is an abstract base class and thus cannot be instantiated
itself.
To ask a filter module for consideration of the message, Courier::Filter calls
"$module->consider()", passing a Courier::Message object. "$module->consider()" (if not
overrided from Courier::Filter::Module) then calls "$module->match()", passing through the
message object.
The "match()" method really is where a filter module decides whether a message matches the
filter criteria, and this is usually the only method of Courier::Filter::Module that needs
to be overrided. That method may use any configuration information from the filter module
object (see Courier::Filter::Module, and of course your own class), and any information
from the message object (see Courier::Message).
If a filter module wants to call external commands using "system()", or functions from
Perl modules that directly operate on files, it can efficiently bypass the message and
control files processing features of Courier::Message by using the message object's
"control_file_names" and "file_name" properties only.
Finally, after the message has been examined, "match()" must return a match result of...
true
if the module wants to state an explicit match (the first return value being the SMTP
status response text, an optional second one being the SMTP status response code),
undef
if the module wants to state an implicit mismatch, that is, indifference of whether
the message should be accepted or rejected,
false
if the module wants to state an explicit mismatch.
"consider()" then translates the match result into a acceptability result as described in
"How filter modules work".
"match()" should usually never return an explicit mismatch (false), but an implicit one
(undef) instead for the message to pass this filter module, while still allowing any
further modules to explicitly reject (under normal polarity) or accept (under inverse
polarity) the message. See the description of the "modules" option in "new()" in
Courier::Filter for specifics on how Courier::Filter uses acceptability results.
A sample HeaderSimple filter module
Now let's see in practice how to write a simple filter module. For instance, we will
create a simple variant of the "Header" module that matches a specified message header
field against a specified string. Let's call it "HeaderSimple".
First, we create a Perl module for the class Courier::Filter::Module::HeaderSimple, with
the file name "Courier/Filter/Module/HeaderSimple.pm". (That is, you need to install the
file "HeaderSimple.pm" in the proper place in your Perl include path.)
Second, in that Perl module, we state the package/class name, and the name of the base
class, which is usually Courier::Filter::Module:
package Courier::Filter::Module::HeaderSimple;
use base qw(Courier::Filter::Module);
Third, we override the "match()" method by defining a rudimentary "match" sub:
sub match {
my ($self, $message) = @_;
# ...
}
The first argument of the "match()" method is (as usual in Perl's object orientation
model) the module object itself, which provides access to its configuration options. The
second argument is the message object that is to be examined. The ellipsis ("...") is
where we will place our own filter logic.
Now, we expect our module to be instantiated like this:
Courier::Filter::Module::HeaderSimple->new(
field => 'subject',
value => 'viagra',
response => 'Go away, spammer!'
)
which makes the configuration options available from the hash keys "$self->{field}",
"$self->{value}", and "$self->{response}".
We want to test whether the configured header field of the message matches the configured
value, and if so, return the configured response, so we write:
return $self->{response}
if $message->header($self->{field}) =~ m/\Q$self->{value}\E/;
return undef;
# otherwise.
That's it. This is how the complete filter module looks like:
package Courier::Filter::Module::HeaderSimple;
use base qw(Courier::Filter::Module);
sub match {
my ($self, $message) = @_;
return $self->{response}
if $message->header($self->{field}) =~ m/\Q$self->{value}\E/;
return undef;
# otherwise.
}
Testing Courier::Filter modules
You may dry-test filter modules using the "test-filter-module" utility. See its manpage
for details.
You may also switch any or all installed filter modules into "testing" mode so you can
test them without risking messages being actually rejected. See "new()" in
Courier::Filter and "new()" in Courier::Filter::Module.
Bundled Courier::Filter modules
The following prepared filter modules are included with this version of Courier::Filter:
BlankBody
Detection of messages with blank bodies (symptom of stupid spammers)
DNSBL
Checking of the calling MTA's IP address against one or more DNS black-lists
SPF SPF (Sender Policy Framework) authorization checking of the calling MTA's IP address
against the envelope sender domain (classic inbound SPF checking)
SPFout
SPF authorization checking of the local system's IP address against the envelope
sender domain (so-called outbound SPF checking)
Envelope
Literal and reg-exp matching of one or more RFC 2821 message envelope fields
Header
Literal and reg-exp matching of one or more RFC 2822 message header fields
FakeDate
Detection of implausible and malformed "Date" and "Resent-Date" header fields
ClamAVd
Malware detection using the ClamAV anti-virus scanner
SpamAssassin
Spam detection using SpamAssassin
Parts
MIMEParts (DEPRECATED)
Size and MD5 sum matching of message (MIME multipart and ZIP archive) parts
SendCopy
Pseudo-filter for sending message copies to additional recipients
Bundled Courier::Filter loggers
The following prepared loggers are included with this version of Courier::Filter:
IOHandle
Logging to I/O handles
Syslog
Logging to syslog (based on the IOHandle logger)
File
Logging to files (based on the IOHandle logger)
SEE ALSO
courier-filter-perl, test-filter-module, Courier::Filter, Courier::Filter::Module,
Courier::Message, Courier::Config
REFERENCES
The courierfilter interface
<http://www.courier-mta.org/courierfilter.html>
courierperlfilter
<http://www.courier-mta.org/courierperlfilter.html>
pythonfilter
<http://phantom.dragonsdawn.net/~gordon/courier-patches/courier-pythonfilter/>
AVAILABILITY and SUPPORT
The latest version of Courier::Filter is available on CPAN and at
<http://www.mehnle.net/software/courier-filter>.
Support is usually (but not guaranteed to be) given by the author, Julian Mehnle
<julian@mehnle.net>, preferably through the Courier MTA's courier-users mailing list
<courier-users@lists.sourceforge.net>, which is subscribable through
<http://lists.sourceforge.net/lists/listinfo/courier-users>.
AUTHOR and LICENSE
Courier::Filter is Copyright (C) 2003-2008 Julian Mehnle <julian@mehnle.net>. All rights
reserved.
Courier::Filter is free software. You may use, modify, and distribute it under the same
terms as Perl itself, i.e. under the GNU GPL or the Artistic License.