Refer to the new SIEVE RFCs instead of the drafts.
[exim.git] / doc / doc-txt / README.SIEVE
CommitLineData
eed2e0b1 1$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.12 2008/01/28 12:26:31 michael Exp $
495ae4b0
PH
2
3 Notes on the Sieve implementation for Exim
4
5Exim Filter Versus Sieve Filter
6
7Exim supports two incompatible filters: The traditional Exim filter and
8the Sieve filter. Since Sieve is a extensible language, it is important
9to understand "Sieve" in this context as "the specific implementation
10of Sieve for Exim".
11
12The Exim filter contains more features, such as variable expansion, and
13better integration with the host environment, like external processes
14and pipes.
15
eed2e0b1 16Sieve is a standard for interoperable filters, defined in RFC 5228,
495ae4b0
PH
17with multiple implementations around. If interoperability is important,
18then there is no way around it.
19
20
21Exim Implementation
22
eed2e0b1
MH
23The Exim Sieve implementation offers the core as defined by RFC 5228,
24the "encoded-character" extension (RFC 5228), the "envelope" test (RFC
255228), the "fileinto" action (5228), the "copy" parameter (RFC 3894), the
26"vacation" action (5230), the "notify" action (draft-ietf-sieve-notify-12)
27with mailto URIs (draft-ietf-sieve-notify-mailto-05), the
28"i;ascii-numeric" comparator (RFC 2244) and the subaddress parameter
29(RFC 5233).
495ae4b0
PH
30
31The Sieve filter is integrated in Exim and works very similar to the
32Exim filter: Sieve scripts are recognized by the first line containing
33"# sieve filter". When using "keep" or "fileinto" to save a mail into a
34folder, the resulting string is available as the variable $address_file
1c59d63b
PH
35in the transport that stores it. The following routers and transport
36show a typical use of Sieve:
37
38begin routers
39
40localuser_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
49localuser_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
66begin transports
495ae4b0
PH
67
68localuser:
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} \
1c59d63b 74 {$home/mail/$address_file} \
495ae4b0
PH
75 }} \
76 }
77 delivery_date_add
78 envelope_to_add
79 return_path_add
80 mode = 0600
81
1c59d63b
PH
82vacation:
83 driver = autoreply
495ae4b0 84
1c59d63b
PH
85Absolute files are stored where specified, relative files are stored
86relative to $home/mail and "inbox" goes to the standard mailbox location.
87To enable "vacation", sieve_vacation_directory is set to the directory
88where vacation databases are held (don't put anything else in that
89directory) and point reply_transport to an autoreply transport.
90Setting the Sieve useraddress and subaddress allows to use the subaddress
91extension.
495ae4b0
PH
92
93
94RFC Compliance
95
96Exim requires the first line to be "# sieve filter". Of course the RFC
97does not enforce that line. Don't expect examples to work without adding
98it, though.
99
eed2e0b1 100RFC 5228 requires using CRLF to terminate the end of a line.
495ae4b0
PH
101The rationale was that CRLF is universally used in network protocols
102to mark the end of the line. This implementation does not embed Sieve
103in a network protocol, but uses Sieve scripts as part of the Exim MTA.
104Since all parts of Exim use \n as newline character, this implementation
105does, too. You can change this by defining the macro RFC_EOL at compile
106time to enforce CRLF being used.
107
495ae4b0 108The folder specified by "fileinto" must not contain the character
eed2e0b1 109sequence ".." to avoid security problems. RFC 5228 does not specify the
495ae4b0
PH
110syntax of folders apart from keep being equivalent to fileinto "INBOX".
111This implementation uses "inbox" instead.
112
113Sieve script errors currently cause that messages are silently filed into
eed2e0b1 114"inbox". RFC 5228 requires that the user is notified of that condition.
495ae4b0
PH
115This may be implemented in future by adding a header line to mails that
116are filed into "inbox" due to an error in the filter.
117
87fcc8b9
PH
118The automatic replies generated by "vacation" do not contain an updated
119"references" header field.
120
495ae4b0 121
495ae4b0
PH
122Semantics Of Keep
123
124The keep command is equivalent to fileinto "inbox": It saves the
125message and resets the implicit keep flag. It does not set the
126implicit keep flag; there is no command to set it once it has
127been reset.
128
129
024bd3c2 130Semantics Of Fileinto
495ae4b0 131
eed2e0b1 132RFC 5228 does not specify if "fileinto" tries to create a mail folder,
495ae4b0
PH
133in case it does not exist. This implementation allows to configure
134that aspect using the appendfile transport options "create_directory",
135"create_file" and "file_must_exist". See the appendfile transport in
136the Exim specification for details.
137
138
024bd3c2
PH
139Allof And Anyof Test
140
eed2e0b1 141RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
024bd3c2
PH
142Exim uses shortcut evaluation.
143
144
145Action Reordering
146
eed2e0b1 147RFC 5228 does not specify if actions may be executed out of order.
024bd3c2
PH
148Exim may execute them out of order, e.g. messages may be filed to
149folders or forwarded in a different order than specified, because
150those actions only setup delivery, but do not execute it themselves.
151
152
024bd3c2 153Sieve Syntax And Semantics
495ae4b0 154
eed2e0b1
MH
155RFC 5228 uses a generic grammar as syntax for commands and tests and
156performs many checks during semantic analysis. Syntax is specified
157by grammar rules, semantics by natural language. The intention is to
158provide a framework for the syntax that describes current commands as
159well as future extensions, and describing commands by semantics.
160
161The following replacement for section 8.2 gives a grammar for specific
162commands of this implementation, thus removing most of the semantic
163analysis. Since the parser can not parse unsupported extensions, the
164result is strict error checking of any executed and not executed code
1c59d63b 165until "stop" is executed or the end of the script is reached.
495ae4b0
PH
166
1678.2. Grammar
168
495ae4b0
PH
169The grammar is specified in ABNF with two extensions to describe tagged
170arguments that can be reordered and grammar extensions: { } denotes a
171sequence of symbols that may appear in any order. Example:
172
1c59d63b
PH
173 options = a b c
174 start = { options }
495ae4b0
PH
175
176is equivalent to:
177
1c59d63b 178 start = ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
495ae4b0
PH
179
180The symbol =) is used to append to a rule:
181
182 start = a
183 start =) b
184
185is equivalent to
186
187 start = a b
188
495ae4b0
PH
189The basic Sieve commands are specified using the following grammar, which
190language 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
231The extensions "envelope" and "fileinto" are specified using the following
232grammar 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
242The extension "copy" is specified as:
243
244 fileinto-options =) ":copy"
245 redirect-options =) ":copy"
246
247
248The i;ascii-numeric Comparator
249
250RFC 2244 describes this comparator and specifies that non-numeric strings
251are considered equal with an ordinal value higher than any numeric string.
252Although not stated explicitly, this includes the empty string. A range
253of at least 2^31 is required. This implementation does not limit the
254range, because it does not convert numbers to binary representation
255before comparing them.
256
257
258The vacation extension
259
260The extension "vacation" is specified using the following grammar
261extension.
262
263 vacation-command = "vacation" { vacation-options } <reason: string>
264 vacation-options = [":days" number]
495ae4b0 265 [":subject" string]
f656d135
PH
266 [":from" string]
267 [":addresses" string-list]
495ae4b0 268 [":mime"]
f656d135 269 [":handle" string]
495ae4b0
PH
270 command =/ vacation-command
271
272
273Semantics Of ":mime"
274
f656d135
PH
275The draft does not specify how strings using MIME entities are used
276to compose messages. As a result, different implementations generate
277different mails. The Exim Sieve implementation splits the reason into
278header and body. It adds the header to the mail header and uses the body
279as mail body. Be aware, that other imlementations compose a multipart
280structure with the reason as only part. Both conform to the specification
281(or lack thereof).
495ae4b0
PH
282
283
284Semantics Of Not Using ":mime"
285
286Sieve scripts are written in UTF-8, so is the reason string in this
287case. This implementation adds MIME headers to indicate that. This
288is not required by the vacation draft, which does not specify how
289the UTF-8 reason is processed to compose the resulting message.
290
291
495ae4b0
PH
292Default Subject
293
eed2e0b1 294RFC 5230 specifies that the default message subject is "Auto: " plus
5ea81592
PH
295the old subject. Using this subject is dangerous, because many mailing
296lists verify addresses by sending a secret key in the subject of a
297message, asking to reply to the message for confirmation. Using the
298default vacation subject confirms any subscription request of this kind,
299allowing to subscribe a third party to any mailing list, either to annoy
300the user or to declare spam as legitimate mail by proving to use opt-in.
495ae4b0
PH
301
302
303Rate Limiting Responses
304
f656d135
PH
305In absence of a handle, this implementation hashes the reason,
306":subject" option, ":mime" option and ":from" option and uses the hex
307string representation as filename within the "sieve_vacation_directory"
308to store the recipient addresses for this vacation parameter set.
495ae4b0
PH
309
310The draft specifies that sites may define a minimum ":days" value than 1.
311This implementation uses 1. The maximum value MUST greater than 7,
312and SHOULD be greater than 30. This implementation uses a maximum of 31.
313
314Vacation recipient address databases older than 31 days are automatically
315removed. Users do not have to remove them manually when modifying their
316scripts. Don't put anything but vacation databases in that directory
317or you risk that it will be removed, too!
318
319
320Global Reply Address Blacklist
321
322The draft requires that each implementation offers a global black list
323of addresses that will never be replied to. Exim offers this as option
324"never_mail" in the autoreply transport.
84024b72
PH
325
326
327The enotify extension
328
329The extension "enotify" is specified using the following grammar
330extension.
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
345Only the mailto URI scheme is implemented.