2 Network Working Group M. Smith, Editor
4 Intended Category: Informational R. Weltman
5 Expires: September 2000 Netscape Communications Corp.
12 Persistent Search: A Simple LDAP Change Notification Mechanism
13 <draft-ietf-ldapext-psearch-02.txt>
19 1. Status of this Memo
21 This document is an Internet-Draft and is in full conformance with all
22 provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
23 ments of the Internet Engineering Task Force (IETF), its areas, and its
24 working groups. Note that other groups may also distribute working
25 documents as Internet-Drafts.
27 Internet-Drafts are draft documents valid for a maximum of six months
28 and may be updated, replaced, or obsoleted by other documents at any
29 time. It is inappropriate to use Internet-Drafts as reference material
30 or to cite them other than as "work in progress."
32 The list of current Internet-Drafts can be accessed at
33 http://www.ietf.org/ietf/1id-abstracts.txt.
35 The list of Internet-Draft Shadow Directories can be accessed at
36 http://www.ietf.org/shadow.html.
38 This draft document will be submitted to the RFC Editor as an Informa-
39 tional document. Distribution of this memo is unlimited. Technical dis-
40 cussion of this document will take place on the IETF LDAP Extension
41 Working Group mailing list <ietf-ldapext@netscape.com>. Please send
42 editorial comments directly to the editor <mcs@netscape.com>.
44 Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
46 Please see the Copyright section near the end of this document for more
53 Smith, et. al. Intended Category: Informational [Page 1]
55 LDAP Persistent Search 7 March 2000
60 This document defines two controls that extend the LDAPv3 [LDAP] search
61 operation to provide a simple mechanism by which an LDAP client can
62 receive notification of changes that occur in an LDAP server. The
63 mechanism is designed to be very flexible yet easy for clients and
64 servers to implement. Since the IETF is likely to pursue a different,
65 more comprehensive solution in this area, this document will eventually
66 be published with Informational status in order to document an existing
69 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
70 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
71 to be interpreted as described in RFC 2119 [KEYWORDS].
77 The approach taken by the Persistent Search mechanism described in this
78 document is to alter the standard LDAP search operation so that it does
79 not end after the initial set of entries matching the search criteria
80 are returned. Instead, LDAP servers keep the search operation going.
81 This provides clients and servers participating in Persistent Search
82 with an active channel through which entries that change (and additional
83 information about the changes that occur) can be communicated.
87 4. Persistent Search Control
89 This control may be included in the Controls portion of an LDAPv3 Sear-
90 chRequest message. The controlType is "2.16.840.1.113730.3.4.3".
92 PersistentSearch ::= SEQUENCE {
98 Upon receiving this control, a server that supports it MUST process this
99 as a standard LDAPv3 search with the following exceptions:
102 a) If changesOnly is TRUE, the server MUST NOT return any existing
103 entries that match the search criteria. Entries are only
104 returned when they are changed (added, modified, deleted, or
105 subject to a modifyDN operation).
109 Smith, et. al. Intended Category: Informational [Page 2]
111 LDAP Persistent Search 7 March 2000
114 b) The server MUST NOT return a SearchResult message. Instead, the
115 search operation MUST be kept active until it is abandoned by
116 the client or until the client unbinds.
119 c) As changes are made to the server, the effected entries MUST be
120 returned to the client if they match the standard search cri-
121 teria and if the operation that caused the change is included in
122 the changeTypes field. The changeTypes field is the logical OR
123 of one or more of these values: add (1), delete (2), modify (4),
127 d) If returnECs is TRUE, the server MUST return an Entry Change
128 Notification control with each entry returned as the result of
129 changes. This control is described in the next section.
133 5. Entry Change Notification Control
135 This control provides additional information about the change the caused
136 a particular entry to be returned as the result of a persistent search.
137 The controlType is "2.16.840.1.113730.3.4.7". If the client set the
138 returnECs boolean to TRUE in the PersistentSearch control, servers MUST
139 include an EntryChangeNotification control in the Controls portion of
140 each SearchResultEntry that is returned due to an entry being added,
141 deleted, or modified.
143 EntryChangeNotification ::= SEQUENCE {
144 changeType ENUMERATED {
150 previousDN LDAPDN OPTIONAL, -- modifyDN ops. only
151 changeNumber INTEGER OPTIONAL -- if supported
154 changeType indicates what LDAP operation caused the entry to be
157 previousDN is present only for modifyDN operations and gives the DN of
158 the entry before it was renamed and/or moved. Servers MUST include this
159 optional field only when returning change notifications as a result of
165 Smith, et. al. Intended Category: Informational [Page 3]
167 LDAP Persistent Search 7 March 2000
170 changeNumber is the change number [CHANGELOG] assigned by a server for
171 the change. If a server supports an LDAP Change Log it SHOULD include
178 Some of the scenarios that the Persistent Search mechanism described in
179 this document is designed to support are described in this section.
180 Other uses of the mechanism are possible as well, but please refer to
181 the "Implementation Considerations" section for some issues to consider.
184 6.1. Cache Consistency
186 An LDAP client application with high performance needs may want to main-
187 tain a temporary, local cache of information obtained through LDAP
188 search, compare, or bind operations. To improve performance, the local
189 cache is always consulted before sending a request to an LDAP server.
190 The client application can use Persistent Search(es) against the change-
191 log [CHANGELOG] (if one is available) or against one or more subtrees
192 within the LDAP server to enable it to maintain consistency between the
193 data in its local cache and the data stored in the LDAP server. A Per-
194 sistent Search request where the changesOnly flag is FALSE can be used
195 if it is desirable to prime the cache; otherwise changesOnly would typi-
196 cally be set to TRUE in the request.
198 Caches are used for reasons other than performance improvement as well.
199 In some cases, they arise naturally out of a particular application's
200 design. For example, an LDAP client designed for administration of
201 information held in LDAP servers will undoubtedly generate screen
202 displays that show information gleaned from an LDAP server. The screen
203 display is a cache that is active and visible until the user of the
204 application takes some action that causes different information to be
205 displayed. A refresh button or similar control may be provided to the
206 user to allow them to update the cached display. A Persistent Search
207 request can be used instead by the administrative application to
208 automatically refresh the screen display as soon as the underlying LDAP
214 Some LDAP clients such as those that execute on a portable computer may
215 maintain a partial or complete offline copy of the entries stored in an
216 LDAP server. While connected to the network, such a client can direct
217 all queries to the copy of data it holds and use a Persistent Search to
221 Smith, et. al. Intended Category: Informational [Page 4]
223 LDAP Persistent Search 7 March 2000
226 actively maintain the contents of the offline copy (alternatively, the
227 client could direct requests to the LDAP server that is the source of
228 the data). While disconnected from the network, the client must satisfy
229 all queries using its offline copy of the data. When the client recon-
230 nects to the network, it can synchronize its own copy of the data with
231 the one stored on the LDAP server and proceed to actively maintain its
232 offline copy by issuing a Persistent Search with the changesOnly flag
233 set to FALSE against the server's changelog [CHANGELOG]. A search
234 filter like "(changeNumber>=NUM)" where NUM is an integer one greater
235 than the last change the client processed would be used to limit the
236 entries returned to the set of changes the client has not yet seen.
239 6.3. Triggered Actions
241 An LDAP client application may want to take some action when an entry in
242 the directory is changed. A Persistent Search request can be used to
243 proactively monitor one or more LDAP servers for interesting changes
244 that in turn cause specific actions to be taken by an application. For
245 example, an electronic mail repository may want to perform a "create
246 mailbox" task when a new person entry is added to an LDAP directory and
247 a "delete mailbox" task when a person entry is deleted from an LDAP
252 7. Implementation Considerations
254 Implementors of servers that support the mechanism described in this
255 document should ensure that their implementation scales well as the
256 number of active Persistent Search requests increases and as the number
257 of changes made in the directory increases.
259 Each active Persistent Search request requires that an open TCP connec-
260 tion be maintained between an LDAP client and an LDAP server that might
261 not otherwise be kept open. Therefore, client implementors are
262 encouraged to avoid using Persistent Search for non-essential tasks and
263 to close idle LDAP connections as soon as practical. Server implemen-
264 tors are encouraged to support a large number of client connections if
265 they need to support large numbers of Persistent Search clients.
268 This specification makes no guarantees about how soon a server should
269 send notification of a changed entry to a Persistent Search client.
270 This is intentional as any specific maximum delay would be impossible to
271 meet in a distributed directory service implementation. Server imple-
272 mentors are encouraged to minimize the delay before sending notifica-
273 tions to ensure that clients' needs for timeliness of change
277 Smith, et. al. Intended Category: Informational [Page 5]
279 LDAP Persistent Search 7 March 2000
282 notification are met.
286 8. Security Considerations
288 In some situations, it may be important to prevent general exposure of
289 information about changes that occur in an LDAP server. Therefore,
290 servers that implement the mechanism described in this document SHOULD
291 provide a means to enforce access control on the entries returned and
292 MAY also provide specific access control mechanisms to control the use
293 of the PersistentSearch and EntryChangeNotification controls.
296 As with normal LDAP search requests, a malicious client can initiate a
297 large number of Persistent Search requests in an attempt to consume all
298 available server resources and deny service to legitimate clients. For
299 this reason, servers that implement the mechanism described in the docu-
300 ment SHOULD provide a means to limit the number of resources that can be
301 consumed by a single client.
307 Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
309 This document and translations of it may be copied and furnished to oth-
310 ers, and derivative works that comment on or otherwise explain it or
311 assist in its implementation may be prepared, copied, published and dis-
312 tributed, in whole or in part, without restriction of any kind, provided
313 that the above copyright notice and this paragraph are included on all
314 such copies and derivative works. However, this document itself may not
315 be modified in any way, such as by removing the copyright notice or
316 references to the Internet Society or other Internet organizations,
317 except as needed for the purpose of developing Internet standards in
318 which case the procedures for copyrights defined in the Internet Stan-
319 dards process must be followed, or as required to translate it into
320 languages other than English.
322 The limited permissions granted above are perpetual and will not be
323 revoked by the Internet Society or its successors or assigns.
325 This document and the information contained herein is provided on an "AS
326 IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK
327 FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT
328 LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT
329 INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
333 Smith, et. al. Intended Category: Informational [Page 6]
335 LDAP Persistent Search 7 March 2000
338 FITNESS FOR A PARTICULAR PURPOSE.
344 [KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
345 ment Levels", RFC 2119, March 1997.
347 [LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
348 Protocol (v3)", RFC 2251, December 1997.
350 [CHANGELOG] G. Good, "Definition of an Object Class to Hold LDAP Change
351 Record", INTERNET-DRAFT <draft-ietf-asid-changelog-01.txt>,
354 [PSEARCHAPI] M. Smith, "LDAP C API Extensions for Persistent Search",
355 INTERNET-DRAFT <draft-ietf-ldapext-c-api-psearch-00.txt>,
360 11. Authors' Addresses
363 Netscape Communications Corp.
364 501 E. Middlefield Rd., Mailstop MV068
365 Mountain View, CA 94043
371 Netscape Communications Corp.
372 501 E. Middlefield Rd., Mailstop MV068
373 Mountain View, CA 94043
379 Netscape Communications Corp.
380 501 E. Middlefield Rd., Mailstop MV068
381 Mountain View, CA 94043
384 rweltman@netscape.com
389 Smith, et. al. Intended Category: Informational [Page 7]
391 LDAP Persistent Search 7 March 2000
404 12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt
406 "Status of this Memo" section: changed "Intended Category" to Infor-
407 mational. Also updated boilerplate text to reflect current I-D
408 guidelines and updated copyright to include the year "2000."
410 "Abstract" section: added sentence that says why this will be pub-
411 lished as Informational.
413 "Entry Change Notification Control" section: added the word "only" to
414 clarify that the previousDN field is only returned for modifyDN
417 "Authors' Addresses" section: updated Tim Howes' information.
445 Smith, et. al. Intended Category: Informational [Page 8]
449 1. Status of this Memo............................................1
450 2. Abstract.......................................................2
451 3. General Approach...............................................2
452 4. Persistent Search Control......................................2
453 5. Entry Change Notification Control..............................3
454 6. Intended Use...................................................4
455 6.1. Cache Consistency...........................................4
456 6.2. Synchronization.............................................4
457 6.3. Triggered Actions...........................................5
458 7. Implementation Considerations..................................5
459 8. Security Considerations........................................6
460 9. Copyright......................................................6
461 10. Bibliography...................................................7
462 11. Authors' Addresses.............................................7
463 12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt...8