From 0441d265f2bb9da249c7abf333f0f771fadb4ab5 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Mon, 15 Apr 2024 19:36:47 +0200
Subject: Adding upstream version 1:2.3.21+dfsg1.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 pigeonhole/INSTALL | 903 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 903 insertions(+)
 create mode 100644 pigeonhole/INSTALL

(limited to 'pigeonhole/INSTALL')

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.
+
+
-- 
cgit v1.2.3