diff options
Diffstat (limited to 'pigeonhole/INSTALL')
| -rw-r--r-- | pigeonhole/INSTALL | 903 |
1 files changed, 903 insertions, 0 deletions
diff --git a/pigeonhole/INSTALL b/pigeonhole/INSTALL new file mode 100644 index 0000000..eca1360 --- /dev/null +++ b/pigeonhole/INSTALL @@ -0,0 +1,903 @@ +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. + + |