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. Instead, 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 instead.
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       -a orig-recipient-address
34              The  original  envelope  recipient address. This is what Sieve's
35              envelope test will compare to when the  "to"  envelope  part  is
36              requested.  Some  tests  and  actions  will also use this as the
37              script owner's e-mail address. If this option  is  omitted,  the
38              recipient address is retrieved from the "Envelope-To:", or "To:"
39              message headers. If none of these headers is present either, the
40              recipient address defaults to recipient@example.com.
41
42       -c config-file
43              Alternative Dovecot configuration file path.
44
45       -C     Force  compilation. By default, the compiled binary is stored on
46              disk. When this binary is found during  the  next  execution  of
47              sieve-test  and  its  modification  time is more recent than the
48              script file, it is used and the script is  not  compiled  again.
49              This  option forces the script to be compiled, thus ignoring any
50              present binary. Refer to sievec(1) for  more  information  about
51              Sieve compilation.
52
53       -D     Enable Sieve debugging.
54
55       -d dump-file
56              Causes  a dump of the generated code to be written to the speci‐
57              fied  file.  This  is  identical  to  the   dump   produced   by
58              sieve-dump(1). Using '-' as filename causes the dump to be writ‐
59              ten to stdout.
60
61       -e     Enables true execution of the set of actions that  results  from
62              running  the  script.  In combination with the -l parameter, the
63              actual delivery of messages can be tested. Note that  this  will
64              not  transmit  any  messages  to  remote  SMTP  recipients. Such
65              actions only print the outgoing message to stdout.
66
67       -f envelope-sender
68              The envelope sender address (return path). This is what  Sieve's
69              envelope  test  will compare to when the "from" envelope part is
70              requested. Also, this is where response messages are 'sent'  to.
71              If  this option is omitted, the sender address is retrieved from
72              the "Return-Path:", "Sender:" or  "From:"  message  headers.  If
73              none  of  these  headers  is present either, the sender envelope
74              address defaults to sender@example.com.
75
76       -l mail-location
77              The location of the  user's  mail  store.  The  syntax  of  this
78              option's  mail-location  parameter  is identical to what is used
79              for the mail_location setting in the Dovecot config  file.  This
80              parameter  is  typically used in combination with -e to test the
81              actual delivery of messages. If -l is omitted when -e is  speci‐
82              fied, mail store actions like fileinto and keep are skipped.
83
84       -m default-mailbox
85              The  mailbox  where  the keep action stores the message. This is
86              "INBOX" by default.
87
88       -o setting=value
89              Overrides  the  configuration  setting  from  /etc/dovecot/dove‐
90              cot.conf  and from the userdb with the given value.  In order to
91              override multiple settings, the -o option may be specified  mul‐
92              tiple times.
93
94       -r recipient-address
95              The  final  envelope  recipient  address. Some tests and actions
96              will use this as the script owner's e-mail address. For example,
97              this  is  what is used by the vacation action to check whether a
98              reply is appropriate. If the -r option is omitted, the  original
99              envelope  recipient  address will be used instead (see -a option
100              for more info).
101
102       -s script-file
103              Specify additional  scripts  to  be  executed  before  the  main
104              script.  Multiple  -s  arguments  are  allowed and the specified
105              scripts are executed sequentially in the order specified at  the
106              command line.
107
108       -t trace-file
109              Enables   runtime  trace  debugging.  Trace  debugging  provides
110              detailed insight  in  the  operations  performed  by  the  Sieve
111              script.  Refer to the runtime trace debugging section below. The
112              trace information is written to the specified file.   Using  '-'
113              as filename causes the trace data to be written to stdout.
114
115       -T trace-option
116              Configures runtime trace debugging, which is enabled with the -t
117              option.  Refer to the runtime trace debugging section below.
118
119       -u user
120              Run the Sieve script for the given user. When omitted, the  com‐
121              mand  will  be  executed  with  the environment of the currently
122              logged in user.
123
124       -x extensions
125              Set the available extensions. The parameter is a space-separated
126              list of the active extensions. By prepending the extension iden‐
127              tifiers with + or -, extensions can be included or excluded rel‐
128              ative  to  the configured set of active extensions. If no exten‐
129              sions have a + or -  prefix,  only  those  extensions  that  are
130              explicitly  listed  will  be  enabled.  Unknown  extensions  are
131              ignored and a warning is produced.
132
133              For example -x "+imapflags -enotify" will enable the  deprecated
134              imapflags  extension and disable the enotify extension. The rest
135              of the active extensions depends  on  the  sieve_extensions  and
136              sieve_global_extensions   settings.   By   default,  i.e.   when
137              sieve_extensions and  sieve_global_extensions  remain  unconfig‐
138              ured,  all supported extensions are available, except for depre‐
139              cated extensions or those that are still under development.
140
141

ARGUMENTS

143       script-file
144              Specifies the script to (compile and) execute.
145
146              Note that this tool looks for a pre-compiled binary file with  a
147              .svbin  extension  and  with  basename and path identical to the
148              specified script. Use the -C option to disable this behavior  by
149              forcing the script to be compiled into a new binary.
150
151       mail-file
152              Specifies the file containing the e-mail message to test with.
153

USAGE

155   RUNTIME TRACE DEBUGGING
156       Using  the  -t  option,  the sieve-test tool can be configured to print
157       detailed trace information on the Sieve script execution to a  file  or
158       standard  output.  For example, the encountered commands, the performed
159       tests and the matched values can be printed.
160
161       The runtime trace can be configured using the -T option, which  can  be
162       specified multiple times. It can be used as follows:
163
164
165       -Tlevel=...
166         Set  the  detail  level  of the trace debugging. One of the following
167         values can be supplied:
168
169         actions (default)
170            Only print executed action commands, like keep,  fileinto,  reject
171            and redirect.
172
173         commands
174            Print any executed command, excluding test commands.
175
176         tests
177            Print all executed commands and performed tests.
178
179         matching
180            Print  all  executed  commands,  performed  tests  and  the values
181            matched in those tests.
182
183       -Tdebug
184         Print debug messages as well. This is usually only useful for  devel‐
185         opers and is likely to produce messy output.
186
187       -Taddresses
188         Print  byte  code  addresses  for the current trace output. Normally,
189         only the current Sieve source code position (line number) is printed.
190         The  byte  code  addresses are equal to those listed in a binary dump
191         produced using the -d option or by the sieve-dump(1) command.
192
193   DEBUG SIEVE EXTENSION
194       To improve script debugging, this Sieve implementation supports a  cus‐
195       tom  Sieve  language  extension called 'vnd.dovecot.debug'. It adds the
196       debug_log command that allows logging debug messages.
197
198       Example:
199
200       require "vnd.dovecot.debug";
201
202       if header :contains "subject" "hello" {
203
204         debug_log "Subject header contains hello!";
205
206       }
207
208       Tools such as sieve-test, sievec and sieve-dump have  support  for  the
209       vnd.dovecot.debug  extension enabled by default and it is not necessary
210       to enable nor possible to disable the availability of the debug  exten‐
211       sion  with  the -x option. The logged messages are written to stdout in
212       this case.
213
214       In contrast, for the actual Sieve plugin for  the  Dovecot  LDA  (dove‐
215       cot-lda(1)) the vnd.dovecot.debug extension needs to be enabled explic‐
216       itly using the sieve_extensions setting. The messages are  then  logged
217       to  the user's private script log file. If used in a global script, the
218       messages are logged through the default Dovecot logging facility.
219

EXIT STATUS

221       sieve-test will exit with one of the following values:
222
223       0   Execution was successful. (EX_OK, EXIT_SUCCESS)
224
225       1   Operation  failed.  This  is  returned  for  almost  all  failures.
226           (EXIT_FAILURE)
227
228       64  Invalid parameter given. (EX_USAGE)
229

FILES

231       /etc/dovecot/dovecot.conf
232              Dovecot's main configuration file.
233
234       /etc/dovecot/conf.d/90-sieve.conf
235              Sieve interpreter settings (included from Dovecot's main config‐
236              uration file)
237

REPORTING BUGS

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

SEE ALSO

244       dovecot(1), dovecot-lda(1), sieve-dump(1), sieve-filter(1),  sievec(1),
245       pigeonhole(7)
246
247
248
249Pigeonhole v0.5 for Dovecot v2.3  2017-12-18                     SIEVE-TEST(1)
Impressum