1
1
.\" Copyright (c) 2010-2012 Pigeonhole authors, see the included COPYING file
2
.TH "SIEVE\-FILTER" 1 "2012-01-07" "Pigeonhole for Dovecot v2.0" "Pigeonhole"
2
.TH "SIEVE\-FILTER" 1 "2012-01-07" "Pigeonhole for Dovecot v2.1" "Pigeonhole"
4
4
sieve\-filter \- Pigeonhole\(aqs Sieve mailbox filter tool
7
\fBWARNING: \fRThis tool is not finished and should \fB*NOT*\fR be used, unless
8
you feel like testing newly developed features! The behavior described in this
9
manual page represents the design and not necessarily what the tool currently
7
\fBWARNING: \fRThis tool is still experimental. Read this manual carefully, and
8
backup any important mail before using this tool. Also note that some of the
9
features documented here are not actually implemented yet; this is clearly
10
indicated where applicable.
11
11
.\"------------------------------------------------------------------------
17
.RI [ source\-action ]
17
.RI [ discard\-action ]
20
20
The \fBsieve\-filter\fP command is part of the Pigeonhole Project
25
25
However, there are occasions when it is desirable to filter messages that are
26
26
already stored in a mailbox, for instance when a bug in a Sieve script caused
27
27
many messages to be delivered incorrectly. Using the sieve\-filter tool it is
28
possible to apply a Sieve script on all messages in a particular mailbox, making
29
it possible to delete messages, to store them in a different mailbox and to
30
change the assigned IMAP flags and keywords. Attempts to send messages to the
31
outside world are ignored by default for obvious reasons, but, using the proper
32
command line options, it is possible to capture outgoing mail as well.
28
possible to apply a Sieve script on all messages in a particular
29
\fIsource\-mailbox\fP, making it possible to delete messages, to store them in a
30
different mailbox, to change their content, and to change the assigned IMAP
31
flags and keywords. Attempts to send messages to the outside world are ignored
32
by default for obvious reasons, but, using the proper command line options, it
33
is possible to capture and handle outgoing mail as well.
34
35
If no options are specified, the sieve\-filter command runs in a simulation mode
35
36
in which it only prints what would be performed, without actually doing
36
37
anything. Use the \fB\-e\fP option to activate true script execution. Also, the
37
source mailbox is opened read\-only by default, so that the source mailbox
38
remains unchanged. Use the \fB\-W\fP option to allow changes in the source mailbox.
39
And even with the \fB\-W\fP option enabled, messages in the source mailbox are
40
only potentially modified and not (re)moved, unless a \fIsource\-action\fP
41
argument other than \fBkeep\fP is specified.
38
\fIsource\-mailbox\fP is opened read\-only by default, meaning that it normally
39
always remains unchanged. Use the \fB\-W\fP option to allow changes in the
40
\fIsource\-mailbox\fP.
42
Even with the \fB\-W\fP option enabled, messages in the \fIsource\-mailbox\fP
43
are only potentially modified or moved to a different folder. Messages are never
44
lost unless a \fIdiscard\-action\fP argument other than \fBkeep\fP (the default)
45
is specified. If the Sieve filter decides to store the message in the
46
\fIsource\-mailbox\fP, where it obviously already exists, it is never duplicated
47
there. In that case, the IMAP flags of the original message can be modified by
48
the Sieve interpreter using the \fIimap4flags\fP extension, provided that
49
\fB\-W\fP is specified. If the message itself is modified by the Sieve
50
interpreter (e.g. using the \fIeditheader\fP extension), a new message is stored
51
and the old one is expunged. However, if \fB-W\fP is omitted, the original
52
message is left untouched and the modifications are discarded.
43
55
Although this is a very useful tool, it can also be very destructive when used
44
56
improperly. A small bug in your Sieve script in combination with the wrong
45
57
command line options could cause it to discard the wrong e\-mails. And, even if
46
the source mailbox is opened in read\-only mode to prevent such mishaps, it can
47
still litter other mailboxes with spurious copies of your e\-mails if your Sieve
48
script decides to do so. Therefore, users are advised to read this manual
49
carefully and to use the simulation mode first to check what the script will do.
58
the \fIsource\-mailbox\fP is opened in read\-only mode to prevent such mishaps,
59
it can still litter other mailboxes with spurious copies of your e\-mails if
60
your Sieve script decides to do so. Therefore, users are advised to read this
61
manual carefully and to use the simulation mode first to check what the script
62
will do. And, of course:
52
64
\fBMAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!\fP
72
84
Turns on execution mode. By default, the sieve\-filter command runs in
73
85
simulation mode in which it changes nothing, meaning that no mailbox is altered
74
86
in any way and no actions are performed. It only prints what would be done.
75
Using this option the sieve\-filter command becomes active and performs the
87
Using this option, the sieve\-filter command becomes active and performs the
78
90
.BI \-m\ default\-mailbox
79
The mailbox where the (implicit) \fBkeep\fP Sieve action stores messages. This is
80
equal to the source mailbox by default.
83
Enable move mode. This will cause all messages that were succesfully stored
84
somewhere else to be expunged from the source mailbox, regardless of what the
85
\fIsource\-action\fP is (refer to Arguments section below). However, if the
86
Sieve filter decides to keep the message in the source mailbox, it is left
87
there and not affected by this option.
89
Note that some Sieve actions, such as \fBredirect\fP, don't store the message
90
anywhere and are thus \- with respect to the fate of the message in the source
91
mailbox \- treated as if a \fBdiscard\fP action were executed.
93
.BI \-q\ output\-mailbox\ \fR[not\ implemented\ yet]\fP
91
The mailbox where the (implicit) \fBkeep\fP Sieve action stores messages. This
92
is equal to the \fIsource\-mailbox\fP by default. Specifying a different folder
93
will have the effect of moving (or copying if \fB\-W\fP is omitted) all kept
94
messages to the indicated folder, instead of just leaving them in the
95
\fIsource\-mailbox\fP.
97
.BI \-q\ output\-mailbox\ \fB[not\ implemented\ yet]\fP
94
98
Store outgoing e\-mail into the indicated \fIoutput\-mailbox\fP. By default,
95
99
the sieve\-filter command ignores Sieve actions such as redirect, reject,
96
100
vacation and notify, but using this option outgoing messages can be appended to
97
101
the indicated mailbox. This option has no effect in simulation mode. Flags of
98
102
redirected messages are not preserved.
100
.BI \-Q\ mail\-command\ \fR[not\ implemented\ yet]\fP
104
.BI \-Q\ mail\-command\ \fB[not\ implemented\ yet]\fP
101
105
Send outgoing e\-mail (e.g. as produced by redirect, reject and vacation)
102
106
through the specified program. By default, the sieve\-filter command ignores
103
107
Sieve actions such as redirect, reject, vacation and notify, but using this
105
109
command. This option has no effect in simulation mode. Unless you really know
106
110
what you are doing, \fBDO NOT USE THIS TO FEED MAIL TO SENDMAIL!\fP.
108
.BI \-s\ script\-file\ \fR[not\ implemented\ yet]\fP
112
.BI \-s\ script\-file\ \fB[not\ implemented\ yet]\fP
109
113
Specify additional scripts to be executed before the main script. Multiple
110
114
\fB\-s\fP arguments are allowed and the specified scripts are executed
111
sequentially in the order specified at the command
115
sequentially in the order specified at the command line.
115
118
Run the Sieve script for the given \fIuser\fP.
121
Produce verbose output during filtering.
118
Enables write access to the source mailbox. This allows deleting the messages
119
from the source mailbox and changing the assigned IMAP flags and keywords.
124
Enables write access to the \fIsource\-mailbox\fP. This allows (re)moving the
125
messages from the \fIsource\-mailbox\fP, changing their contents, and changing
126
the assigned IMAP flags and keywords.
121
128
.BI \-x\ extensions
122
129
Set the available extensions. The parameter is a space\-separated list of the
123
130
active extensions. By prepending the extension identifiers with \fB+\fP or
124
\fB\-\fP, extensions can be included or excluded relative to the default set of
125
extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only those
126
extensions that are explicitly listed will be enabled. Unknown extensions are
127
ignored and a warning is produced. By default, all supported extensions are
128
available, except for deprecated extensions or those that are still under
131
\fB\-\fP, extensions can be included or excluded relative to the configured set
132
of active extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only
133
those extensions that are explicitly listed will be enabled. Unknown extensions
134
are ignored and a warning is produced.
131
136
For example \fB\-x\fP \(dq+imapflags \-enotify\(dq will enable the deprecated
132
imapflags extension along with all extensions that are available by default,
133
except for the enotify extension.
137
imapflags extension and disable the enotify extension. The rest of the active
138
extensions depends on the \fIsieve_extensions\fP and
139
\fIsieve_global_extensions\fP settings. By default, i.e.
140
when \fIsieve_extensions\fP and \fIsieve_global_extensions\fP remain
141
unconfigured, all supported extensions are available, except for deprecated
142
extensions or those that are still under development.
135
144
.\"------------------------------------------------------------------------
139
Specifies the script to (compile and) execute.
148
Specifies the Sieve script to (compile and) execute.
141
150
Note that this tool looks for a pre\-compiled binary file with a \fI.svbin\fP
142
151
extension and with basename and path identical to the specified script. Use the
144
153
into a new binary.
146
155
.I source\-mailbox
147
The name of the source mailbox.
156
The name of the source mailbox containing the messages that the Sieve filter
157
will act upon. This mailbox is not modified unless the \fB\-W\fP option is
150
Specifies what is done with messages in the source mailbox once processed by the
151
Sieve script. The \fIsource\-action\fP parameter accepts one of the following values:
161
Specifies what is done with messages in the \fIsource\-mailbox\fP that where not
162
kept or otherwise stored by the Sieve script; i.e. those messages that would
163
normally be discarded if the Sieve script were executed at delivery.
164
The \fIdiscard\-action\fP parameter accepts one of the following values:
154
167
.BR keep\ (default)
155
Keep processed messages in source mailbox. When the filter decides to store the message
156
in the source mailbox, it is never duplicated there. However, in that case, the
157
IMAP flags of the original message can be modified by the Sieve interpreter.
168
Keep discarded messages in source mailbox.
159
170
.BI move\ mailbox
160
Move processed messages to the indicated \fImailbox\fP. This is for instance useful
161
to move messages to a Trash mailbox.
171
Move discarded messages to the indicated \fImailbox\fP. This is for instance
172
useful to move messages to a Trash mailbox.
164
Flag processed messages as \\DELETED.
175
Flag discarded messages as \\DELETED.
167
Expunge processed messages, meaning that these are removed irreversibly when the
178
Expunge discarded messages, meaning that these are removed irreversibly when the
168
179
tool finishes filtering.
171
The \fBsource\-action\fP is normally applied to all messages in the source mailbox,
172
but there are a few exceptions:
175
When the \fB\-W\fP option is not specified, the source mailbox is immutable and
176
the specified \fIsource\-action\fP has no effect.
178
When the \fB\-M\fR option (move mode) is active, all messages that were
179
successfully moved to another mailbox are expunged irrespective of the specified
180
\fIsource\-action\fP.
182
If the filter decides to keep the message in the source mailbox, it is left there
183
and not affected by the \fIsource\-action\fP.
182
When the \fB\-W\fP option is not specified, the \fIsource\-mailbox\fP is
183
immutable and the specified \fIdiscard\-action\fP has no effect. This means that
184
messages are at most \fIcopied\fP to a new location. In contrast, when the
185
\fB\-W\fP is specified, messages that are successfully stored somewhere else by
186
the Sieve script are \fBalways\fP expunged from the \fIsource\-mailbox\fP, with
187
the effect that these are thus \fImoved\fP to the new location. This happens
188
irrespective of the specified \fIdiscard\-action\fP. Remember: only discarded
189
messages are affected by the specified \fIdiscard\-action\fP.
186
191
.\"------------------------------------------------------------------------
added
removed
pigeonhole/doc/man/sieve-filter.1.in
