dovecot-2.2-pigeonhole: Updated configuration-related documentat...
pigeonhole at rename-it.nl
pigeonhole at rename-it.nl
Thu Mar 26 22:32:31 UTC 2015
details: http://hg.rename-it.nl/dovecot-2.2-pigeonhole/rev/5547d6d1778c
changeset: 2027:5547d6d1778c
user: Stephan Bosch <stephan at rename-it.nl>
date: Thu Mar 26 23:32:21 2015 +0100
description:
Updated configuration-related documentation.
diffstat:
INSTALL | 46 ++++++++-----
doc/extensions/duplicate.txt | 4 -
doc/locations/dict.txt | 145 +++++++++++++++++++++++++++++++++++++++++++
doc/locations/file.txt | 48 ++++++++++++++
doc/locations/ldap.txt | 73 +++++++++++++++++++++
doc/script-location-dict.txt | 143 ------------------------------------------
doc/script-location-ldap.txt | 73 ---------------------
7 files changed, 293 insertions(+), 239 deletions(-)
diffs (truncated from 600 to 300 lines):
diff -r 971969e1671d -r 5547d6d1778c INSTALL
--- a/INSTALL Thu Mar 19 23:27:48 2015 +0100
+++ b/INSTALL Thu Mar 26 23:32:21 2015 +0100
@@ -86,14 +86,17 @@
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'.
- dict - Dovecot dict lookup. The location path is a dict uri. Read
- doc/scipt-location-dict.txt for more information and examples.
- ldap - LDAP database lookup. The location path is a configuration file with
- LDAP options. Read doc/scipt-location-ldap.txt for more information
- and examples.
+ 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
@@ -144,12 +147,18 @@
The Sieve interpreter recognizes the following configuration options in the
plugin section of the config file (default values are shown if applicable):
- sieve = ~/.dovecot.sieve
+ 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 is also where the ManageSieve service will store
- the user's scripts, if supported by the location type.
+ :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
@@ -425,16 +434,15 @@
configuration and are not enabled for use by default. Refer to
doc/extensions/spamtest-virustest.txt for configuration information.
-- Vnd.dovecot.duplicate extension:
+- Duplicate extension:
- The vnd.dovecot.duplicate extension augments the Sieve filtering
- implementation with a test that allows detecting and handling duplicate
- message deliveries, e.g. as caused by mailinglists when people reply both to
- the mailinglist and the user directly.
+ 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.
- The vnd.dovecot.duplicate extension requires explicit configuration and is not
- enabled for use by default. Refer to doc/extensions/vnd.dovecot.duplicate.txt
- for configuration information.
+ Refer to doc/extensions/vnd.dovecot.duplicate.txt for configuration
+ information.
- Extprograms plugin;
vnd.dovovecot.pipe, vnd.dovecot.filter, vnd.dovecot.execute extensions:
diff -r 971969e1671d -r 5547d6d1778c doc/extensions/duplicate.txt
--- a/doc/extensions/duplicate.txt Thu Mar 19 23:27:48 2015 +0100
+++ b/doc/extensions/duplicate.txt Thu Mar 26 23:32:21 2015 +0100
@@ -23,8 +23,6 @@
Configuration
=============
-The "duplicate" extension is not enabled by default.
-
The following configuration settings are used:
sieve_duplicate_default_period = 14d
@@ -40,8 +38,6 @@
plugin {
sieve = ~/.dovecot.sieve
- sieve_extensions = +vnd.dovecot.duplicate
-
sieve_duplicate_default_period = 1h
sieve_duplicate_max_period = 1d
}d
diff -r 971969e1671d -r 5547d6d1778c doc/locations/dict.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/locations/dict.txt Thu Mar 26 23:32:21 2015 +0100
@@ -0,0 +1,145 @@
+DICT Sieve Script Location Type
+
+Description
+===========
+
+This location type is used to retrieve Sieve scripts from a Dovecot dict lookup.
+Such dictionaries use a file or an SQL database as backend. Refer to the Dovecot
+dict documentation for more information on dict lookups.
+
+To retrieve a Sieve script from the dict database, two lookups are performed.
+First, the name of the Sieve script is queried from the dict path
+`/priv/sieve/name/<name>'. If the Sieve script exists, this yields a data ID
+which in turn points to the actual script text. The script text is subsequently
+queried from the dict path '/priv/sieve/data/<dict-id>'.
+
+The second query is only necessary when no compiled binary is available or when
+the script has changed and needs to be recompiled. The data ID is used to detect
+changes in the dict's underlying database. Changing a Sieve script in the
+database must be done by first making a new script data item with a new data ID.
+Then, the mapping from name to data ID must be changed to point to the new
+script text, thereby changing the data ID returned from the name lookup, i.e.
+the first query mentioned above. Script binaries compiled from Sieve scripts
+contained in a dict database record the data ID. While the data ID contained in
+the binary is identical to the one returned from the dict lookup, the binary is
+assumed up-to-date. When the returned data ID is different, the new script text
+is retrieved using the second query and compiled into a new binary containing
+the updated data ID.
+
+Note that, by default, compiled binaries are not stored at all for Sieve scripts
+retrieved from a dict database. The bindir= option needs to be specified in the
+location specification. Refer to the INSTALL file for more general information
+about configuration of script locations.
+
+Configuration
+=============
+
+The script location syntax is specified as follows:
+
+location = dict:<dict-uri>[;<option>[=<value>][;...]]
+
+The following additional options are recognized:
+
+ user=<username>
+ Overrides the user name used for the dict lookup. Normally, the name of the
+ user running the Sieve interpreter is used.
+
+If the name of the Script is left unspecified and not otherwise provided by the
+Sieve interpreter, the name defaults to `default'.
+
+Examples
+========
+
+Example 1
+---------
+
+This example is mainly useful for performing a quick test of the dict location
+configuration without configuring an actual (SQL) database. For this example, a
+very simple file dict is assumed to be contained in the file
+/etc/dovecot/sieve.dict:
+
+priv/sieve/name/keep
+1
+priv/sieve/name/discard
+2
+priv/sieve/name/spam
+3
+priv/sieve/data/1
+keep;
+priv/sieve/data/2
+discard;
+priv/sieve/data/3
+require ["fileinto", "mailbox"]; fileinto :create "spam";
+
+To use this file dict for the main active script, you can change the
+configuration as follows (e.g. in /etc/dovecot/conf.d/90-sieve.conf):
+
+plugin {
+ sieve = dict:file:/etc/dovecot/sieve.dict;name=keep;bindir=~/.sieve-bin
+}
+
+The Sieve script named "keep" is retrieved from the file dict as the main
+script. Binaries are stored in the ~/.sieve-bin directory.
+
+Example 2
+---------
+
+This example uses a PostgreSQL database. Our database contains the following
+table:
+
+CREATE TABLE user_sieve_scripts (
+ id integer,
+ username varchar(40),
+ script_name varchar(256),
+ script_data varchar(10240),
+
+ PRIMARY KEY (id),
+ UNIQUE(username, script_name)
+);
+
+We create a file /etc/dovecot/dict-sieve-sql.conf with the following content:
+
+connect = host=localhost dbname=dovecot user=dovecot password=password
+map {
+ pattern = priv/sieve/name/$script_name
+ table = user_sieve_scripts
+ username_field = username
+ value_field = id
+ fields {
+ script_name = $script_name
+ }
+}
+map {
+ pattern = priv/sieve/data/$id
+ table = user_sieve_scripts
+ username_field = username
+ value_field = script_data
+ fields {
+ id = $id
+ }
+}
+
+These are the mappings used by the SQL dict. The first mapping is the name query
+that yields the id of the Sieve script. The second mapping is the query used to
+retrieve the Sieve script itself.
+
+Much like the dict configuration for mailbox quota, it is often not possible to
+directly use an SQL dict because the SQL drivers are not linked to binaries such
+as dovecot-lda and lmtp. You need to use the dict proxy service. Add the dict
+URI to the dict section (typically located in your main dovecot.conf):
+
+dict {
+ sieve = pgsql:/etc/dovecot/dict-sieve-sql.conf.ext
+}
+
+To use this SQL dict for the main active script, you can change the
+configuration as follows (e.g. in /etc/dovecot/conf.d/90-sieve.conf):
+
+plugin {
+ sieve = dict:proxy::sieve;name=active;bindir=~/.sieve-bin
+}
+
+This uses the proxy dict uri `proxy::sieve'. This refers to the `sieve =' entry
+in the dict {...} section above. With this configuration, a Sieve script called
+"main" is retrieved from the SQL dict. Binaries are stored in the ~/.sieve-bin
+directory.
diff -r 971969e1671d -r 5547d6d1778c doc/locations/file.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/locations/file.txt Thu Mar 26 23:32:21 2015 +0100
@@ -0,0 +1,48 @@
+FILE Sieve Script Location Type
+
+Description
+===========
+
+This location type is used to retrieve Sieve scripts from the file system. The
+location can either point to a directory or to a regular file. If the location
+points to a directory, a script called "name" is retrieved by reading a file
+from that directory with the file name "name.sieve".
+
+When this location type is involved in a sieve_before/sieve_after script
+sequence and the location points to a directory, all files in that directory
+with a ".sieve" extension are part of the sequence. The sequence order of the
+scripts in that directory is determined by the file names, using a normal 8bit
+per-character comparison.
+
+Unless overridden using the `bindir=<path' location option, compiled binaries
+for scripts retrieved from the `file' location type are by default stored in the
+same directory as where the script file was found if possible. Refer to the
+INSTALL file for more general information about configuration of script
+locations.
+
+Configuration
+=============
+
+The script location syntax is specialized as follows:
+
+location = file:<path>[;<option>[=<value>][;...]]
+
+The following additional options are recognized:
+
+ active=<path>
+ When ManageSieve is used, one script in the storage can be active; i.e.,
+ evaluated at delivery. For the `file' location, the active script in the
+ storage directory pointed to by a symbolic link. This option configures
+ where this symbolic link is located. If the `file' location path points to
+ a regular file, this setting has no effect (and ManageSieve cannot be used).
+
+Examples
+========
+
+plugin {
+ ...
+ sieve = file:~/sieve;active=~/.dovecot.sieve
+
+ sieve_default = file:/var/lib/dovecot/;name=default
+}
+
diff -r 971969e1671d -r 5547d6d1778c doc/locations/ldap.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/locations/ldap.txt Thu Mar 26 23:32:21 2015 +0100
More information about the dovecot-cvs
mailing list