Compiling
---------

First of all you'll need to have pre-built Dovecot 1.2 sources available. It's 
also not a good idea to build the plugin against self-compiled Dovecot sources, 
but then actually use a prebuilt binary package of Dovecot. That might work if 
the Dovecot versions are the same, but it's not guaranteed. You can also use 
installed Dovecot headers to compile this package, but then command line tools 
like sievec and sieved will not be compiled. This is also true for the test 
suite. 

This package is compiled and configured as follows:

./configure --with-dovecot=../dovecot-1.2
make
sudo make install

The --with-dovecot parameter points to your Dovecot sources or, in case you are 
compiling against the headers, to the directory where the dovecot-config file is 
installed.

If you downloaded this package through Mercurial, you need to execute 
./autogen.sh first to build the automake/autoconf structure. This requires
autotools and libtool to be installed. 

Configuring
-----------

Configuration is currently mostly identical to the cmusieve module. However, the 
name of the module is 'sieve' and not 'cmusieve'. For a detailed description on 
installing the cmusieve plugin for deliver refer to the dovecot wiki:

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

The following options for the plugin section of the Dovecot config file are new
when compared to the old CMU Sieve:

  sieve_extensions = 

    Use this setting to specify which Sieve language extensions are available 
    to users. By default, all supported extensions are available, but some 
    system administrators may want to disable certain Sieve extensions. 

  sieve_before = 
  sieve_after =

    This Sieve implementation allows executing multiple Sieve scripts 
    sequentially. These two options are used to specify what scripts need to
    be executed before and after the user's script (as specified by the sieve
    option). These settings allow specifying only one path each. However, if 
    the path leads to a directory, all the Sieve scripts contained therein are 
    executed. The order of execution is determined by the file names, using 
    a normal 8bit per-character comparison.

    After one script terminates, the next script is 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;'. Keep in mind that `fileinto "INBOX"' is not 
    the same as a keep action in this context (only for the last script).

    Just as for executing a single script the normal way, this implementation 
    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.

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

  sieve_subaddress_sep = +

    This setting specifies what separator is used 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:

# ...

protocol lda {
  postmaster_address = postmaster@example.com

  mail_plugins = sieve

  # ... 
}

plugin {
   # The user's own script
   sieve = ~/.dovecot.sieve

   # Global script if user has none
   #   If this is omitted, Sieve processing is skipped when the user has no 
   #   script of his own. This includes multiscript
   sieve_global_path = /etc/dovecot/sieve.global/default.sieve

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

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

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.