CMU Sieve plugin
================

Introduction
------------

The CMU Sieve plugin v1.0.x code is taken from Cyrus IMAP v2.2.12. The CMU
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 these
plugins.

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

You can get the CMUSieve plugin from Dovecot's download page
[http://www.dovecot.org/download.html].

Alternatively, you can obtain the latest versions from Mercurial repositories:

 * For Dovecot v1.0: 'http://hg.dovecot.org/dovecot-sieve-1.0'
 * For Dovecot v1.1+: 'http://hg.dovecot.org/dovecot-sieve-1.1'

In Ubuntu, starting from version 7.10 Gutsy, the CMU Sieve plugin 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". This is also true for Debian Etch.

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. For
    example:

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

 2. Compiled Dovecot sources' root directory. For example:
    ---%<---------------------------------------------------------------------
    ./configure --with-dovecot=../dovecot-1.1.0/
    make
    make install
    ---%<---------------------------------------------------------------------

If you downloaded the sources using Mercurial, you will need to execute
'./autogen.sh' first to build the automake structure in your source tree. This
process requires autotools and libtool to be installed.

Binaries for command line tools like 'sievec' and 'sieved' are built only if
you use method 2, because they need to link Dovecot's .a libraries, which can
only be found from Dovecot's source tree (make install doesn't install them).
These two tools can be used to compile and decompile Sieve scripts. You
probably do not need these, except when using the Python <ManageSieve.txt>
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 Sieve
plugin in your 'dovecot.conf':

---%<-------------------------------------------------------------------------
protocol lda {
  # Support for dynamically loadable plugins. mail_plugins is a space separated
  # list of plugins to load.
  mail_plugins = cmusieve # ... other plugins like quota
}

plugin {
  # Path to a global sieve script file, which gets executed ONLY if
  # user's private Sieve script doesn't exist. (e.g.
/etc/dovecot/default.sieve)
  # (v1.0.1 and older called this setting "global_script_path")
  #sieve_global_path =

  # Directory for :global include scripts (for v1.1 include extension)
  #sieve_global_dir =
}
---%<-------------------------------------------------------------------------

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.

For CMU Sieve, 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 an ".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 the 'sievec' tool.

How to stop using sieve
-----------------------

A user may want to stop using his/her own sieve (and maybe return to using
global sieve script). Or the administrator may want to disable global sieve.

To stop using sieve, both the .sieve source file and the compiled .sieve *c*
file must be deleted (or renamed).

(This file was created from the wiki on 2011-05-11 04:42)
