<!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>2. Sieve filter files</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_ch02.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_ch01.html"><-previous</a><a class="next_page" href="filter_ch03.html">next-></a><div id="chapter" class="chapter"> <h2 id="CHAPsievefilter" class="">Chapter 2 - Sieve filter files</h2> <p> The code for Sieve filtering in Exim was contributed by Michael Haardt, and most of the content of this chapter is taken from the notes he provided. Since Sieve is an extensible language, it is important to understand “Sieve” in this context as “the specific implementation of Sieve for Exim”. </p> <p> This chapter does not contain a description of Sieve, since that can be found in RFC 3028, which should be read in conjunction with these notes. </p> <p> The Exim Sieve implementation offers the core as defined by RFC 3028, comparison tests, the subaddress parameter, the <span class="docbook_emphasis">copy</span>, <span class="docbook_emphasis">envelope</span>, <span class="docbook_emphasis">fileinto</span>, <span class="docbook_emphasis">notify</span>, and <span class="docbook_emphasis">vacation</span> extensions, but not the <span class="docbook_emphasis">reject</span> extension. Exim does not support message delivery notifications (MDNs), so adding it just to the Sieve filter (as required for <span class="docbook_emphasis">reject</span>) makes little sense. </p> <p> In order for Sieve to work properly in Exim, the system administrator needs to make some adjustments to the Exim configuration. These are described in the chapter on the <span class="docbook_command">redirect</span> router in the full Exim specification. </p> <div class="section"> <h3 id="SEC05" class="">1. Recognition of Sieve filters</h3> <p> A filter file is interpreted as a Sieve filter if its first line is </p> <div class="docbook_literallayout"><pre> # Sieve filter </pre></div> <p> This is what distinguishes it from a conventional <span class="docbook_filename">.forward</span> file or an Exim filter file. </p> </div> <div class="section"> <h3 id="SEC06" class="">2. Saving to specified folders</h3> <p> If the system administrator has set things up as suggested in the Exim specification, and you use <span class="docbook_command">keep</span> or <span class="docbook_command">fileinto</span> to save a mail into a folder, absolute files are stored where specified, relative files are stored relative to $home, and <span class="docbook_filename">inbox</span> goes to the standard mailbox location. </p> </div> <div class="section"> <h3 id="SEC07" class="">3. Strings containing header names</h3> <p> RFC 3028 does not specify what happens if a string denoting a header field does not contain a valid header name, for example, it contains a colon. This implementation generates an error instead of ignoring the header field in order to ease script debugging, which fits in with the common picture of Sieve. </p> </div> <div class="section"> <h3 id="SEC08" class="">4. Exists test with empty list of headers</h3> <p> The <span class="docbook_emphasis">exists</span> test succeeds only if all the specified headers exist. RFC 3028 does not explicitly specify what happens on an empty list of headers. This implementation evaluates that condition as true, interpreting the RFC in a strict sense. </p> </div> <div class="section"> <h3 id="SEC09" class="">5. Header test with invalid MIME encoding in header</h3> <p> Some MUAs process invalid base64 encoded data, generating junk. Others ignore junk after seeing an equal sign in base64 encoded data. RFC 2047 does not specify how to react in this case, other than stating that a client must not forbid to process a message for that reason. RFC 2045 specifies that invalid data should be ignored (apparently looking at end of line characters). It also specifies that invalid data may lead to rejecting messages containing them (and there it appears to talk about true encoding violations), which is a clear contradiction to ignoring them. </p> <p> RFC 3028 does not specify how to process incorrect MIME words. This implementation treats them literally, as it does if the word is correct but its character set cannot be converted to UTF-8. </p> </div> <div class="section"> <h3 id="SEC10" class="">6. Address test for multiple addresses per header</h3> <p> A header may contain multiple addresses. RFC 3028 does not explicitly specify how to deal with them, but since the address test checks if anything matches anything else, matching one address suffices to satisfy the condition. That makes it impossible to test if a header contains a certain set of addresses and no more, but it is more logical than letting the test fail if the header contains an additional address besides the one the test checks for. </p> </div> <div class="section"> <h3 id="SEC11" class="">7. Semantics of keep</h3> <p> The <span class="docbook_command">keep</span> command is equivalent to </p> <div class="docbook_literallayout"><pre> fileinto "inbox"; </pre></div> <p> It saves the message and resets the implicit keep flag. It does not set the implicit keep flag; there is no command to set it once it has been reset. </p> </div> <div class="section"> <h3 id="SEC12" class="">8. Semantics of fileinto</h3> <p> RFC 3028 does not specify whether <span class="docbook_command">fileinto</span> should try to create a mail folder if it does not exist. This implementation allows the sysadmin to configure that aspect using the <span class="docbook_command">appendfile</span> transport options <span class="docbook_option">create_directory</span>, <span class="docbook_option">create_file</span>, and <span class="docbook_option">file_must_exist</span>. See the <span class="docbook_command">appendfile</span> transport in the Exim specification for details. </p> </div> <div class="section"> <h3 id="SEC13" class="">9. Semantics of redirect</h3> <p> Sieve scripts are supposed to be interoperable between servers, so this implementation does not allow mail to be redirected to unqualified addresses, because the domain would depend on the system being used. On systems with virtual mail domains, the default domain is probably not what the user expects it to be. </p> </div> <div class="section"> <h3 id="SEC14" class="">10. String arguments</h3> <p> There has been confusion if the string arguments to <span class="docbook_command">require</span> are to be matched case-sensitively or not. This implementation matches them with the match type <span class="docbook_command">:is</span> (default, see section 2.7.1 of the RFC) and the comparator <span class="docbook_command">i;ascii-casemap</span> (default, see section 2.7.3 of the RFC). The RFC defines the command defaults clearly, so any different implementations violate RFC 3028. The same is valid for comparator names, also specified as strings. </p> </div> <div class="section"> <h3 id="SEC15" class="">11. Number units</h3> <p> There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte. The mistake is obvious, because RFC 3028 specifies G to denote 2^30 (which is gibi, not tebi), and that is what this implementation uses as the scaling factor for the suffix G. </p> </div> <div class="section"> <h3 id="SEC16" class="">12. RFC compliance</h3> <p> Exim requires the first line of a Sieve filter to be </p> <div class="docbook_literallayout"><pre> # Sieve filter </pre></div> <p> Of course the RFC does not specify that line. Do not expect examples to work without adding it, though. </p> <p> RFC 3028 requires the use of CRLF to terminate a line. The rationale was that CRLF is universally used in network protocols to mark the end of the line. This implementation does not embed Sieve in a network protocol, but uses Sieve scripts as part of the Exim MTA. Since all parts of Exim use LF as the newline character, this implementation does, too, by default, though the system administrator may choose (at Exim compile time) to use CRLF instead. </p> <p> Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so this implementation repeats this violation to stay consistent with Exim. This is in preparation for UTF-8 data. </p> <p> Sieve scripts cannot contain NUL characters in strings, but mail headers could contain MIME encoded NUL characters, which could never be matched by Sieve scripts using exact comparisons. For that reason, this implementation extends the Sieve quoted string syntax with \0 to describe a NUL character, violating \0 being the same as 0 in RFC 3028. Even without using \0, the following tests are all true in this implementation. Implementations that use C-style strings will only evaluate the first test as true. </p> <div class="docbook_literallayout"><pre> Subject: =?iso-8859-1?q?abc=00def header :contains "Subject" ["abc"] header :contains "Subject" ["def"] header :matches "Subject" ["abc?def"] </pre></div> <p> Note that by considering Sieve to be an MUA, RFC 2047 can be interpreted in a way that NUL characters truncating strings is allowed for Sieve implementations, although not recommended. It is further allowed to use encoded NUL characters in headers, but that’s not recommended either. The above example shows why. </p> <p> RFC 3028 states that if an implementation fails to convert a character set to UTF-8, two strings cannot be equal if one contains octets greater than 127. Assuming that all unknown character sets are one-byte character sets with the lower 128 octets being US-ASCII is not sound, so this implementation violates RFC 3028 and treats such MIME words literally. That way at least something could be matched. </p> <p> The folder specified by <span class="docbook_command">fileinto</span> must not contain the character sequence “..” to avoid security problems. RFC 3028 does not specify the syntax of folders apart from <span class="docbook_command">keep</span> being equivalent to </p> <div class="docbook_literallayout"><pre> fileinto "INBOX"; </pre></div> <p> This implementation uses <span class="docbook_filename">inbox</span> instead. </p> <p> Sieve script errors currently cause messages to be silently filed into <span class="docbook_filename">inbox</span>. RFC 3028 requires that the user is notified of that condition. This may be implemented in the future by adding a header line to mails that are filed into <span class="docbook_filename">inbox</span> due to an error in the filter. </p> </div> </div> <a class="previous_page" href="filter_ch01.html"><-previous</a><a class="next_page" href="filter_ch03.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>
