This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Pigeonhole Sieve Configuration

Basic Configuration

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

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. 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. 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, 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. 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 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 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. 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 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 the location 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, or see this wiki page.

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:

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.

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.

Migration

General Dovecot 2.0 changes

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). However, there are a few important differences in the supported Sieve language features:

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

Pigeonhole/Sieve/Configuration (last edited 2014-05-20 16:12:36 by cpc46-slam6-2-0-cust675)