diff --git a/.hgignore b/.hgignore index a091e78e4f139d7f853e6ccb5acc5e847407d13a..4996405ab6d6bd0ad58583d3b2d219ac77dde7b1 100644 --- a/.hgignore +++ b/.hgignore @@ -55,6 +55,11 @@ m4/lt~obsolete.m4 **/.libs **/.deps +doc/man/sievec.1 +doc/man/sieve-dump.1 +doc/man/sieve-test.1 +doc/man/sieve-filter.1 + src/sieve-tools/sievec src/sieve-tools/sieve-dump src/sieve-tools/sieve-test diff --git a/TODO b/TODO index be957ce7381f1ee7bbb1ebd8a3a19d7b816d3bf5..95355fffe946a2b06ced0a1300d746b62d07345f 100644 --- a/TODO +++ b/TODO @@ -10,7 +10,6 @@ Current activities: Next (in order of descending priority/precedence): -* Update man pages to match style of Dovecot man pages. * Enforce ManageSieve protocol syntax better with some of the commands. Some commands still allow spurious extra arguments. * Code cleanup: diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am index eeae3d0992269be6c1782903c88595c5f1434e7a..1a5eefaa1cb6292ef08c09b9d94c286bd61fbec3 100644 --- a/doc/man/Makefile.am +++ b/doc/man/Makefile.am @@ -2,16 +2,36 @@ unfinished = sieve-filter.1 if BUILD_UNFINISHED unfinished_mans = $(unfinished) -else -unfinished_dist = $(unfinished) endif -EXTRA_DIST = \ - $(unfinished_dist) +dist_man1_MANS = \ + sieved.1 -dist_man_MANS = \ +nodist_man1_MANS = \ sievec.1 \ sieve-dump.1 \ sieve-test.1 \ $(unfinished_mans) +nodist_man7_MANS = \ + pigeonhole.7 + +man_includefiles = \ + $(srcdir)/reporting-bugs.inc + +EXTRA_DIST = \ + sievec.1.in \ + sieve-dump.1.in \ + sieve-test.1.in \ + sieve-filter.1.in \ + pigeonhole.7.in + +CLEANFILES = $(nodist_man1_MANS) $(nodist_man7_MANS) + +%.1: $(srcdir)/%.1.in $(man_includefiles) Makefile + $(SHELL) $(srcdir)/sed.sh $(srcdir) $(rundir) $(pkgsysconfdir) \ + < $(srcdir)/$< > $@ + +%.7: $(srcdir)/%.7.in $(man_includefiles) Makefile + $(SHELL) $(srcdir)/sed.sh $(srcdir) $(rundir) $(pkgsysconfdir) \ + < $(srcdir)/$< > $@ diff --git a/doc/man/pigeonhole.7 b/doc/man/pigeonhole.7 new file mode 100644 index 0000000000000000000000000000000000000000..8ee7e1b75de02c1c287e32e3503f1388e7c9c848 --- /dev/null +++ b/doc/man/pigeonhole.7 @@ -0,0 +1,98 @@ +.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file +.TH "PIGEONHOLE" 7 "2010-08-21" "Pigeonhole for Dovecot v2.0" "Pigeonhole" +.\"------------------------------------------------------------------------ +.SH NAME +pigeonhole \- Overview of the Pigeonhole project\(aqs Sieve support for the +Dovecot secure IMAP and POP3 server +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.PP +The Pigeonhole project <http://pigeonhole.dovecot.org> adds support for the +Sieve language (RFC 5228) and the ManageSieve protocol (RFC 5804) to the +Dovecot Secure IMAP and POP3 Server (\fBdovecot\fR(1)). In the literal sense, +a pigeonhole is a a hole or recess inside a dovecot for pigeons to nest in. +It is, however, also the name for one of a series of small, open compartments +in a cabinet used for filing or sorting mail. As a verb, it describes the act +of putting an item into one of those pigeonholes. The name "Pigeonhole" +therefore well describes an important part of the functionality that this +project adds to Dovecot: sorting and filing e-mail messages. +.PP +The Sieve language is used to specify how e-mail needs to be processed. By +writing Sieve scripts, users can customize how messages are delivered, e.g. +whether they are forwarded or stored in special folders. Unwanted messages can +be discarded or rejected, and, when the user is not available, the Sieve +interpreter can send an automated reply. Above all, the Sieve language is meant +to be simple, extensible and system independent. And, unlike most other mail +filtering script languages, it does not allow users to execute arbitrary +programs. This is particularly useful to prevent virtual users from having full +access to the mail store. The intention of the language is to make it impossible +for users to do anything more complex (and dangerous) than write simple mail +filters. +.PP +Using the ManageSieve protocol, users can upload their Sieve scripts remotely, +without needing direct filesystem access through FTP or SCP. Additionally, a +ManageSieve server always makes sure that uploaded scripts are valid, preventing +compile failures at mail delivery. +.PP +The Pigeonhole project provides the following items: +.IP \(bu 4 +The LDA Sieve plugin for Dovecot\(aqs Local Delivery Agent (LDA) +(\fBdovecot-lda\fR(1)) that facilitates the actual Sieve filtering upon +delivery. +.IP \(bu +The ManageSieve Service that implements the ManageSieve protocol through which +users can remotely manage Sieve scripts on the server. +.IP \(bu +Command line tools that provide the means to manually compile, analyse and test +Sieve scripts. +.PP +The functionality and configuration of the LDA Sieve plugin and the ManageSieve +service is described in detail in the README and INSTALL files contained in the +Pigeonhole package and in the Dovecot Wiki +<http://wiki2.dovecot.org/Pigeonhole>. +.PP +The following command line tools are available: +.TP +.BR sievec (1) +Compiles sieve scripts into a binary representation for later execution. +.TP +.BR sieve\-test (1) +The universal Sieve test tool for testing the effect of a Sieve script on a +particular message. +.TP +.BR sieve\-dump (1) +Dumps the content of a Sieve binary file for (development) debugging purposes. +.\"------------------------------------------------------------------------ +.SH REPORTING BUGS +Report bugs, including +.I doveconf \-n +output, to the Dovecot Mailing List <dovecot@dovecot.org>. +Information about reporting Dovecot and Pigeonhole bugs is available at: +http://dovecot.org/bugreport.html +.\"------------------------------------------------------------------------ +.SH AUTHOR +Pigeonhole <http://pigeonhole.dovecot.org> and its manual pages were written by +the Pigeonhole authors <http://pigeonhole.dovecot.org/doc/AUTHORS>, mainly +Stephan Bosch <stephan at rename-it.nl>, and are licensed under the terms of the +LGPLv2.1 license, which is the same license as Dovecot, see +<http://dovecot.org/doc/COPYING> for details. +.\"------------------------------------------------------------------------ +.SH "SEE ALSO" +.BR dovecot (1), +.BR dovecot\-lda (1), +.BR sievec (1), +.BR sieve\-test (1), +.BR sieve\-dump (1) +.\"------------------------------------- +.PP +Additional resources: +.IP "Dovecot website" +http://www.dovecot.org +.IP "Dovecot v2.0 Wiki" +http://wiki2.dovecot.org/Pigeonhole +.IP "Pigeonhole website" +http://pigeonhole.dovecot.org + + + + diff --git a/doc/man/pigeonhole.7.in b/doc/man/pigeonhole.7.in new file mode 100644 index 0000000000000000000000000000000000000000..2d590c43ff79d862c82ae8bc4dda14960b123130 --- /dev/null +++ b/doc/man/pigeonhole.7.in @@ -0,0 +1,93 @@ +.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file +.TH "PIGEONHOLE" 7 "2010-08-21" "Pigeonhole for Dovecot v2.0" "Pigeonhole" +.\"------------------------------------------------------------------------ +.SH NAME +pigeonhole \- Overview of the Pigeonhole project\(aqs Sieve support for the +Dovecot secure IMAP and POP3 server +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.PP +The Pigeonhole project <http://pigeonhole.dovecot.org> adds support for the +Sieve language (RFC 5228) and the ManageSieve protocol (RFC 5804) to the +Dovecot Secure IMAP and POP3 Server (\fBdovecot\fR(1)). In the literal sense, +a pigeonhole is a a hole or recess inside a dovecot for pigeons to nest in. +It is, however, also the name for one of a series of small, open compartments +in a cabinet used for filing or sorting mail. As a verb, it describes the act +of putting an item into one of those pigeonholes. The name "Pigeonhole" +therefore well describes an important part of the functionality that this +project adds to Dovecot: sorting and filing e-mail messages. +.PP +The Sieve language is used to specify how e-mail needs to be processed. By +writing Sieve scripts, users can customize how messages are delivered, e.g. +whether they are forwarded or stored in special folders. Unwanted messages can +be discarded or rejected, and, when the user is not available, the Sieve +interpreter can send an automated reply. Above all, the Sieve language is meant +to be simple, extensible and system independent. And, unlike most other mail +filtering script languages, it does not allow users to execute arbitrary +programs. This is particularly useful to prevent virtual users from having full +access to the mail store. The intention of the language is to make it impossible +for users to do anything more complex (and dangerous) than write simple mail +filters. +.PP +Using the ManageSieve protocol, users can upload their Sieve scripts remotely, +without needing direct filesystem access through FTP or SCP. Additionally, a +ManageSieve server always makes sure that uploaded scripts are valid, preventing +compile failures at mail delivery. +.PP +The Pigeonhole project provides the following items: +.IP \(bu 4 +The LDA Sieve plugin for Dovecot\(aqs Local Delivery Agent (LDA) +(\fBdovecot-lda\fR(1)) that facilitates the actual Sieve filtering upon +delivery. +.IP \(bu +The ManageSieve Service that implements the ManageSieve protocol through which +users can remotely manage Sieve scripts on the server. +.IP \(bu +Command line tools that provide the means to manually compile, analyse and test +Sieve scripts. +.PP +The functionality and configuration of the LDA Sieve plugin and the ManageSieve +service is described in detail in the README and INSTALL files contained in the +Pigeonhole package and in the Dovecot Wiki +<http://wiki2.dovecot.org/Pigeonhole>. +.PP +The following command line tools are available: +.TP +.BR sievec (1) +Compiles sieve scripts into a binary representation for later execution. +.TP +.BR sieve\-test (1) +The universal Sieve test tool for testing the effect of a Sieve script on a +particular message. +.TP +.BR sieve\-dump (1) +Dumps the content of a Sieve binary file for (development) debugging purposes. +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH AUTHOR +Pigeonhole <http://pigeonhole.dovecot.org> and its manual pages were written by +the Pigeonhole authors <http://pigeonhole.dovecot.org/doc/AUTHORS>, mainly +Stephan Bosch <stephan at rename-it.nl>, and are licensed under the terms of the +LGPLv2.1 license, which is the same license as Dovecot, see +<http://dovecot.org/doc/COPYING> for details. +.\"------------------------------------------------------------------------ +.SH "SEE ALSO" +.BR dovecot (1), +.BR dovecot\-lda (1), +.BR sievec (1), +.BR sieve\-test (1), +.BR sieve\-dump (1) +.\"------------------------------------- +.PP +Additional resources: +.IP "Dovecot website" +http://www.dovecot.org +.IP "Dovecot v2.0 Wiki" +http://wiki2.dovecot.org/Pigeonhole +.IP "Pigeonhole website" +http://pigeonhole.dovecot.org + + + + diff --git a/doc/man/reporting-bugs.inc b/doc/man/reporting-bugs.inc new file mode 100644 index 0000000000000000000000000000000000000000..c3288a8ca8f16bda4c10964743d781025fba9c78 --- /dev/null +++ b/doc/man/reporting-bugs.inc @@ -0,0 +1,6 @@ +.SH REPORTING BUGS +Report bugs, including +.I doveconf \-n +output, to the Dovecot Mailing List <dovecot@dovecot.org>. +Information about reporting Dovecot and Pigeonhole bugs is available at: +http://dovecot.org/bugreport.html diff --git a/doc/man/sed.sh b/doc/man/sed.sh new file mode 100644 index 0000000000000000000000000000000000000000..e96c38d5fe916f3df34eeebd7fe0f71bbc41686f --- /dev/null +++ b/doc/man/sed.sh @@ -0,0 +1,11 @@ +#!/bin/sh + +SRCDIR="${1:-`pwd`}" +RUNDIR="${2:-/usr/local/var/run/dovecot}" +PKGSYSCONFDIR="${3:-/usr/local/etc/dovecot}" + +sed -e "/^@INCLUDE:reporting-bugs@$/{ + r ${SRCDIR}/reporting-bugs.inc + d + }" | sed -e "s|@pkgsysconfdir@|${PKGSYSCONFDIR}|" -e "s|@rundir@|${RUNDIR}|" + diff --git a/doc/man/sieve-dump.1 b/doc/man/sieve-dump.1 deleted file mode 100644 index 30bde1647130577c337486715cd7121d91daec35..0000000000000000000000000000000000000000 --- a/doc/man/sieve-dump.1 +++ /dev/null @@ -1,61 +0,0 @@ -.TH "SIEVE-DUMP" "1" "11 July 2010" -.SH NAME -sieve\-dump \- Sieve script binary dump tool for the Dovecot secure IMAP server -.SH SYNOPSIS -sieve\-dump [\fB\-c\fR \fIconfig\-file\fR] [\fB\-x\fR "\fIextension extension ...\fR"] \fIsieve\-binary\fR [\fIout\-file\fR] -.br -.SH DESCRIPTION -.PP -The \fBsieve\-dump\fP command is part of the Pigeonhole Sieve implementation for the Dovecot secure -IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering -e\-mail messages. It can be implemented for any type of mail access protocol, mail -architecture and operating system. The language cannot execute external programs and in -its basic form it does not provide the means to cause infinite loops, making it suitable -for running securely on mail servers where mail users have no permission run arbitrary programs. -.PP -Using the \fBsieve\-dump\fP command, Sieve binaries, which are produced for instance by -\fBsievec\fP(1), can be transformed into a human\-readable textual representation. This can -provide valuable insight in how the Sieve script is executed. This is also particularly useful -to view corrupt binaries that can result from bugs in the Sieve implementation. This tool is -intended mainly for development purposes, so normally system administrators and users will not -need to use this tool. -.PP -The \fIsieve\-binary\fR argument specifies the Sieve binary file that needs to be dumped. The -optional \fIout\-file\fR argument specifies where the output must be written. If omitted, the -output is written to \fBstdout\fR. -.PP -The format of the output is not explained here in detail, but it should be relatively easy -to understand. The Sieve binaries comprise a set of data blocks, each of which can contain -arbitrary data. For the base language implementation two blocks are used: the first containing -a specification of all required language extensions and the second containing the main Sieve -program. Compiled Sieve programs are represented as flat byte code and therefore the dump of -the main program is a disassembly listing of the interpreter operations. Extensions can define -new operations and use additional blocks. Therefore, the output of \fBsieve\-dump\fP depends greatly -on the language extensions used when compiling the binary. -.SH OPTIONS -.TP -\fB\-c\fP \fIconfig\-file\fP -Alternative Dovecot configuration file path. -.TP -\fB\-x\fP "\fIextension extension ...\fP" -Set the available extensions. The parameter is a space\-separated list of the active extensions. By -prepending the extension identifiers with \fB+\fP or \fB\-\fP, extensions can be included or excluded -relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only -those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a -warning is produced. By default, all supported extensions are available, except for deprecated -extensions or those that are still under development. - -For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated imapflags extension along with all -extensions that are available by default, except for the enotify extension. -.SH AUTHOR -.PP -Pigeonhole for Dovecot was written by Stephan Bosch <stephan@rename\-it.nl>. -.PP -Dovecot was written by Timo Sirainen <tss@iki.fi>. -.SH "SEE ALSO" -.BR sievec (1), -.BR sieve\-test (1) -.PP -Dovecot website: http://www.dovecot.org -.PP -Pigeonhole website: http://pigeonhole.dovecot.org diff --git a/doc/man/sieve-dump.1.in b/doc/man/sieve-dump.1.in new file mode 100644 index 0000000000000000000000000000000000000000..3cde03a36c182f22689fa092af87e028d9825157 --- /dev/null +++ b/doc/man/sieve-dump.1.in @@ -0,0 +1,95 @@ +.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file +.TH "SIEVE-DUMP" 1 "2010-08-22" "Pigeonhole for Dovecot v2.0" "Pigeonhole" +.\"------------------------------------------------------------------------ +.SH NAME +sieve\-dump \- Pigeonhole\(aqs Sieve script binary dump tool +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.B sieve\-dump +.RI [ options ] +.I sieve\-binary +.RI [ out\-file ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.PP +The \fBsieve\-dump\fP command is part of the Pigeonhole Project +(\fBpigeonhole\fR(7)), which adds Sieve (RFC 5228) support to the Dovecot +secure IMAP and POP3 server (\fBdovecot\fR(1)). +.PP +Using the \fBsieve\-dump\fP command, Sieve binaries, which are produced for +instance by \fBsievec\fP(1), can be transformed into a human\-readable textual +representation. This can provide valuable insight in how the Sieve script is +executed. This is also particularly useful to view corrupt binaries that can +result from bugs in the Sieve implementation. This tool is intended mainly for +development purposes, so normally system administrators and users will not need +to use this tool. +.PP +The format of the output is not explained here in detail, but it should be +relatively easy to understand. The Sieve binaries comprise a set of data blocks, +each of which can contain arbitrary data. For the base language implementation +two blocks are used: the first containing a specification of all required +language extensions and the second containing the main Sieve program. Compiled +Sieve programs are represented as flat byte code and therefore the dump of the +main program is a disassembly listing of the interpreter operations. Extensions +can define new operations and use additional blocks. Therefore, the output of +\fBsieve\-dump\fP depends greatly on the language extensions used when compiling +the binary. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.TP +.BI \-c\ config\-file +Alternative Dovecot configuration file path. +.TP +.BI \-x\ extensions +Set the available extensions. The parameter is a space\-separated list of the +active extensions. By prepending the extension identifiers with \fB+\fP or +\fB\-\fP, extensions can be included or excluded relative to the default set of +extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only those +extensions that are explicitly listed will be enabled. Unknown extensions are +ignored and a warning is produced. By default, all supported extensions are +available, except for deprecated extensions or those that are still under +development. + +For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated +imapflags extension along with all extensions that are available by default, +except for the enotify extension. +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I sieve\-binary +Specifies the Sieve binary file that needs to be dumped. +.TP +.I out\-file +Specifies where the output must be written. This argument is optional. If +omitted, the output is written to \fBstdout\fR. +.\"------------------------------------------------------------------------ +.SH "EXIT STATUS" +.B sieve\-dump +will exit with one of the following values: +.TP 4 +.B 0 +Delivery was successful. (EX_OK, EXIT_SUCCES) +.TP +.B 1 +Operation failed. This is returned for almost all failures. +(EXIT_FAILURE) +.TP +.B 64 +Invalid parameter given. (EX_USAGE) +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @pkgsysconfdir@/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @pkgsysconfdir@/conf.d/90\-sieve.conf +Sieve interpreter settings (included from Dovecot\(aqs main configuration file) +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH "SEE ALSO" +.BR pigeonhole (7), +.BR sieve\-test (1), +.BR sievec (1), +.BR dovecot (1), +.BR dovecot-lda (1) diff --git a/doc/man/sieve-filter.1 b/doc/man/sieve-filter.1.in similarity index 97% rename from doc/man/sieve-filter.1 rename to doc/man/sieve-filter.1.in index 5733eb9bf0a095f7075f01b0c296e5f9b1f175f0..c7efc02f85ada50cc1411a5d63aa67b496c2dbab 100644 --- a/doc/man/sieve-filter.1 +++ b/doc/man/sieve-filter.1.in @@ -141,12 +141,15 @@ extensions that are available by default, except for the enotify extension. .TP [...] +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ .SH AUTHOR .PP The Sieve implementation for Dovecot was written by Stephan Bosch <stephan@rename\-it.nl>. .PP Dovecot was written by Timo Sirainen <tss@iki.fi>. - +.\"------------------------------------------------------------------------ .SH "SEE ALSO" .BR sievec (1), .BR sieve\-dump (1), diff --git a/doc/man/sieve-test.1 b/doc/man/sieve-test.1 deleted file mode 100644 index 031fe121308429fad20faa874d0875c3c491d960..0000000000000000000000000000000000000000 --- a/doc/man/sieve-test.1 +++ /dev/null @@ -1,182 +0,0 @@ -.TH "SIEVE\-TEST" "1" "11 July 2010" -.SH NAME -sieve\-test \- Sieve script tester for the Dovecot secure IMAP server -.SH SYNOPSIS -sieve\-test -[\fB\-c\fR \fIconfig\-file\fR] -[\fB\-C\fR] -[\fB\-D\fR] -[\fB\-d\fR \fIdump\-file\fR] -[\fB\-e\fR] -[\fB\-f\fR \fIenvelope\-sender\fR] -[\fB\-l\fR \fImail\-location\fR] -[\fB\-m\fR \fIdefault\-mailbox\fR] -[\fB\-r\fR \fIrecipient\-address\fR] -[\fB\-s\fR \fIscript\-file\fR] -[\fB\-t\fR \fItrace\-option\fR] -[\fB\-x\fR "\fIextension extension ...\fR"] -\fIscript\-file\fR \fImail\-file\fR -.SH DESCRIPTION -.PP -The \fBsieve\-test\fP command is part of the Pigeonhole Sieve implementation for the Dovecot secure -IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering -e\-mail messages. It can be implemented for any type of mail access protocol, mail -architecture and operating system. The language cannot execute external programs and in -its basic form it does not provide the means to cause infinite loops, making it suitable -for running securely on mail servers where mail users have no permission run arbitrary programs. -.PP -Using the \fBsieve\-test\fP command, the execution of Sieve scripts can be tested. This evaluates -the script for the provided message, yielding a set of Sieve actions. Unless the \fB\-e\fP option is -specified, it does not actually execute these actions, meaning that it does not store or forward the -message anywere. In stead, it prints a detailed list of what actions would normally take place. -Note that, even when \fB\-e\fP is specified, no messages are ever transmitted to remote SMTP -recipients. The outgoing messages are printed to \fBstdout\fP in stead. -.PP -This is a very useful tool to debug the execution of Sieve scripts. It can be used to verify -newly installed scripts for the intended behaviour and it can provide more detailed information -about script execution problems that are reported by the Sieve plugin. -.PP -The command has two mandatory arguments: the \fIscript\-file\fP argument, which specifies the -script to (compile and) execute, and the \fImail\-file\fP argument, which specifies the file -containing the e\-mail message to filter. - -Note that this tool looks for a pre\-compiled binary file with a \fI.svbin\fP extension and -with basename and path identical to the specified script. Use the \fB\-C\fP option to disable this -behavior by forcing the script to be compiled into a new binary. -.SH OPTIONS -.TP -\fB\-c\fP \fIconfig\-file\fP -Alternative Dovecot configuration file path. -.TP -\fB\-C\fP -Force compilation. By default, the compiled binary is stored on disk. When this binary is found -during the next execution of \fBsieve\-test\fP and its modification time is more recent than the -script file, it is used and the script is not compiled again. This option forces the script to be -compiled, thus ignoring any present binary. Refer to \fBsievec\fP(1) for more information about -Sieve compilation. -.TP -\fB\-D\fP -Enable Sieve debugging. -.TP -\fB\-d\fP \fIdump\-file\fP -Causes a dump of the generated code to be written to the specified file. This is identical to the -dump produced by \fBsieve\-dump\fR(1). Using '\-' as filename causes the dump to be written to \fBstdout\fP. -.TP -\fB\-e\fP -Turns on true execution of the set of actions that results from running the script. In combination -with the \fB\-l\fP parameter, the actual delivery of messages can be tested. Note that this will -not transmit any messages to remote SMTP recipients. Such actions only print the outgoing message -to \fBstdout\fP. -.TP -\fB\-f\fP \fIenvelope\-sender\fP -The envelope sender or return path. This is what Sieve's envelope test will compare to when the -"from" envelope part is requested. Also, this is where response messages are sent to. -.TP -\fB\-l\fP \fImail\-location\fP -The location of the user's mail store. The syntax of this option's \fImail\-location\fP parameter -is identical to what is used for the mail_location setting in the Dovecot config file. This -parameter is typically used in combination with \fB\-e\fP to test the actual delivery of messages. -If \fB\-l\fP is omitted when \fB\-e\fP is specified, mail store actions like fileinto and keep are -skipped. -.TP -\fB\-m\fP \fIdefault\-mailbox\fP -The mailbox where the keep action stores the message. This is "INBOX" by default. -.TP -\fB\-r\fP \fIrecipient\-address\fP -The envelope recipient address. This is what Sieve's envelope test will compare to when the "to" -envelope part is requested. Some tests and actions will also use this as the owner's e\-mail address. -.TP -\fB\-s\fP \fIscript\-file\fP -Specify additional scripts to be executed before the main script. Multiple \fB\-s\fP arguments are -allowed and the specified scripts are executed sequentially in the order specified at the command -line. -.TP -\fB\-t\fP \fItrace\-file\fP -Enables runtime trace debugging. Trace debugging provides detailed insight in the operations performed -by the Sieve script. Refer to the runtime trace debugging section below. The trace information is -written to the specified file. Using '\-' as filename causes the trace data to be written to \fBstdout\fP. -.TP -\fB\-T\fP \fItrace\-option\fP -Configures runtime trace debugging, which is enabled with the \fP\-t\fP option. Refer to the runtime -trace debugging section below. -.TP -\fB\-x\fP "\fIextension extension ...\fP" -Set the available extensions. The parameter is a space\-separated list of the active extensions. By -prepending the extension identifiers with \fB+\fP or \fB\-\fP, extensions can be included or excluded -relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only -those extensions that are explicitly listed will be enabled. Unknown extensions are ignored and a -warning is produced. By default, all supported extensions are available, except for deprecated extensions -or those that are still under development. - -For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated imapflags extension along with all -extensions that are available by default, except for the enotify extension. - -.SH RUNTIME TRACE DEBUGGING -.PP -Using the \fB-t\fP option, the \fBsieve\-test\fP tool can be configured to print detailed trace information -on the Sieve script execution to a file or standard output. For example, the encountered commands, the -performed tests and the matched values can be printed. -.PP -The runtime trace can be configured using the \fB\-T\fP option, which can be specified multiple times. -It can be used as follows: - -.TP 2 -\fB\-Tlevel=...\fP -Set the verbosity level of the trace debugging. One of the following values can be supplied: -.RS 2 -.TP 3 -\fIactions\fP (default) -Only print executed action commands, like keep, fileinto, reject and redirect. -.TP -\fIcommands\fP -Print any command, excluding tests. -.TP -\fItests\fP -Print all commands and performed tests. -.TP -\fImatching\fP -Print all commands, performed tests and the values matched for those tests. -.RE -.TP 2 -\fB\-Tdebug\fP -Print debug messages as well. This is usually only useful for developers and produces messy output. -.TP -\fB\-Taddresses\fP -Print byte code addresses for the current trace output. Normally, only the current Sieve source code -position is printed. The byte code addresses are equal to those listed in a binary dump produced -using the \fB\-d\fP option or by the \fBsieve\-dump(1)\fP command. - -.SH DEBUG SIEVE EXTENSION -.PP -To improve script debugging, the Sieve command line tools such as \fBsieve\-test\fP support a custom -Sieve language extension called 'vnd.dovecot.debug'. It adds the \fBdebug_print\fP command that allows -printing debug messages to \fBstdout\fP. -.PP -Example: -.PP -require "vnd.dovecot.debug"; -.PP -if header :contains "subject" "hello" { -.PP - debug_print "Subject header contains hello!"; -.PP -} -.PP -Other tools like \fBsievec\fP and \fBsieve\-dump\fP also recognize the vnd.dovecot.debug extension. In contrast, -the actual Sieve plugin for the Dovecot LDA does not allow the use of the debug extension. So, keep in mind that -scripts and compiled binaries that refer to de debug extension will fail to be run by the Sieve plugin itself. -.PP -Note that it is not necessary to enable nor possible to disable the availability of the debug extension with -the \fB\-x\fP option. -.SH AUTHOR -.PP -Pigeonhole for Dovecot was written by Stephan Bosch <stephan@rename\-it.nl>. -.PP -Dovecot was written by Timo Sirainen <tss@iki.fi>. -.SH "SEE ALSO" -.BR sievec (1), -.BR sieve\-dump (1) -.PP -Dovecot website: http://www.dovecot.org -.PP -Pigeonhole website: http://pigeonhole.dovecot.org diff --git a/doc/man/sieve-test.1.in b/doc/man/sieve-test.1.in new file mode 100644 index 0000000000000000000000000000000000000000..29e44830626d0c0034bd9b536fd920472fed1039 --- /dev/null +++ b/doc/man/sieve-test.1.in @@ -0,0 +1,221 @@ +.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file +.TH "SIEVE-TEST" 1 "2010-08-22" "Pigeonhole for Dovecot v2.0" "Pigeonhole" +.SH NAME +sieve\-test \- Pigeonhole\(aqs Sieve script tester +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.B sieve\-test +.RI [ options ] +.I script\-file +.I mail\-file +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.PP +The \fBsieve\-test\fP command is part of the Pigeonhole Project +(\fBpigeonhole\fR(7)), which adds Sieve (RFC 5228) support to the Dovecot +secure IMAP and POP3 server (\fBdovecot\fR(1)). +.PP +Using the \fBsieve\-test\fP command, the execution of Sieve scripts can be +tested. This evaluates the script for the provided message, yielding a set of +Sieve actions. Unless the \fB\-e\fP option is specified, it does not actually +execute these actions, meaning that it does not store or forward the message +anywere. In stead, it prints a detailed list of what actions would normally take +place. Note that, even when \fB\-e\fP is specified, no messages are ever +transmitted to remote SMTP recipients. The outgoing messages are always printed +to \fBstdout\fP in stead. +.PP +This is a very useful tool to debug the execution of Sieve scripts. It can be +used to verify newly installed scripts for the intended behaviour and it can +provide more detailed information about script execution problems that are +reported by the Sieve plugin, for example by tracing the execution and +evaluation of commands and tests respectively. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.TP +.BI \-c\ config\-file +Alternative Dovecot configuration file path. +.TP +.B \-C +Force compilation. By default, the compiled binary is stored on disk. When this +binary is found during the next execution of \fBsieve\-test\fP and its +modification time is more recent than the script file, it is used and the script +is not compiled again. This option forces the script to be compiled, thus +ignoring any present binary. Refer to \fBsievec\fP(1) for more information about +Sieve compilation. +.TP +.B \-D +Enable Sieve debugging. +.TP +.BI \-d\ dump\-file +Causes a dump of the generated code to be written to the specified file. This is +identical to the dump produced by \fBsieve\-dump\fR(1). Using '\-' as filename +causes the dump to be written to \fBstdout\fP. +.TP +.BI \-e +Enables true execution of the set of actions that results from running the +script. In combination with the \fB\-l\fP parameter, the actual delivery of +messages can be tested. Note that this will not transmit any messages to remote +SMTP recipients. Such actions only print the outgoing message to \fBstdout\fP. +.TP +.BI \-f\ envelope\-sender +The envelope sender or return path. This is what Sieve's envelope test will +compare to when the "from" envelope part is requested. Also, this is where +response messages are sent to. +.TP +.BI \-l\ mail\-location +The location of the user's mail store. The syntax of this option's +\fImail\-location\fP parameter is identical to what is used for the +mail_location setting in the Dovecot config file. This parameter is typically +used in combination with \fB\-e\fP to test the actual delivery of messages. If +\fB\-l\fP is omitted when \fB\-e\fP is specified, mail store actions like +fileinto and keep are skipped. +.TP +.BI \-m\ default\-mailbox +The mailbox where the keep action stores the message. This is "INBOX" by +default. +.TP +.BI \-r\ recipient\-address +The envelope recipient address. This is what Sieve's envelope test will compare +to when the "to" envelope part is requested. Some tests and actions will also +use this as the owner's e\-mail address. +.TP +.BI \-s\ script\-file +Specify additional scripts to be executed before the main script. Multiple +\fB\-s\fP arguments are allowed and the specified scripts are executed +sequentially in the order specified at the command +line. +.TP +.BI \-t\ trace\-file +Enables runtime trace debugging. Trace debugging provides detailed insight in +the operations performed by the Sieve script. Refer to the runtime trace +debugging section below. The trace information is written to the specified file. +Using '\-' as filename causes the trace data to be written to \fBstdout\fP. +.TP +.BI \-T\ trace\-option +Configures runtime trace debugging, which is enabled with the \fP\-t\fP option. +Refer to the runtime trace debugging section below. +.TP +.BI \-x\ extensions +Set the available extensions. The parameter is a space\-separated list of the +active extensions. By prepending the extension identifiers with \fB+\fP or +\fB\-\fP, extensions can be included or excluded relative to the default set of +extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only those +extensions that are explicitly listed will be enabled. Unknown extensions are +ignored and a warning is produced. By default, all supported extensions are +available, except for deprecated extensions or those that are still under +development. + +For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated +imapflags extension along with all extensions that are available by default, +except for the enotify extension. +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I script\-file +Specifies the script to (compile and) execute. + +Note that this tool looks for a pre\-compiled binary file with a \fI.svbin\fP +extension and with basename and path identical to the specified script. Use the +\fB\-C\fP option to disable this behavior by forcing the script to be compiled +into a new binary. +.TP +.I mail\-file +Specifies the file containing the e\-mail message to test with. +.\"------------------------------------------------------------------------ +.SH USAGE +.SS RUNTIME TRACE DEBUGGING +.PP +Using the \fB-t\fP option, the \fBsieve\-test\fP tool can be configured to print +detailed trace information on the Sieve script execution to a file or standard +output. For example, the encountered commands, the performed tests and the +matched values can be printed. +.PP +The runtime trace can be configured using the \fB\-T\fP option, which can be +specified multiple times. It can be used as follows: + +.TP 2 +\fB\-Tlevel=...\fP +Set the detail level of the trace debugging. One of the following values can +be supplied: +.RS 2 +.TP 3 +\fIactions\fP (default) +Only print executed action commands, like keep, fileinto, reject and redirect. +.TP +\fIcommands\fP +Print any executed command, excluding test commands. +.TP +\fItests\fP +Print all executed commands and performed tests. +.TP +\fImatching\fP +Print all executed commands, performed tests and the values matched in those +tests. +.RE +.TP 2 +\fB\-Tdebug\fP +Print debug messages as well. This is usually only useful for developers and +is likely to produce messy output. +.TP +\fB\-Taddresses\fP +Print byte code addresses for the current trace output. Normally, only the +current Sieve source code position (line number) is printed. The byte code +addresses are equal to those listed in a binary dump produced using the +\fB\-d\fP option or by the \fBsieve\-dump(1)\fP command. +.\"------------------------------------------------------------------------ +.SS DEBUG SIEVE EXTENSION +.PP +To improve script debugging, the Sieve command line tools such as +\fBsieve\-test\fP support a custom Sieve language extension called +'vnd.dovecot.debug'. It adds the \fBdebug_print\fP command that allows printing +debug messages to \fBstdout\fP. +.PP +Example: +.PP +require "vnd.dovecot.debug"; +.PP +if header :contains "subject" "hello" { +.PP + debug_print "Subject header contains hello!"; +.PP +} +.PP +Other tools like \fBsievec\fP and \fBsieve\-dump\fP also recognize the +vnd.dovecot.debug extension. In contrast, the actual Sieve plugin for the +Dovecot LDA (\fBdovecot-lda\fR(1)) does not allow the use of the debug +extension. So, keep in mind that scripts and compiled binaries that refer to de +debug extension will fail to be run by the Sieve plugin itself. +.PP +Note that it is not necessary to enable nor possible to disable the availability +of the debug extension with the \fB\-x\fP option. +.\"------------------------------------------------------------------------ +.SH "EXIT STATUS" +.B sieve\-test +will exit with one of the following values: +.TP 4 +.B 0 +Delivery was successful. (EX_OK, EXIT_SUCCES) +.TP +.B 1 +Operation failed. This is returned for almost all failures. +(EXIT_FAILURE) +.TP +.B 64 +Invalid parameter given. (EX_USAGE) +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @pkgsysconfdir@/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @pkgsysconfdir@/conf.d/90\-sieve.conf +Sieve interpreter settings (included from Dovecot\(aqs main configuration file) +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH "SEE ALSO" +.BR pigeonhole (7), +.BR sievec (1), +.BR sieve\-dump (1), +.BR dovecot (1), +.BR dovecot-lda (1) diff --git a/doc/man/sievec.1 b/doc/man/sievec.1 deleted file mode 100644 index dffd0f640a5516d90e1c66f1675c77d2152de767..0000000000000000000000000000000000000000 --- a/doc/man/sievec.1 +++ /dev/null @@ -1,78 +0,0 @@ -.TH "SIEVEC" "1" "11 July 2010" -.SH NAME -sievec \- Sieve script compiler for the Dovecot secure IMAP server -.SH SYNOPSIS -sievec [\fB\-c\fR \fIconfig\-file\fR] [\fB\-d\fR] [\fB\-x\fR "\fIextension extension ...\fR"] \fIscript\-file\fR [\fIout\-file\fR] -.SH DESCRIPTION -.PP -The \fBsievec\fP command is part of the Pigeonhole Sieve implementation for the Dovecot secure -IMAP server. Sieve (RFC 5228) is a simple and highly extensible language for filtering -e\-mail messages. It can be implemented for any type of mail access protocol, mail -architecture and operating system. The language cannot execute external programs and in -its basic form it does not provide the means to cause infinite loops, making it suitable -for running securely on mail servers where mail users have no permission run arbitrary programs. -.PP -Using the \fBsievec\fP command, Sieve scripts can be compiled into a binary representation. -The resulting binary can be used directly to process e\-mail messages during the delivery process. -The delivery of mail messages and therefore also the execution of Sieve scripts is -performed by Dovecot's local delivery agent (LDA) called \fBdeliver\fP. Usually, it is not -necessary to compile the Sieve script manually using \fBsievec\fP, because \fBdeliver\fP will do -this automatically if the binary is missing. However, in some cases \fBdeliver\fP does not have -permission to write the compiled binary to disk, forcing it to recompile the script every time it -is executed. Using the \fBsievec\fP tool, this can be performed manually by an authorized user to -increase performance. -.PP -The \fBsievec\fP command accepts two arguments: the \fIscript\-file\fP argument specifies the -script to be compiled and the \fIout\-file\fR argument specifies where the (binary) output is to -be written. This Sieve implementation reconizes files with a \fB.sieve\fP extension as Sieve -scripts and corresponding files with a \fB.svbin\fP extension as the associated compiled binary. -This means for example that Dovecot's deliver process will look for a binary file 'dovecot.svbin' -when it needs to execute 'dovecot.sieve'. Such filename is chosen automatically for the binary output -when the out\-file argument is missing. -.PP -If the \fIscript\-file\fP argument is a directory, all files in that directory with a \fI.sieve\fP -extension are compiled into a corresponding \fI.svbin\fP binary file. The compilation is not halted -upon errors; it attempts to compile as many scripts in the directory as possible. Note that the -\fB\-d\fP option and the \fIout\-file\fP argument are not allowed when the \fIscript\-file\fP argument -is a directory. -.PP -The \fBsievec\fP command is also useful to verify Sieve scripts before using. Additionally, with -the \fB\-d\fP option it can output a textual (and thus human\-readable) dump of the generated Sieve -code to the specified file. The output is then identical to what the \fBsieve\-dump\fP(1) command produces -for a stored binary file. This output is mainly useful to find bugs in the compiler that yield corrupt -binaries. -.SH OPTIONS -.TP -\fB\-c\fP \fIconfig\-file\fP -Alternative Dovecot configuration file path. -.TP -\fB\-d\fP -Don't write the binary to \fIout\-file\fP, but write a textual dump of the binary in -stead. In this context, the \fIout\-file\fP value '\-' has special meaning: it causes the the textual -dump to be written to \fBstdout\fP. The \fIout\-file\fP argument may also be omitted, which has -the same effect as '\-'. The output is identical to what the \fBsieve\-dump\fP(1) command produces for -a compiled Sieve binary file. Note that this option is not allowed when the \fIout\-file\fP argument -is a directory. -.TP -\fB\-x\fP "\fIextension extension ...\fP" -Set the available extensions. The parameter is a space\-separated list of the active extensions. By -prepending the extension identifiers with \fB+\fP or \fB\-\fP, extensions can be included or excluded -relative to the default set of extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only -those extensions that are explicitly listed will be enabled. Unknown extensions are ignored -and a warning is produced. By default, all supported extensions are available, except for deprecated -extensions or those that are still under development. - -For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated imapflags extension along with all -extensions that are available by default, except for the enotify extension. -.SH AUTHOR -.PP -Pigeonhole for Dovecot was written by Stephan Bosch <stephan@rename\-it.nl>. -.PP -Dovecot was written by Timo Sirainen <tss@iki.fi>. -.SH "SEE ALSO" -.BR sieve\-dump (1), -.BR sieve\-test (1) -.PP -Dovecot website: http://www.dovecot.org -.PP -Pigeonhole website: http://pigeonhole.dovecot.org diff --git a/doc/man/sievec.1.in b/doc/man/sievec.1.in new file mode 100644 index 0000000000000000000000000000000000000000..757a203b5ab03c25c546124298a09b530e47afd6 --- /dev/null +++ b/doc/man/sievec.1.in @@ -0,0 +1,117 @@ +.\" Copyright (c) 2010 Pigeonhole authors, see the included COPYING file +.TH "SIEVEC" 1 "2010-08-22" "Pigeonhole for Dovecot v2.0" "Pigeonhole" +.\"------------------------------------------------------------------------ +.SH NAME +sievec \- Pigeonhole\(aqs Sieve script compiler +.\"------------------------------------------------------------------------ +.SH SYNOPSIS +.B sievec +.RI [ options ] +.I script\-file +.RI [ out\-file ] +.\"------------------------------------------------------------------------ +.SH DESCRIPTION +.PP +The \fBsieve\-dump\fP command is part of the Pigeonhole Project +(\fBpigeonhole\fR(7)), which adds Sieve (RFC 5228) support to the Dovecot +secure IMAP and POP3 server (\fBdovecot\fR(1)). +.PP +Using the \fBsievec\fP command, Sieve scripts can be compiled into a binary +representation. The resulting binary can be used directly to process e\-mail +messages during the delivery process. The delivery of mail messages and \- by +means of the LDA Sieve plugin \- also the execution of Sieve scripts is +performed by Dovecot\aqs local delivery agent (LDA) called \fBdovecot-lda\fP(1). +Usually, it is not necessaryto compile the Sieve script manually using +\fBsievec\fP, because \fBdovecot-lda\fP will do this automatically if the binary +is missing. However, in some cases \fBdovecot-lda\fP does not have permission to +write the compiled binary to disk, forcing it to recompile the script every time +it is executed. Using the \fBsievec\fP tool, this can be performed manually by +an authorized user to increase performance. +.PP +The Pigeonhole Sieve implementation recognizes files with a \fB.sieve\fP +extension as Sieve scripts and corresponding files with a \fB.svbin\fP extension +as the associated compiled binary. This means for example that Dovecot\(aqs LDA +process will first look for a binary file "dovecot.svbin" when it needs to +execute "dovecot.sieve". It will compile a new binary when it is missing. +.PP +The \fBsievec\fP command is also useful to verify Sieve scripts before using. +Additionally, with the \fB\-d\fP option it can output a textual (and thus +human\-readable) dump of the generated Sieve code to the specified file. The +output is then identical to what the \fBsieve\-dump\fP(1) command produces for a +stored binary file. This output is mainly useful to find bugs in the compiler +that yield corrupt binaries. +.\"------------------------------------------------------------------------ +.SH OPTIONS +.TP +.BI \-c\ config\-file +Alternative Dovecot configuration file path. +.TP +.B \-d +Don't write the binary to \fIout\-file\fP, but write a textual dump of the +binary instead. In this context, the \fIout\-file\fP value '\-' has special +meaning: it causes the the textual dump to be written to \fBstdout\fP. +The \fIout\-file\fP argument may also be omitted, which has the same effect as +'\-'. The output is identical to what the \fBsieve\-dump\fP(1) command produces +for a compiled Sieve binary file. Note that this option is not allowed when the +\fIout\-file\fP argument is a directory. +.TP +.BI \-x\ extensions +Set the available extensions. The parameter is a space\-separated list of the +active extensions. By prepending the extension identifiers with \fB+\fP or +\fB\-\fP, extensions can be included or excluded relative to the default set of +extensions. If no extensions have a \fB+\fP or \fB\-\fP prefix, only +those extensions that are explicitly listed will be enabled. Unknown extensions +are ignored and a warning is produced. By default, all supported extensions are +available, except for deprecated extensions or those that are still under +development. + +For example \fB\-x\fP "+imapflags \-enotify" will enable the deprecated +imapflags extension along with all extensions that are available by default, +except for the enotify extension. +.\"------------------------------------------------------------------------ +.SH ARGUMENTS +.TP +.I script\-file +Specifies the script to be compiled. If the \fIscript\-file\fP argument is a +directory, all files in that directory with a \fI.sieve\fP extension are +compiled into a corresponding \fI.svbin\fP binary file. The compilation is not +halted upon errors; it attempts to compile as many scripts in the directory as +possible. Note that the \fB\-d\fP option and the \fIout\-file\fP argument are +not allowed when the \fIscript\-file\fP argument is a directory. +.TP +.I out\-file +Specifies where the (binary) output is to be written. This argument is optional. +If omitted a binary compiled from <scriptname>.sieve is saved as +<scriptname>.svbin. If \fB\-b\fP is specified, the binary dump is output to +\fBstdout\fP. +.\"------------------------------------------------------------------------ +.SH "EXIT STATUS" +.B sievec +will exit with one of the following values: +.TP 4 +.B 0 +Delivery was successful. (EX_OK, EXIT_SUCCES) +.TP +.B 1 +Operation failed. This is returned for almost all failures. +(EXIT_FAILURE) +.TP +.B 64 +Invalid parameter given. (EX_USAGE) +.\"------------------------------------------------------------------------ +.SH FILES +.TP +.I @pkgsysconfdir@/dovecot.conf +Dovecot\(aqs main configuration file. +.TP +.I @pkgsysconfdir@/conf.d/90\-sieve.conf +Sieve interpreter settings (included from Dovecot\(aqs main configuration file) +.\"------------------------------------------------------------------------ +@INCLUDE:reporting-bugs@ +.\"------------------------------------------------------------------------ +.SH "SEE ALSO" +.BR pigeonhole (7), +.BR sieve\-test (1), +.BR sieve\-dump (1), +.BR dovecot (1), +.BR dovecot-lda (1)