JJ/03 installed exipick 20100323.0, fixing doc bug (debian 574778)

[users/heiko/exim.git] / doc / doc-txt / README.SIEVE

diff --git a/doc/doc-txt/README.SIEVE b/doc/doc-txt/README.SIEVE
index 04383f6e596e739d4373ddaee7b578e727d582e6..4a9950e3b2b46fa05dfae72fbba258944e6210a4 100644 (file)
--- a/doc/doc-txt/README.SIEVE
+++ b/doc/doc-txt/README.SIEVE
@@ -1,4 +1,4 @@
-$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.4 2005/05/03 10:02:27 ph10 Exp $
+$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.12 2008/01/28 12:26:31 michael Exp $

 
               Notes on the Sieve implementation for Exim
 
 
               Notes on the Sieve implementation for Exim
 


@@ -13,25 +13,57 @@ The Exim filter contains more features, such as variable expansion, and
 better integration with the host environment, like external processes
 and pipes.
 
 better integration with the host environment, like external processes
 and pipes.
 

-Sieve is a standard for interoperable filters, defined in RFC 3028,
+Sieve is a standard for interoperable filters, defined in RFC 5228,

 with multiple implementations around. If interoperability is important,
 then there is no way around it.
 
 
 Exim Implementation
 
 with multiple implementations around. If interoperability is important,
 then there is no way around it.
 
 
 Exim Implementation
 

-The Exim Sieve implementation offers the core as defined by RFC 3028, the
-"envelope" (RFC 3028), the "fileinto" (RFC 3028), the "copy" (RFC 3894)
-and the "vacation" (draft-ietf-sieve-vacation-01.txt) extension,
-the "i;ascii-numeric" comparator, but not the "reject" extension.
-Exim does not support MDMs, so adding it just to the sieve filter makes
-little sense.
+The Exim Sieve implementation offers the core as defined by RFC 5228,
+the "encoded-character" extension (RFC 5228), the "envelope" test (RFC
+5228), the "fileinto" action (5228), the "copy" parameter (RFC 3894), the
+"vacation" action (5230), the "notify" action (draft-ietf-sieve-notify-12)
+with mailto URIs (draft-ietf-sieve-notify-mailto-05), the
+"i;ascii-numeric" comparator (RFC 2244) and the subaddress parameter
+(RFC 5233).

 
 The Sieve filter is integrated in Exim and works very similar to the
 Exim filter: Sieve scripts are recognized by the first line containing
 "# sieve filter".  When using "keep" or "fileinto" to save a mail into a
 folder, the resulting string is available as the variable $address_file
 
 The Sieve filter is integrated in Exim and works very similar to the
 Exim filter: Sieve scripts are recognized by the first line containing
 "# sieve filter".  When using "keep" or "fileinto" to save a mail into a
 folder, the resulting string is available as the variable $address_file

-in the transport that stores it.  A suitable transport could be:
+in the transport that stores it.  The following routers and transport
+show a typical use of Sieve:
+
+begin routers
+
+localuser_verify:
+  driver = accept
+  domains = +localdomains
+  local_part_suffix = "-*"
+  local_part_suffix_optional
+  check_local_user
+  require_files = $home/.forward
+  verify_only = true
+
+localuser_deliver:
+  driver = redirect
+  domains = +localdomains
+  local_part_suffix = "-*"
+  local_part_suffix_optional
+  sieve_subaddress = "${sg{$local_part_suffix}{^-}{}}"
+  sieve_useraddress = "$local_part"
+  check_local_user
+  require_files = $home/.forward
+  file = $home/.forward
+  check_ancestor
+  allow_filter
+  file_transport = localuser
+  reply_transport = vacation
+  sieve_vacation_directory = $home/mail/vacation
+  verify = false
+
+begin transports

 
 localuser:
   driver = appendfile
 
 localuser:
   driver = appendfile


@@ -39,7 +71,7 @@ localuser:
               {/var/mail/$local_part} \
               {${if eq{${substr_0_1:$address_file}}{/} \
                     {$address_file} \
               {/var/mail/$local_part} \
               {${if eq{${substr_0_1:$address_file}}{/} \
                     {$address_file} \

-                    {$home/$address_file} \
+                    {$home/mail/$address_file} \

               }} \
          }
   delivery_date_add
               }} \
          }
   delivery_date_add


@@ -47,13 +79,16 @@ localuser:
   return_path_add
   mode = 0600
 
   return_path_add
   mode = 0600
 

-Absolute files are stored where specified, relative files are stored
-relative to $home and "inbox" goes to the standard mailbox location.
+vacation:
+  driver = autoreply

 
 

-To enable "vacation", set sieve_vacation_directory for the router to
-the directory where vacation databases are held (don't put anything
-else in that directory) and point reply_transport to an autoreply
-transport.
+Absolute files are stored where specified, relative files are stored
+relative to $home/mail and "inbox" goes to the standard mailbox location.
+To enable "vacation", sieve_vacation_directory is set to the directory
+where vacation databases are held (don't put anything else in that
+directory) and point reply_transport to an autoreply transport.
+Setting the Sieve useraddress and subaddress allows to use the subaddress
+extension.

 
 
 RFC Compliance
 
 
 RFC Compliance


@@ -62,7 +97,7 @@ Exim requires the first line to be "# sieve filter".  Of course the RFC
 does not enforce that line.  Don't expect examples to work without adding
 it, though.
 
 does not enforce that line.  Don't expect examples to work without adding
 it, though.
 

-RFC 3028 requires using CRLF to terminate the end of a line.
+RFC 5228 requires using CRLF to terminate the end of 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.
 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.


@@ -70,86 +105,18 @@ Since all parts of Exim use \n as newline character, this implementation
 does, too.  You can change this by defining the macro RFC_EOL at compile
 time to enforce CRLF being used.
 
 does, too.  You can change this by defining the macro RFC_EOL at compile
 time to enforce CRLF being used.
 

-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 to UTF-8 data.
-
-Sieve scripts can not 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
-evaulate the first test as true.
-
-Subject: =?iso-8859-1?q?abc=00def
-
-header :contains "Subject" ["abc"]
-header :contains "Subject" ["def"]
-header :matches "Subject" ["abc?def"]
-
-Note that by considering Sieve to be a 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.  Good code should still be able to deal
-with it.
-
-RFC 3028 states that if an implementation fails to convert a character
-set to UTF-8, two strings can not be equal if one contains octects greater
-than 127.  Assuming that all unknown character sets are one-byte character
-sets with the lower 128 octects 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.
-

 The folder specified by "fileinto" must not contain the character
 The folder specified by "fileinto" must not contain the character

-sequence ".." to avoid security problems.  RFC 3028 does not specifiy the
+sequence ".." to avoid security problems.  RFC 5228 does not specify the

 syntax of folders apart from keep being equivalent to fileinto "INBOX".
 This implementation uses "inbox" instead.
 
 Sieve script errors currently cause that messages are silently filed into
 syntax of folders apart from keep being equivalent to fileinto "INBOX".
 This implementation uses "inbox" instead.
 
 Sieve script errors currently cause that messages are silently filed into

-"inbox".  RFC 3028 requires that the user is notified of that condition.
+"inbox".  RFC 5228 requires that the user is notified of that condition.

 This may be implemented in future by adding a header line to mails that
 are filed into "inbox" due to an error in the filter.
 
 This may be implemented in future by adding a header line to mails that
 are filed into "inbox" due to an error in the filter.
 

-
-Strings Containing Header Names Or Envelope Elements
-
-RFC 3028 does not specify what happens if a string denoting a header
-field or envelope element does not contain a valid name, e.g. it
-contains a colon for a header or it is not "from" or "to" for envelopes.
-This implementation generates an error instead of ignoring the header
-field in order to ease script debugging, which fits in the common picture
-of Sieve.
-
-
-Header Test With Invalid MIME Encoding In Header
-
-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 (appearantly
-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.
-
-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 can not be converted to UTF-8.
-
-
-Address Test For Multiple Addresses Per Header
-
-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
-satify 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.
+The automatic replies generated by "vacation" do not contain an updated
+"references" header field.

 
 
 Semantics Of Keep
 
 
 Semantics Of Keep


@@ -160,83 +127,55 @@ implicit keep flag; there is no command to set it once it has
 been reset.
 
 
 been reset.
 
 

-Semantics of Fileinto
+Semantics Of Fileinto

 
 

-RFC 3028 does not specify if "fileinto" tries to create a mail folder,
+RFC 5228 does not specify if "fileinto" tries to create a mail folder,

 in case it does not exist.  This implementation allows to configure
 that aspect using the appendfile transport options "create_directory",
 "create_file" and "file_must_exist".  See the appendfile transport in
 the Exim specification for details.
 
 
 in case it does not exist.  This implementation allows to configure
 that aspect using the appendfile transport options "create_directory",
 "create_file" and "file_must_exist".  See the appendfile transport in
 the Exim specification for details.
 
 

-Semantics of Redirect
-
-Sieve scripts are supposed to be interoperable between servers, so this
-implementation does not allow redirecting mail to unqualified addresses,
-because the domain would depend on the used system and on systems with
-virtual mail domains it is probably not what the user expects it to be.
-
+Allof And Anyof Test

 
 

-String Arguments
+RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
+Exim uses shortcut evaluation.

 
 

-There has been confusion if the string arguments to "require" are to be
-matched case-sensitive or not.  This implementation matches them with
-the match type ":is" (default, see section 2.7.1) and the comparator
-"i;ascii-casemap" (default, see section 2.7.3).  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.

 
 

+Action Reordering

 
 

-Number Units
+RFC 5228 does not specify if actions may be executed out of order.
+Exim may execute them out of order, e.g. messages may be filed to
+folders or forwarded in a different order than specified, because
+those actions only setup delivery, but do not execute it themselves.

 
 

-There is a mistake in RFC 3028: The suffix G denotes gibi-, not tebibyte.
-The mistake os obvious, because RFC 3028 specifies G to denote 2^30
-(which is gibi, not tebi), and that's what this implementation uses as
-scaling factor for the suffix G.

 
 

+Sieve Syntax And Semantics

 
 

-Sieve Syntax and Semantics
+RFC 5228 uses a generic grammar as syntax for commands and tests and
+performs many checks during semantic analysis.  Syntax is specified
+by grammar rules, semantics by natural language.  The intention is to
+provide a framework for the syntax that describes current commands as
+well as future extensions, and describing commands by semantics.

 
 

-RFC 3028 confuses syntax and semantics sometimes.  It uses a generic
-grammar as syntax for actions and tests and performs many checks during
-semantic analysis.  Syntax is specified as grammar rule, semantics
-with natural language, despire the latter often talking about syntax.
-The intention was to provide a framework for the syntax that describes
-current commands as well as future extensions, and describing commands
-by semantics.  Since the semantic analysis is not specified by formal
-rules, it is easy to get that phase wrong, as demonstrated by the mistake
-in RFC 3028 to forbid "elsif" being followed by "elsif" (which is allowed
-in Sieve, it's just not specified correctly).
-
-RFC 3028 does not define if semantic checks are strict (always treat
-unknown extensions as errors) or lazy (treat unknown extensions as error,
-if they are executed), and since it employs a very generic grammar,
-it is not unreasonable for an implementation using a parser for the
-generic grammar to indeed process scripts that contain unknown commands
-in dead code.  It is just required to treat disabled but known extensions
-the same as unknown extensions.
-
-The following suggestion for section 8.2 gives two grammars, one for
-the framework, and one for specific commands, thus removing most of the
-semantic analysis.  Since the parser can not parse unsupported extensions,
-the result is strict error checking.  As required in section 2.10.5, known
-but not enabled extensions must behave the same as unknown extensions,
-so those also result strictly in errors (though at the thin semantic
-layer), even if they can be parsed fine.
+The following replacement for section 8.2 gives a grammar for specific
+commands of this implementation, thus removing most of the semantic
+analysis.  Since the parser can not parse unsupported extensions, the
+result is strict error checking of any executed and not executed code
+until "stop" is executed or the end of the script is reached.

 
 8.2. Grammar
 
 
 8.2. Grammar
 

-The atoms of the grammar are lexical tokens.  White space or comments may
-appear anywhere between lexical tokens, they are not part of the grammar.

 The grammar is specified in ABNF with two extensions to describe tagged
 arguments that can be reordered and grammar extensions: { } denotes a
 sequence of symbols that may appear in any order.  Example:
 
 The grammar is specified in ABNF with two extensions to describe tagged
 arguments that can be reordered and grammar extensions: { } denotes a
 sequence of symbols that may appear in any order.  Example:
 

-  start =  { a b c }
+  options = a b c
+  start   = { options }

 
 is equivalent to:
 
 
 is equivalent to:
 

-  start =  ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
+  start   =  ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )

 
 The symbol =) is used to append to a rule:
 
 
 The symbol =) is used to append to a rule:
 


@@ -247,21 +186,6 @@ is equivalent to
 
   start =  a b
 
 
   start =  a b
 

-All Sieve commands, including extensions, MUST be words of the following
-generic grammar with the start symbol "start".  They SHOULD be specified
-using a specific grammar, though.
-
-   argument        = string-list / number / tag
-   arguments       = *argument [test / test-list]
-   block           = "{" commands "}"
-   commands        = *command
-   string          = quoted-string / multi-line
-   string-list     = "[" string *("," string) "]" / string
-   test            = identifier arguments
-   test-list       = "(" test *("," test) ")"
-   command         = identifier arguments ( ";" / block )
-   start           = command
-

 The basic Sieve commands are specified using the following grammar, which
 language is a subset of the generic grammar above.  The start symbol is
 "start".
 The basic Sieve commands are specified using the following grammar, which
 language is a subset of the generic grammar above.  The start symbol is
 "start".


@@ -367,19 +291,13 @@ the UTF-8 reason is processed to compose the resulting message.
 
 Default Subject
 
 
 Default Subject
 

-The draft specifies that the default message subject is "Re: "
-plus the old subject, stripped by any leading "Re: " strings.
-This string is to be taken literally, unlike some software which
-matches a regular expression like "[rR][eE]: *".  Using this
-subject is dangerous, because many mailing lists verify addresses
-by sending a secret key in the subject of a message, asking to
-reply to the message for confirmation.  Using the default vacation
-subject confirms any subscription request of this kind, allowing
-to subscribe a third party to any mailing list, either to annoy
-the user or to declare spam as legitimate mail by proving to
-use opt-in.  The draft specifies to use "Re: " in front of the
-subject, but this implementation uses "Auto: ", as suggested in
-RFC 3834, section 3.1.5.
+RFC 5230 specifies that the default message subject is "Auto: " plus
+the old subject.  Using this subject is dangerous, because many mailing
+lists verify addresses by sending a secret key in the subject of a
+message, asking to reply to the message for confirmation.  Using the
+default vacation subject confirms any subscription request of this kind,
+allowing to subscribe a third party to any mailing list, either to annoy
+the user or to declare spam as legitimate mail by proving to use opt-in.

 
 
 Rate Limiting Responses
 
 
 Rate Limiting Responses


@@ -406,9 +324,22 @@ of addresses that will never be replied to.  Exim offers this as option
 "never_mail" in the autoreply transport.
 
 
 "never_mail" in the autoreply transport.
 
 

-Interaction With Other Sieve Elements
+The enotify extension
+
+The extension "enotify" is specified using the following grammar
+extension.
+
+  notify-command =  "notify" { notify-options } <method: string>
+  notify-options =  [":from" string]
+                    [":importance" <"1" / "2" / "3">]
+                    [":options" 1*(string-list / number)]
+                    [":message" string]
+
+  command          =/ notify-command
+
+  valid_notify_method = "valid_notify_method"
+                        <notification-uris: string-list>
+
+  test             =/ valid_notify_method

 
 

-The draft describes the interaction with vacation, discard, keep,
-fileinto and redirect.  It MUST describe compatibility with other
-actions, but doesn't.  In this implementation, vacation is compatible
-with any other action.
+Only the mailto URI scheme is implemented.