diff options
Diffstat (limited to 'doc/wiki/Pigeonhole.Sieve.Configuration.Dict.txt')
| -rw-r--r-- | doc/wiki/Pigeonhole.Sieve.Configuration.Dict.txt | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/doc/wiki/Pigeonhole.Sieve.Configuration.Dict.txt b/doc/wiki/Pigeonhole.Sieve.Configuration.Dict.txt new file mode 100644 index 0000000..6ec686f --- /dev/null +++ b/doc/wiki/Pigeonhole.Sieve.Configuration.Dict.txt @@ -0,0 +1,187 @@ +Pigeonhole Sieve: Dict Lookup for Sieve Scripts +=============================================== + +Sieve scripts can be obtained from a number of different <types of locations> +[Pigeonhole.Sieve.Configuration.txt]. This page shows how to retrieve them from +a Dovecot dictionary [http://wiki2.dovecot.org/Dictionary] (abbreviated as +'dict'), which can have either a file or database backend. + +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=<path>' option needs to be +specified in the <location specification> [Pigeonhole.Sieve.Configuration.txt]. + +Configuration +------------- + +The script location syntax is specified as follows: + +---%<------------------------------------------------------------------------- +sieve = 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 is not otherwise provided by +the Sieve interpreter, the name defaults to `default'. + +Examples +-------- + +Using a flat file backend +------------------------- + +Flat file example 1 +------------------- + +To retrieve the Sieve script named "keep" from the dict file +/etc/dovecot/sieve.dict: + +---%<------------------------------------------------------------------------- +sieve = dict:file:/etc/dovecot/sieve.dict;name=keep +---%<------------------------------------------------------------------------- + +The file /etc/dovecot/sieve.dict might look like this. Note that with the above +configuration, only the "keep" script will be used. + +---%<------------------------------------------------------------------------- +priv/sieve/name/keep +1 +priv/sieve/name/discard +2 +priv/sieve/data/1 +keep; +priv/sieve/data/2 +discard; +---%<------------------------------------------------------------------------- + +Flat file example 2 +------------------- + +Following on from example 1, a more advanced script. This notifies an external +email address when new mail has arrived. Note that the script all needs to be +on one line. + +---%<------------------------------------------------------------------------- +priv/sieve/name/notify +5 +priv/sieve/data/5 +require ["enotify", "variables"]; if header :matches "From" "*" { set "from" +"${1}";} notify :importance "3" :message "New email from ${from}" +"mailto:other@domain.com?body=New%20email%20has%20arrived."; +---%<------------------------------------------------------------------------- + +Using a SQL backend +------------------- + +For greater flexibility, it's possible to use a SQL backend for your dict +scripts. First, set up a configuration file (such as +/etc/dovecot/dict-sieve-sql.conf) with your database configuration. This should +consist of the following parts: + +---%<------------------------------------------------------------------------- +# The database connection params +connect = host=localhost dbname=dovecot user=dovecot password=password + +# The name mapping that yields the ID of the Sieve script +map { + pattern = priv/sieve/name/$script_name # The name of the script, as per +the "sieve" config parameter + table = user_sieve_scripts # The database table + username_field = username # The field in the table to query +on + value_field = id # The field which contains the +return value of the script ID + fields { + script_name = $script_name # FIXME: The other database field +to query? + } +} + +# The name mapping that yields the script content from ID +{ + pattern = priv/sieve/data/$id # The ID, obtained from above + table = user_sieve_scripts # The database table + username_field = username # The field in the table to query + value_field = script_data # The field which contains the +script + fields { + id = $id # FIXME: The other database field +to query? + } +} +---%<------------------------------------------------------------------------- + +Next, create a dict proxy service. Normally in /etc/dovecot/dovecot.conf: + +---%<------------------------------------------------------------------------- +dict { + sieve = pgsql:/etc/dovecot/dict-sieve-sql.conf.ext +} +---%<------------------------------------------------------------------------- + +Finally, configure Sieve to check the dict (e.g. in +/etc/dovecot/conf.d/90-sieve.conf). This looks up a script called "active" in +the database. + +---%<------------------------------------------------------------------------- +plugin { + sieve = dict:proxy::sieve;name=active +} +---%<------------------------------------------------------------------------- + +As with the flat file, the database query will need to return the Sieve script +all in one line, otherwise the subsequent lines will be ignored. + +Note: you might need to <configure the proxy permissions> [Dict.txt] + +Caching the compiled Sieve binaries +----------------------------------- + +With the configuration described above, the Sieve binaries will be compiled +each time they are called. To improve performance, it is preferable to cache +them, which can be done using the bindir parameter, which is added to the Sieve +configuration. For example: + +---%<------------------------------------------------------------------------- +{ + sieve = dict:file:/etc/dovecot/sieve.dict;name=keep;bindir=~/.sieve-bin +} +---%<------------------------------------------------------------------------- + +Or: + +---%<------------------------------------------------------------------------- +{ + sieve = +dict:file:/etc/dovecot/sieve.dict;name=keep;bindir=/var/sieve-scripts/%u +} +---%<------------------------------------------------------------------------- + +*Note:* Sieve uses the ID number as its cache index and to detect the need to +compile. Therefore, if a script is changed, then its ID must also be changed +for it to be reloaded. + +(This file was created from the wiki on 2019-06-19 12:42) |