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