Introduction to Sieve in the SCS Environment

Sieve in the CORVID environment

There are a number of ways to filter mail in the CORVID environment; sieve is a simple server-side mail processing system built into the Cyrus IMAP server.

What Sieve Is

Sieve is a server-side mail processing facility built into the Cyrus IMAP server.

Sieve is meant to be simple. Sieve only processes mail at delivery time — mail delivered to the IMAP server will only pass through sieve once. The command set of sieve is somewhat limited, in an attempt to reduce the possibility of mail loops (or similiar effects of clever behavior). While sieve is simple, it is powerful enough to deal with most common tasks that can be done with incoming mail at delivery time.

What Sieve Can Do

Sieve can do lots of things, based on specific characteristics of an email message. Common tasks that sieve can perform include:

Automatically file the mail into a folder (or folders)
Forward a copy of the mail to another address
Sent notification of arrival (via zephyr)
Statically whitelist or black list domains and addresses

In addition, sieve can be used for sending automatic vacation messages.

This is not a comprehensive list of sieve's functionality; for a tutorial, please see Writing Custom Scripts - A Sieve cookbook.

What Sieve Does Not Do

Because of the environment sieve runs in and the desire to keep sieve simple, there are some limitations.

Sieve can not call out to arbitrary external programs
Sieve only processes mail once, upon delivery

These functionalities are still available in the CORVID mail system, but not with sieve. Doing this sort of thing with one's mail is covered in the CORVID external processing page.

Differences Between Sieve and .maildelivery

MMDF uses .maildelivery files to preform mail processing operations on incoming mail. It is important to note that while sieve fulfills a similar role in the CORVID system, it does so in a different way.

The most notable difference between sieve scripts and .maildelivery scripts is that the sieve subsystem is contained; sieve does not allow the user to run arbitrary external scripts or programs against incoming mail.

On the other hand, sieve offers a good deal more flexibility in handling mail than .maildelivery scripts — sieve makes it much easier to select for and act on mail matching specific characteristics.

Simple Set-up of Spam Filtering and Vacation Messages

While the full power of sieve can be accessed by writing custom scripts, the most common operations are filtering spam and setting up vacation messages. To enable (and disable) sieve scripts that filter spam and/or generate a vacation message, visit the page:

http://webmail.cs.cmu.edu/websieve/

This interface will generate the appropriate sieve scripts.

Note: the simple sieve interface generates a new script each time it's run - it does not preserve state, and does not remember previous settings. For more permanent solutions, use of either the Advanced Websieve editor or sieveshell is required, as below.

Using Sieve With Custom Sieve Scripts

Sieve takes its commands about how to process incoming mail from sieve scripts. These scripts are simple text files that reside on the IMAP server (each user has a protected space for this). Users can have several sieve scripts on the server at a time, but only one may be active.

There are currently two supported methods for managing scripts on the IMAP server: a web interface, and a command line interface.

Custom Scripts with the WebSieve Interface

The advanced section of the websieve interface allows for listing scripts on the server, inspecting scripts, adding and removing scripts, editing scripts in place, and selecting the active script. The advanced Websieve interface will check all scripts for syntax, and will not allow the installation of a broken script.

To use the advanced Websieve interface, select the Advanced Mail Filtering link from the front page of the WebSieve interface.

The Advanced Mail Filtering page includes tools to list scripts on the server, activate and deactivate scripts, inspect individual scripts and edit them in place. The Websieve tool will check all edited scripts for syntax; it will not allow the installation of a broken script.

Note: the websieve tool does not activate scripts by default — processing will only occur if a script is activated. The currently enabled script can be determined by checking which script is designated as (ENABLED) in the list of scripts. If no script is so designated, no processing will take place, and all mail will be delivered to the default location (the INBOX).

Custom Scripts with SieveShell

Sieveshell is a unix command line tool, available as part of the CORVID system and the SCS Facilities computing environment:

bovik$ /usr/local/bin/sieveshell imap.srv.cs.cmu.edu

Sieveshell can be used to list scripts on the server, inspect scripts, add and remove scripts from the server, and select the active script. Sieveshell will check all new scripts for syntax; the tool will not allow the installation of a broken script.

The help command will show a list of available commands, with a brief description for each. The following commands are available:

help — display the help screen
list — list the avaialble scripts on server
put filename — upload filename to the server
get scriptname [filename] — Display (if a filename is given, save the script to that file)
delete scriptname — delete the script scriptname
activate scriptname — set scriptname as the active script
deactivate — deactivate all scripts
quit — quit the sieveshell utility

Note: the sieveshell tool does not activate scripts by default — processing will only occur if a script is activated. The currently enabled script can be determined by checking which script is designated as the active script in the list of scripts. If no script is so designated, no processing will take place, and all mail will be delivered to the default location (the INBOX).

Note: as of Nov-05, sieveshell is stil in beta on Fedora Core 3 platforms. Users are advised to run sieveshell on a RedHat9 machine.

Writing Custom Scripts - A Sieve Cookbook

General Notes

The sieve processing system uses a scripting language to process mail. As above, while each user may have multiple scripts on the server, only one script may be active at one time. Sieve scripts execute in order, and will generally try to keep processing mail until told to stop (either implictly by using a command like fileinto, or explicitly). The default action for a sieve script is to deliver mail into the user's INBOX.

While it is recommended to keep sieve scripts as simple as possible, sieve can be a powerful tool! Please exercise care when writing and testing sieve scripts; it is possible to irretrievably lose mail with a badly formed script.

Syntax in sieve scripts is important; both sieveshell and the Websieve interface will check your syntax for you, and will not allow scripts broken scripts to be installed.

Comments

Any line starting with a "#" is treated as a comment. This can be handy for documenting what a script does, especially if scripts become clever.

The `require` line

All sieve scripts must begin with a require statement. This line defines what extensions the sieve subsystem can use to process mail. In most cases, this line should include all avalable extensions, as follows:

require ["fileinto","reject","vacation","imapflags","relational","regex","notify"];

There should only be one require line in a sieve script.

Selecting Messages

In if blocks, the selection criteria for messages can be selected either singly:

if header :contains "From" "bovik@cs.cmu.edu" { ... }

....or in a list:

if header :contains "From" ["bovik@cs.cmu.edu","bovik+@cs.cmu.edu","hbovik@gmail.com"] {...}

In the first example, the sieve script will act on mail from "bovik@cs.cmu.edu". In the second example, the seive script will act on mail from any of the addresses specified.

Filing mail into a folder

Sieve files mail into specific folders with the fileinto command. In the following example, mail from "bovik@cs.cmu.edu" is automatically filed into the mailbox "Bovik":

# Check if the message is from a specific user
#
if header :contains "From" "bovik@cs.cmu.edu" {
        fileinto "INBOX.Bovik";
}

Note: please make sure when using the fileinto command that the folder specified exists!

Sieve can also check other headers. For example, checking the "To" field can be handy for dealing with mailing lists:

# Put mail from the SCS-all mailing list into a folder:
#
if header :contains "To" "scs-all@cs.cmu.edu" {
        fileinto "INBOX.scsall";
}

Or, as another example, sieve can handle automatic filing of things like the PMX:VIRUS messages:

# Put virus warnings into their own folder
#
if header :contains "Subject" "PMX:VIRUS" {
        fileinto "INBOX.VIRUS";
}

Filtering SPAM

Filtering SPAM is a lot like the above example, except this time the test is for a special header added by the PureMessage spam tagging service.

# Check if the PureMessage service thinks this message is spam;
# if so, file it into the SPAM folder
#
if header :contains "X-Spam-Warning" "" {
        fileinto "INBOX.SPAM";
}

Note: the "SPAM" folder is created by default with each IMAP account.

Redirecting or Resending Mail

Redirecting mail can be accomplished with the redirect command. This can be useful if the user would also like to receive mail at another address:

# Resend a copy of the message to another address
#
if true {
       redirect "bovik@exchange.cs.cmu.edu";
}

Vacation Messages

Sieve can handle the automatic sending of vacation messages:

# Automatic vacation message
#
vacation 
         :days 3 
         :addresses ["bovik+@cs.cmu.edu","harry.bovik@cs.cmu.edu"] 
         :subject "Vacation Message"

# Body of the vacation message, in double quotes
"
I am on vacation and will read your e-mail on my return.
"

;

There are several options in the above script that the user can set:

The :days keyword will set the notification timeout for sending vacation messages. Sieve keeps track of who has received vacation notification messages from a user, and can hold off on sending responses even if the sender continues to send mail. In the above example, sieve will wait three days between sending automatic notifications. Note: this should not be used to specify the length of a vacation; turning off vacation messages is accomplished by activating another script.

The :addresses keyword is used to list mail addresses that require an automatic apply. The vacation extension works on strict matches, so if the user has multiple email addresses, they should be listed here.

The :subject keyword specifies the Subject line of the automatic response mail.

The remainder of vacation stanza is the body of the automatic response mail, enclosed in double quotes and terminated with a semicolon.

Sieve Script Examples - Putting It All Together

Our user Harry wants to set up two scripts; a general script that does typical filtering duties, and a travelling script that he can use on the road. The scripts might look like this:

Harry's General Script


# Harry's general purpose sieve script
#
# general.sieve
#
require ["fileinto","reject","vacation","imapflags","relational","regex","notify"];

# Move mail tagged as SPAM into a dedicated folder
if header :matches "X-Spam-Warning" "*"
{
	fileinto "INBOX.SPAM";
}
# Move PMX:VIRUS messages into a dedicated folder
elsif header :contains "Subject" "PMX:VIRUS"
{
	fileinto "INBOX.VIRUS";
}
# Process everything else...
else
{
       # Send a copy to the exchange server as a backup
       redirect "bovik@exchange.cs.cmu.edu";

       # File mail to scs-all into a dedicated folder
       if header :contains "To" "scs-all@cs.cmu.edu" {
               fileinto "INBOX.scsall";
       }
       # Deliver everything else into the inbox
       else {
               fileinto "INBOX";
       }
}

Harry's Travelling Script


# Harry's travelling sieve script
#
# general.sieve
#
require ["fileinto","reject","vacation","imapflags","relational","regex","notify"];

# Move mail tagged as SPAM into a dedicated folder
if header :matches "X-Spam-Warning" "*"
{
	fileinto "INBOX.SPAM";
}
# Move PMX:VIRUS messages into a dedicated folder
elsif header :contains "Subject" "PMX:VIRUS"
{
	fileinto "INBOX.VIRUS";
}
# Process everything else...
else
{
       # Send a copy to the exchange server as a backup
       redirect "bovik@exchange.cs.cmu.edu";

       # Send a copy to the travelling account, too
       redirect "hbovik@gmail.com";

       # File mail to scs-all into a dedicated folder
       if header :contains "To" "scs-all@cs.cmu.edu" {
               fileinto "INBOX.scsall";
       }
       # Deliver everything else into the inbox
       else {
               fileinto "INBOX";
       }
}

vacation 
         :days 3 
         :addresses ["bovik+@cs.cmu.edu","harry.bovik@cs.cmu.edu"] 
         :subject "Vacation Message"

# Body of the vacation message, in double quotes
"
I am on vacation and will read your e-mail on my return.
"

;

With both of these scripts on the server, Harry can simply select the vacation script for when he's out of town, and re-activate the general script upon return.