Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SIEVE-FILTER(1)			  Pigeonhole		       SIEVE-FILTER(1)

       sieve-filter - Pigeonhole's Sieve mailbox filter	tool

       WARNING:	 This  tool is still experimental. Read	this manual carefully,
       and backup any important	mail before using this tool.  Also  note  that
       some  of	the features documented	here are not actually implemented yet;
       this is clearly indicated where applicable.

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

       The sieve-filter	command	is part	of  the	 Pigeonhole  Project  (pigeon-
       hole(7)),  which	 adds  Sieve  (RFC 5228) support to the	Dovecot	secure
       IMAP and	POP3 server (dovecot(1)).

       The Sieve language was originally meant for filtering messages upon de-
       livery.	 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. Us-
       ing the sieve-filter tool it is possible	to apply a Sieve script	on all
       messages	 in  a particular source-mailbox, making it possible to	delete
       messages, to store them in a different mailbox, to  change  their  con-
       tent,  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 and handle outgoing mail	as well.

       If no options are specified, the	sieve-filter command runs in a simula-
       tion  mode in which it only prints what would be	performed, without ac-
       tually doing anything. Use the -e option	to activate true script	execu-
       tion.  Also, the	source-mailbox is opened read-only by default, meaning
       that it normally	always remains unchanged. Use the -W option  to	 allow
       changes in the source-mailbox.

       Even  with  the	-W  option enabled, messages in	the source-mailbox are
       only potentially	modified or moved to a different folder. Messages  are
       never  lost  unless  a discard-action argument other than keep (the de-
       fault) is specified. If the Sieve filter	decides	to store  the  message
       in  the	source-mailbox,	where it obviously already exists, it is never
       duplicated there. In that case, the IMAP	flags of the original  message
       can  be	modified  by the Sieve interpreter using the imap4flags	exten-
       sion, provided that -W is specified. If the message itself is  modified
       by  the	Sieve interpreter (e.g.	using the editheader extension), a new
       message is stored and the old one is expunged. However, if -W is	 omit-
       ted,  the  original message is left untouched and the modifications are

       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 the wrong
       e-mails.	And, even if the source-mailbox	is opened in read-only mode to
       prevent such mishaps, it	can still litter other mailboxes with spurious
       copies  of  your	 e-mails if your Sieve script decides to do so.	There-
       fore, users are advised to read this manual carefully and  to  use  the
       simulation mode first to	check what the script will do. And, of course:


       -c config-file
	      Alternative Dovecot configuration	file path.

       -C     Force  compilation. By default, the compiled binary is stored on
	      disk. When this binary is	found during  the  next	 execution  of
	      sieve-filter  and	 its modification time is more recent than the
	      script file, it is used and the script is	 not  compiled	again.
	      This  option forces the script to	be compiled, thus ignoring any
	      present binary. Refer to sievec(1) for  more  information	 about
	      Sieve compilation.

       -D     Enable Sieve debugging.

       -e     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 per-
	      formed. It only prints what would	be done.  Using	 this  option,
	      the  sieve-filter	 command  becomes  active and performs the re-
	      quested actions.

       -m default-mailbox
	      The mailbox where	the (implicit) keep Sieve action  stores  mes-
	      sages.  This is equal to the source-mailbox by default. Specify-
	      ing a different folder will have the effect of moving (or	 copy-
	      ing if -W	is omitted) all	kept messages to the indicated folder,
	      instead of just leaving them in the source-mailbox. Refer	to the
	      explanation  of the source-mailbox argument for more information
	      on mailbox naming.

       -o setting=value
	      Overrides	the configuration  setting  from  /usr/local/etc/dove-
	      cot/dovecot.conf	and  from the userdb with the given value.  In
	      order to override	multiple settings, the -o option may be	speci-
	      fied multiple times.

       -q output-mailbox [not implemented yet]
	      Store  outgoing e-mail into the indicated	output-mailbox.	By de-
	      fault, the sieve-filter command ignores Sieve  actions  such  as
	      redirect,	 reject,  vacation  and	 notify, but using this	option
	      outgoing messages	can be appended	to the indicated mailbox. This
	      option  has  no  effect  in simulation mode. Flags of redirected
	      messages are not preserved.

       -Q mail-command [not implemented	yet]
	      Send outgoing e-mail (e.g. as produced by	redirect,  reject  and
	      vacation)	  through  the	specified  program.  By	 default,  the
	      sieve-filter command ignores Sieve actions such as redirect, re-
	      ject,  vacation  and notify, but using this option outgoing mes-
	      sages can	be fed to the stdin of an external shell command. This
	      option  has no effect in simulation mode.	Unless you really know
	      what you are doing, DO NOT USE THIS TO FEED MAIL TO SENDMAIL!.

       -s script-file [not implemented yet]
	      Specify additional  scripts  to  be  executed  before  the  main
	      script.  Multiple	 -s  arguments	are  allowed and the specified
	      scripts are executed sequentially	in the order specified at  the
	      command line.

       -u user
	      Run  the Sieve script for	the given user.	When omitted, the com-
	      mand will	be executed with  the  environment  of	the  currently
	      logged in	user.

       -v     Produce verbose output during filtering.

       -W     Enables write access to the source-mailbox. This allows (re)mov-
	      ing the messages from the	source-mailbox,	 changing  their  con-
	      tents, and changing the assigned IMAP flags and keywords.

       -x extensions
	      Set the available	extensions. The	parameter is a space-separated
	      list of the active extensions. By	prepending the extension iden-
	      tifiers with + or	-, extensions can be included or excluded rel-
	      ative to the configured set of active extensions.	If  no	exten-
	      sions  have  a + or - prefix, only those extensions that are ex-
	      plicitly listed will be enabled. Unknown extensions are  ignored
	      and a warning is produced.

	      For  example -x "+imapflags -enotify" will enable	the deprecated
	      imapflags	extension and disable the enotify extension. The  rest
	      of  the  active  extensions  depends on the sieve_extensions and
	      sieve_global_extensions  settings.  By   default,	  i.e.	  when
	      sieve_extensions	and  sieve_global_extensions  remain unconfig-
	      ured, all	supported extensions are available, except for	depre-
	      cated extensions or those	that are still under development.

	      Specifies	the Sieve script to (compile and) execute.

	      Note  that this tool looks for a pre-compiled binary file	with a
	      .svbin extension and with	basename and  path  identical  to  the
	      specified	 script. Use the -C option to disable this behavior by
	      forcing the script to be compiled	into a new binary.

	      Specifies	the source mailbox containing the  messages  that  the
	      Sieve filter will	act upon.

	      This  is	the name of a mailbox, as visible to IMAP clients, ex-
	      cept in UTF-8 format. The	hierarchy separator between  a	parent
	      and  child  mailbox  is commonly '/' or '.', but this depends on
	      your selected mailbox storage format  and	 namespace  configura-
	      tion. The	mailbox	names may also require a namespace prefix.

	      This mailbox is not modified unless the -W option	is specified.

	      Specifies	 what is done with messages in the source-mailbox that
	      where not	kept or	otherwise stored by  the  Sieve	 script;  i.e.
	      those  messages  that  would  normally be	discarded if the Sieve
	      script were executed at delivery.	 The discard-action  parameter
	      accepts one of the following values:

	      keep (default)
		     Keep discarded messages in	source mailbox.

	      move mailbox
		     Move discarded messages to	the indicated mailbox. This is
		     for instance useful to move messages to a Trash  mailbox.
		     Refer  to	the explanation	of the source-mailbox argument
		     for more information on mailbox naming.

	      delete Flag discarded messages as	\DELETED.

		     Expunge discarded messages, meaning that  these  are  re-
		     moved irreversibly	when the tool finishes filtering.

	      When  the	 -W option is not specified, the source-mailbox	is im-
	      mutable and the specified	discard-action	has  no	 effect.  This
	      means  that  messages  are  at most copied to a new location. In
	      contrast,	when the -W is specified, messages that	 are  success-
	      fully  stored  somewhere else by the Sieve script	are always ex-
	      punged from the source-mailbox, with the effect that  these  are
	      thus moved to the	new location. This happens irrespective	of the
	      specified	discard-action.	Remember: only discarded messages  are
	      affected by the specified	discard-action.


       sieve-filter will exit with one of the following	values:

       0   Sieve filter	applied	successfully. (EX_OK, EXIT_SUCCESS)

       1   Operation  failed.  This  is	 returned  for	almost	all  failures.

       64  Invalid parameter given. (EX_USAGE)

	      Dovecot's	main configuration file.

	      Sieve interpreter	settings (included from	Dovecot's main config-
	      uration file)

       Report  bugs, including doveconf	-n output, to the Dovecot Mailing List
       <>.  Information about reporting bugs	 is  available

       dovecot(1),  dovecot-lda(1),  sieve-dump(1),  sieve-test(1), sievec(1),

Pigeonhole for Dovecot v2.4	  2016-04-05		       SIEVE-FILTER(1)


Want to link to this manual page? Use this URL:

home | help