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