Add comments about "!" to configure.default.
[exim.git] / doc / doc-txt / README.SIEVE
CommitLineData
87fcc8b9 1$Cambridge: exim/doc/doc-txt/README.SIEVE,v 1.8 2005/11/14 11:41:23 ph10 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
16Sieve is a standard for interoperable filters, defined in RFC 3028,
17with multiple implementations around. If interoperability is important,
18then there is no way around it.
19
20
21Exim Implementation
22
1c59d63b
PH
23The Exim Sieve implementation offers the core as defined by draft
243028bis-4 (next version of RFC 3028 that fixes specification mistakes),
25the "envelope" (3028bis), the "fileinto" (3028bis), the "copy" (RFC 3894)
87fcc8b9 26and the "vacation" (draft-ietf-sieve-vacation-04.txt) extension, the
1c59d63b 27"i;ascii-numeric" comparator (RFC 2244).
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
98RFC 3028 requires using CRLF to terminate the end of a line.
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
PH
106Sieve scripts can not contain NUL characters in strings, but mail
107headers could contain MIME encoded NUL characters, which could never
108be matched by Sieve scripts using exact comparisons. For that reason,
109this implementation extends the Sieve quoted string syntax with \0
110to describe a NUL character, violating \0 being the same as 0 in
1c59d63b 111RFC 3028.
495ae4b0
PH
112
113The folder specified by "fileinto" must not contain the character
1c59d63b 114sequence ".." to avoid security problems. RFC 3028 does not specify the
495ae4b0
PH
115syntax of folders apart from keep being equivalent to fileinto "INBOX".
116This implementation uses "inbox" instead.
117
118Sieve script errors currently cause that messages are silently filed into
119"inbox". RFC 3028 requires that the user is notified of that condition.
120This may be implemented in future by adding a header line to mails that
121are filed into "inbox" due to an error in the filter.
122
87fcc8b9
PH
123The automatic replies generated by "vacation" do not contain an updated
124"references" header field.
125
495ae4b0 126
495ae4b0
PH
127Semantics Of Keep
128
129The keep command is equivalent to fileinto "inbox": It saves the
130message and resets the implicit keep flag. It does not set the
131implicit keep flag; there is no command to set it once it has
132been reset.
133
134
135Semantics of Fileinto
136
137RFC 3028 does not specify if "fileinto" tries to create a mail folder,
138in case it does not exist. This implementation allows to configure
139that aspect using the appendfile transport options "create_directory",
140"create_file" and "file_must_exist". See the appendfile transport in
141the Exim specification for details.
142
143
495ae4b0
PH
144Sieve Syntax and Semantics
145
146RFC 3028 confuses syntax and semantics sometimes. It uses a generic
1c59d63b
PH
147grammar as syntax for commands and tests and performs many checks during
148semantic analysis. Syntax is specified by grammar rules, semantics
149by natural language, despite the latter often talking about syntax.
495ae4b0
PH
150The intention was to provide a framework for the syntax that describes
151current commands as well as future extensions, and describing commands
31c4e005 152by semantics.
495ae4b0 153
1c59d63b 154The following replacement for section 8.2 gives two grammars, one for
495ae4b0
PH
155the framework, and one for specific commands, thus removing most of the
156semantic analysis. Since the parser can not parse unsupported extensions,
1c59d63b
PH
157the result is strict error checking of any executed and not executed code
158until "stop" is executed or the end of the script is reached.
495ae4b0
PH
159
1608.2. Grammar
161
162The atoms of the grammar are lexical tokens. White space or comments may
163appear anywhere between lexical tokens, they are not part of the grammar.
164The grammar is specified in ABNF with two extensions to describe tagged
165arguments that can be reordered and grammar extensions: { } denotes a
166sequence of symbols that may appear in any order. Example:
167
1c59d63b
PH
168 options = a b c
169 start = { options }
495ae4b0
PH
170
171is equivalent to:
172
1c59d63b 173 start = ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
495ae4b0
PH
174
175The symbol =) is used to append to a rule:
176
177 start = a
178 start =) b
179
180is equivalent to
181
182 start = a b
183
184All Sieve commands, including extensions, MUST be words of the following
185generic grammar with the start symbol "start". They SHOULD be specified
186using a specific grammar, though.
187
188 argument = string-list / number / tag
189 arguments = *argument [test / test-list]
190 block = "{" commands "}"
191 commands = *command
192 string = quoted-string / multi-line
193 string-list = "[" string *("," string) "]" / string
194 test = identifier arguments
195 test-list = "(" test *("," test) ")"
196 command = identifier arguments ( ";" / block )
197 start = command
198
199The basic Sieve commands are specified using the following grammar, which
200language is a subset of the generic grammar above. The start symbol is
201"start".
202
203 address-part = ":localpart" / ":domain" / ":all"
204 comparator = ":comparator" string
205 match-type = ":is" / ":contains" / ":matches"
206 string = quoted-string / multi-line
207 string-list = "[" string *("," string) "]" / string
208 address-test = "address" { [address-part] [comparator] [match-type] }
209 string-list string-list
210 test-list = "(" test *("," test) ")"
211 allof-test = "allof" test-list
212 anyof-test = "anyof" test-list
213 exists-test = "exists" string-list
214 false-test = "false"
215 true=test = "true"
216 header-test = "header" { [comparator] [match-type] }
217 string-list string-list
218 not-test = "not" test
219 relop = ":over" / ":under"
220 size-test = "size" relop number
221 block = "{" commands "}"
222 if-command = "if" test block *( "elsif" test block ) [ "else" block ]
223 stop-command = "stop" { stop-options } ";"
224 stop-options =
225 keep-command = "keep" { keep-options } ";"
226 keep-options =
227 discard-command = "discard" { discard-options } ";"
228 discard-options =
229 redirect-command = "redirect" { redirect-options } string ";"
230 redirect-options =
231 require-command = "require" { require-options } string-list ";"
232 require-options =
233 test = address-test / allof-test / anyof-test / exists-test
234 / false-test / true-test / header-test / not-test
235 / size-test
236 command = if-command / stop-command / keep-command
237 / discard-command / redirect-command
238 commands = *command
239 start = *require-command commands
240
241The extensions "envelope" and "fileinto" are specified using the following
242grammar extension.
243
244 envelope-test = "envelope" { [comparator] [address-part] [match-type] }
245 string-list string-list
246 test =/ envelope-test
247
248 fileinto-command = "fileinto" { fileinto-options } string ";"
249 fileinto-options =
250 command =/ fileinto-command
251
252The extension "copy" is specified as:
253
254 fileinto-options =) ":copy"
255 redirect-options =) ":copy"
256
257
258The i;ascii-numeric Comparator
259
260RFC 2244 describes this comparator and specifies that non-numeric strings
261are considered equal with an ordinal value higher than any numeric string.
262Although not stated explicitly, this includes the empty string. A range
263of at least 2^31 is required. This implementation does not limit the
264range, because it does not convert numbers to binary representation
265before comparing them.
266
267
268The vacation extension
269
270The extension "vacation" is specified using the following grammar
271extension.
272
273 vacation-command = "vacation" { vacation-options } <reason: string>
274 vacation-options = [":days" number]
495ae4b0 275 [":subject" string]
f656d135
PH
276 [":from" string]
277 [":addresses" string-list]
495ae4b0 278 [":mime"]
f656d135 279 [":handle" string]
495ae4b0
PH
280 command =/ vacation-command
281
282
283Semantics Of ":mime"
284
f656d135
PH
285The draft does not specify how strings using MIME entities are used
286to compose messages. As a result, different implementations generate
287different mails. The Exim Sieve implementation splits the reason into
288header and body. It adds the header to the mail header and uses the body
289as mail body. Be aware, that other imlementations compose a multipart
290structure with the reason as only part. Both conform to the specification
291(or lack thereof).
495ae4b0
PH
292
293
294Semantics Of Not Using ":mime"
295
296Sieve scripts are written in UTF-8, so is the reason string in this
297case. This implementation adds MIME headers to indicate that. This
298is not required by the vacation draft, which does not specify how
299the UTF-8 reason is processed to compose the resulting message.
300
301
495ae4b0
PH
302Default Subject
303
5ea81592
PH
304The draft specifies that the default message subject is "Auto: " plus
305the old subject. Using this subject is dangerous, because many mailing
306lists verify addresses by sending a secret key in the subject of a
307message, asking to reply to the message for confirmation. Using the
308default vacation subject confirms any subscription request of this kind,
309allowing to subscribe a third party to any mailing list, either to annoy
310the user or to declare spam as legitimate mail by proving to use opt-in.
495ae4b0
PH
311
312
313Rate Limiting Responses
314
f656d135
PH
315In absence of a handle, this implementation hashes the reason,
316":subject" option, ":mime" option and ":from" option and uses the hex
317string representation as filename within the "sieve_vacation_directory"
318to store the recipient addresses for this vacation parameter set.
495ae4b0
PH
319
320The draft specifies that sites may define a minimum ":days" value than 1.
321This implementation uses 1. The maximum value MUST greater than 7,
322and SHOULD be greater than 30. This implementation uses a maximum of 31.
323
324Vacation recipient address databases older than 31 days are automatically
325removed. Users do not have to remove them manually when modifying their
326scripts. Don't put anything but vacation databases in that directory
327or you risk that it will be removed, too!
328
329
330Global Reply Address Blacklist
331
332The draft requires that each implementation offers a global black list
333of addresses that will never be replied to. Exim offers this as option
334"never_mail" in the autoreply transport.