dovecot-2.0-pigeonhole: Updated INSTALL documentation.
pigeonhole at rename-it.nl
pigeonhole at rename-it.nl
Wed Sep 8 21:52:45 EEST 2010
details: http://hg.rename-it.nl/dovecot-2.0-pigeonhole/rev/991a6b09f2a9
changeset: 1416:991a6b09f2a9
user: Stephan Bosch <stephan at rename-it.nl>
date: Wed Sep 08 20:52:38 2010 +0200
description:
Updated INSTALL documentation.
diffstat:
INSTALL | 332 +++++++++++++++++++++++++++++++++++++++---------------------------
1 files changed, 196 insertions(+), 136 deletions(-)
diffs (truncated from 484 to 300 lines):
diff -r 91117b838f30 -r 991a6b09f2a9 INSTALL
--- a/INSTALL Wed Sep 08 20:04:56 2010 +0200
+++ b/INSTALL Wed Sep 08 20:52:38 2010 +0200
@@ -11,39 +11,39 @@
--with-dovecot=<path> to point to dovecot-config file's directory. There are two
possibilities where this could exist:
- 1. Dovecot's library directory when compiling against a Dovecot installation:
+ 1. Dovecot's library directory when compiling against a Dovecot installation:
- If you configured Dovecot with --enable-header-install, you'll have
- dovecot-config installed in the $prefix/lib/dovecot/ directory. Pigeonhole
- is then for example configured as follows:
+ If you configured Dovecot with --enable-header-install, you'll have
+ dovecot-config installed in the $prefix/lib/dovecot/ directory. Pigeonhole
+ is then for example configured as follows:
./configure --with-dovecot=/usr/local/lib/dovecot
- 2. The root directory of a built Dovecot source tree:
+ 2. The root directory of a built Dovecot source tree:
- The compilation of the Dovecot sources will produce the dovecot-config file
- in the root of the source tree. Pigeonhole is then for example configured
- as follows:
+ The compilation of the Dovecot sources will produce the dovecot-config file
+ in the root of the source tree. Pigeonhole is then for example configured
+ as follows:
./configure --with-dovecot=../dovecot-2.0/
The following additional parameters are of interest for the configuration of the
Pigeonhole build:
- --with-managesieve=yes
- Controls whether the ManageSieve is compiled and installed. ManageSieve is
- compiled by default.
+ --with-managesieve=yes
+ Controls whether the ManageSieve is compiled and installed. ManageSieve is
+ compiled by default.
- --enable-header-install=no
- Controls whether Pigeonhole will install development headers for building
- external plugins. The default is not to install development headers.
+ --enable-header-install=no
+ Controls whether Pigeonhole will install development headers for building
+ external plugins. The default is not to install development headers.
- --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-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.
After the package is successfully configured, you can compile and install the
package.
@@ -56,7 +56,7 @@
The Pigeonhole package provides the following items:
- - The LDA Sieve plugin for Dovecot's Local Delivery Agent (LDA): This
+ - 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
@@ -67,55 +67,64 @@
configuration files are provided in the doc/example-config directory of this
package.
-LDA Sieve Plugin - Basic Configuration
---------------------------------------
+Sieve Interpreter - Basic Configuration
+---------------------------------------
-To use Sieve, you will first need to make sure you are using Dovecot's LDA
-for delivering incoming mail to users' mailboxes. Then, you need to enable the
-LDA Sieve plugin in your dovecot.conf:
+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 {
..
- # Support for dynamically loadable plugins. mail_plugins is a space separated
- # list of plugins to load.
mail_plugins = sieve # ... other plugins like quota
}
-The sieve plugin recognizes the following configuration options in the plugin
-section of the config file (default values are shown if applicable):
+protocol lmtp {
+..
+ mail_plugins = sieve # ... other plugins like quota
+}
-sieve = ~/.dovecot.sieve
- The path to the user's main active script.
+The Sieve interpreter recognizes the following configuration options in the
+plugin section of the config file (default values are shown if applicable):
-sieve_global_path
- A path to a global sieve script file, which gets executed ONLY if user's
- private Sieve script doesn't exist, e.g. /var/lib/dovecot/default.sieve. Be
- sure to pre-compile this script manually using the sievec command line tool,
- as explained in the README file.
+ sieve = ~/.dovecot.sieve
+ The path to the user's main active script.
+
+ sieve_global_path
+ A path to a global sieve script file, which gets executed ONLY if user's
+ private Sieve script doesn't exist, e.g. /var/lib/dovecot/default.sieve. Be
+ sure to pre-compile this script manually using the sievec command line tool,
+ as explained in the README file.
-sieve_global_dir =
- Directory for :global include scripts for the include extension.
+ sieve_global_dir =
+ Directory for :global include scripts for the Sieve include extension.
-sieve_dir = ~/
- Directory for :personal include scripts for the include extension.
+ sieve_dir = ~/
+ Directory for :personal include scripts for the Sieve include extension.
-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. Supported extensions are listed on this page. This setting can use
- '+' and '-' to specify differences relative to the default. For example
- `sieve_extensions = +imapflags' will enable the deprecated imapflags extension
- in addition to all extensions enabled by default.
+ sieve_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. Supported extensions are listed on this page. This setting can use
+ '+' and '-' to specify differences relative to the default. For example
+ `sieve_extensions = +imapflags' will enable the deprecated imapflags
+ extension in addition to all extensions enabled by default.
-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_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.
+
+ 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.
For example:
@@ -138,25 +147,25 @@
sieve_global_dir = /var/lib/dovecot/sieve/global/
}
-LDA Sieve Plugin - Configurable Limits
---------------------------------------
+Sieve Interpreter - 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.
+ sieve_max_script_size = 1M
+ The maximum size of a Sieve script. The compiler will refuse to compile any
+ script larger than this limit.
-sieve_max_actions = 32
- The maximum number of actions that can be performed during a single script
- execution.
+ sieve_max_actions = 32
+ The maximum number of actions that can be performed during a single script
+ execution.
-sieve_max_redirects = 4
- The maximum number of redirect actions that can be performed during a single
- script execution.
+ sieve_max_redirects = 4
+ The maximum number of redirect actions that can be performed during a single
+ script execution.
-A value of 0 for these settings means that the limit is not enforced.
+A value of 0 for these settings means that the limit is not enforced.
-LDA Sieve Plugin - Per-user Sieve script location
--------------------------------------------------
+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
@@ -184,10 +193,10 @@
A relative path (or just a filename) will be interpreted to point under the
user's home directory.
-LDA Sieve Plugin - Executing Multiple Scripts Sequentially
-----------------------------------------------------------
+Sieve Interpreter - Executing Multiple Scripts Sequentially
+-----------------------------------------------------------
-Pigeonhole's LDA Sieve plugin allows executing multiple Sieve scripts
+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. This is not possible using the sieve_global_path setting,
@@ -195,16 +204,16 @@
exist. The following settings in the plugin section of the Dovecot config file
control the execution sequence:
-sieve_before =
- Path to a script file or a directory containing script files that need to be
- executed before the user's script. If the path points to a directory, all the
- Sieve scripts contained therein (with the proper .sieve extension) are
- executed. The order of execution is determined by the file names, using a
- normal 8bit per-character comparison.
+ sieve_before =
+ Path to a script file or a directory containing script files that need to be
+ executed before the user's script. If the path points to a directory, all the
+ Sieve scripts contained therein (with the proper .sieve extension) are
+ executed. The order of execution is determined by the file names, using a
+ normal 8bit per-character comparison.
-sieve_after =
- Identical to sieve_before, only the specified scripts are executed after the
- user's script (only when keep is still in effect!).
+ sieve_after =
+ Identical to sieve_before, only the specified scripts are executed after the
+ user's script (only when keep is still in effect!).
The script execution ends when the currently executing script in the sequence
does not yield a "keep" result: when the script terminates, the next script is
@@ -250,8 +259,8 @@
IMPORTANT: Be sure to manually pre-compile the scripts specified by sieve_before
and sieve_after using the sievec tool, as explained in the README file.
-LDA Sieve Plugin - Spamtest and Virustest Extensions
-----------------------------------------------------
+Sieve Interpreter - 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
@@ -266,8 +275,8 @@
configuration and are not enabled for use by default. Refer to
doc/spamtest-virustest.txt for configuration information.
-LDA Sieve Plugin - Migration from CMUSieve
-------------------------------------------
+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
@@ -288,16 +297,29 @@
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"
+ * 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
More information about the dovecot-cvs
mailing list