OpenSSL 1.0.0 const fix for SSL_get_current_cipher
[users/heiko/exim.git] / doc / doc-txt / README.SIEVE
1 $Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.12 2008/01/28 12:26:31 michael 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 5228,
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 5228,
24 the "encoded-character" extension (RFC 5228), the "envelope" test (RFC
25 5228), the "fileinto" action (5228), the "copy" parameter (RFC 3894), the
26 "vacation" action (5230), the "notify" action (draft-ietf-sieve-notify-12)
27 with mailto URIs (draft-ietf-sieve-notify-mailto-05), the
28 "i;ascii-numeric" comparator (RFC 2244) and the subaddress parameter
29 (RFC 5233).
30
31 The Sieve filter is integrated in Exim and works very similar to the
32 Exim filter: Sieve scripts are recognized by the first line containing
33 "# sieve filter".  When using "keep" or "fileinto" to save a mail into a
34 folder, the resulting string is available as the variable $address_file
35 in the transport that stores it.  The following routers and transport
36 show a typical use of Sieve:
37
38 begin routers
39
40 localuser_verify:
41   driver = accept
42   domains = +localdomains
43   local_part_suffix = "-*"
44   local_part_suffix_optional
45   check_local_user
46   require_files = $home/.forward
47   verify_only = true
48
49 localuser_deliver:
50   driver = redirect
51   domains = +localdomains
52   local_part_suffix = "-*"
53   local_part_suffix_optional
54   sieve_subaddress = "${sg{$local_part_suffix}{^-}{}}"
55   sieve_useraddress = "$local_part"
56   check_local_user
57   require_files = $home/.forward
58   file = $home/.forward
59   check_ancestor
60   allow_filter
61   file_transport = localuser
62   reply_transport = vacation
63   sieve_vacation_directory = $home/mail/vacation
64   verify = false
65
66 begin transports
67
68 localuser:
69   driver = appendfile
70   file = ${if eq{$address_file}{inbox} \
71               {/var/mail/$local_part} \
72               {${if eq{${substr_0_1:$address_file}}{/} \
73                     {$address_file} \
74                     {$home/mail/$address_file} \
75               }} \
76          }
77   delivery_date_add
78   envelope_to_add
79   return_path_add
80   mode = 0600
81
82 vacation:
83   driver = autoreply
84
85 Absolute files are stored where specified, relative files are stored
86 relative to $home/mail and "inbox" goes to the standard mailbox location.
87 To enable "vacation", sieve_vacation_directory is set to the directory
88 where vacation databases are held (don't put anything else in that
89 directory) and point reply_transport to an autoreply transport.
90 Setting the Sieve useraddress and subaddress allows to use the subaddress
91 extension.
92
93
94 RFC Compliance
95
96 Exim requires the first line to be "# sieve filter".  Of course the RFC
97 does not enforce that line.  Don't expect examples to work without adding
98 it, though.
99
100 RFC 5228 requires using CRLF to terminate the end of a line.
101 The rationale was that CRLF is universally used in network protocols
102 to mark the end of the line.  This implementation does not embed Sieve
103 in a network protocol, but uses Sieve scripts as part of the Exim MTA.
104 Since all parts of Exim use \n as newline character, this implementation
105 does, too.  You can change this by defining the macro RFC_EOL at compile
106 time to enforce CRLF being used.
107
108 The folder specified by "fileinto" must not contain the character
109 sequence ".." to avoid security problems.  RFC 5228 does not specify the
110 syntax of folders apart from keep being equivalent to fileinto "INBOX".
111 This implementation uses "inbox" instead.
112
113 Sieve script errors currently cause that messages are silently filed into
114 "inbox".  RFC 5228 requires that the user is notified of that condition.
115 This may be implemented in future by adding a header line to mails that
116 are filed into "inbox" due to an error in the filter.
117
118 The automatic replies generated by "vacation" do not contain an updated
119 "references" header field.
120
121
122 Semantics Of Keep
123
124 The keep command is equivalent to fileinto "inbox": It saves the
125 message and resets the implicit keep flag.  It does not set the
126 implicit keep flag; there is no command to set it once it has
127 been reset.
128
129
130 Semantics Of Fileinto
131
132 RFC 5228 does not specify if "fileinto" tries to create a mail folder,
133 in case it does not exist.  This implementation allows to configure
134 that aspect using the appendfile transport options "create_directory",
135 "create_file" and "file_must_exist".  See the appendfile transport in
136 the Exim specification for details.
137
138
139 Allof And Anyof Test
140
141 RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
142 Exim uses shortcut evaluation.
143
144
145 Action Reordering
146
147 RFC 5228 does not specify if actions may be executed out of order.
148 Exim may execute them out of order, e.g. messages may be filed to
149 folders or forwarded in a different order than specified, because
150 those actions only setup delivery, but do not execute it themselves.
151
152
153 Sieve Syntax And Semantics
154
155 RFC 5228 uses a generic grammar as syntax for commands and tests and
156 performs many checks during semantic analysis.  Syntax is specified
157 by grammar rules, semantics by natural language.  The intention is to
158 provide a framework for the syntax that describes current commands as
159 well as future extensions, and describing commands by semantics.
160
161 The following replacement for section 8.2 gives a grammar for specific
162 commands of this implementation, thus removing most of the semantic
163 analysis.  Since the parser can not parse unsupported extensions, the
164 result is strict error checking of any executed and not executed code
165 until "stop" is executed or the end of the script is reached.
166
167 8.2. Grammar
168
169 The grammar is specified in ABNF with two extensions to describe tagged
170 arguments that can be reordered and grammar extensions: { } denotes a
171 sequence of symbols that may appear in any order.  Example:
172
173   options = a b c
174   start   = { options }
175
176 is equivalent to:
177
178   start   =  ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
179
180 The symbol =) is used to append to a rule:
181
182   start =  a
183   start =) b
184
185 is equivalent to
186
187   start =  a b
188
189 The basic Sieve commands are specified using the following grammar, which
190 language is a subset of the generic grammar above.  The start symbol is
191 "start".
192
193   address-part     =  ":localpart" / ":domain" / ":all"
194   comparator       =  ":comparator" string
195   match-type       =  ":is" / ":contains" / ":matches"
196   string           =  quoted-string / multi-line
197   string-list      =  "[" string *("," string) "]" / string
198   address-test     =  "address" { [address-part] [comparator] [match-type] }
199                       string-list string-list
200   test-list        =  "(" test *("," test) ")"
201   allof-test       =  "allof" test-list
202   anyof-test       =  "anyof" test-list
203   exists-test      =  "exists" string-list
204   false-test       =  "false"
205   true=test        =  "true"
206   header-test      =  "header" { [comparator] [match-type] }
207                       string-list string-list
208   not-test         =  "not" test
209   relop            =  ":over" / ":under"
210   size-test        =  "size" relop number
211   block            =  "{" commands "}"
212   if-command       =  "if" test block *( "elsif" test block ) [ "else" block ]
213   stop-command     =  "stop" { stop-options } ";"
214   stop-options     =
215   keep-command     =  "keep" { keep-options } ";"
216   keep-options     =
217   discard-command  =  "discard" { discard-options } ";"
218   discard-options  =
219   redirect-command =  "redirect" { redirect-options } string ";"
220   redirect-options =
221   require-command  =  "require" { require-options } string-list ";"
222   require-options  =
223   test             =  address-test / allof-test / anyof-test / exists-test
224                       / false-test / true-test / header-test / not-test
225                       / size-test
226   command          =  if-command / stop-command / keep-command
227                       / discard-command / redirect-command
228   commands         =  *command
229   start            =  *require-command commands
230
231 The extensions "envelope" and "fileinto" are specified using the following
232 grammar extension.
233
234   envelope-test    =  "envelope" { [comparator] [address-part] [match-type] }
235                       string-list string-list
236   test             =/ envelope-test
237
238   fileinto-command =  "fileinto" { fileinto-options } string ";"
239   fileinto-options =
240   command          =/ fileinto-command
241
242 The extension "copy" is specified as:
243
244   fileinto-options =) ":copy"
245   redirect-options =) ":copy"
246
247
248 The i;ascii-numeric Comparator
249
250 RFC 2244 describes this comparator and specifies that non-numeric strings
251 are considered equal with an ordinal value higher than any numeric string.
252 Although not stated explicitly, this includes the empty string.  A range
253 of at least 2^31 is required.  This implementation does not limit the
254 range, because it does not convert numbers to binary representation
255 before comparing them.
256
257
258 The vacation extension
259
260 The extension "vacation" is specified using the following grammar
261 extension.
262
263   vacation-command =  "vacation" { vacation-options } <reason: string>
264   vacation-options =  [":days" number]
265                       [":subject" string]
266                       [":from" string]
267                       [":addresses" string-list]
268                       [":mime"]
269                       [":handle" string]
270   command          =/ vacation-command
271
272
273 Semantics Of ":mime"
274
275 The draft does not specify how strings using MIME entities are used
276 to compose messages.  As a result, different implementations generate
277 different mails.  The Exim Sieve implementation splits the reason into
278 header and body.  It adds the header to the mail header and uses the body
279 as mail body.  Be aware, that other imlementations compose a multipart
280 structure with the reason as only part.  Both conform to the specification
281 (or lack thereof).
282
283
284 Semantics Of Not Using ":mime"
285
286 Sieve scripts are written in UTF-8, so is the reason string in this
287 case.  This implementation adds MIME headers to indicate that.  This
288 is not required by the vacation draft, which does not specify how
289 the UTF-8 reason is processed to compose the resulting message.
290
291
292 Default Subject
293
294 RFC 5230 specifies that the default message subject is "Auto: " plus
295 the old subject.  Using this subject is dangerous, because many mailing
296 lists verify addresses by sending a secret key in the subject of a
297 message, asking to reply to the message for confirmation.  Using the
298 default vacation subject confirms any subscription request of this kind,
299 allowing to subscribe a third party to any mailing list, either to annoy
300 the user or to declare spam as legitimate mail by proving to use opt-in.
301
302
303 Rate Limiting Responses
304
305 In absence of a handle, this implementation hashes the reason,
306 ":subject" option, ":mime" option and ":from" option and uses the hex
307 string representation as filename within the "sieve_vacation_directory"
308 to store the recipient addresses for this vacation parameter set.
309
310 The draft specifies that sites may define a minimum ":days" value than 1.
311 This implementation uses 1.  The maximum value MUST greater than 7,
312 and SHOULD be greater than 30.  This implementation uses a maximum of 31.
313
314 Vacation recipient address databases older than 31 days are automatically
315 removed.  Users do not have to remove them manually when modifying their
316 scripts.  Don't put anything but vacation databases in that directory
317 or you risk that it will be removed, too!
318
319
320 Global Reply Address Blacklist
321
322 The draft requires that each implementation offers a global black list
323 of addresses that will never be replied to.  Exim offers this as option
324 "never_mail" in the autoreply transport.
325
326
327 The enotify extension
328
329 The extension "enotify" is specified using the following grammar
330 extension.
331
332   notify-command =  "notify" { notify-options } <method: string>
333   notify-options =  [":from" string]
334                     [":importance" <"1" / "2" / "3">]
335                     [":options" 1*(string-list / number)]
336                     [":message" string]
337
338   command          =/ notify-command
339
340   valid_notify_method = "valid_notify_method"
341                         <notification-uris: string-list>
342
343   test             =/ valid_notify_method
344
345 Only the mailto URI scheme is implemented.