Adding upstream version 1:2.3.19.1+dfsg1.upstream/1%2.3.19.1+dfsg1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 257 insertions, 0 deletions

diff --git a/pigeonhole/doc/man/sieve-test.1.in b/pigeonhole/doc/man/sieve-test.1.in
new file mode 100644
index 0000000..65e5230
--- /dev/null
+++ b/pigeonhole/doc/man/sieve-test.1.in
@@ -0,0 +1,257 @@
+.\" Copyright (c) 2010-2018 Pigeonhole authors, see the included COPYING file
+.TH "SIEVE\-TEST" 1 "2016-04-05" "Pigeonhole for Dovecot v2.4" "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. Instead, 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 instead.
+.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 \-a\  orig\-recipient\-address
+The original envelope recipient address. This is what Sieve\(aqs envelope test
+will compare to when the \(dqto\(dq envelope part is requested. Some tests and
+actions will also use this as the script owner\(aqs e\-mail address. If this
+option is omitted, the recipient address is retrieved from the
+\(dqEnvelope-To:\(dq, or \(dqTo:\(dq message headers. If none of these headers
+is present either, the recipient address defaults to
+\fIrecipient@example.com\fP.
+.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 \(aq\-\(aq 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 address (return path). This is what Sieve\(aqs envelope test
+will compare to when the \(dqfrom\(dq envelope part is requested. Also, this is
+where response messages are \(aqsent\(aq to. If this option is omitted, the sender
+address is retrieved from the \(dqReturn-Path:\(dq, \(dqSender:\(dq or
+\(dqFrom:\(dq message headers. If none of these headers is present either,
+the sender envelope address defaults to \fIsender@example.com\fP.
+.TP
+.BI \-l\  mail\-location
+The location of the user\(aqs mail store. The syntax of this option\(aqs
+\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 \(dqINBOX\(dq
+by default.
+.TP
+.BI \-o\  setting = value
+Overrides the configuration
+.I setting
+from
+.I @pkgsysconfdir@/dovecot.conf
+and from the userdb with the given
+.IR value .
+In order to override multiple settings, the
+.B \-o
+option may be specified multiple times.
+.TP
+.BI \-r\  recipient\-address
+The final envelope recipient address. Some tests and actions will
+use this as the script owner\(aqs e\-mail address. For example, this is what is
+used by the vacation action to check whether a reply is appropriate. If the
+\fB\-r\fP option is omitted, the original envelope recipient address will be used
+instead (see \fB\-a\fP option for more info).
+.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 \-u\  user
+Run the Sieve script for the given \fIuser\fP. When omitted, the
+.I command
+will be executed with the environment of the currently logged in user.
+.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 configured set
+of active 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.
+
+For example \fB\-x\fP \(dq+imapflags \-enotify\(dq will enable the deprecated
+imapflags extension and disable the enotify extension. The rest of the active
+extensions depends on the \fIsieve_extensions\fP and
+\fIsieve_global_extensions\fP settings. By default, i.e.
+when \fIsieve_extensions\fP and \fIsieve_global_extensions\fP remain
+unconfigured, all supported extensions are available, except for deprecated
+extensions or those that are still under development.
+
+.\"------------------------------------------------------------------------
+.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, this Sieve implementation supports a custom Sieve
+language extension called \(aqvnd.dovecot.debug\(aq. It adds the \fBdebug_log\fP
+command that allows logging debug messages.
+.PP
+Example:
+.PP
+require \(dqvnd.dovecot.debug\(dq;
+.PP
+if header :contains \(dqsubject\(dq \(dqhello\(dq {
+.PP
+  debug_log \(dqSubject header contains hello!\(dq;
+.PP
+}
+.PP
+Tools such as \fBsieve\-test\fP, \fBsievec\fP and \fBsieve\-dump\fP have support
+for the vnd.dovecot.debug extension enabled by default and it is not necessary
+to enable nor possible to disable the availability of the debug extension with
+the \fB\-x\fP option. The logged messages are written to \fBstdout\fP in this
+case.
+
+In contrast, for the actual Sieve plugin for the Dovecot LDA
+(\fBdovecot\-lda\fR(1)) the vnd.dovecot.debug extension needs to be enabled
+explicitly using the \fIsieve_extensions\fP setting. The messages are then
+logged to the user's private script log file. If used in a global script, the
+messages are logged through the default Dovecot logging facility.
+.\"------------------------------------------------------------------------
+.SH "EXIT STATUS"
+.B sieve\-test
+will exit with one of the following values:
+.TP 4
+.B 0
+Execution was successful. (EX_OK, EXIT_SUCCESS)
+.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 dovecot (1),
+.BR dovecot\-lda (1),
+.BR sieve\-dump (1),
+.BR sieve\-filter (1),
+.BR sievec (1),
+.BR pigeonhole (7)