<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on September, 10 2009 by texi2html 1.78 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <texi2html-bug@nongnu.org>
-->
<head>
<title>Exim's interfaces to mail filtering: 1. Forwarding and filtering in Exim</title>
<meta name="description" content="Exim's interfaces to mail filtering: 1. Forwarding and filtering in Exim">
<meta name="keywords" content="Exim's interfaces to mail filtering: 1. Forwarding and filtering in Exim">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.78">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Forwarding-and-filtering-in-Exim"></a>
<a name="SEC1"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC2" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[ << ]</td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h1 class="chapter"> 1. Forwarding and filtering in Exim </h1>
<p>This document describes the user interfaces to Exim's in-built mail filtering
facilities, and is copyright (c) University of Cambridge 2007. It
corresponds to Exim version 4.68.
</p>
<table class="menu" border="0" cellspacing="0">
<tr><td align="left" valign="top"><a href="#SEC2">1.1 Introduction</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC3">1.2 Filter operation</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC4">1.3 Testing a new filter file</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC5">1.4 Installing a filter file</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC6">1.5 Testing an installed filter file</a></td><td> </td><td align="left" valign="top">
</td></tr>
<tr><td align="left" valign="top"><a href="#SEC7">1.6 Details of filtering commands</a></td><td> </td><td align="left" valign="top">
</td></tr>
</table>
<hr size="6">
<a name="Introduction"></a>
<a name="SEC2"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC1" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC3" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.1 Introduction </h2>
<p>Most Unix mail transfer agents (programs that deliver mail) permit individual
users to specify automatic forwarding of their mail, usually by placing a list
of forwarding addresses in a file called ‘<tt>.forward</tt>’ in their home
directories. Exim extends this facility by allowing the forwarding instructions
to be a set of rules rather than just a list of addresses, in effect providing
"‘<tt>.forward</tt>’ with conditions". Operating the set of rules is called
<em>filtering</em>, and the file that contains them is called a <em>filter file</em>.
</p>
<p>Exim supports two different kinds of filter file. An <em>Exim filter</em> contains
instructions in a format that is unique to Exim. A <em>Sieve filter</em> contains
instructions in the Sieve format that is defined by RFC 3028. As this is a
standard format, Sieve filter files may already be familiar to some users.
Sieve files should also be portable between different environments. However,
the Exim filtering facility contains more features (such as variable
expansion), and better integration with the host environment (such as the use
of external processes and pipes).
</p>
<p>The choice of which kind of filter to use can be left to the end-user, provided
that the system administrator has configured Exim appropriately for both kinds
of filter. However, if interoperability is important, Sieve is the only
choice.
</p>
<p>The ability to use filtering or traditional forwarding has to be enabled by the
system administrator, and some of the individual facilities can be separately
enabled or disabled. A local document should be provided to describe exactly
what has been enabled. In the absence of this, consult your system
administrator.
</p>
<p>This document describes how to use a filter file and the format of its
contents. It is intended for use by end-users. Both Sieve filters and Exim
filters are covered. However, for Sieve filters, only issues that relate to the
Exim implementation are discussed, since Sieve itself is described elsewhere.
</p>
<p>The contents of traditional ‘<tt>.forward</tt>’ files are not described here. They
normally contain just a list of addresses, file names, or pipe commands,
separated by commas or newlines, but other types of item are also available.
The full details can be found in the chapter on the <code>redirect</code> router in the
Exim specification, which also describes how the system administrator can set
up and control the use of filtering.
</p>
<hr size="6">
<a name="Filter-operation"></a>
<a name="SEC3"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC2" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC4" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.2 Filter operation </h2>
<p>It is important to realize that, in Exim, no deliveries are actually made while
a filter or traditional ‘<tt>.forward</tt>’ file is being processed. Running a filter
or processing a traditional ‘<tt>.forward</tt>’ file sets up future delivery
operations, but does not carry them out.
</p>
<p>The result of filter or ‘<tt>.forward</tt>’ file processing is a list of destinations
to which a message should be delivered. The deliveries themselves take place
later, along with all other deliveries for the message. This means that it is
not possible to test for successful deliveries while filtering. It also means
that any duplicate addresses that are generated are dropped, because Exim never
delivers the same message to the same address more than once.
</p>
<hr size="6">
<a name="Testing-a-new-filter-file"></a>
<a name="SEC4"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC3" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC5" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.3 Testing a new filter file </h2>
<p>Filter files, especially the more complicated ones, should always be tested, as
it is easy to make mistakes. Exim provides a facility for preliminary testing
of a filter file before installing it. This tests the syntax of the file and
its basic operation, and can also be used with traditional ‘<tt>.forward</tt>’ files.
</p>
<p>Because a filter can do tests on the content of messages, a test message is
required. Suppose you have a new filter file called ‘<tt>myfilter</tt>’ and a test
message in a file called ‘<tt>test-message</tt>’. Assuming that Exim is installed with
the conventional path name ‘<tt>/usr/sbin/sendmail</tt>’ (some operating systems use
‘<tt>/usr/lib/sendmail</tt>’), the following command can be used:
</p>
<table><tr><td> </td><td><pre class="example">/usr/sbin/sendmail -bf myfilter <test-message
</pre></td></tr></table>
<p>The <code>-bf</code> option tells Exim that the following item on the command line is
the name of a filter file that is to be tested. There is also a <code>-bF</code> option,
which is similar, but which is used for testing system filter files, as opposed
to user filter files, and which is therefore of use only to the system
administrator.
</p>
<p>The test message is supplied on the standard input. If there are no
message-dependent tests in the filter, an empty file (‘<tt>/dev/null</tt>’) can be
used. A supplied message must start with header lines or the "From" message
separator line that is found in many multi-message folder files. Note that
blank lines at the start terminate the header lines. A warning is given if no
header lines are read.
</p>
<p>The result of running this command, provided no errors are detected in the
filter file, is a list of the actions that Exim would try to take if presented
with the message for real. For example, for an Exim filter, the output
</p>
<table><tr><td> </td><td><pre class="example">Deliver message to: gulliver@lilliput.fict.example
Save message to: /home/lemuel/mail/archive
</pre></td></tr></table>
<p>means that one copy of the message would be sent to
<em>gulliver@lilliput.fict.example</em>, and another would be added to the file
‘<tt>/home/lemuel/mail/archive</tt>’, if all went well.
</p>
<p>The actions themselves are not attempted while testing a filter file in this
way; there is no check, for example, that any forwarding addresses are valid.
For an Exim filter, if you want to know why a particular action is being taken,
add the <code>-v</code> option to the command. This causes Exim to output the results of
any conditional tests and to indent its output according to the depth of
nesting of <code>if</code> commands. Further additional output from a filter test can be
generated by the <code>testprint</code> command, which is described below.
</p>
<p>When Exim is outputting a list of the actions it would take, if any text
strings are included in the output, non-printing characters therein are
converted to escape sequences. In particular, if any text string contains a
newline character, this is shown as "\n" in the testing output.
</p>
<p>When testing a filter in this way, Exim makes up an "envelope" for the
message. The recipient is by default the user running the command, and so is
the sender, but the command can be run with the <code>-f</code> option to supply a
different sender. For example,
</p>
<table><tr><td> </td><td><pre class="example">/usr/sbin/sendmail -bf myfilter \
-f islington@never.where <test-message
</pre></td></tr></table>
<p>Alternatively, if the <code>-f</code> option is not used, but the first line of the
supplied message is a "From" separator from a message folder file (not the
same thing as a <em>From:</em> header line), the sender is taken from there. If
<code>-f</code> is present, the contents of any "From" line are ignored.
</p>
<p>The "return path" is the same as the envelope sender, unless the message
contains a <em>Return-path:</em> header, in which case it is taken from there. You
need not worry about any of this unless you want to test out features of a
filter file that rely on the sender address or the return path.
</p>
<p>It is possible to change the envelope recipient by specifying further options.
The <code>-bfd</code> option changes the domain of the recipient address, while the
<code>-bfl</code> option changes the "local part", that is, the part before the @
sign. An adviser could make use of these to test someone else's filter file.
</p>
<p>The <code>-bfp</code> and <code>-bfs</code> options specify the prefix or suffix for the local
part. These are relevant only when support for multiple personal mailboxes is
implemented; see the description in section <a href="filter_3.html#SEC52">Multiple personal mailboxes</a> below.
</p>
<hr size="6">
<a name="Installing-a-filter-file"></a>
<a name="SEC5"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC4" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC6" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.4 Installing a filter file </h2>
<p>A filter file is normally installed under the name ‘<tt>.forward</tt>’ in your home
directory - it is distinguished from a conventional ‘<tt>.forward</tt>’ file by its
first line (described below). However, the file name is configurable, and some
system administrators may choose to use some different name or location for
filter files.
</p>
<hr size="6">
<a name="Testing-an-installed-filter-file"></a>
<a name="SEC6"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC5" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="#SEC7" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.5 Testing an installed filter file </h2>
<p>Testing a filter file before installation cannot find every potential problem;
for example, it does not actually run commands to which messages are piped.
Some "live" tests should therefore also be done once a filter is installed.
</p>
<p>If at all possible, test your filter file by sending messages from some other
account. If you send a message to yourself from the filtered account, and
delivery fails, the error message will be sent back to the same account, which
may cause another delivery failure. It won't cause an infinite sequence of such
messages, because delivery failure messages do not themselves generate further
messages. However, it does mean that the failure won't be returned to you, and
also that the postmaster will have to investigate the stuck message.
</p>
<p>If you have to test an Exim filter from the same account, a sensible precaution
is to include the line
</p>
<table><tr><td> </td><td><pre class="example">if error_message then finish endif
</pre></td></tr></table>
<p>as the first filter command, at least while testing. This causes filtering to
be abandoned for a delivery failure message, and since no destinations are
generated, the message goes on to be delivered to the original address. Unless
there is a good reason for not doing so, it is recommended that the above test
be left in all Exim filter files. (This does not apply to Sieve files.)
</p>
<hr size="6">
<a name="Details-of-filtering-commands"></a>
<a name="SEC7"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC6" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="#SEC1" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<h2 class="section"> 1.6 Details of filtering commands </h2>
<p>The filtering commands for Sieve and Exim filters are completely different in
syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next
chapter we describe how it is integrated into Exim. The subsequent chapter
covers Exim filtering commands in detail.
</p>
<hr size="6">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="#SEC1" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="filter_2.html#SEC8" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="filter.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[Contents]</td>
<td valign="middle" align="left">[Index]</td>
<td valign="middle" align="left">[<a href="filter_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated on <i>September, 10 2009</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.78</i></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
a4080654d049ad31b216b761b9173c1f
>
files
>
104
