Pigeonhole Sieve Configuration
==============================

Basic Configuration
-------------------

To use Sieve, you will first need to make sure you are using Dovecot <LDA.txt>
or <LMTP.txt> for delivering incoming mail to users' mailboxes. Then, you need
to enable the Pigeonhole Sieve plugin in your configuration:

---%<-------------------------------------------------------------------------
protocol lda {
  mail_plugins = $mail_plugins sieve
}
protocol lmtp {
  mail_plugins = $mail_plugins sieve
}
---%<-------------------------------------------------------------------------

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 Sieve script. When <ManageSieve>
  [Pigeonhole.ManageSieve.txt] is used, this is a symbolic link pointing to the
  active script in the 'sieve_dir' directory. Avoid placing the active Sieve
  script inside the 'sieve_dir' directory.

sieve_default = (v0.3+) :
  The location of the default personal sieve script file which gets executed
  ONLY if user's private Sieve script does no exist,
  e.g.'/var/lib/dovecot/default.sieve'. Check the <multiscript section>
  [Pigeonhole.Sieve.Configuration.txt] for instructions on running global Sieve
  scripts before and after the user's personal script. This is usually a global
  script, so be sure to pre-compile the specified script manually in that case
  using the 'sievec' command line tool, as explained <here>
  [Pigeonhole.Sieve.Usage.txt].

sieve_global_path = :
  The deprecated name for the 'sieve_default' setting (Pigeonhole v0.2 and
  earlier).

sieve_global_dir = :
  Directory for :global include scripts for the include extension
  [http://tools.ietf.org/html/draft-ietf-sieve-include-05]. The Sieve
  interpreter only recognizes files that end with a '.sieve' extension, so the
  include extension expects a file called 'name.sieve' to exist in the
  'sieve_global_dir' directory for the following example:

:
  ---%<-----------------------------------------------------------------------
  require "include";
  include :global "name";
  ---%<-----------------------------------------------------------------------

sieve_dir = ~/:
  Directory for :personal include scripts for the include extension
  [http://tools.ietf.org/html/draft-ietf-sieve-include-05]. The Sieve
  interpreter only recognizes files that end with a '.sieve' extension, so the
  include extension expects a file called 'name.sieve' to exist in the
  'sieve_dir' directory for:

:
  ---%<-----------------------------------------------------------------------
  require "include";
  include :personal "name";
  ---%<-----------------------------------------------------------------------

:
  When using <ManageSieve> [Pigeonhole.ManageSieve.txt], this is also the
  directory where scripts are uploaded.

sieve_extensions = :
  Which Sieve language extensions are available to users. By default, all
  supported extensions are available, except for deprecated extensions,
  extensions that add the ability to change messages, extensions that require
  explicit configuration or extensions that are still under development. Some
  system administrators may want to disable certain Sieve extensions or enable
  those that are not available by default. All supported extensions are listed
  <here> [Pigeonhole.Sieve.txt]. Normally, all enabled extensions must be
  listed for this setting, but starting with Sieve version 0.1.7, this setting
  can use '+' and '-' to specify differences relative to the default. For
  example 'sieve_extensions = +imapflags' will enable the deprecated imapflags
  extension [http://tools.ietf.org/html/draft-melnikov-sieve-imapflags-03] in
  addition to all extensions enabled by default.

sieve_global_extensions = (v0.3+) :
  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_plugins = :
  The Pigeonhole Sieve interpreter can have plugins of its own. Using this
  setting, the used plugins can be specified. Check the <Sieve plugins page>
  [Pigeonhole.Sieve.Plugins.txt] for available plugins.

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 [http://tools.ietf.org/html/rfc5233/].
  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.txt>
  service with identical semantics.

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

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. 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. The meaning of 0 differs based on your version. For
  versions v0.3.0 and beyond this means that redirect is prohibited. For older
  versions, however, this means that the number of redirects is /unlimited/, so
  be careful.

Script Locations
----------------

/(Pigeonhole v0.3.1+ only)/

The location of Sieve scripts is not limited to the file system. The Sieve
interpreter can be extended to retrieve Sieve scripts from other sources as
well, such as a database. Currently, all settings that are used to obtain
thelocation of a single Sieve script, such as 'sieve=', 'sieve_default=',
'sieve_dir=' and 'sieve_global_dir=' accept the following extended 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'.

dict :
  Dovecot dict lookup. The location path is a dict uri. Read
  doc/script-location-dict.txt in the Pigeonhole source package for more
  information and examples (/FIXME: make a wiki page for this/).

If the type prefix is omitted, the script location type is 'file'.

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, 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, 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 include a script
  from the 'sieve_dir=' location), this option has no effect.

bindir=<dirpath> :
  Points to the directory where the compiled binaries for this script location
  are stored. 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.

Extension-specific Configuration
--------------------------------

The following Sieve language extensions have specific configuration
options/needs:

 * <vacation and vacation-seconds> [Pigeonhole.Sieve.Extensions.Vacation.txt]
 * <spamtest and virustest> [Pigeonhole.Sieve.Extensions.SpamtestVirustest.txt]
   (configuration required)

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> [VirtualUsers.txt] 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>
    [UserDatabase.ExtraFields.txt].

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>
[Variables.txt].

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

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 <here>
[Pigeonhole.Sieve.Usage.txt].

Migration
---------

General Dovecot 2.0 changes
---------------------------

 * Note that the Dovecot v2.0 <LDA.txt> does not create mailfolders
   automatically by default anymore. If your configuration relies on this, you
   need to enable the 'lda_mailbox_autocreate' setting for <LDA.txt> or start
   using the Sieve mailbox extension's ':create' tag for *fileinto* commands.
 * Dovecot v2.0 adds support for <LMTP.txt>. Much like the <Dovecot LDA>
   [LDA.txt], it can make use of the Pigeonhole Sieve plugin. Since the
   <LMTP.txt> 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.txt>.

From CMUSieve (Dovecot v1.0/v1.1)
---------------------------------

For the most part, migration from CMUSieve to Pigeonhole Sieve 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> [Pigeonhole.Sieve.Configuration.txt]). However, there are a
few important differences in the supported Sieve language features:

 * The *imapflags* extension is now called *imap4flags*. The CMUSieve
   implementation is based on an old draft specification
   [http://tools.ietf.org/html/draft-melnikov-sieve-imapflags-03] that is not
   completely compatible with the new version
   [http://tools.ietf.org/html/rfc5232/]. 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>
   [Pigeonhole.Sieve.Configuration.txt]). This is disabled by default.
 * The *notify* extension is now called *enotify*. The CMUSieve implementation
   is based on an old draft specification
   [http://tools.ietf.org/html/draft-martin-sieve-notify-01] that is not
   completely compatible with the new version
   [http://tools.ietf.org/html/rfc5435/]. 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>
   [Pigeonhole.Sieve.Configuration.txt]). This is disabled by default.
 * The include extension [http://tools.ietf.org/html/draft-ietf-sieve-include]
   now requires your script /file/ names to end with ".sieve". This means that
   'include :personal "myscript"' won't work unless your script file is called
   "'myscript.sieve'" on disk. Also note that the "'.sieve'" extension has no
   special meaning within the Sieve script; if you 'include "myscript.sieve"',
   the Sieve interpreter will look for a script file called
   'myscript.sieve.sieve' and not 'myscript.sieve'.
 * Be sure to use *UTF8* for the mailbox argument of the *fileinto* command.
   Older CMUSieve installations used modified UTF7 (as IMAP does) for the
   mailbox parameter. If not adjusted, the Pigeonhole Sieve plugin will use the
   wrong folder name for storing the message.

From Dovecot Sieve v0.1.x (Dovecot v1.2)
----------------------------------------

 * The 'sieve_subaddress_sep' setting for the Sieve subaddress extension
   [http://tools.ietf.org/html/rfc5233/] 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.txt> service also uses the 'recipient_delimiter' setting.

(This file was created from the wiki on 2013-11-24 04:42)