44
44
--with-unfinished-features=no
45
45
Controls whether unfinished features and extensions are built. Enabling this
46
46
will enable the compilation of code that is considered unfinished and highly
47
experimental and may therefore introduce bugs and unexpected behavior.
47
experimental and may therefore introduce bugs and unexpected behavior.
48
48
In fact, it may not compile at all. Enable this only when you are eager to
49
49
test some of the new development functionality.
57
57
facilitates the actual Sieve filtering upon delivery.
59
59
- The ManageSieve Service: This implements the ManageSieve protocol through
60
which users can remotely manage Sieve scripts on the server.
60
which users can remotely manage Sieve scripts on the server.
62
The functionality of these items is described in more detail in the README file.
62
The functionality of these items is described in more detail in the README file.
63
63
In this file and in this section their configuration is described. Example
64
64
configuration files are provided in the doc/example-config directory of this
67
67
Sieve Interpreter - Basic Configuration
68
68
---------------------------------------
85
85
plugin section of the config file (default values are shown if applicable):
87
87
sieve = ~/.dovecot.sieve
88
The location of the user's main active script.
88
The location of the user's main active script.
91
91
The location of the default personal sieve script file, which gets executed
92
92
ONLY if user's private Sieve script does no exist, e.g.
93
93
/var/lib/dovecot/default.sieve. This is usually a global script, so be sure
96
96
`sieve_global_path', but that name is now deprecated.
99
Location for :global include scripts for the Sieve include extension.
99
Location for :global include scripts for the Sieve include extension.
101
101
sieve_dir = ~/sieve
102
Location for :personal include scripts for the Sieve include extension.
102
Location for :personal include scripts for the Sieve include extension.
104
104
sieve_extensions =
105
Which Sieve language extensions are available to users. By default, all
106
supported extensions are available, except for deprecated extensions or those
107
that are still under development. Some system administrators may want to
108
disable certain Sieve extensions or enable those that are not available by
105
Which Sieve language extensions are available to users. By default, all
106
supported extensions are available, except for deprecated extensions or those
107
that are still under development. Some system administrators may want to
108
disable certain Sieve extensions or enable those that are not available by
109
109
default. This setting can use '+' and '-' to specify differences relative to
110
110
the default. For example `sieve_extensions = +imapflags' will enable the
111
111
deprecated imapflags extension in addition to all extensions were already
114
114
sieve_global_extensions =
115
115
Which Sieve language extensions are ONLY avalable in global scripts. This can
117
117
control, for instance when these extensions can cause security concerns. This
118
118
setting has higher precedence than the `sieve_extensions' setting (above),
119
119
meaning that the extensions enabled with this setting are never available to
120
the user's personal script no matter what is specified for the
120
the user's personal script no matter what is specified for the
121
121
`sieve_extensions' setting. The syntax of this setting is similar to
122
122
the `sieve_extensions' setting, with the difference that extensions are
123
123
enabled or disabled for exclusive use in global scripts. Currently, no
127
127
The Pigeonhole Sieve interpreter can have plugins of its own. Using this
128
128
setting, the used plugins can be specified. Check the Dovecot wiki
129
129
(wiki2.dovecot.org) or the pigeonhole website (http://pigeonhole.dovecot.org)
130
for available plugins.
130
for available plugins. The sieve_extprograms plugin is included in this
133
134
The path to the file where the user log file is written. If not configured, a
134
135
default location is used. If the main user's personal Sieve (as configured
135
136
with sieve=) is a file, the logfile is set to <filename>.log by default. If
136
it is not a file, the default user log file is ~/.dovecot.sieve.log.
137
it is not a file, the default user log file is ~/.dovecot.sieve.log.
138
139
recipient_delimiter = +
139
The separator that is expected between the :user and :detail address parts
140
The separator that is expected between the :user and :detail address parts
140
141
introduced by the subaddress extension. This may also be a sequence of
141
142
characters (e.g. '--'). The current implementation looks for the separator
142
143
from the left of the localpart and uses the first one encountered. The :user
150
151
# The location of the user's active script:
151
152
sieve = ~/.dovecot.sieve
153
# If the user has no personal active script (i.e. if the file
154
# If the user has no personal active script (i.e. if the file
154
155
# indicated in sieve= does not exist), use this one:
155
156
sieve_default = /var/lib/dovecot/sieve/default.sieve
157
# The include extension fetches the :personal scripts from this
158
# directory. When ManageSieve is used, this is also where scripts
158
# The include extension fetches the :personal scripts from this
159
# directory. When ManageSieve is used, this is also where scripts
160
161
sieve_dir = ~/sieve
162
# The include extension fetches the :global scripts from this
163
# The include extension fetches the :global scripts from this
164
165
sieve_global_dir = /var/lib/dovecot/sieve/global/
228
229
file in the user's home directory (~/.dovecot.sieve). This requires that the
229
230
home directory is set for the user.
231
If you want to store the script elsewhere, you can override the default using
232
If you want to store the script elsewhere, you can override the default using
232
233
the sieve= setting, which specifies the location of the user's script file. This
233
234
can be done in two ways:
235
236
1. Define the sieve setting in the plugin section of dovecot.conf.
236
2. Return sieve extra field from userdb extra fields.
237
2. Return sieve extra field from userdb extra fields.
238
For example, to use a Sieve script file named <username>.sieve in
239
For example, to use a Sieve script file named <username>.sieve in
239
240
/var/sieve-scripts, use:
244
245
sieve = /var/sieve-scripts/%u.sieve
247
You may use templates like %u, as shown in the example. Refer to
248
You may use templates like %u, as shown in the example. Refer to
248
249
http://wiki.dovecot.org/Variables for more information.
250
A relative path (or just a filename) will be interpreted to point under the
251
A relative path (or just a filename) will be interpreted to point under the
251
252
user's home directory.
253
254
Sieve Interpreter - Executing Multiple Scripts Sequentially
254
255
-----------------------------------------------------------
256
Pigeonhole's Sieve interpreter allows executing multiple Sieve scripts
257
Pigeonhole's Sieve interpreter allows executing multiple Sieve scripts
257
258
sequentially. The extra scripts can be executed before and after the user's
258
259
private script. For example, this allows executing global Sieve policies before
259
260
the user's script. The following settings in the plugin section of the Dovecot
267
268
directory, all the Sieve scripts contained therein (with the proper .sieve
268
269
extension) are executed. The order of execution within that directory is
269
270
determined by the file names, using a normal 8bit per-character comparison.
271
272
Multiple script file or directory paths can be specified by appending an
272
273
increasing number. The Sieve scripts found from these paths are added to the
273
274
script execution sequence in the specified order. Reading the numbered
279
280
sieve_after3 = (etc..)
280
281
Identical to sieve_before, but the specified scripts are executed after the
281
user's script (only when keep is still in effect, as explained below).
282
user's script (only when keep is still in effect, as explained below).
283
284
The script execution ends when the currently executing script in the sequence
284
does not yield a "keep" result: when the script terminates, the next script is
285
does not yield a "keep" result: when the script terminates, the next script is
285
286
only executed if an implicit or explicit "keep" is in effect. Thus, to end all
286
287
script execution, a script must not execute keep and it must cancel the implicit
287
keep, e.g. by executing "discard; stop;". This means that the command "keep;"
288
has different semantics when used in a sequence of scripts. For normal Sieve
288
keep, e.g. by executing "discard; stop;". This means that the command "keep;"
289
has different semantics when used in a sequence of scripts. For normal Sieve
289
290
execution, "keep;" is equivalent to "fileinto "INBOX";", because both cause the
290
291
message to be stored in INBOX. However, in sequential script execution, it only
291
292
controls whether the next script is executed. Storing the message into INBOX
305
306
Just as for executing a single script the normal way, the Pigeonhole LDA Sieve
306
307
plugin takes care never to duplicate deliveries, forwards or responses. When
307
vacation actions are executed multiple times in different scripts, the usual
308
vacation actions are executed multiple times in different scripts, the usual
308
309
error is not triggered: the subsequent duplicate vacation actions are simply
325
326
# E.g. user-specific default mail filing rules
326
327
sieve_after = /var/vmail/%d/%n/sieve-after
328
# Global scripts executed after the user's personal script
329
# Global scripts executed after the user's personal script
329
330
# (if keep is still in effect)
330
331
# E.g. default mail filing rules.
331
332
sieve_after2 = /var/lib/dovecot/sieve/after.d/
367
368
configuration options. Refer to doc/extensions/include.txt for settings
368
369
specific to the include extension.
370
- Spamtest and Virustest extensions:
371
- Spamtest and virustest extensions:
372
373
Using the spamtest and virustest extensions (RFC 5235), the Sieve language
373
374
provides a uniform and standardized command interface for evaluating spam and
382
383
configuration and are not enabled for use by default. Refer to
383
384
doc/extensions/spamtest-virustest.txt for configuration information.
386
- Vnd.dovecot.duplicate extension:
388
The vnd.dovecot.duplicate extension augments the Sieve filtering
389
implementation with a test that allows detecting and handling duplicate
390
message deliveries, e.g. as caused by mailinglists when people reply both to
391
the mailinglist and the user directly.
393
The vnd.dovecot.duplicate extension requires explicit configuration and is not
394
enabled for use by default. Refer to doc/extensions/vnd.dovecot.duplicate.txt
395
for configuration information.
397
- Extprograms plugin;
398
vnd.dovovecot.pipe, vnd.dovecot.filter, vnd.dovecot.execute extensions:
400
The "sieve_extprograms" plugin provides extensions to the Sieve filtering
401
language adding new action commands for invoking a predefined set of external
402
programs. Messages can be piped to or filtered through those programs and
403
string data can be input to and retrieved from those programs.
405
This plugin and the extensions it provides require explicit configuration and
406
are not enabled for use by default. Refer to doc/plugins/sieve_extprograms.txt
407
for more information.
385
409
Sieve Interpreter - Migration from CMUSieve (Dovecot v1.0/v1.1)
386
410
---------------------------------------------------------------
388
For the most part, migration from CMUSieve to the Pigeonhole LDA Sieve plugin is
412
For the most part, migration from CMUSieve to the Pigeonhole LDA Sieve plugin is
389
413
just a matter of changing the used plugin name from 'cmusieve' to 'sieve' in the
390
414
mail_plugins option in the protocol lda section of the config file (as explained
391
415
above). However, there are a few important differences:
407
431
* The include extension now requires your script file names to end with
408
432
".sieve". This means that ` include :personal "myscript"; ' won't work unless
409
you rename "myscript" to "myscript.sieve"
433
you rename "myscript" to "myscript.sieve"
411
435
Sieve Interpreter - Migration from Dovecot Sieve v0.1.x (Dovecot v1.2)
412
436
----------------------------------------------------------------------
414
* Dovecot v2.0 adds support for LMTP. Much like the Dovecot LDA, it can make
415
use of the Pigeonhole Sieve plugin. Since the LMTP service has its own
416
prototocol lmtp section in the config file, you need to add the Sieve plugin
438
* Dovecot v2.0 adds support for LMTP. Much like the Dovecot LDA, it can make
439
use of the Pigeonhole Sieve plugin. Since the LMTP service has its own
440
prototocol lmtp section in the config file, you need to add the Sieve plugin
417
441
to the mail_plugins setting there too when you decide to use LMTP.
418
* The 'sieve_subaddress_sep' setting for the Sieve subaddress extension is now
442
* The 'sieve_subaddress_sep' setting for the Sieve subaddress extension is now
419
443
known as 'recipient_delimiter'. Although sieve_subaddress_sep is still
420
444
recognized for backwards compatibility, it is recommended to update the
421
445
setting to the new name, since the LMTP service also uses the
422
recipient_delimiter setting.
446
recipient_delimiter setting.
424
448
ManageSieve Service - Basic Configuration
425
449
-----------------------------------------
429
If you have used the LDA Sieve plugin without ManageSieve before and you have
453
If you have used the LDA Sieve plugin without ManageSieve before and you have
430
454
.dovecot.sieve files in user directories, you are advised to make a backup
431
455
before installing ManageSieve. Although the ManageSieve service takes care to
432
move these files to the Sieve directory before it is substituted with a
456
move these files to the Sieve directory before it is substituted with a
433
457
symbolic link, this is not a very well tested operation, meaning that there is
434
458
a slim possibility that existing Sieve scripts get lost.
436
Just like all other binaries that Dovecot uses, the managesieve and
460
Just like all other binaries that Dovecot uses, the managesieve and
437
461
managesieve-login binaries are installed during make install.
439
463
There are two things that have be done to activate the ManageSieve support in
442
* The first step is to add `sieve' to the protocols= configuration line in
466
* The first step is to add `sieve' to the protocols= configuration line in
443
467
your dovecot.conf.
445
469
* The next step is specifying an additional service type for the ManageSieve
446
service. This could be done in Dovecot's conf.d/master.conf or you can use
470
service. This could be done in Dovecot's conf.d/master.conf or you can use
447
471
the 20-managesieve.conf file from the doc/example-config/conf.d directory of
467
491
managesieve_logout_format = bytes=%i/%o
468
492
Specifies the string pattern used to compose the logout message of an
469
authenticated session. The following substitutions are available:
493
authenticated session. The following substitutions are available:
471
495
%i - total number of bytes read from client
472
496
%o - total number of bytes sent to client
474
498
managesieve_implementation_string = Dovecot Pigeonhole
475
To fool ManageSieve clients that are focused on CMU's timesieved you can
476
specify the IMPLEMENTATION capability that the Dovecot reports to clients
499
To fool ManageSieve clients that are focused on CMU's timesieved you can
500
specify the IMPLEMENTATION capability that the Dovecot reports to clients
477
501
(e.g. 'Cyrus timsieved v2.2.13').
479
503
managesieve_max_compile_errors = 5
480
The maximum number of compile errors that are returned to the client upon
504
The maximum number of compile errors that are returned to the client upon
481
505
script upload or script verification.
483
507
managesieve_sieve_capability =
512
536
already exists at the location specified by the sieve setting, it is moved to
513
537
the sieve_dir location before the symbolic link is installed. It is renamed
514
538
to dovecot.orig.sieve and therefore listed as `dovecot.orig' by a ManageSieve
517
541
The following provides an example configuration for Sieve and ManageSieve. Only
518
sections and settings relevant to ManageSieve are shown. Refer to
519
20-managesieve.conf in the doc/example-config/conf.d directory for a full
520
example with comments, but don't forget to configure Sieve and add sieve to the
542
sections and settings relevant to ManageSieve are shown. Refer to
543
20-managesieve.conf in the doc/example-config/conf.d directory for a full
544
example with comments, but don't forget to configure Sieve and add sieve to the
521
545
'protocols = ...' setting if you use it.
523
547
# *** conf.d/20-managesieve.conf ***
594
618
The following has changed since the ManageSieve releases for Dovecot v1.x:
596
620
* For Dovecot v1.0 and v1.1, the sieve_dir setting used by ManageSieve was
597
called sieve_storage. Also, the sieve and sieve_storage settings were located
621
called sieve_storage. Also, the sieve and sieve_storage settings were located
598
622
inside the 'protocol managesieve' section of the configuration. As per
599
623
Dovecot v1.2, these settings are shared with the Sieve plugin and located in
600
624
the 'plugin' section of the configuration. Make sure you have updated the
611
635
* The Dovecot configuration now calls the ManageSieve protocol 'sieve' instead
612
636
of 'managesieve' because it is registered as such with IANA. The binaries and
613
637
the services are still called 'managesieve' and 'managesieve-login'. The
614
example above demonstrates how this affects the configuration.
638
example above demonstrates how this affects the configuration.
619
643
This package includes a test suite to verify the basic processing of the Sieve
620
interpreter on your particular platform. Note that the test suite is not
621
available when this package is compiled against the Dovecot headers only. The
622
test suite executes a list of test cases and halts when one of them fails. If it
623
executes all test cases successfully, the test suite finishes. You can execute
624
the test suite using `make test`.
644
interpreter on your particular platform. Note that the test suite is not
645
available when this package is compiled against the Dovecot headers only. The
646
test suite executes a list of test cases and halts when one of them fails. If it
647
executes all test cases successfully, the test suite finishes. You can execute
648
the basic test suite using `make test`, which does not include the plugins. You
649
can test the plugins using `make test-plugins`.
626
651
A failing test case is always a bug and a report is greatly appreciated.
added
removed
pigeonhole/INSTALL
