-. $Cambridge: exim/doc/doc-docbook/filter.xfpt,v 1.3 2006/04/27 15:19:27 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
.include stdflags
.include stdmacs
+.include ./local_params
.docbook
+
+. /////////////////////////////////////////////////////////////////////////////
+. These lines are processing instructions for the Simple DocBook Processor that
+. Philip Hazel has developed as a less cumbersome way of making PostScript and
+. PDFs than using xmlto and fop. They will be ignored by all other XML
+. processors.
+. /////////////////////////////////////////////////////////////////////////////
+
+.literal xml
+<?sdop
+ foot_right_recto="&chaptertitle;"
+ foot_right_verso="&chaptertitle;"
+ table_warn_overflow="overprint"
+ toc_chapter_blanks="yes,yes"
+ toc_title="Exim's interfaces to mail filtering"
+?>
+.literal off
+
.book
. ===========================================================================
.endmacro
. ===========================================================================
+. Copyright year. Update this (only) when changing content.
+
+.macro copyyear
+2023
+.endmacro
+
+. ===========================================================================
+
+. /////////////////////////////////////////////////////////////////////////////
+. /////////////////////////////////////////////////////////////////////////////
. This preliminary stuff creates a <bookinfo> entry in the XML. This is removed
. when creating the PostScript/PDF output, because we do not want a full-blown
-. title page created for those versions. The stylesheet fudges up a title line
-. to replace the text "Table of contents". However, for the other forms of
-. output, the <bookinfo> element is retained and used.
+. title page created for those versions. When fop is being used to create
+. PS/PDF, the stylesheet fudges up a title line to replace the text "Table of
+. contents". When SDoP is being used, a processing instruction does this job.
+. For the other forms of output, the <bookinfo> element is retained and used.
.literal xml
<bookinfo>
<title>Exim's interfaces to mail filtering</title>
<titleabbrev>Exim filtering</titleabbrev>
-<date>27 April 2006</date>
+<date>
+.fulldate
+</date>
<author><firstname>Philip</firstname><surname>Hazel</surname></author>
<authorinitials>PH</authorinitials>
<revhistory><revision>
- <revnumber>4.62</revnumber>
- <date>27 April 2006</date>
+.versiondatexml
<authorinitials>PH</authorinitials>
</revision></revhistory>
-<copyright><year>2006</year><holder>University of Cambridge</holder></copyright>
+<copyright><year>
+.copyyear
+ </year><holder>The Exim Maintainers</holder></copyright>
</bookinfo>
.literal off
+. /////////////////////////////////////////////////////////////////////////////
+. /////////////////////////////////////////////////////////////////////////////
-.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 2006. It
-corresponds to Exim version 4.62.
+facilities, and is copyright © The Exim Maintainers ©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
-.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
implemented; see the description in section &<<SECTmbox>>& 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
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.
-.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
in RFC 3028, which should be read in conjunction with these notes.
The Exim Sieve implementation offers the core as defined by RFC 3028,
-comparison tests, the &*copy*&, &*envelope*&, &*fileinto*&, 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.
+comparison tests, the subaddress parameter, the &*copy*&, &*envelope*&,
+&*fileinto*&, &*notify*&, and &*vacation*& extensions, but not the &*reject*&
+extension.
+Exim did not support message delivery notifications (MDNs) when Sieve handling
+was introduced, so &*reject*& (which need them) could not be supported.
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
-.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
-.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
-.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
-.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
-.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
-.section "Semantics of keep"
+.section "Semantics of keep" "SEC11"
The &(keep)& command is equivalent to
.code
fileinto "inbox";
-.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
-.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
-.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
-.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
-.section "RFC compliance"
+.section "RFC compliance" "SEC16"
Exim requires the first line of a Sieve filter to be
.code
# Sieve 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
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
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:
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 &<<SECTadd>>&). These can be
used for &"scoring"& messages in various ways. If Exim is configured to run a
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
-.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:
(duplicate &(save)& commands are ignored).
If the file name does not start with a / character, the contents of the
-&$home$& variable are prepended, unless it is empty. In conventional
-configurations, this variable is normally set in a user filter to the user's
-home directory, but the system administrator may set it to some other path. In
-some configurations, &$home$& may be unset, in which case a non-absolute path
-name may be generated. Such configurations convert this to an absolute path
-when the delivery takes place. In a system filter, &$home$& is never set.
+&$home$& variable are prepended, unless it is empty, or the system
+administrator has disabled this feature. In conventional configurations, this
+variable is normally set in a user filter to the user's home directory, but the
+system administrator may set it to some other path. In some configurations,
+&$home$& may be unset, or prepending may be disabled, in which case a
+non-absolute path name may be generated. Such configurations convert this to an
+absolute path when the delivery takes place. In a system filter, &$home$& is
+never set.
The user must of course have permission to write to the file, and the writing
of the file takes place in a process that is running as the user, under the
&` [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,
&`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
-.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
.endd
For a &"matches"& test, after expansion of both strings, the second one is
-interpreted as a regular expression. Exim uses the PCRE regular expression
+interpreted as a regular expression. Exim uses the PCRE2 regular expression
library, which provides regular expressions that are compatible with Perl.
The match succeeds if the regular expression matches any part of the first
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
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
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
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
-.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,
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
$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
-.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
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
-.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
git://git.exim.org / exim.git / blobdiff