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