INSTALL

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
with respect 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.

  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, but 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.

  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.
   sieve_global_path = /etc/dovecot/sieve.global/default.sieve

   # E.g. handling messages marked as dangerous
   sieve_before = /etc/dovecot/sieve.global/discard-virusses.sieve

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