1SIEVE-TEST(1) Pigeonhole SIEVE-TEST(1)
2
6 sieve-test - Pigeonhole's Sieve script tester
7
9 sieve-test [options] script-file mail-file
10
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 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 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
33 -c config-file
34 Alternative Dovecot configuration file path.
35 -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 -D Enable Sieve debugging.
45 -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 -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 -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 -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 -m default-mailbox
72 The mailbox where the keep action stores the message. This is
73 "INBOX" by default.
74 -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 -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 -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 -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 -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 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
114 script-file
115 Specifies the script to (compile and) execute.
116 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 mail-file
123 Specifies the file containing the e-mail message to test with.
124
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 The runtime trace can be configured using the -T option, which can be
133 specified multiple times. It can be used as follows:
134 -Tlevel=...
137 Set the detail level of the trace debugging. One of the following
138 values can be supplied:
139 actions (default)
141 Only print executed action commands, like keep, fileinto, reject
142 and redirect.
143 commands
145 Print any executed command, excluding test commands.
146 tests
148 Print all executed commands and performed tests.
149 matching
151 Print all executed commands, performed tests and the values
152 matched in those tests.
153 -Tdebug
155 Print debug messages as well. This is usually only useful for devel‐
156 opers and is likely to produce messy output.
157 -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 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 Example:
171 require "vnd.dovecot.debug";
173 if header :contains "subject" "hello" {
175 debug_print "Subject header contains hello!";
177 }
179 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 Note that it is not necessary to enable nor possible to disable the
187 availability of the debug extension with the -x option.
188
190 sieve-test will exit with one of the following values:
191 0 Delivery was successful. (EX_OK, EXIT_SUCCES)
193 1 Operation failed. This is returned for almost all failures.
195 (EXIT_FAILURE)
196 64 Invalid parameter given. (EX_USAGE)
198
200 /usr/local/etc/dovecot/dovecot.conf
201 Dovecot's main configuration file.
202 /usr/local/etc/dovecot/conf.d/90-sieve.conf
204 Sieve interpreter settings (included from Dovecot's main config‐
205 uration file)
206
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
213 dovecot(1), dovecot-lda(1), sieve-dump(1), sievec(1), pigeonhole(7)
214Pigeonhole for Dovecot v2.0 2010-08-23 SIEVE-TEST(1)