<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>courierfilter</title><link rel="stylesheet" href="style.css" type="text/css"/><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"/><link rel="home" href="#id376647" title="courierfilter"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 Double Precision, Inc.  See COPYING for distribution
information.

--></head><body><div class="refentry" title="courierfilter"><a id="id376647" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>courierfilter — Courier mail filters</p></div><div class="refsynopsisdiv" title="Synopsis"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">courierfilter</code>  [[start] |  [stop] |  [restart]]</p></div><div class="cmdsynopsis"><p><code class="command">filterctl</code>  [[start] |  [stop]] [<em class="replaceable"><code>filter</code></em>]</p></div></div><div class="refsect1" title="DESCRIPTION"><a id="id377003" shape="rect"> </a><h2>DESCRIPTION</h2><p>
The <span class="command"><strong>filterctl</strong></span> commands install or uninstall global
mail <em class="replaceable"><code>filter</code></em>s. Global mail filters are used to
selectively block unwanted
mail. More than one mail filter can be enabled at the same time. Two filters -
<a class="ulink" href="dupfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">dupfilter</span>(8)</span></a>
and
<a class="ulink" href="courierperlfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courierperlfilter</span>(8)</span></a> -
are provided as examples for writing mail filters.</p><p>
<span class="command"><strong>courierfilter start</strong></span> runs all mail filters that have been
installed by <span class="command"><strong>filterctl</strong></span>.
<span class="command"><strong>courierfilter stop</strong></span> shuts down all running mail filters.
After <span class="command"><strong>courierfilter start</strong></span>, any
<span class="command"><strong>filterctl</strong></span> commands take effect immediately. After
<span class="command"><strong>courierfilter stop</strong></span> any <span class="command"><strong>filterctl</strong></span>
commands will take
effect at the next <span class="command"><strong>courierfilter start</strong></span>.</p><p>
<span class="command"><strong>courierfilter restart</strong></span> signals the running
<span class="command"><strong>courierfilter</strong></span> to
reread its configuration files. This is normally done automatically, by
<span class="command"><strong>filterctl</strong></span>.</p><p>
If any mail filter is installed, the mail filter must be running in order
for any mail to be processed.  Mail filters are assumed to be empowered to
enforce system-wide mail policies, so if an installed mail filter is not
running then mail will not be accepted by the system.  Note that mail will not
be rejected, if possible.  Every attempt will be made to send a temporary
error code to an external mail system, asking it to try again later.</p><p>
For this reason, you should modify your system boot script to run
<span class="command"><strong>courierfilter start</strong></span> as soon as possible, and run
<span class="command"><strong>courierfilter stop</strong></span> during the final portion of your system
shutdown script. It is not necessary to run <span class="command"><strong>courierfilter</strong></span>
if you do not install a mail filter with <span class="command"><strong>filterctl</strong></span>.</p></div><div class="refsect1" title="MAIL FILTER IMPLEMENTATION"><a id="id376285" shape="rect"> </a><h2>MAIL FILTER IMPLEMENTATION</h2><p>
This section explains how mail filters are implemented, and how to write a
new global mail filter.</p><p>
Available mail filter binaries are located in the directory
<code class="filename">@libexecdir@/filters</code>.
The <span class="command"><strong>filterctl</strong></span> script looks in
this directory to see which mail filters are available to be installed.
Installing a mail filter consists of simply creating a soft link from the
directory <code class="filename">@sysconfdir@/filters/active</code> to its
corresponding binary in <code class="filename">@libexecdir@/filters</code>.
The <code class="filename">courierfilter start</code> command simply reads
<code class="filename">@sysconfdir@/filters/active</code> and runs every
program in this directory.</p><p>
The <span class="command"><strong>filterctl</strong></span> script sends a HUP signal to
<span class="command"><strong>courierfilter</strong></span> after installing or uninstalling a filter.
<span class="command"><strong>courierfilter</strong></span> will reread the contents of
<code class="filename">@sysconfdir@/filters/active</code> then start or stop
individual mail filters.</p><p>
After starting, an individual mail filter must create a filesystem domain
socket in one of two directories:
<code class="filename">@localstatedir@/filters</code> or
<code class="filename">@localstatedir@/allfilters</code>.  The name of the socket
should be the
same as a name of the filter, and the mail filter must make sure to remove any
socket by the same name in the other directory.  For various silly reasons,
the recommended implementation is to create
<code class="filename">@localstatedir@/filters/.<em class="replaceable"><code>NAME</code></em></code> or
<code class="filename">@localstatedir@/allfilters/.<em class="replaceable"><code>NAME</code></em></code>
(after making sure that it doesn't exist) then
rename <em class="replaceable"><code>.NAME</code></em> to
<em class="replaceable"><code>NAME</code></em>.</p><p>
After initializing the socket, the mail filter must then close its file
descriptor #3.  File descriptor 3 is inherited by every mail filter that's
executed by the <span class="command"><strong>courierfilter start</strong></span> command.  The
mail filter's file descriptor 3 is connected to the <span class="emphasis"><em>write</em></span>
end of a pipe, which may be relevant to certain ways of implementing the
closing of the file descriptor, for instance in Perl where you may be forced to
pseudo-open the descriptor (in write mode) before closing it.  The
<span class="command"><strong>courierfilter start</strong></span> command will not exit until every
started
mail filter closes its file descriptor 3.  This allows for all mail filters to
orderly initialize themselves before <span class="command"><strong>courierfilter start</strong></span>
command returns.</p><p>
All mail filters also inherit a pipe on standard input, and must terminate
when the pipe is closed.  Mail filters must simultaneously listen for new
connections on the mail filter socket, and for their standard input to
close.</p><p>
The mail filter receives a new connection on its socket for every message
that needs to be filtered.  After establishing a connection, the mail filter
will immediately read the following information from the new socket:</p><p>
A pathname to a file containing the contents of the message.</p><p>
One or more pathnames to control files for this message.</p><p>
Each pathname is terminated by a single newline character.  The last
pathname is followed by a second newline character.  The pathnames may either
be relative pathnames to <code class="filename">@prefix@</code> or absolute
pathnames, depending on the system configuration.</p><p>
The mail filter is free to judge the message's worthiness by reading its
contents and/or control file(s) as soon as a second consecutive newline
character is received. The final verdict is rendered by writing back a result
code on the same socket. The result code follows the same format as regular
SMTP replies (even though the message may not have been received via SMTP),
and can be used to communicate acceptance, temporary failure, or a permanent
failure. If it's a failure, then the text portion of the result code will be
used, if possible.  The result code may be a multiline response, just like a
regular SMTP reply.  The mail filter must immediately close the connection
after writing the result code.  After closing the socket the mail filter must
then proceed to wait for another connection request on the original listening
socket.</p><p>
The mail filter can be multithreaded or multitasked, and can accept
multiple connections simultaneously.  When its standard input is closed the
mail filter should stop accepting new connections and wait for any existing
connections to be closed, prior to exiting.</p><p>
Global mail filters must be EXTREMELY resilient to runtime failures.  Since
mail will not be processed if an installed mail filter is not running, if a
mail filter crashes it will effectively shut down the mail server.  Currently
<span class="command"><strong>courierfilter</strong></span> does not attempt to restart mail filters which
crash.</p></div><div class="refsect1" title="MAIL FILTER INVOCATION"><a id="id375951" shape="rect"> </a><h2>MAIL FILTER INVOCATION</h2><p>
The system administrator defines what mail gets filtered by editing the
contents of the <code class="filename">enablefiltering</code> configuration file in
<code class="filename">@sysconfdir@</code>.  This configuration file contains a
list of mail sources that should be filtered, like esmtp or local.  See
<a class="ulink" href="courier.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courier</span>(8)</span></a>
for more information.  A default
<code class="filename">@sysconfdir@/enablefiltering</code> file is installed that
specifies
only the <code class="literal">esmtp</code> mail source as subject to filtering.</p><p>
A message is not subject to filtering if its source is not listed in
<code class="filename">@sysconfdir@/enablefiltering</code>.  Otherwise the
following rules apply.</p><p>
Certain mail destinations have the ability to selectively whitelist
arbitrary messages.  For example, local mail recipients have the ability to
selectively whitelist individual messages, provided that a local mail filter
(independent of any global mail filter) is installed that implements the
<a class="ulink" href="localmailfilter.html" target="_top" shape="rect">maildrop filtering API</a>.</p><p>
New messages are filtered by connecting to every socket in
<code class="filename">@localstatedir@/filters</code> and/or
<code class="filename">@localstatedir@/allfilters</code>, one at a time.
All mail filters must
accept the message, for it to be accepted by Courier.  If a socket exists but
a connection cannot be established then the message is not accepted, and a
temporary failure indication is returned. That's why no mail will be accepted
unless all installed mail filters are running.</p><p>
Mail recipients that did not whitelist the sender, via the maildrop API,
will have their mail filtered against everything in
<code class="filename">@localstatedir@/filters</code> and
<code class="filename">@localstatedir@/allfilters</code>.
Mail to recipients that whitelisted
the sender, or mail to destinations that do not use a maildrop API-compatible
filter, will be filtered only against the contents of
<code class="filename">@localstatedir@/allfilters</code>.</p><p>
This gives system administrators a choice whether to install selective, or
mandatory mail filters, or a combination of both.</p></div><div class="refsect1" title="BUGS"><a id="id376065" shape="rect"> </a><h2>BUGS</h2><p>
Many filesystem domain socket implementation are buggy.</p><p>
Handling of crashed mail filters could be improved.</p></div><div class="refsect1" title="FILES"><a id="id376079" shape="rect"> </a><h2>FILES</h2><div class="variablelist"><dl><dt><span class="term"><code class="filename">@libexecdir@/filters</code></span></dt><dd><p>
Available mail filters.</p></dd><dt><span class="term"><code class="filename">@sysconfdir@/filters</code></span></dt><dd><p>
Miscellaneous configuration files.</p></dd><dt><span class="term"><code class="filename">@sysconfdir@/filters/active</code></span></dt><dd><p>
Installed mail filters.</p></dd><dt><span class="term"><code class="filename">@sysconfdir@/enablefiltering</code></span></dt><dd><p>
Which mail sources to filter.</p></dd><dt><span class="term"><code class="filename">@localstatedir@/allfilters</code></span></dt><dd><p>
Mandatory filters.</p></dd><dt><span class="term"><code class="filename">@localstatedir@/filters</code></span></dt><dd><p>
Optional filters.</p></dd></dl></div></div><div class="refsect1" title="SEE ALSO"><a id="id420724" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="localmailfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">localmailfilter</span>(7)</span></a>,
<a class="ulink" href="courier.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courier</span>(8)</span></a>,
<a class="ulink" href="dupfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">dupfilter</span>(8)</span></a>,
<a class="ulink" href="courierperlfilter.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">courierperlfilter</span>(8)</span></a>.</p></div></div></body></html>
