Add the unwanted input to the log line for a synchronization error right
[exim.git] / doc / doc-txt / README.SIEVE
1 $Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.1 2004/10/07 15:04:35 ph10 Exp $
2
3               Notes on the Sieve implementation for Exim
4
5 Exim Filter Versus Sieve Filter
6
7 Exim supports two incompatible filters: The traditional Exim filter and
8 the Sieve filter. Since Sieve is a extensible language, it is important
9 to understand "Sieve" in this context as "the specific implementation
10 of Sieve for Exim".
11
12 The Exim filter contains more features, such as variable expansion, and
13 better integration with the host environment, like external processes
14 and pipes.
15
16 Sieve is a standard for interoperable filters, defined in RFC 3028,
17 with multiple implementations around. If interoperability is important,
18 then there is no way around it.
19
20
21 Exim Implementation
22
23 The Exim Sieve implementation offers the core as defined by RFC 3028, the
24 "envelope" (RFC 3028), the "fileinto" (RFC 3028), the "copy" (RFC 3894)
25 and the "vacation" (draft-showalter-sieve-vacation-05.txt) extension,
26 the "i;ascii-numeric" comparator, but not the "reject" extension.
27 Exim does not support MDMs, so adding it just to the sieve filter makes
28 little sense.
29
30 The Sieve filter is integrated in Exim and works very similar to the
31 Exim filter: Sieve scripts are recognized by the first line containing
32 "# sieve filter".  When using "keep" or "fileinto" to save a mail into a
33 folder, the resulting string is available as the variable $address_file
34 in the transport that stores it.  A suitable transport could be:
35
36 localuser:
37   driver = appendfile
38   file = ${if eq{$address_file}{inbox} \
39               {/var/mail/$local_part} \
40               {${if eq{${substr_0_1:$address_file}}{/} \
41                     {$address_file} \
42                     {$home/$address_file} \
43               }} \
44          }
45   delivery_date_add
46   envelope_to_add
47   return_path_add
48   mode = 0600
49
50 Absolute files are stored where specified, relative files are stored
51 relative to $home and "inbox" goes to the standard mailbox location.
52
53 To enable "vacation", set sieve_vacation_directory for the router to
54 the directory where vacation databases are held (don't put anything
55 else in that directory) and point reply_transport to an autoreply
56 transport.
57
58
59 RFC Compliance
60
61 Exim requires the first line to be "# sieve filter".  Of course the RFC
62 does not enforce that line.  Don't expect examples to work without adding
63 it, though.
64
65 RFC 3028 requires using CRLF to terminate the end of a line.
66 The rationale was that CRLF is universally used in network protocols
67 to mark the end of the line.  This implementation does not embed Sieve
68 in a network protocol, but uses Sieve scripts as part of the Exim MTA.
69 Since all parts of Exim use \n as newline character, this implementation
70 does, too.  You can change this by defining the macro RFC_EOL at compile
71 time to enforce CRLF being used.
72
73 Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so
74 this implementation repeats this violation to stay consistent with Exim.
75 This is in preparation to UTF-8 data.
76
77 Sieve scripts can not contain NUL characters in strings, but mail
78 headers could contain MIME encoded NUL characters, which could never
79 be matched by Sieve scripts using exact comparisons.  For that reason,
80 this implementation extends the Sieve quoted string syntax with \0
81 to describe a NUL character, violating \0 being the same as 0 in
82 RFC 3028.  Even without using \0, the following tests are all true in
83 this implementation.  Implementations that use C-style strings will only
84 evaulate the first test as true.
85
86 Subject: =?iso-8859-1?q?abc=00def
87
88 header :contains "Subject" ["abc"]
89 header :contains "Subject" ["def"]
90 header :matches "Subject" ["abc?def"]
91
92 Note that by considering Sieve to be a MUA, RFC 2047 can be interpreted
93 in a way that NUL characters truncating strings is allowed for Sieve
94 implementations, although not recommended.  It is further allowed to use
95 encoded NUL characters in headers, but that's not recommended either.
96 The above example shows why.  Good code should still be able to deal
97 with it.
98
99 RFC 3028 states that if an implementation fails to convert a character
100 set to UTF-8, two strings can not be equal if one contains octects greater
101 than 127.  Assuming that all unknown character sets are one-byte character
102 sets with the lower 128 octects being US-ASCII is not sound, so this
103 implementation violates RFC 3028 and treats such MIME words literally.
104 That way at least something could be matched.
105
106 The folder specified by "fileinto" must not contain the character
107 sequence ".." to avoid security problems.  RFC 3028 does not specifiy the
108 syntax of folders apart from keep being equivalent to fileinto "INBOX".
109 This implementation uses "inbox" instead.
110
111 Sieve script errors currently cause that messages are silently filed into
112 "inbox".  RFC 3028 requires that the user is notified of that condition.
113 This may be implemented in future by adding a header line to mails that
114 are filed into "inbox" due to an error in the filter.
115
116
117 Strings Containing Header Names
118
119 RFC 3028 does not specify what happens if a string denoting a header
120 field does not contain a valid header name, e.g. it contains a colon.
121 This implementation generates an error instead of ignoring the header
122 field in order to ease script debugging, which fits in the common
123 picture of Sieve.
124
125
126 Header Test With Invalid MIME Encoding In Header
127
128 Some MUAs process invalid base64 encoded data, generating junk.
129 Others ignore junk after seeing an equal sign in base64 encoded data.
130 RFC 2047 does not specify how to react in this case, other than stating
131 that a client must not forbid to process a message for that reason.
132 RFC 2045 specifies that invalid data should be ignored (appearantly
133 looking at end of line characters).  It also specifies that invalid data
134 may lead to rejecting messages containing them (and there it appears to
135 talk about true encoding violations), which is a clear contradiction to
136 ignoring them.
137
138 RFC 3028 does not specify how to process incorrect MIME words.
139 This implementation treats them literally, as it does if the word is
140 correct, but its character set can not be converted to UTF-8.
141
142
143 Address Test For Multiple Addresses Per Header
144
145 A header may contain multiple addresses.  RFC 3028 does not explicitly
146 specify how to deal with them, but since the "address" test checks if
147 anything matches anything else, matching one address suffices to
148 satify the condition.  That makes it impossible to test if a header
149 contains a certain set of addresses and no more, but it is more logical
150 than letting the test fail if the header contains an additional address
151 besides the one the test checks for.
152
153
154 Semantics Of Keep
155
156 The keep command is equivalent to fileinto "inbox": It saves the
157 message and resets the implicit keep flag.  It does not set the
158 implicit keep flag; there is no command to set it once it has
159 been reset.
160
161
162 Semantics of Fileinto
163
164 RFC 3028 does not specify if "fileinto" tries to create a mail folder,
165 in case it does not exist.  This implementation allows to configure
166 that aspect using the appendfile transport options "create_directory",
167 "create_file" and "file_must_exist".  See the appendfile transport in
168 the Exim specification for details.
169
170
171 Semantics of Redirect
172
173 Sieve scripts are supposed to be interoperable between servers, so this
174 implementation does not allow redirecting mail to unqualified addresses,
175 because the domain would depend on the used system and on systems with
176 virtual mail domains it is probably not what the user expects it to be.
177
178
179 String Arguments
180
181 There has been confusion if the string arguments to "require" are to be
182 matched case-sensitive or not.  This implementation matches them with
183 the match type ":is" (default, see section 2.7.1) and the comparator
184 "i;ascii-casemap" (default, see section 2.7.3).  The RFC defines the
185 command defaults clearly, so any different implementations violate RFC
186 3028.  The same is valid for comparator names, also specified as strings.
187
188
189 Number Units
190
191 There is a mistake in RFC 3028: The suffix G denotes gibi-, not tebibyte.
192 The mistake os obvious, because RFC 3028 specifies G to denote 2^30
193 (which is gibi, not tebi), and that's what this implementation uses as
194 scaling factor for the suffix G.
195
196
197 Sieve Syntax and Semantics
198
199 RFC 3028 confuses syntax and semantics sometimes.  It uses a generic
200 grammar as syntax for actions and tests and performs many checks during
201 semantic analysis.  Syntax is specified as grammar rule, semantics
202 with natural language, despire the latter often talking about syntax.
203 The intention was to provide a framework for the syntax that describes
204 current commands as well as future extensions, and describing commands
205 by semantics.  Since the semantic analysis is not specified by formal
206 rules, it is easy to get that phase wrong, as demonstrated by the mistake
207 in RFC 3028 to forbid "elsif" being followed by "elsif" (which is allowed
208 in Sieve, it's just not specified correctly).
209
210 RFC 3028 does not define if semantic checks are strict (always treat
211 unknown extensions as errors) or lazy (treat unknown extensions as error,
212 if they are executed), and since it employs a very generic grammar,
213 it is not unreasonable for an implementation using a parser for the
214 generic grammar to indeed process scripts that contain unknown commands
215 in dead code.  It is just required to treat disabled but known extensions
216 the same as unknown extensions.
217
218 The following suggestion for section 8.2 gives two grammars, one for
219 the framework, and one for specific commands, thus removing most of the
220 semantic analysis.  Since the parser can not parse unsupported extensions,
221 the result is strict error checking.  As required in section 2.10.5, known
222 but not enabled extensions must behave the same as unknown extensions,
223 so those also result strictly in errors (though at the thin semantic
224 layer), even if they can be parsed fine.
225
226 8.2. Grammar
227
228 The atoms of the grammar are lexical tokens.  White space or comments may
229 appear anywhere between lexical tokens, they are not part of the grammar.
230 The grammar is specified in ABNF with two extensions to describe tagged
231 arguments that can be reordered and grammar extensions: { } denotes a
232 sequence of symbols that may appear in any order.  Example:
233
234   start =  { a b c }
235
236 is equivalent to:
237
238   start =  ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
239
240 The symbol =) is used to append to a rule:
241
242   start =  a
243   start =) b
244
245 is equivalent to
246
247   start =  a b
248
249 All Sieve commands, including extensions, MUST be words of the following
250 generic grammar with the start symbol "start".  They SHOULD be specified
251 using a specific grammar, though.
252
253    argument        = string-list / number / tag
254    arguments       = *argument [test / test-list]
255    block           = "{" commands "}"
256    commands        = *command
257    string          = quoted-string / multi-line
258    string-list     = "[" string *("," string) "]" / string
259    test            = identifier arguments
260    test-list       = "(" test *("," test) ")"
261    command         = identifier arguments ( ";" / block )
262    start           = command
263
264 The basic Sieve commands are specified using the following grammar, which
265 language is a subset of the generic grammar above.  The start symbol is
266 "start".
267
268   address-part     =  ":localpart" / ":domain" / ":all"
269   comparator       =  ":comparator" string
270   match-type       =  ":is" / ":contains" / ":matches"
271   string           =  quoted-string / multi-line
272   string-list      =  "[" string *("," string) "]" / string
273   address-test     =  "address" { [address-part] [comparator] [match-type] }
274                       string-list string-list
275   test-list        =  "(" test *("," test) ")"
276   allof-test       =  "allof" test-list
277   anyof-test       =  "anyof" test-list
278   exists-test      =  "exists" string-list
279   false-test       =  "false"
280   true=test        =  "true"
281   header-test      =  "header" { [comparator] [match-type] }
282                       string-list string-list
283   not-test         =  "not" test
284   relop            =  ":over" / ":under"
285   size-test        =  "size" relop number
286   block            =  "{" commands "}"
287   if-command       =  "if" test block *( "elsif" test block ) [ "else" block ]
288   stop-command     =  "stop" { stop-options } ";"
289   stop-options     =
290   keep-command     =  "keep" { keep-options } ";"
291   keep-options     =
292   discard-command  =  "discard" { discard-options } ";"
293   discard-options  =
294   redirect-command =  "redirect" { redirect-options } string ";"
295   redirect-options =
296   require-command  =  "require" { require-options } string-list ";"
297   require-options  =
298   test             =  address-test / allof-test / anyof-test / exists-test
299                       / false-test / true-test / header-test / not-test
300                       / size-test
301   command          =  if-command / stop-command / keep-command
302                       / discard-command / redirect-command
303   commands         =  *command
304   start            =  *require-command commands
305
306 The extensions "envelope" and "fileinto" are specified using the following
307 grammar extension.
308
309   envelope-test    =  "envelope" { [comparator] [address-part] [match-type] }
310                       string-list string-list
311   test             =/ envelope-test
312
313   fileinto-command =  "fileinto" { fileinto-options } string ";"
314   fileinto-options =
315   command          =/ fileinto-command
316
317 The extension "copy" is specified as:
318
319   fileinto-options =) ":copy"
320   redirect-options =) ":copy"
321
322
323 The i;ascii-numeric Comparator
324
325 RFC 2244 describes this comparator and specifies that non-numeric strings
326 are considered equal with an ordinal value higher than any numeric string.
327 Although not stated explicitly, this includes the empty string.  A range
328 of at least 2^31 is required.  This implementation does not limit the
329 range, because it does not convert numbers to binary representation
330 before comparing them.
331
332
333 The vacation extension
334
335 The extension "vacation" is specified using the following grammar
336 extension.
337
338   vacation-command =  "vacation" { vacation-options } <reason: string>
339   vacation-options =  [":days" number]
340                       [":addresses" string-list]
341                       [":subject" string]
342                       [":mime"]
343   command          =/ vacation-command
344
345
346 Semantics Of ":mime"
347
348 RFC 3028 does not specify how strings using MIME parts are used to compose
349 messages.  The vacation draft refers to RFC 3028 and does not specify it
350 either.  As a result, different implementations generate different mails.
351 The Exim Sieve implementation splits the reason into header and body.
352 It adds the header to the mail header and uses the body as mail body.
353 Be aware, that other imlementations compose a multipart structure with
354 the reason as only part.  Both conform to the specification (or lack
355 thereof).
356
357
358 Semantics Of Not Using ":mime"
359
360 Sieve scripts are written in UTF-8, so is the reason string in this
361 case.  This implementation adds MIME headers to indicate that.  This
362 is not required by the vacation draft, which does not specify how
363 the UTF-8 reason is processed to compose the resulting message.
364
365
366 Envelope Sender
367
368 The vacation draft does not specify the envelope sender.  This
369 implementation uses the empty envelope sender to prevent mail loops.
370
371
372 Default Subject
373
374 The draft specifies that the default message subject is "Re: "
375 plus the old subject, stripped by any leading "Re: " strings.
376 This string is to be taken literally, unlike some software which
377 matches a regular expression like "[rR][eE]: *".  Using this
378 subject is dangerous, because many mailing lists verify addresses
379 by sending a secret key in the subject of a message, asking to
380 reply to the message for confirmation.  Using the default vacation
381 subject confirms any subscription request of this kind, allowing
382 to subscribe a third party to any mailing list, either to annoy
383 the user or to declare spam as legitimate mail by proving to
384 use opt-in.  The draft specifies to use "Re: " in front of the
385 subject, but this implementation uses "Auto: ", as suggested in
386 the current draft concerning automatic mail responses.
387
388
389 Rate Limiting Responses
390
391 The draft says:
392
393      Vacation responses are not just per address, but are per address
394      per vacation command.
395
396 This is badly worded, because commands are not enumerated.  It meant
397 to say:
398
399      Vacation responses are not just per address, but are per address
400      per reason string and per specified subject and ":mime" option.
401
402 Existing implementations work that way and it makes more sense, too.
403 Including the ":mime" option is mostly for correctness, as the reason
404 strings with and without this option are rarely equal.
405
406 This implementation hashes the reason, specified subject and ":mime"
407 option and uses the hex string representation as filename within the
408 "sieve_vacation_directory" to store the recipient addresses for this
409 vacation parameter set.
410
411 The draft specifies that sites may define a minimum ":days" value than 1.
412 This implementation uses 1.  The maximum value MUST greater than 7,
413 and SHOULD be greater than 30.  This implementation uses a maximum of 31.
414
415 Vacation recipient address databases older than 31 days are automatically
416 removed.  Users do not have to remove them manually when modifying their
417 scripts.  Don't put anything but vacation databases in that directory
418 or you risk that it will be removed, too!
419
420
421 Global Reply Address Blacklist
422
423 The draft requires that each implementation offers a global black list
424 of addresses that will never be replied to.  Exim offers this as option
425 "never_mail" in the autoreply transport.
426
427
428 Interaction With Other Sieve Elements
429
430 The draft describes the interaction with vacation, discard, keep,
431 fileinto and redirect.  It MUST describe compatibility with other
432 actions, but doesn't.  In this implementation, vacation is compatible
433 with any other action.