~ubuntu-dev/ubuntu/lucid/dovecot/lucid-201002101901

« back to all changes in this revision

Viewing changes to doc/wiki/ManageSieve.txt

  • Committer: Chuck Short
  • Date: 2010-01-21 20:21:25 UTC
  • mfrom: (4.1.11 squeeze)
  • Revision ID: zulcss@ubuntu.com-20100121202125-pme73o491kfwj5nc
* Merge from debian testing, remaining changes:
  + Add new binary pkg dovecot-postfix that integrates postfix and dovecot
    automatically: (LP: #164837)
  + debian/control:
    - add new binary with short description
    - set Architecture all for dovecot-postfix (LP: #329878)
  + debian/dovecot-postfix.postinst:
    - create initial certificate symlinks to snakeoil.
    - set up postfix with postconf to:
      - use Maildir/ as the default mailbox.
      - use dovecot as the sasl authentication server.
      - use dovecot LDA (deliver).
      - use tls for smtp{d} services.
    - fix certificates paths in postfix' main.cf
    - add reject_unauth_destination to postfix' recipient restrictions
    - add reject_unknown_sender_domain to postfix' sender restriction
    - rename configuration name on remove, delete on purge
    - restart dovecot after linking certificates
    - handle use case when postfix is unconfigurated
  + debian/dovecot-postfix.dirs: create backup directory for postfix's config
    configuration
  + restart postfix and dovecot.
  + debian/dovecot-postfix.postrm:
    - remove all dovecot related configuration from postfix.
    - restart postfix and dovecot.
  + debian/dovecot-common.init:
    - check if /etc/dovecot/dovecot-postfix.conf exists and use it
      as the configuration file if so.
  + debian/patches/warning-ubuntu-postfix.dpatch
    - add warning about dovecot-postfix.conf in dovecot default
      configuration file
  + debian/patches/dovecot-postfix.conf.diff:
    - Ubuntu server custom changes to the default dovecot configuration for
      better interfation with postfix.
    - enable sieve plugin.
    - Ubuntu server custom changes to the default dovecot configuration for
      better integration with postfix:
      - enable imap, pop3, imaps, pop3s and managesieve by default.
      - enable dovecot LDA (deliver).
      - enable SASL auth socket in postfix private directory
   + debian/rules:
     - copy, patch and install dovecot-postfix.conf in /etc/dovecot/.
     - build architecure independent packages too
   + Use Snakeoil SSL certificates by default.
     - debian/control: Depend on ssl-cert.
     - debian/patches/ssl-cert-snakeoil.dpatch: Change default SSL cert
       paths to snakeoil.
     - debian/dovecot-common.postinst: Relax grep for SSL_* a bit.
   + Add autopkgtest to debian/tests/*.
   + Fast TearDown: Update the lsb init header to not stop in level 6.
   + Add ufw integration:
     - Created debian/dovecot-common.ufw.profile.
     - debian/rules: install profile.
     - debian/control: suggest ufw.
   + debian/{control,rules}: enable PIE hardening.
   + dovecot-imapd, dovecot-pop3: Replaces dovecot-common (<< 1:1.1). (LP: #254721)
   + debian/control: Update Vcs-* headers.
   + Add SMTP-AUTH support for Outlook (login auth mechanism)
* New upstream release.
* debian/patches/gold-fix.patch: Removed. Fixed upstream.
* Moved libexec to lib corrections in dovecot-managesieve.patch and
  dovecot-managesieve-dist.patch to dovecot-example.patch
* debian/patches/dovecot-mboxlocking.patch: Regenerated to avoid FTBFS
  when quilt isn't installed.
* debian/patches/quota-mountpoint.patch: Removed. Not needed anymore.
* debian/patches/dovecot-quota.patch: Removed. Quotas aren't properly
  enabled unless mail_plugins = quota imap_quota.
* debian/patches/gold-fix.patch: Fixed configure script to build even
  with binutils-gold or --no-add-needed linker flag (Closes: #554306)
* debian/dovecot-common.init: fixed LSB headers. Thanks to Pascal Volk.
  (Closes: #558040)
* debian/changelog: added CVE references to previous changelog entry.
* debian/rules: checked up the build system. It's not fragile anymore.
  (Closes: 493803)
* debian/dovecot-common.postinst: Now invoking dpkg-reconfigure
  on dovecot-common is enough to generate new certificates
  if the previous ones were removed. (Closes: #545582)
* debian/rules: No longer install convert-tool in /usr/bin.
  It isn't an user utility and it should stay in /usr/lib/dovecot
  like all other similar tool.
* New upstream release. (Closes: #557601)
* [SECURITY] Fixes local information disclosure and denial of service.
  (see: http://www.dovecot.org/list/dovecot-news/2009-November/000143.html
  and CVE-2009-3897)
* Added myself to uploaders.
* Switched to the new source format "3.0 (quilt)":
  - removed dpatch from build-depends
  - removed debian/README.source because now we use only standard
    dpkg features
  - regenerated all patches
* Prepared to switch to multi-origin source:
  - recreated dovecot-libsieve.patch and dovecot-managesieve-dist.patch
    starting from the upstream tarball
  - removed all autotools related build-depends and build-conflict
  - renamed dovecot-libsieve and dovecot-managesieve directories
    to libsieve and managesieve.
* debian/rules: Moved the configuration of libsieve and managesieve from
  the build phase to the configuration phase
* Added dovecot-dbg package  with debugging symbols.  Thanks Stephan Bosch.
  (Closes: #554710)
* Fixed some stray libexec'isms in the default configuration.
* New upstream release.
* debian/dovecot-common.init:
  - use $CONF when starting the daemon. (Closes: #549944)
  - always output start/stop messages. (Closes: #523810)

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
1
Dovecot ManageSieve Server
2
2
==========================
3
3
 
4
 
Contents
5
 
 
6
 
 
7
 
 1. Dovecot ManageSieve Server
8
 
 
9
 
     1. Introduction
10
 
 
11
 
     2. Versions and Downloading
12
 
 
13
 
         1. Tarball releases
14
 
 
15
 
         2. Mercurial repositories
16
 
 
17
 
     3. Patching Dovecot
18
 
 
19
 
         1. v1.0
20
 
 
21
 
         2. v1.1/v1.2
22
 
 
23
 
         3. Mercurial
24
 
 
25
 
     4. Compiling
26
 
 
27
 
         1. v1.0
28
 
 
29
 
         2. v1.1/v1.2
30
 
 
31
 
     5. Configuring
32
 
 
33
 
         1. Proxy
34
 
 
35
 
     6. Troubleshooting
36
 
 
37
 
         1. Manual Login and Script Upload
38
 
 
39
 
         2. Manual TLS Login
40
 
 
41
 
         3. Client Problems
42
 
 
43
 
     7. Known Issues
44
 
 
45
 
     8. Contact Info
46
 
 
47
 
Introduction
48
 
------------
49
 
 
50
 
The <Sieve plugin> [LDA.Sieve.txt] for Dovecot's /*<deliver> [LDA.txt]*/ LDA
51
 
expects a user's Sieve script to reside somewhere in the user's directory
52
 
(~/.dovecot.sieve by default). If the user is to be able to change his sieve
53
 
script, he needs shell or FTP access to his home directory, which is not always
54
 
desirable. This is especially applicable to mail servers with virtual users. As
55
 
a solution, theManageSieve protocol was proposed to manage sieve scripts on the
56
 
server without the need for direct file system access by the users.
57
 
Additionally, the Sieve scripts are compiled before they are installed, making
58
 
sure that the uploaded script is valid. This prevents a user from inadvertently
59
 
installing a broken Sieve script. The protocol specification
60
 
[http://tools.ietf.org/id/draft-martin-managesieve-12.txt] still has a draft
61
 
status, but it is already supported by quite a few (web)mail clients. Dovecot
62
 
now supportsManageSieve by means of an external patch and package.
63
 
Alternatively, an external python-based daemon called pysieved
64
 
[http://woozle.org/~neale/src/pysieved/] written by Neale Pickett can be used,
65
 
but this page only describes the native Dovecot implementation.
66
 
 
67
 
Versions and Downloading
68
 
------------------------
69
 
 
70
 
The ManageSieve daemon is available for Dovecot versions past and including
71
 
1.0. There is an important architectural difference between v1.0 and the later
72
 
implementations however. The v1.0 version is a very large patch that includes
73
 
another copy of the CMU Sieve library as used by deliver's<Sieve plugin>
74
 
[LDA.Sieve.txt]. In contrast, the v1.1 and later versions are largely
75
 
implemented as an external package with a small patch to enableManageSieve
76
 
service support in Dovecot itself. This means that these newer implementations
77
 
no longer include another copy of the CMU Sieve library: these use the Sieve
78
 
plugin package for compilation against the Sieve library. With the advent of
79
 
Dovecot v2.0, the patch that is now still necessary for Dovecot v1.X is likely
80
 
to disappear completely, as Dovecot will then include support for custom
81
 
services.
82
 
 
83
 
Tarball releases
84
 
----------------
85
 
 
86
 
The latest released versions of the ManageSieve implementation for Dovecot can
87
 
be downloaded from the following locations:
88
 
 
89
 
 * Dovecot v1.0: http://www.rename-it.nl/dovecot/1.0/
90
 
    * Patch filenames look as follows:
91
 
      *'dovecot-1.0.'*'X'*'-MANAGESIEVE-v'*'<version>'*'.diff.gz'*
92
 
 * Dovecot v1.1: http://www.rename-it.nl/dovecot/1.1/
93
 
    * Patch filenames look as follows:
94
 
      *'dovecot-1.1.'*'X'*'-managesieve-'*'<version>'*'.diff.gz'* Package
95
 
      filenames look as
96
 
      follows:*'dovecot-1.1-managesieve-'*'<version>'*'.tar.gz'*
97
 
 * Dovecot v1.2: http://www.rename-it.nl/dovecot/1.2/
98
 
    * Patch filenames look as follows:
99
 
      *'dovecot-1.2.'*'X'*'-managesieve-'*'<version>'*'.diff.gz'* Package
100
 
      filenames look as
101
 
      follows:*'dovecot-1.2-managesieve-'*'<version>'*'.tar.gz'*
102
 
 
103
 
The tarball releases are signed with public key 0x3DFBB4F4 which can be found
104
 
at wwwkeys.pgp.net.
105
 
 
106
 
Mercurial repositories
107
 
----------------------
108
 
 
109
 
The ManageSieve implementation is maintained in a set of Mercurial
110
 
repositories, just like Dovecot itself. If you need to use the very latest
111
 
version, even before it is released as a tarball, you can download it through
112
 
Mercurial. TheManageSieve repositories for the various Dovecot versions are
113
 
publicly available at:
114
 
 
115
 
---%<-------------------------------------------------------------------------
116
 
http://hg.rename-it.nl/
117
 
---%<-------------------------------------------------------------------------
118
 
 
119
 
For each Dovecot version, there is a dovecot-1.X-managesieve and a
120
 
dovecot-1.X-managesieve-patch repository. The -patch repositories contain the
121
 
patches against the various dovecot versions. These are so-called Mercurial
122
 
Queues (MQ) repositories. This provides an easy (quilt-like) means to manage
123
 
patches over an upstream source repository like the one that exists for
124
 
Dovecot. The patches are managed in a repository called 'patches' below the .hg
125
 
directory in your main repository. Currently, these MQ repositories only have
126
 
the managesieve.patch, which is the actual patch that is refreshed and released
127
 
each time Timo makes a new Dovecot release. The dovecot-1.x-managesieve
128
 
repositories contain the actualManageSieve implementation. As explained before,
129
 
this is missing for v1.0.
130
 
 
131
 
Using these repositories is explained in the next two sections that deal with
132
 
patching the Dovecot tree and compiling Dovecot andManageSieve.
133
 
 
134
 
Patching Dovecot
135
 
----------------
136
 
 
137
 
Applying the patch to Dovecot varies a little between the different versions.
138
 
Downloading from Mercurial is a special case.
139
 
 
140
 
v1.0
141
 
----
142
 
 
143
 
As shown above, the ManageSieve implementation for Dovecot v1.0 consists solely
144
 
of a large patch. You need to apply the downloaded '.diff.gz' patch to your
145
 
'dovecot-1.0' source tree. This is achieved by executing the following command
146
 
line inside the source tree (''../patchfile.diff.gz'' must be substituted with
147
 
the location of the patch file you downloaded):
148
 
 
149
 
---%<-------------------------------------------------------------------------
150
 
gzip -dc ../pathfile.diff.gz | patch -p1
151
 
---%<-------------------------------------------------------------------------
152
 
 
153
 
Compiling the patched sources is described in the next section.
154
 
 
155
 
v1.1/v1.2
156
 
---------
157
 
 
158
 
The ManageSieve implementations for v1.1 and v1.2 consist of a patch in
159
 
'.diff.gz' format and a separate '.tar.gz' package. You first need to patch and
160
 
compile the Dovecot sources. Applying the patch is achieved by executing the
161
 
following command line inside the dovecot source tree (''../patchfile.diff.gz''
162
 
must be substituted with the location of the patch file you downloaded):
163
 
 
164
 
---%<-------------------------------------------------------------------------
165
 
gzip -dc ../pathfile.diff.gz | patch -p1
166
 
---%<-------------------------------------------------------------------------
167
 
 
168
 
Once patched, you can compile Dovecot using the usual <build process>
169
 
[CompilingSource.txt]. So, unlike the v1.0 implementation, you do not need
170
 
'autotools'.
171
 
 
172
 
Mercurial
173
 
---------
174
 
 
175
 
The following command sequence shows how to incorporate the ManageSieve patch
176
 
repository in a freshly cloned dovecot-1.1 tree:
177
 
 
178
 
---%<-------------------------------------------------------------------------
179
 
hg clone http://hg.dovecot.org/dovecot-1.1
180
 
cd dovecot-1.1
181
 
hg clone http://hg.rename-it.nl/dovecot-1.1-managesieve-patch .hg/patches
182
 
hg qpush
183
 
---%<-------------------------------------------------------------------------
184
 
 
185
 
The procedure is identical for the other dovecot versions.
186
 
 
187
 
When updating the dovecot tree it is important to unapply all patches before
188
 
performing ''hg pull'' on the dovecot tree:
189
 
 
190
 
---%<-------------------------------------------------------------------------
191
 
hg qpop --all
192
 
hg pull
193
 
hg update
194
 
hg qpush
195
 
---%<-------------------------------------------------------------------------
196
 
 
197
 
This otherwise results in a multi-head situation which can be resolved using a
198
 
''hg rollback'' or using ''hg qpop --all'' afterwards, which should gracefully
199
 
clean up the situation (never merge the heads!).
200
 
 
201
 
Updating the patch repository works as follows:
202
 
 
203
 
---%<-------------------------------------------------------------------------
204
 
hg qpop --all
205
 
hg -R .hg/patches pull
206
 
hg -R .hg/patches update
207
 
hg qpush
208
 
---%<-------------------------------------------------------------------------
209
 
 
210
 
After 'hg qpush', the dovecot repository is patched and can be compiled as
211
 
explained in the next section (don't forget ./autogen.sh for compiling dovecot
212
 
in a mercurial repository).
213
 
 
214
 
Compiling
215
 
---------
216
 
 
217
 
v1.0
218
 
----
219
 
 
220
 
After applying the patch to the v1.0 Dovecot tree, the usual './configure',
221
 
'make', 'make install' sequence is not enough. First the 'automake'/'autoconf'
222
 
structure needs to be rebuilt to include theManageSieve sources in the
223
 
compilation process. This requires 'autotools' to be installed on your system.
224
 
When you downloaded using Mercurial, you have a script called 'autogen.sh' in
225
 
your source tree and you should proceed as specified<here>
226
 
[CompilingSource.txt]. Otherwise, execute the following command inside the
227
 
dovecot source tree:
228
 
 
229
 
---%<-------------------------------------------------------------------------
230
 
autoreconf -i
231
 
---%<-------------------------------------------------------------------------
232
 
 
233
 
Afterwards, you can continue the usual <build process> [CompilingSource.txt].
234
 
 
235
 
v1.1/v1.2
236
 
---------
237
 
 
238
 
The first prerequisite for compiling the ManageSieve service is a patched and
239
 
compiled dovecot tree, as explained in the previous section. Note that the
240
 
service will compile against an unpatched dovecot tree, but keep in mind that
241
 
Dovecot will not know about the existence ofManageSieve without the patch. The
242
 
second prerequisite is a compiled dovecot-sieve source tree. Compiling the
243
 
Sieve plugin is described<here> [LDA.Sieve.txt].
244
 
 
245
 
Now that you have both a compiled dovecot and a compiled dovecot-sieve source
246
 
tree, you can continue building theManageSieve service. You can either unpack
247
 
the '.tar.gz' package somewhere or clone the Mercurial repository. When you
248
 
have cloned the repository, you must first execute ''./autogen.sh'' inside the
249
 
source tree. For both alternatives the following commands subsequently need to
250
 
be executed inside the source tree:
251
 
 
252
 
---%<-------------------------------------------------------------------------
253
 
./configure --with-dovecot=<dovecot source tree>
254
 
--with-dovecot-sieve=<dovecot-sieve source tree>
255
 
make
256
 
sudo make install
257
 
---%<-------------------------------------------------------------------------
258
 
 
259
 
The parameters to './configure' represent the following:
260
 
 
261
 
 * --with-dovecot=<path>
262
 
    * Path to the compiled dovecot tree
263
 
 * --with-dovecot-sieve=<path>
264
 
    * Path to the compiled dovecot-sieve tree
265
 
 
266
 
Configuring
267
 
-----------
268
 
 
269
 
*NOTE*: If you have used the sieve plugin before and you have '.dovecot.sieve'
270
 
files in user directories, you are advised to *make a backup first*. Although
271
 
the managesieve daemon takes care to move these files to the sieve storage
272
 
before it is substituted with a symbolic link, this is not a very well tested
273
 
operation, meaning that there is a possibility that existing sieve scripts get
274
 
lost.
275
 
 
276
 
*NOTE*: This section describes the configuration for Dovecot v1.0 and v1.1. The
277
 
newly released v1.2 version differs in terms of configuration and you are
278
 
referred to its README
279
 
[http://hg.rename-it.nl/dovecot-1.2-managesieve/file/tip/README] file for a
280
 
proper explanation.
281
 
 
282
 
Along with all other binaries that dovecot uses, the managesieve and
283
 
managesieve-login binaries are installed during 'make install'. The only thing
284
 
you need to do to activate theManageSieve support in dovecot is to add
285
 
'managesieve' to the 'protocols=' configuration line in your dovecot.conf. The
286
 
managesieve daemon will listen on port 2000 by default. As the implementation
287
 
of the managesieve daemon is largely based on the original IMAP implementation,
288
 
it is very similar in terms of configuration. In addition to most<mail daemon
289
 
config settings> [MainConfig.txt], the managesieve daemon accepts a few more.
290
 
The following settings can be configured in the 'protocol managesieve' section:
291
 
 
292
 
listen = *:2000:
293
 
  IP or host address where to listen in for connections.
294
 
 
295
 
login_executable = /usr/libexec/dovecot/managesieve-login:
296
 
  Login executable location.
297
 
 
298
 
mail_executable = /usr/libexec/dovecot/managesieve:
299
 
  managesieve executable location. See mail_executable for IMAP for examples
300
 
  how this could be changed.
301
 
 
302
 
managesieve_max_line_length = 65536:
303
 
  Maximum managesieve command line length in bytes. This setting is directly
304
 
  borrowed from IMAP. But, since long command lines are very unlikely
305
 
  withManageSieve, changing this will not be very useful.
306
 
 
307
 
sieve_storage = :
308
 
  This specifies the path to the directory where the uploaded scripts are
309
 
  stored. In terms of '%' variable substitution it is identical to dovecot's
310
 
  'mail_location' setting used by the mail protocol daemons. Scripts are stored
311
 
  as separate files with extension '.sieve', all other files are ignored when
312
 
  scripts are listed by aManageSieve client. If this setting remains
313
 
  unspecified, the 'mail_location' setting is used as explained below.
314
 
 
315
 
sieve = ~/.dovecot.sieve:
316
 
  Specifies the location of the symbolic link pointing to the active script in
317
 
  the sieve storage directory. This must match the<sieve setting used by
318
 
  deliver> [LDA.Sieve.txt]. Variable substitution with % is recognized. If a
319
 
  regular file exists at this location, it is moved to the 'sieve_storage'
320
 
  location before the symbolic link is installed. It is renamed to
321
 
  'dovecot.orig.sieve' and therefore listed as 'dovecot.orig' by a ManageSieve
322
 
  client.
323
 
 
324
 
mail_location =:
325
 
  If, for some inobvious reason, the sieve_storage remains unset, the
326
 
  managesieve daemon uses the specification of the mail_location to find out
327
 
  where to store the sieve files. However, this is provided only for backwards
328
 
  compatibility and you should always use the sieve_storage setting in stead.
329
 
 
330
 
managesieve_implementation_string = dovecot:
331
 
  To fool ManageSieve clients that are focused on CMU's timesieved you can
332
 
  specify the IMPLEMENTATION capability that the dovecot reports to clients
333
 
  (e.g. ''Cyrus timsieved v2.2.13'').
334
 
 
335
 
Scripts are stored at the location specified by the 'sieve_storage' setting.
336
 
The active sieve script is managed as a symbolic link pointing to the active
337
 
script in the sieve storage direcotory. The location of this symlink can be
338
 
specified with the 'sieve' setting. Make sure this setting is identical to what
339
 
<deliver> [LDA.txt] is using for the <Sieve plugin> [LDA.Sieve.txt]. The
340
 
default location is '~/.dovecot.sieve'. Note that if a file starting with '.'
341
 
is placed inside a Maildir, it will be recognized as a folder, so try to avoid
342
 
that.
343
 
 
344
 
The current version of the managesieve daemon places the script storage
345
 
directory in the mail folder as specified by the 'mail_location' setting if no
346
 
sieve_storage is specified. Actually, it is placed in the 'CONTROL=' directory
347
 
of 'mail_location' if specified, otherwise the 'sieve' directory is placed in
348
 
the root of the mail location. In a mail or mail control directory, scripts are
349
 
always stored in a 'sieve' subdirectory. Note that for some mail storage types
350
 
(e.g. mbox) this script directory is listed as a mail folder, so be sure to put
351
 
the sieve scripts somewhere else if you can.
352
 
 
353
 
A storage location specified by 'sieve_storage' is always generated
354
 
automatically if it does not exist (as far as the system permits the user to do
355
 
so; no root privileges are used). This is similar to the behaviour of the mail
356
 
daemons. Note that when 'mail_location' is used to specify the script storage
357
 
location, only the 'sieve' subdirectory is generated automatically.
358
 
 
359
 
The following provides an example configuration for ManageSieve in
360
 
dovecot.conf. Only sections relevant toManageSieve are shown. Refer to
361
 
dovecot-example.conf in your patched dovecot tree for a full example with
362
 
comments, but don't forget to add 'managesieve' to the 'protocols' setting if
363
 
you use it.
364
 
 
365
 
---%<-------------------------------------------------------------------------
366
 
# Start imap, pop3 and managesieve services
367
 
protocols = imap pop3 managesieve
368
 
 
369
 
protocol managesieve {
370
 
  # Specify an alternative address:port the daemon must listen on
371
 
  # (default: *:2000)
372
 
  #listen = localhost:2000
373
 
 
374
 
  sieve=~/.dovecot.sieve
375
 
  sieve_storage=~/sieve
376
 
}
377
 
---%<-------------------------------------------------------------------------
378
 
 
379
 
Proxy
380
 
-----
381
 
 
382
 
Like Dovecot's imapd, the ManageSieve login daemon supports proxying to
383
 
multiple backend servers. Although the underlying code is copied from the imapd
384
 
sources for the most part, it has someManageSieve-specifics that have not seen
385
 
much testing. The<proxy configuration wiki page>
386
 
[PasswordDatabase.ExtraFields.Proxy.txt] for POP3 and IMAP should apply to
387
 
ManageSieve as well.
388
 
 
389
 
Troubleshooting
390
 
---------------
391
 
 
392
 
Like Dovecot itself, *the ManageSieve service always logs a detailed error
393
 
message* if something goes wrong at the server (refer to <Dovecot Logging>
394
 
[Logging.txt] for more details): the logs are the first place to look if you
395
 
suspect something is wrong. To get additional debug messages in your log file,
396
 
you should set 'mail_debug=yes' in <dovecot.conf> [MainConfig.txt] (inside
397
 
'protocol managesieve {...}'if you want to enable this for managesieve only).
398
 
 
399
 
If the client commits protocol violations or sends invalid scripts, an error
400
 
response is provided to the client which is not necessarily logged on the
401
 
server. A goodManageSieve client presents such error messages to the user.
402
 
 
403
 
Manual Login and Script Upload
404
 
------------------------------
405
 
 
406
 
If you fail to login or upload scripts to the server, it is not necessarily
407
 
caused by Dovecot or your configuration. It is often best to test
408
 
yourManageSieve server manually first. This also provides you with the direct
409
 
error messages from the server without intermission of your client. If you do
410
 
not use TLS, you can connect using a simple 'telnet' or 'netcat' connection to
411
 
the configured port. Otherwise you must use a TLS-capable text protocol client
412
 
like 'gnutls-cli' as described below. Upon connection, the server presents the
413
 
initial greeting with its capabilities:
414
 
 
415
 
---%<-------------------------------------------------------------------------
416
 
"IMPLEMENTATION" "dovecot"
417
 
"SASL" "PLAIN"
418
 
"SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify
419
 
include envelope body relational regex subaddress copy"
420
 
"STARTTLS"
421
 
OK "Dovecot ready."
422
 
---%<-------------------------------------------------------------------------
423
 
 
424
 
Note that the reported 'STARTTLS' capability means that the server accepts TLS,
425
 
but, since you are using telnet/netcat, you cannot use this (refer to Manual
426
 
TLS Login below). The 'SASL' capability lists the available SASL authentication
427
 
mechanisms. If this list is empty and 'STARTTLS' is available, it probably
428
 
means that the server forces you to initiate TLS first (as dictated by
429
 
''disable_plaintext_auth=yes'' in <dovecot.conf> [MainConfig.txt]).
430
 
 
431
 
Now you need to log in. Although potentially multiple SASL mechanisms are
432
 
available, only 'PLAIN' is described here. Authentication is performed using
433
 
theManageSieve 'AUTHENTICATE' command. This command typically looks as follows
434
 
when the 'PLAIN' mechanism is used:
435
 
 
436
 
---%<-------------------------------------------------------------------------
437
 
AUTHENTICATE "PLAIN" "<base64-encoded credentials>"
438
 
---%<-------------------------------------------------------------------------
439
 
 
440
 
The credentials are the base64-encoded version of the string
441
 
'"\0<username>\0<password"' (in which '\0' represents the ASCII NUL character).
442
 
Generating this is cumbersome and a bit daunting for the novice user, so for
443
 
convenience a simple Perl script is provided to generate the 'AUTHENTICATE'
444
 
command for you. It is available here
445
 
[http://www.rename-it.nl/dovecot/utilities/sieve-auth-command.pl] and used as
446
 
follows:
447
 
 
448
 
---%<-------------------------------------------------------------------------
449
 
sieve-auth-command.pl <username> <password>
450
 
---%<-------------------------------------------------------------------------
451
 
 
452
 
The command is written to stdout and you can paste this to your protocol
453
 
session, e.g.:
454
 
 
455
 
---%<-------------------------------------------------------------------------
456
 
AUTHENTICATE "PLAIN" "AHVzZXJuYW1lAHBhc3N3b3Jk"
457
 
OK "Logged in."
458
 
---%<-------------------------------------------------------------------------
459
 
 
460
 
Now that you are logged in, you can upload a script. This is done using the
461
 
'PUTSCRIPT' command. Its first argument is the name for the script and its
462
 
second argument is a string literal. A string literal starts with a length
463
 
specification ''{<bytes>+}'' followed by a newline. Thereafter the server
464
 
expects '<bytes>' bytes of script data. The following uploads a trivial 6 byte
465
 
long sieve script that keeps every message (6th byte is the newline character):
466
 
 
467
 
---%<-------------------------------------------------------------------------
468
 
PUTSCRIPT "hutsefluts" {6+}
469
 
keep;
470
 
OK "Putscript completed."
471
 
---%<-------------------------------------------------------------------------
472
 
 
473
 
Upon successful upload, you should find a file called 'hutsefluts.sieve' in
474
 
your 'sieve_storage' directory. The script should also be listed by the server
475
 
as follows when the 'LISTSCRIPTS' command is issued:
476
 
 
477
 
---%<-------------------------------------------------------------------------
478
 
LISTSCRIPTS
479
 
"hutsefluts"
480
 
OK "Listscripts completed."
481
 
---%<-------------------------------------------------------------------------
482
 
 
483
 
You can check whether your script is uploaded correctly by downloading it using
484
 
the 'GETSCRIPT' command. This command accepts the name of the downloaded script
485
 
as its only parameter:
486
 
 
487
 
---%<-------------------------------------------------------------------------
488
 
GETSCRIPT "hutsefluts"
489
 
{6}
490
 
keep;
491
 
OK "Getscript completed."
492
 
---%<-------------------------------------------------------------------------
493
 
 
494
 
To let the Sieve plugin use your newly uploaded script, you must activate it
495
 
using the 'SETACTIVE' command (only one script can be active at any time). The
496
 
active script is indicated 'ACTIVE' in the 'LISTSCRIPTS' output, e.g.:
497
 
 
498
 
---%<-------------------------------------------------------------------------
499
 
SETACTIVE "hutsefluts"
500
 
OK "Setactive completed."
501
 
LISTSCRIPTS
502
 
"hutsefluts" ACTIVE
503
 
OK "Listscripts completed.
504
 
---%<-------------------------------------------------------------------------
505
 
 
506
 
The symbolic link configured with the 'sieve' setting should now point to the
507
 
activated script in the 'sieve_storage' directory. If no script is active, this
508
 
symbolic link is absent.
509
 
 
510
 
Manual TLS Login
511
 
----------------
512
 
 
513
 
When TLS needs to be used during manual testing, 'gnutls-cli' provides the
514
 
means to do so. This command-line utility is part of the GNUTLS distribution
515
 
and on most systems this should be easy to install. It is used to connect
516
 
toManageSieve as follows:
517
 
 
518
 
---%<-------------------------------------------------------------------------
519
 
gnutls-cli --starttls -p <port> <host>
520
 
---%<-------------------------------------------------------------------------
521
 
 
522
 
This starts the client in plain text mode first. As shown in the previous
523
 
section, the server presents a greeting with all capabilities of the server. If
524
 
'STARTTLS' is listed, you can issue the 'STARTTLS' command as follows:
525
 
 
526
 
---%<-------------------------------------------------------------------------
527
 
STARTTLS
528
 
OK "Begin TLS negotiation now."
529
 
---%<-------------------------------------------------------------------------
530
 
 
531
 
If an OK response is given by the server you can press 'Ctrl-D' to make
532
 
'gnutls-cli' start the TLS negotiation. Upon pressing 'Ctrl-D', 'gnutls-cli'
533
 
will show information on the negotiated TLS session and finally the first
534
 
response of the server is shown:
535
 
 
536
 
---%<-------------------------------------------------------------------------
537
 
"IMPLEMENTATION" "dovecot"
538
 
"SASL" "PLAIN"
539
 
"SIEVE" "comparator-i;ascii-numeric fileinto reject vacation imapflags notify
540
 
include envelope body relational regex subaddress copy"
541
 
OK "TLS negotiation successful."
542
 
---%<-------------------------------------------------------------------------
543
 
 
544
 
Hereafter, you can continue to authenticate and upload a script as described in
545
 
the previous section.
546
 
 
547
 
Client Problems
548
 
---------------
549
 
 
550
 
If manual efforts to upload a script are successful, but your client still
551
 
fails, you need to obtain a view on what the client communicates with the
552
 
server. A common method is to sniff the client protocol session using a tool
553
 
like 'ngrep'. However, this will not work when TLS is active. If the problem is
554
 
not specific to TLS, you are advised to temporarily turn off TLS and sniff the
555
 
plain text protocol. If TLS is part of the issue, you can use Dovecot's<rawlog>
556
 
[Debugging.Rawlog.txt] facility to see what is going on if the client is logged
557
 
in. If the authentication is the problem, there is no real nice way to obtain a
558
 
transcript of the protocol. One way is to run managesieve from inetd, wrapping
559
 
it into a script that writes the protocol messages somewhere (*FIXME*: This
560
 
needs some checking and explanation). Alternatively, if possible, the client
561
 
can be altered to write its protocol messages somewhere.
562
 
 
563
 
Known Issues
564
 
------------
565
 
 
566
 
 * Although this ManageSieve server should comply with the draft specification
567
 
   of theManageSieve protocol, quite a few clients don't. This is particularly
568
 
   true for the TLS support. However, now that Cyrus' Timsieved has changed its
569
 
   behaviour towards protocol compliance, all those clients will follow
570
 
   eventually. The core of the TLS problem is that aManageSieve server is
571
 
   required to send an unsolicited CAPABILITY response right after successful
572
 
   TLS negotiation. Older Cyrus servers did not do this and many clients
573
 
   incorporated this protocol error as the standard, meaning that these do not
574
 
   expect the CAPABILITY response and thus fail with subsequent commands. The
575
 
   following clients are known to have this TLS issue:
576
 
 
577
 
   Thunderbird Sieve add-on:
578
 
     TLS broken for old versions. Starting with version 0.1.5 the Thunderbird
579
 
     Sieve add-on properly supports TLS.
580
 
 
581
 
   KMail + kio_sieve:
582
 
     TLS broken for old versions. This issue is fixed at least in kmail 1.9.9 /
583
 
     kde 3.5.9.
584
 
 
585
 
   SquirrelMail/AvelSieve:
586
 
     For some users the Avelsieve client stores scripts but fails to retrieve
587
 
     them later. This problem is directly caused by<AvelSieve.txt>'s TLS
588
 
     support. A quick way to fix this is not to enable TLS forManageSieve.
589
 
     <AvelSieve.txt> stable (v1.0.1) does not have TLS support at all, so you
590
 
     will see this happen only with the development or SVN versions.  Another
591
 
     issue is that (at least with avelsieve-1.9.7) it is impossible to delete
592
 
     the last rule of a script. For avelsieve-1.9.7 you find a patch that fixes
593
 
     these two issues here
594
 
     [http://www.rename-it.nl/dovecot/client-patches/avelsieve-1.9.7-dovecot.patch].
595
 
 
596
 
 * Other client issues:
597
 
   SmartSieve, WebSieve:
598
 
     These clients are specifically written for Cyrus timsieved and fail on
599
 
     multiple stages of the protocol when connected to DovecotManageSieve.
600
 
      * /(Stephan Bosch)/: I intend to look at these in the future, but
601
 
        currently these are very much unavailable for use with Dovecot. But,
602
 
        feel free to fix these yourself:)
603
 
      * /(Steffen "Stefreak" Neubauer)/: I've fixed the problems for
604
 
        smartsieve. Just replace your lib/Managesieve.php with this
605
 
        here:https://www.commail.org/sieve/lib/Managesieve.phps - HAVE FUN!
606
 
 
607
 
 * The current implementation of the daemon does not have quota enforcement as
608
 
   recommended in the specification. So keep in mind that malicious users could
609
 
   fill your file system with loads of spurious script files.
610
 
 * The ANONYMOUS authentication mechanism is currently not supported and
611
 
   explicitly denied.
612
 
 
613
 
*NOTE*: If you add new issues to this list, notify the author or send an e-mail
614
 
to the Dovecot mailing list as described below. In any case, you must make sure
615
 
that the issue is properly explained and that the author can contact you for
616
 
more information.
 
4
ManageSieve service is used to manage a user's <Sieve> [LDA.Sieve.txt] script
 
5
collection. It has the following advantages over doing it directly via
 
6
filesystem:
 
7
 
 
8
 * No need to let users log in via FTP/SFTP/etc, which could be difficult
 
9
   especially with virtual users.
 
10
 * ManageSieve is a standard protocol
 
11
   [http://tools.ietf.org/id/draft-martin-managesieve-12.txt] (although still a
 
12
   draft), so users can manage their scripts using (hopefully)
 
13
   user-friendlyManageSieve clients. Many webmails already include a
 
14
   ManageSieve client.
 
15
 * Scripts are compiled before they are installed, which guarantees that the
 
16
   uploaded script is valid. This prevents a user from inadvertently installing
 
17
   a broken Sieve script.
 
18
 
 
19
Dovecot's ManageSieve support is distributed in a separate package. Currently
 
20
it also requires patching Dovecot sources, but this won't be necessary anymore
 
21
in Dovecot v2.0. There exists also an alternative pysieved
 
22
[http://woozle.org/~neale/src/pysieved/] ManageSieve server that works with
 
23
Dovecot.
 
24
 
 
25
 * <Download and Installation> [ManageSieve.Install.txt]
 
26
 * <Configuration> [ManageSieve.Configuration.txt]
 
27
 * <Troubleshooting> [ManageSieve.Troubleshooting.txt]
 
28
 * <Client Issues> [ManageSieve.Clients.txt]
617
29
 
618
30
Contact Info
619
31
------------
620
32
 
621
33
 * Author: Stephan Bosch, stephan@rename-it.nl
622
 
 * IRC: Freenode, #dovecot, S[r]us
 
34
 * IRC: Freenode [http://freenode.net/], #dovecot, S[r]us
623
35
 * Please use the Dovecot mailing list
624
36
   [http://www.dovecot.org/mailinglists.html] for questions about the
625
37
   ManageSieve service. You don't have to subscribe to it. 
626
38
 
627
 
(This file was created from the wiki on 2009-07-10 04:42)
 
39
(This file was created from the wiki on 2009-10-16 04:42)