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

FreeBSD Manual Pages

  
 
  

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

NAME
       sieve-test - Pigeonhole's Sieve script tester

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

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

OPTIONS
       -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 recipient@example.com.

       -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	sender@example.com.

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

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

       mail-file
	      Specifies	the file containing the	e-mail message to test with.

USAGE
   RUNTIME TRACE DEBUGGING
       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:

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

	 commands
	    Print any executed command,	excluding test commands.

	 tests
	    Print all executed commands	and performed tests.

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

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

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

   DEBUG SIEVE EXTENSION
       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.

       Example:

       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.

EXIT STATUS
       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.
	   (EXIT_FAILURE)

       64  Invalid parameter given. (EX_USAGE)

FILES
       /usr/local/etc/dovecot/dovecot.conf
	      Dovecot's	main configuration file.

       /usr/local/etc/dovecot/conf.d/90-sieve.conf
	      Sieve interpreter	settings (included from	Dovecot's main config-
	      uration file)

REPORTING BUGS
       Report  bugs, including doveconf	-n output, to the Dovecot Mailing List
       <dovecot@dovecot.org>.  Information about reporting bugs	 is  available
       at: http://dovecot.org/bugreport.html

SEE ALSO
       dovecot(1),  dovecot-lda(1), sieve-dump(1), sieve-filter(1), sievec(1),
       pigeonhole(7)

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

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=sieve-test&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help