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_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'.
  Check the <multiscript section> [Pigeonhole.Sieve.Configuration.txt] for
  instructions on running global Sieve scripts before and after the user's
  personal script. Be sure to pre-compile the specified script manually using
  the 'sievec' command line tool, as explained <here>
  [Pigeonhole.Sieve.Usage.txt].

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 require explicit configuration 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. 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_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.

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

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" :'include :personal
   "myscript";' won't work unless you rename "myscript" to "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 2011-08-29 04:42)