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' (some operating systems use `/usr/sbin/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. There is also a -bF option, which is similar, but which is used for testing system filter files, as opposed to user filter files, and which is therefore of use only to the system administrator.
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.example Save message to: /home/lemuel/mail/archive
means that one copy of the message would be sent to gulliver@lilliput.fict.example, 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 26 below.
Go to the first, previous, next, last section, table of contents.