[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04 05

   LDUP Replication Update Protocol                   John McMeeking
   Internet-Draft                                     IBM Corporation
   Intended Category: Experimental
   Expires: June 2004                                 December 2003


                   The LDUP Replication Update Protocol
                     <draft-ietf-ldup-protocol-05.txt>

1.  Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC2026.

   Internet-Drafts are working 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.

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 updateable 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 LDAPv3 extended operations
   and controls. LDAPv3 is described in RFC 2251 [LDAPv3]. Some LDAPv3
   extended operations and controls described here are LDAPv3 extended
   operations used to group related operations. The protocol elements
   used for grouping are described in LDAPv3: Grouping of Related
   Operations [GROUPING].

   Certain terms used in this document are defined in the document
   "LDAP Replication Architecture" [ARCHITECTURE].




McMeeking               Expires September 2003                [Page 1]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

   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].

















































McMeeking               Expires September 2003                [Page 2]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

3.  Table of Contents

1.  Status of this Memo..............................................1
2.  Abstract.........................................................1
3.  Table of Contents................................................3
4.  Overview of Protocol.............................................4
5.  High-level Description of Protocol Flow..........................4
5.1.     Supplier-initiated replication protocol.....................4
5.2.     Consumer-initiated replication protocol.....................6
6.  Replication protocol element definitions.........................6
6.1.     createGroupingRequest Extended Operation....................6
6.2.     createGroupingResponse Extended Response....................8
6.3.     ReplicationUpdate Extended Operation.......................10
6.3.1.     UniqueIdentifier.........................................10
6.3.2.     ReplicationPrimitive.....................................11
6.3.2.1.     AddEntryPrimitive.....................................11
6.3.2.2.     MoveEntryPrimitive....................................11
6.3.2.4.     RemoveEntryPrimitive..................................12
6.3.2.5.     AddAttributeValuePrimitive............................12
6.3.2.6.     RemoveAttributeValuePrimitive.........................13
6.3.2.7.     RemoveAttributePrimitive..............................13
6.4.     endGroupingRequest Extended Operation......................14
6.5.     endGroupingResponse Extended Response......................14
6.6.     ReplicationUpdateResponse Extended Response................15
6.7.     ReplicationUpdateNotice Extended Response..................15
7.  Semantics of Full and Incremental Update protocols..............16
8.  Semantics of the LDAP Replication Grouping Type.................17
9.  Summary of response codes.......................................17
10. Security Considerations.........................................18
11. IANA Considerations.............................................18
12. Acknowledgements................................................19
13. References......................................................19
14. Author's Addresses..............................................20
15. Appendix A - Complete ASN.1 Definition..........................20
16. Intellectual Property Notice....................................22
17. Copyright Information...........................................22












McMeeking               Expires September 2003                [Page 3]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol


4.  Overview of Protocol

   The LDAP Replication Architecture [ARCHITECTURE] describes the
   overall approach used in ensuring consistency of multiple updateable
   replicas of directory content. The protocol described in this
   document implements the approach described in that document.

   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]. You must understand URP to
   process/send and receive/process the updates correctly.  What you
   send may depend on whether your implementation is state-based or
   log-based; what you receive is independent of whether you are state-
   based or log-based. Consistent application of the update resolution
   policies ensures that all replicas eventually converge and contain
   the same directory data.  The protocol depends upon elements of the
   information model set forth in [INFOMOD] and [ENTRYUUID].  In
   particular, the notion of a universally unique identifier (UUID) to
   identify a particular entry is used in elements of the protocol. The
   protocol also makes use LDAP Change Sequence Numbers, which provide
   an ordering of changes across multiple servers. LDAP Change Sequence
   Numbers are defined in [CSN].

   The protocol is intended to meet the requirements set forth in
   [REQ].

5.  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 operation to the consumer, and "C -> S" indicates that the
   consumer is sending an LDAPv3 operation to the supplier.

5.1.   Supplier-initiated replication protocol

      S -> C: LDAP bind operation (identity and credentials used are
              implementation-defined)

      C -> S: Bind response

      S -> C: createGroupingRequest LDAPv3 extended operation. The
              parameters are:

                1) The LDUP Replication grouping type OID.
McMeeking               Expires September 2003                [Page 4]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

                2) Area of replication subentry DN (unambiguously
                identifies the replicated area)
                3) Supplier's replicaID
                4) OID of replication protocol to be used (this
                document defines IETF-LDUP incremental and IETF-LDUP
                total update protocols)
                5) The protocol initiation type - Supplier-Initiated in
                this case.
                6) A table of UUID to replicaID mappings.

      C -> S: createGroupingResponse LDAPv3 extended response. The
              parameters are:

                1) A groupCookie that represents the LDUP Replication
                group just created
                2) A response code (see section 9)
                3) An optional update vector that is present 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)
                3) A groupingControl containing the groupCookie for
                this LDUP Replication group

      C -> S: At any time, the consumer may send an unsolicited
              ReplicationUpdateNotice LDAPv3 extended response. 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 ReplicationUpdateNotice 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.
                3) A groupingControl containing the groupCookie for
                this LDUP Replication group.

      S -> C: After all required updates have been sent to the
              consumer, the supplier sends an endGroupingRequest LDAPv3
              extended operation. The parameters are:

                1) A groupCookie for this LDUP Replication group


McMeeking               Expires September 2003                [Page 5]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

      C -> S: The consumer responds by sending an endGroupingResponse
              LDAPv3 extended response.

      S -> C: The supplier then sends an unbind operation and both
              sides close the connection.

5.2.   Consumer-initiated replication protocol

      C -> S: LDAP bind operation (identity and credentials used are
              implementation-defined)

      S -> C: Bind response

      C -> S: createGroupingRequest LDAPv3 extended operation. The
              parameters are:

                1) The LDUP replication grouping type OID
                2) Area of replication subentry DN (unambiguously
                identifies the replicated area)
                3) Consumer's replicaID
                4) OID of replication protocol to be used (this
                document defines ietf-ldup-incremental-update and ietf-
                ldup-full-update protocols)
                5) The protocol initiation type - Consumer-Initiated in
                this case

      S -> C: createGroupingResponse LDAPv3 extended response. The
              parameters are:

                1) A groupCookie that represents the LDUP replication
                group just created
                2) A LDUP response code (see section 9)

      C -> S: The consumer then sends an unbind operation and both
              sides close the connection.

   The supplier server then connects to the consumer, beginning a
   Supplier- Initiated protocol session (see section 5.1).

6.  Replication protocol element definitions

   The following sub-sections define the individual protocol elements
   that make up the update replication protocol.  Portions of the ASN.1
   use ASN.1 types defined in [LDAPv3].

6.1.   createGroupingRequest Extended Operation

   The creation of an LDAP Replication grouping type by a replication
   initiator indicates that a replication session should commence. An
   LDUP Replication grouping type is created by sending a
   createGroupingRequest extended operation with a createGroupType OID
   value specifying the LDAP Replication grouping type. For supplier-
McMeeking               Expires September 2003                [Page 6]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

   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 createGroupingRequest extended operation is defined in section
   2.2.1 of [GROUPING].

   The createGroupType of the createGroupingRequestValue must be LDUP-
   OID.3.1.1. This OID represents the LDAP Replication grouping type.

   The createGroupValue of the createGroupingRequestValue must be set
   to the BER-encoding of the following:

         createGroupValue ::= createReplGroupReqValue

         createReplGroupReqValue ::= SEQUENCE {
             areaOfReplication      LDAPDN,
             replicaID              LDAPString,
             replicationProtocolOID LDAPOID,
             replicationInitiator   ENUMERATED
             {
                 supplier (0),
                 consumer (1)
             }
             replicaIDTable SEQUENCE OPTIONAL {
                 tableLength   INTEGER
                 table SEQUENCE OF SEQUENCE {
                     replicaID    LDAPString,
                     replicaUUID  LDAPString
                 }
             }
         }

   The parameters in the createGroupValue of the
   createGroupingRequestValue are:

      - areaOfReplication: the distinguished name of the
        areaOfReplicationSubentry object that 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] and [ENTRYUUID].
        To be more efficient in data transfer of the replication update
        protocol, each referenced replica is assigned an id that is

McMeeking               Expires September 2003                [Page 7]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

        protocol session-specific.  The replicaIDTable is used to map
        between the replicaID (used here and in ChangeSequenceNumber
        values in the protocol) and the UUID corresponding to the
        replicaSubEntry representing the replica.

      - replicationProtocolOID: OID of the replication protocol that
         should be used to transfer the updates.  This document
         describes two replication protocols:

            ietf-ldup-full-update          LDUP-OID.3.2.1
            ietf-ldup-incremental-update   LDUP-OID.3.2.2

        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 <supplier>,
        then the initiator is the supplier, and the receiver of this
        operation should prepare to receive a set of replication
        updates (or should reject the operation is replication updates
        are not permitted for some reason, perhaps due to access
        control restrictions).  If the replicationInitiator contains
        the enumerated value <consumer>, then the receiver should
        prepare to establish a supplier-initiated replication session
        with the consumer as soon as possible, updating the replicated
        area given by areaOfReplication and using the update protocol
        given by replicationProtocolOID.

      - replicaIDTable: used to set up a mapping of shorter "ids" to
        UUIDs of the replicaSubEntry entries that correspond to the
        ids.  These ids are used in the change sequence numbers sent
        over the replication update protocol instead of the full change
        sequence number (including the UUID).  This greatly reduces the
        data transfer requirements of the update replication protocol.

6.2.   createGroupingResponse Extended Response

   The createGroupingResponse extended response is sent in response to
   a createGroupingRequest extended operation.

   For a supplier-initiated session, the createGroupingResponse
   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 createGroupingResponse extended response
   containing a success code and the consumer's replica update vector.

McMeeking               Expires September 2003                [Page 8]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

   If the consumer is unwilling or unable to accept updates, it sends a
   createGroupingResponse extended response containing an error code.

   For a consumer-initiated session, the createGroupingResponse
   extended response 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
   createGroupingResponse extended response with a success code. If the
   supplier is unwilling or unable to send updates to the consumer, it
   sends a createGroupingResponse extended response containing an error
   code. In both cases, the consumer unbinds and disconnects from the
   supplier. If the supplier sent a success code to the consumer, the
   supplier opens a connection to the consumer as soon as possible and
   initiates a supplier-initiated replication session.

   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 createGroupingResponse extended response is defined in section
   2.2.2 of [GROUPING].

   The createGroupCookie of the createGroupingResponseValue will
   contain a cookie uniquely identifying this instance of the LDAP
   Replication grouping type created as a result of the
   createGroupRequest corresponding to this response. This cookie will
   be used in subsequent operations in this replication session.

   The createGroupValue of the createGroupingResponseValue is set to
   the BER-encoding of the following:

         createGroupValue ::= createReplGroupRespValue

         createReplGroupRespValue ::= SEQUENCE {
             replicaUpdateVector   Attribute OPTIONAL,
         }

   The LDAP response codes applicable to this response are defined in
   section 9.

   The replicaUpdateVector contains a replica update vector, as defined
   in [INFOMOD]. The update vector is encoded as a normal LDAP
   attribute, defined in [LDAPv3].




McMeeking               Expires September 2003                [Page 9]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

6.3.   ReplicationUpdate Extended Operation

   The ReplicationUpdate extended operation carries a set of
   replication primitives that represent the changes necessary to bring
   a single entry to a desired final state.

   The ReplicationUpdate extended operation is defined as follows:

   An LDAPv3 Extended Request is defined in [LDAPv3] as follows:

         ReplicationUpdate ::= [APPLICATION  23] SEQUENCE {
            requestName    [0] LDAPOID,
            requestValue   [1] OCTET STRING
         }

   The requestName of the ReplicationUpdate is the OID LDUP-OID.3.3.1.

   The requestValue of the ReplicationUpdate is set to the BER-encoding
   of the following:

         requestValue ::= replicationUpdateRequestValue

         replicationUpdateRequestValue ::= SEQUENCE {
            uniqueID  UniqueIdentifier,
            updates   SET OF ReplicationPrimitive
         }

   Each ReplicationUpdate extended operation MUST be accompanied by a
   groupingControl control identifying the replication session to which
   the ReplicationUpdate operation belongs. The groupingControl control
   is defined in section 2.7 of [GROUPING]. The groupingCookie of the
   groupingControlValue contains the group cookie returned in the
   createGroupingResponse. The groupValue of the groupingControlValue
   is not present.

6.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

   Unique identifiers are also known as UUIDs in this document.  Values
   for UUIDs are taken from an entry's 'entryUUID' operational
   attribute [ENTRYUUID].


McMeeking               Expires September 2003               [Page 10]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

6.3.2.   ReplicationPrimitive


   A ReplicationPrimitive carries a single assertion about changes
   necessary to bring about 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 a ChangeSequenceNumber that is used by the
   consumer server to correctly resolve update conflicts. [URP]
   describes the update reconciliation procedures.

6.3.2.1.  AddEntryPrimitive

   The AddEntryPrimitive is used to add a new entry.

         AddEntryPrimitive ::= [APPLICATION 0] SEQUENCE {
            csn         ChangeSequenceNumber,
            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.

6.3.2.2.  MoveEntryPrimitive

   The MoveEntryPrimitive is used to move an entry to a new location in
   the DIT.


McMeeking               Expires September 2003               [Page 11]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

         MoveEntryPrimitive ::= [APPLICATION 1] SEQUENCE {
            csn       ChangeSequenceNumber,
            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.

6.3.2.3.  RenameEntryPrimitive

   The RenameEntryPrimitive is used to change the RDN of an entry.

         RenameEntryPrimitive ::= [APPLICATION 2] SEQUENCE {
            csn   ChangeSequenceNumber,
            rdn   RelativeLDAPDN
         }

   Parameters of the RenameEntryPrimitive are:

      - csn: The change sequence number of the primitive.

      - rdn: The new relative distinguished name of the entry.

6.3.2.4.  RemoveEntryPrimitive

   The RemoveEntryPrimitive is used to delete an entry from the DIT.

         RemoveEntryPrimitive ::= [APPLICATION 3] SEQUENCE {
            csn  ChangeSequenceNumber
         }

   Parameters of the RemoveEntryPrimitive are:

      - csn: The change sequence number of the primitive.

6.3.2.5.  AddAttributeValuePrimitive

   The AddAttributeValuePrimitive is use to add a new attribute value
   to an entry.

         AddAttributeValuePrimitive ::= [APPLICATION 4] SEQUENCE {
            csn     ChangeSequenceNumber,
            type    AttributeDescription,
            value   AttributeValue
         }
McMeeking               Expires September 2003               [Page 12]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol


   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.

   Multiple added values are represented multiple primitives.

6.3.2.6.  RemoveAttributeValuePrimitive

   The RemoveAttributeValuePrimitive is used to remove a particular
   attribute value from an entry.

         RemoveAttributeValuePrimitive ::= [APPLICATION 5] SEQUENCE {
            csn      ChangeSequenceNumber,
            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.

   Multiple removed values are represented using multiple primitives.

6.3.2.7.  RemoveAttributePrimitive

   The RemoveAttributePrimitive is used to remove an attribute and all
   its values from an entry.

         RemoveAttributePrimitive ::= [APPLICATION 6] SEQUENCE {
            csn    ChangeSequenceNumber,
            type   AttributeDescription
         }

   Parameters of the RemoveAttributePrimitive are:

      - csn: The change sequence number of the primitive.

      - type: The type of the attribute being removed.
McMeeking               Expires September 2003               [Page 13]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol


6.4.   endGroupingRequest Extended Operation

   The endGroupingRequest 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 endGroupingRequest 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 endGroupingRequest extended operation is defined in section
   2.3.1 of [GROUPING].

   The endGroupCookie of the endGroupingRequestValue must be the cookie
   identifying this instance of the LDAP Replication grouping type.

   The endGroupValue of the endGroupingRequestValue must be set to the
   BER-encoding of the following:

         endGroupValue ::= endReplGroupReqValue

         endReplGroupReqValue ::= SEQUENCE {
            returnConsumerUpdateVector BOOLEAN,
            replicaUpdateVector        Attribute OPTIONAL
         }

   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.

6.5.   endGroupingResponse Extended Response

   The endGroupingResponse extended response is sent by a consumer to a
   supplier in response to an endGroupingRequest extended operation.

   The endGroupingResponse extended response is defined in section
   2.3.2 of [GROUPING].

   The endGroupValue of the endGroupingResponseValue must be set to the
   BER-encoding of the following:

         endGroupValue ::= endReplGroupRespValue

         endReplGroupRespValue ::= SEQUENCE {
             replicaUpdateVector    Attribute OPTIONAL
McMeeking               Expires September 2003               [Page 14]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

         }

   The replicaUpdateVector contains the consumer's current replica
   update vector, and is optional. The consumer server MUST send the
   replicaUpdateVector if requested by the supplier server in the
   EndReplicationRequest extended operation.

6.6.   ReplicationUpdateResponse Extended Response

   The ReplicationUpdateResponse extended response is sent in response
   to each ReplicationUpdate extended request.

   The responseName of the ReplicationUpdateResponse is the
   ReplicationUpdate extended request OID.

   The response field of the ReplicationUpdateResponse is not used.

   LDAP response codes that apply to the ReplicationUpdateResponse are
   defined in section 9.

6.7.   ReplicationUpdateNotice Extended Response

   The ReplicationUpdateNotice is an LDAP unsolicited notification sent
   by a consumer to a supplier when the consumer wishes to inform the
   supplier of committed results or tell the supplier to stop sending
   updates.  The notice is an extended response where:

   The responseName of the ReplicationUpdateNotice is the OID LDUP-
   OID.3.3.2.

   The response field of the ReplicationUpdateNotice is set to the BER-
   encoding of the following:

         response ::= replicationUpdateNotice

         replicationUpdateNotice ::= SEQUENCE {
            replicaUpdateVector  Attribute OPTIONAL
            abortUpdate          BOOLEAN OPTIONAL DEFAULT FALSE
         }

   The parameters of the ReplicationUpdateNotice are:

      - replicaUpdateVector: 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"].
      - abortUpdate: an optional Boolean flag.  If a supplier receives
        a ReplicationUpdateNotice 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.

McMeeking               Expires September 2003               [Page 15]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol


   Each ReplicationUpdateNotice extended response MUST be accompanied
   by a groupingControl control identifying the replication session to
   which the ReplicationUpdateNotice applies. The groupingControl
   control is defined in section 2.7 of [GROUPING]. The groupingCookie
   of the groupingControlValue contains the group cookie returned in
   the createGroupingResponse. The groupValue of the
   groupingControlValue is not present.

7.  Semantics of Full and Incremental Update protocols

   The full and incremental update protocols are very similar.  In the
   full update protocol, the replication session is initiated in the
   same manner as prescribed above for either supplier-initiated or
   consumer-initiated replication.  In the full update protocol, the
   consumer's update vector is assumed to be set to times "earlier
   than" the oldest times known to the supplier server.  The supplier
   server then begins by sending addEntryPrimitive protocol elements
   for each entry in the replication area, starting from the top of the
   tree and moving deeper into the tree.  If any entry's attributes
   have been modified since the add operation,
   addAttributeValuePrimitive and removeAttributeValuePrimitive
   operations are also sent to bring the consumer's view of an entry
   (including change sequence number information) up to date with the
   supplier's knowledge about each entry.

   The order of entries sent SHOULD be:

      - "highest" entries in the tree sent prior to "lower" entries
        (ancestors sent before parents).
      - replication topology "subentries" sent prior to any other
        entries in the DIT, sent in a "breadth-first" order
      - other entries in the DIT, sent in a "breadth-first" order

   This order allows "ancestor" entries to be seen by the consumer
   before child entries, thus reducing the chances that the
   lostAndFound entry will need to be used during processing of a full
   update protocol.

   A incremental update replication session SHOULD be requested by the
   consumer shortly after the completion of the full update replication
   session to ensure a timely update of entries in the replica for
   updates made while the full replication protocol was taking place.

   In the incremental update protocol, note that it is desirable that
   within an entry, update replication primitives are sent in change
   sequence number order (per replica on which the change was made) to
   reduce the processing on the consumer side.  While this is not
   required, it is recommended.



McMeeking               Expires September 2003               [Page 16]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

8.  Semantics of the LDAP Replication Grouping Type

   In addition to the operational semantics in section 4 of [GROUPING]
   that are applicable to all grouping types, the following semantics
   apply to the LDAP Replication grouping type:

      - The LDAP Replication grouping type MUST NOT be nested.

      - Operations that do not belong to the current instance of the
        LDAP Replication grouping type SHALL NOT be sent between the
        createGroupingRequest and the receipt of the
        endGroupingResponse.  In effect, this means that a replication
        session (as framed by the createGroupingRequest and its
        corresponding endGroupingRequest) has exclusive use of the LDAP
        connection.

9.  Summary of response codes

   The following list describes the response codes that may be included
   in the createGroupingResponse and ReplicationUpdateResponse extended
   responses.

       resultCode  ENUMERATED {
           success                           (0),
           operationsError                   (1),
           protocolError                     (2),
           insufficientAccessRights         (50),
           busy                             (51),
           excessiveCSNSkew    ([IANA-assigned]),
           other                            (80)
       }

   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.

McMeeking               Expires September 2003               [Page 17]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

10. Security Considerations

   Given the authority necessarily granted to perform replication and
   the sensitive nature of data that is replicated, replication SHOULD
   be done using an authentication method and security layer that
   protects the authentication credentials and ensures both the
   integrity and confidentiality of the replicated data [AUTHMETH].

   Error message returned is listed as 'permission denied' regardless
   of why request couldn't be performed, e.g. so that a client cannot
   discover what replicas exist or identity that cannot perform
   replication.

11. IANA Considerations

   This document lists several values that are to be assigned by or
   registered with IANA.

   The following LDAP result code is to be assigned by IANA as
   described in section 3.6 of [RFC3383]:

      excessiveCSNSkew

   The following Object Identifier [OID] is to be assigned by IANA as
   described in section 3.1 of [RFC3383]:

      LDUP-OID

   This OID is used by various LDUP documents to generate OID for
   object classes, attribute types, control and extended requests as
   follows:

      - [INFOMOD] generates OIDs from the OID arc LDUP-OID.1.

      - [MRM] generates OIDs from the OID arc LDUP-OID.2.

      - This document generates OIDs from the OID arc LDUP-OID.3.

   The following LDAP protocol elements are to be registered with IANA
   as described in section 3.2 of [RFC3383].

   Name                            Type  OID
   ------------------------------  ----  -------------
   LDAP Replication Grouping Type  G     LDUP-OID.3.1.1
   ReplicationUpdate               E     LDUP-OID.3.3.1

   Legend:
   -------
   E => supportedExtension
   G => supportedGroupingType


McMeeking               Expires September 2003               [Page 18]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

12. Acknowledgements

   The author would like to thank previous authors of this document,
   Gordon Good, America Online, Roger Harrison, Novell, Inc., Ellen
   Stokes and Timothy Hahn, IBM Corporation, and members of the LDUP
   working group for their significant contributions to this document.

13. References

   [ARCHITECTURE]
     J. Merrells, E. Reed, U. Srinivasan, "LDAP Replication
     Architecture", Internet-Draft, draft-ietf-ldup-model-xx.txt, a
     work in progress.

   [AUTHMETH]
     Wahl, M., Alvestrand, H., Hodges, J. and R. Morgan,
     "Authentication Methods for LDAP", RFC 2829, May 2000.

   [CSN]
     J. Sermersheim, "The LDAP Change Sequence Number Syntax and
     Matching Rules", Internet-Draft, draft-sermersheim-ldap-csn-
     xx.txt, a work in progress.

   [ENTRYUUID]
     K. Zeilenga, "The LDAP entryuuid operational attribute", Internet-
     Draft, draft-zeilenga-ldap-uuid-xx.txt, a work in progress.

   [GROUPING]
     K. Zeilenga, "LDAPv3: Grouping of Related Operations", Internet-
     Draft, draft-zeilenga-ldap-grouping-xx.txt, a work in progress.

   [INFOMOD]
     R. Huber, J. McMeeking, R. Moats, "LDAP Replication Information
     Model", Internet-Draft, draft-ietf-ldup-infomod-xx.txt, a work in
     progress.

   [KEYWORDS]
     S. Bradner, "Key Words for use in RFCs to Indicate Requirement
     Levels", Harvard University, RFC 2119, March 1997.

   [LDAPv3]
     M. Wahl, S. Kille, T. Howes, "Lightweight Directory Access
     Protocol (v3)", RFC 2251, December 1997.

   [MRM]
     R. Moats, R. Huber, J. McMeeking, "Mandatory LDAP Replica
     Management", Internet-Draft, draft-ietf-ldup-mrm-xx.txt, a work in
     progress.




McMeeking               Expires September 2003               [Page 19]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

   [REQ]
     E. Stokes, R. Weiser, R. Moats, R. Huber, "Lightweight Directory
     Access Protocol (version 3) Replication Requirements", RFC 3384,
     October 2002.

   [URP]
     S. Legg, A. Payne, "LDUP Update Reconciliation Procedures",
     Internet-Draft, draft-ietf-ldup-urp-xx.txt, a work in progress.

14. Author's Addresses

   John McMeeking
   IBM Corporation
   Rochester, MN
   USA
   Email: jmcmeek@us.ibm.com
   phone: +1 507 253 4596

15. Appendix A - Complete ASN.1 Definition

      createReplGroupReqValue ::= SEQUENCE {
          areaOfReplication      LDAPDN,
          replicaID              LDAPString,
          replicationProtocolOID LDAPOID,
          replicationInitiator   ENUMERATED
          {
              supplier (0),
              consumer (1)
          }
          replicaIDTable SEQUENCE OPTIONAL {
              tableLength   INTEGER
              table SEQUENCE OF SEQUENCE {
                  replicaID    LDAPString,
                  replicaUUID  LDAPString
              }
          }
      }

      createReplGroupRespValue ::= SEQUENCE {
          replicaUpdateVector   Attribute OPTIONAL,
      }

      replicationUpdateRequestValue ::= SEQUENCE {
          uniqueID  UniqueIdentifier,
          updates   SET OF ReplicationPrimitive
      }

      UniqueIdentifier ::= LDAPString

McMeeking               Expires September 2003               [Page 20]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol


      ReplicationPrimitive ::= CHOICE {
          addEntryPrimitive              AddEntryPrimitive,
          moveEntryPrimitive             MoveEntryPrimitive,
          renameEntryPrimitive           RenameEntryPrimitive,
          removeEntryPrimitive           RemoveEntryPrimitive,
          addAttributeValuePrimitive     AddAttributeValuePrimitive,
          removeAttributeValuePrimitive
                                         RemoveAttributeValuePrimitive,
          removeAttributePrimitive       RemoveAttributePrimitive
      }

      AddEntryPrimitive ::= [APPLICATION 0] SEQUENCE {
          csn         ChangeSequenceNumber,
          superior    UniqueIdentifier,
          rdn         RelativeLDAPDN
      }

      MoveEntryPrimitive ::= [APPLICATION 1] SEQUENCE {
          csn       ChangeSequenceNumber,
          superior  UniqueIdentifier
      }

      RenameEntryPrimitive ::= [APPLICATION 2] SEQUENCE {
          csn   ChangeSequenceNumber,
          rdn   RelativeLDAPDN
      }

      RemoveEntryPrimitive ::= [APPLICATION 3] SEQUENCE {
          csn  ChangeSequenceNumber
      }

      AddAttributeValuePrimitive ::= [APPLICATION 4] SEQUENCE {
          csn     ChangeSequenceNumber,
          type    AttributeDescription,
          value   AttributeValue
      }

      RemoveAttributeValuePrimitive ::= [APPLICATION 5] SEQUENCE {
          csn      ChangeSequenceNumber,
          type     AttributeDescription,
          value    AttributeValue
      }

      RemoveAttributePrimitive ::= [APPLICATION 6] SEQUENCE {
          csn    ChangeSequenceNumber,
McMeeking               Expires September 2003               [Page 21]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

          type   AttributeDescription
      }

      endReplGroupReqValue ::= SEQUENCE {
          returnConsumerUpdateVector BOOLEAN,
          replicaUpdateVector        Attribute OPTIONAL
      }

      endReplGroupRespValue ::= SEQUENCE {
          replicaUpdateVector    Attribute OPTIONAL
      }

      replicationUpdateNotice ::= SEQUENCE {
          replicaUpdateVector    Attribute OPTIONAL
          abortUpdate            BOOLEAN OPTIONAL DEFAULT FALSE
      }

16. Intellectual Property Notice

   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.

17. Copyright Information

   Full Copyright Statement

   Copyright (C) The Internet Society (2003).  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
McMeeking               Expires September 2003               [Page 22]

Internet Draft             LDUP Replication                 March 2003
                            Update Protocol

   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.

















































McMeeking               Expires September 2003               [Page 23]


Html markup produced by rfcmarkup 1.107, available from http://tools.ietf.org/tools/rfcmarkup/