RFC 4373

Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP)

📅 published January 2006, from ietf

RFC 4373 🎀

okay bestie, this one is RFC 4373, and it's called Lightweight Directory Access Protocol (LDAP) Bulk Update/Replication Protocol (LBURP) ✨

  • Series: Network Working Group
  • Authors: R. Harrison, J. Sermersheim, and Y. Dong 💜 (the author block lists Novell, Inc.)
  • Category: Informational 🌸
  • Date: January 2006
  • Obsoletes / Updates: the header doesn't list any, so it doesn't obsolete or update another RFC 🧚

Status of This Memo 📜

okay so this memo is here to give info to the Internet community 🦋 It is not an Internet standard of any kind, and you can distribute it as much as you want ✨

The Internet Society owns the copyright here, and the year is 2006 🌈

Abstract 💖

so LBURP is the thing that lets an LDAP client do a bulk update to an LDAP server 🔥 The client wraps a numbered set of update operations inside a pair of LDAP extended operations, which tells the server that all those updates are connected, and that the order has to stay the same during processing even if the client sends them out of order over the wire 👑 The updates can also be bundled into one protocol message, which makes the client and server talk way more efficiently 💅

It's basically built for making a big pile of changes to the entries in an LDAP server, and it does that really well ✨

Table of Contents 🗂️

   1. Introduction ....................................................3
   2. Conventions Used in This Document ...............................3
   3. Overview of Protocol ............................................3
      3.1. Update Initiation ..........................................4
      3.2. Update Stream ..............................................4
           3.2.1. LBURPUpdateRequest ..................................4
           3.2.2. LBURPUpdateResponse .................................4
      3.3. Update Termination .........................................4
      3.4. Applicability of Protocol ..................................5
   4. Description of Protocol Flow ....................................5
   5. Elements of Protocol ............................................6
      5.1. StartLBURPRequest ..........................................7
           5.1.1. updateStyleOID ......................................7
      5.2. StartLBURPResponse .........................................7
           5.2.1. maxOperations .......................................8
      5.3. LBURPUpdateRequest .........................................8
           5.3.1. sequenceNumber ......................................8
           5.3.2. UpdateOperationList .................................9
      5.4. LBURPUpdateResponse ........................................9
           5.4.1. OperationResults ...................................10
                  5.4.1.1. operationNumber ...........................10
                  5.4.1.2. ldapResult ................................10
      5.5. EndLBURPRequest ...........................................10
           5.5.1. sequenceNumber .....................................10
      5.6. EndLBURPResponse ..........................................11
   6. Semantics of the Incremental Update Style ......................11
   7. General LBURP Semantics ........................................11
   8. Security Considerations ........................................12
   9. IANA Considerations ............................................13
      9.1. LDAP Object Identifier Registrations ......................13
   10. Normative References ..........................................14
   11. Informative References ........................................14

1. Introduction ✨

so LBURP came from a real need: letting an LDAP client send huge piles of updates to an LDAP server efficiently, and having the server process them efficiently too 🫶 It doesn't add a lot of brand-new stuff to LDAP, because the update requests the client sends just wrap up normal LDAP [RFC2251] update operations 🎀 The big win is that the client can send those updates asynchronously and the server still keeps everything in the right order 🔥 The server can also notice when a client is about to send a potentially massive batch and switch to a processing strategy that's built for that 👑

2. Conventions Used in This Document 📚

the imperative keywords defined in RFC 2119 [RFC2119] are used in this document, and they mean what RFC 2119 says they mean 💅

all Basic Encoding Rules (BER) [X.690] encodings follow the conventions found in section 5.1 of [RFC2251] 🧚

  • supplier is the word for an LDAP client, or an LDAP server acting as a client, that supplies a set of update operations to a consumer 🦋
  • consumer is the word for an LDAP server that consumes (aka processes) the ordered set of update operations a supplier sends it 🌸

3. Overview of Protocol 🗺️

LBURP frames a set of update operations inside a pair of LDAP extended operations, one marking the start and one marking the end of the update set 💖 Those updates go out in LDAP extended operations, and each one has a sequence number plus a list of one or more update operations for the consumer to perform 🔥 Even though they're grouped together as part of a bigger LDAP message, each subset of update operations is still encoded as normal LDAP update operations, using the LDAP Abstract Syntax Notation One (ASN.1) [X.680] message types from [RFC2251] 💅

3.1. Update Initiation 🚀

the protocol kicks off when a supplier sends a StartLBURPRequest extended operation to a consumer 🌈 That's the supplier saying "hey, a stream of associated LBURPUpdateRequests is coming." The supplier gives that stream its meaning by putting the Object Identifier (OID) of the bulk update/replication style inside the StartLBURPRequest ✨ The consumer answers the StartLBURPRequest with a StartLBURPResponse message 👑

3.2. Update Stream 🌊

after the consumer responds with a StartLBURPResponse, the supplier sends a stream of LBURPUpdateRequest messages to the consumer 💜 Messages in this stream can be sent asynchronously to make the transfer as efficient as possible 🔥 The consumer answers each LBURPUpdateRequest with an LBURPUpdateResponse message 🫶

3.2.1. LBURPUpdateRequest 📦

each LBURPUpdateRequest has a sequence number that says where it sits in the update stream, and an UpdateOperationList with an ordered list of LDAP update operations to apply to the Directory Information Tree (DIT) 🎀 The sequence number is what lets the consumer process the requests in the order the supplier sent them, even when they arrive asynchronously 🧚 The consumer handles each LBURPUpdateRequest by applying the LDAP update operations in its UpdateOperationList to the DIT, in the order they're listed 💅

3.2.2. LBURPUpdateResponse 📬

once the consumer has processed the update operations from an UpdateOperationList, it sends an LBURPUpdateResponse back to the supplier 🦋 That response says whether the update operations in the matching LBURPUpdateRequest succeeded or failed ✨

3.3. Update Termination 🏁

after the supplier has sent all of its LBURPUpdateRequest messages, it sends an EndLBURPRequest message to the consumer to close out the update stream 🌸 Once the consumer has serviced all the LBURPOperation requests and received the EndLBURPRequest, it replies with an EndLBURPResponse, and the update is done 🎉

3.4. Applicability of Protocol 🌍

LBURP is built to make bulk updates to LDAP servers easier 💖 It can also be used to sync directory information from a single master to multiple slaves 🔥

the protocol does not try to handle the problems that come with multiple-master replication environments, like keeping modification times of attribute values, so that updates to the same entry on different replicas can be correctly ordered 😭 Because of that, when LBURP alone is used for replication, data convergence across all replicas can only be assured in a single-master replication environment 💀

heads up bestie: if you're using LBURP for replication, only a single-master setup can promise that all your replicas end up with the same data 🙈

4. Description of Protocol Flow 🧭

this section walks through the LBURP protocol flow and the info in each message ✨ Throughout it, a client or server acting as a supplier is marked with "S", and a server acting as a consumer is marked with "C" 💜 The notation "S -> C" means the supplier is sending an LDAP message to the consumer, and "C -> S" means the consumer is sending one back to the supplier 🫶 The flow below assumes that a properly authenticated LDAP session is already set up between the supplier and consumer 🔐

here's the whole flow, verbatim:

       S -> C: StartLBURPRequest message.  The parameter is:

                  1) OID for the LBURP update style (see section 5.1.1).

       C -> S: StartLBURPResponse message.  The parameter is:

                  1) An optional maxOperations instruction
                     (see section 5.2.1).

       S -> C: An update stream consisting of zero or more
               LBURPUpdateRequest messages.  The requests MAY be sent
               asynchronously.  The parameters are:

                  1) A sequence number specifying the order of
                     this LBURPUpdateRequest with respect to the
                     other LBURPUpdateRequest messages in the update
                     stream (see section 5.3.1).

                  2) LBURPUpdateRequest.updateOperationList, a list
                     of one or more LDAP update operations (see section
                     5.3.2).

               The consumer processes the LBURPUpdateRequest messages
               in the order of their sequence numbers and applies the
               LDAP update operations contained within each
               LBURPUpdateRequest to the DIT in the order they are
               listed.

       C -> S: LBURPUpdateResponse message.  This is sent when the
               consumer completes processing the update operations
               from each LBURPUpdateRequest.updateOperationList.

       S -> C: EndLBURPRequest message.  This is sent after the
               supplier sends all of its LBURPUpdateRequest messages
               to the consumer.  The parameter is:

                  1) A sequence number that is one greater than the
                     sequence number of the last LBURPUpdateRequest
                     message in the update stream.  This allows the
                     EndLBURPRequest to also be sent asynchronously.

       C -> S: EndLBURPResponse message.  This is sent in response to
               the EndLBURPRequest after the consumer has serviced
               all LBURPOperation requests.

5. Elements of Protocol ✨

okay so LBURP only needs two LDAP ExtendedRequest messages to start and end the whole thing, StartLBURPRequest and EndLBURPRequest 🚀. Then there's a third one, LBURPUpdateRequest, which is how the supplier sends update operations over to the consumer 💌. Those three requests plus their responses are the entire protocol, no extras, no cap 💅

The LBURP request messages are built on the LDAP ExtendedRequest [RFC2251] like this:

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

The LBURP response messages are built on the LDAP ExtendedResponse [RFC2251] like this:

ExtendedResponse ::= [APPLICATION 24] SEQUENCE {
    COMPONENTS of LDAPResult,
    responseName  [10] LDAPOID OPTIONAL,
    response      [11] OCTET STRING OPTIONAL
}

5.1. StartLBURPRequest 🎬

the requestName for StartLBURPRequest is OID 1.3.6.1.1.17.1, so that's how you know it's the opener 🔑

its requestValue holds the BER-encoding of this ASN.1:

StartLBURPRequestValue ::= SEQUENCE {
    updateStyleOID LDAPOID
}

LDAPOID is defined in [RFC2251], section 4.1.2.

5.1.1. updateStyleOID 🏷️

the updateStyleOID is an OID that uniquely identifies which LBURP update style is being used 🪪 this doc only defines ONE update style that can go between the StartLBURPRequest and EndLBURPRequest, but the field is there for the future. like, a later spec could come along with a style that replaces every existing entry with a brand new set, and that style would only allow the Add operation 👀 iconic planning

the updateStyleOID for the LBURP Incremental Update style is 1.3.6.1.1.17.7. you can read how that style actually works in section 6 💖

5.2. StartLBURPResponse 💬

the responseName of StartLBURPResponse is OID 1.3.6.1.1.17.2 ✨

the optional response element holds the BER-encoding of this ASN.1:

StartLBURPResponseValue ::= maxOperations

maxOperations ::= INTEGER (0 .. maxInt)

maxInt INTEGER ::= 2147483647 -- (2^^31 - 1) --

5.2.1. maxOperations 🧮

when this is present, maxOperations tells the supplier to keep it to that many update operations per LBURPUpdateRequest.updateOperationList (see section 5.3.2) 🤏 if the consumer doesn't send a maxOperations value, the consumer MUST be prepared to accept any number of update operations per LBURPUpdateRequest.updateOperationList 🫶 the supplier MAY send fewer, but it MUST NOT send more than maxOperations update operations in a single LBURPUpdateRequest.updateOperationList 🚫 respect the limit, bestie

5.3. LBURPUpdateRequest 📦

the LBURPUpdateRequest message is how the supplier sends a set of zero or more LDAP update operations to the consumer 🚚 it also comes with sequencing info, so the consumer can keep multiple asynchronous LBURPUpdateRequest messages in the right order even when they show up out of line 🧩

the requestName of LBURPUpdateRequest is OID 1.3.6.1.1.17.5 🪧

the requestValue of an LBURPOperation holds the BER-encoding of this ASN.1:

LBURPUpdateRequestValue ::= SEQUENCE {
    sequenceNumber INTEGER (1 .. maxInt),
    updateOperationList UpdateOperationList
}

5.3.1. sequenceNumber 🔢

the sequenceNumber puts the associated LBURPOperation requests in order 📋 that way the consumer can process them in the exact order the supplier picked 🥰 the supplier MUST set the sequenceNumber of the first LBURPUpdateRequest to 1, and MUST increment the sequenceNumber by 1 for each request after that 📈 in the unlikely event the number of LBURPUpdateRequest messages goes past maxInt, a sequenceNumber of 1 is treated as the one that comes right after a sequence number of maxInt 🔄 a full circle moment 🌈

5.3.2. UpdateOperationList 📝

the UpdateOperationList is a list of one or more standard LDAP update requests, defined like this:

UpdateOperationList ::= SEQUENCE OF SEQUENCE{
    updateOperation CHOICE {
       addRequest       AddRequest,
       modifyRequest    ModifyRequest,
       delRequest       DelRequest,
       modDNRequest     ModifyDNRequest
    },
    controls       [0] Controls OPTIONAL
}

AddRequest, ModifyRequest, DelRequest, and ModifyDNRequest are defined in [RFC2251], sections 4.6, 4.7, 4.8, and 4.9.

the LDAP update requests in the UpdateOperationList MUST be applied to the DIT in the order they're listed 🗂️ order matters, no skipping ahead 💅

5.4. LBURPUpdateResponse 📬

an LBURPUpdateResponse is sent from the consumer back to the supplier to say that ALL the update operations from an LBURPUpdateRequest's UpdateOperationList are done 🎉 it also reports the results for those operations 📊

the responseName of LBURPUpdateResponse is OID 1.3.6.1.1.17.6 🪪

if the consumer server can't successfully decode an LBURPUpdateRequest in its entirety, the resultCode on the matching LBURPUpdateResponse gets set to protocolError, and the response element gets left out 🙅‍♀️ and in that situation, updates from that LBURPUpdateRequest SHALL NOT be committed to the DIT 🚫 nothing sneaks in half-baked

if every update operation being reported by an LBURPUpdateResponse came back as success, the resultCode of that response is set to success and the response element is left out ✅ clean and easy

if ANY of the update operations being reported came back as something other than success, the resultCode for the whole LBURPUpdateResponse is set to other, which signals that the response element is there 🔍

5.4.1. OperationResults 🗒️

when a response element is included in an LBURPUpdateResponse, it holds the BER-encoding of this ASN.1:

OperationResults ::= SEQUENCE OF OperationResult

OperationResult ::= SEQUENCE {
   operationNumber    INTEGER,
   ldapResult         LDAPResult
}

an OperationResult is included for each operation from the UpdateOperationList that failed during processing 💔 only the ones that failed get listed

5.4.1.1. operationNumber 🔖

the operationNumber identifies the LDAP update operation from the UpdateOperationList of the LBURPUpdateRequest that failed 🕵️‍♀️ operations are numbered starting at 1

5.4.1.2. ldapResult 🧾

the ldapResult inside an OperationResult is the same ldapResult that would've been sent for the failed update operation if it had failed as a normal LDAP update operation 🥹 same energy, same result. LDAPResult is defined in [RFC2251], section 4.1.10.

5.5. EndLBURPRequest 🏁

the requestName of EndLBURPRequest is OID 1.3.6.1.1.17.3 🎀

its requestValue holds the BER-encoding of this ASN.1:

EndLBURPRequestValue::= SEQUENCE {
    sequenceNumber INTEGER (1 .. maxInt)
}

5.5.1. sequenceNumber 🔚

the value in sequenceNumber is ONE greater than the last LBURPUpdateRequest.sequenceNumber in the update stream 🧠 it lets the server know when it has received ALL the outstanding asynchronous LBURPUpdateRequests, so nothing's left hanging 🫡

5.6. EndLBURPResponse 🌙

the responseName of EndLBURPResponse is OID 1.3.6.1.1.17.4 🦋

there is no response element in the EndLBURPResponse message. simple, clean, done ✨

6. Semantics of the Incremental Update Style 🌸

the initial state of entries in the consumer's DIT, plus the LBURPUpdateRequest messages in the update stream, together add up to the desired final state of the consumer's DIT 🧮💜 every LDAP update operation defined in [RFC2251] is allowed in the incremental update stream: Add, Modify, Delete, and Modify DN 🎯 and all the usual semantics of those operations still apply. so for example, trying to add an entry that already exists will fail, the same way it would in a normal LDAP Add operation 🙃 no sneaky exceptions

7. General LBURP Semantics 💫

the consumer server can take whatever action it needs to process the updates efficiently 🏃‍♀️💨 the only rule is that the final state has to match what you'd have gotten if the updates in the stream were applied to the DIT with normal LDAP update operations 🤝

the LBURPUpdateRequest messages that make up the update stream MAY be sent asynchronously by the supplier to the consumer 🌊 that means the supplier doesn't have to wait for an LBURPUpdateResponse for one LBURPUpdateRequest before it sends the next one 🏎️

when the LBURP update stream contains a request that affects multiple Directory System Agents (DSAs), the consumer MAY choose to perform the request or return a resultCode value of affectsMultipleDSAs 🧩 and just like any LDAP operation, a consumer MAY send a resultCode value of referral as part of the OperationResult element for any operation on an entry it doesn't contain 👉 if the consumer is set up to do so, it MAY chain on behalf of the supplier to finish the update operation instead 🔗

while a consumer server is processing an LBURP update stream, it may choose not to service LDAP requests on other connections 🙈 this is there so implementers have the freedom to build super-efficient ways of handling the stream, without being stuck keeping a live, working DIT database running the whole time 🏋️‍♀️

if a consumer chooses to refuse LDAP operation requests from other suppliers during an LBURP update, it is RECOMMENDED that the consumer refer those requests to another server that has the right data to complete the operation 💁‍♀️ be helpful, bestie

unless attribute values specifying timestamps are included as part of the update stream, updates made using LBURP are treated the same as other LDAP operations, meaning they're deemed to occur at the present ⏰ a consumer MAY store timestamp values sent by suppliers, but it isn't required to 📅

implementations may choose to perform the operations in the update stream with special permissions to improve performance 🚀

consumer implementations should include functionality to detect and terminate connections on which an LBURP session has been initiated but the information needed to complete it (such as the EndLBURPRequest) is never received ⏳ a timeout is one mechanism that can be used to do this 🧯 no ghosting allowed 👻

8. Security Considerations 🔒✨

Okay bestie, security is where things get seriously dramatic, so read this part carefully 💅. Implementations should make sure that a supplier sending an LBURP request is properly authenticated and authorized to make the updates it asks for. Making updates to the DIT without proper authorization can cause data loss, and that's a real risk 😭.

If you use LBURP for replication, note that it's different from other replication protocols because no existing replication agreement between supplier and consumer is required 🙈. The risks get higher if the consumer server also processes the update stream with special permissions to speed things up. So implementers should think hard about which permissions an LBURP operation should require, and take steps to make sure only connections with appropriate authorization are allowed to perform them 🔐.

The data in the update stream may include passwords and other sensitive stuff, so take care to protect it while it's in transit between supplier and consumer 🫶. One mechanism that can be used to provide data confidentiality and integrity for this purpose is the StartTLS [RFC2830] operation.

As with any asynchronous LDAP operation, an LBURP supplier might be able to send asynchronous LBURPUpdateRequest messages to the consumer faster than the consumer can process them. Consumer implementers should take steps to stop LBURP suppliers from interfering with the normal operation of a consumer server by flooding it with a rapid stream of asynchronous LBURPUpdateRequest messages 🚨.

9. IANA Considerations 🧚

Registration of the following values has been made by the IANA [RFC3383].

9.1. LDAP Object Identifier Registrations 🌸

The IANA has registered LDAP Object Identifiers that identify the protocol elements defined in this technical specification. The following registration template was provided:

Subject: Request for LDAP OID Registration
Person & email address to contact for further information:
    Roger Harrison
    rharrison@novell.com
Specification: RFC 4373
Author/Change Controller: IESG
Comments:
Seven delegations will be made under the assigned OID.  The
following 6 OIDs are Protocol Mechanism OIDs of type "E"
(supportedExtension):

1.3.6.1.1.17.1 StartLBURPRequest LDAP ExtendedRequest message
1.3.6.1.1.17.2 StartLBURPResponse LDAP ExtendedResponse message
1.3.6.1.1.17.3 EndLBURPRequest LDAP ExtendedRequest message
1.3.6.1.1.17.4 EndLBURPResponse LDAP ExtendedResponse message
1.3.6.1.1.17.5 LBURPUpdateRequest LDAP ExtendedRequest message
1.3.6.1.1.17.6 LBURPUpdateResponse LDAP ExtendedResponse message

The following 1 OID is a Protocol Mechanism OID of type "F"
(supportedFeature):

1.3.6.1.1.17.7 LBURP Incremental Update style OID

10. Normative References 📚

[RFC2119]  Bradner, S., "Key Words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

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

[RFC3383]  Zeilenga, K., "Internet Assigned Numbers Authority (IANA)
           Considerations for the Lightweight Directory Access
           Protocol (LDAP)", BCP 64, RFC 3383, September 2002.

[X.680]    ITU-T Recommendation X.680 (07/2002) | ISO/IEC 8824-1:2002
           "Information Technology - Abstract Syntax Notation One
           (ASN.1): Specification of basic notation"

[X.690]    ITU-T Rec. X.690 (07/2002) | ISO/IEC 8825-1:2002,
           "Information technology - ASN.1 encoding rules:
           Specification of Basic Encoding Rules (BER), Canonical
           Encoding Rules (CER) and Distinguished Encoding Rules
           (DER)", 2002.

11. Informative References 💜

[RFC2830]  Hodges, J., Morgan, R., and M. Wahl, "Lightweight
           Directory Access Protocol (v3): Extension for Transport
           Layer Security", RFC 2830, May 2000.

Authors' Addresses 🎀

Roger Harrison
Novell, Inc.
1800 S. Novell Place
Provo, UT 84606

Phone: +1 801 861 2642
EMail: rharrison@novell.com


Jim Sermersheim
Novell, Inc.
1800 S. Novell Place
Provo, UT 84606

Phone: +1 801 861 3088
EMail: jimse@novell.com


Yulin Dong

EMail: yulindong@gmail.com

Copyright (C) The Internet Society (2006).

This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.

This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property 🦋

The IETF takes no position on the validity or scope of any Intellectual Property Rights or other rights that might be claimed to apply to the implementation or use of the technology described in this document, or on the extent to which any license under such rights might or might not be available. It also doesn't claim to have made any independent effort to identify any such rights. Info on the procedures for rights in RFC documents can be found in BCP 78 and BCP 79.

Copies of IPR disclosures made to the IETF Secretariat, any assurances of licenses to be made available, or the result of an attempt to get a general license or permission for implementers or users to use these proprietary rights can be obtained from the IETF on-line IPR repository at:

http://www.ietf.org/ipr

The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology needed to implement this standard. Please send that information to the IETF at:

ietf-ipr@ietf.org

Acknowledgement 🫶

Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). 💖

📦 where this page comes from