README
1Exim Documentation
2------------------
3
4This directory should contain the following files:
5
6 ChangeLog most recent log of all changes to Exim
7 NewStuff features that haven't made it to the manual yet,
8 and/or a list of newly-added functionality
9 OptionLists.txt lists of all Exim's options
10 README this document
11 README.SIEVE notes on the Sieve support
12 Exim3.upgrade information about upgrading from release 2.12 to 3.00
13 Exim4.upgrade information about upgrading from release 3.33 to 4.00
14 dbm.discuss.txt discussion of DBM libraries
15 filter.txt specification of filter file contents
16 spec.txt main specification of Exim
17 experimental-spec.txt specification of experimental features
18
19
20PostScript
21----------
22
23The Exim specifications are also available in PostScript. This is not included
24in the main distribution because not everyone wants it. Wherever you got this
25distribution from should also have carried another file called
26exim-postscript-<version>.tar.gz which contains the PostScript documentation.
27When de-tarred it creates a directory called exim-postscript-<version> into
28which it places the files doc/filter.ps and doc/spec.ps.
29
30
31HTML
32----
33
34A conversion from the original sources into HTML is done to create the online
35documentation at http://www.exim.org. This set of files is also available for
36installation on other servers. Wherever you got this distribution from should
37also have carried another file called exim-html-<version>.tar.gz which contains
38the HTML documentation. When de-tarred it creates a directory called
39exim-html-<version> into which it places a directory called doc/html containing
40the set of HTML files. The kick off point is the traditional index.html.
41
42
43PDF
44---
45
46The Exim specifications are available in Portable Document Format. Wherever you
47got this distribution from should also have carried another file called
48exim-pdf-<version>.tar.gz which contains the PDF documentation. When de-tarred
49it creates a directory called exim-pdf-<version> into which it places the files
50doc/filter.pdf and doc/spec.pdf.
51
52
53TeXinfo
54-------
55
56A version of the documentation that has been converted to TeXinfo format is
57available in the distribution file exim-texinfo-<version>.gz. When de-tarred it
58creates a directory called exim-texinfo-<version> into which it places the
59files doc/filter.texinfo and doc/spec.texinfo.
60
61The conversion process is automatic, so the result isn't as nice as
62hand-maintained TeXinfo files would be, and some information is lost; for
63example, TeXinfo does not support the use of change bars.
64
65-- End --
66
README.SIEVE
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
14Sieve is a standard for interoperable filters, defined in RFC 5228,
15with multiple implementations around. If interoperability is important,
16then there is no way around it.
17
18
19Exim Implementation
20
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).
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
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
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} \
72 {$home/mail/$address_file} \
73 }} \
74 }
75 delivery_date_add
76 envelope_to_add
77 return_path_add
78 mode = 0600
79
80vacation:
81 driver = autoreply
82
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.
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 5228 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
106The folder specified by "fileinto" must not contain the character
107sequence ".." to avoid security problems. RFC 5228 does not specify the
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
112"inbox". RFC 5228 requires that the user is notified of that condition.
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
116The automatic replies generated by "vacation" do not contain an updated
117"references" header field.
118
119
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
128Semantics Of Fileinto
129
130RFC 5228 does not specify if "fileinto" tries to create a mail folder,
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
137Allof And Anyof Test
138
139RFC 5228 does not specify if these tests use shortcut/lazy evaluation.
140Exim uses shortcut evaluation.
141
142
143Action Reordering
144
145RFC 5228 does not specify if actions may be executed out of order.
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
151Sieve Syntax And Semantics
152
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
163until "stop" is executed or the end of the script is reached.
164
1658.2. Grammar
166
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
171 options = a b c
172 start = { options }
173
174is equivalent to:
175
176 start = ( a b c ) / ( a c b ) / ( b a c ) / ( b c a ) / ( c a b ) / ( c b a )
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
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]
263 [":subject" string]
264 [":from" string]
265 [":addresses" string-list]
266 [":mime"]
267 [":handle" string]
268 command =/ vacation-command
269
270
271Semantics Of ":mime"
272
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 implementations compose a multipart
278structure with the reason as only part. Both conform to the specification
279(or lack thereof).
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
290Default Subject
291
292RFC 5230 specifies that the default message subject is "Auto: " plus
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.
299
300
301Rate Limiting Responses
302
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.
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.
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.
344