KEP-0014.txt
Georg Greve
greve at kolabsys.com
Thu Sep 15 13:32:00 CEST 2011
KEP-0014.txt | 81 ++++++++++++++++++++++++++++++++++++-----------------------
1 file changed, 50 insertions(+), 31 deletions(-)
New commits:
commit 874f2b4beccd6bdb8f1a5fc598c150042af921c3
Author: Georg Greve <greve at kolabsys.com>
Date: Thu Sep 15 13:31:23 2011 +0200
Included feedback from discussions w/Jeroen and a few background points for implementors.
diff --git a/KEP-0014.txt b/KEP-0014.txt
index a4fc59f..a2c876d 100644
--- a/KEP-0014.txt
+++ b/KEP-0014.txt
@@ -32,7 +32,7 @@ It '''SHALL''' be automatically deployed and activated for all users in that sys
To be compliant with this KEP, Sieve editors '''MUST''' check for the presence of the [[#MASTER|MASTER]] file, and, if present, '''MUST''' do the following:
* hide [[#MASTER|MASTER]] and all other [[#Protected Names|Protected Names]] from user selection;
* protect all [[#Protected Names|Protected Names]] by preventing users from choosing them for their own scripts;
-* define a consistent name and version to be used in the provisions outlined in [[#USER|USER]] and [[#User_specific_scripts|User specific scripts]];
+* define a consistent name and version to be used in the provisions outlined in [[#User_specific_scripts|User specific scripts]];
* upon startup read [[#USER|USER]] to get the number and order of active scripts;
* regularly check for changes by other editors to [[#USER|USER]] or any of the active scripts;
* edit scripts in line with the [[#User_specific_scripts|User specific scripts]] provisions;
@@ -40,11 +40,13 @@ To be compliant with this KEP, Sieve editors '''MUST''' check for the presence o
* ensure that after finishing its modification(s), [[#MASTER|MASTER]] is the active script.
At the choice of its author, a Sieve editor '''MAY''' visualize scripts that are executed before or after the scripts edited by the user. How this is implemented is largely up to the individual editors, but it should ensure that
-* it is made clear to the user these rules cannot be edited within this editor, e.g. through graying out;
+* it is made clear to the user where appropriate that these rules cannot be edited within this editor, e.g. through graying out;
* the user is given some indication as to where these rules can be edited, e.g. in the management console.
If there is no [[#MASTER|MASTER]] file in the users list of Sieve scripts, editors '''MAY''' behave as they see fit, but '''MUST''' always ensure its users do not use [[#Protected Names|Protected Names]] and '''MUST''' always ensure that users do not create a [[#MASTER|MASTER]] which would trigger the functionality according to this KEP.
+{{warning|Nesting depth|The nesting depth for inclusion will typically be limited by the server, with a minimum of three levels, as specified by the 'Sieve Email Filtering: Include Extension' draft<ref name="include" />. The mechanisms in this KEP use two of these levels for management purposes, so it is recommended that editors do not provide for include functionality in their user scripts unless they know the server to support deeper nesting. The maximum level of supported nesting is the ''maximum depth supported by the server minus two''.}}
+
=== Management system requirements ===
To be compliant with this KEP, management systems that make use of Sieve for some of their functionality '''MUST''' check for the presence of the [[#MASTER|MASTER]] file, and, if present, '''MUST''' do the following:
* limit themselves to the [[#MANAGEMENT|MANAGEMENT]] script;
@@ -64,6 +66,8 @@ This can be in the form of adding this to the default behaviour for all users, b
Sieve editors '''MUST''' be able to rely on the proper creation of the [[#MASTER|MASTER]] script before they are called for the first time. It is the responsibility of the platform integrator or deployment engineer to ensure this is done properly.
+{{note|Limited number of sieve scripts|IMAP servers typically limit the number of sieve scripts a user can store. A common value for this number would be five. This KEP uses three scripts in the users name space for special purposes, so a normal IMAP server might only allow two more scripts defined by the user themselves. It is therefore suggested to raise the number of scripts by three to keep the number of total user defined scripts constant, or whatever seems sensible for this particular platform or installation.}}
+
=== MASTER ===
This is an example of the MASTER script, which can act as a template and '''SHALL''' be modified during integration and deployment as required for the particular installation.
@@ -84,7 +88,7 @@ This is an example of the MASTER script, which can act as a template and '''SHAL
# OPTIONAL: Includes for all or a group of users
# include :global "all-users";
# include :global "this-group-of-users";
-
+
# The script maintained by the general management system
include :personal "MANAGEMENT";
@@ -96,7 +100,7 @@ MASTER, [[#MANAGEMENT|MANAGEMENT]] and [[#USER|USER]] '''SHALL''' be receiving t
MANAGEMENT is the script written by the management system of the platform, USER is the script intended for controling the execution of individual scripts by a user. General sieve editors available to users and platform management systems '''MUST NOT''' alter this script.
=== MANAGEMENT ===
-Management systems '''SHALL''' define the variables 'global.management_system' and 'global.management_system_version' to correspond to their name/platform and version somewhere in the MANAGEMENT script by using the Variables Extension according to {{rfc|5229}}<ref name="variables">{{rfc|5229|title=Sieve Email Filtering: Variables Extension}}</ref>.
+Management systems '''SHALL''' define the variables 'management_system' and 'management_system_version' to correspond to their name/platform and version somewhere in the MANAGEMENT script by using the Variables Extension according to {{rfc|5229}}<ref name="variables">{{rfc|5229|title=Sieve Email Filtering: Variables Extension}}</ref>.
Otherwise management systems are free to write to each user's MANAGEMENT script as required and appropriate.
@@ -105,71 +109,86 @@ General sieve editors available to users '''MUST NOT''' alter this script.
=== USER ===
Editors '''SHALL''' be reading in the USER script, parsing it for individual includes of user-defined scripts, which take the form of
- ## <EDITOR NAME>
- ## <EDITOR VERSION>
include :personal "<filename>"
-where <EDITOR NAME> is the name of the editor that wrote this include, <EDITOR VERSION> is its version, and <filename> is the file name of the script written by this editor of this version for the current user.
+where <filename> is the file name of a local script of the current user.
Parsing '''SHALL''' preserve all comments that do not conform to the above format and discard the rest of the file.
-When replacing the USER script on the server, editor '''SHALL''' first write out all preserved comments, followed by an empty line, and then the client side includes, each followed by an empty line. The order of entries '''SHALL''' always be preserved unless explicitly changed by the user.
+When replacing the USER script on the server, editor '''SHALL''' first write out all preserved comments, followed by an empty line, then the include requirement, followed by an empty line, and then iterate over all client side includes, each followed by an empty line.
+
+The order of entries '''SHALL''' always be preserved unless explicitly changed by the user.
==== Sample USER Script ====
- # USER Master Script
+ # USER Management Script
#
# This script includes the various active sieve scripts
# it is AUTOMATICALLY GENERATED. DO NOT EDIT MANUALLY!
#
# For more information, see http://wiki.kolab.org/KEP:14#USER
#
+
+ require ["include"];
- ## Roundcube Sieve Plugin
- ## 0.6
include :personal "superspamrules"
- ## Roundcube Sieve Plugin
- ## 0.6
include :personal "mailinglists"
- ## Horde Ingo
- ## 2.0.5
include :personal "personalmail"
- ## Roundcube Sieve Plugin
- ## 0.6
include :personal "workmail"
=== User specific scripts ===
-User specific scripts contain the actual Sieve commands as defined by the user through the editors. When reading in such a script, editors '''SHALL''' parse it for the existance of {{rfc|5229}}<ref name="variables" /> variables for 'global.editor' and 'global.editor_version'.
-
-If at least one of these variables is not set, editor '''SHALL''' assume that the file is not under control of any particular editor and '''SHOULD''' import it as best it can and claim authority over it by setting the variables to its own name and version when replacing the script on the server. Alternatively, the editor '''MAY''' consider the script immutable '''--- AND/OR ---''' suggest it for deletion by the user.
-
-If the variables are set propery, editor '''MUST''' consider the format of that editor authoritative and keep the file compliant to the format of the specified editor, although editor '''MAY''' update the format of the file to a newer version of that same editor when replacing the script on the server. Editor '''MAY''' only edit the script if it can fully parse and edit the file accordingly, otherwise editor '''MUST''' consider the script read-only.
-
-Manually edited scripts '''MUST''' be designated with the value 'MANUAL' for editor and 'NONE' for its version and '''MUST''' always be considered read-only by all editors.
+User specific scripts contain the actual Sieve commands as defined by the user through the editors.
+
+When creating a new script, editor '''SHALL''' define the variables 'editor' and 'editor_version' to correspond to their name and version somewhere in the user specific script by using the Variables Extension according to {{rfc|5229}}<ref name="variables" />.
+
+When parsing an existing script, editor '''SHALL''' parse for the variables 'editor' and 'editor_version' and based on their values behave as follows:
+* '''Same editor, same version'''
+: If the variables are set and match their name and version, editor '''SHALL''' parse the script as usual and present it to the user for display/editing as required.
+* '''Same editor, different version'''
+:If the variables are set and match the name of the editor, but with different version, editor '''SHALL''' attempt to parse the script and upon success present it to the user for display/editing as required, saving it out with its own version. If editor cannot parse the script, it '''SHALL''' inform user about the version incompatibility and '''MAY''' choose to display the script in raw text form, as best it can, or not at all and '''SHALL''' always consider it '''read only'''.
+* '''Different, supported editor'''
+:If the variables are set and match a different editor and version which is supported by the editor reading the script, editor '''MAY''' parse the script normally and present it to the user for display/editing. When changing the file on the server, editor '''SHALL''' preserve the format of the editor and version which originally wrote the file and '''MUST''' preserve the variables accordingly.
+* '''Different editor'''
+:If the variables are set and match a different editor, editor '''MAY''' attempt to parse the script. Upon success, editor '''SHALL''' default to presenting the user with the script for display in '''read-only''' mode. Editor '''MAY''' allow the user to edit the script if the user requests that the editor take ownership of this script. Upon replacing the script on the server the editor '''SHALL''' then write out the script in its own format and with the editor and version variables set to its own name and version.
+:If editor has not attempted to parse the script, or could not successfuly parse, it '''SHALL''' treat the script as read-only and '''MAY''' present it to the user as best it can, in raw format, or not at all.
+* '''Variables not set'''
+:If the variables are '''not''' set, editor '''SHALL''' assume a manually written script. It '''MAY''' attempt to parse the script and proceed as outlined in the 'Different editor' provisions, above.
+* '''Variables set to READONLY, NONE'''
+:If the editor variable is set to 'READONLY' and the version is set to 'NONE', editor '''SHALL''' treat the script as '''explicitly read only'''. It '''MAY''' attempt to parse and display, but it '''MUST''' never modify this script.
==== Sample user specific script ====
A manual script example:
# Spam Rules, manually defined
- require ["variables", "fileinto", "comparator-i;ascii-numeric", "imapflags", "regex"];
- global "editor";
- global "editor_version";
- set "global.editor" "MANUAL";
- set "global.editor_version" "NONE";
+ require ["fileinto", "comparator-i;ascii-numeric", "imapflags", "regex"];
if anyof ( not exists ["From","Date"],
- header :comparator "i;ascii-casemap" :contains "X-Spam-Level" "*****",
- header :is ["X-Spam-Flag", "X-Spam-Status"] ["YES","Yes","yes"] ) {
+ header :comparator "i;ascii-casemap" :contains "X-Spam-Level" "*****",
+ header :is ["X-Spam-Flag", "X-Spam-Status"] ["YES","Yes","yes"] ) {
setflag "\\Seen";
fileinto "INBOX/Spam";
stop;
}
+
+The same script as an explicit '''read only, do not touch''' script:
+
+ # Spam Rules, manually defined
+ require ["variables", "fileinto", "comparator-i;ascii-numeric", "imapflags", "regex"];
+ set "editor" "READONLY";
+ set "editor_version" "NONE";
+ if anyof ( not exists ["From","Date"],
+ header :comparator "i;ascii-casemap" :contains "X-Spam-Level" "*****",
+ header :is ["X-Spam-Flag", "X-Spam-Status"] ["YES","Yes","yes"] ) {
+ setflag "\\Seen";
+ fileinto "INBOX/Spam";
+ stop;
+ }
=== Protected Names ===
More information about the commits
mailing list