draft-ietf-sieve-include-09.txt   draft-ietf-sieve-include-10.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Intended status: Standards Track July 8, 2011 Intended status: Standards Track July 10, 2011
Expires: January 9, 2012 Expires: January 11, 2012
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-09 draft-ietf-sieve-include-10
Abstract Abstract
The Sieve Email Filtering "include" extension permits users to The Sieve Email Filtering "include" extension permits users to
include one Sieve script inside another. This can make managing include one Sieve script inside another. This can make managing
large scripts or multiple sets of scripts much easier, and allows a large scripts or multiple sets of scripts much easier, and allows a
site and its users to build up libraries of scripts. Users are able site and its users to build up libraries of scripts. Users are able
to include their own personal scripts or site-wide scripts. to include their own personal scripts or site-wide scripts.
Status of this Memo Status of this Memo
skipping to change at page 1, line 34 skipping to change at page 1, line 34
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2012. This Internet-Draft will expire on January 11, 2012.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 11 skipping to change at page 2, line 11
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
2. Conventions Used in This Document . . . . . . . . . . . . . . 3 2. Conventions Used in This Document . . . . . . . . . . . . . . 3
3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 3
3.1. General Considerations . . . . . . . . . . . . . . . . . . 3 3.1. General Considerations . . . . . . . . . . . . . . . . . . 3
3.2. Control Structure include . . . . . . . . . . . . . . . . 5 3.2. Control Structure include . . . . . . . . . . . . . . . . 4
3.3. Control Structure return . . . . . . . . . . . . . . . . . 8 3.3. Control Structure return . . . . . . . . . . . . . . . . . 8
3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8 3.4. Interaction with Variables . . . . . . . . . . . . . . . . 8
3.4.1. Control Structure global . . . . . . . . . . . . . . . 8 3.4.1. Control Structure global . . . . . . . . . . . . . . . 8
3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10 3.4.2. Variables Namespace global . . . . . . . . . . . . . . 10
4. Security Considerations . . . . . . . . . . . . . . . . . . . 11 4. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
5.1. "include" Extension Registration . . . . . . . . . . . . . 11 5.1. "include" Extension Registration . . . . . . . . . . . . . 11
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 11
6.1. Normative References . . . . . . . . . . . . . . . . . . . 11 6.1. Normative References . . . . . . . . . . . . . . . . . . . 11
6.2. Informative References . . . . . . . . . . . . . . . . . . 12 6.2. Informative References . . . . . . . . . . . . . . . . . . 12
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12 Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 12
Appendix B. Change History (to be removed prior to Appendix B. Change History (to be removed prior to
publication as an RFC) . . . . . . . . . . . . . . . 12 publication as an RFC) . . . . . . . . . . . . . . . 12
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 15
1. Introduction and Overview 1. Introduction and Overview
It's convenient to be able to break SIEVE [RFC5228] scripts down into It's convenient to be able to break SIEVE [RFC5228] scripts down into
smaller components which can be reused in a variety of different smaller components which can be reused in a variety of different
circumstances. For example, users may want to have a default script circumstances. For example, users may want to have a default script
and a special 'vacation' script, the latter being activated when the and a special 'vacation' script, the latter being activated when the
user goes on vacation. In that case the default actions should user goes on vacation. In that case the default actions should
continue to be run, but a vacation command should be executed first. continue to be run, but a vacation command should be executed first.
One option is to edit the default script to add or remove the One option is to edit the default script to add or remove the
skipping to change at page 5, line 7 skipping to change at page 4, line 49
include each other. For example, if a script defines the variable include each other. For example, if a script defines the variable
"${status}" with one particular meaning or usage, and another defines "${status}" with one particular meaning or usage, and another defines
"${status}" with a different meaning, then if one script includes the "${status}" with a different meaning, then if one script includes the
other there is an issue as to which "${status}" is being referenced. other there is an issue as to which "${status}" is being referenced.
To solve this problem, Sieve implementations MUST follow the scoping To solve this problem, Sieve implementations MUST follow the scoping
rules defined in Section 3.4 and support the "global" command defined rules defined in Section 3.4 and support the "global" command defined
there. there.
3.2. Control Structure include 3.2. Control Structure include
Usage: include [LOCATION] [ONCE] <value: string> Usage: include *[PARAMETERS] <value: string>
PARAMETERS = LOCATION / :once / :optional
LOCATION = ":personal" / ":global" LOCATION = :personal / :global
ONCE = ":once"
The "include" command takes an optional "location" parameter, an The "include" command takes an optional "location" parameter, an
optional ":once" parameter, and a single string argument representing optional ":once" parameter, an optional ":optional" parameter, and a
the name of the script to include for processing at that point. It single string argument representing the name of the script to include
is RECOMMENDED that implementations restrict script names according for processing at that point. It is RECOMMENDED that implementations
to MANAGESIEVE [RFC5804] Section 1.7. Implementations MUST NOT allow restrict script names according to MANAGESIEVE [RFC5804] Section 1.7.
variables to be expanded into the names of Sieve scripts; in other Implementations MUST NOT allow variables to be expanded into the
words, the value MUST be a constant string as defined in VARIABLES names of Sieve scripts; in other words, the value MUST be a constant
[RFC5229], Section 3. string as defined in VARIABLES [RFC5229], Section 3.
The "location" parameter MUST default to ":personal" if not The "location" parameter MUST default to ":personal" if not
specified. The "location" has the following meanings: specified. The "location" parameter MUST NOT be specified more than
once. The "location" has the following meanings:
:personal :personal
Indicates that the named script is stored in the user's own Indicates that the named script is stored in the user's own
personal (private) Sieve repository. personal (private) Sieve repository.
:global :global
Indicates that the named script is stored in a site-wide Sieve Indicates that the named script is stored in a site-wide Sieve
repository, accessible to all users of the Sieve system. repository, accessible to all users of the Sieve system.
The ":once" parameter tells the interpreter only to include the named The ":once" parameter tells the interpreter only to include the named
script if it has not already been included at any other point during script if it has not already been included at any other point during
script execution. If the script has already been included, script execution. If the script has already been included,
processing continues immediately following the include command. processing continues immediately following the include command.
Implementations MUST NOT generate an error if an "include :once" Implementations MUST NOT generate an error if an "include :once"
command names a script whose inclusion would be recursive; in this command names a script whose inclusion would be recursive; in this
case, the script MUST be considered previously included and therefore case, the script MUST be considered previously included and therefore
"include :once" will not include it again. "include :once" will not include it again.
The ":optional" parameter indicates that the script may be missing.
Ordinarily, an implementation MUST generate an error at runtime if an
include command specifies a script that does not exist. When
":optional" is specified, implementations MUST NOT generate an error
for a missing script, and MUST continue as if the include command had
not been present.
Note: It is RECOMMENDED that script authors / generators use this Note: It is RECOMMENDED that script authors / generators use this
parameter only when including a script that performs general duties parameter only when including a script that performs general duties
such as declaring global variables and making sanity checks of the such as declaring global variables and making sanity checks of the
environment. environment.
The included script MUST be a valid Sieve script. Each script MUST The included script MUST be a valid Sieve script. Each script MUST
have its own "require" statements for all optional capabilities used have its own "require" statements for all optional capabilities used
by that script. The scope of a "require" statement is the script in by that script. The scope of a "require" statement is the script in
which it immediately appears, and neither inherits nor passes on which it immediately appears, and neither inherits nor passes on
capabilities to other scripts during the course of execution. capabilities to other scripts during the course of execution.
skipping to change at page 10, line 40 skipping to change at page 10, line 40
set "global.i_am_on_vacation" "1"; set "global.i_am_on_vacation" "1";
Variables declared global and variables accessed via the global Variables declared global and variables accessed via the global
namespace MUST be one and the same. In the following example script, namespace MUST be one and the same. In the following example script,
we see the variable "i_am_on_vacation" used in a "global" command, we see the variable "i_am_on_vacation" used in a "global" command,
and again with the "global." namespace. Consider these as two and again with the "global." namespace. Consider these as two
syntaxes with identical meaning. syntaxes with identical meaning.
Example: Example:
require ["variables", "include"]; require ["variables", "include", "vacation"];
global "i_am_on_vacation"; global "i_am_on_vacation";
set "global.i_am_on_vacation" "1"; set "global.i_am_on_vacation" "1";
if string :is "${i_am_on_vacation}" "1" if string :is "${i_am_on_vacation}" "1"
{ {
vacation "It's true, I am on vacation."; vacation "It's true, I am on vacation.";
} }
4. Security Considerations 4. Security Considerations
skipping to change at page 12, line 26 skipping to change at page 12, line 26
Appendix A. Acknowledgments Appendix A. Acknowledgments
Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz, Thanks to Ken Murchison, Rob Siemborski, Alexey Melnikov, Marc Mutz,
Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba, Kjetil Torgrim Homme, Stephan Bosch, Arnt Gulbrandsen, Barry Leiba,
and Jeffrey Hutzelman for comments and corrections. and Jeffrey Hutzelman for comments and corrections.
Appendix B. Change History (to be removed prior to publication as an Appendix B. Change History (to be removed prior to publication as an
RFC) RFC)
Changes from ietf-09 to ietf-10:
a. Another example script error caught by Stephan Bosch.
b. Add :optional argument to allow a missing script to be ignored.
Changes from ietf-08 to ietf-09: Changes from ietf-08 to ietf-09:
a. Better variables language from Stephan Bosch. a. Better variables language from Stephan Bosch.
Changes from ietf-07 to ietf-08: Changes from ietf-07 to ietf-08:
a. Nits from Stephan Bosch. a. Nits from Stephan Bosch.
b. Nits from Barry Leiba. b. Nits from Barry Leiba.
 End of changes. 11 change blocks. 
20 lines changed or deleted 32 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/