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