dovecot-2.0-pigeonhole: Updated documentation.
pigeonhole at rename-it.nl
pigeonhole at rename-it.nl
Tue Aug 17 19:30:22 EEST 2010
details: http://hg.rename-it.nl/dovecot-2.0-pigeonhole/rev/126e6b9fad21
changeset: 1377:126e6b9fad21
user: Stephan Bosch <stephan at rename-it.nl>
date: Tue Aug 17 18:30:17 2010 +0200
description:
Updated documentation.
diffstat:
INSTALL | 90 +++++++++++++++++++++++++-------------------
README | 79 ++++++++++++++++++---------------------
2 files changed, 87 insertions(+), 82 deletions(-)
diffs (truncated from 316 to 300 lines):
diff -r d22162f0d0eb -r 126e6b9fad21 INSTALL
--- a/INSTALL Tue Aug 17 17:46:12 2010 +0200
+++ b/INSTALL Tue Aug 17 18:30:17 2010 +0200
@@ -56,8 +56,8 @@
The Pigeonhole package provides the following items:
- - The Sieve plugin for Dovecot's Local Delivery Agent (LDA): This facilitates
- the actual Sieve filtering upon delivery.
+ - The LDA Sieve 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.
@@ -67,12 +67,12 @@
configuration files are provided in the doc/example-config directory of this
package.
-Sieve Plugin - Basic Configuration
-----------------------------------
+LDA Sieve Plugin - 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
-Sieve plugin in your dovecot.conf:
+LDA Sieve plugin in your dovecot.conf:
protocol lda {
..
@@ -138,8 +138,8 @@
sieve_global_dir = /var/lib/dovecot/sieve/global/
}
-Sieve Plugin - Configurable Limits
-----------------------------------
+LDA Sieve Plugin - Configurable Limits
+--------------------------------------
sieve_max_script_size = 1M
The maximum size of a Sieve script. The compiler will refuse to compile any
@@ -155,11 +155,11 @@
A value of 0 for these settings means that the limit is not enforced.
-Sieve Plugin - Per-user Sieve script location
----------------------------------------------
+LDA Sieve Plugin - Per-user Sieve script location
+-------------------------------------------------
-By default, the Dovecot Sieve plugin looks for the user's Sieve script file in
-the user's home directory (~/.dovecot.sieve). This requires that the home
+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
@@ -178,21 +178,22 @@
sieve = /var/sieve-scripts/%u.sieve
}
-You may use templates like %u, as shown in the example. See all variables.
+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 Plugin - Executing Multiple Scripts Sequentially
-------------------------------------------------------
+LDA Sieve Plugin - Executing Multiple Scripts Sequentially
+----------------------------------------------------------
-The Dovecot Sieve plugin allows executing multiple Sieve scripts sequentially.
-The extra scripts can be executed before and after the user's private script.
-For example, this allows executing global Sieve policies before the user's
-script. This is not possible using the sieve_global_path setting, because that
-is only used when the user's private script does not exist. The following
-settings in the plugin section of the Dovecot config file control the execution
-sequence:
+Pigeonhole's LDA Sieve plugin allows executing multiple Sieve scripts
+sequentially. The extra scripts can be executed before and after the user's
+private script. For example, this allows executing global Sieve policies before
+the user's script. This is not possible using the sieve_global_path setting,
+because that is only used as a default when the user's private script does not
+exist. The following settings in the plugin section of the Dovecot config file
+control the execution sequence:
sieve_before =
Path to a script file or a directory containing script files that need to be
@@ -224,12 +225,14 @@
in the sequence encounters an error, actions from earlier executed scripts are
not affected. The sequence is broken however, meaning that the script execution
of the offending script is aborted and no further scripts are executed. An
-implicit keep is executed in stead.
+implicit keep is executed in stead 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 Dovecot Sieve plugin
-takes care never to duplicate deliveries, forwards or responses. When vacation
-actions are executed multiple times in different scripts, the usual error is not
-triggered: the subsequent duplicate vacation actions are simply discarded.
+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:
@@ -247,8 +250,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.
-Sieve Plugin - Spamtest and Virustest Extensions
-------------------------------------------------
+LDA Sieve Plugin - 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
@@ -263,11 +266,11 @@
configuration and are not enabled for use by default. Refer to
doc/spamtest-virustest.txt for configuration information.
-Sieve Plugin - Migration from CMUSieve
---------------------------------------
+LDA Sieve Plugin - Migration from CMUSieve
+------------------------------------------
-For the most part, migration from CMUSieve to the Pigeonhole Sieve plugin is
-just a matter of changing the used plugin name from cmusieve to sieve in the
+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:
@@ -277,14 +280,17 @@
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. Sieve scripts need to be adjusted
- to incorporate this change: unlike imapflags, no backwards compatibility is
- provided currently.
-
- * The include extension now requires your script file names to end with
- ".sieve" : include :personal "myscript"; won't work unless you rename
- "myscript" to "myscript.sieve"
+
+ * 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"
ManageSieve Service - Basic Configuration
-----------------------------------------
@@ -301,7 +307,7 @@
Just like all other binaries that Dovecot uses, the managesieve and
managesieve-login binaries are installed during make install.
-There are two things to have be done to activate the ManageSieve support in
+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
@@ -329,7 +335,7 @@
borrowed from IMAP. But, since long command lines are very unlikely with
ManageSieve, changing this will not be very useful.
-managesieve_implementation_string = Dovecot
+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').
@@ -343,11 +349,11 @@
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 user).
+ (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 ones used by the Sieve
-plugin.
+plugin section of the config file. These settings are the same ones used by
+the LDA Sieve plugin.
sieve_dir = ~/sieve
This specifies the path to the directory where the uploaded scripts are
diff -r d22162f0d0eb -r 126e6b9fad21 README
--- a/README Tue Aug 17 17:46:12 2010 +0200
+++ b/README Tue Aug 17 18:30:17 2010 +0200
@@ -5,39 +5,36 @@
Introduction
============
-This package provides Sieve support for the Dovecot Secure IMAP server. Sieve is
-a machine language specifically tailored for internet message filtering. By
-writing Sieve scripts, users can customize how messages are delivered, e.g.
-whether they are forwarded or stored in special folders. The Sieve language is
-meant to be simple, extensible and system independent. And, unlike most other
-mail filtering script languages, it does not allow users to execute arbitrary
-programs. This is particularly useful to prevent virtual users from having full
-access to the mail store. The intention of the language is to make it impossible
-for users to do anything more complex (and dangerous) than write simple mail
-filters.
+This package is part of the Pigeonhole project (http://pigeonhole.dovecot.org).
+It adds support for the Sieve language (RFC 5228) and the ManageSieve protocol
+(RFC 5804) to the Dovecot Secure IMAP Server. In the literal sense, a
+pigeonhole is a a hole or recess inside a dovecot for pigeons to nest in. It
+is, however, also the name for one of a series of small, open compartments in
+a cabinet used for filing or sorting mail. As a verb, it describes the act of
+putting an item into one of those pigeonholes. The name `Pigeonhole' therefore
+well describes an important part of the functionality that this project adds to
+Dovecot: sorting and filing e-mail messages.
-Support for filtering messages through Sieve scripts is provided at message
-delivery. This is implemented as a plugin for Dovecot's Local Delivery Agent
-(LDA).
+The Sieve language is used to specify how e-mail needs to be processed. By
+writing Sieve scripts, users can customize how messages are delivered, e.g.
+whether they are forwarded or stored in special folders. Unwanted messages can
+be discarded or rejected, and, when the user is not available, the Sieve
+interpreter can send an automated reply. Above all, the Sieve language is meant
+to be simple, extensible and system independent. And, unlike most other mail
+filtering script languages, it does not allow users to execute arbitrary
+programs. This is particularly useful to prevent virtual users from having full
+access to the mail store. The intention of the language is to make it
+impossible for users to do anything more complex (and dangerous) than write
+simple mail filters.
-This package also adds a ManageSieve service to Dovecot, which can be used to
-let users manage their Sieve script remotely. It has the following advantages
-over managing these directly via the filesystem:
+Using the ManageSieve protocol, users can upload their Sieve scripts remotely,
+without needing direct filesystem access through FTP or SCP. Additionally, a
+ManageSieve server always makes sure that uploaded scripts are valid,
+preventing compile failures at mail delivery.
- * There is no need to let users log in via FTP/SFTP/etc, which could be
- difficult and undesirable, especially with virtual users.
-
- * ManageSieve is a standard protocol (although still a draft), so users can
- manage their scripts using (hopefully) user-friendly ManageSieve clients.
- Many webmails already include a ManageSieve client.
-
- * Scripts are compiled before they are installed, which guarantees that the
- uploaded script is valid, preventing a user from inadvertently installing a
- broken Sieve script.
-
-More information about the Pigeonhole project can be found at:
-
- http://pigeonhole.dovecot.org
+This package provides Sieve support as a plugin to Dovecot's Local Delivery
+Agent (LDA). The ManageSieve protocol is provided is an additional service,
+next to Dovecot's own POP3 and IMAP services.
Features
========
@@ -192,11 +189,11 @@
Compiling Sieve Scripts
=======================
-When the Sieve plugin executes a script for the first time (or after it has been
-changed), it's compiled into into a binary form. Pigeonhole Sieve implementation
-uses the .svbin extension to store compiled Sieve scripts (e.g. .dovecot.svbin).
-To store the binary, the plugin needs write access in the directory in which the
-script is located.
+When the LDA Sieve plugin executes a script for the first time (or after it has
+been changed), it is compiled into into a binary form. The Pigeonhole Sieve
+implementation uses the .svbin extension to store compiled Sieve scripts (e.g.
+.dovecot.svbin). To store the binary, the plugin needs write access in the
+directory in which the script is located.
A problem occurs when a global script is encountered by the plugin. For security
reasons, global script directories are not supposed to be writable by the user.
@@ -216,12 +213,8 @@
This is necessary for scripts listed in the sieve_global_path, sieve_before and
sieve_after settings. For global scripts that are only included in other scripts
using the include extension, this step is not necessary, since included scripts
-are incorporated into the binary produced for the main script.
-
-When manually compiling scripts with sievec, if those scripts use the include
-sieve extension and your sieve_dir is not the sieve subfolder of the directory
-of the main file, you can specify it by defining the SIEVE_DIR environment
-variable (e.g SIEVE_DIR=~/.sieve sievec .dovecot.sieve )
+are incorporated into the binary produced for the main script located in a
+user directory.
Compile and Runtime Logging
===========================
@@ -240,7 +233,7 @@
produced.
More information about the dovecot-cvs
mailing list