sieve-test(category34-froxlor.html) - phpMan

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
              requested.  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
              recipient address defaults to recipient AT 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
              actions 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
              address defaults to sender AT example.com.
       -l mail-location
              The location of the  user's  mail  store.  The  syntax  of  this
              option's  mail-location  parameter  is identical to what is used
              for the mail_location setting in the Dovecot config  file.  This
              parameter  is  typically used in combination with -e to test the
              actual 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  /etc/dovecot/dove-
              cot.conf  and from the userdb with the given value.  In order to
              override multiple settings, the -o option may be specified  mul-
              tiple 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
              detailed 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
              explicitly  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
       detailed 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
       /etc/dovecot/dovecot.conf
              Dovecot's main configuration file.
       /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 AT 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)