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. 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 [http://www.dovecot.org/download.html].

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> [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
------------------------------

By default Dovecot looks for user's Sieve script from '.dovecot.sieve' file in
user's home directory. This requires that the<home directory>
[VirtualUsers.txt] 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>
    [UserDatabase.ExtraFields.txt].

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

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:

 * 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
------------------

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 Manage ''Sieve
protocol. Two alternatives are available for Dovecot:

 * Python implementation: http://woozle.org/~neale/src/pysieved/
 * <Dovecot native ManageSieve implementation> [ManageSieve.txt]

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:

 * v1.0:
    * Envelope sender: Return-Path: header in the message.
    * Envelope recipient: -d parameter to deliver. If -d isn't given
      (delivering to system users), the $USER environment is used.
 * v1.1:
    * Envelope sender: -f parameter to deliver if given, otherwise Return-Path:
      header in the message.
    * Envelope recipient: -a parameter to deliver if given, otherwise -d
      parameter to deliver. If neither is given (delivering to system users),
      the $USER environment is used.

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:

 * 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.

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 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> [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 2008-06-20 04:42)
