← Back to branch summary

~ubuntu-dev/ubuntu/lucid/dovecot/lucid-201002101901

« back to all changes in this revision

Viewing changes to libsieve/doc/man/sieve-test.1

  • Committer: Chuck Short
  • Date: 2010-01-21 20:21:25 UTC
  • mfrom: (4.1.11 squeeze)
  • Revision ID: zulcss@ubuntu.com-20100121202125-pme73o491kfwj5nc
http://bugs.debian.org/493803
http://bugs.debian.org/523810
http://bugs.debian.org/545582
http://bugs.debian.org/549944
http://bugs.debian.org/554306
http://bugs.debian.org/554710
http://bugs.debian.org/557601
http://bugs.debian.org/558040
https://launchpad.net/bugs/164837
https://launchpad.net/bugs/254721
https://launchpad.net/bugs/329878
* Merge from debian testing, remaining changes:
  + Add new binary pkg dovecot-postfix that integrates postfix and dovecot
    automatically: (LP: #164837)
  + debian/control:
    - add new binary with short description
    - set Architecture all for dovecot-postfix (LP: #329878)
  + debian/dovecot-postfix.postinst:
    - create initial certificate symlinks to snakeoil.
    - set up postfix with postconf to:
      - use Maildir/ as the default mailbox.
      - use dovecot as the sasl authentication server.
      - use dovecot LDA (deliver).
      - use tls for smtp{d} services.
    - fix certificates paths in postfix' main.cf
    - add reject_unauth_destination to postfix' recipient restrictions
    - add reject_unknown_sender_domain to postfix' sender restriction
    - rename configuration name on remove, delete on purge
    - restart dovecot after linking certificates
    - handle use case when postfix is unconfigurated
  + debian/dovecot-postfix.dirs: create backup directory for postfix's config
    configuration
  + restart postfix and dovecot.
  + debian/dovecot-postfix.postrm:
    - remove all dovecot related configuration from postfix.
    - restart postfix and dovecot.
  + debian/dovecot-common.init:
    - check if /etc/dovecot/dovecot-postfix.conf exists and use it
      as the configuration file if so.
  + debian/patches/warning-ubuntu-postfix.dpatch
    - add warning about dovecot-postfix.conf in dovecot default
      configuration file
  + debian/patches/dovecot-postfix.conf.diff:
    - Ubuntu server custom changes to the default dovecot configuration for
      better interfation with postfix.
    - enable sieve plugin.
    - Ubuntu server custom changes to the default dovecot configuration for
      better integration with postfix:
      - enable imap, pop3, imaps, pop3s and managesieve by default.
      - enable dovecot LDA (deliver).
      - enable SASL auth socket in postfix private directory
   + debian/rules:
     - copy, patch and install dovecot-postfix.conf in /etc/dovecot/.
     - build architecure independent packages too
   + Use Snakeoil SSL certificates by default.
     - debian/control: Depend on ssl-cert.
     - debian/patches/ssl-cert-snakeoil.dpatch: Change default SSL cert
       paths to snakeoil.
     - debian/dovecot-common.postinst: Relax grep for SSL_* a bit.
   + Add autopkgtest to debian/tests/*.
   + Fast TearDown: Update the lsb init header to not stop in level 6.
   + Add ufw integration:
     - Created debian/dovecot-common.ufw.profile.
     - debian/rules: install profile.
     - debian/control: suggest ufw.
   + debian/{control,rules}: enable PIE hardening.
   + dovecot-imapd, dovecot-pop3: Replaces dovecot-common (<< 1:1.1). (LP: #254721)
   + debian/control: Update Vcs-* headers.
   + Add SMTP-AUTH support for Outlook (login auth mechanism)
* New upstream release.
* debian/patches/gold-fix.patch: Removed. Fixed upstream.
* Moved libexec to lib corrections in dovecot-managesieve.patch and
  dovecot-managesieve-dist.patch to dovecot-example.patch
* debian/patches/dovecot-mboxlocking.patch: Regenerated to avoid FTBFS
  when quilt isn't installed.
* debian/patches/quota-mountpoint.patch: Removed. Not needed anymore.
* debian/patches/dovecot-quota.patch: Removed. Quotas aren't properly
  enabled unless mail_plugins = quota imap_quota.
* debian/patches/gold-fix.patch: Fixed configure script to build even
  with binutils-gold or --no-add-needed linker flag (Closes: #554306)
* debian/dovecot-common.init: fixed LSB headers. Thanks to Pascal Volk.
  (Closes: #558040)
* debian/changelog: added CVE references to previous changelog entry.
* debian/rules: checked up the build system. It's not fragile anymore.
  (Closes: 493803)
* debian/dovecot-common.postinst: Now invoking dpkg-reconfigure
  on dovecot-common is enough to generate new certificates
  if the previous ones were removed. (Closes: #545582)
* debian/rules: No longer install convert-tool in /usr/bin.
  It isn't an user utility and it should stay in /usr/lib/dovecot
  like all other similar tool.
* New upstream release. (Closes: #557601)
* [SECURITY] Fixes local information disclosure and denial of service.
  (see: http://www.dovecot.org/list/dovecot-news/2009-November/000143.html
  and CVE-2009-3897)
* Added myself to uploaders.
* Switched to the new source format "3.0 (quilt)":
  - removed dpatch from build-depends
  - removed debian/README.source because now we use only standard
    dpkg features
  - regenerated all patches
* Prepared to switch to multi-origin source:
  - recreated dovecot-libsieve.patch and dovecot-managesieve-dist.patch
    starting from the upstream tarball
  - removed all autotools related build-depends and build-conflict
  - renamed dovecot-libsieve and dovecot-managesieve directories
    to libsieve and managesieve.
* debian/rules: Moved the configuration of libsieve and managesieve from
  the build phase to the configuration phase
* Added dovecot-dbg package  with debugging symbols.  Thanks Stephan Bosch.
  (Closes: #554710)
* Fixed some stray libexec'isms in the default configuration.
* New upstream release.
* debian/dovecot-common.init:
  - use $CONF when starting the daemon. (Closes: #549944)
  - always output start/stop messages. (Closes: #523810)

Show diffs side-by-side

added added

removed removed

Lines of Context:
libsieve/doc/man/sieve-test.1
 
1
.TH "SIEVE-TEST" "1" "4 July 2009"
 
2
.SH NAME
 
3
sieve-test \- Sieve script tester for the Dovecot secure IMAP server
 
4
.SH SYNOPSIS
 
5
sieve-test
 
6
[\fB-c\fR] 
 
7
[\fB-d\fR \fIdump-file\fR]
 
8
[\fB-e\fR]
 
9
[\fB-f\fR \fIenvelope-sender\fR]
 
10
[\fB-l\fR \fImail-location\fR]
 
11
[\fB-m\fR \fIdefault-mailbox\fR]
 
12
[\fB-r\fR \fIrecipient-address\fR]
 
13
[\fB-s\fR \fIscript-file\fR]
 
14
[\fB-t\fR]
 
15
[\fB-x\fR "\fIextension extension ...\fR"]
 
16
\fIscript-file\fR \fImail-file\fR
 
17
.SH DESCRIPTION
 
18
.PP
 
19
The \fBsieve-test\fP command is part of the Sieve implementation for the Dovecot secure 
 
20
IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering 
 
21
e-mail messages. It can be implemented for any type of mail access protocol, mail 
 
22
architecture and operating system. The language cannot execute external programs and in 
 
23
its basic form it does not provide the means to cause infinite loops, making it suitable 
 
24
for running securely on mail servers where mail users have no permission run arbitrary programs.
 
25
.PP
 
26
Using the \fBsieve-test\fP command, the execution of Sieve scripts can be tested. This evaluates
 
27
the script for the provided message, yielding a set of Sieve actions. Unless the \fB-e\fP option is 
 
28
specified, it does not actually execute these actions, meaning that it does not store or forward the 
 
29
message anywere. In stead, it prints a detailed list of what actions would normally take place. 
 
30
Note that, even when \fB-e\fP is specified, no messages are ever transmitted to remote SMTP 
 
31
recipients. The outgoing messages are printed to \fBstdout\fP in stead. 
 
32
.PP
 
33
This is a very useful tool to debug the execution of Sieve scripts. It can be used to verify
 
34
newly installed scripts for the intended behaviour and it can provide more detailed information
 
35
about script execution problems that are reported by the Sieve plugin.
 
36
.PP
 
37
The command has two mandatory arguments: the \fIscript-file\fP argument, which specifies the
 
38
script to (compile and) execute, and the \fImail-file\fP argument, which specifies the file 
 
39
containing the e-mail message to filter. 
 
40
 
 
41
Note that this tool looks for a pre-compiled binary file with a \fI.svbin\fP extension and 
 
42
with basename and path identical to the specified script. Use the \fB-c\fP option to disable this
 
43
behavior by forcing the script to be compiled into a new binary.  
 
44
.SH OPTIONS
 
45
.TP 
 
46
\fB-c\fP
 
47
Force compilation. By default, the compiled binary is stored on disk. When this binary is found
 
48
during the next execution of \fBsieve-test\fP and its modification time is more recent than the
 
49
script file, it is used and the script is not compiled again. This option forces the script to be
 
50
compiled, thus ignoring any present binary. Refer to \fBsievec\fP(1) for more information about 
 
51
Sieve compilation.
 
52
.TP
 
53
\fB-d\fP \fIdump-file\fP
 
54
Causes a dump of the generated code to be written to the specified file. This is identical to the
 
55
dump produced by \fBsieved\fR(1). Using '-' as filename causes the dump to be written to \fBstdout\fP.
 
56
.TP
 
57
\fB-e\fP
 
58
Turns on true execution of the set of actions that results from running the script. In combination
 
59
with the \fB-l\fP parameter, the actual delivery of messages can be tested. Note that this will
 
60
not transmit any messages to remote SMTP recipients. Such actions only print the outgoing message
 
61
to \fBstdout\fP.
 
62
.TP
 
63
\fB-f\fP \fIenvelope-sender\fP
 
64
The envelope sender or return path. This is what Sieve's envelope test will compare to when the 
 
65
"from" envelope part is requested. Also, this is where response messages are sent to. 
 
66
.TP
 
67
\fB-l\fP \fImail-location\fP
 
68
The location of the user's mail store. The syntax of this option's \fImail-location\fP parameter 
 
69
is identical to what is used for the mail_location setting in the Dovecot config file. This 
 
70
parameter is typically used in combination with \fB-e\fP to test the actual delivery of messages. 
 
71
If \fB-l\fP is omitted when \fB-e\fP is specified, mail store actions like fileinto and keep are 
 
72
skipped.
 
73
.TP
 
74
\fB-m\fP \fIdefault-mailbox\fP
 
75
The mailbox where the keep action stores the message. This is "INBOX" by default.
 
76
.TP
 
77
\fB-r\fP \fIrecipient-address\fP
 
78
The envelope recipient address. This is what Sieve's envelope test will compare to when the "to"
 
79
envelope part is requested. Some tests and actions will also use this as the owner's e-mail address.
 
80
.TP
 
81
\fB-s\fP \fIscript-file\fP
 
82
Specify additional scripts to be executed before the main script. Multiple \fB-s\fP arguments are
 
83
allowed and the specified scripts are executed sequentially in the order specified at the command
 
84
line.
 
85
.TP
 
86
\fB-t\fP
 
87
Enable simple trace debugging; prints all encountered byte code instructions to \fBstdout\fP. This is
 
88
currently only intelligible for developers.
 
89
.TP
 
90
\fB-x\fP "\fIextension extension ...\fP"
 
91
Set the available extensions. The parameter is a space-separated list of the active extensions. By
 
92
prepending the extension identifiers with \fB+\fP or \fB-\fP, extensions can be included or excluded
 
93
relative to the default set of extensions. If no extensions have a \fB+\fP or \fB-\fP prefix, only 
 
94
those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a 
 
95
warning is produced. By default, all supported extensions are available, except for deprecated extensions 
 
96
or those that are still under development.
 
97
 
 
98
For example \fB-x\fP "+imapflags -enotify" will enable the deprecated imapflags extension along with all
 
99
extensions that are available by default, except for the enotify extension.
 
100
.SH DEBUG SUPPORT
 
101
.PP
 
102
To improve script debugging, the Sieve command line tools such as \fBsieve-test\fP support a custom
 
103
Sieve language extension called 'vnd.dovecot.debug'. It adds the \fBdebug_print\fP command that allows
 
104
printing debug messages to \fBstdout\fP. 
 
105
.PP
 
106
Example:
 
107
.PP
 
108
require "vnd.dovecot.debug";
 
109
.PP
 
110
if header :contains "subject" "hello" {
 
111
.PP
 
112
  debug_print "Subject header contains hello!";
 
113
.PP
 
114
}
 
115
.PP
 
116
Other tools like \fBsievec\fP and \fBsieved\fP also recognize the vnd.dovecot.debug extension. In contrast,
 
117
the actual Sieve plugin for the Dovecot LDA does not allow the use of the debug extension. So, keep in mind that 
 
118
scripts and compiled binaries that refer to de debug extension will fail to be run by the Sieve plugin itself.
 
119
.PP
 
120
Note that it is not necessary to enable nor possible to disable the availability of the debug extension with 
 
121
the \fB-x\fP option.
 
122
.SH AUTHOR
 
123
.PP
 
124
The Sieve implementation for Dovecot was written by Stephan Bosch <stephan@rename-it.nl>.
 
125
.PP
 
126
Dovecot was written by Timo Sirainen <tss@iki.fi>.
 
127
.SH "SEE ALSO"
 
128
.BR sievec (1),
 
129
.BR sieved (1)
 
130