<!DOCTYPE html PUBLIC "XSLT-compat"> <html lang="en-GB"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> <link rel="stylesheet" type="text/css" href="../../../../common.css"> <meta name="author" content="The Exim Project. <http://www.exim.org/>"> <meta name="copyright" content="Copyright ©2010 The Exim Project. All rights reserved"> <meta name="description" content="Exim is a message transfer agent (MTA) developed at the University of Cambridge for use on Unix systems connected to the Internet."> <meta name="keywords" content="exim,smtp,mta,email"> <meta name="robots" content="noodp,noydir,index,follow"> <meta name="viewport" content="width=device-width"> <title>1. Forwarding and filtering in Exim</title> <link rel="stylesheet" type="text/css" href="../../../../doc/chapter.css"> <link rel="canonical" href="http://www.exim.org/exim-html-current/doc/html/spec_html/filter_ch01.html"> </head> <body> <h1 id="header"><a href="../../../..">Exim Internet Mailer</a></h1> <div id="outer"> <ul id="nav_flow" class="nav"> <li><a href="../../../../index.html">Home</a></li> <li><a href="../../../../mirrors.html">Download</a></li> <li><a href="../../../../docs.html">Documentation</a></li> <li><a href="../../../../maillist.html">Mailing Lists</a></li> <li><a href="http://wiki.exim.org/">Wiki</a></li> <li><a href="http://www.exim.org/bugzilla/">Bugs</a></li> <li><a href="../../../../credits.html">Credits</a></li> <li class="search"><form action="http://www.google.com/search" method="get"> <span class="search_field_container"><input type="search" name="q" placeholder="Search Docs" class="search_field"></span><input type="hidden" name="hl" value="en"><input type="hidden" name="ie" value="UTF-8"><input type="hidden" name="as_qdr" value="all"><input type="hidden" name="q" value="site:www.exim.org"><input type="hidden" name="q" value="inurl:exim-html-current"> </form></li> </ul> <div id="inner"><div id="content"> <a class="previous_page" href="filter.html"><-previous</a><a class="next_page" href="filter_ch02.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPforandfilt" class="">Chapter 1 - Forwarding and filtering in Exim</h2> <p> This document describes the user interfaces to Exim’s in-built mail filtering facilities, and is copyright © University of Cambridge 2007. It corresponds to Exim version 4.73. </p> <div class="section"> <h3 id="SEC00" class="">1. Introduction</h3> <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 <span class="docbook_filename">.forward</span> 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 “<span class="docbook_filename">.forward</span> with conditions”. Operating the set of rules is called <span class="docbook_emphasis">filtering</span>, and the file that contains them is called a <span class="docbook_emphasis">filter file</span>. </p> <p> Exim supports two different kinds of filter file. An <span class="docbook_emphasis">Exim filter</span> contains instructions in a format that is unique to Exim. A <span class="docbook_emphasis">Sieve filter</span> 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 <span class="docbook_filename">.forward</span> 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 <span class="docbook_command">redirect</span> router in the Exim specification, which also describes how the system administrator can set up and control the use of filtering. </p> </div> <div class="section"> <h3 id="SEC01" class="">2. Filter operation</h3> <p> It is important to realize that, in Exim, no deliveries are actually made while a filter or traditional <span class="docbook_filename">.forward</span> file is being processed. Running a filter or processing a traditional <span class="docbook_filename">.forward</span> file sets up future delivery operations, but does not carry them out. </p> <p> The result of filter or <span class="docbook_filename">.forward</span> 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> </div> <div class="section"> <h3 id="SECTtesting" class="">3. Testing a new filter file</h3> <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 <span class="docbook_filename">.forward</span> 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 <span class="docbook_filename">myfilter</span> and a test message in a file called <span class="docbook_filename">test-message</span>. Assuming that Exim is installed with the conventional path name <span class="docbook_filename">/usr/sbin/sendmail</span> (some operating systems use <span class="docbook_filename">/usr/lib/sendmail</span>), the following command can be used: </p> <div class="docbook_literallayout"><pre> /usr/sbin/sendmail -bf myfilter <test-message </pre></div> <p> The <span class="docbook_option">-bf</span> 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 <span class="docbook_option">-bF</span> 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 (<span class="docbook_filename">/dev/null</span>) 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> <div class="docbook_literallayout"><pre> Deliver message to: gulliver@lilliput.fict.example Save message to: /home/lemuel/mail/archive </pre></div> <p> means that one copy of the message would be sent to <span class="docbook_emphasis">gulliver@lilliput.fict.example</span>, and another would be added to the file <span class="docbook_filename">/home/lemuel/mail/archive</span>, 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 <span class="docbook_option">-v</span> 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 <span class="docbook_command">if</span> commands. Further additional output from a filter test can be generated by the <span class="docbook_command">testprint</span> 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 <span class="docbook_option">-f</span> option to supply a different sender. For example, </p> <div class="docbook_literallayout"><pre> /usr/sbin/sendmail -bf myfilter \ -f islington@never.where <test-message </pre></div> <p> Alternatively, if the <span class="docbook_option">-f</span> 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 <span class="docbook_emphasis">From:</span> header line), the sender is taken from there. If <span class="docbook_option">-f</span> 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 <span class="docbook_emphasis">Return-path:</span> 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 <span class="docbook_option">-bfd</span> option changes the domain of the recipient address, while the <span class="docbook_option">-bfl</span> 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 <span class="docbook_option">-bfp</span> and <span class="docbook_option">-bfs</span> 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_ch03.html#SECTmbox" title="3. Exim filter files">3.31</a> below. </p> </div> <div class="section"> <h3 id="SEC02" class="">4. Installing a filter file</h3> <p> A filter file is normally installed under the name <span class="docbook_filename">.forward</span> in your home directory – it is distinguished from a conventional <span class="docbook_filename">.forward</span> 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> </div> <div class="section"> <h3 id="SEC03" class="">5. Testing an installed filter file</h3> <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> <div class="docbook_literallayout"><pre> if error_message then finish endif </pre></div> <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> </div> <div class="section"> <h3 id="SEC04" class="">6. Details of filtering commands</h3> <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> </div> </div> <a class="previous_page" href="filter.html"><-previous</a><a class="next_page" href="filter_ch02.html">next-></a> </div></div> <iframe id="branding" name="branding" src="../../../../branding/branding.html" height="0" frameborder="no" scrolling="no"></iframe><div id="footer">Website design by <a href="https://secure.grepular.com/">Mike Cardwell</a>, of <a href="http://cardwellit.com/">Cardwell IT Ltd.</a> </div> <div class="left_bar"></div> <div class="right_bar"></div> <div id="toc"> <ul class="hidden"></ul> <img src="../../../../doc/contents.png" width="16" height="155"> </div> </div> <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.4/jquery.min.js"></script><script type="text/javascript" src="../../../../common.js"></script><script type="text/javascript" src="../../../../doc/chapter.js"></script> </body> </html>
