Commit | Line | Data |
---|---|---|
9b371988 PH |
1 | . ///////////////////////////////////////////////////////////////////////////// |
2 | . This is the primary source of the document that describes Exim's filtering | |
3 | . facilities. It is an xfpt document that is converted into DocBook XML for | |
4 | . subsequent conversion into printing and online formats. The markup used | |
5 | . herein is "standard" xfpt markup, with some extras. The markup is summarized | |
6 | . in a file called Markup.txt. | |
7 | . ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | .include stdflags | |
10 | .include stdmacs | |
2aee48d6 | 11 | .include ./local_params |
9b371988 | 12 | .docbook |
f89d2485 PH |
13 | |
14 | . ///////////////////////////////////////////////////////////////////////////// | |
15 | . These lines are processing instructions for the Simple DocBook Processor that | |
16 | . Philip Hazel has developed as a less cumbersome way of making PostScript and | |
17 | . PDFs than using xmlto and fop. They will be ignored by all other XML | |
18 | . processors. | |
19 | . ///////////////////////////////////////////////////////////////////////////// | |
20 | ||
21 | .literal xml | |
22 | <?sdop | |
23 | foot_right_recto="&chaptertitle;" | |
24 | foot_right_verso="&chaptertitle;" | |
2ff4a98a | 25 | table_warn_overflow="overprint" |
f89d2485 PH |
26 | toc_chapter_blanks="yes,yes" |
27 | toc_title="Exim's interfaces to mail filtering" | |
28 | ?> | |
29 | .literal off | |
30 | ||
9b371988 PH |
31 | .book |
32 | ||
33 | . =========================================================================== | |
34 | . Additional xfpt markup used by this document, over and above the default | |
35 | . provided in the xfpt library. | |
36 | ||
37 | . Override the &$ flag to automatically insert a $ with the variable name | |
38 | ||
39 | .flag &$ $& "<varname>$" "</varname>" | |
40 | ||
41 | . A macro for the common 2-column tables | |
42 | ||
43 | .macro table2 100pt 300pt | |
44 | .itable none 0 0 2 $1 left $2 left | |
45 | .endmacro | |
46 | . =========================================================================== | |
47 | ||
7d837ca7 JH |
48 | . Copyright year. Update this (only) when changing content. |
49 | ||
50 | .macro copyyear | |
51 | 2010 | |
52 | .endmacro | |
53 | ||
54 | . =========================================================================== | |
9b371988 | 55 | |
f89d2485 PH |
56 | . ///////////////////////////////////////////////////////////////////////////// |
57 | . ///////////////////////////////////////////////////////////////////////////// | |
58 | ||
9b371988 PH |
59 | . This preliminary stuff creates a <bookinfo> entry in the XML. This is removed |
60 | . when creating the PostScript/PDF output, because we do not want a full-blown | |
f89d2485 PH |
61 | . title page created for those versions. When fop is being used to create |
62 | . PS/PDF, the stylesheet fudges up a title line to replace the text "Table of | |
63 | . contents". When SDoP is being used, a processing instruction does this job. | |
64 | . For the other forms of output, the <bookinfo> element is retained and used. | |
9b371988 PH |
65 | |
66 | .literal xml | |
67 | <bookinfo> | |
68 | <title>Exim's interfaces to mail filtering</title> | |
69 | <titleabbrev>Exim filtering</titleabbrev> | |
2aee48d6 JH |
70 | <date> |
71 | .fulldate | |
72 | </date> | |
9b371988 PH |
73 | <author><firstname>Philip</firstname><surname>Hazel</surname></author> |
74 | <authorinitials>PH</authorinitials> | |
75 | <revhistory><revision> | |
2aee48d6 JH |
76 | <revnumber> |
77 | .version | |
78 | </revnumber> | |
79 | <date> | |
80 | .fulldate | |
81 | </date> | |
9b371988 PH |
82 | <authorinitials>PH</authorinitials> |
83 | </revision></revhistory> | |
2aee48d6 | 84 | <copyright><year> |
7d837ca7 | 85 | .copyyear |
2aee48d6 | 86 | </year><holder>University of Cambridge</holder></copyright> |
9b371988 PH |
87 | </bookinfo> |
88 | .literal off | |
89 | ||
f89d2485 PH |
90 | . ///////////////////////////////////////////////////////////////////////////// |
91 | . ///////////////////////////////////////////////////////////////////////////// | |
92 | ||
9b371988 | 93 | |
4aa45c31 | 94 | .chapter "Forwarding and filtering in Exim" "CHAPforandfilt" |
9b371988 | 95 | This document describes the user interfaces to Exim's in-built mail filtering |
7d837ca7 | 96 | facilities, and is copyright © University of Cambridge ©year(). It |
2aee48d6 | 97 | corresponds to Exim version &version(). |
9b371988 PH |
98 | |
99 | ||
100 | ||
4aa45c31 | 101 | .section "Introduction" "SEC00" |
9b371988 PH |
102 | Most Unix mail transfer agents (programs that deliver mail) permit individual |
103 | users to specify automatic forwarding of their mail, usually by placing a list | |
104 | of forwarding addresses in a file called &_.forward_& in their home | |
105 | directories. Exim extends this facility by allowing the forwarding instructions | |
106 | to be a set of rules rather than just a list of addresses, in effect providing | |
107 | &"&_.forward_& with conditions"&. Operating the set of rules is called | |
108 | &'filtering'&, and the file that contains them is called a &'filter file'&. | |
109 | ||
110 | Exim supports two different kinds of filter file. An &'Exim filter'& contains | |
111 | instructions in a format that is unique to Exim. A &'Sieve filter'& contains | |
112 | instructions in the Sieve format that is defined by RFC 3028. As this is a | |
113 | standard format, Sieve filter files may already be familiar to some users. | |
114 | Sieve files should also be portable between different environments. However, | |
115 | the Exim filtering facility contains more features (such as variable | |
116 | expansion), and better integration with the host environment (such as the use | |
117 | of external processes and pipes). | |
118 | ||
119 | The choice of which kind of filter to use can be left to the end-user, provided | |
120 | that the system administrator has configured Exim appropriately for both kinds | |
121 | of filter. However, if interoperability is important, Sieve is the only | |
122 | choice. | |
123 | ||
124 | The ability to use filtering or traditional forwarding has to be enabled by the | |
125 | system administrator, and some of the individual facilities can be separately | |
126 | enabled or disabled. A local document should be provided to describe exactly | |
127 | what has been enabled. In the absence of this, consult your system | |
128 | administrator. | |
129 | ||
130 | This document describes how to use a filter file and the format of its | |
131 | contents. It is intended for use by end-users. Both Sieve filters and Exim | |
132 | filters are covered. However, for Sieve filters, only issues that relate to the | |
133 | Exim implementation are discussed, since Sieve itself is described elsewhere. | |
134 | ||
135 | The contents of traditional &_.forward_& files are not described here. They | |
136 | normally contain just a list of addresses, file names, or pipe commands, | |
137 | separated by commas or newlines, but other types of item are also available. | |
138 | The full details can be found in the chapter on the &(redirect)& router in the | |
139 | Exim specification, which also describes how the system administrator can set | |
140 | up and control the use of filtering. | |
141 | ||
142 | ||
143 | ||
4aa45c31 | 144 | .section "Filter operation" "SEC01" |
9b371988 PH |
145 | It is important to realize that, in Exim, no deliveries are actually made while |
146 | a filter or traditional &_.forward_& file is being processed. Running a filter | |
147 | or processing a traditional &_.forward_& file sets up future delivery | |
148 | operations, but does not carry them out. | |
149 | ||
150 | The result of filter or &_.forward_& file processing is a list of destinations | |
151 | to which a message should be delivered. The deliveries themselves take place | |
152 | later, along with all other deliveries for the message. This means that it is | |
153 | not possible to test for successful deliveries while filtering. It also means | |
154 | that any duplicate addresses that are generated are dropped, because Exim never | |
155 | delivers the same message to the same address more than once. | |
156 | ||
157 | ||
158 | ||
159 | ||
160 | .section "Testing a new filter file" "SECTtesting" | |
161 | Filter files, especially the more complicated ones, should always be tested, as | |
162 | it is easy to make mistakes. Exim provides a facility for preliminary testing | |
163 | of a filter file before installing it. This tests the syntax of the file and | |
164 | its basic operation, and can also be used with traditional &_.forward_& files. | |
165 | ||
166 | Because a filter can do tests on the content of messages, a test message is | |
167 | required. Suppose you have a new filter file called &_myfilter_& and a test | |
168 | message in a file called &_test-message_&. Assuming that Exim is installed with | |
169 | the conventional path name &_/usr/sbin/sendmail_& (some operating systems use | |
170 | &_/usr/lib/sendmail_&), the following command can be used: | |
171 | .code | |
172 | /usr/sbin/sendmail -bf myfilter <test-message | |
173 | .endd | |
174 | The &%-bf%& option tells Exim that the following item on the command line is | |
175 | the name of a filter file that is to be tested. There is also a &%-bF%& option, | |
176 | which is similar, but which is used for testing system filter files, as opposed | |
177 | to user filter files, and which is therefore of use only to the system | |
178 | administrator. | |
179 | ||
180 | The test message is supplied on the standard input. If there are no | |
181 | message-dependent tests in the filter, an empty file (&_/dev/null_&) can be | |
182 | used. A supplied message must start with header lines or the &"From&~"& message | |
183 | separator line that is found in many multi-message folder files. Note that | |
184 | blank lines at the start terminate the header lines. A warning is given if no | |
185 | header lines are read. | |
186 | ||
187 | The result of running this command, provided no errors are detected in the | |
188 | filter file, is a list of the actions that Exim would try to take if presented | |
189 | with the message for real. For example, for an Exim filter, the output | |
190 | .code | |
191 | Deliver message to: gulliver@lilliput.fict.example | |
192 | Save message to: /home/lemuel/mail/archive | |
193 | .endd | |
194 | means that one copy of the message would be sent to | |
195 | &'gulliver@lilliput.fict.example'&, and another would be added to the file | |
196 | &_/home/lemuel/mail/archive_&, if all went well. | |
197 | ||
198 | The actions themselves are not attempted while testing a filter file in this | |
199 | way; there is no check, for example, that any forwarding addresses are valid. | |
200 | For an Exim filter, if you want to know why a particular action is being taken, | |
201 | add the &%-v%& option to the command. This causes Exim to output the results of | |
202 | any conditional tests and to indent its output according to the depth of | |
203 | nesting of &(if)& commands. Further additional output from a filter test can be | |
204 | generated by the &(testprint)& command, which is described below. | |
205 | ||
206 | When Exim is outputting a list of the actions it would take, if any text | |
207 | strings are included in the output, non-printing characters therein are | |
208 | converted to escape sequences. In particular, if any text string contains a | |
209 | newline character, this is shown as &"\n"& in the testing output. | |
210 | ||
211 | When testing a filter in this way, Exim makes up an &"envelope"& for the | |
212 | message. The recipient is by default the user running the command, and so is | |
213 | the sender, but the command can be run with the &%-f%& option to supply a | |
214 | different sender. For example, | |
215 | .code | |
216 | /usr/sbin/sendmail -bf myfilter \ | |
217 | -f islington@never.where <test-message | |
218 | .endd | |
219 | Alternatively, if the &%-f%& option is not used, but the first line of the | |
220 | supplied message is a &"From&~"& separator from a message folder file (not the | |
221 | same thing as a &'From:'& header line), the sender is taken from there. If | |
222 | &%-f%& is present, the contents of any &"From&~"& line are ignored. | |
223 | ||
224 | The &"return path"& is the same as the envelope sender, unless the message | |
225 | contains a &'Return-path:'& header, in which case it is taken from there. You | |
226 | need not worry about any of this unless you want to test out features of a | |
227 | filter file that rely on the sender address or the return path. | |
228 | ||
229 | It is possible to change the envelope recipient by specifying further options. | |
230 | The &%-bfd%& option changes the domain of the recipient address, while the | |
231 | &%-bfl%& option changes the &"local part"&, that is, the part before the @ | |
232 | sign. An adviser could make use of these to test someone else's filter file. | |
233 | ||
234 | The &%-bfp%& and &%-bfs%& options specify the prefix or suffix for the local | |
235 | part. These are relevant only when support for multiple personal mailboxes is | |
236 | implemented; see the description in section &<<SECTmbox>>& below. | |
237 | ||
238 | ||
4aa45c31 | 239 | .section "Installing a filter file" "SEC02" |
9b371988 PH |
240 | A filter file is normally installed under the name &_.forward_& in your home |
241 | directory &-- it is distinguished from a conventional &_.forward_& file by its | |
242 | first line (described below). However, the file name is configurable, and some | |
243 | system administrators may choose to use some different name or location for | |
244 | filter files. | |
245 | ||
246 | ||
4aa45c31 | 247 | .section "Testing an installed filter file" "SEC03" |
9b371988 PH |
248 | Testing a filter file before installation cannot find every potential problem; |
249 | for example, it does not actually run commands to which messages are piped. | |
250 | Some &"live"& tests should therefore also be done once a filter is installed. | |
251 | ||
252 | If at all possible, test your filter file by sending messages from some other | |
253 | account. If you send a message to yourself from the filtered account, and | |
254 | delivery fails, the error message will be sent back to the same account, which | |
255 | may cause another delivery failure. It won't cause an infinite sequence of such | |
256 | messages, because delivery failure messages do not themselves generate further | |
257 | messages. However, it does mean that the failure won't be returned to you, and | |
258 | also that the postmaster will have to investigate the stuck message. | |
259 | ||
260 | If you have to test an Exim filter from the same account, a sensible precaution | |
261 | is to include the line | |
262 | .code | |
263 | if error_message then finish endif | |
264 | .endd | |
265 | as the first filter command, at least while testing. This causes filtering to | |
266 | be abandoned for a delivery failure message, and since no destinations are | |
267 | generated, the message goes on to be delivered to the original address. Unless | |
268 | there is a good reason for not doing so, it is recommended that the above test | |
269 | be left in all Exim filter files. (This does not apply to Sieve files.) | |
270 | ||
271 | ||
272 | ||
4aa45c31 | 273 | .section "Details of filtering commands" "SEC04" |
9b371988 PH |
274 | The filtering commands for Sieve and Exim filters are completely different in |
275 | syntax and semantics. The Sieve mechanism is defined in RFC 3028; in the next | |
276 | chapter we describe how it is integrated into Exim. The subsequent chapter | |
277 | covers Exim filtering commands in detail. | |
278 | ||
279 | ||
280 | ||
281 | .chapter "Sieve filter files" "CHAPsievefilter" | |
282 | The code for Sieve filtering in Exim was contributed by Michael Haardt, and | |
283 | most of the content of this chapter is taken from the notes he provided. Since | |
284 | Sieve is an extensible language, it is important to understand &"Sieve"& in | |
285 | this context as &"the specific implementation of Sieve for Exim"&. | |
286 | ||
287 | This chapter does not contain a description of Sieve, since that can be found | |
288 | in RFC 3028, which should be read in conjunction with these notes. | |
289 | ||
290 | The Exim Sieve implementation offers the core as defined by RFC 3028, | |
f89d2485 PH |
291 | comparison tests, the subaddress parameter, the &*copy*&, &*envelope*&, |
292 | &*fileinto*&, &*notify*&, and &*vacation*& extensions, but not the &*reject*& | |
293 | extension. Exim does not support message delivery notifications (MDNs), so | |
294 | adding it just to the Sieve filter (as required for &*reject*&) makes little | |
295 | sense. | |
9b371988 PH |
296 | |
297 | In order for Sieve to work properly in Exim, the system administrator needs to | |
298 | make some adjustments to the Exim configuration. These are described in the | |
299 | chapter on the &(redirect)& router in the full Exim specification. | |
300 | ||
301 | ||
4aa45c31 | 302 | .section "Recognition of Sieve filters" "SEC05" |
9b371988 PH |
303 | A filter file is interpreted as a Sieve filter if its first line is |
304 | .code | |
305 | # Sieve filter | |
306 | .endd | |
307 | This is what distinguishes it from a conventional &_.forward_& file or an Exim | |
308 | filter file. | |
309 | ||
310 | ||
311 | ||
4aa45c31 | 312 | .section "Saving to specified folders" "SEC06" |
9b371988 PH |
313 | If the system administrator has set things up as suggested in the Exim |
314 | specification, and you use &(keep)& or &(fileinto)& to save a mail into a | |
315 | folder, absolute files are stored where specified, relative files are stored | |
316 | relative to &$home$&, and &_inbox_& goes to the standard mailbox location. | |
317 | ||
318 | ||
319 | ||
4aa45c31 | 320 | .section "Strings containing header names" "SEC07" |
9b371988 PH |
321 | RFC 3028 does not specify what happens if a string denoting a header field does |
322 | not contain a valid header name, for example, it contains a colon. This | |
323 | implementation generates an error instead of ignoring the header field in order | |
324 | to ease script debugging, which fits in with the common picture of Sieve. | |
325 | ||
326 | ||
327 | ||
4aa45c31 | 328 | .section "Exists test with empty list of headers" "SEC08" |
9b371988 PH |
329 | The &*exists*& test succeeds only if all the specified headers exist. RFC 3028 |
330 | does not explicitly specify what happens on an empty list of headers. This | |
331 | implementation evaluates that condition as true, interpreting the RFC in a | |
332 | strict sense. | |
333 | ||
334 | ||
335 | ||
4aa45c31 | 336 | .section "Header test with invalid MIME encoding in header" "SEC09" |
9b371988 PH |
337 | Some MUAs process invalid base64 encoded data, generating junk. Others ignore |
338 | junk after seeing an equal sign in base64 encoded data. RFC 2047 does not | |
339 | specify how to react in this case, other than stating that a client must not | |
340 | forbid to process a message for that reason. RFC 2045 specifies that invalid | |
341 | data should be ignored (apparently looking at end of line characters). It also | |
342 | specifies that invalid data may lead to rejecting messages containing them (and | |
343 | there it appears to talk about true encoding violations), which is a clear | |
344 | contradiction to ignoring them. | |
345 | ||
346 | RFC 3028 does not specify how to process incorrect MIME words. This | |
347 | implementation treats them literally, as it does if the word is correct but its | |
348 | character set cannot be converted to UTF-8. | |
349 | ||
350 | ||
351 | ||
4aa45c31 | 352 | .section "Address test for multiple addresses per header" "SEC10" |
9b371988 PH |
353 | A header may contain multiple addresses. RFC 3028 does not explicitly specify |
354 | how to deal with them, but since the address test checks if anything matches | |
355 | anything else, matching one address suffices to satisfy the condition. That | |
356 | makes it impossible to test if a header contains a certain set of addresses and | |
357 | no more, but it is more logical than letting the test fail if the header | |
358 | contains an additional address besides the one the test checks for. | |
359 | ||
360 | ||
361 | ||
4aa45c31 | 362 | .section "Semantics of keep" "SEC11" |
9b371988 PH |
363 | The &(keep)& command is equivalent to |
364 | .code | |
365 | fileinto "inbox"; | |
366 | .endd | |
367 | It saves the message and resets the implicit keep flag. It does not set the | |
368 | implicit keep flag; there is no command to set it once it has been reset. | |
369 | ||
370 | ||
371 | ||
4aa45c31 | 372 | .section "Semantics of fileinto" "SEC12" |
9b371988 PH |
373 | RFC 3028 does not specify whether &(fileinto)& should try to create a mail |
374 | folder if it does not exist. This implementation allows the sysadmin to | |
375 | configure that aspect using the &(appendfile)& transport options | |
376 | &%create_directory%&, &%create_file%&, and &%file_must_exist%&. See the | |
377 | &(appendfile)& transport in the Exim specification for details. | |
378 | ||
379 | ||
380 | ||
4aa45c31 | 381 | .section "Semantics of redirect" "SEC13" |
9b371988 PH |
382 | Sieve scripts are supposed to be interoperable between servers, so this |
383 | implementation does not allow mail to be redirected to unqualified addresses, | |
384 | because the domain would depend on the system being used. On systems with | |
385 | virtual mail domains, the default domain is probably not what the user expects | |
386 | it to be. | |
387 | ||
388 | ||
389 | ||
4aa45c31 | 390 | .section "String arguments" "SEC14" |
9b371988 PH |
391 | There has been confusion if the string arguments to &(require)& are to be |
392 | matched case-sensitively or not. This implementation matches them with the | |
393 | match type &(:is)& (default, see section 2.7.1 of the RFC) and the comparator | |
394 | &(i;ascii-casemap)& (default, see section 2.7.3 of the RFC). The RFC defines | |
395 | the command defaults clearly, so any different implementations violate RFC | |
396 | 3028. The same is valid for comparator names, also specified as strings. | |
397 | ||
398 | ||
399 | ||
4aa45c31 | 400 | .section "Number units" "SEC15" |
9b371988 PH |
401 | There is a mistake in RFC 3028: the suffix G denotes gibi-, not tebibyte. |
402 | The mistake is obvious, because RFC 3028 specifies G to denote 2^30 | |
403 | (which is gibi, not tebi), and that is what this implementation uses as | |
404 | the scaling factor for the suffix G. | |
405 | ||
406 | ||
407 | ||
4aa45c31 | 408 | .section "RFC compliance" "SEC16" |
9b371988 PH |
409 | Exim requires the first line of a Sieve filter to be |
410 | .code | |
411 | # Sieve filter | |
412 | .endd | |
413 | Of course the RFC does not specify that line. Do not expect examples to work | |
414 | without adding it, though. | |
415 | ||
416 | RFC 3028 requires the use of CRLF to terminate a line. The rationale was that | |
417 | CRLF is universally used in network protocols to mark the end of the line. This | |
418 | implementation does not embed Sieve in a network protocol, but uses Sieve | |
419 | scripts as part of the Exim MTA. Since all parts of Exim use LF as the newline | |
420 | character, this implementation does, too, by default, though the system | |
421 | administrator may choose (at Exim compile time) to use CRLF instead. | |
422 | ||
423 | Exim violates RFC 2822, section 3.6.8, by accepting 8-bit header names, so this | |
424 | implementation repeats this violation to stay consistent with Exim. This is in | |
425 | preparation for UTF-8 data. | |
426 | ||
427 | Sieve scripts cannot contain NUL characters in strings, but mail headers could | |
428 | contain MIME encoded NUL characters, which could never be matched by Sieve | |
429 | scripts using exact comparisons. For that reason, this implementation extends | |
430 | the Sieve quoted string syntax with \0 to describe a NUL character, violating | |
431 | \0 being the same as 0 in RFC 3028. Even without using \0, the following tests | |
432 | are all true in this implementation. Implementations that use C-style strings | |
433 | will only evaluate the first test as true. | |
434 | .code | |
435 | Subject: =?iso-8859-1?q?abc=00def | |
436 | ||
437 | header :contains "Subject" ["abc"] | |
438 | header :contains "Subject" ["def"] | |
439 | header :matches "Subject" ["abc?def"] | |
440 | .endd | |
441 | Note that by considering Sieve to be an MUA, RFC 2047 can be interpreted in a | |
442 | way that NUL characters truncating strings is allowed for Sieve | |
443 | implementations, although not recommended. It is further allowed to use encoded | |
444 | NUL characters in headers, but that's not recommended either. The above example | |
445 | shows why. | |
446 | ||
447 | RFC 3028 states that if an implementation fails to convert a character set to | |
448 | UTF-8, two strings cannot be equal if one contains octets greater than 127. | |
449 | Assuming that all unknown character sets are one-byte character sets with the | |
450 | lower 128 octets being US-ASCII is not sound, so this implementation violates | |
451 | RFC 3028 and treats such MIME words literally. That way at least something | |
452 | could be matched. | |
453 | ||
454 | The folder specified by &(fileinto)& must not contain the character sequence | |
455 | &".."& to avoid security problems. RFC 3028 does not specify the syntax of | |
456 | folders apart from &(keep)& being equivalent to | |
457 | .code | |
458 | fileinto "INBOX"; | |
459 | .endd | |
460 | This implementation uses &_inbox_& instead. | |
461 | ||
462 | Sieve script errors currently cause messages to be silently filed into | |
463 | &_inbox_&. RFC 3028 requires that the user is notified of that condition. | |
464 | This may be implemented in the future by adding a header line to mails that | |
465 | are filed into &_inbox_& due to an error in the filter. | |
466 | ||
467 | ||
468 | ||
469 | .chapter "Exim filter files" "CHAPeximfilter" | |
470 | This chapter contains a full description of the contents of Exim filter files. | |
471 | ||
472 | ||
4aa45c31 | 473 | .section "Format of Exim filter files" "SEC17" |
9b371988 PH |
474 | Apart from leading white space, the first text in an Exim filter file must be |
475 | .code | |
476 | # Exim filter | |
477 | .endd | |
478 | This is what distinguishes it from a conventional &_.forward_& file or a Sieve | |
479 | filter file. If the file does not have this initial line (or the equivalent for | |
480 | a Sieve filter), it is treated as a conventional &_.forward_& file, both when | |
481 | delivering mail and when using the &%-bf%& testing mechanism. The white space | |
482 | in the line is optional, and any capitalization may be used. Further text on | |
483 | the same line is treated as a comment. For example, you could have | |
484 | .code | |
485 | # Exim filter <<== do not edit or remove this line! | |
486 | .endd | |
487 | The remainder of the file is a sequence of filtering commands, which consist of | |
488 | keywords and data values. For example, in the command | |
489 | .code | |
490 | deliver gulliver@lilliput.fict.example | |
491 | .endd | |
492 | the keyword is &`deliver`& and the data value is | |
493 | &`gulliver@lilliput.fict.example`&. White space or line breaks separate the | |
494 | components of a command, except in the case of conditions for the &(if)& | |
495 | command, where round brackets (parentheses) also act as separators. Complete | |
496 | commands are separated from each other by white space or line breaks; there are | |
497 | no special terminators. Thus, several commands may appear on one line, or one | |
498 | command may be spread over a number of lines. | |
499 | ||
500 | If the character # follows a separator anywhere in a command, everything from | |
501 | # up to the next newline is ignored. This provides a way of including comments | |
502 | in a filter file. | |
503 | ||
504 | ||
4aa45c31 | 505 | .section "Data values in filter commands" "SEC18" |
9b371988 PH |
506 | There are two ways in which a data value can be input: |
507 | ||
508 | .ilist | |
509 | If the text contains no white space, it can be typed verbatim. However, if it | |
510 | is part of a condition, it must also be free of round brackets (parentheses), | |
511 | as these are used for grouping in conditions. | |
512 | .next | |
513 | Otherwise, text must be enclosed in double quotation marks. In this case, the | |
514 | character \ (backslash) is treated as an &"escape character"& within the | |
515 | string, causing the following character or characters to be treated specially: | |
516 | .display | |
517 | &`\n`& is replaced by a newline | |
518 | &`\r`& is replaced by a carriage return | |
519 | &`\t`& is replaced by a tab | |
520 | .endd | |
521 | .endlist | |
522 | ||
523 | Backslash followed by up to three octal digits is replaced by the character | |
524 | specified by those digits, and &`\x`& followed by up to two hexadecimal digits | |
525 | is treated similarly. Backslash followed by any other character is replaced by | |
526 | the second character, so that in particular, &`\"`& becomes &`"`& and &`\\`& | |
527 | becomes &`\`&. A data item enclosed in double quotes can be continued onto the | |
528 | next line by ending the first line with a backslash. Any leading white space at | |
529 | the start of the continuation line is ignored. | |
530 | ||
531 | In addition to the escape character processing that occurs when strings are | |
532 | enclosed in quotes, most data values are also subject to &'string expansion'& | |
533 | (as described in the next section), in which case the characters &`$`& and | |
534 | &`\`& are also significant. This means that if a single backslash is actually | |
535 | required in such a string, and the string is also quoted, &`\\\\`& has to be | |
536 | entered. | |
537 | ||
538 | The maximum permitted length of a data string, before expansion, is 1024 | |
539 | characters. | |
540 | ||
541 | ||
542 | .section "String expansion" "SECTfilterstringexpansion" | |
543 | Most data values are expanded before use. Expansion consists of replacing | |
544 | substrings beginning with &`$`& with other text. The full expansion facilities | |
545 | available in Exim are extensive. If you want to know everything that Exim can | |
546 | do with strings, you should consult the chapter on string expansion in the Exim | |
547 | documentation. | |
548 | ||
549 | In filter files, by far the most common use of string expansion is the | |
550 | substitution of the contents of a variable. For example, the substring | |
551 | .code | |
552 | $reply_address | |
553 | .endd | |
554 | is replaced by the address to which replies to the message should be sent. If | |
555 | such a variable name is followed by a letter or digit or underscore, it must be | |
556 | enclosed in curly brackets (braces), for example, | |
557 | .code | |
558 | ${reply_address} | |
559 | .endd | |
560 | If a &`$`& character is actually required in an expanded string, it must be | |
561 | escaped with a backslash, and because backslash is also an escape character in | |
562 | quoted input strings, it must be doubled in that case. The following two | |
563 | examples illustrate two different ways of testing for a &`$`& character in a | |
564 | message: | |
565 | .code | |
566 | if $message_body contains \$ then ... | |
567 | if $message_body contains "\\$" then ... | |
568 | .endd | |
569 | You can prevent part of a string from being expanded by enclosing it between | |
570 | two occurrences of &`\N`&. For example, | |
571 | .code | |
572 | if $message_body contains \N$$$$\N then ... | |
573 | .endd | |
574 | tests for a run of four dollar characters. | |
575 | ||
576 | ||
4aa45c31 | 577 | .section "Some useful general variables" "SEC19" |
9b371988 PH |
578 | A complete list of the available variables is given in the Exim documentation. |
579 | This shortened list contains the ones that are most likely to be useful in | |
580 | personal filter files: | |
581 | ||
582 | &$body_linecount$&: The number of lines in the body of the message. | |
583 | ||
584 | &$body_zerocount$&: The number of binary zero characters in the body of the | |
585 | message. | |
586 | ||
587 | &$home$&: In conventional configurations, this variable normally contains the | |
588 | user's home directory. The system administrator can, however, change this. | |
589 | ||
590 | &$local_part$&: The part of the email address that precedes the @ sign &-- | |
591 | normally the user's login name. If support for multiple personal mailboxes is | |
592 | enabled (see section &<<SECTmbox>>& below) and a prefix or suffix for the local | |
593 | part was recognized, it is removed from the string in this variable. | |
594 | ||
595 | &$local_part_prefix$&: If support for multiple personal mailboxes is enabled | |
596 | (see section &<<SECTmbox>>& below), and a local part prefix was recognized, | |
597 | this variable contains the prefix. Otherwise it contains an empty string. | |
598 | ||
599 | &$local_part_suffix$&: If support for multiple personal mailboxes is enabled | |
600 | (see section &<<SECTmbox>>& below), and a local part suffix was recognized, | |
601 | this variable contains the suffix. Otherwise it contains an empty string. | |
602 | ||
603 | &$message_body$&: The initial portion of the body of the message. By default, | |
604 | up to 500 characters are read into this variable, but the system administrator | |
605 | can configure this to some other value. Newlines in the body are converted into | |
606 | single spaces. | |
607 | ||
608 | &$message_body_end$&: The final portion of the body of the message, formatted | |
609 | and limited in the same way as &$message_body$&. | |
610 | ||
611 | &$message_body_size$&: The size of the body of the message, in bytes. | |
612 | ||
613 | &$message_exim_id$&: The message's local identification string, which is unique | |
614 | for each message handled by a single host. | |
615 | ||
616 | &$message_headers$&: The header lines of the message, concatenated into a | |
617 | single string, with newline characters between them. | |
618 | ||
619 | &$message_size$&: The size of the entire message, in bytes. | |
620 | ||
621 | &$original_local_part$&: When an address that arrived with the message is | |
622 | being processed, this contains the same value as the variable &$local_part$&. | |
623 | However, if an address generated by an alias, forward, or filter file is being | |
624 | processed, this variable contains the local part of the original address. | |
625 | ||
626 | &$reply_address$&: The contents of the &'Reply-to:'& header, if the message | |
627 | has one; otherwise the contents of the &'From:'& header. It is the address to | |
628 | which normal replies to the message should be sent. | |
629 | ||
630 | &$return_path$&: The return path &-- that is, the sender field that will be | |
631 | transmitted as part of the message's envelope if the message is sent to another | |
632 | host. This is the address to which delivery errors are sent. In many cases, | |
633 | this variable has the same value as &$sender_address$&, but if, for example, | |
634 | an incoming message to a mailing list has been expanded, &$return_path$& may | |
635 | have been changed to contain the address of the list maintainer. | |
636 | ||
637 | &$sender_address$&: The sender address that was received in the envelope of | |
638 | the message. This is not necessarily the same as the contents of the &'From:'& | |
639 | or &'Sender:'& header lines. For delivery error messages (&"bounce messages"&) | |
640 | there is no sender address, and this variable is empty. | |
641 | ||
642 | &$tod_full$&: A full version of the time and date, for example: Wed, 18 Oct | |
643 | 1995 09:51:40 +0100. The timezone is always given as a numerical offset from | |
644 | GMT. | |
645 | ||
646 | &$tod_log$&: The time and date in the format used for writing Exim's log files, | |
647 | without the timezone, for example: 1995-10-12 15:32:29. | |
648 | ||
649 | &$tod_zone$&: The local timezone offset, for example: +0100. | |
650 | ||
651 | ||
652 | ||
653 | .section "Header variables" "SECTheadervariables" | |
654 | There is a special set of expansion variables containing the header lines of | |
655 | the message being processed. These variables have names beginning with | |
656 | &$header_$& followed by the name of the header line, terminated by a colon. | |
657 | For example, | |
658 | .code | |
659 | $header_from: | |
660 | $header_subject: | |
661 | .endd | |
662 | The whole item, including the terminating colon, is replaced by the contents of | |
663 | the message header line. If there is more than one header line with the same | |
664 | name, their contents are concatenated. For header lines whose data consists of | |
665 | a list of addresses (for example, &'From:'& and &'To:'&), a comma and newline | |
666 | is inserted between each set of data. For all other header lines, just a | |
667 | newline is used. | |
668 | ||
669 | Leading and trailing white space is removed from header line data, and if there | |
670 | are any MIME &"words"& that are encoded as defined by RFC 2047 (because they | |
671 | contain non-ASCII characters), they are decoded and translated, if possible, to | |
672 | a local character set. Translation is attempted only on operating systems that | |
673 | have the &[iconv()]& function. This makes the header line look the same as it | |
674 | would when displayed by an MUA. The default character set is ISO-8859-1, but | |
675 | this can be changed by means of the &(headers)& command (see below). | |
676 | ||
677 | If you want to see the actual characters that make up a header line, you can | |
678 | specify &$rheader_$& instead of &$header_$&. This inserts the &"raw"& | |
679 | header line, unmodified. | |
680 | ||
681 | There is also an intermediate form, requested by &$bheader_$&, which removes | |
682 | leading and trailing space and decodes MIME &"words"&, but does not do any | |
683 | character translation. If an attempt to decode what looks superficially like a | |
684 | MIME &"word"& fails, the raw string is returned. If decoding produces a binary | |
685 | zero character, it is replaced by a question mark. | |
686 | ||
687 | The capitalization of the name following &$header_$& is not significant. | |
688 | Because any printing character except colon may appear in the name of a | |
689 | message's header (this is a requirement of RFC 2822, the document that | |
690 | describes the format of a mail message) curly brackets must &'not'& be used in | |
691 | this case, as they will be taken as part of the header name. Two shortcuts are | |
692 | allowed in naming header variables: | |
693 | ||
694 | .ilist | |
695 | The initiating &$header_$&, &$rheader_$&, or &$bheader_$& can be | |
696 | abbreviated to &$h_$&, &$rh_$&, or &$bh_$&, respectively. | |
697 | .next | |
698 | The terminating colon can be omitted if the next character is white space. The | |
699 | white space character is retained in the expanded string. However, this is not | |
700 | recommended, because it makes it easy to forget the colon when it really is | |
701 | needed. | |
702 | .endlist | |
703 | ||
704 | If the message does not contain a header of the given name, an empty string is | |
705 | substituted. Thus it is important to spell the names of headers correctly. Do | |
706 | not use &$header_Reply_to$& when you really mean &$header_Reply-to$&. | |
707 | ||
708 | ||
4aa45c31 | 709 | .section "User variables" "SEC20" |
9b371988 PH |
710 | There are ten user variables with names &$n0$& &-- &$n9$& that can be |
711 | incremented by the &(add)& command (see section &<<SECTadd>>&). These can be | |
712 | used for &"scoring"& messages in various ways. If Exim is configured to run a | |
713 | &"system filter"& on every message, the values left in these variables are | |
714 | copied into the variables &$sn0$& &-- &$sn9$& at the end of the system filter, | |
715 | thus making them available to users' filter files. How these values are used is | |
716 | entirely up to the individual installation. | |
717 | ||
718 | ||
4aa45c31 | 719 | .section "Current directory" "SEC21" |
9b371988 PH |
720 | The contents of your filter file should not make any assumptions about the |
721 | current directory. It is best to use absolute paths for file names; you can | |
722 | normally make use of the &$home$& variable to refer to your home directory. The | |
723 | &(save)& command automatically inserts &$home$& at the start of non-absolute | |
724 | paths. | |
725 | ||
726 | ||
727 | ||
728 | ||
729 | .section "Significant deliveries" "SECTsigdel" | |
730 | When in the course of delivery a message is processed by a filter file, what | |
731 | happens next, that is, after the filter file has been processed, depends on | |
732 | whether or not the filter sets up any &'significant deliveries'&. If at least | |
733 | one significant delivery is set up, the filter is considered to have handled | |
734 | the entire delivery arrangements for the current address, and no further | |
735 | processing of the address takes place. If, however, no significant deliveries | |
736 | are set up, Exim continues processing the current address as if there were no | |
737 | filter file, and typically sets up a delivery of a copy of the message into a | |
738 | local mailbox. In particular, this happens in the special case of a filter file | |
739 | containing only comments. | |
740 | ||
741 | The delivery commands &(deliver)&, &(save)&, and &(pipe)& are by default | |
742 | significant. However, if such a command is preceded by the word &"unseen"&, its | |
743 | delivery is not considered to be significant. In contrast, other commands such | |
744 | as &(mail)& and &(vacation)& do not set up significant deliveries unless | |
745 | preceded by the word &"seen"&. The following example commands set up | |
746 | significant deliveries: | |
747 | .code | |
748 | deliver jack@beanstalk.example | |
749 | pipe $home/bin/mymailscript | |
750 | seen mail subject "message discarded" | |
751 | seen finish | |
752 | .endd | |
753 | The following example commands do not set up significant deliveries: | |
754 | .code | |
755 | unseen deliver jack@beanstalk.example | |
756 | unseen pipe $home/bin/mymailscript | |
757 | mail subject "message discarded" | |
758 | finish | |
759 | .endd | |
760 | ||
761 | ||
762 | ||
4aa45c31 | 763 | .section "Filter commands" "SEC222" |
9b371988 PH |
764 | The filter commands that are described in subsequent sections are listed |
765 | below, with the section in which they are described in brackets: | |
766 | ||
767 | .table2 | |
768 | .row &(add)& "&~&~increment a user variable (section &<<SECTadd>>&)" | |
769 | .row &(deliver)& "&~&~deliver to an email address (section &<<SECTdeliver>>&)" | |
770 | .row &(fail)& "&~&~force delivery failure (sysadmin use) (section &<<SECTfail>>&)" | |
771 | .row &(finish)& "&~&~end processing (section &<<SECTfinish>>&)" | |
772 | .row &(freeze)& "&~&~freeze message (sysadmin use) (section &<<SECTfreeze>>&)" | |
773 | .row &(headers)& "&~&~set the header character set (section &<<SECTheaders>>&)" | |
774 | .row &(if)& "&~&~test condition(s) (section &<<SECTif>>&)" | |
775 | .row &(logfile)& "&~&~define log file (section &<<SECTlog>>&)" | |
776 | .row &(logwrite)& "&~&~write to log file (section &<<SECTlog>>&)" | |
777 | .row &(mail)& "&~&~send a reply message (section &<<SECTmail>>&)" | |
778 | .row &(pipe)& "&~&~pipe to a command (section &<<SECTpipe>>&)" | |
779 | .row &(save)& "&~&~save to a file (section &<<SECTsave>>&)" | |
780 | .row &(testprint)& "&~&~print while testing (section &<<SECTtestprint>>&)" | |
781 | .row &(vacation)& "&~&~tailored form of &(mail)& (section &<<SECTmail>>&)" | |
782 | .endtable | |
783 | ||
784 | The &(headers)& command has additional parameters that can be used only in a | |
785 | system filter. The &(fail)& and &(freeze)& commands are available only when | |
786 | Exim's filtering facilities are being used as a system filter, and are | |
787 | therefore usable only by the system administrator and not by ordinary users. | |
788 | They are mentioned only briefly in this document; for more information, see the | |
789 | main Exim specification. | |
790 | ||
791 | ||
792 | ||
793 | .section "The add command" "SECTadd" | |
794 | .display | |
795 | &` add `&<&'number'&>&` to `&<&'user variable'&> | |
796 | &`e.g. add 2 to n3`& | |
797 | .endd | |
798 | ||
799 | There are 10 user variables of this type, with names &$n0$& &-- &$n9$&. Their | |
800 | values can be obtained by the normal expansion syntax (for example &$n3$&) in | |
801 | other commands. At the start of filtering, these variables all contain zero. | |
802 | Both arguments of the &(add)& command are expanded before use, making it | |
803 | possible to add variables to each other. Subtraction can be obtained by adding | |
804 | negative numbers. | |
805 | ||
806 | ||
807 | ||
808 | .section "The deliver command" "SECTdeliver" | |
809 | .display | |
810 | &` deliver`& <&'mail address'&> | |
811 | &`e.g. deliver "Dr Livingstone <David@somewhere.africa.example>"`& | |
812 | .endd | |
813 | ||
814 | This command provides a forwarding operation. The delivery that it sets up is | |
815 | significant unless the command is preceded by &"unseen"& (see section | |
816 | &<<SECTsigdel>>&). The message is sent on to the given address, exactly as | |
817 | happens if the address had appeared in a traditional &_.forward_& file. If you | |
818 | want to deliver the message to a number of different addresses, you can use | |
819 | more than one &(deliver)& command (each one may have only one address). | |
820 | However, duplicate addresses are discarded. | |
821 | ||
822 | To deliver a copy of the message to your normal mailbox, your login name can be | |
823 | given as the address. Once an address has been processed by the filtering | |
824 | mechanism, an identical generated address will not be so processed again, so | |
825 | doing this does not cause a loop. | |
826 | ||
827 | However, if you have a mail alias, you should &'not'& refer to it here. For | |
828 | example, if the mail address &'L.Gulliver'& is aliased to &'lg303'& then all | |
829 | references in Gulliver's &_.forward_& file should be to &'lg303'&. A reference | |
830 | to the alias will not work for messages that are addressed to that alias, | |
831 | since, like &_.forward_& file processing, aliasing is performed only once on an | |
832 | address, in order to avoid looping. | |
833 | ||
834 | Following the new address, an optional second address, preceded by | |
835 | &"errors_to"& may appear. This changes the address to which delivery errors on | |
836 | the forwarded message will be sent. Instead of going to the message's original | |
837 | sender, they go to this new address. For ordinary users, the only value that is | |
838 | permitted for this address is the user whose filter file is being processed. | |
839 | For example, the user &'lg303'& whose mailbox is in the domain | |
840 | &'lilliput.example'& could have a filter file that contains | |
841 | .code | |
842 | deliver jon@elsewhere.example errors_to lg303@lilliput.example | |
843 | .endd | |
844 | Clearly, using this feature makes sense only in situations where not all | |
845 | messages are being forwarded. In particular, bounce messages must not be | |
846 | forwarded in this way, as this is likely to create a mail loop if something | |
847 | goes wrong. | |
848 | ||
849 | ||
850 | ||
851 | .section "The save command" "SECTsave" | |
852 | .display | |
853 | &` save `&<&'file name'&> | |
854 | &`e.g. save $home/mail/bookfolder`& | |
855 | .endd | |
856 | ||
857 | This command specifies that a copy of the message is to be appended to the | |
858 | given file (that is, the file is to be used as a mail folder). The delivery | |
859 | that &(save)& sets up is significant unless the command is preceded by | |
860 | &"unseen"& (see section &<<SECTsigdel>>&). | |
861 | ||
862 | More than one &(save)& command may be obeyed; each one causes a copy of the | |
863 | message to be written to its argument file, provided they are different | |
864 | (duplicate &(save)& commands are ignored). | |
865 | ||
866 | If the file name does not start with a / character, the contents of the | |
f89d2485 PH |
867 | &$home$& variable are prepended, unless it is empty, or the system |
868 | administrator has disabled this feature. In conventional configurations, this | |
553c0e3a PH |
869 | variable is normally set in a user filter to the user's home directory, but the |
870 | system administrator may set it to some other path. In some configurations, | |
f89d2485 | 871 | &$home$& may be unset, or prepending may be disabled, in which case a |
553c0e3a PH |
872 | non-absolute path name may be generated. Such configurations convert this to an |
873 | absolute path when the delivery takes place. In a system filter, &$home$& is | |
874 | never set. | |
9b371988 PH |
875 | |
876 | The user must of course have permission to write to the file, and the writing | |
877 | of the file takes place in a process that is running as the user, under the | |
878 | user's primary group. Any secondary groups to which the user may belong are not | |
879 | normally taken into account, though the system administrator can configure Exim | |
880 | to set them up. In addition, the ability to use this command at all is | |
881 | controlled by the system administrator &-- it may be forbidden on some systems. | |
882 | ||
883 | An optional mode value may be given after the file name. The value for the mode | |
884 | is interpreted as an octal number, even if it does not begin with a zero. For | |
885 | example: | |
886 | .code | |
887 | save /some/folder 640 | |
888 | .endd | |
889 | This makes it possible for users to override the system-wide mode setting for | |
890 | file deliveries, which is normally 600. If an existing file does not have the | |
891 | correct mode, it is changed. | |
892 | ||
893 | An alternative form of delivery may be enabled on your system, in which each | |
894 | message is delivered into a new file in a given directory. If this is the case, | |
895 | this functionality can be requested by giving the directory name terminated by | |
896 | a slash after the &(save)& command, for example | |
897 | .code | |
898 | save separated/messages/ | |
899 | .endd | |
900 | There are several different formats for such deliveries; check with your system | |
901 | administrator or local documentation to find out which (if any) are available | |
902 | on your system. If this functionality is not enabled, the use of a path name | |
903 | ending in a slash causes an error. | |
904 | ||
905 | ||
906 | ||
907 | .section "The pipe command" "SECTpipe" | |
908 | .display | |
909 | &` pipe `&<&'command'&> | |
910 | &`e.g. pipe "$home/bin/countmail $sender_address"`& | |
911 | .endd | |
912 | ||
913 | This command specifies that the message is to be delivered to the specified | |
914 | command using a pipe. The delivery that it sets up is significant unless the | |
915 | command is preceded by &"unseen"& (see section &<<SECTsigdel>>&). Remember, | |
916 | however, that no deliveries are done while the filter is being processed. All | |
917 | deliveries happen later on. Therefore, the result of running the pipe is not | |
918 | available to the filter. | |
919 | ||
920 | When the deliveries are done, a separate process is run, and a copy of the | |
921 | message is passed on its standard input. The process runs as the user, under | |
922 | the user's primary group. Any secondary groups to which the user may belong are | |
923 | not normally taken into account, though the system administrator can configure | |
924 | Exim to set them up. More than one &(pipe)& command may appear; each one causes | |
925 | a copy of the message to be written to its argument pipe, provided they are | |
926 | different (duplicate &(pipe)& commands are ignored). | |
927 | ||
928 | When the time comes to transport the message, the command supplied to &(pipe)& | |
929 | is split up by Exim into a command name and a number of arguments. These are | |
930 | delimited by white space except for arguments enclosed in double quotes, in | |
931 | which case backslash is interpreted as an escape, or in single quotes, in which | |
932 | case no escaping is recognized. Note that as the whole command is normally | |
933 | supplied in double quotes, a second level of quoting is required for internal | |
934 | double quotes. For example: | |
935 | .code | |
936 | pipe "$home/myscript \"size is $message_size\"" | |
937 | .endd | |
938 | String expansion is performed on the separate components after the line has | |
939 | been split up, and the command is then run directly by Exim; it is not run | |
940 | under a shell. Therefore, substitution cannot change the number of arguments, | |
941 | nor can quotes, backslashes or other shell metacharacters in variables cause | |
942 | confusion. | |
943 | ||
944 | Documentation for some programs that are normally run via this kind of pipe | |
945 | often suggest that the command should start with | |
946 | .code | |
947 | IFS=" " | |
948 | .endd | |
949 | This is a shell command, and should &'not'& be present in Exim filter files, | |
950 | since it does not normally run the command under a shell. | |
951 | ||
952 | However, there is an option that the administrator can set to cause a shell to | |
953 | be used. In this case, the entire command is expanded as a single string and | |
954 | passed to the shell for interpretation. It is recommended that this be avoided | |
955 | if at all possible, since it can lead to problems when inserted variables | |
956 | contain shell metacharacters. | |
957 | ||
958 | The default PATH set up for the command is determined by the system | |
959 | administrator, usually containing at least &_/bin_& and &_/usr/bin_& so that | |
960 | common commands are available without having to specify an absolute file name. | |
961 | However, it is possible for the system administrator to restrict the pipe | |
962 | facility so that the command name must not contain any / characters, and must | |
963 | be found in one of the directories in the configured PATH. It is also possible | |
964 | for the system administrator to lock out the use of the &(pipe)& command | |
965 | altogether. | |
966 | ||
967 | When the command is run, a number of environment variables are set up. The | |
968 | complete list for pipe deliveries may be found in the Exim reference manual. | |
969 | Those that may be useful for pipe deliveries from user filter files are: | |
970 | ||
971 | .display | |
972 | &`DOMAIN `& the domain of the address | |
973 | &`HOME `& your home directory | |
974 | &`LOCAL_PART `& see below | |
975 | &`LOCAL_PART_PREFIX `& see below | |
976 | &`LOCAL_PART_SUFFIX `& see below | |
977 | &`LOGNAME `& your login name | |
978 | &`MESSAGE_ID `& the unique id of the message | |
979 | &`PATH `& the command search path | |
980 | &`RECIPIENT `& the complete recipient address | |
981 | &`SENDER `& the sender of the message | |
982 | &`SHELL `& &`/bin/sh`& | |
983 | &`USER `& see below | |
984 | .endd | |
985 | ||
986 | LOCAL_PART, LOGNAME, and USER are all set to the same value, namely, your login | |
987 | id. LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX may be set if Exim is configured to | |
988 | recognize prefixes or suffixes in the local parts of addresses. For example, a | |
989 | message addressed to &'pat-suf2@domain.example'& may cause the filter for user | |
990 | &'pat'& to be run. If this sets up a pipe delivery, LOCAL_PART_SUFFIX is | |
991 | &`-suf2`& when the pipe command runs. The system administrator has to configure | |
992 | Exim specially for this feature to be available. | |
993 | ||
994 | If you run a command that is a shell script, be very careful in your use of | |
995 | data from the incoming message in the commands in your script. RFC 2822 is very | |
996 | generous in the characters that are permitted to appear in mail addresses, and | |
997 | in particular, an address may begin with a vertical bar or a slash. For this | |
998 | reason you should always use quotes round any arguments that involve data from | |
999 | the message, like this: | |
1000 | .code | |
1001 | /some/command '$SENDER' | |
1002 | .endd | |
1003 | so that inserted shell meta-characters do not cause unwanted effects. | |
1004 | ||
1005 | Remember that, as was explained earlier, the pipe command is not run at the | |
1006 | time the filter file is interpreted. The filter just defines what deliveries | |
1007 | are required for one particular addressee of a message. The deliveries | |
1008 | themselves happen later, once Exim has decided everything that needs to be done | |
1009 | for the message. | |
1010 | ||
1011 | A consequence of this is that you cannot inspect the return code from the pipe | |
1012 | command from within the filter. Nevertheless, the code returned by the command | |
1013 | is important, because Exim uses it to decide whether the delivery has succeeded | |
1014 | or failed. | |
1015 | ||
1016 | The command should return a zero completion code if all has gone well. Most | |
1017 | non-zero codes are treated by Exim as indicating a failure of the pipe. This is | |
1018 | treated as a delivery failure, causing the message to be returned to its | |
1019 | sender. However, there are some completion codes that are treated as temporary | |
1020 | errors. The message remains on Exim's spool disk, and the delivery is tried | |
1021 | again later, though it will ultimately time out if the delivery failures go on | |
1022 | too long. The completion codes to which this applies can be specified by the | |
1023 | system administrator; the default values are 73 and 75. | |
1024 | ||
1025 | The pipe command should not normally write anything to its standard output or | |
1026 | standard error file descriptors. If it does, whatever is written is normally | |
1027 | returned to the sender of the message as a delivery error, though this action | |
1028 | can be varied by the system administrator. | |
1029 | ||
1030 | ||
1031 | ||
1032 | .section "Mail commands" "SECTmail" | |
1033 | There are two commands that cause the creation of a new mail message, neither | |
1034 | of which count as a significant delivery unless the command is preceded by the | |
1035 | word &"seen"& (see section &<<SECTsigdel>>&). This is a powerful facility, but | |
1036 | it should be used with care, because of the danger of creating infinite | |
1037 | sequences of messages. The system administrator can forbid the use of these | |
1038 | commands altogether. | |
1039 | ||
1040 | To help prevent runaway message sequences, these commands have no effect when | |
1041 | the incoming message is a bounce (delivery error) message, and messages sent by | |
1042 | this means are treated as if they were reporting delivery errors. Thus, they | |
1043 | should never themselves cause a bounce message to be returned. The basic | |
1044 | mail-sending command is | |
1045 | .display | |
1046 | &`mail [to `&<&'address-list'&>&`]`& | |
1047 | &` [cc `&<&'address-list'&>&`]`& | |
1048 | &` [bcc `&<&'address-list'&>&`]`& | |
1049 | &` [from `&<&'address'&>&`]`& | |
1050 | &` [reply_to `&<&'address'&>&`]`& | |
1051 | &` [subject `&<&'text'&>&`]`& | |
1052 | &` [extra_headers `&<&'text'&>&`]`& | |
1053 | &` [text `&<&'text'&>&`]`& | |
1054 | &` [[expand] file `&<&'filename'&>&`]`& | |
1055 | &` [return message]`& | |
1056 | &` [log `&<&'log file name'&>&`]`& | |
1057 | &` [once `&<&'note file name'&>&`]`& | |
1058 | &` [once_repeat `&<&'time interval'&>&`]`& | |
9b371988 PH |
1059 | &`e.g. mail text "Your message about $h_subject: has been received"`& |
1060 | .endd | |
1061 | Each <&'address-list'&> can contain a number of addresses, separated by commas, | |
1062 | in the format of a &'To:'& or &'Cc:'& header line. In fact, the text you supply | |
1063 | here is copied exactly into the appropriate header line. It may contain | |
1064 | additional information as well as email addresses. For example: | |
1065 | .code | |
1066 | mail to "Julius Caesar <jc@rome.example>, \ | |
1067 | <ma@rome.example> (Mark A.)" | |
1068 | .endd | |
1069 | Similarly, the texts supplied for &%from%& and &%reply_to%& are copied into | |
1070 | their respective header lines. | |
1071 | ||
1072 | As a convenience for use in one common case, there is also a command called | |
1073 | &(vacation)&. It behaves in the same way as &(mail)&, except that the defaults | |
1074 | for the &%subject%&, &%file%&, &%log%&, &%once%&, and &%once_repeat%& options | |
1075 | are | |
1076 | .code | |
1077 | subject "On vacation" | |
1078 | expand file .vacation.msg | |
1079 | log .vacation.log | |
1080 | once .vacation | |
1081 | once_repeat 7d | |
1082 | .endd | |
1083 | respectively. These are the same file names and repeat period used by the | |
1084 | traditional Unix &(vacation)& command. The defaults can be overridden by | |
1085 | explicit settings, but if a file name is given its contents are expanded only | |
1086 | if explicitly requested. | |
1087 | ||
1088 | &*Warning*&: The &(vacation)& command should always be used conditionally, | |
1089 | subject to at least the &(personal)& condition (see section &<<SECTpersonal>>& | |
1090 | below) so as not to send automatic replies to non-personal messages from | |
1091 | mailing lists or elsewhere. Sending an automatic response to a mailing list or | |
1092 | a mailing list manager is an Internet Sin. | |
1093 | ||
1094 | For both commands, the key/value argument pairs can appear in any order. At | |
1095 | least one of &%text%& or &%file%& must appear (except with &(vacation)&, where | |
1096 | there is a default for &%file%&); if both are present, the text string appears | |
1097 | first in the message. If &%expand%& precedes &%file%&, each line of the file is | |
1098 | subject to string expansion before it is included in the message. | |
1099 | ||
1100 | Several lines of text can be supplied to &%text%& by including the escape | |
1101 | sequence &"\n"& in the string wherever a newline is required. If the command is | |
1102 | output during filter file testing, newlines in the text are shown as &"\n"&. | |
1103 | ||
1104 | Note that the keyword for creating a &'Reply-To:'& header is &%reply_to%&, | |
1105 | because Exim keywords may contain underscores, but not hyphens. If the &%from%& | |
1106 | keyword is present and the given address does not match the user who owns the | |
1107 | forward file, Exim normally adds a &'Sender:'& header to the message, though it | |
1108 | can be configured not to do this. | |
1109 | ||
1110 | The &%extra_headers%& keyword allows you to add custom header lines to the | |
1111 | message. The text supplied must be one or more syntactically valid RFC 2822 | |
1112 | header lines. You can use &"\n"& within quoted text to specify newlines between | |
1113 | headers, and also to define continued header lines. For example: | |
1114 | .code | |
1115 | extra_headers "h1: first\nh2: second\n continued\nh3: third" | |
1116 | .endd | |
1117 | No newline should appear at the end of the final header line. | |
1118 | ||
1119 | If no &%to%& argument appears, the message is sent to the address in the | |
1120 | &$reply_address$& variable (see section &<<SECTfilterstringexpansion>>& above). | |
1121 | An &'In-Reply-To:'& header is automatically included in the created message, | |
1122 | giving a reference to the message identification of the incoming message. | |
1123 | ||
1124 | If &%return message%& is specified, the incoming message that caused the filter | |
1125 | file to be run is added to the end of the message, subject to a maximum size | |
1126 | limitation. | |
1127 | ||
1128 | If a log file is specified, a line is added to it for each message sent. | |
1129 | ||
1130 | If a &%once%& file is specified, it is used to hold a database for remembering | |
1131 | who has received a message, and no more than one message is ever sent to any | |
1132 | particular address, unless &%once_repeat%& is set. This specifies a time | |
1133 | interval after which another copy of the message is sent. The interval is | |
1134 | specified as a sequence of numbers, each followed by the initial letter of one | |
1135 | of &"seconds"&, &"minutes"&, &"hours"&, &"days"&, or &"weeks"&. For example, | |
1136 | .code | |
1137 | once_repeat 5d4h | |
1138 | .endd | |
1139 | causes a new message to be sent if at least 5 days and 4 hours have elapsed | |
1140 | since the last one was sent. There must be no white space in a time interval. | |
1141 | ||
1142 | Commonly, the file name specified for &%once%& is used as the base name for | |
1143 | direct-access (DBM) file operations. There are a number of different DBM | |
1144 | libraries in existence. Some operating systems provide one as a default, but | |
1145 | even in this case a different one may have been used when building Exim. With | |
1146 | some DBM libraries, specifying &%once%& results in two files being created, | |
1147 | with the suffixes &_.dir_& and &_.pag_& being added to the given name. With | |
1148 | some others a single file with the suffix &_.db_& is used, or the name is used | |
1149 | unchanged. | |
1150 | ||
1151 | Using a DBM file for implementing the &%once%& feature means that the file | |
1152 | grows as large as necessary. This is not usually a problem, but some system | |
1153 | administrators want to put a limit on it. The facility can be configured not to | |
1154 | use a DBM file, but instead, to use a regular file with a maximum size. The | |
1155 | data in such a file is searched sequentially, and if the file fills up, the | |
1156 | oldest entry is deleted to make way for a new one. This means that some | |
1157 | correspondents may receive a second copy of the message after an unpredictable | |
1158 | interval. Consult your local information to see if your system is configured | |
1159 | this way. | |
1160 | ||
1161 | More than one &(mail)& or &(vacation)& command may be obeyed in a single filter | |
1162 | run; they are all honoured, even when they are to the same recipient. | |
1163 | ||
1164 | ||
1165 | ||
1166 | .section "Logging commands" "SECTlog" | |
1167 | A log can be kept of actions taken by a filter file. This facility is normally | |
1168 | available in conventional configurations, but there are some situations where | |
1169 | it might not be. Also, the system administrator may choose to disable it. Check | |
1170 | your local information if in doubt. | |
1171 | ||
1172 | Logging takes place while the filter file is being interpreted. It does not | |
1173 | queue up for later like the delivery commands. The reason for this is so that a | |
1174 | log file need be opened only once for several write operations. There are two | |
1175 | commands, neither of which constitutes a significant delivery. The first | |
1176 | defines a file to which logging output is subsequently written: | |
1177 | .display | |
1178 | &` logfile `&<&'file name'&> | |
1179 | &`e.g. logfile $home/filter.log`& | |
1180 | .endd | |
1181 | The file name must be fully qualified. You can use &$home$&, as in this | |
1182 | example, to refer to your home directory. The file name may optionally be | |
1183 | followed by a mode for the file, which is used if the file has to be created. | |
1184 | For example, | |
1185 | .code | |
1186 | logfile $home/filter.log 0644 | |
1187 | .endd | |
1188 | The number is interpreted as octal, even if it does not begin with a zero. | |
1189 | The default for the mode is 600. It is suggested that the &(logfile)& command | |
1190 | normally appear as the first command in a filter file. Once a log file has | |
1191 | been obeyed, the &(logwrite)& command can be used to write to it: | |
1192 | .display | |
1193 | &` logwrite "`&<&'some text string'&>&`"`& | |
1194 | &`e.g. logwrite "$tod_log $message_id processed"`& | |
1195 | .endd | |
1196 | It is possible to have more than one &(logfile)& command, to specify writing to | |
1197 | different log files in different circumstances. Writing takes place at the end | |
1198 | of the file, and a newline character is added to the end of each string if | |
1199 | there isn't one already there. Newlines can be put in the middle of the string | |
1200 | by using the &"\n"& escape sequence. Lines from simultaneous deliveries may get | |
1201 | interleaved in the file, as there is no interlocking, so you should plan your | |
1202 | logging with this in mind. However, data should not get lost. | |
1203 | ||
1204 | ||
1205 | ||
1206 | .section "The finish command" "SECTfinish" | |
1207 | The command &(finish)&, which has no arguments, causes Exim to stop | |
1208 | interpreting the filter file. This is not a significant action unless preceded | |
1209 | by &"seen"&. A filter file containing only &"seen finish"& is a black hole. | |
1210 | ||
1211 | ||
1212 | .section "The testprint command" "SECTtestprint" | |
1213 | It is sometimes helpful to be able to print out the values of variables when | |
1214 | testing filter files. The command | |
1215 | .display | |
1216 | &` testprint `&<&'text'&> | |
1217 | &`e.g. testprint "home=$home reply_address=$reply_address"`& | |
1218 | .endd | |
1219 | does nothing when mail is being delivered. However, when the filtering code is | |
1220 | being tested by means of the &%-bf%& option (see section &<<SECTtesting>>& | |
1221 | above), the value of the string is written to the standard output. | |
1222 | ||
1223 | ||
1224 | .section "The fail command" "SECTfail" | |
1225 | When Exim's filtering facilities are being used as a system filter, the | |
1226 | &(fail)& command is available, to force delivery failure. Because this command | |
1227 | is normally usable only by the system administrator, and not enabled for use by | |
1228 | ordinary users, it is described in more detail in the main Exim specification | |
1229 | rather than in this document. | |
1230 | ||
1231 | ||
1232 | .section "The freeze command" "SECTfreeze" | |
1233 | When Exim's filtering facilities are being used as a system filter, the | |
1234 | &(freeze)& command is available, to freeze a message on the queue. Because this | |
1235 | command is normally usable only by the system administrator, and not enabled | |
1236 | for use by ordinary users, it is described in more detail in the main Exim | |
1237 | specification rather than in this document. | |
1238 | ||
1239 | ||
1240 | ||
1241 | .section "The headers command" "SECTheaders" | |
1242 | The &(headers)& command can be used to change the target character set that is | |
1243 | used when translating the contents of encoded header lines for insertion by the | |
1244 | &$header_$& mechanism (see section &<<SECTheadervariables>>& above). The | |
1245 | default can be set in the Exim configuration; if not specified, ISO-8859-1 is | |
1246 | used. The only currently supported format for the &(headers)& command in user | |
1247 | filters is as in this example: | |
1248 | .code | |
1249 | headers charset "UTF-8" | |
1250 | .endd | |
1251 | That is, &(headers)& is followed by the word &"charset"& and then the name of a | |
1252 | character set. This particular example would be useful if you wanted to compare | |
1253 | the contents of a header to a UTF-8 string. | |
1254 | ||
1255 | In system filter files, the &(headers)& command can be used to add or remove | |
1256 | header lines from the message. These features are described in the main Exim | |
1257 | specification. | |
1258 | ||
1259 | ||
1260 | ||
1261 | .section "Obeying commands conditionally" "SECTif" | |
1262 | Most of the power of filtering comes from the ability to test conditions and | |
1263 | obey different commands depending on the outcome. The &(if)& command is used to | |
1264 | specify conditional execution, and its general form is | |
1265 | .display | |
1266 | &`if `&<&'condition'&> | |
1267 | &`then `&<&'commands'&> | |
1268 | &`elif `&<&'condition'&> | |
1269 | &`then `&<&'commands'&> | |
1270 | &`else `&<&'commands'&> | |
1271 | &`endif`& | |
1272 | .endd | |
1273 | There may be any number of &(elif)& and &(then)& sections (including none) and | |
1274 | the &(else)& section is also optional. Any number of commands, including nested | |
1275 | &(if)& commands, may appear in any of the <&'commands'&> sections. | |
1276 | ||
1277 | Conditions can be combined by using the words &(and)& and &(or)&, and round | |
1278 | brackets (parentheses) can be used to specify how several conditions are to | |
1279 | combine. Without brackets, &(and)& is more binding than &(or)&. For example: | |
1280 | .code | |
1281 | if | |
1282 | $h_subject: contains "Make money" or | |
1283 | $h_precedence: is "junk" or | |
1284 | ($h_sender: matches ^\\d{8}@ and not personal) or | |
1285 | $message_body contains "this is not spam" | |
1286 | then | |
1287 | seen finish | |
1288 | endif | |
1289 | .endd | |
1290 | A condition can be preceded by &(not)& to negate it, and there are also some | |
1291 | negative forms of condition that are more English-like. | |
1292 | ||
1293 | ||
1294 | ||
4aa45c31 | 1295 | .section "String testing conditions" "SEC23" |
9b371988 PH |
1296 | There are a number of conditions that operate on text strings, using the words |
1297 | &"begins"&, &"ends"&, &"is"&, &"contains"& and &"matches"&. If you want to | |
1298 | apply the same test to more than one header line, you can easily concatenate | |
1299 | them into a single string for testing, as in this example: | |
1300 | .code | |
1301 | if "$h_to:, $h_cc:" contains me@domain.example then ... | |
1302 | .endd | |
1303 | If a string-testing condition name is written in lower case, the testing | |
1304 | of letters is done without regard to case; if it is written in upper case | |
1305 | (for example, &"CONTAINS"&), the case of letters is taken into account. | |
1306 | ||
1307 | .display | |
1308 | &` `&<&'text1'&>&` begins `&<&'text2'&> | |
1309 | &` `&<&'text1'&>&` does not begin `&<&'text2'&> | |
1310 | &`e.g. $header_from: begins "Friend@"`& | |
1311 | .endd | |
1312 | ||
1313 | A &"begins"& test checks for the presence of the second string at the start of | |
1314 | the first, both strings having been expanded. | |
1315 | ||
1316 | .display | |
1317 | &` `&<&'text1'&>&` ends `&<&'text2'&> | |
1318 | &` `&<&'text1'&>&` does not end `&<&'text2'&> | |
1319 | &`e.g. $header_from: ends "public.com.example"`& | |
1320 | .endd | |
1321 | ||
1322 | An &"ends"& test checks for the presence of the second string at the end of | |
1323 | the first, both strings having been expanded. | |
1324 | ||
1325 | .display | |
1326 | &` `&<&'text1'&>&` is `&<&'text2'&> | |
1327 | &` `&<&'text1'&>&` is not `&<&'text2'&> | |
1328 | &`e.g. $local_part_suffix is "-foo"`& | |
1329 | .endd | |
1330 | ||
1331 | An &"is"& test does an exact match between the strings, having first expanded | |
1332 | both strings. | |
1333 | ||
1334 | .display | |
1335 | &` `&<&'text1'&>&` contains `&<&'text2'&> | |
1336 | &` `&<&'text1'&>&` does not contain `&<&'text2'&> | |
1337 | &`e.g. $header_subject: contains "evolution"`& | |
1338 | .endd | |
1339 | ||
1340 | A &"contains"& test does a partial string match, having expanded both strings. | |
1341 | ||
1342 | .display | |
1343 | &` `&<&'text1'&>&` matches `&<&'text2'&> | |
1344 | &` `&<&'text1'&>&` does not match `&<&'text2'&> | |
1345 | &`e.g. $sender_address matches "(bill|john)@"`& | |
1346 | .endd | |
1347 | ||
1348 | For a &"matches"& test, after expansion of both strings, the second one is | |
1349 | interpreted as a regular expression. Exim uses the PCRE regular expression | |
1350 | library, which provides regular expressions that are compatible with Perl. | |
1351 | ||
1352 | The match succeeds if the regular expression matches any part of the first | |
1353 | string. If you want a regular expression to match only at the start or end of | |
1354 | the subject string, you must encode that requirement explicitly, using the | |
1355 | &`^`& or &`$`& metacharacters. The above example, which is not so constrained, | |
1356 | matches all these addresses: | |
1357 | .code | |
1358 | bill@test.example | |
1359 | john@some.example | |
1360 | spoonbill@example.com | |
1361 | littlejohn@example.com | |
1362 | .endd | |
1363 | To match only the first two, you could use this: | |
1364 | .code | |
1365 | if $sender_address matches "^(bill|john)@" then ... | |
1366 | .endd | |
1367 | Care must be taken if you need a backslash in a regular expression, because | |
1368 | backslashes are interpreted as escape characters both by the string expansion | |
1369 | code and by Exim's normal processing of strings in quotes. For example, if you | |
1370 | want to test the sender address for a domain ending in &'.com'& the regular | |
1371 | expression is | |
1372 | .code | |
1373 | \.com$ | |
1374 | .endd | |
1375 | The backslash and dollar sign in that expression have to be escaped when used | |
1376 | in a filter command, as otherwise they would be interpreted by the expansion | |
1377 | code. Thus, what you actually write is | |
1378 | .code | |
1379 | if $sender_address matches \\.com\$ | |
1380 | .endd | |
1381 | An alternative way of handling this is to make use of the &`\N`& expansion | |
1382 | flag for suppressing expansion: | |
1383 | .code | |
1384 | if $sender_address matches \N\.com$\N | |
1385 | .endd | |
1386 | Everything between the two occurrences of &`\N`& is copied without change by | |
1387 | the string expander (and in fact you do not need the final one, because it is | |
1388 | at the end of the string). If the regular expression is given in quotes | |
1389 | (mandatory only if it contains white space) you have to write either | |
1390 | .code | |
1391 | if $sender_address matches "\\\\.com\\$" | |
1392 | .endd | |
1393 | or | |
1394 | .code | |
1395 | if $sender_address matches "\\N\\.com$\\N" | |
1396 | .endd | |
1397 | ||
1398 | If the regular expression contains bracketed sub-expressions, numeric | |
1399 | variable substitutions such as &$1$& can be used in the subsequent actions | |
1400 | after a successful match. If the match fails, the values of the numeric | |
1401 | variables remain unchanged. Previous values are not restored after &(endif)&. | |
1402 | In other words, only one set of values is ever available. If the condition | |
1403 | contains several sub-conditions connected by &(and)& or &(or)&, it is the | |
1404 | strings extracted from the last successful match that are available in | |
1405 | subsequent actions. Numeric variables from any one sub-condition are also | |
1406 | available for use in subsequent sub-conditions, because string expansion of a | |
1407 | condition occurs just before it is tested. | |
1408 | ||
1409 | ||
4aa45c31 | 1410 | .section "Numeric testing conditions" "SEC24" |
9b371988 PH |
1411 | The following conditions are available for performing numerical tests: |
1412 | ||
1413 | .display | |
1414 | &` `&<&'number1'&>&` is above `&<&'number2'&> | |
1415 | &` `&<&'number1'&>&` is not above `&<&'number2'&> | |
1416 | &` `&<&'number1'&>&` is below `&<&'number2'&> | |
1417 | &` `&<&'number1'&>&` is not below `&<&'number2'&> | |
1418 | &`e.g. $message_size is not above 10k`& | |
1419 | .endd | |
1420 | ||
1421 | The <&'number'&> arguments must expand to strings of digits, optionally | |
1422 | followed by one of the letters K or M (upper case or lower case) which cause | |
1423 | multiplication by 1024 and 1024x1024 respectively. | |
1424 | ||
1425 | ||
4aa45c31 | 1426 | .section "Testing for significant deliveries" "SEC25" |
9b371988 PH |
1427 | You can use the &(delivered)& condition to test whether or not any previously |
1428 | obeyed filter commands have set up a significant delivery. For example: | |
1429 | .code | |
1430 | if not delivered then save mail/anomalous endif | |
1431 | .endd | |
1432 | &"Delivered"& is perhaps a poor choice of name for this condition, because the | |
1433 | message has not actually been delivered; rather, a delivery has been set up for | |
1434 | later processing. | |
1435 | ||
1436 | ||
4aa45c31 | 1437 | .section "Testing for error messages" "SEC26" |
9b371988 PH |
1438 | The condition &(error_message)& is true if the incoming message is a bounce |
1439 | (mail delivery error) message. Putting the command | |
1440 | .code | |
1441 | if error_message then finish endif | |
1442 | .endd | |
1443 | at the head of your filter file is a useful insurance against things going | |
1444 | wrong in such a way that you cannot receive delivery error reports. &*Note*&: | |
1445 | &(error_message)& is a condition, not an expansion variable, and therefore is | |
1446 | not preceded by &`$`&. | |
1447 | ||
1448 | ||
4aa45c31 | 1449 | .section "Testing a list of addresses" "SEC27" |
9b371988 PH |
1450 | There is a facility for looping through a list of addresses and applying a |
1451 | condition to each of them. It takes the form | |
1452 | .display | |
1453 | &`foranyaddress `&<&'string'&>&` (`&<&'condition'&>&`)`& | |
1454 | .endd | |
1455 | where <&'string'&> is interpreted as a list of RFC 2822 addresses, as in a | |
1456 | typical header line, and <&'condition'&> is any valid filter condition or | |
1457 | combination of conditions. The &"group"& syntax that is defined for certain | |
1458 | header lines that contain addresses is supported. | |
1459 | ||
1460 | The parentheses surrounding the condition are mandatory, to delimit it from | |
1461 | possible further sub-conditions of the enclosing &(if)& command. Within the | |
1462 | condition, the expansion variable &$thisaddress$& is set to the non-comment | |
1463 | portion of each of the addresses in the string in turn. For example, if the | |
1464 | string is | |
1465 | .code | |
1466 | B.Simpson <bart@sfld.example>, lisa@sfld.example (his sister) | |
1467 | .endd | |
1468 | then &$thisaddress$& would take on the values &`bart@sfld.example`& and | |
1469 | &`lisa@sfld.example`& in turn. | |
1470 | ||
1471 | If there are no valid addresses in the list, the whole condition is false. If | |
1472 | the internal condition is true for any one address, the overall condition is | |
1473 | true and the loop ends. If the internal condition is false for all addresses in | |
1474 | the list, the overall condition is false. This example tests for the presence | |
1475 | of an eight-digit local part in any address in a &'To:'& header: | |
1476 | .code | |
1477 | if foranyaddress $h_to: ( $thisaddress matches ^\\d{8}@ ) then ... | |
1478 | .endd | |
1479 | When the overall condition is true, the value of &$thisaddress$& in the | |
1480 | commands that follow &(then)& is the last value it took on inside the loop. At | |
1481 | the end of the &(if)& command, the value of &$thisaddress$& is reset to what it | |
1482 | was before. It is best to avoid the use of multiple occurrences of | |
1483 | &(foranyaddress)&, nested or otherwise, in a single &(if)& command, if the | |
1484 | value of &$thisaddress$& is to be used afterwards, because it isn't always | |
1485 | clear what the value will be. Nested &(if)& commands should be used instead. | |
1486 | ||
1487 | Header lines can be joined together if a check is to be applied to more than | |
1488 | one of them. For example: | |
1489 | .code | |
1490 | if foranyaddress $h_to:,$h_cc: .... | |
1491 | .endd | |
1492 | This scans through the addresses in both the &'To:'& and the &'Cc:'& headers. | |
1493 | ||
1494 | ||
1495 | .section "Testing for personal mail" "SECTpersonal" | |
1496 | A common requirement is to distinguish between incoming personal mail and mail | |
1497 | from a mailing list, or from a robot or other automatic process (for example, a | |
1498 | bounce message). In particular, this test is normally required for &"vacation | |
1499 | messages"&. | |
1500 | ||
1501 | The &(personal)& condition checks that the message is not a bounce message and | |
1502 | that the current user's email address appears in the &'To:'& header. It also | |
1503 | checks that the sender is not the current user or one of a number of common | |
1504 | daemons, and that there are no header lines starting &'List-'& in the message. | |
1505 | Finally, it checks the content of the &'Precedence:'& header line, if there is | |
1506 | one. | |
1507 | ||
1508 | You should always use the &(personal)& condition when generating automatic | |
1509 | responses. This example shows the use of &(personal)& in a filter file that is | |
1510 | sending out vacation messages: | |
1511 | .code | |
1512 | if personal then | |
1513 | mail to $reply_address | |
1514 | subject "I am on holiday" | |
1515 | file $home/vacation/message | |
1516 | once $home/vacation/once | |
1517 | once_repeat 10d | |
1518 | endif | |
1519 | .endd | |
1520 | It is tempting, when writing commands like the above, to quote the original | |
1521 | subject in the reply. For example: | |
1522 | .code | |
1523 | subject "Re: $h_subject:" | |
1524 | .endd | |
1525 | There is a danger in doing this, however. It may allow a third party to | |
1526 | subscribe you to an opt-in mailing list, provided that the list accepts bounce | |
1527 | messages as subscription confirmations. (Messages sent from filters are always | |
1528 | sent as bounce messages.) Well-managed lists require a non-bounce message to | |
1529 | confirm a subscription, so the danger is relatively small. | |
1530 | ||
1531 | If prefixes or suffixes are in use for local parts &-- something which depends | |
1532 | on the configuration of Exim (see section &<<SECTmbox>>& below) &-- the tests | |
1533 | for the current user are done with the full address (including the prefix and | |
1534 | suffix, if any) as well as with the prefix and suffix removed. If the system is | |
1535 | configured to rewrite local parts of mail addresses, for example, to rewrite | |
1536 | &`dag46`& as &`Dirk.Gently`&, the rewritten form of the address is also used in | |
1537 | the tests. | |
1538 | ||
1539 | ||
1540 | ||
4aa45c31 | 1541 | .section "Alias addresses for the personal condition" "SEC28" |
9b371988 PH |
1542 | It is quite common for people who have mail accounts on a number of different |
1543 | systems to forward all their mail to one system, and in this case a check for | |
1544 | personal mail should test all their various mail addresses. To allow for this, | |
1545 | the &(personal)& condition keyword can be followed by | |
1546 | .display | |
1547 | &`alias `&<&'address'&> | |
1548 | .endd | |
1549 | any number of times, for example: | |
1550 | .code | |
1551 | if personal alias smith@else.where.example | |
1552 | alias jones@other.place.example | |
1553 | then ... | |
1554 | .endd | |
1555 | The alias addresses are treated as alternatives to the current user's email | |
1556 | address when testing the contents of header lines. | |
1557 | ||
1558 | ||
4aa45c31 | 1559 | .section "Details of the personal condition" "SEC29" |
9b371988 PH |
1560 | The basic &(personal)& test is roughly equivalent to the following: |
1561 | .code | |
1562 | not error_message and | |
1563 | $message_headers does not contain "\nList-Id:" and | |
1564 | $message_headers does not contain "\nList-Help:" and | |
1565 | $message_headers does not contain "\nList-Subscribe:" and | |
1566 | $message_headers does not contain "\nList-Unsubscribe:" and | |
1567 | $message_headers does not contain "\nList-Post:" and | |
1568 | $message_headers does not contain "\nList-Owner:" and | |
1569 | $message_headers does not contain "\nList-Archive:" and | |
1570 | ( | |
8f3414a1 | 1571 | "${if def:h_auto-submitted:{present}{absent}}" is "absent" or |
9b371988 PH |
1572 | $header_auto-submitted: is "no" |
1573 | ) and | |
1574 | $header_precedence: does not contain "bulk" and | |
1575 | $header_precedence: does not contain "list" and | |
1576 | $header_precedence: does not contain "junk" and | |
1577 | foranyaddress $header_to: | |
1578 | ( $thisaddress contains "$local_part$domain" ) and | |
1579 | not foranyaddress $header_from: | |
1580 | ( | |
c0712871 PH |
1581 | $thisaddress contains "$local_part@$domain" or |
1582 | $thisaddress contains "server@" or | |
1583 | $thisaddress contains "daemon@" or | |
1584 | $thisaddress contains "root@" or | |
1585 | $thisaddress contains "listserv@" or | |
1586 | $thisaddress contains "majordomo@" or | |
1587 | $thisaddress contains "-request@" or | |
1588 | $thisaddress matches "^owner-[^@]+@" | |
9b371988 PH |
1589 | ) |
1590 | .endd | |
1591 | The variable &$local_part$& contains the local part of the mail address of | |
1592 | the user whose filter file is being run &-- it is normally your login id. The | |
1593 | &$domain$& variable contains the mail domain. As explained above, if aliases | |
1594 | or rewriting are defined, or if prefixes or suffixes are in use, the tests for | |
1595 | the current user are also done with alternative addresses. | |
1596 | ||
1597 | ||
1598 | ||
1599 | ||
4aa45c31 | 1600 | .section "Testing delivery status" "SEC30" |
9b371988 PH |
1601 | There are two conditions that are intended mainly for use in system filter |
1602 | files, but which are available in users' filter files as well. The condition | |
1603 | &(first_delivery)& is true if this is the first process that is attempting to | |
1604 | deliver the message, and false otherwise. This indicator is not reset until the | |
1605 | first delivery process successfully terminates; if there is a crash or a power | |
1606 | failure (for example), the next delivery attempt is also a &"first delivery"&. | |
1607 | ||
1608 | In a user filter file &(first_delivery)& will be false if there was previously | |
1609 | an error in the filter, or if a delivery for the user failed owing to, for | |
1610 | example, a quota error, or if forwarding to a remote address was deferred for | |
1611 | some reason. | |
1612 | ||
1613 | The condition &(manually_thawed)& is true if the message was &"frozen"& for | |
1614 | some reason, and was subsequently released by the system administrator. It is | |
1615 | unlikely to be of use in users' filter files. | |
1616 | ||
1617 | ||
4aa45c31 | 1618 | .section "Multiple personal mailboxes" "SECTmbox" "SEC31" |
9b371988 PH |
1619 | The system administrator can configure Exim so that users can set up variants |
1620 | on their email addresses and handle them separately. Consult your system | |
1621 | administrator or local documentation to see if this facility is enabled on your | |
1622 | system, and if so, what the details are. | |
1623 | ||
1624 | The facility involves the use of a prefix or a suffix on an email address. For | |
1625 | example, all mail addressed to &'lg303-'&<&'something'&> would be the property | |
1626 | of user &'lg303'&, who could determine how it was to be handled, depending on | |
1627 | the value of <&'something'&>. | |
1628 | ||
1629 | There are two possible ways in which this can be set up. The first possibility | |
1630 | is the use of multiple &_.forward_& files. In this case, mail to &'lg303-foo'&, | |
1631 | for example, is handled by looking for a file called &_.forward-foo_& in | |
1632 | &'lg303'&'s home directory. If such a file does not exist, delivery fails | |
1633 | and the message is returned to its sender. | |
1634 | ||
1635 | The alternative approach is to pass all messages through a single &_.forward_& | |
1636 | file, which must be a filter file so that it can distinguish between the | |
1637 | different cases by referencing the variables &$local_part_prefix$& or | |
1638 | &$local_part_suffix$&, as in the final example in section &<<SECTex>>& below. | |
1639 | ||
1640 | It is possible to configure Exim to support both schemes at once. In this case, | |
1641 | a specific &_.forward-foo_& file is first sought; if it is not found, the basic | |
1642 | &_.forward_& file is used. | |
1643 | ||
1644 | The &(personal)& test (see section &<<SECTpersonal>>&) includes prefixes and | |
1645 | suffixes in its checking. | |
1646 | ||
1647 | ||
1648 | ||
4aa45c31 | 1649 | .section "Ignoring delivery errors" "SEC43" |
9b371988 PH |
1650 | As was explained above, filtering just sets up addresses for delivery &-- no |
1651 | deliveries are actually done while a filter file is active. If any of the | |
1652 | generated addresses subsequently suffers a delivery failure, an error message | |
1653 | is generated in the normal way. However, if a filter command that sets up a | |
1654 | delivery is preceded by the word &"noerror"&, errors for that delivery, | |
1655 | and any deliveries consequent on it (that is, from alias, forwarding, or | |
1656 | filter files it invokes) are ignored. | |
1657 | ||
1658 | ||
1659 | ||
1660 | .section "Examples of Exim filter commands" "SECTex" | |
1661 | Simple forwarding: | |
1662 | ||
1663 | .code | |
1664 | # Exim filter | |
1665 | deliver baggins@rivendell.middle-earth.example | |
1666 | .endd | |
1667 | ||
1668 | Vacation handling using traditional means, assuming that the &_.vacation.msg_& | |
1669 | and other files have been set up in your home directory: | |
1670 | ||
1671 | .code | |
1672 | # Exim filter | |
1673 | unseen pipe "/usr/ucb/vacation \"$local_part\"" | |
1674 | .endd | |
1675 | ||
1676 | Vacation handling inside Exim, having first created a file called | |
1677 | &_.vacation.msg_& in your home directory: | |
1678 | ||
1679 | .code | |
1680 | # Exim filter | |
1681 | if personal then vacation endif | |
1682 | .endd | |
1683 | ||
1684 | File some messages by subject: | |
1685 | ||
1686 | .code | |
1687 | # Exim filter | |
1688 | if $header_subject: contains "empire" or | |
1689 | $header_subject: contains "foundation" | |
1690 | then | |
1691 | save $home/mail/f+e | |
1692 | endif | |
1693 | .endd | |
1694 | ||
1695 | Save all non-urgent messages by weekday: | |
1696 | ||
1697 | .code | |
1698 | # Exim filter | |
1699 | if $header_subject: does not contain "urgent" and | |
1700 | $tod_full matches "^(...)," | |
1701 | then | |
1702 | save $home/mail/$1 | |
1703 | endif | |
1704 | .endd | |
1705 | ||
1706 | Throw away all mail from one site, except from postmaster: | |
1707 | ||
1708 | .code | |
1709 | # Exim filter | |
1710 | if $reply_address contains "@spam.site.example" and | |
1711 | $reply_address does not contain "postmaster@" | |
1712 | then | |
1713 | seen finish | |
1714 | endif | |
1715 | .endd | |
1716 | ||
1717 | Handle multiple personal mailboxes: | |
1718 | ||
1719 | .code | |
1720 | # Exim filter | |
1721 | if $local_part_suffix is "-foo" | |
1722 | then | |
1723 | save $home/mail/foo | |
1724 | elif $local_part_suffix is "-bar" | |
1725 | then | |
1726 | save $home/mail/bar | |
1727 | endif | |
1728 | .endd | |
1729 |