7 INTERNET-DRAFT Kurt D. Zeilenga
8 Intended Category: Standard Track OpenLDAP Foundation
9 Expires in six months Jonghyuk Choi
17 LDAP Content Synchronization Operation
18 <draft-zeilenga-ldup-sync-02.txt>
23 1. Status of this Memo
25 This document is an Internet-Draft and is in full conformance with all
26 provisions of Section 10 of RFC2026.
28 Distribution of this memo is unlimited. Technical discussion of this
29 document will take place on the IETF LDUP Working Group mailing list
30 at <ietf-ldup@imc.org>. Please send editorial comments directly to
31 the document editor at <Kurt@OpenLDAP.org>.
33 Internet-Drafts are working documents of the Internet Engineering Task
34 Force (IETF), its areas, and its working groups. Note that other
35 groups may also distribute working documents as Internet-Drafts.
36 Internet-Drafts are draft documents valid for a maximum of six months
37 and may be updated, replaced, or obsoleted by other documents at any
38 time. It is inappropriate to use Internet-Drafts as reference
39 material or to cite them other than as ``work in progress.''
41 The list of current Internet-Drafts can be accessed at
42 <http://www.ietf.org/ietf/1id-abstracts.txt>. The list of
43 Internet-Draft Shadow Directories can be accessed at
44 <http://www.ietf.org/shadow.html>.
46 Copyright 2003, The Internet Society. All Rights Reserved.
48 Please see the Copyright section near the end of this document for
58 Zeilenga LDAP Content Sync Operation [Page 1]
60 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
65 This specification describes the LDAP (Lightweight Directory Access
66 Protocol) Content Synchronization operation. The operation allows a
67 client to maintain a shadow copy of a fragment of directory
68 information tree. It supports both polling for changes and listening
69 for changes. The operation is defined as an extension of the LDAP
75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
77 document are to be interpreted as described in BCP 14 [RFC2119].
79 Protocol elements are described using ASN.1 [X.680]. The term
80 "BER-encoded" means the element is to be encoded using the Basic
81 Encoding Rules [X.690] under the restrictions detailed in Section 5.1
87 The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides a
88 mechanism, the search operation [RFC2251], to allow a client to
89 request the return of content matching a complex set of assertions and
90 for the server to return this content, subject to access control and
91 other restrictions, to the client. However, short of repeating a
92 search operation each time a new copy needed, LDAP does not provide an
93 effective and efficient mechanism for maintaining synchronized copies
96 This document defines the LDAP Content Synchronization operation, or
97 Sync operation for short, which allows a client to maintain a
98 synchronized shadow copy of a fragment of a Directory Information Tree
99 (DIT). The Sync operation is defined as a set of controls and other
100 protocol elements which extend the Search operation.
105 Over the years, a number of directory synchronization approaches have
106 been suggested. These approaches are inadequate for one or more of
107 the following reasons:
109 1) do not ensure a reasonable level of convergence;
110 2) fail to detect that convergence cannot be achieved (without
114 Zeilenga LDAP Content Sync Operation [Page 2]
116 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
120 3) require pre-arranged synchronization agreements;
121 4) require the server to maintain synchronization state on a per
123 5) require the server to maintain histories of past changes to DIT
124 content and/or meta information; and/or
125 6) are overly chatty.
127 The Sync operation provides eventual convergence of synchronized
128 content when possible and, when not, notification that content reload
131 The Sync operation does not require pre-arranged synchronization
134 The Sync operation does not require servers to maintain
135 synchronization state on a per user basis.
137 The Sync operation does not require servers to maintain any history of
138 past changes to the DIT or to meta information. While histories
139 (e.g., change logs, tombstones, DIT snapshots) may be used in the
140 implementation of the Sync operation, the operation may be implemented
141 using purely state-based approaches.
143 As the Sync operation does not require servers to maintain any
144 histories of past changes, it can be implemented in environments where
145 it is not feasible to maintain such histories. Histories, if
146 available, may be used by the server to reduce the number of messages
147 generated and reduce their size.
149 The Sync operation chattiness is reasonably bound.
154 The Sync operation is intended to be used in applications requiring
155 eventual-convergent content synchronization. Upon completion of each
156 synchronization phase of the operation, all information to construct
157 an synchronized shadow copy of the content has been provided to the
158 client or the client has been notified that a complete content reload
159 is necessary. Excepting for transient inconsistencies due to
160 concurrent operation (or other) processing at the server, the shadow
161 copy is an accurate reflection of the content held by the server.
162 Each inconsistency is transient in that it will be corrected during
163 subsequent synchronization requests.
165 Possible uses include:
166 - White page service applications may use the Sync operation to
170 Zeilenga LDAP Content Sync Operation [Page 3]
172 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
175 maintain current shadow copy of a DIT fragment. For example, an
176 mail user agent which use the sync operation to maintain a local
177 copy of an enterprise address book.
179 - Meta-information engines may use the Sync operation to maintain a
180 shadow copy of a DIT fragment.
182 - Caching proxy services may use the Sync operation to maintain a
183 coherent content cache.
185 - Lightweight master-slave replication between heterogeneous
186 directory servers. For example, the Sync operation can be used by
187 a slave server to maintain a shadow copy of a DIT fragment.
189 Note: The International Telephone Union (ITU) has defined the X.500
190 Directory Synchronization Protocol [X.525] which may be used for
191 master-slave replication between LDAP servers. Other
192 experimental LDAP replication protocols exist. The Sync
193 operation should be viewed as complementary to these replication
196 This protocol is not intended to be used in applications requiring
197 transactional data consistency.
199 As this protocol transfers all visible values of entries upon change
200 instead of change deltas, this protocol is not appropriate for
201 bandwidth-challenged applications or deployments.
206 This section provides an overview of basis ways the Sync operation can
207 be used to maintain a synchronized shadow copy of a DIT fragment.
209 - Polling for Changes: refreshOnly mode
210 - Listening for Changes: refreshAndPersist mode
213 1.3.1. Polling for Changes (refreshOnly)
215 To obtain its initial shadow copy, the client issues a Sync request: a
216 search request with the Sync Request Control with mode set to
217 refreshOnly. The server, much like it would with a normal search
218 operation, returns (subject to access controls and other restrictions)
219 the content matching the search criteria (baseObject, scope, filter).
220 Additionally, with each entry returned, the server provides a Sync
221 State control indicating state add. This control contains the
222 Universally Unique Identifier (UUID) [UUID] of the entry. Unlike
226 Zeilenga LDAP Content Sync Operation [Page 4]
228 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
231 Distinguished Names (DNs), which may change over time, an entry's
232 UUIDs are stable. The initial content is followed by a
233 searchResultDone with a Sync Done control. The Sync Done control
234 provides a syncCookie. The syncCookie represents session state.
236 To poll for updates to the shadow copy, the client reissues the Sync
237 operation with the syncCookie previously returned. The server, much
238 as it would with a normal search operation, determines which content
239 would be returned as if the operation was a normal search operation.
240 However, using the syncCookie as an indicator of what content the
241 client was sent previously, the server sends copies of entries which
242 have changed with a Sync State control indicating state add. For each
243 unchanged entry, the server sends an empty entry (e.g., no attributes)
244 with a Sync State control indicating state present. The set of
245 updates is followed by a searchResultDone with a Sync Done control.
247 If the server can reliably determine which entries in the prior shadow
248 copy are no longer present in the content and the number of such
249 entries is less than or equal to the number of unchanged entries, the
250 server may, instead of returning an empty entry with state present for
251 each present entry, send an empty entry with state delete for each
252 entry which is no longer in the content. Also, the Sync Done control
253 refreshDeletes is set to TRUE to indicate to the client that this
254 method was used. This field is FALSE otherwise.
256 The synchronized shadow copy of the DIT fragment is constructed by the
259 If refreshDeletes is FALSE, the new copy includes all changed entries
260 returned by the reissued Sync operation as well as all unchanged
261 entries identified as being present by the reissued Sync operation,
262 but whose content is provided by the previous Sync operation. The
263 unchanged entries not identified as being present are deleted from the
264 shadow content. They had been either deleted, moved, or otherwise
265 scoped-out from the content.
267 If refreshDeletes is TRUE, the new copy includes all changed entries
268 returned by the reissued Sync operation as well as all other entries
269 of the previous copy except those which were identified as having been
270 deleted from the content.
272 The client can, at some later time, re-poll for changes to this
273 synchronized shadow copy.
276 1.3.2. Listening for Changes (refreshAndPersist)
278 Polling for changes can be expensive in terms of server, client, and
282 Zeilenga LDAP Content Sync Operation [Page 5]
284 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
287 network resources. The refreshAndPersist mode allows for active
288 updates of changed entries in the content.
290 By selecting the refreshAndPersist mode, the client requests the
291 server to send updates of entries that are changed after the the
292 initial refresh content is determined. Instead of sending a
293 searchResultDone message as described above, the server sends a Sync
294 Info message to the client indicating that refresh phase is complete
295 and then enters persist phase. After receipt of this Sync Info
296 message, the client will have a synchronized shadow copy as described
299 The server may then send change notifications. For entries to be
300 added to the returned content, the server sends a searchResultEntry
301 (with attributes) with a Sync State control indicating state add. For
302 entries to be deleted from the content, the server sends a
303 searchResultEntry containing with no attributes and a Sync State
304 control indicating state delete. To modify entries in the return
305 content, the server sends a searchResultEntry (with attributes) with a
306 Sync State control indicating state modify. Upon modification of an
307 entry, all (modified or unmodified) attributes belonging to the
310 Note that renaming an entry of the DIT may cause an add state change
311 where the entry is renamed into the content, a delete state change
312 where the entry is renamed out of the content, and a modify state
313 change where the entry remains in the content. Also note that a
314 modification of an entry of the DIT may cause a add, delete, or modify
315 state change to the content.
317 Upon receipt of a change notification, the client updates its copy of
320 If the server desires to update the syncCookie during the persist
321 stage, it may include the syncCookie any Sync State control or Sync
322 Info message returned.
324 The operation persists until canceled [CANCEL] by the client or
325 terminated by the server. A Sync Done control may be attached to
326 searchResultDone message to provide a new syncCookie.
329 2. Elements of the Sync Operation
331 The Sync Operation is defined as an extension to the LDAP Search
332 Operation [RFC2251] where the directory user agent (DUA or client)
333 submits a SearchRequest message with a Sync Request control and the
334 directory system agent (DSA or server) responses with zero or more
338 Zeilenga LDAP Content Sync Operation [Page 6]
340 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
343 SearchResultEntry messages, each with a Sync State control; zero or
344 more SearchResultReference messages, each with a Sync State control;
345 zero or more Sync Intermediate Response messages; and a
346 searchResultDone message with a Sync Done control.
348 To allow clients to discover support for this operation, servers
349 implementing this operation SHOULD publish the IANA-ASSIGNED-OID.1 as
350 a value of supportedControl root DSE attribute.
353 2.1 Common ASN.1 elements
357 The syncUUID is a notational convenience to indicate that, while the
358 syncUUID type is encoded as an OCTET STRING, its value is restricted
359 to the string representation of an Universally Unique Identifier
360 (UUID) defined in [UUID].
362 syncUUID ::= OCTET STRING
367 The syncCookie is a notational convenience to indicate that, while the
368 syncCookie type is encoded as an OCTET STRING, its value is an opaque
369 value containing information about the synchronization session and its
370 state. Generally, the session information would include a hash of the
371 operation parameters which the server requires not be changed; the
372 synchronization state information includes a commit (log) sequence
373 number, a change sequence number, or a time stamp; and a digital
374 signature for detection of tampering.
376 syncCookie ::= OCTET STRING
379 2.2 Sync Request Control
381 The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2]
382 where the controlType is the object identifier IANA-ASSIGNED-OID.1 and
383 the controlValue, an OCTET STRING, contains a BER-encoded
384 syncRequestValue. The criticality field is either TRUE or FALSE.
386 syncRequestValue ::= SEQUENCE {
394 Zeilenga LDAP Content Sync Operation [Page 7]
396 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
399 refreshAndPersist (3)
401 cookie syncCookie OPTIONAL
404 The Sync Request Control is only applicable to the searchRequest
408 2.3 Sync State Control
410 The Sync State Control is an LDAP Control [RFC2251, Section 4.1.2]
411 where the controlType is the object identifier IANA-ASSIGNED-OID.2 and
412 the controlValue, an OCTET STRING, contains a BER-encoded
413 syncStateValue. The criticality is FALSE.
415 syncStateValue ::= SEQUENCE {
423 cookie syncCookie OPTIONAL
426 The Sync State Control is only applicable to SearchResultEntry and
427 SearchResultReference messages.
430 2.4 Sync Done Control
432 The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2]
433 where the controlType is the object identifier IANA-ASSIGNED-OID.3 and
434 the controlValue contains a BER-encoded syncDoneValue. The
435 criticality is FALSE (and hence absent).
437 syncDoneValue ::= SEQUENCE {
438 cookie syncCookie OPTIONAL,
439 refreshDeletes BOOLEAN DEFAULT FALSE,
442 The Sync Done Control is only applicable to SearchResultDone message.
445 2.5 Sync Info Message
450 Zeilenga LDAP Content Sync Operation [Page 8]
452 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
455 The Sync Info Message is an LDAP Intermediate Response Message
456 [LDAPIRM] where responseName is the object identifier
457 IANA-ASSIGNED-OID.4 and responseValue contains a BER-encoded
458 syncInfoValue. The criticality is FALSE (and hence absent).
460 syncInfoValue ::= CHOICE {
461 newcookie [0] syncCookie,
462 refreshDone [1] SEQUENCE {
463 cookie syncCookie OPTIONAL,
464 refreshDeletes BOOLEAN DEFAULT FALSE
469 2.6 Sync Result Codes
471 The following LDAP resultCodes [RFC2251] are defined:
473 syncRefreshRequired (IANA-ASSIGNED-CODE-0)
476 3. Content Synchronization
478 The Sync Operation is invoked by the client sending a searchRequest
479 message with a Sync Request Control.
481 The absence of a cookie indicates a request for initial content while
482 the presence of a cookie indicates a request for content update.
483 Synchronization Sessions are discussed in Section 3.1. Content
484 Determination is discussed in Section 3.2.
486 The mode is either refreshOnly or refreshAndPersist. The refreshOnly
487 and refreshAndPersist modes are discussed in Section 3.3 and 3.4,
488 respectively. The refreshOnly mode consists only of a refresh stage,
489 while the refreshAndPersist mode consists of a refresh stage and a
490 subsequent persist stage.
493 3.1. Synchronization Session
495 A sequence of Sync Operations where the last cookie returned by a
496 operation is provided by the client in the next operation are said to
497 belong to the same Synchronization Session.
499 The client MUST specify the same content controlling parameters (see
500 Section 3.5) in each Search Request of the session. The client SHOULD
501 also issue each Sync request of a session under the same
502 authentication and authorization associations with equivalent
506 Zeilenga LDAP Content Sync Operation [Page 9]
508 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
511 integrity and confidential protections. If the server does not
512 recognize the request cookie or the request is made under different
513 associations or inequivalent protections, the server SHALL process the
514 request as if no cookie had been provided.
516 A Synchronization Session may span multiple LDAP sessions between the
517 client and the server. The client SHOULD issue each Sync request of a
518 session to the same server.
521 3.2. Content Determination
523 The content to be provided is determined by parameters of the Search
524 Request, as described in [RFC2251], and possibly other controls. The
525 same content SHOULD be used in each Sync request of a session. If
526 different content is requested and the server is unwilling or unable
527 to process the request, the server SHALL process the request as if no
528 cookie had been provided.
530 The content may not necessarily include all entries or references
531 which would be returned by a normal search operation nor, for those
532 entries included, not all attributes returned by a normal search.
533 Where the server is unwilling or unable to provide synchronization for
534 an attribute for a set of entries, the server MUST treat all filter
535 components matching against these attribute as Undefined and MUST NOT
536 return the attribute in searchResultEntry responses.
538 Servers SHOULD support synchronization for all non-collective
539 user-applications attributes for all entries.
541 The server may also return continuation references to other servers or
542 to itself. The latter is allowed as the server may partition the
543 entries it holds into separate synchronization contexts.
545 The client may chase all or some of these continuations, each in a
546 separate LDAP session.
549 3.3. refreshOnly mode
551 A Sync request with mode refreshOnly and no cookie is a poll for
552 initial content. A Sync request with mode refreshOnly and cookie is a
553 poll for content update.
556 3.3.1. Initial Content Poll
558 Upon receipt of the request, the server provides the initial content
562 Zeilenga LDAP Content Sync Operation [Page 10]
564 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
567 using a set of zero or more searchResultEntry and
568 searchResultReference messages followed by a searchResultDone message.
570 Each searchResultEntry message SHALL include a Sync State control of
571 state add, entryUUID containing the entry's UUID, and no cookie. Each
572 searchResultReference message SHALL include a Sync State control of
573 state add, entryUUID containing the UUID associated with the reference
574 (normally the referral [RFC3296] object's entryUUID), and no cookie.
575 The searchResultDone message SHALL include a Sync Done control. The
576 refreshDeletes SHALL be FALSE.
578 A resultCode value of success indicates the operation successfully
579 completed. Otherwise, the result code indicates the nature of
582 If the operation is successful, a cookie SHOULD be returned for use in
583 subsequent Sync operations.
586 3.3.2. Content Update Poll
588 Upon receipt of the request the server provides the content refresh
589 using a set of zero or more searchResultEntry and
590 searchResultReference messages followed by a searchResultDone message.
592 The server is REQUIRED to either:
593 a) provide the sequence of messages necessary for eventual
594 convergence of the client's copy of the content to the server's
597 b) treat the request as an initial content request (e.g., ignore
600 c) indicate that convergence is not possible by returning
603 d) return a resultCode other than success or syncRefreshRequired.
605 For each entry or reference added to the content or was changed since
606 the previous Sync operation indicated by the cookie, the server
607 returns a searchResultEntry or searchResultReference message,
608 respectively, each with a Sync State cookie of state add, entryUUID
609 containing the UUID of the entry or reference, and no cookie. Each
610 searchResultEntry message represents the current state of a changed
611 entry. Each SearchResultReference message represents the current
612 state of a changed reference.
614 For each entry which has not been changed since the previous Sync
618 Zeilenga LDAP Content Sync Operation [Page 11]
620 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
623 operation, a searchResultEntry is returned whose objectName reflects
624 the entry's current DN, the attributes field is empty, and a Sync
625 State control of state present, entryUUID containing the UUID of the
626 entry, and no cookie. For each reference which has not been changed
627 since the previous Sync operation, a searchResultReference containing
628 an empty SEQUENCE OF LDAPURL is returned with a Sync State control of
629 state present, entryUUID containing the UUID of the entry, and no
630 cookie. No messages are sent for entries or references which are no
633 As an alternative to sending messages for each entry and reference
634 which has not been changed, the server may instead return the
635 following. For each entry no longer in content, return a
636 searchResultEntry whose objectName reflects a past DN of the entry or
637 is empty, the attributes field is empty, and a Sync State control of
638 state delete, entryUUID containing the UUID of the deleted entry, and
639 no cookie. For each reference no longer in content, a
640 searchResultReference containing an empty SEQUENCE OF LDAPURL is
641 returned with a a Sync State control of state delete, entryUUID
642 containing the UUID of the deleted reference, and no cookie.
644 A resultCode value of success indicates the operation successfully
645 completed. Otherwise, the result code indicates the nature of
648 If the operation is successful, a cookie SHOULD be returned for use in
649 subsequent Sync operations.
652 3.4. refreshAndPersist mode
654 A Sync request with mode refreshAndPersist asks for initial content or
655 content update (during the refresh stage) followed by change
656 notifications (during the persist stage).
661 The content refresh is provided as described in Section 3.3 excepting
662 that successful completion of content refresh is indicated by sending
663 a Sync Info with state refreshDone message instead of a
664 SearchResultDone message with resultCode success. A cookie SHOULD be
665 returned for use in subsequent Sync operations.
670 Change notifications are provided during the persist stage.
674 Zeilenga LDAP Content Sync Operation [Page 12]
676 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
679 As updates are made to the DIT the server notifies the client of
680 changes to the content. DIT updates may cause entries references to
681 be added to the content, deleted from the content, or modify entries
682 in the content. DIT updates may also cause references to be added,
683 deleted, or modified within the content.
685 Where DIT updates cause an entry to be added to the content, the
686 server provides a searchResultEntry message which represents the entry
687 as it appears in the content. The message SHALL include a Sync State
688 control with state of add, entryUUID containing the entry's UUID, and
691 Where DIT updates cause a reference to be added to the content, the
692 server provides a searchResultReference message which represents the
693 reference in the content. The message SHALL include a Sync State
694 control with state of add, entryUUID containing the UUID associated
695 with the reference, and an optional cookie.
697 Where DIT updates cause an entry to be modified in the content, the
698 server provides a searchResultEntry message which represents the entry
699 as it appears in the content. The message SHALL include a Sync State
700 control with state of modify, entryUUID containing the entry's UUID,
701 and an optional cookie.
703 Where DIT updates cause a reference to be modified in the content, the
704 server provides a searchResultEntry message which represents the
705 reference in the content. The message SHALL include a Sync State
706 control with state of modify, entryUUID containing the UUID associated
707 with the reference, and an optional cookie.
709 Where DIT updates cause an entry to be deleted from the content, the
710 server provides a searchResultReference message with an empty SEQUENCE
711 OF LDAPURL. The message SHALL include a Sync State control with state
712 of delete, entryUUID containing the UUID associated with the
713 reference, and an optional cookie.
715 Where DIT updates cause a reference to be deleted from the content,
716 the server provides a searchResultEntry message with no attributes.
717 The message SHALL include a Sync State control with state of delete,
718 entryUUID containing the entry's UUID, and an optional cookie.
720 With each of these messages, the server may provide a new cookie to be
721 used in subsequent Sync operations. Additionally, the server may also
722 return Sync Info messages of choice newCookie to provide a new cookie.
723 The client SHOULD use newest (last) cookie it received from the server
724 in subsequent Sync operations.
730 Zeilenga LDAP Content Sync Operation [Page 13]
732 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
735 3.5. Search Request Parameters
737 As stated in Section 3.1, the client SHOULD specify the same content
738 controlling parameters (see Section 3.5) in each Search Request of the
739 session. All fields of the SearchRequest message are considered
740 content controlling parameters except for sizeLimit and timeLimit.
743 3.5.1. baseObject Issues
745 As with the normal search operation, the refresh and persist phases
746 are not isolated from DIT changes. It is possible that the entry
747 referred to be the baseObject be deleted, renamed, or moved. It is
748 also possible that alias object used in finding the entry referred to
749 by the baseObject is changed such that the baseObject refers to a
752 If the DIT is updated during processing of the Sync Operation in a
753 manner that causes the baseObject to no longer refers to any entry or
754 changes which entry the baseObject refers to, the server SHALL return
755 an appropriate non-success result code such as noSuchObject,
756 aliasProblem, aliasDereferencingProblem, referral, or
760 3.5.2. derefAliases Issues
762 This operation does not support alias dereferencing during searching.
763 The client SHALL specify neverDerefAliases or derefFindingBaseObj for
764 the searchRequest derefAliases parameter. The server SHALL treat
765 other values (e.g., derefInSearching, derefAlways) as protocol errors.
768 3.5.3. sizeLimit Issues
770 The sizeLimit applies only to entries (regardless of their syncState)
771 returned during refreshOnly processing or the refresh stage of the
772 refreshAndPersist processing.
775 3.5.4. timeLimit Issues
777 For a refreshOnly Sync operation, the timeLimit applies to the whole
778 operation. For a refreshAndPersist operation, the timeLimit applies
779 to processing up to and including generating the Sync Info with state
786 Zeilenga LDAP Content Sync Operation [Page 14]
788 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
793 The client SHOULD avoid filter assertions which apply to values of
794 attributes likely to be considered by the server as holding meta-
795 information. See section 4.
798 3.6. objectName Issues
800 The Sync operation uses entryUUID values provided in the Sync State
801 control as the primary keys to entries. The client MUST use these
802 entryUUIDs to correlate synchronization messages.
804 In some circumstances the DN returned may not reflect the entry's
805 current DN. In particular, when the entry is being deleted from the
806 content, the server MAY provide an empty DN if the server does not
807 wish to disclose the entry's current DN (or, if deleted from the DIT,
808 the entry's last DN).
810 It should also be noted that the entry's DN may be viewed as meta
811 information (see section 4.1).
814 3.7. Canceling the Sync Operation
816 Servers SHOULD implement the LDAP Cancel [CANCEL] operation and
817 support cancellation of outstanding Sync operations as described here.
819 To cancel an outstanding Sync Operation, the client SHOULD issue a
820 Cancel operation [CANCEL]....
823 3.7. Refresh Required
825 In order to achieve the eventual-convergent synchronization, the
826 server may terminate the Sync operation in refresh or persist stage by
827 returning a syncRefreshRequired resultCode to the client. The client
828 may then request a full reload (e.g., no cookie) instead of
829 incremental synchronization in order to obtain a new copy of the
830 content. In case that the client issues incremental synchronization
831 requests between the issue of a syncRefreshRequired and that of a full
832 reload, the server should send a syncRefreshRequired response again,
833 but the client may receive one or more searchResultEntry responses
834 before it receives the syncRefreshRequired response.
836 The server may also choose to provide a full copy in the refresh stage
837 (e.g., ignore the cookie) instead of providing an incremental refresh
838 in order to achieve the eventual convergence.
842 Zeilenga LDAP Content Sync Operation [Page 15]
844 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
847 In the case of persist stage Sync, the server returns the resultCode
848 of syncRefreshRequired to the client to indicate that the client needs
849 to issue a full reload operation (e.g., no cookie) in order to obtain
850 a synchronized copy of the content.
852 The server may also return syncRefreshRequired if it determines that a
853 refresh would be more efficient than sending all the messages required
857 3.8. Chattiness Considerations
859 The server MUST ensure that the number of entry messages generated to
860 refresh the client content does not exceed the number of entries
861 presently in the content. While there is no requirement for servers
862 to maintain historical information, if the server has sufficient
863 history to allow it to reliably determine which entries in the prior
864 shadow copy are no longer present in the content and the number of
865 such entries is less than equal the number of unchanged entries, the
866 server SHOULD generate delete entry messages instead of present entry
867 messages (see Section 3.3.2).
869 The server SHOULD maintain enough (current or historical) state
870 information (such as a context-wide last modify time stamp), to
871 determine that no changes were made in the context since the content
872 to refresh was provided and, and when no changes were made, generate
873 zero delete entry messages instead of present messages.
875 The server implementor should also consider chattiness issues which
876 span multiple Sync operations of a session. As noted in Section 3.7,
877 the server may return syncRefreshRequired if it determines that a
878 refresh would be more efficient than continuing under the current
881 The server SHOULD transfer a new cookie frequently to avoid having to
882 transfer information already provided to the client. Even where DIT
883 changes do not cause content synchronization changes to be
884 transferred, it may be advantageous to provide a new cookie using a
885 Sync Info message. However, the server SHOULD avoid overloading the
886 client or network with Sync Info messages.
888 During persist mode, the server SHOULD coalesce multiple outstanding
889 messages updating the same entry. The server MAY delay generation of
890 an entry update in anticipation of subsequent changes to that entry
891 which could be coalesced. The length of the delay should be long
892 enough to allow coalescing of update requests issued back to back but
893 short enough that the transient inconsistency induced by the delay is
894 corrected in a timely manner.
898 Zeilenga LDAP Content Sync Operation [Page 16]
900 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
903 4. Meta Information Considerations
907 As an entry's DN is constructed from its relative DN (RDN) and the
908 entry's parent's DN, it is often viewed as meta information.
910 While renaming or moving a superior to an entry causes the entry's DN
911 to change, that change SHOULD NOT, by itself, cause synchronization
912 message to be sent for that entry. However, if renaming or moving of
913 a superior could cause the entry to added or deleted from the content
914 and, if so, appropriate synchronization messages should be generated
915 to indicate this to the client.
917 Where a server treats the entry's DN as meta information, the server
919 - evaluate all MatchingRuleAssertions to TRUE if matching a value
920 of an attribute of the entry and otherwise Undefined, or
921 - evaluate all MatchingRuleAssertion with dnAttributes of TRUE
924 The latter choice is offered for ease of server implementation.
927 4.2. Operational Attributes
929 Where values of an operational attribute is determined by values not
930 held as part of the entry it appears in, the operational attribute
931 SHOULD NOT support synchronization of that operational attribute.
933 For example, in servers which implement X.501 subschema model [X.501],
934 servers should not support synchronization of the subschemaSubentry
935 attribute as its value is determined by values held and administrated
936 in subschema subentries.
938 For a counter example, servers which implement aliases
939 [RFC2256][X.501] can support synchronization of the aliasedObjectName
940 attribute as its values are held and administrated as part of the
943 Servers SHOULD support synchronization of the following operational
944 attributes: createTimestamp, modifyTimestamp, creatorsName,
945 modifiersName [RFC2252]. Servers MAY support synchronization of other
946 operational attributes. Synchronization of operational attributes is
947 discussed in Section 4.1.
950 4.3. Collective Attributes
954 Zeilenga LDAP Content Sync Operation [Page 17]
956 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
959 A collective attribute is "a user attribute whose values are the same
960 for each member of an entry collection" [X.501]. Use of collective
961 attributes in LDAP is detailed in [COLLECTIVE].
963 Modification of a collective attribute generally affects the content
964 of multiple entries, each a member of the collection. It is
965 inefficient to include values of collective attributes visible in
966 entries of the collection, as a single modification of a collective
967 attribute require transmission of multiple SearchResultEntry (one of
968 each entry of the collection which the modification affected) to be
971 Servers SHOULD NOT synchronize collective attributes appearing in
972 entries of any collection. Servers MAY support synchronization of
973 collective attributes appearing in collective attribute subentries.
976 4.4. Access and other administrative controls
978 Entries are commonly subject to access and other administrative
979 controls. While portions of the policy information governing a
980 particular entry may be held in the entry, policy information is often
981 held elsewhere (in superior entries, in subentries, in the root DSE,
982 in configuration files, ...). Because of this, changes to policy
983 information make it difficult to ensure eventual convergence during
984 incremental synchronization.
986 Where it is impractical or infeasible to generate content changes
987 resulting from a change to policy information, servers may opt to
988 return syncRefreshRequired or treat the Sync Operation as an initial
989 content request (e.g., ignore the cookie).
992 5. Interaction with other controls
994 The Sync Operation may be used with:
996 - ManageDsaIT Control [RFC3296]
997 - Subentries Control [SUBENTRY]
999 as described below. The Sync operation may be used with other LDAP
1000 extensions as detailed in other documents.
1003 5.1. ManageDsaIT control
1005 The ManageDsaIT control [RFC3296] indicates that the operation acts
1006 upon the DSA Information Tree and causes referral and other special
1010 Zeilenga LDAP Content Sync Operation [Page 18]
1012 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1015 objects to be treated as normal objects with respect to the operation.
1018 5.2. Subentries control
1020 The Subentries control is used with the search operation "to control
1021 the visibility of entries and subentries which are within scope"
1022 [SUBENTRY]. When used with the Sync Operation, the subentries control
1023 and other factors (search scope, filter, etc.) are used to determining
1024 whether an entry or subentry appear in the content or not.
1027 6. Security Considerations
1029 In order to maintain a synchronized copy of the content, a client is
1030 to delete information from its copy of the content as described above.
1031 However, the client may maintain knowledge of information disclosed to
1032 it by the server separate from its copy of the content used for
1033 synchronization. Management of this knowledge is beyond the scope of
1036 While the information provided by a series of refreshOnly Sync
1037 operations is similar to that provided by a series of Search
1038 operations, persist stage may disclose additional information. A
1039 client may be able to discern information about the particular
1040 sequence of update operations which caused content change.
1042 Implementors should take precautions against malicious cookie content,
1043 including malformed cookies or valid cookies used with different
1044 security associations and/or protections in attempt to obtain
1045 unauthorized access to information.
1047 The Sync operation may be the target of denial of service attacks.
1048 Implementors should provide safeguards to ensure these mechanisms are
1049 not abused. Servers may place access control or other restrictions
1050 upon the use of this operation.
1052 Implementors of this (or any) LDAP extension should be familiar with
1053 general LDAP security considerations [RFC3377].
1056 7. IANA Considerations
1058 Registration of the following values is requested.
1061 7.1. Object Identifier
1066 Zeilenga LDAP Content Sync Operation [Page 19]
1068 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1071 It is requested that IANA register upon Standards Action an LDAP
1072 Object Identifier to identify elements of the LDAP Content
1073 Synchronization Operation as defined in this document.
1075 Subject: Request for LDAP Object Identifier Registration
1076 Person & email address to contact for further information:
1077 Kurt Zeilenga <kurt@OpenLDAP.org>
1078 Specification: RFCXXXX
1079 Author/Change Controller: IESG
1081 Identifies elements of the LDAP Content Synchronization Operation
1084 7.2. LDAP Protocol Mechanism
1086 It is requested that IANA register upon Standards Action the LDAP
1087 Protocol Mechanism described in this document.
1089 Subject: Request for LDAP Protocol Mechanism Registration
1090 Object Identifier: IANA-ASSIGNED-OID
1091 Description: LDAP Content Synchronization Control
1092 Person & email address to contact for further information:
1093 Kurt Zeilenga <kurt@openldap.org>
1095 Specification: RFCXXXX
1096 Author/Change Controller: IESG
1100 7.3. LDAP Result Codes
1102 It is requested that IANA register upon Standards Action the LDAP
1103 Result Codes described in this document.
1105 Subject: LDAP Result Code Registration
1106 Person & email address to contact for further information:
1107 Kurt Zeilenga <kurt@OpenLDAP.org>
1108 Result Code Name: syncRefreshRequired (IANA-ASSIGNED-CODE-0)
1109 Specification: RFCXXXX
1110 Author/Change Controller: IESG
1116 This work borrows significantly from the LDAP Client Update Protocol
1117 [LCUP]. This work also benefited Persistent Search [PSEARCH],
1118 Triggered Search [TSEARCH], and Directory Synchronization [DIRSYNC]
1122 Zeilenga LDAP Content Sync Operation [Page 20]
1124 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1127 efforts. This work also borrows from "Lightweight Directory Access
1128 Protocol (v3)" [RFC2251].
1131 9. Normative References
1133 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
1134 Requirement Levels", BCP 14 (also RFC 2119), March 1997.
1136 [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
1137 Access Protocol (v3)", RFC 2251, December 1997.
1139 [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
1140 Directory Access Protocol (v3): Attribute Syntax
1141 Definitions", RFC 2252, December 1997.
1143 [RFC2256] M. Wahl, "A Summary of the X.500(96) User Schema for use
1144 with LDAPv3", RFC 2256, December 1997.
1146 [RFC2830] J. Hodges, R. Morgan, and M. Wahl, "Lightweight Directory
1147 Access Protocol (v3): Extension for Transport Layer
1148 Security", RFC 2830, May 2000.
1150 [RFC3296] K. Zeilenga, "Named Subordinate References in Lightweight
1151 Directory Access Protocol (LDAP) Directories", RFC 3296,
1154 [RFC3377] J. Hodges, R.L. Morgan, "Lightweight Directory Access
1155 Protocol (v3): Technical Specification", RFC 3377,
1158 [LDAPIRM] R. Harrison, K. Zeilenga, "LDAP Intermediate Response
1159 Message", draft-rharrison-ldap-intermediate-resp-xx.txt
1160 (a work in progress).
1162 [SUBENTRY] K. Zeilenga, S. Legg, "Subentries in LDAP",
1163 draft-zeilenga-ldap-subentry-xx.txt, a work in progress.
1165 [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
1166 Specification of Basic Notation", X.680, 1994.
1168 [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
1169 Canonical, and Distinguished Encoding Rules", X.690,
1172 [CANCEL] K. Zeilenga, "LDAP Cancel Extended Operation",
1173 draft-zeilenga-ldap-cancel-xx.txt, a work in progress.
1178 Zeilenga LDAP Content Sync Operation [Page 21]
1180 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1183 [UUID] International Organization for Standardization (ISO),
1184 "Information technology - Open Systems Interconnection -
1185 Remote Procedure Call", ISO/IEC 11578:1996.
1188 10. Informative References
1190 [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 (also
1191 RFC 3383), September 2002.
1193 [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
1194 Models and Service", 1993.
1196 [X.511] ITU, "The Directory: Abstract Service Definition", ITU-T
1199 [X.525] ITU, "The Directory: Replication", ITU-T Rec. X.525,
1202 [COLLECTIVE] K. Zeilenga, "Collective Attributes in LDAP",
1203 draft-zeilenga-ldap-collective-xx.txt, a work in
1206 [DIRSYNC] M. Armijo, "Microsoft LDAP Control for Directory
1207 Synchronization", draft-armijo-ldap-dirsync-xx.txt, a
1210 [LCUP] R. Megginson, et. al., "LDAP Client Update Protocol",
1211 draft-ietf-ldup-lcup-xx.txt, a work in progress.
1213 [PSEARCH] M. Smith, et. al., "Persistent Search: A Simple LDAP
1214 Change Notification Mechanism",
1215 draft-ietf-ldapext-psearch-xx.txt, a work in progress.
1217 [TSEARCH] M. Wahl, "LDAPv3 Triggered Search Control",
1218 draft-ietf-ldapext-trigger-xx.txt, a work in progress.
1220 [UUID-CSN] K. Zeilenga, J. Choi, "LDAP UUID and CSN Operational
1221 Attributes", draft-zeilenga-ldap-uuid-csn-xx.txt, a work
1222 (not yet) in progress.
1225 10. Authors' Address
1234 Zeilenga LDAP Content Sync Operation [Page 22]
1236 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1241 <jongchoi@us.ibm.com>
1246 Copyright 2003, The Internet Society. All Rights Reserved.
1248 This document and translations of it may be copied and furnished to
1249 others, and derivative works that comment on or otherwise explain it
1250 or assist in its implementation may be prepared, copied, published and
1251 distributed, in whole or in part, without restriction of any kind,
1252 provided that the above copyright notice and this paragraph are
1253 included on all such copies and derivative works. However, this
1254 document itself may not be modified in any way, such as by removing
1255 the copyright notice or references to the Internet Society or other
1256 Internet organizations, except as needed for the purpose of
1257 developing Internet standards in which case the procedures for
1258 copyrights defined in the Internet Standards process must be followed,
1259 or as required to translate it into languages other than English.
1261 The limited permissions granted above are perpetual and will not be
1262 revoked by the Internet Society or its successors or assigns.
1264 This document and the information contained herein is provided on an
1265 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
1266 ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
1267 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
1268 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
1269 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1272 Appendix - CSN-based Implementation Considerations
1274 This appendix is provided for informational purposes only, it is not a
1275 normative part of the LDAP Content Synchronization Operation's
1276 technical specification.
1278 This appendix discusses some of the implementation considerations
1279 associated with a Change Sequence Number [UUID-CSN] based approaches
1280 to supporting the LDAP Content Synchronization Operation.
1282 Change Sequence Number-based approaches are targetted for use in
1283 servers which do not maintain historical information (e.g., change
1284 logs, state snapshots, etc.) about changes made to the Directory and
1285 hence, must rely on current directory state and minimal
1286 synchronization state information embedded in Sync Cookie. Servers
1290 Zeilenga LDAP Content Sync Operation [Page 23]
1292 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1295 which maintain historical information should consider an other
1296 approaches which exploit the historical information.
1298 A Change Sequence Number is, effectively a time stamp has sufficient
1299 granularity to ensure that relationship in time of two updates to the
1300 same object can be determined. Change Sequence Numbers are not to be
1301 confused with Commit Sequence Numbers or Commit Log Record Numbers. A
1302 Commit Sequence Number allow one to determine how to two commits (to
1303 the same object or different objects) relate to each other in time.
1304 Change Sequence Number associated with different entries may be
1305 committed out of order. In the remainder of this Appendix, the term
1306 CSN refers to a Change Sequence Number.
1308 In these approaches, the server not only maintains an entry CSN
1309 operational attribute for each directory entry (as discussed in [UUID-
1310 CSN], but maintains a value which we will call the context CSN. The
1311 context CSN is the greatest committed entry CSN which is not greater
1312 than any outstanding entry CSNs for all entries in a directory
1313 context. The values of context CSN are used in syncCookie values as
1314 synchronization state indicators.
1316 As search operations are not isolated from individual directory update
1317 operations and individual update operations cannot be assumed to be
1318 serialized, one cannot assume that the returned content incorporates
1319 all relevant changes whose change sequence number is less than or
1320 equal to the greatest entry CSN in the content. The content
1321 incorporates all the relevant changes whose change sequence number is
1322 less than or equal to context CSN before search processing. The
1323 content may also incorporate any subset of the the changes whose
1324 change sequence number is greater than context CSN before search
1325 processing but less than or equal to the context CSN after search
1326 processing. The content does not incorporate any of the changes whose
1327 CSN is greater than the context CSN after search processing.
1329 A simple server implementation could use value of the context CSN
1330 before search processing to indicate state. Such an implementation
1331 would embed this value into each SyncCookie returned. We'll call this
1332 the cookie CSN. When a refresh was requested, the server would simply
1333 entry "update" messages for all entries in the content whose CSN is
1334 greater than the cookie CSN and entry "present" messages for all other
1335 entries in the content. However, if the current context CSN is same
1336 as the cookie CSN, the server should instead generate zero "updates",
1337 zero "delete" messages and indicate refreshDeletes of TRUE as the
1338 directory has not changed.
1340 The implementation should also consider the impact of changes to meta
1341 information, such as access controls, which affects content
1342 determination. One approach is for the server to maintain a context
1346 Zeilenga LDAP Content Sync Operation [Page 24]
1348 INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
1351 wide meta information CSN or meta CSN. This meta CSN would be updated
1352 whenever meta information affecting content determination was changed.
1353 If the value of the meta CSN is greater than cookie CSN, the server
1354 should ignore the cookie and treat the request as an initial request
1402 Zeilenga LDAP Content Sync Operation [Page 25]