summaryrefslogtreecommitdiffstats
path: root/doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:51:24 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-28 09:51:24 +0000
commitf7548d6d28c313cf80e6f3ef89aed16a19815df1 (patch)
treea3f6f2a3f247293bee59ecd28e8cd8ceb6ca064a /doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt
parentInitial commit. (diff)
downloaddovecot-upstream.tar.xz
dovecot-upstream.zip
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>
Diffstat (limited to 'doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt')
-rw-r--r--doc/wiki/Pigeonhole.Sieve.Plugins.Pipe.txt187
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)