-
-
-
-
INTERNET-DRAFT Kurt D. Zeilenga
-Intended Category: Standard Track OpenLDAP Foundation
-Expires in six months Jonghyuk Choi
+Intended Category: Experimental OpenLDAP Foundation
+Expires in six months Jong Hyuk Choi
IBM Corporation
- 5 May 2003
+ 3 February 2004
- LDAP Content Synchronization Operation
- <draft-zeilenga-ldup-sync-02.txt>
+ The LDAP Content Synchronization Operation
+ <draft-zeilenga-ldup-sync-05.txt>
-1. Status of this Memo
+Status of this Memo
This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.
Internet-Draft Shadow Directories can be accessed at
<http://www.ietf.org/shadow.html>.
- Copyright 2003, The Internet Society. All Rights Reserved.
+ Copyright (C) The Internet Society (2004). All Rights Reserved.
- Please see the Copyright section near the end of this document for
- more information.
+ Please see the Full Copyright section near the end of this document
+ for more information.
Zeilenga LDAP Content Sync Operation [Page 1]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
Abstract
This specification describes the LDAP (Lightweight Directory Access
- Protocol) Content Synchronization operation. The operation allows a
- client to maintain a shadow copy of a fragment of directory
- information tree. It supports both polling for changes and listening
- for changes. The operation is defined as an extension of the LDAP
- Search operation.
+ Protocol) Content Synchronization Operation. The operation allows a
+ client to maintain a copy of a fragment of directory information tree.
+ It supports both polling for changes and listening for changes. The
+ operation is defined as an extension of the LDAP Search Operation.
+
+
+Table of Contents
+
+ Status of this Memo 1
+ Abstract 2
+ Table of Contents
+ 1. Introduction 3
+ 1.1. Background
+ 1.2. Intended Usage 4
+ 1.3. Overview 5
+ 1.4. Conventions
+ 2. Elements of the Sync Operation 8
+ 2.1. Common ASN.1 Elements 9
+ 2.2. Sync Request Control
+ 2.3. Sync State Control
+ 2.4. Sync Done Control 10
+ 2.5. Sync Info Message
+ 2.6. Sync Result Codes 11
+ 3. Content Synchronization
+ 3.1. Synchronization Session
+ 3.2. Content Determination 12
+ 3.3. refreshOnly Mode 13
+ 3.4. refreshAndPersist Mode 16
+ 3.5. Search Request Parameters 17
+ 3.6. objectName Issues 18
+ 3.7. Canceling the Sync Operation 19
+ 3.8. Refresh Required
+ 3.9. Chattiness Considerations 20
+ 3.10. Operation Multiplexing 21
+ 4. Meta Information Considerations 22
+ 4.1. Entry DN
+ 4.2. Operational Attributes
+ 4.3. Collective Attributes 23
+ 4.4. Access and Other Administrative Controls
+ 5. Interaction with Other Controls
+ 5.1. ManageDsaIT Control 24
+ 5.2. Subentries Control
+ 6. Shadowing Considerations
+ 7. Security Considerations 25
+ 8. IANA Considerations
-Conventions
- The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
- "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
- document are to be interpreted as described in BCP 14 [RFC2119].
+Zeilenga LDAP Content Sync Operation [Page 2]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
- Protocol elements are described using ASN.1 [X.680]. The term
- "BER-encoded" means the element is to be encoded using the Basic
- Encoding Rules [X.690] under the restrictions detailed in Section 5.1
- of [RFC2251].
+ 8.1. Object Identifier 26
+ 8.2. LDAP Protocol Mechanism
+ 8.3. LDAP Result Codes
+ 9. Acknowledgments
+ 10. Normative References 27
+ 11. Informative References 28
+ 12. Authors' Addresses 29
+ Appendix A. CSN-based Implementation Considerations
+ Intellectual Property Rights 31
+ Full Copyright
1. Introduction
The Lightweight Directory Access Protocol (LDAP) [RFC3377] provides a
- mechanism, the search operation [RFC2251], to allow a client to
- request the return of content matching a complex set of assertions and
- for the server to return this content, subject to access control and
- other restrictions, to the client. However, short of repeating a
- search operation each time a new copy needed, LDAP does not provide an
- effective and efficient mechanism for maintaining synchronized copies
- of directory content.
-
- This document defines the LDAP Content Synchronization operation, or
- Sync operation for short, which allows a client to maintain a
- synchronized shadow copy of a fragment of a Directory Information Tree
- (DIT). The Sync operation is defined as a set of controls and other
- protocol elements which extend the Search operation.
+ mechanism, the search operation [RFC2251], which allows a client to
+ request directory content matching a complex set of assertions and for
+ the server to return this content, subject to access control and other
+ restrictions, to the client. However, LDAP does not provide (despite
+ the introduction of numerous extensions in this area) an effective and
+ efficient mechanism for maintaining synchronized copies of directory
+ content. This document introduces a new mechanism specifically
+ designed to met the content synchronization requirements of
+ sophisticated directory applications.
+
+ This document defines the LDAP Content Synchronization Operation, or
+ Sync Operation for short, which allows a client to maintain a
+ synchronized copy of a fragment of a Directory Information Tree (DIT).
+ The Sync Operation is defined as a set of controls and other protocol
+ elements which extend the Search Operation.
1.1. Background
- Over the years, a number of directory synchronization approaches have
- been suggested. These approaches are inadequate for one or more of
- the following reasons:
+ Over the years, a number of content synchronization approaches have
+ been suggested for use in LDAP directory services. These approaches
+ are inadequate for one or more of the following reasons:
- 1) do not ensure a reasonable level of convergence;
- 2) fail to detect that convergence cannot be achieved (without
+ - fail to ensure a reasonable level of convergence;
+ - fail to detect that convergence cannot be achieved (without
+ reload);
+ - require pre-arranged synchronization agreements;
+ - require the server to maintain histories of past changes to DIT
+ content and/or meta information;
+ - require the server to maintain synchronization state on a per
+ client basis; and/or
+ - are overly chatty.
-Zeilenga LDAP Content Sync Operation [Page 2]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+Zeilenga LDAP Content Sync Operation [Page 3]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- reload);
- 3) require pre-arranged synchronization agreements;
- 4) require the server to maintain synchronization state on a per
- client basis;
- 5) require the server to maintain histories of past changes to DIT
- content and/or meta information; and/or
- 6) are overly chatty.
- The Sync operation provides eventual convergence of synchronized
- content when possible and, when not, notification that content reload
+ The Sync Operation provides eventual convergence of synchronized
+ content when possible and, when not, notification that a full reload
is required.
- The Sync operation does not require pre-arranged synchronization
+ The Sync Operation does not require pre-arranged synchronization
agreements.
- The Sync operation does not require servers to maintain
- synchronization state on a per user basis.
-
- The Sync operation does not require servers to maintain any history of
- past changes to the DIT or to meta information. While histories
- (e.g., change logs, tombstones, DIT snapshots) may be used in the
- implementation of the Sync operation, the operation may be implemented
- using purely state-based approaches.
-
- As the Sync operation does not require servers to maintain any
- histories of past changes, it can be implemented in environments where
- it is not feasible to maintain such histories. Histories, if
- available, may be used by the server to reduce the number of messages
- generated and reduce their size.
-
- The Sync operation chattiness is reasonably bound.
+ The Sync Operation does not require servers to maintain nor to use any
+ history of past changes to the DIT or to meta information. However,
+ servers may maintain and use histories (e.g., change logs, tombstones,
+ DIT snapshots) to reduce the number of messages generated and to
+ reduce their size. As it is not always feasible to maintain and use
+ histories, the operation may be implemented using purely (current)
+ state-based approaches. The Sync Operation allows use of either the
+ state-based approach or the history-based approach in an operation by
+ operation basis to balance the size of history and the amount of
+ traffic. The Sync Operation also allows the combined use of the
+ state-based and the history-based approaches.
+
+ The Sync Operation does not require servers to maintain
+ synchronization state on a per client basis. However, servers may
+ maintain and use per client state information to reduce the number of
+ messages generated and the size of such messages.
+
+ A synchronization mechanism can be considered overly chatty when
+ synchronization traffic is not reasonably bounded. The Sync Operation
+ traffic is bounded by the size of updated (or new) entries and the
+ number of unchanged entries in the content. The operation is designed
+ to avoid full content exchanges even in the case that the history
+ information available to the server is insufficient to determine the
+ client's state. The operation is also designed to avoid transmission
+ of out-of-content history information, as its size is not bounded by
+ the content and it is not always feasible to transmit such history
+ information due to security reasons.
+
+ This document includes a number of non-normative appendices providing
+ additional information to server implementors.
1.2. Intended Usage
- The Sync operation is intended to be used in applications requiring
- eventual-convergent content synchronization. Upon completion of each
- synchronization phase of the operation, all information to construct
- an synchronized shadow copy of the content has been provided to the
- client or the client has been notified that a complete content reload
- is necessary. Excepting for transient inconsistencies due to
- concurrent operation (or other) processing at the server, the shadow
- copy is an accurate reflection of the content held by the server.
- Each inconsistency is transient in that it will be corrected during
- subsequent synchronization requests.
-
- Possible uses include:
- - White page service applications may use the Sync operation to
+ The Sync Operation is intended to be used in applications requiring
+ eventually-convergent content synchronization. Upon completion of
+ each synchronization stage of the operation, all information to
+ construct a synchronized client copy of the content has been provided
+ to the client or the client has been notified that a complete content
+ reload is necessary. Except for transient inconsistencies due to
+ concurrent operation (or other) processing at the server, the client
-Zeilenga LDAP Content Sync Operation [Page 3]
+Zeilenga LDAP Content Sync Operation [Page 4]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- maintain current shadow copy of a DIT fragment. For example, an
- mail user agent which use the sync operation to maintain a local
- copy of an enterprise address book.
+ copy is an accurate reflection of the content held by the server.
+ Transient inconsistencies will be resolved by subsequent
+ synchronization operations.
- - Meta-information engines may use the Sync operation to maintain a
- shadow copy of a DIT fragment.
+ Possible uses include:
+ - White page service applications may use the Sync Operation to
+ maintain current copy of a DIT fragment. For example, a mail user
+ agent which uses the sync operation to maintain a local copy of an
+ enterprise address book.
+
+ - Meta-information engines may use the Sync Operation to maintain a
+ copy of a DIT fragment.
- - Caching proxy services may use the Sync operation to maintain a
+ - Caching proxy services may use the Sync Operation to maintain a
coherent content cache.
- Lightweight master-slave replication between heterogeneous
- directory servers. For example, the Sync operation can be used by
+ directory servers. For example, the Sync Operation can be used by
a slave server to maintain a shadow copy of a DIT fragment.
-
- Note: The International Telephone Union (ITU) has defined the X.500
- Directory Synchronization Protocol [X.525] which may be used for
- master-slave replication between LDAP servers. Other
- experimental LDAP replication protocols exist. The Sync
- operation should be viewed as complementary to these replication
- protocols.
+ (Note: The International Telephone Union (ITU) has defined the
+ X.500 Directory [X.500] Information Shadowing Protocol (DISP)
+ [X.525] which may be used for master-slave replication between
+ directory servers. Other experimental LDAP replication protocols
+ also exist.)
This protocol is not intended to be used in applications requiring
transactional data consistency.
- As this protocol transfers all visible values of entries upon change
- instead of change deltas, this protocol is not appropriate for
- bandwidth-challenged applications or deployments.
+ As this protocol transfers all visible values of entries belonging to
+ the content upon change instead of change deltas, this protocol is not
+ appropriate for bandwidth-challenged applications or deployments.
1.3. Overview
- This section provides an overview of basis ways the Sync operation can
- be used to maintain a synchronized shadow copy of a DIT fragment.
+ This section provides an overview of basic ways the Sync Operation can
+ be used to maintain a synchronized client copy of a DIT fragment.
- Polling for Changes: refreshOnly mode
- Listening for Changes: refreshAndPersist mode
1.3.1. Polling for Changes (refreshOnly)
- To obtain its initial shadow copy, the client issues a Sync request: a
+ To obtain its initial client copy, the client issues a Sync request: a
search request with the Sync Request Control with mode set to
refreshOnly. The server, much like it would with a normal search
operation, returns (subject to access controls and other restrictions)
- the content matching the search criteria (baseObject, scope, filter).
- Additionally, with each entry returned, the server provides a Sync
- State control indicating state add. This control contains the
- Universally Unique Identifier (UUID) [UUID] of the entry. Unlike
-Zeilenga LDAP Content Sync Operation [Page 4]
+Zeilenga LDAP Content Sync Operation [Page 5]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- Distinguished Names (DNs), which may change over time, an entry's
- UUIDs are stable. The initial content is followed by a
- searchResultDone with a Sync Done control. The Sync Done control
+ the content matching the search criteria (baseObject, scope, filter,
+ attributes). Additionally, with each entry returned, the server
+ provides a Sync State Control indicating state add. This control
+ contains the Universally Unique Identifier (UUID) [UUID] of the entry
+ [EntryUUID]. Unlike the Distinguished Name (DN), which may change
+ over time, an entry's UUID is stable. The initial content is followed
+ by a SearchResultDone with a Sync Done Control. The Sync Done Control
provides a syncCookie. The syncCookie represents session state.
- To poll for updates to the shadow copy, the client reissues the Sync
- operation with the syncCookie previously returned. The server, much
+ To poll for updates to the client copy, the client reissues the Sync
+ Operation with the syncCookie previously returned. The server, much
as it would with a normal search operation, determines which content
would be returned as if the operation was a normal search operation.
However, using the syncCookie as an indicator of what content the
client was sent previously, the server sends copies of entries which
- have changed with a Sync State control indicating state add. For each
- unchanged entry, the server sends an empty entry (e.g., no attributes)
- with a Sync State control indicating state present. The set of
- updates is followed by a searchResultDone with a Sync Done control.
+ have changed with a Sync State Control indicating state add. For each
+ changed entry, all (modified or unmodified) attributes belonging to
+ the content are sent.
+
+ The server may perform either or both of the two distinct
+ synchronization phases which are distinguished by how to synchronize
+ entries deleted from the content: the present and the delete phases.
+ When the server uses a single phase for the refresh stage, each phase
+ is marked as ended by a SearchResultDone with a Sync Done Control. A
+ present phase is identified by a FALSE refreshDeletes value in the
+ Sync Done Control. A delete phase is identified by a TRUE
+ refreshDeletes value. The present phase may be followed by a delete
+ phase. The two phases are delimited by a refreshPresent Sync Info
+ Message having a FALSE refreshDone value. In the case that both the
+ phases are used, the present phase is used to bring the client copy up
+ to the state at which the subsequent delete phase can begin.
+
+ In the present phase, the server sends an empty entry (i.e., no
+ attributes) with a Sync State Control indicating state present for
+ each unchanged entry.
+
+ The delete phase may be used when the server can reliably determine
+ which entries in the prior client copy are no longer present in the
+ content and the number of such entries is less than or equal to the
+ number of unchanged entries. In the delete mode, the server sends an
+ empty entry with a Sync State Control indicating state delete for each
+ entry which is no longer in the content, instead of returning an empty
+ entry with state present for each present entry.
+
+ The server may send syncIdSet Sync Info Messages containing the set of
+ UUIDs of either unchanged present entries or deleted entries, instead
+ of sending multiple individual messages. If refreshDeletes of
+ syncIdSet is set to FALSE, the UUIDs of unchanged present entries are
- If the server can reliably determine which entries in the prior shadow
- copy are no longer present in the content and the number of such
- entries is less than or equal to the number of unchanged entries, the
- server may, instead of returning an empty entry with state present for
- each present entry, send an empty entry with state delete for each
- entry which is no longer in the content. Also, the Sync Done control
- refreshDeletes is set to TRUE to indicate to the client that this
- method was used. This field is FALSE otherwise.
- The synchronized shadow copy of the DIT fragment is constructed by the
+
+Zeilenga LDAP Content Sync Operation [Page 6]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ contained in the syncUUIDs set; if refreshDeletes of syncIdSet is set
+ to TRUE, the UUIDs of the entries no longer present in the content are
+ contained in the syncUUIDs set. An optional cookie can be included in
+ the syncIdSet to represent the state of the content after
+ synchronizing the presence or the absence of the entries contained in
+ the syncUUIDs set.
+
+ The synchronized copy of the DIT fragment is constructed by the
client.
- If refreshDeletes is FALSE, the new copy includes all changed entries
- returned by the reissued Sync operation as well as all unchanged
- entries identified as being present by the reissued Sync operation,
- but whose content is provided by the previous Sync operation. The
- unchanged entries not identified as being present are deleted from the
- shadow content. They had been either deleted, moved, or otherwise
- scoped-out from the content.
+ If refreshDeletes of syncDoneValue is FALSE, the new copy includes all
+ changed entries returned by the reissued Sync Operation as well as all
+ unchanged entries identified as being present by the reissued Sync
+ Operation, but whose content is provided by the previous Sync
+ Operation. The unchanged entries not identified as being present are
+ deleted from the client content. They had been either deleted, moved,
+ or otherwise scoped-out from the content.
- If refreshDeletes is TRUE, the new copy includes all changed entries
- returned by the reissued Sync operation as well as all other entries
- of the previous copy except those which were identified as having been
- deleted from the content.
+ If refreshDeletes of syncDoneValue is TRUE, the new copy includes all
+ changed entries returned by the reissued Sync Operation as well as all
+ other entries of the previous copy except for those which are
+ identified as having been deleted from the content.
The client can, at some later time, re-poll for changes to this
- synchronized shadow copy.
+ synchronized client copy.
1.3.2. Listening for Changes (refreshAndPersist)
Polling for changes can be expensive in terms of server, client, and
+ network resources. The refreshAndPersist mode allows for active
+ updates of changed entries in the content.
+ By selecting the refreshAndPersist mode, the client requests the
+ server to send updates of entries that are changed after the initial
+ refresh content is determined. Instead of sending a SearchResultDone
+ Message as in polling, the server sends a Sync Info Message to the
+ client indicating that the refresh stage is complete and then enters
+ the persist stage. After receipt of this Sync Info Message, the
+ client will construct a synchronized copy as described in Section
+ 1.3.1.
+ The server may then send change notifications as the result of the
+ original Sync search request which now remains persistent in the
+ server. For entries to be added to the returned content, the server
+ sends a SearchResultEntry (with attributes) with a Sync State Control
+ indicating state add. For entries to be deleted from the content, the
+ server sends a SearchResultEntry containing no attributes and a Sync
-Zeilenga LDAP Content Sync Operation [Page 5]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
- network resources. The refreshAndPersist mode allows for active
- updates of changed entries in the content.
+Zeilenga LDAP Content Sync Operation [Page 7]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- By selecting the refreshAndPersist mode, the client requests the
- server to send updates of entries that are changed after the the
- initial refresh content is determined. Instead of sending a
- searchResultDone message as described above, the server sends a Sync
- Info message to the client indicating that refresh phase is complete
- and then enters persist phase. After receipt of this Sync Info
- message, the client will have a synchronized shadow copy as described
- above.
-
- The server may then send change notifications. For entries to be
- added to the returned content, the server sends a searchResultEntry
- (with attributes) with a Sync State control indicating state add. For
- entries to be deleted from the content, the server sends a
- searchResultEntry containing with no attributes and a Sync State
- control indicating state delete. To modify entries in the return
- content, the server sends a searchResultEntry (with attributes) with a
- Sync State control indicating state modify. Upon modification of an
- entry, all (modified or unmodified) attributes belonging to the
- content are sent.
+
+ State Control indicating state delete. For entries to be modified in
+ the return content, the server sends a SearchResultEntry (with
+ attributes) with a Sync State Control indicating state modify. Upon
+ modification of an entry, all (modified or unmodified) attributes
+ belonging to the content are sent.
Note that renaming an entry of the DIT may cause an add state change
where the entry is renamed into the content, a delete state change
where the entry is renamed out of the content, and a modify state
change where the entry remains in the content. Also note that a
- modification of an entry of the DIT may cause a add, delete, or modify
- state change to the content.
+ modification of an entry of the DIT may cause an add, delete, or
+ modify state change to the content.
Upon receipt of a change notification, the client updates its copy of
the content.
If the server desires to update the syncCookie during the persist
- stage, it may include the syncCookie any Sync State control or Sync
- Info message returned.
+ stage, it may include the syncCookie in any Sync State Control or Sync
+ Info Message returned.
The operation persists until canceled [CANCEL] by the client or
- terminated by the server. A Sync Done control may be attached to
- searchResultDone message to provide a new syncCookie.
+ terminated by the server. A Sync Done Control shall be attached to
+ SearchResultDone Message to provide a new syncCookie.
+
+
+1.4. Conventions
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+ document are to be interpreted as described in BCP 14 [RFC2119].
+
+ Protocol elements are described using ASN.1 [X.680] with implicit
+ tags. The term "BER-encoded" means the element is to be encoded using
+ the Basic Encoding Rules [X.690] under the restrictions detailed in
+ Section 5.1 of [RFC2251].
2. Elements of the Sync Operation
The Sync Operation is defined as an extension to the LDAP Search
Operation [RFC2251] where the directory user agent (DUA or client)
- submits a SearchRequest message with a Sync Request control and the
+ submits a SearchRequest Message with a Sync Request Control and the
directory system agent (DSA or server) responses with zero or more
+ SearchResultEntry Messages, each with a Sync State Control; zero or
+ more SearchResultReference Messages, each with a Sync State Control;
+ zero or more Sync Info Intermediate Response Messages; and a
+ SearchResultDone Message with a Sync Done Control.
-Zeilenga LDAP Content Sync Operation [Page 6]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+Zeilenga LDAP Content Sync Operation [Page 8]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- SearchResultEntry messages, each with a Sync State control; zero or
- more SearchResultReference messages, each with a Sync State control;
- zero or more Sync Intermediate Response messages; and a
- searchResultDone message with a Sync Done control.
To allow clients to discover support for this operation, servers
- implementing this operation SHOULD publish the IANA-ASSIGNED-OID.1 as
- a value of supportedControl root DSE attribute.
+ implementing this operation SHOULD publish the
+ 1.3.6.1.4.1.4203.1.9.1.1 as a value of 'supportedControl' attribute
+ [RFC2252] of the root DSA-specific entry (DSE). A server MAY choose
+ to advertise this extension only when the client is authorized to use
+ it.
-2.1 Common ASN.1 elements
+2.1 Common ASN.1 Elements
2.1.1 syncUUID
- The syncUUID is a notational convenience to indicate that, while the
- syncUUID type is encoded as an OCTET STRING, its value is restricted
- to the string representation of an Universally Unique Identifier
- (UUID) defined in [UUID].
+ The syncUUID data type is an OCTET STRING holding a 128-bit (16-octet)
+ Universally Unique Identifier (UUID) [UUID].
- syncUUID ::= OCTET STRING
+ syncUUID ::= OCTET STRING (SIZE(16))
+ -- constrained to UUID
- 2.1.2 syncCookie
+2.1.2 syncCookie
The syncCookie is a notational convenience to indicate that, while the
syncCookie type is encoded as an OCTET STRING, its value is an opaque
value containing information about the synchronization session and its
state. Generally, the session information would include a hash of the
- operation parameters which the server requires not be changed; the
- synchronization state information includes a commit (log) sequence
- number, a change sequence number, or a time stamp; and a digital
- signature for detection of tampering.
+ operation parameters which the server requires not be changed and the
+ synchronization state information would include a commit (log)
+ sequence number, a change sequence number, or a time stamp. For
+ convenience of description, the term no cookie refers either to null
+ cookie or to a cookie with pre-initialized synchronization state.
syncCookie ::= OCTET STRING
2.2 Sync Request Control
The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2]
- where the controlType is the object identifier IANA-ASSIGNED-OID.1 and
- the controlValue, an OCTET STRING, contains a BER-encoded
- syncRequestValue. The criticality field is either TRUE or FALSE.
+ where the controlType is the object identifier
+ 1.3.6.1.4.1.4203.1.9.1.1 and the controlValue, an OCTET STRING,
+ contains a BER-encoded syncRequestValue. The criticality field is
+ either TRUE or FALSE.
syncRequestValue ::= SEQUENCE {
mode ENUMERATED {
-- 0 unused
refreshOnly (1),
-- 2 reserved
+ refreshAndPersist (3)
-Zeilenga LDAP Content Sync Operation [Page 7]
+Zeilenga LDAP Content Sync Operation [Page 9]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- refreshAndPersist (3)
},
- cookie syncCookie OPTIONAL
+ cookie syncCookie OPTIONAL,
+ reloadHint BOOLEAN DEFAULT FALSE
}
- The Sync Request Control is only applicable to the searchRequest
- message.
+ The Sync Request Control is only applicable to the SearchRequest
+ Message.
2.3 Sync State Control
The Sync State Control is an LDAP Control [RFC2251, Section 4.1.2]
- where the controlType is the object identifier IANA-ASSIGNED-OID.2 and
- the controlValue, an OCTET STRING, contains a BER-encoded
- syncStateValue. The criticality is FALSE.
+ where the controlType is the object identifier
+ 1.3.6.1.4.1.4203.1.9.1.2 and the controlValue, an OCTET STRING,
+ contains a BER-encoded syncStateValue. The criticality is FALSE.
syncStateValue ::= SEQUENCE {
state ENUMERATED {
delete (3)
},
entryUUID syncUUID,
- cookie syncCookie OPTIONAL
+ cookie syncCookie OPTIONAL
}
The Sync State Control is only applicable to SearchResultEntry and
- SearchResultReference messages.
+ SearchResultReference Messages.
2.4 Sync Done Control
The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2]
- where the controlType is the object identifier IANA-ASSIGNED-OID.3 and
- the controlValue contains a BER-encoded syncDoneValue. The
- criticality is FALSE (and hence absent).
+ where the controlType is the object identifier
+ 1.3.6.1.4.1.4203.1.9.1.3 and the controlValue contains a BER-encoded
+ syncDoneValue. The criticality is FALSE (and hence absent).
syncDoneValue ::= SEQUENCE {
- cookie syncCookie OPTIONAL,
- refreshDeletes BOOLEAN DEFAULT FALSE,
+ cookie syncCookie OPTIONAL,
+ refreshDeletes BOOLEAN DEFAULT FALSE
}
- The Sync Done Control is only applicable to SearchResultDone message.
+ The Sync Done Control is only applicable to SearchResultDone Message.
2.5 Sync Info Message
-Zeilenga LDAP Content Sync Operation [Page 8]
+Zeilenga LDAP Content Sync Operation [Page 10]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
The Sync Info Message is an LDAP Intermediate Response Message
[LDAPIRM] where responseName is the object identifier
- IANA-ASSIGNED-OID.4 and responseValue contains a BER-encoded
+ 1.3.6.1.4.1.4203.1.9.1.4 and responseValue contains a BER-encoded
syncInfoValue. The criticality is FALSE (and hence absent).
syncInfoValue ::= CHOICE {
- newcookie [0] syncCookie,
- refreshDone [1] SEQUENCE {
- cookie syncCookie OPTIONAL,
- refreshDeletes BOOLEAN DEFAULT FALSE
- }
+ newcookie [0] syncCookie,
+ refreshDelete [1] SEQUENCE {
+ cookie syncCookie OPTIONAL,
+ refreshDone BOOLEAN DEFAULT TRUE
+ },
+ refreshPresent [2] SEQUENCE {
+ cookie syncCookie OPTIONAL,
+ refreshDone BOOLEAN DEFAULT TRUE
+ },
+ syncIdSet [3] SEQUENCE {
+ cookie syncCookie OPTIONAL,
+ refreshDeletes BOOLEAN DEFAULT FALSE,
+ syncUUIDs SET OF syncUUID
+ }
}
2.6 Sync Result Codes
- The following LDAP resultCodes [RFC2251] are defined:
+ The following LDAP resultCode [RFC2251] is defined:
- syncRefreshRequired (IANA-ASSIGNED-CODE-0)
+ e-syncRefreshRequired (IANA-ASSIGNED-CODE)
3. Content Synchronization
- The Sync Operation is invoked by the client sending a searchRequest
- message with a Sync Request Control.
+ The Sync Operation is invoked by the client sending a SearchRequest
+ Message with a Sync Request Control.
- The absence of a cookie indicates a request for initial content while
- the presence of a cookie indicates a request for content update.
- Synchronization Sessions are discussed in Section 3.1. Content
- Determination is discussed in Section 3.2.
+ The absence of a cookie or an initialized synchronization state in a
+ cookie indicates a request for initial content while the presence of a
+ cookie representing a state of a client copy indicates a request for
+ content update. Synchronization Sessions are discussed in Section
+ 3.1. Content Determination is discussed in Section 3.2.
The mode is either refreshOnly or refreshAndPersist. The refreshOnly
- and refreshAndPersist modes are discussed in Section 3.3 and 3.4,
- respectively. The refreshOnly mode consists only of a refresh stage,
- while the refreshAndPersist mode consists of a refresh stage and a
- subsequent persist stage.
+ and refreshAndPersist modes are discussed in Section 3.3 and Section
+ 3.4, respectively. The refreshOnly mode consists only of a refresh
+ stage, while the refreshAndPersist mode consists of a refresh stage
+ and a subsequent persist stage.
-3.1. Synchronization Session
- A sequence of Sync Operations where the last cookie returned by a
- operation is provided by the client in the next operation are said to
- belong to the same Synchronization Session.
- The client MUST specify the same content controlling parameters (see
- Section 3.5) in each Search Request of the session. The client SHOULD
- also issue each Sync request of a session under the same
- authentication and authorization associations with equivalent
+Zeilenga LDAP Content Sync Operation [Page 11]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
-Zeilenga LDAP Content Sync Operation [Page 9]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+3.1. Synchronization Session
+ A sequence of Sync Operations where the last cookie returned by the
+ server for one operation is provided by the client in the next
+ operation are said to belong to the same Synchronization Session.
- integrity and confidential protections. If the server does not
- recognize the request cookie or the request is made under different
- associations or inequivalent protections, the server SHALL process the
- request as if no cookie had been provided.
+ The client MUST specify the same content controlling parameters (see
+ Section 3.5) in each Search Request of the session. The client SHOULD
+ also issue each Sync request of a session under the same
+ authentication and authorization associations with equivalent
+ integrity and protections. If the server does not recognize the
+ request cookie or the request is made under different associations or
+ non-equivalent protections, the server SHALL return the initial
+ content as if no cookie had been provided or return an empty content
+ with the e-syncRefreshRequired LDAP result code. The decision between
+ the return of the initial content and the return of the empty content
+ with the e-syncRefreshRequired result code MAY be based on reloadHint
+ in the Sync Request Control from the client. If the server recognizes
+ the request cookie as representing empty or initial synchronization
+ state of the client copy, the server SHALL return the initial content.
A Synchronization Session may span multiple LDAP sessions between the
client and the server. The client SHOULD issue each Sync request of a
- session to the same server.
+ session to the same server. (Note: Shadowing considerations are
+ discussed in Section 6.)
3.2. Content Determination
The content to be provided is determined by parameters of the Search
Request, as described in [RFC2251], and possibly other controls. The
- same content SHOULD be used in each Sync request of a session. If
- different content is requested and the server is unwilling or unable
- to process the request, the server SHALL process the request as if no
- cookie had been provided.
+ same content parameters SHOULD be used in each Sync request of a
+ session. If different content is requested and the server is
+ unwilling or unable to process the request, the server SHALL return
+ the initial content as if no cookie had been provided or return an
+ empty content with the e-syncRefreshRequired LDAP result code. The
+ decision between the return of the initial content and the return of
+ the empty content with the e-syncRefreshRequired result code MAY be
+ based on reloadHint in the Sync Request Control from the client.
The content may not necessarily include all entries or references
which would be returned by a normal search operation nor, for those
entries included, not all attributes returned by a normal search.
- Where the server is unwilling or unable to provide synchronization for
- an attribute for a set of entries, the server MUST treat all filter
- components matching against these attribute as Undefined and MUST NOT
- return the attribute in searchResultEntry responses.
+ When the server is unwilling or unable to provide synchronization for
+ any attribute for a set of entries, the server MUST treat all filter
+ components matching against these attributes as Undefined and MUST NOT
+ return these attributes in SearchResultEntry responses.
+
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 12]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
Servers SHOULD support synchronization for all non-collective
- user-applications attributes for all entries.
+ user-application attributes for all entries.
The server may also return continuation references to other servers or
to itself. The latter is allowed as the server may partition the
entries it holds into separate synchronization contexts.
- The client may chase all or some of these continuations, each in a
- separate LDAP session.
+ The client may chase all or some of these continuations, each as a
+ separate content synchronization session.
-3.3. refreshOnly mode
+3.3. refreshOnly Mode
- A Sync request with mode refreshOnly and no cookie is a poll for
- initial content. A Sync request with mode refreshOnly and cookie is a
- poll for content update.
+ A Sync request with mode refreshOnly and with no cookie is a poll for
+ initial content. A Sync request with mode refreshOnly and with a
+ cookie representing a synchronization state is a poll for content
+ update.
3.3.1. Initial Content Poll
Upon receipt of the request, the server provides the initial content
+ using a set of zero or more SearchResultEntry and
+ SearchResultReference Messages followed by a SearchResultDone Message.
-
-
-Zeilenga LDAP Content Sync Operation [Page 10]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
- using a set of zero or more searchResultEntry and
- searchResultReference messages followed by a searchResultDone message.
-
- Each searchResultEntry message SHALL include a Sync State control of
+ Each SearchResultEntry Message SHALL include a Sync State Control of
state add, entryUUID containing the entry's UUID, and no cookie. Each
- searchResultReference message SHALL include a Sync State control of
+ SearchResultReference Message SHALL include a Sync State Control of
state add, entryUUID containing the UUID associated with the reference
- (normally the referral [RFC3296] object's entryUUID), and no cookie.
- The searchResultDone message SHALL include a Sync Done control. The
- refreshDeletes SHALL be FALSE.
+ (normally the UUID of the associated named referral [RFC3296] object),
+ and no cookie. The SearchResultDone Message SHALL include a Sync Done
+ Control having refreshDeletes set to FALSE.
A resultCode value of success indicates the operation successfully
completed. Otherwise, the result code indicates the nature of
- failure.
+ failure. The server may return e-syncRefreshRequired result code on
+ the initial content poll if it is safe to do so when it is unable to
+ perform the operation due to various reasons. reloadHint is set to
+ FALSE in the SearchRequest Message requesting the initial content
+ poll.
- If the operation is successful, a cookie SHOULD be returned for use in
- subsequent Sync operations.
+ If the operation is successful, a cookie representing the
+ synchronization state of the current client copy SHOULD be returned
+ for use in subsequent Sync Operations.
3.3.2. Content Update Poll
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 13]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
Upon receipt of the request the server provides the content refresh
- using a set of zero or more searchResultEntry and
- searchResultReference messages followed by a searchResultDone message.
+ using a set of zero or more SearchResultEntry and
+ SearchResultReference Messages followed by a SearchResultDone Message.
The server is REQUIRED to either:
a) provide the sequence of messages necessary for eventual
copy,
b) treat the request as an initial content request (e.g., ignore
- the cookie),
+ the cookie or the synchronization state represented in the
+ cookie),
+
+ c) indicate that the incremental convergence is not possible by
+ returning e-syncRefreshRequired,
+
+ d) return a resultCode other than success or
+ e-syncRefreshRequired.
+
+ A Sync Operation may consist of a single present phase, a single
+ delete phase, or a present phase followed by a delete phase.
+
+ In each phase, for each entry or reference which has been added to the
+ content or been changed since the previous Sync Operation indicated by
+ the cookie, the server returns a SearchResultEntry or
+ SearchResultReference Message, respectively, each with a Sync State
+ Control consisting of state add, entryUUID containing the UUID of the
+ entry or reference, and no cookie. Each SearchResultEntry Message
+ represents the current state of a changed entry. Each
+ SearchResultReference Message represents the current state of a
+ changed reference.
+
+ In the present phase, for each entry which has not been changed since
+ the previous Sync Operation, an empty SearchResultEntry is returned
+ whose objectName reflects the entry's current DN, the attributes field
+ is empty, and a Sync State Control consisting of state present,
+ entryUUID containing the UUID of the entry, and no cookie. For each
+ reference which has not been changed since the previous Sync
+ Operation, an empty SearchResultReference containing an empty SEQUENCE
+ OF LDAPURL is returned with a Sync State Control consisting of state
+ present, entryUUID containing the UUID of the entry, and no cookie.
+ No messages are sent for entries or references which are no longer in
+ the content.
- c) indicate that convergence is not possible by returning
- syncRefreshRequired,
+ Multiple empty entries with a Sync State Control of state present
+ SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
+ value with refreshDeletes set to FALSE. syncUUIDs contain a set of
+ UUIDs of the entries and references unchanged since the last Sync
- d) return a resultCode other than success or syncRefreshRequired.
- For each entry or reference added to the content or was changed since
- the previous Sync operation indicated by the cookie, the server
- returns a searchResultEntry or searchResultReference message,
- respectively, each with a Sync State cookie of state add, entryUUID
- containing the UUID of the entry or reference, and no cookie. Each
- searchResultEntry message represents the current state of a changed
- entry. Each SearchResultReference message represents the current
- state of a changed reference.
- For each entry which has not been changed since the previous Sync
+Zeilenga LDAP Content Sync Operation [Page 14]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ Operation. syncUUIDs may be empty. The Sync Info Message of
+ syncIdSet may contain cookie to represent the state of the content
+ after performing the synchronization of the entries in the set.
+
+ In the delete phase, for each entry no longer in the content, the
+ server returns a SearchResultEntry whose objectName reflects a past DN
+ of the entry or is empty, the attributes field is empty, and a Sync
+ State Control consisting of state delete, entryUUID containing the
+ UUID of the deleted entry, and no cookie. For each reference no
+ longer in the content, a SearchResultReference containing an empty
+ SEQUENCE OF LDAPURL is returned with a Sync State Control consisting
+ of state delete, entryUUID containing the UUID of the deleted
+ reference, and no cookie.
+
+ Multiple empty entries with a Sync State Control of state delete
+ SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
+ value with refreshDeletes set to TRUE. syncUUIDs contain a set of
+ UUIDs of the entries and references which has been deleted from the
+ content since the last Sync Operation. syncUUIDs may be empty. The
+ Sync Info Message of syncIdSet may contain cookie to represent the
+ state of the content after performing the synchronization of the
+ entries in the set.
+
+ When a present phase is followed by a delete phase, the two phases are
+ delimited by a Sync Info Message containing syncInfoValue of
+ refreshPresent, which may contain cookie representing the state after
+ completing the present phase. The refreshPresent contains refreshDone
+ which is always FALSE in the refreshOnly mode of Sync Operation
+ because it is followed by a delete phase.
+
+ If a Sync Operation consists of a single phase, each phase and hence
+ the Sync Operation are marked ended by a SearchResultDone Message with
+ Sync Done Control which SHOULD contain cookie representing the state
+ of the content after completing the Sync Operation. The Sync Done
+ Control contains refreshDeletes which is set to FALSE for the present
+ phase and set to TRUE for the delete phase.
+
+ If a Sync Operation consists of a present phase followed by a delete
+ phase, the Sync Operation are marked ended at the end of the delete
+ phase by a SearchResultDone Message with Sync Done Control which
+ SHOULD contain cookie representing the state of the content after
+ completing the Sync Operation. The Sync Done Control contains
+ refreshDeletes which is set to TRUE.
+
+ The client can specify whether it prefers to receive an initial
+ content by supplying reloadHint of TRUE or to receive a
+ e-syncRefreshRequired resultCode by supplying reloadHint of FALSE
+ (hence absent), in the case that the server determines that it is
-Zeilenga LDAP Content Sync Operation [Page 11]
+Zeilenga LDAP Content Sync Operation [Page 15]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
- operation, a searchResultEntry is returned whose objectName reflects
- the entry's current DN, the attributes field is empty, and a Sync
- State control of state present, entryUUID containing the UUID of the
- entry, and no cookie. For each reference which has not been changed
- since the previous Sync operation, a searchResultReference containing
- an empty SEQUENCE OF LDAPURL is returned with a Sync State control of
- state present, entryUUID containing the UUID of the entry, and no
- cookie. No messages are sent for entries or references which are no
- longer in content.
-
- As an alternative to sending messages for each entry and reference
- which has not been changed, the server may instead return the
- following. For each entry no longer in content, return a
- searchResultEntry whose objectName reflects a past DN of the entry or
- is empty, the attributes field is empty, and a Sync State control of
- state delete, entryUUID containing the UUID of the deleted entry, and
- no cookie. For each reference no longer in content, a
- searchResultReference containing an empty SEQUENCE OF LDAPURL is
- returned with a a Sync State control of state delete, entryUUID
- containing the UUID of the deleted reference, and no cookie.
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- A resultCode value of success indicates the operation successfully
- completed. Otherwise, the result code indicates the nature of
- failure.
- If the operation is successful, a cookie SHOULD be returned for use in
- subsequent Sync operations.
+ impossible or inefficient to achieve the eventual convergence by
+ continuing the current incremental synchronization thread.
+
+ A resultCode value of success indicates the operation is successfully
+ completed. A resultCode value of e-syncRefreshRequired indicates that
+ a full or partial refresh is needed. Otherwise, the result code
+ indicates the nature of failure. A cookie is provided in the Sync
+ Done Control for use in subsequent Sync Operations for incremental
+ synchronization.
-3.4. refreshAndPersist mode
+3.4. refreshAndPersist Mode
A Sync request with mode refreshAndPersist asks for initial content or
content update (during the refresh stage) followed by change
notifications (during the persist stage).
-3.4.1. refresh stage
+3.4.1. refresh Stage
The content refresh is provided as described in Section 3.3 excepting
- that successful completion of content refresh is indicated by sending
- a Sync Info with state refreshDone message instead of a
- SearchResultDone message with resultCode success. A cookie SHOULD be
- returned for use in subsequent Sync operations.
+ that the successful completion of content refresh is indicated by
+ sending a Sync Info Message of refreshDelete or refreshPresent with a
+ refreshDone value set to TRUE instead of a SearchResultDone Message
+ with resultCode success. A cookie SHOULD be returned in the Sync Info
+ Message to represent the state of the content after finishing the
+ refresh stage of the Sync Operation.
-3.4.2. persist stage
+3.4.2. persist Stage
Change notifications are provided during the persist stage.
-
-
-Zeilenga LDAP Content Sync Operation [Page 12]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
As updates are made to the DIT the server notifies the client of
- changes to the content. DIT updates may cause entries references to
- be added to the content, deleted from the content, or modify entries
- in the content. DIT updates may also cause references to be added,
- deleted, or modified within the content.
+ changes to the content. DIT updates may cause entries and references
+ to be added to the content, deleted from the content, or modified
+ within the content. DIT updates may also cause references to be
+ added, deleted, or modified within the content.
Where DIT updates cause an entry to be added to the content, the
- server provides a searchResultEntry message which represents the entry
+ server provides a SearchResultEntry Message which represents the entry
as it appears in the content. The message SHALL include a Sync State
- control with state of add, entryUUID containing the entry's UUID, and
+ Control with state of add, entryUUID containing the entry's UUID, and
an optional cookie.
Where DIT updates cause a reference to be added to the content, the
- server provides a searchResultReference message which represents the
+ server provides a SearchResultReference Message which represents the
reference in the content. The message SHALL include a Sync State
- control with state of add, entryUUID containing the UUID associated
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 16]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ Control with state of add, entryUUID containing the UUID associated
with the reference, and an optional cookie.
- Where DIT updates cause an entry to be modified in the content, the
- server provides a searchResultEntry message which represents the entry
- as it appears in the content. The message SHALL include a Sync State
- control with state of modify, entryUUID containing the entry's UUID,
- and an optional cookie.
+ Where DIT updates cause an entry to be modified within the content,
+ the server provides a SearchResultEntry Message which represents the
+ entry as it appears in the content. The message SHALL include a Sync
+ State Control with state of modify, entryUUID containing the entry's
+ UUID, and an optional cookie.
- Where DIT updates cause a reference to be modified in the content, the
- server provides a searchResultEntry message which represents the
+ Where DIT updates cause a reference to be modified within the content,
+ the server provides a SearchResultEntry Message which represents the
reference in the content. The message SHALL include a Sync State
- control with state of modify, entryUUID containing the UUID associated
+ Control with state of modify, entryUUID containing the UUID associated
with the reference, and an optional cookie.
Where DIT updates cause an entry to be deleted from the content, the
- server provides a searchResultReference message with an empty SEQUENCE
- OF LDAPURL. The message SHALL include a Sync State control with state
+ server provides a SearchResultReference Message with an empty SEQUENCE
+ OF LDAPURL. The message SHALL include a Sync State Control with state
of delete, entryUUID containing the UUID associated with the
reference, and an optional cookie.
Where DIT updates cause a reference to be deleted from the content,
- the server provides a searchResultEntry message with no attributes.
- The message SHALL include a Sync State control with state of delete,
+ the server provides a SearchResultEntry Message with no attributes.
+ The message SHALL include a Sync State Control with state of delete,
entryUUID containing the entry's UUID, and an optional cookie.
- With each of these messages, the server may provide a new cookie to be
- used in subsequent Sync operations. Additionally, the server may also
- return Sync Info messages of choice newCookie to provide a new cookie.
- The client SHOULD use newest (last) cookie it received from the server
- in subsequent Sync operations.
+ Multiple empty entries with a Sync State Control of state delete
+ SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
+ value with refreshDeletes set to TRUE. syncUUIDs contain a set of
+ UUIDs of the entries and references which has been deleted from the
+ content. The Sync Info Message of syncIdSet may contain cookie to
+ represent the state of the content after performing the
+ synchronization of the entries in the set.
+ With each of these messages, the server may provide a new cookie to be
+ used in subsequent Sync Operations. Additionally, the server may also
+ return Sync Info Messages of choice newCookie to provide a new cookie.
+ The client SHOULD use the newest (last) cookie it received from the
+ server in subsequent Sync Operations.
+3.5. Search Request Parameters
+ As stated in Section 3.1, the client SHOULD specify the same content
+ controlling parameters in each Search Request of the session. All
+ fields of the SearchRequest Message are considered content controlling
+ parameters except for sizeLimit and timeLimit.
-Zeilenga LDAP Content Sync Operation [Page 13]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-3.5. Search Request Parameters
- As stated in Section 3.1, the client SHOULD specify the same content
- controlling parameters (see Section 3.5) in each Search Request of the
- session. All fields of the SearchRequest message are considered
- content controlling parameters except for sizeLimit and timeLimit.
+Zeilenga LDAP Content Sync Operation [Page 17]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
-3.5.1. baseObject Issues
+3.5.1. baseObject
- As with the normal search operation, the refresh and persist phases
+ As with the normal search operation, the refresh and persist stages
are not isolated from DIT changes. It is possible that the entry
- referred to be the baseObject be deleted, renamed, or moved. It is
+ referred to by the baseObject is deleted, renamed, or moved. It is
also possible that alias object used in finding the entry referred to
by the baseObject is changed such that the baseObject refers to a
different entry.
If the DIT is updated during processing of the Sync Operation in a
- manner that causes the baseObject to no longer refers to any entry or
- changes which entry the baseObject refers to, the server SHALL return
- an appropriate non-success result code such as noSuchObject,
- aliasProblem, aliasDereferencingProblem, referral, or
- syncRefreshRequired.
+ manner that causes the baseObject to no longer refer to any entry or
+ in a manner that changes the entry the baseObject refers to, the
+ server SHALL return an appropriate non-success result code such as
+ noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or
+ e-syncRefreshRequired.
-3.5.2. derefAliases Issues
+3.5.2. derefAliases
This operation does not support alias dereferencing during searching.
The client SHALL specify neverDerefAliases or derefFindingBaseObj for
- the searchRequest derefAliases parameter. The server SHALL treat
+ the SearchRequest derefAliases parameter. The server SHALL treat
other values (e.g., derefInSearching, derefAlways) as protocol errors.
-3.5.3. sizeLimit Issues
+3.5.3. sizeLimit
- The sizeLimit applies only to entries (regardless of their syncState)
- returned during refreshOnly processing or the refresh stage of the
- refreshAndPersist processing.
+ The sizeLimit applies only to entries (regardless of their state in
+ Sync State Control) returned during the refreshOnly operation or the
+ refresh stage of the refreshAndPersist operation.
-3.5.4. timeLimit Issues
+3.5.4. timeLimit
- For a refreshOnly Sync operation, the timeLimit applies to the whole
+ For a refreshOnly Sync Operation, the timeLimit applies to the whole
operation. For a refreshAndPersist operation, the timeLimit applies
- to processing up to and including generating the Sync Info with state
- refreshDone message.
+ only to the refresh stage including the generation of the Sync Info
+ Message with a refreshDone value of TRUE.
+3.5.5. filter
+ The client SHOULD avoid filter assertions which apply to the values of
+ the attributes likely to be considered by the server as ones holding
+ meta-information. See Section 4.
-Zeilenga LDAP Content Sync Operation [Page 14]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
+3.6. objectName
-3.5.5. filter Issues
- The client SHOULD avoid filter assertions which apply to values of
- attributes likely to be considered by the server as holding meta-
- information. See section 4.
+Zeilenga LDAP Content Sync Operation [Page 18]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
-3.6. objectName Issues
- The Sync operation uses entryUUID values provided in the Sync State
- control as the primary keys to entries. The client MUST use these
+ The Sync Operation uses entryUUID values provided in the Sync State
+ Control as the primary keys to entries. The client MUST use these
entryUUIDs to correlate synchronization messages.
In some circumstances the DN returned may not reflect the entry's
current DN. In particular, when the entry is being deleted from the
- content, the server MAY provide an empty DN if the server does not
+ content, the server may provide an empty DN if the server does not
wish to disclose the entry's current DN (or, if deleted from the DIT,
the entry's last DN).
It should also be noted that the entry's DN may be viewed as meta
- information (see section 4.1).
+ information (see Section 4.1).
3.7. Canceling the Sync Operation
- Servers SHOULD implement the LDAP Cancel [CANCEL] operation and
- support cancellation of outstanding Sync operations as described here.
+ Servers MUST implement the LDAP Cancel [CANCEL] Operation and support
+ cancellation of outstanding Sync Operations as described here.
- To cancel an outstanding Sync Operation, the client SHOULD issue a
- Cancel operation [CANCEL]....
+ To cancel an outstanding Sync Operation, the client issues an LDAP
+ Cancel [CANCEL] Operation.
+ If at any time the server becomes unwilling or unable to continue
+ processing a Sync Operation, the server SHALL return a
+ SearchResultDone with a non-success resultCode indicating the reason
+ for the termination of the operation.
-3.7. Refresh Required
+ Whether the client or the server initiated the termination, the server
+ may provide a cookie in the Sync Done Control for use in subsequent
+ Sync Operations.
- In order to achieve the eventual-convergent synchronization, the
- server may terminate the Sync operation in refresh or persist stage by
- returning a syncRefreshRequired resultCode to the client. The client
- may then request a full reload (e.g., no cookie) instead of
- incremental synchronization in order to obtain a new copy of the
- content. In case that the client issues incremental synchronization
- requests between the issue of a syncRefreshRequired and that of a full
- reload, the server should send a syncRefreshRequired response again,
- but the client may receive one or more searchResultEntry responses
- before it receives the syncRefreshRequired response.
- The server may also choose to provide a full copy in the refresh stage
- (e.g., ignore the cookie) instead of providing an incremental refresh
- in order to achieve the eventual convergence.
+3.8. Refresh Required
+ In order to achieve the eventually-convergent synchronization, the
+ server may terminate the Sync Operation in the refresh or the persist
+ stage by returning a e-syncRefreshRequired resultCode to the client.
+ If no cookie is provided, a full refresh is needed. If a cookie
+ representing a synchronization state is provided in this response, an
+ incremental refresh is needed.
+ To obtain a full refresh, the client then issues a new synchronization
+ request with no cookie. To obtain an incremental reload, the client
+ issues a new synchronization with the provided cookie.
-Zeilenga LDAP Content Sync Operation [Page 15]
+ The server may choose to provide a full copy in the refresh stage
+ (e.g., ignore the cookie or the synchronization state represented in
+ the cookie) instead of providing an incremental refresh in order to
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 19]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+ achieve the eventual convergence.
+
+ The decision between the return of the initial content and the return
+ of the e-syncRefreshRequired result code may be based on reloadHint in
+ the Sync Request Control from the client.
+
In the case of persist stage Sync, the server returns the resultCode
- of syncRefreshRequired to the client to indicate that the client needs
- to issue a full reload operation (e.g., no cookie) in order to obtain
- a synchronized copy of the content.
+ of e-syncRefreshRequired to the client to indicate that the client
+ needs to issue a new Sync Operation in order to obtain a synchronized
+ copy of the content. If no cookie is provided, a full refresh is
+ needed. If a cookie representing a synchronization state is provided,
+ an incremental refresh is needed.
- The server may also return syncRefreshRequired if it determines that a
- refresh would be more efficient than sending all the messages required
- for convergence.
+ The server may also return e-syncRefreshRequired if it determines that
+ a refresh would be more efficient than sending all the messages
+ required for convergence.
+ It is noted that the client may receive one or more of
+ SearchResultEntry, SearchResultReference, and/or Sync Info Messages
+ before it receives SearchResultDone Message with the
+ e-syncRefreshRequired result code.
-3.8. Chattiness Considerations
+
+3.9. Chattiness Considerations
The server MUST ensure that the number of entry messages generated to
refresh the client content does not exceed the number of entries
presently in the content. While there is no requirement for servers
- to maintain historical information, if the server has sufficient
- history to allow it to reliably determine which entries in the prior
- shadow copy are no longer present in the content and the number of
- such entries is less than equal the number of unchanged entries, the
+ to maintain history information, if the server has sufficient history
+ to allow it to reliably determine which entries in the prior client
+ copy are no longer present in the content and the number of such
+ entries is less than or equal to the number of unchanged entries, the
server SHOULD generate delete entry messages instead of present entry
messages (see Section 3.3.2).
+ When the amount of history information maintained in the server is not
+ enough for the clients to perform infrequent refreshOnly Sync
+ Operations, it is likely that the server has incomplete history
+ information (e.g. due to truncation) by the time those clients connect
+ again.
+
+ The server SHOULD NOT resort to full reload when the history
+ information is not enough to generate delete entry messages. The
+ server SHOULD generate either present entry messages only or present
+ entry messages followed by delete entry messages to bring the client
+ copy to the current state. In the latter case, the present entry
+ messages bring the client copy to a state covered by the history
+ information maintained in the server.
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 20]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
The server SHOULD maintain enough (current or historical) state
- information (such as a context-wide last modify time stamp), to
- determine that no changes were made in the context since the content
- to refresh was provided and, and when no changes were made, generate
- zero delete entry messages instead of present messages.
+ information (such as a context-wide last modify time stamp) to
+ determine if no changes were made in the context since the content
+ refresh was provided and, and when no changes were made, generate zero
+ delete entry messages instead of present messages.
+
+ The server SHOULD NOT use the history information when its use does
+ not reduce the synchronization traffic or when its use can expose
+ sensitive information not allowed to be received by the client.
The server implementor should also consider chattiness issues which
- span multiple Sync operations of a session. As noted in Section 3.7,
- the server may return syncRefreshRequired if it determines that a
- refresh would be more efficient than continuing under the current
- operation.
+ span multiple Sync Operations of a session. As noted in Section 3.8,
+ the server may return e-syncRefreshRequired if it determines that a
+ reload would be more efficient than continuing under the current
+ operation. If reloadHint in the Sync Request is TRUE, the server may
+ initiate a reload without directing the client to request a reload.
The server SHOULD transfer a new cookie frequently to avoid having to
transfer information already provided to the client. Even where DIT
changes do not cause content synchronization changes to be
transferred, it may be advantageous to provide a new cookie using a
- Sync Info message. However, the server SHOULD avoid overloading the
- client or network with Sync Info messages.
+ Sync Info Message. However, the server SHOULD avoid overloading the
+ client or network with Sync Info Messages.
During persist mode, the server SHOULD coalesce multiple outstanding
messages updating the same entry. The server MAY delay generation of
short enough that the transient inconsistency induced by the delay is
corrected in a timely manner.
+ The server SHOULD use syncIdSet Sync Info Message when there are
+ multiple delete or present messages to reduce the amount of
+ synchronization traffic.
+ It is also noted that there may be many clients interested in a
+ particular directory change, and servers attempting to service all of
+ these at once may cause congestion on the network. The congestion
+ issues are magnified when the change requires a large transfer to each
+ interested client. Implementors and deployers of servers should take
+ steps to prevent and manage network congestion.
-Zeilenga LDAP Content Sync Operation [Page 16]
+
+3.10. Operation Multiplexing
+
+ The LDAP protocol model [RFC2251] allows operations to be multiplexed
+ over a single LDAP session. Clients SHOULD NOT maintain multiple LDAP
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 21]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ sessions with the same server. Servers SHOULD ensure that responses
+ from concurrently processed operations are interleaved fairly.
+
+ Clients SHOULD combine Sync Operations whose result set is largely
+ overlapping. This avoids having to return multiple messages, once for
+ each overlapping session, for changes to entries in the overlap.
+
+ Clients SHOULD NOT combine Sync Operations whose result sets are
+ largely non-overlapping with each other. This ensures that an event
+ requiring a e-syncRefreshRequired response can be limited to as few
+ result sets as possible.
4. Meta Information Considerations
As an entry's DN is constructed from its relative DN (RDN) and the
entry's parent's DN, it is often viewed as meta information.
- While renaming or moving a superior to an entry causes the entry's DN
- to change, that change SHOULD NOT, by itself, cause synchronization
- message to be sent for that entry. However, if renaming or moving of
- a superior could cause the entry to added or deleted from the content
- and, if so, appropriate synchronization messages should be generated
- to indicate this to the client.
+ While renaming or moving to a new superior causes the entry's DN to
+ change, that change SHOULD NOT, by itself, cause synchronization
+ messages to be sent for that entry. However, if the renaming or the
+ moving could cause the entry to be added or deleted from the content,
+ appropriate synchronization messages should be generated to indicate
+ this to the client.
- Where a server treats the entry's DN as meta information, the server
+ When a server treats the entry's DN as meta information, the server
SHALL either
- - evaluate all MatchingRuleAssertions to TRUE if matching a value
- of an attribute of the entry and otherwise Undefined, or
- - evaluate all MatchingRuleAssertion with dnAttributes of TRUE
- as Undefined.
+
+ - evaluate all MatchingRuleAssertions [RFC2251] to TRUE if
+ matching a value of an attribute of the entry and otherwise
+ Undefined, or
+ - evaluate all MatchingRuleAssertion with dnAttributes of TRUE as
+ Undefined.
The latter choice is offered for ease of server implementation.
For example, in servers which implement X.501 subschema model [X.501],
servers should not support synchronization of the subschemaSubentry
attribute as its value is determined by values held and administrated
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 22]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
in subschema subentries.
- For a counter example, servers which implement aliases
- [RFC2256][X.501] can support synchronization of the aliasedObjectName
- attribute as its values are held and administrated as part of the
- alias entries.
+ As a counter example, servers which implement aliases [RFC2256][X.501]
+ can support synchronization of the aliasedObjectName attribute as its
+ values are held and administrated as part of the alias entries.
Servers SHOULD support synchronization of the following operational
attributes: createTimestamp, modifyTimestamp, creatorsName,
modifiersName [RFC2252]. Servers MAY support synchronization of other
- operational attributes. Synchronization of operational attributes is
- discussed in Section 4.1.
+ operational attributes.
4.3. Collective Attributes
-
-
-Zeilenga LDAP Content Sync Operation [Page 17]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
A collective attribute is "a user attribute whose values are the same
for each member of an entry collection" [X.501]. Use of collective
- attributes in LDAP is detailed in [COLLECTIVE].
+ attributes in LDAP is discussed in [RFC3371].
Modification of a collective attribute generally affects the content
- of multiple entries, each a member of the collection. It is
+ of multiple entries, which are the members of the collection. It is
inefficient to include values of collective attributes visible in
entries of the collection, as a single modification of a collective
- attribute require transmission of multiple SearchResultEntry (one of
+ attribute requires transmission of multiple SearchResultEntry (one for
each entry of the collection which the modification affected) to be
transmitted.
collective attributes appearing in collective attribute subentries.
-4.4. Access and other administrative controls
+4.4. Access and Other Administrative Controls
Entries are commonly subject to access and other administrative
- controls. While portions of the policy information governing a
+ Controls. While portions of the policy information governing a
particular entry may be held in the entry, policy information is often
held elsewhere (in superior entries, in subentries, in the root DSE,
- in configuration files, ...). Because of this, changes to policy
+ in configuration files etc.). Because of this, changes to policy
information make it difficult to ensure eventual convergence during
incremental synchronization.
Where it is impractical or infeasible to generate content changes
resulting from a change to policy information, servers may opt to
- return syncRefreshRequired or treat the Sync Operation as an initial
- content request (e.g., ignore the cookie).
+ return e-syncRefreshRequired or treat the Sync Operation as an initial
+ content request (e.g., ignore the cookie or the synchronization state
+ represented in the cookie).
+
+
-5. Interaction with other controls
+
+Zeilenga LDAP Content Sync Operation [Page 23]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+5. Interaction with Other Controls
The Sync Operation may be used with:
- ManageDsaIT Control [RFC3296]
- - Subentries Control [SUBENTRY]
+ - Subentries Control [RFC3672]
- as described below. The Sync operation may be used with other LDAP
+ as described below. The Sync Operation may be used with other LDAP
extensions as detailed in other documents.
-5.1. ManageDsaIT control
+5.1. ManageDsaIT Control
- The ManageDsaIT control [RFC3296] indicates that the operation acts
+ The ManageDsaIT Control [RFC3296] indicates that the operation acts
upon the DSA Information Tree and causes referral and other special
+ entries to be treated as object entries with respect to the operation.
+5.2. Subentries Control
-Zeilenga LDAP Content Sync Operation [Page 18]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+ The Subentries Control is used with the search operation "to control
+ the visibility of entries and subentries which are within scope"
+ [RFC3672]. When used with the Sync Operation, the subentries control
+ and other factors (search scope, filter, etc.) are used to determine
+ whether an entry or subentry appear in the content or not.
- objects to be treated as normal objects with respect to the operation.
+6. Shadowing Considerations
+ As noted in [RFC2251], some servers may hold shadow copies of entries
+ which can be used to answer search and comparison queries. Such
+ servers may also support content synchronization requests. This
+ section discusses considerations for implementors and deployers for
+ the implementation and deployment of the Sync operation in shadowed
+ directories.
-5.2. Subentries control
+ While a client may know of multiple servers which are equally capable
+ of being used to obtain particular directory content from, a client
+ SHOULD NOT assume that each of these server is equally capable of
+ continuing a content synchronization session. As stated in Section
+ 3.1, the client SHOULD issue each Sync request of a Sync session to
+ the same server.
- The Subentries control is used with the search operation "to control
- the visibility of entries and subentries which are within scope"
- [SUBENTRY]. When used with the Sync Operation, the subentries control
- and other factors (search scope, filter, etc.) are used to determining
- whether an entry or subentry appear in the content or not.
+ However, through domain naming or IP address redirection or other
+ techniques, multiple physical servers can be made to appear as one
+ logical server to a client. Only servers which are equally capable in
+ regards to their support for the Sync operation and which hold equally
+ complete copies of the entries should be made to appear as one logical
+
+
+
+Zeilenga LDAP Content Sync Operation [Page 24]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ server. In particular, each physical server acting as one logical
+ server SHOULD be equally capable of continuing a content
+ synchronization based upon cookies provided by any of the other
+ physical servers without requiring a full reload. Because there is no
+ standard LDAP shadowing mechanism, the specification of how to
+ independently implement equally capable servers (as well as the
+ precise definition of "equally capable") is left to future documents.
+ It is noted that it may be difficult for the server to reliably
+ determine what content was provided to the client by another server,
+ especially in the shadowing environments which allow shadowing events
+ to be coalesced. Where so, the use of the delete phase discussed in
+ Section 3.3.2 may not be applicable.
-6. Security Considerations
+
+7. Security Considerations
In order to maintain a synchronized copy of the content, a client is
to delete information from its copy of the content as described above.
However, the client may maintain knowledge of information disclosed to
it by the server separate from its copy of the content used for
synchronization. Management of this knowledge is beyond the scope of
- this document.
+ this document. Servers should be careful not to disclose information
+ for content which the client is not authorized to have knowledge of
+ and/or about.
While the information provided by a series of refreshOnly Sync
- operations is similar to that provided by a series of Search
- operations, persist stage may disclose additional information. A
+ Operations is similar to that provided by a series of Search
+ Operations, persist stage may disclose additional information. A
client may be able to discern information about the particular
sequence of update operations which caused content change.
Implementors should take precautions against malicious cookie content,
including malformed cookies or valid cookies used with different
security associations and/or protections in attempt to obtain
- unauthorized access to information.
+ unauthorized access to information. Servers may include a digital
+ signature in the cookie to detect tampering.
- The Sync operation may be the target of denial of service attacks.
- Implementors should provide safeguards to ensure these mechanisms are
- not abused. Servers may place access control or other restrictions
- upon the use of this operation.
+ The operation may be the target of direct denial of service attacks.
+ Implementors should provide safeguards to ensure the operation is not
+ abused. Servers may place access control or other restrictions upon
+ the use of this operation.
- Implementors of this (or any) LDAP extension should be familiar with
- general LDAP security considerations [RFC3377].
+ It is noted that even small updates to the directory may cause
+ significant amount of traffic to be generated to clients using this
+ operation. A user could abuse its update privileges to mount an
+ indirect denial of service to these clients, other clients, and/or
+ portions of the network. Servers should provide safeguards to ensure
-7. IANA Considerations
- Registration of the following values is requested.
-
-
-7.1. Object Identifier
+Zeilenga LDAP Content Sync Operation [Page 25]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+ update operations are not abused.
+ Implementors of this (or any) LDAP extension should be familiar with
+ general LDAP security considerations [RFC3377].
-Zeilenga LDAP Content Sync Operation [Page 19]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+8. IANA Considerations
- It is requested that IANA register upon Standards Action an LDAP
- Object Identifier to identify elements of the LDAP Content
- Synchronization Operation as defined in this document.
+ Registration of the following values is requested.
- Subject: Request for LDAP Object Identifier Registration
- Person & email address to contact for further information:
- Kurt Zeilenga <kurt@OpenLDAP.org>
- Specification: RFCXXXX
- Author/Change Controller: IESG
- Comments:
- Identifies elements of the LDAP Content Synchronization Operation
+ The OID arc 1.3.6.1.4.1.4203.1.9.1 was assigned [ASSIGN] by OpenLDAP
+ Foundation, under its IANA-assigned private enterprise allocation
+ [PRIVATE], for use in this specification.
-7.2. LDAP Protocol Mechanism
+8.2. LDAP Protocol Mechanism
- It is requested that IANA register upon Standards Action the LDAP
- Protocol Mechanism described in this document.
+ It is requested that IANA register the LDAP Protocol Mechanism
+ described in this document.
Subject: Request for LDAP Protocol Mechanism Registration
- Object Identifier: IANA-ASSIGNED-OID
+ Object Identifier: 1.3.6.1.4.1.4203.1.9.1.1
Description: LDAP Content Synchronization Control
Person & email address to contact for further information:
Kurt Zeilenga <kurt@openldap.org>
Usage: Control
- Specification: RFCXXXX
+ Specification: RFC XXXX
Author/Change Controller: IESG
Comments: none
-7.3. LDAP Result Codes
+8.3. LDAP Result Codes
- It is requested that IANA register upon Standards Action the LDAP
- Result Codes described in this document.
+ It is requested that IANA register the LDAP Result Code described in
+ this document.
Subject: LDAP Result Code Registration
Person & email address to contact for further information:
Kurt Zeilenga <kurt@OpenLDAP.org>
- Result Code Name: syncRefreshRequired (IANA-ASSIGNED-CODE-0)
- Specification: RFCXXXX
+ Result Code Name: e-syncRefreshRequired (IANA-ASSIGNED-CODE)
+ Specification: RFC XXXX
Author/Change Controller: IESG
Comments: none
-8. Acknowledgment
+9. Acknowledgments
- This work borrows significantly from the LDAP Client Update Protocol
- [LCUP]. This work also benefited Persistent Search [PSEARCH],
- Triggered Search [TSEARCH], and Directory Synchronization [DIRSYNC]
+ This document borrows significantly from the LDAP Client Update
-Zeilenga LDAP Content Sync Operation [Page 20]
+Zeilenga LDAP Content Sync Operation [Page 26]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
- efforts. This work also borrows from "Lightweight Directory Access
- Protocol (v3)" [RFC2251].
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
-9. Normative References
+ Protocol [LCUP], a product of the IETF LDUP working group. This
+ document also benefited from Persistent Search [PSEARCH], Triggered
+ Search [TSEARCH], and Directory Synchronization [DIRSYNC] works. This
+ document also borrows from "Lightweight Directory Access Protocol
+ (v3)" [RFC2251].
- [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
- Requirement Levels", BCP 14 (also RFC 2119), March 1997.
- [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory
- Access Protocol (v3)", RFC 2251, December 1997.
+10. Normative References
- [RFC2252] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
- Directory Access Protocol (v3): Attribute Syntax
- Definitions", RFC 2252, December 1997.
+ [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
+ Requirement Levels", BCP 14 (also RFC 2119), March 1997.
- [RFC2256] M. Wahl, "A Summary of the X.500(96) User Schema for use
- with LDAPv3", RFC 2256, December 1997.
+ [RFC2251] Wahl, M., T. Howes and S. Kille, "Lightweight Directory
+ Access Protocol (v3)", RFC 2251, December 1997.
- [RFC2830] J. Hodges, R. Morgan, and M. Wahl, "Lightweight Directory
- Access Protocol (v3): Extension for Transport Layer
- Security", RFC 2830, May 2000.
+ [RFC2252] Wahl, M., A. Coulbeck, T. Howes, and S. Kille,
+ "Lightweight Directory Access Protocol (v3): Attribute
+ Syntax Definitions", RFC 2252, December 1997.
- [RFC3296] K. Zeilenga, "Named Subordinate References in Lightweight
- Directory Access Protocol (LDAP) Directories", RFC 3296,
- July 2002.
+ [RFC3296] Zeilenga, K., "Named Subordinate References in
+ Lightweight Directory Access Protocol (LDAP)
+ Directories", RFC 3296, July 2002.
- [RFC3377] J. Hodges, R.L. Morgan, "Lightweight Directory Access
- Protocol (v3): Technical Specification", RFC 3377,
- September 2002.
+ [RFC3377] Hodges, J. and R. Morgan, "Lightweight Directory Access
+ Protocol (v3): Technical Specification", RFC 3377,
+ September 2002.
- [LDAPIRM] R. Harrison, K. Zeilenga, "LDAP Intermediate Response
- Message", draft-rharrison-ldap-intermediate-resp-xx.txt
- (a work in progress).
+ [RFC3671] Zeilenga, K., "Collective Attributes in LDAP", RFC 3671,
+ December 2003.
- [SUBENTRY] K. Zeilenga, S. Legg, "Subentries in LDAP",
- draft-zeilenga-ldap-subentry-xx.txt, a work in progress.
+ [RFC3672] Zeilenga, K. and S. Legg, "Subentries in LDAP", RFC
+ 3672, December 2003.
- [X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
- Specification of Basic Notation", X.680, 1994.
+ [CANCEL] Zeilenga, K., "LDAP Cancel Extended Operation",
+ draft-zeilenga-ldap-cancel-xx.txt, a work in progress.
+ [EntryUUID] Zeilenga, K., "The LDAP EntryUUID Operational
+ Attribute", draft-zeilenga-ldap-uuid-xx.txt, a work in
+ progress.
- [X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
- Canonical, and Distinguished Encoding Rules", X.690,
- 1994.
+ [LDAPIRM] Harrison, R. and Zeilenga, K., "LDAP Intermediate
+ Response",
+ draft-rharrison-ldap-intermediate-resp-00.txt, a work in
+ progress.
- [CANCEL] K. Zeilenga, "LDAP Cancel Extended Operation",
- draft-zeilenga-ldap-cancel-xx.txt, a work in progress.
+ [UUID] International Organization for Standardization (ISO),
+ "Information technology - Open Systems Interconnection -
+ Remote Procedure Call", ISO/IEC 11578:1996
-Zeilenga LDAP Content Sync Operation [Page 21]
+Zeilenga LDAP Content Sync Operation [Page 27]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- [UUID] International Organization for Standardization (ISO),
- "Information technology - Open Systems Interconnection -
- Remote Procedure Call", ISO/IEC 11578:1996.
+ [X.680] International Telecommunication Union -
+ Telecommunication Standardization Sector, "Abstract
+ Syntax Notation One (ASN.1) - Specification of Basic
+ Notation", X.680(1997) (also ISO/IEC 8824-1:1998).
+ [X.690] International Telecommunication Union -
+ Telecommunication Standardization Sector, "Specification
+ of ASN.1 encoding rules: Basic Encoding Rules (BER),
+ Canonical Encoding Rules (CER), and Distinguished
+ Encoding Rules (DER)", X.690(1997) (also ISO/IEC
+ 8825-1:1998).
-10. Informative References
- [RFC3383] K. Zeilenga, "IANA Considerations for LDAP", BCP 64 (also
- RFC 3383), September 2002.
+11. Informative References
- [X.500] ITU-T Rec. X.500, "The Directory: Overview of Concepts,
- Models and Service", 1993.
+ [RFC2256] Wahl, M., "A Summary of the X.500(96) User Schema for
+ use with LDAPv3", RFC 2256, December 1997.
- [X.511] ITU, "The Directory: Abstract Service Definition", ITU-T
- Rec. X.511, 1993.
+ [RFC3383] Zeilenga, K., "IANA Considerations for LDAP", BCP 64
+ (also RFC 3383), September 2002.
- [X.525] ITU, "The Directory: Replication", ITU-T Rec. X.525,
- 1993.
+ [PRIVATE] IANA, "Private Enterprise Numbers",
+ http://www.iana.org/assignments/enterprise-numbers.
- [COLLECTIVE] K. Zeilenga, "Collective Attributes in LDAP",
- draft-zeilenga-ldap-collective-xx.txt, a work in
- progress.
+ [ASSIGN] OpenLDAP Foundation, "OpenLDAP OID Delegations",
+ http://www.openldap.org/foundation/oid-delegate.txt.
- [DIRSYNC] M. Armijo, "Microsoft LDAP Control for Directory
- Synchronization", draft-armijo-ldap-dirsync-xx.txt, a
- work in progress.
+ [X.500] International Telecommunication Union -
+ Telecommunication Standardization Sector, "The Directory
+ -- Overview of concepts, models and services,"
+ X.500(1993) (also ISO/IEC 9594-1:1994).
- [LCUP] R. Megginson, et. al., "LDAP Client Update Protocol",
- draft-ietf-ldup-lcup-xx.txt, a work in progress.
+ [X.511] International Telecommunication Union -
+ Telecommunication Standardization Sector, "The
+ Directory: Abstract Service Definition", X.511(1993).
- [PSEARCH] M. Smith, et. al., "Persistent Search: A Simple LDAP
- Change Notification Mechanism",
- draft-ietf-ldapext-psearch-xx.txt, a work in progress.
+ [X.525] International Telecommunication Union -
+ Telecommunication Standardization Sector, "The
+ Directory: Replication", X.525(1993).
- [TSEARCH] M. Wahl, "LDAPv3 Triggered Search Control",
- draft-ietf-ldapext-trigger-xx.txt, a work in progress.
+ [UUIDinfo] The Open Group, "Universally Unique Identifier" appendix
+ of the CAE Specification "DCE 1.1: Remote Procedure
+ Calls", Document Number C706,
+ <http://www.opengroup.org/products/publications/
+ catalog/c706.htm> (appendix available at:
+ <http://www.opengroup.org/onlinepubs/9629399/
+ apdxa.htm>), August 1997.
- [UUID-CSN] K. Zeilenga, J. Choi, "LDAP UUID and CSN Operational
- Attributes", draft-zeilenga-ldap-uuid-csn-xx.txt, a work
- (not yet) in progress.
-10. Authors' Address
- Kurt D. Zeilenga
- OpenLDAP Foundation
- <Kurt@OpenLDAP.org>
+Zeilenga LDAP Content Sync Operation [Page 28]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+ [DIRSYNC] Armijo, M., "Microsoft LDAP Control for Directory
+ Synchronization", draft-armijo-ldap-dirsync-xx.txt, a
+ work in progress.
+ [LCUP] Megginson, R., et. al., "LDAP Client Update Protocol",
+ draft-ietf-ldup-lcup-xx.txt, a work in progress.
-Zeilenga LDAP Content Sync Operation [Page 22]
-\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+ [PSEARCH] Smith, M., et. al., "Persistent Search: A Simple LDAP
+ Change Notification Mechanism",
+ draft-ietf-ldapext-psearch-xx.txt, a work in progress.
+ [TSEARCH] Wahl, M., "LDAPv3 Triggered Search Control",
+ draft-ietf-ldapext-trigger-xx.txt, a work in progress.
- Jonghyuk Choi
- IBM Corporation
- <jongchoi@us.ibm.com>
-
-
-Full Copyright
- Copyright 2003, The Internet Society. All Rights Reserved.
+12. Authors' Addresses
- This document and translations of it may be copied and furnished to
- others, and derivative works that comment on or otherwise explain it
- or assist in its implementation may be prepared, copied, published and
- distributed, in whole or in part, without restriction of any kind,
- provided that the above copyright notice and this paragraph are
- included on all such copies and derivative works. However, this
- document itself may not be modified in any way, such as by removing
- the copyright notice or references to the Internet Society or other
- Internet organizations, except as needed for the purpose of
- developing Internet standards in which case the procedures for
- copyrights defined in the Internet Standards process must be followed,
- or as required to translate it into languages other than English.
+ Kurt D. Zeilenga
+ OpenLDAP Foundation
+ <Kurt@OpenLDAP.org>
- The limited permissions granted above are perpetual and will not be
- revoked by the Internet Society or its successors or assigns.
+ Jong Hyuk Choi
+ IBM Corporation
+ <jongchoi@us.ibm.com>
- This document and the information contained herein is provided on an
- "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE INTERNET
- ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED,
- INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
- INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
- WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-Appendix - CSN-based Implementation Considerations
+Appendix A. CSN-based Implementation Considerations
This appendix is provided for informational purposes only, it is not a
normative part of the LDAP Content Synchronization Operation's
technical specification.
- This appendix discusses some of the implementation considerations
- associated with a Change Sequence Number [UUID-CSN] based approaches
- to supporting the LDAP Content Synchronization Operation.
+ This appendix discusses LDAP Content Synchronization Operation server
+ implementation considerations associated with a Change Sequence Number
+ based approaches.
- Change Sequence Number-based approaches are targetted for use in
- servers which do not maintain historical information (e.g., change
- logs, state snapshots, etc.) about changes made to the Directory and
- hence, must rely on current directory state and minimal
- synchronization state information embedded in Sync Cookie. Servers
+ Change Sequence Number based approaches are targeted for use in
+ servers which do not maintain history information (e.g., change logs,
+ state snapshots, etc.) about changes made to the Directory and hence,
+ must rely on current directory state and minimal synchronization state
+ information embedded in Sync Cookie. Servers which maintain history
+ information should consider other approaches which exploit the history
+ information.
+ A Change Sequence Number is effectively a time stamp which has
+ sufficient granularity to ensure that the precedence relationship in
+ time of two updates to the same object can be determined. Change
-Zeilenga LDAP Content Sync Operation [Page 23]
+
+Zeilenga LDAP Content Sync Operation [Page 29]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
-
-
- which maintain historical information should consider an other
- approaches which exploit the historical information.
-
- A Change Sequence Number is, effectively a time stamp has sufficient
- granularity to ensure that relationship in time of two updates to the
- same object can be determined. Change Sequence Numbers are not to be
- confused with Commit Sequence Numbers or Commit Log Record Numbers. A
- Commit Sequence Number allow one to determine how to two commits (to
- the same object or different objects) relate to each other in time.
- Change Sequence Number associated with different entries may be
- committed out of order. In the remainder of this Appendix, the term
- CSN refers to a Change Sequence Number.
-
- In these approaches, the server not only maintains an entry CSN
- operational attribute for each directory entry (as discussed in [UUID-
- CSN], but maintains a value which we will call the context CSN. The
- context CSN is the greatest committed entry CSN which is not greater
- than any outstanding entry CSNs for all entries in a directory
- context. The values of context CSN are used in syncCookie values as
- synchronization state indicators.
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+
+
+ Sequence Numbers are not to be confused with Commit Sequence Numbers
+ or Commit Log Record Numbers. A Commit Sequence Number allows one to
+ determine how two commits (to the same object or different objects)
+ relate to each other in time. Change Sequence Number associated with
+ different entries may be committed out of order. In the remainder of
+ this Appendix, the term CSN refers to a Change Sequence Number.
+
+ In these approaches, the server not only maintains a CSN for each
+ directory entry (the entry CSN), but also maintains a value which we
+ will call the context CSN. The context CSN is the greatest committed
+ entry CSN which is not greater than any outstanding (uncommitted)
+ entry CSNs for all entries in a directory context. The values of
+ context CSN are used in syncCookie values as synchronization state
+ indicators.
As search operations are not isolated from individual directory update
operations and individual update operations cannot be assumed to be
equal to the greatest entry CSN in the content. The content
incorporates all the relevant changes whose change sequence number is
less than or equal to context CSN before search processing. The
- content may also incorporate any subset of the the changes whose
- change sequence number is greater than context CSN before search
- processing but less than or equal to the context CSN after search
- processing. The content does not incorporate any of the changes whose
- CSN is greater than the context CSN after search processing.
+ content may also incorporate any subset of the changes whose change
+ sequence number is greater than context CSN before search processing
+ but less than or equal to the context CSN after search processing.
+ The content does not incorporate any of the changes whose CSN is
+ greater than the context CSN after search processing.
A simple server implementation could use value of the context CSN
before search processing to indicate state. Such an implementation
would embed this value into each SyncCookie returned. We'll call this
the cookie CSN. When a refresh was requested, the server would simply
- entry "update" messages for all entries in the content whose CSN is
- greater than the cookie CSN and entry "present" messages for all other
- entries in the content. However, if the current context CSN is same
- as the cookie CSN, the server should instead generate zero "updates",
- zero "delete" messages and indicate refreshDeletes of TRUE as the
- directory has not changed.
+ generate "update" messages for all entries in the content whose CSN is
+ greater than the supplied cookie CSN and generate "present" messages
+ for all other entries in the content. However, if the current context
+ CSN is the same as the cookie CSN, the server should instead generate
+ zero "updates" and zero "delete" messages, and indicate refreshDeletes
+ of TRUE as the directory has not changed.
The implementation should also consider the impact of changes to meta
information, such as access controls, which affects content
determination. One approach is for the server to maintain a context
+ wide meta information CSN or meta CSN. This meta CSN would be updated
+ whenever meta information affecting content determination was changed.
+ If the value of the meta CSN is greater than cookie CSN, the server
+ should ignore the cookie and treat the request as an initial request
+ for content.
-Zeilenga LDAP Content Sync Operation [Page 24]
+
+Zeilenga LDAP Content Sync Operation [Page 30]
\f
-INTERNET-DRAFT draft-zeilenga-ldup-sync-02 5 May 2003
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
- wide meta information CSN or meta CSN. This meta CSN would be updated
- whenever meta information affecting content determination was changed.
- If the value of the meta CSN is greater than cookie CSN, the server
- should ignore the cookie and treat the request as an initial request
- for content.
+ Additionally, servers may want to consider maintaining some
+ per-session history information to reduce the number of messages
+ needed to be transferred during incremental refreshes. Specifically,
+ a server could record information about entries as they leave the
+ scope of a disconnected sync session and later use this information to
+ generate delete messages instead of present messages.
+
+ When the history information is truncated, the CSN of the latest
+ truncated history information entry may be recorded as the truncated
+ CSN of the history information. The truncated CSN may be used to
+ determine whether a client copy can be covered by the history
+ information by comparing it to the synchronization state contained in
+ the cookie supplied by the client.
+
+ When there are a large number of sessions, it may make sense to
+ maintain such history only for the selected clients. Also, servers
+ taking this approach need to consider resource consumption issues to
+ ensure reasonable server operation and to protect against abuse. It
+ may be appropriate to restrict this mode of operation by policy.
+
+
+
+
+Intellectual Property Rights
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to pertain
+ to the implementation or use of the technology described in this
+ document or the extent to which any license under such rights might or
+ might not be available; neither does it represent that it has made any
+ effort to identify any such rights. Information on the IETF's
+ procedures with respect to rights in standards-track and
+ standards-related documentation can be found in BCP-11. Copies of
+ claims of rights made available for publication and any assurances of
+ licenses to be made available, or the result of an attempt made to
+ obtain a general license or permission for the use of such proprietary
+ rights by implementors or users of this specification can be obtained
+ from the IETF Secretariat.
+ The IETF invites any interested party to bring to its attention any
+ copyrights, patents or patent applications, or other proprietary
+ rights which may cover technology that may be required to practice
+ this standard. Please address the information to the IETF Executive
+ Director.
+Full Copyright
+
+Zeilenga LDAP Content Sync Operation [Page 31]
+\f
+INTERNET-DRAFT draft-zeilenga-ldup-sync-05 3 February 2004
+ Copyright (C) The Internet Society (2004). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published and
+ distributed, in whole or in part, without restriction of any kind,
+ provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be followed,
+ or as required to translate it into languages other than English.
-Zeilenga LDAP Content Sync Operation [Page 25]
+Zeilenga LDAP Content Sync Operation [Page 32]
\f
+
projects / openldap / commitdiff