18.15 To Debug User-level Filters

If a user complains that a Sieve filter is not behaving as expected, there are a number of steps you can take to debug the filters. These are described here.

To Debug User-level Filters

1. For fileinto filtering to work, check that the ims-ms channel in the imta.cnf file is marked as follows:

   fileinto $U+$S@$D

2. Get the user level filters from the user’s LDAP entry.

   User level filters are stored in their LDAP entry under the MailSieveRuleSource attribute(s). To retrieve this with a ldapsearch command, remember they are base64 encoded so you will need to decode the output by using the -Bo switch.

   ./ldapsearch -D "cn=directory manager" -w password -b "o=alcatraz.sesta.com,o=isp" -Bo uid=test

   The imsimta test -rewrite command, described below, will also automatically decode them.

3. Verify that the user’s filters are being seen by the MTA.

   Issue the command:

   # imsimta test -rewrite -filter -debug user@sesta.com

   This should output the user’s Sieve filters that you retrieve in the previous step. If you do not see the filters, then you need to figure out why the LDAP entry isn't returning them. If the imsimta test -rewrite output shows the filters, then you know that the user’s filters are being seen by the MTA. The next step is to test the interpretation of the filters by using the imsimta test -expression command.

4. Use imsimta test -exp to debug the user's filter. The following information is required:

   1. The user's Sieve language statements from their mailSieveRuleSource attribute. See the steps above.

   2. The rfc2822 message that was supposed to trigger the filter.

   3. Description of what they expected the filter to do to the message.

5. Create a text file (example: temp.filter) containing the Sieve language statements based on the user's mailSieveRuleSource: values. Example:

   require "fileinto";
   if anyof(header :contains
   ["To","Cc","Bcc","Resent-to","Resent-cc", 
      "Resent-bcc"] "commsqa"){ 
      fileinto "QMSG";
   }

   Expected result: if commsqa is a recipient for this message, then file the message into a folder called QMSG.

6. Create a text file called test.msg that contains the contents of the rfc2822 message file supplied by user.

   You can either use a .msg file from the user's message store area, or create a text file called test_rfc2822.msg that contains the contents of the rfc2822 message file supplied by user.

7. Use the imsimta test -exp command:

   # imsimta test -exp -mm -block -input=temp.filter -message=test_rfc2822.msg

8. Examine the output.

   The last lines of the imsimta test -exp command will show the result of the Sieve interpretation. They will look like this:

   Sieve Result: [] or this: Sieve Result: [action]

   where action is the action that would be done as a result of applying the Sieve filter on this message.

   If the criteria of the filter matched, you will have some action displayed as the result. If nothing matched, then the Sieve result will be blank, and there is either a logic error in the Sieve filter or the .msg file doesn't contain matching information. If you get any other error, then there is a syntax error in the Sieve script file, and you need to debug it.

   For more details on the output, see 18.15.1 imsimta test -exp Output.

9. If the filter is syntactically valid and results are correct, then the next step is to examine a tcp_local_slave.log debug log file.

   It may be that the message file you're testing and the one being sent aren't identical. The only way to see what's being received is to examine a tcp_local_slave.log file. This log will show you the exact message being sent to the MTA and how the filter is being applied to that message.

   For more information on getting a tcp_local_slave.log debug file, see the slave_debug keyword in 12.11.2 Debugging Keywords.

18.15.1 imsimta test -exp Output

The full command imsimta test -exp for is as follows:

# imsimta test -exp -mm -block -input=temp.filter -message=rfc2822.msg

An example of the output is as follows:

Example 18–4 imsimta test -exp Output

# imsimta test -exp -mm -block -input tmp.filter -message=rfc2822.msg
Expression: if header :contains ["to"] ["pamw"]       (1)
Expression: {
Expression: redirect "usr3@sesta.com";
Expression: keep;
Expression: }
Expression:
Expression: Dump: header:2000114;0  3  1  :contains  1  "to"  1
"pamw"  if  8  ;
Dump: redirect:2000121;0  1  1  "usr3@sesta.com"  ;  keep:2000117;0 (2)
Dump: 0
Result: 0
Filter result: [ redirect "usr3@sesta.com" keep ]    (3)
            

1) The Expression: output lines show the filter being read and parsed from tmp.filter text file. These are not particularly useful in debugging the script.

2) The Dump: output lines are the result of the computer interpreting the Sieve statements. You should not see any errors and the output should seem to match your input. For example the dump shows the word redirect, usr3@sesta.com which is like the line in the filter file redirect "usr3@sesta.com";

If it didn't show this matching text, then you'd be concerned, otherwise, these also are not particularly useful in debugging the script.

3) At the bottom of the output you will get the Filter result: statement. As stated earlier there are two possible results:

Sieve Result: [] or this: Sieve Result: [action]

where action is the action taken by the Sieve script. Note that sometimes the results are expected to be empty. For example, for a discard filter, you should test that it doesn't always discard every .msg file you test it against. If there is some action between the brackets, for example:

Filter result: [ fileinto "QMSG" keep]

This means the text in the rfc2822.msg file matched the filter criteria. In this particular example, the filter will file the mail into folder QMSG and keep a copy in the inbox. The resulting actions in this case are fileinto and keep.

When testing filters you should test various .msg files for both results. You should always test that messages that match your filter are filtered, and messages that you do not want to match are not filtered.

Keep in mind that if for wildcard matches, you must use the :matches test and not :contains. For example, if you wish from=*@sesta.com to match, you must use :matches or the test will fail as it will not ever satisfy the test condition.

18.15.2 imsimta test -exp Syntax

imsimta test -exp tests Sieve language statements against a specified RFC2822 message and sends the results of the filter to standard output.

The syntax is as follows:

imsimta test -exp -mm -block -input=Sieve_language_scriptfile -message=rfc2822_message_file

where,

-block treats the entire input as a single Sieve script. The default is to treat each line as a separate script and to evaluate it separately. The Sieve will only be evaluated once the end of file is reached.

-input=Sieve_file is a file containing the Sieve script. The default is to read the test script lines or script block from stdin.

-message=message_file is a text file containing the RFC 2822 message you want to test your Sieve script against. This has to be an RFC 2822 message only. It cannot be a queue file (not a zz*.00 file).

Once activated, this command reads script information, evaluates it in the context of the test message, and writes out the result. The result shows what actions would be taken as well as the result of evaluating the final statement in the script.

Additional useful qualifiers are:

-from=address specifies the envelope from: address to be used in envelope tests. The default is to use the value specified by the RETURN_ADDRESS MTA option.

-output=file writes results to file. The default is to write the results of script evaluation to stdout.