1SIEVE-TEST(1)                     Pigeonhole                     SIEVE-TEST(1)
2
3
4

NAME

6       sieve-test - Pigeonhole's Sieve script tester
7

SYNOPSIS

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

DESCRIPTION

12       The  sieve-test  command  is  part  of  the Pigeonhole Project (pigeon‐
13       hole(7)), which adds Sieve (RFC 5228) support  to  the  Dovecot  secure
14       IMAP and POP3 server (dovecot(1)).
15
16       Using  the  sieve-test  command,  the execution of Sieve scripts can be
17       tested. This evaluates the script for the provided message, yielding  a
18       set  of  Sieve  actions. Unless the -e option is specified, it does not
19       actually execute these actions, meaning that it does not store or  for‐
20       ward  the  message anywere. In stead, it prints a detailed list of what
21       actions would normally take place. Note that, even when  -e  is  speci‐
22       fied,  no  messages are ever transmitted to remote SMTP recipients. The
23       outgoing messages are always printed to stdout in stead.
24
25       This is a very useful tool to debug the execution of Sieve scripts.  It
26       can  be  used to verify newly installed scripts for the intended behav‐
27       iour and it can provide more detailed information about  script  execu‐
28       tion  problems  that  are  reported by the Sieve plugin, for example by
29       tracing the execution and evaluation  of  commands  and  tests  respec‐
30       tively.
31

OPTIONS

33       -c config-file
34              Alternative Dovecot configuration file path.
35
36       -C     Force  compilation. By default, the compiled binary is stored on
37              disk. When this binary is found during  the  next  execution  of
38              sieve-test  and  its  modification  time is more recent than the
39              script file, it is used and the script is  not  compiled  again.
40              This  option forces the script to be compiled, thus ignoring any
41              present binary. Refer to sievec(1) for  more  information  about
42              Sieve compilation.
43
44       -D     Enable Sieve debugging.
45
46       -d dump-file
47              Causes  a dump of the generated code to be written to the speci‐
48              fied  file.  This  is  identical  to  the   dump   produced   by
49              sieve-dump(1). Using '-' as filename causes the dump to be writ‐
50              ten to stdout.
51
52       -e     Enables true execution of the set of actions that  results  from
53              running  the  script.  In combination with the -l parameter, the
54              actual delivery of messages can be tested. Note that  this  will
55              not  transmit  any  messages  to  remote  SMTP  recipients. Such
56              actions only print the outgoing message to stdout.
57
58       -f envelope-sender
59              The envelope sender or return path. This is what  Sieve's  enve‐
60              lope  test  will  compare  to  when  the "from" envelope part is
61              requested. Also, this is where response messages are sent to.
62
63       -l mail-location
64              The location of the  user's  mail  store.  The  syntax  of  this
65              option's  mail-location  parameter  is identical to what is used
66              for the mail_location setting in the Dovecot config  file.  This
67              parameter  is  typically used in combination with -e to test the
68              actual delivery of messages. If -l is omitted when -e is  speci‐
69              fied, mail store actions like fileinto and keep are skipped.
70
71       -m default-mailbox
72              The  mailbox  where  the keep action stores the message. This is
73              "INBOX" by default.
74
75       -r recipient-address
76              The envelope recipient address. This is  what  Sieve's  envelope
77              test  will  compare to when the "to" envelope part is requested.
78              Some tests and actions will also use this as the owner's  e-mail
79              address.
80
81       -s script-file
82              Specify  additional  scripts  to  be  executed  before  the main
83              script. Multiple -s arguments  are  allowed  and  the  specified
84              scripts  are executed sequentially in the order specified at the
85              command line.
86
87       -t trace-file
88              Enables  runtime  trace  debugging.  Trace  debugging   provides
89              detailed  insight  in  the  operations  performed  by  the Sieve
90              script. Refer to the runtime trace debugging section below.  The
91              trace  information  is written to the specified file.  Using '-'
92              as filename causes the trace data to be written to stdout.
93
94       -T trace-option
95              Configures runtime trace debugging, which is enabled with the -t
96              option.  Refer to the runtime trace debugging section below.
97
98       -x extensions
99              Set the available extensions. The parameter is a space-separated
100              list of the active extensions. By prepending the extension iden‐
101              tifiers with + or -, extensions can be included or excluded rel‐
102              ative to the default set of extensions. If no extensions have  a
103              +  or - prefix, only those extensions that are explicitly listed
104              will be enabled. Unknown extensions are ignored and a warning is
105              produced.  By  default,  all supported extensions are available,
106              except for deprecated extensions or those that are  still  under
107              development.
108
109              For  example -x "+imapflags -enotify" will enable the deprecated
110              imapflags extension along with all extensions that are available
111              by default, except for the enotify extension.
112

ARGUMENTS

114       script-file
115              Specifies the script to (compile and) execute.
116
117              Note  that this tool looks for a pre-compiled binary file with a
118              .svbin extension and with basename and  path  identical  to  the
119              specified  script. Use the -C option to disable this behavior by
120              forcing the script to be compiled into a new binary.
121
122       mail-file
123              Specifies the file containing the e-mail message to test with.
124

USAGE

126   RUNTIME TRACE DEBUGGING
127       Using the -t option, the sieve-test tool can  be  configured  to  print
128       detailed  trace  information on the Sieve script execution to a file or
129       standard output. For example, the encountered commands,  the  performed
130       tests and the matched values can be printed.
131
132       The  runtime  trace can be configured using the -T option, which can be
133       specified multiple times. It can be used as follows:
134
135
136       -Tlevel=...
137         Set the detail level of the trace debugging.  One  of  the  following
138         values can be supplied:
139
140         actions (default)
141            Only  print  executed action commands, like keep, fileinto, reject
142            and redirect.
143
144         commands
145            Print any executed command, excluding test commands.
146
147         tests
148            Print all executed commands and performed tests.
149
150         matching
151            Print all  executed  commands,  performed  tests  and  the  values
152            matched in those tests.
153
154       -Tdebug
155         Print  debug messages as well. This is usually only useful for devel‐
156         opers and is likely to produce messy output.
157
158       -Taddresses
159         Print byte code addresses for the  current  trace  output.  Normally,
160         only the current Sieve source code position (line number) is printed.
161         The byte code addresses are equal to those listed in  a  binary  dump
162         produced using the -d option or by the sieve-dump(1) command.
163
164   DEBUG SIEVE EXTENSION
165       To  improve  script  debugging,  the  Sieve  command line tools such as
166       sieve-test support a custom Sieve language extension called  'vnd.dove‐
167       cot.debug'.  It adds the debug_print command that allows printing debug
168       messages to stdout.
169
170       Example:
171
172       require "vnd.dovecot.debug";
173
174       if header :contains "subject" "hello" {
175
176         debug_print "Subject header contains hello!";
177
178       }
179
180       Other tools like sievec and sieve-dump  also  recognize  the  vnd.dove‐
181       cot.debug extension. In contrast, the actual Sieve plugin for the Dove‐
182       cot LDA (dovecot-lda(1)) does not allow the use of the debug extension.
183       So,  keep  in  mind that scripts and compiled binaries that refer to de
184       debug extension will fail to be run by the Sieve plugin itself.
185
186       Note that it is not necessary to enable nor  possible  to  disable  the
187       availability of the debug extension with the -x option.
188

EXIT STATUS

190       sieve-test will exit with one of the following values:
191
192       0   Delivery was successful. (EX_OK, EXIT_SUCCES)
193
194       1   Operation  failed.  This  is  returned  for  almost  all  failures.
195           (EXIT_FAILURE)
196
197       64  Invalid parameter given. (EX_USAGE)
198

FILES

200       /etc/dovecot/dovecot.conf
201              Dovecot's main configuration file.
202
203       /etc/dovecot/conf.d/90-sieve.conf
204              Sieve interpreter settings (included from Dovecot's main config‐
205              uration file)
206

REPORTING BUGS

208       Report  bugs, including doveconf -n output, to the Dovecot Mailing List
209       <dovecot@dovecot.org>.  Information about reporting Dovecot and Pigeon‐
210       hole bugs is available at: http://dovecot.org/bugreport.html
211

SEE ALSO

213       dovecot(1), dovecot-lda(1), sieve-dump(1), sievec(1), pigeonhole(7)
214
215
216
217Pigeonhole for Dovecot v2.0       2011-02-23                     SIEVE-TEST(1)
Impressum