Network Working Group Javed Khan Steven Sonntag Internet Draft Novell, Inc. Document: draft-khan-ldapext-replica-mgmt-00.txt January 2001 Category: Informational LDAP Extensions for Managing Replication Context and Replicas Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet- Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 1. Abstract Version 3 of the LDAP Protocol provides a mechanism for sending and receiving extended LDAP requests. This document describes twelve extended operations supported by Novell eDirectory Servers. A client application can use these extensions to manage directory replication contexts (partitions) and replicas. 2. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [1]. 3. Introduction Version 3 of the LDAP Protocol provides a mechanism for sending and receiving extended LDAP requests. This document describes twelve extensions supported by Novell Inc.Æs eDirectory servers (version 8.5). These extensions can be used for performing replication Khan Informational û Expires July 2001 1 January 2001 context (partition) and replica management operations. A replication context as referred to in this document is the same as the eDirectory partition object. Each replication context is identified in this document by its root most entry. The ASN.1 format for an extended request as defined in [3] is shown below: ExtendedRequest ::= [APPLICATION 23] SEQUENCE { requestName [0] LDAPOID, requestValue [1] OCTET STRING OPTIONAL } Each extension uses its own OID and an ASN.1 encoded requestValue. The ASN.1 encoding and the corresponding OID for each of these extended requests is described in the remainder of this document. Similarly the ASN.1 for an extended response as defined in [3] is shown below ExtendedResponse ::= [APPLICATION 24] SEQUENCE { COMPONENTS OF LDAPResult, responseName [10] LDAPOID OPTIONAL, responseValue [11] OCTET STRING OPTIONAL } Each extension uses its own response OID and an ASN.1 encoded responseValue. The ASN.1 encoding and corresponding OID for each extended response is described in the remainder of this document. 4. Overview of Extended Requests A typical exchange between an application and an LDAP server that supports these extensions will involve the following steps. The APIÆs referred to in the following few lines are defined in [4]. 1. Application initializes an LDAP session with an LDAP server. The ldap_init() function returns a handle to the session. 2. The application authenticates to the LDAP server. The ldap_bind() function and friends support a variety of authentication methods. 3. The application MAY call standard LDAP V3 operations such as ldap_search, ldap_add or any combination of those. 4. The application calls the ldap_extended_operation requests with the appropriate requestValue (an OCTET STRING) and requestName(an OCTET STRING representing the OID). The LDAP server returns a responseName (an OCTET STRING representing an OID) and an optional responseValue (an OCTET STRING). Khan Informational û Expires July 2001 2 January 2001 5. The application closes the session with a call to the ldap_unbind() function. 5. Replication Context Management operations This section describes extended operations for manipulating replication contexts. 5.1 Creating a new replication context This extension creates a new LDAP replication context at the specified entry. The entry specified must be a container object. Set the requestName field to the string 2.16.840.1.113719.1.27.100.3. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { flags REPLICAFLAGS, dn LDAPDN } The parameters in the requestValue field are: flags: This parameter is an enumeration that can take one of the two integer values as described in section 8.1. dn: The distinguished name of the entry which will be at the root of the new replication context. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.4 There is no responseValue returned. 5.2 Deleting a replication context This extension merges a child replication context into its parent replication context. Set the requestName field to the string 2.16.840.1.113719.1.27.100.5. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { flags REPLICAFLAGS, dn LDAPDN } Khan Informational û Expires July 2001 3 January 2001 The parameters in the requestValue field are: flags: This parameter is an enumeration that can take one of the two integer values as described in section 8.1. dn: The root of the replication context which will be merged with its parent. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.6 There is no responseValue returned. 5.3 Counting objects in a replication context This extension returns the number of entries in the specified replication context. Set the requestName field to the string 2.16.840.1.113719.1.27.100.13. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { dn LDAPDN } The parameters in the requestValue field are: dn: The distinguished name of the root of the replication context. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.14. The responseValue field will contain the BER encoded value of the following ASN.1: responseValue ::= SEQUENCE { count INTEGER } The parameters in the responseValue field are: count: A count of the number of entries in the specified partition. 6. Replica Management operations This section describes extended operations for manipulating replicas. Khan Informational û Expires July 2001 4 January 2001 6.1 Adding a replica to specific server This extension adds a replica of the specified replication context onto the specified directory server. Set the requestName field to the string 2.16.840.1.113719.1.27.100.7. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { flags REPLICAFLAGS, replicaType REPLICATYPE, serverName LDAPDN, dn LDAPDN } The parameters in the requestValue field are: flags: This parameter is an enumeration that can take one of the two integer values as described in section 8.1. replicaType: The type of replica to add. Replica types are explained in Section 8.2. serverName: The distinguished name of the server on which to add the replica. dn: The distinguished name of the entry at the root of the replication context. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.8. There is no responseValue returned. 6.2 Deleting a replica from a specific server This extension removes a replica from the specified directory server. Set the requestName field to the string 2.16.840.1.113719.1.27.100.11. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { flags REPLICAFLAGS, serverName LDAPDN, dn LDAPDN } The parameters in the requestValue field are: Khan Informational û Expires July 2001 5 January 2001 flags: This parameter is an enumeration that can take one of the two integer values as described in section 8.1. serverName: The distinguished name of the server from which to remove the replica. dn: The distinguished name of the entry at the root of the replication context. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.12. There is no responseValue returned. Master replicas as described in Section 8.2 cannot be removed from the directory server. 6.3 Changing a replica type This extension changes the type of the specified replica on the specified directory server. Set the requestName field to the string 2.16.840.1.113719.1.27.100.15. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { flags REPLICAFLAGS, replicaType REPLICATYPE, serverName LDAPDN, dn LDAPDN } The parameters in the requestValue field are: flags: This parameter is an enumeration that can take one of the two integer values as described in section 8.1. replicaType: The new replica type. Replica types are explained in Section 8.2. serverName: The distinguished name of the server entry on which to change the replica type dn: The distinguished name of the root of the replication context. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.16. There is no responseValue returned. 6.4 Getting replica information Khan Informational û Expires July 2001 6 January 2001 This extension returns information about the specified replica on the specified directory server. Set the requestName field to the string 2.16.840.1.113719.1.27.100.17. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { serverName LDAPDN, dn LDAPDN } The parameters in the requestValue field are: serverName: The distinguished name of the server on which the replica resides. dn: Distinguished name of the replication context for which information is being requested. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.18. The responseValue field will contain the BER encoded value of the following ASN.1: responseValue ::= SEQUENCE { partitionID INTEGER, replicaState REPLICASTATE, modificationTime INTEGER, purgeTime INTEGER, localPartitionID INTEGER, partitionDN LDAPDN, replicaType REPLICATYPE, partitionBusy BOOLEAN } The parameters in the responseValue field are: partitionID: A unique id of the partition on the specified server. replicaState: The current state of the replica. Replica states are further explained in Section 8.3. modificationTime: This parameter is a timestamp of the last time the replica was modified. The returned integer represents the seconds since Jan 1, 1970. purgeTime: The last time the replica was purged. The returned integer represents the seconds since Jan 1, 1970. localPartitionID: The local id of the partition. Khan Informational û Expires July 2001 7 January 2001 partitionDN: The distinguished name of the replication context. replicaType: The type of the replica. Replica types are explained in Section 8.2. partitionBusy: A boolean value indicating whether the replica is currently busy performing another partitioning operation. 6.5 Listing all replicas on a specified server This extension returns a list of all the replicas on the specified directory server. Set the requestName field to the string 2.16.840.1.113719.1.27.100.19. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { serverName LDAPDN } The parameters in the requestValue field are: serverName: Distinguished name of the server. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.20. The responseValue field will contain the BER encoded value of the following ASN.1: responseValue ::= SEQUENCE { replicaList SEQUENCE OF LDAPDN } The parameters in the responseValue field are: replicaList: Distinguished names of all replicas that reside on the specified server. 7. Replica and Schema synchronization operations This section describes extended operations that can be used to trigger various replication and schema synchronization events on directory servers. 7.1 Refreshing a specific replica Khan Informational û Expires July 2001 8 January 2001 This extension forces a complete refresh of a replica (specified by the partitionRoot parameter) located on the specified directory server (specified by the toServerDN parameter) from another directory server (specified by the fromServerDN parameter). Set the requestName field to the string 2.16.840.1.113719.1.27.100.21. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { partitionRoot LDAPDN, toServerDN LDAPDN, fromServerDN LDAPDN } The parameters in the requestValue field are: partitionRoot: The distinguished name of the root of the replication context. toServerDN: The distinguished name of the server which contains the replica to be refreshed. fromServerDN: The distinguished name of the server from which replica content will be sent. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.22. There is no responseValue returned. 7.2 Refreshing all replicas This extension forces the directory server (specified by the origServerDN parameter) to send a copy of the replica (specified by the partitionRoot parameter) to all other servers holding a copy of that replication context. Set the requestName field to the string 2.16.840.1.113719.1.27.100.23. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { partitionRoot LDAPDN, origServerDN LDAPDN } The parameters in the requestValue field are: partitionRoot: The distingusished name of the root of the replication context. Khan Informational û Expires July 2001 9 January 2001 origServerDN: the distinguished name of the server entry from which replica content will be sent. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.24. There is no responseValue returned. 7.3 Request Replication Context Synchronization This extension forces the specified server to synchronize the specified replication context with all other servers holding a copy of the replication context. Set the requestName field to the string 2.16.840.1.113719.1.27.100.25. Set the requestValue field to the BER encoded value of the following ASN.1: requestValue ::= SEQUENCE { ServerName OCTET STRING, partitionRoot OCTET STRING, delay INTEGER } The parameters in the requestValue field are: serverName: The distinguished name of the server being synchronized. partitionRoot: The distinguished name of the root of the replication context. delay: The delay in seconds after which the replication should be initiated. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.26. There is no responseValue returned. 7.4 Schedules Schema Synchronization This extension schedules a schema synchronization event. Schema updates will be sent out from the specified directory sever after a specified number of seconds. Set the requestName field to the string 2.16.840.1.113719.1.27.100.27. Set the requestValue field to the BER encoded value of the following ASN.1: Khan Informational û Expires July 2001 10 January 2001 requestValue SEQUENCE { serverName LDAPDN, delay INTEGER } The parameters in the requestValue field are: serverName: The distinguished name of the server from which schema updates are sent. delay: The delay in seconds after which the replication should be initiated. Upon return the responseName field has a value of 2.16.840.1.113719.1.27.100.28. There is no responseValue returned. 8. Description of parameters This section describes some of the new parameter types defined in request and response packets. 8.1 REPLICAFLAGS parameter A flag value of 1 requires that each server holding a copy of the replication context is up and running for this operation to proceed. Otherwise the operation fails. Setting the flag to 0 does not require all servers to be running and proceeds with the particular operation. Servers that are not up will perform the operation after they become operational. REPLICAFLAGS ENUMERATED { noflags (0), allserversup (1) } 8.2 REPLICATYPE parameter The REPLICATYPE parameter identifies one of the six-supported replica types. A detailed description of each of these replica types is beyond the scope of this text. Please see eDirectory documentation for a detailed description of each of these. REPLICATYPE ENUMERATED { master (0), secondary (1), readonly (2), subreference (3), sparsewrite (4), sparseread (5) } Khan Informational û Expires July 2001 11 January 2001 A master replica for a replication context MUST exist on one and only one server. A sparse replica is a replica that contains only a subset of attributes and classes defined in the schema. 8.3 REPLICASTATE parameter The REPLICASTATE parameter identifies state that the replica is in. At any given time a replica is in one of the following four states depending on operations that might be in progress. REPLICASTATE ENUMERATED { on (0), new (1), dying (2), locked (3) } new: A recently created replica will be typically stay in the new state until it receives initial updates form other replicas in the ring. on: After the replica has been created it enters the on state and will spend most of its life cycle in this state. locked: Certain eDirectory operations i.e. partitioning require that the replica be locked while the operation completes. The duration for which the replica will be locked depends on the number of objects in the replica. dying: A replica that has recently been deleted stays in this state while the delete operation completes. 9. LDAP Error Codes The extended operation request returns valid LDAP V3 return result codes. 10. Security Considerations The server implementation of the extensions must use the same credentials (or identity) as was supplied during the bind request. 11. References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [2] M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight Directory Access Protocol: Attribute Syntax Definitions", RFC 2252, December 1997 [3] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access Protocol (v3)", RFC 2251, December 1997. Khan Informational û Expires July 2001 12 January 2001 [4] M. Smith, T. Howes, A. Herron, M. Wahl, A. Anantha, "The C LDAP Application Program Interface", , 8 October 1999. 12. Acknowledgments The authors wish to thank Jim Sermersheim and Alan Clark for taking the time to review this document. 13. Author's Addresses Javed Khan Novell, Inc. 1800 South Novell Place M/S-PRV-H-533 Provo UT-84606 Phone: 801 861 2794 Email: jkhan@novell.com Steven Sonntag Novell, Inc. 1800 South Novell Place M/S-PRV-H-533 Provo UT-84606 Phone: 801 861 7097 Email: vtag@novell.com Khan Informational û Expires July 2001 13 January 2001 Full Copyright Statement "Copyright (C) The Internet Society (date). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implmentation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assigns. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society. Khan Informational û Expires July 2001 14