Subject: Re: I-D ACTION:draft-ietf-ldup-framing-profile-00.txt

From: Ryan Moats <[email-masked]>
Date: Tue, 13 Nov 2001 12:51:33 -0600

I-D editor:

please insert the following (below '...===cuthere')
as draft-ietf-ldup-mrm-00.txt.

LDUP:

Here's -00 of Mandatory LDAP Replica Management.  Many thanks to Mark
and Ed for the initial text.  A lot of this document is still TBD
(as you will see), but we wanted to get something in the repository
for SLC and we've fleshed out enough of it for us to ask the WG
for consensus on the following issues.

1. In Section 4.5, do we need the ability to copy (i.e. read and set) all
operational attributes as part of this operation? If so, LDAP will need
a change.

2. Section 4.6 currently requires that all replicaSubentries representing the
same server have the same entryUUID.  How is this accomplished?

3. Section 5.1.1 posits some out-of-band transport for the initial copy
of the source server.  Is LDIF appropriate for this transport?  If so,
how do we carry replication meta-data (e.g. CSNs)?

4. Should the operations in section 5.12 be condensed into a single extended
operation? The rationale behind an extended operation is that this should
be a mechanical process.  Having a mechanism to "replicate" this from one
server to the others:
- reduces likelihood of missing something
- allows replication framework to ensure that this information gets to
  every server in the event that a server is down or so

Enjoy
Ryan Moats (for the authors)

=============================cut here

Internet-Draft                                               Ryan Moats 
LDAP Duplication/Replication/Update                Lemur Networks, Inc. 
Protocols WG                                                 Rick Huber 
Intended Category: Standard                           AT&T Laboratories 

Expires May 2002                                         John McMeeking 
                                                                    IBM 
                                                          November 2001 

                   Mandatory LDAP Replica Management 
                 Filename: draft-ietf-ldup-mrm-00.txt 

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/lid-abstracts.txt. 
 
The list of Internet-Drafts Shadow Directories can be accessed at 
http://www.ietf.org/shadow.html. 
 
Copyright Notice 
 
Copyright (C) The Internet Society (2000). All Rights Reserved. 
 
Abstract 
 
The goal of standards for LDAP replication is to allow interoperable 
replication among products from many different vendors.  Defining the 
mechanism to move data among replicas is a necessary part of this work, 
but management of the replicated environment must also be standardized 
for replication to be truly interoperable. 
 
This document presents the replication management functions that must 
be performed.  Whenever possible, these functions are defined in terms 
of existing LDAP functionality using existing LDAP operations and 
existing data definitions.  In some cases, changes or additions to the 
existing model are requires, and specifications for these changes are 
included in this document. 

Moats, et al               Expires May 2002                    [Page 1] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
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 [RFC2119]. 
 
1  Table of Contents 

Status of this Memo...................................................1 
Abstract..............................................................1 
1 Table of Contents ..................................................2 
2 Introduction .......................................................3 
3 Administrative Precursors ..........................................4 
4 Operational "Atoms" ................................................4 
 4.1  Create replicaContext on a single server .......................5 
 4.2  Delete replicaContext from a single server .....................5 
 4.3  Add area of replication to a server ............................5 
 4.4  Delete area of replication from a server .......................6 
 4.5  Copy base of area of replication between servers ...............6 
 4.6  Create server entry in area of replication .....................6 
 4.7  Delete Server Entry for an area of replication .................7 
 4.8  Modify replica .................................................7 
  4.8.1  Change Replica Type .........................................7 
  4.8.2  Change Between Full/Partial Replica .........................7 
  4.8.3  Change Replica URI for one server for one area of replication
         7 
 4.9  Add Replication Agreement ......................................7 
 4.10   Delete Replication Agreement .................................8 
 4.11   Modify Replication Agreement .................................8 
 4.12   Suspend Replication ..........................................8 
 4.13   Resume Replication ...........................................8 
 4.14   Trigger an Immediate Replica Cycle ...........................8 
5 Common Tasks .......................................................8 
 5.1  Add a new replica to an existing replica group .................9 
  5.1.1  Large area of replication support ...........................9 
 5.2  Set up (but do not start) replication between two servers ......9 
 5.3  Set up (but do not start) replication between a server and an 
 existing replica group ..............................................9 
 5.4  Verify replication information is present between two servers ..9 
 5.5  Start replication between two servers. .........................9 
 5.6  Start replication between an existing replica group and a new 
 server ..............................................................9 
 5.7  Temporarily Suspend all replication activity from a given server
      9 
 5.8  Halt replication on all areas of a server ......................9 
 5.9  List status of a particular area of replication on a given 
 server ..............................................................9 
 5.10   List all areas of replication defined on a given server and 
 their status .......................................................10 
 5.11   Restore a server and replication agreements after a server 
 crash  10 
 5.12   Split an Area of Replication ................................10 
 5.13   Move an existing area of replication to a new server ........10 
 5.14   Join two Areas of Replication ...............................10 
  5.14.1   Preconditions ............................................10 
 
Moats, et al               Expires May 2002                    [Page 2] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
  5.14.2   Procedure ................................................10 
  5.14.3   Server requirements ......................................11 
 5.15   Stop Replicating an Area of Replication. ....................11 
 5.16   Suspending and Resuming Replication .........................12 

 5.17   Convert a read-only replica to an updateable replica ........12 
 5.18   Changing Replica URI on all servers handling an area of 
 replication ........................................................12 
 5.19   Postpone a Replica Cycle to a Later Time ....................12 
 5.20   Examine Replication Audit History on a Server ...............12 
 5.21   Compare Two Replicas on Two Servers for Differences .........12 
 5.22   Fix an Entry Without Triggering Replication .................12 
 5.23   Check Reported Schema Mismatches Discovered During Replication
        13 
 5.24   Adding a new directory server to a replica group and 
 initializing the contents ..........................................13 
 5.25   Restore from the master failure in a single-master system ...13 
6 Formal Specifications .............................................13 
 6.1  New/Modified Object Classes ...................................13 
 6.2  New/Modified Attributes .......................................13 
 6.3  New/Modified Extended Operations ..............................13 
 6.4  New/Modified Replication Primitives ...........................14 
7 Security Considerations ...........................................14 
8 Acknowledgements ..................................................14 
9 References ........................................................14 
Author's Addresses:..................................................15 
Full Copyright Statement.............................................15 

2  Introduction 
 
In the LDAP replication architecture [Arch], the LDAP servers and 
replication agreements between them are represented by entries in the 
directory tree, as part of the replicated naming context.  The LDAP 
replication information model [InfoMod] describes the contents of these 
entries. 
 
Replication management entries, such as replicaSubentries or 
replication agreements, can be altered on any updateable replica. These 
entries are implicitly included in the directory entries governed by 
any agreement associated with this area of replication.  As a result, 
all servers with a replica of an area of replication will have access 
to information about all other replicas of that area of replication and 
associated agreements. 
 
The deployment and maintenance of a replicated directory network 
involves the creation and management on the replicas themselves and 
associated replication control information (e.g. replicationSubentries 
and replication agreements).  This document outlines the administrative 
actions necessary to create and maintain replication agreements.  
 
Typically, administrative tools will guide the administrator and 
facilitate these actions. 

Moats, et al               Expires May 2002                    [Page 3] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
3  Administrative Precursors 
In this document the term "administrative user" refers to an identity 
that will be performing replication configuration by binding to and 
invoking operations on directory servers.  Most LDAP server 
implementations have the concept of a superuser or power user, however 
this need not be the same as the administrative user, so long as the 
administrative user has been granted appropriate privileges. The 
administrative user MAY be running as an autonomous process, and MUST 
be capable of securely maintaining its own credentials. 
 
Servers SHOULD support the concept of there being multiple 
administrative users, and SHOULD allow each to have distinct rights 
from the others. 
 
Deployments SHOULD create an administrative user identity that is 
granted access to all servers holding a replica of a naming context to 
perform the procedures described below, in particular to read the root 
DSE, the replicationContext prefix entry and all subordinate 
subentries. The administrative user who will be viewing or modifying 
the replication status MUST have already been provided with and 
established in the directory server or servers appropriate 
authentication credentials and authorization rights to retrieve 
attributes and invoke DIT modification operations that are beyond the 
ability of the 'average' directory user. 
 
Through out-of-band means one of the following will have occurred: 
 
  1. 
     the administrative user and the directory server have agreed upon 
     a shared secret which the administrator will use to authenticate 
     itself, or 
  2. 
     the administrative user will have a certificate that can be 
     validated by the directory server. 
 
Note that the secret in the first case need not be held by the 
directory server itself but could be maintained by an authentication 
service trusted by the directory server. 
 
4  Operational "Atoms" 
 
The following operational atoms are used to build up more complex tasks 
in section 5. 
 
Most of these operational "atoms" make the following assumptions: 
 
Through prior LDAP or out-of-band means the administrative user MUST 
have been granted the following access control permissions to the 
directory in order to establish replication: 
 
  -Modify the attribute 'replicaContextRoots' of the root DSE by 
     adding values 
  -Create the naming context prefix entry 

Moats, et al               Expires May 2002                    [Page 4] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
  -Create subentries immediately below the naming context prefix 
     entry 
 
In several sections below, we refer to "source" and "target" servers. 
The "source" server is a server that already holds a copy of the area 
of replication.  It may already be replicating that area with other 
servers.  The "target" server does not currently hold a copy of the 
area of replication.  The "target" is being added to the replica-group.  
 
Issue: Any write or modify being done to a readOnly replica requires 
some thought. 
 
Issue: Whether each of these atoms is propagated by replication and how 
it impacts the replication process. 
 
4.1 Create replicaContext on a single server 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the empty string (naming the root DSE), and the modification list 
consists of a single item to add the distinguished name of the context 
prefix to the attribute replicaContextRoots.  If the server responds 
with the resultCode attributeOrValueExists, then the value is already 
there.  If the server responds with a resultCode other than 
attributeOrValueExists or success, then this is an error. 
 
4.2 Delete replicaContext from a single server 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the empty string  (naming the root DSE), and the modifications list 
consists of a single item, to delete the value of the distinguished 
name of the context prefix from the attribute replicaContextRoots.  If 
 
the server responds with the resultCode noSuchAttribute, then the value 
has already been removed.  If the server responds with a resultCode 
other than noSuchAttribute or success, then this is an error. 
 
4.3 Add area of replication to a server 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the context prefix of the replication context, and the modification 
list consists of a single item to add the value replicationContext to 
the attribute objectClass.  If the server responds with the resultCode 
attributeOrValueExists, then the value is already there.  If the server 
responds with a resultCode other than attributeOrValueExists or 
success, then this is an error.  Should an error occur at this point, 
the server is in an inconsistent state and needs to be fixed.  
 
After this step is completed, the server will begin storing change 
information for this area of replication.  
 
WG ISSUE: If replicaContextRoots were an operational attribute, then it 
would be possible to have the server maintain that attribute when 
replicationContext is added or deleted.  Without it, these steps need 

Moats, et al               Expires May 2002                    [Page 5] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
to be separate LDAP protocol operations and thus it is possible to have 
inconsistent states. 
 
4.4 Delete area of replication from a server 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the context prefix of the replication context, and the modification 
list consists of a single item to remove the value replicationContext 
to the attribute objectClass.  If the server responds with the 
resultCode noSuchAttribute, then the value has already been removed.  
If the server responds with a resultCode other than noSuchAttribute or 
success, then this is an error.   
 
After this step is completed, the server will no longer replicate this 
area of replication. 
 
4.5 Copy base of area of replication between servers 
In this section, the 'target server' is the server on which the client 
has just modified the root DSE. 
 
The client MUST separately contact another server, one that already 
holds a copy of this replication context, and issue a SearchRequest on 
that server in which the baseObject is the DN of the of base the area 
of replication, the scope baseObject, the filter "(objectClass=*)" and 
the attributes list "*".  If the client cannot obtain the single entry 
at this point, the procedure will fail, and the client SHOULD invoke on 
the slave server a ModifyRequest in which the object field is the empty 
string, and the modifications list consists of a single item, a delete 
of the attribute replicaContextRoots with the value the distinguished 
name of the context prefix. 
 
WG Issue: Do we need the ability to copy (i.e. read and set) all 
operational attributes as part of this operation? If so, LDAP will need 
a change. 
 
Now that it has the entry, the client SHOULD invoke an AddRequest on 
the target server with entry set to the DN of the base of the area of 
replication and attributes the same list as obtained in the previous 
search. 
 
If the server returns a resultCode other than success, it is an error, 
and the server will be in an inconsistent state. 
 
4.6 Create server entry in area of replication 
 
Each server needs to have in its copy of the area of replication a 
replicaSubentry for each of the servers involved in replicating that 
area before replication can be started. These entries MUST have the 
following attributes: 
 
1.   objectclass, with values top, ldapSubentry and replicaSubentry 
2.   cn 
3.   replicaURI 
 
Moats, et al               Expires May 2002                    [Page 6] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
4.   replicaType 
5.   replicaOnline 
 
and MAY contain other attributes, as described in the Information Model 
[InfoMod]. 
 
WG Issue: This requires that all replicaSubentries representing the 
same server have the same entryUUID.  How is this accomplished? 
 
4.7 Delete Server Entry for an area of replication 
 
The client SHOULD issue a SearchRequest in which the baseObject is the 
DN of the context prefix, the scope oneLevel, the filter 
"(objectClass=replicaSubentries)" and the attributes list. For each 
entry returned, the client SHOULD then issue a DeleteReques in which 
the object field is the DN of the entry.   If the server responds with 
the resultCode noSuchObject, then the entry has already been removed.  
If the server responds with a resultCode other than noSuchObject or 
success, then this is an error. 
 
4.8 Modify replica 
 
4.8.1     Change Replica Type 
 
Note: This section covers only the simple protocol operation to change 
the replica type. Section 5.17 coverts the full set of operations for 
converting from a ReadOnly to an Updateable replica. 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the replicationSubentry, and the modification list consists of a single 
item to change the value of the attribute replicaType.  If the server 
responds with the resultCode attributeOrValueExists, then the value is 
already there.  If the server responds with a resultCode other than 
attributeOrValueExists or success, then this is an error.  
 
4.8.2     Change Between Full/Partial Replica 
 
TBD 
 
4.8.3     Change Replica URI for one server for one area of replication 
 
Note: This section covers only the simple protocol operation to change 
the replica type. Section 5.18 covers the full set of operations for 
changing the replica URI on all servers. 
 
The client SHOULD invoke a ModifyRequest in which the object field is 
the replicationSubentry, and the modification list consists of a single 
item to change the value of the attribute replicaURI to the new value.  
If the server responds with the resultCode attributeOrValueExists, then 
the value is already there.  If the server responds with a resultCode 
other than attributeOrValueExists or success, then this is an error. 
 
4.9 Add Replication Agreement 
 
TBD 
Moats, et al               Expires May 2002                    [Page 7] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
4.10 Delete Replication Agreement 
 
The termination of replication agreements should be done with caution 
as it can easily result in a partition of the directory servers if 
performed incorrectly. 
 
Once all replication agreements have been terminated between a server 
and others for a naming context, then that copy of the context on the 
server will be divergent, and any updates made there will not be 
propagated to any other server. 
 
TBD 
 
4.11 Modify Replication Agreement 
 
TBD 
 
4.12 Suspend Replication 
The client SHOULD invoke a ModifyRequest in which the object field is 
the DN of the target replicationSubentry, and the modification list 
consists of a single item to change the value of replicaOnline 
attribute to false. If the server responds with the resultCode 
attributeOrValueExists, then the value is already there.  If the server 
responds with a resultCode other than attributeOrValueExists or 
success, then this is an error. 
 
4.13 Resume Replication 
The client SHOULD invoke a ModifyRequest in which the object field is 
the DN of the target replicationSubentry, and the modification list 
consists of a single item to change the value of replicaOnline 
attribute to true. If the server responds with the resultCode 
attributeOrValueExists, then the value is already there.  If the server 
responds with a resultCode other than attributeOrValueExists or 
success, then this is an error.  
 
4.14 Trigger an Immediate Replica Cycle 
 
TBD 
 
Issue: An administrative client could trigger an immediate replication 
cycle by issuing a "Trigger Replication" extended operation to the 
supplier server.  The extended operation value specifies the DN of a 
replication agreement between the supplier and target replicas, and the 
type of replication session to be performed (full update or incremental 
update).  The replication agreement is used to specify the target 
replica, connection information, and authentication information. 
 
5  Common Tasks 
There are many tasks that administrators need to perform in a 
replicated environment.  This section describes many typical tasks and 
describes how they are performed in terms of the atoms defined above. 

Moats, et al               Expires May 2002                    [Page 8] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
5.1 Add a new replica to an existing replica group 
 
TBD 
 
5.1.1     Large area of replication support 
 
In some cases, an area of replication is so large or available 
bandwidth so small that out-of-band mechanisms (e.g. mailing a tape) 
need to be used to transport the initial copy from the source to the 
target.  The target then needs to be updated with changes made to the 
source since the copy was made.  This section describes how this 
situation is handled. 
 
Details TBD. 
 
WG Issue: is LDIF appropriate for this transport?  If so, how do we 
carry replication meta-data (e.g. CSNs)? 
 
5.2 Set up (but do not start) replication between two servers 
 
TBD 
 
5.3 Set up (but do not start) replication between a server and an 
    existing replica group 
 
TBD 
 
5.4 Verify replication information is present between two servers 
 
TBD 
 
5.5 Start replication between two servers. 
 
For this operation, the client SHOULD follow the steps in Section 5.2 
followed by starting replication as specified in Section 4.13. 
 
5.6 Start replication between an existing replica group and a new 
    server 
For this operation, the client SHOULD follow the steps in Section 5.3 
followed by starting replication as specified in Section 4.13. 
 
5.7 Temporarily Suspend all replication activity from a given server 
 
TBD  
 
5.8 Halt replication on all areas of a server 
 
TBD 
 
5.9 List status of a particular area of replication on a given server 
 
TBD 
 
Moats, et al               Expires May 2002                    [Page 9] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
 
5.10 List all areas of replication defined on a given server and their 
    status 
 
TBD 
 
5.11 Restore a server and replication agreements after a server crash 
 
TBD 
 
5.12 Split an Area of Replication 
 
To split an area of replication, the atoms are: 
1.   Add the subordinate area of replication to the servers' 
     replicaContextRoots (Section 4.1) 
2.   Add the replicationContext objectclass to the root entry of the 
     area of replication (Section 4.3) 
3.   Create replicaSubentry objects under the new area of replication 
     for each replica of the parent area of replication (Section 4.6) 
4.   Create replicaAgreement objects (and schedules?) under the new 
     replicaSubentries, where agreements are created that correspond to 
     each agreement defined for the parent (Section 4.9). 
These operations must be performed on each server containing a replica 
of the parent area of replication.   
 
WG Issue: Extended op or not? The rationale behind an extended 
operation is that this should be a mechanical process.  Having a 
mechanism to "replicate" this from one server to the others: 
- reduces likelihood of missing something 
- allows replication framework to ensure that this information gets to 
  every server in the event that a server is down or some other error 
  prevents the client from completing all of these operations. 
 
5.13 Move an existing area of replication to a new server  
 
TBD 
 
5.14 Join two Areas of Replication 
 
This section describes how to join two areas of replication. 
 
5.14.1    Preconditions 
 
Before joining two areas of replication there are certain preconditions 
that need to be satisfied: 
1.   Any server that contains a replica of one area of replication must 
     also contain a replica of the other area of replication. This may 
     require copying either area of replication to additional servers, 
     or deleting either area of replication from servers. 
2.   The replicas on any given server MUST be of the same type.  Both 
     replicas must be updateable, both-readonly, or both primary.  
     Furthermore, if the replicas are readonly, they must both be full 
     replicas, or must both be fractional replicas with identical 
     fractional entry specifications. 
 
5.14.2    Procedure 

Moats, et al               Expires May 2002                   [Page 10] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
1. On each server, delete the replicationContext objectclass value from 
  the subordinate area of replication (Section TBD). 
   
  We'd like this to be replicated under the parent area of replication, 
  and we'd like this to have the affect of causing all not yet 
  replicated updates and future client changes as if they occurred 
  under the parent area f replication.  This is going to cause problems 
  with respect to CSNs if there are "old" changes in the subordinate 
  context.  Maybe we require that there be no pending updates?  This is 
  going to be potentially ugly. 
2. 
  Delete all replication agreements for the subordinate area of 
  replication 
3. 
  Delete all replicaSubentries for the subordinate area of replication 
 
5.14.3    Server requirements 
 
When the replicationContext objectclass is removed from the root of an 
area of replication, the server MUST immediately treat entries within 
the area of replication as belonging to the parent area of replication 
(if there is any).  This includes replicating any pending replication 
updates (those not yet replicated to other replicas) as if they 
occurred under the parent area of replication, as well as preserving 
any Lost and Found entries. 
 
If a server receives a request to delete the replicationContext from an 
area of replication, and there is a parent area of replication, the 
Server MUST verify that these replicas are of the same type, and if 
fractional, that the fractional entry specifications are identical.  If 
the replicas are not of the same type, the request MUST be failed with 
resultCode unwillingToPerform. 
 
5.15 Stop Replicating an Area of Replication. 
 
This section describes how to stop replicating an area of replication.  
At the end of the procedure, the subtree represented by the area of 
replication will exist on one server, all replication agreements will 
have been deleted, and the root of the area of replication will no 
longer be an area of replication.  The server on which the subtree will 
remain is referred to as the surviving replica.   
To stop replicating an area of replication, a client with 
administrative authority should perform the following operations: 
 
1.   Halt replication 
 
After halting, the client MAY optionally delete information by: 
 
2.   Delete all replication agreements (Section 4.10). 
3.   Delete all replicaSubentries under the area of replication 
     (section 4.7)  
4.   Issue a modifyRequest to the surviving server where the object 
     field is the DN of the area of replication, and the modifications 
     list consists of a single item, delete the attribute objectclasss 
     with value replicationContext. 
 
Moats, et al               Expires May 2002                   [Page 11] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
5.   Delete replicaContext from that server (Section 4.2) 
6.   Delete the area of replication from servers containing other 
     replicas (Section 4.4). 
 
Note that client updates accepted on the non-surviving replicas during 
this procedure may be lost (because they were not replicated to the 
surviving server). 
 
5.16 Suspending and Resuming Replication 
 
To suspend replication of an area of replication to a specific server, 
an administrative client can perform a modifyRequest of the 
replicaSubentry, with a modification list replacing the replicaOnline 
attribute with the value false.   Performing this request on the 
specified server causes the server to stop accepting or initiating 
replication requests for that area of replication.  This procedure can 
also be performed on any other replica.  The modifyRequest will be 
replicated to other servers.  When a server other than that specified 
by the replicaSubentry receives the request the server MUST stop 
sending replication updates to the specified server.  The unsent 
changes MUST be saved until the replicaOnline attribute is chnaged to 
true.  Servers MUST continue to repond to replication updates sent from 
the specified server. 
 
To resume replication of an area of replication to a specific server, 
an administrative client can perform a modifyRequest of the 
replicaSubentry, with a modification list replacing the replicaOnline 
attribute with the value false.   This request must be performed on the 
specified server, or it will not resume replication.  This operation 
may also be performed on other servers. 
 
5.17 Convert a read-only replica to an updateable replica 
 
TBD 
 
5.18 Changing Replica URI on all servers handling an area of 
    replication 
 
The client issues this request to the server whose address has been 
changed, which replicates it to the other replicas like other client 
updates.  It may be necessary to issue the same request to other 
replicas, for example, when the server does not have proper replication 
agreements to fully replicate this change (as in consumer initiated 
replication). 
 
5.19 Postpone a Replica Cycle to a Later Time 
 
TBD 
 
5.20 Examine Replication Audit History on a Server 
 
TBD 
 
5.21 Compare Two Replicas on Two Servers for Differences 
 
TBD 
 
5.22 Fix an Entry Without Triggering Replication 
 
When conflicts cause entries to be put in the Lost+Found area, the 
administrator needs a mechanism to make appropriate changes.  These 
Moats, et al               Expires May 2002                   [Page 12] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
changes should not trigger replication since they are used to fix 
previous replication problems.  In addition, these changes may include 
fixes to UUIDs, CSNs, or other control data that cannot be changed 
using normal LDAP operations. 
 
TBD 
 
5.23 Check Reported Schema Mismatches Discovered During Replication 
 
TBD 
 
5.24 Adding a new directory server to a replica group and initializing 
    the contents 
 
In this case, the client: 
 
1. Creates the replicaContext on the new server (section 4.1) 
2. Copies the base entry for the area of replication from a source to 
the target (section 4.5) 
3. 
  Create the entries for the new server on all servers in the replica 
  group (section 4.6) 
4. 
  Create the entries for the existing replica group servers on the new 
  (section 4.6) 
5. 
  Create the replication agreement on all servers (section 4.9) 
6. 
  Client issues a "Initiate Full Update" request to a full replica for 
  the new replica -- or new replica requests consumer initiated full 
  update 

5.25 Restore from the master failure in a single-master system 
 
TBD 
 
6  Formal Specifications 
 
The Replica Management features depend heavily on defined LDAP and LDUP 
structure, operations, and data formats.  But some changes will be 
needed to accommodate Replica Management.  All these changes are pulled 
together in this section for easy reference. 
 
6.1 New/Modified Object Classes 
 
TBD 
 
6.2 New/Modified Attributes 
 
TBD 
 
6.3 New/Modified Extended Operations 
 
Trigger Replica Operation 
 
TBD 

Moats, et al               Expires May 2002                   [Page 13] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
 
6.4 New/Modified Replication Primitives 
 
TBD 
 
7  Security Considerations 
 
In all cases, it is assumed that the client establishes a connection to 
the LDAP server and SHOULD authenticate using a recommended 
authentication method [RFC2829] that establishes the identity of the 
client user and SHOULD provide for connection integrity.  In 
deployments where the underlying network service is vulnerable to 
eavesdropping and clients are intending to retrieve sensitive server 
credentials, the chosen method SHOULD also provide for encryption of 
data in transit. 
 
In general, where the client is unaware of any network level protection 
services, it is RECOMMENDED that the client immediately after 
connection establishment invoke Start TLS to establish connection 
integrity and confidentiality, and follow this by authentication by one 
of: 
 
  - the "DIGEST-MD5" SASL mechanism, 
  - the "simple" authentication choice, or 
  - the "EXTERNAL" SASL mechanism if the client provided its  
     certificate during TLS establishment. 
 
The client MAY determine the supported authentication mechanisms of the 
server from the supportedSASLMechanisms attribute of the root DSE after 
Start TLS has been invoked, and use this to decide whether to use 
DIGEST-MD5 or EXTERNAL.  See [RFC2830] for more information on TLS. 
 
8  Acknowledgements 
 
Thanks to Mark Wahl and Ed Reed for providing a lot of the initial 
text. 
 
This document is a product of the LDUP Working Group of the IETF.  The 
contributions of its members are greatly appreciated. 
 
9  References 
[Arch] J. Merrells, E. Reed, U. Srinvasan, "LDAP Replication 
Architecture", draft-ietf-ldup-model-01.txt. 
 
[InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf-
ldup-infomod-00.txt 
 
[RFC2119] S. Bradner, "Key Words for Use in RFCs to Indicate 
Requirement Levels", RFC 2119, March 1997. 
 
[RFC2829] M. Wahl, H. Alvestrand, J. Hodges, RL Morgan, "Authentication 
Methods for LDAP", RFC 2829, May 2000. 

 
Moats, et al               Expires May 2002                   [Page 14] 


INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
[RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access 
Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 
2000. 
 
Author's Addresses: 
 
Ryan Moats 
Lemur Networks, Inc. 
Email: [email-masked] 
 
Rick Huber 
AT&T Laboratories 
Email: [email-masked] 
 
John McMeeking 
IBM 
Email: [email-masked] 
 
Full Copyright Statement 
 
Copyright (C) The Internet Society (2000).  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 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. 

Moats, et al               Expires May 2002                   [Page 15]

---

From: Ryan Moats <[email-masked]>
Date: Tue, 13 Nov 2001 13:09:14 -0600

Doh... lets try this with a correct subject...

On Tue, Nov 13, 2001 at 12:51:33PM -0600, Ryan Moats wrote:
| LDUP:
| 
| Here's -00 of Mandatory LDAP Replica Management.  Many thanks to Mark
| and Ed for the initial text.  A lot of this document is still TBD
| (as you will see), but we wanted to get something in the repository
| for SLC and we've fleshed out enough of it for us to ask the WG
| for consensus on the following issues.
| 
| 1. In Section 4.5, do we need the ability to copy (i.e. read and set) all
| operational attributes as part of this operation? If so, LDAP will need
| a change.
| 
| 2. Section 4.6 currently requires that all replicaSubentries representing the
| same server have the same entryUUID.  How is this accomplished?
| 
| 3. Section 5.1.1 posits some out-of-band transport for the initial copy
| of the source server.  Is LDIF appropriate for this transport?  If so,
| how do we carry replication meta-data (e.g. CSNs)?
| 
| 4. Should the operations in section 5.12 be condensed into a single extended
| operation? The rationale behind an extended operation is that this should
| be a mechanical process.  Having a mechanism to "replicate" this from one
| server to the others:
| - reduces likelihood of missing something
| - allows replication framework to ensure that this information gets to
|   every server in the event that a server is down or so
| 
| Enjoy
| Ryan Moats (for the authors)
| 
| 
| =============================cut here
| 
| 
| 
| 
| Internet-Draft                                               Ryan Moats 
| LDAP Duplication/Replication/Update                Lemur Networks, Inc. 
| Protocols WG                                                 Rick Huber 
| Intended Category: Standard                           AT&T Laboratories 
| 
| Expires May 2002                                         John McMeeking 
|                                                                     IBM 
|                                                           November 2001 
|  
|  
|                    Mandatory LDAP Replica Management 
|                  Filename: draft-ietf-ldup-mrm-00.txt 
|  
|  
| 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/lid-abstracts.txt. 
|  
| The list of Internet-Drafts Shadow Directories can be accessed at 
| http://www.ietf.org/shadow.html. 
|  
| Copyright Notice 
|  
| Copyright (C) The Internet Society (2000). All Rights Reserved. 
|  
| Abstract 
|  
| The goal of standards for LDAP replication is to allow interoperable 
| replication among products from many different vendors.  Defining the 
| mechanism to move data among replicas is a necessary part of this work, 
| but management of the replicated environment must also be standardized 
| for replication to be truly interoperable. 
|  
| This document presents the replication management functions that must 
| be performed.  Whenever possible, these functions are defined in terms 
| of existing LDAP functionality using existing LDAP operations and 
| existing data definitions.  In some cases, changes or additions to the 
| existing model are requires, and specifications for these changes are 
| included in this document. 
|  
|  
|  
| Moats, et al               Expires May 2002                    [Page 1] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 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 [RFC2119]. 
|  
| 1  Table of Contents 
|  
|  
| Status of this Memo...................................................1 
| Abstract..............................................................1 
| 1 Table of Contents ..................................................2 
| 2 Introduction .......................................................3 
| 3 Administrative Precursors ..........................................4 
| 4 Operational "Atoms" ................................................4 
|  4.1  Create replicaContext on a single server .......................5 
|  4.2  Delete replicaContext from a single server .....................5 
|  4.3  Add area of replication to a server ............................5 
|  4.4  Delete area of replication from a server .......................6 
|  4.5  Copy base of area of replication between servers ...............6 
|  4.6  Create server entry in area of replication .....................6 
|  4.7  Delete Server Entry for an area of replication .................7 
|  4.8  Modify replica .................................................7 
|   4.8.1  Change Replica Type .........................................7 
|   4.8.2  Change Between Full/Partial Replica .........................7 
|   4.8.3  Change Replica URI for one server for one area of replication
|          7 
|  4.9  Add Replication Agreement ......................................7 
|  4.10   Delete Replication Agreement .................................8 
|  4.11   Modify Replication Agreement .................................8 
|  4.12   Suspend Replication ..........................................8 
|  4.13   Resume Replication ...........................................8 
|  4.14   Trigger an Immediate Replica Cycle ...........................8 
| 5 Common Tasks .......................................................8 
|  5.1  Add a new replica to an existing replica group .................9 
|   5.1.1  Large area of replication support ...........................9 
|  5.2  Set up (but do not start) replication between two servers ......9 
|  5.3  Set up (but do not start) replication between a server and an 
|  existing replica group ..............................................9 
|  5.4  Verify replication information is present between two servers ..9 
|  5.5  Start replication between two servers. .........................9 
|  5.6  Start replication between an existing replica group and a new 
|  server ..............................................................9 
|  5.7  Temporarily Suspend all replication activity from a given server
|       9 
|  5.8  Halt replication on all areas of a server ......................9 
|  5.9  List status of a particular area of replication on a given 
|  server ..............................................................9 
|  5.10   List all areas of replication defined on a given server and 
|  their status .......................................................10 
|  5.11   Restore a server and replication agreements after a server 
|  crash  10 
|  5.12   Split an Area of Replication ................................10 
|  5.13   Move an existing area of replication to a new server ........10 
|  5.14   Join two Areas of Replication ...............................10 
|   5.14.1   Preconditions ............................................10 
|  
| Moats, et al               Expires May 2002                    [Page 2] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
|   5.14.2   Procedure ................................................10 
|   5.14.3   Server requirements ......................................11 
|  5.15   Stop Replicating an Area of Replication. ....................11 
|  5.16   Suspending and Resuming Replication .........................12 
| 
|  5.17   Convert a read-only replica to an updateable replica ........12 
|  5.18   Changing Replica URI on all servers handling an area of 
|  replication ........................................................12 
|  5.19   Postpone a Replica Cycle to a Later Time ....................12 
|  5.20   Examine Replication Audit History on a Server ...............12 
|  5.21   Compare Two Replicas on Two Servers for Differences .........12 
|  5.22   Fix an Entry Without Triggering Replication .................12 
|  5.23   Check Reported Schema Mismatches Discovered During Replication
|         13 
|  5.24   Adding a new directory server to a replica group and 
|  initializing the contents ..........................................13 
|  5.25   Restore from the master failure in a single-master system ...13 
| 6 Formal Specifications .............................................13 
|  6.1  New/Modified Object Classes ...................................13 
|  6.2  New/Modified Attributes .......................................13 
|  6.3  New/Modified Extended Operations ..............................13 
|  6.4  New/Modified Replication Primitives ...........................14 
| 7 Security Considerations ...........................................14 
| 8 Acknowledgements ..................................................14 
| 9 References ........................................................14 
| Author's Addresses:..................................................15 
| Full Copyright Statement.............................................15 
|  
|  
|  
| 2  Introduction 
|  
| In the LDAP replication architecture [Arch], the LDAP servers and 
| replication agreements between them are represented by entries in the 
| directory tree, as part of the replicated naming context.  The LDAP 
| replication information model [InfoMod] describes the contents of these 
| entries. 
|  
| Replication management entries, such as replicaSubentries or 
| replication agreements, can be altered on any updateable replica. These 
| entries are implicitly included in the directory entries governed by 
| any agreement associated with this area of replication.  As a result, 
| all servers with a replica of an area of replication will have access 
| to information about all other replicas of that area of replication and 
| associated agreements. 
|  
| The deployment and maintenance of a replicated directory network 
| involves the creation and management on the replicas themselves and 
| associated replication control information (e.g. replicationSubentries 
| and replication agreements).  This document outlines the administrative 
| actions necessary to create and maintain replication agreements.  
|  
| Typically, administrative tools will guide the administrator and 
| facilitate these actions. 
|  
|  
|  
| Moats, et al               Expires May 2002                    [Page 3] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 3  Administrative Precursors 
| In this document the term "administrative user" refers to an identity 
| that will be performing replication configuration by binding to and 
| invoking operations on directory servers.  Most LDAP server 
| implementations have the concept of a superuser or power user, however 
| this need not be the same as the administrative user, so long as the 
| administrative user has been granted appropriate privileges. The 
| administrative user MAY be running as an autonomous process, and MUST 
| be capable of securely maintaining its own credentials. 
|  
| Servers SHOULD support the concept of there being multiple 
| administrative users, and SHOULD allow each to have distinct rights 
| from the others. 
|  
| Deployments SHOULD create an administrative user identity that is 
| granted access to all servers holding a replica of a naming context to 
| perform the procedures described below, in particular to read the root 
| DSE, the replicationContext prefix entry and all subordinate 
| subentries. The administrative user who will be viewing or modifying 
| the replication status MUST have already been provided with and 
| established in the directory server or servers appropriate 
| authentication credentials and authorization rights to retrieve 
| attributes and invoke DIT modification operations that are beyond the 
| ability of the 'average' directory user. 
|  
| Through out-of-band means one of the following will have occurred: 
|  
|   1. 
     the administrative user and the directory server have agreed upon 
|      a shared secret which the administrator will use to authenticate 
|      itself, or 
|   2. 
     the administrative user will have a certificate that can be 
|      validated by the directory server. 
|  
| Note that the secret in the first case need not be held by the 
| directory server itself but could be maintained by an authentication 
| service trusted by the directory server. 
|  
| 4  Operational "Atoms" 
|  
| The following operational atoms are used to build up more complex tasks 
| in section 5. 
|  
| Most of these operational "atoms" make the following assumptions: 
|  
| Through prior LDAP or out-of-band means the administrative user MUST 
| have been granted the following access control permissions to the 
| directory in order to establish replication: 
|  
|   -Modify the attribute 'replicaContextRoots' of the root DSE by 
|      adding values 
|   -Create the naming context prefix entry 
|  
|  
|  
| Moats, et al               Expires May 2002                    [Page 4] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
|   -Create subentries immediately below the naming context prefix 
|      entry 
|  
| In several sections below, we refer to "source" and "target" servers. 
| The "source" server is a server that already holds a copy of the area 
| of replication.  It may already be replicating that area with other 
| servers.  The "target" server does not currently hold a copy of the 
| area of replication.  The "target" is being added to the replica-group.  
|  
| Issue: Any write or modify being done to a readOnly replica requires 
| some thought. 
|  
| Issue: Whether each of these atoms is propagated by replication and how 
| it impacts the replication process. 
|  
| 4.1 Create replicaContext on a single server 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the empty string (naming the root DSE), and the modification list 
| consists of a single item to add the distinguished name of the context 
| prefix to the attribute replicaContextRoots.  If the server responds 
| with the resultCode attributeOrValueExists, then the value is already 
| there.  If the server responds with a resultCode other than 
| attributeOrValueExists or success, then this is an error. 
|  
| 4.2 Delete replicaContext from a single server 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the empty string  (naming the root DSE), and the modifications list 
| consists of a single item, to delete the value of the distinguished 
| name of the context prefix from the attribute replicaContextRoots.  If 
|  
| the server responds with the resultCode noSuchAttribute, then the value 
| has already been removed.  If the server responds with a resultCode 
| other than noSuchAttribute or success, then this is an error. 
|  
| 4.3 Add area of replication to a server 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the context prefix of the replication context, and the modification 
| list consists of a single item to add the value replicationContext to 
| the attribute objectClass.  If the server responds with the resultCode 
| attributeOrValueExists, then the value is already there.  If the server 
| responds with a resultCode other than attributeOrValueExists or 
| success, then this is an error.  Should an error occur at this point, 
| the server is in an inconsistent state and needs to be fixed.  
|  
| After this step is completed, the server will begin storing change 
| information for this area of replication.  
|  
| WG ISSUE: If replicaContextRoots were an operational attribute, then it 
| would be possible to have the server maintain that attribute when 
| replicationContext is added or deleted.  Without it, these steps need 
|  
|  
| Moats, et al               Expires May 2002                    [Page 5] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| to be separate LDAP protocol operations and thus it is possible to have 
| inconsistent states. 
|  
| 4.4 Delete area of replication from a server 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the context prefix of the replication context, and the modification 
| list consists of a single item to remove the value replicationContext 
| to the attribute objectClass.  If the server responds with the 
| resultCode noSuchAttribute, then the value has already been removed.  
| If the server responds with a resultCode other than noSuchAttribute or 
| success, then this is an error.   
|  
| After this step is completed, the server will no longer replicate this 
| area of replication. 
|  
| 4.5 Copy base of area of replication between servers 
| In this section, the 'target server' is the server on which the client 
| has just modified the root DSE. 
|  
| The client MUST separately contact another server, one that already 
| holds a copy of this replication context, and issue a SearchRequest on 
| that server in which the baseObject is the DN of the of base the area 
| of replication, the scope baseObject, the filter "(objectClass=*)" and 
| the attributes list "*".  If the client cannot obtain the single entry 
| at this point, the procedure will fail, and the client SHOULD invoke on 
| the slave server a ModifyRequest in which the object field is the empty 
| string, and the modifications list consists of a single item, a delete 
| of the attribute replicaContextRoots with the value the distinguished 
| name of the context prefix. 
|  
| WG Issue: Do we need the ability to copy (i.e. read and set) all 
| operational attributes as part of this operation? If so, LDAP will need 
| a change. 
|  
| Now that it has the entry, the client SHOULD invoke an AddRequest on 
| the target server with entry set to the DN of the base of the area of 
| replication and attributes the same list as obtained in the previous 
| search. 
|  
| If the server returns a resultCode other than success, it is an error, 
| and the server will be in an inconsistent state. 
|  
| 4.6 Create server entry in area of replication 
|  
| Each server needs to have in its copy of the area of replication a 
| replicaSubentry for each of the servers involved in replicating that 
| area before replication can be started. These entries MUST have the 
| following attributes: 
|  
| 1.   objectclass, with values top, ldapSubentry and replicaSubentry 
| 2.   cn 
| 3.   replicaURI 
|  
| Moats, et al               Expires May 2002                    [Page 6] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 4.   replicaType 
| 5.   replicaOnline 
|  
| and MAY contain other attributes, as described in the Information Model 
| [InfoMod]. 
|  
| WG Issue: This requires that all replicaSubentries representing the 
| same server have the same entryUUID.  How is this accomplished? 
|  
| 4.7 Delete Server Entry for an area of replication 
|  
| The client SHOULD issue a SearchRequest in which the baseObject is the 
| DN of the context prefix, the scope oneLevel, the filter 
| "(objectClass=replicaSubentries)" and the attributes list. For each 
| entry returned, the client SHOULD then issue a DeleteReques in which 
| the object field is the DN of the entry.   If the server responds with 
| the resultCode noSuchObject, then the entry has already been removed.  
| If the server responds with a resultCode other than noSuchObject or 
| success, then this is an error. 
|  
| 4.8 Modify replica 
|  
| 4.8.1     Change Replica Type 
|  
| Note: This section covers only the simple protocol operation to change 
| the replica type. Section 5.17 coverts the full set of operations for 
| converting from a ReadOnly to an Updateable replica. 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the replicationSubentry, and the modification list consists of a single 
| item to change the value of the attribute replicaType.  If the server 
| responds with the resultCode attributeOrValueExists, then the value is 
| already there.  If the server responds with a resultCode other than 
| attributeOrValueExists or success, then this is an error.  
|  
| 4.8.2     Change Between Full/Partial Replica 
|  
| TBD 
|  
| 4.8.3     Change Replica URI for one server for one area of replication 
|  
| Note: This section covers only the simple protocol operation to change 
| the replica type. Section 5.18 covers the full set of operations for 
| changing the replica URI on all servers. 
|  
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the replicationSubentry, and the modification list consists of a single 
| item to change the value of the attribute replicaURI to the new value.  
| If the server responds with the resultCode attributeOrValueExists, then 
| the value is already there.  If the server responds with a resultCode 
| other than attributeOrValueExists or success, then this is an error. 
|  
| 4.9 Add Replication Agreement 
|  
| TBD 
| Moats, et al               Expires May 2002                    [Page 7] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 4.10 Delete Replication Agreement 
|  
| The termination of replication agreements should be done with caution 
| as it can easily result in a partition of the directory servers if 
| performed incorrectly. 
|  
| Once all replication agreements have been terminated between a server 
| and others for a naming context, then that copy of the context on the 
| server will be divergent, and any updates made there will not be 
| propagated to any other server. 
|  
| TBD 
|  
| 4.11 Modify Replication Agreement 
|  
| TBD 
|  
| 4.12 Suspend Replication 
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the DN of the target replicationSubentry, and the modification list 
| consists of a single item to change the value of replicaOnline 
| attribute to false. If the server responds with the resultCode 
| attributeOrValueExists, then the value is already there.  If the server 
| responds with a resultCode other than attributeOrValueExists or 
| success, then this is an error. 
|  
| 4.13 Resume Replication 
| The client SHOULD invoke a ModifyRequest in which the object field is 
| the DN of the target replicationSubentry, and the modification list 
| consists of a single item to change the value of replicaOnline 
| attribute to true. If the server responds with the resultCode 
| attributeOrValueExists, then the value is already there.  If the server 
| responds with a resultCode other than attributeOrValueExists or 
| success, then this is an error.  
|  
| 4.14 Trigger an Immediate Replica Cycle 
|  
| TBD 
|  
| Issue: An administrative client could trigger an immediate replication 
| cycle by issuing a "Trigger Replication" extended operation to the 
| supplier server.  The extended operation value specifies the DN of a 
| replication agreement between the supplier and target replicas, and the 
| type of replication session to be performed (full update or incremental 
| update).  The replication agreement is used to specify the target 
| replica, connection information, and authentication information. 
|  
| 5  Common Tasks 
| There are many tasks that administrators need to perform in a 
| replicated environment.  This section describes many typical tasks and 
| describes how they are performed in terms of the atoms defined above. 
|  
|  
| Moats, et al               Expires May 2002                    [Page 8] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 5.1 Add a new replica to an existing replica group 
|  
| TBD 
|  
| 5.1.1     Large area of replication support 
|  
| In some cases, an area of replication is so large or available 
| bandwidth so small that out-of-band mechanisms (e.g. mailing a tape) 
| need to be used to transport the initial copy from the source to the 
| target.  The target then needs to be updated with changes made to the 
| source since the copy was made.  This section describes how this 
| situation is handled. 
|  
| Details TBD. 
|  
| WG Issue: is LDIF appropriate for this transport?  If so, how do we 
| carry replication meta-data (e.g. CSNs)? 
|  
| 5.2 Set up (but do not start) replication between two servers 
|  
| TBD 
|  
| 5.3 Set up (but do not start) replication between a server and an 
|     existing replica group 
|  
| TBD 
|  
| 5.4 Verify replication information is present between two servers 
|  
| TBD 
|  
| 5.5 Start replication between two servers. 
|  
| For this operation, the client SHOULD follow the steps in Section 5.2 
| followed by starting replication as specified in Section 4.13. 
|  
| 5.6 Start replication between an existing replica group and a new 
|     server 
| For this operation, the client SHOULD follow the steps in Section 5.3 
| followed by starting replication as specified in Section 4.13. 
|  
| 5.7 Temporarily Suspend all replication activity from a given server 
|  
| TBD  
|  
| 5.8 Halt replication on all areas of a server 
|  
| TBD 
|  
| 5.9 List status of a particular area of replication on a given server 
|  
| TBD 
|  
| Moats, et al               Expires May 2002                    [Page 9] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
|  
| 5.10 List all areas of replication defined on a given server and their 
|     status 
|  
| TBD 
|  
| 5.11 Restore a server and replication agreements after a server crash 
|  
| TBD 
|  
| 5.12 Split an Area of Replication 
|  
| To split an area of replication, the atoms are: 
| 1.   Add the subordinate area of replication to the servers' 
|      replicaContextRoots (Section 4.1) 
| 2.   Add the replicationContext objectclass to the root entry of the 
|      area of replication (Section 4.3) 
| 3.   Create replicaSubentry objects under the new area of replication 
|      for each replica of the parent area of replication (Section 4.6) 
| 4.   Create replicaAgreement objects (and schedules?) under the new 
|      replicaSubentries, where agreements are created that correspond to 
|      each agreement defined for the parent (Section 4.9). 
| These operations must be performed on each server containing a replica 
| of the parent area of replication.   
|  
| WG Issue: Extended op or not? The rationale behind an extended 
| operation is that this should be a mechanical process.  Having a 
| mechanism to "replicate" this from one server to the others: 
| - reduces likelihood of missing something 
| - allows replication framework to ensure that this information gets to 
|   every server in the event that a server is down or some other error 
|   prevents the client from completing all of these operations. 
|  
| 5.13 Move an existing area of replication to a new server  
|  
| TBD 
|  
| 5.14 Join two Areas of Replication 
|  
| This section describes how to join two areas of replication. 
|  
| 5.14.1    Preconditions 
|  
| Before joining two areas of replication there are certain preconditions 
| that need to be satisfied: 
| 1.   Any server that contains a replica of one area of replication must 
|      also contain a replica of the other area of replication. This may 
|      require copying either area of replication to additional servers, 
|      or deleting either area of replication from servers. 
| 2.   The replicas on any given server MUST be of the same type.  Both 
|      replicas must be updateable, both-readonly, or both primary.  
|      Furthermore, if the replicas are readonly, they must both be full 
|      replicas, or must both be fractional replicas with identical 
|      fractional entry specifications. 
|  
| 5.14.2    Procedure 
|  
|  
| Moats, et al               Expires May 2002                   [Page 10] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 1. On each server, delete the replicationContext objectclass value from 
|   the subordinate area of replication (Section TBD). 
|    
|   We'd like this to be replicated under the parent area of replication, 
|   and we'd like this to have the affect of causing all not yet 
|   replicated updates and future client changes as if they occurred 
|   under the parent area f replication.  This is going to cause problems 
|   with respect to CSNs if there are "old" changes in the subordinate 
|   context.  Maybe we require that there be no pending updates?  This is 
|   going to be potentially ugly. 
| 2. 
  Delete all replication agreements for the subordinate area of 
|   replication 
| 3. 
  Delete all replicaSubentries for the subordinate area of replication 
|  
| 5.14.3    Server requirements 
|  
| When the replicationContext objectclass is removed from the root of an 
| area of replication, the server MUST immediately treat entries within 
| the area of replication as belonging to the parent area of replication 
| (if there is any).  This includes replicating any pending replication 
| updates (those not yet replicated to other replicas) as if they 
| occurred under the parent area of replication, as well as preserving 
| any Lost and Found entries. 
|  
| If a server receives a request to delete the replicationContext from an 
| area of replication, and there is a parent area of replication, the 
| Server MUST verify that these replicas are of the same type, and if 
| fractional, that the fractional entry specifications are identical.  If 
| the replicas are not of the same type, the request MUST be failed with 
| resultCode unwillingToPerform. 
|  
| 5.15 Stop Replicating an Area of Replication. 
|  
| This section describes how to stop replicating an area of replication.  
| At the end of the procedure, the subtree represented by the area of 
| replication will exist on one server, all replication agreements will 
| have been deleted, and the root of the area of replication will no 
| longer be an area of replication.  The server on which the subtree will 
| remain is referred to as the surviving replica.   
| To stop replicating an area of replication, a client with 
| administrative authority should perform the following operations: 
|  
| 1.   Halt replication 
|  
| After halting, the client MAY optionally delete information by: 
|  
| 2.   Delete all replication agreements (Section 4.10). 
| 3.   Delete all replicaSubentries under the area of replication 
|      (section 4.7)  
| 4.   Issue a modifyRequest to the surviving server where the object 
|      field is the DN of the area of replication, and the modifications 
|      list consists of a single item, delete the attribute objectclasss 
|      with value replicationContext. 
|  
| Moats, et al               Expires May 2002                   [Page 11] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| 5.   Delete replicaContext from that server (Section 4.2) 
| 6.   Delete the area of replication from servers containing other 
|      replicas (Section 4.4). 
|  
| Note that client updates accepted on the non-surviving replicas during 
| this procedure may be lost (because they were not replicated to the 
| surviving server). 
|  
| 5.16 Suspending and Resuming Replication 
|  
| To suspend replication of an area of replication to a specific server, 
| an administrative client can perform a modifyRequest of the 
| replicaSubentry, with a modification list replacing the replicaOnline 
| attribute with the value false.   Performing this request on the 
| specified server causes the server to stop accepting or initiating 
| replication requests for that area of replication.  This procedure can 
| also be performed on any other replica.  The modifyRequest will be 
| replicated to other servers.  When a server other than that specified 
| by the replicaSubentry receives the request the server MUST stop 
| sending replication updates to the specified server.  The unsent 
| changes MUST be saved until the replicaOnline attribute is chnaged to 
| true.  Servers MUST continue to repond to replication updates sent from 
| the specified server. 
|  
| To resume replication of an area of replication to a specific server, 
| an administrative client can perform a modifyRequest of the 
| replicaSubentry, with a modification list replacing the replicaOnline 
| attribute with the value false.   This request must be performed on the 
| specified server, or it will not resume replication.  This operation 
| may also be performed on other servers. 
|  
| 5.17 Convert a read-only replica to an updateable replica 
|  
| TBD 
|  
| 5.18 Changing Replica URI on all servers handling an area of 
|     replication 
|  
| The client issues this request to the server whose address has been 
| changed, which replicates it to the other replicas like other client 
| updates.  It may be necessary to issue the same request to other 
| replicas, for example, when the server does not have proper replication 
| agreements to fully replicate this change (as in consumer initiated 
| replication). 
|  
| 5.19 Postpone a Replica Cycle to a Later Time 
|  
| TBD 
|  
| 5.20 Examine Replication Audit History on a Server 
|  
| TBD 
|  
| 5.21 Compare Two Replicas on Two Servers for Differences 
|  
| TBD 
|  
| 5.22 Fix an Entry Without Triggering Replication 
|  
| When conflicts cause entries to be put in the Lost+Found area, the 
| administrator needs a mechanism to make appropriate changes.  These 
| Moats, et al               Expires May 2002                   [Page 12] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| changes should not trigger replication since they are used to fix 
| previous replication problems.  In addition, these changes may include 
| fixes to UUIDs, CSNs, or other control data that cannot be changed 
| using normal LDAP operations. 
|  
| TBD 
|  
| 5.23 Check Reported Schema Mismatches Discovered During Replication 
|  
| TBD 
|  
| 5.24 Adding a new directory server to a replica group and initializing 
|     the contents 
|  
| In this case, the client: 
|  
| 1. Creates the replicaContext on the new server (section 4.1) 
| 2. Copies the base entry for the area of replication from a source to 
| the target (section 4.5) 
| 3. 
  Create the entries for the new server on all servers in the replica 
|   group (section 4.6) 
| 4. 
  Create the entries for the existing replica group servers on the new 
|   (section 4.6) 
| 5. 
  Create the replication agreement on all servers (section 4.9) 
| 6. 
  Client issues a "Initiate Full Update" request to a full replica for 
|   the new replica -- or new replica requests consumer initiated full 
|   update 
|  
|  
|  
| 5.25 Restore from the master failure in a single-master system 
|  
| TBD 
|  
| 6  Formal Specifications 
|  
| The Replica Management features depend heavily on defined LDAP and LDUP 
| structure, operations, and data formats.  But some changes will be 
| needed to accommodate Replica Management.  All these changes are pulled 
| together in this section for easy reference. 
|  
| 6.1 New/Modified Object Classes 
|  
| TBD 
|  
| 6.2 New/Modified Attributes 
|  
| TBD 
|  
| 6.3 New/Modified Extended Operations 
|  
| Trigger Replica Operation 
|  
| TBD 
|  
|  
| Moats, et al               Expires May 2002                   [Page 13] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
|  
| 6.4 New/Modified Replication Primitives 
|  
| TBD 
|  
| 7  Security Considerations 
|  
| In all cases, it is assumed that the client establishes a connection to 
| the LDAP server and SHOULD authenticate using a recommended 
| authentication method [RFC2829] that establishes the identity of the 
| client user and SHOULD provide for connection integrity.  In 
| deployments where the underlying network service is vulnerable to 
| eavesdropping and clients are intending to retrieve sensitive server 
| credentials, the chosen method SHOULD also provide for encryption of 
| data in transit. 
|  
| In general, where the client is unaware of any network level protection 
| services, it is RECOMMENDED that the client immediately after 
| connection establishment invoke Start TLS to establish connection 
| integrity and confidentiality, and follow this by authentication by one 
| of: 
|  
|   - the "DIGEST-MD5" SASL mechanism, 
|   - the "simple" authentication choice, or 
|   - the "EXTERNAL" SASL mechanism if the client provided its  
|      certificate during TLS establishment. 
|  
| The client MAY determine the supported authentication mechanisms of the 
| server from the supportedSASLMechanisms attribute of the root DSE after 
| Start TLS has been invoked, and use this to decide whether to use 
| DIGEST-MD5 or EXTERNAL.  See [RFC2830] for more information on TLS. 
|  
| 8  Acknowledgements 
|  
| Thanks to Mark Wahl and Ed Reed for providing a lot of the initial 
| text. 
|  
| This document is a product of the LDUP Working Group of the IETF.  The 
| contributions of its members are greatly appreciated. 
|  
| 9  References 
| [Arch] J. Merrells, E. Reed, U. Srinvasan, "LDAP Replication 
| Architecture", draft-ietf-ldup-model-01.txt. 
|  
| [InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf-
| ldup-infomod-00.txt 
|  
| [RFC2119] S. Bradner, "Key Words for Use in RFCs to Indicate 
| Requirement Levels", RFC 2119, March 1997. 
|  
| [RFC2829] M. Wahl, H. Alvestrand, J. Hodges, RL Morgan, "Authentication 
| Methods for LDAP", RFC 2829, May 2000. 
|  
|  
|  
|  
| Moats, et al               Expires May 2002                   [Page 14] 

|  
|  
| INTERNET DRAFT     Mandatory LDAP Replica Management      November 2001 
| [RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access 
| Protocol (v3): Extension for Transport Layer Security", RFC 2830, May 
| 2000. 
|  
| Author's Addresses: 
|  
| Ryan Moats 
| Lemur Networks, Inc. 
| Email: [email-masked] 
|  
| Rick Huber 
| AT&T Laboratories 
| Email: [email-masked] 
|  
| John McMeeking 
| IBM 
| Email: [email-masked] 
|  
| Full Copyright Statement 
|  
| Copyright (C) The Internet Society (2000).  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 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. 
| 
| 
| 
| 
| 
| 
| 
| Moats, et al               Expires May 2002                   [Page 15]