ARCHIVED: At IU, on the Shakespeare and Jewel systems, how do I set up server-side mail filters?

Warning: Though filters on the Shakespeare and Jewel systems were designed to reduce the risk of mail loss, it is also easy to accidentally misfile or even destroy your mail. Use caution when designing your rule sets.

Note: It is currently not possible to use server-side filters to catch spam based on the "X-Spam-Flag" notation that you may see if you view the full headers of mail messages. This header is assigned by the UITS spam quarantine service. For more information, see the Knowledge Base document ARCHIVED: At IU, what is the spam quarantine service? For instructions on opting into the spam quarantine service, see the Knowledge Base document ARCHIVED: At IU, how can I filter spam?

At Indiana University, to create server-side filters on the Shakespeare and Jewel systems, you must create a filter description file, add rules to the filter, then apply the filter.

Create the filter description file

1. In Pine, from the Main Menu, press ! (the exclamation point) to exit to the Unix shell.

2. Enter the following command:

     pico ~/.filter

   This opens the new file .filter in the Pico editor.

Note: You do not have to name your description file .filter. However, if you give the file a different name, substitute that name for .filter throughout the rest of this document.

Add rules to the filter

The filter program translates the rules within this file into Procmail "recipes", which the IMAP servers understand. Your filter description file should look similar to the following:

  [Ruleset 1]
  FROM=Josh
  SUBJECT=I like turtles
  CONTINUE=no
  ACTION=file
  DESTINATION=folder1

The first line, [Ruleset 1], is the name of the rule set. You may name the rule set anything you want, but the name should be enclosed in brackets as shown.

The second and third lines, FROM=Josh and SUBJECT=I like turtles, are the match rules. They determine if a message is affected by the rule set. In this case, any message with a "From:" line that begins with "Josh" and a "Subject:" line that begins with "I like turtles" will be affected. As another example, if you wanted to filter messages sent to you from dvader@iupui.edu, with a subject beginning with "Death Star Plans", you would enter the following:

  FROM=.*dvader@iupui\.edu
  SUBJECT=Death Star Plans

If you wanted to filter all mail sent to you from dvader@iupui.edu, you would enter:

  FROM=.*dvader@iupui\.edu

Note: If you wish to filter for a specific email address, you must preface the address with .*. The period (.) is a wildcard that means "any one character", while the asterisk (*) means "any number of the previous character". You have to include this because the filter program begins matching at the first character of the header. The "From:" field has the format Real Name <username@machine.name>, and the value .* followed by an email address tells the filter to match on any "From:" line that contains, rather than begins with, the address. You must also put a backslash ( \ ) before any period in an email address to prevent the filter from interpreting it as the "any one character" wildcard.

It is possible to match the following headers: "From", "To", "Cc", "Subject", "X-Sender", "Return-Path", and "Reply-To". In addition, the following special headers are allowed:

• ^TO_: Most destination specifications containing a specific address. In Procmail, this expands to:

    '(^((Original-)?(Resent-)?(To|Cc|Bcc)|(X-Envelope|Apparently(-Resent)?)-To):(.*[^-a-zA-Z0-9_.])?)'

• ^TO: Most destination specifications containing a specific word. In Procmail, this expands to:

    `(^((Original-)?(Resent-)?(To|Cc|Bcc)|(X-Envelope|Apparently(-Resent)?)-To):(.*[^a-zA-Z])?)'

• ^FROM_DAEMON: Mail from most daemons.
• ^FROM_MAILER: Mail from most mail-daemons.

Note: Each rule set may have multiple match rules. However, rules cannot match text in the body of the message.

The fourth line, CONTINUE=, specifies whether or not to continue applying rule sets if there has been a match. Entering "yes" after the CONTINUE= allows you to apply other rule sets. Entering "no" specifies that messages that matched the rules would be acted on immediately and will not be passed on to other rule sets for evaluation. If a message does not match any rule set, it is delivered normally.

The ACTION= line has two options, "file" or "forward". If the action is "file", the value following DESTINATION= should be the name of the folder to contain the message. For example, if you want all messages from dvader@iupui.edu with a subject line beginning with "Death Star Plans" sent immediately to the Empire folder, you would enter:

  FROM=.*dvader@iupui\.edu
  SUBJECT=Death Star Plans
  CONTINUE=no
  ACTION=file
  DESTINATION=Empire

If the folder does not exist, matched messages will be put in your Inbox. In addition, if you want to delete messages that match the rule set, enter /dev/null for the folder name.

If the ACTION= line is set to "forward", the value in the DESTINATION= line should be the email address to receive the forwarded message. To follow the preceding example, if you want the messages sent from dvader@iupui.edu forwarded to luke@force.com, enter:

  FROM=.*dvader@iupui\.edu
  SUBJECT=Death Star Plans
  CONTINUE=no
  ACTION=forward
  DESTINATION=luke@force.com

Note: You can forward messages to only one address.

When you've completed your edits, press Ctrl-x to exit and save the file.

Apply the filter

Once you create your filter description file, your next step is to apply the filters to incoming mail. At the Unix prompt, enter:

  filter on

You will then be prompted for the filter name. Enter the name of your filter description file:

  .filter

Every time you make changes to your filter description file, you will need to enter filter on again.

If you wanted to turn filtering off, you would enter the following command:

  filter off

To see what your current filter looks like, enter:

  filter list

To view your current filter as its Procmail translation, enter:

  filter raw