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