dovecot-2.2-pigeonhole: Created specification for the vnd.doveco...
pigeonhole at rename-it.nl
pigeonhole at rename-it.nl
Fri Aug 10 00:01:49 EEST 2012
details: http://hg.rename-it.nl/dovecot-2.2-pigeonhole/rev/54a0d0552be7
changeset: 1650:54a0d0552be7
user: Stephan Bosch <stephan at rename-it.nl>
date: Thu Aug 09 22:58:53 2012 +0200
description:
Created specification for the vnd.dovecot.debug extension.
Also fixed a small mistake in the spefication for the vnd.dovecot.duplicate extension.
diffstat:
doc/rfc/spec-bosch-sieve-debug.txt | 224 +++++++++++++++++++++++++++++
doc/rfc/xml/reference.VARIABLES.xml | 15 +
doc/rfc/xml/spec-bosch-sieve-debug.xml | 168 +++++++++++++++++++++
doc/rfc/xml/spec-bosch-sieve-duplicate.xml | 2 +-
4 files changed, 408 insertions(+), 1 deletions(-)
diffs (truncated from 431 to 300 lines):
diff -r 9d962388f5f6 -r 54a0d0552be7 doc/rfc/spec-bosch-sieve-debug.txt
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/rfc/spec-bosch-sieve-debug.txt Thu Aug 09 22:58:53 2012 +0200
@@ -0,0 +1,224 @@
+
+
+
+Pigeonhole Project S. Bosch
+ August 9, 2012
+
+
+ Sieve Email Filtering: Logging Debug Messages
+
+Abstract
+
+ This document defines a new vendor-defined test command "debug_log"
+ for the "Sieve" email filtering language. It provides the means to
+ debug a Sieve script by logging debug messages.
+
+
+Table of Contents
+
+ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2
+ 2. Conventions Used in This Document . . . . . . . . . . . . . . . 2
+ 3. Command "debug_log" . . . . . . . . . . . . . . . . . . . . . . 2
+ 4. Sieve Capability Strings . . . . . . . . . . . . . . . . . . . 2
+ 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
+ 6. Security Considerations . . . . . . . . . . . . . . . . . . . . 3
+ 7. Normative References . . . . . . . . . . . . . . . . . . . . . 3
+ Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 4
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bosch [Page 1]
+
+ Sieve: Debug Logging August 2012
+
+
+1. Introduction
+
+ This is an extension to the Sieve filtering language defined by RFC
+ 5228 [SIEVE]. It adds a command that provides the means to debug a
+ Sieve script by logging debug messages.
+
+ Much like any other kind of computer program, Sieve scripts are prone
+ to all kinds of mistakes. Often, there are no real error conditions,
+ e.g. Sieve language violations, that cause the failure and no error
+ or warning messages are logged for the user or administrator to
+ determine what caused the erroneous result. A convenient method of
+ debugging such issues is printing debug messages to some kind of
+ logging facility. This way for example, script authors can check
+ whether specific sections of the script are executed. When combined
+ with the "variables" [VARIABLES] extension, intermittent results,
+ message data and status information can be included in those log
+ messages, further improving the information available for debugging.
+
+ This extension is specific to the Pigeonhole Sieve implementation for
+ the Dovecot Secure IMAP server. It will therefore most likely not be
+ supported by web interfaces and GUI-based Sieve editors.
+
+
+2. Conventions Used in This Document
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in [KEYWORDS].
+
+ Conventions for notations are as in [SIEVE] Section 1.1, including
+ use of the "Usage:" label for the definition of action and tagged
+ arguments syntax.
+
+
+3. Command "debug_log"
+
+ Usage: "debug_log" <message: string>
+
+ The "debug_log" command prints the debug message provided as the
+ command's "message" argument to an implementation-defined logging
+ facility. The message MAY contain variable substitutions as provided
+ by the "variables" [VARIABLES] extension to dynamically compose the
+ message from information available at runtime.
+
+
+4. Sieve Capability Strings
+
+ A Sieve implementation that defines the "debug_log" action command
+
+
+
+Bosch [Page 2]
+
+ Sieve: Debug Logging August 2012
+
+
+ will advertise the capability string "vnd.dovecot.debug".
+
+
+5. Examples
+
+ The following example logs a message when the message's subject
+ contains the "hello":
+
+ require "vnd.dovecot.debug";
+
+ if header :contains "subject" "hello" {
+ debug_log "Subject header contains hello!";
+ }
+
+ The next example logs the envelope of the message using the
+ "variables" [VARIABLES] extension and the "envelope" [SIEVE]
+ extension:
+
+ require ["variables", "envelope", "vnd.dovecot.debug"];
+
+ if envelope :matches "to" "*" { set "to" "${1}"; }
+ if envelope :matches "from" "*" { set "from" "${1}"; }
+
+ debug_log "Received message TO=${to} FROM=${from}";
+
+
+6. Security Considerations
+
+ If the "vnd.dovecot.debug" extension is used from scripts that are
+ managed by a user, the log messages SHOULD only be logged to a
+ personal log file specific to that user. Otherwise, users could
+ litter system log files with loads of log messages.
+
+
+7. Normative References
+
+ [KEYWORDS]
+ Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+ [SIEVE] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
+ Language", RFC 5228, January 2008.
+
+ [VARIABLES]
+ Homme, K., "Sieve Email Filtering: Variables Extension",
+ RFC 5229, January 2008.
+
+
+
+
+
+Bosch [Page 3]
+
+ Sieve: Debug Logging August 2012
+
+
+Author's Address
+
+ Stephan Bosch
+ Enschede
+ NL
+
+ Email: stephan at rename-it.nl
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Bosch [Page 4]
+
diff -r 9d962388f5f6 -r 54a0d0552be7 doc/rfc/xml/reference.VARIABLES.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/rfc/xml/reference.VARIABLES.xml Thu Aug 09 22:58:53 2012 +0200
@@ -0,0 +1,15 @@
+<?xml version='1.0' encoding='UTF-8'?>
+
+<reference anchor='VARIABLES'>
+
+<front>
+<title>Sieve Email Filtering: Variables Extension</title>
+<author initials='K.' surname='Homme' fullname='K. Homme'>
+<organization /></author>
+<date year='2008' month='January' />
+<abstract>
+<t>In advanced mail filtering rule sets, it is useful to keep state or configuration details across rules. This document updates the Sieve filtering language (RFC 5228) with an extension to support variables. The extension changes the interpretation of strings, adds an action to store data in variables, and supplies a new test so that the value of a string can be examined. [STANDARDS-TRACK]</t></abstract></front>
+
+<seriesInfo name='RFC' value='5229' />
+<format type='TXT' octets='20023' target='http://www.rfc-editor.org/rfc/rfc5229.txt' />
+</reference>
diff -r 9d962388f5f6 -r 54a0d0552be7 doc/rfc/xml/spec-bosch-sieve-debug.xml
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/rfc/xml/spec-bosch-sieve-debug.xml Thu Aug 09 22:58:53 2012 +0200
@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="US-ASCII"?>
+
+<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
+
+<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
+<!-- used by XSLT processors -->
+<?rfc strict="yes" ?>
+<?rfc toc="yes"?>
+<?rfc tocdepth="4"?>
+<?rfc symrefs="yes"?>
+<?rfc sortrefs="yes" ?>
+<?rfc compact="yes" ?>
+<?rfc subcompact="no" ?>
+<?rfc private="Pigeonhole Project" ?>
+
+<rfc category="info" docName="spec-bosch-sieve-debug">
+<!-- ***** FRONT MATTER ***** -->
+
+<front>
+<title abbrev="Sieve: Debug Logging">
+Sieve Email Filtering: Logging Debug Messages
+</title>
+
+<author fullname="Stephan Bosch" initials="S." surname="Bosch">
+ <organization/>
+ <address>
+ <postal>
+ <street></street>
+ <city>Enschede</city>
+ <country>NL</country>
+ </postal>
+ <email>stephan at rename-it.nl</email>
+ </address>
+</author>
+
+<date/>
+
+<area>General</area>
+<workgroup>Pigeonhole Project</workgroup>
+<keyword>sieve</keyword>
+<keyword>debug</keyword>
+<keyword>logging</keyword>
+
+<abstract>
+<t>
+This document defines a new vendor-defined test command "debug_log" for the
+"Sieve" email filtering language. It provides the means to debug a Sieve script
+by logging debug messages.
+</t>
More information about the dovecot-cvs
mailing list