path: root/pigeonhole/INSTALL

Compiling
=========

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.

If you installed Dovecot from sources, Pigeonhole's configure script should be
able to find the installed dovecot-config automatically:

./configure
make
sudo make install

If your system uses a $prefix different than the default /usr/local, the
configure script can still find the installed dovecot-config automatically when
supplied with the proper --prefix argument:

./configure --prefix=/usr
make
sudo make install

If this doesn't work, you can use --with-dovecot=<path> configure option, where
the path points to a directory containing dovecot-config file. This can point to
an installed file:

./configure --with-dovecot=/usr/local/lib/dovecot
make
sudo make install

or to a Dovecot source directory that is already compiled:

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

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

 --with-managesieve=yes
   Controls whether Pigeonhole ManageSieve is compiled and installed, which is
   the default.

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

 --with-ldap=no
   Controls wether Sieve LDAP support is built. This allows retrieving Sieve
   scripts from an LDAP database. When set to `yes', support is built in. When
   set to `plugin', LDAP support is compiled into a Sieve plugin called
   `sieve_storage_ldap'.

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

The Pigeonhole package provides the following items:

  - The Sieve interpreter 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 Interpreter - Script Locations
------------------------------------

The Sieve interpreter can retrieve Sieve scripts from several types of
locations. The default `file' location type is a local filesystem path pointing
to a Sieve script file or a directory containing multiple Sieve script files.
More complex setups can use other location types such as `ldap' or `dict' to
fetch Sieve scripts from remote databases.

All settings that specify the location of one ore more Sieve scripts accept the
following syntax:

location = [<type>:]path[;<option>[=<value>][;...]]

The following script location types are implemented by default:

  file  - The location path is a file system path pointing to the script file
          or a directory containing script files with names structured as
          `<script-name>.sieve'. Read doc/locations/file.txt for more
          information and examples.

  dict  - The location path is a Dovecot dict uri. Read doc/locations/dict.txt
          for more information and examples.

  ldap  - LDAP database lookup. The location path is a configuration file with
          LDAP options. Read doc/locations/ldap.txt for more information
          and examples.

If the type prefix is omitted, the script location type is 'file' and the 
location is interpreted as a local filesystem path pointing to a Sieve script
file or directory.

The following options are defined for all location types:

  name=<script-name>
    Set the name of the Sieve script that this location points to. If the name
    of the Sieve script is not contained in the location path and the
    location of a single script is specified, this option is required
    (e.g. for dict locations that must point to a particular script).
    If the name of the script is contained in the location path, the value of
    the name option overrides the name retrieved from the location. If the Sieve
    interpreter explicitly queries for a specific name (e.g. to let the Sieve
    "include" extension retrieve a script from the sieve_global= location),
    this option has no effect.

  bindir=<dirpath>
    Points to the directory where the compiled binaries for this script location
    are stored. This directory is created automatically if possible. If this
    option is omitted, the behavior depends on the location type. For `file'
    type locations, the binary is then stored in the same directory as where the
    script file was found if possible. For `dict' type locations, the binary is
    not stored at all in that case. Don't specify the same directory for
    different script locations, as this will result in undefined behavior.
    Multiple mail users can share a single script directory if the script
    location is the same and all users share the same system credentials (uid,
    gid).

Sieve Interpreter - Basic Configuration
---------------------------------------

To use Sieve, you will first need to make sure you are using Dovecot LDA
or Dovecot LMTP for delivering incoming mail to users' mailboxes. Then, you need
to enable the Sieve interpreter plugin for LDA/LMTP in your dovecot.conf:

protocol lda {
..
  mail_plugins = sieve # ... other plugins like quota
}

protocol lmtp {
..
  mail_plugins = sieve # ... other plugins like quota
}

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

 sieve = file:~/sieve;active=~/.dovecot.sieve
   The location of the user's main Sieve script or script storage. The LDA
   Sieve plugin uses this to find the active script for Sieve filtering at
   delivery. The "include" extension uses this location for retrieving
   :personal" scripts.

   This location is also where the ManageSieve service will store the user's
   scripts, if supported by the location type. For the 'file' location type, the
   location will then be the path to the storage directory for all the user's
   personal Sieve scripts. ManageSieve maintains a symbolic link pointing to
   the currently active script (the script executed at delivery). The location
   of this symbolic link can be configured using the `;active=<path>' option.

 sieve_default =
   The location of the default personal sieve script file, which gets executed
   ONLY if user's private Sieve script does not exist, e.g.
   /var/lib/dovecot/default.sieve. This is usually a global script, so be sure
   to pre-compile this script manually using the sievec command line tool, as
   explained in the README file. This setting used to be called
   `sieve_global_path', but that name is now deprecated.

 sieve_default_name = 
   The name by which the default Sieve script is visible to ManageSieve
   clients. Normally, it is not visible at all. See "Visible Default Script"
   section below for more information.

 sieve_global =
   Location for :global include scripts for the Sieve include extension. This
   setting used to be called `sieve_global_dir', but that name is now
   deprecated.

 sieve_discard =
   The location of a Sieve script that is run for any message that is about to
   be discarded; i.e., it is not delivered anywhere by the normal Sieve
   execution. This only happens when the "implicit keep" is canceled, by e.g.
   the "discard" action, and no actions that deliver the message are executed.
   This "discard script" can prevent discarding the message, by executing
   alternative actions. If the discard script does nothing, the message is still
   discarded as it would be when no discard script is configured.

 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. 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 were already
   enabled by default.

 sieve_global_extensions =
   Which Sieve language extensions are ONLY avalable in global scripts. This can
   be used to restrict the use of certain Sieve extensions to administrator
   control, for instance when these extensions can cause security concerns. This
   setting has higher precedence than the `sieve_extensions' setting (above),
   meaning that the extensions enabled with this setting are never available to
   the user's personal script no matter what is specified for the
   `sieve_extensions' setting. The syntax of this setting is similar to
   the `sieve_extensions' setting, with the difference that extensions are
   enabled or disabled for exclusive use in global scripts. Currently, no
   extensions are marked as such by default.

 sieve_implicit_extensions =
   Which Sieve language extensions are implicitly available to users. The
   extensions listed in this setting do not need to be enabled explicitly using
   the Sieve "require" command. This behavior directly violates the Sieve
   standard, but can be necessary for compatibility with some existing
   implementations of Sieve (notably jSieve). Do not use this setting unless you
   really need to! The syntax and semantics of this setting are otherwise
   identical to the `sieve_extensions' setting

 sieve_plugins =
   The Pigeonhole Sieve interpreter can have plugins of its own. Using this
   setting, the used plugins can be specified. Check the Dovecot wiki
   (wiki2.dovecot.org) or the pigeonhole website (http://pigeonhole.dovecot.org)
   for available plugins. The `sieve_extprograms' plugin is included in this
   release. LDAP support may also be compiled as a plugin called
   `sieve_storage_ldap'.

 sieve_user_email =
   The primary e-mail address for the user. This is used as a default when no
   other appropriate address is available for sending messages. If this setting
   is not configured, either the postmaster or null "<>" address is used as a
   sender, depending on the action involved. This setting is important when
   there is no message envelope to extract addresses from, such as when the
   script is executed in IMAP.

 sieve_user_log =
   The path to the file where the user log file is written. If not configured, a
   default location is used. If the main user's personal Sieve (as configured
   with sieve=) is a file, the logfile is set to <filename>.log by default. If
   it is not a file, the default user log file is ~/.dovecot.sieve.log.

 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.

 sieve_redirect_envelope_from = sender
   Specifies what envelope sender address is used for redirected messages.
   Normally, the Sieve "redirect" command copies the sender address for the
   redirected message from the  processed message. So, the redirected message
   appears to originate from the original sender. The following values are
   supported for this setting:
   
     "sender"         - The sender address is used (default).
     "recipient"      - The final recipient address is used.
     "orig_recipient" - The original recipient is used.
     "user_email"     - The user's primary address is used. This is
                        configured with the "sieve_user_email" setting. If
                        that setting is unconfigured, "user_mail" is equal to
                        "sender" (the default).
     "postmaster"     - The postmaster_address configured for the LDA.
     "<user@domain>"  - Redirected messages are always sent from user@domain.
                        The angle brackets are mandatory. The null "<>" address
                        is also supported.

   When the envelope sender of the processed message is the null address "<>",
   the envelope sender of the redirected message is also always "<>",
   irrespective of what is configured for this setting. 

 sieve_redirect_duplicate_period = 12h
   In an effort to halt potential mail loops, the Sieve redirect action records
   identifying information for messages it has forwarded. If a duplicate message
   is seen, it is not redirected and the message is discarded; i.e., the
   implicit keep is canceled. This setting configures the period during which
   the identifying information is recorded. If an account forwards many
   messages, it may be necessary to lower this setting to prevent the
   ~/.dovecot.lda-dupes database file (in which these are recorded) from growing
   to an impractical size.

For example:

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

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

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

Sieve Interpreter - Configurable Limits
---------------------------------------

The settings that specify a period are specified in s(econds), unless followed
by a d(ay), h(our), or m(inute) specifier character.

 sieve_max_script_size = 1M
   The maximum size of a Sieve script. The compiler will refuse to compile any
   script larger than this limit. If set to 0, no limit on the script size is
   enforced.

 sieve_max_actions = 32
   The maximum number of actions that can be performed during a single script
   execution. If set to 0, no limit on the total number of actions is enforced.

 sieve_max_redirects = 4
   The maximum number of redirect actions that can be performed during a single
   script execution. If set to 0, no redirect actions are allowed.

 sieve_max_cpu_time = 30s
   The maximum amount of CPU time that a Sieve script is allowed to use while
   executing. If the execution exceeds this resource limit, the script ends with
   an error, causing the implicit "keep" action to be executed. This limit is
   not only enforced for a single script execution, but also cumulatively for
   the last executions within a configurable timeout
   (see sieve_resource_usage_timeout).

 sieve_resource_usage_timeout = 1h
   To prevent abuse, the Sieve interpreter can record resource usage of a Sieve
   script execution in the compiled binary if it is significant. Currently, this
   happens when CPU system + user time exceeds 1.5 seconds for one execution.
   Such high resource usage is summed over time in the binary and once that
   cumulative resource usage exceeds the limits (sieve_max_cpu_time), the Sieve
   script is disabled in the binary for future execution, even if an individual
   execution exceeded no limits. If the last time high resource usage was
   recorded is older than sieve_resource_usage_timeout, the resource usage in
   the binary is reset. This means that the Sieve script is only disabled when
   the limits are cumulatively exceeded within this timeout. With the default
   configuration this means that the Sieve script is only disabled when the
   total CPU time of Sieve executions that lasted more than 1.5 seconds exceeds
   30 seconds in the last hour. A disabled Sieve script can be reactivated by
   the user by uploading a new version of the Sieve script after the excessive
   resource usage times out. An administrator can force reactivation by forcing
   a script compile (e.g. using the sievec command line tool).

Sieve Interpreter - Per-user Sieve Script Location
--------------------------------------------------

By default, the Pigeonhole LDA 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 location of 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. Refer to
http://wiki.dovecot.org/Variables for more information.

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

Sieve Interpreter - Executing Multiple Scripts Sequentially
-----------------------------------------------------------

Pigeonhole's Sieve interpreter 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. The following settings in the plugin section of the Dovecot
config file control the execution sequence:

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

   Multiple script locations can be specified by appending an increasing number
   to the setting name. The Sieve scripts found from these locations are added
   to the script execution sequence in the specified order. Reading the numbered
   sieve_before settings stops at the first missing setting, so no numbers may
   be skipped.

 sieve_after =
 sieve_after2 =
 sieve_after3 = (etc..)
   Identical to sieve_before, but the specified scripts are executed after the
   user's script (only when keep is still in effect, as explained below).

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 instead if necessary, meaning that the interpreter
makes sure that the message is at least stored in the default folder (INBOX).

Just as for executing a single script the normal way, the Pigeonhole LDA 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 {
...
   # Global scripts executed before the user's personal script.
   #   E.g. handling messages marked as dangerous
   sieve_before = /var/lib/dovecot/sieve/discard-virusses.sieve

   # Domain-level scripts retrieved from LDAP
   sieve_before2 = ldap:/etc/dovecot/sieve-ldap.conf;name=ldap-domain

   # User-specific scripts executed before the user's personal script.
   #   E.g. a vacation script managed through a non-ManageSieve GUI.
   sieve_before3 = /var/vmail/%d/%n/sieve-before

   # User-specific scripts executed after the user's personal script.
   # (if keep is still in effect)
   #   E.g. user-specific default mail filing rules
   sieve_after = /var/vmail/%d/%n/sieve-after

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

IMPORTANT: The scripts specified by sieve_before and sieve_after are often
located in global locations to which the Sieve interpreter has no write access
to store the compiled binaries. In that case, be sure to manually pre-compile
those scripts using the sievec tool, as explained in the README file.

Sieve Interpreter - Visible Default Script
------------------------------------------

The `sieve_default=' setting specifies the location of a default script that
is executed when the user has no active personal script. Normally, this
default script is invisible to the user; i.e., it is not listed in ManageSieve.
To give the user the ability to see and read the default script, it is possible
to make it visible under a specific configurable name using the
`sieve_default_name' setting.

ManageSieve will magically list the default script under that name, even though
it does not actually exist in the user's normal script storage location. This
way, the ManageSieve client can see that it exists and it can retrieve its
contents. If no normal script is active, the default is always listed as active.
The user can replace the default with a custom script, by uploading it under the
default script's name. If that custom script is ever deleted, the default script
will reappear from the shadows implicitly.

This way, ManageSieve clients will not need any special handling for this
feature. If the name of the default script is equal to the name the client uses
for the main script, it will initially see and read the default script when the
user account is freshly created. The user can edit the script, and when the
edited script is saved through the ManageSieve client, it will will override the
default script. If the user ever wants to revert to the default, the user only
needs to delete the edited script and the default will reappear.

The name by which the default script will be known is configured using the
`sieve_default_name' setting. Of course, the `sieve_default' setting needs to
point to a valid script location as well for this to work. If the default script
does not exist at the indicated location, it is not shown.

For example:

plugin {
...
  sieve = file:~/sieve;active=~/.dovecot.sieve

  sieve_default = /var/lib/dovecot/sieve/default.sieve
	sieve_default_name = roundcube
}

Sieve Interpreter - Extension Configuration
-------------------------------------------

- Editheader extension:

  The editheader extension [RFC5293] enables sieve scripts to interact with
  other components that consume or produce header fields by allowing the script
  to delete and add header fields.

  The editheader extension requires explicit configuration and is not enabled
  for use by default. Refer to doc/extensions/editheader.txt for configuration
  information.

- Vacation extension:

  The Sieve vacation extension [RFC5230] defines a mechanism to generate
  automatic replies to incoming email messages.

  The vacation extension is available by default, but it has its own specific
  configuration options. Refer to doc/extensions/vacation.txt for settings
  specific to the vacation extension.

- Variables extension:

  The Sieve variables extension [RFC5229] adds the concept of variables to the
  Sieve language.

  The variables extension is available by default, but it has its own specific
  configuration options. Refer to doc/extensions/variables.txt for settings
  specific to the variables extension.

- Include extension:

  The Sieve include extension (draft) permits users to include one Sieve script
  into another.

  The include extension is available by default, but it has its own specific
  configuration options. Refer to doc/extensions/include.txt for settings
  specific to the include extension.

- Spamtest and virustest extensions:

  Using the spamtest and virustest extensions (RFC 5235), the Sieve language
  provides a uniform and standardized command interface for evaluating spam and
  virus tests performed on the message. Users no longer need to know what headers
  need to be checked and how the scanner's verdict is represented in the header
  field value. They only need to know how to use the spamtest (spamtestplus) and
  virustest extensions. This also gives GUI-based Sieve editors the means to
  provide a portable and easy to install interface for spam and virus filter
  configuration.

  The spamtest, spamtestplus and virustest extensions require explicit
  configuration and are not enabled for use by default. Refer to
  doc/extensions/spamtest-virustest.txt for configuration information.

- Duplicate extension:

  The duplicate extension augments the Sieve filtering implementation with a
  test that facilitates detecting and handling duplicate message deliveries,
  e.g. as caused by mailinglists when people reply both to the mailinglist and
  the user directly.

  Refer to doc/extensions/vnd.dovecot.duplicate.txt for configuration
  information.

- Dovecot environment extension:

  The vnd.dovecot.environment extension builds on the standard environment
  extension. It adds a few extra environment items that are useful for Sieve
  scripts used by Dovecot.

  Refer to doc/extensions/vnd.dovecot.environment.txt for more information.

- Extprograms plugin;
    vnd.dovovecot.pipe, vnd.dovecot.filter, vnd.dovecot.execute extensions:

  The "sieve_extprograms" plugin provides extensions to the Sieve filtering
  language adding new action commands for invoking a predefined set of external
  programs. Messages can be piped to or filtered through those programs	and
  string data can be input to and retrieved from those programs.

  This plugin and the extensions it provides require explicit configuration and
  are not enabled for use by default. Refer to doc/plugins/sieve_extprograms.txt
  for more information.

- Imapsieve plugins

  The "sieve_imapsieve" Sieve plugin and the "imap_sieve" IMAP plugin add Sieve
  support to IMAP.

  Refer to doc/plugins/imapsieve.txt for more information.

- IMAP Filter Sieve plugin

  The "imap_filter_sieve" plugin adds the ability to manually invoke Sieve
  filtering in IMAP.

  Refer to doc/plugins/imap_filter_sieve.txt for more information.

Sieve Interpreter - Trace Debugging
-----------------------------------

Trace debugging provides detailed insight in the operations performed by
the Sieve script. Messages about what the Sieve script is doing are written
to the specified directory.

WARNING: On a busy server, this functionality can quickly fill up the trace
directory with a lot of trace files. Enable this only temporarily and as
selective as possible.

The following settings apply to both the LDA Sieve plugin and the IMAPSIEVE
plugin:

 sieve_trace_dir =  
  The directory where trace files are written. Trace debugging is disabled if
  this setting is not configured or if the directory does not exist. If the 
  path is relative or it starts with "~/" it is interpreted relative to the
  current user's home directory.

 sieve_trace_level = 
   The verbosity level of the trace messages. Trace debugging is disabled if
   this setting is not configured. Possible values are:
  
     "actions"  - Only print executed action commands, like keep, fileinto,
                  reject and redirect.
     "commands" - Print any executed command, excluding test commands.
     "tests"    - Print all executed commands and performed tests.
     "matching" - Print all executed commands, performed tests and the values
                  matched in those tests.

 sieve_trace_debug = no  
   Enables highly verbose debugging messages that are usually only useful for
   developers.

 sieve_trace_addresses = no   
   Enables showing byte code addresses in the trace output, rather than only
   the source line numbers.

Sieve Interpreter - Migration from CMUSieve (Dovecot v1.0/v1.1)
---------------------------------------------------------------

For the most part, migration from CMUSieve to the Pigeonhole LDA 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. The CMUSieve implementation is
   based on an old draft specification that is not completely compatible.
   Particularly, the denotify command and $text$ substitutions 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 include extension now requires your script file names to end with
   ".sieve". This means that ` include :personal "myscript"; ' won't work unless
   you rename "myscript" to "myscript.sieve"

Sieve Interpreter - Migration from Dovecot Sieve v0.1.x (Dovecot v1.2)
----------------------------------------------------------------------

 * Dovecot v2.0 adds support for LMTP. Much like the Dovecot LDA, it can make
   use of the Pigeonhole Sieve plugin. Since the LMTP service has its own
   prototocol lmtp section in the config file, you need to add the Sieve plugin
   to the mail_plugins setting there too when you decide to use LMTP.
 * The 'sieve_subaddress_sep' setting for the Sieve subaddress extension is now
   known as 'recipient_delimiter'. Although sieve_subaddress_sep is still
   recognized for backwards compatibility, it is recommended to update the
   setting to the new name, since the LMTP service also uses the
   recipient_delimiter setting.

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

IMPORTANT:

  If you have used the LDA 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 that have be done to activate the ManageSieve support in
Dovecot:

 * The first step is to add `sieve' 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 20-managesieve.conf file from the doc/example-config/conf.d directory of
   this package.

   For example:

    service managesieve-login {
      inet_listener sieve {
        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 sieve' 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_logout_format = bytes=%i/%o
   Specifies the string pattern used to compose the logout message of an
   authenticated session. The following substitutions are available:

     %i - total number of bytes read from client
     %o - total number of bytes sent to client

 managesieve_implementation_string = Dovecot Pigeonhole
   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 =
 managesieve_notify_capability =
   Respectively the SIEVE and NOTIFY capabilities reported by the ManageSieve
   service before authentication. If left unassigned these will be assigned
   dynamically according to what the Sieve interpreter supports by default
   (after login this may differ depending on the authenticated user).

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

 sieve = file:~/sieve;active=~/.dovecot.sieve
   This specifies the location where the scripts that are uploaded through
   ManageSieve are stored. During delivery, the LDA Sieve plugin uses this
   location setting to find the active script for Sieve filtering. The Sieve
   "include" extension uses this location for retrieving ":personal" scripts.
   If the location type does not allow uploading scripts, the ManageSieve
   service cannot be used. Currently, only the 'file' location type supports
   ManageSieve. 

   For the 'file' location type:

    * The location is the path to the storage directory for all the user's
      personal Sieve scripts. Scripts are stored as separate files with
      extension .sieve. All other files are ignored when scripts are listed
      by a ManageSieve client. The storage directory 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 regarding the mail_location configuration.
   
    * ManageSieve maintains a symbolic link pointing to the currently active
      script (the script executed at delivery). The location of this symbolic
      link can be configured using the ;active=<path> option. If a regular
      file already exists at the location specified by in the ;active=<path>
      location option, it is moved to the storage directory before the
      symbolic link is installed. It is renamed to dovecot.orig.sieve and
      therefore listed as dovecot.orig by a ManageSieve client.

      NOTE: It is not wise to place this active symbolic link inside your
            mail store, as it may be mistaken for a mail folder. Inside a
            maildir for instance, the default .dovecot.sieve would show up
            as phantom folder /dovecot/sieve in your IMAP tree. 

   For Pigeonhole versions before v0.3.1, this setting can only be a
   filesystem path pointing to a script file, or - when ManageSieve is used -
   it is the location of the symbolic link pointing to the active script in
   the storage directory. That storage directory is then configured using the
   deprecated `sieve_dir' setting. 

The following provides an example configuration for Sieve and ManageSieve. Only
sections and settings relevant to ManageSieve are shown. Refer to
20-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/20-managesieve.conf ***

service managesieve-login {
  inet_listener sieve {
    # 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 sieve {
  managesieve_max_compile_errors = 10
}

# ***  conf.d/90-sieve.conf ***

plugin {
  sieve=file:~/sieve;active=~/.dovecot.sieve
}

# *** dovecot.conf ***

# .... (other config items)

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

# .... (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. If set to 0, no limit on the script size
   is enforced.

 sieve_quota_max_scripts = 0
   The maximum number of personal Sieve scripts a single user can have. If set
   to 0, no limit on the number of scripts is enforced.

 sieve_quota_max_storage = 0
   The maximum amount of disk storage a single user's scripts may occupy. If set
   to 0, no limit on the used amount of disk storage 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

ManageSieve Service - Migration
-------------------------------

The following has changed since the ManageSieve releases for Dovecot v1.x:

 * For Dovecot v1.0 and v1.1, the sieve_dir setting used by ManageSieve was
   called sieve_storage. Also, the sieve and sieve_storage settings were located
   inside the 'protocol managesieve' section of the configuration. As per
   Dovecot v1.2, these settings are shared with the Sieve plugin and located in
   the 'plugin' section of the configuration. Make sure you have updated the
   name of the sieve_dir setting and the location of both these settings if you
   are upgrading from ManageSieve for Dovecot v1.0/v1.1.
 * Pigeonhole ManageSieve does not use the mail_location configuration as a
   fall-back anymore to determine a default location for storing Sieve scripts.
   It always uses the sieve_dir setting, with default value ~/sieve.
 * The Pigeonhole ManageSieve service now binds to TCP port 4190 by default due
   to the IANA port assignment for the ManageSieve service. When upgrading from
   v1.x, this should be taken into account. For a smooth transition, the service
   can be configured manually to listen on both port 2000 and port 4190, as
   demonstrated in the example above.
 * The Dovecot configuration now calls the ManageSieve protocol 'sieve' instead
   of 'managesieve' because it is registered as such with IANA. The binaries and
   the services are still called 'managesieve' and 'managesieve-login'. The
   example above demonstrates how this affects the configuration.

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 basic test suite using `make test`, which does not include the plugins. You
can test the plugins using `make test-plugins`.

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