3 INTERNET-DRAFT Kurt D. Zeilenga
4 Intended Category: Experimental OpenLDAP Foundation
5 Expires in six months Jong Hyuk Choi
13 The LDAP Content Synchronization Operation
14 <draft-zeilenga-ldup-sync-05.txt>
21 This document is an Internet-Draft and is in full conformance with all
22 provisions of Section 10 of RFC2026.
24 Distribution of this memo is unlimited. Technical discussion of this
25 document will take place on the IETF LDUP Working Group mailing list
26 at <ietf-ldup@imc.org>. Please send editorial comments directly to
27 the document editor at <Kurt@OpenLDAP.org>.
29 Internet-Drafts are working documents of the Internet Engineering Task
30 Force (IETF), its areas, and its working groups. Note that other
31 groups may also distribute working documents as Internet-Drafts.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as ``work in progress.''
37 The list of current Internet-Drafts can be accessed at
38 <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
39 Internet-Draft Shadow Directories can be accessed at
40 <http://www.ietf.org/shadow.html>.
42 Copyright (C) The Internet Society (2004). All Rights Reserved.
44 Please see the Full Copyright section near the end of this document
54 Zeilenga LDAP Content Sync Operation [Page 1]
56 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
61 This specification describes the LDAP (Lightweight Directory Access
62 Protocol) Content Synchronization Operation. The operation allows a
63 client to maintain a copy of a fragment of directory information tree.
64 It supports both polling for changes and listening for changes. The
65 operation is defined as an extension of the LDAP Search Operation.
78 2. Elements of the Sync Operation 8
79 2.1. Common ASN.1 Elements 9
80 2.2. Sync Request Control
81 2.3. Sync State Control
82 2.4. Sync Done Control 10
83 2.5. Sync Info Message
84 2.6. Sync Result Codes 11
85 3. Content Synchronization
86 3.1. Synchronization Session
87 3.2. Content Determination 12
88 3.3. refreshOnly Mode 13
89 3.4. refreshAndPersist Mode 16
90 3.5. Search Request Parameters 17
91 3.6. objectName Issues 18
92 3.7. Canceling the Sync Operation 19
94 3.9. Chattiness Considerations 20
95 3.10. Operation Multiplexing 21
96 4. Meta Information Considerations 22
98 4.2. Operational Attributes
99 4.3. Collective Attributes 23
100 4.4. Access and Other Administrative Controls
101 5. Interaction with Other Controls
102 5.1. ManageDsaIT Control 24
103 5.2. Subentries Control
104 6. Shadowing Considerations
105 7. Security Considerations 25
106 8. IANA Considerations
110 Zeilenga LDAP Content Sync Operation [Page 2]
112 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
115 8.1. Object Identifier 26
116 8.2. LDAP Protocol Mechanism
117 8.3. LDAP Result Codes
119 10. Normative References 27
120 11. Informative References 28
121 12. Authors' Addresses 29
122 Appendix A. CSN-based Implementation Considerations
123 Intellectual Property Rights 31
129 The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides a
130 mechanism, the search operation [RFC2251], which allows a client to
131 request directory content matching a complex set of assertions and for
132 the server to return this content, subject to access control and other
133 restrictions, to the client. However, LDAP does not provide (despite
134 the introduction of numerous extensions in this area) an effective and
135 efficient mechanism for maintaining synchronized copies of directory
136 content. This document introduces a new mechanism specifically
137 designed to met the content synchronization requirements of
138 sophisticated directory applications.
140 This document defines the LDAP Content Synchronization Operation, or
141 Sync Operation for short, which allows a client to maintain a
142 synchronized copy of a fragment of a Directory Information Tree (DIT).
143 The Sync Operation is defined as a set of controls and other protocol
144 elements which extend the Search Operation.
149 Over the years, a number of content synchronization approaches have
150 been suggested for use in LDAP directory services. These approaches
151 are inadequate for one or more of the following reasons:
153 - fail to ensure a reasonable level of convergence;
154 - fail to detect that convergence cannot be achieved (without
156 - require pre-arranged synchronization agreements;
157 - require the server to maintain histories of past changes to DIT
158 content and/or meta information;
159 - require the server to maintain synchronization state on a per
166 Zeilenga LDAP Content Sync Operation [Page 3]
168 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
171 The Sync Operation provides eventual convergence of synchronized
172 content when possible and, when not, notification that a full reload
175 The Sync Operation does not require pre-arranged synchronization
178 The Sync Operation does not require servers to maintain nor to use any
179 history of past changes to the DIT or to meta information. However,
180 servers may maintain and use histories (e.g., change logs, tombstones,
181 DIT snapshots) to reduce the number of messages generated and to
182 reduce their size. As it is not always feasible to maintain and use
183 histories, the operation may be implemented using purely (current)
184 state-based approaches. The Sync Operation allows use of either the
185 state-based approach or the history-based approach in an operation by
186 operation basis to balance the size of history and the amount of
187 traffic. The Sync Operation also allows the combined use of the
188 state-based and the history-based approaches.
190 The Sync Operation does not require servers to maintain
191 synchronization state on a per client basis. However, servers may
192 maintain and use per client state information to reduce the number of
193 messages generated and the size of such messages.
195 A synchronization mechanism can be considered overly chatty when
196 synchronization traffic is not reasonably bounded. The Sync Operation
197 traffic is bounded by the size of updated (or new) entries and the
198 number of unchanged entries in the content. The operation is designed
199 to avoid full content exchanges even in the case that the history
200 information available to the server is insufficient to determine the
201 client's state. The operation is also designed to avoid transmission
202 of out-of-content history information, as its size is not bounded by
203 the content and it is not always feasible to transmit such history
204 information due to security reasons.
206 This document includes a number of non-normative appendices providing
207 additional information to server implementors.
212 The Sync Operation is intended to be used in applications requiring
213 eventually-convergent content synchronization. Upon completion of
214 each synchronization stage of the operation, all information to
215 construct a synchronized client copy of the content has been provided
216 to the client or the client has been notified that a complete content
217 reload is necessary. Except for transient inconsistencies due to
218 concurrent operation (or other) processing at the server, the client
222 Zeilenga LDAP Content Sync Operation [Page 4]
224 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
227 copy is an accurate reflection of the content held by the server.
228 Transient inconsistencies will be resolved by subsequent
229 synchronization operations.
231 Possible uses include:
232 - White page service applications may use the Sync Operation to
233 maintain current copy of a DIT fragment. For example, a mail user
234 agent which uses the sync operation to maintain a local copy of an
235 enterprise address book.
237 - Meta-information engines may use the Sync Operation to maintain a
238 copy of a DIT fragment.
240 - Caching proxy services may use the Sync Operation to maintain a
241 coherent content cache.
243 - Lightweight master-slave replication between heterogeneous
244 directory servers. For example, the Sync Operation can be used by
245 a slave server to maintain a shadow copy of a DIT fragment.
246 (Note: The International Telephone Union (ITU) has defined the
247 X.500 Directory [X.500] Information Shadowing Protocol (DISP)
248 [X.525] which may be used for master-slave replication between
249 directory servers. Other experimental LDAP replication protocols
252 This protocol is not intended to be used in applications requiring
253 transactional data consistency.
255 As this protocol transfers all visible values of entries belonging to
256 the content upon change instead of change deltas, this protocol is not
257 appropriate for bandwidth-challenged applications or deployments.
262 This section provides an overview of basic ways the Sync Operation can
263 be used to maintain a synchronized client copy of a DIT fragment.
265 - Polling for Changes: refreshOnly mode
266 - Listening for Changes: refreshAndPersist mode
269 1.3.1. Polling for Changes (refreshOnly)
271 To obtain its initial client copy, the client issues a Sync request: a
272 search request with the Sync Request Control with mode set to
273 refreshOnly. The server, much like it would with a normal search
274 operation, returns (subject to access controls and other restrictions)
278 Zeilenga LDAP Content Sync Operation [Page 5]
280 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
283 the content matching the search criteria (baseObject, scope, filter,
284 attributes). Additionally, with each entry returned, the server
285 provides a Sync State Control indicating state add. This control
286 contains the Universally Unique Identifier (UUID) [UUID] of the entry
287 [EntryUUID]. Unlike the Distinguished Name (DN), which may change
288 over time, an entry's UUID is stable. The initial content is followed
289 by a SearchResultDone with a Sync Done Control. The Sync Done Control
290 provides a syncCookie. The syncCookie represents session state.
292 To poll for updates to the client copy, the client reissues the Sync
293 Operation with the syncCookie previously returned. The server, much
294 as it would with a normal search operation, determines which content
295 would be returned as if the operation was a normal search operation.
296 However, using the syncCookie as an indicator of what content the
297 client was sent previously, the server sends copies of entries which
298 have changed with a Sync State Control indicating state add. For each
299 changed entry, all (modified or unmodified) attributes belonging to
300 the content are sent.
302 The server may perform either or both of the two distinct
303 synchronization phases which are distinguished by how to synchronize
304 entries deleted from the content: the present and the delete phases.
305 When the server uses a single phase for the refresh stage, each phase
306 is marked as ended by a SearchResultDone with a Sync Done Control. A
307 present phase is identified by a FALSE refreshDeletes value in the
308 Sync Done Control. A delete phase is identified by a TRUE
309 refreshDeletes value. The present phase may be followed by a delete
310 phase. The two phases are delimited by a refreshPresent Sync Info
311 Message having a FALSE refreshDone value. In the case that both the
312 phases are used, the present phase is used to bring the client copy up
313 to the state at which the subsequent delete phase can begin.
315 In the present phase, the server sends an empty entry (i.e., no
316 attributes) with a Sync State Control indicating state present for
317 each unchanged entry.
319 The delete phase may be used when the server can reliably determine
320 which entries in the prior client copy are no longer present in the
321 content and the number of such entries is less than or equal to the
322 number of unchanged entries. In the delete mode, the server sends an
323 empty entry with a Sync State Control indicating state delete for each
324 entry which is no longer in the content, instead of returning an empty
325 entry with state present for each present entry.
327 The server may send syncIdSet Sync Info Messages containing the set of
328 UUIDs of either unchanged present entries or deleted entries, instead
329 of sending multiple individual messages. If refreshDeletes of
330 syncIdSet is set to FALSE, the UUIDs of unchanged present entries are
334 Zeilenga LDAP Content Sync Operation [Page 6]
336 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
339 contained in the syncUUIDs set; if refreshDeletes of syncIdSet is set
340 to TRUE, the UUIDs of the entries no longer present in the content are
341 contained in the syncUUIDs set. An optional cookie can be included in
342 the syncIdSet to represent the state of the content after
343 synchronizing the presence or the absence of the entries contained in
346 The synchronized copy of the DIT fragment is constructed by the
349 If refreshDeletes of syncDoneValue is FALSE, the new copy includes all
350 changed entries returned by the reissued Sync Operation as well as all
351 unchanged entries identified as being present by the reissued Sync
352 Operation, but whose content is provided by the previous Sync
353 Operation. The unchanged entries not identified as being present are
354 deleted from the client content. They had been either deleted, moved,
355 or otherwise scoped-out from the content.
357 If refreshDeletes of syncDoneValue is TRUE, the new copy includes all
358 changed entries returned by the reissued Sync Operation as well as all
359 other entries of the previous copy except for those which are
360 identified as having been deleted from the content.
362 The client can, at some later time, re-poll for changes to this
363 synchronized client copy.
366 1.3.2. Listening for Changes (refreshAndPersist)
368 Polling for changes can be expensive in terms of server, client, and
369 network resources. The refreshAndPersist mode allows for active
370 updates of changed entries in the content.
372 By selecting the refreshAndPersist mode, the client requests the
373 server to send updates of entries that are changed after the initial
374 refresh content is determined. Instead of sending a SearchResultDone
375 Message as in polling, the server sends a Sync Info Message to the
376 client indicating that the refresh stage is complete and then enters
377 the persist stage. After receipt of this Sync Info Message, the
378 client will construct a synchronized copy as described in Section
381 The server may then send change notifications as the result of the
382 original Sync search request which now remains persistent in the
383 server. For entries to be added to the returned content, the server
384 sends a SearchResultEntry (with attributes) with a Sync State Control
385 indicating state add. For entries to be deleted from the content, the
386 server sends a SearchResultEntry containing no attributes and a Sync
390 Zeilenga LDAP Content Sync Operation [Page 7]
392 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
395 State Control indicating state delete. For entries to be modified in
396 the return content, the server sends a SearchResultEntry (with
397 attributes) with a Sync State Control indicating state modify. Upon
398 modification of an entry, all (modified or unmodified) attributes
399 belonging to the content are sent.
401 Note that renaming an entry of the DIT may cause an add state change
402 where the entry is renamed into the content, a delete state change
403 where the entry is renamed out of the content, and a modify state
404 change where the entry remains in the content. Also note that a
405 modification of an entry of the DIT may cause an add, delete, or
406 modify state change to the content.
408 Upon receipt of a change notification, the client updates its copy of
411 If the server desires to update the syncCookie during the persist
412 stage, it may include the syncCookie in any Sync State Control or Sync
413 Info Message returned.
415 The operation persists until canceled [CANCEL] by the client or
416 terminated by the server. A Sync Done Control shall be attached to
417 SearchResultDone Message to provide a new syncCookie.
422 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
423 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
424 document are to be interpreted as described in BCP 14 [RFC2119].
426 Protocol elements are described using ASN.1 [X.680] with implicit
427 tags. The term "BER-encoded" means the element is to be encoded using
428 the Basic Encoding Rules [X.690] under the restrictions detailed in
429 Section 5.1 of [RFC2251].
432 2. Elements of the Sync Operation
434 The Sync Operation is defined as an extension to the LDAP Search
435 Operation [RFC2251] where the directory user agent (DUA or client)
436 submits a SearchRequest Message with a Sync Request Control and the
437 directory system agent (DSA or server) responses with zero or more
438 SearchResultEntry Messages, each with a Sync State Control; zero or
439 more SearchResultReference Messages, each with a Sync State Control;
440 zero or more Sync Info Intermediate Response Messages; and a
441 SearchResultDone Message with a Sync Done Control.
446 Zeilenga LDAP Content Sync Operation [Page 8]
448 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
451 To allow clients to discover support for this operation, servers
452 implementing this operation SHOULD publish the
453 1.3.6.1.4.1.4203.1.9.1.1 as a value of 'supportedControl' attribute
454 [RFC2252] of the root DSA-specific entry (DSE). A server MAY choose
455 to advertise this extension only when the client is authorized to use
459 2.1 Common ASN.1 Elements
463 The syncUUID data type is an OCTET STRING holding a 128-bit (16-octet)
464 Universally Unique Identifier (UUID) [UUID].
466 syncUUID ::= OCTET STRING (SIZE(16))
467 -- constrained to UUID
472 The syncCookie is a notational convenience to indicate that, while the
473 syncCookie type is encoded as an OCTET STRING, its value is an opaque
474 value containing information about the synchronization session and its
475 state. Generally, the session information would include a hash of the
476 operation parameters which the server requires not be changed and the
477 synchronization state information would include a commit (log)
478 sequence number, a change sequence number, or a time stamp. For
479 convenience of description, the term no cookie refers either to null
480 cookie or to a cookie with pre-initialized synchronization state.
482 syncCookie ::= OCTET STRING
485 2.2 Sync Request Control
487 The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2]
488 where the controlType is the object identifier
489 1.3.6.1.4.1.4203.1.9.1.1 and the controlValue, an OCTET STRING,
490 contains a BER-encoded syncRequestValue. The criticality field is
491 either TRUE or FALSE.
493 syncRequestValue ::= SEQUENCE {
498 refreshAndPersist (3)
502 Zeilenga LDAP Content Sync Operation [Page 9]
504 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
508 cookie syncCookie OPTIONAL,
509 reloadHint BOOLEAN DEFAULT FALSE
512 The Sync Request Control is only applicable to the SearchRequest
516 2.3 Sync State Control
518 The Sync State Control is an LDAP Control [RFC2251, Section 4.1.2]
519 where the controlType is the object identifier
520 1.3.6.1.4.1.4203.1.9.1.2 and the controlValue, an OCTET STRING,
521 contains a BER-encoded syncStateValue. The criticality is FALSE.
523 syncStateValue ::= SEQUENCE {
531 cookie syncCookie OPTIONAL
534 The Sync State Control is only applicable to SearchResultEntry and
535 SearchResultReference Messages.
538 2.4 Sync Done Control
540 The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2]
541 where the controlType is the object identifier
542 1.3.6.1.4.1.4203.1.9.1.3 and the controlValue contains a BER-encoded
543 syncDoneValue. The criticality is FALSE (and hence absent).
545 syncDoneValue ::= SEQUENCE {
546 cookie syncCookie OPTIONAL,
547 refreshDeletes BOOLEAN DEFAULT FALSE
550 The Sync Done Control is only applicable to SearchResultDone Message.
553 2.5 Sync Info Message
558 Zeilenga LDAP Content Sync Operation [Page 10]
560 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
563 The Sync Info Message is an LDAP Intermediate Response Message
564 [LDAPIRM] where responseName is the object identifier
565 1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded
566 syncInfoValue. The criticality is FALSE (and hence absent).
568 syncInfoValue ::= CHOICE {
569 newcookie [0] syncCookie,
570 refreshDelete [1] SEQUENCE {
571 cookie syncCookie OPTIONAL,
572 refreshDone BOOLEAN DEFAULT TRUE
574 refreshPresent [2] SEQUENCE {
575 cookie syncCookie OPTIONAL,
576 refreshDone BOOLEAN DEFAULT TRUE
578 syncIdSet [3] SEQUENCE {
579 cookie syncCookie OPTIONAL,
580 refreshDeletes BOOLEAN DEFAULT FALSE,
581 syncUUIDs SET OF syncUUID
586 2.6 Sync Result Codes
588 The following LDAP resultCode [RFC2251] is defined:
590 e-syncRefreshRequired (IANA-ASSIGNED-CODE)
593 3. Content Synchronization
595 The Sync Operation is invoked by the client sending a SearchRequest
596 Message with a Sync Request Control.
598 The absence of a cookie or an initialized synchronization state in a
599 cookie indicates a request for initial content while the presence of a
600 cookie representing a state of a client copy indicates a request for
601 content update. Synchronization Sessions are discussed in Section
602 3.1. Content Determination is discussed in Section 3.2.
604 The mode is either refreshOnly or refreshAndPersist. The refreshOnly
605 and refreshAndPersist modes are discussed in Section 3.3 and Section
606 3.4, respectively. The refreshOnly mode consists only of a refresh
607 stage, while the refreshAndPersist mode consists of a refresh stage
608 and a subsequent persist stage.
614 Zeilenga LDAP Content Sync Operation [Page 11]
616 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
619 3.1. Synchronization Session
621 A sequence of Sync Operations where the last cookie returned by the
622 server for one operation is provided by the client in the next
623 operation are said to belong to the same Synchronization Session.
625 The client MUST specify the same content controlling parameters (see
626 Section 3.5) in each Search Request of the session. The client SHOULD
627 also issue each Sync request of a session under the same
628 authentication and authorization associations with equivalent
629 integrity and protections. If the server does not recognize the
630 request cookie or the request is made under different associations or
631 non-equivalent protections, the server SHALL return the initial
632 content as if no cookie had been provided or return an empty content
633 with the e-syncRefreshRequired LDAP result code. The decision between
634 the return of the initial content and the return of the empty content
635 with the e-syncRefreshRequired result code MAY be based on reloadHint
636 in the Sync Request Control from the client. If the server recognizes
637 the request cookie as representing empty or initial synchronization
638 state of the client copy, the server SHALL return the initial content.
640 A Synchronization Session may span multiple LDAP sessions between the
641 client and the server. The client SHOULD issue each Sync request of a
642 session to the same server. (Note: Shadowing considerations are
643 discussed in Section 6.)
646 3.2. Content Determination
648 The content to be provided is determined by parameters of the Search
649 Request, as described in [RFC2251], and possibly other controls. The
650 same content parameters SHOULD be used in each Sync request of a
651 session. If different content is requested and the server is
652 unwilling or unable to process the request, the server SHALL return
653 the initial content as if no cookie had been provided or return an
654 empty content with the e-syncRefreshRequired LDAP result code. The
655 decision between the return of the initial content and the return of
656 the empty content with the e-syncRefreshRequired result code MAY be
657 based on reloadHint in the Sync Request Control from the client.
659 The content may not necessarily include all entries or references
660 which would be returned by a normal search operation nor, for those
661 entries included, not all attributes returned by a normal search.
662 When the server is unwilling or unable to provide synchronization for
663 any attribute for a set of entries, the server MUST treat all filter
664 components matching against these attributes as Undefined and MUST NOT
665 return these attributes in SearchResultEntry responses.
670 Zeilenga LDAP Content Sync Operation [Page 12]
672 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
675 Servers SHOULD support synchronization for all non-collective
676 user-application attributes for all entries.
678 The server may also return continuation references to other servers or
679 to itself. The latter is allowed as the server may partition the
680 entries it holds into separate synchronization contexts.
682 The client may chase all or some of these continuations, each as a
683 separate content synchronization session.
686 3.3. refreshOnly Mode
688 A Sync request with mode refreshOnly and with no cookie is a poll for
689 initial content. A Sync request with mode refreshOnly and with a
690 cookie representing a synchronization state is a poll for content
694 3.3.1. Initial Content Poll
696 Upon receipt of the request, the server provides the initial content
697 using a set of zero or more SearchResultEntry and
698 SearchResultReference Messages followed by a SearchResultDone Message.
700 Each SearchResultEntry Message SHALL include a Sync State Control of
701 state add, entryUUID containing the entry's UUID, and no cookie. Each
702 SearchResultReference Message SHALL include a Sync State Control of
703 state add, entryUUID containing the UUID associated with the reference
704 (normally the UUID of the associated named referral [RFC3296] object),
705 and no cookie. The SearchResultDone Message SHALL include a Sync Done
706 Control having refreshDeletes set to FALSE.
708 A resultCode value of success indicates the operation successfully
709 completed. Otherwise, the result code indicates the nature of
710 failure. The server may return e-syncRefreshRequired result code on
711 the initial content poll if it is safe to do so when it is unable to
712 perform the operation due to various reasons. reloadHint is set to
713 FALSE in the SearchRequest Message requesting the initial content
716 If the operation is successful, a cookie representing the
717 synchronization state of the current client copy SHOULD be returned
718 for use in subsequent Sync Operations.
721 3.3.2. Content Update Poll
726 Zeilenga LDAP Content Sync Operation [Page 13]
728 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
731 Upon receipt of the request the server provides the content refresh
732 using a set of zero or more SearchResultEntry and
733 SearchResultReference Messages followed by a SearchResultDone Message.
735 The server is REQUIRED to either:
736 a) provide the sequence of messages necessary for eventual
737 convergence of the client's copy of the content to the server's
740 b) treat the request as an initial content request (e.g., ignore
741 the cookie or the synchronization state represented in the
744 c) indicate that the incremental convergence is not possible by
745 returning e-syncRefreshRequired,
747 d) return a resultCode other than success or
748 e-syncRefreshRequired.
750 A Sync Operation may consist of a single present phase, a single
751 delete phase, or a present phase followed by a delete phase.
753 In each phase, for each entry or reference which has been added to the
754 content or been changed since the previous Sync Operation indicated by
755 the cookie, the server returns a SearchResultEntry or
756 SearchResultReference Message, respectively, each with a Sync State
757 Control consisting of state add, entryUUID containing the UUID of the
758 entry or reference, and no cookie. Each SearchResultEntry Message
759 represents the current state of a changed entry. Each
760 SearchResultReference Message represents the current state of a
763 In the present phase, for each entry which has not been changed since
764 the previous Sync Operation, an empty SearchResultEntry is returned
765 whose objectName reflects the entry's current DN, the attributes field
766 is empty, and a Sync State Control consisting of state present,
767 entryUUID containing the UUID of the entry, and no cookie. For each
768 reference which has not been changed since the previous Sync
769 Operation, an empty SearchResultReference containing an empty SEQUENCE
770 OF LDAPURL is returned with a Sync State Control consisting of state
771 present, entryUUID containing the UUID of the entry, and no cookie.
772 No messages are sent for entries or references which are no longer in
775 Multiple empty entries with a Sync State Control of state present
776 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
777 value with refreshDeletes set to FALSE. syncUUIDs contain a set of
778 UUIDs of the entries and references unchanged since the last Sync
782 Zeilenga LDAP Content Sync Operation [Page 14]
784 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
787 Operation. syncUUIDs may be empty. The Sync Info Message of
788 syncIdSet may contain cookie to represent the state of the content
789 after performing the synchronization of the entries in the set.
791 In the delete phase, for each entry no longer in the content, the
792 server returns a SearchResultEntry whose objectName reflects a past DN
793 of the entry or is empty, the attributes field is empty, and a Sync
794 State Control consisting of state delete, entryUUID containing the
795 UUID of the deleted entry, and no cookie. For each reference no
796 longer in the content, a SearchResultReference containing an empty
797 SEQUENCE OF LDAPURL is returned with a Sync State Control consisting
798 of state delete, entryUUID containing the UUID of the deleted
799 reference, and no cookie.
801 Multiple empty entries with a Sync State Control of state delete
802 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
803 value with refreshDeletes set to TRUE. syncUUIDs contain a set of
804 UUIDs of the entries and references which has been deleted from the
805 content since the last Sync Operation. syncUUIDs may be empty. The
806 Sync Info Message of syncIdSet may contain cookie to represent the
807 state of the content after performing the synchronization of the
810 When a present phase is followed by a delete phase, the two phases are
811 delimited by a Sync Info Message containing syncInfoValue of
812 refreshPresent, which may contain cookie representing the state after
813 completing the present phase. The refreshPresent contains refreshDone
814 which is always FALSE in the refreshOnly mode of Sync Operation
815 because it is followed by a delete phase.
817 If a Sync Operation consists of a single phase, each phase and hence
818 the Sync Operation are marked ended by a SearchResultDone Message with
819 Sync Done Control which SHOULD contain cookie representing the state
820 of the content after completing the Sync Operation. The Sync Done
821 Control contains refreshDeletes which is set to FALSE for the present
822 phase and set to TRUE for the delete phase.
824 If a Sync Operation consists of a present phase followed by a delete
825 phase, the Sync Operation are marked ended at the end of the delete
826 phase by a SearchResultDone Message with Sync Done Control which
827 SHOULD contain cookie representing the state of the content after
828 completing the Sync Operation. The Sync Done Control contains
829 refreshDeletes which is set to TRUE.
831 The client can specify whether it prefers to receive an initial
832 content by supplying reloadHint of TRUE or to receive a
833 e-syncRefreshRequired resultCode by supplying reloadHint of FALSE
834 (hence absent), in the case that the server determines that it is
838 Zeilenga LDAP Content Sync Operation [Page 15]
840 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
843 impossible or inefficient to achieve the eventual convergence by
844 continuing the current incremental synchronization thread.
846 A resultCode value of success indicates the operation is successfully
847 completed. A resultCode value of e-syncRefreshRequired indicates that
848 a full or partial refresh is needed. Otherwise, the result code
849 indicates the nature of failure. A cookie is provided in the Sync
850 Done Control for use in subsequent Sync Operations for incremental
854 3.4. refreshAndPersist Mode
856 A Sync request with mode refreshAndPersist asks for initial content or
857 content update (during the refresh stage) followed by change
858 notifications (during the persist stage).
863 The content refresh is provided as described in Section 3.3 excepting
864 that the successful completion of content refresh is indicated by
865 sending a Sync Info Message of refreshDelete or refreshPresent with a
866 refreshDone value set to TRUE instead of a SearchResultDone Message
867 with resultCode success. A cookie SHOULD be returned in the Sync Info
868 Message to represent the state of the content after finishing the
869 refresh stage of the Sync Operation.
874 Change notifications are provided during the persist stage.
876 As updates are made to the DIT the server notifies the client of
877 changes to the content. DIT updates may cause entries and references
878 to be added to the content, deleted from the content, or modified
879 within the content. DIT updates may also cause references to be
880 added, deleted, or modified within the content.
882 Where DIT updates cause an entry to be added to the content, the
883 server provides a SearchResultEntry Message which represents the entry
884 as it appears in the content. The message SHALL include a Sync State
885 Control with state of add, entryUUID containing the entry's UUID, and
888 Where DIT updates cause a reference to be added to the content, the
889 server provides a SearchResultReference Message which represents the
890 reference in the content. The message SHALL include a Sync State
894 Zeilenga LDAP Content Sync Operation [Page 16]
896 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
899 Control with state of add, entryUUID containing the UUID associated
900 with the reference, and an optional cookie.
902 Where DIT updates cause an entry to be modified within the content,
903 the server provides a SearchResultEntry Message which represents the
904 entry as it appears in the content. The message SHALL include a Sync
905 State Control with state of modify, entryUUID containing the entry's
906 UUID, and an optional cookie.
908 Where DIT updates cause a reference to be modified within the content,
909 the server provides a SearchResultEntry Message which represents the
910 reference in the content. The message SHALL include a Sync State
911 Control with state of modify, entryUUID containing the UUID associated
912 with the reference, and an optional cookie.
914 Where DIT updates cause an entry to be deleted from the content, the
915 server provides a SearchResultReference Message with an empty SEQUENCE
916 OF LDAPURL. The message SHALL include a Sync State Control with state
917 of delete, entryUUID containing the UUID associated with the
918 reference, and an optional cookie.
920 Where DIT updates cause a reference to be deleted from the content,
921 the server provides a SearchResultEntry Message with no attributes.
922 The message SHALL include a Sync State Control with state of delete,
923 entryUUID containing the entry's UUID, and an optional cookie.
925 Multiple empty entries with a Sync State Control of state delete
926 SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
927 value with refreshDeletes set to TRUE. syncUUIDs contain a set of
928 UUIDs of the entries and references which has been deleted from the
929 content. The Sync Info Message of syncIdSet may contain cookie to
930 represent the state of the content after performing the
931 synchronization of the entries in the set.
933 With each of these messages, the server may provide a new cookie to be
934 used in subsequent Sync Operations. Additionally, the server may also
935 return Sync Info Messages of choice newCookie to provide a new cookie.
936 The client SHOULD use the newest (last) cookie it received from the
937 server in subsequent Sync Operations.
940 3.5. Search Request Parameters
942 As stated in Section 3.1, the client SHOULD specify the same content
943 controlling parameters in each Search Request of the session. All
944 fields of the SearchRequest Message are considered content controlling
945 parameters except for sizeLimit and timeLimit.
950 Zeilenga LDAP Content Sync Operation [Page 17]
952 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
957 As with the normal search operation, the refresh and persist stages
958 are not isolated from DIT changes. It is possible that the entry
959 referred to by the baseObject is deleted, renamed, or moved. It is
960 also possible that alias object used in finding the entry referred to
961 by the baseObject is changed such that the baseObject refers to a
964 If the DIT is updated during processing of the Sync Operation in a
965 manner that causes the baseObject to no longer refer to any entry or
966 in a manner that changes the entry the baseObject refers to, the
967 server SHALL return an appropriate non-success result code such as
968 noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or
969 e-syncRefreshRequired.
974 This operation does not support alias dereferencing during searching.
975 The client SHALL specify neverDerefAliases or derefFindingBaseObj for
976 the SearchRequest derefAliases parameter. The server SHALL treat
977 other values (e.g., derefInSearching, derefAlways) as protocol errors.
982 The sizeLimit applies only to entries (regardless of their state in
983 Sync State Control) returned during the refreshOnly operation or the
984 refresh stage of the refreshAndPersist operation.
989 For a refreshOnly Sync Operation, the timeLimit applies to the whole
990 operation. For a refreshAndPersist operation, the timeLimit applies
991 only to the refresh stage including the generation of the Sync Info
992 Message with a refreshDone value of TRUE.
997 The client SHOULD avoid filter assertions which apply to the values of
998 the attributes likely to be considered by the server as ones holding
999 meta-information. See Section 4.
1006 Zeilenga LDAP Content Sync Operation [Page 18]
1008 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1011 The Sync Operation uses entryUUID values provided in the Sync State
1012 Control as the primary keys to entries. The client MUST use these
1013 entryUUIDs to correlate synchronization messages.
1015 In some circumstances the DN returned may not reflect the entry's
1016 current DN. In particular, when the entry is being deleted from the
1017 content, the server may provide an empty DN if the server does not
1018 wish to disclose the entry's current DN (or, if deleted from the DIT,
1019 the entry's last DN).
1021 It should also be noted that the entry's DN may be viewed as meta
1022 information (see Section 4.1).
1025 3.7. Canceling the Sync Operation
1027 Servers MUST implement the LDAP Cancel [CANCEL] Operation and support
1028 cancellation of outstanding Sync Operations as described here.
1030 To cancel an outstanding Sync Operation, the client issues an LDAP
1031 Cancel [CANCEL] Operation.
1033 If at any time the server becomes unwilling or unable to continue
1034 processing a Sync Operation, the server SHALL return a
1035 SearchResultDone with a non-success resultCode indicating the reason
1036 for the termination of the operation.
1038 Whether the client or the server initiated the termination, the server
1039 may provide a cookie in the Sync Done Control for use in subsequent
1043 3.8. Refresh Required
1045 In order to achieve the eventually-convergent synchronization, the
1046 server may terminate the Sync Operation in the refresh or the persist
1047 stage by returning a e-syncRefreshRequired resultCode to the client.
1048 If no cookie is provided, a full refresh is needed. If a cookie
1049 representing a synchronization state is provided in this response, an
1050 incremental refresh is needed.
1052 To obtain a full refresh, the client then issues a new synchronization
1053 request with no cookie. To obtain an incremental reload, the client
1054 issues a new synchronization with the provided cookie.
1056 The server may choose to provide a full copy in the refresh stage
1057 (e.g., ignore the cookie or the synchronization state represented in
1058 the cookie) instead of providing an incremental refresh in order to
1062 Zeilenga LDAP Content Sync Operation [Page 19]
1064 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1067 achieve the eventual convergence.
1069 The decision between the return of the initial content and the return
1070 of the e-syncRefreshRequired result code may be based on reloadHint in
1071 the Sync Request Control from the client.
1073 In the case of persist stage Sync, the server returns the resultCode
1074 of e-syncRefreshRequired to the client to indicate that the client
1075 needs to issue a new Sync Operation in order to obtain a synchronized
1076 copy of the content. If no cookie is provided, a full refresh is
1077 needed. If a cookie representing a synchronization state is provided,
1078 an incremental refresh is needed.
1080 The server may also return e-syncRefreshRequired if it determines that
1081 a refresh would be more efficient than sending all the messages
1082 required for convergence.
1084 It is noted that the client may receive one or more of
1085 SearchResultEntry, SearchResultReference, and/or Sync Info Messages
1086 before it receives SearchResultDone Message with the
1087 e-syncRefreshRequired result code.
1090 3.9. Chattiness Considerations
1092 The server MUST ensure that the number of entry messages generated to
1093 refresh the client content does not exceed the number of entries
1094 presently in the content. While there is no requirement for servers
1095 to maintain history information, if the server has sufficient history
1096 to allow it to reliably determine which entries in the prior client
1097 copy are no longer present in the content and the number of such
1098 entries is less than or equal to the number of unchanged entries, the
1099 server SHOULD generate delete entry messages instead of present entry
1100 messages (see Section 3.3.2).
1102 When the amount of history information maintained in the server is not
1103 enough for the clients to perform infrequent refreshOnly Sync
1104 Operations, it is likely that the server has incomplete history
1105 information (e.g. due to truncation) by the time those clients connect
1108 The server SHOULD NOT resort to full reload when the history
1109 information is not enough to generate delete entry messages. The
1110 server SHOULD generate either present entry messages only or present
1111 entry messages followed by delete entry messages to bring the client
1112 copy to the current state. In the latter case, the present entry
1113 messages bring the client copy to a state covered by the history
1114 information maintained in the server.
1118 Zeilenga LDAP Content Sync Operation [Page 20]
1120 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1123 The server SHOULD maintain enough (current or historical) state
1124 information (such as a context-wide last modify time stamp) to
1125 determine if no changes were made in the context since the content
1126 refresh was provided and, and when no changes were made, generate zero
1127 delete entry messages instead of present messages.
1129 The server SHOULD NOT use the history information when its use does
1130 not reduce the synchronization traffic or when its use can expose
1131 sensitive information not allowed to be received by the client.
1133 The server implementor should also consider chattiness issues which
1134 span multiple Sync Operations of a session. As noted in Section 3.8,
1135 the server may return e-syncRefreshRequired if it determines that a
1136 reload would be more efficient than continuing under the current
1137 operation. If reloadHint in the Sync Request is TRUE, the server may
1138 initiate a reload without directing the client to request a reload.
1140 The server SHOULD transfer a new cookie frequently to avoid having to
1141 transfer information already provided to the client. Even where DIT
1142 changes do not cause content synchronization changes to be
1143 transferred, it may be advantageous to provide a new cookie using a
1144 Sync Info Message. However, the server SHOULD avoid overloading the
1145 client or network with Sync Info Messages.
1147 During persist mode, the server SHOULD coalesce multiple outstanding
1148 messages updating the same entry. The server MAY delay generation of
1149 an entry update in anticipation of subsequent changes to that entry
1150 which could be coalesced. The length of the delay should be long
1151 enough to allow coalescing of update requests issued back to back but
1152 short enough that the transient inconsistency induced by the delay is
1153 corrected in a timely manner.
1155 The server SHOULD use syncIdSet Sync Info Message when there are
1156 multiple delete or present messages to reduce the amount of
1157 synchronization traffic.
1159 It is also noted that there may be many clients interested in a
1160 particular directory change, and servers attempting to service all of
1161 these at once may cause congestion on the network. The congestion
1162 issues are magnified when the change requires a large transfer to each
1163 interested client. Implementors and deployers of servers should take
1164 steps to prevent and manage network congestion.
1167 3.10. Operation Multiplexing
1169 The LDAP protocol model [RFC2251] allows operations to be multiplexed
1170 over a single LDAP session. Clients SHOULD NOT maintain multiple LDAP
1174 Zeilenga LDAP Content Sync Operation [Page 21]
1176 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1179 sessions with the same server. Servers SHOULD ensure that responses
1180 from concurrently processed operations are interleaved fairly.
1182 Clients SHOULD combine Sync Operations whose result set is largely
1183 overlapping. This avoids having to return multiple messages, once for
1184 each overlapping session, for changes to entries in the overlap.
1186 Clients SHOULD NOT combine Sync Operations whose result sets are
1187 largely non-overlapping with each other. This ensures that an event
1188 requiring a e-syncRefreshRequired response can be limited to as few
1189 result sets as possible.
1192 4. Meta Information Considerations
1196 As an entry's DN is constructed from its relative DN (RDN) and the
1197 entry's parent's DN, it is often viewed as meta information.
1199 While renaming or moving to a new superior causes the entry's DN to
1200 change, that change SHOULD NOT, by itself, cause synchronization
1201 messages to be sent for that entry. However, if the renaming or the
1202 moving could cause the entry to be added or deleted from the content,
1203 appropriate synchronization messages should be generated to indicate
1206 When a server treats the entry's DN as meta information, the server
1209 - evaluate all MatchingRuleAssertions [RFC2251] to TRUE if
1210 matching a value of an attribute of the entry and otherwise
1212 - evaluate all MatchingRuleAssertion with dnAttributes of TRUE as
1215 The latter choice is offered for ease of server implementation.
1218 4.2. Operational Attributes
1220 Where values of an operational attribute is determined by values not
1221 held as part of the entry it appears in, the operational attribute
1222 SHOULD NOT support synchronization of that operational attribute.
1224 For example, in servers which implement X.501 subschema model [X.501],
1225 servers should not support synchronization of the subschemaSubentry
1226 attribute as its value is determined by values held and administrated
1230 Zeilenga LDAP Content Sync Operation [Page 22]
1232 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1235 in subschema subentries.
1237 As a counter example, servers which implement aliases [RFC2256][X.501]
1238 can support synchronization of the aliasedObjectName attribute as its
1239 values are held and administrated as part of the alias entries.
1241 Servers SHOULD support synchronization of the following operational
1242 attributes: createTimestamp, modifyTimestamp, creatorsName,
1243 modifiersName [RFC2252]. Servers MAY support synchronization of other
1244 operational attributes.
1247 4.3. Collective Attributes
1249 A collective attribute is "a user attribute whose values are the same
1250 for each member of an entry collection" [X.501]. Use of collective
1251 attributes in LDAP is discussed in [RFC3371].
1253 Modification of a collective attribute generally affects the content
1254 of multiple entries, which are the members of the collection. It is
1255 inefficient to include values of collective attributes visible in
1256 entries of the collection, as a single modification of a collective
1257 attribute requires transmission of multiple SearchResultEntry (one for
1258 each entry of the collection which the modification affected) to be
1261 Servers SHOULD NOT synchronize collective attributes appearing in
1262 entries of any collection. Servers MAY support synchronization of
1263 collective attributes appearing in collective attribute subentries.
1266 4.4. Access and Other Administrative Controls
1268 Entries are commonly subject to access and other administrative
1269 Controls. While portions of the policy information governing a
1270 particular entry may be held in the entry, policy information is often
1271 held elsewhere (in superior entries, in subentries, in the root DSE,
1272 in configuration files etc.). Because of this, changes to policy
1273 information make it difficult to ensure eventual convergence during
1274 incremental synchronization.
1276 Where it is impractical or infeasible to generate content changes
1277 resulting from a change to policy information, servers may opt to
1278 return e-syncRefreshRequired or treat the Sync Operation as an initial
1279 content request (e.g., ignore the cookie or the synchronization state
1280 represented in the cookie).
1286 Zeilenga LDAP Content Sync Operation [Page 23]
1288 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1291 5. Interaction with Other Controls
1293 The Sync Operation may be used with:
1295 - ManageDsaIT Control [RFC3296]
1296 - Subentries Control [RFC3672]
1298 as described below. The Sync Operation may be used with other LDAP
1299 extensions as detailed in other documents.
1302 5.1. ManageDsaIT Control
1304 The ManageDsaIT Control [RFC3296] indicates that the operation acts
1305 upon the DSA Information Tree and causes referral and other special
1306 entries to be treated as object entries with respect to the operation.
1309 5.2. Subentries Control
1311 The Subentries Control is used with the search operation "to control
1312 the visibility of entries and subentries which are within scope"
1313 [RFC3672]. When used with the Sync Operation, the subentries control
1314 and other factors (search scope, filter, etc.) are used to determine
1315 whether an entry or subentry appear in the content or not.
1318 6. Shadowing Considerations
1320 As noted in [RFC2251], some servers may hold shadow copies of entries
1321 which can be used to answer search and comparison queries. Such
1322 servers may also support content synchronization requests. This
1323 section discusses considerations for implementors and deployers for
1324 the implementation and deployment of the Sync operation in shadowed
1327 While a client may know of multiple servers which are equally capable
1328 of being used to obtain particular directory content from, a client
1329 SHOULD NOT assume that each of these server is equally capable of
1330 continuing a content synchronization session. As stated in Section
1331 3.1, the client SHOULD issue each Sync request of a Sync session to
1334 However, through domain naming or IP address redirection or other
1335 techniques, multiple physical servers can be made to appear as one
1336 logical server to a client. Only servers which are equally capable in
1337 regards to their support for the Sync operation and which hold equally
1338 complete copies of the entries should be made to appear as one logical
1342 Zeilenga LDAP Content Sync Operation [Page 24]
1344 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1347 server. In particular, each physical server acting as one logical
1348 server SHOULD be equally capable of continuing a content
1349 synchronization based upon cookies provided by any of the other
1350 physical servers without requiring a full reload. Because there is no
1351 standard LDAP shadowing mechanism, the specification of how to
1352 independently implement equally capable servers (as well as the
1353 precise definition of "equally capable") is left to future documents.
1355 It is noted that it may be difficult for the server to reliably
1356 determine what content was provided to the client by another server,
1357 especially in the shadowing environments which allow shadowing events
1358 to be coalesced. Where so, the use of the delete phase discussed in
1359 Section 3.3.2 may not be applicable.
1362 7. Security Considerations
1364 In order to maintain a synchronized copy of the content, a client is
1365 to delete information from its copy of the content as described above.
1366 However, the client may maintain knowledge of information disclosed to
1367 it by the server separate from its copy of the content used for
1368 synchronization. Management of this knowledge is beyond the scope of
1369 this document. Servers should be careful not to disclose information
1370 for content which the client is not authorized to have knowledge of
1373 While the information provided by a series of refreshOnly Sync
1374 Operations is similar to that provided by a series of Search
1375 Operations, persist stage may disclose additional information. A
1376 client may be able to discern information about the particular
1377 sequence of update operations which caused content change.
1379 Implementors should take precautions against malicious cookie content,
1380 including malformed cookies or valid cookies used with different
1381 security associations and/or protections in attempt to obtain
1382 unauthorized access to information. Servers may include a digital
1383 signature in the cookie to detect tampering.
1385 The operation may be the target of direct denial of service attacks.
1386 Implementors should provide safeguards to ensure the operation is not
1387 abused. Servers may place access control or other restrictions upon
1388 the use of this operation.
1390 It is noted that even small updates to the directory may cause
1391 significant amount of traffic to be generated to clients using this
1392 operation. A user could abuse its update privileges to mount an
1393 indirect denial of service to these clients, other clients, and/or
1394 portions of the network. Servers should provide safeguards to ensure
1398 Zeilenga LDAP Content Sync Operation [Page 25]
1400 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1403 update operations are not abused.
1405 Implementors of this (or any) LDAP extension should be familiar with
1406 general LDAP security considerations [RFC3377].
1409 8. IANA Considerations
1411 Registration of the following values is requested.
1413 The OID arc 1.3.6.1.4.1.4203.1.9.1 was assigned [ASSIGN] by OpenLDAP
1414 Foundation, under its IANA-assigned private enterprise allocation
1415 [PRIVATE], for use in this specification.
1418 8.2. LDAP Protocol Mechanism
1420 It is requested that IANA register the LDAP Protocol Mechanism
1421 described in this document.
1423 Subject: Request for LDAP Protocol Mechanism Registration
1424 Object Identifier: 1.3.6.1.4.1.4203.1.9.1.1
1425 Description: LDAP Content Synchronization Control
1426 Person & email address to contact for further information:
1427 Kurt Zeilenga <kurt@openldap.org>
1429 Specification: RFC XXXX
1430 Author/Change Controller: IESG
1434 8.3. LDAP Result Codes
1436 It is requested that IANA register the LDAP Result Code described in
1439 Subject: LDAP Result Code Registration
1440 Person & email address to contact for further information:
1441 Kurt Zeilenga <kurt@OpenLDAP.org>
1442 Result Code Name: e-syncRefreshRequired (IANA-ASSIGNED-CODE)
1443 Specification: RFC XXXX
1444 Author/Change Controller: IESG
1450 This document borrows significantly from the LDAP Client Update
1454 Zeilenga LDAP Content Sync Operation [Page 26]
1456 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1459 Protocol [LCUP], a product of the IETF LDUP working group. This
1460 document also benefited from Persistent Search [PSEARCH], Triggered
1461 Search [TSEARCH], and Directory Synchronization [DIRSYNC] works. This
1462 document also borrows from "Lightweight Directory Access Protocol
1466 10. Normative References
1468 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
1469 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
1471 [RFC2251] Wahl, M., T. Howes and S. Kille, "Lightweight Directory
1472 Access Protocol (v3)", RFC 2251, December 1997.
1474 [RFC2252] Wahl, M., A. Coulbeck, T. Howes, and S. Kille,
1475 "Lightweight Directory Access Protocol (v3): Attribute
1476 Syntax Definitions", RFC 2252, December 1997.
1478 [RFC3296] Zeilenga, K., "Named Subordinate References in
1479 Lightweight Directory Access Protocol (LDAP)
1480 Directories", RFC 3296, July 2002.
1482 [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
1483 Protocol (v3): Technical Specification", RFC 3377,
1486 [RFC3671] Zeilenga, K., "Collective Attributes in LDAP", RFC 3671,
1489 [RFC3672] Zeilenga, K. and S. Legg, "Subentries in LDAP", RFC
1490 3672, December 2003.
1492 [CANCEL] Zeilenga, K., "LDAP Cancel Extended Operation",
1493 draft-zeilenga-ldap-cancel-xx.txt, a work in progress.
1494 [EntryUUID] Zeilenga, K., "The LDAP EntryUUID Operational
1495 Attribute", draft-zeilenga-ldap-uuid-xx.txt, a work in
1498 [LDAPIRM] Harrison, R. and Zeilenga, K., "LDAP Intermediate
1500 draft-rharrison-ldap-intermediate-resp-00.txt, a work in
1503 [UUID] International Organization for Standardization (ISO),
1504 "Information technology - Open Systems Interconnection -
1505 Remote Procedure Call", ISO/IEC 11578:1996
1510 Zeilenga LDAP Content Sync Operation [Page 27]
1512 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1515 [X.680] International Telecommunication Union -
1516 Telecommunication Standardization Sector, "Abstract
1517 Syntax Notation One (ASN.1) - Specification of Basic
1518 Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
1520 [X.690] International Telecommunication Union -
1521 Telecommunication Standardization Sector, "Specification
1522 of ASN.1 encoding rules: Basic Encoding Rules (BER),
1523 Canonical Encoding Rules (CER), and Distinguished
1524 Encoding Rules (DER)", X.690(1997) (also ISO/IEC
1528 11. Informative References
1530 [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for
1531 use with LDAPv3", RFC 2256, December 1997.
1533 [RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64
1534 (also RFC 3383), September 2002.
1536 [PRIVATE] IANA, "Private Enterprise Numbers",
1537 http://www.iana.org/assignments/enterprise-numbers.
1539 [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
1540 http://www.openldap.org/foundation/oid-delegate.txt.
1542 [X.500] International Telecommunication Union -
1543 Telecommunication Standardization Sector, "The Directory
1544 -- Overview of concepts, models and services,"
1545 X.500(1993) (also ISO/IEC 9594-1:1994).
1547 [X.511] International Telecommunication Union -
1548 Telecommunication Standardization Sector, "The
1549 Directory: Abstract Service Definition", X.511(1993).
1551 [X.525] International Telecommunication Union -
1552 Telecommunication Standardization Sector, "The
1553 Directory: Replication", X.525(1993).
1555 [UUIDinfo] The Open Group, "Universally Unique Identifier" appendix
1556 of the CAE Specification "DCE 1.1: Remote Procedure
1557 Calls", Document Number C706,
1558 <http://www.opengroup.org/products/publications/
1559 catalog/c706.htm> (appendix available at:
1560 <http://www.opengroup.org/onlinepubs/9629399/
1561 apdxa.htm>), August 1997.
1566 Zeilenga LDAP Content Sync Operation [Page 28]
1568 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1571 [DIRSYNC] Armijo, M., "Microsoft LDAP Control for Directory
1572 Synchronization", draft-armijo-ldap-dirsync-xx.txt, a
1575 [LCUP] Megginson, R., et. al., "LDAP Client Update Protocol",
1576 draft-ietf-ldup-lcup-xx.txt, a work in progress.
1578 [PSEARCH] Smith, M., et. al., "Persistent Search: A Simple LDAP
1579 Change Notification Mechanism",
1580 draft-ietf-ldapext-psearch-xx.txt, a work in progress.
1582 [TSEARCH] Wahl, M., "LDAPv3 Triggered Search Control",
1583 draft-ietf-ldapext-trigger-xx.txt, a work in progress.
1586 12. Authors' Addresses
1594 <jongchoi@us.ibm.com>
1598 Appendix A. CSN-based Implementation Considerations
1600 This appendix is provided for informational purposes only, it is not a
1601 normative part of the LDAP Content Synchronization Operation's
1602 technical specification.
1604 This appendix discusses LDAP Content Synchronization Operation server
1605 implementation considerations associated with a Change Sequence Number
1608 Change Sequence Number based approaches are targeted for use in
1609 servers which do not maintain history information (e.g., change logs,
1610 state snapshots, etc.) about changes made to the Directory and hence,
1611 must rely on current directory state and minimal synchronization state
1612 information embedded in Sync Cookie. Servers which maintain history
1613 information should consider other approaches which exploit the history
1616 A Change Sequence Number is effectively a time stamp which has
1617 sufficient granularity to ensure that the precedence relationship in
1618 time of two updates to the same object can be determined. Change
1622 Zeilenga LDAP Content Sync Operation [Page 29]
1624 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1627 Sequence Numbers are not to be confused with Commit Sequence Numbers
1628 or Commit Log Record Numbers. A Commit Sequence Number allows one to
1629 determine how two commits (to the same object or different objects)
1630 relate to each other in time. Change Sequence Number associated with
1631 different entries may be committed out of order. In the remainder of
1632 this Appendix, the term CSN refers to a Change Sequence Number.
1634 In these approaches, the server not only maintains a CSN for each
1635 directory entry (the entry CSN), but also maintains a value which we
1636 will call the context CSN. The context CSN is the greatest committed
1637 entry CSN which is not greater than any outstanding (uncommitted)
1638 entry CSNs for all entries in a directory context. The values of
1639 context CSN are used in syncCookie values as synchronization state
1642 As search operations are not isolated from individual directory update
1643 operations and individual update operations cannot be assumed to be
1644 serialized, one cannot assume that the returned content incorporates
1645 all relevant changes whose change sequence number is less than or
1646 equal to the greatest entry CSN in the content. The content
1647 incorporates all the relevant changes whose change sequence number is
1648 less than or equal to context CSN before search processing. The
1649 content may also incorporate any subset of the changes whose change
1650 sequence number is greater than context CSN before search processing
1651 but less than or equal to the context CSN after search processing.
1652 The content does not incorporate any of the changes whose CSN is
1653 greater than the context CSN after search processing.
1655 A simple server implementation could use value of the context CSN
1656 before search processing to indicate state. Such an implementation
1657 would embed this value into each SyncCookie returned. We'll call this
1658 the cookie CSN. When a refresh was requested, the server would simply
1659 generate "update" messages for all entries in the content whose CSN is
1660 greater than the supplied cookie CSN and generate "present" messages
1661 for all other entries in the content. However, if the current context
1662 CSN is the same as the cookie CSN, the server should instead generate
1663 zero "updates" and zero "delete" messages, and indicate refreshDeletes
1664 of TRUE as the directory has not changed.
1666 The implementation should also consider the impact of changes to meta
1667 information, such as access controls, which affects content
1668 determination. One approach is for the server to maintain a context
1669 wide meta information CSN or meta CSN. This meta CSN would be updated
1670 whenever meta information affecting content determination was changed.
1671 If the value of the meta CSN is greater than cookie CSN, the server
1672 should ignore the cookie and treat the request as an initial request
1678 Zeilenga LDAP Content Sync Operation [Page 30]
1680 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1683 Additionally, servers may want to consider maintaining some
1684 per-session history information to reduce the number of messages
1685 needed to be transferred during incremental refreshes. Specifically,
1686 a server could record information about entries as they leave the
1687 scope of a disconnected sync session and later use this information to
1688 generate delete messages instead of present messages.
1690 When the history information is truncated, the CSN of the latest
1691 truncated history information entry may be recorded as the truncated
1692 CSN of the history information. The truncated CSN may be used to
1693 determine whether a client copy can be covered by the history
1694 information by comparing it to the synchronization state contained in
1695 the cookie supplied by the client.
1697 When there are a large number of sessions, it may make sense to
1698 maintain such history only for the selected clients. Also, servers
1699 taking this approach need to consider resource consumption issues to
1700 ensure reasonable server operation and to protect against abuse. It
1701 may be appropriate to restrict this mode of operation by policy.
1706 Intellectual Property Rights
1708 The IETF takes no position regarding the validity or scope of any
1709 intellectual property or other rights that might be claimed to pertain
1710 to the implementation or use of the technology described in this
1711 document or the extent to which any license under such rights might or
1712 might not be available; neither does it represent that it has made any
1713 effort to identify any such rights. Information on the IETF's
1714 procedures with respect to rights in standards-track and
1715 standards-related documentation can be found in BCP-11. Copies of
1716 claims of rights made available for publication and any assurances of
1717 licenses to be made available, or the result of an attempt made to
1718 obtain a general license or permission for the use of such proprietary
1719 rights by implementors or users of this specification can be obtained
1720 from the IETF Secretariat.
1722 The IETF invites any interested party to bring to its attention any
1723 copyrights, patents or patent applications, or other proprietary
1724 rights which may cover technology that may be required to practice
1725 this standard. Please address the information to the IETF Executive
1734 Zeilenga LDAP Content Sync Operation [Page 31]
1736 INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
1739 Copyright (C) The Internet Society (2004). All Rights Reserved.
1741 This document and translations of it may be copied and furnished to
1742 others, and derivative works that comment on or otherwise explain it
1743 or assist in its implementation may be prepared, copied, published and
1744 distributed, in whole or in part, without restriction of any kind,
1745 provided that the above copyright notice and this paragraph are
1746 included on all such copies and derivative works. However, this
1747 document itself may not be modified in any way, such as by removing
1748 the copyright notice or references to the Internet Society or other
1749 Internet organizations, except as needed for the purpose of
1750 developing Internet standards in which case the procedures for
1751 copyrights defined in the Internet Standards process must be followed,
1752 or as required to translate it into languages other than English.
1790 Zeilenga LDAP Content Sync Operation [Page 32]