X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/f89d2485b9084317af07bf48bf09a81dc5780caa..a3ab48f23ee4a83f796440ef67d7ac7b43aad4b5:/doc/doc-docbook/filter.xfpt diff --git a/doc/doc-docbook/filter.xfpt b/doc/doc-docbook/filter.xfpt index 4c56cbdd1..d146f72f0 100644 --- a/doc/doc-docbook/filter.xfpt +++ b/doc/doc-docbook/filter.xfpt @@ -1,5 +1,3 @@ -. $Cambridge: exim/doc/doc-docbook/filter.xfpt,v 1.5 2007/04/11 15:26:09 ph10 Exp $ - . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the document that describes Exim's filtering . facilities. It is an xfpt document that is converted into DocBook XML for @@ -10,6 +8,7 @@ .include stdflags .include stdmacs +.include ./local_params .docbook . ///////////////////////////////////////////////////////////////////////////// @@ -23,7 +22,7 @@ @@ -46,6 +45,13 @@ .endmacro . =========================================================================== +. Copyright year. Update this (only) when changing content. + +.macro copyyear +2018 +.endmacro + +. =========================================================================== . ///////////////////////////////////////////////////////////////////////////// . ///////////////////////////////////////////////////////////////////////////// @@ -61,15 +67,18 @@ Exim's interfaces to mail filtering Exim filtering -31 July + +.fulldate + PhilipHazel PH - 4.63 - 31 July 2006 +.versiondatexml PH -2006University of Cambridge + +.copyyear + University of Cambridge .literal off @@ -77,14 +86,14 @@ . ///////////////////////////////////////////////////////////////////////////// -.chapter "Forwarding and filtering in Exim" +.chapter "Forwarding and filtering in Exim" "CHAPforandfilt" 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.67. +facilities, and is copyright © University of Cambridge ©year(). It +corresponds to Exim version &version(). -.section "Introduction" +.section "Introduction" "SEC00" 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 &_.forward_& in their home @@ -127,7 +136,7 @@ up and control the use of filtering. -.section "Filter operation" +.section "Filter operation" "SEC01" It is important to realize that, in Exim, no deliveries are actually made while a filter or traditional &_.forward_& file is being processed. Running a filter or processing a traditional &_.forward_& file sets up future delivery @@ -222,7 +231,7 @@ part. These are relevant only when support for multiple personal mailboxes is implemented; see the description in section &<>& below. -.section "Installing a filter file" +.section "Installing a filter file" "SEC02" A filter file is normally installed under the name &_.forward_& in your home directory &-- it is distinguished from a conventional &_.forward_& file by its first line (described below). However, the file name is configurable, and some @@ -230,7 +239,7 @@ system administrators may choose to use some different name or location for filter files. -.section "Testing an installed filter file" +.section "Testing an installed filter file" "SEC03" 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. @@ -256,7 +265,7 @@ be left in all Exim filter files. (This does not apply to Sieve files.) -.section "Details of filtering commands" +.section "Details of filtering commands" "SEC04" 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 @@ -273,21 +282,19 @@ this context as &"the specific implementation of Sieve for Exim"&. 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. -.new The Exim Sieve implementation offers the core as defined by RFC 3028, comparison tests, the subaddress parameter, the &*copy*&, &*envelope*&, &*fileinto*&, &*notify*&, and &*vacation*& extensions, but not the &*reject*& extension. Exim does not support message delivery notifications (MDNs), so adding it just to the Sieve filter (as required for &*reject*&) makes little sense. -.wen 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 &(redirect)& router in the full Exim specification. -.section "Recognition of Sieve filters" +.section "Recognition of Sieve filters" "SEC05" A filter file is interpreted as a Sieve filter if its first line is .code # Sieve filter @@ -297,7 +304,7 @@ filter file. -.section "Saving to specified folders" +.section "Saving to specified folders" "SEC06" If the system administrator has set things up as suggested in the Exim specification, and you use &(keep)& or &(fileinto)& to save a mail into a folder, absolute files are stored where specified, relative files are stored @@ -305,7 +312,7 @@ relative to &$home$&, and &_inbox_& goes to the standard mailbox location. -.section "Strings containing header names" +.section "Strings containing header names" "SEC07" 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 @@ -313,7 +320,7 @@ to ease script debugging, which fits in with the common picture of Sieve. -.section "Exists test with empty list of headers" +.section "Exists test with empty list of headers" "SEC08" The &*exists*& 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 @@ -321,7 +328,7 @@ strict sense. -.section "Header test with invalid MIME encoding in header" +.section "Header test with invalid MIME encoding in header" "SEC09" 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 @@ -337,7 +344,7 @@ character set cannot be converted to UTF-8. -.section "Address test for multiple addresses per header" +.section "Address test for multiple addresses per header" "SEC10" 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 @@ -347,7 +354,7 @@ contains an additional address besides the one the test checks for. -.section "Semantics of keep" +.section "Semantics of keep" "SEC11" The &(keep)& command is equivalent to .code fileinto "inbox"; @@ -357,7 +364,7 @@ implicit keep flag; there is no command to set it once it has been reset. -.section "Semantics of fileinto" +.section "Semantics of fileinto" "SEC12" RFC 3028 does not specify whether &(fileinto)& should try to create a mail folder if it does not exist. This implementation allows the sysadmin to configure that aspect using the &(appendfile)& transport options @@ -366,7 +373,7 @@ configure that aspect using the &(appendfile)& transport options -.section "Semantics of redirect" +.section "Semantics of redirect" "SEC13" 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 @@ -375,7 +382,7 @@ it to be. -.section "String arguments" +.section "String arguments" "SEC14" There has been confusion if the string arguments to &(require)& are to be matched case-sensitively or not. This implementation matches them with the match type &(:is)& (default, see section 2.7.1 of the RFC) and the comparator @@ -385,7 +392,7 @@ the command defaults clearly, so any different implementations violate RFC -.section "Number units" +.section "Number units" "SEC15" 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 @@ -393,7 +400,7 @@ the scaling factor for the suffix G. -.section "RFC compliance" +.section "RFC compliance" "SEC16" Exim requires the first line of a Sieve filter to be .code # Sieve filter @@ -458,7 +465,7 @@ are filed into &_inbox_& due to an error in the filter. This chapter contains a full description of the contents of Exim filter files. -.section "Format of Exim filter files" +.section "Format of Exim filter files" "SEC17" Apart from leading white space, the first text in an Exim filter file must be .code # Exim filter @@ -490,7 +497,7 @@ If the character # follows a separator anywhere in a command, everything from in a filter file. -.section "Data values in filter commands" +.section "Data values in filter commands" "SEC18" There are two ways in which a data value can be input: .ilist @@ -562,7 +569,7 @@ if $message_body contains \N$$$$\N then ... tests for a run of four dollar characters. -.section "Some useful general variables" +.section "Some useful general variables" "SEC19" A complete list of the available variables is given in the Exim documentation. This shortened list contains the ones that are most likely to be useful in personal filter files: @@ -694,7 +701,7 @@ substituted. Thus it is important to spell the names of headers correctly. Do not use &$header_Reply_to$& when you really mean &$header_Reply-to$&. -.section "User variables" +.section "User variables" "SEC20" There are ten user variables with names &$n0$& &-- &$n9$& that can be incremented by the &(add)& command (see section &<>&). These can be used for &"scoring"& messages in various ways. If Exim is configured to run a @@ -704,7 +711,7 @@ thus making them available to users' filter files. How these values are used is entirely up to the individual installation. -.section "Current directory" +.section "Current directory" "SEC21" The contents of your filter file should not make any assumptions about the current directory. It is best to use absolute paths for file names; you can normally make use of the &$home$& variable to refer to your home directory. The @@ -748,7 +755,7 @@ finish -.section "Filter commands" +.section "Filter commands" "SEC222" The filter commands that are described in subsequent sections are listed below, with the section in which they are described in brackets: @@ -1044,7 +1051,6 @@ mail-sending command is &` [log `&<&'log file name'&>&`]`& &` [once `&<&'note file name'&>&`]`& &` [once_repeat `&<&'time interval'&>&`]`& - &`e.g. mail text "Your message about $h_subject: has been received"`& .endd Each <&'address-list'&> can contain a number of addresses, separated by commas, @@ -1183,7 +1189,9 @@ been obeyed, the &(logwrite)& command can be used to write to it: &`e.g. logwrite "$tod_log $message_id processed"`& .endd It is possible to have more than one &(logfile)& command, to specify writing to -different log files in different circumstances. Writing takes place at the end +different log files in different circumstances. +A previously opened log is closed on a subsequent &(logfile)& command. +Writing takes place at the end of the file, and a newline character is added to the end of each string if there isn't one already there. Newlines can be put in the middle of the string by using the &"\n"& escape sequence. Lines from simultaneous deliveries may get @@ -1281,7 +1289,7 @@ negative forms of condition that are more English-like. -.section "String testing conditions" +.section "String testing conditions" "SEC23" There are a number of conditions that operate on text strings, using the words &"begins"&, &"ends"&, &"is"&, &"contains"& and &"matches"&. If you want to apply the same test to more than one header line, you can easily concatenate @@ -1396,7 +1404,7 @@ available for use in subsequent sub-conditions, because string expansion of a condition occurs just before it is tested. -.section "Numeric testing conditions" +.section "Numeric testing conditions" "SEC24" The following conditions are available for performing numerical tests: .display @@ -1412,7 +1420,7 @@ followed by one of the letters K or M (upper case or lower case) which cause multiplication by 1024 and 1024x1024 respectively. -.section "Testing for significant deliveries" +.section "Testing for significant deliveries" "SEC25" You can use the &(delivered)& condition to test whether or not any previously obeyed filter commands have set up a significant delivery. For example: .code @@ -1423,7 +1431,7 @@ message has not actually been delivered; rather, a delivery has been set up for later processing. -.section "Testing for error messages" +.section "Testing for error messages" "SEC26" The condition &(error_message)& is true if the incoming message is a bounce (mail delivery error) message. Putting the command .code @@ -1435,7 +1443,7 @@ wrong in such a way that you cannot receive delivery error reports. &*Note*&: not preceded by &`$`&. -.section "Testing a list of addresses" +.section "Testing a list of addresses" "SEC27" There is a facility for looping through a list of addresses and applying a condition to each of them. It takes the form .display @@ -1527,7 +1535,7 @@ the tests. -.section "Alias addresses for the personal condition" +.section "Alias addresses for the personal condition" "SEC28" It is quite common for people who have mail accounts on a number of different systems to forward all their mail to one system, and in this case a check for personal mail should test all their various mail addresses. To allow for this, @@ -1545,7 +1553,7 @@ The alias addresses are treated as alternatives to the current user's email address when testing the contents of header lines. -.section "Details of the personal condition" +.section "Details of the personal condition" "SEC29" The basic &(personal)& test is roughly equivalent to the following: .code not error_message and @@ -1557,7 +1565,7 @@ $message_headers does not contain "\nList-Post:" and $message_headers does not contain "\nList-Owner:" and $message_headers does not contain "\nList-Archive:" and ( -"${if def h_auto-submitted:{present}{absent}}" is "absent" or +"${if def:h_auto-submitted:{present}{absent}}" is "absent" or $header_auto-submitted: is "no" ) and $header_precedence: does not contain "bulk" and @@ -1586,7 +1594,7 @@ the current user are also done with alternative addresses. -.section "Testing delivery status" +.section "Testing delivery status" "SEC30" There are two conditions that are intended mainly for use in system filter files, but which are available in users' filter files as well. The condition &(first_delivery)& is true if this is the first process that is attempting to @@ -1604,7 +1612,7 @@ some reason, and was subsequently released by the system administrator. It is unlikely to be of use in users' filter files. -.section "Multiple personal mailboxes" "SECTmbox" +.section "Multiple personal mailboxes" "SECTmbox" "SEC31" The system administrator can configure Exim so that users can set up variants on their email addresses and handle them separately. Consult your system administrator or local documentation to see if this facility is enabled on your @@ -1635,7 +1643,7 @@ suffixes in its checking. -.section "Ignoring delivery errors" +.section "Ignoring delivery errors" "SEC43" As was explained above, filtering just sets up addresses for delivery &-- no deliveries are actually done while a filter file is active. If any of the generated addresses subsequently suffers a delivery failure, an error message