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. 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 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 -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 -c config-file
43 Alternative Dovecot configuration file path.
44 -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 -D Enable Sieve debugging.
54 -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 -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 -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 -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 -m default-mailbox
85 The mailbox where the keep action stores the message. This is
86 "INBOX" by default.
87 -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 -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 -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 -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 -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 -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 -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 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
143 script-file
144 Specifies the script to (compile and) execute.
145 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 mail-file
152 Specifies the file containing the e-mail message to test with.
153
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 The runtime trace can be configured using the -T option, which can be
162 specified multiple times. It can be used as follows:
163 -Tlevel=...
166 Set the detail level of the trace debugging. One of the following
167 values can be supplied:
168 actions (default)
170 Only print executed action commands, like keep, fileinto, reject
171 and redirect.
172 commands
174 Print any executed command, excluding test commands.
175 tests
177 Print all executed commands and performed tests.
178 matching
180 Print all executed commands, performed tests and the values
181 matched in those tests.
182 -Tdebug
184 Print debug messages as well. This is usually only useful for devel‐
185 opers and is likely to produce messy output.
186 -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 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 Example:
199 require "vnd.dovecot.debug";
201 if header :contains "subject" "hello" {
203 debug_log "Subject header contains hello!";
205 }
207 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 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
221 sieve-test will exit with one of the following values:
222 0 Execution was successful. (EX_OK, EXIT_SUCCESS)
224 1 Operation failed. This is returned for almost all failures.
226 (EXIT_FAILURE)
227 64 Invalid parameter given. (EX_USAGE)
229
231 /etc/dovecot/dovecot.conf
232 Dovecot's main configuration file.
233 /etc/dovecot/conf.d/90-sieve.conf
235 Sieve interpreter settings (included from Dovecot's main config‐
236 uration file)
237
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
244 dovecot(1), dovecot-lda(1), sieve-dump(1), sieve-filter(1), sievec(1),
245 pigeonhole(7)
246Pigeonhole v0.5 for Dovecot v2.3 2017-12-18 SIEVE-TEST(1)