+++ /dev/null
-
-INTERNET-DRAFT David Boreham, Netscape
- Jim Sermersheim, Novell
- Anoop Anantha, Microsoft
- Michael Armijo, Microsoft
-ldapext Working Group 6 April, 2000
-
-
- LDAP Extensions for Scrolling View Browsing of Search Results
-
- draft-ietf-ldapext-ldapv3-vlv-04.txt
- This document expires on 5 October 2000
-
-1. Status of this Memo
-
-This document is an Internet-Draft and is in full conformance with all
-provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
-ments of the Internet Engineering Task Force (IETF), its areas, and its
-working groups. Note that other groups may also distribute working
-documents as Internet-Drafts.
-
-Internet-Drafts are draft documents valid for a maximum of six months
-and may be updated, replaced, or obsoleted by other documents at any
-time. It is inappropriate to use Internet- Drafts as reference material
-or to cite them other than as "work in progress."
-
-The list of current Internet-Drafts can be accessed at
-http://www.ietf.org/ietf/1id-abstracts.txt
-
-The list of Internet-Draft Shadow Directories can be accessed at
-http://www.ietf.org/shadow.html.
-
-2. Abstract
-
-This document describes a Virtual List View control extension for the
-LDAP Search operation. This control is designed to allow the "virtual
-list box" feature, common in existing commercial e-mail address book
-applications, to be supported efficiently by LDAP servers. LDAP servers'
-inability to support this client feature is a significant impediment to
-LDAP replacing proprietary protocols in commercial e-mail systems.
-
-The control allows a client to specify that the server return, for a
-given LDAP search with associated sort keys, a contiguous subset of the
-search result set. This subset is specified in terms of offsets into the
-ordered list, or in terms of a greater than or equal comparison value.
-
-3. Background
-
-A Virtual List is a graphical user interface technique employed where
-
-
-
-Boreham et al [Page 1]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-ordered lists containing a large number of entries need to be displayed.
-A window containing a small number of visible list entries is drawn. The
-visible portion of the list may be relocated to different points within
-the list by means of user input. This input can be to a scroll bar
-slider; from cursor keys; from page up/down keys; from alphanumeric keys
-for "typedown". The user is given the impression that they may browse
-the complete list at will, even though it may contain millions of
-entries. It is the fact that the complete list contents are never
-required at any one time that characterizes Virtual List View. Rather
-than fetch the complete list from wherever it is stored (typically from
-disk or a remote server), only that information which is required to
-display the part of the list currently in view is fetched. The subject
-of this document is the interaction between client and server required
-to implement this functionality in the context of the results from a
-sorted LDAP search request.
-
-For example, suppose an e-mail address book application displays a list
-view onto the list containing the names of all the holders of e-mail
-accounts at a large university. The list is sorted alphabetically.
-While there may be tens of thousands of entries in this list, the
-address book list view displays only 20 such accounts at any one time.
-The list has an accompanying scroll bar and text input window for type-
-down. When first displayed, the list view shows the first 20 entries in
-the list, and the scroll bar slider is positioned at the top of its
-range. Should the user drag the slider to the bottom of its range, the
-displayed contents of the list view should be updated to show the last
-20 entries in the list. Similarly, if the slider is positioned somewhere
-in the middle of its travel, the displayed contents of the list view
-should be updated to contain the 20 entries located at that relative
-position within the complete list. Starting from any display point, if
-the user uses the cursor keys or clicks on the scroll bar to request
-that the list be scrolled up or down by one entry, the displayed con-
-tents should be updated to reflect this. Similarly the list should be
-displayed correctly when the user requests a page scroll up or down.
-Finally, when the user types characters in the type-down window, the
-displayed contents of the list should "jump" or "seek" to the appropri-
-ate point within the list. For example, if the user types "B", the
-displayed list could center around the first user with a name beginning
-with the letter "B". When this happens, the scroll bar slider should
-also be updated to reflect the new relative location within the list.
-
-This document defines a request control which extends the LDAP search
-operation. Always used in conjunction with the server side sorting
-control[SSS], this allows a client to retrieve selected portions of
-large search result set in a fashion suitable for the implementation of
-a virtual list view.
-
-The key words "MUST", "SHOULD", and "MAY" used in this document are to
-
-
-
-Boreham et al [Page 2]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-be interpreted as described in [Bradner97].
-
-4. Client-Server Interaction
-
-The Virtual List View control extends a regular LDAP Search operation
-which must also include a server-side sorting control[SSS]. Rather than
-returning the complete set of appropriate SearchResultEntry messages,
-the server is instructed to return a contiguous subset of those entries,
-taken from the sorted result set, centered around a particular target
-entry. Henceforth, in the interests of brevity, the sorted search result
-set will be referred to as "the list".
-
-The sort control MAY contain any sort specification valid for the
-server. The attributeType field in the first SortKeyList sequence ele-
-ment has special significance for "typedown".
-
-The desired target entry, and the number of entries to be returned both
-before, and after, that target entry in the list, are determined by the
-client's VirtualListViewRequest control.
-
-When the server returns the set of entries to the client, it attaches a
-VirtualListViewResponse control to the SearchResultDone message. The
-server returns in this control: its current estimate for the list con-
-tent count, the location within the list corresponding to the target
-entry, and any error codes.
-
-The target entry is specified in the VirtualListViewRequest control by
-one of two methods. The first method is for the client to indicate the
-target entry's offset within the list. The second way is for the client
-to supply an attribute assertion value. The value is compared against
-the values of the attribute specified as the primary sort key in the
-sort control attached to the search operation. The first sort key in
-the SortKeyList is the primary sort key. The target entry is the first
-entry in the list with value greater than or equal to (in the primary
-sort order), the presented value. The order is determined by rules
-defined in [SSS]. Selection of the target entry by this means is
-designed to implement "typedown". Note that it is possible that no
-entry satisfies these conditions, in which case there is no target
-entry. This condition is indicated by the server returning the special
-value contentCount + 1 in the target position field.
-
-Because the server may not have an accurate estimate of the number of
-entries in the list, and to take account of cases where the list size is
-changing during the time the user browses the list, and because the
-client needs a way to indicate specific list targets "beginning" and
-"end", offsets within the list are transmitted between client and server
-as ratios---offset to content count. The server sends its latest esti-
-mate as to the number of entries in the list (content count) to the
-
-
-
-Boreham et al [Page 3]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-client in every response control. The client sends its assumed value
-for the content count in every request control. The server examines the
-content count and offsets presented by the client and computes the
-corresponding offsets within the list, based on its own idea of the con-
-tent count.
-
- Si = Sc * (Ci / Cc)
-
- Where:
- Si is the actual list offset used by the server
- Sc is the server's estimate for content count
- Ci is the client's submitted offset
- Cc is the client's submitted content count
- The result is rounded to the nearest integer.
-
-If the content count is stable, and the client returns to the server the
-content count most recently received, Cc = Sc and the offsets transmit-
-ted become the actual server list offsets.
-
-The following special cases are allowed: a client sending a content
-count of zero (Cc = 0) means "client has no idea what the content count
-is, server MUST use its own content count estimate in place of the
-client's". An offset value of one (Ci = 1) always means that the target
-is the first entry in the list. Client specifying an offset which equals
-the content count specified in the same request control (Ci = Cc) means
-that the target is the last entry in the list. Ci may only equal zero
-when Cc is also zero. This signifies the last entry in the list.
-
-Because the server always returns contentCount and targetPosition, the
-client can always determine which of the returned entries is the target
-entry. Where the number of entries returned is the same as the number
-requested, the client is able to identify the target by simple arith-
-metic. Where the number of entries returned is not the same as the
-number requested (because the requested range crosses the beginning or
-end of the list, or both), the client must use the target position and
-content count values returned by the server to identify the target
-entry. For example, suppose that 10 entries before and 10 after the tar-
-get were requested, but the server returns 13 entries, a content count
-of 100 and a target position of 3. The client can determine that the
-first entry must be entry number 1 in the list, therefore the 13 entries
-returned are the first 13 entries in the list, and the target is the
-third one.
-
-A server-generated context identifier MAY be returned to clients. A
-client receiving a context identifier SHOULD return it unchanged in a
-subsequent request which relates to the same list. The purpose of this
-interaction is to enhance the performance and effectiveness of servers
-which employ approximate positioning.
-
-
-
-Boreham et al [Page 4]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-5. The Controls
-
-Support for the virtual list view control extension is indicated by the
-presence of the OID "2.16.840.1.113730.3.4.9" in the supportedControl
-attribute of a server's root DSE.
-
-5.1. Request Control
-
-This control is included in the SearchRequest message as part of the
-controls field of the LDAPMessage, as defined in Section 4.1.12 of
-[LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri-
-ticality SHOULD be set to TRUE. If this control is included in a Sear-
-chRequest message, a Server Side Sorting request control [SSS] MUST also
-be present in the message. The controlValue is an OCTET STRING whose
-value is the BER-encoding of the following SEQUENCE:
-
- VirtualListViewRequest ::= SEQUENCE {
- beforeCount INTEGER (0..maxInt),
- afterCount INTEGER (0..maxInt),
- CHOICE {
- byoffset [0] SEQUENCE {
- offset INTEGER (0 .. maxInt),
- contentCount INTEGER (0 .. maxInt) },
- greaterThanOrEqual [1] AssertionValue },
- contextID OCTET STRING OPTIONAL }
-
-beforeCount indicates how many entries before the target entry the
-client wants the server to send. afterCount indicates the number of
-entries after the target entry the client wants the server to send.
-offset and contentCount identify the target entry as detailed in section
-4. greaterThanOrEqual is an attribute assertion value defined in
-[LDAPv3]. If present, the value supplied in greaterThanOrEqual is used
-to determine the target entry by comparison with the values of the
-attribute specified as the primary sort key. The first list entry who's
-value is no less than (less than or equal to when the sort order is
-reversed) the supplied value is the target entry. If present, the con-
-textID field contains the value of the most recently received contextID
-field from a VirtualListViewResponse control. The type AssertionValue
-and value maxInt are defined in [LDAPv3]. contextID values have no
-validity outwith the connection on which they were received. That is, a
-client should not submit a contextID which it received from another con-
-nection, a connection now closed, or a different server.
-
-
-5.2. Response Control
-
-This control is included in the SearchResultDone message as part of the
-controls field of the LDAPMessage, as defined in Section 4.1.12 of
-
-
-
-Boreham et al [Page 5]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-[LDAPv3].
-
-The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is
-FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value
-is the BER encoding of a value of the following SEQUENCE:
-
- VirtualListViewResponse ::= SEQUENCE {
- targetPosition INTEGER (0 .. maxInt),
- contentCount INTEGER (0 .. maxInt),
- virtualListViewResult ENUMERATED {
- success (0),
- operationsError (1),
- unwillingToPerform (53),
- insufficientAccessRights (50),
- busy (51),
- timeLimitExceeded (3),
- adminLimitExceeded (11),
- sortControlMissing (60),
- offsetRangeError (61),
- other (80) },
- contextID OCTET STRING OPTIONAL }
-
-targetPosition gives the list offset for the target entry. contentCount
-gives the server's estimate of the current number of entries in the
-list. Together these give sufficient information for the client to
-update a list box slider position to match the newly retrieved entries
-and identify the target entry. The contentCount value returned SHOULD be
-used in a subsequent VirtualListViewRequest control. contextID is a
-server-defined octet string. If present, the contents of the contextID
-field SHOULD be returned to the server by a client in a subsequent Vir-
-tualListViewRequest control.
-
-The virtualListViewResult codes which are common to the LDAP sear-
-chResponse (adminLimitExceeded, timeLimitExceeded, busy, operationsEr-
-ror, unwillingToPerform, insufficientAccessRights) have the same mean-
-ings as defined in [LDAPv3], but they pertain specifically to the VLV
-operation. For example, the server could exceed an administration limit
-processing a SearchRequest with a VirtualListViewRequest control. How-
-ever, the same administration limit would not be exceeded should the
-same SearchRequest be submitted by the client without the VirtualList-
-ViewRequest control. In this case, the client can determine that an
-administration limit has been exceeded in servicing the VLV request, and
-can if it chooses resubmit the SearchRequest without the VirtualList-
-ViewRequest control.
-
-insufficientAccessRights means that the server denied the client permis-
-sion to perform the VLV operation.
-
-
-
-
-Boreham et al [Page 6]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-If the server determines that the results of the search presented exceed
-the range provided by the 32-bit offset values, it MUST return
-offsetRangeError.
-
-6. Protocol Example
-
-Here we walk through the client-server interaction for a specific vir-
-tual list view example: The task is to display a list of all 78564 peo-
-ple in the US company "Ace Industry". This will be done by creating a
-graphical user interface object to display the list contents, and by
-repeatedly sending different versions of the same virtual list view
-search request to the server. The list view displays 20 entries on the
-screen at a time.
-
-We form a search with baseDN "o=Ace Industry, c=us"; search scope sub-
-tree; filter "objectClass=inetOrgPerson". We attach a server sort order
-control to the search, specifying ascending sort on attribute "cn". To
-this base search, we attach a virtual list view request control with
-contents determined by the user activity and send the search to the
-server. We display the results from each search in the list window and
-update the slider position.
-
-When the list view is first displayed, we want to initialize the con-
-tents showing the beginning of the list. Therefore, we set beforeCount =
-0, afterCount = 19, contentCount = 0, offset = 1 and send the request to
-the server. The server duly returns the first 20 entries in the list,
-plus the content count = 78564 and targetPosition = 1. We therefore
-leave the scroll bar slider at its current location (the top of its
-range).
-
-Say that next the user drags the scroll bar slider down to the bottom of
-its range. We now wish to display the last 20 entries in the list, so
-we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset =
-78564 and send the request to the server. The server returns the last 20
-entries in the list, plus the content count = 78564 and targetPosition =
-78564.
-
-Next the user presses a page up key. Our page size is 20, so we set
-beforeCount = 0, afterCount = 19, contentCount = 78564, offset =
-78564-19-20 and send the request to the server. The server returns the
-preceding 20 entries in the list, plus the content count = 78564 and
-targetPosition = 78525.
-
-Now the user grabs the scroll bar slider and drags it to 68% of the way
-down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after-
-Count = 10, contentCount = 78564, offset = 53424 and send the request to
-the server. The server returns the preceding 20 entries in the list,
-plus the content count = 78564 and targetPosition = 53424.
-
-
-
-Boreham et al [Page 7]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-Lastly, the user types the letter "B". We set beforeCount = 9, after-
-Count = 10 and greaterThanOrEqual = "B". The server finds the first
-entry in the list not less than "B", let's say "Babs Jensen", and
-returns the nine preceding entries, the target entry, and the proceeding
-10 entries. The server returns content count = 78564 and targetPosition
-= 5234 and so the client updates its scroll bar slider to 6.7% of full
-scale.
-
-7. Notes for Implementers
-
-While the feature is expected to be generally useful for arbitrary
-search and sort specifications, it is specifically designed for those
-cases where the result set is very large. The intention is that this
-feature be implemented efficiently by means of pre-computed indices per-
-taining to a set of specific cases. For example, an offset relating to
-"all the employees in the local organization, sorted by surname" would
-be a common case.
-
-The intention for client software is that the feature should fit easily
-with the host platform's graphical user interface facilities for the
-display of scrolling lists. Thus the task of the client implementers
-should be one of reformatting up the requests for information received
-from the list view code to match the format of the virtual list view
-request and response controls.
-
-Client implementers should note that any offset value returned by the
-server may be approximate. Do not design clients > which only operate
-correctly when offsets are exact.
-
-Server implementers using indexing technology which features approximate
-positioning should consider returning context identifiers to clients.
-The use of a context identifier will allow the server to distinguish
-between client requests which relate to different displayed lists on the
-client. Consequently the server can decide more intelligently whether to
-reposition an existing database cursor accurately to within a short dis-
-tance of its current position, or to reposition to an approximate posi-
-tion. Thus the client will see precise offsets for "short" repositioning
-(e.g. paging up or down), but approximate offsets for a "long" reposi-
-tion (e.g. a slider movement).
-
-Server implementers are free to return status code unwillingToPerform
-should their server be unable to service any particular VLV search.
-This might be because the resolution of the search is computationally
-infeasible, or because excessive server resources would be required to
-service the search.
-
-Client implementers should note that this control is only defined on a
-client interaction with a single server. If a server returns referrals
-
-
-
-Boreham et al [Page 8]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-as a part of its response to the search request, the client is responsi-
-ble for deciding when and how to apply this control to the referred-to
-servers, and how to collate the results from multiple servers.
-
-
-8. Relationship to "Simple Paged Results"
-
-These controls are designed to support the virtual list view, which has
-proved hard to implement with the Simple Paged Results mechanism
-[SPaged]. However, the controls described here support any operation
-possible with the Simple Paged Results mechanism. The two mechanisms are
-not complementary, rather one has a superset of the other's features.
-One area where the mechanism presented here is not a strict superset of
-the Simple Paged Results scheme is that here we require a sort order to
-be specified. No such requirement is made for paged results.
-
-
-9. Security Considerations
-
-Server implementers may wish to consider whether clients are able to
-consume excessive server resources in requesting virtual list opera-
-tions. Access control to the feature itself; configuration options lim-
-iting the feature's use to certain predetermined search base DNs and
-filters; throttling mechanisms designed to limit the ability for one
-client to soak up server resources, may be appropriate.
-
-Consideration should be given as to whether a client will be able to
-retrieve the complete contents, or a significant subset of the complete
-contents of the directory using this feature. This may be undesirable in
-some circumstances and consequently it may be necessary to enforce some
-access control.
-
-Clients can, using this control, determine how many entries are con-
-tained within a portion of the DIT. This may constitute a security
-hazard. Again, access controls may be appropriate.
-
-Server implementers SHOULD exercise caution concerning the content of
-the contextID. Should the contextID contain internal server state, it
-may be possible for a malicious client to use that information to gain
-unauthorized access to information.
-
-10. Acknowledgements
-
-Chris Weider of Microsoft co-authored a previous version of this docu-
-ment.
-
-
-
-
-
-
-Boreham et al [Page 9]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-11. References
-
-[LDAPv3]
- Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro-
- tocol (v3)", Internet Standard, December, 1997. RFC2251.
-
-[SPaged]
- Weider, C, A. Herron, A. Anantha, and T. Howes, "LDAP Control
- Extension for Simple Paged Results Manipulation", September
- 1999. RFC2696
-
-[SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
- Side Sorting of Search Results", Internet Draft, April, 1999.
- Available as draft-ietf-asid-ldapv3-sorting-02.txt.
-
-[Bradner97]
- Bradner, S., "Key Words for use in RFCs to Indicate Requirement
- Levels", BCP 14, RFC 2119, March 1997.
-
-12. Authors' Addresses
-
- David Boreham
- iPlanet e-commerce solutions
- 501 E. Middlefield Road
- Mountain View, CA 94043, USA
- +1 650 937-5206
- dboreham@netscape.com
-
- Jim Sermersheim
- Novell
- 122 East 1700 South
- Provo, Utah 84606, USA
- jimse@novell.com
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052, USA
- +1 425 882-8080
- anoopa@microsoft.com
-
- Michael Armijo
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052, USA
- +1 425 882-8080
- micharm@microsoft.com
- This document expires on 5 October 2000
-
-
-
-Boreham et al [Page 10]
-
-
-
-
-
-RFC DRAFT April 2000
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Boreham et al [Page 11]
-
-
--- /dev/null
+
+INTERNET-DRAFT David Boreham, Netscape
+ Jim Sermersheim, Novell
+ Anoop Anantha, Microsoft
+ Michael Armijo, Microsoft
+ldapext Working Group 6 April, 2000
+
+
+ LDAP Extensions for Scrolling View Browsing of Search Results
+
+ draft-ietf-ldapext-ldapv3-vlv-04.txt
+ This document expires on 5 October 2000
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet- Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+2. Abstract
+
+This document describes a Virtual List View control extension for the
+LDAP Search operation. This control is designed to allow the "virtual
+list box" feature, common in existing commercial e-mail address book
+applications, to be supported efficiently by LDAP servers. LDAP servers'
+inability to support this client feature is a significant impediment to
+LDAP replacing proprietary protocols in commercial e-mail systems.
+
+The control allows a client to specify that the server return, for a
+given LDAP search with associated sort keys, a contiguous subset of the
+search result set. This subset is specified in terms of offsets into the
+ordered list, or in terms of a greater than or equal comparison value.
+
+3. Background
+
+A Virtual List is a graphical user interface technique employed where
+
+
+
+Boreham et al [Page 1]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+ordered lists containing a large number of entries need to be displayed.
+A window containing a small number of visible list entries is drawn. The
+visible portion of the list may be relocated to different points within
+the list by means of user input. This input can be to a scroll bar
+slider; from cursor keys; from page up/down keys; from alphanumeric keys
+for "typedown". The user is given the impression that they may browse
+the complete list at will, even though it may contain millions of
+entries. It is the fact that the complete list contents are never
+required at any one time that characterizes Virtual List View. Rather
+than fetch the complete list from wherever it is stored (typically from
+disk or a remote server), only that information which is required to
+display the part of the list currently in view is fetched. The subject
+of this document is the interaction between client and server required
+to implement this functionality in the context of the results from a
+sorted LDAP search request.
+
+For example, suppose an e-mail address book application displays a list
+view onto the list containing the names of all the holders of e-mail
+accounts at a large university. The list is sorted alphabetically.
+While there may be tens of thousands of entries in this list, the
+address book list view displays only 20 such accounts at any one time.
+The list has an accompanying scroll bar and text input window for type-
+down. When first displayed, the list view shows the first 20 entries in
+the list, and the scroll bar slider is positioned at the top of its
+range. Should the user drag the slider to the bottom of its range, the
+displayed contents of the list view should be updated to show the last
+20 entries in the list. Similarly, if the slider is positioned somewhere
+in the middle of its travel, the displayed contents of the list view
+should be updated to contain the 20 entries located at that relative
+position within the complete list. Starting from any display point, if
+the user uses the cursor keys or clicks on the scroll bar to request
+that the list be scrolled up or down by one entry, the displayed con-
+tents should be updated to reflect this. Similarly the list should be
+displayed correctly when the user requests a page scroll up or down.
+Finally, when the user types characters in the type-down window, the
+displayed contents of the list should "jump" or "seek" to the appropri-
+ate point within the list. For example, if the user types "B", the
+displayed list could center around the first user with a name beginning
+with the letter "B". When this happens, the scroll bar slider should
+also be updated to reflect the new relative location within the list.
+
+This document defines a request control which extends the LDAP search
+operation. Always used in conjunction with the server side sorting
+control[SSS], this allows a client to retrieve selected portions of
+large search result set in a fashion suitable for the implementation of
+a virtual list view.
+
+The key words "MUST", "SHOULD", and "MAY" used in this document are to
+
+
+
+Boreham et al [Page 2]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+be interpreted as described in [Bradner97].
+
+4. Client-Server Interaction
+
+The Virtual List View control extends a regular LDAP Search operation
+which must also include a server-side sorting control[SSS]. Rather than
+returning the complete set of appropriate SearchResultEntry messages,
+the server is instructed to return a contiguous subset of those entries,
+taken from the sorted result set, centered around a particular target
+entry. Henceforth, in the interests of brevity, the sorted search result
+set will be referred to as "the list".
+
+The sort control MAY contain any sort specification valid for the
+server. The attributeType field in the first SortKeyList sequence ele-
+ment has special significance for "typedown".
+
+The desired target entry, and the number of entries to be returned both
+before, and after, that target entry in the list, are determined by the
+client's VirtualListViewRequest control.
+
+When the server returns the set of entries to the client, it attaches a
+VirtualListViewResponse control to the SearchResultDone message. The
+server returns in this control: its current estimate for the list con-
+tent count, the location within the list corresponding to the target
+entry, and any error codes.
+
+The target entry is specified in the VirtualListViewRequest control by
+one of two methods. The first method is for the client to indicate the
+target entry's offset within the list. The second way is for the client
+to supply an attribute assertion value. The value is compared against
+the values of the attribute specified as the primary sort key in the
+sort control attached to the search operation. The first sort key in
+the SortKeyList is the primary sort key. The target entry is the first
+entry in the list with value greater than or equal to (in the primary
+sort order), the presented value. The order is determined by rules
+defined in [SSS]. Selection of the target entry by this means is
+designed to implement "typedown". Note that it is possible that no
+entry satisfies these conditions, in which case there is no target
+entry. This condition is indicated by the server returning the special
+value contentCount + 1 in the target position field.
+
+Because the server may not have an accurate estimate of the number of
+entries in the list, and to take account of cases where the list size is
+changing during the time the user browses the list, and because the
+client needs a way to indicate specific list targets "beginning" and
+"end", offsets within the list are transmitted between client and server
+as ratios---offset to content count. The server sends its latest esti-
+mate as to the number of entries in the list (content count) to the
+
+
+
+Boreham et al [Page 3]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+client in every response control. The client sends its assumed value
+for the content count in every request control. The server examines the
+content count and offsets presented by the client and computes the
+corresponding offsets within the list, based on its own idea of the con-
+tent count.
+
+ Si = Sc * (Ci / Cc)
+
+ Where:
+ Si is the actual list offset used by the server
+ Sc is the server's estimate for content count
+ Ci is the client's submitted offset
+ Cc is the client's submitted content count
+ The result is rounded to the nearest integer.
+
+If the content count is stable, and the client returns to the server the
+content count most recently received, Cc = Sc and the offsets transmit-
+ted become the actual server list offsets.
+
+The following special cases are allowed: a client sending a content
+count of zero (Cc = 0) means "client has no idea what the content count
+is, server MUST use its own content count estimate in place of the
+client's". An offset value of one (Ci = 1) always means that the target
+is the first entry in the list. Client specifying an offset which equals
+the content count specified in the same request control (Ci = Cc) means
+that the target is the last entry in the list. Ci may only equal zero
+when Cc is also zero. This signifies the last entry in the list.
+
+Because the server always returns contentCount and targetPosition, the
+client can always determine which of the returned entries is the target
+entry. Where the number of entries returned is the same as the number
+requested, the client is able to identify the target by simple arith-
+metic. Where the number of entries returned is not the same as the
+number requested (because the requested range crosses the beginning or
+end of the list, or both), the client must use the target position and
+content count values returned by the server to identify the target
+entry. For example, suppose that 10 entries before and 10 after the tar-
+get were requested, but the server returns 13 entries, a content count
+of 100 and a target position of 3. The client can determine that the
+first entry must be entry number 1 in the list, therefore the 13 entries
+returned are the first 13 entries in the list, and the target is the
+third one.
+
+A server-generated context identifier MAY be returned to clients. A
+client receiving a context identifier SHOULD return it unchanged in a
+subsequent request which relates to the same list. The purpose of this
+interaction is to enhance the performance and effectiveness of servers
+which employ approximate positioning.
+
+
+
+Boreham et al [Page 4]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+5. The Controls
+
+Support for the virtual list view control extension is indicated by the
+presence of the OID "2.16.840.1.113730.3.4.9" in the supportedControl
+attribute of a server's root DSE.
+
+5.1. Request Control
+
+This control is included in the SearchRequest message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3]. The controlType is set to "2.16.840.1.113730.3.4.9". The cri-
+ticality SHOULD be set to TRUE. If this control is included in a Sear-
+chRequest message, a Server Side Sorting request control [SSS] MUST also
+be present in the message. The controlValue is an OCTET STRING whose
+value is the BER-encoding of the following SEQUENCE:
+
+ VirtualListViewRequest ::= SEQUENCE {
+ beforeCount INTEGER (0..maxInt),
+ afterCount INTEGER (0..maxInt),
+ CHOICE {
+ byoffset [0] SEQUENCE {
+ offset INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt) },
+ greaterThanOrEqual [1] AssertionValue },
+ contextID OCTET STRING OPTIONAL }
+
+beforeCount indicates how many entries before the target entry the
+client wants the server to send. afterCount indicates the number of
+entries after the target entry the client wants the server to send.
+offset and contentCount identify the target entry as detailed in section
+4. greaterThanOrEqual is an attribute assertion value defined in
+[LDAPv3]. If present, the value supplied in greaterThanOrEqual is used
+to determine the target entry by comparison with the values of the
+attribute specified as the primary sort key. The first list entry who's
+value is no less than (less than or equal to when the sort order is
+reversed) the supplied value is the target entry. If present, the con-
+textID field contains the value of the most recently received contextID
+field from a VirtualListViewResponse control. The type AssertionValue
+and value maxInt are defined in [LDAPv3]. contextID values have no
+validity outwith the connection on which they were received. That is, a
+client should not submit a contextID which it received from another con-
+nection, a connection now closed, or a different server.
+
+
+5.2. Response Control
+
+This control is included in the SearchResultDone message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+
+
+
+Boreham et al [Page 5]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+[LDAPv3].
+
+The controlType is set to "2.16.840.1.113730.3.4.10". The criticality is
+FALSE (MAY be absent). The controlValue is an OCTET STRING, whose value
+is the BER encoding of a value of the following SEQUENCE:
+
+ VirtualListViewResponse ::= SEQUENCE {
+ targetPosition INTEGER (0 .. maxInt),
+ contentCount INTEGER (0 .. maxInt),
+ virtualListViewResult ENUMERATED {
+ success (0),
+ operationsError (1),
+ unwillingToPerform (53),
+ insufficientAccessRights (50),
+ busy (51),
+ timeLimitExceeded (3),
+ adminLimitExceeded (11),
+ sortControlMissing (60),
+ offsetRangeError (61),
+ other (80) },
+ contextID OCTET STRING OPTIONAL }
+
+targetPosition gives the list offset for the target entry. contentCount
+gives the server's estimate of the current number of entries in the
+list. Together these give sufficient information for the client to
+update a list box slider position to match the newly retrieved entries
+and identify the target entry. The contentCount value returned SHOULD be
+used in a subsequent VirtualListViewRequest control. contextID is a
+server-defined octet string. If present, the contents of the contextID
+field SHOULD be returned to the server by a client in a subsequent Vir-
+tualListViewRequest control.
+
+The virtualListViewResult codes which are common to the LDAP sear-
+chResponse (adminLimitExceeded, timeLimitExceeded, busy, operationsEr-
+ror, unwillingToPerform, insufficientAccessRights) have the same mean-
+ings as defined in [LDAPv3], but they pertain specifically to the VLV
+operation. For example, the server could exceed an administration limit
+processing a SearchRequest with a VirtualListViewRequest control. How-
+ever, the same administration limit would not be exceeded should the
+same SearchRequest be submitted by the client without the VirtualList-
+ViewRequest control. In this case, the client can determine that an
+administration limit has been exceeded in servicing the VLV request, and
+can if it chooses resubmit the SearchRequest without the VirtualList-
+ViewRequest control.
+
+insufficientAccessRights means that the server denied the client permis-
+sion to perform the VLV operation.
+
+
+
+
+Boreham et al [Page 6]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+If the server determines that the results of the search presented exceed
+the range provided by the 32-bit offset values, it MUST return
+offsetRangeError.
+
+6. Protocol Example
+
+Here we walk through the client-server interaction for a specific vir-
+tual list view example: The task is to display a list of all 78564 peo-
+ple in the US company "Ace Industry". This will be done by creating a
+graphical user interface object to display the list contents, and by
+repeatedly sending different versions of the same virtual list view
+search request to the server. The list view displays 20 entries on the
+screen at a time.
+
+We form a search with baseDN "o=Ace Industry, c=us"; search scope sub-
+tree; filter "objectClass=inetOrgPerson". We attach a server sort order
+control to the search, specifying ascending sort on attribute "cn". To
+this base search, we attach a virtual list view request control with
+contents determined by the user activity and send the search to the
+server. We display the results from each search in the list window and
+update the slider position.
+
+When the list view is first displayed, we want to initialize the con-
+tents showing the beginning of the list. Therefore, we set beforeCount =
+0, afterCount = 19, contentCount = 0, offset = 1 and send the request to
+the server. The server duly returns the first 20 entries in the list,
+plus the content count = 78564 and targetPosition = 1. We therefore
+leave the scroll bar slider at its current location (the top of its
+range).
+
+Say that next the user drags the scroll bar slider down to the bottom of
+its range. We now wish to display the last 20 entries in the list, so
+we set beforeCount = 19, afterCount = 0, contentCount = 78564, offset =
+78564 and send the request to the server. The server returns the last 20
+entries in the list, plus the content count = 78564 and targetPosition =
+78564.
+
+Next the user presses a page up key. Our page size is 20, so we set
+beforeCount = 0, afterCount = 19, contentCount = 78564, offset =
+78564-19-20 and send the request to the server. The server returns the
+preceding 20 entries in the list, plus the content count = 78564 and
+targetPosition = 78525.
+
+Now the user grabs the scroll bar slider and drags it to 68% of the way
+down its travel. 68% of 78564 is 53424 so we set beforeCount = 9, after-
+Count = 10, contentCount = 78564, offset = 53424 and send the request to
+the server. The server returns the preceding 20 entries in the list,
+plus the content count = 78564 and targetPosition = 53424.
+
+
+
+Boreham et al [Page 7]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+Lastly, the user types the letter "B". We set beforeCount = 9, after-
+Count = 10 and greaterThanOrEqual = "B". The server finds the first
+entry in the list not less than "B", let's say "Babs Jensen", and
+returns the nine preceding entries, the target entry, and the proceeding
+10 entries. The server returns content count = 78564 and targetPosition
+= 5234 and so the client updates its scroll bar slider to 6.7% of full
+scale.
+
+7. Notes for Implementers
+
+While the feature is expected to be generally useful for arbitrary
+search and sort specifications, it is specifically designed for those
+cases where the result set is very large. The intention is that this
+feature be implemented efficiently by means of pre-computed indices per-
+taining to a set of specific cases. For example, an offset relating to
+"all the employees in the local organization, sorted by surname" would
+be a common case.
+
+The intention for client software is that the feature should fit easily
+with the host platform's graphical user interface facilities for the
+display of scrolling lists. Thus the task of the client implementers
+should be one of reformatting up the requests for information received
+from the list view code to match the format of the virtual list view
+request and response controls.
+
+Client implementers should note that any offset value returned by the
+server may be approximate. Do not design clients > which only operate
+correctly when offsets are exact.
+
+Server implementers using indexing technology which features approximate
+positioning should consider returning context identifiers to clients.
+The use of a context identifier will allow the server to distinguish
+between client requests which relate to different displayed lists on the
+client. Consequently the server can decide more intelligently whether to
+reposition an existing database cursor accurately to within a short dis-
+tance of its current position, or to reposition to an approximate posi-
+tion. Thus the client will see precise offsets for "short" repositioning
+(e.g. paging up or down), but approximate offsets for a "long" reposi-
+tion (e.g. a slider movement).
+
+Server implementers are free to return status code unwillingToPerform
+should their server be unable to service any particular VLV search.
+This might be because the resolution of the search is computationally
+infeasible, or because excessive server resources would be required to
+service the search.
+
+Client implementers should note that this control is only defined on a
+client interaction with a single server. If a server returns referrals
+
+
+
+Boreham et al [Page 8]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+as a part of its response to the search request, the client is responsi-
+ble for deciding when and how to apply this control to the referred-to
+servers, and how to collate the results from multiple servers.
+
+
+8. Relationship to "Simple Paged Results"
+
+These controls are designed to support the virtual list view, which has
+proved hard to implement with the Simple Paged Results mechanism
+[SPaged]. However, the controls described here support any operation
+possible with the Simple Paged Results mechanism. The two mechanisms are
+not complementary, rather one has a superset of the other's features.
+One area where the mechanism presented here is not a strict superset of
+the Simple Paged Results scheme is that here we require a sort order to
+be specified. No such requirement is made for paged results.
+
+
+9. Security Considerations
+
+Server implementers may wish to consider whether clients are able to
+consume excessive server resources in requesting virtual list opera-
+tions. Access control to the feature itself; configuration options lim-
+iting the feature's use to certain predetermined search base DNs and
+filters; throttling mechanisms designed to limit the ability for one
+client to soak up server resources, may be appropriate.
+
+Consideration should be given as to whether a client will be able to
+retrieve the complete contents, or a significant subset of the complete
+contents of the directory using this feature. This may be undesirable in
+some circumstances and consequently it may be necessary to enforce some
+access control.
+
+Clients can, using this control, determine how many entries are con-
+tained within a portion of the DIT. This may constitute a security
+hazard. Again, access controls may be appropriate.
+
+Server implementers SHOULD exercise caution concerning the content of
+the contextID. Should the contextID contain internal server state, it
+may be possible for a malicious client to use that information to gain
+unauthorized access to information.
+
+10. Acknowledgements
+
+Chris Weider of Microsoft co-authored a previous version of this docu-
+ment.
+
+
+
+
+
+
+Boreham et al [Page 9]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+11. References
+
+[LDAPv3]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access Pro-
+ tocol (v3)", Internet Standard, December, 1997. RFC2251.
+
+[SPaged]
+ Weider, C, A. Herron, A. Anantha, and T. Howes, "LDAP Control
+ Extension for Simple Paged Results Manipulation", September
+ 1999. RFC2696
+
+[SSS]Wahl, M, A. Herron and T. Howes, "LDAP Control Extension for Server
+ Side Sorting of Search Results", Internet Draft, April, 1999.
+ Available as draft-ietf-asid-ldapv3-sorting-02.txt.
+
+[Bradner97]
+ Bradner, S., "Key Words for use in RFCs to Indicate Requirement
+ Levels", BCP 14, RFC 2119, March 1997.
+
+12. Authors' Addresses
+
+ David Boreham
+ iPlanet e-commerce solutions
+ 501 E. Middlefield Road
+ Mountain View, CA 94043, USA
+ +1 650 937-5206
+ dboreham@netscape.com
+
+ Jim Sermersheim
+ Novell
+ 122 East 1700 South
+ Provo, Utah 84606, USA
+ jimse@novell.com
+
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+ +1 425 882-8080
+ anoopa@microsoft.com
+
+ Michael Armijo
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052, USA
+ +1 425 882-8080
+ micharm@microsoft.com
+ This document expires on 5 October 2000
+
+
+
+Boreham et al [Page 10]
+
+
+
+
+
+RFC DRAFT April 2000
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Boreham et al [Page 11]
+
+
+++ /dev/null
-
-Network Working Group A. Herron, Microsoft
-INTERNET DRAFT T. Howes, Netscape
-Expire in six months M. Wahl, Critical Angle Inc
- A. Anantha, Microsoft
- April 5, 1999
-
- LDAP Control Extension for Server Side Sorting of Search Results
- draft-ietf-ldapext-sorting-02.txt
-
-
-1. Status of this Memo
-
-This document is an Internet-Draft. Internet-Drafts are working docu-
-ments of the Internet Engineering Task Force (IETF), its areas, and its
-working groups. Note that other groups may also distribute working
-documents as Internet-Drafts.
-
-Internet-Drafts are draft documents valid for a maximum of six months
-and may be updated, replaced, or obsoleted by other documents at any
-time. It is inappropriate to use Internet- Drafts as reference material
-or to cite them other than as ``work in progress.''
-
-To learn the current status of any Internet-Draft, please check the
-``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow
-Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
-ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
-
-This document expires on October 5, 1999.
-
-2. Abstract
-
-This document describes two LDAPv3 control extensions for server side
-sorting of search results. These controls allows a client to specify the
-attribute types and matching rules a server should use when returning
-the results to an LDAP search request. The controls may be useful when
-the LDAP client has limited functionality or for some other reason
-cannot sort the results but still needs them sorted. Other permissible
-controls on search operations are not defined in this extension.
-
-The sort controls allow a server to return a result code for the sorting
-of the results that is independent of the result code returned for the
-search operation.
-
-The key words "MUST", "SHOULD", and "MAY" used in this document are to
-be interpreted as described in [bradner97].
-
-3. The Controls
-
-3.1 Request Control
-
-This control is included in the searchRequest message as part of the
-controls field of the LDAPMessage, as defined in Section 4.1.12 of
-[LDAPv3].
-
-The controlType is set to "1.2.840.113556.1.4.473". The criticality
-MAY be either TRUE or FALSE (where absent is also equivalent to
-FALSE) at the client's option. The controlValue is an OCTET STRING,
-whose value is the BER encoding of a value of the following SEQUENCE:
-
- SortKeyList ::= SEQUENCE OF SEQUENCE {
- attributeType AttributeDescription,
- orderingRule [0] MatchingRuleId OPTIONAL,
- reverseOrder [1] BOOLEAN DEFAULT FALSE }
-
-The SortKeyList sequence is in order of highest to lowest sort key
-precedence.
-
-The MatchingRuleID SHOULD be one that is valid for the attribute type
-it applies to. If it is not, the server MUST return unwillingToPerform.
-
-Each attributeType should only occur in the SortKeyList once. If an
-attributeType is included in the sort key list multiple times, the
-server should return an error in the sortResult of unwillingToPerform.
-
-If the orderingRule is omitted, the ordering MatchingRule defined for use
-with this attribute MUST be used.
-
-Any conformant implementation of this control MUST allow a sort key
-list with at least one key.
-
-3.2 Response Control
-
-This control is included in the searchResultDone message as part of the
-controls field of the LDAPMessage, as defined in Section 4.1.12 of
-[LDAPv3].
-
-The controlType is set to "1.2.840.113556.1.4.474". The criticality is
-FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
-value is the BER encoding of a value of the following SEQUENCE:
-
- SortResult ::= SEQUENCE {
- sortResult ENUMERATED {
- success (0), -- results are sorted
- operationsError (1), -- server internal failure
- timeLimitExceeded (3), -- timelimit reached before
- -- sorting was completed
- strongAuthRequired (8), -- refused to return sorted
- -- results via insecure
- -- protocol
- adminLimitExceeded (11), -- too many matching entries
- -- for the server to sort
- noSuchAttribute (16), -- unrecognized attribute
- -- type in sort key
- inappropriateMatching (18), -- unrecognized or inappro-
- -- priate matching rule in
- -- sort key
- insufficientAccessRights (50), -- refused to return sorted
- -- results to this client
- busy (51), -- too busy to process
- unwillingToPerform (53), -- unable to sort
- other (80)
- },
- attributeType [0] AttributeDescription OPTIONAL }
-
-4. Client-Server Interaction
-
-The sortKeyRequestControl specifies one or more attribute types and
-matching rules for the results returned by a search request. The server
-SHOULD return all results for the search request in the order specified
-by the sort keys. If the reverseOrder field is set to TRUE, then the
-entries will be presented in reverse sorted order for the specified
-key.
-
-There are six possible scenarios that may occur as a result of the sort
-control being included on the search request :
-
-1 - If the server does not support this sorting control and the client
-specified TRUE for the control's criticality field, then the server
-MUST return unavailableCriticalExtension as a return code in the
-searchResultDone message and not send back any other results. This
-behavior is specified in section 4.1.12 of [LDAPv3].
-
-2 - If the server does not support this sorting control and the client
-specified FALSE for the control's criticality field, then the server
-MUST ignore the sort control and process the search request as if it
-were not present. This behavior is specified in section 4.1.12 of
-[LDAPv3].
-
-3 - If the server supports this sorting control but for some reason
-cannot sort the search results using the specified sort keys and the
-client specified TRUE for the control's criticality field, then the
-server SHOULD do the following: return unavailableCriticalExtension as
-a return code in the searchResultDone message; include the
-sortKeyResponseControl in the searchResultDone message, and not send
-back any search result entries.
-
-4 - If the server supports this sorting control but for some reason
-cannot sort the search results using the specified sort keys and the
-client specified FALSE for the control's criticality field, then the
-server should return all search results unsorted and include the
-sortKeyResponseControl in the searchResultDone message.
-
-5 - If the server supports this sorting control and can sort the search
-results using the specified sort keys, then it should include the
-sortKeyResponseControl in the searchResultDone message with a
-sortResult of success.
-
-6 - If the search request failed for any reason and/or there are no
-searchResultEntry messages returned for the search response, then the
-server SHOULD omit the sortKeyResponseControl from the
-searchResultDone message.
-
-The client application is assured that the results are sorted in the
-specified key order if and only if the result code in the
-sortKeyResponseControl is success. If the server omits the
-sortKeyResponseControl from the searchResultDone message, the client
-SHOULD assume that the sort control was ignored by the server.
-
-The sortKeyResponseControl, if included by the server in the
-searchResultDone message, should have the sortResult set to either
-success if the results were sorted in accordance with the keys
-specified in the sortKeyRequestControl or set to the appropriate error
-code as to why it could not sort the data (such as noSuchAttribute or
-inappropriateMatching). Optionally, the server MAY set the
-attributeType to the first attribute type specified in the SortKeyList
-that was in error. The client SHOULD ignore the attributeType field if
-the sortResult is success.
-
-The server may not be able to sort the results using the specified sort
-keys because it may not recognize one of the attribute types, the
-matching rule associated with an attribute type is not applicable, or
-none of the attributes in the search response are of these types.
-Servers may also restrict the number of keys allowed in the control,
-such as only supporting a single key.
-
-Servers that chain requests to other LDAP servers should ensure that
-the server satisfying the client's request sort the entire result set
-prior to sending back the results.
-
-4.1 Behavior in a chained environment
-
-If a server receives a sort request, the client expects to receive a
-set of sorted results. If a client submits a sort request to a server
-which chains the request and gets entries from multiple servers, and
-the client has set the criticality of the sort extension to TRUE, the
-server MUST merge sort the results before returning them to the client
-or MUST return unwillingToPerform.
-
-4.2 Other sort issues
-
-An entry that meets the search criteria may be missing one or more of
-the sort keys. In that case, the entry is considered to have a value of
-NULL for that key. This standard considers NULL to be a larger value
-than all other valid values for that key. For example, if only one key
-is specified, entries which meet the search criteria but do not have
-that key collate after all the entries which do have that key. If the
-reverseOrder flag is set, and only one key is specified, entries which
-meet the search criteria but do not have that key collate BEFORE all
-the entries which do have that key.
-
-If a sort key is a multi-valued attribute, and an entry happens to have
-multiple values for that attribute and no other controls are present that
-affect the sorting order, then the server SHOULD use the least value
-(according to the ORDERING rule for that attribute).
-
-5. Interaction with other search controls
-
-When the sortKeyRequestControl control is included with the
-pagedResultsControl control as specified in [LdapPaged], then the
-server should send the searchResultEntry messages sorted according to
-the sort keys applied to the entire result set. The server should not
-simply sort each page, as this will give erroneous results to the
-client.
-
-The sortKeyList must be present on each searchRequest message for the
-paged result. It also must not change between searchRequests for the
-same result set. If the server has sorted the data, then it SHOULD
-send back a sortKeyResponseControl control on every searchResultDone
-message for each page. This will allow clients to quickly determine
-if the result set is sorted, rather than waiting to receive the entire
-result set.
-
-
-6. Security Considerations
-
-Implementors and administrators should be aware that allowing sorting
-of results could enable the retrieval of a large number of records from
-a given directory service, irregardless of administrative limits set on
-the maximum number of records to return.
-
-A client that desired to pull all records out of a directory service
-could use a combination of sorting and updating of search filters to
-retrieve all records in a database in small result sets, thus
-circumventing administrative limits.
-
-This behavior can be overcome by the judicious use of permissions on
-the directory entries by the administrator and by intelligent
-implementations of administrative limits on the number of records
-retrieved by a client.
-
-
-7. References
-
-[LDAPv3]
- Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
-Pro-
- tocol (v3)", RFC 2251, December, 1997.
-
-[Bradner97]
- Bradner, Scott, "Key Words for use in RFCs to Indicate
-Requirement
- Levels", RFC 2119, March, 1997.
-
-[LdapPaged]
- C. Weider, A. Herron, and T. Howes, "LDAP Control Extension for
- Simple Paged Results Manipulation", Internet Draft, February, 1997.
- Available as draft-ietf-asid-ldapv3-simplepaged-00.txt.
-
-
-8. Author's Address
-
- Anoop Anantha
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
- Anoopa@microsoft.com
- +1 425 882-8080
-
- Andy Herron
- Microsoft Corp.
- 1 Microsoft Way
- Redmond, WA 98052
- USA
- andyhe@microsoft.com
- +1 425 882-8080
-
- Tim Howes
- Netscape Communications Corp.
- 501 E. Middlefield Road
- Mountain View, CA 94043
- USA
- howes@netscape.com
- +1 415 937-2600
-
- Mark Wahl
- Critical Angle Inc.
- 4815 W Braker Lane #502-385
- Austin, TX 78759
- USA
- M.Wahl@critical-angle.com
-
--- /dev/null
+
+Network Working Group A. Herron, Microsoft
+INTERNET DRAFT T. Howes, Netscape
+Expire in six months M. Wahl, Critical Angle Inc
+ A. Anantha, Microsoft
+ April 5, 1999
+
+ LDAP Control Extension for Server Side Sorting of Search Results
+ draft-ietf-ldapext-sorting-02.txt
+
+
+1. Status of this Memo
+
+This document is an Internet-Draft. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet- Drafts as reference material
+or to cite them other than as ``work in progress.''
+
+To learn the current status of any Internet-Draft, please check the
+``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow
+Directories on ds.internic.net (US East Coast), nic.nordu.net (Europe),
+ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific Rim).
+
+This document expires on October 5, 1999.
+
+2. Abstract
+
+This document describes two LDAPv3 control extensions for server side
+sorting of search results. These controls allows a client to specify the
+attribute types and matching rules a server should use when returning
+the results to an LDAP search request. The controls may be useful when
+the LDAP client has limited functionality or for some other reason
+cannot sort the results but still needs them sorted. Other permissible
+controls on search operations are not defined in this extension.
+
+The sort controls allow a server to return a result code for the sorting
+of the results that is independent of the result code returned for the
+search operation.
+
+The key words "MUST", "SHOULD", and "MAY" used in this document are to
+be interpreted as described in [bradner97].
+
+3. The Controls
+
+3.1 Request Control
+
+This control is included in the searchRequest message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3].
+
+The controlType is set to "1.2.840.113556.1.4.473". The criticality
+MAY be either TRUE or FALSE (where absent is also equivalent to
+FALSE) at the client's option. The controlValue is an OCTET STRING,
+whose value is the BER encoding of a value of the following SEQUENCE:
+
+ SortKeyList ::= SEQUENCE OF SEQUENCE {
+ attributeType AttributeDescription,
+ orderingRule [0] MatchingRuleId OPTIONAL,
+ reverseOrder [1] BOOLEAN DEFAULT FALSE }
+
+The SortKeyList sequence is in order of highest to lowest sort key
+precedence.
+
+The MatchingRuleID SHOULD be one that is valid for the attribute type
+it applies to. If it is not, the server MUST return unwillingToPerform.
+
+Each attributeType should only occur in the SortKeyList once. If an
+attributeType is included in the sort key list multiple times, the
+server should return an error in the sortResult of unwillingToPerform.
+
+If the orderingRule is omitted, the ordering MatchingRule defined for use
+with this attribute MUST be used.
+
+Any conformant implementation of this control MUST allow a sort key
+list with at least one key.
+
+3.2 Response Control
+
+This control is included in the searchResultDone message as part of the
+controls field of the LDAPMessage, as defined in Section 4.1.12 of
+[LDAPv3].
+
+The controlType is set to "1.2.840.113556.1.4.474". The criticality is
+FALSE (MAY be absent). The controlValue is an OCTET STRING, whose
+value is the BER encoding of a value of the following SEQUENCE:
+
+ SortResult ::= SEQUENCE {
+ sortResult ENUMERATED {
+ success (0), -- results are sorted
+ operationsError (1), -- server internal failure
+ timeLimitExceeded (3), -- timelimit reached before
+ -- sorting was completed
+ strongAuthRequired (8), -- refused to return sorted
+ -- results via insecure
+ -- protocol
+ adminLimitExceeded (11), -- too many matching entries
+ -- for the server to sort
+ noSuchAttribute (16), -- unrecognized attribute
+ -- type in sort key
+ inappropriateMatching (18), -- unrecognized or inappro-
+ -- priate matching rule in
+ -- sort key
+ insufficientAccessRights (50), -- refused to return sorted
+ -- results to this client
+ busy (51), -- too busy to process
+ unwillingToPerform (53), -- unable to sort
+ other (80)
+ },
+ attributeType [0] AttributeDescription OPTIONAL }
+
+4. Client-Server Interaction
+
+The sortKeyRequestControl specifies one or more attribute types and
+matching rules for the results returned by a search request. The server
+SHOULD return all results for the search request in the order specified
+by the sort keys. If the reverseOrder field is set to TRUE, then the
+entries will be presented in reverse sorted order for the specified
+key.
+
+There are six possible scenarios that may occur as a result of the sort
+control being included on the search request :
+
+1 - If the server does not support this sorting control and the client
+specified TRUE for the control's criticality field, then the server
+MUST return unavailableCriticalExtension as a return code in the
+searchResultDone message and not send back any other results. This
+behavior is specified in section 4.1.12 of [LDAPv3].
+
+2 - If the server does not support this sorting control and the client
+specified FALSE for the control's criticality field, then the server
+MUST ignore the sort control and process the search request as if it
+were not present. This behavior is specified in section 4.1.12 of
+[LDAPv3].
+
+3 - If the server supports this sorting control but for some reason
+cannot sort the search results using the specified sort keys and the
+client specified TRUE for the control's criticality field, then the
+server SHOULD do the following: return unavailableCriticalExtension as
+a return code in the searchResultDone message; include the
+sortKeyResponseControl in the searchResultDone message, and not send
+back any search result entries.
+
+4 - If the server supports this sorting control but for some reason
+cannot sort the search results using the specified sort keys and the
+client specified FALSE for the control's criticality field, then the
+server should return all search results unsorted and include the
+sortKeyResponseControl in the searchResultDone message.
+
+5 - If the server supports this sorting control and can sort the search
+results using the specified sort keys, then it should include the
+sortKeyResponseControl in the searchResultDone message with a
+sortResult of success.
+
+6 - If the search request failed for any reason and/or there are no
+searchResultEntry messages returned for the search response, then the
+server SHOULD omit the sortKeyResponseControl from the
+searchResultDone message.
+
+The client application is assured that the results are sorted in the
+specified key order if and only if the result code in the
+sortKeyResponseControl is success. If the server omits the
+sortKeyResponseControl from the searchResultDone message, the client
+SHOULD assume that the sort control was ignored by the server.
+
+The sortKeyResponseControl, if included by the server in the
+searchResultDone message, should have the sortResult set to either
+success if the results were sorted in accordance with the keys
+specified in the sortKeyRequestControl or set to the appropriate error
+code as to why it could not sort the data (such as noSuchAttribute or
+inappropriateMatching). Optionally, the server MAY set the
+attributeType to the first attribute type specified in the SortKeyList
+that was in error. The client SHOULD ignore the attributeType field if
+the sortResult is success.
+
+The server may not be able to sort the results using the specified sort
+keys because it may not recognize one of the attribute types, the
+matching rule associated with an attribute type is not applicable, or
+none of the attributes in the search response are of these types.
+Servers may also restrict the number of keys allowed in the control,
+such as only supporting a single key.
+
+Servers that chain requests to other LDAP servers should ensure that
+the server satisfying the client's request sort the entire result set
+prior to sending back the results.
+
+4.1 Behavior in a chained environment
+
+If a server receives a sort request, the client expects to receive a
+set of sorted results. If a client submits a sort request to a server
+which chains the request and gets entries from multiple servers, and
+the client has set the criticality of the sort extension to TRUE, the
+server MUST merge sort the results before returning them to the client
+or MUST return unwillingToPerform.
+
+4.2 Other sort issues
+
+An entry that meets the search criteria may be missing one or more of
+the sort keys. In that case, the entry is considered to have a value of
+NULL for that key. This standard considers NULL to be a larger value
+than all other valid values for that key. For example, if only one key
+is specified, entries which meet the search criteria but do not have
+that key collate after all the entries which do have that key. If the
+reverseOrder flag is set, and only one key is specified, entries which
+meet the search criteria but do not have that key collate BEFORE all
+the entries which do have that key.
+
+If a sort key is a multi-valued attribute, and an entry happens to have
+multiple values for that attribute and no other controls are present that
+affect the sorting order, then the server SHOULD use the least value
+(according to the ORDERING rule for that attribute).
+
+5. Interaction with other search controls
+
+When the sortKeyRequestControl control is included with the
+pagedResultsControl control as specified in [LdapPaged], then the
+server should send the searchResultEntry messages sorted according to
+the sort keys applied to the entire result set. The server should not
+simply sort each page, as this will give erroneous results to the
+client.
+
+The sortKeyList must be present on each searchRequest message for the
+paged result. It also must not change between searchRequests for the
+same result set. If the server has sorted the data, then it SHOULD
+send back a sortKeyResponseControl control on every searchResultDone
+message for each page. This will allow clients to quickly determine
+if the result set is sorted, rather than waiting to receive the entire
+result set.
+
+
+6. Security Considerations
+
+Implementors and administrators should be aware that allowing sorting
+of results could enable the retrieval of a large number of records from
+a given directory service, irregardless of administrative limits set on
+the maximum number of records to return.
+
+A client that desired to pull all records out of a directory service
+could use a combination of sorting and updating of search filters to
+retrieve all records in a database in small result sets, thus
+circumventing administrative limits.
+
+This behavior can be overcome by the judicious use of permissions on
+the directory entries by the administrator and by intelligent
+implementations of administrative limits on the number of records
+retrieved by a client.
+
+
+7. References
+
+[LDAPv3]
+ Wahl, M, S. Kille and T. Howes, "Lightweight Directory Access
+Pro-
+ tocol (v3)", RFC 2251, December, 1997.
+
+[Bradner97]
+ Bradner, Scott, "Key Words for use in RFCs to Indicate
+Requirement
+ Levels", RFC 2119, March, 1997.
+
+[LdapPaged]
+ C. Weider, A. Herron, and T. Howes, "LDAP Control Extension for
+ Simple Paged Results Manipulation", Internet Draft, February, 1997.
+ Available as draft-ietf-asid-ldapv3-simplepaged-00.txt.
+
+
+8. Author's Address
+
+ Anoop Anantha
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ Anoopa@microsoft.com
+ +1 425 882-8080
+
+ Andy Herron
+ Microsoft Corp.
+ 1 Microsoft Way
+ Redmond, WA 98052
+ USA
+ andyhe@microsoft.com
+ +1 425 882-8080
+
+ Tim Howes
+ Netscape Communications Corp.
+ 501 E. Middlefield Road
+ Mountain View, CA 94043
+ USA
+ howes@netscape.com
+ +1 415 937-2600
+
+ Mark Wahl
+ Critical Angle Inc.
+ 4815 W Braker Lane #502-385
+ Austin, TX 78759
+ USA
+ M.Wahl@critical-angle.com
+
--- /dev/null
+
+Extended Operations for Framing LDAP Operations
+Internet-Draft
+Intended Category: Standards Track
+Expires: September 10, 2000
+
+
+ Ellen Stokes
+ IBM Corporation
+
+ Roger Harrison
+ Novell, Inc.
+
+ Gordon Good
+ Netscape Communications Corp.
+
+ March 10, 2000
+
+ Extended Operations for Framing LDAP Operations
+ Filename: draft-ietf-ldup-framing-00.txt
+
+Table of Contents
+
+1. Status of this Memo.............................................2
+2. Abstract........................................................2
+3. Overview........................................................2
+4. Protocol element definitions....................................3
+4.1 StartFramedProtocolRequest Extended Operation...................3
+4.2 StartFramedProtocolResponse Extended Operation..................3
+4.3 EndFramedProtocolRequest Extended Operation.....................4
+4.4 EndFramedProtocolResponse Extended Operation....................4
+5. Acknowledgments.................................................5
+6. References......................................................5
+7. Author's Addresses..............................................5
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Stokes, Harrison and Good [Page 1]
+\f
+Internet-Draft LDUP Workgroup March 10, 2000
+
+
+1. Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that other
+ groups may also distribute working documents as Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet- Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+.
+
+ This Internet Draft expires September 10, 2000.
+
+
+2. Abstract
+
+ Certain types of LDAP applications can benefit from the ability to
+ specify the beginning and end of a related group of operations. For
+ example, the LDUP multimaster update protocol [ARCHITECTURE] requires
+ that two servers agree to begin a session to transfer pending
+ replication updates. This document provides a framework for
+ constructing protocols that feature a framed set of related
+ operations. It defines a pair of LDAPv3 extended operations that
+ provide begin-end framing, and a pair of extended operations used to
+ respond the begin-end framing operations. The nature of the actual
+ LDAP operations carried inside these framing operations is not
+ specified in this document.
+
+ All protocol elements described here are LDAP Version 3 extended
+ operations. LDAP Version 3 is described in RFC 2251 [LDAPv3].
+
+ Certain terms used in this document are defined in the document "LDAP
+ Replication Architecture" [ARCHITECTURE].
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
+ to be interpreted as described in RFC 2119 [KEYWORDS].
+
+3. Overview
+
+ This document describes two LDAPv3 Extended Operations that are used
+ to signal the beginning and end of a set of grouped operations, and
+
+
+
+Stokes, Harrison and Good [Page 2]
+\f
+Internet-Draft LDUP Workgroup March 10, 2000
+
+
+ two LDAPv3 extended operations that are used to respond to these
+ operations. These extended operations provide a framework that may be
+ used when developing a protocol that requires begin-end framing.
+
+4. Protocol element definitions
+
+4.1 StartFramedProtocolRequest Extended Operation
+
+ The StartFramedProtocolRequest extended operation indicates that the
+ initiator wishes to begin transmission of a set of related LDAP
+ operations. The requestValue of the StartFramedProtocolRequest
+ extended operation contains an OID that describes the specific framed
+ protocol being initiated, and a protocol-specific payload.
+
+ An LDAPv3 Extended Request is defined in [LDAPv3] as follows:
+
+ ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+ requestName [0] LDAPOID,
+ requestValue [1] OCTET STRING OPTIONAL
+ }
+
+ The requestName portion of the StartFramedProtocolRequest must be the
+ OID "2.16.840.1.113719.1.142.100.1".
+
+ The requestValue of the StartFramedProtocolRequest must be set to the
+ BER-encoding of the following:
+
+ StartFramedProtocolRequestValue ::= SEQUENCE {
+ framedProtocolOID LDAPOID,
+ framedProtocolPayload OPTIONAL OCTET STRING
+ }
+
+ The parameters in the requestValue of the StartFramedProtocolRequest
+ are:
+
+ - framedProtocolOID: An OID that uniquely identifies the protocol
+ framed by this operation. - framedProtocolPayload: An octet
+ string that contains protocol-specific
+ information.
+
+
+4.2 StartFramedProtocolResponse Extended Operation
+
+ The StartFramedProtocolResponse extended operation is sent in
+ response to a StartFramedProtocolResponse extended operation.
+
+ An LDAPv3 Extended Response is defined in [LDAPv3] as follows:
+
+
+
+
+Stokes, Harrison and Good [Page 3]
+\f
+Internet-Draft LDUP Workgroup March 10, 2000
+
+
+ ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+ COMPONENTS of LDAPResult,
+ responseName [10] LDAPOID OPTIONAL,
+ response [11] OCTET STRING OPTIONAL
+ }
+
+ The responseName of the StartFramedProtocolResponse must be the OID
+ "2.16.840.1.113719.1.142.100.2".
+
+ The response of the StartFramedProtocolResponse is set to the BER-
+ encoding of a protocol-specific response.
+
+4.3 EndFramedProtocolRequest Extended Operation
+
+ The EndFramedProtocolRequest extended operation indicates the end a
+ set of related LDAP operations. The requestValue of the
+ EndFramedProtocolRequest extended operation contains a protocol-
+ specific payload.
+
+ An LDAPv3 Extended Request is defined in [LDAPv3] as follows:
+
+ ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+ requestName [0] LDAPOID,
+ requestValue [1] OCTET STRING OPTIONAL
+ }
+
+ The requestName of the EndFramedProtocolRequest must be the OID
+ "2.16.840.1.113719.1.142.100.4".
+
+ The requestValue of the EndFramedProtocolRequest is set to the BER-
+ encoding of a protocol-specific response.
+
+4.4 EndFramedProtocolResponse Extended Operation
+
+ The EndFramedProtocolResponse extended operation is sent in response
+ to an EndFramedProtocolRequest.
+
+ An LDAPv3 Extended Response is defined in [LDAPv3] as follows:
+
+ ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+ COMPONENTS of LDAPResult,
+ responseName [10] LDAPOID OPTIONAL,
+ response [11] OCTET STRING OPTIONAL
+ }
+
+ The responseName of the EndFramedProtocolResponse must be the OID
+ "2.16.840.1.113719.1.142.100.5".
+
+
+
+
+Stokes, Harrison and Good [Page 4]
+\f
+Internet-Draft LDUP Workgroup March 10, 2000
+
+
+ The response of the EndFramedProtocolResponse is set to the BER-
+ encoding of a protocol-specific response.
+
+5. Acknowledgments
+
+The authors gratefully acknowledge the contributions of the IETF LDUP
+working group.
+
+6. References
+
+
+[KEYWORDS]
+ S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
+ els", Harvard University, RFC 2119, March 1997.
+
+
+[ARCHITECTURE]
+ J. Merrells, E. Reed, U. Srinivasan, "LDAP Replication Architec-
+ ture", Internet-Draft, draft-ietf-ldup-model-02.txt, October 1999.
+
+
+[LDAPv3]
+ M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
+ (v3)", RFC 2251, December 1997.
+
+7. Author's Addresses
+
+ Ellen Stokes
+ IBM
+ 11400 Burnet Rd
+ Austin, TX 78758
+ USA
+ EMail: stokes@austin.ibm.com
+ phone: +1 512 838 3725
+ fax: +1 512 838 0156
+
+ Roger Harrison
+ Novell, Inc.
+ 122 E. 1700 S.
+ Provo, UT 84606
+ USA
+ EMail: roger_harrison@novell.com
+ Phone: +1 801 861 2642
+
+ Gordon Good
+ Netscape Communications Corp.
+ 501 E. Middlefield Rd.
+ Mailstop MV068
+
+
+
+Stokes, Harrison and Good [Page 5]
+\f
+Internet-Draft LDUP Workgroup March 10, 2000
+
+
+ Mountain View, CA 94043
+ USA
+ EMail: ggood@netscape.com
+ Phone: +1 650 937-3825
+
+
+Appendix A - Complete ASN.1 Definition
+
+StartFramedProtocolRequest ::= ExtendedRequest
+
+StartFramedProtocolRequestValue ::= SEQUENCE {
+ framedProtocolOID LDAPOID,
+ framedProtocolPayload OPTIONAL OCTET STRING
+}
+
+StartFramedProtocolResponse ::= ExtendedResponse
+
+EndFramedProtocolRequest ::= ExtendedRequest
+
+EndFramedProtocolResponse ::= ExtendedResponse
+
+Full Copyright Statement
+
+Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+This document and translations of it may be copied and furnished to oth-
+ers, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and dis-
+tributed, 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 Stan-
+dards process must be followed, or as required to translate it into
+languages other than English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an "AS
+IS" basis and 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 FIT-
+NESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+Stokes, Harrison and Good [Page 6]
--- /dev/null
+INTERNET-DRAFT
+draft-ietf-ldup-infomod-01.txt
+ Ed Reed
+ Reed-Matthews, Inc.
+ March 9, 2000
+
+ LDUP Replication Information Model
+
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026.
+
+Internet-Drafts are working documents of the Internet Engineering Task
+Force (IETF), its areas, and its working groups. Note that other
+groups may also distribute working documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet-Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt.
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+This Internet-Draft expires on May 11, 1999.
+
+
+2. Abstract
+
+[LDUP Model] describes the architectural approach to replication of
+LDAP directory contents. This document describes the information
+model and schema elements which support LDAP Replication Services
+which conform to [LDUP Model].
+
+Directory schema is extended to provide object classes, subentries,
+and attributes to describe areas of the namespace which are under
+common administrative authority, units of replication (ie, subtrees,
+or partitions of the namespace, which are replicated), servers which
+hold replicas of various types for the various partitions of the
+namespace, which namespaces are held on given servers, and the
+progress of various namespace management and replication operations.
+Among other things, this knowledge of where directory content is
+
+
+
+Reed [Page 1]
+ Expires September 9, 2000 \f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+located will provide the basis for dynamic generation of LDAP
+referrals for clients who can follow them.
+
+The controlling framework by which the relationships, types, and
+health of replicas of the directory content will be defined so that,
+as much as possible, directory content is itself used to monitor and
+control the environment.
+
+Security information, including access control policy identifiers and
+information will be treated as directory content by the replication
+protocols when specified by the LDAPEXT group.
+
+The information model will describe required and optional house-
+keeping duties for compliant systems to implement, such as garbage
+collection of deleted objects, reconciliation of moved and renamed
+objects, update sequencing and transaction bracketing of changes, etc.
+
+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 RFC 2119 [RFC2119]. The
+sections below reiterate these definitions and include some additional
+ones.
+
+
+2.1 Changes in this version
+
+LDAP Subentry definition is moved to its own document [SUBENTRY].
+
+LDAP Schedule Subentry definition is defined.
+
+LDAP Access Point removed in favor of just using the DN of the server
+holding the replica (so a new syntax isn't required).
+
+LDAP Change Sequence Number syntax eleminated in favor of just calling
+it a CaseIgnoreString, so new comparison rules aren't required.
+
+Deleted ldapSearchFilter definition from here. Sparse replicas is
+deferred. Might sparse be supported for single-master configurations
+(read-only, of course).
+
+Fractional are okay in multi-master configurations, but again, only on
+read-only replicas.
+
+Changed the naming convention upper-lower case usage to look less
+weird.
+
+Note:
+
+
+Reed [Page 2]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+Consistency discussion
+
+Schema document must clearly indicate that clients can and should
+inspect the replica subentries to understand the single-master/multi-
+master nature of the naming context to which they're talking.
+
+The paradigm change, to distributed data, needs to be exhaustively
+discussed in the profile documents. How old applications which assume
+single-master behave or misbehave in a multi-master environment is
+critical to make clear. Draw examples from SMP pre-emptive
+programming practices, from DNS vs host file models, etc.
+
+
+
+Decisions from wash ietf_
+
+1) define two simple schema classes _ event driven histeresis
+ buckets, and cron-like thing. Then, the replica has a single
+ value pointer to a schedule. More schedule things can be
+ defined in the future.
+
+2) Create attribute ReplicaURI to provide service access point for
+ that replica. No DSA entry requirement.
+
+3) Replica id table discussion should move to protocol spec.
+
+To do:
+1) define the cron schedule subentry class
+2) define the rest of the attributes used in the classes
+3) verify LDUP OID number with Novell (!) one more time
+4) verify all OIDs assigned
+5) verify all OIDs documented at the end of the document
+6) scrub editorial comments
+7) cross reference with arch document on schema element names
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reed [Page 3]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+Table of Contents
+1. Status of this Memo .............................................1
+2. Abstract 1
+2.1 Changes in this version........................................2
+3. Introduction ....................................................4
+3.1 Scope 4
+3.2 Terms and Definitions..........................................5
+4. Data design: ....................................................5
+5. Directory Knowledge .............................................5
+6. Schema 6
+6.1 Data Structure Definitions.....................................6
+6.1.1 ldapChangeSequenceNumber..................................6
+6.2 Attribute Definitions..........................................7
+6.2.1 attributeExclusionFilter..................................7
+6.2.2 attributeInclusionFilter..................................8
+6.2.3 replicaURI................................................8
+6.2.4 replicationStatus.........................................9
+6.2.5 replicaType...............................................9
+6.2.6 SecsToWait Attributes....................................11
+6.2.6.1 secsToWaitCat1 ........................................11
+6.2.6.2 secsToWaitCat2 ........................................11
+6.2.6.3 secsToWaitCat3 ........................................11
+6.2.6.4 secsToWaitCat4 ........................................11
+6.2.6.5 secsToWaitCat5 ........................................11
+6.2.7 updateVector.............................................12
+6.3 Class Definitions.............................................12
+6.3.1 nameContext..............................................12
+6.3.2 replicaSubentry..........................................12
+6.3.3 replicaAgreementSubentry.................................13
+6.3.4 eventScheduledSubentry Class.............................14
+6.3.5 timeScheduledSubentry Class..............................15
+7. Object Identifier Assignments ..................................15
+8. Security Considerations ........................................16
+9. References .....................................................16
+10. Copyright Notice ...............................................17
+11. Acknowledgements ...............................................17
+12. Author's Address ...............................................18
+
+
+3. Introduction
+
+
+3.1 Scope
+
+This document describes schema of subentries representing replicas,
+replication agreements and their dependencies.
+
+
+
+Reed [Page 4]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+Management and status schema elements may be defined if there is
+sufficient consensus.
+
+Semantic interpretation of schema elements, including any special
+handling expectations are to be provided here.
+
+
+3.2 Terms and Definitions
+
+Definitions are provided in [LDUP Requirements], and may be reproduced
+here for the convenience of the reader.
+
+
+
+4. Data design:
+
+As described in [LDUP Model], knowledge of replicated portions of the
+directory information tree (DIT) is stored in the directory itself.
+
+An auxiliary class is defined to designate containers, or nodes, in
+the DIT which are the root-most, or base, of naming contexts
+[RFC2251]. Directory subentries [X501] are used to hold information
+about replicas and replica agreements.
+
+
+
+5. Directory Knowledge
+
+Information about what replicas exist, what they contain, their types,
+where they are stored, and how they may be contacted inevitably
+provides the basis for distributed directory knowledge. As namespaces
+from stand-alone servers are inter-connected with one another, this
+replica information can and will be used by name resolution operations
+to locate servers holding copies of specific objects, and to optimize
+distributed searches which span multiple Naming Contexts.
+
+However, the focus of this document is NOT to fully enable such
+distributed directory uses. Instead, we are focused on how portions
+of the namespace (Directory Information Tree - DIT) may be replicated,
+and how those replicas are configured and related to one another via
+Replication Agreements.
+
+As such, the following high level description (from [LDUP Model])of
+the information model envisioned is provided as reference for the
+reader before presenting the detailed specifications.
+
+Generally, the DSE Naming Context attribute of an LDAPv3 server names
+the Naming Contexts for which there are replicas on that server.
+
+Reed [Page 5]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+The Naming Context Auxiliary Class (nameContext) is added to container
+objects which may have separately defined replication policy.
+
+Immediately subordinate to a Naming Context object are the Replica
+Subentry containers which identify where the identified replica
+resides (ie, its LDAP Access Point), its type (Primary, Updateable,
+ReadOnly), if it is sparse, the LDAP search filter which defines what
+object classes it holds, and if it is fractional, the attributes it
+does or does not hold.
+
+Immediately subordinate in the namespace to a Replica Subentry are
+Replication Agreement leaf entries which each identify another
+Replica, the scheduling policy for replication operations (including
+times when replication is to be performed, when it is not to be
+performed, or the policies governing event-driven replication
+initiation).
+
+
+
+6. Schema
+
+
+6.1 Data Structure Definitions
+
+For the purposes of defining the encoding rules for attribute
+structures, the BNF definitions in section 4.1 of [RFC2252] will be
+used. They are based on the BNF styles of [RFC822].
+
+To avoid requiring new syntax support to be added unnecessarily to
+existing LDAPv3 directory service implementations (and the
+accompanying matching rules, etc. they would entail), a string
+encoding is defined for ldapChangeSequenceNumber which can use
+CaseIgnoreString matching rules for ordering and equality.
+
+6.1.1 ldapChangeSequenceNumber
+
+( 1.3.6.1.4.1.1466.115.121.1.TBD DESC 'LDAP Change Sequence Number' )
+
+Values in this syntax are encoded according to the following BNF.
+Note there MUST NOT be any whitespace separators, unless they are in
+replicaID, which must be encoded according to the instructions below.
+
+This encoding is specified so that the CaseIgnoreString equality and
+ordering rules will work correctly when replicaNumber is used.
+
+When replicaID is used, CaseIgnoreString comparison rules will not
+work unless each replicaID is exactly the same length with no padded
+
+
+Reed [Page 6]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+white spaces (because CaseIgnoreString suppresses duplicate adjacent
+white space when it compares two strings).
+
+LDAPChangeSequenceNumber = GeneralizedZTime "#" S1 "#" replicaID
+ "#" S2
+GeneralizedZTime = yyyy | mm | dd | hh | mi | ss | "Z"
+yyyy = dddd <four digit year, e.g. 1998>
+mm = dd <two digit month of the year, e.g. 06>
+dd = dd <two digit day of month, e.g. 17>
+hh = dd <two digit hour of the day, inclusive range (00..23)>
+mi = dd <two digit minute of the hour, inclusive range (00..59)>
+ss = dd <two digit seconds of the minute, inclusive range (00..59)>
+replicaID = dstring
+S1, S2 = numericstring
+
+The GeneralizedTime is used as described (cf. [X680] section 39.3 case
+b) without separators or whitespace, and representing a coordinated
+universal time (i.e., Greenwich Mean Time, or GMT). All times
+referenced by this syntax MUST be normalized to GMT - no local times,
+nor time zone offsets are permitted. To simplify comparisons of two
+CSNs, the "Z" MUST be the UTF-8 capital-Z character.
+
+The ReplicaID represents the specific Replica of this Naming Context
+where the event associated with this LDAPChangeSequenceNumber
+occurred. Note that in actual transfer, the ReplicaID MAY be
+represented by a number (see the specification of the
+replicaLookupTable, above).
+
+S1 and S2 are sequence numbers which are used to order two events with
+the same Generalized Time and ReplicaID. In order to use string
+matching rules for equality and ordering with values with this
+encoding, the length of each field must be consistent. Thus, all
+instances of S1 MUST be represented with the same number of digits,
+using leading zeros as necessary. The same with S2 and replicaID.
+
+
+
+
+6.2 Attribute Definitions
+
+
+6.2.1 attributeExclusionFilter
+
+( 2.16.840.1.113719.142.4.1 NAME 'attributeExclusionFilter'
+ SYNTAX OCTET STRING
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation )
+
+
+
+Reed [Page 7]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+The attributeExclusionFilter is intended to contain a list of
+attributes in the form of an AttributeDescriptionList as described in
+section 4.5.1. Search Request of [RFC2251] with the following
+interpretation: an empty attributeExclusionFilter means that no
+attributes are excluded; the special values "*" and "1.1" mean that
+ALL attributes are excluded.
+
+A non-empty attributeExclusionFilter attribute on a replica subEntry
+describes the attributes NOT PRESENT on entries held by that replica.
+Replicas MUST NOT accept changes for attributes they're not permitted
+to hold, per the attributeInclusionFilter and attributeExclusionFilter
+attributes on their replica subEntry.
+
+A non-empty attributeExclusionFilter attribute on a
+replicationAgreement subEntry describes which additional attributes
+are to be excluded from the updates to be sent from the supplier
+replica to the consumer replica.
+
+
+6.2.2 attributeInclusionFilter
+
+( {2.16.840.1.113719.142.4.2 NAME 'attributeInclusionFilter'
+ SYNTAX OCTET STRING
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation )
+
+The attributeInclusionFilter is intended to contain a list of
+attributes in the form of an AttributeDescriptionList as described in
+section 4.5.1. Search Request of [RFC2251] with the following
+interpretation: an empty attributeInclusionFilter means that all
+attributes are included; the special value "*" means that ALL
+attributes are included; the special value "1.1" is meaningless and is
+ignored in this usage.
+
+A non-empty attributeInclusionFilter attribute on a replica subEntry
+describes the attributes that may be PRESENT on entries held by that
+replica. Replicas MUST NOT accept changes for attributes they're not
+permitted to hold, per the attributeIncludionFilter and
+attributeExclusionFilter attributes on their replica subEntry.
+
+
+6.2.3 replicaURI
+
+(2.16.840.1.113719.142.4.x NAME `replicaURI'
+ DESC `how to connect to this replica'
+ SYNTAX ldapURI
+ USAGE dSAOperation )
+
+
+
+Reed [Page 8]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+6.2.4 replicationStatus
+
+(2.16.840.1.113719.142.4.3 NAME 'replicationStatus'
+ DESC 'human readable status of last replication attempt'
+ SYNTAX DirectoryString
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation )
+
+
+The replicationStatus attribute MAY be used to hold a human readable
+message describing the most recent replication session attempt for a
+replicationAgreement.
+
+For example, such a messages might include
+
+1) 19980805162203Z # Success #
+
+2) 19980805162322Z # Failure # Server too busy, try again
+
+3) 19980805170215Z # Failure # Unable to connect to DSA
+
+4) 19980806002301Z # Failure # Authentication failed
+
+5) 19980806003201Z # Failure # lost connection, reset by peer
+
+It is suggested, but not required, that the time of a replication
+attempt (completion, if successful or failure, if not), the result of
+the attempt, and any additional information about a failure be
+included in the string message.
+
+It is suggested, but not required, that the messages be stored with
+language tags (English, French, German, Japanese, Chinese, per [LANG
+TAG]) particularly if multiple translations of the error messages are
+available to the DSA implementers.
+
+Note that this is a single-valued attribute. Sequences of status
+entries SHOULD be written to log files or other persistent storage, or
+in multi-valued replication history attributes, but are not specified
+here.
+
+
+6.2.5 replicaType
+
+(2.16.840.1.113719.142.4.4 NAME 'replicaType'
+ DESC 'Enum: 0-reserved, 1-Primary, 2-Updateable, 3-ReadOnly, all
+others reserved'
+ EQUALITY integerMatch
+ SYNTAX INTEGER
+ SINGLE-VALUE NO-USER-MODIFICATION USAGE dSAOperation )
+
+Reed [Page 9]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+ReplicaType is a simple enumeration, used to identify what kind of
+replica is being described in a Replica object entry.
+
+A ReadOnly replica only accepts LDAP Search operations (to Read
+entries, list containers, and search for entries). Because no updates
+ever originate from ReadOnly replicas, they never have changes to send
+to another replica. However, a ReadOnly replica may be designated a
+supplier DSA in a replica agreement, if it is simply passing along
+information it receives from other Updateable replicas about entries
+and their changes.
+
+ReadOnly replicas may be incomplete replicas.
+
+An Updateable replica may accept both LDAP Search operations (to read,
+list, or search entries), as well as modification operations (to add,
+modify, or delete entries).
+
+The consequences of having incomplete updateable replicas are not
+fully understood. LDAP DSAs MAY require updateable replicas to be
+complete replicas.
+
+A Primary replica is an Updateable replica, but it is "more special"
+than other Updateable replicas. When LDAP application want to direct
+their operations to a single replica, so that the application can be
+sure that all application LDAP modification (add, delete, modify)
+operations will be immediately visible to application readers, the
+Primary replica is a good choice. Such a use would be consistent with
+High Confidence DAP option [X518]. One such application might be a
+management application which creates new naming contexts or joins two
+naming contexts into a single naming context. Another application
+might be one which creates new replicas, or replication agreements.
+
+There SHOULD be only one Primary replica defined for a naming context
+at any time. If applications, expecting there to be a Primary replica
+discover, by search or inspection of ReplicaType attributes of the
+defined Replicas of a naming context, find more than one _ they should
+realize that something is wrong.
+
+There MAY be NO primary replica defined for a naming context.
+
+Primary replicas MAY NOT be incomplete replicas.
+
+The way in which replicas change their type, as from ReadOnly to
+Updateable, or Updateable to Primary is outside the scope of this
+document.
+
+Section 5.1 "Replica Type" of [LDUP MODEL] details the permissible
+combinations of replica types and sparse/fractional replicas.
+
+Reed [Page 10]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+6.2.6 SecsToWait Attributes
+
+The secsToWait attributes document the number of seconds a replica is
+to wait after the occurrence of a "category n" change event before
+initiating a new replication session for replicationAgreements
+governed by an eventScheduledSubentry. The definition of a "category
+n" change event is implementation dependent, and may be defined
+differently by different directory servers. The absence of a value
+for any of these attributes MUST be interpreted as meaning "do not
+initiate a replication session for change events of this category".
+
+
+6.2.6.1 secsToWaitCat1
+
+( 2.16.840.1.113719.142.4.5.1 NAME 'secsToWaitCat1'
+ SYNTAX INTEGER
+ USAGE dSAOperation )
+
+
+6.2.6.2 secsToWaitCat2
+
+( 2.16.840.1.113719.142.4.5.2 NAME 'secsToWaitCat2'
+ SYNTAX INTEGER
+ USAGE dSAOperation )
+
+
+6.2.6.3 secsToWaitCat3
+
+( 2.16.840.1.113719.142.4.5.3 NAME 'secsToWaitCat3'
+ SYNTAX INTEGER
+ USAGE dSAOperation )
+
+
+6.2.6.4 secsToWaitCat4
+
+( 2.16.840.1.113719.142.4.5.4 NAME 'secsToWaitCat4'
+ SYNTAX INTEGER
+ USAGE dSAOperation )
+
+
+6.2.6.5 secsToWaitCat5
+
+( 2.16.840.1.113719.142.4.5.5 NAME 'secsToWaitCat5'
+ SYNTAX INTEGER
+ USAGE dSAOperation )
+
+
+
+
+Reed [Page 11]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+6.2.7 updateVector
+
+( 2.16.840.1.113719.142.4.6 NAME 'updateVector'
+ SYNTAX ldapChangeSequenceNumberSyntax
+ NO-USER-MODIFICATION USAGE dSAOperation )
+
+The attribute updateVector is a multi-valued attribute which contains
+information for a replica describing the latest changes received by
+the replica from other replicas.
+
+There may be only one ldapChangeSequenceNumber entry from each replica
+in the updateVector. That is to say, there is a unique value
+constraint on the ReplicaID component of entries in the list.
+
+
+6.3 Class Definitions
+
+
+6.3.1 nameContext
+
+( 2.16.840.1.113719.142.6.2.1 NAME 'nameContext' SUP top AUXILIARY )
+
+
+The nameContext auxiliary class, when present on an object, indicates
+the beginning, or root, of a naming context. The naming context is
+said to be rooted at the entry with the nameContext auxiliary class in
+its list of object classes. The root-most entry of a naming context
+is the entry with the nameContext auxiliary class in its list of
+object classes.
+
+Characteristics of the replication topology of a naming context are
+defined in the replicaSubentry sub-entries associated with the naming
+context.
+
+The attribute accessControlPolicyOID has been removed from here, and
+should be published as an ldapSubEntry subordinate to the nameContext,
+instead.
+
+The attribute nameContextCreationTimestamp used here in previous
+drafts has been eliminated as redundant. The ldapChangeSequenceNumber
+associated with the nameContext value in the list of objectClasses
+attribute serves the same purpose.
+
+
+6.3.2 replicaSubentry
+
+( 2.16.840.1.113719.142.6.3.1 NAME 'replicaSubentry' SUP ldapSubEntry
+ STRUCTURAL
+
+Reed [Page 12]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+ MUST (cn, replicaURI, replicaType)
+ MAY (attributeExclusionFilter, attributeInclusionFilter,
+description, updateVector) )
+
+Entries of type replicaSubentry MAY be named by their cn attribute.
+
+The attributes attributeExclusionFilter and attributeInclusionFilter,
+if present, govern which entries and attributes from the local naming
+context are to be sent (or not sent) to the replica named in replicaDN
+of replica agreements for this replica. The attributeExclusionFilter
+names attributes which SHOULD NOT be sent. The
+attributeInclusionFilter names attributes which SHOULD be sent.
+
+The attribute replicaURI contains information in ldapURI format that
+can be used to contact (ie, open a connection to) this replica.
+
+The attribute description contains a human-readable description of the
+sub-entry.
+
+The attribute updateVector contains a set of
+ldapChangeSequenceNumbers, one for each of the other replicas for this
+naming context, which records, from this replicas perspective, the
+last change event received from the other indicated replica.
+
+
+6.3.3 replicaAgreementSubentry
+
+( 2.16.840.1.113719.142.6.4.1 NAME 'replicaAgreementSubentry'
+ SUP ldapSubEntry STRUCTURAL
+ MUST ( cn )
+ MAY ( attributeExclusionFilter, description, replicaDN,
+replicationMechanismOID, replicationStatus, scheduleDN ) )
+
+Entries of type replicaAgreementSubentry MAY be named by their cn
+attribute.
+
+The attributes attributeExclusionFilter, and ldapSearchFilter, if
+present, govern which entries and attributes from the local naming
+context are to be sent (or not sent) to the replica named in
+replicaDN. The attributeExclusionFilter names attributes SHOULD NOT be
+sent. Note there is no attributeInclusionFilter, because the list of
+attributes that may be sent may not be extended beyond those
+documented in the attributeInclusionFilter on the replicaSubentry.
+
+Processing of allowable changes to be sent is as follows:
+
+1) the attributeInclusionFilter from the replica subentry defines a
+ set of attributes which SHOULD be sent, less exclusions;
+
+Reed [Page 13]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+2) the union of attributes excluded by the attributeExclusionFilter
+ from the replicasubentry and the attributeExclusionFilter from the
+ replicaAgreementSubentry defines a set of attributes which SHOULD
+ NOT be sent;
+
+3) the subtraction of attributes which SHOULD NOT be sent by (2) from
+ the attributes which SHOULD be sent by (1) constitute the set of
+ attributes for which changes MAY be sent.
+
+The attribute description contains a human-readable description of the
+sub-entry.
+
+The attribute replicaDN of syntax DN names another sub-entry of type
+replicaSubentry to whom changes are to be sent. If there is no value
+for the replicaDN attribute on a replicaAgreementSubentry, the
+replicaAgreementSubentry is ignored. Absence of a value may occur
+briefly when replicas and replica agreements are first being created,
+or when the replica to which a replica agreement applies is being
+deleted.
+
+The attribute replicationStatus MAY be used to record the most recent
+result of an attempt to send changes to the replica named in
+replicaDN, whether success, or if failure, the nature of the problem
+encountered.
+
+The attribute schedule, if present, names one or more entries of type
+scheduleSubentry which govern the schedule for replication attempts.
+If not present, replication MUST be attempted when there are changes
+to be sent.
+
+
+6.3.4 eventScheduledSubentry Class
+
+( 2.16.840.1.113719.142.6.1.1 NAME 'eventScheduledSubentry'
+ SUP ldapSubEntry STRUCTURAL
+ MUST ( cn )
+ MAY ( description, secsToWaitCat1, secsToWaitCat2, secsToWaitCat3,
+secsToWaitCat4, secsToWaitCat5 ) )
+
+Note that replication agreements using eventScheduledSubentry policy
+are, by definition, supplier-initiated.
+
+The description attribute may be used by the administrator to document
+or comment on this subentry.
+
+The secsToWaitCat1 attribute documents the number of seconds a replica
+is to wait after the occurrence of a "category 1" change event before
+initiating a new replication session for replicationAgreements
+
+Reed [Page 14]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+governed by this eventScheduledSubentry. The definition of a
+"category 1" change event is implementation dependent, and may be
+defined differently by different directory servers. The absence of a
+value for this attribute MUST be interpreted as meaning "do not
+initiate a replication session for change events of this category".
+
+The secsToWaitCat2 _ secsToWaitCat5 attributes are similarly defined
+for their respective categoriess of change events.
+
+6.3.5 timeScheduledSubentry Class
+
+( 2.16.840.1.113719.142.6.5.1 NAME 'timeScheduledSubentry'
+ SUP ldapSubEntry STRUCTURAL
+ MUST ( cn )
+ MAY ( description ) )
+
+
+
+
+7. Object Identifier Assignments
+
+The LDUP OID prefix is
+
+ID ::= OBJECT IDENTIFIER
+
+ldup ID ::= { joint-iso-ccitt(2) country(16) us(840)
+ organization(1) novell(113719) ldup(142) }
+
+The OID assignments defined in this document are:
+
+Attributes:
+attributeExclusionFilter ID ::= 2.16.840.1.113719.142.4.1
+attributeInclusionFilter ID ::= 2.16.840.1.113719.142.4.2
+replicationStatus ID ::= 2.16.840.1.113719.142.4.3
+replicaType ID ::= 2.16.840.1.113719.142.4.4
+secsToWaitClass1 ID ::= 2.16.840.1.113719.142.4.5.1
+secsToWaitClass2 ID ::= 2.16.840.1.113719.142.4.5.2
+secsToWaitClass3 ID ::= 2.16.840.1.113719.142.4.5.3
+secsToWaitClass4 ID ::= 2.16.840.1.113719.142.4.5.4
+secsToWaitClass5 ID ::= 2.16.840.1.113719.142.4.5.5
+updateVector ID ::= 2.16.840.1.113719.142.4.6
+
+Object Classes:
+eventScheduledSubentry ID ::= 2.16.840.1.113719.142.6.1.1
+nameContext ID ::= 2.16.840.1.113719.142.6.2.1
+replicaSubentry ID ::= 2.16.840.1.113719.142.6.3.1
+replicaAgreementSubentry ID ::= 2.16.840.1.113719.142.6.4.1
+timeScheduledSubentry ID ::= 2.16.840.1.113719.142.6.5.1
+
+Reed [Page 15]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+
+Note: Object Class OIDs have version numbers, Attribute OIDs don't.
+
+
+8. Security Considerations
+
+Many of the attributes and object classes described in this document
+should be considered _security sensitive_, and protected from
+unintended modification by LDAP servers. Generally, creating Naming
+Contexts, Replicas and Replica Agreement entries should only be
+allowed by directory administrators who are authorized to do so.
+
+The values of attributes defined here are intended to control the
+behavior of the directory service agents, themselves. Unintended
+modification of their values may result in incomplete replication of
+data (if ldapSearchFilter or attributeExclusionFilter are changed),
+inappropriate disclosure of information (if attributeInclusionFilter
+is changed), or updates may be lost (if updateVector is changed).
+
+To avoid depending to much on the ldapAccessPoint values for other
+replicas, connections between LDAP servers for the purpose of
+replication MUST ALWAYS be authenticated using an authentication
+mechanism appropriate for the nature of information to be exchanged.
+
+
+
+9. References
+
+[LANG TAG] _ M. Wahl, T. Howes, _Use of Language Codes in LDAP_,
+Internet draft, draft-ietf-ldapext-lang-01.txt
+
+[LDUP Model] - J. Merrells, E. Reed, U. Srinivisan, _An Abstract Model
+of LDAP Replication_, Internet draft, draft-merrells-ldup-model-01.txt
+
+[LDUP Requirements] - R. Weiser, E. Stokes _LDAP Replication
+Requirements_, Internet draft, draft-weiser-replica-req-02.txt, April
+1998
+
+[RFC2251] _ M. Wahl, T. Howes, S. Kille, _Lightweight Directory Access
+Protocol (v3)_, December 1997, RFC 2251
+
+[RFC2252] _ M. Wahl, A. Coulbeck, T. Howes, S. Kille, _Lightweight
+Directory Access Protocol (v3): Attribute Syntax Definitions_,
+December 1997, RFC 2252
+
+[X525] - ITU-T Recommendation X.525 (1997) | ISO/IEC 9594-9:1997,
+Information Technology _ Open Systems Interconnection _ The Directory:
+Replication
+
+Reed [Page 16]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+[X680] - ITU-T Recommendation X.680 (1994) | ISO/IEC 8824-1:1995,
+Information technology _ Abstract Syntax Notation One (ASN.1):
+Specification of Basic Notation
+
+
+
+10. Copyright Notice
+
+Copyright (C) The Internet Society (1999). 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 implmentation 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.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an
+"AS IS" basis and 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."
+
+
+11. Acknowledgements
+
+The use of subEntry object class to store Replica and Replication
+Agreement information is due primarily to the lucid explanation by
+Mark Wahl, Innosoft, of how they could be used and extended.
+
+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
+
+Reed [Page 17]
+ Expires September 9, 2000
+\f
+
+
+INTERNET-DRAFT 9 March 2000
+ LDUP Replication Information Model
+
+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.
+
+
+
+12. Author's Address
+
+ Edwards E. Reed
+ Reed-Matthews, Inc.
+ 1064 East 140 North
+ Lindon, UT 84042
+ USA
+ E-mail: eer@oncalldba.com
+
+ LDUP Mailing List: ietf-ldup@idc.org
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Reed [Page 18]
+ Expires September 9, 2000
+\f
--- /dev/null
+INTERNET-DRAFT
+
+draft-ietf-ldup-model-03.txt
+
+
+ John Merrells
+ Netscape Communications Corp.
+ Ed Reed
+ Reed-Matthews, Inc.
+ Uppili Srinivasan
+ Oracle, Inc.
+ March 10, 2000
+
+ LDAP Replication Architecture
+
+Copyright (C) The Internet Society (1998,1999, 2000).
+All Rights Reserved.
+
+Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026.
+
+Internet-Drafts are working documents of the Internet Engineering Task
+Force (IETF), its areas, and its working groups. Note that other
+groups may also distribute working documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or made obsolete by other documents at
+any time. It is inappropriate to use Internet-Drafts as reference
+material or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+This draft, file name draft-ietf-ldup-model-03.txt, is intended to be
+become a Proposed Standard RFC, to be published by the IETF Working
+Group LDUP. Distribution of this document is unlimited. Comments
+should be sent to the LDUP Replication mailing list <ldup@imc.org> or
+to the authors.
+
+This Internet-Draft expires on 10 September 2000.
+
+
+
+
+
+
+
+Merrells, Reed, Srinivasan [Page 1]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+
+
+
+
+
+1 Abstract
+
+This architectural document outlines a suite of schema and protocol
+extensions to LDAPv3 that enables the robust, reliable, server-to-
+server exchange of directory content and changes.
+
+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 RFC 2119 [RFC2119]. The
+sections below reiterate these definitions and include some additional
+ones.
+
+
+2 Table of Contents
+
+1 Abstract......................................................2
+2 Table of Contents.............................................2
+3 Introduction..................................................4
+3.1 Scope.........................................................4
+3.2 Document Objectives...........................................5
+3.3 Document Non-Objectives.......................................6
+3.4 Existing Implementations......................................6
+3.4.1 Replication Log Implementations.........................6
+3.4.2 State-Based Implementations.............................7
+3.5 Terms and Definitions.........................................7
+3.6 Consistency Models............................................8
+3.7 LDAP Constraints..............................................9
+4 Directory Model..............................................10
+4.1 Replica Type.................................................10
+4.1.1 Primary Replica........................................10
+4.1.2 Updatable Replica......................................10
+4.1.3 Read-Only Replica......................................10
+4.1.4 Fractional Replicas....................................10
+4.2 Sub-Entries..................................................11
+4.3 Glue Entries.................................................11
+4.4 Unique Identifiers...........................................11
+4.5 Change Sequence Number.......................................11
+4.5.1 CSN Composition........................................11
+4.5.2 CSN Representation.....................................12
+4.5.3 CSN Generation.........................................12
+4.6 State Change Information.....................................13
+4.1.1 Entry Change State Storage and Representation..........13
+4.1.2 Attribute Change State Storage.........................14
+
+Merrells, Reed, Srinivasan [Page 2]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+4.1.3 Attribute Value Change State Storage...................14
+4.2 LDAP Update Operations.......................................14
+5 Information Model............................................15
+5.1 Entries,
+ Semantics and Relationships............................15
+5.2 Root DSE Attributes..........................................15
+5.3 Naming Context...............................................15
+5.4 Replica Object Class and Entries.............................16
+5.5 Lost and Found Entry.........................................16
+5.6 Replication Agreement Object Class and Entries...............16
+5.6.1 Replication Schedule...................................17
+6 Policy Information...........................................18
+6.1 Schema Knowledge.............................................18
+7 LDUP Update Transfer Protocol Framework......................18
+7.1 Replication Session Initiation...............................19
+7.1.1 Authentication.........................................19
+7.1.2 Consumer Initiated.....................................19
+7.1.3 Supplier Initiated.....................................19
+7.2 Start Replication Session....................................20
+7.2.1 Start Replication Request..............................20
+7.2.2 Start Replication Response.............................20
+7.3 Update Transfer..............................................20
+7.4 End Replication Session......................................20
+7.5 Integrity & Confidentiality..................................21
+8 LDUP Update Protocols........................................21
+8.1 Replication Updates and Update Primitives....................21
+8.2 Fractional Updates...........................................21
+9 LDUP Full Update Transfer Protocol...........................22
+9.1 Full Update Transfer.........................................22
+9.2 Replication Update Generation................................22
+9.3 Replication Update Consumption...............................22
+9.4 Full Update, End Replication Session.........................22
+9.5 Interrupted Transmission.....................................23
+10 LDUP Incremental Update Transfer Protocol....................23
+10.1 Update Vector................................................23
+10.2 Supplier Initiated, Incremental Update,
+ Start Replication Session................................24
+10.3 Replication Update Generation................................24
+10.3.1 Replication Log Implementation.......................25
+10.3.2 State-Based Implementation...........................25
+10.4 Replication Update Consumption...............................25
+10.5 Update Resolution Procedures.................................25
+10.5.1 URP: Distinguished Names.............................26
+10.5.2 URP: Orphaned Entries................................26
+10.5.3 URP: Distinguished Not Present.......................26
+10.5.4 URP: Schema - Single Valued Attributes...............26
+10.5.5 URP: Schema - Required Attributes....................27
+10.5.6 URP: Schema - Extra Attributes.......................27
+
+
+Merrells, Reed, Srinivasan [Page 3]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+10.5.7 URP: Duplicate Attribute Values......................27
+10.5.8 URP: Ancestry Graph Cycle............................27
+10.6 Incremental Update, End Replication Session..................27
+10.7 Interrupted Transmission.....................................28
+11 Purging State Information....................................28
+11.1 Purge Vector.................................................28
+11.2 Purging Deleted Entries, Attributes, and Attribute Values....29
+12 Replication Configuration and Management.....................29
+13 Time.........................................................30
+14 Security Considerations......................................31
+15 Acknowledgements.............................................31
+16 References...................................................32
+17 Intellectual Property Notice.................................32
+18 Copyright Notice.............................................33
+19 Authors' Address.............................................33
+20 Appendix A - LDAP Constraints................................34
+20.1 LDAP Constraints Clauses.....................................34
+20.2 LDAP Data Model Constraints..................................35
+20.3 LDAP Operation Behaviour Constraints.........................36
+20.4 New LDAP Constraints.........................................37
+20.4.1 New LDAP Data Model Constraints......................37
+20.4.2 New LDAP Operation Behaviour Constraints.............37
+
+
+
+
+
+
+3 Introduction
+
+
+3.1 Scope
+
+This architectural document provides an outline of an LDAP based
+replication scheme. Further detailed design documents will draw
+guidance from here.
+
+The design proceeds from prior work in the industry, including
+concepts from the ITU-T Recommendation X.525 (1993, 1997) Directory
+Information Shadowing Protocol (DISP) [X525], experience with widely
+deployed distributed directories in network operating systems,
+electronic mail address books, and other database technologies. The
+emphasis of the design is on:
+
+1. Simplicity of operation.
+
+2. Flexibility of configuration.
+
+3. Manageability of replica operations among mixed heterogeneous
+ vendor LDAP servers under common administration.
+
+
+Merrells, Reed, Srinivasan [Page 4]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+4. Security of content and configuration information when LDAP servers
+ from more than one administrative authority are interconnected.
+
+A range of deployment scenarios are supported, including multi-master
+and single-master topologies. Replication networks may include
+transitive and redundant relationships between LDAP servers.
+
+The controlling framework used to define the relationships, types, and
+state of replicas of the directory content is defined. In this way the
+directory content can itself be used to monitor and control the
+replication network. The directory schema is extended to define object
+classes, auxiliary classes, and attributes that describe areas of the
+namespace which are replicated, LDAP servers which hold replicas of
+various types for the various partitions of the namespace, LDAP Access
+Points (network addresses) where such LDAP servers may be contacted,
+which namespaces are held on given LDAP servers, and the progress of
+replication operations. Among other things, this knowledge of where
+directory content is located could serve as the basis for dynamic
+generation of LDAP referrals.
+
+An update transfer protocol, which actually brings a replica up to
+date with respect to changes in directory content at another replica,
+is defined using LDAPv3 protocol extensions. The representation of
+directory content and changes will be defined by the LDAP Replication
+Update Transfer Protocol sub-team. Incremental and full update
+transfer mechanisms are described. Replication protocols are required
+to include initial population, change updates, and removal of
+directory content.
+
+Security information, including access control policy will be treated
+as directory content by the replication protocols. Confidentiality
+and integrity of replication information is required to be provided by
+lower-level transport/session protocols such as IPSEC and/or TLS.
+
+
+
+3.2 Document Objectives
+
+The objectives of this document are:
+
+a) To define the architectural foundations for LDAP Replication, so
+ that further detailed design documents may be written. For
+ instance, the Information Model, Update Transfer Protocol, and
+ Update Resolution Procedures documents.
+
+b) To provide an architectural solution for each clause of the
+ requirements document [LDUP Requirements].
+
+c) To preserve the LDAP Data Model and Operation Behavior
+constraints
+ defined for LDAP in RFC 2251 [See Appendix A]
+
+d) To avoid tying the LDUP working group to the schedule of any other
+ working group.
+
+e) Not to infringe upon known registered intellectual property rights.
+
+
+Merrells, Reed, Srinivasan [Page 5]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+
+
+3.3 Document Non-Objectives
+
+This document does not address the following issues, as they are
+considered beyond the scope of the Working Group.
+
+a) How LDAP becomes a distributed directory. There are many issues
+ beyond replication that should be considered. Such as, support for
+ external references, algorithms for computing referrals from the
+ distributed directory knowledge, etc.
+
+b) Specifying management protocols to create naming contexts or new
+ replicas. LDAP may be sufficient for this. The document describes
+ how new replicas and naming contexts are represented, in the
+ directory, as entries, attributes, and attribute values.
+
+c) How transactions will be replicated. However, the architecture
+ should not knowingly prevent or impede them, given the Working
+ Group's incomplete understanding of the issues at this time.
+
+d) The mapping or merging of disparate Schema definitions.
+
+e) Support of overlapping replicated regions.
+
+f) The case where separate attributes of an entry may be mastered by
+ different LDAP servers. This might be termed a 'Split Primary'.
+ Replica roles are defined in section 4.1.
+
+g) The specification of a replication system that supports Sparse
+ Replication. A Sparse Replica contains a subset of the naming
+ context entries, being modified by an Entry Selection Filter
+ criteria associated with the replica. An Entry Selection Filter is
+ an LDAP filter expression that describes the entries to be
+ replicated. The design and implementation of this functionality is
+ not yet well enough understood to specify here.
+
+
+
+3.4 Existing Implementations
+
+In order to define a standard replication scheme that may be readily
+implemented we must consider the architectures of current LDAP server
+implementations. Existing systems currently support proprietary
+replication schemes based on one of two general approaches: log-based
+or state-based. Some sections of this text may specifically address
+the concerns of one approach. They will be clearly marked.
+
+
+
+3.4.1R
+ eplication Log Implementations
+
+Implementations based on the original University of Michigan LDAP
+server code record LDAP operations to a operation log. During a
+replication session operations are replayed from this log to bring the
+
+Merrells, Reed, Srinivasan [Page 6]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+Consumer replica up to date. Example implementations of this type at
+this time are the Innosoft, Netscape, and Open LDAP Directory Servers.
+
+
+
+3.4.2S
+ tate-Based Implementations
+
+Directory Server implementations from Novell and Microsoft at this
+time do not replay LDAP operations from a operation log. When a
+replication session occurs each entry in the Replicated Area is
+considered in turn, compared against the update state of the Consumer,
+and any resultant changes transmitted. These changes are a set of
+assertions about the presence or absence of entries, attributes, and
+their values.
+
+
+
+3.5 Terms and Definitions
+
+The definitions from the Replication Requirements document have been
+copied here and extended.
+
+For brevity, an LDAP server implementation is referred to throughout
+as 'the server'.
+
+The LDAP update operations; Add, Delete, Modify, Modify RDN (LDAPv2)
+and Modify DN (LDAPv3), are collectively referred to as LDAP Update
+Operations.
+
+A Naming Context is a subtree of entries in the Directory Information
+Tree (DIT). There may be multiple Naming Contexts stored on a single
+server. Naming Contexts are defined in section 17 of [X501].
+
+A Naming Context is based at an entry identified as its root and
+includes all its subordinate entries down the tree until another
+Naming Context is encountered.
+
+A Replica is an instance of a replicated Naming Context.
+
+A replicated Naming Context is said to be single-mastered if there is
+only one Replica where it may be updated, and multi-mastered if there
+is more than one Replica where it may be updated.
+
+A Replication Relationship is established between two or more Replicas
+that are hosted on servers that cooperate to service a common area of
+the DIT.
+
+A Replication Agreement is defined between two parties of a
+Replication Relationship. The properties of the agreement codify the
+Unit of Replication, the Update Transfer Protocol to be used, and the
+Replication Schedule of a Replication Session.
+
+A Replication Session is an LDAP session between the two servers
+identified by a replication agreement. Interactions occur between the
+two servers, resulting in the transfer of updates from the supplier
+replica to the consumer replica.
+
+Merrells, Reed, Srinivasan [Page 7]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+The Initiator of a Replication Session is the initiating server.
+
+A Responder server responds to the replication initiation request from
+the Initiator server.
+
+A Supplier server is the source of the updates to be transferred.
+
+A Consumer server is the recipient of the update sequence.
+
+The Update Transfer Protocol is the means by which the Replication
+Session proceeds. It defines the protocol for exchanging updates
+between the Replication Relationship partners.
+
+A Replication Update is an LDAP Extended Operation that contains
+updates to be applied to the DIT. The Update Transfer Protocol carries
+a sequence of these messages from the Supplier to the Consumer.
+
+The Update Resolution Procedures repair constraint violations that
+occur when updates to a multi-mastered Replica collide.
+
+A Fractional Entry Specification is a list of entry attributes to be
+included, or a list of attributes to be excluded in a replica. An
+empty specification implies that all entry attributes are included.
+
+A Fractional Entry is an entry that contains only a subset of its
+original attributes. It results from the replication of changes
+governed by a Fractional Entry
+Specification.
+
+A Fractional Replica is a replica that holds Fractional Entries of its
+naming context.
+
+
+
+3.6 Consistency Models
+
+This replication architecture supports a loose consistency model
+between replicas of a naming context. It does not attempt to provide
+the appearance of a single copy of a replica. The contents of each
+replica may be different, but over time they will be converging
+towards the same state. This architecture is not intended to support
+LDAP Clients that require a tight consistency model, where the state
+of all replicas is always equivalent.
+
+Three levels of consistency are available to LDAP Clients, which are
+characterized by their deployment topologies. Single-Server, where
+there is just the naming context and no replicas. Single-master, where
+there are replicas, but only one may be updated. And, multi-master,
+where there is more than one replica to which LDAP update operations
+may be directed. The consistency properties of each model are rooted
+in their serialization of read and write operations.
+
+1) A single-server deployment of a naming context provides tight
+consistency to LDAP applications. LDAP Clients have no choice but to
+direct all their operations to a single server, serializing both read
+
+
+Merrells, Reed, Srinivasan [Page 8]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+and write operations.
+
+2) A single-mastered deployment of a naming context provides both
+tight and loose consistency to LDAP applications. LDAP Clients must
+direct all write operations to the single updateable replica, but may
+direct their reads to any of the replicas. A client experiences tight
+consistency by directing all its operations to the single updatable
+replica, and loose consistency by directing any read operations to any
+other replica.
+
+3) A multi-mastered deployment of a naming context can provide only
+loose consistency to LDAP applications. Across the system writes and
+reads are not serialized. An LDAP Client could direct their read and
+write operations to a single updateable replica, but they will not
+receive tight consistency as interleaved writes could be occurring at
+another replica.
+
+Tight consistency can be achieved in a multi-master deployment for a
+particular LDAP application if and only if all instances of its client
+are directed towards the same updateable replica, and the application
+data is not updated by any other LDAP application. Introducing these
+constraints to an application and deployment of a naming-context
+ensures that writes are serialized providing tight consistency for the
+application.
+
+Future work could make use of the architecture proposed in this
+document as a basis for allowing clients to request session guarantees
+from a server when establishing a connection.
+
+
+
+3.7 LDAP Constraints
+
+The LDAP-v3 Internet RFC [LDAPv3] defines a set of Data Model and
+Operation Behaviour constraints that a compliant LDAP server must
+enforce. The server must reject an LDAP Update Operation if its
+application to the target entry would violate any one of these LDAP
+Constraints. [Appendix A B contains the original text clauses from RFC
+2251, and also a summary.]
+
+In the case of a single-server or single-mastered naming context all
+LDAP Constraints are immediately enforced at the single updateable
+replica. An error result code is returned to an LDAP Client that
+presents an operation that would violate the constraints.
+
+In the case of a multi-mastered naming context not all LDAP
+Constraints can be immediately enforced at the updateable replica to
+which the LDAP Update Operation is applied. This loosely consistent
+replication architecture ensures that at each replica all constraints
+are imposed, but as updates are replicated constraint violations may
+arise
+that can not be reported to the appropriate client. Any constraint
+violations that occur are repaired by a set of update resolution
+procedures.
+
+Any LDAP client that has been implemented to expect immediate
+
+
+Merrells, Reed, Srinivasan [Page 9]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+enforcement of all LDAP Constraints may not behave as expected
+against a multi-mastered naming context.
+
+
+
+4 Directory Model
+
+
+This section describes extensions to the LDAP Directory Model that are
+required by this replication architecture.
+
+
+
+4.1 Replica Type
+
+Each Replica is characterized with a replica type. This may be
+Primary, Updatable, or Read-Only. A Read-Only Replica may be further
+defined as being Fractional.
+
+
+
+4.1.1
+ Primary Replica
+
+The Primary Replica is a full copy of the Replica, to which all
+applications that require tight consistency should direct their LDAP
+Operations. There can be only one Primary Replica within the set of
+Replicas of a given Naming Context. It is also permissible for none
+of the Replicas to be designated the Primary. The Primary Replica MUST
+NOT be a Fractional Replica.
+
+
+4.1.2
+ Updatable Replica
+
+An Updatable Replica is a Replica that accepts all the LDAP Update
+Operations, but is not the Primary Replica. There could be none, one,
+or many Updatable Replicas within the set of Replicas of a given
+Naming Context. An Updatable Replica MUST NOT be a Fractional Replica.
+
+
+
+4.1.3
+ Read-Only Replica
+
+A Read-Only Replica will accept only non-modifying LDAP operations.
+All modification operations shall be referred to an updateable
+Replica. The server referred to would usually be a Supplier of this
+Replica.
+
+
+
+4.1.4
+ Fractional Replicas
+
+Fractional Replicas must always be Read-Only. All LDAP Update
+Operations must be referred to an Updatable Replica. The server
+referred to would usually be a Supplier of this Fractional Replica.
+
+
+Merrells, Reed, Srinivasan [Page 10]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+4.2 Sub-Entries
+
+Replication management entries are to be stored at the base of the
+replicated naming context. They will be of a 'ldapSubentry'
+objectclass
+to exclude them from regular searches. Entries with the objectclass
+subentry are not returned as the result of a search unless the filter
+component "(objectclass=ldapSubentry)" is included in the search
+filter.
+
+
+
+4.3 Glue Entries
+
+A glue entry is an entry that contains knowledge of its name only. No
+other information is held with it. Such glue entries will be
+distinguished through a special object class defined for that purpose.
+Glue entries may be created during a replication session to repair a
+constraint violation.
+
+
+4.4 Unique Identifiers
+
+Distinguished names can change, so are therefore unreliable as
+identifiers. A Unique Identifier must therefore be assigned to each
+entry as it is created. This identifier will be stored as an
+operational attribute of the entry, named 'entryUUID'. The entryUUID
+attribute is single valued. A consistent algorithm for generating such
+unique identifiers should be defined for use in the LDUP standards
+documents that detail the LDUP information model and LDUP protocols.
+
+
+4.5 Change Sequence Number
+
+Change Sequence Numbers (CSNs) are used to impose a total ordering
+upon the causal sequence of updates applied to all the replicas of a
+naming context. Every LDAP Update Operation is assigned at least one
+CSN. A Modify operation MUST be assigned one CSN per modification.
+
+
+
+4.5.1
+ CSN Composition
+
+A CSN is formed of four components. In order of significance they
+are; the time, a change count, a Replica Identifier, and a
+modification number. The CSN is composed thus to ensure the uniqueness
+of every generated CSN. When CSNs are compared to determine their
+ordering they are compared component by component. First the time,
+then the change count, then the replica identifier, and finally the
+modification number.
+
+The time component is a year-2000-safe representation of the real
+world time, with a granularity of one second.
+
+Because many LDAP Update Operations, at a single replica, may be
+
+Merrells, Reed, Srinivasan [Page 11]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+applied to the same data in a single second, the change count
+component of the CSN is provided to further order the changes. Each
+replica maintains a count of LDAP update operations applied against
+it. It is reset to zero at the start of each second, and is
+monotonically increasing within that second, incremented for each and
+every update operation. Should LDAP Update Operations occur at
+different replicas, to the same data, within the same single second,
+and happen to be assigned the same change count number, then the
+Replica Identifier is used to further order the changes.
+
+The Replica Identifier is the value of the RDN attribute on the
+Replica Subentry. The Replica Identifier could be assigned
+programmatically or administratively, in either case short values are
+advised to minimise resource usage. The IA5CaseIgnoreString syntax is
+used to compare and order Replica Identifier values.
+
+The fourth and final CSN component, the modification number, is used
+for ordering the modifications within an LDAP Modify operation.
+
+
+
+4.5.2
+ CSN Representation
+
+The preferred CSN representation is:
+ yyyy mm dd hh:mi:ssz # 0xSSSS # replica id # 0xssss
+
+The 'z' in the time stipulates that the time is expressed in GMT
+without any daylight savings time offsets permitted, and the 0xssss
+represents the hexadecimal representation of an unsigned
+integer.
+Implementations must support 16 bit change counts and should support
+longer ones (32, 64, or 128 bits).
+
+An example CSN would be " 1998081018:44:31z#0x000F#1#0x0000 ". The
+update assigned this CSN would have been applied at time
+1998081018:44:31z happened to be the 16th operation which was applied
+in that second, was made against the replica with identifier '1', and
+was the first modification of the operation that caused the change.
+
+
+
+4.5.3
+ CSN Generation
+
+Because Change Sequence Numbers are primarily based on timestamps,
+clock differences between servers can cause unexpected change
+ordering. The synchronization of server clocks is not required, though
+it is preferable that clocks are accurate. If timestamps are not
+accurate, and a server consistently produces timestamps which are
+significantly older than those of other servers, its updates will not
+have effect and the real world time ordering of updates will not be
+maintained.
+
+However, an implementation may choose to require clock
+synchronisation. The Network Time Protocol [NTP] [SNTP] offers a
+protocol means by which heterogeneous server hosts may be time
+synchronised.
+
+Merrells, Reed, Srinivasan [Page 12]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+The modifications which made up an LDAP Modify operation are presented
+in a sequence. This must be preserved when the resultant changes of
+this operation are replicated.
+
+
+
+
+4.5.3.1 CSN Generation - Log Based Implementation
+
+
+The modification number component may not be required, since the
+ordering of the modifications within an LDAP Modify operation have
+been preserved in the operation log.
+
+
+4.5.3.2 CSN Generation - State Based Implementation
+
+
+The modification number component may be needed to ensure that the
+order of the modifications within an LDAP Modify operation are
+faithfully replicated.
+
+
+4.6 State Change Information
+
+State changes can be introduced via either LDAP Update Operations or
+via Replication Updates. A CSN is included with all changes made to an
+entry, its attributes, and attribute values. This state information
+must be recorded for the entry to enable a total ordering of updates.
+The CSN recorded is the CSN assigned to the state change at the server
+where the state change was first made. CSNs are only assigned to state
+changes that originate from LDAP Update Operations.
+
+Each of the LDAP Update Operations change their target entry in
+different ways, and record the CSN of the change differently. The
+state information for the resultant state changes are recorded at
+three levels. The entry level, attribute level, and attribute value
+level. The state change may be shown through.
+
+1) The creation of a deletion CSN for the entry, an attribute, or an
+ attribute value.
+
+2) In the addition of a new entry, attribute or attribute value, and
+ its existence CSN.
+
+3) An update to an existing attribute, attribute value, entry
+ distinguished name, or entry superior name, and its update CSN.
+
+
+
+4.1.1
+ Entry Change State Storage and Representation
+
+When an entry is created, with the LDAP Add operation, the CSN of the
+change is added to the entry as the value of an operational attribute
+
+
+Merrells, Reed, Srinivasan [Page 13]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+named 'createdEntryCSN', of syntax type LDAPChangeSequenceNumber.
+
+ createdEntryCSN ::= csn
+
+Deleted entries are marked as deleted by the addition of the object
+class 'deletedEntry'. The attribute 'deletedEntryCSN', of syntax type
+LDAP Change Sequence Number, is added to record where and when the
+entry was deleted. Deleted entries are not visible to LDAP clients -
+they may not be read, they don't appear in lists or search results,
+and they may not be changed once deleted. Names of deleted entries
+are available for reuse by new entries immediately after the deleted
+entry is so marked. It may be desirable to allow deleted entries to be
+accessed and manipulated by management and data recovery applications,
+but that is outside the scope of this document.
+
+ deletedEntryCSN ::= csn
+
+A CSN is recorded for both the RDN, and the Superior DN of the entry.
+
+
+4.1.2A
+ ttribute Change State Storage
+
+When all values of an attribute have been deleted, the attribute is
+marked as deleted and the CSN of the deletion is recorded. The deleted
+state and CSN are stored by the server, but have no representation on
+the entry, and may not be the subject of a search operation. This
+state information must be stored to enable the Update Resolution
+Procedures to be performed.
+
+
+
+4.1.3
+ Attribute Value Change State Storage
+
+The Modification CSN for each value is to be set by the server when it
+accepts a modification request to the value, or when a new value with
+a later Modification CSN is received via Replication. The modified
+value and the Modification CSN changes are required to be atomic, so
+that the value and its Modification CSN cannot be out of synch on a
+given server. The state information is stored by the server, but it
+has no representation on the entry, and may not be the subject of a
+search operation.
+
+When the value of an attribute is deleted the state of its deletion
+must be recorded, with the CSN of the modifying change. It must be
+stored to enable the Update Resolution Procedures to be performed.
+
+
+
+4.2 LDAP Update Operations
+
+The server must reject LDAP client update operations with a CSN that
+is older than the state information that would be replaced if the
+operation were performed. This could occur in a replication topology
+where the difference between the clocks of updateable replicas was too
+large. Result code 72, serverClocksOutOfSync, is returned to the
+client.
+
+Merrells, Reed, Srinivasan [Page 14]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+5 Information Model
+
+
+This section describes the object classes of the entries that
+represent the replication topology. The operational information for
+replication are administered through these entries. The LDUP Working
+Group will work towards defining an Internet standard to fully detail
+all these schema elements.
+
+
+5.1 Entries, Semantics and Relationships
+
+This section defines the organization of operational data for directory
+replication in terms of the relative placement of the entries that
+represent Naming Contexts, its Replicas, and their associated
+Replication agreements. This section also describes the purpose of
+these objects and abstractly describes their content.
+A Naming Context defines an area of DIT with independent replication
+policies. There are many mechanisms available to identify the set of
+Naming Contexts in a Directory, including through special auxiliary
+classes or through operational attributes in root DSE pointing to
+such entries. The LDUP information model standards will detail an
+appropriate mechanism.
+
+Entries representing the set of Replicas associated with a Naming
+Context are created immediately below (children) the Naming Context
+entries. Replica entries are defined as subentries and are
+intended to hold attributes that identify the Replica's LDAP Access
+Point, its Replica Type, and if it is a Fractional Replica, the
+attributes it does or does not hold. The attribute value of the entry's
+Relative Distinguished Name (RDN) is termed the Replica Identifier and
+is used as a component of each CSN associated with the replica.
+
+Immediately subordinate to each Replica Subentry are the entries
+representing the Replication Agreements between this replica and
+another replica on some other server in the network. A Replication
+Agreement entry is associated with exactly one remote replica.
+These entries are defined to hold attributes identifying
+the remote Replica associated with this agreement, the scheduling
+policy for replication operations, including times when replication is
+to be performed, when it is not to be performed, or the policies
+governing event-driven replication initiation another Replica, the
+scheduling policy for replication operations, including times when
+replication is to be performed, when it is not to be performed, or the
+policies governing event-driven replication initiation.
+
+
+
+5.2 Root DSE Attributes
+
+LDUP information model will define Root DSE attributes to identify the
+set of naming Contexts and replicas present in an LDAP server.
+
+5.3 Naming Context
+
+The LDUP Information Model will implement schema elements for
+
+Merrells, Reed, Srinivasan [Page 15]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+representing configuration and policy information common for all
+replicas of the Naming Context. Attributes for recording the location
+and time of creation of naming contexts may also be identified by the
+information model.
+
+In future LDAP Access Control standards would define mechanisms for
+identifying the ACL policy associated with a Naming Context as well as
+the syntax and semantics of its representation.
+
+
+5.4 Replica Object Class and Entries
+
+Each Replica is characterized by a replica type. This may be Primary,
+Updatable, or Read-Only. The latter two types may be further defined
+as being Fractional. The Replica entry will include a Fractional Entry
+Specification for a Fractional Replica.
+
+There is a need to represent network addresses of servers holding
+replicas participating in Replication Agreements. For this,
+the LDUP information model will define an attribute with an
+appropriate syntax to represent an LDAP server addresses with which to
+contact replicas.
+
+
+An Update Vector describes the point to which the Replica has been
+updated, in respect to all the other Replicas of the Naming Context.
+The vector is used at the initiation of a replication session to
+determine the sequence of updates that should be transferred.
+
+Enabling LDAP to be a fully distributed service is not an objective
+for the design of LDUP information model, though the information stored
+in replica entries could facilitate certain distributed operations.
+
+
+5.5 Lost and Found Entry
+
+When replicating operations between servers, conflicts may arise that
+cause a parent entry to be removed causing its child entries to become
+orphaned. In this case the Update Resolution Procedures will make the
+Lost and Found Entry the child's new superior.
+
+Each Replica Entry names it's Lost and Found Entry, which would
+usually be an entry below the Replica Entry itself. This well known
+place allows administrators, and their tools, to find and repair
+abandoned entries.
+
+
+
+5.6 Replication Agreement Object Class and Entries
+
+The Replication Agreement defines:
+
+1. The schedule for Replication Sessions initiation.
+
+2. The server that initiates the Replication Session, either the
+ Consumer or the Supplier.
+
+Merrells, Reed, Srinivasan [Page 16]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+3. The authentication credentials that will be presented between
+ servers.
+
+4. The network/transport security scheme that will be employed in
+ order to ensure data confidentiality.
+
+5. The replication protocols and relevant protocol parameters to be
+ used for Full and Incremental updates. An OID is used to identify
+ the update transfer protocol, thus allowing for future extensions
+ or bilaterally agreed upon alternatives.
+
+6. If the Replica is Fractional, the Fractional Entry Specification for
+the attributes to be included or excluded
+
+Permission to participate in replication sessions will be controlled,
+at least in part, by the presence and content of replica agreements.
+
+The Supplier must be subject to the access control policy enforced by
+the Consumer. Since the access control policy information is stored
+and replicated as directory content, the access control imposed on the
+Supplier by the Consumer must be stored in the Consumer's Replication
+Agreement.
+
+
+
+5.6.1
+ Replication Schedule
+
+There are two broad mechanisms for initiating replication sessions:
+(1) scheduled event driven and (2) change event driven. The mechanism
+used to schedule replication operations between two servers is
+determined by the Schedule information that is part of the Replication
+Agreement governing the Replicas on those two servers. Because each
+Replication Agreement describes the policy for one direction of the
+relationship, it is possible that events propagate via scheduled
+events in one direction, and by change events in the other.
+
+Change event driven replication sessions are, by their nature,
+initiated by suppliers of change information. The server, which the
+change is made against, schedules a replication session in response to
+the change itself, so that notification of the change is passed on to
+other Replicas.
+
+Scheduled event driven replication sessions can be initiated by either
+consumers or suppliers of change information. The schedule defines a
+calendar of time periods during which Replication Sessions should be
+initiated.
+
+Schedule information may include both scheduled and change event
+driven mechanisms. For instance, one such policy may be to begin
+replication within 15 seconds of any change event, or every 30 minutes
+if no change events are received.
+
+
+
+
+
+Merrells, Reed, Srinivasan [Page 17]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+6 Policy Information
+
+
+Administrative policy information governs the behavior of the server
+This policy information needs to be consistently known and
+applied by all replicas of a Naming Context. It may be
+represented in the DIT as sub-entries, attributes, and attribute
+values. Auxiliary classes are a convenient way to hold such
+policy information and to uniformly replicate them among all its
+replicas. For a naming context to be faithfully reproduced, all
+applicable prescriptive policy information represented among its
+ancestral entries must also be replicated. In all cases such
+policy information is transmitted as if it were an element of
+the Replica root entry.
+
+Policy information is always replicated in the same manner as any
+other entries, attributes, and attribute values.
+
+
+
+6.1 Schema Knowledge
+
+Schema subentries should be subordinate to the naming contexts to
+which they apply. Given our model, a single server may hold replicas
+of several naming contexts. It is therefore essential that schema
+should not be considered to be a server-wide policy, but rather to be
+scoped by the namespace to which it applies.
+
+Schema modifications replicate in the same manner as other directory
+data. Given the strict ordering of replication events, schema
+modifications will naturally be replicated prior to entry creations
+which use them, and subsequent to data deletions which eliminate
+references to schema elements to be deleted. Servers MUST NOT
+replicate information about entries which are not defined in the
+schema. Servers should not replicate modifications to existing schema
+definitions for which there are existing entries and/or attributes
+which rely on the schema element.
+
+Should a schema change cause an entry to be in violation of the new
+schema, it is recommended that the server preserve the entry for
+administrative repair. The server could add a known object class to
+make the entry valid and to mark the entry for maintenance.
+
+
+
+7 LDUP Update Transfer Protocol Framework
+
+
+A Replication Session occurs between a Supplier server and Consumer
+server over an LDAP connection. This section describes the process by
+which a Replication Session is initiated, started and stopped.
+
+The session initiator, termed the Initiator, could be either the
+Supplier or Consumer. The Initiator sends an LDAP extended operation
+to the Responder identifying the replication agreement being acted on.
+The Supplier then sends a sequence of updates to the Consumer.
+
+Merrells, Reed, Srinivasan [Page 18]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+All transfers are in one direction only. A two way exchange requires
+two replication sessions; one session in each direction.
+
+
+7.1 Replication Session Initiation
+
+The Initiator starts the Replication Session by opening an LDAP
+connection to its Responder. The Initiator binds using the
+authentication credentials provided in the Replication Agreement.
+The LDUP Update Transfer Protocol will define the LDAP extended
+operation the Initiator should perform to initialize an LDUP session.
+For the sake of convenience, this extended LDAP operation for
+initializing a replication session is referred to as the "Start
+Replication" operation. Among other things, this operation will
+identify the role each
+server will perform, and what type of replication is to be performed.
+
+One server is to be the Consumer, the other the Supplier, and the
+replication may be either Full or Incremental.
+
+
+
+7.1.1
+ Authentication
+
+
+The initiation of a Replication Session is to be restricted to
+privileged clients. The identity and the credentials for the client
+eligible for initiating a replication session will be defined as
+attributes within Replication Agreements.
+
+7.1.2
+ Consumer Initiated
+
+The Consumer binds to the Supplier using the authentication
+credentials provided in the Replication Agreement. The Consumer sends
+the "Start Replication" extended request to begin the Replication
+Session. The Supplier returns a "Start Replication" extended response
+containing a response code. The Consumer then disconnects from the
+Supplier. If the Supplier has agreed to the replication session
+initiation, it binds to the Consumer and behaves just as if the
+Supplier initiated the replication.
+
+
+
+7.1.3
+ Supplier Initiated
+
+The Supplier binds to the Consumer using the authentication
+credentials provided in the Replication Agreement. The Supplier sends
+the "Start Replication" extended request to begin the
+Replication Session. The Consumer returns a "Start Replication"
+extended
+response containing a response code, and possibly its Update Vector.
+If the Consumer has agreed to the Replication Session initiation, then
+the transfer protocol begins.
+
+
+
+Merrells, Reed, Srinivasan [Page 19]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+
+7.2 Start Replication Session
+
+7.2.1S
+ tart Replication Request
+
+
+The LDUP Update Transfer Protocol would define an LDAP Extended
+Request, referred to in this document as "Start Replication Request",
+that is sent from the Initiator to Responder. The parameters of the
+"Start Replication Request" would identify the Replication Agreement
+associated with the session, the Update Transfer Protocol associated \
+with the replication session, and other state information necessary
+to resume replication between the two servers.
+
+
+7.2.2S
+ tart Replication Response
+
+
+The LDUP Update Transfer Protocol would define an LDAP Extended
+Response, "Start Replication Response", sent in reply to a Start
+Replication Request, from the Responder to the Initiator. The
+parameters of the Start Replication Response include an response code,
+and an optional Update Vector.
+
+
+
+7.3 Update Transfer
+
+Each Update Transfer Protocol is identified by an OID. An LDUP
+conformant server implementation must support those update protocols
+that are
+defined as mandatory in the Update Transfer Protocol standard , and
+may support many others. A server will advertise its
+protocols in the Root DSE multi-valued attribute
+'supportedReplicationProtocols'.
+
+The Update Transfer Protocol would define the mechanisms for a
+Consumer to receive a complete (full) update or incremental update
+based on the current state of replication represented in the Update
+Vector. A full update is necessary for initializing a consumer
+replica upon establishment of replication agreements.
+
+
+
+7.4 End Replication Session
+
+A Replication Session is terminated by the "End Replication Request"
+initiated by the supplier. The purpose of this request and response
+is to secure the state of the Update Vector associated with the two
+replicas that participated in replication. This is necessary for
+proper resumption of replication during subsequent LDUP sessions
+
+
+
+
+Merrells, Reed, Srinivasan [Page 20]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+7.5 Integrity & Confidentiality
+
+Data integrity (ie, protection from unintended changes) and
+confidentiality (ie, protection from unintended disclosure to
+eavesdroppers) SHOULD be provided by appropriate selection of
+underlying transports, for instance TLS, or IPSEC. Replication MUST
+be supported across TLS LDAP connections. Servers MAY be configured
+to refuse replication connections over unprotected TCP connections.
+
+
+
+
+8 LDUP Update Protocols
+
+
+This Internet-Draft defines two transfer protocols for the supplier to
+push changes to the consumer. Other protocols could be defined to
+transfer changes, including those which pull changes from the supplier
+to the consumer, but those are left for future work.
+
+
+
+8.1 Replication Updates and Update Primitives
+
+Both LDUP Update Protocols define how Replication Updates are
+transferred from the Supplier to the Consumer. Each Replication Update
+consists of a set of Update Primitives that describe the state changes
+that have been made to a single entry. Each Replication Update is
+associated with a single entry identified by its UUID.
+
+
+ The Update Transfer Protocol would define a set of Update Primitives
+each of which codifies an assertion about the state change of an entry
+that resulted from a directory update operation. The primitives will
+include sufficient data to allow recreation of corresponding state
+changes on the consumer's replica. An assertion based approach has
+been chosen in such a way that the Primitives are idempotent, meaning
+that re-application of a Primitive to an Entry will cause no change to
+the entry. This is desirable as it provides some resilience against
+some kinds of system failures.
+
+Each Update Primitive contains a CSN that represents an ordering among
+all such primitives generated anywhere in the
+network. This ordering information is used by the consumer to reconcile
+among those primitives that lead to consistency violation
+ier.
+
+
+8.2 Fractional Updates
+
+When fully populating or incrementally bringing up to date a
+Fractional Replica each of the Replication Updates must only contain
+updates to the attributes in the Fractional Entry Specification.
+
+
+
+Merrells, Reed, Srinivasan [Page 21]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+9 LDUP Full Update Transfer Protocol
+
+
+
+
+9.1 Full Update Transfer
+
+This Full Update Protocol provides a bulk transfer of the replica
+contents for the initial population of new replicas, and the
+refreshing of existing replicas. The LDUP Update Transfer protocol
+standard will define the ways for this transfer is initiated.
+
+The Consumer must replace its entire replica contents with that sent
+from the Supplier.
+
+The Consumer need not service any requests for this Naming Context
+whilst the full update is in progress. The Consumer could instead
+return a
+referral to another replica, possibly the supplier.
+
+
+
+9.2 Replication Update Generation
+
+The entire state of a Replicated Area can be mapped onto a sequence of
+Replication Updates, each of which contains a sequence of Update
+Primitives that describe the entire state of a single entry.
+
+The sequence of Replication Updates must be ordered such that no entry
+is created before its parent.
+
+
+
+9.3 Replication Update Consumption
+
+A Consumer will receive the Replication Updates, extract the sequence
+of Update Primitives, and must apply them to the DIB in the order
+provided.
+
+
+
+9.4 Full Update, End Replication Session
+
+
+A Full Update should also result in the replication of all appropriate
+LDUP meta data (which are part of the replicated naming context), such
+as the sub-entry representing the Replica being updated and the Update
+Vector associated with it.
+The Supplier could be accepting updates whilst the update is in
+progress. Once the Full Update has completed, an Incremental Update
+should be performed to transfer these changes.
+
+
+
+
+
+Merrells, Reed, Srinivasan [Page 22]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+9.5 Interrupted Transmission
+
+If the Replication Session terminates before the End Replication
+Request is sent, then the Replica could be in an inconsistent state.
+ Until the replica is restored to a consistent
+state, the consumer might not permit LDAP Clients to access the
+incomplete replica. The Consumer could refer the Client to the
+Supplier Replica, or return an error result code.
+
+
+
+10 LDUP Incremental Update Transfer Protocol
+
+
+For efficiency, the Incremental Update Protocol transmits only those
+changes that have been made to the Supplier replica that the Consumer
+has not already received. In a replication topology with transitive
+redundant replication agreements, changes may propagate through the
+replica network via different routes.
+
+The Consumer must not support multiple concurrent replication sessions
+with more than one Supplier for the same Naming Context. A Supplier
+that attempts to initiate a Replication Session with a Consumer
+already participating as a Consumer in another Replication Session
+will receive appropriate error. .
+
+
+
+10.1 Update Vector
+
+The Supplier uses the Consumer's Update Vector to determine the
+sequence of updates that should be sent to the Consumer.
+
+Each Replica entry includes an Update Vector to record the point to
+which the replica has been updated. The vector is a set of CSN values,
+one value for each known updateable Replica. Each CSN value in the
+vector corresponds to the most recent change that occurred in an
+updateable replica that has been replicated to the replica whose
+replication state this Update Vector represents.
+
+For example, consider two updatable replicas of a naming context, one
+is assigned replica identifier '1', the other replica identifier '2'.
+Each is responsible for maintaining its own update vector, which will
+contain two CSNs, one for each replica. So, if both replicas are
+identical they will have equivalent update vectors.
+
+Both Update Vectors =
+
+{1998081018:44:31z#0x000F#1#0x0000, 1998081018:51:20z#0x0001#2#0x0000}
+
+Subsequently, at 7pm, an update is applied to replica '2', so its
+update vector is updated.
+
+Replica '1' Update Vector =
+
+{1998081018:44:31z#0x000F#1#0x0000, 1998081018:51:20z#0x0001#2#0x0000}
+
+Merrells, Reed, Srinivasan [Page 23]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+Replica '2' Update Vector =
+
+{1998081018:44:31z#0x000F#1#0x0000, 1998081019:00:00z#0x0000#2#0x0000}
+
+Since the Update Vector records the state to which the replica has
+been updated, a supplier server, during Replication Session
+initiation, can determine the sequence of updates that should be sent
+to the consumer. From the example above no updates need to be sent
+from replica '1' to replica '2', but there is an update pending from
+replica '2' to replica '1'.
+
+Because the Update Vector embodies knowledge of updates made at all
+known replicas it supports replication topologies that include
+transitive and redundant connections between replicas. It ensures that
+changes are not transferred to a consumer multiple times even though
+redundant replication agreements may exist. It also ensures that
+updates are passed across the replication network between replicas
+that are not directly linked to each other.
+
+It may be the case that a CSN for a given replica is absent, for one
+of two reasons.
+
+1. CSNs for Read-Only replicas might be absent because no changes will
+ have ever been applied to that Replica, so there are no changes to
+ replicate.
+
+2. CSNs for newly created replicas may be absent because no changes to
+ that replica have yet been propagated.
+
+An Update Vector might also contain a CSN for a replica that no longer
+exists. The replica may have been temporarily taken out of service,
+or may have been removed from the replication topology permanently. An
+implementation may choose to retire a CSN after some configurable time
+period.
+
+
+
+10.2 Supplier Initiated, Incremental Update, Start Replication Session
+
+The Consumer Responder must return its Update Vector to the Supplier
+Initiator. The Supplier uses this to determine the sequence of
+Replication Updates that need to be sent to the Consumer.
+
+
+
+10.3 Replication Update Generation
+
+The Supplier generates a sequence of Replication Updates to be sent to
+the consumer. To enforce LDAP Constraint 20.1.6, that the LDAP Modify
+must be applied atomically, each Replication Update must contain the
+entire sequence of Update Primitives for all the LDAP Operations for
+which the Replication Update contains Update Primitives. Stated less
+formally, for each primitive the update contains, it must also contain
+all the other primitives that came from the same operation.
+
+
+Merrells, Reed, Srinivasan [Page 24]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+
+10.3.1 Replication Log Implementation
+
+A log-based implementation might take the approach of mapping LDAP
+Operations onto an equivalent sequence of Update Primitives. A
+systematic procedure for achieving this will be fully described in the
+standard document defining Update Reconciliation Procedures.
+
+The Consumer Update Vector is used to determine the sequence of LDAP
+Operations in the operation log that the Consumer has not yet seen.
+
+
+
+10.3.2 State-Based Implementation
+
+A state-based implementation might consider each entry of the replica
+in turn using the Update Vector of the consumer to find all the state
+changes that need to be transferred. Each state change (entry,
+attribute, or value - creation, deletion, or update) is mapped onto
+the equivalent Update Primitive. All the Update Primitives for a
+single entry might be collected into a single Replication Update.
+Consequently, it could contain the resultant primitives of many LDAP
+operations.
+
+
+
+10.4 Replication Update Consumption
+
+A Consumer will receive Replication Updates, extract the sequence of
+Update Primitives, and must apply them to the DIB in the order
+provided. LDAP Constraint 20.1.6 states that the modifications within
+an LDAP Modify operation must be applied in the sequence provided.
+
+Those Update Primitives must be reconciled with the current replica
+contents and any previously received updates. In short,,
+updates are compared to the state information associated with the item
+being operated on. If the change has a more recent CSN, then it is
+applied to the directory contents. If the change has an older CSN it
+is no longer relevant and its change must not be effected.
+
+If the consumer acts as a supplier to other replicas then the updates
+are retained for forwarding.
+
+
+
+10.5 Update Resolution Procedures
+
+The LDAP Update Operations must abide by the constraints imposed by
+the LDAP Data Model and LDAP Operational Behaviour, Appendix A. An
+operation that would violate at least one of these constraints is
+rejected with an error result code.
+
+The loose consistency model of this replication architecture and its
+support for multiple updateable replicas of a naming context means
+
+
+Merrells, Reed, Srinivasan [Page 25]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+that LDAP Update Operations could be valid at one replica, but not in
+another. At the time of acceptance, the accepting
+replica may not have received other updates that would cause a
+constraint to be violated, and the operation to be rejected.
+
+Replication Updates must never be rejected because of a violation of
+an LDAP Constraint. If the result of applying the Replication Update
+causes a constraint violation to occur, then some remedial action must
+be taken to satisfy the constraint. These Update Resolution Procedures
+are introduced here will be fully defined withinLDUP Update Resolution
+Procedures.
+
+
+
+10.5.1 URP: Distinguished Names
+
+LDAP Constraints 20.1.1 and 20.1.10 ensure that each entry in the
+replicated area has a unique DN. A Replication Update could violate
+this constraint producing two entries, with different unique
+identifiers, but with the same DN. The resolution procedure is to
+rename the most recently named entry so that its RDN includes its own
+unique identifier. This ensures that the new DN of the entry shall be
+unique.
+
+
+
+10.5.2 URP: Orphaned Entries
+
+LDAP Constraints 20.1.11 ensures that every entry must have a parent
+entry. A Replication Update could violate this constraint producing an
+entry with no parent entry. The resolution procedure is to create a
+Glue Entry to take the place of the absent parent. The Glue Entry's
+superior will be the Lost and Found Entry. This well known place
+allows administrators and their tools to find and repair abandoned
+entries.
+
+
+
+10.5.3 URP: Distinguished Not Present
+
+LDAP Constraints 20.1.8 and 20.1.9 ensure that the components of an
+RDN appear as attribute values of the entry. A Replication Update
+could violate this constraint producing an entry without its
+distinguished values. The resolution procedure is to add the missing
+attribute values, and mark them as distinguished not present, so that
+they can be deleted when the attribute values are no longer
+distinguished.
+
+
+
+10.5.4 URP: Schema - Single Valued Attributes
+
+LDAP Constraint 20.1.7 enforces the single-valued attribute schema
+restriction. A Replication Update could violate this constraint
+creating a multi-value single-valued attribute. The resolution
+
+
+Merrells, Reed, Srinivasan [Page 26]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+procedure is to consider the value of a single-valued attribute as
+always being equal. In this way the most recently added value will be
+retained, and the older one discarded.
+
+
+
+10.5.5 URP: Schema - Required Attributes
+
+LDAP Constraint 20.1.7 enforces the schema objectclass definitions on
+an entry. A Replication Update could violate this constraint creating
+an entry that does not have attribute values for required attributes.
+The resolution procedure is to ignore the schema violation and mark
+the entry for administrative repair.
+
+
+
+10.5.6 URP: Schema - Extra Attributes
+
+LDAP Constraint 20.1.3 and 20.1.7 enforces the schema objectclass
+definitions on an entry. A Replication Update could violate this
+constraint creating an entry that has attribute values not allowed by
+the objectclass values of the entry. The resolution procedure is to
+ignore the schema violation and mark the entry for administrative
+repair.
+
+
+
+10.5.7 URP: Duplicate Attribute Values
+
+LDAP Constraint 20.1.5 ensures that the values of an attribute
+constitute a set of unique values. A Replication Update could violate
+this constraint. The resolution procedure is to enforce this
+constraint, recording the most recently assigned CSN with the value.
+
+
+
+10.5.8 URP: Ancestry Graph Cycle
+
+LDAP Constraint 20.4.2.1 prevents against a cycle in the DIT. A
+Replication Update could violate this constraint causing an entry to
+become it's own parent, or for it to appear even higher in it's
+ancestry graph. The resolution procedure is to break the cycle by
+changing the parent of the entry closest to be the lost and found
+entry.
+
+
+
+10.6 Incremental Update, End Replication Session
+
+If the Supplier sent none of its own updates to the Consumer, then the
+Supplier's CSN within the Supplier's update vector should be updated
+with the earliest possible CSN that it could generate, to record the
+time of the last successful replication session. The Consumer will
+have received the Supplier's Update Vector in the replica sub-entry it
+holds for the Supplier replica.
+
+Merrells, Reed, Srinivasan [Page 27]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+The Consumer's resultant Update Vector CSN values will be at least as
+great as the Supplier's Update Vector.
+
+The Supplier may request that the Consumer return its resultant Update
+Vector so that the Supplier can update its replica sub-entry for the
+Consumer Replica. The Supplier requests this by setting a flag in the
+End Replication Request. The default flag value is TRUE meaning the
+Consumer Update Vector must be returned.
+
+
+
+10.7 Interrupted Transmission
+
+If the Replication Session terminates before the End Replication
+Request is sent then the Consumer's Update Vector may or may not be
+updated to reflect the updates received. The Start Replication request
+includes a Replication Update Ordering flag which states whether the
+updates were sent in CSN order per replica.
+
+If updates are sent in CSN order per replica then it is possible to
+update the Consumer Update Vector to reflect that some portion of the
+updates to have been sent have been received and successfully applied.
+The next Incremental Replication Session will pick up where the failed
+session left off.
+
+If updates are not sent in CSN order per replica then the Consumer
+Update can not be updated. The next Incremental Replication Session
+will begin where the failed session began. Some updates will be
+replayed, but because the application of Replication Updates is
+idempotent they will not cause any state changes.
+
+
+
+11 Purging State Information
+
+
+The state information stored with each entry need not be stored
+indefinitely. A server implementation may choose to periodically, or
+continuously, remove state information that is no longer required. The
+mechanism is implementation-dependent, but to ensure interoperability
+between implementations, the state information must not be purged
+until all known replicas have received and acknowledged the change
+associated with a CSN. This is determined from the Purge Vector
+[11.1].
+
+All the CSNs stored that are lower than the Purge Vector may be
+purged, because no changes with older CSNs can be replicated to this
+replica.
+
+
+
+11.1 Purge Vector
+
+The Purge Vector is an Update Vector constructed from the Update
+Vectors of all known replicas. Each replica has a sub-entry for each
+
+Merrells, Reed, Srinivasan [Page 28]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+known replica stored below its naming context. Each of those entries
+contains the last known update vector for that replica. The lowest CSN
+for each replica are taken from these update vectors to form the Purge
+Vector. The Purge Vector is used to determine when state information
+and updates need no longer be stored.
+
+
+
+11.2 Purging Deleted Entries, Attributes, and Attribute Values
+
+The following conditions must hold before an item can be deleted from
+the Directory Information Base.
+
+1) The LDAP delete operation has been propagated to all replication
+agreement partners.
+
+2) All the updates from all the other replicas with CSNs less than the
+CSN on the deletion have been propagated to the server holding the
+deleted entry (similarly for deleted attributes and attribute values).
+
+3) The CSN generator of the other Replicas must have advanced beyond
+the deletion CSN of the deleted entry. Otherwise, it is possible for
+one of those Replicas to generate operations with CSNs earlier than
+the deleted entry.
+
+
+12 Replication Configuration and Management
+
+
+Replication management entries, such as replica or replication
+agreement entries, can be altered on any updateable replica. These
+entries are implicitly included in the directory entries governed by
+any agreement associated with this naming context. As a result, all
+servers with a replica of a naming context will have access to
+information about all other replicas and associated agreements.
+
+The deployment and maintenance of a replicated directory network
+involves the creation and management of all the replicas of a naming
+context and replication agreements among these replicas. This section
+outlines, through an example, the administrative actions necessary to
+create a new replica and establish replication agreements. Typically,
+administrative tools will guide the administrator and facilitate these
+actions. The objective of this example is to illustrate the
+architectural relationship among various replication related
+operational information.
+
+A copy of an agreement should exist on both the supplier and consumer
+side for the replication update transfer protocol to be able to start.
+For this purpose, the root of the naming context, replica objects and
+the replication agreement objects are created first on one of the
+servers. A copy of these objects are then manually created on the
+second server associated with the agreement.
+
+The scenario below starts with a server (named DSA1) that holds an
+updateable replica of a naming context NC1. Procedures to establish
+an updateable replica of the naming context on a second server (DSA2)
+
+Merrells, Reed, Srinivasan [Page 29]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+are outlined.
+
+On DSA1:
+
+1) Add the context prefix for NC1 to the Root DSE attribute
+ 'replicaRoot' if it does not already exist.
+
+2) Alter the 'ObjectClass' attribute of the root entry of NC1 to
+ include the "namingContext" auxiliary class.
+
+3) Create a replica object, NC1R1, (as a child of the root of NC1) to
+ represent the replica on DSA1. The attributes include replica type
+ (updateable, read-only etc.) and DSA1 access point information.
+
+4) Create a copy of the replica object NC1R2 (after it is created on
+ DSA2)
+
+5) Create a replication agreement, NC1R1-R2 to represent update
+ transfer from NC1R1 to NC1R2. This object is a child of NC1R1.
+
+On DSA2:
+
+1) Add NC1's context prefix to the Root DSE attribute 'replicaRoot'.
+
+2) Create a copy of the root entry of NC1 as a copy of the one in DSA1
+ (including the namingContext auxiliary class)
+
+3) Create a copy of the replica object NC1R1
+
+4) Create a second replica object, NC1R2 (as a sibling of NC1R1) to
+ represent the replica on DSA2.
+
+5) Create a copy of the replication agreement, NC1R1-R2
+
+6) Create a replication agreement, NC1R2-R1, to represent update
+ transfer from NC1R2 to NC1R1. This object is a sibling of NC1R1-
+ R2.
+
+After these actions update transfer to satisfy either of the two
+agreements can commence.
+
+If data already existed in one of the replicas, the update transfer
+protocol should perform a complete update of the data associated with
+the agreement before normal replication begins.
+
+
+
+13 Time
+
+
+The server assigns a CSN for every LDAP update operation it receives.
+Since the CSN is principally based on time, the CSN is susceptible to
+the Replica clocks drifting in relation to each other (either forwards
+or backwards).
+
+The server must never assign a CSN older than or equal to the last CSN
+it assigned.
+
+Merrells, Reed, Srinivasan [Page 30]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+
+The server must reject update operations, from any source, which would
+result in setting a CSN on an entry or a value which is earlier than
+the one that is there. The error code serverClocksOutOfSync (72)
+should be returned.
+
+
+14 Security Considerations
+
+
+The preceding architecture discussion covers the server
+authentication, session confidentiality, and session integrity in
+sections 7.1.1 and 7.5
+
+The internet draft "Authentication Methods" for LDAP, provides a
+detailed LDAP security discussion. Its introductory passage is
+paraphrased below. [AUTH]
+
+A Replication Session can be protected with the following security
+mechanisms.
+
+1) Authentication by means of the SASL mechanism set, possibly backed
+ by the TLS credentials exchange mechanism,
+
+2) Authorization by means of access control based on the Initiators
+ authenticated identity,
+
+3) Data integrity protection by means of the TLS protocol or data-
+ integrity SASL mechanisms,
+
+4) Protection against snooping by means of the TLS protocol or data-
+ encrypting SASL mechanisms,
+
+The configuration entries that represent Replication Agreements may
+contain authentication information. This information must never be
+replicated between replicas.
+
+Updates to a multi-mastered entry may collide causing the Update
+Resolution Procedures [10.5] to reject or reverse one of the changes
+to the entry. The URP algorithms resolve conflicts by using the total
+ordering of updates imposed by the assignment of CSNs for every
+operation. As a consequence updates originating from system
+administrators have no priority over updates originating from regular
+system users.
+
+
+
+15 Acknowledgements
+
+
+This document is a product of the LDUP Working Group of the IETF. The
+contributions of its members is greatly appreciated.
+
+
+
+
+
+Merrells, Reed, Srinivasan [Page 31]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+16 References
+
+
+[AUTH] - M. Wahl, H. Alvestrand, J. Hodges, RL "Bob" Morgan,
+"Authentication Methods for LDAP", Internet Draft, draft-ietf-ldapext-
+authmeth-02.txt, June 1998.
+
+[BCP-11] - R. Hovey, S. Bradner, "The Organizations Involved in the
+IETF Standards Process", BCP 11, RFC 2028, October 1996.
+
+[LDAPv3] - M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
+Protocol (v3)", RFC 2251, December1997.
+
+[LDUP Requirements] - R. Weiser, E. Stokes 'LDAP Replication
+Requirements', Internet Draft, draft-weiser-replica-req-02.txt,
+October, 1999
+
+[NTP] - D. L. Mills, "Network Time Protocol (Version 3)", RFC 1305,
+March, 1992.
+
+[RFC2119] - S. Bradner, "Key words for use in RFCs to Indicate
+Requirement Levels", RFC 2119.
+
+[RFC2252] - M. Wahl, A. Coulbeck, T. Howes, S. Kille, 'Lightweight
+Directory Access Protocol (v3): Attribute Syntax Definitions', RFC
+2252, December 1997.
+
+[SNTP] - D. L. Mills, "Simple Network Time Protocol (SNTP) Version 4
+for IPv4, IPv6 and OSI", RFC 2030, University of Delaware, October
+1996.
+
+[TLS] - J. Hodges, R. L. "Bob" Morgan, M. Wahl, "Lightweight
+Directory Access Protocol (v3): Extension for Transport
+Layer Security", Internet draft, draft-ietf-ldapext-ldapv3-tls-01.txt,
+June 1998.
+
+[X501] - ITU-T Recommendation X.501 (1993), ) | ISO/IEC 9594-2:1993,
+Information Technology - Open Systems Interconnection - The Directory:
+Models
+
+[X680] - ITU-T Recommendation X.680 (1994) | ISO/IEC 8824-1:1995,
+Information technology - Abstract Syntax Notation One (ASN.1):
+Specification of Basic Notation
+
+[X525] - ITU-T Recommendation X.525 (1997) | ISO/IEC 9594-9:1997,
+Information Technology - Open Systems Interconnection - The Directory:
+Replication
+
+
+17 Intellectual Property Notice
+
+
+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
+
+
+Merrells, Reed, Srinivasan [Page 32]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+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. [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.
+
+
+18 Copyright Notice
+
+
+ Copyright (C) The Internet Society (1998,1999). 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.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an
+"AS IS" basis and 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.
+
+
+19 Authors' Address
+
+
+ John Merrells
+ Netscape Communications, Inc.
+ 501 East Middlefield Road
+ Mountain View
+ CA 94043
+ USA
+ E-mail: merrells@netscape.com
+
+
+Merrells, Reed, Srinivasan [Page 33]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+ Phone: +1 650-937-5739
+
+ Edwards E. Reed
+ Reed-Matthews, Inc.
+ 1064 East 140 North
+ Lindon
+ UT 84042
+ USA
+ E-mail: eer@oncalldba.com
+ Phone: +1 801-796-7065
+
+ Uppili Srinivasan
+ Oracle, Inc.
+ Redwood Shores
+ CA
+ USA
+ E-mail: usriniva@us.oracle.com
+ Phone: +1 650 506 3039
+
+ LDUP Engineering Mailing List: ldup-repl@external.cisco.com
+ LDUP Working Group Mailing List: ietf-ldup@imc.org
+
+
+20 Appendix A - LDAP Constraints
+
+
+20.1 LDAP Constraints Clauses
+
+This is an enumeration of the Data Model and Operation Behaviour
+constraint clauses defined in RFC 2251. [LDAPv3]
+
+1) Data Model - Entries have names: one or more attribute values from
+ the entry form its relative distinguished name (RDN), which MUST be
+ unique among all its siblings. (p5)
+
+2) Data Model - Attributes of Entries - Each entry MUST have an
+ objectClass attribute. (p6)
+
+3) Data Model - Attributes of Entries - Servers MUST NOT permit
+ clients to add attributes to an entry unless those attributes are
+ permitted by the object class definitions. (p6)
+
+4) Relationship to X.500 - This document defines LDAP in terms of
+ X.500 as an X.500 access mechanism. An LDAP server MUST act in
+ accordance with the X.500 (1993) series of ITU recommendations when
+ providing the service. However, it is not required that an LDAP
+ server make use of any X.500 protocols in providing this service,
+ e.g. LDAP can be mapped onto any other directory system so long as
+ the X.500 data and service model as used in LDAP is not violated in
+ the LDAP interface. (p8)
+
+5) Elements of Protocol - Common Elements - Attribute - Each attribute
+ value is distinct in the set (no duplicates). (p14)
+
+6) Elements of Protocol - Modify Operation - The entire list of entry
+ modifications MUST be performed in the order they are listed, as a
+
+Merrells, Reed, Srinivasan [Page 34]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+ single atomic operation. (p33)
+
+7) Elements of Protocol - Modify Operation - While individual
+ modifications may violate the directory schema, the resulting entry
+ after the entire list of modifications is performed MUST conform to
+ the requirements of the directory schema. (p33)
+
+8) Elements of Protocol - Modify Operation - The Modify Operation
+ cannot be used to remove from an entry any of its distinguished
+ values, those values which form the entry's relative distinguished
+ name. (p34)
+
+9) Elements of Protocol - Add Operation - Clients MUST include
+ distinguished values (those forming the entry's own RDN) in this
+ list, the objectClass attribute, and values of any mandatory
+ attributes of the listed object classes. (p35)
+
+10) Elements of Protocol - Add Operation - The entry named in the
+ entry field of the AddRequest MUST NOT exist for the AddRequest to
+ succeed. (p35)
+
+11) Elements of Protocol - Add Operation - The parent of the entry to
+ be added MUST exist. (p35)
+
+12) Elements of Protocol - Delete Operation - ... only leaf entries
+ (those with no subordinate entries) can be deleted with this
+ operation. (p35)
+
+13) Elements of Protocol - Modify DN Operation - If there was already
+ an entry with that name [the new DN], the operation would fail.
+ (p36)
+
+14) Elements of Protocol - Modify DN Operation - The server may not
+ perform the operation and return an error code if the setting of
+ the deleteoldrdn parameter would cause a schema inconsistency in
+ the entry. (p36)
+
+
+
+20.2 LDAP Data Model Constraints
+
+The LDAP Data Model Constraint clauses as written in RFC 2251 [LDAPv3]
+may be summarised as follows.
+
+a) The parent of an entry must exist. (LDAP Constraint 11 & 12.)
+
+b) The RDN of an entry is unique among all its siblings. (LDAP
+ Constraint 1.)
+
+c) The components of the RDN must appear as attribute values of the
+ entry. (LDAP Constraint 8 & 9.)
+
+d) An entry must have an objectclass attribute. (LDAP Constraint 2 &
+ 9.)
+
+e) An entry must conform to the schema constraints. (LDAP Constraint
+
+
+Merrells, Reed, Srinivasan [Page 35]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+ 3 & 7.)
+
+f) Duplicate attribute values are not permitted. (LDAP Constraint 5.)
+
+
+
+20.3 LDAP Operation Behaviour Constraints
+
+The LDAP Operation Behaviour Constraint clauses as written in RFC 2251
+[LDAPv3] may be summarised as follows.
+
+A) The Add Operation will fail if an entry with the target DN already
+exists. (LDAP Constraint 10.)
+
+B) The Add Operation will fail if the entry violates data constraints:
+
+ a - The parent of the entry does not exist. (LDAP Constraint 11.)
+
+ b - The entry already exists. (LDAP Constraint 10.)
+
+ c - The entry RDN components appear as attribute values on the
+ entry. (LDAP Constraint 9.)
+
+ d - The entry has an objectclass attribute. (LDAP Constraint 9.)
+
+ e - The entry conforms to the schema constraints. (LDAP
+ Constraint 9.)
+
+ f - The entry has no duplicated attribute values. (LDAP
+Constraint 5.)
+
+C) The modifications of a Modify Operation are applied in the order
+presented. (LDAP Constraint 6.)
+
+D) The modifications of a Modify Operation are applied atomically.
+(LDAP Constraint 6.)
+
+E) A Modify Operation will fail if it results in an entry that
+violates data constraints:
+
+ c - If it attempts to remove distinguished attribute values.
+ (LDAP Constraint 8.)
+
+ d - If it removes the objectclass attribute. (LDAP Constraint 2.)
+
+ e - If it violates the schema constraints. (LDAP Constraint 7.)
+
+ f - If it creates duplicate attribute values. (LDAP Constraint
+ 5.)
+
+F) The Delete Operation will fail if it would result in a DIT that
+violates data constraints:
+
+ a - The deleted entry must not have any children. (LDAP
+Constraint 12.)
+
+
+
+Merrells, Reed, Srinivasan [Page 36]
+ Expires 10 September 2000
+
+
+
+
+
+INTERNET-DRAFT LDAP Replication Architecture March 10, 2000
+
+
+G) The ModDN Operation will fail if it would result in a DIT or entry
+that violates data constraints:
+
+ b - The new Superior entry must exist. (Derived LDAP Data Model
+ Constraint A)
+
+ c - An entry with the new DN must not already exist. (LDAP
+ Constraint 13.)
+
+ c - The new RDN components do not appear as attribute values on
+ the entry. (LDAP Constraint 1.)
+
+ d - If it removes the objectclass attribute. (LDAP Constraint 2.)
+
+ e - It is permitted for the operation to result in an entry that
+ violates the schema constraints. (LDAP Constraint 14.)
+
+
+
+20.4 New LDAP Constraints
+
+The introduction of support for multi-mastered entries, by the
+replication scheme presented in this document, necessitates the
+imposition of new constraints upon the Data Model and LDAP Operation
+Behaviour.
+
+
+
+20.4.1 New LDAP Data Model Constraints
+
+1) Each entry shall have a unique identifier generated by the UUID
+algorithm available through the 'entryUUID' operational attribute. The
+entryUUID attribute is single valued.
+
+
+
+20.4.2 New LDAP Operation Behaviour Constraints
+
+1) The LDAP Data Model Constraints do not prevent cycles in the
+ ancestry graph. Existing constraints Data Model Constraint - 20.4.1
+ - (a) and Operation Constraint - 20.4.2 - (B) would prevent this in
+ the single master case, but not in the presence of multiple
+ masters.
+
+2) The LDAP Data Model Constraints state that only the LDAP Modify
+ Operation is atomic. All other LDAP Update Operations are also
+ considered to be atomically applied to the DIB.
+
+
+
+
+
+
+
+
+
+Merrells, Reed, Srinivasan [Page 37]
+ Expires 10 September 2000
+
+
--- /dev/null
+
+LDUP Replication Update Protocol
+Internet-Draft
+Intended Category: Standards Track
+Expires: September 10, 2000
+
+
+ Ellen Stokes
+ IBM Corporation
+
+ Gordon Good
+ Netscape Communications Corp.
+
+ March 10 2000
+
+ The LDUP Replication Update Protocol
+ Filename: draft-ietf-ldup-protocol-01.txt
+
+Table of Contents
+
+1. Status of this Memo.............................................2
+2. Abstract........................................................2
+3. Overview of Protocol............................................2
+4. High-level Description of Protocol Flow.........................3
+4.1 Supplier-initiated incremental replication protocol.............3
+4.2. Consumer-initiated replication protocol......................4
+5. Replication protocol element definitions........................5
+5.1 StartFramedProtocolRequest Extended Operation...................5
+5.2 StartFramedProtocolResponse Extended Operation..................6
+5.3 ReplicationUpdate Extended Operation............................7
+5.3.1 UniqueIdentifier.............................................8
+5.3.2 ReplicationPrimitive.........................................8
+5.3.2.1 AddEntryPrimitive.........................................8
+5.3.2.2 MoveEntryPrimitive........................................9
+5.3.2.3 RenameEntryPrimitive......................................9
+5.3.2.4 RemoveEntryPrimitive......................................9
+5.3.2.5 AddAttributeValuePrimitive................................10
+5.3.2.6 RemoveAttributeValuePrimitive.............................10
+5.3.2.7 RemoveAttributePrimitive..................................10
+5.4 EndFramedProtocolRequest Extended Operation.....................11
+5.5 EndFramedProtocolResponse Extended Operation....................11
+5.6 ReplicationUpdateResponse Extended Operation....................12
+6. Semantics of Full and Incremental Update protocols..............13
+7. Summary of response codes.......................................13
+8. Implications for log-based and state-based servers..............13
+9. Replication of access control and schema information............13
+10. Security Considerations.........................................14
+11. Glossary of Terms...............................................14
+12. Acknowledgments.................................................14
+13. References......................................................14
+14. Author's Addresses..............................................15
+
+
+
+Stokes and Good [Page 1]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+1. Status of this Memo
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that other
+ groups may also distribute working documents as Internet-Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet- Drafts as reference
+ material or to cite them other than as "work in progress."
+
+ To view the list Internet-Draft Shadow Directories, see
+ http://www.ietf.org/shadow.html.
+
+ This Internet Draft expires September 10, 2000.
+
+
+2. Abstract
+
+ The protocol described in this document is designed to allow one LDAP
+ server to replicate its directory content to another LDAP server. The
+ protocol is designed to be used in a replication configuration where
+ multiple updatable servers are present. Provisions are made in the
+ protocol to carry information that allows the server receiving
+ updates to apply a total ordering to all updates in the replicated
+ system. This total ordering allows all replicas to correctly resolve
+ conflicts that arise when LDAP clients submit changes to different
+ servers that later replicate to one another.
+
+ All protocol elements described here are LDAP Version 3 extended
+ operations. LDAP Version 3 is described in RFC 2251 [LDAPv3].
+
+ Certain terms used in this document are defined in the document "LDAP
+ Replication Architecture" (draft-ietf-ldup-model-00.txt).
+
+ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+ "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
+ to be interpreted as described in RFC 2119 [KEYWORDS].
+
+3. Overview of Protocol
+
+ The LDAP Replication Architecture [ARCHITECTURE] describes the
+ overall approach used in ensuring consistency of multiple updatable
+ replicas of directory content. The protocol described in this
+ document implements the approach desribed in that document.
+
+
+
+Stokes and Good [Page 2]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ LDAP Version 3 extended operations are used to carry replicated
+ content from one server to another. The extended operations defined
+ in this document are used to initiate and end a replication session,
+ and to exchange updates. These updates carry with them information
+ that allows the receiving server to apply a total ordering to all of
+ the updates in a replicated system. All servers that receive
+ replication updates apply a consistent set of update resolution
+ policies, described in [URP]. Consistent application of the update
+ resolution policies ensures that all replicas eventually converge and
+ contain the same directory data.
+
+ This protocol is based upon the extended operations defined in
+ [FRAMING].
+
+ This protocol is intended to meet the requirements set forth in
+ [REQ].
+
+4. High-level Description of Protocol Flow
+
+ The following section provides a high-level overview of the
+ replication protocol. Throughout this section, the supplier server is
+ indicated by the letter "S" and the consumer server by the letter
+ "C". The construct "S -> C" indicates that the supplier is sending an
+ LDAPv3 extended operation to the consumer, and "C -> S" indicates
+ that the consumer is sending an LDAPv3 extended operation to the
+ supplier.
+
+4.1 Supplier-initiated incremental replication protocol
+
+ S -> C: LDAP bind operation (identity and credentials
+ used are implementation-defined)
+
+ C -> S: Bind response
+
+ S -> C: StartFramedProtocolRequest LDAPv3 extended
+ operation. The parameters are:
+
+ 1) The OID for the LDUP incremental replication protocol or the
+ LDUP total update protocol, depending on whether an incremental
+ or complete refresh of the replica is to be performed.
+ 2) A protocol-specific payload containing:
+ a) The root of replicated area (unambiguously
+ identifies the replicated area)
+ b) The supplier's replicaID
+ c) The protocol initiation type - Supplier-Initiated
+ in this case.
+
+ C -> S: StartFramedProtocolResponse LDAPv3 extended operation. The
+
+
+
+Stokes and Good [Page 3]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ parameters are:
+
+ 1) A protocol-specific payload containing:
+ a) A response code (see section 7)
+ b) An optional update vector that is included
+ if and only if the response code is REPL_SUCCESS.
+
+ S -> C: The supplier may send zero or more ReplicationUpdate LDAPv3
+ extended operations. The parameters are:
+
+ 1) The UUID of the entry being updated
+ 2) One or more Replication Primitives (The supplier
+ may send as many of these as required to bring
+ the consumer up to date)
+
+ C -> S: At any time, the consumer may send an unsolicited
+ ReplicationUpdateResponse LDAPv3 extended operation. The
+ parameters are:
+
+ 1) An optional update vector. If sent, this indicates that
+ the consumer has committed all updates whose CSNs are
+ covered by the transmitted update vector [see glossary
+ for a definition of "covered by"].
+ 2) An optional AbortUpdate boolean flag. If a supplier
+ receives a ReplicationUpdateResponse from a consumer with
+ the AbortUpdate flag set to true, the supplier server MUST
+ immediately cease sending updates and terminate its
+ connection to the consumer.
+
+ S -> C: After all required updates have been sent to the consumer, the
+ supplier sends an EndFramedProtocolRequest LDAPv3 extended
+ operation.
+
+ C -> S: The consumer responds by sending an EndFramedProtocolResponse
+ LDAPv3 extended operation, and then closes the connection.
+
+4.2. Consumer-initiated replication protocol
+
+ C -> S: LDAP bind operation (identity and credentials
+ used are implementation-defined)
+
+ S -> C: Bind response
+
+ C -> S: StartFramedProtocolRequest LDAPv3 extended
+ operation. The parameters are:
+
+ 1) The OID for the LDUP incremental replication protocol or the
+ LDUP total update protocol, depending on whether an incremental
+
+
+
+Stokes and Good [Page 4]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ or complete refresh of the replica is to be performed.
+ 2) A protocol-specific payload containing:
+ a) The root of replicated area (unambiguously
+ identifies the replicated area)
+ b) The consumer's replicaID
+ c) The protocol initiation type - Consumer-Initiated
+ in this case.
+
+ S -> C: StartFramedProtocolResponse LDAPv3 extended operation. The
+ parameters are:
+
+ 1) A protocol-specific payload containing:
+ a) A response code (see section 7)
+
+ S -> C: The supplier server disconnects from the consumer server,
+ and then connects to the consumer, beginning a Supplier-
+ Initiated protocol session (see section 4.1).
+
+
+5. Replication protocol element definitions
+
+5.1 StartFramedProtocolRequest Extended Operation
+
+ The StartFramedProtocolRequest extended operation is sent by a replication
+ initiator to a server to indicate that a replication session should
+ commence. For supplier-initiated replication, the supplier sends this
+ extended operation to the replication consumer to indicate that a
+ replication session should commence. For consumer-initiated
+ replication, the consumer sends this extended operation to the
+ replication supplier to indicate that the supplier should initiate a
+ replication session to the consumer as soon as possible.
+
+ The StartFramedProtocolRequest extended operation is defined
+ in [FRAMING]. When signaling the beginning of a replication
+ session, then requestValue of the StartFramedProtocolRequest
+ is set to the following:
+
+ requestValue ::= SEQUENCE {
+ framedProtocolOID LDAPOID,
+ framedProtocolPayload OPTIONAL OCTET STRING
+ }
+
+ The framedProtocolOID of the StartReplicationRequest must be the OID
+ for the LDUP incremental replication protocol,
+ 2.16.840.1.113719.1.142.1.4.3, or the LDUP total update protocol,
+ 2.16.840.1.113719.1.142.1.4.4. See section 7 for information on the
+ semantic behavior of these update protocols. Implementations MUST
+ support the two update protocols defined in this document.
+
+
+
+Stokes and Good [Page 5]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ The framedProtocolPayload of the StartFramedProtocolRequestValue must
+ be set to the BER-encoding of the following:
+
+ framedProtocolPayload ::= SEQUENCE {
+ replicaRoot LDAPDN,
+ replicaID LDAPString,
+ replicationInitiator ENUMERATED {
+ supplier (0),
+ consumer (1)
+ }
+ }
+
+ The parameters in the framedProtocolPayload of the
+ StartFramedProtocolRequestValue are:
+
+ - replicaRoot: the distinguished name of the entry at the top of
+ the replicated area, and uniquely identifies the unit of
+ replication.
+
+ - replicaID: the replica identifier of the replication initiator.
+ Each replica of a given replicated area is identified by a unique
+ identifier, described in [ARCHITECTURE].
+
+ - replicationInitiator: used to differentiate between a supplier-
+ initiated session and a consumer-initiated session. If the
+ replicationInitiator contains the enumerated value <supplier>,
+ then the initiator is the supplier, and the receiver of this
+ operation should prepare to receive a set of replication updates
+ (or should reject the operation is replication updates are not
+ permitted for some reasonm, perhaps due to access control
+ restrictions). If the replicationInitiator contains the
+ enumerated value <consumer>, then the receiver should prepare to
+ establish a supplier-initiated replication session with the
+ consumer as soon as possible, updating the replicated are given by
+ replicaRoot and using the update protocol given by
+ replicationProtocolOID.
+
+5.2 StartFramedProtocolResponse Extended Operation
+
+ The StartFramedProtocolResponse extended operation is sent in
+ response to a StartFramedProtocolRequest extended operation.
+
+ For a supplier-initiated session, the response field of the
+ StartFramedProtocolResponse extended response indicates that the
+ consumer is or is not prepared to accept a set of updates. If the
+ consumer is prepared to accept updates, it sends a response field
+ containing a success code and the consumer's replica update vector.
+ If the consumer is unwilling or unable to accept updates, it sends a
+
+
+
+Stokes and Good [Page 6]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ response field containing an error code.
+
+ For a consumer-initiated session, the response field of the
+ StartFramedProtocolResponse extended respons indicates that the
+ supplier is or is not prepared to send a set of updates to the
+ consumer. If the supplier is prepared to send updates to the
+ consumer, it sends a response field containing a success code. If the
+ supplier is unwilling or unable to send updates to the consumer, it
+ sends a response field containing an error code. In both cases, the
+ supplier disconnects from the consumer. If the supplier sent a
+ success code to the consumer, it opens a connection to the consumer
+ as soon as possible and initiates a supplier-initiated replication
+ session.
+
+ The StartFramedProtocolResponse extended operation is defined in
+ [FRAMING]. When responding to a StartFramedProtocolRequest signaling
+ the beginning of an LDUP replication session, the response field of
+ the StartFramedProtocolResponse is set to the following:
+
+ StartFramedProtocolResponseValue ::= SEQUENCE {
+ responseCode LDUPResponseCode,
+ replicaUpdateVector Attribute,
+ }
+
+ LDUPResponseCodes are defined in section 8.
+
+ The replicaUpdateVector contains a replica update vector, as defined
+ in [INFOMOD]. The update vector is encoded as a normal LDAP
+ attribute, defined in [LDAPv3].
+
+
+5.3 ReplicationUpdate Extended Operation
+
+The ReplicationUpdate extended operation carries a set of replication
+primitives that represent the desired final state of a single entry.
+
+The ReplicationUpdate extended operation is defined as follows:
+
+An LDAPv3 Extended Request is defined in [LDAPv3] as follows:
+
+ ExtendedRequest ::= [APPLICATION 23] SEQUENCE {
+ requestName [0] LDAPOID
+ requestValue [1] OCTET STRING OPTIONAL
+ }
+
+The requestName of the ReplicationUpdate must be the OID
+2.16.840.1.113719.1.142.100.3.
+
+
+
+
+Stokes and Good [Page 7]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+The requestValue of the ReplicationUpdate must be set to the BER-
+encoding of the following:
+
+ requestValue ::= SEQUENCE {
+ uniqueID UniqueIdentifier,
+ updates SET OF ReplicationPrimitive
+ }
+
+5.3.1 UniqueIdentifier
+
+ The Distinguished Name of an entry may be changed (by renaming the
+ entry), or the entry may not have a distinguished name (if it was
+ deleted). The Unique Identifier provides an immutable name,
+ independent of the current name or deletion status, for an entry. All
+ replicated operations address entries by their Unique Identifiers.
+
+ UniqueIdentifier ::= LDAPString
+
+
+5.3.2 ReplicationPrimitive
+
+ A ReplicationPrimitive carries a single assertion about the the final
+ state of an entry, attribute, or attribute value. There are seven
+ types of primitives.
+
+ ReplicationPrimitive ::= CHOICE {
+ addEntryPrimitive AddEntryPrimitive,
+ moveEntryPrimitive MoveEntryPrimitive,
+ renameEntryPrimitive RenameEntryPrimitive,
+ removeEntryPrimitive RemoveEntryPrimitive,
+ addAttributeValuePrimitive AddAttributeValuePrimitive,
+ removeAttributeValuePrimitive RemoveAttributeValuePrimitive,
+ removeAttributePrimitive RemoveAttributePrimitive
+ }
+
+ Each primitive applies to the entry referred to by the
+ uniqueIdentifier in the enclosing ReplicationUpdate extended
+ operation.
+
+ Each primitive carries an lLDAPChangeSequenceNumber that is used by
+ the consumer server to correctly resolve update conflicts. [URP]
+ describes the update reconciliation procedures.
+
+5.3.2.1 AddEntryPrimitive
+
+ The AddEntryPrimitive is used to add a new entry.
+
+ AddEntryPrimitive ::= [APPLICATION 0] SEQUENCE {
+
+
+
+Stokes and Good [Page 8]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ csn lDAPChangeSequenceNumber,
+ superior UniqueIdentifier,
+ rdn RelativeLDAPDN
+ }
+
+ Parameters of the AddEntryPrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - superior: The unique identifier of the superior (parent) entry.
+
+ - rdn: The relative distinguished name of the new entry.
+
+5.3.2.2 MoveEntryPrimitive
+
+ The MoveEntryPrimitive is used to move an entry to a new location in
+ the DIT.
+
+ MoveEntryPrimitive ::= [APPLICATION 1] SEQUENCE {
+ csn lDAPChangeSequenceNumber,
+ superior UniqueIdentifier
+ }
+
+ Parameters of the MoveEntryPrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - superior: The unique identifier of the new superior (parent)
+ entry.
+
+5.3.2.3 RenameEntryPrimitive
+
+ The RenameEntryPrimitive is used to change the RDN of an entry.
+
+ RenameEntryPrimitive ::= [APPLICATION 2] SEQUENCE {
+ csn lDAPChangeSequenceNumber,
+ rdn RelativeLDAPDN
+ }
+
+ Parameters of the RenameEntryPrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - rdn: The new relative distinguished name of the entry.
+
+5.3.2.4 RemoveEntryPrimitive
+
+ The RemoveEntryPrimitive is used to delete an entry from the DIT.
+
+
+
+Stokes and Good [Page 9]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ RemoveEntryPrimitive ::= [APPLICATION 3] SEQUENCE {
+ csn lDAPChangeSequenceNumber
+ }
+
+ Parameters of the RemoveEntryPrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+5.3.2.5 AddAttributeValuePrimitive
+
+ The AddAttributeValuePrimitive is use to add a new attribute value to
+ an entry.
+
+ AddAttributeValuePrimitive ::= [APPLICATION 4] SEQUENCE {
+ csn lDAPChangeSequenceNumber,
+ type AttributeDescription,
+ value AttributeValue
+ }
+
+ Parameters of the AddAttributeValuePrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - type: The type of the attribute being added.
+
+ - value: The value being added. Multiple values are not permitted.
+
+5.3.2.6 RemoveAttributeValuePrimitive
+
+ The RemoveAttributeValuePrimitive is used to remove a particular
+ attribute value from an entry.
+
+ RemoveAttributeValuePrimitive ::= [APPLICATION 5] SEQUENCE {
+ csn lDAPChangeSequenceNumber,
+ type AttributeDescription,
+ value AttributeValue
+ }
+
+ Parameters of the RemoveAttributeValuePrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - type: The type of the attribute being removed.
+
+ - value: The value being removed. Multiple values are not
+ permitted.
+
+5.3.2.7 RemoveAttributePrimitive
+
+
+
+Stokes and Good [Page 10]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ The RemoveAttributePrimitive is used to remove an attribute and all
+ its values from an entry.
+
+ RemoveAttributePrimitive ::= [APPLICATION 6] SEQUENCE {
+ csn lDAPChangeSequenceNumber,
+ type AttributeDescription
+ }
+
+ Parameters of the RemoveAttributePrimitive are:
+
+ - csn: The change sequence number of the primitive.
+
+ - type: The type of the attribute being removed.
+
+
+5.4 EndFramedProtocolRequest Extended Operation
+
+ The EndFramedProtocolRequest extended operation is sent from the
+ replication supplier to the replication consumer to indicate the end
+ of the sequence of replication updates. In the event that the
+ supplier is sending a total update, the requestValue field of the
+ EndFramedProtocolRequest extended operation contains a replica update
+ vector. The consumer server must replace its replica update vector,
+ if present, with the one provided by the supplier. In the event that
+ the supplier is sending an incremental update, the replica update
+ vector is absent.
+
+ The EndFramedProtocolRequest extended operation is defined in
+ [FRAMING]. When used to signal the termination of an LDUP incremental
+ or total update session, the requestValue field of the
+ EndFramedProtocolRequest is set to the following:
+
+ requestValue ::= SEQUENCE {
+ replicaUpdateVector Attribute OPTIONAL,
+ returnConsumerUpdateVector BOOLEAN
+ }
+
+ If returnConsumerUpdateVector is TRUE, the consumer server must
+ return its current update vector to the supplier in the response
+ field of the EndFramedProtocolResponse extended response (defined in
+ section 5.5). Typically, the supplier will request the consumer's
+ update vector for read-only replicas, since the read-only replica
+ will never initiate a replication session, and will therefore never
+ have the opportunity to provide its update vector to other servers.
+
+
+5.5 EndFramedProtocolResponse Extended Operation
+
+
+
+
+Stokes and Good [Page 11]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ The EndFramedProtocolResponse extended operation is defined in
+ [FRAMING]. It is used to respond to a EndFramedProtocolRequest. The
+ response field of the EndFramedProtocolResponse extended operation is
+ set to the following:
+
+ response ::= SEQUENCE {
+ replicaUpdateVector Attribute OPTIONAL
+ }
+
+ The replicaUpdateVector contains the consumer's current replica
+ update vector, and is optional. The consumer server should only send
+ the replicaUpdateVector if requested by the supplier server in the
+ EndReplicationRequest extended operation.
+
+5.6 ReplicationUpdateResponse Extended Operation
+
+The ReplicationUpdateResponse extended operation is sent, unsolicited,
+by a consumer to a supplier when the consumer wishes the supplier to
+stop sending updates.
+
+An LDAPv3 extended response is defined in [LDAPv3] as follows:
+
+ ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
+ COMPONENTS of LDAPResult,
+ responseName [10] LDAPOID OPTIONAL,
+ response [11] OCTET STRING OPTIONAL
+ }
+
+The responseName of the ReplicationUpdateResponse must be the OID [OID
+to be assigned].
+
+The response field of the ReplicationUpdateResponse must be set to the
+BER-encoding of the following:
+
+ response ::= SEQUENCE {
+ replicaUpdateVector Attribute OPTIONAL
+ abortUpdate BOOLEAN
+ }
+
+The parameters of the ReplicationUpdateResponse are:
+
+- An optional update vector. If sent, this indicates that the consumer
+has committed all updates whose CSNs are covered by the transmitted
+update vector [see glossary for a definition of "covered by"]. - An
+optional AbortUpdate boolean flag. If a supplier receives a
+ReplicationUpdateResponse from a consumer with the AbortUpdate flag set
+to true, the supplier server MUST immediately cease sending updates and
+terminate its connection to the consumer.
+
+
+
+Stokes and Good [Page 12]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+6. Semantics of Full and Incremental Update protocols
+
+[To be written]
+
+7. Summary of response codes
+
+The following list describes the response codes that may be included in
+the StartFramedProtocolResponse, EndFramedProtocolResponse, and
+ReplicationUpdateResponse extended operations.
+
+ LDUPResponseCode ::= SEQUENCE {
+ resultCode ENUMERATED {
+ success (0),
+ operationsError (1),
+ protocolError (2),
+ insufficientAccessRights (50),
+ busy (51),
+ excessiveCSNSkew (200),
+
+ other (80) },
+ errorMessage LDAPString }
+
+The meanings of the response codes are as follows:
+
+ success..................... As defined in [LDAPv3].
+ operationsError............. As defined in [LDAPv3].
+ protocolError............... As defined in [LDAPv3].
+ insufficientAccessRights.... Access denied. The identity that the
+ initiator provided in the bind request does
+ not have sufficient privileges to perform
+ the operation.
+ busy........................ The replica is temporarily unable to accept
+ updates.
+ excessiveCSNSkew............ The consumer server has detected that the
+ CSNs being generated by the supplier are
+ too small (perhaps because the supplier's
+ clock was set back). Updates from the
+ supplier will not be applied.
+ other....................... Some other error occurred.
+
+8. Implications for log-based and state-based servers
+
+To be written, or possibly incorporated into [ARCHITECTURE].
+
+9. Replication of access control and schema information
+
+To be written, or possibly incorporated into [ARCHITECTURE].
+
+
+
+
+Stokes and Good [Page 13]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+10. Security Considerations
+
+To be written.
+
+11. Glossary of Terms
+
+ Covered by: We say that a CSN is "covered by" an update vector if and
+ only if the CSN is less than or equal to the component of the update
+ vector corresponding to the replica ID in the CSN. In other words,
+ given a CSN with components <t,S,r,s> and an update vector with CSNs
+ <t0,S0,r0,s0>,<t1,S1,r1,s1>...<tn,Sn,Rn,sn>, then the CSN is covered
+ by the RUV if and only if one of the following holds for some value
+ i:
+ a) r = ri and t < ti
+ b) r = ri and t = ti and S < Si
+ c) r = ri and t = ti and S = Si and s < si
+
+
+12. Acknowledgments
+
+To be written.
+
+13. References
+
+
+[ARCHITECTURE]
+ J. Merrells, E. Reed, U. Srinivasan, "LDAP Replication Architec-
+ ture", Internet-Draft, draft-ietf-ldup-model-02.txt, October 1999.
+
+
+[FRAMING]
+ E. Stokes, G. Good, "Extended Operations for Framing LDAP Bulk
+ Update Operations", Internet-Draft, draft-ietf-ldup-framing-00.txt,
+ March 2000.
+
+
+[INFOMOD]
+ E. Reed, "LDAP Replication Information Model", Internet-Draft,
+ draft-reed-ldup-infomod-00.txt, June 1999.
+
+
+[KEYWORDS]
+ S. Bradner, "Key Words for use in RFCs to Indicate Requirement Lev-
+ els", Harvard University, RFC 2119, March 1997.
+
+
+[LDAPv3]
+ M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol
+
+
+
+Stokes and Good [Page 14]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+ (v3)", RFC 2251, December 1997.
+
+
+[REQ]R. Weiser, E. Stokes, "LDAP V3 Replication Requirements",
+ Internet-Draft, draft-ietf-ldup-replica-req-02.txt, October 1999.
+
+
+[URP]S. Legg, A. Payne, "LDUP Update Reconciliation Procedures",
+ Internet-Draft, draft-ietf-ldup-urp-02.txt, October 1999.
+
+14. Author's Addresses
+
+ Ellen Stokes
+ IBM
+ 11400 Burnet Rd
+ Austin, TX 78758
+ USA
+ EMail: stokes@austin.ibm.com
+ phone: +1 512 838 3725
+ fax: +1 512 838 0156
+
+ Gordon Good
+ Netscape Communications Corp.
+ 501 E. Middlefield Rd.
+ Mailstop MV068
+ Mountain View, CA 94043
+ USA
+ EMail: ggood@netscape.com
+ Phone: +1 650 937-3825
+
+ 15. Document Revision History
+ (This section will be removed prior to this document's publication
+ as a proposed standard)
+
+ Differences between draft-ietf-ldup-protocol-00.txt and
+ draft-ietf-ldup-protocol-01.txt:
+
+ 1) The document was reworked to use the ldup framed protocol
+ draft [FRAMING].
+
+
+Appendix A - Complete ASN.1 Definition
+
+To be written.
+
+Full Copyright Statement
+
+Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+
+
+Stokes and Good [Page 15]
+\f
+Internet-Draft LDUP Workgroup March 10 2000
+
+
+This document and translations of it may be copied and furnished to oth-
+ers, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and dis-
+tributed, 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 Stan-
+dards process must be followed, or as required to translate it into
+languages other than English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an "AS
+IS" basis and 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 FIT-
+NESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Stokes and Good [Page 16]
--- /dev/null
+ INTERNET-DRAFT Russel F. Weiser
+ Informational Draft Digital Signature Trust Co.
+ Expires 21 April 2000 Ellen Stokes
+ IBM
+ 21 October 1999
+
+
+
+
+
+ LDAP V3 Replication Requirements
+
+ <draft-ietf-ldup-replica-req-02.txt>
+
+
+
+ Status of this Memo
+
+
+
+ This document is am Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+
+ Internet-Drafts are draft documents valid for a maximum of six
+ months and may be updated, replaced, or obsoleted by other documents
+ at any time. It is inappropriate to use Internet-Drafts as
+ reference material or to cite them other than as ``work in
+ progress.''
+
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/lid-abstracts.txt
+
+
+ The list of Internet-Drafts Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+
+
+
+ Abstract
+
+
+ This document discusses the fundamental requirements for replication
+ of data accessible via the LDAPv3 [RFC2251] protocol. It is intended
+ to be a gathering place for general replication requirements needed
+ to provide interoperability between informational directories.
+
+
+ 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 [RFC2119].
+
+
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [PAGE 1]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+
+
+ Table of Contents
+
+
+ 1.Introduction.....................................................3
+ 2. Terminology.....................................................3
+ 3. Objective.......................................................5
+ 4. Applicability Statement.........................................5
+ 5. Replication Model..............................................10
+ 6. Replication Protocol...........................................12
+ 7. Schema.........................................................13
+ 8. Administration and Management Considerations...................13
+ 9. Acknowledgement................................................14
+ 10. References....................................................15
+ 11. Author's Address..............................................15
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 2]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+
+
+
+
+ 1. Introduction
+
+
+ The ability to distribute directory information throughout the
+ network provides a two fold benefit to the network: (1) increasing
+ the reliability of the directory through fault tolerance, and
+ (2) brings the directory content closer to the clients using the
+ data. LDAPÆs acceptance as an access protocol for directory
+ information is driving the need to distribute LDAP directory content
+ among servers within enterprise and Internet. Currently LDAP does
+ not define a replication mechanism and only generally mentions LDAP
+ shadow servers (see [RFC2251] and [Changelog]) in passing. The
+ requirements for replication are critical to the successful
+ deployment and acceptance of LDAP in the market place.
+
+
+
+ 2. Terminology
+
+
+ For the purposes of this document, the following terminology
+ definitions are used:
+
+
+ Area of replication - A whole or portion of a directory tree(DIT)
+ making up a distinct unit of data to be replicated. This may also be
+ known as "unit of replication".
+
+ Atomic operation - The ability to treat and contain several updates
+ or attribute changes as a single operation for replication purposes
+ to guarantee that the several updates or attribute changes are
+ propagated to a replica as a single unit.
+
+ Authoritative Master Replica - The Primary updateable replica of the
+ replicated information.
+
+
+ Conflict resolution - Deterministic procedures within replication
+ protocols, utilized to resolve change information conflicts that may
+ arise due to conflicting changes affecting a directory entry.
+
+
+ Fractional replication - The capability to replicate a subset of
+ attributes of any given entry.
+
+ Incremental Update - The process of updating a replica, or copy, of
+ a naming context, by updating only those fields or objects which
+ have changed.
+
+
+ Master Slave, or Single Master Replication - Replication model that
+ assumes only one server, the master, allows write access to the
+ replicated data. Note that Master-Slave replication can be
+ considered a proper subset of multi-master replication.
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 3]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+
+
+ Multi-Master Replication - A replication model where entries can be
+ written and updated on any of several updateable replica copies
+ without requiring communication with other updateable replicas
+ before the write or update is performed.
+
+
+ Naming Context - Suffix of a Sub-tree. A sub-tree of entries held in
+ a single server [X.500].
+
+
+ One-way Replication - The process of synchronization in a single
+ direction where the authoritative source information is provided to
+ a replica.
+
+
+ Partial Replication - The capability to replicate some subset of
+ entries in a naming context.
+
+
+ Propagation behavior - The general behavior of the actual
+ synchronization process between a consumer and a provider of
+ replication information.
+
+ Read-only Replica - A read-only copy of a replicated directory. A
+ read-only replica is assumed to be a slave replica of master slave
+ or single master replication definition.
+
+
+ Replica - A single instance of a whole or portion of the Directory
+ tree (DIT) as defined by area of replication.
+
+
+ Replica Ring - A set of servers, which hold in common the same DIT
+ information as, defined by ôArea of replicationö. These servers may
+ be managed under a single replication agreement that handles all
+ members of the set of servers as a group.
+
+
+ Replica Cycle - When a change or groups of changes need to be
+ propagated to the other member of a replica ring. The process of
+ contacting a replica member would be considered the beginning of a
+ replication cycle; the termination of communications with a replica
+ is the end of the cycle whether its due to an error or successful
+ exchange of update records.
+
+
+ Replication - The process of copying portions of naming context
+ information and content between multiple LDAP servers, such that
+ certain predefined portions of the information are available from
+ different servers. Replication can occur between either homogeneous
+ implementations across heterogeneous platforms (operating systems)
+ or heterogeneous implementations supporting identical replication
+ across heterogeneous platforms (operating systems).
+
+
+ Sparse Replica - A incomplete copy of a sub-tree which maybe
+ inclusive with updateable, or Read-only. See Partial replication and
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 4]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ Fractional replication.
+
+
+ Topology - Refers to the shape of the directed graph describing the
+ relationships between replicas, as in the replicated directory
+ topology.
+
+
+ Two-way Replication - The process of synchronization where change
+ information may flow bi-directionally between two replica.
+
+ Update Propagation - Protocol-based process by which directory
+ replicas are reconciled.
+
+
+ Updateable Replica - A Non-authoritative read-writeable copy of the
+ replicated information. Such that during conflict resolution a
+ authoritative master takes precedents in resolving conflicts.
+
+
+
+ 3. Objective
+
+
+ The major objective is to provide an interoperable LDAP V3 directory
+ synchronization protocol which is simple, highly efficient and
+ flexible enough to support both multi-master and master-slave
+ replication operations to meet the needs of both the internet and
+ enterprise environments.
+
+
+ 4. Applicability Statement
+
+
+ Generally replication can be characterized by looking at data
+ consistency models across existing technologies. This may provide
+ insight to LDAP v3 replication requirements. The following is a
+ brief examination of the following data models.
+
+
+ Model 1: Tight Consistency -- Includes environments where all
+ replicas must always contain exactly the same directory content. Two
+ phase commit transaction models may be used to preserve transaction
+ consistency.
+
+
+ Model 2: Eventual Consistency or Transient Consistency -- Includes
+ X.500 Directories, Bayou [XEROX], and NDS (Novell Directory
+ Services) names service where definite knowledge of the global
+ replica topology is provided through predetermined replication
+ agreements. Such that every update propagates to every replica that
+ it can reach via a path of stepwise eventual connectivity.
+ Transaction consistency is preserved for transactions directed at
+ the master server in X.500 implementations. NDS additionally
+ provides deterministic consistency over time to all replicas due to
+ its inherent replication policies.
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 5]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ Model 3: Limited Effort Eventual Consistency -- Includes Xerox
+ Clearinghouse [XEROX] that provides a statistical probability of
+ convergence with global knowledge of replica topology. Similar to
+ "Eventual Consistency", except where replicas may purge updates
+ therefore dropping propagation changes when some replica time
+ boundary is exceeded, thus leaving some changes replicated to a
+ portion of the replica topology. Transactional consistency is not
+ preserved, though some weaker constraints on consistency are
+ available.
+
+ Model 4: Loosest Consistency -- Includes opportunistic or simple
+ cache where information is provided from the cache until stale.
+
+
+ Model 5: Ad hoc -- A copy of a date store where no follow up checks
+ are made for the accuracy/freshness of the data.
+
+
+ Consistency models 2, and 3 involve the use of prearranged
+ replication agreements or "Predefined Replication Agreements"
+ between cooperating servers. The complexity of Model 1's use of 2-
+ phase commit adds additional overhead that should not considered at
+ this time. Models 4 and 5 involve unregistered replicas which
+ "pull" updates from another directory server without that server's
+ knowledge. These models can be considered to violate a directory's
+ security policies. Therefore models 1, 4, and 5 are declared to be
+ out of scope of this working group.
+
+
+ So through further review of these consistency models two
+ application areas can then be derived with even further
+ characterizations of the data types usages.
+
+ Eventual Consistency or Transient Consistency (Model 2) - This model
+ provides policy configuration through security management
+ parameters; the data is more dynamic and utilizes dynamic address
+ information.
+
+ Limited Effort Eventual Consistency (Model 3) - This model matches a
+ white-pages environment which contains fairly static data and
+ address information. This model mainly replicates message
+ attributes.
+
+ Therefore it is believed an LDAP replication should be flexible
+ enough to cover the above range of capabilities. The generalized use
+ of LDUP replication environment is to provide for the distribution
+ of LDAP directory information in order to improve accessibility and
+ consistency of the information held by the directory.
+
+
+
+ 4.1 Replication Scenarios
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 6]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ The following directory deployment examples are intended to
+ substantiate and validate our replication requirements. It is
+ assumed in all cases that directory implementations from different
+ vendors are involved.
+
+ 4.1.1 Extranet Example
+
+
+ A company has a trading partner to whom it wishes to provide
+ directory information. This information may be as simple as a
+ corporate telephone directory, or as complex as an extranet work
+ flow application. For performance reasons the company may wish to
+ have a replica of its directory within the Partner Company, rather
+ than simply exposed beyond its firewall.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - One-way replication, single mastered.
+ - Authentication of clients.
+ - Common access control and access control identification.
+ - Secure transmission of updates.
+ - Selective attribute replication (Fractional Replication), so that
+ only partial entries can be replicated.
+
+
+
+ 4.1.2 Consolidation Example
+
+
+ Company A acquires company B. In the transition period, whilst the
+ organizations are merged, both directory services must coexist.
+ Company A may wish to attach company B's directory to its own.
+
+ The requirements, which follow from this scenario, are:
+
+ - Multi-Master replication.
+ - Common access control model. Access control model identification.
+ - Secure transmission of updates.
+ - Replication between DITs with potentially differing schema.
+
+
+ 4.1.3 Replication Heterogeneous Deployment Example
+
+ An organization may deliberately deploy multiple directory services
+ within their enterprise to employ the differing benefits of each
+ service. In this case multi-master replication will be required to
+ ensure that the multiple updateable replicas of the DIT are
+ synchronized. Some vendors may provide directory clients, which are
+ tied to their own directory service.
+
+
+ The requirements, which follow from this scenario, are:
+
+
+ - Multi-Master replication
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 7]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ - Common access control model and Access control model
+ identification.
+ - Secure transmission of updates.
+ - Replication between DITs with potentially differing schemas.
+
+ 4.1.4 Shared Name Space Example
+
+
+ Two organizations may choose to cooperate on some venture and need a
+ shared name space to manage their operation. Both organizations
+ will require administrative rights over the shared name space.
+
+ The requirements, which follow from this scenario, are:
+
+ - Multi-Master replication.
+ - Common access control model and Access control model
+ identification.
+ - Secure transmission of updates.
+
+ 4.1.5 Supplier Initiated Replication
+
+ A single master environment, which maintains a number of replicas of
+ the DIT by pushing changes, based on a defined schedule.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Single-master environment.
+ - Supplier-initiated replication.
+ - Secure transmission of updates.
+
+
+ 4.1.6 Consumer Initiated Replication
+
+
+ Again a single mastered replication topology, but the replica
+ initiates the replication exchange rather than the master. An
+ example of this is a replica that resides on a laptop computer that
+ may run disconnected for a period of time.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Single-master environment.
+ - Consumer initiated replication.
+ - Open scheduling (anytime).
+
+ 4.1.7 Prioritized attribute replication
+
+
+ The password attribute can provide an example of the requirement for
+ prioritized attribute replication. A user is working in Utah and the
+ administrator resides in California. The user has forgotten his
+ password. So the user calls or emails the administrator to request a
+ new password. The administrator provides the updated password (a
+ change). Policy states that this attribute is critical and must be
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 8]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ available to the user for login immediately (e.g. shortly) after the
+ administrator changed it. Replication needs to occur immediately for
+ critical attributes/objects.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Incremental replication of changes.
+ - Automatic replication on change of certain attributes.
+ - Replicate based on time/attribute semantics.
+
+ 4.1.8 Bandwidth issues
+
+
+ The replication of Server (A) R/W replica (a) in Katmandu is handled
+ via a dial up phone link to Paris where server (B) R/W replica of
+ (a) resides. Server (C) R/W replica of(a) is connected by a T1
+ connection to server (B). Each connection has a different
+ performance characteristic.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Minimize repetitive updates when replicating from multiple
+ replication paths.
+ - Incremental replication of changes.
+ - Provide replication cycles to delay and/or retry when connections
+ can not be reached.
+ - Allowances for consumer initiated or supplier initiated
+ replication.
+
+
+ 4.1.9 Interoperable Administration and Management
+
+ The administrator with administrative authority of the corporate
+ directory which is replicated by numerous geographically dispersed
+ LDAP servers from different vendors notices that the replication
+ process is not completing correctly as the change log is continuing
+ to grow and/or error message informs him. The administrator uses his
+ $19.95 RepCo LDAP directory replication diagnostics tools to look at
+ Root DSE replica knowledge on server 17 and determines that server
+ 42 made by LDAPÆRUS Inc. is not replicating properly due to an
+ Object conflict. Using his Repco Remote repair tools he connects to
+ server 42 and resolves the conflict on the remote server.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Provides replication audit history.
+ - Provisions for managing conflict resolution.
+ - Provide LDAP access to predetermined agreements, topology and
+ policy attributes.
+ - Provide operations for comparing replicaÆs content for validity.
+ - Provide LDAP access to status and audit information.
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 9]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ 4.1.10 Enterprise Directory Replication Mesh
+
+
+ A Corporation builds a mesh of directory servers within the
+ enterprise utilizing LDAP servers from various vendors. Five servers
+ are holding the same area of replication. The predetermined
+ replication agreement(s) for the enterprise mesh are under a single
+ management, and the security domain allows a single predetermined
+ replication agreement to manage the 5 servers replication.
+
+
+ The requirements, which follow from this scenario, are:
+
+ - Predefined replication agreements that manage more than a single
+ area of replication that is held on numerous servers.
+ - Common support of replication management knowledge across vendor
+ implementation.
+ - Rescheduling and continuation of a replication cycle when one
+ server in a replica ring is busy and/or unavailable.
+
+ 5. Replication Model
+
+
+ 5.1 LDAP Replication MUST be allowed to span different vendors
+ directory services in order to provide interoperability.
+
+ 5.2 All replicas MUST eventually be updated with the changed
+ information, if specified by the replication policy.
+
+
+ 5.3 Replication schedules MUST be configurable to allow for
+ periodic replication, with the replication period determined by
+ administrator of the replicated system.
+
+
+ 5.4 Replication Model MUST enable replication cycle to be initiated
+ on change or based on the number of pending changes.
+
+ 5.5 The replication model MUST allow for administrative
+ initiation of replication cycle for any replica that may have
+ just come back online or was unavailable during previous
+ replication cycles.
+
+ 5.6 The replication model MUST support both master-slave and
+ authoritative multi-updateable replica relationships.
+
+
+ 5.7 All replicated information between the master database and its
+ replica databases MUST be identical including all non-user
+ modify operational attributes such as time stamps. Note this
+ does not imply that the entire database is identical from
+ replica to replica, but that the subset of data, chosen to
+ replicate is identical from replica to replica. Some
+ operational attributes may be dynamically evaluated; these
+ attributes will not necessarily appear to be identical.
+
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 10]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ 5.8 In distributed multi-vendor environment, LDAP replication MUST
+ NOT require all copies of the replicated information be
+ complete copies of the replicated object.
+
+
+ 5.9 LDAP replication MUST encompass common schema objects and
+ attributes, access control, and name space information.
+
+
+ 5.10 Sub-tree Replication MUST be defined to allow for greater
+ flexibility in replication topologies of the DIT as defined by
+ the area of replication called partial replication.
+
+
+ 5.11 Replication of critical values MUST be synchronized and have
+ priority over non-critical values. An example of a critical
+ value might be a password or certificate value.
+
+ 5.12 Replication activities MUST occur within the context of a
+ predefined replication agreement that addresses proper
+ knowledge of access requirements and credentials between the
+ synchronizing directories. Currently X.525 DISP [X.525]
+ discusses this as a shadowing agreement including such
+ information as unit of replication, update mode, and access
+ point defining many of the policies between the master and a
+ replica.
+
+
+ 5.13 The acceptance and usage of the Internet requires that LDAP
+ replication be available across disparate vendor directory
+ services.
+
+
+ 5.14 LDAP replication MUST provide scalability to both enterprise
+ and Internet environments, e.g. an LDAP server may provide
+ replication services to replicas within an enterprise as well
+ as across the Internet.
+
+
+ 5.15 The replication model MUST define deterministic policy such
+ that replication cycle startup time conflicts between two or
+ more competing master replicas may be resolved
+ programmatically. An example might be automatic submission and
+ rescheduling by one of the masters. In such a case, these
+ replication "conflicts" MUST be resolved by the replication
+ policy.
+
+
+ 5.16 Any replication capable LDAP server MUST allow replication
+ where the 2 replicating servers agree they can replicate. This
+ may be accomplished through administrative agreements assuming
+ compatible access control model and common schema are provided.
+
+
+ 5.17 The replication model MUST be able to handle convergence and
+ resurrection of attributes and objects. This is a consequence
+ of delete and move with respect to the replication process.
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 11]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ 5.18 It is not realistic to assume that all vendors have cooperating
+ schemas, but that replication may be allowed between diverse
+ schema. The Model MAY allow for replication between divergent
+ schema of objects.
+
+
+ 6. Replication Protocol
+
+
+ 6.1 The act of replication SHOULD have minimal impact on both the
+ system and network performance.
+
+ 6.2 The replica synchronization SHOULD be handled in such a manner
+ as to not saturate network with repetitive entry replication
+ from multiple synchronization providers points.
+
+
+ 6.3 Replication MUST only be allowed after the authentication and
+ verification of authorization of both the replica and the
+ source directory.
+
+
+ 6.4 The transport for LDAP synchronization MUST allow for the
+ integrity and confidentiality of each replicated server.
+
+
+ 6.5 Replicated data MUST be transferable in a secure manner.
+
+
+ 6.6 Replication protocol MUST provide for recovery and rescheduling
+ of a replication cycle due to a replication initiation
+ conflicts (e.g. consumer busy replicating with other servers)
+ and or loss of connection(e.g. supplier cannot reach a
+ replica). The replication protocol MUST include restarting at
+ the last acknowledged update prior to interruption rather than
+ re-sending updates it had already sent to a consuming replica.
+
+
+ 6.7 LDAP replication MUST allow for full update to facilitate
+ replica initialization and reset loading utilizing a
+ standardized format such as LDIF [LDIF] format.
+
+ 6.8 The replication standard SHOULD NOT limit the size of a
+ replica. The area of replication is defined to be a whole or
+ portion of a DIT, also allowing a portion of a naming context
+ to be replicated. Incremental replication SHOULD be allowed.
+
+ 6.9 The replication agreements MUST accommodate multiple servers
+ receiving the same replica under a single predefined agreement.
+
+
+ 6.10 The replication protocol MUST allow either a master or replica
+ to initiate the replication process.
+
+
+ 6.11 Additionally the initiator MUST be allowed to determine
+ whether it will become a consumer or supplier during the
+ synchronization startup process. This would allow a replica to
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 12]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ be periodically connected and synchronized from remote sites at
+ the local administrator's discretion.
+
+
+ 6.12 Multiple LDAP changes to a single server: If transactional
+ consistency is propagated during replication, then multiple LDAP
+ changes submitted to a single server SHOULD BE treated as a
+ single 'atomic unit of work'.
+
+
+ 6.13 An LDAP Replication Standard SHOULD NOT limit the transaction
+ rate of a replication session.
+
+
+ 6.14 Entry change information MUST be purged or discarded in a
+ timely manner when change information becomes outdated due to
+ propagated to all replica members.
+
+
+
+
+ 7. Schema
+
+
+ 7.1 Replica knowledge MUST be provided as DSE attributes.
+
+ 7.2 The Replication Protocol documents MUST define standard schema
+ for representing replication agreements, and MUST define the
+ semantics associated with modifying the attributes of
+ replication agreements. The documents MUST also define a
+ standard method for determining the location of these
+ agreements accessible utilizing LDAP.
+
+
+ 7.3 The Replication Protocol documents MUST define standard schema
+ for publishing state information about a given replica, and
+ MUST define a standard method for determining the location of
+ this information.
+
+
+ 7.4 A location independent management point MUST be defined to
+ provide authorized administrators with well known access to the
+ replication policies, regardless of network location.
+
+
+ 7.5 Replication agreements of all servers containing replicated
+ information MUST be accessible via LDAP.
+
+
+ 7.6 All objects MUST be uniquely identifiable throughout the object
+ lifetime .
+
+
+
+
+ 8. Administration and Management Considerations
+
+
+
+ 8.1 Replication policies MUST allow replication of changed
+ information to be administratively postponed to a more
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 13]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ convenient period.
+
+
+ 8.2 Allowance for non-scheduled replication of a replica MUST be
+ provided upon request such that the replica server has been
+ down or unconnected for a period of time.
+
+
+ 8.3 Each copy of a replica MUST maintain audit history information
+ of which servers it has replicated with and which servers have
+ replicated with it.
+
+ 8.4 A replica MUST store conflicted versions of the replicated
+ object to allow optional human review and intervention.
+
+
+ 8.5 Access to replication predetermined agreements, topologies, and
+ policies attributes MUST be provided through LDAP access.
+
+
+ 8.6 The capability to check the differences between two replicas
+ for the same information SHOULD be provided for. This should
+ entail a client invoking an operation at some server, which
+ causes that server to extract the contents from some other
+ server it has a replication agreement with and report the
+ differences back to the client as the result.
+
+
+ 8.7 Authenticated access SHOULD be provided so that Administrative
+ LDAP clients may query a server for the current state and
+ replication history for each replica that the server maintains
+ replication agreements with.
+
+
+ 8.8 The ability to view replication conflicts, and override the
+ resolution derived by the replication policy MUST be provided.
+
+
+ 8.9 The deletion of sensitive data MUST be handled in an orderly
+ manner so that at no time will that data be available without
+ proper access control. That is, access control information
+ (ACI) associated with sensitive data must be deleted after or
+ simultaneously with the delete of the sensitive data. Likewise,
+ when adding sensitive data, ACI MUST be added first or
+ simultaneously with the addition of that data.
+
+
+
+
+ 9. Acknowledgement
+
+
+ This document is based on input from IETF members interested in LDUP
+ Replication.
+
+
+
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 14]\f
+
+
+ INTERNET-DRAFT LDAP Replication Requirements 21 October 1999
+
+
+
+
+
+ 10. References
+
+
+
+ [RFC2251] M. Wahl, T. Howes, S. Kille "Lightweight Directory Access
+ Protocal", RFC 2251.
+
+
+ [RFC2119] S.Bradner, " Key words for use in RFCs to indicate
+ Requirement Levels", RFC 2119.
+
+
+ [LDIF] Gordon Good, "The LDAP Data Interchange Format (LDIF)",
+ Internet draft, draft-ietf-asid-ldif-00.txt, November 1996.
+
+
+ [Changelog] Gordon Good, "Definitions of an Object Class to Hold
+ LDAP Change records", Internet Draft, draft-ietf-asid-changelog-
+ 00.txt, November 1996.
+
+
+ [X.501] ITU-T Recommendation X.501 (1993), | ISO/IEC 9594-2: 1993,
+ Information Technology - Open Systems Interconnection - The
+ Directory: Models
+
+ [XEROX] Hauser, C. "Managing update conflicts in Bayou, a weakly
+ connected replicated storage system". Palo Alto, CA: Xerox PARC,
+ Computer Science Laboratory; 1995 August; CSL-95-4. [CSL-95-04]
+
+
+
+ 11. Author's Address
+
+
+ Russel F. Weiser
+ Digital Signature Trust Co.
+ One South Main Street
+ Salt Lake City, Utah 84111
+ USA
+
+
+ E-mail: rweiser@digsigtrust.com
+ Telephone: +1-801-983-4415
+ Fax +1-801-983-4408
+
+
+
+ Ellen J. Stokes
+ IBM
+ 11400 Burnet Rd.
+ Austin, Texas 78758
+ USA
+
+ E-mail: stokes@austin.ibm.com
+ Telephone: +1-512-838-3725
+ Fax: +1-512-838-0156
+
+
+
+
+
+ Weiser & Stokes 21 April 2000 [Page 15]\f
--- /dev/null
+INTERNET-DRAFT S. Legg
+draft-ietf-ldup-urp-02.txt Telstra
+ A. Payne
+ PricewaterhouseCoopers
+ October 22, 1999
+
+
+ LDUP Update Reconciliation Procedures
+
+ Copyright (C) The Internet Society (1999). All Rights Reserved.
+
+ Status of this Memo
+
+
+ This document is an Internet-Draft and is in full conformance with
+ all provisions of Section 10 of RFC2026.
+
+ Internet-Drafts are working documents of the Internet Engineering
+ Task Force (IETF), its areas, and its working groups. Note that
+ other groups may also distribute working documents as Internet-
+ Drafts.
+
+ Internet-Drafts are draft documents valid for a maximum of six months
+ and may be updated, replaced, or obsoleted by other documents at any
+ time. It is inappropriate to use Internet-Drafts as reference
+ material or to cite them other than as "work in progress".
+
+ The list of current Internet-Drafts can be accessed at
+ http://www.ietf.org/ietf/1id-abstracts.txt
+
+ The list of Internet-Draft Shadow Directories can be accessed at
+ http://www.ietf.org/shadow.html.
+
+ This draft is published by the IETF LDUP Working Group. Distribution
+ of this document is unlimited. Comments should be sent to the LDUP
+ Replication mailing list <ldup@imc.org> or to the authors.
+
+ This Internet-Draft expires on 22 April 2000.
+
+ 1. Abstract
+
+ This document describes the procedures used by directory servers to
+ reconcile updates performed by autonomously operating directory
+ servers in a distributed, replicated directory service.
+
+
+
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 1]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ 2. Table of Contents
+
+ 1. Abstract 1
+ 2. Table of Contents 2
+ 3. Introduction 2
+ 4. Model Extensions 3
+ 4.1 Unique Identifier 3
+ 4.2 Timestamps & Existence 3
+ 4.3 Replication Primitives 4
+ 4.4 Lost & Found 5
+ 5. Replication Procedures 6
+ 5.1 Processing LDAP, DAP or DSP Operations on the DIT 6
+ 5.1.1 Add Entry 7
+ 5.1.2 Remove Entry 7
+ 5.1.3 Modify Entry 7
+ 5.1.4 Modify DN 9
+ 5.2 Generating Replication Primitives 9
+ 5.3 Processing Replication Primitives on the DIT 11
+ 5.3.1 Saving Deletion Records 12
+ 5.3.2 Glue Entries 13
+ 5.3.3 Generating Change Sequence Numbers 13
+ 5.3.4 Comparison of Attribute Values 14
+ 5.3.5 Entry Naming 14
+ 5.3.6 Processing Add Attribute Value Primitive 17
+ 5.3.7 Processing Remove Attribute Value Primitive 17
+ 5.3.8 Processing Remove Attribute Primitive 19
+ 5.3.9 Processing Add Entry Primitive 19
+ 5.3.10 Processing Remove Entry Primitive 20
+ 5.3.11 Processing Move Entry Primitive 21
+ 5.3.12 Processing Rename Entry Primitive 22
+ 6. Security Considerations 23
+ 7. Acknowledgements 23
+ 8. References 23
+ 9. Intellectual Property Notice 23
+ 10. Copyright Notice 24
+ 11. Authors' Address 25
+ 12. Appendix A - Changes From Previous Drafts 25
+ 12.1 Changes in Draft 01 25
+ 12.2 Changes in Draft 02 26
+ 13. Appendix B - Open Issues 26
+
+
+ 3. Introduction
+
+ Each DAP, LDAP or DSP operation successfully performed by a DSA is
+ subsequently reported to other DSAs with which it has a replication
+ agreement as a set of one or more simple timestamped replication
+ primitives. These primitives reflect the intended final state of an
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 2]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ update operation rather than the specific changes required to achieve
+ that state.
+
+ A DSA will receive replication primitives from its various agreement
+ partners according to the agreement schedules. Those primitives must
+ be reconciled with the current DSA contents. In broad outline,
+ received replication primitives are compared to the timestamp
+ information associated with the directory data item being operated
+ on. If the primitive has a more recent timestamp a change in the
+ directory contents is made (which may involve only the revision of
+ the timestamp). If the DSA has other replication agreements then the
+ change will be reflected in primitives sent during replication
+ sessions for those other agreements. If the primitive has an older
+ timestamp it is no longer relevant and is simply ignored.
+
+ The update reconciliation procedures are designed to produce a
+ consistent outcome at all participating DSAs regardless of the order
+ in which the primitives are received. The primitives can also be
+ safely replayed in the event that an exchange of replication
+ information with another DSA is interrupted. This greatly simplifies
+ the recovery mechanisms required in the replication protocol.
+
+ 4. Model Extensions
+
+ This section describes the extensions to the data model required to
+ effect multiple master replication.
+
+ 4.1 Unique Identifier
+
+ A Unique Identifier is associated with each entry in the global DIT.
+ This Unique Identifier must be globally unique for all time in the
+ Directory. This can be achieved by defining a unique DSA prefix for
+ each DSA and then ensuring that the suffix of the Unique Identifier
+ is locally unique.
+
+ Some pre-allocated global Unique Identifier values will be used to
+ indicate the X.500 global root entry, and the Lost & Found entry (see
+ Section 4.4).
+
+ 4.2 Timestamps & Existence
+
+ The timestamp for a replication primitive or directory data item is
+ in the form of a Change Sequence Number (CSN). The components of the
+ CSN are, from most significant to least significant, a time in
+ seconds, a change count, a Replica Identifier and a modification
+ number. Notionally a CSN is associated with an entry's Relative
+ Distinguished Name (the Name CSN), the reference to its superior
+ entry (the Parent CSN) and each of its attribute values (including
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 3]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ the distinguished values), to record the time of the most recent
+ action on that part of the entry.
+
+ The entry itself has a CSN (the Entry CSN) asserting the most recent
+ time at which the entry was added. An entry is permitted to be
+ removed and then re-added at one or more DSAs. In this context re-
+ adding an entry means reusing the Unique Identifier of a removed
+ entry and does not refer to the case of reusing the RDN of a removed
+ entry. The reuse of a Unique Identifier can arise by the explicit
+ action of a directory administrator to restore an entry that was
+ mistakenly removed. The mechanism by which an administrator adds an
+ entry with a reused Unique Identifier is outside the scope of the
+ X.500 and LDAP standards since the Unique Identifier of an entry is
+ not a user modifiable attribute. Note that from the perspective of a
+ consumer DSA of a partial area of replication an entry may appear to
+ be removed and added several times because modifications to the entry
+ change whether the entry satisfies the replication agreement
+ specification for the area of replication.
+
+ Additionally, a deletion record is kept for each of the recently
+ deleted entries, attributes, or attribute values. The deletion record
+ contains a CSN and asserts that the associated directory object no
+ longer existed at the particular time.
+
+ 4.3 Replication Primitives
+
+ Each update operation performed on an entry in a part of the DIT
+ subject to one or more replication agreements must be subsequently
+ reported as replication primitives to the replication partner DSAs of
+ those agreements. The collection of primitives sent by a DSA to a
+ replication partner may reflect both the results of locally processed
+ user update requests and also of replicated updates received from
+ other DSAs. A single update operation will decompose in one or more
+ primitives.
+
+ Common to all update primitives is an entry identifier argument, uid,
+ containing the Unique Identifier of the target entry of the change,
+ and a CSN argument, csn, to indicate the time of the change. In the
+ case of adding a new entry, the Unique Identifier for the entry is
+ allocated by the DSA in the course of processing the operation.
+ Additional arguments are present depending on the type of replication
+ primitive.
+
+ The p-add-entry(uid, csn, superior, rdn) primitive is used to add a
+ new entry with minimal contents. The superior argument contains the
+ Unique Identifier of the immediate superior entry of the added entry.
+ The rdn argument contains the Relative Distinguished Name of the
+ added entry.
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 4]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ The p-move-entry(uid, csn, superior) primitive is used to change the
+ immediate superior of an entry. The superior argument contains the
+ Unique Identifier of the new superior entry.
+
+ The p-rename-entry(uid, csn, rdn) primitive is used to change the
+ Relative Distinguished Name of an entry. The rdn argument contains
+ the new RDN for the entry.
+
+ The p-remove-entry(uid, csn) primitive is used to remove an entry.
+
+ The p-add-attribute-value(uid, csn, type, value) primitive is used to
+ add a single attribute value to an entry. The type argument contains
+ the attribute type of the value and the value argument contains the
+ attribute value.
+
+ The p-remove-attribute-value(uid, csn, type, value) primitive is used
+ to remove a single attribute value from an entry. The type argument
+ contains the attribute type of the value and the value argument
+ contains the attribute value.
+
+ The p-remove-attribute(uid, csn, type) primitive is used to remove
+ all values of an attribute from an entry. The type argument contains
+ the attribute type to be removed.
+
+ These primitives reflect the intended final state of an update
+ operation rather than the specific changes required to achieve that
+ state.
+
+ 4.4 Lost & Found
+
+ Each connected set of mastering DSAs have a Lost & Found entry
+ nominated. As a result of conflicting updates at two or more master
+ DSAs, an entry may be left with a reference to a non-existent
+ superior entry. Such an entry is called an orphaned entry. When this
+ situation arises, the DSA creates a glue entry for the missing
+ superior entry. This glue entry is made a subordinate of the Lost &
+ Found entry and the orphaned entry becomes a subordinate of the glue
+ superior entry (see Section 5.3.2). Entries that exist in the Lost &
+ Found subtree may still be modified by actions of the replication
+ protocol since entries are identified by Unique Identifiers in the
+ protocol, independent of their positioning in the global DIT.
+
+ Entries will also be explicitly moved to become immediate
+ subordinates of the Lost & Found entry to prevent the formation of a
+ loop in the superior-subordinate relationships in the DIT. This
+ situation can only arise through conflicting move entry operations at
+ two or more master DSAs.
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 5]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ Entries that exist under the Lost & Found entry may be returned to a
+ suitable position in the DIT by an administrator or user with
+ appropriate access rights.
+
+ 5. Replication Procedures
+
+ The procedures defined in this section ensure the consistent and
+ correct application of the results of DAP, LDAP or DSP operations
+ across all multi-master replication DSAs.
+
+ 5.1 Processing LDAP, DAP or DSP Operations on the DIT
+
+ A successful DAP, LDAP or DSP operation applied to a part of the DIT
+ subject to a replication agreement will create or replace one or more
+ CSNs on an entry or its contents, and create zero, one or more
+ deletion records referencing the entry or its contents. The CSNs and
+ deletion records generated from an operation are atomic with that
+ operation. That is, either the operation succeeds, the CSNS are
+ revised and the deletion records are stored, or the operation fails,
+ no CSNs are revised and no deletion records are stored. In all
+ cases, all current error conditions (i.e. reasons for rejecting an
+ LDAP, DAP or DSP update operation) remain.
+
+ At some later time, possibly immediately following the update or
+ concurrently with it, the CSNs on entry contents and deletion records
+ are used to generate the replication primitives that will report the
+ update to other DSAs via a replication session.
+
+ All the CSNs generated from a single update operation must use the
+ same time, change count and Replica Identifier. The modification
+ number is permitted to vary but must be assigned such that when the
+ CSNs resulting from the operation, including those in the deletion
+ records, are compared to the CSNs resulting from any other operation
+ they are all strictly greater than or all strictly less than those
+ other CSNs (i.e. in a global CSN ordering of the primitives
+ resulting from all operations the primitives of each operation must
+ be contiguous in that ordering). In order for the update to be
+ consistently applied when replicated to other DSAs the CSNs generated
+ during that update must generally be greater than any pre-existing
+ CSNs on the updated entry's contents. It is expected that DSAs will
+ normally use the current time according to their system clocks in
+ generating the CSNs for an operation. However in an environment where
+ DSA clocks are not necessarily synchronized the current time may be
+ older than existing CSNs on entry contents. The constraints the new
+ CSNs must satisfy with respect to pre-existing CSNs on entry data are
+ covered in the sections on each type of update operation. The current
+ LDUP architecture draft [LDUP Model] requires client update
+ operations to be rejected if the current time does not satisfy the
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 6]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ constraints on the generation of the CSNs. As written, URP allows a
+ DSA to generate CSNs in advance of its current time to satisfy the
+ constraints and proceed with the update.
+
+ The LDUP Update Vector mechanism imposes the additional constraint
+ that the CSN generated for an update operation must also be greater
+ than the highest CSN generated by the DSA that has already been seen
+ by any other DSA. An implementation that generates successively
+ greater CSNs for each operation will satisfy this constraint.
+
+ The following sections describe the additional actions to support
+ replication carried out in processing each particular type of update
+ operation.
+
+ 5.1.1 Add Entry
+
+ The LDAP Add operation or DAP addEntry operation is used to add a
+ leaf entry to the DIT. A successful request will generate a CSN for
+ the entry. The CSN on the entry's RDN, the CSN on the entry's
+ superior reference, and the CSN on each distinguished and non-
+ distinguished value added to the entry by the add entry operation are
+ set to this same value. The affected values include any operational
+ attributes automatically generated by the DSA.
+
+ The Unique Identifier generated for an entry created by a user
+ request is required to be globally unique for all time, so there
+ cannot be a pre-existing entry deletion record for the same Unique
+ Identifier. However it is recognized that, in practice, Directory
+ administrators may need to restore a deleted entry using its original
+ Unique Identifier (the mechanism used to achieve this is undefined
+ and outside the scope of this specification). In this case the CSN
+ for the entry must be generated such that it is greater than or equal
+ to the CSN of any existing entry, attribute or value deletion records
+ and greater than any of the CSNs contained in an existing glue entry,
+ for the same Unique Identifier.
+
+ 5.1.2 Remove Entry
+
+ The LDAP Delete operation or DAP removeEntry operation is used to
+ remove a leaf entry from the DIT. If the request succeeds then an
+ entry deletion record is stored containing the Unique Identifier of
+ the removed entry. The CSN for the entry deletion record must be
+ generated such that it is greater than the entry CSN of the removed
+ entry.
+
+ 5.1.3 Modify Entry
+
+ The LDAP Modify operation (ModifyRequest) or DAP modifyEntry
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 7]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ operation is used to perform a series of one or more modifications to
+ an entry. If the request succeeds then zero, one or more new values
+ with CSNs are added to the entry contents, and zero, one or more
+ value or attribute deletion records are stored.
+
+ The modifications described by the modification argument of the LDAP
+ ModifyRequest have the following additional effects:
+
+ a) The add alternative associates a CSN with each of the added
+ attribute values.
+
+ b) The delete alternative with no listed values generates an
+ attribute deletion record for the removed attribute type.
+
+ c) The delete alternative with listed values generates a value
+ deletion record for each of the removed values.
+
+ d) The replace alternative first generates an attribute deletion
+ record for the removed attribute type. A CSN is then associated
+ with each of the added values.
+
+ The modifications described by the changes argument of the X.500
+ modifyEntry operation have the following additional effects:
+
+ a) The addAttribute and addValues alternatives associate a CSN
+ with each of the added attribute values. These two alternatives
+ are equivalent from the point of view of URP since there is no CSN
+ associated specifically with the attribute type.
+
+ b) The removeAttribute alternative generates an attribute deletion
+ record for the removed attribute type.
+
+ c) The removeValues alternative generates a value deletion record
+ for each of the removed values.
+
+ d) The alterValues alternative first generates a value deletion
+ record for each of the old values. Secondly, a CSN is associated
+ with each of the new values.
+
+ e) The resetValues alternative generates a value deletion record
+ for each value actually removed.
+
+ The CSNs generated by a modify operation must be greater than the CSN
+ of any pre-existing attribute value that is removed, greater than or
+ equal to the CSN of any pre-existing attribute deletion record or
+ value deletion record applying to an added attribute value, and
+ greater than or equal to the CSN of the entry.
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 8]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ A further constraint applies to the modification number component of
+ the CSNs generated by a single modify operation. The CSN generated
+ for an added attribute value must be greater than or equal to the CSN
+ on any applicable value deletion record or attribute deletion record
+ already created by this same operation. This constraint is satisfied
+ if the same modification number is used in all the CSNs generated by
+ a single modify operation, or if the CSNs generated as the sequence
+ of modifications in the operation are applied in order use
+ monotonically increasing modification numbers. The modification
+ numbers need not be consecutive in this case.
+
+ Whenever a new value is added to the entry contents any value
+ deletion record for the same entry, attribute type and attribute
+ value may be discarded.
+
+ 5.1.4 Modify DN
+
+ The LDAP Modify DN operation and DAP modifyDN operation are used to
+ change the Relative Distinguished Name of an entry and/or to move an
+ entry to a new superior in the DIT. If the entry is moved to a new
+ superior in the DIT then the CSN on the entry's superior reference is
+ replaced. If the entry's RDN is changed then the CSN on the entry's
+ RDN is replaced. A value deletion record is stored for each of the
+ formally distinguished attribute values removed from the entry as a
+ consequence of the deleteOldRDN (modifyDN) flag or deleteoldrdn
+ (ModifyDNRequest) flag being set.
+
+ If the CSN on the entry's superior reference is revised then the new
+ value must be greater than the previous value. If the CSN on the
+ entry's RDN is revised then the new value must be greater than the
+ previous value of the CSN on the RDN. The CSNs for any value
+ deletion records must be greater than the CSNs on the removed
+ attribute values.
+
+ 5.2 Generating Replication Primitives
+
+ Each time a replication session is invoked, the supplier DSA must
+ generate and send replication primitives for updates known to the
+ supplier but not yet known to the consumer DSA. The supplier uses the
+ Update Vector of the consumer to determine what to send.
+ Conceptually, the supplier scans all the glue and non-glue entries
+ and deletion records covered by the replication agreement with the
+ consumer and generates primitives where the CSNs held by the supplier
+ are greater than the CSN for the corresponding identified replica in
+ the consumer's Update Vector.
+
+ A p-add-entry primitive is generated for each entry whose entry CSN
+ is greater than the Update Vector CSN for the same replica. The
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 9]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ superior argument of the p-add-entry primitive contains the Unique
+ Identifier of the immediate superior entry of the added entry. The
+ rdn argument of the p-add-entry primitive contains the Relative
+ Distinguished Name of the created entry except that the Unique
+ Identifier, if distinguished, is always omitted from the RDN. The
+ superior and rdn arguments are provided even if the CSN on the
+ superior reference or the RDN are greater than the CSN on the entry.
+
+ A p-add-attribute-value primitive is generated for each distinguished
+ value that has a CSN greater than the Update Vector CSN for the same
+ replica and greater than the CSN on the RDN of its entry, and for
+ each non-distinguished value that has a CSN greater than the Update
+ Vector CSN for the same replica. The p-add-attribute-value primitive
+ uses the CSN of the corresponding value. There are no separate
+ primitives generated for the distinguished values that have the same
+ CSN as the CSN on their entry's RDN.
+
+ If the CSN on an entry's RDN is greater than the Update Vector CSN
+ for the same replica and greater than the CSN on the entry then a p-
+ rename-entry primitive is generated. The CSN for this primitive is
+ the CSN on the entry's RDN and the rdn argument contains the Relative
+ Distinguished Name of the entry.
+
+ If the CSN on the entry's superior reference is greater than the
+ Update Vector CSN for the same replica and greater than the CSN on
+ the entry then a p-move-entry primitive is generated. The CSN for
+ this primitive is the CSN on the entry's superior reference and the
+ superior argument of the contains the Unique Identifier of the
+ immediate superior entry.
+
+ A p-remove-attribute-value primitive is generated for each value
+ deletion record having a CSN greater than the Update Vector CSN for
+ the same replica. The primitive uses exactly the same arguments as
+ the value deletion record.
+
+ A p-remove-attribute primitive is generated for each attribute
+ deletion record having a CSN greater than the Update Vector CSN for
+ the same replica. The primitive uses exactly the same arguments as
+ the attribute deletion record.
+
+ A p-remove-entry primitive is generated for each entry deletion
+ record having a CSN greater than the Update Vector CSN for the same
+ replica. The primitive uses exactly the same arguments as the entry
+ deletion record.
+
+ Rather than scanning the DIT, an implementation may choose to
+ generate replication primitives as the user update requests are being
+ processed and put these primitives into a replication log in
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 10]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ preparation for sending during the next replication session. Any
+ replication primitives generated from an operation in this way MUST
+ be atomic with that operation. That is, either the operation
+ succeeds, and primitives are added to the replication log, or the
+ operation fails, and no primitives are added to the log. The
+ replication log may be filtered prior to sending to eliminate any
+ primitives that are superseded by later primitives in the log, and
+ any primitives having CSNs less than or equal to the relevant CSNs
+ contained in a consumer DSA's Update Vector.
+
+ In a log based implementation, the p-add-attribute-value primitive
+ supersedes a p-remove-attribute-value primitive for the same entry,
+ attribute type, attribute value and equal or older CSN. It supersedes
+ another p-add-attribute-value primitive for the same entry, attribute
+ type, attribute value and older CSN.
+
+ The p-remove-attribute-value primitive supersedes a p-add-attribute-
+ value primitive for the same entry, attribute type, attribute value
+ and older CSN. It supersedes another p-remove-attribute-value
+ primitive for the same entry, attribute type, attribute value and
+ equal or older CSN.
+
+ The p-remove-attribute primitive supersedes a p-add-attribute-value
+ primitive for the same entry, attribute type and older CSN. It
+ supersedes a p-remove-attribute-value or another p-remove-attribute
+ primitive for the same entry, attribute type and equal or older CSN.
+
+ The p-remove-entry primitive supersedes a p-add-attribute-value, p-
+ add-entry, p-move-entry or p-rename-entry primitive for the same
+ entry and older CSN. It supersedes a p-remove-attribute-value or p-
+ remove-attribute or another p-remove-entry primitive for the same
+ entry and equal or older CSN.
+
+ The p-move-entry primitive supersedes another p-move-entry primitive
+ for the same entry and older CSN.
+
+ 5.3 Processing Replication Primitives on the DIT
+
+ Each replication primitive received from another DSA during a
+ replication session is processed against the DIT.
+
+ This section defines some commonly used sub-procedures and the
+ algorithms for processing each of the primitives. Components of
+ primitives, entries, attributes and values are referenced with the .
+ operator. In particular the notation X.csn refers to the CSN of the
+ directory object X. The operators, < and > when applied to CSNs, use
+ the convention of CSNs becoming greater with the progression of time,
+ so older CSNs are less than younger CSNs. In the case where the CSN
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 11]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ for object X has been discarded through the purging mechanism, X.csn
+ is assumed to have the least possible CSN value. In some of the
+ procedures a CSN will be explicitly purged. An implementation may
+ instead keep the CSN but set it to some value that is old enough for
+ it to be eligible for purging (e.g. the least possible CSN value)
+ without affecting the correctness of the procedures.
+
+ For an entry, E, the notation E.rdn refers to the entry's Relative
+ Distinguished Name, E.dn refers to the entry's Distinguished Name,
+ and E.superior refers to the Unique Identifier of the entry's
+ superior in the DIT.
+
+
+ 5.3.1 Saving Deletion Records
+
+ It is necessary for a DSA to remember that some entry, attribute or
+ attribute value has been deleted, for a period after the processing
+ of the update operation or primitive causing the deletion. These
+ records are called deletion records in the sections that follow and
+ are of three kinds: entry deletion records, attribute deletion
+ records and value deletion records.
+
+ Value deletion records result from, and have the same parameters as,
+ the p-remove-attribute-value primitive. The StoreValueDeletion
+ procedure creates a value deletion record from the actual arguments
+ and stores it for later access by the various primitive processing
+ procedures. When an attribute value is added to an entry, a value
+ deletion record for the same entry, attribute type and value, and
+ with an older CSN, may be discarded.
+
+ Attribute deletion records result from, and have the same parameters
+ as, the p-remove-attribute primitive. The StoreAttributeDeletion
+ procedure creates an attribute deletion record from the actual
+ arguments and stores it for later access. When an attribute deletion
+ record is stored any value deletion records for the same entry and
+ attribute type, and with equal or older CSNs, may be discarded.
+
+ Entry deletion records result from, and have the same parameters as,
+ the p-remove-entry primitive. The StoreEntryDeletion procedure
+ creates an entry deletion record from the actual arguments and stores
+ it for later access. When an entry deletion record is stored any
+ value deletion records and attribute deletion records for the same
+ entry, and with equal or older CSNs, may be discarded.
+
+ Since the deletion records have the same components as their
+ associated remove primitives an implementation may choose to use the
+ same internal structures for both.
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 12]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ 5.3.2 Glue Entries
+
+ Entries are permitted to be re-added and this can lead to situations
+ where applicable primitives are received in the period after an entry
+ is removed but before the arrival of the notification of it being
+ re-added. In these cases a glue entry is created for the Unique
+ Identifier to preserve relevant updates in the event that a p-add-
+ entry primitive with an older CSN is later received for the same
+ entry. A glue entry is upgraded to a normal entry by a subsequent p-
+ add-entry primitive.
+
+ A glue entry with no subordinate entries and containing only CSNs (on
+ itself or its component parts) that are eligible to be purged
+ (according to the Purge Vector in LDUP, or the Oldest Time in DMRP)
+ may be removed. A glue entry is discarded if its contents are
+ completely superseded by another p-remove-entry primitive.
+
+ The CreateGlueEntry function is called when required to create a glue
+ entry as a subordinate of Lost & Found. CreateGlueEntry takes a
+ single parameter which is the Unique Identifier for the glue entry.
+ The Unique Identifier also becomes the RDN for the glue entry. No
+ CSNs are associated with the entry, the entry's superior reference,
+ or the entry's name (or equivalently they are set to the least
+ possible CSN value).
+
+ 5.3.3 Generating Change Sequence Numbers
+
+ There are circumstances where conflicts arise in the processing of a
+ replication primitive. It is necessary in these cases for the DSA
+ processing the primitives to make corrective changes and emit
+ additional primitives to ensure that all other DSAs reach the same
+ consistent state. The GenerateNextCSN function is used to obtain a
+ CSN for the corrective change. An implementation that generates
+ replication primitives as the user update requests are being
+ processed and puts them into a replication log must take the
+ additional step of creating a primitive to convey the corrective
+ change to other DSAs. Implementations that generate primitives by
+ scanning entries will pick up the corrective change automatically.
+
+ As is the case for CSNs generated from DAP, DSP or LDAP operations, a
+ CSN is typically generated from the current clock time of the DSA.
+ The conditions imposed for the correct operation of the LDUP Update
+ Vector must also be satisfied.
+
+ GenerateNextCSN takes a single CSN parameter. In addition to all
+ other conditions the CSN generated by the function must be greater
+ than this parameter. Since the CSN parameter passed to
+ GenerateNextCSN is always an actual CSN from some directory object
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 13]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ stored in the local DSA, an implementation may choose to allocate
+ CSNs from an incrementing internal CSN register that is reset after
+ each replication session to a value greater than the largest CSN seen
+ so far, and thereby be safely able to disregard the parameter to
+ GenerateNextCSN.
+
+ 5.3.4 Comparison of Attribute Values
+
+ Values in primitives, in deletion records or in entries are compared
+ using the equality matching rule for the associated attribute type
+ where that type is permitted to be multi-valued. This means that two
+ values that are considered equal may nonetheless have minor
+ differences. For example, two commonName values may be equal, but use
+ different letter case and have different numbers of leading or
+ trailing spaces. Whenever a CSN for some value is refreshed the value
+ is also refreshed using the exact value from the primitive so that
+ all DSAs use exactly the same representation for the value.
+
+ Compared values for a single-valued attribute type are all considered
+ to be equal even though they may be significantly different according
+ to that attribute type's equality matching rule. In effect the
+ equality operator, '=', in the following procedures is
+ unconditionally true when used to compare values of a single-valued
+ attribute type. Whenever a CSN for the value of a single-valued
+ attribute is refreshed the value is also refreshed using the value
+ from the primitive. One significant consequence is that an entry
+ whose RDN contains a value of a single-valued attribute type is
+ effectively renamed by a p-add-attribute-value primitive with a more
+ recent value for the attribute type.
+
+ A value in an entry that is replaced by the exact representation from
+ a primitive retains its distinguished or non-distinguished status.
+ This includes replaced values of single-valued attribute types.
+
+ 5.3.5 Entry Naming
+
+ Independent changes at two or more DSAs can lead to the situation of
+ two distinct entries having the same name. The procedure,
+ CheckUniqueness(E, S, R), takes an entry and determines whether it is
+ uniquely named. If not, it disambiguates the names of the entries by
+ adding the Unique Identifier of each of the conflicting entries to
+ their own RDN.
+
+ The procedure CheckUniqueness is called in each circumstance where
+ the Relative Distinguished Name of an entry might conflict with
+ another entry, either because the entry has been renamed or because
+ it has been moved to a new superior. An entry can be renamed
+ directly by a p-rename-entry primitive, or as a side-effect of other
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 14]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ primitives causing changes to distinguished values. While each move
+ or rename of an entry potentially causes a conflict with some other
+ entry already having the new Distinguished Name, it also potentially
+ removes a previous conflict on the old Distinguished Name. The
+ enable the CheckUniqueness function to remove the Unique Identifier
+ from an entry's RDN when it is no longer needed the old name for an
+ entry is passed through the second and third parameters. The
+ parameter, S, is the Unique Identifier of the old superior entry of
+ E, and the parameter, R, is the old RDN of E. CheckUniqueness needs
+ to ignore distinguished UniqueIdentifiers when comparing entry RDNs.
+ The function BaseRDN(rdn) returns its argument minus any
+ distinguished UniqueIdentifiers to support these comparisons.
+
+ CheckUniqueness(E, S, R)
+ {
+ make E.uid non-distinguished
+ IF there exists exactly one subordinate entry, C, of S
+ where BaseRDN(C.rdn) = BaseRDN(R)
+ make C.uid non-distinguished
+ IF E.rdn is empty
+ make C.uid distinguished
+ ELSE IF there exists a subordinate entry, C, of E.superior
+ where E <> C AND BaseRDN(C.rdn) = BaseRDN(E.rdn)
+ {
+ make C.uid distinguished
+ make E.uid distinguished
+ }
+ }
+
+ Because updates are performed in isolation at multiple DSAs in a
+ multimaster configuration it is possible to encounter a situation
+ where there is a request to delete a distinguished value in an entry.
+ The recommended practice in these circumstances is to remove the
+ distinguished value and call CheckUniqueness to correct any resulting
+ name conflicts. An implementation may instead reassert the existence
+ of the distinguished value with a more recent CSN to avoid altering
+ the entry's RDN. This option is only available to updatable replicas.
+ Read-only replicas MUST remove the distinguished value. The function
+ ProtectDistinguished() returns true for an updatable part of the DIT
+ in an DSA that implements this option, and false otherwise. DSAs
+ exercising this option must generate p-add-attribute-value primitive
+ so that other DSAs are guaranteed to also reassert the distinguished
+ value. DSAs that implement the option will correctly interwork with
+ servers that do not.
+
+ The primitives p-add-entry and p-rename-entry contain common elements
+ that are applied to the Relative Distinguished Name of an entry in
+ the same way. This common processing is described in the RenameEntry
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 15]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ procedure. The parameters to this procedure are the entry, E, and the
+ p-add-entry or p-rename-entry primitive specifying the new RDN. The
+ procedure assumes that the entry does not currently contain any
+ distinguished values. It is the responsibility of the calling
+ procedure to first reset any pre-existing distinguished values to
+ non-distinguished. The procedure then resets the CSNs and sets the
+ distinguished flags for existing values and adds distinguished values
+ if necessary. The CSN for the entry's RDN, as distinct from the CSNs
+ on each of the distinguished values making up the RDN, is also set.
+
+ RenameEntry(E, P)
+ {
+ FOREACH AttributeTypeAndValue, N, in P.rdn
+ IF there exists an attribute value, V, in E of type N.type
+ where V = N.value
+ {
+ IF P.csn > V.csn
+ {
+ replace V with N.value if they are not identical
+ V.csn := P.csn
+ }
+ make V distinguished
+ }
+ ELSE IF ProtectDistinguished()
+ {
+ V := N.value
+ add V to E as a distinguished value
+ V.csn := P.csn
+ FOREACH attribute deletion record (uid, type, csn)
+ where (uid = P.uid AND type = N.type)
+ IF csn > V.csn
+ V.csn := csn
+ FOREACH value deletion record (uid, type, value, csn)
+ where (uid = P.uid AND type = N.type AND value = N.value)
+ IF csn > V.csn
+ V.csn := csn
+ V.csn := GenerateNextCSN(V.csn)
+ }
+ ELSE IF no attribute deletion record (uid, type, csn) exists
+ where (uid = P.uid AND type = N.type AND csn > P.csn)
+ AND no value deletion record (uid, type, value, csn) exists
+ where (uid = P.uid AND type = N.type AND
+ value = N.value AND csn > P.csn)
+ {
+ V := N.value
+ add V to E as a distinguished value
+ V.csn := P.csn
+ }
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 16]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ E.rdn.csn := P.csn
+ }
+
+
+ 5.3.6 Processing Add Attribute Value Primitive
+
+ This section describes the algorithm for processing the p-add-
+ attribute-value (P.uid, P.type, P.value, P.csn) primitive, which is
+ responsible for adding a single attribute value.
+
+ IF no value deletion record (uid, type, value, csn) exists where
+ (uid = P.uid AND type = P.type
+ AND value = P.value AND csn > P.csn)
+ AND no attribute deletion record (uid, type, csn) exists where
+ (uid = P.uid and type = P.type AND csn > P.csn)
+ AND no entry deletion record (uid, csn) exists where
+ (uid = P.uid AND csn > P.csn)
+ {
+ IF entry, E, with uid = P.uid does not exist
+ E := CreateGlueEntry(P.uid)
+ IF P.csn >= E.csn
+ IF attribute value V, of type P.type
+ where V = P.value exists in E
+ {
+ IF P.csn > V.csn
+ {
+ V.csn := P.csn
+ R := E.rdn
+ replace V with P.value if they are not identical
+ IF V is distinguished
+ AND P.type is a single-valued attribute type
+ CheckUniqueness(E, E.superior, R)
+ }
+ }
+ ELSE
+ {
+ V := P.value
+ Add V to E as a non-distinguished attribute value
+ V.csn := P.csn
+ }
+ }
+
+
+ 5.3.7 Processing Remove Attribute Value Primitive
+
+ This section describes the algorithm for processing the p-remove-
+ attribute-value (P.uid, P. type, P.value, P.csn) primitive, which is
+ responsible for removing a single attribute value. A value that is
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 17]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ distinguished is tagged as distinguished-not-present rather than
+ being immediately removed. Such a value will be physically removed
+ when it becomes non-distinguished.
+
+ IF no value deletion record (uid, type, value, csn) exists
+ where (uid = P.uid AND type = P.type AND
+ value = P.value AND csn >= P.csn)
+ AND
+ no attribute deletion record (uid, type, csn) exists
+ where (uid = P.uid AND type = P.type AND csn >= P.csn)
+ AND
+ no entry deletion record (uid, csn) exists
+ where (uid = P.uid AND csn >= P.csn)
+ IF entry, E, with uid = P.uid exists
+ {
+ IF P.csn > E.csn
+ IF attribute value, V, of P.type
+ where V = P.value, exists in E
+ {
+ IF P.csn > V.csn
+ IF V is distinguished
+ IF ProtectDistinguished()
+ V.csn := GenerateNextCSN(P.csn)
+ ELSE
+ {
+ R := E.rdn
+ remove value V
+ CheckUniqueness(E, E.superior, R)
+ StoreValueDeletion (P.uid, P.type, P.value, P.csn)
+ }
+ ELSE
+ {
+ remove value V
+ StoreValueDeletion (P.uid, P.type, P.value, P.csn)
+ }
+ }
+ ELSE
+ StoreValueDeletion (P.uid, P.type, P.value, P.csn)
+ }
+ ELSE
+ StoreValueDeletion (P.uid, P.type, P.value, P.csn)
+
+ The presence of a younger deletion record for the entry, attribute or
+ value provides a convenient test for whether the p-remove-attribute-
+ value primitive needs to be processed at all. If the value exists to
+ be removed then there cannot be a deletion record affecting it that
+ has a younger CSN. If there is a younger deletion record than the
+ primitive then there cannot be an older value to remove.
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 18]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ 5.3.8 Processing Remove Attribute Primitive
+
+ This section describes the algorithm for processing the p-remove-
+ attribute (P.uid, P.type, P.csn) primitive, which is responsible for
+ removing all attribute values of P.type. Values that are
+ distinguished are tagged as distinguished-not-present rather than
+ being immediately removed. Such values will be physically removed
+ when they become non-distinguished.
+
+ IF no attribute deletion record (uid, type, csn) exists
+ where (uid = P.uid AND type = P.type AND csn >= P.csn)
+ AND no entry deletion record (uid, csn) exists where
+ (uid = P.uid AND csn >= P.csn)
+ IF entry, E, with uid = P.uid exists
+ {
+ IF P.csn > E.csn
+ {
+ FOREACH attribute value, V, of type P.type in E (if any)
+ IF P.csn > V.csn
+ IF V is distinguished
+ IF ProtectDistinguished()
+ V.csn := GenerateNextCSN(P.csn)
+ ELSE
+ {
+ R := E.rdn
+ remove value V
+ CheckUniqueness(E, E.superior, R)
+ }
+ ELSE
+ remove value V
+ StoreAttributeDeletion (P.uid, P.type, P.csn)
+ }
+ }
+ ELSE
+ StoreAttributeDeletion (P.uid, P.type, P.csn)
+
+
+ 5.3.9 Processing Add Entry Primitive
+
+ This section describes the algorithm for processing the p-add-entry
+ (P.uid, P.superior, P.rdn, P.csn) primitive, which is responsible for
+ adding an entry. The CSN on an entry records the time of the latest
+ p-add-entry primitive for the Unique Identifier. In normal
+ circumstances there will only ever be one p-add-entry primitive
+ associated with an entry. The entry CSN may be discarded when it
+ becomes eligible to be purged according to the Purge Vector.
+
+ IF no entry deletion record (uid, csn) exists where
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 19]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ (uid = P.uid AND csn > P.csn)
+ IF entry, E, with uid = P.uid exists
+ {
+ IF P.csn > E.csn
+ {
+ E.csn := P.csn
+ FOREACH attribute value, V, in E
+ IF V.csn < P.csn
+ remove value V
+ process P according to
+ p-rename-entry(P.uid, P.rdn, P.csn)
+ process P according to
+ p-move-entry(P.uid, P.superior, P.csn)
+ }
+ }
+ ELSE
+ {
+ create entry E
+ E.csn := P.csn
+ E.uid := P.uid
+ E.uid.csn := P.csn
+ IF an entry with uid = P.superior does not exist
+ CreateGlueEntry(P.superior)
+ E.superior = P.superior
+ E.superior.csn := P.csn
+ RenameEntry(E, P)
+ CheckUniqueness(E, E.superior, E.rdn)
+ }
+
+
+ 5.3.10 Processing Remove Entry Primitive
+
+ This section describes the algorithm for processing the p-remove-
+ entry (P.uid, P.csn) primitive, which is responsible for removing an
+ entry. If the target entry has attribute values with CSNs greater
+ than the primitive's CSN, a superior reference with a greater CSN, or
+ if it has any subordinate entries, it becomes a glue entry instead of
+ being removed. Unless it has a CSN for its superior reference that
+ is greater than the CSN of the p-remove-entry it is also moved to
+ Lost & Found.
+
+ IF no entry deletion record (uid, csn) exists
+ where (uid = P.uid AND csn >= P.csn)
+ IF entry, E, with uid = P.uid exists
+ {
+ IF P.csn > E.csn
+ {
+ IF E.superior.csn >= P.csn
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 20]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ OR any value, V, with csn >= P.csn exists
+ OR E has subordinates
+ {
+ R := E.rdn
+ S := E.superior
+ make E a glue entry
+ purge E.csn
+ IF E.superior.csn < P.csn
+ {
+ E.superior := LOST_AND_FOUND
+ purge E.superior.csn
+ }
+ IF E.rdn.csn < P.csn
+ purge E.rdn.csn
+ FOREACH attribute value, V, in E
+ IF V.csn < P.csn
+ remove value V
+ CheckUniqueness(E, S, R)
+ }
+ ELSE
+ remove entry E
+ StoreEntryDeletion (P.uid, P.csn)
+ }
+ }
+ ELSE
+ StoreEntryDeletion (P.uid, P.csn)
+
+
+ 5.3.11 Processing Move Entry Primitive
+
+ This section describes the algorithm for processing the p-move-entry
+ (P.uid, P.superior, P.csn) primitive, which is responsible for
+ moving an entry. If the new superior specified by the primitive does
+ not exist or is a direct or indirect subordinate of the entry being
+ moved then the entry is moved to Lost & Found instead.
+
+ IF no entry deletion record (uid, csn) exists
+ where (uid = P.uid AND csn > P.csn)
+ {
+ IF entry, E, with uid = P.uid does not exist
+ E := CreateGlueEntry(P.uid)
+ IF P.csn > E.superior.csn
+ {
+ R := E.rdn
+ O := E.superior
+ IF entry, S, with uid = P.superior does not exist
+ S := CreateGlueEntry(P.superior)
+ IF S is not in the subtree of E
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 21]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ {
+ E.superior := P.superior
+ E.superior.csn = P.csn
+ }
+ ELSE
+ {
+ E.superior := LOST_AND_FOUND;
+ E.superior.csn := GenerateNextCSN(P.csn)
+ }
+ CheckUniqueness(E, O, R)
+ }
+ }
+
+
+ 5.3.12 Processing Rename Entry Primitive
+
+ This section describes the algorithm for processing the p-rename-
+ entry (P.uid, P.rdn, P.csn) primitive, which changes the Relative
+ Distinguished Name of an entry. A p-rename-entry primitive that is
+ older than current name of an entry is not simply ignored since it
+ may contain attribute values that would have been added to the entry
+ had the primitives arrived in CSN order. These extra values would
+ now be non-distinguished.
+
+ IF no entry deletion record (uid, csn) exists
+ where (uid = P.uid AND csn >= P.csn)
+ {
+ IF entry, E, with uid = P.uid does not exist
+ E := CreateGlueEntry(P.uid)
+ IF P.csn > E.rdn.csn
+ {
+ R := E.rdn
+ FOREACH distinguished attribute value, V, in entry E
+ make V non-distinguished
+ RenameEntry(E, P)
+ CheckUniqueness(E, E.superior, R)
+ }
+ ELSE
+ FOREACH AttributeTypeAndValue, N, in P.rdn
+ {
+ IF there exists an attribute value, V, in E of type
+ N.type AND V = N.value
+ {
+ IF P.csn > V.csn
+ {
+ replace V with N.value if they are not identical
+ V.csn := P.csn
+ }
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 22]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ }
+ ELSE
+ {
+ IF no value deletion record (uid, type, value, csn)
+ exists where (uid = P.uid AND type = N.type AND
+ value = N.value AND csn > P.csn)
+ AND
+ no attribute deletion record (uid, type, csn)
+ exists where (uid = P.uid AND type = N.type AND
+ csn > P.csn)
+ {
+ V := N.value
+ Add V to E
+ V.csn := P.csn
+ }
+ }
+ }
+ }
+
+
+ 6. Security Considerations
+
+ [To be supplied]
+
+
+ 7. Acknowledgements
+
+ The authors would like to thank Suellen Faulks, Tony Robertson and
+ Mark Ennis from Telstra Research Laboratories who contributed to the
+ design and verification of the procedures described in this document.
+
+ The authors would also like to thank the members of the LDUP
+ architecture group for their input into the refinement of the design.
+
+
+ 8. References
+
+ [LDUP Model] - E. Reed, "LDUP Replication Architecture", Internet
+ Draft, draft-merrells-ldup-model-01.txt, November 1998.
+
+ [BCP-11] - R. Hovey, S. Bradner, "The Organizations Involved in the
+ IETF Standards Process", BCP 11, RFC 2028, October 1996.
+
+
+ 9. Intellectual Property Notice
+
+ The IETF takes no position regarding the validity or scope of any
+ intellectual property or other rights that might be claimed to
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 23]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ 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. [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.
+
+
+ 10. Copyright Notice
+
+ Copyright (C) The Internet Society (1999). 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.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and 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.
+
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 24]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ 11. Authors' Address
+
+ Steven Legg
+ Telstra Research Laboratories
+ 770 Blackburn Road
+ Clayton, Victoria 3168
+ AUSTRALIA
+
+ Phone: +61 3 9253 6771
+ Fax: +61 3 9253 6485
+ EMail: s.legg@trl.telstra.com.au
+
+ Alison Payne
+ PricewaterhouseCoopers
+ St Jakobs Strasse 25
+ CH-4002 Basel
+ SWITZERLAND
+
+ Phone: +41-79-458 4177
+ EMail: alison.b.payne@ch.pwcglobal.com
+
+ 12. Appendix A - Changes From Previous Drafts
+
+ 12.1 Changes in Draft 01
+
+ Some of the terminology has been changed to better align with the
+ terminology used in the LDUP architecture draft.
+
+ Descriptions on the usage of CSNs have been revised to account for
+ the extra modification number component.
+
+ The semantics of re-added entries has been simplified so that only
+ changes after the latest re-add are preserved instead of all those
+ after the earliest re-add. This eliminates the need for Addition CSNs
+ in the entry. It is anticipated that new replication primitives will
+ be introduced to manage entries that come and go from partial
+ replicas instead of using p-add-entry and p-remove-entry.
+
+ Orphaned entries are no longer moved directly to Lost & Found.
+ Instead a glue entry is created in Lost & Found for the missing
+ superior and the orphaned entry becomes a subordinate of that. This
+ change eliminates the need for explicit propagated primitives for
+ moving orphaned entries to Lost & Found.
+
+ Glue entries have also been used as the mechanism for saving
+ primitives. There are no longer any references to saved primitives
+ though the functionality is still present.
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 25]
+
+
+
+
+
+INTERNET-DRAFT LDUP Update Reconciliation Procedures October 22, 1999
+
+
+ The procedures for processing received replication primitives have
+ been rearranged to follow a more consistent pattern where the
+ presence of deletion records is tested first.
+
+ 12.2 Changes in Draft 02
+
+ Multimaster replication has been dropped as a work item for the next
+ edition of X.500 so references to the proposed X.500 multimaster
+ replication protocol have been removed.
+
+ The treatment of distinguished values has been simplified. Previously
+ an attempt to remove a distinguished value caused the value to be
+ tagged distinguished-not-present. Now the distinguished value is
+ removed, and if necessary, the Unique Identifier is made
+ distinguished to avoid an empty RDN. Optionally, the value to be
+ removed can be reasserted by emitting an explicit p-add-attribute-
+ value primitive.
+
+ The current draft is more implementation neutral. A replication log
+ no longer figures prominently in the specification. The previous
+ descriptions had the user updates generating replication primitives,
+ which in turn were used to determine the CSNs and deletion records.
+ The new descriptions have user updates generating CSNs and deletion
+ records and the primitives are subsequently generated from them.
+
+ 13. Appendix B - Open Issues
+
+ The precise location of the Lost & Found entry has not yet been
+ decided.
+
+ Extensions to the algorithms to properly deal with partial replicas
+ are still to be decided.
+
+ The draft needs some editing to use MAY, MUST, etc, in the proper
+ way.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Legg & Payne Expires 22 April 2000 [Page 26]
+
+
+++ /dev/null
-Network Working Group M. Smith
-INTERNET-DRAFT Netscape Communications Corp.
-Intended Category: Standards Track
-Expires: 18 April 2000
-
- 18 October 1999
-
- LDAP C API Virtual List View Extension
- <draft-smith-ldap-c-api-ext-vlv-00.txt>
-
-1. Status of this Memo
-
-This document is an Internet-Draft and is in full conformance with all
-provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
-ments of the Internet Engineering Task Force (IETF), its areas, and its
-working groups. Note that other groups may also distribute working
-documents as Internet-Drafts.
-
-Internet-Drafts are draft documents valid for a maximum of six months
-and may be updated, replaced, or obsoleted by other documents at any
-time. It is inappropriate to use Internet-Drafts as reference material
-or to cite them other than as "work in progress."
-
-The list of current Internet-Drafts can be accessed at
-http://www.ietf.org/ietf/1id-abstracts.txt.
-
-The list of Internet-Draft Shadow Directories can be accessed at
-http://www.ietf.org/shadow.html.
-
-This draft document will be submitted to the RFC Editor as a Standards
-Track document. Distribution of this memo is unlimited. Technical dis-
-cussion of this document will take place on the IETF LDAP Extension
-Working Group mailing list <ietf-ldapext@netscape.com>. Please send
-editorial comments directly to the author <mcs@netscape.com>.
-
-Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
-
-Please see the Copyright section near the end of this document for more
-information.
-
-Expires: 18 April 2000 [Page 1]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-2. Introduction
-
-This document defines a virtual list view extension for the LDAP C API
-to support the LDAP protocol extensions for scrolling view browsing of
-search results. More specifically, this document defines functions to
-create virtual list view request controls and to parse virtual list view
-response controls.
-
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
-to be interpreted as described in RFC 2119 [KEYWORDS].
-
-3. Table of Contents
-
-1. Status of this Memo............................................1
-2. Introduction...................................................2
-3. Table of Contents..............................................2
-4. Background and Intended Usage..................................2
-5. Advertising the Virtual List View C LDAP API Extension.........3
-6. Creating a Virtual List View Request Control...................3
-7. Parsing a Virtual List View Response Control...................6
-8. Example Code...................................................8
-9. Security Considerations........................................8
-10. Copyright......................................................8
-11. Bibliography...................................................9
-12. Author's Address...............................................9
-13. Appendix A - Summary of Additions to the C LDAP API............9
-
-4. Background and Intended Usage
-
-The LDAP C API [CAPI] defines a C language application programming
-interface (API) to the Lightweight Directory Access Protocol [LDAP].
-This document defines an extension to that API to support an optional
-LDAP protocol extension for scrolling view browsing of search results,
-also known as Virtual List View [VLV].
-
-The scrolling view browsing LDAP extension itself is designed to allow a
-"virtual list box" feature to be supported efficiently by LDAP servers
-and clients. The protocol extension consists of two LDAP controls: a
-Virtual List View (VLV) Request control which is sent by a client to a
-server along with an LDAP search request and a Virtual List View
-Response control which is returned by the server to send back status
-information about the VLV request.
-
-LDAP clients that wish to use the "virtual list box" feature SHOULD
-first check the supportedControls attribute in a server's rootDSE to
-
-Expires: 18 April 2000 [Page 2]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-determine if a value identical to the Virtual List View Request
-control's OID is present. If the OID is present and the client chooses
-to use the VLV feature, it MUST construct a Virtual List View Request
-control and a Server Side Sorting Control [SSS] and send both controls
-to the server within an LDAP searchRequest message. Both controls
-SHOULD be marked critical. Client applications MAY use the
-ldap_create_vlv_control() function described in this document to create
-a Virtual List View Request control.
-
-At the end of the search request processing, the server SHOULD return a
-Virtual List View Response control in the LDAP searchResultDone message.
-A Virtual List View Response control MAY be parsed to extract its con-
-tents by using the ldap_parse_vlv_control() function described in this
-document.
-
-5. Advertising the Virtual List View C LDAP API Extension
-
-To conform with the requirements defined in the C LDAP API specification
-[CAPI], implementations that support this extension SHOULD advertise the
-existence of this extension as follows:
-
- Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
- corresponds to the "level" or revision of this specification. When
- this document is published as an RFC, the value to use for
- LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself. While
- this document is an Internet Draft, the value to use is 1000 plus the
- revision number of this draft, i.e., 1000 for the -00 revision of
- this draft, 1001 for the -01 version, and so on.
-
- Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
- array of the LDAPAPIInfo structure following a successful call to
- ldap_get_option() with an option parameter value of
- LDAP_OPT_API_INFO.
-
- Return information about the extension when the ldapaif_name field in
- the LDAPAPIFeatureInfo structure is set to the text string
- VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
- parameter value of LDAP_OPT_API_FEATURE_INFO is made.
-
-6. Creating a Virtual List View Request Control
-
-The LDAPVLVInfo structure describes a Virtual List View Request control
-and is passed to the ldap_create_vlv_control() function to create a Vir-
-tualListViewRequest control. The resulting control SHOULD be passed to
-
-Expires: 18 April 2000 [Page 3]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-the ldap_search_ext() or ldap_search_ext_s() functions described in
-[CAPI] to send them to the server. The ldap_create_sort_control() func-
-tion described in [SSSAPI] MAY be used to create a Sort control that is
-be passed to the server along with the VirtualListViewRequest control.
-
-The LDAPVLVInfo structure MAY also be used by applications to manage the
-state information associated with a series of virtual list view
-client/server interactions.
-
- /* LDAPVLVInfo structure: */
- typedef struct ldapvlvinfo {
- int ldvlv_version; /* version of this struct (1) */
- unsigned long ldvlv_before_count;
- unsigned long ldvlv_after_count;
- unsigned long ldvlv_offset; /* used if ldvlv_attrvalue is NULL
-*/
- unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
-*
- struct berval *ldvlv_attrvalue;
- struct berval *ldvlv_context;
- void *ldvlv_extradata; /* for use by application */
- } LDAPVLVInfo;
-
- /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
- #define LDAP_VLVINFO_VERSION 1
-
- /* function used to create a VirtualListViewRequest control: */
- int ldap_create_vlv_control(
- LDAP *ld,
- LDAPVLVInfo *vlvinfop,
- LDAPControl **ctrlp
- );
-
- /* OID of the VirtualListViewRequest control: */
- #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
-
-The parameters to the ldap_create_vlv_control() function are:
-
-ld An LDAP session handle, as obtained from a call to
- ldap_init().
-
-vlvinfop The address of an LDAPVLVInfo structure whose con-
- tents are used to construct the value of the control
- that is created.
-
-ctrlp A result parameter that will be assigned the address
- of an LDAPControl structure that contains the Virtu-
- alListViewRequest control created by this function.
- The memory occupied by the LDAPControl structure
- SHOULD be freed when it is no longer in use by
-
-Expires: 18 April 2000 [Page 4]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
- calling ldap_control_free().
-
-The ldap_create_vlv_control() function returns a C LDAP API error code
-to indicate success or failure (LDAP_SUCCESS if all goes well).
-
-The members of the LDAPVLVInfo structure are:
-
-ldvlv_version A number that identifies the version of the
- LDAPVLVInfo structure. This SHOULD always be set to
- the value LDAP_VLVINFO_VERSION (1).
-
-ldvlv_before_count A count of the number of entries before the target
- entry the client wants the server to send back.
- This field corresponds to the beforeCount element of
- the BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_after_count A count of the number of entries after the target
- entry the client wants the server to send back.
- This field corresponds to the afterCount element of
- the BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_offset This field is only used if ldvlv_attrvalue is NULL,
- i.e, if the byoffset choice within the VirtualList-
- ViewRequest control is to be used. ldvlv_offset is
- used along with the ldvlv_count value by the server
- to determine the target entry. This field
- corresponds to the offset element within the BER-
- encoded VirtualListViewRequest control value itself.
-
-ldvlv_count This field is only used if ldvlv_attrvalue is NULL,
- i.e., if the byIndex choice within the VirtualList-
- ViewRequest control is to be used. ldvlv_count is
- used along with the ldvlv_offset value by the server
- to determine the target entry. This field
- corresponds to the contentCount element within the
- BER-encoded VirtualListViewRequest control value
- itself.
-
-ldvlv_attrvalue If this is not NULL, it indicates that the
- greaterThanOrEqual choice within the VirtualList-
- ViewRequest is to be used. ldvlv_attrvalue
- corresponds to the assertionValue element of the
- BER-encoded VirtualListViewRequest control value
- itself. This value is compared by the server with
- the values of the attribute specified by the primary
- sort key to determine the target entry.
-
-Expires: 18 April 2000 [Page 5]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-ldvlv_context If this is not NULL, it is included as the context
- identifier in the VirtualListViewRequest control;
- ldvlv_context corresponds to the contextID element
- within the BER-encoded VirtualListViewRequest con-
- trol value itself. If ldvlv_context is NULL, no
- context identifier is included in the VirtualList-
- ViewRequest control.
-
-ldvlv_extradata This field is reserved for application-specific use
- and is not used by the ldap_create_vlv_control()
- function; it has no effect on the control that is
- created.
-
-7. Parsing a Virtual List View Response Control
-
-When an application receives the result from a VLV search, it SHOULD use
-the ldap_parse_vlv_control() function to look for and parse the Virtual
-List View Response control returned by the server.
-
- /* function used to look for and parse a VirtualListViewResponse
-control: */
- int ldap_parse_vlv_control(
- LDAP *ld,
- LDAPControl **ctrls,
- unsigned long *target_posp,
- unsigned long *list_countp,
- struct berval **contextp,
- int *errcodep
- );
-
- /* OID of the VirtualListViewResponse control: */
- #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
-
- /* new error codes: */
- #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
- #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
-
-The parameters to the ldap_parse_vlv_control() function are:
-
-ld An LDAP session handle.
-
-ctrls The address of a NULL-terminated array of LDAPCon-
- trol structures, typically obtained by a call to
- ldap_parse_result().
-
-target_posp This result parameter is filled in with the list
- index of the target entry. If this parameter is
- NULL, the target position is not returned. The
-
-Expires: 18 April 2000 [Page 6]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
- value for this result parameter is pulled from the
- targetPosition element of the BER-encoded Virtual-
- ListViewResponse control value itself.
-
-list_countp This result parameter is filled in with the server's
- estimate of the size of the list. If this parameter
- is NULL, the size is not returned. The value for
- this result parameter is pulled from the con-
- tentCount element of the BER-encoded VirtualList-
- ViewResponse control value itself.
-
-contextp This result parameter is filled in with the address
- of a struct berval that contains the server-
- generated context identifier if one was returned by
- the server. If the server did not return a context
- identifier, this parameter will be set to NULL. The
- struct berval returned SHOULD be disposed of by cal-
- ling ber_bvfree() when it is no longer needed. If
- NULL is passed for contextp, the context identifier
- is not returned.
-
-errcodep This result parameter is filled in with the VLV
- result code. If this parameter is NULL, the result
- code is not returned. The value for this result
- parameter is pulled from the virtualListViewResult
- element of the BER-encoded VirtualListViewResponse
- control value itself. As specified in the VLV pro-
- tocol extension [VLV], it will have one of the fol-
- lowing values:
-
- LDAP_SUCCESS (0); defined in [CAPI]
- LDAP_OPERATIONS_ERROR (1); defined in [CAPI]
- LDAP_UNWILLING_TO_PERFORM (53); defined in [CAPI]
- LDAP_INSUFFICIENT_ACCESS (50); defined in [CAPI]
- LDAP_BUSY (51); defined in [CAPI]
- LDAP_TIMELIMIT_EXCEEDED (3); defined in [CAPI]
- LDAP_ADMINLIMIT_EXCEEDED (11); defined in [CAPI]
- LDAP_SORT_CONTROL_MISSING (60); defined above
- LDAP_INDEX_RANGE_ERROR (61); defined above
- LDAP_OTHER (80); defined in [CAPI]
-
-The ldap_parse_vlv_control() function returns an LDAP error code that
-indicates whether a VLV Result control was found and whether the parsing
-was successful. LDAP_SUCCESS is returned if all goes well,
-LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a
-VirtualListViewResponse control, and another LDAP error code that is
-defined in [CAPI] is returned if a parsing error or other problem
-occurs.
-
-Expires: 18 April 2000 [Page 7]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-8. Example Code
-
-To be provided.
-
-9. Security Considerations
-
-Most servers will be configured to restrict access to the Virtual List
-View feature since poorly-behaved or malicious clients may cause many
-resources to be consumed on the server, or allow users to retrieve too
-many entries, or allow users to get an accurate count of the number of
-entries present in a portion of the DIT. Clients should take care to
-not abuse the VLV feature and should be prepared for servers to refuse
-to service a particular VLV request due to access control or other
-site-defined policies.
-
-Please see the protocol extension document [VLV] for a discussion of
-related security considerations.
-
-10. Copyright
-
-Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
-
-This document and translations of it may be copied and furnished to oth-
-ers, and derivative works that comment on or otherwise explain it or
-assist in its implementation may be prepared, copied, published and dis-
-tributed, 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 Stan-
-dards process must be followed, or as required to translate it into
-languages other than English.
-
-The limited permissions granted above are perpetual and will not be
-revoked by the Internet Society or its successors or assigns.
-
-This document and the information contained herein is provided on an "AS
-IS" basis and 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 FIT-
-NESS FOR A PARTICULAR PURPOSE.
-
-Expires: 18 April 2000 [Page 8]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-11. Bibliography
-
-[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
- LDAP Application Program Interface", INTERNET-DRAFT,
- <draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
-
-[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
- ment Levels", RFC 2119, March 1997.
-
-[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
- Protocol (v3)", RFC 2251, December 1997.
-
-[SSS] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control
- Extension for Server Side Sorting of Search Results",
- INTERNET-DRAFT, April 1999.
-
-[SSSAPI] C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
- Extensions for Sort and Simple Paged Results", INTERNET-
- DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.
-
-[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
- Extensions for Scrolling View Browsing of Search Results",
- INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
- June 1999.
-
-12. Author's Address
-
- Mark Smith
- Netscape Communications Corp.
- 501 E. Middlefield Rd., Mailstop MV068
- Mountain View, CA 94043
- USA
- +1 650 937-3477
- mcs@netscape.com
-
-13. Appendix A - Summary of Additions to the C LDAP API
-
-This extension introduces the following macros:
-
- LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
- LDAP_VLVINFO_VERSION
- LDAP_CONTROL_VLVREQUEST
- LDAP_CONTROL_VLVRESPONSE
- LDAP_SORT_CONTROL_MISSING
- LDAP_INDEX_RANGE_ERROR
-
-Expires: 18 April 2000 [Page 9]
-
-INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
-
-This extension introduces the following structures and typedefs:
-
- ldapvlvinfo
- LDAPVLVInfo
-
-This extension introduces the following functions:
-
- ldap_create_vlv_control()
- ldap_parse_vlv_control()
-
-Expires: 18 April 2000 [Page 10]
--- /dev/null
+Network Working Group M. Smith
+INTERNET-DRAFT Netscape Communications Corp.
+Intended Category: Standards Track
+Expires: 18 April 2000
+
+ 18 October 1999
+
+ LDAP C API Virtual List View Extension
+ <draft-smith-ldap-c-api-ext-vlv-00.txt>
+
+1. Status of this Memo
+
+This document is an Internet-Draft and is in full conformance with all
+provisions of Section 10 of RFC2026. Internet-Drafts are working docu-
+ments of the Internet Engineering Task Force (IETF), its areas, and its
+working groups. Note that other groups may also distribute working
+documents as Internet-Drafts.
+
+Internet-Drafts are draft documents valid for a maximum of six months
+and may be updated, replaced, or obsoleted by other documents at any
+time. It is inappropriate to use Internet-Drafts as reference material
+or to cite them other than as "work in progress."
+
+The list of current Internet-Drafts can be accessed at
+http://www.ietf.org/ietf/1id-abstracts.txt.
+
+The list of Internet-Draft Shadow Directories can be accessed at
+http://www.ietf.org/shadow.html.
+
+This draft document will be submitted to the RFC Editor as a Standards
+Track document. Distribution of this memo is unlimited. Technical dis-
+cussion of this document will take place on the IETF LDAP Extension
+Working Group mailing list <ietf-ldapext@netscape.com>. Please send
+editorial comments directly to the author <mcs@netscape.com>.
+
+Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
+
+Please see the Copyright section near the end of this document for more
+information.
+
+Expires: 18 April 2000 [Page 1]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+2. Introduction
+
+This document defines a virtual list view extension for the LDAP C API
+to support the LDAP protocol extensions for scrolling view browsing of
+search results. More specifically, this document defines functions to
+create virtual list view request controls and to parse virtual list view
+response controls.
+
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+"SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are
+to be interpreted as described in RFC 2119 [KEYWORDS].
+
+3. Table of Contents
+
+1. Status of this Memo............................................1
+2. Introduction...................................................2
+3. Table of Contents..............................................2
+4. Background and Intended Usage..................................2
+5. Advertising the Virtual List View C LDAP API Extension.........3
+6. Creating a Virtual List View Request Control...................3
+7. Parsing a Virtual List View Response Control...................6
+8. Example Code...................................................8
+9. Security Considerations........................................8
+10. Copyright......................................................8
+11. Bibliography...................................................9
+12. Author's Address...............................................9
+13. Appendix A - Summary of Additions to the C LDAP API............9
+
+4. Background and Intended Usage
+
+The LDAP C API [CAPI] defines a C language application programming
+interface (API) to the Lightweight Directory Access Protocol [LDAP].
+This document defines an extension to that API to support an optional
+LDAP protocol extension for scrolling view browsing of search results,
+also known as Virtual List View [VLV].
+
+The scrolling view browsing LDAP extension itself is designed to allow a
+"virtual list box" feature to be supported efficiently by LDAP servers
+and clients. The protocol extension consists of two LDAP controls: a
+Virtual List View (VLV) Request control which is sent by a client to a
+server along with an LDAP search request and a Virtual List View
+Response control which is returned by the server to send back status
+information about the VLV request.
+
+LDAP clients that wish to use the "virtual list box" feature SHOULD
+first check the supportedControls attribute in a server's rootDSE to
+
+Expires: 18 April 2000 [Page 2]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+determine if a value identical to the Virtual List View Request
+control's OID is present. If the OID is present and the client chooses
+to use the VLV feature, it MUST construct a Virtual List View Request
+control and a Server Side Sorting Control [SSS] and send both controls
+to the server within an LDAP searchRequest message. Both controls
+SHOULD be marked critical. Client applications MAY use the
+ldap_create_vlv_control() function described in this document to create
+a Virtual List View Request control.
+
+At the end of the search request processing, the server SHOULD return a
+Virtual List View Response control in the LDAP searchResultDone message.
+A Virtual List View Response control MAY be parsed to extract its con-
+tents by using the ldap_parse_vlv_control() function described in this
+document.
+
+5. Advertising the Virtual List View C LDAP API Extension
+
+To conform with the requirements defined in the C LDAP API specification
+[CAPI], implementations that support this extension SHOULD advertise the
+existence of this extension as follows:
+
+ Define the macro LDAP_API_FEATURE_VIRTUAL_LIST_VIEW as a value that
+ corresponds to the "level" or revision of this specification. When
+ this document is published as an RFC, the value to use for
+ LDAP_API_FEATURE_VIRTUAL_LIST_VIEW is the RFC number itself. While
+ this document is an Internet Draft, the value to use is 1000 plus the
+ revision number of this draft, i.e., 1000 for the -00 revision of
+ this draft, 1001 for the -01 version, and so on.
+
+ Return the text string VIRTUAL_LIST_VIEW in the ldapai_extensions
+ array of the LDAPAPIInfo structure following a successful call to
+ ldap_get_option() with an option parameter value of
+ LDAP_OPT_API_INFO.
+
+ Return information about the extension when the ldapaif_name field in
+ the LDAPAPIFeatureInfo structure is set to the text string
+ VIRTUAL_LIST_VIEW and a call to ldap_get_option() with an option
+ parameter value of LDAP_OPT_API_FEATURE_INFO is made.
+
+6. Creating a Virtual List View Request Control
+
+The LDAPVLVInfo structure describes a Virtual List View Request control
+and is passed to the ldap_create_vlv_control() function to create a Vir-
+tualListViewRequest control. The resulting control SHOULD be passed to
+
+Expires: 18 April 2000 [Page 3]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+the ldap_search_ext() or ldap_search_ext_s() functions described in
+[CAPI] to send them to the server. The ldap_create_sort_control() func-
+tion described in [SSSAPI] MAY be used to create a Sort control that is
+be passed to the server along with the VirtualListViewRequest control.
+
+The LDAPVLVInfo structure MAY also be used by applications to manage the
+state information associated with a series of virtual list view
+client/server interactions.
+
+ /* LDAPVLVInfo structure: */
+ typedef struct ldapvlvinfo {
+ int ldvlv_version; /* version of this struct (1) */
+ unsigned long ldvlv_before_count;
+ unsigned long ldvlv_after_count;
+ unsigned long ldvlv_offset; /* used if ldvlv_attrvalue is NULL
+*/
+ unsigned long ldvlv_count; /* used if ldvlv_attrvalue is NULL
+*
+ struct berval *ldvlv_attrvalue;
+ struct berval *ldvlv_context;
+ void *ldvlv_extradata; /* for use by application */
+ } LDAPVLVInfo;
+
+ /* value for the ldvlv_version field of the LDAPVLVInfo structure: */
+ #define LDAP_VLVINFO_VERSION 1
+
+ /* function used to create a VirtualListViewRequest control: */
+ int ldap_create_vlv_control(
+ LDAP *ld,
+ LDAPVLVInfo *vlvinfop,
+ LDAPControl **ctrlp
+ );
+
+ /* OID of the VirtualListViewRequest control: */
+ #define LDAP_CONTROL_VLVREQUEST "2.16.840.1.113730.3.4.9"
+
+The parameters to the ldap_create_vlv_control() function are:
+
+ld An LDAP session handle, as obtained from a call to
+ ldap_init().
+
+vlvinfop The address of an LDAPVLVInfo structure whose con-
+ tents are used to construct the value of the control
+ that is created.
+
+ctrlp A result parameter that will be assigned the address
+ of an LDAPControl structure that contains the Virtu-
+ alListViewRequest control created by this function.
+ The memory occupied by the LDAPControl structure
+ SHOULD be freed when it is no longer in use by
+
+Expires: 18 April 2000 [Page 4]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ calling ldap_control_free().
+
+The ldap_create_vlv_control() function returns a C LDAP API error code
+to indicate success or failure (LDAP_SUCCESS if all goes well).
+
+The members of the LDAPVLVInfo structure are:
+
+ldvlv_version A number that identifies the version of the
+ LDAPVLVInfo structure. This SHOULD always be set to
+ the value LDAP_VLVINFO_VERSION (1).
+
+ldvlv_before_count A count of the number of entries before the target
+ entry the client wants the server to send back.
+ This field corresponds to the beforeCount element of
+ the BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_after_count A count of the number of entries after the target
+ entry the client wants the server to send back.
+ This field corresponds to the afterCount element of
+ the BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_offset This field is only used if ldvlv_attrvalue is NULL,
+ i.e, if the byoffset choice within the VirtualList-
+ ViewRequest control is to be used. ldvlv_offset is
+ used along with the ldvlv_count value by the server
+ to determine the target entry. This field
+ corresponds to the offset element within the BER-
+ encoded VirtualListViewRequest control value itself.
+
+ldvlv_count This field is only used if ldvlv_attrvalue is NULL,
+ i.e., if the byIndex choice within the VirtualList-
+ ViewRequest control is to be used. ldvlv_count is
+ used along with the ldvlv_offset value by the server
+ to determine the target entry. This field
+ corresponds to the contentCount element within the
+ BER-encoded VirtualListViewRequest control value
+ itself.
+
+ldvlv_attrvalue If this is not NULL, it indicates that the
+ greaterThanOrEqual choice within the VirtualList-
+ ViewRequest is to be used. ldvlv_attrvalue
+ corresponds to the assertionValue element of the
+ BER-encoded VirtualListViewRequest control value
+ itself. This value is compared by the server with
+ the values of the attribute specified by the primary
+ sort key to determine the target entry.
+
+Expires: 18 April 2000 [Page 5]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ldvlv_context If this is not NULL, it is included as the context
+ identifier in the VirtualListViewRequest control;
+ ldvlv_context corresponds to the contextID element
+ within the BER-encoded VirtualListViewRequest con-
+ trol value itself. If ldvlv_context is NULL, no
+ context identifier is included in the VirtualList-
+ ViewRequest control.
+
+ldvlv_extradata This field is reserved for application-specific use
+ and is not used by the ldap_create_vlv_control()
+ function; it has no effect on the control that is
+ created.
+
+7. Parsing a Virtual List View Response Control
+
+When an application receives the result from a VLV search, it SHOULD use
+the ldap_parse_vlv_control() function to look for and parse the Virtual
+List View Response control returned by the server.
+
+ /* function used to look for and parse a VirtualListViewResponse
+control: */
+ int ldap_parse_vlv_control(
+ LDAP *ld,
+ LDAPControl **ctrls,
+ unsigned long *target_posp,
+ unsigned long *list_countp,
+ struct berval **contextp,
+ int *errcodep
+ );
+
+ /* OID of the VirtualListViewResponse control: */
+ #define LDAP_CONTROL_VLVRESPONSE "2.16.840.1.113730.3.4.10"
+
+ /* new error codes: */
+ #define LDAP_SORT_CONTROL_MISSING 0x3C /* 60 */
+ #define LDAP_INDEX_RANGE_ERROR 0x3D /* 61 */
+
+The parameters to the ldap_parse_vlv_control() function are:
+
+ld An LDAP session handle.
+
+ctrls The address of a NULL-terminated array of LDAPCon-
+ trol structures, typically obtained by a call to
+ ldap_parse_result().
+
+target_posp This result parameter is filled in with the list
+ index of the target entry. If this parameter is
+ NULL, the target position is not returned. The
+
+Expires: 18 April 2000 [Page 6]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+ value for this result parameter is pulled from the
+ targetPosition element of the BER-encoded Virtual-
+ ListViewResponse control value itself.
+
+list_countp This result parameter is filled in with the server's
+ estimate of the size of the list. If this parameter
+ is NULL, the size is not returned. The value for
+ this result parameter is pulled from the con-
+ tentCount element of the BER-encoded VirtualList-
+ ViewResponse control value itself.
+
+contextp This result parameter is filled in with the address
+ of a struct berval that contains the server-
+ generated context identifier if one was returned by
+ the server. If the server did not return a context
+ identifier, this parameter will be set to NULL. The
+ struct berval returned SHOULD be disposed of by cal-
+ ling ber_bvfree() when it is no longer needed. If
+ NULL is passed for contextp, the context identifier
+ is not returned.
+
+errcodep This result parameter is filled in with the VLV
+ result code. If this parameter is NULL, the result
+ code is not returned. The value for this result
+ parameter is pulled from the virtualListViewResult
+ element of the BER-encoded VirtualListViewResponse
+ control value itself. As specified in the VLV pro-
+ tocol extension [VLV], it will have one of the fol-
+ lowing values:
+
+ LDAP_SUCCESS (0); defined in [CAPI]
+ LDAP_OPERATIONS_ERROR (1); defined in [CAPI]
+ LDAP_UNWILLING_TO_PERFORM (53); defined in [CAPI]
+ LDAP_INSUFFICIENT_ACCESS (50); defined in [CAPI]
+ LDAP_BUSY (51); defined in [CAPI]
+ LDAP_TIMELIMIT_EXCEEDED (3); defined in [CAPI]
+ LDAP_ADMINLIMIT_EXCEEDED (11); defined in [CAPI]
+ LDAP_SORT_CONTROL_MISSING (60); defined above
+ LDAP_INDEX_RANGE_ERROR (61); defined above
+ LDAP_OTHER (80); defined in [CAPI]
+
+The ldap_parse_vlv_control() function returns an LDAP error code that
+indicates whether a VLV Result control was found and whether the parsing
+was successful. LDAP_SUCCESS is returned if all goes well,
+LDAP_CONTROL_NOT_FOUND is returned if the ctrls array does not include a
+VirtualListViewResponse control, and another LDAP error code that is
+defined in [CAPI] is returned if a parsing error or other problem
+occurs.
+
+Expires: 18 April 2000 [Page 7]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+8. Example Code
+
+To be provided.
+
+9. Security Considerations
+
+Most servers will be configured to restrict access to the Virtual List
+View feature since poorly-behaved or malicious clients may cause many
+resources to be consumed on the server, or allow users to retrieve too
+many entries, or allow users to get an accurate count of the number of
+entries present in a portion of the DIT. Clients should take care to
+not abuse the VLV feature and should be prepared for servers to refuse
+to service a particular VLV request due to access control or other
+site-defined policies.
+
+Please see the protocol extension document [VLV] for a discussion of
+related security considerations.
+
+10. Copyright
+
+Copyright (C) The Internet Society (1998-1999). All Rights Reserved.
+
+This document and translations of it may be copied and furnished to oth-
+ers, and derivative works that comment on or otherwise explain it or
+assist in its implementation may be prepared, copied, published and dis-
+tributed, 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 Stan-
+dards process must be followed, or as required to translate it into
+languages other than English.
+
+The limited permissions granted above are perpetual and will not be
+revoked by the Internet Society or its successors or assigns.
+
+This document and the information contained herein is provided on an "AS
+IS" basis and 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 FIT-
+NESS FOR A PARTICULAR PURPOSE.
+
+Expires: 18 April 2000 [Page 8]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+11. Bibliography
+
+[CAPI] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C
+ LDAP Application Program Interface", INTERNET-DRAFT,
+ <draft-ietf-ldapext-ldap-c-api-04.txt>, 8 October 1999.
+
+[KEYWORDS] S. Bradner, "Key words for use in RFCs to Indicate Require-
+ ment Levels", RFC 2119, March 1997.
+
+[LDAP] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
+ Protocol (v3)", RFC 2251, December 1997.
+
+[SSS] A. Herron, T. Howes, M. Wahl, A. Anantha, "LDAP Control
+ Extension for Server Side Sorting of Search Results",
+ INTERNET-DRAFT, April 1999.
+
+[SSSAPI] C. Weider, A. Herron, T. Howes, M. Smith, M. Wahl, "LDAP API
+ Extensions for Sort and Simple Paged Results", INTERNET-
+ DRAFT, <draft-ietf-asid-ldapv3-api-ext-00.txt>, July 1997.
+
+[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP
+ Extensions for Scrolling View Browsing of Search Results",
+ INTERNET-DRAFT <draft-ietf-ldapext-ldapv3-vlv-03.txt>, 11
+ June 1999.
+
+12. Author's Address
+
+ Mark Smith
+ Netscape Communications Corp.
+ 501 E. Middlefield Rd., Mailstop MV068
+ Mountain View, CA 94043
+ USA
+ +1 650 937-3477
+ mcs@netscape.com
+
+13. Appendix A - Summary of Additions to the C LDAP API
+
+This extension introduces the following macros:
+
+ LDAP_API_FEATURE_VIRTUAL_LIST_VIEW
+ LDAP_VLVINFO_VERSION
+ LDAP_CONTROL_VLVREQUEST
+ LDAP_CONTROL_VLVRESPONSE
+ LDAP_SORT_CONTROL_MISSING
+ LDAP_INDEX_RANGE_ERROR
+
+Expires: 18 April 2000 [Page 9]
+
+INTERNET-DRAFT LDAP C API Virtual List View Extension 18 October 1999
+
+This extension introduces the following structures and typedefs:
+
+ ldapvlvinfo
+ LDAPVLVInfo
+
+This extension introduces the following functions:
+
+ ldap_create_vlv_control()
+ ldap_parse_vlv_control()
+
+Expires: 18 April 2000 [Page 10]
projects / openldap / commitdiff