156 lines
8.2 KiB
Diff
156 lines
8.2 KiB
Diff
diff -up dovecot-1.2-sieve-0.1.11/doc/man/sieve-filter.1.devnull dovecot-1.2-sieve-0.1.11/doc/man/sieve-filter.1
|
|
--- /dev/null 2009-08-10 16:08:33.895265368 +0200
|
|
+++ dovecot-1.2-sieve-0.1.11/doc/man/sieve-filter.1 2009-08-10 16:08:02.899248904 +0200
|
|
@@ -0,0 +1,151 @@
|
|
+.TH "SIEVE-FILTER" "1" "5 August 2009"
|
|
+.SH NAME
|
|
+sieve-filter \- Sieve mailbox filter tool for the Dovecot secure IMAP server
|
|
+.PP
|
|
+\fBWARNING: \fRThis tool is not finished and should \fB*NOT*\fR be used, unless you feel like testing newly developed
|
|
+features! The behavior described in this manual page represents the design and not necessarily what the tool currently implements.
|
|
+
|
|
+.SH SYNOPSIS
|
|
+sieve-filter [\fIoptions\fR] \fIscript-file\fR \fIsource-location\fR \fIsource-mailbox\fR [\fIinbox-namespace\fR [\fInamespace\fR ...]]
|
|
+.TP
|
|
+\fInamepace\fR = [prefix=]location[;option=value,option=value,...]
|
|
+.TP
|
|
+[FIXME: what would be the easiest way to specify a filter operation without always needing to
|
|
+delve into the complexity of namespaces]
|
|
+
|
|
+.SH DESCRIPTION
|
|
+.PP
|
|
+The \fBsieve-filter\fP command is part of the Sieve implementation for the Dovecot secure
|
|
+IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering
|
|
+e-mail messages. It can be implemented for any type of mail access protocol, mail
|
|
+architecture and operating system. The language cannot execute external programs and in
|
|
+its basic form it does not provide the means to cause infinite loops, making it suitable
|
|
+for running securely on mail servers where mail users have no permission run arbitrary programs.
|
|
+.PP
|
|
+The Sieve language was originally meant for filtering messages upon delivery. However, there are
|
|
+occasions when it is desirable to filter messages that are already stored in a mailbox, for
|
|
+instance when a bug in a Sieve script caused many messages to be delivered incorrectly.
|
|
+Using the sieve-filter tool it is possible to apply a Sieve script on all messages in a particular
|
|
+mailbox, making it possible to delete messages, to store them in a different folder and to change
|
|
+the assigned IMAP flags and keywords. Attempts to send messages to the outside world are ignored by default
|
|
+for obvious reasons, but, using the proper command line options, it is possible to capture outgoing
|
|
+mail as well.
|
|
+.PP
|
|
+The command has three mandatory arguments: the \fIscript-file\fP argument, which specifies the path of the
|
|
+Sieve script, the \fIsource-location\fP argument, which specifies the mail storage of the source mailbox
|
|
+(e.g. `maildir:~/Maildir'), and the \fIsource-mailbox\fP argument, which specifies the name of the source
|
|
+mailbox within the specified mail storage (e.g. `INBOX.Spam').
|
|
+.PP
|
|
+This tool does not (yet) use Dovecot's configuration file to obtain information on namespaces and the
|
|
+location of mailboxes. Therefore, any used namespaces need to be specified on the command line. These
|
|
+specifications directly follow the \fIsource-mailbox\fP parameter. The first specified namespace will
|
|
+be the INBOX namespace.
|
|
+.PP
|
|
+If no namespaces are defined on the commandline, the source-location is used as the default mail store
|
|
+where the INBOX is located. This means that the keep action could operate on the folder the message
|
|
+originates from. In this case the message remains untouched and it is not duplicated, but IMAP flags and
|
|
+keywords can be evaluated and changed with the imap4flags extension . If namespaces are defined explicitly,
|
|
+the source location is available as a namespace with prefix `#src/'.
|
|
+.PP
|
|
+If no options are specified, the sieve-filter command runs in a simulation mode in which it only
|
|
+prints what would be performed, without actually doing anything. Use the \fB-e\fP option to activate
|
|
+true script execution. Also, the source mailbox is opened read-only by default, so that the source mailbox
|
|
+remains unchanged. Use the \fB-W\fP to allow changes in the source mailbox.
|
|
+
|
|
+.SH CAUTION
|
|
+Although this is a very useful tool, it can also be very destructive when used improperly. A small
|
|
+bug in your Sieve script in combination with the wrong command line options could cause it to
|
|
+discard (many) more e-mails than it was supposed to. Therefore, users are advised to read this manual
|
|
+carefully and to use the simulation mode first to check what the script will do.
|
|
+.PP
|
|
+\fBMAKING A BACKUP IS IMPERATIVE FOR ANY IMPORTANT MAIL!\fP
|
|
+.PP
|
|
+By default, it will open the source mailbox in a read-only mode, such that it will not delete any of your
|
|
+e-mails. However, it can still litter other mailboxes with spurious copies of your e-mails if your
|
|
+Sieve script decides to do so.
|
|
+
|
|
+.SH OPTIONS
|
|
+.TP
|
|
+\fB-D\fP \fIsource-action\fP
|
|
+By default, the sieve-filter command does not delete the messages from the source mailbox. This means that
|
|
+a copy operation is executed by default and the source mailbox is not altered. The \fIsource-action\fP
|
|
+parameter of the \fB-D\fP option can take four different values:
|
|
+.RS 7
|
|
+.TP
|
|
+\fBkeep\fP (default)
|
|
+Keep messages in source folder. If \fB-W\fR is specified and the source mailbox is the destination of
|
|
+a keep or fileinto action, flags can be changed by the Sieve script. Messages are never duplicated in the
|
|
+source mailbox.
|
|
+.TP
|
|
+\fBflag\fP
|
|
+Flag messages as \\DELETED.
|
|
+.TP
|
|
+\fBmove\fP [\fIfolder\fP]
|
|
+Move messages to the indicated \fIfolder\fP.
|
|
+.TP
|
|
+\fBexpunge\fP
|
|
+Expunge messages, meaning that these are removed irreversibly when the tool finishes filtering.
|
|
+.PP
|
|
+Note that values other than `keep' have no effect, unless the \fB-W\fP option is specified as well.
|
|
+.RE
|
|
+.TP
|
|
+\fB-e\fP
|
|
+Turns on execution mode. By default, the sieve-filter command runs in simulation mode in which it
|
|
+changes nothing, meaning that no mailbox is altered in any way and no actions are performed. It only
|
|
+prints what would be done. Using this option the sieve-filter command becomes active and performs the
|
|
+requested actions.
|
|
+.TP
|
|
+\fB-f\fP \fIenvelope-sender\fP
|
|
+The envelope sender or return path. This is what Sieve's envelope test will compare to when the
|
|
+"from" envelope part is requested. Also, this is where response messages are sent to.
|
|
+.TP
|
|
+\fB-m\fP \fIdefault-mailbox\fP
|
|
+The mailbox within the default namespace where the keep action stores the message. This is "INBOX"
|
|
+by default.
|
|
+.TP
|
|
+\fB-Q\fP \fImail-command\fP
|
|
+Send outgoing e-mail through the specified program. By default, the sieve-filter command ignores
|
|
+Sieve actions such as redirect, reject, vacation and notify, but using this option outgoing messages
|
|
+can be fed to the \fBstdin\fP of an external shell command. This option has no effect in simulation
|
|
+mode, Unless you really know what you are doing, \fBDO NOT USE THIS TO FEED MAIL TO SENDMAIL!\f.
|
|
+.TP
|
|
+\fB-r\fP \fIrecipient-address\fP
|
|
+The envelope recipient address. This is what Sieve's envelope test will compare to when the "to"
|
|
+envelope part is requested. Some tests and actions will also use this as the owner's e-mail address.
|
|
+.TP
|
|
+\fB-S\fP \fIscript-file\fP
|
|
+Specify additional scripts to be executed before the main script. Multiple \fB-s\fP arguments are
|
|
+allowed and the specified scripts are executed sequentially in the order specified at the command
|
|
+line.
|
|
+.TP
|
|
+\fB-W\fP
|
|
+Enables write access to the source mailbox. This allows deleting the messages from the source mailbox
|
|
+and changing the assigned IMAP flags and keywords.
|
|
+.TP
|
|
+\fB-x\fP "\fIextension extension ...\fP"
|
|
+Set the available extensions. The parameter is a space-separated list of the active extensions. By
|
|
+prepending the extension identifiers with \fB+\fP or \fB-\fP, extensions can be included or excluded
|
|
+relative to the default set of extensions. If no extensions have a \fB+\fP or \fB-\fP prefix, only
|
|
+those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a
|
|
+warning is produced. By default, all supported extensions are available, except for deprecated extensions
|
|
+or those that are still under development.
|
|
+
|
|
+For example \fB-x\fP "+imapflags -enotify" will enable the deprecated imapflags extension along with all
|
|
+extensions that are available by default, except for the enotify extension.
|
|
+
|
|
+.SH EXAMPLES
|
|
+
|
|
+.TP
|
|
+[...]
|
|
+
|
|
+.SH AUTHOR
|
|
+.PP
|
|
+The Sieve implementation for Dovecot was written by Stephan Bosch <stephan@rename-it.nl>.
|
|
+.PP
|
|
+Dovecot was written by Timo Sirainen <tss@iki.fi>.
|
|
+
|
|
+.SH "SEE ALSO"
|
|
+.BR sievec (1),
|
|
+.BR sieved (1),
|
|
+.BR sieve-test (1)
|
|
+
|