Internet DRAFT - draft-ldapext-khan-replica-mgmt
draft-ldapext-khan-replica-mgmt
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", <draft-ietf-ldapext-ldap-c-api-
04.txt>, 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
