Sieve implementation for Dovecot v1.2

WARNING: This sieve implementation is still experimental since it needs thorough
testing. The current status of this project is outlined in the TODO file.

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

Sieve is computer language specifically tailored for internet message filtering.
This package compiles into a Sieve plugin for the Dovecot local delivery agent 
called Deliver. The plugin adds Sieve filtering support to the delivery process.  

Previously, the same functionality was provided by the cmusieve plugin for 
Dovecot. This old plugin is based on the CMU Sieve implementation included with
the Cyrus project. This new package provides a complete rewrite of the Sieve 
engine integrating it tightly with Dovecot. The actual execution of the Sieve 
actions is based on the original cmusieve plugin, but only on the code added to 
interface the CMU Sieve implementation to Dovocot. 

The main reason for rewriting the Sieve engine is to provide more reliable 
script execution and to provide better error messages to users and system 
administrators. Also, since the Sieve language evolves quickly with new language 
extensions published every year, the aim is to provide support for quickly 
extending the engine with new features. 

Features
--------

* Well-structured 3-stage compiler: uses dovecot framework and avoids using
  lex/yacc. Compiler doesn't bail on first error, but tries to find more. 
  Produced errors are aimed to be useful and generally user-comprehensible.  
  Things like 'Generic error' are a nuisance of the past. 
* Highly extendable with new sieve capabilities: This keeps the possibility of 
  plugins in mind. It should eventually provide the necessary infrastructure for 
  at least all currently known (proposed) extensions. The goal is to keep the
  extension interface provided by sieve engine as generic as possible, i.e. 
  without explicit support for specific extensions. New similar extensions can
  then use the same interface methods without changes to the sieve engine code.
  If an extension is not loaded using the require command, the compiler truly 
  does not know of its existance. 
* Supports almost all extensions provided by the original CMUSieve plugin 
  (currently except notify) and in addition to that it has support for the new 
  and very useful variables extension (see list below).
* This Sieve implementation is supported by the ManageSieve implementation for 
  Dovecot v1.2. Therefore, ManageSieve support can be added to Dovecot for the 
  new Sieve plugin just as for the cmusieve plugin.  

Implementation Status
---------------------

The the core of the language (as specified in RFC 5228) is fully supported. In 
addition to that, this Sieve implementation features various extensions. The 
following list outlines the implementation status of each supported extension:
	
  Base specification (RFC5228):
    fileinto: full
    reject: full (without Dovecot LMTP currently no refuse support)
    envelope: full
    encoded-character: full

  Other RFCs/drafts:
    subaddress: mostly full; not configurable
    comparator-i;ascii-numeric: full
    relational: full 
    copy: full
    regex: mostly full; but suboptimal and no UTF-8
    body: mostly full, but text body-transform implementation is simple
	      and some issues make it still not RFC incompliant. 
    include: mostly full; needs some more work (no external binaries)
    vacation: mostly full; no support for required References header and
	          and handling of utf-8 in headers is non-existant
    imapflags: full
    variables: mostly full; currently no support for future namespaces 

All implemented extensions are like the engine itself currently experimental. 
A status of 'full' does not necessarily mean that the extension is bug-free or 
even fully RFC-compliant.
 
Many more extensions to the language exist. Not all of these extensions are 
useful for Dovecot in particular, but many of them are. Currently, the author 
has taken notice of the following extensions:

    notify: planned, first mailto only 
		environment: planned
		date,index: planned
    editheader: planned, needs additional support from Dovecot though.
    mimeloop: planned

These extensions will be added as soon as the necessary infrastructure is 
available. Extensions already supported by cmusieve have priority, meaning that 
notify is next in line.

Compiling and Configuring
-------------------------

Refer to INSTALL file.

Using
-----

The main purpose of this package is to replace the existing cmusieve plugin that 
is currently available for Dovecot's deliver. With this respect it is currently 
not very different from the cmusieve plugin implementation. 

Unlike cmusieve, this sieve module logs runtime errors to <scriptfile>.log if 
it can and not <scriptfile>.err. It appends new timestamped log entries to the 
end of the logfile. If the log grows too large (currently > 10kB), the logfile 
is rotated to <scriptfile>.log.0 and <scriptfile>.log starts out empty again. 

The cmusieve plugin compiled the script into a file with an appended c, e.g. 
'test.sievec'. This new implementation recognizes scripts to have the .sieve 
extension. The binary is (by default) written to a file with extension .svbin. 
This means that the default .dovecot.sieve is compiled into .dovecot.svbin. 
Included scripts are currently always compiled into the main binary, meaning 
that no other files are written and no permission to do so is necessary for the 
global script directories. 

To test the sieve engine outside deliver it is useful to execute the binaries 
that exist in the src/sieve-bin/ directory of this package. After installation, 
these scripts are available in the dovecot lib directory. The following commands
are available:

--

sievec [-d] <sieve-file> <out-file>

Compiles the script and produces a sieve binary. However, when the -d option is
provided, a code dump is written to the output file. When the output file is '-'
the dump output is written to stdout (only if -d is specified). 

--

sieved <bin-file> [<dump-file>]

Reads a sieve binary and produces a code dump. The optional dump-file parameter
provides the means to specify a file to which the dump is to be written. 
Otherwise, the dump is printed to stdout. 

-- 

sieve-test [-r <recipient address>][-s <envelope sender>]
           [-m <mailbox>][-d <dump filename>][-c][-t] <scriptfile> <mailfile>

Reads mail message from the specified mailfile and executes the specified sieve 
script to produce a verdict. This prints a list of actions that would 
have been performed on this message.

Options:
  -r  envelope recipient address
  -s  envelope sender
  -m  the mailbox where the keep action should store
  -d  causes a dump of the generated code to be written to the specified
      file. Using - as filename causes the dump to be written to stdout
  -c  force compilation (ignore any existing binary)
  -t  enable trace simple debugging; prints all encountered byte code
      instructions on stdout. 

--

sieve-exec

Currently undocumented (will be merged with sieve-test).

--

Various example scripts are bundled in the directory 'examples'. 

Authors
-------

Refer to AUTHORS file.

Contact Info
------------

Stephan Bosch <stephan at rename-it dot nl>
IRC: Freenode, #dovecot, S[r]us

Please use the Dovecot mailing list <dovecot at dovecot.org> for questions about 
this package. You can post to the list without subscribing, the mail then waits 
in a moderator queue for a while. See http://dovecot.org/mailinglists.html