Filter files, especially the more complicated ones, should always be tested, as it is easy to make mistakes. Exim provides a facility for preliminary testing of a filter file before installing it. This tests the syntax of the file and its basic operation, and can also be used with ordinary `.forward' files.
Because a filter can do tests on the content of messages, a test message is required. Suppose you have a new filter file called "new-filter" and a test message called "test-message". Assuming that Exim is installed with the conventional path name `/usr/lib/sendmail', the following command can be used:
/usr/lib/sendmail -bf new-filter <test-message
The `-bf' option tells Exim that the following item on the command line is the name of a filter file which is to be tested, and the test message is supplied on the standard input. If there are no message-dependent tests in the filter, then an empty file can be used. A supplied message must start with header lines or the `From' message separator line which is found in many multi-message folder files. Note that blank lines at the start terminate the header lines. A warning is given if no headers are read.
The result of running this command, provided no errors are detected in the filter file, is a list of the actions that Exim would try to take if presented with the message for real. For example, the output
Deliver message to: gulliver@lilliput.fict.book Save message to: /home/lemuel/mail/archive
means that one copy of the message would be sent to `gulliver@lilliput.fict.book', and another would be added to the file `/home/lemuel/mail/archive', if all went well.
The actions themselves are not attempted while testing a filter file in this way; there is no check, for example, that any forwarding addresses are valid. If you want to know why a particular action is being taken, add the `-v' option to the command. This causes Exim to output the results of any conditional tests and to indent its output according to the depth if nesting of `if' commands. Further additional output from a filter test can be generated by the `testprint' command, which is described below.
When Exim is outputting a list of the actions it would take, if any text strings are included in the output, non-printing characters therein are converted to escape sequences. In particular, if any text string contains a newline character, this is shown as `\n' in the testing output.
When testing a filter in this way, Exim makes up an `envelope' for the message. The recipient is by default the user running the command, and so is the sender, but the command can be run with the `-f' option to supply a different sender. For example,
/usr/lib/sendmail -bf new-filter -f islington@neverwhere <test-message
Alternatively, if the `-f' option is not used, but the first line of the supplied message is a `From' separator from a message folder file (not the same thing as a "From:" header line), the sender is taken from there. If `-f' is present, the contents of any `From' line are ignored.
The `return path' is the same as the envelope sender, unless the message contains a "Return-path:" header, in which case it is taken from there. You need not worry about any of this unless you want to test out features of a filter file that rely on the sender address or the return path.
It is possible to change the envelope recipient by specifying further options. The `-bfd' option changes the domain of the recipient address, while the `-bfl' option changes the `local part', that is, the part before the @ sign. An adviser could make use of these to test someone else's filter file.
The `-bfp' and `-bfs' options specify the prefix or suffix for the local part. These are relevant only when support for multiple personal mailboxes is implemented; see the description in section "Multiple personal mailboxes" below.
Go to the first, previous, next, last section, table of contents.