1SIEVE-FILTER(1)                   Pigeonhole                   SIEVE-FILTER(1)
2
3
4

NAME

6       sieve-filter - Pigeonhole's Sieve mailbox filter tool
7
8
9       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

SYNOPSIS

15       sieve-filter [options] script-file source-mailbox [discard-action]
16

DESCRIPTION

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
22       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
34       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
41       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
54
55   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
65       MAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!
66
67

OPTIONS

69       -c config-file
70              Alternative Dovecot configuration file path.
71
72       -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
80       -D     Enable Sieve debugging.
81
82       -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
89       -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
98       -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
104       -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
112       -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
121       -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
127       -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
132       -v     Produce verbose output during filtering.
133
134       -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
138       -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
147              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
155

ARGUMENTS

157       script-file
158              Specifies the Sieve script to (compile and) execute.
159
160              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
165       source-mailbox
166              Specifies the source mailbox containing the  messages  that  the
167              Sieve filter will act upon.
168
169              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
175              This mailbox is not modified unless the -W option is specified.
176
177       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
184              keep (default)
185                     Keep discarded messages in source mailbox.
186
187              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
193              delete Flag discarded messages as \DELETED.
194
195              expunge
196                     Expunge  discarded  messages,  meaning  that  these   are
197                     removed irreversibly when the tool finishes filtering.
198
199              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
209
210

EXAMPLES

212       [...]
213
214

EXIT STATUS

216       sieve-filter will exit with one of the following values:
217
218       0   Sieve filter applied successfully. (EX_OK, EXIT_SUCCESS)
219
220       1   Operation  failed.  This  is  returned  for  almost  all  failures.
221           (EXIT_FAILURE)
222
223       64  Invalid parameter given. (EX_USAGE)
224

FILES

226       /etc/dovecot/dovecot.conf
227              Dovecot's main configuration file.
228
229       /etc/dovecot/conf.d/90-sieve.conf
230              Sieve interpreter settings (included from Dovecot's main config‐
231              uration file)
232

REPORTING BUGS

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

SEE ALSO

239       dovecot(1),  dovecot-lda(1),  sieve-dump(1),  sieve-test(1), sievec(1),
240       pigeonhole(7)
241
242
243
244Pigeonhole for Dovecot v2.2       2016-04-05                   SIEVE-FILTER(1)
Impressum