WWWWWW

Current Directory: /usr/share/doc/dovecot/sieve/plugins
Viewing File: /usr/share/doc/dovecot/sieve/plugins/sieve_extprograms.txt
Sieve Extprograms plugin for Pigeonhole

Relevant specifications
=======================

	doc/rfc/spec-bosch-sieve-extprograms.txt

Introduction
============

Sieve (RFC 5228) is a highly extensible machine language specifically tailored
for internet message filtering. For the Dovecot Secure IMAP server, Sieve
support is provided by the Pigeonhole Sieve plugin. This package includes a
plugin for Pigeonhole called "sieve_extprograms", which extends the Sieve 
filtering implementation with 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.

The Sieve language is explicitly designed to be powerful enough to be useful yet
limited in order to allow for a safe server-side filtering system. Therefore,
the base specification of the language makes it impossible for users to do
anything more complex (and dangerous) than write simple mail filters. One of the
consequences of this security-minded design is that users cannot execute
external programs from their mail filter. Particularly for server-side filtering
setups in which mail accounts have no corresponding system account, allowing the
execution of arbitrary programs from the mail filter can be a significant
security risk. However, such functionality can also be very useful, for instance
to easily implement a custom action or external effect that Sieve normally
cannot provide.

The "sieve_extprograms" plugin provides an extension to the Sieve filtering
language adding new action commands for invoking a predefined set of external
programs. To mitigate the security concerns, the external programs cannot be
chosen arbitrarily; the available programs are restricted through administrator
configuration.

This extension is specific to the Pigeonhole Sieve implementation for the
Dovecot Secure IMAP server. It will therefore most likely not be supported by
web interfaces or GUI-based Sieve editors. This extension is primarily meant for
use in small setups or global scripts that are managed by the systems
administrator.

Implementation Status
---------------------

The "vnd.dovecot.pipe", "vnd.dovecot.filter" and "vnd.dovecot.execute" Sieve
language extensions introduced by this plugin are vendor-specific with draft
status and their implementation for Pigeonhole is experimental, which means that
the language extensions are still subject to change and that the current
implementation is not thoroughly tested.

Configuration
=============

The plugin is activated by adding it to the sieve_plugins setting:

sieve_plugins = sieve_extprograms

This plugin registers the "vnd.dovecot.pipe", "vnd.dovecot.filter" and
"vnd.dovecot.execute" extensions with the Sieve interpreter. However, these
extensions are not enabled by default and thus need to be enabled explicitly. It
is recommended to restrict the use of these extensions to global context by
adding these to the "sieve_global_extensions" setting. If personal user scripts
also need to directly access external programs, the extensions need to be added
to the "sieve_extensions" setting. 

The commands introduced by the Sieve language extensions in this plugin can
directly pipe a message or string data to an external program (typically a shell
script) by forking a new process. Alternatively, these can connect to a unix
socket behind which a Dovecot script service is listening to start the external
program, e.g. to execute as a different user or for added security.

The program name specified for the new Sieve "pipe", "filter" and "execute"
commands is used to find the program or socket in a configured directory.
Separate directories are specified for the sockets and the directly executed
binaries. The socket directory is searched first. Since the use of "/" in
program names is prohibited, it is not possible to build a hierarchical
structure.

Directly forked programs are executed with a limited set of environment
variables: HOME, USER, HOST, SENDER, RECIPIENT and ORIG_RECIPIENT. Programs
executed through the script-pipe socket service currently have no environment
set at all.

If a shell script is expected to read a message or string data, it must fully
read the provided input until the data ends with EOF, otherwise the Sieve action
invoking the program will fail. The action will also fail when the shell script
returns a nonzero exit code. Standard output is available for returning a
message (for the filter command) or string data (for the execute command) to the
Sieve interpreter. Standard error is written to the LDA log file. 

The three extensions introduced by this plugin - "vnd.dovecot.pipe",
"vnd.dovecot.filter" and "vnd.dovecot.pipe" - each have separate but similar
configuration. The settings that specify a time period are specified in
s(econds), unless followed by a d(ay), h(our) or m(inute) specifier character.
The following configuration settings are used, for which "<extension>" in the
setting name is replaced by either "pipe", "filter" or "execute" depending on
which extension is being configured.

sieve_<extension>_socket_dir =
  Points to a directory relative to the Dovecot base_dir where the plugin looks
  for script service sockets. 

sieve_<extension>_bin_dir =
  Points to a directory where the plugin looks for programs (shell scripts) to
  execute directly and pipe messages to.

sieve_<extension>_exec_timeout = 10s
  Configures the maximum execution time after which the program is forcibly
  terminated.

sieve_<extension>_input_eol = crlf
  Determines the end-of-line character sequence used for the data piped to
  external programs. The default is currently "crlf", which represents a
  sequence of the carriage return (CR) and line feed (LF) characters. This
  matches the Internet Message Format (RFC5322) and what Sieve itself uses as a
  line ending. Set this setting to "lf" to use a single LF character instead.

Examples
--------

Example 1: socket service for "pipe" and "execute"

plugin {
  sieve = ~/.dovecot.sieve

  sieve_plugins = sieve_extprograms
  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.execute

  # pipe sockets in /var/run/dovecot/sieve-pipe
  sieve_pipe_socket_dir = sieve-pipe        

  # execute sockets in /var/run/dovecot/sieve-execute
  sieve_execute_socket_dir = sieve-execute
}

service sieve-pipe-script {
  # This script is executed for each service connection
  executable = script /usr/lib/dovecot/sieve-extprograms/sieve-pipe-action.sh

  # use some unprivileged user for execution
  user = dovenull

  # socket name is program-name in Sieve (without sieve-pipe/ prefix)
  unix_listener sieve-pipe/sieve-pipe-script {
  }
}

service sieve-execute-action {
  # This script is executed for each service connection
  executable = script /usr/lib/dovecot/sieve-extprograms/sieve-execute-action.sh

  # use some unprivileged user for execution
  user = dovenull

  # socket name is program-name in Sieve (without sieve-execute/ prefix)
  unix_listener sieve-execute/sieve-execute-action {
  }
}

Example 2: direct execution for "pipe" and "filter"

plugin {
  sieve = ~/.dovecot.sieve

  sieve_plugins = sieve_extprograms
  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.filter

  # This directory contains the scripts that are available for the pipe command.
  sieve_pipe_bin_dir = /usr/lib/dovecot/sieve-pipe

  # This directory contains the scripts that are available for the filter
  # command.
  sieve_filter_bin_dir = /usr/lib/dovecot/sieve-filter
}

Using
=====

Refer to doc/rfc/spec-bosch-sieve-extprograms.txt for a specification of the
Sieve language extensions.
F1l3 Manager
