<?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@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>
</abstract>
</front>

<middle>

<section title="Introduction">
<t>This is an extension to the Sieve filtering language defined by
<xref target="SIEVE">RFC 5228</xref>. It adds a command that provides the means
to debug a Sieve script by logging debug messages.
</t>

<t>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" <xref target="VARIABLES"/> extension, intermittent results, message
data and status information can be included in those log messages, further
improving the information available for debugging.</t>

<t>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.
</t>
</section>

<section title="Conventions Used in This Document">
<t>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 <xref target="KEYWORDS"/>.</t>
<t>Conventions for notations are as in <xref target="SIEVE"/> Section 1.1,
including use of the "Usage:" label for the definition of action and tagged
arguments syntax.</t>
</section>

<section title="Command &quot;debug_log&quot;">
<?rfc needLines="3" ?>
<figure>
<artwork><![CDATA[
Usage: "debug_log" <message: string>
]]></artwork>
</figure>

<t>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"
<xref target="VARIABLES"/> extension to dynamically compose the message from
information available at runtime.
</t>
</section>

<section title="Sieve Capability Strings">
<t>A Sieve implementation that defines the "debug_log" action command 
will advertise the capability string "vnd.dovecot.debug".
</t>
</section>

<section title="Examples">
<t>The following example logs a message when the message's subject contains the
"hello":
</t>

<?rfc needLines="5" ?>
<figure>
<artwork><![CDATA[
require "vnd.dovecot.debug";

if header :contains "subject" "hello" {
  debug_log "Subject header contains hello!";
}
]]></artwork>
</figure>

<t>The next example logs the envelope of the message using the "variables"
<xref target="VARIABLES"/> extension and the "envelope" <xref target="SIEVE"/>
extension:
</t>

<?rfc needLines="6" ?>
<figure>
<artwork><![CDATA[
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}";
]]></artwork>
</figure>

</section>

<section anchor="Security" title="Security Considerations">
<t>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.</t>
</section>
</middle>

<!--  *****BACK MATTER ***** -->

<back>
<!-- References split into informative and normative -->

<references title="Normative References">
  <?rfc include="reference.KEYWORDS.xml"?>
  <?rfc include="reference.SIEVE.xml"?>
  <?rfc include="reference.VARIABLES.xml"?>
</references>

<!--<references title="Informative References">
  
</references> -->
</back>

</rfc>
