Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 187 insertions, 0 deletions

diff --git a/doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt b/doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt
new file mode 100644
index 0000000..b307037
--- /dev/null
+++ b/doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt
@@ -0,0 +1,187 @@
+Pigeonhole Sieve Pipe Plugin
+============================
+
+The sieve_pipe plugin adds the vnd.dovecot.pipe extension to the Sieve language
+[http://www.sieve.info]. The extension adds a new action command for piping
+messages to a pre-defined 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 plugin is available for <Pigeonhole.txt> v0.2. This plugin is superseded
+by the <Extprograms> [Pigeonhole.Sieve.Plugins.Extprograms.txt] plugin for
+Pigeonhole v0.3 and beyond.
+
+Getting the sources
+-------------------
+
+Currently, the sources of the sieve_pipe plugin are not released, but you can
+get them from the the Mercurial repository:
+
+---%<-------------------------------------------------------------------------
+hg clone  http://hg.rename-it.nl/pigeonhole-0.2-sieve-pipe/
+---%<-------------------------------------------------------------------------
+
+Compiling
+---------
+
+If you downloaded the sources of this plugin using Mercurial, you will need to
+execute './autogen.sh' first to build the automake structure in your source
+tree. This process requires autotools and libtool to be installed.
+
+If you installed Dovecot from sources, the plugin's configure script should be
+able to find the installed 'dovecot-config' automatically, along with the
+Pigeonhole development headers:
+
+---%<-------------------------------------------------------------------------
+./configure
+make
+sudo make install
+---%<-------------------------------------------------------------------------
+
+If this doesn't work, you can use '--with-dovecot=<path>' configure option,
+where the path points to a directory containing 'dovecot-config' file. This can
+point to an installed file:
+
+---%<-------------------------------------------------------------------------
+./configure --with-dovecot=/usr/local/lib/dovecot
+make
+sudo make install
+---%<-------------------------------------------------------------------------
+
+The above example should also find the necessary Pigeonhole development headers
+implicitly. You can also compile by pointing to compiled Dovecot and Pigeonhole
+source trees:
+
+---%<-------------------------------------------------------------------------
+./configure --with-dovecot=../dovecot-2.0.0/
+--with-pigeonhole=../dovecot-2.0-pigeonhole-0.2.0
+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 of 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 of 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
+}
+---%<-------------------------------------------------------------------------
+
+Usage
+-----
+
+Sieve scripts can use the new 'vnd.dovecot.pipe' extension as follows:
+
+---%<-------------------------------------------------------------------------
+require ["vnd.dovecot.pipe"];
+
+pipe "external-program";
+---%<-------------------------------------------------------------------------
+
+Read the full specification
+[http://hg.rename-it.nl/pigeonhole-0.2-sieve-pipe/raw-file/tip/doc/rfc/spec-bosch-sieve-pipe.txt]
+for more information.
+
+Examples
+--------
+
+Example of a jabber notification notify.sieve:
+
+---%<-------------------------------------------------------------------------
+require [ "vnd.dovecot.pipe", "copy", "variables" ];
+if header :matches "subject" "*" { set "subject" "${1}"; }
+if header :matches "from" "*" { set "from" "${1}"; }
+pipe :args [ "USER@DOMAIN.TLD", "${from}", "${subject}" ] :copy :try
+"jabber_notify.sh" ;
+---%<-------------------------------------------------------------------------
+
+The jabber_notify.sh:
+
+---%<-------------------------------------------------------------------------
+USER="$1"
+FROM="$2"
+SUBJECT="$3"
+# clix accepts this as a config search directory
+# you can use clix - lua based
+# http://code.matthewwild.co.uk/clix/summary
+# or use any other jabber cmd line client that can send things
+export XDG_CONFIG_HOME=/srv/mail
+/srv/mail/clix.bin send -q --account=default --to="$USER" "New mail from
+${FROM} about ${SUBJECT}"
+# we don't care about the exit status in this case
+exit 0
+---%<-------------------------------------------------------------------------
+
+The $XDG_CONFIG_HOME/.clixrc:
+
+---%<-------------------------------------------------------------------------
+[default]
+jid=USER@DOMAIN.TLD
+password=PASSWORD
+---%<-------------------------------------------------------------------------
+
+(This file was created from the wiki on 2019-06-19 12:42)