INSTALL

Compiling
=========

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. 

Subsequently, the package needs to be configured using the configure script.
Pigeonhole can either be built against installed Dovecot v2.0 development 
headers and libraties or against a pre-built Dovecot v2.0 source tree. Use 
--with-dovecot=<path> to point to dovecot-config file's directory. There are two
possibilities where this could exist:

  1. Dovecot's library directory when compiling against a Dovecot installation:

     If you configured Dovecot with --enable-header-install, you'll have 
     dovecot-config installed in the $prefix/lib/dovecot/ directory. Pigeonhole
     is then for example configured as follows:

     ./configure --with-dovecot=/usr/local/lib/dovecot

  2. The root directory of a built Dovecot source tree:

     The compilation of the Dovecot sources will produce the dovecot-config file
     in the root of the source tree. Pigeonhole is then for example configured
     as follows:

     ./configure --with-dovecot=../dovecot-2.0/

The following additional parameters are of interest for the configuration of the
Pigeonhole build:

  --with-managesieve=yes
    Controls whether the ManageSieve is compiled and installed. ManageSieve is
    compiled by default.

  --enable-header-install=no
    Controls whether Pigeonhole will install development headers for building
    external plugins. The default is not to install development headers.

  --with-unfinished-features=no
	  Controls whether unfinished features and extensions are built. Enabling this
    will enable the compilation of code that is considered unfinished and highly
    experimental and may therefore introduce bugs and unexpected behavior. 
    In fact, it may not compile at all. Enable this only when you are eager to
    test some of the new development functionality.

After the package is successfully configured, you can compile and install the 
package.

make
sudo make install

Configuration
=============

The Pigeonhole package provides the following items:

  - The Sieve plugin for Dovecot's Local Delivery Agent (LDA): This facilitates 
    the actual Sieve filtering upon delivery.

  - The ManageSieve Service: This implements the ManageSieve protocol through
    which users can remotely manage Sieve scripts on the server. 

The functionality of these items is described in more detail in the README file. 
In this file and in this section their configuration is described. Example
configuration files are provided in the doc/example-config directory of this
package. 

Sieve Plugin - Basic Configuration
----------------------------------

To use Sieve, you will first need to make sure you are using Dovecot's LDA
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. 

recipient_delimiter = +
  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. This setting is
  also used by Dovecot's LMTP service.

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/
}

Sieve Plugin - 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. 

Sieve Plugin - 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.

Sieve Plugin - 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.

Sieve Plugin - Migration from CMUSieve
--------------------------------------

For the most part, migration from CMUSieve to the Pigeonhole 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"

ManageSieve Service - Basic Configuration
-----------------------------------------

IMPORTANT:

  If you have used the Sieve plugin without ManageSieve before and you have 
  .dovecot.sieve files in user directories, you are advised to make a backup
  before installing ManageSieve. Although the ManageSieve service takes care to
  move these files to the Sieve directory before it is substituted with a 
  symbolic link, this is not a very well tested operation, meaning that there is
  a slim possibility that existing Sieve scripts get lost.

Just like all other binaries that Dovecot uses, the managesieve and 
managesieve-login binaries are installed during make install.

There are two things to have be done to activate the ManageSieve support in
Dovecot:

  - The first step is to add `managesieve' to the protocols= configuration line in 
    your dovecot.conf.

  - The next step is specifying an additional service type for the ManageSieve
    service. This could be done in Dovecot's conf.d/master.conf or you can use 
    the managesieve.conf file from the doc/example-config/conf.d directory of
    this package. 

    For example:

    service managesieve-login {
      inet_listener {
        port = 4190
      }
    }

Because the implementation of the ManageSieve daemon is largely based on the
original IMAP implementation, it is very similar in terms of configuration. The 
following settings can be configured in the 'protocol managesieve' section:

managesieve_max_line_length = 65536
  The maximum ManageSieve command line length in bytes. This setting is directly
  borrowed from IMAP. But, since long command lines are very unlikely with 
  ManageSieve, changing this will not be very useful.

managesieve_implementation_string = Dovecot
  To fool ManageSieve clients that are focused on CMU's timesieved you can 
  specify the IMPLEMENTATION capability that the Dovecot reports to clients 
  (e.g. 'Cyrus timsieved v2.2.13').

managesieve_max_compile_errors = 5
	The maximum number of compile errors that are returned to the client upon 
  script upload or script verification.

managesieve_sieve_capability =
	The SIEVE capability reported by the ManageSieve service before 
  authentication.

Additionally, the ManageSieve service uses the following settings from the
plugin section of the config file. These settings are the ones used by the Sieve
plugin.

sieve_dir = ~/sieve
  This specifies the path to the directory where the uploaded scripts are 
  stored. Scripts are stored as separate files with extension '.sieve'. All 
  other files are ignored when scripts are listed by a ManageSieve client.

sieve = ~/.dovecot.sieve
  Specifies the location of the symbolic link pointing to the active script in
  the Sieve storage directory. If a regular file exists at this location, it is
  moved to the sieve_dir location before the symbolic link is installed. It is
  renamed to dovecot.orig.sieve and therefore listed as `dovecot.orig' by a
  ManageSieve client.

Scripts are stored in a special directory at the location specified by the
sieve_dir setting. The active Sieve script is managed as a symbolic link 
pointing to the active script in the script directory. The location of this
symlink is specified with the 'sieve' setting. The default location is
~/.dovecot.sieve. Note that if a file starting with '.' is placed inside a
Maildir, it will be recognized as a folder, so try to avoid that.

A storage location specified by 'sieve_dir' is always generated automatically if 
it does not exist (as far as the system permits the user to do so; no root 
privileges are used). This is similar to the behavior of the mail daemons. 

The following provides an example configuration for Sieve and ManageSieve. 
Only sections and settings relevant to ManageSieve are shown. Refer to 
managesieve.conf in the doc/example-config/conf.d directory for a full example 
with comments, but don't forget to configure Sieve and add sieve to the 
'protocols = ...' setting if you use it.

# *** conf.d/managesieve.conf ***

service managesieve-login {
  inet_listener {
    # Bind the daemon only to the specified address(es)
    # (default: *, ::)
    address = 127.0.0.1
    # Specify an alternative port the daemon must listen on
    # (default: 4190)
    port = 2000
  }
}

protocol managesieve {
  managesieve_sieve_capability = fileinto reject
}

# ***  conf.d/sieve.conf ***

plugin {
  sieve=~/.dovecot.sieve
  sieve_dir=~/sieve
}

# *** dovecot.conf ***

# .... (other config items)

# Start imap, pop3, lmtp and managesieve services
protocols = imap pop3 lmtp managesieve

# .... (other config items)

ManageSieve Service - Quota Support
-----------------------------------

By default, users can manage an unlimited number of Sieve scripts on the server
through ManageSieve. However, ManageSieve can be configured to enforce limits on
the number of personal Sieve scripts per user and/or the amount of disk storage
used by these scripts. The maximum size of individual uploaded scripts is
dictated by the configuration of the Sieve plugin. The limits are configured in
the plugin section of the Dovecot configuration as follows:

sieve_max_script_size = 1M
  The maximum size of a Sieve script.

sieve_quota_max_scripts = 0
  The maximum number of personal Sieve scripts a single user can have.

sieve_quota_max_storage = 0
  The maximum amount of disk storage a single user's scripts may occupy.

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

ManageSieve Service - Proxying
------------------------------

Like Dovecot's imapd, the ManageSieve login daemon supports proxying to multiple
backend servers. Although the underlying code is copied from the imapd sources
for the most part, it has some ManageSieve-specifics that have not seen much
testing.

The proxy configuration wiki page for POP3 and IMAP should apply to ManageSieve
as well:

http://wiki.dovecot.org/PasswordDatabase/ExtraFields/Proxy

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.