idnits 2.17.1 draft-ietf-acap-motd-dataset-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing document type: Expected "INTERNET-DRAFT" in the upper left hand corner of the first page ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 7 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** The abstract seems to contain references ([ACAP]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 482 has weird spacing: '...r, "Key words...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: 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 this information to display what subscription a MOTD came from. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 26, 1999) is 9181 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 2234 (ref. 'ABNF') (Obsoleted by RFC 4234) Summary: 12 errors (**), 0 flaws (~~), 4 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group Ryan Troll 3 Document: draft-ietf-acap-motd-dataset-00.txt Carnegie Mellon 4 Expires September 3, 1999 February 26, 1999 6 ACAP Message of the Day Dataset Class 8 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. Internet-Drafts are 14 working documents of the Internet Engineering Task Force (IETF), its 15 areas, and its working groups. Note that other groups may also 16 distribute working documents as Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other documents 20 at any time. It is inappropriate to use Internet- Drafts as 21 reference material or to cite them other than as "work in progress." 23 To view the list Internet-Draft Shadow Directories, see 24 http://www.ietf.org/shadow.html. 26 Distribution of this memo is unlimited. 28 Abstract 30 The Application Configuration Access Protocol [ACAP] is designed to 31 support remote storage and access of common application option, 32 configuration and preference information. Once such piece of 33 information is the "Message of the Day" greeting, used by system 34 administrators to communicate important information to all users 35 when they begin to use a system. This document describes a common 36 format for storing MOTD information in ACAP, how site administrators 37 may configure their ACAP MOTD service to allow multiple groups 38 within the site to provide custom MOTD information, and how a client 39 should access and use this information. 41 Table of Contents 43 Status of this Memo ............................................... 1 45 Abstract .......................................................... 1 47 1. Introduction .................................................. 3 48 1.1. Conventions Used in the Document ........................ 3 49 1.2. Terminology ............................................. 3 51 2. ACAP MOTD Dataset Prefix ...................................... 4 53 3. ACAP MOTD Hierarchy ........................................... 4 55 4. ACAP MOTD Attributes .......................................... 4 56 4.1. Basic Attributes ........................................ 4 57 4.2. Specific Attributes ..................................... 5 58 4.3. Common ABNF ............................................. 6 59 4.4. MOTD Entry Naming Scheme ................................ 6 61 5. Client MOTD Behaviour ......................................... 7 62 5.1. Advanced Client Behaviour ............................... 8 63 5.1.1. Example: Subscribe ................................ 8 64 5.1.2. Example: Unsubscribe .............................. 8 65 5.1.3. Example: Prune .................................... 9 67 6. Server Configuration .......................................... 9 69 7. Design Issues ................................................. 10 71 8. Security Considerations ....................................... 10 73 9. Acknowledgments ............................................... 10 75 10. Copyright .................................................... 10 77 11. References ................................................... 11 79 12. Author's Address ............................................. 11 80 1. Introduction 82 Multi-user systems offer a small "Message of the Day" (MOTD) 83 greeting to all users that sign onto the system, informing them of 84 any changes made to the system, scheduled outages, etc. As systems 85 become more distributed, the ability to make announcements to all 86 users becomes substantially harder. Additionally, distributed 87 systems may now fall under the management of multiple administrative 88 domains, and each domain may wish to notify its users of upcoming 89 events. 91 The ACAP MOTD dataset class specifies a way to store small messages 92 in ACAP. The MOTD dataset structure also leverages ACAP's 93 inheritance capabilities to allow users to "subscribe" to MOTD 94 providers. 96 MOTD clients will allow users to view any existing MOTDs, mark MOTDs 97 as read, and notify users when new MOTD entries are posted. 98 Advanced MOTD clients will also allow users to subscribe or 99 unsubscribe from MOTD providers, as well as prune any old message 100 information. Administrative clients will create MOTDs. 102 1.1. Conventions Used in the Document 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 106 document are to be interpreted as described in [KEYWORDS]. 108 Dataset names will use the string "{group-name}" to indicate that 109 any group name may be used, and "{user-name}" to indicate that any 110 user name, may be used in that part of the name. 112 In examples, "C:" and "S:" indicate lines sent by the client and 113 server respectively. 115 1.2. Terminology 117 Subscription 118 A user may wish to view MOTD information from a variety of 119 administrative sources. This is accomplished by creating sub- 120 datasets within the user's MOTD hierarchy (/motd/user/{user- 121 name}) with a specific name. This sub-dataset inherits entries 122 from the administrative MOTD repository. 124 MOTD Provider 125 A MOTD provider is an administrative organization that wishes to 126 provide MOTD information to clients. Each provider MUST have a 127 group dataset within the ACAP hierarchy, under 128 /motd/group/{group-name}. 130 2. ACAP MOTD Dataset Prefix 132 Datasets whose names begin with "/motd" are assumed to contain MOTD 133 entries as defined in this document. 135 3. ACAP MOTD Hierarchy 137 MOTD entries will be stored by administrators in either the 138 /motd/site dataset, or the appropriate /motd/group/{group-name} 139 dataset. The dataset /motd/user/{user-name} will inherit entries 140 directly from /motd/site, giving all users access to the default, 141 site-wide MOTD entries. 143 Additionally, users will be able to create sub-datasets under 144 /motd/user/{user-name}, which will be configured to inherit from one 145 of the datasets under /motd/group. This sub-dataset indicates a 146 subscription to a MOTD provider. 148 4. ACAP MOTD Attributes 150 Attributes are specified using Augmented Backus-Naur Form [ABNF]. 151 All attributes are single-valued. 153 The ABNF defines the content of the attribute values prior to their 154 encoding as an ACAP string. Clients MUST conform to the syntax when 155 generating these attributes, but MUST NOT assume that the attribute 156 values will conform to this syntax on access. Servers MUST NOT 157 enforce the syntax. 159 4.1. Basic Attributes 161 These attributes are defined in ACAP [ACAP] and have meaning in all 162 dataset classes. This section describes how they are used in a MOTD 163 dataset. 165 entry 166 The "entry" attribute is a unique string used to identify and 167 entry within the MOTD dataset. MOTD entries MUST follow the 168 entry naming scheme defined below. 170 subdataset 171 The "subdataset" attribute indicates there is another MOTD 172 dataset underneath the current dataset. This is used to specify 173 MOTD subscriptions and their locations. Entries that contain 174 this attribute are not actually messages, and MUST not be 175 displayed by a MOTD viewer client. However, the client MAY use 176 this information to display what subscription a MOTD came from. 178 dataset.inherit 179 The "dataset.inherit" attribute specifies what dataset this 180 dataset inherits from. Inheritance is used in every MOTD 181 dataset under /motd/user. All base user MOTD datasets 182 (/motd/user/{user-name}) have this attribute set to 183 "/motd/site". Subscriptions have this attribute set to the path 184 of the subscribed to MOTD provider. 186 For more information on inheritance, consult [ACAP], section 187 5.1. 189 4.2. Specific Attributes 191 These attributes are specific to the MOTD dataset class. 193 motd.ExpirationDate 194 The "motd.ExpirationDate" attribute contains the date this MOTD 195 entry becomes invalid. This field is present only to aid MOTD 196 administrators, and MAY be ignored by clients when displaying 197 the MOTD. It is optional. 199 motd.ExpirationDate = motd-datetime 200 ; specified in Common ABNF 202 motd.Title 203 The "motd.Title" attribute contains a short (less than 80 204 characters) title for the MOTD entry. All MOTD entries MUST 205 have the title attribute set when they are created. However, 206 clients MUST NOT assume that all MOTD entries have this field, 207 as purged entries MAY leave blank entries in the hierarchy. 208 This is described in detail below. 210 motd.Title = 1*TEXT-UTF8-CHAR 211 ; Length <= 80 chars XXXXX 213 motd.Body 214 The "motd.Body" attribute contains the actual text of the MOTD. 215 As with "motd.Title", this attribute MUST be set when the entry 216 is created, but clients MUST NOT assume that this field is 217 present. 219 motd.Body = 1*TEXT-UTF8-CHAR 221 motd.Seen 222 The "motd.Seen" attribute indiciates whether or not the user has 223 marked the message as seen. The contents of this attribute is 224 the time at which the user marked the entry as seen. 226 motd.Seen = motd-datetime 227 ; specified in Common ABNF 229 4.3. Common ABNF 231 The following [ABNF] rules are used above: 233 motd-datetime = time-year time-month time-day time-hour 234 time-minute time-second time-subsecond 235 ;; Timestamp in UTC 237 time-day = 2DIGIT ;; 01-31 239 time-hour = 2DIGIT ;; 00-23 241 time-minute = 2DIGIT ;; 00-59 243 time-month = 2DIGIT ;; 01-12 245 time-second = 2DIGIT ;; 00-60 247 time-subsecond = *DIGIT 249 time-year = 4DIGIT 251 4.4. MOTD Entry Naming Scheme 253 MOTD entry names MUST be the creation time of the entry, using the 254 UTC encoding scheme described above. If multiple entries are being 255 written at the same time (IE: from different administrative 256 clients), all entries MUST delay a random amount of time, and then 257 try again. This time information is informative, and used as a 258 uniquifier within the dataset. It MAY also be displayed by clients 259 to show when the MOTD entry was created. 261 When subdatasets are created to provide subscription information, 262 the entry name MUST be "sub-{group-name}", where "{group-name}" is 263 the name of the group this subscription is for, if the group is 264 present under /motd/group. If the MOTD provider is on an external 265 source, the dataset entry name MUST be "ext-{name}", where the 266 choice of "{name}" is up to the user. If a conflict arises with 267 something already in use, the client MUST choose another name. 269 5. Client MOTD Behaviour 271 When fetching all available MOTDs, clients will search the user's 272 MOTD dataset with a depth of 2, excluding entries that have already 273 been seen. 275 C: . SEARCH "/motd/~" DEPTH 2 RETURN ("*") NOT EQUAL "motd.Seen" 276 "i;octet" NIL 277 S: . ENTRY "/motd/~/19990222130000" (("entry" "19990222130000") 278 ("modtime" "19990222130000") ("motd.Title" "Cyrus Server 279 Unavailable") ("motd.Body" "The Cyrus EMail Server will be 280 unavailable on Feb 23rd from 3AM to 6AM EST.")) 281 S: . ENTRY "/motd/~/sub-asg/19990222125700" (("entry" "19990222125700") 282 ("modtime" "19990222125700") ("motd.Title" "New Calendar 283 Clients") ("motd.Body" "The new calendar clients are available 284 via http://calendar.andrew.cmu.edu/.")) 285 S: . REFER "/motd/~/ext-whatever" 286 "acap://some.server.org/motd/group/whatever" 287 S: . MODTIME "19990222133450" 288 S: . OK "SEARCH Complete" 290 The client MUST follow any referrals returned by the server, by 291 performing a search of depth 1, and ignoring any subdatasets that 292 are present in the remote store. (There SHOULD NOT be any 293 subdatasets present, as referrals are only used to indicate a remote 294 MOTD provider the user has subscribed to.) 296 All entries that are returned SHOULD be displayed to the user. 298 Clients can view entries that have been marked as seen by removing 299 the seen restriction in the search. However, when doing this, the 300 client MUST ignore any entries that have no title. These entries 301 represent seen messages that were previously removed from the 302 server. The ACAP server administrator will remove this at a later 303 date. 305 C: . SEARCH "/motd/~" DEPTH 2 RETURN ("*") ALL 306 S: . ENTRY "/motd/~/19990222130000" (("entry" "19990222130000") 307 ("modtime" "19990222130000") ("motd.Title" "Cyrus Server 308 Unavailable") ("motd.Body" "The Cyrus EMail Server will be 309 unavailable on Feb 23rd from 3AM to 6AM EST.")) 310 S: . ENTRY "/motd/~/sub-asg/19990222125700" (("entry" "19990222125700") 311 ("modtime" "19990222125700") ("motd.Title" "New Calendar 312 Clients") ("motd.Body" "The new calendar clients are available 313 via http://calendar.andrew.cmu.edu/.")) 314 S: . ENTRY "/motd/~/19990222100000" (("entry" "19990222100000") 315 ("modtime" "19990222100000") ("motd.Seen" "19990221173200")) 316 S: . REFER "/motd/~/ext-whatever" 317 "acap://some.server.org/motd/group/whatever" 318 S: . MODTIME "19990222133500" 319 S: . OK "SEARCH Complete" 321 By using ACAP search contexts and notifications, clients MAY keep 322 informed of any pertinent MOTD changes. 324 5.1. Advanced Client Behaviour 326 By searching /motd/group, advanced MOTD clients MAY see what MOTD 327 services are available. Clients may subscribe to a service by 328 creating an entry within the user's MOTD hierarchy 329 (/motd/user/{user-name}). This entry MUST indicate a subdataset 330 relative to the root by setting the entry's "subdataset" attribute 331 to ".". The client MUST then create the subdataset, and configure 332 it to inherit from the appropriate group dataset. 334 Advanced clients will also be able to locate and prune all entries 335 that are no longer pertinent within the user's data store. This 336 will remove the partial entries that were left around when 337 administrators removed MOTDs that the user had marked as seen. 339 5.1.1. Example: Subscribe 341 First, the client would search the ACAP hierarchy to see what MOTD 342 groups are available: 344 C: . SEARCH "/motd/group" RETURN () ALL 345 S: . ENTRY "compserv" 346 S: . ENTRY "asg" 347 S: . MODTIME "19990222133600" 348 S: . OK "SEARCH Complete" 350 If the user decides to subscribe to the "compserv" MOTD group, the 351 client MUST create the dataset "/motd/~/link-compserv", and set the 352 "dataset.inherit" attribute to "/motd/group/compserv". 354 C: . STORE ("/motd/~/link-compserv" 355 "dataset.inherit" "/motd/group/compserv" 356 "subdataset" ".") 357 S: . OK "STORE Complete" 359 5.1.2. Example: Unsubscribe 361 A client may view current subscriptions by performing the following 362 ACAP search: 364 C: . SEARCH "/motd/~" RETURN () NOT EQUAL "subdataset" 365 "i;octet" NIL 366 S: . ENTRY "link-compserv" 367 S: . MODTIME "19990222133700" 368 S: . OK "SEARCH Complete" 370 In order to unsubscribe from a MOTD provider, the client MUST remove 371 the subdataset entry. To unsubscribe from the "compserv" MOTD 372 provider, both the entry and the dataset /motd/user/{user- 373 name}/link-compserv MUST be removed. 375 C: . STORE ("/motd/~/link-compserv" "entry" NIL) 376 S: . OK "STORE Complete" 378 5.1.3. Example: Prune 380 A client MAY find all of the existing entries that should be pruned 381 by performing the following ACAP search: 383 C: . SEARCH "/motd/~" DEPTH 2 RETURN ("entry") AND EQUAL "motd.Title" 384 "i;octet" NIL EQUAL "subdataset" "i;octet" NIL 385 S: . ENTRY "/motd/~/19990222130000" ("entry" "19990222130000") 386 S: . ENTRY "/motd/~/sub-asg/19990222125700" ("entry" "19990222125700") 387 S: . ENTRY "/motd/~/19990222100000" ("entry" "19990222100000") 388 S: . MODTIME "19990222164000" 389 S: . OK "SEARCH Complete" 391 All of the returned entries do not have titles, and are not 392 subdataset identifiers. They may all be removed. 394 C: . STORE ("/motd/~/19990222130000" "entry" NIL) 395 S: . OK "STORE Complete" 396 C: . STORE ("/motd/~/sub-asg/199902212700" "entry" NIL) 397 S: . OK "STORE Complete" 398 C: . STORE ("/motd/~/19990222100000" "entry" NIL) 399 S: . OK "STORE Complete" 401 6. Server Configuration 403 Administrators of ACAP servers that provide MOTD service must make 404 sure that each initial "/motd/user/{user-name}" dataset is 405 configured to inherit from "/motd/site". 407 Admins MUST make sure that the ACLs are set correctly on all MOTD 408 datasets. "Anyone" MUST be given "r" access to "/motd/site". 410 Finally, admins may want to go through and prune the entire /motd 411 hierarchy, per the instructions defined above. 413 7. Design Issues 415 The MOTD dataset class was designed with the following ideas in 416 mind: 418 Multiple administrative domains MUST be able to provide MOTD 419 information, 421 Users MUST be able to specify what administrative domains they 422 would like to receive MOTD information from, and 424 Users MUST be able to both mark MOTD information as read, and be 425 able to go back and view messages that were marked as seen, but 426 are still being provided. 428 The current specification meets all of these needs. 430 8. Security Considerations 432 It is important to make sure that access controls are set correctly 433 on all MOTD datasets. Incorrect ACLs will result in users not being 434 able to see all messages, or malicious users introducing false 435 messages. 437 9. Acknowledgments 439 Many thanks to Rob Earhart, for his numerous technical discussions 440 about ACAP. 442 10. Copyright 444 Copyright (C) The Internet Society 1999. All Rights Reserved. 446 This document and translations of it may be copied and furnished to 447 others, and derivative works that comment on or otherwise explain it 448 or assist in its implementation may be prepared, copied, published 449 and distributed, in whole or in part, without restriction of any 450 kind, provided that the above copyright notice and this paragraph 451 are included on all such copies and derivative works. However, this 452 document itself may not be modified in any way, such as by removing 453 the copyright notice or references to the Internet Society or other 454 Internet organizations, except as needed for the purpose of 455 developing Internet standards in which case the procedures for 456 copyrights defined in the Internet Standards process must be 457 followed, or as required to translate it into languages other than 458 English. 460 The limited permissions granted above are perpetual and will not be 461 revoked by the Internet Society or its successors or assigns. 463 This document and the information contained herein is provided on an 464 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 465 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 466 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 467 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 468 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 470 11. References 472 [ABNF] D. Crocker, P. Overell, "Augmented BNF for Syntax 473 Specifications: ABNF", RFC 2234, November 1997 475 477 [ACAP] C. Newman, J. G. Myers, "Application Configuration Access 478 Protocol", RFC 2244, November 1997 480 482 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate 483 Requirement Levels", RFC 2119, March 1997 485 487 12. Author's Address 489 Ryan Troll 490 Computing Services 491 Carnegie Mellon 492 5000 Forbes Avenue 493 Pittsburgh, PA 15213 495 Phone: (412) 268-8691 496 EMail: ryan@andrew.cmu.edu