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

FreeBSD Manual Pages


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

       sieve-test - Pigeonhole's Sieve script tester

       sieve-test [options] script-file	mail-file

       The  sieve-test	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)).

       Using  the  sieve-test  command,	 the execution of Sieve	scripts	can be
       tested. This evaluates the script for the provided message, yielding  a
       set  of	Sieve  actions.	Unless the -e option is	specified, it does not
       actually	execute	these actions, meaning that it does not	store or  for-
       ward  the  message  anywere. Instead, it	prints a detailed list of what
       actions would normally take place. Note that, even when	-e  is	speci-
       fied,  no  messages are ever transmitted	to remote SMTP recipients. The
       outgoing	messages are always printed to stdout instead.

       This is a very useful tool to debug the execution of Sieve scripts.  It
       can  be	used to	verify newly installed scripts for the intended	behav-
       iour and	it can provide more detailed information about	script	execu-
       tion  problems  that  are  reported by the Sieve	plugin,	for example by
       tracing the execution and evaluation  of	 commands  and	tests  respec-

       -a orig-recipient-address
	      The  original  envelope  recipient address. This is what Sieve's
	      envelope test will compare to when the "to" envelope part	is re-
	      quested. Some tests and actions will also	use this as the	script
	      owner's e-mail address. If this option is	omitted, the recipient
	      address  is  retrieved from the "Envelope-To:", or "To:" message
	      headers. If none of these	headers	is present either, the recipi-
	      ent address defaults to

       -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-test  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.

       -d dump-file
	      Causes  a	dump of	the generated code to be written to the	speci-
	      fied  file.  This	 is  identical	to  the	  dump	 produced   by
	      sieve-dump(1). Using '-' as filename causes the dump to be writ-
	      ten to stdout.

       -e     Enables true execution of	the set	of actions that	 results  from
	      running  the  script.  In	combination with the -l	parameter, the
	      actual delivery of messages can be tested. Note that  this  will
	      not  transmit  any  messages to remote SMTP recipients. Such ac-
	      tions only print the outgoing message to stdout.

       -f envelope-sender
	      The envelope sender address (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.
	      If  this option is omitted, the sender address is	retrieved from
	      the "Return-Path:", "Sender:" or	"From:"	 message  headers.  If
	      none of these headers is present either, the sender envelope ad-
	      dress defaults to

       -l mail-location
	      The location of the user's mail store. The syntax	 of  this  op-
	      tion's  mail-location parameter is identical to what is used for
	      the mail_location	setting	in the Dovecot config file.  This  pa-
	      rameter is typically used	in combination with -e to test the ac-
	      tual delivery of messages. If -l is omitted when	-e  is	speci-
	      fied, mail store actions like fileinto and keep are skipped.

       -m default-mailbox
	      The  mailbox  where  the keep action stores the message. This is
	      "INBOX" by default.

       -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.

       -r recipient-address
	      The  final  envelope  recipient  address.	Some tests and actions
	      will use this as the script owner's e-mail address. For example,
	      this  is	what is	used by	the vacation action to check whether a
	      reply is appropriate. If the -r option is	omitted, the  original
	      envelope	recipient  address will	be used	instead	(see -a	option
	      for more info).

       -s script-file
	      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.

       -t trace-file
	      Enables  runtime	trace  debugging. Trace	debugging provides de-
	      tailed insight in	the operations performed by the	Sieve  script.
	      Refer  to	 the  runtime trace debugging section below. The trace
	      information is written to	the  specified	file.	Using  '-'  as
	      filename causes the trace	data to	be written to stdout.

       -T trace-option
	      Configures runtime trace debugging, which	is enabled with	the -t
	      option.  Refer to	the runtime trace debugging section below.

       -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.

       -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 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 file containing the	e-mail message to test with.

       Using the -t option, the	sieve-test tool	can be configured to print de-
       tailed trace information	on the Sieve script execution  to  a  file  or
       standard	 output.  For example, the encountered commands, the performed
       tests and the matched values can	be printed.

       The runtime trace can be	configured using the -T	option,	which  can  be
       specified multiple times. It can	be used	as follows:

	 Set  the  detail  level  of the trace debugging. One of the following
	 values	can be supplied:

	 actions (default)
	    Only print executed	action commands, like keep,  fileinto,	reject
	    and	redirect.

	    Print any executed command,	excluding test commands.

	    Print all executed commands	and performed tests.

	    Print  all	executed  commands,  performed	tests  and  the	values
	    matched in those tests.

	 Print debug messages as well. This is usually only useful for	devel-
	 opers and is likely to	produce	messy output.

	 Print	byte  code  addresses  for the current trace output. Normally,
	 only the current Sieve	source code position (line number) is printed.
	 The  byte  code  addresses are	equal to those listed in a binary dump
	 produced using	the -d option or by the	sieve-dump(1) command.

       To improve script debugging, this Sieve implementation supports a  cus-
       tom  Sieve  language  extension called 'vnd.dovecot.debug'. It adds the
       debug_log command that allows logging debug messages.


       require "vnd.dovecot.debug";

       if header :contains "subject" "hello" {

	 debug_log "Subject header contains hello!";


       Tools such as sieve-test, sievec	and sieve-dump have  support  for  the
       vnd.dovecot.debug  extension enabled by default and it is not necessary
       to enable nor possible to disable the availability of the debug	exten-
       sion  with  the -x option. The logged messages are written to stdout in
       this case.

       In contrast, for	the actual Sieve plugin	for  the  Dovecot  LDA	(dove-
       cot-lda(1)) the vnd.dovecot.debug extension needs to be enabled explic-
       itly using the sieve_extensions setting.	The messages are  then	logged
       to  the user's private script log file. If used in a global script, the
       messages	are logged through the default Dovecot logging facility.

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

       0   Execution was successful. (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-filter(1),  sievec(1),

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


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

home | help