[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.122, available from
https://tools.ietf.org/tools/rfcmarkup/