Dovecot Sieve plugin

Contents

  1. Dovecot Sieve plugin
    1. Getting the sources
    2. Compiling
    3. Configuring
    4. Per-user Sieve script location
    5. Script compiling and errors
    6. Features
    7. ManageSieve server
    8. Validate your script
    9. v1.0 namespaces and fileinto
    10. Vacation auto-reply
    11. Example scripts
      1. SpamAssassin tagged mail filtering
      2. Mail filtering by various headers
      3. Vacation auto-reply
      4. Include scripts
    12. Migration from Procmail

Getting the sources

The Sieve plugin is distributed in a separate package. You can get it from Dovecot's download page.

In Ubuntu, starting from version 7.10 Gutsy, sieve plug-in already comes with Dovecot regular install. In this case you do not have to download additional packages. Simply skip "Compiling" section and proceed to "Configuring".

Compiling

Use --with-dovecot=<path> to point to dovecot-config file's directory. There are two possibilities where this could exist:

  1. If you configured Dovecot with --enable-header-install, you'll have dovecot-config installed in $prefix/lib/dovecot/ directory.

  2. Compiled Dovecot sources' root directory.

So for example: 

./configure --with-dovecot=/usr/local/lib/dovecot
make
sudo make install

sievec and sieved binaries are built only if you use method 2, because they need to link with Dovecot's libraries. They can be used to compile and decompile Sieve scripts. You probably don't need these, except when using the Python managesieve server (it uses sievec to verify uploaded scripts).

Configuring

First, you'll need to make sure you're using Dovecot's deliver to deliver incoming mail to users' mailboxes. Then you need to enable the cmusieve plugin: 

protocol lda {
..
  # If there is no user-specific Sieve-script, global Sieve script is
  # executed if set. (v1.0.1 and older used "global_script_path")
  #sieve_global_path =
  # Support for dynamically loadable plugins. mail_plugins is a space separated
  # list of plugins to load.
  mail_plugins = cmusieve # ... other plugins like quota
}

In this context script path refers to a filename, not just a directory.

Per-user Sieve script location

By default Dovecot looks for user's Sieve script from .dovecot.sieve file in user's home directory. This requires that the home directory is set for the user.

If you want to store the script elsewhere, you can override the default by returning sieve setting containing path to the file. This can be done in two ways:

  1. Define sieve setting in plugin section of dovecot.conf.

  2. Return sieve extra field from userdb extra fields.

For example to create a Sieve script file named <username>.sieve in /var/sieve-scripts, use: 

plugin {
 # NOTE: %variable expansion works only with Dovecot v1.0.2+
 sieve = /var/sieve-scripts/%u.sieve
}

You may use templates like %u in the example. See all variables.

A relative path (or just a filename) will be interpreted to point under the user's home directory.

Script compiling and errors

When the Sieve script is executed for the first time (or after it has been changed), it's compiled into into a binary form. The binary is stored by appending "c" letter after the script name (e.g. ".dovecot.sievec"). If there are errors in the script, the error messages are stored into ".err" file (e.g. ".dovecot.sieve.err"). This means that deliver must have write access to the directory where the script is stored.

Global scripts have the same problem. Either allow deliver to write to the global script's directory, or compile the script before deliver sees it. Scripts can be compiled using sievec binary.

Features

The Sieve plugin v1.0.x code is taken from Cyrus IMAP v2.2.12. The Sieve plugin v1.1.x code is taken from Cyrus IMAP v2.3.8. Whatever information you can find about those versions of Cyrus Sieve, it should also apply to Dovecot.

The supported Sieve features are:

You can find more information about these at the Sieve Mail Filtering Language Charter.

NB: Sieve doesn't support running external programs.

ManageSieve server

To give users the ability to upload their own Sieve scripts to your server, i.e. without the need for shell or FTP access, you can use the ManageSieve protocol. Two alternatives are available for Dovecot:

Validate your script

Use the following page to validate your sieve rules: http://libsieve-php.sourceforge.net/

v1.0 namespaces and fileinto

Dovecot v1.0's deliver doesn't support namespaces, so if you have a namespace prefix configured for IMAP, you must not use it with fileinto command. This also means that delivering mails to multiple namespaces isn't possible.

v1.1's deliver supports namespaces and the namespace prefixes must be used with fileinto commands.

Vacation auto-reply

Vacation uses envelope sender and envelope recipient. They're taken from:

The vacation replies are sent to the envelope sender.

List of autoreplied senders is stored in .dovecot.lda-dupes file in user's home directory. When you're testing the vacation feature, it's easy to forget that the reply is sent only once in the number of configured days. If you've problems getting the vacation reply, try deleting this file. If that didn't help, make sure the problem isn't related to sending mails in general by trying the "reject" Sieve command.

The automatic replies aren't sent if any of the following is true:

A bare username without a domain gets canonicalised by the libsieve code to "<username>@unspecified-domain", which means it is highly unlikely to pass the last two tests in the list above.

Example scripts

Below are some simple Sieve code examples, more can be found from http://libsieve.sourceforge.net/script1.php and http://wiki.fastmail.fm/index.php?title=SieveExamples.

SpamAssassin tagged mail filtering

Redirect SpamAssassin tagged mails into mbox folder "spam": 

require "fileinto";
if exists "X-Spam-Flag" {
  fileinto "spam";
}

Discard SpamAssassin tagged mails: 

if exists "X-Spam-Flag" {
  discard;
}

Mail filtering by various headers

Use if/elsif/else to store messages into various folders/subfolders:

Forward mails with "order" or "buy" in their subject to another address:

Message-ID and recipient of forwarded message are stored in a .dovecot.lda-dupes at users home directory to prevent mail loops.

Vacation auto-reply

require ["fileinto", "vacation"];
# Move spam to spam folder
if exists "X-Spam-Flag" {
  fileinto "spam";
  # Stop here so that we do not reply on spams
  stop;
}
vacation
  # Reply at most once a day to a same sender
  :days 1
  :subject "Out of office reply"
  # List of recipient addresses which are included in the auto replying.
  # If a mail's recipient is not on this list, no vacation reply is sent for it.
  :addresses ["j.doe@company.dom", "john.doe@company.dom"]
"I'm out of office, please contact Joan Doe instead.
Best regards
John Doe";

Include scripts

With v1.1 it's possible to include other Sieve scripts in your script: 

require ["include"];
include :global "global-spam.sieve";
include :personal "my-own-spam.sieve";

If you want to use global scripts, you'll need to set up the global script directory: 

protocol lda {
  # ..
  sieve_global_dir = /etc/dovecot/sieve/
}

Personal scripts are looked up from sieve_dir if it's returned in userdb extra fields, or home directory if not. If neither is known, the include fails.

It's not currently possible to use subdirectories for the scripts. Having a '/' character in the script name always fails the include. This is just an extra check to avoid potential problems with including scripts within mail directories.

Migration from Procmail

There exists a script which attempts to translate simple Procmail rules into Sieve rules: http://www.earth.ox.ac.uk/~steve/sieve/procmail2sieve.pl

Here's the original post announcing it: http://dovecot.org/list/dovecot/2007-March/020895.html

LDA/Sieve (last edited 2008-06-26 09:13:56 by gaffer)