Internet-Draft Ellen Stokes LDUP Workgroup IBM Intended Category: Standards Track Gordon Good Expires: 22 April 2000 America Online/Netscape 22 October 1999 The LDUP Replication Update Protocol Filename: draft-ietf-ldup-protocol-00.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 replication protocol.........................3 4.2. Consumer-initiated replication protocol......................4 5. Replication protocol element definitions........................5 5.1 StartReplicationRequest Extended Operation......................5 5.2 StartReplicationResponse 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 EndReplicationRequest Extended Operation........................11 5.5 EndReplicationResponse Extended Operation.......................11 6. Semantics of Full and Incremental Update protocols..............12 7. Summary of response codes.......................................12 8. Implications for log-based and state-based servers..............13 9. Replication of access control and schema information............13 10. Security Considerations.........................................13 11. Glossary of Terms...............................................13 12. Acknowledgments.................................................13 13. References......................................................13 14. Author's Addresses..............................................14 Stokes and Good [Page 1] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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 22 April 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 Replication Update Protocol 22 October 1999 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. The 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 replication protocol S -> C: LDAP bind operation (identity and credentials used are implementation-defined) C -> S: Bind response S -> C: StartReplicationRequest LDAPv3 extended operation. The parameters are: 1) Root of replicated area (unambiguously identifies the replicated area) 2) Supplier's replicaID 3) OID of replication protocol to be used (this document defines IETF-LDUP incremental and IETF-LDUP total update protocols) 4) The protocol initiation type - Supplier-Initiated in this case. C -> S: StartReplicationResponse LDAPv3 extended operation. The parameters are: 1) A response code (see section 7) 2) An optional update vector that is included if and only if the response code is REPL_SUCCESS. Stokes and Good [Page 3] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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 EndReplicationRequest LDAPv3 extended operation C -> S: The consumer responds by sending an EndReplicationRequest 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: StartReplicationRequest LDAPv3 extended operation. The parameters are: 1) Root of replicated area (unambiguously identifies the replicated area) 2) Consumer's replicaID 3) OID of replication protocol to be used (this document defines IETF-LDUP incremental and IETF-LDUP total update protocols) 4) The protocol initiation type - Consumer-Initiated in this case S -> C: StartReplicationResponse LDAPv3 extended operation. The Stokes and Good [Page 4] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 parameters are: 1) 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 StartReplicationRequest Extended Operation The StartReplicationRequest 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 StartReplicationRequest extended operation is defined as follows: StartReplicationRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName of the StartReplicationRequest must be [OID to be assigned]. The requestValue of the StartReplicationRequest must be set to the BER-encoding of the following: requestValue ::= SEQUENCE { replicaRoot LDAPDN, replicaID LDAPString, replicationProtocolOID LDAPOID, replicationInitiator ENUMERATED { supplier (0), consumer (1) } } The parameters in the requestValue of the StartReplicationRequest are: - replicaRoot: the distinguished name of the entry at the top of the replicated area, and uniquely identifies the unit of Stokes and Good [Page 5] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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]. - replicationProtocolOID: the type of replication protocol that should be used to transfer the updates. This document describes two protocols; ietf-ldup-full-update and ietf-ldup-incremental-update. See section 7 for information on the semantic behavior of these update protocols. Implementations MUST support the two update protocols defined in this document. - 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 StartReplicationResponse Extended Operation The StartReplicationResponse extended operation is sent in response to a StartReplicationRequest extended operation. For a supplier-initiated session, the StartReplicationResponse extended operation 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 StartReplicationResponse extended operation containing a success code and the consumer's replica update vector. If the consumer is unwilling or unable to accept updates, it sends a StartReplicationResponse extended operation containing an error code. For a consumer-initiated session, the StartReplicationResponse extended operation 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 StartReplicationResponse extended operation with a success code. If the supplier is unwilling or unable to send updates to the consumer, it sends a StartReplicationResponse extended operation 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 Stokes and Good [Page 6] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 initiates a supplier-initiated replication session. The StartReplicationResponse extended operation is defined as follows: StartReplicationResponse ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName of the StartReplicationResponse must be [OID to be assigned]. The requestValue of the StartReplicationResponse must be set to the BER-encoding of the following: requestValue ::= 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: ReplicationUpdate ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName of the ReplicationUpdate must be [OID to be assigned]. The requestValue of the ReplicationUpdate must be set to the BER-encoding of the following: requestValue ::= SEQUENCE { uniqueID UniqueIdentifier, Stokes and Good [Page 7] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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 { csn lDAPChangeSequenceNumber, superior UniqueIdentifier, rdn RelativeLDAPDN } Parameters of the AddEntryPrimitive are: Stokes and Good [Page 8] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 - 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. RemoveEntryPrimitive ::= [APPLICATION 3] SEQUENCE { csn lDAPChangeSequenceNumber } Parameters of the RemoveEntryPrimitive are: - csn: The change sequence number of the primitive. Stokes and Good [Page 9] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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 The RemoveAttributePrimitive is used to remove an attribute and all its values from an entry. RemoveAttributePrimitive ::= [APPLICATION 6] SEQUENCE { csn lDAPChangeSequenceNumber, type AttributeDescription } Stokes and Good [Page 10] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 Parameters of the RemoveAttributePrimitive are: - csn: The change sequence number of the primitive. - type: The type of the attribute being removed. 5.4 EndReplicationRequest Extended Operation The EndReplicationRequest 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 EndReplicationRequest extended operation contains a replica update vector. The consumer server must replace its replica update vector, if present, with the one provided by the suplier. In the event that the supplier is sending an incremental update, the replica update vector is absent. The EndReplicationRequest extended operation is defined as follows: EndReplicationRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName of the EndReplicationRequest must be [OID to be assigned]. The requestValue of the EndReplicationRequest must be set to the BER-encoding of 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 EndReplicationResponse extended operation. 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 EndReplicationResponse Extended Operation The EndReplicationResponse extended operation is sent by a consumer to a supplier in response to an EndReplicationRequest extended operation. Stokes and Good [Page 11] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 The EndReplicationResponse extended operation is defined as follows: EndReplicationResponse ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING } The requestName of the EndReplicationResponse must be [OID to be assigned]. The requestValue of the EndReplicationResponse must be set to the BER-encoding of the following: requestValue ::= 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. 6. Semantics of Full and Incremental Update protocols 7. Summary of response codes The following list describes the response codes that may be included in the StartReplicationResponse, EndReplicationResponse, 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]. Stokes and Good [Page 12] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 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 This should be covered in the Architecture document. 9. Replication of access control and schema information This should be covered in the Architecture document? 10. Security Considerations 11. Glossary of Terms Note: This probably shouldn't appear here, but rather in the architecture document. However, this "covered by" is a new concept I introduced here, so I've temporarily defined it here. 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 13. References [KEYWORDS] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Stokes and Good [Page 13] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 Levels", Harvard University, RFC 2119, March 1997. [ARCHITECTURE] J. Merrells, E. Reed, U. Srinivasan, "LDAP Replication Architec- ture", Internet-Draft, draft-ietf-ldup-model-00.txt, April 1999. [LDAPv3] M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. [URP]S. Legg, "LDUP Update Reconciliation Procedures", Internet-Draft, draft-legg-ldup-urp-00.txt, February 1999. [INFOMOD] E. Reed, "LDAP Replication Information Model", Internet-Draft, draft-reed-ldup-infomod-00.txt, November 1998. [REQ]R. Weiser, E. Stokes, "LDAP V3 Replication Requirements", Internet-Draft, draft-ietf-ldup-replica-req-00.txt, February 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 America Online/Netscape 501 E. Middlefield Rd. Mailstop MV068 Mountain View, CA 94043 USA EMail: ggood@netscape.com Phone: +1 650 937-3825 This Internet Draft expires 22 April 2000 Appendix A - Complete ASN.1 Definition Stokes and Good [Page 14] INTERNET-DRAFT LDUP Replication Update Protocol 22 October 1999 Appendix A - Complete ASN.1 Definition To be provided. Full Copyright Statement 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 develop- ing 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 MER- CHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Stokes and Good [Page 15]