Websieve

From Peyton Hall Documentation

IMPORTANT: We have phased Websieve out in favor of SmartSieve. We have found it works well and is a bit more intuitive to use than Websieve was; however, we haven't quite finished working on the documentation for SmartSieve yet, so we're going to keep this page around for a bit longer as it explains some concepts common to both. The links to websieve below will not work. You MUST use SmartSieve now.

Sieve is the mail filter scripting language for Cyrus IMAPD (our mail server). Websieve is a web based application which lets you edit Sieve scripts, either directly or through a point and click interface. Websieve, though simple, is fairly powerful and will allow you to create all but the most complex Sieve scripts without ever touching the language itself.

Contents 1 Getting started 1.1 Where is it? 1.2 Viewing and editing rules 1.3 Adding new rules 1.4 Vacation messages 1.5 Managing scripts 1.5.1 Activating a script 1.5.2 Selecting a script 1.5.3 Saving a new script 1.5.4 Deleting a script 1.6 Advanced mode 1.7 Setting ACLs 2 Example Sieve scripts 2.1 Tagged spam filtering 2.2 Finer spam control 2.3 Forwarding email

Getting started

Please read over the following sections before starting.

NOTE:

You MUST activate the Sieve script before it will function. See below for how to do this.

Where is it?

Point your web browser to https://mail.astro.princeton.edu/cgi-bin/websieve.pl to login.

Viewing and editing rules

Clicking on the "View/Edit Rules" link will display all the rules in the current script. Here you can rearrange the rules you have, as well as edit, delete or disable any of the rules in your script.

At any time, you can click on the "Refresh" button to refresh the screen. If you wish to undo any changes that you've made (BEFORE clicking on "Save Changes"), then click on the "Reset Values" button. If you've already saved the changes, you will have to undo them manually.

To delete a rule, select "DELETE" from the drop-down box next to the rule you wish to remove, and then click the "Save Changes" button. The rule will be deleted, and the display will refresh to reflect the changes.

To disable a rule, select "DISABLED" from the drop-down box next to the rule you wish to disable, and then click the "Save Changes" button. The rule will then be disabled, so it will no longer function, however it will remain in the list of rules (marked disabled).

Conversely, to enable a disabled rule, select "ENABLED" and click on "Save Changes".

To modify a rule, select "MODIFY" from the drop-down box next to the rule you wish to modify, and then click the "Save Changes" button. The screen will refresh, and now show that rule with "DELETE" next to it. At the bottom of the screen will be a form to modify the rule; once you've made the changes you desire, click on "Save Changes" again. The old rule will be deleted, and the modifications you made will be put in its place. See below for a description of the modify form, which is the same as the form to add a new rule.

To re-arrange the order of the rules in the list, you'll use the "Priority" field next to each rule. If you notice, each rule has a priority that increases in increments of 2, starting with a priority of 1. The reason for this is so that you can move one rule to in-between two existing ones. For example, if you have 5 rules in the list, their priorities will be 1, 3, 5, 7 and 9. If you wish to move the last rule to in-between the second and third (whose priorities will be 3 and 5, respectively), then you would change the last rule's priority to '4'. When you click "Save Changes", the rules will be re-arranged so that the last one is now between the second and third. If you wish to make a rule the first one in the list, specify its priority at '0' and it will be placed at the top.

Why is the order important? Because the rules are applied from the first to the last, stopping at the first rule that matches (unless that rule states to continue processing after a match). This is handy if you wish to divide mails that have similar characteristics. For example, let's say you have two folders, one for mail from Bob, and one for mail about camping trips. If you have a rule that puts all mail from Bob into the folder "Bob", and Bob sends you a mail about an upcoming camping trip, that mail will also go into the "Bob" folder. So, by placing a rule *before* that one that checks for "Camping" in the subject, you can catch mails from Bob that have to do with camping trips, and put them in the camping folder. Any other mail from Bob will then go to the "Bob" folder. As a general rule, you want to have the most specific rules at the top of the list, and the least specific rules near the bottom.

NOTE:

You MUST activate the Sieve script before it will function. See below for how to do this.

Adding new rules

To add a new sieve rule, click the "Add Rule" link at the top of the page. This will bring up a form with the information required to setup a new filtering rule.

At the top of the form is the rule #, the priority at which this rule will be inserted and the status the rule will have when it's saved (see above for a description of the priority and status fields). Next is three checkable options that define how processing is handled:

• Continue checking other rules after applying this rule

  If checked, then even if the mail in question matches this rule, the system will continue on to the next rule in the list instead of the default action, which is to stop processing after the first match is found.

• Keep a copy in your inbox

  Will do just what it says: keep a copy of this mail in your inbox after performing whatever action is defined below on the mail.

• Use regular expressions

  Allows you to use powerful regexp specifications in the rule definition (for example, ".*(mortgage|refinance|free).*").

Next is the "IF" part of the rule. The drop down box lets you choose between "all of" or "any of"; for example, if you want to match a mail from Bob, or that has 'camping' in the subject, you'd select "Any of". But if you wanted to match a mail that has both, you'd select "All of".

The three text boxes after that are for matching text that is located in the From line, the To line, or the subject. Note that the "To" field will match the "To" header as well as "CC" headers.

After that is a field that lets you test against the size of the message, if it's less or greater than a certain number of KB.

The last line of the "IF" section lets you define your own header to test against. For example, if you wanted to write a rule that takes mail flagged as spam, you'd type "X-Spam-Flag" in the 'Field name' textbox, and "YES" in the contents part (without the quotes on both of those entries).

The next part of the rule is the action to take if the first part matches. The actions listed are:

• file into

  The drop-down box lets you choose what folder the mail will be filed into

• forward to

  Enter an address into the corresponding text box where you wish to have the mail forwarded

• reply with

  You can add an automated reply to send back to the sender to the text box here.

• reject

  You may type a rejection notice which will be sent back to the sender (this will generate a bounce message)

• discard

  Will silently throw the message away.

The last option is the most powerful, letting you define your own custom sieve script to perform as an action on the mail that matches this rule. Use this part with caution! More Sieve scripting information is in the article Sieve.

When you're done editing the rule, click on "Save Rule" to save it into your script.

NOTE:

You MUST activate the Sieve script before it will function. See below for how to do this.

Vacation messages

Click on "Set Vacation" to open the vacation message editor, and you'll see your current vacation message if you have one. To set a vacation message, click the "Yes" option at the top of the form, and type in the vacation message you wish to send to people who email you in the text box provided. The "Repeat days" box lets you set how many days have to pass between reminders to senders that you're on vacation.

If you set repeat days to 7, then someone could send you a mail daily and will only get the vacation message once per week. If you set it to 1, then they will get one vacation message per day, etc.

The last text box is for "vacation addresses"; here you enter the email addresses that are received in your inbox, and Sieve will only respond if the mail is To: or CC:'d to one of those addresses.

If you enter "user@astro.princeton.edu" and "user@princeton.edu", then if a mail comes in for either of those addresses, a vacation response will be sent - however, if mail comes in for "notme@princeton.edu", the vacation response will *not* be sent. This is a simple way to avoid sending vacation messages out to mailing lists, since a mailing list will generally not have your address in the To: or CC: field (but will instead have the mailing list's address there).

Once the form is filled out, click on "Save Changes" to send your changes to the server. As long as your sieve script is active, your vacation message will take effect immediately.

NOTE:

You MUST activate the Sieve script before it will function. See below for how to do this.

Managing scripts

You can have multiple scripts stored on the server, and select which one you wish to use whenever you like. The "Advanced Options" link - which is probably misnamed - contains the tools to do this. It also contains the most important and overlooked tool...

Activating a script

The first item in the "Advanced Options" page is the most important, and shouldn't even be hidden all the way in here; that's the item to turn *on* the script itself! Clicking on the "Yes" and then on "Save Changes" activates the current script that you're editing (the current script is always shown in the top line of the Websieve page, next to "Script:"; it is usually the 'default' one). If you don't activate the script, then it will not process your mail no matter what the other pages say about the rules.

Selecting a script

The next item lets you choose a new script to edit. By typing in a different name to this field and clicking "Save Changes", you will start editing a different script. If the script that you type into this field does not exist, you will start editing a blank one. You can save multiple scripts on the server, but only have one active at a time.

Saving a new script

The "Save to script name" field lets you save the current script under a different name; for example, if you want to make a copy of your script, and work on that copy instead of the currently active one. Type in the name and click "Save Changes" above.

Deleting a script

"Delete script name" will, as you probably guessed, delete the script that you type in to that field. Use with caution, if you don't have a backup copy of your rules they will be lost!

Advanced mode

The last option in the "Advanced Options" page is the option to turn on advanced mode. In advanced mode, instead of the simple "Add a rule" form seen when clicking on the "Add Rule" link, you get an empty text box. Here you can type raw sieve scripts in by hand. Note that once you switch to advanced mode, the basic mode functions will no longer work, and if you switch from advanced back to basic mode you will lose any changes you made while in advanced mode. Use with caution!

Setting ACLs

You should probably not touch this section unless you REALLY know what you're doing. Here you can set things so that another user can read, write, post, delete or append to your mail folders. In most cases, you probably don't want to do that, and it's possible to make it so that you can't even read your own mail anymore. Just Say No.

There is, however, a small item near the bottom of the page, that lets you create a new mailbox. While you can use this, you may find it easier to create folders in Pine or Squirrelmail, since you don't have to remember the exact syntax of how folders are named (ie, to create a 'camping' mailbox, the folder to create would be INBOX.camping)

Example Sieve scripts

Here's a couple quick examples to get you started, and so you get the idea of how Websieve works.

Tagged spam filtering

One example is to take all mail that is deemed "SPAM" by the SpamAssassin program, and file it into a mailbox called "SPAM" that you'll check now and then (just to make sure there's nothing legitimate in there). Here's how you do it.

1. Create the folder you'll save your junk mail into using whatever client you prefer.

   For this example, we'll assume the folder name is "SPAM".

2. Login to Websieve, and click on "Add Rule".
3. In the "New Rule" form, put the header X-Spam-Flag in the text box next to 'Field name', and put YES in for the contents
4. For the action, make sure that "File Into" is selected, and click on the drop-down box beside it. Select the folder you created at the beginning, in our example it will be "INBOX.SPAM".
5. Click on "Save Rule".

Now, make sure that the current script is active (see above).

That's it! All mail that contains the header "X-Spam-Flag: YES" will now be automatically filed into your "SPAM" folder.

Finer spam control

Here's another example which has to deal with spam. What if you decide that you don't want to see any messages that score a 2 or higher, but the X-Spam-Flag header isn't added unless the score is 3? You guessed it, you set the sieve rule based on a different header.

1. For the "field name", type in X-Spam-Level and for "contains" enter \\*\\* (two backslashes and a star, repeated twice).
2. Click on the "Use regular expressions" check box near the top of the form
3. Select the destination folder for the spam in the "file into" dialog.

Now if there's 2 or more stars in the X-Spam-Level header content, the mail will go into your spam folder automatically. As you may know from normal regular expression usage, star matches any number of the previous atom, so backslash star matches the actual star character (it escapes the meaning of * in a regexp). The double backslashes are needed because Sieve sees a backslash as a special character. So the first one escapes the second, and the second one escapes the star.

As a side note, be warned that the X-Spam-Level stars equal the rounded-up score that SpamAssassin assigns to the mail. So if it scores a 2.8, there will be three stars in the X-Spam-Level field. Keep this in mind while writing your filter rules.

Forwarding email

What if you want to forward all your mail somewhere? That's also simple to do.

1. Since most people want to forward everything, the conditions ("IF") section of the rule is simple - leave it blank!

   This will match every email that comes through.

2. Click on the radio button next to "Forward To" and type in the destination email address in the text box next to it.
3. Save the rule, and you're done.

If you want to block spammy messages first, then put a spam rule (as noted above) first in the list, and the forward rule later. This way, if the message wasn't discarded by the time it gets to the forwarding rule, it will be forwarded.