git.sur5r.net Git - openldap/blob - doc/drafts/draft-ietf-ldapext-psearch-xx.txt

   1
   2 Network Working Group                                   M. Smith, Editor
   3 INTERNET-DRAFT                                                   G. Good
   4 Intended Category: Informational                              R. Weltman
   5 Expires: September 2000                    Netscape Communications Corp.
   6                                                                 T. Howes
   7                                                          Loudcloud, Inc.
   8
   9                                                             7 March 2000
  10
  11
  12      Persistent Search: A Simple LDAP Change Notification Mechanism
  13                   <draft-ietf-ldapext-psearch-02.txt>
  14
  15
  16
  17
  18
  19 1.  Status of this Memo
  20
  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.
  26
  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."
  31
  32 The list of current Internet-Drafts can be accessed at
  33 http://www.ietf.org/ietf/1id-abstracts.txt.
  34
  35 The list of Internet-Draft Shadow Directories can be accessed at
  36 http://www.ietf.org/shadow.html.
  37
  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>.
  43
  44 Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
  45
  46 Please see the Copyright section near the end of this document for more
  47 information.
  48
  49
  50
  51
  52
  53 Smith, et. al.      Intended Category: Informational            [Page 1]
  54 \f
  55 LDAP Persistent Search                                      7 March 2000
  56
  57
  58 2.  Abstract
  59
  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
  67 practice.
  68
  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].
  72
  73
  74
  75 3.  General Approach
  76
  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.
  84
  85
  86
  87 4.  Persistent Search Control
  88
  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".
  91
  92            PersistentSearch ::= SEQUENCE {
  93                    changeTypes INTEGER,
  94                    changesOnly BOOLEAN,
  95                    returnECs BOOLEAN
  96            }
  97
  98 Upon receiving this control, a server that supports it MUST process this
  99 as a standard LDAPv3 search with the following exceptions:
 100
 101
 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).
 106
 107
 108
 109 Smith, et. al.      Intended Category: Informational            [Page 2]
 110 \f
 111 LDAP Persistent Search                                      7 March 2000
 112
 113
 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.
 117
 118
 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),
 124         modDN (8).
 125
 126
 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.
 130
 131
 132
 133 5.  Entry Change Notification Control
 134
 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.
 142
 143            EntryChangeNotification ::= SEQUENCE {
 144                      changeType ENUMERATED {
 145                              add             (1),
 146                              delete          (2),
 147                              modify          (4),
 148                              modDN           (8)
 149                      },
 150                      previousDN   LDAPDN OPTIONAL,     -- modifyDN ops. only
 151                      changeNumber INTEGER OPTIONAL     -- if supported
 152            }
 153
 154 changeType indicates what LDAP operation caused the entry to be
 155 returned.
 156
 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
 160 modifyDN operations.
 161
 162
 163
 164
 165 Smith, et. al.      Intended Category: Informational            [Page 3]
 166 \f
 167 LDAP Persistent Search                                      7 March 2000
 168
 169
 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
 172 this field.
 173
 174
 175
 176 6.  Intended Use
 177
 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.
 182
 183
 184 6.1.  Cache Consistency
 185
 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.
 197
 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
 209 information changes.
 210
 211
 212 6.2.  Synchronization
 213
 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
 218
 219
 220
 221 Smith, et. al.      Intended Category: Informational            [Page 4]
 222 \f
 223 LDAP Persistent Search                                      7 March 2000
 224
 225
 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.
 237
 238
 239 6.3.  Triggered Actions
 240
 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
 248 directory.
 249
 250
 251
 252 7.  Implementation Considerations
 253
 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.
 258
 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.
 266
 267
 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
 274
 275
 276
 277 Smith, et. al.      Intended Category: Informational            [Page 5]
 278 \f
 279 LDAP Persistent Search                                      7 March 2000
 280
 281
 282 notification are met.
 283
 284
 285
 286 8.  Security Considerations
 287
 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.
 294
 295
 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.
 302
 303
 304
 305 9.  Copyright
 306
 307 Copyright (C) The Internet Society (1997-2000). All Rights Reserved.
 308
 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.
 321
 322 The limited permissions granted above are perpetual and will not be
 323 revoked by the Internet Society or its successors or assigns.
 324
 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
 330
 331
 332
 333 Smith, et. al.      Intended Category: Informational            [Page 6]
 334 \f
 335 LDAP Persistent Search                                      7 March 2000
 336
 337
 338 FITNESS FOR A PARTICULAR PURPOSE.
 339
 340
 341
 342 10.  Bibliography
 343
 344 [KEYWORDS]   S. Bradner, "Key words for use in RFCs to Indicate Require-
 345              ment Levels", RFC 2119, March 1997.
 346
 347 [LDAP]       M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
 348              Protocol (v3)", RFC 2251, December 1997.
 349
 350 [CHANGELOG]  G. Good, "Definition of an Object Class to Hold LDAP Change
 351              Record", INTERNET-DRAFT <draft-ietf-asid-changelog-01.txt>,
 352              July 1997.
 353
 354 [PSEARCHAPI] M. Smith, "LDAP C API Extensions for Persistent Search",
 355              INTERNET-DRAFT <draft-ietf-ldapext-c-api-psearch-00.txt>,
 356              March 1998.
 357
 358
 359
 360 11.  Authors' Addresses
 361
 362    Mark Smith
 363    Netscape Communications Corp.
 364    501 E. Middlefield Rd., Mailstop MV068
 365    Mountain View, CA 94043
 366    USA
 367    +1 650 937-3477
 368    mcs@netscape.com
 369
 370    Gordon Good
 371    Netscape Communications Corp.
 372    501 E. Middlefield Rd., Mailstop MV068
 373    Mountain View, CA 94043
 374    USA
 375    +1 650 937-3825
 376    ggood@netscape.com
 377
 378    Rob Weltman
 379    Netscape Communications Corp.
 380    501 E. Middlefield Rd., Mailstop MV068
 381    Mountain View, CA 94043
 382    USA
 383    +1 650 937-3301
 384    rweltman@netscape.com
 385
 386
 387
 388
 389 Smith, et. al.      Intended Category: Informational            [Page 7]
 390 \f
 391 LDAP Persistent Search                                      7 March 2000
 392
 393
 394    Tim Howes
 395    Loudcloud, Inc.
 396    615 Tasman Dr.
 397    Sunnyvale, CA 94089
 398    USA
 399    +1 650 321 4565
 400    howes@loudcloud.com
 401
 402
 403
 404 12.  Appendix A:  Changes since draft-ietf-ldapext-psearch-01.txt
 405
 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."
 409
 410    "Abstract" section: added sentence that says why this will be pub-
 411    lished as Informational.
 412
 413    "Entry Change Notification Control" section: added the word "only" to
 414    clarify that the previousDN field is only returned for modifyDN
 415    operations.
 416
 417    "Authors' Addresses" section: updated Tim Howes' information.
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445 Smith, et. al.      Intended Category: Informational            [Page 8]
 446 \f
 447
 448
 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