Network Working Group Ryan Troll Document: draft-ietf-acap-motd-dataset-00.txt Carnegie Mellon Expires September 3, 1999 February 26, 1999 ACAP Message of the Day Dataset Class <draft-ietf-acap-motd-dataset-00.txt> Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." To view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Distribution of this memo is unlimited. Abstract The Application Configuration Access Protocol [ACAP] is designed to support remote storage and access of common application option, configuration and preference information. Once such piece of information is the "Message of the Day" greeting, used by system administrators to communicate important information to all users when they begin to use a system. This document describes a common format for storing MOTD information in ACAP, how site administrators may configure their ACAP MOTD service to allow multiple groups within the site to provide custom MOTD information, and how a client should access and use this information. Expires September 3, 1999 Troll [Page 1]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 Table of Contents Status of this Memo ............................................... 1 Abstract .......................................................... 1 1. Introduction .................................................. 3 1.1. Conventions Used in the Document ........................ 3 1.2. Terminology ............................................. 3 2. ACAP MOTD Dataset Prefix ...................................... 4 3. ACAP MOTD Hierarchy ........................................... 4 4. ACAP MOTD Attributes .......................................... 4 4.1. Basic Attributes ........................................ 4 4.2. Specific Attributes ..................................... 5 4.3. Common ABNF ............................................. 6 4.4. MOTD Entry Naming Scheme ................................ 6 5. Client MOTD Behaviour ......................................... 7 5.1. Advanced Client Behaviour ............................... 8 5.1.1. Example: Subscribe ................................ 8 5.1.2. Example: Unsubscribe .............................. 8 5.1.3. Example: Prune .................................... 9 6. Server Configuration .......................................... 9 7. Design Issues ................................................. 10 8. Security Considerations ....................................... 10 9. Acknowledgments ............................................... 10 10. Copyright .................................................... 10 11. References ................................................... 11 12. Author's Address ............................................. 11 Expires September 3, 1999 Troll [Page 2]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 1. Introduction Multi-user systems offer a small "Message of the Day" (MOTD) greeting to all users that sign onto the system, informing them of any changes made to the system, scheduled outages, etc. As systems become more distributed, the ability to make announcements to all users becomes substantially harder. Additionally, distributed systems may now fall under the management of multiple administrative domains, and each domain may wish to notify its users of upcoming events. The ACAP MOTD dataset class specifies a way to store small messages in ACAP. The MOTD dataset structure also leverages ACAP's inheritance capabilities to allow users to "subscribe" to MOTD providers. MOTD clients will allow users to view any existing MOTDs, mark MOTDs as read, and notify users when new MOTD entries are posted. Advanced MOTD clients will also allow users to subscribe or unsubscribe from MOTD providers, as well as prune any old message information. Administrative clients will create MOTDs. 1.1. Conventions Used in the 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]. Dataset names will use the string "{group-name}" to indicate that any group name may be used, and "{user-name}" to indicate that any user name, may be used in that part of the name. In examples, "C:" and "S:" indicate lines sent by the client and server respectively. 1.2. Terminology Subscription A user may wish to view MOTD information from a variety of administrative sources. This is accomplished by creating sub- datasets within the user's MOTD hierarchy (/motd/user/{user- name}) with a specific name. This sub-dataset inherits entries from the administrative MOTD repository. MOTD Provider A MOTD provider is an administrative organization that wishes to provide MOTD information to clients. Each provider MUST have a group dataset within the ACAP hierarchy, under Expires September 3, 1999 Troll [Page 3]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 /motd/group/{group-name}. 2. ACAP MOTD Dataset Prefix Datasets whose names begin with "/motd" are assumed to contain MOTD entries as defined in this document. 3. ACAP MOTD Hierarchy MOTD entries will be stored by administrators in either the /motd/site dataset, or the appropriate /motd/group/{group-name} dataset. The dataset /motd/user/{user-name} will inherit entries directly from /motd/site, giving all users access to the default, site-wide MOTD entries. Additionally, users will be able to create sub-datasets under /motd/user/{user-name}, which will be configured to inherit from one of the datasets under /motd/group. This sub-dataset indicates a subscription to a MOTD provider. 4. ACAP MOTD Attributes Attributes are specified using Augmented Backus-Naur Form [ABNF]. All attributes are single-valued. The ABNF defines the content of the attribute values prior to their encoding as an ACAP string. Clients MUST conform to the syntax when generating these attributes, but MUST NOT assume that the attribute values will conform to this syntax on access. Servers MUST NOT enforce the syntax. 4.1. Basic Attributes These attributes are defined in ACAP [ACAP] and have meaning in all dataset classes. This section describes how they are used in a MOTD dataset. entry The "entry" attribute is a unique string used to identify and entry within the MOTD dataset. MOTD entries MUST follow the entry naming scheme defined below. subdataset The "subdataset" attribute indicates there is another MOTD dataset underneath the current dataset. This is used to specify MOTD subscriptions and their locations. Entries that contain this attribute are not actually messages, and MUST not be displayed by a MOTD viewer client. However, the client MAY use Expires September 3, 1999 Troll [Page 4]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 this information to display what subscription a MOTD came from. dataset.inherit The "dataset.inherit" attribute specifies what dataset this dataset inherits from. Inheritance is used in every MOTD dataset under /motd/user. All base user MOTD datasets (/motd/user/{user-name}) have this attribute set to "/motd/site". Subscriptions have this attribute set to the path of the subscribed to MOTD provider. For more information on inheritance, consult [ACAP], section 5.1. 4.2. Specific Attributes These attributes are specific to the MOTD dataset class. motd.ExpirationDate The "motd.ExpirationDate" attribute contains the date this MOTD entry becomes invalid. This field is present only to aid MOTD administrators, and MAY be ignored by clients when displaying the MOTD. It is optional. motd.ExpirationDate = motd-datetime ; specified in Common ABNF motd.Title The "motd.Title" attribute contains a short (less than 80 characters) title for the MOTD entry. All MOTD entries MUST have the title attribute set when they are created. However, clients MUST NOT assume that all MOTD entries have this field, as purged entries MAY leave blank entries in the hierarchy. This is described in detail below. motd.Title = 1*TEXT-UTF8-CHAR ; Length <= 80 chars XXXXX motd.Body The "motd.Body" attribute contains the actual text of the MOTD. As with "motd.Title", this attribute MUST be set when the entry is created, but clients MUST NOT assume that this field is present. motd.Body = 1*TEXT-UTF8-CHAR motd.Seen The "motd.Seen" attribute indiciates whether or not the user has marked the message as seen. The contents of this attribute is Expires September 3, 1999 Troll [Page 5]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 the time at which the user marked the entry as seen. motd.Seen = motd-datetime ; specified in Common ABNF 4.3. Common ABNF The following [ABNF] rules are used above: motd-datetime = time-year time-month time-day time-hour time-minute time-second time-subsecond ;; Timestamp in UTC time-day = 2DIGIT ;; 01-31 time-hour = 2DIGIT ;; 00-23 time-minute = 2DIGIT ;; 00-59 time-month = 2DIGIT ;; 01-12 time-second = 2DIGIT ;; 00-60 time-subsecond = *DIGIT time-year = 4DIGIT 4.4. MOTD Entry Naming Scheme MOTD entry names MUST be the creation time of the entry, using the UTC encoding scheme described above. If multiple entries are being written at the same time (IE: from different administrative clients), all entries MUST delay a random amount of time, and then try again. This time information is informative, and used as a uniquifier within the dataset. It MAY also be displayed by clients to show when the MOTD entry was created. When subdatasets are created to provide subscription information, the entry name MUST be "sub-{group-name}", where "{group-name}" is the name of the group this subscription is for, if the group is present under /motd/group. If the MOTD provider is on an external source, the dataset entry name MUST be "ext-{name}", where the choice of "{name}" is up to the user. If a conflict arises with something already in use, the client MUST choose another name. Expires September 3, 1999 Troll [Page 6]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 5. Client MOTD Behaviour When fetching all available MOTDs, clients will search the user's MOTD dataset with a depth of 2, excluding entries that have already been seen. C: . SEARCH "/motd/~" DEPTH 2 RETURN ("*") NOT EQUAL "motd.Seen" "i;octet" NIL S: . ENTRY "/motd/~/19990222130000" (("entry" "19990222130000") ("modtime" "19990222130000") ("motd.Title" "Cyrus Server Unavailable") ("motd.Body" "The Cyrus EMail Server will be unavailable on Feb 23rd from 3AM to 6AM EST.")) S: . ENTRY "/motd/~/sub-asg/19990222125700" (("entry" "19990222125700") ("modtime" "19990222125700") ("motd.Title" "New Calendar Clients") ("motd.Body" "The new calendar clients are available via http://calendar.andrew.cmu.edu/.")) S: . REFER "/motd/~/ext-whatever" "acap://some.server.org/motd/group/whatever" S: . MODTIME "19990222133450" S: . OK "SEARCH Complete" The client MUST follow any referrals returned by the server, by performing a search of depth 1, and ignoring any subdatasets that are present in the remote store. (There SHOULD NOT be any subdatasets present, as referrals are only used to indicate a remote MOTD provider the user has subscribed to.) All entries that are returned SHOULD be displayed to the user. Clients can view entries that have been marked as seen by removing the seen restriction in the search. However, when doing this, the client MUST ignore any entries that have no title. These entries represent seen messages that were previously removed from the server. The ACAP server administrator will remove this at a later date. C: . SEARCH "/motd/~" DEPTH 2 RETURN ("*") ALL S: . ENTRY "/motd/~/19990222130000" (("entry" "19990222130000") ("modtime" "19990222130000") ("motd.Title" "Cyrus Server Unavailable") ("motd.Body" "The Cyrus EMail Server will be unavailable on Feb 23rd from 3AM to 6AM EST.")) S: . ENTRY "/motd/~/sub-asg/19990222125700" (("entry" "19990222125700") ("modtime" "19990222125700") ("motd.Title" "New Calendar Clients") ("motd.Body" "The new calendar clients are available via http://calendar.andrew.cmu.edu/.")) S: . ENTRY "/motd/~/19990222100000" (("entry" "19990222100000") ("modtime" "19990222100000") ("motd.Seen" "19990221173200")) S: . REFER "/motd/~/ext-whatever" Expires September 3, 1999 Troll [Page 7]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 "acap://some.server.org/motd/group/whatever" S: . MODTIME "19990222133500" S: . OK "SEARCH Complete" By using ACAP search contexts and notifications, clients MAY keep informed of any pertinent MOTD changes. 5.1. Advanced Client Behaviour By searching /motd/group, advanced MOTD clients MAY see what MOTD services are available. Clients may subscribe to a service by creating an entry within the user's MOTD hierarchy (/motd/user/{user-name}). This entry MUST indicate a subdataset relative to the root by setting the entry's "subdataset" attribute to ".". The client MUST then create the subdataset, and configure it to inherit from the appropriate group dataset. Advanced clients will also be able to locate and prune all entries that are no longer pertinent within the user's data store. This will remove the partial entries that were left around when administrators removed MOTDs that the user had marked as seen. 5.1.1. Example: Subscribe First, the client would search the ACAP hierarchy to see what MOTD groups are available: C: . SEARCH "/motd/group" RETURN () ALL S: . ENTRY "compserv" S: . ENTRY "asg" S: . MODTIME "19990222133600" S: . OK "SEARCH Complete" If the user decides to subscribe to the "compserv" MOTD group, the client MUST create the dataset "/motd/~/link-compserv", and set the "dataset.inherit" attribute to "/motd/group/compserv". C: . STORE ("/motd/~/link-compserv" "dataset.inherit" "/motd/group/compserv" "subdataset" ".") S: . OK "STORE Complete" 5.1.2. Example: Unsubscribe A client may view current subscriptions by performing the following ACAP search: C: . SEARCH "/motd/~" RETURN () NOT EQUAL "subdataset" Expires September 3, 1999 Troll [Page 8]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 "i;octet" NIL S: . ENTRY "link-compserv" S: . MODTIME "19990222133700" S: . OK "SEARCH Complete" In order to unsubscribe from a MOTD provider, the client MUST remove the subdataset entry. To unsubscribe from the "compserv" MOTD provider, both the entry and the dataset /motd/user/{user- name}/link-compserv MUST be removed. C: . STORE ("/motd/~/link-compserv" "entry" NIL) S: . OK "STORE Complete" 5.1.3. Example: Prune A client MAY find all of the existing entries that should be pruned by performing the following ACAP search: C: . SEARCH "/motd/~" DEPTH 2 RETURN ("entry") AND EQUAL "motd.Title" "i;octet" NIL EQUAL "subdataset" "i;octet" NIL S: . ENTRY "/motd/~/19990222130000" ("entry" "19990222130000") S: . ENTRY "/motd/~/sub-asg/19990222125700" ("entry" "19990222125700") S: . ENTRY "/motd/~/19990222100000" ("entry" "19990222100000") S: . MODTIME "19990222164000" S: . OK "SEARCH Complete" All of the returned entries do not have titles, and are not subdataset identifiers. They may all be removed. C: . STORE ("/motd/~/19990222130000" "entry" NIL) S: . OK "STORE Complete" C: . STORE ("/motd/~/sub-asg/199902212700" "entry" NIL) S: . OK "STORE Complete" C: . STORE ("/motd/~/19990222100000" "entry" NIL) S: . OK "STORE Complete" 6. Server Configuration Administrators of ACAP servers that provide MOTD service must make sure that each initial "/motd/user/{user-name}" dataset is configured to inherit from "/motd/site". Admins MUST make sure that the ACLs are set correctly on all MOTD datasets. "Anyone" MUST be given "r" access to "/motd/site". Finally, admins may want to go through and prune the entire /motd hierarchy, per the instructions defined above. Expires September 3, 1999 Troll [Page 9]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 7. Design Issues The MOTD dataset class was designed with the following ideas in mind: Multiple administrative domains MUST be able to provide MOTD information, Users MUST be able to specify what administrative domains they would like to receive MOTD information from, and Users MUST be able to both mark MOTD information as read, and be able to go back and view messages that were marked as seen, but are still being provided. The current specification meets all of these needs. 8. Security Considerations It is important to make sure that access controls are set correctly on all MOTD datasets. Incorrect ACLs will result in users not being able to see all messages, or malicious users introducing false messages. 9. Acknowledgments Many thanks to Rob Earhart, for his numerous technical discussions about ACAP. 10. Copyright Copyright (C) The Internet Society 1999. All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be Expires September 3, 1999 Troll [Page 10]
Internet Draft ACAP MOTD Dataset Class February 26, 1999 revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 11. References [ABNF] D. Crocker, P. Overell, "Augmented BNF for Syntax Specifications: ABNF", RFC 2234, November 1997 <ftp://ds.internic.net/rfc/rfc2234.txt> [ACAP] C. Newman, J. G. Myers, "Application Configuration Access Protocol", RFC 2244, November 1997 <ftp://ds.internic.net/rfc/rfc2244.txt> [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997 <ftp://ds.internic.net/rfc/rfc2119.txt> 12. Author's Address Ryan Troll Computing Services Carnegie Mellon 5000 Forbes Avenue Pittsburgh, PA 15213 Phone: (412) 268-8691 EMail: ryan@andrew.cmu.edu Expires September 3, 1999 Troll [Page 11]
