3 Internet Draft R. Megginson, Editor
4 Document: <draft-ietf-ldup-lcup-03.txt> M. Smith
5 Category: Proposed Standard Netscape
14 LDAP Client Update Protocol
19 This document is an Internet-Draft and is in full conformance with
20 all provisions of Section 10 of RFC2026 [1].
22 Internet-Drafts are working documents of the Internet Engineering
23 Task Force (IETF), its areas, and its working groups. Note that
24 other groups may also distribute working documents as Internet-
27 Internet-Drafts are draft documents valid for a maximum of six
28 months and may be updated, replaced, or obsoleted by other documents
29 at any time. It is inappropriate to use Internet- Drafts as
30 reference material 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. The list of Internet-
34 Draft Shadow Directories can be accessed at
35 http://www.ietf.org/shadow.html.
39 This document defines the LDAP Client Update Protocol (LCUP). The
40 protocol is intended to allow an LDAP client to synchronize with the
41 content of a directory information tree (DIT) stored by an LDAP
42 server and to be notified about the changes to that content.
45 2. Conventions used in this document
47 In the protocol flow definition, the notation C->S and S->C
48 specifies the direction of the data flow from the client to the
49 server and from the server to the client respectively.
51 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
52 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
53 this document are to be interpreted as described in RFC-2119
62 The LCUP protocol is intended to allow LDAP clients to synchronize
63 with the content stored by LDAP servers.
65 The problem areas addressed by the protocol include:
67 - mobile clients that maintain a local read-only copy of the
68 directory data. While off-line, the client uses the local copy of
69 the data. When the client connects to the network, it
70 synchronizes with the current directory content and can be
71 optionally notified about the changes that occur while it is on-
72 line. For example, a mail client can maintain a local copy of the
73 corporate address book that it synchronizes with the master copy
74 whenever the client gets connected to the corporate network.
76 - applications intending to synchronize heterogeneous data stores.
77 A meta directory application, for instance, would periodically
78 retrieve a list of modified entries from the directory, construct
79 the changes and apply them to a foreign data store.
81 - clients that need to take certain actions when a directory entry
82 is modified. For instance, an electronic mail repository may want
83 to perform a "create mailbox" task when a new person entry is
84 added to an LDAP directory and a "delete mailbox" task when a
85 person entry is removed.
87 The problem areas not being considered:
89 - directory server to directory server synchronization. The IETF is
90 developing a LDAP replication protocol, called [LDUP], which is
91 specifically designed to address this problem area.
93 There are currently several protocols in use for LDAP client server
94 synchronization. While each protocol addresses the needs of a
95 particular group of clients (e.g., on-line clients or off-line
96 clients) none satisfies the requirements of all clients in the
97 target group. For instance, a mobile client that was off-line and
98 wants to become up to date with the server and stay up to date while
99 connected can't be easily supported by any of the existing
102 Several features of the protocol distinguish it from LDUP
103 replication. LCUP is designed such that the server does not need to
104 maintain state information on behalf of the client. The clients are
105 responsible for storing the information about how up to date they
106 are with respect to the server's content. LCUP design avoids the
107 need for LCUP-specific update agreements to be made between client
108 and server prior to LCUP use. The client decides when and from where
109 to retrieve the changes. LCUP design requires clients to initiate
110 the update session and "pull" the changes from server.
112 LCUP operations are subject to administrative and access
113 control policies enforced by the server.
117 Megginson, et. al. Proposed Standard - Expires: December 2002 2
121 A part of the DIT which is enabled for LCUP is referred to as an
122 LCUP Context. A server may support one or more LCUP Contexts.
124 4. Protocol Specification
126 This section describes the protocol elements and the protocol flow.
128 4.1 Universally Unique Identifiers
130 Distinguished names can change, so are therefore unreliable
131 as identifiers. The server SHOULD assign a Universally Unique
132 Identifier (or UUID for short) to each entry as it is created. This
133 identifier will be stored as an operational attribute of the entry,
134 named `entryUUID'. The entryUUID attribute is single valued. A
135 consistent algorithm for generating such universally unique
136 identifiers may be standardized at some point in the future.
137 The definition of the entryUUID attribute type, written using the
138 BNF form of AttributeDescription described in RFC 2252 [RFC2252] is:
140 ( OID-To-Be-Specified
142 DESC `universally unique entry identifier'
143 EQUALITY caseIgnoreMatch
144 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
147 USAGE directoryOperation )
149 4.2 LCUP Cookie Value
151 The LCUP protocol uses a cookie to hold the state of the client's
152 data with respect to the server's data. The LCUP Cookie is a value
153 of the following ASN.1 type:
155 LCUPCookie ::= SEQUENCE {
157 value OCTET STRING OPTIONAL
160 scheme - this is the OID which identifies the format of the value.
161 The scheme OID, like all object identifiers, MUST be unique for a
162 given cookie scheme. The cookie value may be opaque or it may be
163 exposed to LCUP clients. For cookie schemes that expose their
164 value, the preferred form of documentation is an RFC. It is
165 expected that there will be one or more standards track cookie
166 schemes where the value format is exposed and described in detail.
168 value - this is the actual data describing the state of the
169 client's data. This value may be opaque, or its value may have
170 some well-known format, depending on the scheme. The cookie value
171 MUST be included except when a client has no stored state; i.e.,
172 when the client is requesting a full synchronization. When the
173 server sends back a cookie, the cookie value MUST be present.
176 Megginson, et. al. Proposed Standard - Expires: December 2002 3
180 Further uses of the LCUP Cookie value are described below.
182 4.3 Additional LDAP Result Codes defined by LCUP
184 The LDAP result code names and numbers defined in the following
185 table are to be replaced with IANA assigned result code names and
186 numbers per draft-ietf-ldapbis-iana-xx.txt.
188 lcupResourcesExhausted (TBD) the server is running out of
190 lcupSecurityViolation (TBD) the client is suspected of malicious
192 lcupInvalidCookie (TBD) invalid cookie was supplied by the
193 client - both/either the scheme
194 and/or the value part was invalid
195 lcupUnsupportedScheme (TBD) The scheme part of the cookie is a
196 valid OID but is not supported by
198 lcupClientDisconnect (TBD) client requested search termination
199 using the LDAP Cancel extended
200 operation request [CANCEL]
201 lcupReloadRequired (TBD) indicates that client data needs to
202 be reinitialized. This reason is
203 returned if the server does not
204 contain sufficient information to
205 synchronize the client or if the
206 server's data was reloaded since the
207 last synchronization session
209 The uses of these codes are described below.
211 4.4 Client Update Control Value
213 A client initiates a synchronization session with a server by
214 attaching a clientUpdate control to an LDAP searchRequest message.
215 The client SHOULD specify entryUUID in the attributes list in the
216 searchRequest message. The search specification determines the part
217 of the directory information tree (DIT) the client wishes to
218 synchronize with, the set of attributes it is interested in and the
219 amount of data the client is willing to receive. The clientUpdate
220 control contains the client's synchronization specification. The
221 controlType field for the clientUpdate control is
222 ClientUpdateControlOID (to be assigned). The controlValue is an
223 OCTET STRING, whose contents are the bytes of the BER encoding of
235 Megginson, et. al. Proposed Standard - Expires: December 2002 4
239 ClientUpdateControlValue ::= SEQUENCE {
240 updateType ENUMERATED {
242 synchronizeAndPersist (1),
244 sendCookieInterval INTEGER OPTIONAL,
245 cookie LCUPCookie OPTIONAL
248 updateType - specifies the type of update requested by the client
250 synchronizeOnly - the server sends all the data needed to
251 synchronize the client with the server, then closes the
254 synchronizeAndPersist - the server sends all the data needed to
255 synchronize the client with the server, then leaves open the
256 connection, sending to the client any new added, modified, or
257 deleted entries that satisfy the search criteria.
259 persistOnly - the server does not synchronize the data with the
260 client but leaves open the connection and sends over any new
261 added, modified, or deleted entries that satisfy the search
264 sendCookieInterval û (optional) the server SHOULD send the cookie
265 back in the entryUpdate control value for every
266 sendCookieInterval number of SearchResultEntry PDUs returned to
267 the client. For example, if the value is 5, the server SHOULD
268 send the cookie back in the entryUpdate control value for every 5
269 search results returned to the client. If this value is absent,
270 zero or less than zero, the server chooses the interval.
272 cookie - a value that represents the current state of the client's
273 data. If a cookie is provided, the server MUST use the enclosed
274 scheme throughout the duration of the LCUP session or until an
275 LCUP context boundary is crossed, since a new cookie may be
276 required in that case. If the value or scheme part of the cookie
277 is invalid, the server MUST return immediately with a
278 SearchResultDone message with the resultCode set to the value of
279 lcupInvalidCookie. If the scheme part of the cookie is a valid
280 OID, but is not supported, the server MUST return immediately
281 with a SearchResultDone message with the resultCode set to the
282 value of lcupUnsupportedScheme.
284 If the cookie is omitted, the server MAY use any scheme it
287 4.5 Entry Update Control Value
289 In response to the client's synchronization request, the server
290 returns one or more SearchResultEntry PDU that fits the client's
291 specification. Each SearchResultEntry PDU also contains an
292 entryUpdateControl that describes the LCUP state of the returned
294 Megginson, et. al. Proposed Standard - Expires: December 2002 5
298 entry. To represent a deleted entry, the server attaches an
299 entryUpdate control to the corresponding SearchResultEntry. The
300 SearchResultEntry corresponding to a deleted entry MUST contain a
301 valid DN and SHOULD contain a valid UUID but, to reduce the amount
302 of data sent to the client, it SHOULD not contain any other
305 Furthermore, the server may elect to periodically return to the
306 client the cookie that represents the state of the client's data.
307 This information is useful in case the client crashes or gets
308 disconnected. The client MAY specify how often to receive the cookie
309 by the use of the sendCookieInterval in the clientUpdate control
310 value (see above). If the client does not specify a value, the
311 server will determine the interval.
313 The controlType field for the entryUpdate control is
314 EntryUpdateControlOID (to be assigned). The controlValue is an
315 OCTET STRING, whose contents are the bytes of the BER encoding of
318 EntryUpdateControlValue ::= SEQUENCE {
320 entryDeleted BOOLEAN,
321 cookie LCUPCookie OPTIONAL
325 stateUpdate - if set to TRUE, indicates that the entry to which the
326 control is attached contains no changes and it is sent only to
327 communicate to the client the new cookie. In this case, the
328 entryDeleted field MUST be ignored and the cookie field MUST
329 contain the updated cookie. This feature allows updating the
330 client's cookie when there are no changes that effect the
331 client's data store. Note that the control MUST be attached to a
332 valid SearchResultEntry, which should contain a valid LDAPDN in
333 the objectName field, and MAY contain an entryUUID attribute, but
334 SHOULD NOT contain any other attributes. The server MAY send the
335 entry named by the baseObject from the client's search request.
337 entryDeleted - if set to TRUE, indicates that the entry to which
338 the control is attached was deleted. The server MAY also set
339 this to TRUE if the entry has left the client's search result
340 set. As far as the client is concerned, a deleted entry is no
341 different than an entry that has left the result set.
343 cookie - the LCUP cookie value that represents the current state of
346 4.6 Client Update Done Control Value
348 When the server has finished processing the client's request, it
349 attaches a clientUpdateDone control to the SearchResultDone message
350 and sends it to the client. However, if the SearchResultDone message
351 contains a resultCode that is not success or lcupClientDisconnect,
353 Megginson, et. al. Proposed Standard - Expires: December 2002 6
357 the clientUpdateDone control MAY be omitted. The controlType field
358 for the clientUpdateDone control is ClientUpdateDoneControlOID (to
359 be assigned). The controlValue is an OCTET STRING, whose contents
360 are the bytes of the BER encoding of the following:
362 ClientUpdateDoneControlValue ::= SEQUENCE {
363 cookie LCUPCookie OPTIONAL
366 cookie - the LCUP cookie value that represents the current state of
367 the client's data. Although this value is OPTIONAL, it MUST be set
368 in the ClientUpdateDoneControlValue if the SearchResultDone
369 resultCode is success or lcupClientDisconnect. This provides a
370 good "checksum" of what the server thinks the state of the client
371 is. If some error occurred, either an LDAP search error (e.g.
372 insufficientAccessRights) or an LCUP error (e.g.
373 lcupUnsupportedScheme), the cookie MAY be omitted.
375 If server resources become tight, the server can terminate one or
376 more search operations by sending a SearchResultDone message to the
377 client(s) with a resultCode of lcupResourcesExhausted. Unless the
378 client sets the updateType field to persistOnly, the server attaches
379 a clientUpdateDone control that contains the cookie that corresponds
380 to the current state of the client's data. A server set policy is
381 used to decide which searches to terminate. This can also be used as
382 a security mechanism to disconnect clients that are suspected of
383 malicious actions, but if the server can infer that the client is
384 malicious, the server should return lcupSecurityViolation instead.
386 4.7 Client Initiated Termination
388 If the client needs to terminate the synchronization process and it
389 wishes to obtain the cookie that represents the current state of its
390 data, it issues an LDAP Cancel operation [CANCEL]. The server
391 responds immediately with a LDAP Cancel response [CANCEL]. The
392 server MAY send any pending SearchResultEntry PDUs if the server
393 cannot easily abort or remove those search results from its outgoing
394 queue. The server SHOULD send as few of these remaining
395 SearchResultEntry PDUs as possible. Finally, the server sends the
396 message SearchResultDone with the clientUpdateDone control attached.
398 If the client is not interested in the state information, it can
399 simply abandon the search operation or disconnect from the server.
403 The client server interaction can proceed in three different ways
404 depending on the client's requirements. Protocol flows beginning
405 with an asterisk (*) are optional or conditional.
407 If the client's intent is not to synchronize data but to trigger
408 actions in response to directory modifications, the protocol
412 Megginson, et. al. Proposed Standard - Expires: December 2002 7
416 C->S Sends a search operation with a clientUpdate control attached.
417 The search specification determines the part of the DIT the
418 client wishes to synchronize with and the set of attributes it
419 is interested in. The updateType field of the control value
420 should be set to persistOnly.
421 *S->C If there is an error (invalid search scope, invalid cookie)
422 the server returns the appropriate error codes and terminates
423 the request (SearchResultDone message with optional
424 clientUpdateDone control)
425 S->C Sends change notification to the client for each change to the
426 data within the client's search specification. Each
427 SearchResultEntry may have an entryUpdate control attached.
428 *S->C If the server starts to run out of resources or the client is
429 suspected of malicious actions, the server SHOULD terminate
430 the search operation by sending to the client a
431 SearchResultDone message with optional clientUpdateDone
432 control attached. The resultCode in the SearchResultDone
433 mesasge SHOULD be set to lcupResourcesExhausted or
434 lcupSecurityViolation depending on the reason for termination.
435 *C->S If the client receives lcupResourcesExhausted error from the
436 server, it MUST wait for a while before attempting another
437 synchronization session with the server. It is RECOMMENDED
438 that clients use an exponential backoff strategy.
439 C->S The client terminates the search. The client can do this by
440 abandoning the search operation, disconnecting from the
441 server, or by sending an LDAP Cancel operation.
442 *S->C If the server receives the LDAP Cancel op, it will immediately
443 send back the LDAP Cancel response
444 *S->C If the server sent the LDAP Cancel response, the server MAY
445 send any pending SearchResultEntry PDUs in its outgoing queue
446 *S->C If the server sent the LDAP Cancel response, after the server
447 sends the response and any pending SearchResultEntry PDUs, the
448 server sends the SearchResultDone message with the
449 clientUpdateDone control attached. The resultCode in the
450 SearchResultDone message will be either lcupClientDisconnect
451 or some LDAP error code (not success).
452 S->C Stops sending changes to the client and closes the connection.
454 If the client's intent is to synchronize with the server and then
455 disconnect, the protocol proceeds as follows:
457 C->S Sends a search operation with the clientUpdate control
458 attached. The search specification determines the part of the
459 DIT the client wishes to synchronize with, the set of
460 attributes it is interested in and the amount of data the
461 client is willing to receive. If this is the initial
462 synchronization session, the client either does not provide a
463 cookie or provides a cookie with no value; otherwise, the
464 cookie field of the control is set to the cookie received from
465 the server at the end of the last synchronization session. If
466 the scheme field of the cookie was provided, the server MUST
467 use that scheme throughout the duration of the LCUP session or
468 until an LCUP boundary is crossed, since the server will
469 usually require a different cookie in that case anyway. (Note
471 Megginson, et. al. Proposed Standard - Expires: December 2002 8
475 that the client can synchronize with different servers during
476 different synchronization sessions.) The updateType field of
477 the control value is set to synchronizeOnly.
478 *S->C If there is an error (invalid search scope, invalid cookie)
479 the server returns the appropriate error codes and terminates
480 the request (SearchResultDone message with optional
481 clientUpdateDone control)
482 *S->C If no cookie is specified in the clientUpdate control, or if
483 the value field of the cookie is empty, the server sends all
484 data that matches the client's search specification followed
485 by the SearchResultDone message with a clientUpdateDone
486 control attached. The control contains the cookie that
487 corresponds to the current state of the client's data. If
488 synchronization was successful, the resultCode in the
489 SearchResultDone message should be success.
490 *S->C If an invalid cookie is specified, the server sends the
491 SearchResultDone message with the resultCode set to
493 *S->C If a valid cookie is specified and the data that matches the
494 search specification has been reloaded or the server does not
495 contain enough state information to synchronize the client,
496 the server sends a SearchResultDone message with the
497 resultCode set to lcupReloadRequired.
498 *S->C If the cookie is valid and the client is up to date, the
499 server sends a success response to the client.
500 S->C If the cookie is valid and there is data to be sent, the
501 server sends the modified entries to the client. Each
502 SearchResultEntry contains the attributes requested by the
503 client in the search specification regardless of whether they
504 were modified. An entryUpdate control with the entryDeleted
505 field set to TRUE MUST be attached to every deleted entry. The
506 server may also periodically attach an entryUpdate control to
507 the entries sent to the client to indicate the current state
508 of the client's data. In that case, the cookie field of the
509 control represents the state of the client's data including
510 the entry to which the control is attached. Once all the
511 changes are sent successfully, the server sends a
512 SearchResultDone with the clientUpdateDone control attached.
513 The control contains the cookie that represents the current
514 state of the client's data. The resultCode in the
515 SearchResultDone message is set to success. If the resultCode
516 is not success, the server may OPTIONALLY attach the
517 clientUpdateDone control to the SearchResultDone message.
518 The client stores the cookie received from the server until
519 the next synchronization session.
520 *C->S If the resultCode in the SearchResultDone message is set
521 lcupReloadRequired, the client clears its data store and
522 repeats the synchronization process by sending the search
523 operation with clientUpdate control that contains no cookie,
524 or that contains a cookie with no value field.
526 If the client's intent is to be synchronized with the server and
527 stay notified about data modifications, the protocol proceeds as
530 Megginson, et. al. Proposed Standard - Expires: December 2002 9
535 C->S The client behaves exactly as in the previous case except it
536 sets the updateType field in the control value to
537 synchronizeAndPersist.
538 S->C The server behaves exactly as in the previous case except the
539 connection is kept open after the initial set of changes is
540 sent to the client. A SearchResultDone message is not sent to
541 the client; instead, the server keeps sending changes to the
543 *S->C If the server starts to run out of resources or the client is
544 suspected of malicious actions, the server SHOULD terminate
545 the search operation by sending to the client a
546 SearchResultDone message with the resultCode set to
547 lcupResourcesExhausted or lcupSecurityViolation depending on
548 the reason for termination.
549 *C->S If the client receives lcupResourcesExhausted error from the
550 server, it MUST wait for a while before attempting another
551 synchronization session with the server. We recommend
552 exponential backoff strategy.
553 C->S Sends an LDAP Cancel operation to the server to terminate the
554 synchronization session.
555 S->C Responds with an LDAP Cancel response, followed optionally by
556 SearchResultEntry PDUs, followed by a SearchResultDone with
557 the clientUpdateDone control optionally attached. If the
558 control is present, it contains the cookie that represents the
559 current state of the client's data. The value of the
560 resultCode in the SearchResultDone message will be either
561 lcupClientDisconnect or some other LDAPResult resultCode (not
562 success). The control may not be present if some error
565 4.9 Size and Time Limits
567 The search request size or the time limits can only be imposed for
568 non-persistent operations, those that set the updateType field of
569 the ClientUpdateControlValue to synchronizeOnly (for the entire
570 operation) or synchronizeAndPersist (for the initial synchronization
571 phase only). All other operations MUST set both limits to 0. The
572 server SHOULD ignore the limits set for persistent operations.
574 4.10 Changes vs. Operations
576 A server that supports UUIDs SHOULD communicate a modifyDN
577 operation by sending the client the current form of the entry (with
578 its new DN) along with an entryUUID attribute. A server that does
579 not support UUIDs SHOULD communicate a modifyDN operation by sending
580 the client a deletion for the previous DN followed by an entry for
581 the new DN. Note that for servers that do not support UUIDs, no
582 guarantees are made about the correctness of the client state in the
583 presence of modifyDN operations.
585 Communicating modifyDN operations by sending a delete of the old DN
586 followed by an entry with the new DN makes it impossible for an LCUP
587 client to distinguish between a modifyDN operation, which is one
589 Megginson, et. al. Proposed Standard - Expires: December 2002 10
593 atomic operation, and an delete operation followed by an add of a
594 new entry. The loss of information about atomicity may cause
595 problems for some LCUP clients. For example, when an entry is
596 renamed, a client that manages resources such as a person's mailbox
597 might delete the mailbox and everything in it instead of merely
598 changing the name associated with the mailbox.
600 Also note that regardless of how a modifyDN operation is
601 communicated to the client, if the client state shows that the
602 object that underwent the modifyDN operation was the root of a
603 subtree, the client MUST infer that the DNs of all objects in the
604 subtree have changed such that they reflect the new DN of the
607 4.11 Operations on the Same Connection
609 It is permissible for the client to issue other LDAP operations on
610 the connection used by the protocol. Since each LDAP
611 request/response carries a message id there will be no ambiguity
612 about which PDU belongs to which operation. By sharing the
613 connection among multiple operations, the server will be able to
614 conserve its resources.
616 4.12 Interactions with Other LDAP Search and Response Controls
618 LCUP defines neither restrictions nor guarantees about the ability
619 to use the LDAP client update control defined in this document in
620 conjunction with other LDAP controls, except for the following: A
621 server MAY ignore non-critical controls supplied with the LCUP
622 control. A server MAY ignore the LCUP control if it is non-critical
623 and it is supplied with other critical controls. If a server
624 receives a critical LCUP control with another critical control, and
625 the server does not support both controls at the same time, the
626 server SHOULD return unavailableCriticalExtension.
628 5. Additional Features
630 There are several features present in other protocols or considered
631 useful by clients that are currently not included in the protocol
632 primarily because they are difficult to implement on the server.
633 These features are briefly discussed in this section. This section
634 is intended to open a discussion on the merits of including and
635 approaches to implementing these features.
637 5.1 Triggered Search Change Type
639 This feature is present in the Triggered Search specification. A
640 flag is attached to each entry returned to the client indicating the
641 reason why this entry is returned. The possible reasons from the
643 "- notChange: the entry existed in the directory and matched the
644 search at the time the operation is being performed,
645 - enteredSet: the entry entered the result,
646 - leftSet: the entry left the result,
648 Megginson, et. al. Proposed Standard - Expires: December 2002 11
652 - modified: the entry was part of the result set, was modified or
653 renamed, and still is in the result set."
655 The leftSet feature is particularly useful because it indicates to
656 the client that an entry is no longer within the client's search
657 specification and the client can remove the associated data from its
658 data store. Ironically, this feature is the hardest to implement on
659 the server because the server does not keep track of the client's
660 state and has no easy way of telling which entries moved out of
661 scope between synchronization sessions with the client.
663 A compromise could be reached by only providing this feature for the
664 operations that occur while the client is connected to the server.
665 This is easier to accomplish because the decision about the change
666 type can be made based only on the change without need for any
667 historical information. This, however, would add complexity to the
670 5.2 Persistent Search Change Type
672 This feature is present in the Persistent Search specification.
673 Persistent search has the notion of changeTypes. The client
674 specifies which type of updates will cause entries to be returned,
675 and optionally whether the server tags each returned entry with the
676 type of change that caused that entry to be returned.
678 For LCUP, the intention is full synchronization, not partial. Each
679 entry returned by an LCUP search will have some change associated
680 with it that may concern the client. The client may have to have a
681 local index of entries by DN or UUID to determine if the entry has
682 been added or just modified. It is easy for clients to determine if
683 the entry has been deleted because the entryDeleted value of the
684 entryUpdateControl will be TRUE.
688 Some earlier synchronization protocols sent the client(s) only the
689 modified attributes of the entry rather than the entire entry. While
690 this approach can significantly reduce the amount of data returned
691 to the client, it has several disadvantages. First, unless a
692 separate mechanism (like the change type described above) is used to
693 notify the client about entries moving into the search scope,
694 sending only the changes can result in the client having an
695 incomplete version of the data. Let's consider an example. An
696 attribute of an entry is modified. As a result of the change, the
697 entry enters the scope of the client's search. If only the changes
698 are sent, the client would never see the initial data of the entry.
699 Second, this feature is hard to implement since the server might not
700 contain sufficient information to construct the changes based solely
701 on the server's state and the client's cookie. On the other hand,
702 this feature can be easily implemented by the client assuming that
703 the client has the previous version of the data and can perform
704 value by value comparisons.
707 Megginson, et. al. Proposed Standard - Expires: December 2002 12
713 Some earlier synchronization protocols allowed clients to control
714 the amount of data sent to them in the search response. This feature
715 was intended to allow clients with limited resources to process
716 synchronization data in batches. However, an LDAP search operation
717 already provides the means for the client to specify the size limit
718 by setting the sizeLimit field in the SearchRequest to the maximum
719 number of entries the client is willing to receive. While the
720 granularity is not the same, the assumption is that regular LDAP
721 clients that can deal with the limitations of the LDAP protocol will
726 Some earlier synchronization protocols allowed a client to specify
727 that parent entries should be sent before the children for add
728 operations and children entries sent before their parents during
729 delete operations. This ordering helps clients to maintain a
730 hierarchical view of the data in their data store. While possibly
731 useful, this feature is relatively hard to implement and is
732 expensive to perform.
734 6. Client Side Considerations
736 Clients SHOULD always specify entryUUID in the SearchRequest
739 The cookie received from the server after a synchronization session
740 can only be used with the same or more restrictive search
741 specification than the search that generated the cookie. The server
742 will reject the search operation with a cookie that does not satisfy
743 this condition. This is because the client can end up with an
744 incomplete data store otherwise. A more restrictive search
745 specification is the one that generates a subset of the data
746 produced by the original search specification.
748 Because an LCUP client specifies the area of the tree with which it
749 wishes to synchronize through the standard LDAP search
750 specification, the client can be returned noSuchObject error if the
751 root of the synchronization area was renamed between the
752 synchronization sessions or during a synchronization session. If
753 this condition occurs, the client can attempt to locate the root by
754 using the root's UUID saved in client's local data store. It then
755 can repeat the synchronization request using the new search base. In
756 general, a client can detect that an entry was renamed and apply the
757 changes received to the right entry by using the UUID rather than DN
760 Each active persistent operation requires that an open TCP
761 connection be maintained between an LDAP client and an LDAP server
762 that might not otherwise be kept open. Therefore, client
763 implementors are encouraged to avoid using persistent operations for
764 non-essential tasks and to close idle LDAP connections as soon as
766 Megginson, et. al. Proposed Standard - Expires: December 2002 13
770 practical. The server may close connections if server resources
773 The client MAY receive a continuation reference
774 (SearchResultReference [RFC2251 SECTION 4.5.3]) if the search
775 request spans multiple parts of the DIT, some of which may require a
776 different LCUP cookie, some of which may not even be managed by
777 LCUP. The client SHOULD maintain a cache of the LDAP URLs returned
778 in the continuation references and the cookies associated with them.
779 The client is responsible for performing another LCUP search to
780 follow the references, and SHOULD use the cookie corresponding to
781 the LDAP URL for that reference (if it has a cookie).
783 The client may receive a referral (Referral [RFC2251 SECTION
784 4.1.11]) when the search base is a subordinate reference, and this
785 will end the operation.
787 For alias dereferencing, the server will behave as if the client had
788 requested neverDerefAliases or derefFindingBaseObj as the
789 derefAliases field in the search request [RFC2251, Section 4.5.1].
790 If the client specifies a value other than neverDerefAliases or
791 derefFindingBaseObj, the server will return protocolError to the
794 Changes to data (e.g., that might affect the LCUP client's filter or
795 scope) or meta-data (e.g., that might affect the client's read
796 access) may affect the presence of entries in the search set.
797 Servers MAY notify LCUP clients of changes to the search set that
798 result from such changes, but an LCUP client MUST NOT assume that
799 such notification will occur. Therefore, in the case where a client
800 is maintaining a cache of entries using LCUP, the data held by the
801 client may be a superset or a subset of the entries that would be
802 returned by a new search request. For example, if access control
803 meta information is changed to deny access to particular entries in
804 the search result set, and the access control information is outside
805 of the search scope (e.g., in a parent entry), the client may have
806 entries stored locally which are no longer part of its desired
807 search set. Similarly, if entries are added to the search result
808 set due to changes in meta-data, the client's cache of entries may
809 not include these entries.
811 Some clients may wish to perform an initial synchronization in order
812 to prime a cache or establish a baseline set of entries, then look
813 for changes after that. The recommended way to do this is to first
814 issue an LCUP search with the updateType field of the clientUpdate
815 control value set to synchronizeOnly, then after that search
816 successfully completes, immediately issue an LCUP search with the
817 updateType field of the clientUpdate control value set to
818 synchronizeAndPersist.
820 Some clients may have unreliable connections, for example, a
821 wireless device or a WAN connection. These clients may want to
822 insure that the cookie is returned often in the entryUpdate control
823 value, so that if they have to reconnect, they do not have to
825 Megginson, et. al. Proposed Standard - Expires: December 2002 14
829 process many redundant entries. These clients should set the
830 sendCookieInterval in the clientUpdate control value to a low
831 number, perhaps even 1. Also, some clients may have a limited
832 bandwidth connection, and may not want to receive the cookie very
833 often, or even at all (however, the cookie is always sent back in
834 the clientUpdateDone control value upon successful completion).
835 These clients should set the sendCookieInterval in the clientUpdate
836 control value to a high number.
838 7. Server Implementation Considerations
840 Servers SHOULD support UUIDs. Otherwise, it will be very difficult
841 to support modifyDN operations. Adding support for UUIDs should be
842 seen as a necessary component of LCUP.
844 By design, the protocol supports multiple cookie schemes. This is
845 to allow different implementations the flexibility of storing any
846 information applicable to their environment. A reasonable
847 implementation for an LDUP compliant server would be to use the
848 Replica Update Vector (RUV). For each master, RUV contains the
849 largest CSN seen from this master. In addition, the RUV implemented
850 by some directory servers (not yet in LDUP) contains replica
851 generation - an opaque string that identifies the replica's data
852 store. The replica generation value changes whenever the replica's
853 data is reloaded. Replica generation is intended to signal the
854 replication/synchronization peers that the replica's data was
855 reloaded and that all other replicas need to be reinitialized. RUV
856 satisfies the three most important properties of the cookie: (1) it
857 uniquely identifies the state of client's data, (2) it can be used
858 to synchronize with multiple servers, and (3) it can be used to
859 detect that the server's data was reloaded.
861 A server may support one or more LCUP cookie schemes. It is
862 expected that schemes will be published along with their OIDs as
863 RFCs. If a client initiates an LCUP session with a particular
864 scheme, the server MUST use that same scheme throughout the LCUP
865 session, or until an LCUP context boundary is crossed, in which case
866 the server will usually require a different cookie anyway.
868 In addition, the cookie must contain enough information to allow the
869 server to determine whether the cookie can be safely used with the
870 search specification it is attached to. As discussed earlier in the
871 document, the cookie can only be used with the search specification
872 that is equally or more restrictive than the one for which the
873 cookie was generated.
875 An implementation must make sure that it can correctly update the
876 client's cookie when there is a size limit imposed on the search
877 results by either the client's request or by the server's
878 configuration. If RUV is used as the cookie, entries last modified
879 by a particular master must be sent to the client in the order of
880 their last modified CSN. This ordering guarantees that the RUV can
881 be updated after each entry is sent.
884 Megginson, et. al. Proposed Standard - Expires: December 2002 15
888 The server's DIT may be partitioned into different sections which
889 may have different cookies associated with them. For example, some
890 servers may use some sort of replication mechanism to support LCUP.
891 If so, the DIT may be partitioned into multiple replicas. A client
892 may send an LCUP search request that spans multiple replicas. Some
893 parts of the DIT spanned by the search request scope may be managed
894 by LCUP and some may not. A part of the DIT which is enabled for
895 LCUP is referred to as an LCUP Context. The server SHOULD send a
896 SearchResultReference [RFC2251, SECTION 4.5.3] when the LCUP Context
897 for a returned entry changes. The server SHOULD return all entries
898 for a particular LCUP Context before returning a reference to other
899 LCUP Contexts or non-LCUP enabled parts of the DIT, in order to
900 minimize the processing burden on the clients. The LDAP URL(s)
901 returned MUST contain the DN(s) of the base of another section of
902 the DIT (however the server implementation has partitioned the DIT).
903 The client will then issue another LCUP search using the LDAP URL
904 returned. Each section of the DIT MAY require a different cookie
905 value, so the client SHOULD maintain a cache, mapping the different
906 LDAP URL values to different cookies. If the cookie changes, the
907 scheme may change as well, but the cookie scheme MUST be the same
908 within a given LCUP Context.
910 An implementation SHOULD notify the client about all entries deleted
911 from the search set since the client's last session, but an LCUP
912 client MUST NOT assume that such notification will occur. For
913 example, the server might not notify the client of the deletion of
914 an object if the object left the search set following the client's
915 last synchronization and prior to the object's deletion. An LDUP
916 compliant implementation can achieve this through the use of entry
917 tombstones. The implementation should avoid aggressive tombstone
918 purging since lack of tombstones would cause client's data to be
919 reloaded. We suggest that only the tombstone content be removed
920 during the regular trimming cycle while tombstones themselves are
921 discarded much less frequently.
923 The specification makes no guarantees about how soon a server should
924 send notification of a changed entry to the client when the
925 connection between the client and the server is kept open. This is
926 intentional as any specific maximum delay would be impossible to
927 meet in a distributed directory service implementation. Server
928 implementors are encouraged to minimize the delay before sending
929 notifications to ensure that clients' needs for timeliness of change
930 notification are met.
932 Implementors of servers that support the mechanism described in this
933 document should ensure that their implementation scales well as the
934 number of active persistent operations and the number of changes
935 made in the directory increases. Server implementors are also
936 encouraged to support a large number of client connections if they
937 need to support large numbers of persistent operations.
939 8. Synchronizing Heterogeneous Data Stores
943 Megginson, et. al. Proposed Standard - Expires: December 2002 16
947 Clients, like a meta directory join engine, synchronizing multiple
948 writable data stores will only work correctly if each piece of
949 information is single mastered (for instance, only by an LDUP
950 compliant directory). This is because different systems have
951 different notions of time and different update resolution
952 procedures. As a result, a change applied on one system can be
953 discarded by the other, thus preventing the data stores from
956 9. Security Considerations
958 In some situations, it may be important to prevent general exposure
959 of information about changes that occur in an LDAP server.
960 Therefore, servers that implement the mechanism described in this
961 document SHOULD provide a means to enforce access control on the
962 entries returned and MAY also provide specific access control
963 mechanisms to control the use of the controls and extended
964 operations defined in this document.
966 As with normal LDAP search requests, a malicious client can initiate
967 a large number of persistent search requests in an attempt to
968 consume all available server resources and deny service to
969 legitimate clients. The protocol provides the means to stop
970 malicious clients by disconnecting them from the server. The servers
971 that implement the mechanism SHOULD provide the means to detect the
972 malicious clients. In addition, the servers SHOULD provide the means
973 to limit the number of resources that can be consumed by a single
976 Access control on the data can be modified in such a way that the
977 data is no longer visible to the client. The specification does not
978 specify how the server should handle this condition. Moreover, data
979 consistency is not guaranteed if access control is changed from a
980 more restrictive to a less restrictive one. This is because access
981 control can be considered as an additional filter on the search
982 specification and the protocol does not support going from a more to
983 a less restrictive search specification. See Client Side
984 Considerations Section for more detailed explanation of the problem.
986 10. Normative References
988 [KEYWORDS] S. Bradner, "Keywords for use in RFCs to Indicate
989 Requirement Levels", RFC 2119, March 1997.
991 [RFC2251] M. Wahl, T. Howes, S. Kille "Lightweight Directory
992 Access Protocol", RFC 2251, December 1997.
994 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
995 Directory Access Protocol (v3): Attribute Syntax
996 Definitions", RFC 2252, December 1997.
998 [CANCEL] K. Zeilenga, "LDAP Cancel Extended Operation",
999 draft-zeilenga-ldap-cancel-xx.txt, a work in progress.
1002 Megginson, et. al. Proposed Standard - Expires: December 2002 17
1006 11. Acknowledgements
1008 The LCUP protocol is based in part on the Persistent Search Change
1009 Notification Mechanism defined by Mark Smith, Gordon Good, Tim
1010 Howes, and Rob Weltman, the LDAPv3 Triggered Search Control defined
1011 by Mark Wahl, and the LDAP Control for Directory Synchronization
1012 defined by Michael Armijo.
1014 12. Author's Addresses
1017 Netscape Communications Corp.
1019 Palo Alto, CA 94303-4900
1020 Mail Stop SCA17 - 201
1021 Phone: +1 505 797-7762
1022 Email: richm@netscape.com
1028 Phone: +1 408 349-6153
1029 Email: olgan@yahoo-inc.com
1032 Netscape Communications Corp.
1034 Palo Alto, CA 94303-4900
1035 Mail Stop SCA17 - 201
1036 Phone: +1 650 937-3477
1037 Email: mcs@netscape.com
1040 Microsoft Corporation
1042 Redmond, WA 98052-6399
1043 Phone: +1 425 882-8080
1044 Email: jeffparh@microsoft.com
1046 13. Full Copyright Statement
1047 "Copyright (C) The Internet Society (date). All Rights Reserved.
1048 This document and translations of it may be copied and furnished to
1049 others, and derivative works that comment on or otherwise explain it
1050 or assist in its implementation may be prepared, copied, published
1051 and distributed, in whole or in part, without restriction of any
1052 kind, provided that the above copyright notice and this paragraph
1053 are included on all such copies and derivative works. However, this
1054 document itself may not be modified in any way, such as by removing
1055 the copyright notice or references to the Internet Society or other
1056 Internet organizations, except as needed for the purpose of
1057 developing Internet standards in which case the procedures for
1058 copyrights defined in the Internet Standards process must be
1059 followed, or as required to translate it into languages other than
1061 Megginson, et. al. Proposed Standard - Expires: December 2002 18
1067 The limited permissions granted above are perpetual and will not be
1068 revoked by the Internet Society or its successors or assigns.
1070 This document and the information contained herein is provided on an
1071 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1072 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1073 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1074 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1075 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1077 14. Appendix A - Summary of Changes
1079 Changes new to version 03:
1081 Emphasized the use of UUIDs throughout the document. Implementers
1082 are strongly encouraged to use UUIDs as a necessary component of
1085 Removed the LCUP Cancel extended operation in favor of the new
1086 LDAP Cancel operation [CANCEL].
1088 Got rid of the lcupSuccess result code. All result codes will be
1089 added to the IANA LDAP result code registry as part of the LDAP
1090 standard. Also removed the result code and text from the client
1091 update done control value.
1093 Changed any and all wording suggesting an LCUP Context is related
1094 to a naming context. New text says an LCUP Context is a part of
1095 the DIT that supports LCUP, and that a server may have one or more
1098 Removed Old Section 4.2: lcupCookieScheme
1099 We decided that LCUP did not need a discovery mechanism. The
1100 controls and extended operations will be published in the root DSE
1101 as per the LDAP standards.
1103 Changed references to "Unique Identifier" to either "Universally
1104 Unique Identifier" or "UUID".
1106 Added this text to section 6 "Client Side Considerations":
1107 "- The client may receive a referral (Referral [RFC2251 SECTION
1108 4.1.11]) when the search base is a subordinate reference, and
1109 this will end the operation."
1111 Added a note to section 6 "Client Side Considerations" about how
1112 to establish a baseline set of entries or entry cache.
1114 Added the field sendCookieInterval to the clientUpdate control
1117 Added a note to section 6 "Client Side Considerations" explaining
1118 possible uses of the sendCookieInterval.
1120 Megginson, et. al. Proposed Standard - Expires: December 2002 19
1125 Changes new to version 02:
1127 Section 4.2: The lcupCookieScheme operational attribute MUST be
1128 present in the root DSE, and MAY be present in entries. Each
1129 value of the attribute in the root DSE will be a list of OIDs of
1130 cookie schemes followed by the DN of the LCUP context which
1131 supports the schemes. The attribute value in the DIT entries will
1132 be the list of OIDs followed by the DN of the LCUP context.
1134 section 4.5 - the entry uuid is now MAY instead of MUST - if
1135 implementers do not wish to identify entries by a unique ID other
1136 than DN (which may not be unique), then so be it. For returned
1137 SearchResultEntry PDUs other than deleted entries, the client MAY
1138 request that the Unique Identifier attribute be returned by
1139 specifying it in the attribute list to be returned by the search
1142 section 4.5 - added "or the base DN of the client's search
1143 request." to the phrase. "The server MAY send the entry at the
1144 root of the client's tree, or the base DN of the client's search
1145 request." I think this clarifies which entry the client may
1148 section 4.6 - the clientUpdateDone control is now optional for
1149 error conditions. Also, the cookie value of the control is now
1150 optional for lcup error conditions (e.g. not lcupSuccess or
1151 lcupClientDisconnect).
1153 Added section 4.12 - Interactions with Other LDAP Search and
1156 Added blurb about alias dereferencing back to section 6:
1157 "For alias dereferencing, the server will behave as if the client
1158 had requested neverDerefAliases or derefFindingBaseObj as the
1159 derefAliases field in the search request [RFC2251, Section 4.5.1].
1160 If the client specifies a value other than neverDerefAliases or
1161 derefFindingBaseObj, the server will return protocolError to the
1164 Changed this in section 6:
1165 Because an LCUP client specifies the area of the tree with which
1166 it wishes to synchronize through the standard LDAP search
1167 specification, the client can be returned noSuchObject error if
1168 the root of the synchronization area was renamed between the
1169 synchronization sessions "or during a synchronization session"
1171 Changes new to version 01:
1173 The opaque cookie has been split into two parts - a scheme which
1174 is an OID, and a value. The value may or may not have a format
1175 known to the client, depending on the specified scheme. Section
1176 4.2 describes the new cookie format and defines the LCUP Cookie
1179 Megginson, et. al. Proposed Standard - Expires: December 2002 20
1184 Added new section 4.3 - the lcupCookieScheme operational
1187 Changes new to version 00:
1189 Added the definition for Unique Identifier (basically copied from
1190 the LDUP model doc http://search.ietf.org/internet-drafts/draft-
1191 ietf-ldup-model-06.txt. I needed to add the definition here
1192 because LCUP needs a Unique Identifier but should not be dependent
1195 Removed all normative references to LDUP. I've left the
1196 implementation suggestions that refer to LDUP, but LCUP should not
1197 be dependent on LDUP.
1199 Cleaned up the protocol flows.
1201 Removed this text from section 4.8: "Clients MUST NOT issue
1202 multiple synchronization requests on the same connection. This is
1203 because the protocol includes an extended operation and it would
1204 be impossible to decide which synchronization session it belongs
1205 to." - This is no longer true, since the extended operation now
1206 includes the message ID of the search request.
1208 "Client Side Consideration" section - the client will never
1209 receive a referral or continuation reference
1211 Added section 12. Acknowledgements
1213 Removed normative references to documents not depended on.
1215 Removed explicit references to software vendors.
1217 Section 4.1 - Changed ClientUpdateControlValue to remove the
1218 keepConnection and changesOnly fields and replace them with
1219 updateType which is an ENUMERATED with three values:
1220 synchronizeOnly, synchronizeAndPersist, and persistOnly.
1222 Section 4.2 - The EntryUpdateControlValue fields stateUpdate and
1223 entryDeleted no longer have DEFAULT values, they must be specified
1224 - this eliminates any potential ambiguity.
1226 Added this text to the description of the entryDeleted field
1227 (section 4.2): "The server SHOULD also set this to TRUE if the
1228 entry has left the clients search result set. As far as the client
1229 is concerned, a deleted entry is no different than an entry which
1230 has left the result set."
1231 Section 4.2 - Added an explanation of the concept and requirement
1232 for the Unique Identifier.
1234 Section 4.4 - Added to the extended operation a request value
1235 containing the message id of the operation to stop.
1238 Megginson, et. al. Proposed Standard - Expires: December 2002 21
1242 Updated contact information for Olga.
1244 Removed Michael Armijo and added Jeff Parham as an author.
1246 Changes new to previous version:
1248 "Authors" section - added Rich Megginson as the new editor.
1250 "Client Side Consideration" section - added a note and a question
1251 concerning referral and continuation reference handling.
1253 "Client Update Control Value" section (4.1) - clarified the meaning
1254 of keepConnection and added a table summarizing the effects of
1255 different values of keepConnection and changesOnly.
1257 "Stop Client Update Request and Response" - added section 4.4
1258 describing this extended operation.
1297 Megginson, et. al. Proposed Standard - Expires: December 2002 22