draft-ietf-sieve-include-04.txt   draft-ietf-sieve-include-05.txt 
Network Working Group C. Daboo Network Working Group C. Daboo
Internet-Draft A. Stone Internet-Draft A. Stone
Expires: December 28, 2010 June 28, 2010 Intended status: Standards Track July 12, 2010
Expires: January 13, 2011
Sieve Email Filtering: Include Extension Sieve Email Filtering: Include Extension
draft-ietf-sieve-include-04 draft-ietf-sieve-include-05
Abstract
The Sieve Email Filtering "include" extension permits users to
include one Sieve script inside another. This can make managing
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
to include their own personal scripts or site-wide scripts.
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. This document may contain material provisions of BCP 78 and BCP 79.
from IETF Documents or IETF Contributions published or made publicly
available before November 10, 2008. The person(s) controlling the
copyright in some of this material may not have granted the IETF
Trust the right to allow modifications of such material outside the
IETF Standards Process. Without obtaining an adequate license from
the person(s) controlling the copyright in such materials, this
document may not be modified outside the IETF Standards Process, and
derivative works of it may not be created outside the IETF Standards
Process, except to format it for publication as an RFC or to
translate it into languages other than English.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF). Note that other groups may also distribute
other groups may also distribute working documents as Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts. 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."
The list of current Internet-Drafts can be accessed at This Internet-Draft will expire on January 13, 2011.
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on December 28, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the Copyright (c) 2010 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 Provisions This document is subject to BCP 78 and the IETF Trust's Legal
Relating to IETF Documents (http://trustee.ietf.org/license-info) Provisions Relating to IETF Documents
in effect on the date of publication of this document. Please (http://trustee.ietf.org/license-info) in effect on the date of
review these documents carefully, as they describe your rights and publication of this document. Please review these documents
restrictions with respect to this document. Code Components carefully, as they describe your rights and restrictions with respect
extracted from this document must include Simplified BSD License to this document. Code Components extracted from this document must
text as described in Section 4.e of the Trust Legal Provisions and include Simplified BSD License text as described in Section 4.e of
are provided without warranty as described in the Simplified BSD the Trust Legal Provisions and are provided without warranty as
License. described in the Simplified BSD License.
Abstract This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other
than English.
The Sieve Email Filtering "include" extension permits users to Table of Contents
include one Sieve script inside another. This can make managing
large scripts or multiple sets of scripts much easier, and allows a 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5
site and its users to build up libraries of scripts. Users are able 2. Conventions Used in This Document . . . . . . . . . . . . . . 5
to include their own personal scripts or site-wide scripts. 3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5
3.1. General Considerations . . . . . . . . . . . . . . . . . . 5
3.2. Control Structure include . . . . . . . . . . . . . . . . 6
3.3. Control Structure return . . . . . . . . . . . . . . . . . 10
3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10
3.4.1. Control Structure global . . . . . . . . . . . . . . . 10
3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12
4. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
5.1. "include" Extension Registration . . . . . . . . . . . . . 13
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Normative References . . . . . . . . . . . . . . . . . . . 13
6.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
Change History (to be removed prior to publication as an RFC) Change History (to be removed prior to publication as an RFC)
Changes from ietf-04 to ietf-05:
a. Integrate review from Barry Leiba.
Changes from ietf-03 to ietf-04: Changes from ietf-03 to ietf-04:
a. No changes. a. No changes.
Changes from ietf-02 to ietf-03: Changes from ietf-02 to ietf-03:
a. Setting a variable then calling global on it is an error a. Setting a variable then calling global on it is an error
(something like 'use strict'). (something like 'use strict').
b. Specify that the 'global' keyword is only available when b. Specify that the 'global' keyword is only available when
skipping to change at page 4, line 8 skipping to change at page 5, line 5
b. Re-ordered sections at start to conform to RFC style. b. Re-ordered sections at start to conform to RFC style.
c. Moved recursion comment into General Considerations section. c. Moved recursion comment into General Considerations section.
d. Switched to using optional parameter to indicate personal vs d. Switched to using optional parameter to indicate personal vs
global. global.
e. Explicitly state that an error occurs when a missing script is e. Explicitly state that an error occurs when a missing script is
included. included.
Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 5
2. Conventions Used in This Document . . . . . . . . . . . . . . 5
3. Include Extension . . . . . . . . . . . . . . . . . . . . . . 5
3.1. General Considerations . . . . . . . . . . . . . . . . . . 5
3.2. Control Structure include . . . . . . . . . . . . . . . . 6
3.3. Control Structure return . . . . . . . . . . . . . . . . . 10
3.4. Interaction with Variables . . . . . . . . . . . . . . . . 10
3.4.1. Control Structure global . . . . . . . . . . . . . . . 10
3.4.2. Variables Namespace global . . . . . . . . . . . . . . 12
4. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
5.1. "include" Extension Registration . . . . . . . . . . . . . 13
6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6.1. Normative References . . . . . . . . . . . . . . . . . . . 13
6.2. Informative References . . . . . . . . . . . . . . . . . . 13
Appendix A. Acknowledgments . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 13
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
vacation command as needed. Another is to have a vacation script vacation command as needed. Another is to have a vacation script
skipping to change at page 6, line 7 skipping to change at page 6, line 7
3. Include Extension 3. Include Extension
3.1. General Considerations 3.1. General Considerations
Sieve implementations that implement the "include", "return", and Sieve implementations that implement the "include", "return", and
"global" commands described below have an identifier of "include" for "global" commands described below have an identifier of "include" for
use with the capability mechanism. If any of the "include", use with the capability mechanism. If any of the "include",
"return", or "global" commands are used in a script, the "include" "return", or "global" commands are used in a script, the "include"
capability MUST be listed in the "require" statement in that script. capability MUST be listed in the "require" statement in that script.
Sieve implementations must track the use of actions in included Sieve implementations need to track the use of actions in included
scripts so that implicit "keep" behavior can be properly determined scripts so that implicit "keep" behavior can be properly determined
based on whether any actions have executed in any script. based on whether any actions have executed in any script.
Sieve implementations are allowed to limit the total number of nested Sieve implementations are allowed to limit the total number of nested
included scripts, but MUST provide for a total of at least three included scripts, but MUST provide for a total of at least three
levels of nested scripts including the top-level script. An error levels of nested scripts including the top-level script. An error
MUST be generated either when the script is uploaded to the Sieve MUST be generated either when the script is uploaded to the Sieve
repository, or when the script is executed, if any nesting limit is repository, or when the script is executed, if any nesting limit is
exceeded. If such an error is detected whilst processing a Sieve exceeded. If such an error is detected whilst processing a Sieve
script, an implicit "keep" action MUST be executed to prevent loss of script, an implicit "keep" action MUST be executed to prevent loss of
skipping to change at page 8, line 23 skipping to change at page 8, line 23
require ["include"]; require ["include"];
include :personal "always_allow"; include :personal "always_allow";
include :global "spam_tests"; include :global "spam_tests";
include :personal "spam_tests"; include :personal "spam_tests";
include :personal "mailing_lists"; include :personal "mailing_lists";
Personal script "always_allow" Personal script "always_allow"
This script special cases some correspondent email addresses and This script special-cases some correspondent email addresses and
makes sure any message containing those addresses are always kept. makes sure any message containing those addresses are always kept.
if header :is "From" "boss@example.com" if header :is "From" "boss@example.com"
{ {
keep; keep;
} }
elsif header :is "From" "ceo@example.com" elsif header :is "From" "ceo@example.com"
{ {
keep; keep;
} }
skipping to change at page 9, line 14 skipping to change at page 9, line 14
} }
Personal script "mailing_lists" Personal script "mailing_lists"
This script looks for messages from different mailing lists and This script looks for messages from different mailing lists and
files each into a mailbox specific to the mailing list. files each into a mailbox specific to the mailing list.
require ["fileinto"]; require ["fileinto"];
if header :is "Sender" "owner-ietf-mta-filters@imc.org" if header :is "List-ID" "owner-ietf-mta-filters@imc.org"
{ {
fileinto "lists.sieve"; fileinto "lists.sieve";
} }
elsif header :is "Sender" "owner-ietf-imapext@imc.org" elsif header :is "List-ID" "owner-ietf-imapext@imc.org"
{ {
fileinto "lists.imapext"; fileinto "lists.imapext";
} }
There is one script stored in the global repository: There is one script stored in the global repository:
Site script "spam_tests" Site script "spam_tests"
This script does some site-wide spam tests which any user at the This script does some site-wide spam tests which any user at the
site can include in their own scripts at a suitable point. The site can include in their own scripts at a suitable point. The
skipping to change at page 10, line 11 skipping to change at page 10, line 11
{ {
include "my_reject_script"; include "my_reject_script";
} }
3.3. Control Structure return 3.3. Control Structure return
Usage: return Usage: return
The "return" command stops processing of the immediately included The "return" command stops processing of the immediately included
script only and returns processing control to the script which script only and returns processing control to the script which
includes it. If used in the main script (i.e. not in an included includes it. If used in the main script (i.e., not in an included
script), it has the same effect as the "stop" command, including the script), it has the same effect as the "stop" command, including the
appropriate "keep" action if no other actions have been executed up appropriate "keep" action if no other actions have been executed up
to that point. to that point.
3.4. Interaction with Variables 3.4. Interaction with Variables
In order to avoid problems of variables in an included script In order to avoid problems of variables in an included script
"overwriting" those from the script that includes it, this "overwriting" those from the script that includes it, this
specification requires that all variables defined in a script MUST be specification requires that all variables defined in a script MUST be
kept "private" to the immediate script by default - i.e. they are not kept "private" to the immediate script by default - that is, they are
"visible" to other scripts. This ensures that two script authors not "visible" to other scripts. This ensures that two script authors
cannot inadvertently cause problems by choosing the same name for a cannot inadvertently cause problems by choosing the same name for a
variable. variable.
However, sometimes there is a need to make a variable defined in one However, sometimes there is a need to make a variable defined in one
script available to others. This specification defines the new script available to others. This specification defines the new
command "global" to declare that a variable is shared among scripts. command "global" to declare that a variable is shared among scripts.
Effectively, two namespaces are defined: one local to the immediate Effectively, two namespaces are defined: one local to the immediate
script, and another shared among all scripts. Implementations MUST script, and another shared among all scripts. Implementations MUST
allow a non-global variable to have the same name as a global allow a non-global variable to have the same name as a global
variable but have no interaction between them. variable but have no interaction between them.
skipping to change at page 11, line 7 skipping to change at page 11, line 7
If a "global" command is given the name of a variable that has If a "global" command is given the name of a variable that has
previously been defined in the immediate script with "set", an error previously been defined in the immediate script with "set", an error
MUST be generated either when the script is uploaded or at execution MUST be generated either when the script is uploaded or at execution
time. time.
If a "global" command lists a variable that has not been defined in If a "global" command lists a variable that has not been defined in
the global namespace, the name of the variable is now marked as the global namespace, the name of the variable is now marked as
global, and any subsequent "set" command will set the value of the global, and any subsequent "set" command will set the value of the
variable in global scope. variable in global scope.
A variable has global scope in all scripts that have declared it with
the "global" command. If a script uses that variable name without
declaring it global, the name specifies a separate, non-global
variable within that script.
Interpretation of a string containing a variable marked as global, Interpretation of a string containing a variable marked as global,
but without any value set, SHALL behave as any other access to an but without any value set, SHALL behave as any other access to an
unknown variable, as specified in VARIABLES [RFC5229], Section 3 unknown variable, as specified in VARIABLES [RFC5229], Section 3
(i.e., evaluates to an empty string). (i.e., evaluates to an empty string).
Example: Example:
require ["variables", "include"]; require ["variables", "include"];
global "test"; global "test";
global "test-mailbox"; global "test-mailbox";
skipping to change at page 13, line 35 skipping to change at page 13, line 35
[RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering [RFC5228] Guenther, P. and T. Showalter, "Sieve: An Email Filtering
Language", RFC 5228, January 2008. Language", RFC 5228, January 2008.
[RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension", [RFC5229] Homme, K., "Sieve Email Filtering: Variables Extension",
RFC 5229, January 2008. RFC 5229, January 2008.
6.2. Informative References 6.2. Informative References
[I-D.ietf-sieve-managesieve] [I-D.ietf-sieve-managesieve]
Martin, T. and A. Melnikov, "A Protocol for Remotely Melnikov, A. and T. Martin, "A Protocol for Remotely
Managing Sieve Scripts", draft-ietf-sieve-managesieve-09 Managing Sieve Scripts", draft-ietf-sieve-managesieve-09
(work in progress), January 2009. (work in progress), January 2009.
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.
Authors' Addresses Authors' Addresses
 End of changes. 18 change blocks. 
67 lines changed or deleted 73 lines changed or added

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