1SIEVE-FILTER(1) Pigeonhole SIEVE-FILTER(1)
2
6 sieve-filter - Pigeonhole's Sieve mailbox filter tool
7 WARNING: This tool is still experimental. Read this manual carefully,
10 and backup any important mail before using this tool. Also note that
11 some of the features documented here are not actually implemented yet;
12 this is clearly indicated where applicable.
13
15 sieve-filter [options] script-file source-mailbox [discard-action]
16
18 The sieve-filter command is part of the Pigeonhole Project (pigeon‐
19 hole(7)), which adds Sieve (RFC 5228) support to the Dovecot secure
20 IMAP and POP3 server (dovecot(1)).
21 The Sieve language was originally meant for filtering messages upon
23 delivery. However, there are occasions when it is desirable to filter
24 messages that are already stored in a mailbox, for instance when a bug
25 in a Sieve script caused many messages to be delivered incorrectly.
26 Using the sieve-filter tool it is possible to apply a Sieve script on
27 all messages in a particular source-mailbox, making it possible to
28 delete messages, to store them in a different mailbox, to change their
29 content, and to change the assigned IMAP flags and keywords. Attempts
30 to send messages to the outside world are ignored by default for obvi‐
31 ous reasons, but, using the proper command line options, it is possible
32 to capture and handle outgoing mail as well.
33 If no options are specified, the sieve-filter command runs in a simula‐
35 tion mode in which it only prints what would be performed, without
36 actually doing anything. Use the -e option to activate true script exe‐
37 cution. Also, the source-mailbox is opened read-only by default, mean‐
38 ing that it normally always remains unchanged. Use the -W option to
39 allow changes in the source-mailbox.
40 Even with the -W option enabled, messages in the source-mailbox are
42 only potentially modified or moved to a different folder. Messages are
43 never lost unless a discard-action argument other than keep (the
44 default) is specified. If the Sieve filter decides to store the message
45 in the source-mailbox, where it obviously already exists, it is never
46 duplicated there. In that case, the IMAP flags of the original message
47 can be modified by the Sieve interpreter using the imap4flags exten‐
48 sion, provided that -W is specified. If the message itself is modified
49 by the Sieve interpreter (e.g. using the editheader extension), a new
50 message is stored and the old one is expunged. However, if -W is omit‐
51 ted, the original message is left untouched and the modifications are
52 discarded.
53 CAUTION
56 Although this is a very useful tool, it can also be very destructive
57 when used improperly. A small bug in your Sieve script in combination
58 with the wrong command line options could cause it to discard the wrong
59 e-mails. And, even if the source-mailbox is opened in read-only mode to
60 prevent such mishaps, it can still litter other mailboxes with spurious
61 copies of your e-mails if your Sieve script decides to do so. There‐
62 fore, users are advised to read this manual carefully and to use the
63 simulation mode first to check what the script will do. And, of course:
64 MAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!
66
69 -c config-file
70 Alternative Dovecot configuration file path.
71 -C Force compilation. By default, the compiled binary is stored on
73 disk. When this binary is found during the next execution of
74 sieve-filter and its modification time is more recent than the
75 script file, it is used and the script is not compiled again.
76 This option forces the script to be compiled, thus ignoring any
77 present binary. Refer to sievec(1) for more information about
78 Sieve compilation.
79 -D Enable Sieve debugging.
81 -e Turns on execution mode. By default, the sieve-filter command
83 runs in simulation mode in which it changes nothing, meaning
84 that no mailbox is altered in any way and no actions are per‐
85 formed. It only prints what would be done. Using this option,
86 the sieve-filter command becomes active and performs the
87 requested actions.
88 -m default-mailbox
90 The mailbox where the (implicit) keep Sieve action stores mes‐
91 sages. This is equal to the source-mailbox by default. Specify‐
92 ing a different folder will have the effect of moving (or copy‐
93 ing if -W is omitted) all kept messages to the indicated folder,
94 instead of just leaving them in the source-mailbox. Refer to the
95 explanation of the source-mailbox argument for more information
96 on mailbox naming.
97 -o setting=value
99 Overrides the configuration setting from /etc/dovecot/dove‐
100 cot.conf and from the userdb with the given value. In order to
101 override multiple settings, the -o option may be specified mul‐
102 tiple times.
103 -q output-mailbox [not implemented yet]
105 Store outgoing e-mail into the indicated output-mailbox. By
106 default, the sieve-filter command ignores Sieve actions such as
107 redirect, reject, vacation and notify, but using this option
108 outgoing messages can be appended to the indicated mailbox. This
109 option has no effect in simulation mode. Flags of redirected
110 messages are not preserved.
111 -Q mail-command [not implemented yet]
113 Send outgoing e-mail (e.g. as produced by redirect, reject and
114 vacation) through the specified program. By default, the
115 sieve-filter command ignores Sieve actions such as redirect,
116 reject, vacation and notify, but using this option outgoing mes‐
117 sages can be fed to the stdin of an external shell command. This
118 option has no effect in simulation mode. Unless you really know
119 what you are doing, DO NOT USE THIS TO FEED MAIL TO SENDMAIL!.
120 -s script-file [not implemented yet]
122 Specify additional scripts to be executed before the main
123 script. Multiple -s arguments are allowed and the specified
124 scripts are executed sequentially in the order specified at the
125 command line.
126 -u user
128 Run the Sieve script for the given user. When omitted, the com‐
129 mand will be executed with the environment of the currently
130 logged in user.
131 -v Produce verbose output during filtering.
133 -W Enables write access to the source-mailbox. This allows (re)mov‐
135 ing the messages from the source-mailbox, changing their con‐
136 tents, and changing the assigned IMAP flags and keywords.
137 -x extensions
139 Set the available extensions. The parameter is a space-separated
140 list of the active extensions. By prepending the extension iden‐
141 tifiers with + or -, extensions can be included or excluded rel‐
142 ative to the configured set of active extensions. If no exten‐
143 sions have a + or - prefix, only those extensions that are
144 explicitly listed will be enabled. Unknown extensions are
145 ignored and a warning is produced.
146 For example -x "+imapflags -enotify" will enable the deprecated
148 imapflags extension and disable the enotify extension. The rest
149 of the active extensions depends on the sieve_extensions and
150 sieve_global_extensions settings. By default, i.e. when
151 sieve_extensions and sieve_global_extensions remain unconfig‐
152 ured, all supported extensions are available, except for depre‐
153 cated extensions or those that are still under development.
154
157 script-file
158 Specifies the Sieve script to (compile and) execute.
159 Note that this tool looks for a pre-compiled binary file with a
161 .svbin extension and with basename and path identical to the
162 specified script. Use the -C option to disable this behavior by
163 forcing the script to be compiled into a new binary.
164 source-mailbox
166 Specifies the source mailbox containing the messages that the
167 Sieve filter will act upon.
168 This is the name of a mailbox, as visible to IMAP clients,
170 except in UTF-8 format. The hierarchy separator between a parent
171 and child mailbox is commonly '/' or '.', but this depends on
172 your selected mailbox storage format and namespace configura‐
173 tion. The mailbox names may also require a namespace prefix.
174 This mailbox is not modified unless the -W option is specified.
176 discard-action
178 Specifies what is done with messages in the source-mailbox that
179 where not kept or otherwise stored by the Sieve script; i.e.
180 those messages that would normally be discarded if the Sieve
181 script were executed at delivery. The discard-action parameter
182 accepts one of the following values:
183 keep (default)
185 Keep discarded messages in source mailbox.
186 move mailbox
188 Move discarded messages to the indicated mailbox. This is
189 for instance useful to move messages to a Trash mailbox.
190 Refer to the explanation of the source-mailbox argument
191 for more information on mailbox naming.
192 delete Flag discarded messages as \DELETED.
194 expunge
196 Expunge discarded messages, meaning that these are
197 removed irreversibly when the tool finishes filtering.
198 When the -W option is not specified, the source-mailbox is
200 immutable and the specified discard-action has no effect. This
201 means that messages are at most copied to a new location. In
202 contrast, when the -W is specified, messages that are success‐
203 fully stored somewhere else by the Sieve script are always
204 expunged from the source-mailbox, with the effect that these are
205 thus moved to the new location. This happens irrespective of the
206 specified discard-action. Remember: only discarded messages are
207 affected by the specified discard-action.
208
212 [...]
213
216 sieve-filter will exit with one of the following values:
217 0 Sieve filter applied successfully. (EX_OK, EXIT_SUCCESS)
219 1 Operation failed. This is returned for almost all failures.
221 (EXIT_FAILURE)
222 64 Invalid parameter given. (EX_USAGE)
224
226 /etc/dovecot/dovecot.conf
227 Dovecot's main configuration file.
228 /etc/dovecot/conf.d/90-sieve.conf
230 Sieve interpreter settings (included from Dovecot's main config‐
231 uration file)
232
234 Report bugs, including doveconf -n output, to the Dovecot Mailing List
235 <dovecot@dovecot.org>. Information about reporting bugs is available
236 at: http://dovecot.org/bugreport.html
237
239 dovecot(1), dovecot-lda(1), sieve-dump(1), sieve-test(1), sievec(1),
240 pigeonhole(7)
241Pigeonhole for Dovecot v2.2 2016-04-05 SIEVE-FILTER(1)