For the most up-to-date information you are referred to the Dovecot wiki:

http://wiki.dovecot.org/LDA/Sieve/Dovecot

Compiling
---------

Compilation is identical among the CMUSieve and the new Sieve plugin. 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.2.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.

Dovecot Sieve includes several command line tools to perform tasks such as
compile, verify and debug Sieve scripts (refer to the README file for more
information). These 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).

Basic Configuration
-------------------

To use Sieve, you will first need to make sure you are using Dovecot's deliver
for delivering 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 = sieve # ... other plugins like quota
}

The sieve plugin recognizes the following configuration options in the plugin
section of the config file (default values are shown if applicable):

sieve = ~/.dovecot.sieve
  The path to the user's main active script. 

sieve_global_path
  A path to a global sieve script file, which gets executed ONLY if user's 
  private Sieve script doesn't exist, e.g. /var/lib/dovecot/default.sieve. Be 
  sure to pre-compile this script manually using the sievec command line tool,
  as explained in the README file. 

sieve_global_dir =
  Directory for :global include scripts for the include extension. 

sieve_dir = ~/
  Directory for :personal include scripts for the include extension. 

sieve_extensions =
  Which Sieve language extensions are available to users. By default, all 
  supported extensions are available, except for deprecated extensions or those 
  that are still under development. Some system administrators may want to 
  disable certain Sieve extensions or enable those that are not available by 
  default. Supported extensions are listed on this page. This setting can use 
  '+' and '-' to specify differences relative to the default. For example 
  `sieve_extensions = +imapflags' will enable the deprecated imapflags extension
  in addition to all extensions enabled by default. 

sieve_subaddress_sep = +
  The separator that is expected between the :user and :detail address parts 
  introduced by the subaddress extension. This may also be a sequence of
  characters (e.g. '--'). The current implementation looks for the separator
  from the left of the localpart and uses the first one encountered. The :user
  part is left of the separator and the :detail part is right.

For example:

plugin {
...
   # The location of the user's active script:
   sieve = ~/.dovecot.sieve

   # If the user has no personal active script (i.e. if the file 
   # indicated in sieve= does not exist), use this one:
   sieve_global_path = /var/lib/dovecot/sieve/default.sieve

   # The include extension fetches the :personal scripts from this 
   # directory. When ManageSieve is used, this is also where scripts 
   # are uploaded.
   sieve_dir = ~/sieve

   # The include extension fetches the :global scripts from this 
   # directory.
   sieve_global_dir = /var/lib/dovecot/sieve/global/
}

Configurable Limits
-------------------

sieve_max_script_size = 1M
  The maximum size of a Sieve script. The compiler will refuse to compile any
  script larger than this limit. 

sieve_max_actions = 32
  The maximum number of actions that can be performed during a single script
  execution.

sieve_max_redirects = 4
  The maximum number of redirect actions that can be performed during a single
  script execution.

A value of 0 for these settings means that the limit is not enforced. 

Per-user Sieve script location
------------------------------

By default, the Dovecot Sieve plugin looks for the user's Sieve script file in
the user's home directory (~/.dovecot.sieve). This requires that the home 
directory is set for the user.

If you want to store the script elsewhere, you can override the default using 
the sieve setting, which specifies the path to the user's script file. This can 
be done in two ways:

 1. Define the sieve setting in the plugin section of dovecot.conf.
 2. Return sieve extra field from userdb extra fields. 

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

plugin {
...

 sieve = /var/sieve-scripts/%u.sieve
}

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

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

Executing Multiple Scripts Sequentially
---------------------------------------

The Dovecot Sieve plugin allows executing multiple Sieve scripts sequentially.
The extra scripts can be executed before and after the user's private script. 
For example, this allows executing global Sieve policies before the user's 
script. This is not possible using the sieve_global_path setting, because that
is only used when the user's private script does not exist. The following 
settings in the plugin section of the Dovecot config file control the execution
sequence:

sieve_before =
  Path to a script file or a directory containing script files that need to be
  executed before the user's script. If the path points to a directory, all the
  Sieve scripts contained therein (with the proper .sieve extension) are
  executed. The order of execution is determined by the file names, using a
  normal 8bit per-character comparison. 

sieve_after =
  Identical to sieve_before, only the specified scripts are executed after the
  user's script (only when keep is still in effect!). 

The script execution ends when the currently executing script in the sequence
does not yield a "keep" result: when the script terminates, the next script is 
only executed if an implicit or explicit "keep" is in effect. Thus, to end all
script execution, a script must not execute keep and it must cancel the 
implicit keep, e.g. by executing "discard; stop;". This means that the command 
"keep;" has different semantics when used in a sequence of scripts. For normal
Sieve execution, "keep;" is equivalent to "fileinto "INBOX";", because both 
cause the message to be stored in INBOX. However, in sequential script 
execution, it only controls whether the next script is executed. Storing the 
message into INBOX (the default folder) is not done until the last script in 
the sequence executes (implicit) keep. To force storing the message into INBOX
earlier in the sequence, the fileinto command can be used (with ":copy" or 
together with "keep;").

Apart from the keep action, all actions triggered in a script in the sequence
are executed before continuing to the next script. This means that when a script
in the sequence encounters an error, actions from earlier executed scripts are
not affected. The sequence is broken however, meaning that the script execution
of the offending script is aborted and no further scripts are executed. An
implicit keep is executed in stead.

Just as for executing a single script the normal way, the Dovecot Sieve plugin
takes care never to duplicate deliveries, forwards or responses. When vacation
actions are executed multiple times in different scripts, the usual error is not
triggered: the subsequent duplicate vacation actions are simply discarded.

For example:

plugin {
...
   # Scripts executed before the user's script.
   #   E.g. handling messages marked as dangerous
   sieve_before = /var/lib/dovecot/sieve/discard-virusses.sieve

   # Scripts executed after the user's script (if keep is still in effect)
   #   E.g. default mail filing rules.
   sieve_after = /var/lib/dovecot/sieve/after.d/
}

IMPORTANT: Be sure to manually pre-compile the scripts specified by sieve_before 
and sieve_after using the sievec tool, as explained in the README file.

Migration from CMUSieve
-----------------------

For the most part, migration from CMUSieve to the new Sieve plugin is just a
matter of changing the used plugin name from cmusieve to sieve in the
mail_plugins option in the protocol lda section of the config file (as explained
above). However, there are a few important differences:

 * The imapflags extension is now called imap4flags. The CMUSieve implementation
   is based on an old draft specification that is not completely compatible.
   Particularly, the mark and unmark commands were removed from the new
   specification. For backwards compatibility, support for the old imapflags
   extension can be enabled using the sieve_extensions setting (as explained
   above). This is disabled by default.
 
 * The notify extension is now called enotify. Sieve scripts need to be adjusted
   to incorporate this change: unlike imapflags, no backwards compatibility is
   provided currently.
 
 * The include extension now requires your script file names to end with 
   ".sieve" : include :personal "myscript"; won't work unless you rename
   "myscript" to "myscript.sieve" 

Test Suite
----------

This package includes a test suite to verify the basic processing of the Sieve
interpreter on your particular platform. Note that the test suite is not
available when this package is compiled against the Dovecot headers only. The
test suite executes a list of test cases and halts when one of them fails. If it
executes all test cases successfully, the test suite finishes. You can execute
the test suite using `make test`.

A failing test case is always a bug and a report is greatly appreciated.

