From: Kurt Zeilenga Date: Fri, 1 Mar 2002 20:31:15 +0000 (+0000) Subject: obsoleted by smith-psearch X-Git-Tag: OPENLDAP_REL_ENG_2_MP~382 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=e310bd0c86400ccb1e7c2c80aa625d000b84a30d;p=openldap obsoleted by smith-psearch --- diff --git a/doc/drafts/draft-ietf-ldapext-psearch-xx.txt b/doc/drafts/draft-ietf-ldapext-psearch-xx.txt deleted file mode 100644 index c313da6aaa..0000000000 --- a/doc/drafts/draft-ietf-ldapext-psearch-xx.txt +++ /dev/null @@ -1,463 +0,0 @@ - -Network Working Group M. Smith, Editor -INTERNET-DRAFT G. Good -Intended Category: Informational R. Weltman -Expires: September 2000 Netscape Communications Corp. - T. Howes - Loudcloud, Inc. - - 7 March 2000 - - - Persistent Search: A Simple LDAP Change Notification Mechanism - - - - - - -1. 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 docu- -ments 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." - -The list of current Internet-Drafts can be accessed at -http://www.ietf.org/ietf/1id-abstracts.txt. - -The list of Internet-Draft Shadow Directories can be accessed at -http://www.ietf.org/shadow.html. - -This draft document will be submitted to the RFC Editor as an Informa- -tional document. Distribution of this memo is unlimited. Technical dis- -cussion of this document will take place on the IETF LDAP Extension -Working Group mailing list . Please send -editorial comments directly to the editor . - -Copyright (C) The Internet Society (1997-2000). All Rights Reserved. - -Please see the Copyright section near the end of this document for more -information. - - - - - -Smith, et. al. Intended Category: Informational [Page 1] - -LDAP Persistent Search 7 March 2000 - - -2. Abstract - -This document defines two controls that extend the LDAPv3 [LDAP] search -operation to provide a simple mechanism by which an LDAP client can -receive notification of changes that occur in an LDAP server. The -mechanism is designed to be very flexible yet easy for clients and -servers to implement. Since the IETF is likely to pursue a different, -more comprehensive solution in this area, this document will eventually -be published with Informational status in order to document an existing -practice. - -The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", -"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are -to be interpreted as described in RFC 2119 [KEYWORDS]. - - - -3. General Approach - -The approach taken by the Persistent Search mechanism described in this -document is to alter the standard LDAP search operation so that it does -not end after the initial set of entries matching the search criteria -are returned. Instead, LDAP servers keep the search operation going. -This provides clients and servers participating in Persistent Search -with an active channel through which entries that change (and additional -information about the changes that occur) can be communicated. - - - -4. Persistent Search Control - -This control may be included in the Controls portion of an LDAPv3 Sear- -chRequest message. The controlType is "2.16.840.1.113730.3.4.3". - - PersistentSearch ::= SEQUENCE { - changeTypes INTEGER, - changesOnly BOOLEAN, - returnECs BOOLEAN - } - -Upon receiving this control, a server that supports it MUST process this -as a standard LDAPv3 search with the following exceptions: - - - a) If changesOnly is TRUE, the server MUST NOT return any existing - entries that match the search criteria. Entries are only - returned when they are changed (added, modified, deleted, or - subject to a modifyDN operation). - - - -Smith, et. al. Intended Category: Informational [Page 2] - -LDAP Persistent Search 7 March 2000 - - - b) The server MUST NOT return a SearchResult message. Instead, the - search operation MUST be kept active until it is abandoned by - the client or until the client unbinds. - - - c) As changes are made to the server, the effected entries MUST be - returned to the client if they match the standard search cri- - teria and if the operation that caused the change is included in - the changeTypes field. The changeTypes field is the logical OR - of one or more of these values: add (1), delete (2), modify (4), - modDN (8). - - - d) If returnECs is TRUE, the server MUST return an Entry Change - Notification control with each entry returned as the result of - changes. This control is described in the next section. - - - -5. Entry Change Notification Control - -This control provides additional information about the change the caused -a particular entry to be returned as the result of a persistent search. -The controlType is "2.16.840.1.113730.3.4.7". If the client set the -returnECs boolean to TRUE in the PersistentSearch control, servers MUST -include an EntryChangeNotification control in the Controls portion of -each SearchResultEntry that is returned due to an entry being added, -deleted, or modified. - - EntryChangeNotification ::= SEQUENCE { - changeType ENUMERATED { - add (1), - delete (2), - modify (4), - modDN (8) - }, - previousDN LDAPDN OPTIONAL, -- modifyDN ops. only - changeNumber INTEGER OPTIONAL -- if supported - } - -changeType indicates what LDAP operation caused the entry to be -returned. - -previousDN is present only for modifyDN operations and gives the DN of -the entry before it was renamed and/or moved. Servers MUST include this -optional field only when returning change notifications as a result of -modifyDN operations. - - - - -Smith, et. al. Intended Category: Informational [Page 3] - -LDAP Persistent Search 7 March 2000 - - -changeNumber is the change number [CHANGELOG] assigned by a server for -the change. If a server supports an LDAP Change Log it SHOULD include -this field. - - - -6. Intended Use - -Some of the scenarios that the Persistent Search mechanism described in -this document is designed to support are described in this section. -Other uses of the mechanism are possible as well, but please refer to -the "Implementation Considerations" section for some issues to consider. - - -6.1. Cache Consistency - -An LDAP client application with high performance needs may want to main- -tain a temporary, local cache of information obtained through LDAP -search, compare, or bind operations. To improve performance, the local -cache is always consulted before sending a request to an LDAP server. -The client application can use Persistent Search(es) against the change- -log [CHANGELOG] (if one is available) or against one or more subtrees -within the LDAP server to enable it to maintain consistency between the -data in its local cache and the data stored in the LDAP server. A Per- -sistent Search request where the changesOnly flag is FALSE can be used -if it is desirable to prime the cache; otherwise changesOnly would typi- -cally be set to TRUE in the request. - -Caches are used for reasons other than performance improvement as well. -In some cases, they arise naturally out of a particular application's -design. For example, an LDAP client designed for administration of -information held in LDAP servers will undoubtedly generate screen -displays that show information gleaned from an LDAP server. The screen -display is a cache that is active and visible until the user of the -application takes some action that causes different information to be -displayed. A refresh button or similar control may be provided to the -user to allow them to update the cached display. A Persistent Search -request can be used instead by the administrative application to -automatically refresh the screen display as soon as the underlying LDAP -information changes. - - -6.2. Synchronization - -Some LDAP clients such as those that execute on a portable computer may -maintain a partial or complete offline copy of the entries stored in an -LDAP server. While connected to the network, such a client can direct -all queries to the copy of data it holds and use a Persistent Search to - - - -Smith, et. al. Intended Category: Informational [Page 4] - -LDAP Persistent Search 7 March 2000 - - -actively maintain the contents of the offline copy (alternatively, the -client could direct requests to the LDAP server that is the source of -the data). While disconnected from the network, the client must satisfy -all queries using its offline copy of the data. When the client recon- -nects to the network, it can synchronize its own copy of the data with -the one stored on the LDAP server and proceed to actively maintain its -offline copy by issuing a Persistent Search with the changesOnly flag -set to FALSE against the server's changelog [CHANGELOG]. A search -filter like "(changeNumber>=NUM)" where NUM is an integer one greater -than the last change the client processed would be used to limit the -entries returned to the set of changes the client has not yet seen. - - -6.3. Triggered Actions - -An LDAP client application may want to take some action when an entry in -the directory is changed. A Persistent Search request can be used to -proactively monitor one or more LDAP servers for interesting changes -that in turn cause specific actions to be taken by an application. For -example, an electronic mail repository may want to perform a "create -mailbox" task when a new person entry is added to an LDAP directory and -a "delete mailbox" task when a person entry is deleted from an LDAP -directory. - - - -7. Implementation Considerations - -Implementors of servers that support the mechanism described in this -document should ensure that their implementation scales well as the -number of active Persistent Search requests increases and as the number -of changes made in the directory increases. - -Each active Persistent Search request requires that an open TCP connec- -tion be maintained between an LDAP client and an LDAP server that might -not otherwise be kept open. Therefore, client implementors are -encouraged to avoid using Persistent Search for non-essential tasks and -to close idle LDAP connections as soon as practical. Server implemen- -tors are encouraged to support a large number of client connections if -they need to support large numbers of Persistent Search clients. - - -This specification makes no guarantees about how soon a server should -send notification of a changed entry to a Persistent Search client. -This is intentional as any specific maximum delay would be impossible to -meet in a distributed directory service implementation. Server imple- -mentors are encouraged to minimize the delay before sending notifica- -tions to ensure that clients' needs for timeliness of change - - - -Smith, et. al. Intended Category: Informational [Page 5] - -LDAP Persistent Search 7 March 2000 - - -notification are met. - - - -8. Security Considerations - -In some situations, it may be important to prevent general exposure of -information about changes that occur in an LDAP server. Therefore, -servers that implement the mechanism described in this document SHOULD -provide a means to enforce access control on the entries returned and -MAY also provide specific access control mechanisms to control the use -of the PersistentSearch and EntryChangeNotification controls. - - -As with normal LDAP search requests, a malicious client can initiate a -large number of Persistent Search requests in an attempt to consume all -available server resources and deny service to legitimate clients. For -this reason, servers that implement the mechanism described in the docu- -ment SHOULD provide a means to limit the number of resources that can be -consumed by a single client. - - - -9. Copyright - -Copyright (C) The Internet Society (1997-2000). All Rights Reserved. - -This document and translations of it may be copied and furnished to oth- -ers, and derivative works that comment on or otherwise explain it or -assist in its implementation may be prepared, copied, published and dis- -tributed, 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 Stan- -dards 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 -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 - - - -Smith, et. al. Intended Category: Informational [Page 6] - -LDAP Persistent Search 7 March 2000 - - -FITNESS FOR A PARTICULAR PURPOSE. - - - -10. Bibliography - -[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require- - ment Levels", RFC 2119, March 1997. - -[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access - Protocol (v3)", RFC 2251, December 1997. - -[CHANGELOG] G. Good, "Definition of an Object Class to Hold LDAP Change - Record", INTERNET-DRAFT , - July 1997. - -[PSEARCHAPI] M. Smith, "LDAP C API Extensions for Persistent Search", - INTERNET-DRAFT , - March 1998. - - - -11. Authors' Addresses - - Mark Smith - Netscape Communications Corp. - 501 E. Middlefield Rd., Mailstop MV068 - Mountain View, CA 94043 - USA - +1 650 937-3477 - mcs@netscape.com - - Gordon Good - Netscape Communications Corp. - 501 E. Middlefield Rd., Mailstop MV068 - Mountain View, CA 94043 - USA - +1 650 937-3825 - ggood@netscape.com - - Rob Weltman - Netscape Communications Corp. - 501 E. Middlefield Rd., Mailstop MV068 - Mountain View, CA 94043 - USA - +1 650 937-3301 - rweltman@netscape.com - - - - -Smith, et. al. Intended Category: Informational [Page 7] - -LDAP Persistent Search 7 March 2000 - - - Tim Howes - Loudcloud, Inc. - 615 Tasman Dr. - Sunnyvale, CA 94089 - USA - +1 650 321 4565 - howes@loudcloud.com - - - -12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt - - "Status of this Memo" section: changed "Intended Category" to Infor- - mational. Also updated boilerplate text to reflect current I-D - guidelines and updated copyright to include the year "2000." - - "Abstract" section: added sentence that says why this will be pub- - lished as Informational. - - "Entry Change Notification Control" section: added the word "only" to - clarify that the previousDN field is only returned for modifyDN - operations. - - "Authors' Addresses" section: updated Tim Howes' information. - - - - - - - - - - - - - - - - - - - - - - - - - - - -Smith, et. al. Intended Category: Informational [Page 8] - - - -1. Status of this Memo............................................1 -2. Abstract.......................................................2 -3. General Approach...............................................2 -4. Persistent Search Control......................................2 -5. Entry Change Notification Control..............................3 -6. Intended Use...................................................4 -6.1. Cache Consistency...........................................4 -6.2. Synchronization.............................................4 -6.3. Triggered Actions...........................................5 -7. Implementation Considerations..................................5 -8. Security Considerations........................................6 -9. Copyright......................................................6 -10. Bibliography...................................................7 -11. Authors' Addresses.............................................7 -12. Appendix A: Changes since draft-ietf-ldapext-psearch-01.txt...8