Edit File: Pigeonhole.Sieve.Configuration.txt
Pigeonhole Sieve Configuration ============================== Contents 1. Pigeonhole Sieve Configuration 1. Script Locations 2. Basic Configuration 3. Configurable Limits 4. Extension-specific Configuration 5. Per-user Sieve script location 6. Executing Multiple Scripts Sequentially 7. Visible Default Script 8. Trace Debugging 9. Deprecated Settings 10. Migration 1. General Dovecot 2.0 changes 2. From CMUSieve (Dovecot v1.0/v1.1) 3. From Dovecot Sieve v0.1.x (Dovecot v1.2) Script Locations ---------------- The Sieve interpreter can retrieve Sieve scripts from several types of locations. The default 'file' location type is a directory containing one or more Sieve script files with a symlink pointing to the active one. 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 or more Sieve scripts accept the following syntax:: ---%<------------------------------------------------------------------------- <setting> = [<type>:]path[;<option>[=<value>][;...]] ---%<------------------------------------------------------------------------- The following script location types are implemented by default: file : The location path is a file system path pointing to a directory containing one or more script files with names structured as '<script-name>.sieve' with the active option (default ~/.dovecot.sieve) specifying a symlink to the one that will be used, or without the active option specified, it may be a script file instead of a directory. Read <this wiki page> [Pigeonhole.Sieve.Configuration.File.txt] for more information and examples. dict : The location path is a Dovecot dict uri. Read <this wiki page> [Pigeonhole.Sieve.Configuration.Dict.txt] for more information and examples. ldap : LDAP database lookup. The location path is a configuration file with LDAP options. Read <this wiki page> [Pigeonhole.Sieve.Configuration.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 [http://tools.ietf.org/html/draft-ietf-sieve-include-05] 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). *NOTE*: Pigeonhole versions before v0.3.1 do not support the location syntax described here. These versions only support bare filesystem paths pointing to files or directores as script storage location. Also, in that case a few additional <deprecated settings> [Pigeonhole.Sieve.Configuration.txt] are needed for 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 = file:~/sieve;active=~/.dovecot.sieve : The location of the user's main Sieve script or script storage. The <LDA.txt> Sieve plugin uses this to find the active script for Sieve filtering at delivery. The Sieve include extension [http://tools.ietf.org/html/draft-ietf-sieve-include-05] uses this location for retrieving ":personal" scripts. : This location is also where the <ManageSieve> [Pigeonhole.ManageSieve.txt] 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> [Pigeonhole.ManageSieve.txt] 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. : For Pigeonhole versions before v0.3.1, this setting can only be a filesystem path pointing to a script file, or - when <ManageSieve> [Pigeonhole.ManageSieve.txt] 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. sieve_default = (v0.3+) : The location of the default personal sieve script file which gets executed ONLY if user's private Sieve script does not exist, e.g.'file:/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]. This setting used to be called 'sieve_global_path', but that name is now deprecated. sieve_default_name = (v0.4.8+) : The name by which the default Sieve script is visible to <ManageSieve> [Pigeonhole.ManageSieve.txt] clients. Normally, it is not visible at all. Refer to the <visible default script section> [Pigeonhole.Sieve.Configuration.txt] for more information. sieve_global = : Location for :global include scripts for the Sieve include extension [http://tools.ietf.org/html/draft-ietf-sieve-include-05]. This setting used to be called 'sieve_global_dir', but that name is now deprecated. sieve_discard = (v0.4.16+) : 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, 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_implicit_extensions = (v0.4.13+) : 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 <Sieve plugins page> [Pigeonhole.Sieve.Plugins.txt] for available plugins. sieve_user_email = (v0.4.14+) : 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 [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. sieve_redirect_envelope_from = sender (v0.4.4+): 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" (v0.4.14+): The user's primary address is used. This is configured with the "sieve_user_email" setting. If that setting is not configured, "user_mail" is equal to "sender" (the default). "postmaster" : The postmaster_address configured for LDA/LMTP. "<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. For example: ---%<------------------------------------------------------------------------- plugin { ... # The location of the user's main script storage. The active script # in this storage is used as the main user script executed during # delivery. The include extension fetches the :personal scripts # from this location. When ManageSieve is used, this is also where # scripts are uploaded. This example uses the file system as # storage, with all the user's scripts located in the directory # `~/sieve' and the active script (symbolic link) located at # `~/.dovecot.sieve'. sieve = file:~/sieve;active=~/.dovecot.sieve # If the user has no personal active script (i.e. if the location # indicated in sieve= does not exist or has no active script), use # this one: sieve_default = /var/lib/dovecot/sieve/default.sieve # The include extension fetches the :global scripts from this # location. sieve_global = /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. Extension-specific Configuration -------------------------------- The following Sieve language extensions have specific configuration options/needs: * <duplicate> [Pigeonhole.Sieve.Extensions.Duplicate.txt] * <editheader> [Pigeonhole.Sieve.Extensions.Editheader.txt] (configuration required) * <imapsieve> [Pigeonhole.Sieve.Plugins.IMAPSieve.txt] (plugin configuration required) * <include> [Pigeonhole.Sieve.Extensions.Include.txt] * <spamtest and virustest> [Pigeonhole.Sieve.Extensions.SpamtestVirustest.txt] (configuration required) * <vacation and vacation-seconds> [Pigeonhole.Sieve.Extensions.Vacation.txt] 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_default' 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 = : 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 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 { ... # 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*: 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]. 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> [Pigeonhole.ManageSieve.txt]. 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. This feature is only supported for Pigeonhole versions 0.4.8 and higher. 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, theManageSieve 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 theManageSieve 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 } ---%<------------------------------------------------------------------------- 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. This feature is only supported for Pigeonhole versions 0.4.14 and higher. *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; e.g., enable this only for a few users by returning the settings below from userdb as <userdb extra fields> [UserDatabase.ExtraFields.txt], rather than enabling these for everyone. The following settings apply to both the LDA/LMTP Sieve plugin and the <IMAPSieve> [Pigeonhole.Sieve.Plugins.IMAPSieve.txt] 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. Deprecated Settings ------------------- These settings are deprecated in newer versions, but still recognized: sieve_global_path = (< v0.2): The deprecated name for the 'sieve_default' setting. sieve_dir = ~/sieve (< v0.3.1): 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 a script called 'name'. When using <ManageSieve> [Pigeonhole.ManageSieve.txt], this is also the directory where scripts are uploaded. For recent Pigeonhole versions, this location is configured as part of the 'sieve' setting. sieve_global_dir = (< v0.3.1): 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 a script called 'name'. For recent Pigeonhole versions, a more generic version of this setting is called 'sieve_global' and allows locations other than file system directories. 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 2018-02-28 04:42)