idnits 2.17.1 draft-ietf-ldapext-psearch-03.txt: ** The Abstract section seems to be numbered 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: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. 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.) ** There is 1 instance of too long lines in the document, the longest one being 4 characters in excess of 72. ** The abstract seems to contain references ([LDAP], [KEYWORDS]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? RFC 2119 keyword, line 82: '...ver that supports it MUST process this...' RFC 2119 keyword, line 85: '...TRUE, the server MUST NOT return any e...' RFC 2119 keyword, line 92: '... b) The server MUST NOT return a Sea...' RFC 2119 keyword, line 93: '...search operation MUST be kept active u...' RFC 2119 keyword, line 96: '...e server, the effected entries MUST be...' (8 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 287 has weird spacing: '...for the purpo...' -- 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 (15 November 2000) is 8535 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Missing reference section? 'LDAP' on line 307 looks like a reference -- Missing reference section? 'KEYWORDS' on line 304 looks like a reference -- Missing reference section? 'CHANGELOG' on line 310 looks like a reference -- Missing reference section? 'PSEARCHAPI' on line 314 looks like a reference Summary: 7 errors (**), 0 flaws (~~), 1 warning (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group M. Smith, Editor 3 INTERNET-DRAFT Netscape Communications Corp. 4 Intended Category: Informational G. Good 5 Expires: May 2001 T. Howes 6 Loudcloud, Inc. 7 R. Weltman 9 15 November 2000 11 Persistent Search: A Simple LDAP Change Notification Mechanism 12 14 1. Status of this Memo 16 This document is an Internet-Draft and is in full conformance with all 17 provisions of Section 10 of RFC2026. Internet-Drafts are working docu- 18 ments of the Internet Engineering Task Force (IETF), its areas, and its 19 working groups. Note that other groups may also distribute working 20 documents as Internet-Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference material 25 or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This draft document will be submitted to the RFC Editor as an Informa- 34 tional document. Distribution of this memo is unlimited. Technical dis- 35 cussion of this document will take place on the IETF LDAP Extension 36 Working Group mailing list . Please send 37 editorial comments directly to the editor . 39 Copyright (C) The Internet Society (1997-2000). All Rights Reserved. 41 Please see the Copyright section near the end of this document for more 42 information. 44 LDAP Persistent Search 15 November 2000 46 2. Abstract 48 This document defines two controls that extend the LDAPv3 [LDAP] search 49 operation to provide a simple mechanism by which an LDAP client can 50 receive notification of changes that occur in an LDAP server. The 51 mechanism is designed to be very flexible yet easy for clients and 52 servers to implement. Since the IETF is likely to pursue a different, 53 more comprehensive solution in this area, this document will eventually 54 be published with Informational status in order to document an existing 55 practice. 57 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 58 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 59 to be interpreted as described in RFC 2119 [KEYWORDS]. 61 3. General Approach 63 The approach taken by the Persistent Search mechanism described in this 64 document is to alter the standard LDAP search operation so that it does 65 not end after the initial set of entries matching the search criteria 66 are returned. Instead, LDAP servers keep the search operation going. 67 This provides clients and servers participating in Persistent Search 68 with an active channel through which entries that change (and additional 69 information about the changes that occur) can be communicated. 71 4. Persistent Search Control 73 This control may be included in the Controls portion of an LDAPv3 Sear- 74 chRequest message. The controlType is "2.16.840.1.113730.3.4.3". 76 PersistentSearch ::= SEQUENCE { 77 changeTypes INTEGER, 78 changesOnly BOOLEAN, 79 returnECs BOOLEAN 80 } 82 Upon receiving this control, a server that supports it MUST process this 83 as a standard LDAPv3 search with the following exceptions: 85 a) If changesOnly is TRUE, the server MUST NOT return any existing 86 entries that match the search criteria. Entries are only 87 returned when they are changed (added, modified, deleted, or 88 subject to a modifyDN operation). 90 LDAP Persistent Search 15 November 2000 92 b) The server MUST NOT return a SearchResultDone message. Instead, 93 the search operation MUST be kept active until it is abandoned 94 by the client or until the client unbinds. 96 c) As changes are made to the server, the effected entries MUST be 97 returned to the client if they match the standard search cri- 98 teria and if the operation that caused the change is included in 99 the changeTypes field. The changeTypes field is the logical OR 100 of one or more of these values: add (1), delete (2), modify (4), 101 modDN (8). 103 d) If returnECs is TRUE, the server MUST return an Entry Change 104 Notification control with each entry returned as the result of 105 changes. This control is described in the next section. 107 5. Entry Change Notification Control 109 This control provides additional information about the change the caused 110 a particular entry to be returned as the result of a persistent search. 111 The controlType is "2.16.840.1.113730.3.4.7". If the client set the 112 returnECs boolean to TRUE in the PersistentSearch control, servers MUST 113 include an EntryChangeNotification control in the Controls portion of 114 each SearchResultEntry that is returned due to an entry being added, 115 deleted, or modified. 117 EntryChangeNotification ::= SEQUENCE { 118 changeType ENUMERATED { 119 add (1), 120 delete (2), 121 modify (4), 122 modDN (8) 123 }, 124 previousDN LDAPDN OPTIONAL, -- modifyDN ops. only 125 changeNumber INTEGER OPTIONAL -- if supported 126 } 128 changeType indicates what LDAP operation caused the entry to be 129 returned. 131 previousDN is present only for modifyDN operations and gives the DN of 132 the entry before it was renamed and/or moved. Servers MUST include this 133 optional field only when returning change notifications as a result of 134 modifyDN operations. 136 LDAP Persistent Search 15 November 2000 138 changeNumber is the change number [CHANGELOG] assigned by a server for 139 the change. If a server supports an LDAP Change Log it SHOULD include 140 this field. 142 6. Intended Use 144 Some of the scenarios that the Persistent Search mechanism described in 145 this document is designed to support are described in this section. 146 Other uses of the mechanism are possible as well, but please refer to 147 the "Implementation Considerations" section for some issues to consider. 149 6.1. Cache Consistency 151 An LDAP client application with high performance needs may want to main- 152 tain a temporary, local cache of information obtained through LDAP 153 search, compare, or bind operations. To improve performance, the local 154 cache is always consulted before sending a request to an LDAP server. 155 The client application can use Persistent Search(es) against the change- 156 log [CHANGELOG] (if one is available) or against one or more subtrees 157 within the LDAP server to enable it to maintain consistency between the 158 data in its local cache and the data stored in the LDAP server. A Per- 159 sistent Search request where the changesOnly flag is FALSE can be used 160 if it is desirable to prime the cache; otherwise changesOnly would typi- 161 cally be set to TRUE in the request. 163 Caches are used for reasons other than performance improvement as well. 164 In some cases, they arise naturally out of a particular application's 165 design. For example, an LDAP client designed for administration of 166 information held in LDAP servers will undoubtedly generate screen 167 displays that show information gleaned from an LDAP server. The screen 168 display is a cache that is active and visible until the user of the 169 application takes some action that causes different information to be 170 displayed. A refresh button or similar control may be provided to the 171 user to allow them to update the cached display. A Persistent Search 172 request can be used instead by the administrative application to 173 automatically refresh the screen display as soon as the underlying LDAP 174 information changes. 176 6.2. Synchronization 178 Some LDAP clients such as those that execute on a portable computer may 179 maintain a partial or complete offline copy of the entries stored in an 180 LDAP server. While connected to the network, such a client can direct 181 all queries to the copy of data it holds and use a Persistent Search to 182 LDAP Persistent Search 15 November 2000 184 actively maintain the contents of the offline copy (alternatively, the 185 client could direct requests to the LDAP server that is the source of 186 the data). While disconnected from the network, the client must satisfy 187 all queries using its offline copy of the data. When the client recon- 188 nects to the network, it can synchronize its own copy of the data with 189 the one stored on the LDAP server and proceed to actively maintain its 190 offline copy by issuing a Persistent Search with the changesOnly flag 191 set to FALSE against the server's changelog [CHANGELOG]. A search 192 filter like "(changeNumber>=NUM)" where NUM is an integer one greater 193 than the last change the client processed would be used to limit the 194 entries returned to the set of changes the client has not yet seen. 196 6.3. Triggered Actions 198 An LDAP client application may want to take some action when an entry in 199 the directory is changed. A Persistent Search request can be used to 200 proactively monitor one or more LDAP servers for interesting changes 201 that in turn cause specific actions to be taken by an application. For 202 example, an electronic mail repository may want to perform a "create 203 mailbox" task when a new person entry is added to an LDAP directory and 204 a "delete mailbox" task when a person entry is deleted from an LDAP 205 directory. 207 7. Implementation Considerations 209 Implementors of servers that support the mechanism described in this 210 document should ensure that their implementation scales well as the 211 number of active Persistent Search requests increases and as the number 212 of changes made in the directory increases. 214 Each active Persistent Search request requires that an open TCP connec- 215 tion be maintained between an LDAP client and an LDAP server that might 216 not otherwise be kept open. Therefore, client implementors are 217 encouraged to avoid using Persistent Search for non-essential tasks and 218 to close idle LDAP connections as soon as practical. Server implemen- 219 tors are encouraged to support a large number of client connections if 220 they need to support large numbers of Persistent Search clients. 222 This specification makes no guarantees about how soon a server should 223 send notification of a changed entry to a Persistent Search client. 224 This is intentional as any specific maximum delay would be impossible to 225 meet in a distributed directory service implementation. Server imple- 226 mentors are encouraged to minimize the delay before sending notifica- 227 tions to ensure that clients' needs for timeliness of change 228 LDAP Persistent Search 15 November 2000 230 notification are met. 232 8. Limitations of the Persistent Search Mechanism 234 The mechanism described in the document has some limitations that make 235 it unsuitable as a comprehensive LDAP change notification solution. 237 8.1. No Notification When Disconnected 239 Changes that occur in the LDAP data store while a client is not con- 240 nected cannot be detected using Persistent Search. Therefore, discon- 241 nected clients that also require accurate synchronization must use 242 another mechanism such as [CHANGELOG] in conjunction with Persistent 243 Search. This is inconvenient and it introduces an undesireable depen- 244 dency on another mechanism. 246 8.2. No "Enter Set" or "Leave Set" Notifications 248 No notification is provided when an entry enters or leaves a result set 249 (the set of entries specified by the client using the search base, 250 scope, and filter). This kind of indication would be useful, for exam- 251 ple, when an entry enters or leaves the scope of the result set due to a 252 ModifyDN operation or when a Modify operation acts on a attribute value 253 that is used in the search filter. Without this kind of notification, 254 it is difficult for clients to maintain an accurate cache of the entries 255 they wish to monitor. 257 9. Security Considerations 259 In some situations, it may be important to prevent general exposure of 260 information about changes that occur in an LDAP server. Therefore, 261 servers that implement the mechanism described in this document SHOULD 262 provide a means to enforce access control on the entries returned and 263 MAY also provide specific access control mechanisms to control the use 264 of the PersistentSearch and EntryChangeNotification controls. 266 As with normal LDAP search requests, a malicious client can initiate a 267 large number of Persistent Search requests in an attempt to consume all 268 available server resources and deny service to legitimate clients. For 269 this reason, servers that implement the mechanism described in the docu- 270 ment SHOULD provide a means to limit the number of resources that can be 271 consumed by a single client. 273 LDAP Persistent Search 15 November 2000 275 10. Copyright 277 Copyright (C) The Internet Society (1997-2000). All Rights Reserved. 279 This document and translations of it may be copied and furnished to oth- 280 ers, and derivative works that comment on or otherwise explain it or 281 assist in its implementation may be prepared, copied, published and dis- 282 tributed, in whole or in part, without restriction of any kind, provided 283 that the above copyright notice and this paragraph are included on all 284 such copies and derivative works. However, this document itself may not 285 be modified in any way, such as by removing the copyright notice or 286 references to the Internet Society or other Internet organizations, 287 except as needed for the purpose of developing Internet standards in 288 which case the procedures for copyrights defined in the Internet Stan- 289 dards process must be followed, or as required to translate it into 290 languages other than English. 292 The limited permissions granted above are perpetual and will not be 293 revoked by the Internet Society or its successors or assigns. 295 This document and the information contained herein is provided on an "AS 296 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK 297 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT 298 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT 299 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FIT- 300 NESS FOR A PARTICULAR PURPOSE. 302 11. Bibliography 304 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require- 305 ment Levels", RFC 2119, March 1997. 307 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access 308 Protocol (v3)", RFC 2251, December 1997. 310 [CHANGELOG] G. Good, "Definition of an Object Class to Hold LDAP Change 311 Record", INTERNET-DRAFT , 312 July 1997. 314 [PSEARCHAPI] M. Smith, "LDAP C API Extensions for Persistent Search", 315 INTERNET-DRAFT , 316 March 1998. 318 LDAP Persistent Search 15 November 2000 320 12. Authors' Addresses 322 Mark Smith 323 Netscape Communications Corp. 324 901 San Antonio Rd. 325 Palo Alto, CA 94303-4900 326 Mail Stop SCA17 - 201 327 USA 328 +1 650 937-3477 329 mcs@netscape.com 331 Gordon Good 332 Loudcloud, Inc. 333 599 N. Mathilda Avenue 334 Sunnyvale, CA 94085 335 USA 336 +1 408 744-7300 337 ggood@loudcloud.com 339 Rob Weltman 340 +1 650 949-5279 341 robw@worldspot.com 343 Tim Howes 344 Loudcloud, Inc. 345 599 N. Mathilda Avenue 346 Sunnyvale, CA 94085 347 USA 348 +1 408 744-7300 349 howes@loudcloud.com 351 13. Appendix A: Changes since draft-ietf-ldapext-psearch-02.txt 353 "Persistent Search Control" section: replaced 'SearchResult message' 354 with 'SearchResultDone message' to match RFC 2251 terminology. 356 Added new section "Limitations of the Persistent Search Mechanism." 358 Updated Author's Addresses. 360 14. Appendix B: Changes since draft-ietf-ldapext-psearch-01.txt 362 "Status of this Memo" section: changed "Intended Category" to Infor- 363 mational. Also updated boilerplate text to reflect current I-D 364 guidelines and updated copyright to include the year "2000." 366 LDAP Persistent Search 15 November 2000 368 "Abstract" section: added sentence that says why this will be pub- 369 lished as Informational. 371 "Entry Change Notification Control" section: added the word "only" to 372 clarify that the previousDN field is only returned for modifyDN 373 operations. 375 "Authors' Addresses" section: updated Tim Howes' information. 377 1. Status of this Memo............................................1 378 2. Abstract.......................................................2 379 3. General Approach...............................................2 380 4. Persistent Search Control......................................2 381 5. Entry Change Notification Control..............................3 382 6. Intended Use...................................................4 383 6.1. Cache Consistency...........................................4 384 6.2. Synchronization.............................................4 385 6.3. Triggered Actions...........................................5 386 7. Implementation Considerations..................................5 387 8. Limitations of the Persistent Search Mechanism.................6 388 8.1. No Notification When Disconnected...........................6 389 8.2. No "Enter Set" or "Leave Set" Notifications.................6 390 9. Security Considerations........................................6 391 10. Copyright......................................................7 392 11. Bibliography...................................................7 393 12. Authors' Addresses.............................................8 394 13. Appendix A: Changes since draft-ietf-ldapext-psearch-02.txt...8 395 14. Appendix B: Changes since draft-ietf-ldapext-psearch-01.txt...8