← Back to branch summary

~ubuntu-branches/ubuntu/utopic/dovecot/utopic-proposed

« back to all changes in this revision

Viewing changes to pigeonhole/doc/plugins/sieve_extprograms.txt

  • Committer: Package Import Robot
  • Author(s): James Page
  • Date: 2014-01-08 09:35:49 UTC
  • mfrom: (4.1.35 sid)
  • Revision ID: package-import@ubuntu.com-20140108093549-i72o93pux8p0dlaf
Tags: 1:2.2.9-1ubuntu1
* Merge from Debian unstable, remaining changes:
  + Add mail-stack-delivery package:
    - Update d/rules
    - d/control: convert existing dovecot-postfix package to a dummy
      package and add new mail-stack-delivery package.
    - Update maintainer scripts.
    - Rename d/dovecot-postfix.* to debian/mail-stack-delivery.*
    - d/mail-stack-delivery.preinst: Move previously installed backups and
      config files to a new package namespace.
    - d/mail-stack-delivery.prerm: Added to handle downgrades.
  + Use Snakeoil SSL certificates by default:
    - d/control: Depend on ssl-cert.
    - d/dovecot-core.postinst: Relax grep for SSL_* a bit.
  + Add autopkgtest to debian/tests/*.
  + Add ufw integration:
    - d/dovecot-core.ufw.profile: new ufw profile.
    - d/rules: install profile in dovecot-core.
    - d/control: dovecot-core - suggest ufw.
  + d/dovecot-core.dirs: Added usr/share/doc/dovecot-core
  + Add apport hook:
    - d/rules, d/source_dovecot.py
  + Add upstart job:
    - d/rules, d/dovecot-core.dovecot.upstart, d/control,
      d/dovecot-core.dirs, dovecot-imapd.{postrm, postinst, prerm},
      d/dovecot-pop3d.{postinst, postrm, prerm}.
      d/mail-stack-deliver.postinst: Convert init script to upstart.
  + Use the autotools-dev dh addon to update config.guess/config.sub for
    arm64.
* Dropped changes, included in Debian:
  - Update Dovecot name to reflect distribution in login greeting.
  - Update Drac plugin for >= 2.0.0 support.
* d/control: Drop dovecot-postfix package as its no longer required.

Show diffs side-by-side

added added

removed removed

Lines of Context:
pigeonhole/doc/plugins/sieve_extprograms.txt
 
1
Sieve Extprograms plugin for Pigeonhole
 
2
 
 
3
Relevant specifications
 
4
=======================
 
5
 
 
6
        doc/rfc/spec-bosch-sieve-extprograms.txt
 
7
 
 
8
Introduction
 
9
============
 
10
 
 
11
Sieve (RFC 5228) is a highly extensible machine language specifically tailored
 
12
for internet message filtering. For the Dovecot Secure IMAP server, Sieve
 
13
support is provided by the Pigeonhole Sieve plugin. This package includes a
 
14
plugin for Pigeonhole called "sieve_extprograms", which extends the Sieve 
 
15
filtering implementation with action commands for invoking a predefined set of
 
16
external programs. Messages can be piped to or filtered through those programs
 
17
and string data can be input to and retrieved from those programs.
 
18
 
 
19
The Sieve language is explicitly designed to be powerful enough to be useful yet
 
20
limited in order to allow for a safe server-side filtering system. Therefore,
 
21
the base specification of the language makes it impossible for users to do
 
22
anything more complex (and dangerous) than write simple mail filters. One of the
 
23
consequences of this security-minded design is that users cannot execute
 
24
external programs from their mail filter. Particularly for server-side filtering
 
25
setups in which mail accounts have no corresponding system account, allowing the
 
26
execution of arbitrary programs from the mail filter can be a significant
 
27
security risk. However, such functionality can also be very useful, for instance
 
28
to easily implement a custom action or external effect that Sieve normally
 
29
cannot provide.
 
30
 
 
31
The "sieve_extprograms" plugin provides an extension to the Sieve filtering
 
32
language adding new action commands for invoking a predefined set of external
 
33
programs. To mitigate the security concerns, the external programs cannot be
 
34
chosen arbitrarily; the available programs are restricted through administrator
 
35
configuration.
 
36
 
 
37
This extension is specific to the Pigeonhole Sieve implementation for the
 
38
Dovecot Secure IMAP server. It will therefore most likely not be supported by
 
39
web interfaces or GUI-based Sieve editors. This extension is primarily meant for
 
40
use in small setups or global scripts that are managed by the systems
 
41
administrator.
 
42
 
 
43
Implementation Status
 
44
---------------------
 
45
 
 
46
The "vnd.dovecot.pipe", "vnd.dovecot.filter" and "vnd.dovecot.execute" Sieve
 
47
language extensions introduced by this plugin are vendor-specific with draft
 
48
status and their implementation for Pigeonhole is experimental, which means that
 
49
the language extensions are still subject to change and that the current
 
50
implementation is not thoroughly tested.
 
51
 
 
52
Configuration
 
53
=============
 
54
 
 
55
The plugin is activated by adding it to the sieve_plugins setting:
 
56
 
 
57
sieve_plugins = sieve_extprograms
 
58
 
 
59
This plugin registers the "vnd.dovecot.pipe", "vnd.dovecot.filter" and
 
60
"vnd.dovecot.execute" extensions with the Sieve interpreter. However, these
 
61
extensions are not enabled by default and thus need to be enabled explicitly. It
 
62
is recommended to restrict the use of these extensions to global context by
 
63
adding these to the "sieve_global_extensions" setting. If personal user scripts
 
64
also need to directly access external programs, the extensions need to be added
 
65
to the "sieve_extensions" setting. 
 
66
 
 
67
The commands introduced by the Sieve language extensions in this plugin can
 
68
directly pipe a message or string data to an external program (typically a shell
 
69
script) by forking a new process. Alternatively, these can connect to a unix
 
70
socket behind which a Dovecot script service is listening to start the external
 
71
program, e.g. to execute as a different user or for added security.
 
72
 
 
73
The program name specified for the new Sieve "pipe", "filter" and "execute"
 
74
commands is used to find the program or socket in a configured directory.
 
75
Separate directories are specified for the sockets and the directly executed
 
76
binaries. The socket directory is searched first. Since the use of "/" in
 
77
program names is prohibited, it is not possible to build a hierarchical
 
78
structure.
 
79
 
 
80
Directly forked programs are executed with a limited set of environment
 
81
variables: HOME, USER, HOST, SENDER, RECIPIENT and ORIG_RECIPIENT. Programs
 
82
executed through the script-pipe socket service currently have no environment
 
83
set at all.
 
84
 
 
85
If a shell script is expected to read a message or string data, it must fully
 
86
read the provided input until the data ends with EOF, otherwise the Sieve action
 
87
invoking the program will fail. The action will also fail when the shell script
 
88
returns a nonzero exit code. Standard output is available for returning a
 
89
message (for the filter command) or string data (for the execute command) to the
 
90
Sieve interpreter. Standard error is written to the LDA log file. 
 
91
 
 
92
The three extensions introduced by this plugin - "vnd.dovecot.pipe",
 
93
"vnd.dovecot.filter" and "vnd.dovecot.pipe" - each have separate but similar
 
94
configuration. The settings that specify a time period are specified in
 
95
s(econds), unless followed by a d(ay), h(our) or m(inute) specifier character.
 
96
The following configuration settings are used, for which "<extension>" in the
 
97
setting name is replaced by either "pipe", "filter" or "execute" depending on
 
98
which extension is being configured.
 
99
 
 
100
sieve_<extension>_socket_dir =
 
101
  Points to a directory relative to the Dovecot base_dir where the plugin looks
 
102
  for script service sockets. 
 
103
 
 
104
sieve_<extension>_bin_dir =
 
105
  Points to a directory where the plugin looks for programs (shell scripts) to
 
106
  execute directly and pipe messages to.
 
107
 
 
108
sieve_<extension>_exec_timeout = 10s
 
109
  Configures the maximum execution time after which the program is forcefully
 
110
  terminated.
 
111
 
 
112
Examples
 
113
--------
 
114
 
 
115
Example 1: socket service for "pipe" and "execute"
 
116
 
 
117
plugin {
 
118
  sieve = ~/.dovecot.sieve
 
119
 
 
120
  sieve_plugins = sieve_extprograms
 
121
  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.execute
 
122
 
 
123
  # pipe sockets in /var/run/dovecot/sieve-pipe
 
124
  sieve_pipe_socket_dir = sieve-pipe        
 
125
 
 
126
  # execute sockets in /var/run/dovecot/sieve-execute
 
127
  sieve_execute_socket_dir = sieve-execute
 
128
}
 
129
 
 
130
service sieve-pipe-script {
 
131
  # This script is executed for each service connection
 
132
  executable = script /usr/lib/dovecot/sieve-extprograms/sieve-pipe-action.sh
 
133
 
 
134
  # use some unprivileged user for execution
 
135
  user = dovenull
 
136
 
 
137
  # socket name is program-name in Sieve (without sieve-pipe/ prefix)
 
138
  unix_listener sieve-pipe/sieve-pipe-script {
 
139
  }
 
140
}
 
141
 
 
142
service sieve-execute-action {
 
143
  # This script is executed for each service connection
 
144
  executable = script /usr/lib/dovecot/sieve-extprograms/sieve-execute-action.sh
 
145
 
 
146
  # use some unprivileged user for execution
 
147
  user = dovenull
 
148
 
 
149
  # socket name is program-name in Sieve (without sieve-execute/ prefix)
 
150
  unix_listener sieve-execute/sieve-execute-action {
 
151
  }
 
152
}
 
153
 
 
154
Example 2: direct execution for "pipe" and "filter"
 
155
 
 
156
plugin {
 
157
  sieve = ~/.dovecot.sieve
 
158
 
 
159
  sieve_plugins = sieve_extprograms
 
160
  sieve_global_extensions = +vnd.dovecot.pipe +vnd.dovecot.filter
 
161
 
 
162
  # This directory contains the scripts that are available for the pipe command.
 
163
  sieve_pipe_bin_dir = /usr/lib/dovecot/sieve-pipe
 
164
 
 
165
  # This directory contains the scripts that are available for the filter
 
166
  # command.
 
167
  sieve_filter_bin_dir = /usr/lib/dovecot/sieve-filter
 
168
}
 
169
 
 
170
Using
 
171
=====
 
172
 
 
173
Refer to doc/rfc/spec-bosch-sieve-extprograms.txt for a specification of the
 
174
Sieve language extensions.
 
175