INTERNET DRAFT Mandatory LDAP Replica Management March 2003 Internet-Draft Ryan Moats LDAP Duplication/Replication/Update Lemur Networks, Inc. Protocols WG Rick Huber Expires September 2003 AT&T Laboratories John McMeeking IBM March 2003 Mandatory LDAP Replica Management Filename: draft-ietf-ldup-mrm-02.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 required, and specifications for these changes are included in this document. Moats, et al Expires September 2003 [Page 1] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 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]. Table of Contents Status of this Memo...................................................1 Abstract..............................................................1 Table of Contents.....................................................2 1 Introduction .......................................................3 2 Administrative Precursors ..........................................4 3 Operational "Atoms" ................................................4 3.1 Add area of replication to a server ............................5 3.2 Delete area of replication from a server .......................5 3.3 Copy base of area of replication between servers ...............6 3.4 Create server entry for an area of replication .................6 3.5 Delete server entry from an area of replication ................6 3.6 Modify replica .................................................7 3.6.1 Change Replica Type .........................................7 3.6.2 Change Between Full/Partial Replica .........................7 3.6.3 Change Replica URI for one server for one area of replication 8 3.7 Add Replication Agreement ......................................8 3.8 Delete Replication Agreement ...................................9 3.9 Modify Replication Agreement ...................................9 3.10 Suspend Replication ..........................................9 3.11 Resume Replication ..........................................10 3.12 Trigger an Immediate Replica Cycle ..........................10 3.13 Immediately Terminate a Replica Cycle .......................11 3.14 Search with Meta-Data .......................................11 3.15 Changing Replication Meta-Data ..............................12 3.15.1 Add with Meta-Data .......................................12 3.15.2 Delete with Meta-Data ....................................13 3.15.3 Modify with Meta-Data ....................................13 3.16 Write-Unwriteable Control ...................................13 4 Common Tasks ......................................................14 4.1 Add a new replica to an existing replica group ................14 4.1.1 Large area of replication support ..........................15 4.2 Verify replication information is present between two servers .16 4.2.1 Verify that replication objects exist ......................17 4.2.2 Verify that it is valid for replication to occur between these servers .....................................................18 4.3 Start replication between two servers .........................18 4.4 Suspend Replication activity on one area of a server ..........19 4.5 Suspend Replication activity on all areas of a server .........19 4.6 Restart Replication activity on one area of a server ..........19 4.7 Restart Replication activity on all areas of a server .........19 4.8 Halt replication ..............................................19 4.9 List status of a particular area of replication on a given server .............................................................20 4.9.1 Local Replica On-Line ......................................20 4.9.2 Remote Replicas On-Line ....................................20 Moats, et al Expires September 2003 [Page 2] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 4.9.3 Check Status of Outward Replication ........................20 4.9.4 Check Status of Incoming Replication .......................20 4.10 List all areas of replication defined on a given server and their status .......................................................21 4.11 Restore a server and replication agreements after a server crash 21 4.11.1 Recent Backup is Available ...............................21 4.11.2 Backup is Not Available ..................................22 4.12 Split an Area of Replication ................................22 4.13 Move an existing area of replication to a new server ........23 4.14 Join two Areas of Replication ...............................23 4.14.1 Preconditions ............................................23 4.14.2 Procedure ................................................24 4.14.3 Server requirements ......................................24 4.15 Stop Replicating an Area of Replication. ....................24 4.16 Convert a read-only replica to an updateable replica ........25 4.17 Convert an updateable replica to a read-only replica ........25 4.18 Postpone a Replica Cycle to a Later Time ....................26 4.19 Examine Replication Audit History on a Server ...............26 4.20 Compare Two Replicas on Two Servers for Differences .........26 4.21 Fix an Entry Without Triggering Replication .................27 4.22 Check Reported Schema Mismatches Discovered During Replication 27 4.23 Adding a new directory server to a replica group and initializing the contents ..........................................28 4.24 Restore from the master failure in a single-master system ...28 5 Formal Specifications .............................................29 5.1 New/Modified Object Classes ...................................29 5.2 New/Modified Attributes .......................................29 5.3 New/Modified Extended Operations ..............................29 5.4 New/Modified Replication Primitives ...........................29 5.5 New/Modified Controls .........................................29 6 Security Considerations ...........................................30 7 Acknowledgements ..................................................30 8 References ........................................................31 Authors' Addresses:..................................................31 Full Copyright Statement.............................................32 1 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 using standard LDAP operations [RFC2251]. These entries are explicitly included in the directory entries governed by any agreement associated with this area of replication. As a result, all servers with a replica Moats, et al Expires September 2003 [Page 3] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 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 of 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. 2 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. Deployments SHOULD create an administrative user identity that is granted access to all servers holding a copy of a replicated area 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. 3 Operational "Atoms" The following operational atoms are used to build up more complex tasks in section 4. 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: - Create the naming context prefix entry - 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. Moats, et al Expires September 2003 [Page 4] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 The LDUP Architecture [Arch] allows for read-only replicas. Setting up and maintaining a read-only replica will sometimes require that the administrator create or modify data on the read-only replica. In this case, the Write-Unwriteable control (Section 3.16) should be used. In the remainder of the document, any numbered list of steps is intended to be performed in the order given. Un-numbered (dash) lists will be used where order is unimportant. 3.1 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. 3.2 Delete area of replication from a server On the target server, the client SHOULD invoke a SearchRequest to find all replicaSubentry objects which refer to the area of replication: 1. Retrieve all the values of the replicaContextRoots attribute in the root DSE of the server. Each value is the distinguished name of the base entry of a Replication Context held on the server. 2. Perform a one-level LDAP search in each replicaContextRoot for objects of class replicaSubentry whose replicaURI attribute points to the given server (e.g. use a filter of "(&(objectclass=replicaSubentry-2)(replicaURI=ldap://thisserver))") where "thisserver" is the fully-qualified DNS name of the given server with the associated port if it is not port 389. The client then examines the subtreeSpecifications to determine which one it wants and then deletes all replicaSubentries with that subtreeSpecification. If any of the DelRequests fail, the area of replication has not been completely removed. After this step is completed, the target server will no longer replicate this area of replication nor will it record changes for later replication. However, the other servers in the replica group for this area will still have a replicaSubentry for the given server, and this should be cleaned up on all servers that hold the replica. WG Issue: This is a reason for the subtreeSpecification issue. If it were a DN, this would be much easier. Otherwise, we're going to need a matching rule for subtreeSpecification. Moats, et al Expires September 2003 [Page 5] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 3.3 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 base of the area of replication, the scope baseObject, the filter "(objectClass=*)" and the attributes list {"*", entryUuid}. If the client cannot obtain the single entry at this point, the procedure will fail. Now that it has the entry, the client SHOULD invoke an AddWithMetaData (see 3.15.1) 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. 3.4 Create server entry for an 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: - objectclass, with values top, Subentry and replicaSubentry - cn - replicaURI - replicaType and MAY contain other attributes, as described in the Information Model [InfoMod]. WG Issue: This means that InfoMod needs to explicitly define replicaOnline as DSA specific with a default value of FALSE. 3.5 Delete server entry from an area of replication On the target server, the client SHOULD invoke a SearchRequest to find all replicaSubentry objects which refer to the area of replication: 1. Retrieve all the values of the replicaContextRoots attribute in the root DSE of the server. Each value is the distinguished name of the base entry of the base entry of a Replication Context held on the server. 2. Perform a one-level LDAP search in each replicaContextRoot for objects of class replicaSubentry whose replicaURI attribute points to the given server (e.g. use a filter of "(&(objectclass=replicaSubentry-2) (replicaURI=ldap://thisserver))") where "thisserver" is the fully-qualified DNS name of the given server. The subentry control MUST be included on this operation. Moats, et al Expires September 2003 [Page 6] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 The client then examines the subtreeSpecifications and the replicaURI to determine which one(s) it wants and then deletes all replicaSubentries with that proper subtreeSpecification and replicaURI. If any of the DelRequests fail, the area of replication has not been completely removed. WG Issue: This is another reason for the subtreeSpecification issue. If it were a DN, this would be much easier. Otherwise, we're going to need a matching rule for subtreeSpecification. 3.6 Modify replica 3.6.1 Change Replica Type Note: This section covers only the simple protocol operation to change the replica type. Section 4.16 covers the full set of operations for converting from a ReadOnly to an Updateable replica. The client SHOULD invoke a ModifyRequest with the Write-Unwriteable control (Section 3.16) 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. 3.6.2 Change Between Full/Partial Replica Note: This section currently discusses how to change between fractional and full replication. Once the information model supports sparse replication, it will need to be added here. This section only discusses the simple LDAP protocol operations to change between full and partial replicas. Additional actions are discussed in Section 4.15. To switch from fractional to full replication, a client SHOULD invoke a ModifyRequest with the Write-Unwriteable control (Section 3.16) in which the object field is the replicaSubentry, and the modification list consists of two items: one to remove the attribute attributeExclusionFilter and the other to remove the attribute attributeInclusionFilter. If the server responds with a resultCode other than noSuchAttribute or success then an error has occurred. To switch from full to fractional replication, a client SHOULD invoke a ModifyRequest with the Write-Unwriteable control in which the object field is the replicaSubentry, and the modification list consists of one or two items: one to add the attribute attributeExclusionFilter and/or the other to add the attribute attributeInclusionFilter. If the server responds with a resultCode other than attributeOrValueExists or success, then an error has occurred. Moats, et al Expires September 2003 [Page 7] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 3.6.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 URI. Replication will carry this change to other 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 delete the old value of the attribute replicaURI and add 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. 3.7 Add Replication Agreement Each server that acts as a supplier in replication sessions needs to have in its copy of the area of replication a replicaAgreementSubentry for each server that it replicates to. ReplicaAgreementSubentry objects are created as subordinates of the replicaSubentry representing the supplier server. These entries MUST have the following attributes: - objectclass, with values top, Subentry and replicaAgreementSubentry- 2, and - cn and MAY contain other attributes, as described in the Information Model [InfoMod]. The cn attribute value has no significance to replication. The cn attribute SHOULD have a value that is meaningful to the replication administrator. These objects MUST have the following attributes (defined as optional in the Information Model) for replication to occur: - replicaDN If replicaDN is absent, no replication occurs under this agreement. A client AddRequest creates the replicaAgreementSubentry. The entry field of the AddRequest is the DN of the agreement (formed by using the cn attribute as the RDN naming attribute in combination with the DN of the parent replicaSubentry). The attributes field of the AddRequest contains the required attributes for the agreement and any optional attributes that are to be defined at this time. Note: while replicationAgreementSubentries could be replicated, since the replicationCredentialsDN are contained in the replicationAgreementSubentry, there is a bootstrapping issue with replicating via anonymous replication. To avoid this, clients MAY create the replicationAgreementSubentries on all servers. If they do this, they should use the AddWithMetaData operation (Section 3.15.1) to ensure that all replicationAgreementSubentries have the same entryUUID. Moats, et al Expires September 2003 [Page 8] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 3.8 Delete Replication Agreement To delete a replication agreement a LDAP client SHOULD invoke a DeleteRequest naming the replicaAgreementSubentry to be deleted. 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. 3.9 Modify Replication Agreement To modify a replication agreement, the client SHOULD invoke a ModifyRequest naming the replicaAgreementSubentry. The modification list MAY include any of the following attributes: - attributeExclusionFilter - description - replicaDN - replicationMechanismOID - replicationCredentialsDN - replicationScheduleDN No further administrative action is required for these changes to take affect. Changing the replicaDN attribute has the effect of ending the existing agreement with the replica named by the old replicaDN value (if a value was present). Similary, changing the replicationMechanismOID attribute to specify ietf-ldup-full-update has the effect of ending incremental replication relationship. In this respect, these changes are equivalent to deleting a replication agreement and have the same considerations (see section 3.8) The replicationStatus attribute cannot be modified. 3.10 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. If replicaOnline is FALSE for a replicaSubentry that represents the server containing the instance of the replicaSubentry, the server MUST NOT initiate or accept any new incremental replication sessions. If replicaOnline is FALSE for a replicaSubentry that represents a replica Moats, et al Expires September 2003 [Page 9] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 other than the server containing the instance of the replicaSubentry, the server MUST NOT initiate or accept any new incremental replication sessions with that replica. 3.11 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. If replicaOnline is TRUE for a replicaSubentry that represents the server containing the instance of the replicaSubentry, the server MAY initiate or accept new incremental replication sessions. If replicaOnline is TRUE for a replicaSubentry that represents a replica other than the server containing the instance of the replicaSubentry, the server MAY initiate or accept new incremental replication sessions with that replica. 3.12 Trigger an Immediate Replica Cycle An immediate replication cycle can be triggered using an LDAP extended operation - "Trigger Replication". This operation takes 4 or 5 arguments: . The distinguished name of the replicaSubentry for the target replica. If there is no instance of this entry on the server where the extended operation is executed, the operation is not performed and an error is returned. . The LDAP URL of the target server. (Note: Per [Req] M8, a single Replication Agreement may accommodate more than one pair of servers. Thus this argument is necessary.) . Type of replication session to be performed (full update or incremental update). . Flags indicating whether the replication session is online or offline, and if offline whether the server should create the offline file or read the offline file. See Section 4.1.1 for more details of offline replication. . If the replication session is offline, the name of the file to be used. All other required information (connection information, authentication information, etc.) is obtained from the Replication Agreement. The server on which the operation is executed immediately initiates a replica cycle with the target server. Updates are transferred in both directions if allowed by the replication agreement. If either the target server or the server executing the extended operation has a currently-active replica cycle for the replication Moats, et al Expires September 2003 [Page 10] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 context specified by the extended operation, the extended operation will fail ([Arch] Section 10). Since replication is normally an asynchronous operation, the Trigger Replication extended operation completes and returns status when replication is started. It does not wait for completion of the replica cycle and the returned status indicates whether the cycle was started successfully, not whether it completed successfully. Further progress of the replica cycle can be checked using other mechanisms (e.g. Section 4.9). The detailed syntax of the operation and associated response are presented in Section 5.3. 3.13 Immediately Terminate a Replica Cycle Note: this section discusses just the operation for terminating a replica cycle. See section 4.18 for a discussion of suspending replication or changing the replication schedule. An in-progress replication cycle can be terminated immediately using an LDAP extended operation - "Terminate Replication". This operation takes 2 arguments: 1. The distinguished name of the replicaSubentry for the target replica. If there is no instance of this entry on the server where the extended operation is executed, the operation is not performed and an error is returned. 2. The LDAP URL of the target server. (Note: Per [Req] M8, a single Replication Agreement may accommodate more than one pair of servers. Thus this argument is necessary.) All other required information is obtained from the Replication Agreement. The server on which the operation is executed immediately terminates its current replica cycle with the target server. Termination will not interrupt transmission of a Replication Update [Arch], it will occur only between Replication Updates. The detailed syntax of the operation and associated response are presented in Section 5.3. Note: If data is queued awaiting replication between a pair of servers and if replication is set to trigger on updates, the replication system may automatically start a new replica cycle shortly after a cycle is terminated. To avoid this, the replication schedule should be adjusted to suspend replication before the Terminate Replication extended operation is issued. 3.14 Search with Meta-Data Many pieces of replication meta-data are used by LDUP. In some cases (entryUUID, createdEntryCSN) they are stored as operational attributes Moats, et al Expires September 2003 [Page 11] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 and can be read using the LDAP search operation. Other meta-data (deleted entries, CSNs related to changes of attribute values) are not visible via normal LDAP operations but must be obtainable by administrative users attempting to deal with replication problems (e.g. dealing with Lost+Found entries). "Search with Meta-Data" is an extended operation that is modeled on the LDAP search operation [RFC2251]. There is an additional parameter that indicates what additional data should be returned be the search. The following values are permitted: - deletedEntries - Any deleted entries in the scope of the search are returned. Deleted entries can be distinguished from non- deleted entries because the deleted entries will have a value in their deletedEntryCSN attribute. If the deletedEntries controlValue is given, the deletedEntryCSN attribute is automatically added to the AttributeDescriptionList of the search. - attributeChangeState - Each attribute value returned as part of the search will be returned as a triple consisting of the attribute value, the deleted flag associated with the value, and the modificationCSN associated with the value. The formal specification of the Search with Meta-Data extended operation is given in Section 5.3. Note: Search with Meta-Data is designed as an extended operation rather than a control because the format of the returned data (sets of triples) is different from a normal LDAP search operation. Other than this, Search with Meta-Data operates the same as search. 3.15 Changing Replication Meta-Data When fixing a replication problem, administrators need a way to modify meta-data values that are normally treated as operational attributes (createdEntryCSN, entryUUID) or as completely hidden data (deletedEntryCSN, deleted flag, modificationCSN). This set of extended operations mirrors the normal LDAP operations that allow modification, but they allow modification of the associated meta- data as well. 3.15.1 Add with Meta-Data The Add with Meta-Data extended operation is modeled on the LDAP Add operation [RFC2251]. The differences from the standard LDAP Add operation are: - Each value is specified as a triple consisting of the value, the deleted flag to be associated with that value, and the modificationCSN to be associated with that value. - A value may be supplied for the createdEntryCSN attribute. - A value may be supplied for the entryUUID attribute. Moats, et al Expires September 2003 [Page 12] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 - If the Add with Meta-Data extended operation is executed on a readonly replica it will be executed locally rather than returning a referral to an updateable replica. The formal specification of Add with Meta-Data is in Section 5.3. 3.15.2 Delete with Meta-Data The Delete with Meta-Data extended operation is modeled on the LDAP Delete operation [RFC2251]. The differences from the standard LDAP Delete operation are: - A deletedEntryCSN may be supplied with the Delete with Meta-Data extended operation. In this case the delete operation is performed as in [RFC2251], except that the value of the deletedEntryCSN is taken from the controlValue. - It may be flagged as a noRecordDelete. In this case the targeted entry is deleted with no meta-data left behind (no deletedEntry or "tombstone"). - If the Delete with Meta-Data extended operation is executed on a readonly replica it will be executed locally rather than returning a referral to an updateable replica. The formal specification of the Delete with Meta-Data extended operation is given in Section 5.3. 3.15.3 Modify with Meta-Data The Modify with Meta-Data extended operation is modeled on the LDAP Modify operation [RFC2251]. The differences from the standard LDAP Modify operation are: - Each value is specified as a triple consisting of the value, the deleted flag to be associated with that value, and the modificationCSN to be associated with that value. - The createdEntryCSN attribute may be modified. - The entryUUID attribute may be modified. - If the Modify with Meta-Data extended operation is executed on a readonly replica it will be executed locally rather than returning a referral to an updateable replica. The formal specification of Modify with Meta-Data is in Section 5.3. 3.16 Write-Unwriteable Control There are a number of attributes defined in [InfoMod] which are marked "NO-USER-MODIFICATION". When fixing replication problems, there may be times when these values need to be changed. In addition, when administering readonly replicas it may be necessary for administrators to modify values on readonly replicas. The Write-Unwriteable control handles these cases. Moats, et al Expires September 2003 [Page 13] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 The control can be attached to an LDAP modify operation. If the control is present, it allows the modify operation to change values that are marked "NO-USER-MODIFICATION" (the only exception is attributes which are locally calculated by the implementation). Also, if the control is present, modify operations can be executed on readonly replicas. In this case the readonly replica will not return a referral to an updateable replica and the operation will be performed on the readonly replica. The formal specification of the control is given in Section 5.5. The current list of NO-USER-MODIFICATION attributes in [InfoMod] is: attributeExclusionFilter (Section 8.2.4) attributeInclusionFilter (Section 8.2.5) replicationStatus (Section 8.2.7) replicaType (Section 8.2.8) updateVector (Section 8.2.9) secondsToWaitDefault (Section 8.2.18) secondsToWait1 (Section 8.2.19) secondsToWait2 (Section 8.2.21) 4 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. 4.1 Add a new replica to an existing replica group Assume there is an existing replica group for a given area of replication. To add one new server (which does not already hold a copy of the area) to the replica group, perform the following steps: 1. Copy the base entry of the area of replication from one of the current servers to the new server (Section3.3). 2. On one of the existing servers in the replica group, create the replicaSubentry for the new server with the replicaOnline attribute set to "false" (Section 3.4). Replication will copy this to all the existing replicas (trigger immediate replication per Section 3.12 if necessary). Since replicaOnline does not replicate, it needs to be set "false" on all existing servers. 3. On the new server, create a replicaSubentry for one of the other servers in the replica group with the replicaOnline attribute set to "false". The UUID of this replicaSubentry MUST be identical to the UUID it has on the existing replicas, so Add with Meta- Data (Section 3.15.1) should be used to create the entry. 4. If the authentication mechanism used for replication requires credentials, make appropriate entries on all existing servers for the new server and make appropriate entries for all the existing servers on the new server. If any of the credential data is in the current area of replication, use Add with Meta-Data on the Moats, et al Expires September 2003 [Page 14] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 new server and make the UUIDs the same as those on the existing servers. 5. Create the replication agreement(s) on one of the existing servers and let it replicate to the other existing servers (Section 3.7). 6. Set the replicaOnline attribute to true for the new server on both the source and target servers (Section 3.11). 7. On the source server, trigger an immediate "full update" replica cycle (Section 3.12). The data replicated will include the replicaSubentries and replication agreements for all other servers in the replica group since they are in the area of replication. 8. On the new server, set the replicaOnline attributes in the replicaSubentries for all the other servers to "true". 9. On the servers in the replica group other than the source server, set the replicaOnline attribute in the replicaSubentry for the target server to "true". 4.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. While LDIF is typically used to transport bulk LDAP data, it is not suitable here because it does not transport replication meta-data (CSNs, GUIDs, etc.). To ensure that all needed data is available; bulk replication data is stored as a stream of protocol elements from [Proto] in network byte order. There is an LDAP extended operation that will either cause a server to generate or read a stream of protocol elements (see Section 3.12). Use of the extended operation to generate or a read a file is OPTIONAL, but if the file is generated it MUST be a stream of protocol elements. The following restrictions are imposed on the data stream: - The BIND operation is unauthenticated. The extended operation that causes the destination server to read protocol elements from a local file should be restricted to privileged users only (See Section 6); this provides authentication for the operation. - The "supplier initiated" protocol flow is used. - A "full update" replication session is assumed. - Since input is coming from a file, there are no responses. The stream of protocol elements should assume that all response codes are "REPL_SUCCESS". - Since this is a "full update" session, [Proto] specifies that "the consumer's update vector should be assumed to be set to times 'earlier than' the oldest times known to the supplier server." Thus the protocol stream can be generated without receiving a createGroupingResponse extended operation from the consumer. Moats, et al Expires September 2003 [Page 15] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 - The value of the groupCookie in the endGroupingRequest extended operation is ignored. Once the file has been loaded on the destination server, the destination server should initiate a replication session with the source server (Section 3.12). This will pick up changes that have occurred since the original file was created. In summary, to add a new server to an existing replica group for a large replica, follow these steps (steps 1-7 are the same as steps 1-7 of Section 4.1): 1. Copy the base entry of the area of replication from one of the current servers to the new server (Section3.3). 2. On one of the existing servers in the replica group, create the replicaSubentry for the new server with the replicaOnline attribute set to "false" (Section 3.4). Replication will copy this to all the existing replicas. Since replicaOnline does not replicate, it needs to be set "false" on all existing servers. (Trigger immediate replication per Section 3.12 if necessary.) 3. On the new server, create a replicaSubentry for one of the other servers in the replica group with the replicaOnline attribute set to "false". The UUID of this replicaSubentry MUST be identical to the UUID it has on the existing replicas, so Add with Meta- Data (Section 3.15.1) should be used to create the entry. 4. If the authentication mechanism used for replication requires credentials, make appropriate entries on all existing servers for the new server and make appropriate entries for all the existing servers on the new server. If any of the credential data is in the current area of replication, use Add with Meta-Data on the new server and make the UUIDs the same as those on the existing servers. 5. Create the replication agreement(s) on one of the existing servers and let it replicate to the other existing servers (Section 3.7). 6. Set the replicaOnline attribute to "true" for the new server on both the source and target servers (Section 3.11). 7. Generate an update file on the source server (Section 3.12) 8. Transport the file to the destination site by any appropriate means (FTP, express parcel, postal mail, etc.) 9. Load the file onto the destination server (create a disk file from tape if necessary) 10. Import the file into LDAP (Section 3.12) 11. Set the replicaOnline attribute to true for the new server 12. Trigger a replica session between the source and destination machine to pick up changes since the file was generated (Section 3.12) 4.2 Verify replication information is present between two servers This section describes steps that verify the proper replication information is present for replication to occur between two replicas. There are two parts to this process: Moats, et al Expires September 2003 [Page 16] INTERNET DRAFT Mandatory LDAP Replica Management March 2003 1. Verify that the necessary objects have been created on both replicas. These objects include replicaSubentry objects representing the replicas, replication agreements describing consumer-supplier relationships between the replicas, and the credential and schedule objects named in the agreements. 2. Verify that it is valid to replicate between the replicas. For example, a fractional replica cannot act as a supplier to a full replica. 4.2.1 Verify that replication objects exist This section describes how to verify that the necessary replication objects exist. Within this section the term replica refers to one of the two replicas for which information is being verified. It is assumed that an administrator has identified the replicas (both the IP address/host name and the replicaId), the area of replication, and which of the replicas are expected to act as suppliers. One or both of the replicas must be a supplier to the other replica. 1. The client SHOULD invoke an object scope search specifying the DN of the root entry of the area of replication. This entry MUST exist on both servers, and the objectclass attribute values MUST include the value replicationContext. 2. On the replicas which the administrator has indicated is a supplier, the client SHOULD invoke a baseObject scope search of the root DSE requesting the replicationSubentries attribute. The value for this attribute MUST name exactly one replicaSubentry object that is a child of the root entry of the area of replication. The distinguished name of the entry MUST be of the form: cn=, 3. On each supplier replica, the client SHOULD invoke a baseObject scope search specifying the DN of replicaSubentry that was identified in the replicaSubentries attribute of the root DSE in the previous step. This object MUST exist for replication to occur, and MUST include the value replicaSubentry in the list of objectclass values. The client SHOULD invoke an object scope search for the other server. The base DN for this search is of the form: cn=, where is the replicaId of the other replica. This object MUST exist, and MUST include the value replicaSubentry in the list objectclass values. 4. On each supplier replica, the client SHOULD invoke a oneLevel search, specifying the DN of replicaSubentry for that replica as the baseObject, and a search filter like: (&(objectclass=replicationAgreementSubentry-2) (replicaDN=)) where