From: Kurt Zeilenga Date: Fri, 9 Jun 2000 02:09:11 +0000 (+0000) Subject: Import LDUP drafts and reimport poorly imported ldapext drafts X-Git-Tag: LDBM_PRE_GIANT_RWLOCK~2689 X-Git-Url: https://git.sur5r.net/?a=commitdiff_plain;h=e67117a6581ebae59c69b1fa9f5586452f4bb590;p=openldap Import LDUP drafts and reimport poorly imported ldapext drafts --- diff --git a/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-04.txt b/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-04.txt deleted file mode 100644 index e7bb99ef8a..0000000000 --- a/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-04.txt +++ /dev/null @@ -1,655 +0,0 @@ - -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] - - diff --git a/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt b/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt new file mode 100644 index 0000000000..e7bb99ef8a --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-ldapv3-vlv-xx.txt @@ -0,0 +1,655 @@ + +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] + + diff --git a/doc/drafts/draft-ietf-ldapext-sorting-02.txt b/doc/drafts/draft-ietf-ldapext-sorting-02.txt deleted file mode 100644 index 8a7b99f128..0000000000 --- a/doc/drafts/draft-ietf-ldapext-sorting-02.txt +++ /dev/null @@ -1,303 +0,0 @@ - -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 - diff --git a/doc/drafts/draft-ietf-ldapext-sorting-xx.txt b/doc/drafts/draft-ietf-ldapext-sorting-xx.txt new file mode 100644 index 0000000000..8a7b99f128 --- /dev/null +++ b/doc/drafts/draft-ietf-ldapext-sorting-xx.txt @@ -0,0 +1,303 @@ + +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 + diff --git a/doc/drafts/draft-ietf-ldup-framing-xx.txt b/doc/drafts/draft-ietf-ldup-framing-xx.txt new file mode 100644 index 0000000000..404e8ac603 --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-framing-xx.txt @@ -0,0 +1,340 @@ + +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] + +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] + +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] + +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] + +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] + +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] diff --git a/doc/drafts/draft-ietf-ldup-infomod-xx.txt b/doc/drafts/draft-ietf-ldup-infomod-xx.txt new file mode 100644 index 0000000000..b1e5ab1aac --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-infomod-xx.txt @@ -0,0 +1,1021 @@ +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 + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 +mm = dd +dd = dd +hh = dd +mi = dd +ss = dd +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + + + +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 + diff --git a/doc/drafts/draft-ietf-ldup-model-xx.txt b/doc/drafts/draft-ietf-ldup-model-xx.txt new file mode 100644 index 0000000000..1567971548 --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-model-xx.txt @@ -0,0 +1,2468 @@ +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 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 + + diff --git a/doc/drafts/draft-ietf-ldup-protocol-xx.txt b/doc/drafts/draft-ietf-ldup-protocol-xx.txt new file mode 100644 index 0000000000..9108794f06 --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-protocol-xx.txt @@ -0,0 +1,895 @@ + +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] + +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] + +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] + +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] + +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] + +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 , + 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 , 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] + +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] + +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] + +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] + +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] + +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] + +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] + +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] + +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 and an update vector with CSNs + ,..., 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] + +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] + +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] diff --git a/doc/drafts/draft-ietf-ldup-replica-req-xx.txt b/doc/drafts/draft-ietf-ldup-replica-req-xx.txt new file mode 100644 index 0000000000..ac8a526837 --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-replica-req-xx.txt @@ -0,0 +1,1035 @@ + 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 + + + + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] + + + 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] diff --git a/doc/drafts/draft-ietf-ldup-urp-xx.txt b/doc/drafts/draft-ietf-ldup-urp-xx.txt new file mode 100644 index 0000000000..91f24cfadb --- /dev/null +++ b/doc/drafts/draft-ietf-ldup-urp-xx.txt @@ -0,0 +1,1554 @@ +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 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] + + diff --git a/doc/drafts/draft-smith-ldap-c-api-ext-vlv-00.txt b/doc/drafts/draft-smith-ldap-c-api-ext-vlv-00.txt deleted file mode 100644 index 6b4f28b6b5..0000000000 --- a/doc/drafts/draft-smith-ldap-c-api-ext-vlv-00.txt +++ /dev/null @@ -1,468 +0,0 @@ -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 - - -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 . Please send -editorial comments directly to the author . - -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, - , 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, , July 1997. - -[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP - Extensions for Scrolling View Browsing of Search Results", - INTERNET-DRAFT , 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] diff --git a/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt b/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt new file mode 100644 index 0000000000..6b4f28b6b5 --- /dev/null +++ b/doc/drafts/draft-smith-ldap-c-api-ext-vlv-xx.txt @@ -0,0 +1,468 @@ +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 + + +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 . Please send +editorial comments directly to the author . + +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, + , 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, , July 1997. + +[VLV] D. Boreham, J. Sermersheim, A. Anantha, M. Armijo, "LDAP + Extensions for Scrolling View Browsing of Search Results", + INTERNET-DRAFT , 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]