Dovecot Sieve plugin
====================

 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. Vacation auto-reply
     9. Example scripts
         1. SpamAssassin tagged mail filtering
         2. Mail filtering by various headers
         3. Vacation auto-reply
         4. Include scripts
     10. Migration from Procmail

Getting the sources
-------------------

The Sieve plugin is distributed in a separate package. You can get it from
Dovecot's download page [http://www.dovecot.org/download.html].

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> [LDA.txt] 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
------------------------------

There are two choices:

 1. 'sieve' variable can contain the script path (absolute or relative to the
    user's home directory).
 2. If 'sieve' isn't found, '.dovecot.sieve' is used under home directory.

Usually you want to use '~/.dovecot.sieve', which means that your <userdb>
[UserDatabase.txt] lookup must return a home directory. See
<VirtualUsers#homedirs> [VirtualUsers.txt].

'sieve' variable can be set in two ways:

 1. Return it from userdb <extra fields> [UserDatabase.ExtraFields.txt].
 2. Use a template in plugin section.

The template can be set like:

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

A relative path (or just a filename) will be interpreted 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:

 * fileinto
 * reject
 * envelope
 * vacation
 * imapflags
 * notify
 * regex
 * subaddress
 * relational
 * copy (v1.1 only)
 * body (v1.1 only)
 * include (v1.1 only)

You can find more information about these at the Sieve Mail Filtering Language
Charter [http://www.ietf.org/html.charters/sieve-charter.html].

NB: Sieve doesn't support running external programs.

ManageSieve server
------------------

 * Python implementation: http://woozle.org/~neale/src/pysieved/
 * Dovecot patch: http://dovecot.org/list/dovecot/2007-March/021130.html

The Dovecot patch will most likely be added to Dovecot v1.2 version.

Vacation auto-reply
-------------------

The vacation replies are sent to the envelope sender. Currently this is taken
from the Return-Path: header in the message.

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:

 * Auto-Submitted: header exists with any value except "no"
 * Precedence: header exists with value "junk", "bulk" or "list"
 * The envelope sender
    * begins with "MAILER-DAEMON" (case-insensitive)
    * begins with "LISTSERV" (case-insensitive)
    * begins with "majordomo" (case-insensitive)
    * begins with "owner-" (case-sensitive)
    * contains the string "-request" anywhere within it (case-sensitive)
 * The envelope sender and envelope recipient are the same
 * The envelope recipient is not found in the message To:, Cc: or Bcc: fields.

The envelope sender is taken from a Return-Path: header in the message. The
envelope recipient is taken from the recipient user (-d parameter with virtual
user setup). 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/SieveExamples.

SpamAssassin tagged mail filtering
----------------------------------

Redirect <SpamAssassin.txt> tagged mails into mbox folder "spam":

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

Discard <SpamAssassin.txt> tagged mails:

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

Mail filtering by various headers
---------------------------------

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

 * ---%<----------------------------------------------------------------------
   require "fileinto";
   if address :is "to" "dovecot@dovecot.org" {
     fileinto "Dovecot-list";
   } elsif address :is "Return-path" "owner-cipe-l@inka.de" {
     fileinto "lists.cipe";
   } elsif anyof (header :contains "X-listname" "lugog@cip.rz.fh-offenburg.de",
                  header :contains "List-Id" "Linux User Group Offenburg") {
     fileinto "ml.lugog";
   } else {
     # The rest goes into INBOX
     # default is "implicit keep", we do it explicitly here
     keep;
   }
   ---%<----------------------------------------------------------------------
   "anyof" means logical OR, "allof" is AND.

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

 * ---%<----------------------------------------------------------------------
   if header :contains "subject" ["order", "buy"] {
     redirect "orders@company.dom";
   }
   ---%<----------------------------------------------------------------------

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 allowed recipient addresses from auto reply should be sent.
  :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> [UserDatabase.ExtraFields.txt], 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 

(This file was created from the wiki on 2007-10-31 04:42)
