Compiling
---------

If you downloaded this package using Mercurial, you have a script called 
autogen.sh in your source tree. You should execute that first:

./autogen.sh

After this executed successfully or when you downloaded the tarball,
configure needs to be executed with the following parameters:

  --with-dovecot=<path>
    Path to the dovecot-config file. This can either be a compiled dovecot
    source tree or point to the location where the dovecot-config file is
    installed on your system (typically in the $prefix/lib/dovecot directory).

  --with-pigeonhole=<path>	
    Path to the Pigeonhole headers. If the --with-dovecot parameter points to
    the path where dovecot-config is installed on your system, this parameter is
    usually not necessary. This parameter may either point to the a Pigeonhole
    source tree or the location where the Pigeonhole headers are installed on
    your system.

For example, when compiling against sources:

./configure --with-dovecot=../dovecot-1.2 --with-pigeonhole=../dovecot-1.2-sieve

Or when compiling against a Dovecot installation:

./configure --with-dovecot=/usr/local/lib/dovecot/

As usual, to compile and install, execute the following:

make
sudo make install 

Configuration
-------------

This package builds and installs the sieve_pipe plugin for Pigeonhole Sieve. The
plugin is activated by adding it to the sieve_plugins setting:

sieve_plugins = sieve_pipe

The plugin can directly pipe a message to an external program (typically a
shell script) by forking a new process. Alternatively, it 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 Sieve "pipe" command 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 Sieve "pipe" command refuses "/" in program names,
it is not possible to build a hierarchical structure.

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

The following configuration settings are used by the sieve_pipe plugin:

sieve_pipe_socket_dir =
  Points to a directory relative to the Dovecot base_dir where the sieve_pipe
  plugin looks for the sockets. 

sieve_pipe_bin_dir =
  Points to a directory where the sieve_pipe plugin looks for programs (shell
  scripts) to execute directly and pipe messages to.

Example 1: socket service

plugin {
  sieve = ~/.dovecot.sieve

  sieve_plugins = sieve_pipe

  sieve_pipe_socket_dir = sieve-pipe
}

service sieve-custom-action {
  executable = script-pipe /usr/lib/dovecot/sieve-pipe/sieve-custom-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-custom-action {
  }
}

Example 2: direct execution

plugin {
  sieve = ~/.dovecot.sieve

  sieve_plugins = sieve_pipe

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