4.4 Partition Operations
eDirectory allows administrators to create and manage partitions and their replicas. These operations, called partition operations, allow great flexibility in maintaining and modifying an eDirectory tree. This section describes the available operations and the processes behind them. All operations involve two major stages. Stage 1 is the processing of the client request by the Directory Services Agent (DSA) layer and its reply to the client. Stage 2 is the background processing of the request which usually involves requests to other eDirectory servers. The figure below illustrates these stages.
Figure 4-9 Partition Operations
During Stage 2, servers use the replica synchronization protocol to exchange information and move the replicas through the various states associated with the partition operation (see Replica Transition States). The replica synchronization protocol ensures that the other replica is in a state to perform a synchronization and that the information about the partition operation, once received, has been successfully applied. If the operation requires more than one state change, the servers exchange multiple sequences of replica update information.
For partition operations to succeed,
- All servers in the replica ring must be up.
- In NetWare 4.x, all servers must be able to talk to each other.
- In NetWare 5.x, servers with master replicas must be able to talk to each other and to at least one server in their replica ring. The master replica does not need to talk to each and every replica in the ring.
Partition operations include the following:
4.4.1 Replica Transition States
A client can add or delete a replica when another partition operation is taking place. The other partition operations (changing, joining, splitting, moving) cannot occur simultaneously but must be queued to occur sequentially. Partition operations use replica states to indicate the status of the partition and its replicas as they transition to a new state.
NetWare 4.x and NetWare 5.x use different transition states for some partition operations. In a mixed eDirectory tree that contains both NetWare 4.x and NetWare 5.x servers, the master replica determines behavior.
If the master replica is on a NetWare 5.x server,
- Nonmaster replicas on NetWare 5.x servers use NetWare 5.x transition states.
- Nonmaster replicas on NetWare 4.x servers use NetWare 4.x transition states.
If the master replica is on a NetWare 4.x server, all replicas use NetWare 4.x transition states.
The following tables lists the partition operations those transitions states varying according to the NetWare operating system version.
Table 4-3 Partition Operations Versus NetWare Operating System
Some partition operations in NetWare 4.x and NetWare 5.x use the same transition states. The following table lists these operations and their states.
4.4.2 Adding a Replica
Adding a replica causes a new replica to be added to a partition’s replica list and places a replica on the specified server. NetWare 4.x and NetWare 5.x both use a two stage process, but the methods are slightly different.
Adding a Replica in NetWare 4.x
In Stage 1, the client sends the request to an eDirectory server with the server's name, the partition name, and the replica type. The request is sent to the server with the master replica.
The master server verifies that
- Target server exists and doesn't currently hold a replica of the partition.
- Client has sufficient rights to the target server and the partition's root object.
- Partition is not currently involved in another partition operation that prevents an add. Another add or remove operation can be in progress, but any other partition operation will cause the request to be denied.
If the request is valid, the master server starts the process by
- Creating subordinate references requests for any partitions that are below the newly added partition (these requests will be sent to the target server).
- Adding the replica to replica list.
- Setting the replica's state to RS_NEW_REPLICA.
- Sending the client reply indicating success or failure.
In Stage 2, the master server communicates the request to the target server which will add the replica. The master server sends the following to the target server:
- Name of the replica's partition root
- All entries for the replica being added
- All updates to the entries
- The replica's state change to RS_TRANSITION_ON when the target server acknowledges receiving all updates
- The replica's state change to RS_ON when the target server acknowledges receiving updates from the other servers in the replica ring
The target server completes the following tasks:
- Contacts the master replica of each subordinate reference to create a subordinate reference for the target server.
- Adds each subordinate reference as the information comes from each master replica.
- Adds the replica.
- Receives the replica's entries and updates from the master server.
- Requests updates from all servers in the replica ring other than the master.
- Requests a change state to RS_ON when updates have been received from the other servers in the replica ring.
Adding a Replica in NetWare 5.x
In Stage 1, the client sends the request to an eDirectory server with the server's name, the partition name, and the replica type. The request is sent to the server with the master replica.
The master server verifies that
- Target server exists and doesn't currently hold a replica of the partition.
- Client has sufficient rights to the target server and the partition's root object.
- Partition is not currently involved in another partition operation that prevents an add. Another add or remove operation can be in progress, but any other partition operation will cause the request to be denied.
If the request is valid, the master server starts the process by
- Contacting the master replica of each subordinate reference to add a subordinate reference to the target server.
- Adding the replica to replica list.
- Setting the replica's state to RS_BEGIN_ADD.
- Sending the client reply indicating success or failure.
In Stage 2, the master server communicates the request to the replica ring. The master server completes the following tasks:
- Synchronizes its replica list with the replica ring.
- Changes the new replica's state to RS_NEW_REPLICA when subordinate references on the target server are in an RS_ON state.
- Changes the replica's state to RS_ON when the Transitive Vector indicates that the target server has seen the RS_NEW_REPLICA state.
The target server completes the following tasks:
- Adds the subordinate references for the partitions below the replica.
- Adds the replica.
- Receives an inbound synchronization that contains the replica's entries and updates.
- Waits until the end of a successful inbound synchronization with one server in the replica ring before synchronizing with other servers in the ring.
- Sends transitive vector updates to the replica ring as part of outbound synchronization.
4.4.3 Removing a Replica
You can remove a replica from a replica list or ring as long as the requester has managed rights to the partition's root entry, managed rights to the target server which holds the replica, and the target replica is not the master replica. If the target replica is the master replica, another replica must be designated as the master replica before the target replica can be removed.
The NetWare 4.x and NetWare 5.x processes are slightly different and use different replica states. However, both use a two stage process, and the first stage is identical for both. The second stage is different and is described separately for each.
Stage 1. In Stage 1, the client request is received by the master server and either accepted or denied.
The client sends the master server a request that contains
- The name of the replica to remove.
- The name of the server that holds the replica.
The master server verifies that
- The client has the rights to remove the replica.
- The server exists and holds the specified replica.
- The partition is not involved in another partition operation that prevents an add. Another add or remove operation can be in progress, but any other partition operation will cause the request to be denied.
If the request is valid, the master server starts the process by
- Changing the replica's state to RS_DYING_REPLICA.
- Sending the client a reply indicating success or failure.
NetWare 4.x. In Stage 2, the master server must contact the target server which holds the replica that is being removed.
The master server completes the following tasks:
- Sets the Replica attribute to dying and synchronizes it to the target server.
- Deletes the replica or converts it to a subordinate reference, depending on the request from the target server.
The target server completes the following tasks:
- Completes a successful inbound synchronization with the master server that contains the RS_DYING_REPLICA state.
- Completes a successful outbound synchronization that contains the state change with another replica that is not in the RS_DYING_REPLICA state.
- Sends the master replica a request to delete the target replica (if the parent replica wasn't local) or to convert the target replica to a subordinate reference (if the parent replica was local).
- Converts the target replica's root entry and the
children to either subordinate or external references:
- If the parent replica is local, converts the replica to a subordinate reference and the children to external references.
- If the parent replica is not local, converts the replica and its children to external references.
NetWare 5.x. In Stage 2, the master server can communicate the operation to any server in the replica ring, and any server in the replica ring can forward the operation to the target server.
The master server completes the following tasks:
- Sets the Replica attribute to dying and synchronizes the change with the replica ring.
- Changes the replica's state to RS_DEAD_REPLICA when the Transitive Vector indicates that target server has seen the RS_DYING_REPLICA state.
- Deletes the replica or converts it to a subordinate reference, depending on the flag in the Transitive Vector that indicates whether the target server has the parent replica.
The target server completes the following tasks:
- Completes a successful inbound synchronization that contains the RS_DYING_REPLICA state.
- Completes a successful outbound synchronization that contains the state change with another replica that is not in the RS_DYING_REPLICA state.
- Converts the target replica's root entry and the
children to either subordinate or external references:
- If the parent replica is local, converts the replica to a subordinate reference and the children to external references.
- If the parent replica is not local, converts the replica and its children to external references.
4.4.4 Splitting a Partition
You can split any partition as long as the new partition will have a container entry as its root entry. For example, in the figure below, you might want to create a new partition with Utils.Eng.ABC as the new partition root.
Figure 4-10 A Partition before a Split
After Utils has been split into a new partition, the tree structure looks like this.
Figure 4-11 A Partition after a Split
The NetWare 4.x and NetWare 5.x processes are slightly different. However, both use a two stage process, and the first stage is identical for both. The second stage is different and is described separately for each.
Stage 1. The client sends a request to split the partition with the name of the child partition root.
The master server verifies that
- The client has the rights to split the partition.
- The partition is not involved in another partition operation.
- All replicas are in an RS_ON state.
If the request is valid, the master server starts the process by
- Changing all replicas of the parent partition to RS_SS_0 state, setting the Partition Control attribute to RS_SS_0 state, and adding the name of the new child partition to the Partition Control attribute.
- Sending the client a reply indicating success or failure.
NetWare 4.x. In Stage 2, the master server must contact every server in the replica ring.
The master server completes the following tasks:
- Processes any obituaries that may be stored on the new partition root.
- Sends a split request to each server in the replica ring.
- Advances the state of each replica to RS_SS_1 as each replica indicates that it has successfully split the partition.
- Advances all replicas to RS_ON when all replicas reach the RS_SS_1 state.
- Sets the Partition Control attribute to idle, indicating that the operation has completed.
The servers in the replica ring complete the following tasks:
- Split the partition when the request is received.
- Return to the master server a reply indicating the successful completion of the split.
NetWare 5.x. In Stage 2, the split partition operation uses the following process. The master server completes the following tasks:
- Processes any obituaries that may be stored on the new partition root.
- Completes a successful outbound synchronization that contains the split information in the Replica and Partition Control attributes.
- Advances the replicas and the Partition Control attribute to the RS_SS_1 state when the master server's Transitive Vector attributes indicate that all replicas have seen the RS_SS_0 state.
- Advances all replicas to RS_ON and the Partition Control attribute to idle when the master server's Transitive Vector attributes indicate that all replicas have seen the RS_SS_1 state.
The servers in the replica ring complete the following tasks:
- Split the partition when they receive the RS_SS_1 state.
- Modify their transitive vector to indicate they received the RS_SS_1 state.
- Continue to perform outbound synchronization during the splitting states.
4.4.5 Changing Replica Types
You can change a nonmaster replica’s type, such as changing a read-only replica to a read/write replica. The process is different when the operation is used to assign a new master replica.
To change a nonmaster replica’s type, a client sends a Change Replica Type request to the server holding the partition’s master replica. The server then changes the replica type in its replica list and propagates the change to the other servers in the replica ring.
The Change Replica Type process can also be used to change where the master replica is stored. For this routine to succeed, the target server must hold a read/write or read-only replica of the partition. In a replica ring with mixed versions of eDirectory, the master replica cannot be changed to a server which is running an older version of NDS. The NetWare 4.x and 5.x processes are slightly different and use different replica states.
Changing the Master Replica in NetWare 4.x
In Stage 1 on NetWare 4.x, NDS uses the following process to change which replica is the master replica. The client sends the Change Replica Type to the source server containing the master replica.
The source server completes the following tasks:
- Verifies that the operation can take place by checking the client rights and ensuring that the target server contains a replica of the partition.
- Sets the state of the Partition Control attribute to RS_CRT_0 and stores the name of the new master server in the attribute.
- Sets the state of all replicas in the ring to RS_CRT_0.
- Returns a Change Replica Type reply to the client.
In Stage 2, the source server completes the following tasks:
- Synchronizes the state change to all the servers in the replica ring.
- Sends the target server a verb to change its replica type to master.
- Changes its replica type to read/write.
The target server, which will contain the new master replica, completes the following tasks:
- Changes its replica type to master.
- Sets all replicas in the ring to RS_CRT_1.
- Synchronizes the state change to all servers in the replica ring.
- When the synchronization has successfully completed, changes all replicas to RS_ON and sets the Partition Control to the idle state.
Changing the Master Replica in NetWare 5.x
In Stage 1 on NetWare 5.x, NDS uses the following process to change which replica is the master replica. The client sends the Change Replica Type to the source server containing the master replica.
The source server completes the following tasks:
- Verifies that the operation can take place by checking the client rights and ensuring that the target server contains a replica of the partition.
- Sets the state of the old master replica and the new master replica in the ring to RS_MASTER_START.
- Returns a Change Replica Type reply to the client
In stage 2, the source server completes the following tasks:
- Synchronizes the state change to the replica ring.
- When its Transitive Vector attributes indicate that the target server with the new master has received the state change, sets the state of old master replica and the new master replica to RS_MASTER_DONE.
- Synchronizes the state change to the replica ring.
- When its Transitive Vector attributes indicate that the target server has accepted the state change, changes its replica type to Read/Write.
The target server, which will contain the new master replica, completes the following tasks:
- When it receives the RS_MASTER_DONE state, changes its replica type to Master.
- When its Transitive Vector attributes indicate that all servers in the replica ring have received the RS_MASTER_DONE state, sets the state of all replicas in the ring to RS_ON and changes the Partition Control state to idle.
4.4.6 Joining Two Partitions
You can join a partition with its parent partition. Replicas of the two partitions do not have to be stored on the same servers. The Join Partitions operation makes the Replica list the same for both the parent and child partition, excluding the subordinate references from the parent’s replica list. When eDirectory creates all the replicas of the new partition, it erases the partition boundary.
For example, you might want to join the Test partition with its parent partition, Eng.
Figure 4-12 A Partition before a Join
After the operation, the partitions would look like this.
Figure 4-13 A Partition after a Join
NetWare 4.x and NetWare 5.x uses the same procedures in Stage 1 and slightly different procedures in Stage 2.
Joining Operation in NetWare 4.x
Stage 1. The client sends the master replica of the child partition a Join Partitions request.
The server with the child master replica performs the following tasks:
- Validates the request by verifying (1) that every server in the ring is running an NDS version equal to or greater than 435, (2) that the client has sufficient rights for the request, and (3) that the child partition is not involved in another partition operation.
- Sets the state in the Partition Control attribute to RS_JS_0 and stores the current operation (PC_JOINING_UP) in the attribute.
- Sets all the replicas of the child partition to the RS_JS_0 state.
- Sends a Join Start request to the server holding the master replica of the parent partition.
The server with the parent master replica performs the following tasks:
- When it receives the Join Start request, sets the state of the Partition Control attribute to RS_JS_0 and stores the name of the child partition and the current operation (PC_JOINING_DOWN) in the attribute.
- Sets all the replicas of the parent partition to the RS_JS_0 state.
- Sends the server with the child master replica a Join Start reply.
When the server with the child master replica receives the Join Start reply from the parent master, the child master sends the client a Join Partitions reply.
Stage 2. Both servers propagate changes to the servers in their replica rings. The server with the parent master replica performs the following tasks:
- Synchronizes the state change to all replicas.
- Obtains the servers in the child's replica ring.
- Sends an Add Replica requests to add parent replicas to the servers that have the child replica but not the parent. The parent replicas are set to the same type as the child (read/write or read-only).
- Waits while the replicas are added.
- When all the new replicas achieve an RS_ON state, sets all replicas in the ring to an RS_JS_0 state.
- Sets the state in the Partition Control attribute to RS_JS_1.
- Waits for the state of the child's Partition Control attribute to achieve RS_JS_2.
The server holding the child master replica performs the following tasks:
- Synchronizes the state change to all replicas.
- Obtains the servers in the parent's replica ring.
- Sends an Add Replica request to add child replicas to the servers that have the parent replica but not the child. The child replicas are set to the same type as the parent (read/write or read-only).
- Waits while the replicas are added.
- When all the new replicas achieve an RS_ON state, sets all replicas in the ring to an RS_JS_0 state.
- Sets the state in the Partition Control attribute to RS_JS_1.
- Waits for the state of the parent's Partition Control attribute to achieve RS_JS_1.
- When the parent's attribute achieves RS_JS_1, sets its attribute to RS_JS_2 and the replicas in the ring to RS_JS_2. (The replicas are never set to RS_JS_1.)
The server holding the parent master replica checks the state of the Partition Control attribute of child partition. When it reaches RS_JS_2, the server performs the following tasks:
- Sends a low level join request to all servers holding replicas of the two partitions. As each server receives the request, the server erases the boundaries between the partitions.
- Performs a low level join on its parent and child partition.
- Sets the replica state of the parent partition to RS_JS_2.
- Synchronizes the changes to all replicas.
- When the synchronization is completed, sets all replica states to RS_ON.
Joining Operation in NetWare 5.x
Stage 1. The client sends the master replica of the child partition a Join Partitions request.
The server with the child master replica performs the following tasks:
- Validates the request by verifying (1) that every server in the ring is running an NDS version equal to or greater than 435, (2) that the client has sufficient rights for the request, and (3) that the child partition is not involved in another partition operation.
- Sets the state in the Partition Control attribute to RS_JS_0 and stores the current operation (PC_JOINING_UP) in the attribute.
- Sets all the replicas of the child partition to the RS_JS_0 state.
- Sends a Join Start request to the server holding the master replica of the parent partition.
The server with the parent master replica performs the following tasks:
- When it receives the Join Start request, sets the state of the Partition Control attribute to RS_JS_0 and stores the name of the child partition and the current operation (PC_JOINING_DOWN) in the attribute.
- Sets all the replicas of the parent partition to the RS_JS_0 state.
- Sends the server with the child master replica a Join Start reply.
When the server with the child master replica receives the Join Start reply from the parent master, the child master sends the client a Join Partitions reply.
Stage 2. Both servers propagate changes to the servers in their replica rings.
The server holding the child master replica performs the following tasks:
- Obtains the servers in the parent's replica ring.
- Sends an Add Replica request to add child replicas to the servers that have the parent replica but not the child. The child replicas are set to the same type as the parent (read/write or read-only).
- Waits while the replicas are added.
- When all the new replicas achieve an RS_ON state, sets all replicas in the ring to an RS_JS_0 state.
- When all replicas have seen the RS_JS_0 state, sets the state in the Partition Control attribute and all replicas to RS_JS_1.
- When all replicas have seen RS_JS_1 or RS_JS_0, sets the Partition Control attribute and all replicas to RS_JS_2.
When the child replicas have reached RS_JS_2, the server with the child master replica has completed its tasks. The server with the parent master replica now treats it as just another server with copies of both the parent and child partitions.
The server with the parent master replica performs the following tasks:
- Obtains the servers in the child's replica ring.
- Sends an Add Replica request to add parent replicas to the servers that have the child replica but not the parent. The parent replicas are set to the same type as the child (read/write or read-only).
- Waits while the replicas are added.
- When all the new replicas achieve an RS_ON state, sets all replicas in the ring to an RS_JS_0 state.
- Sets the state in the Partition Control attribute to RS_JS_1 and synchronizes the changes.
- Waits until all replicas have seen RS_JS_1, then sets the replicas to RS_JS_2 and synchronizes the changes.
- When each replica receives the RS_JS_2 state, it erases the boundaries between the partitions. When all replicas have seen RS_JS_2, the server with the parent master replica erases the boundaries between the partitions.
- Sets the Partition Control attribute to idle and all replica states to RS_ON.
4.4.7 Moving a Subtree
eDirectory allows you to move any subtree under any container entry that meets the schema rules as long as the subtree to be moved has no child partitions.
The Move Subtree operation moves a container with all its child entries as a unit to another logical location in the eDirectory tree. No entries join or leave the partition during this operation, and the replicas of the partition are held on the same servers they were held on previously. In other words, eDirectory moves the subtree logically, not physically. The entries’ Distinguished Names change, but their Relative Distinguished Names do not.
For example, you may want to move object C and its subordinate objects under container F. Object C’s distinguished name would change from C.B.A to C.F.E.B.A. The subtree that you move must be the partition root The destination does not need to be a partition root, but can be any container within the destination partition.
Figure 4-14 The Subtree Move Operation
The Move Subtree operation is a three stage operation. The client makes two requests: one to the server containing the partition to move and the other to the server containing the new parent partition.
State 1. The client sends a Begin Move Entry request to the destination server which holds the master replica of the parent partition to which the child partition is moving. The request identifies the child partition that is moving and its new parent.
The destination server completes the following tasks:
- Verifies that the client has Create [Entry] rights in the destination container.
- Verifies that no other partition operations are in progress (all replicas are on and that the Partition Control attribute is set to idle).
- Sends the client a Begin Move Entry reply.
- Adds the child to its expectation list and sets a 10 minute timer. If the server does not receive a request to start the move operation within 10 minutes, the server clears the child from the expectation list.
Stage 2. The client sends a Finish Move Entry request to the source server. The source server is the server that holds the master replica of the child partition that is moving.
The source server completes the following tasks:
- Verifies the validity of the request by verifying that the partition is not busy with another partition operation and that client has delete rights to the child partition object.
- Receives the name of the server holding the master replicas of the destination container and sends this destination server a Start Move request.
The destination server completes the following tasks:
- Checks the Start Move request against its expectations list.
- Checks that all replicas are on and the Partition Control attribute is set to idle.
- Verifies that all servers in the replica ring are running a version of eDirectory that supports the move operation.
- On the destination's partition root, sets the function field in the Partition Control attribute to PC_MOVE_SUBTREE_DEST and the state field to RS_MS_0.
- Sets each child replica to RS_MS_0.
- Sends the source server a Start Move reply.
- Synchronizes the changes.
The source server completes the following tasks:
- Creates three Partition Control attributes and sets each function field to PC_MOVE_SUBTREE_SRC and each type field to a different type (PCT_0, PCT_1, or PCT_2).
- Sets all parent replicas to RS_MS_0.
- Adds an obituary (OBT_MOVE_TREE) for each server in the replica ring for the source and for each server in the backlink list.
- Sends a Finish Move Entry reply to the client
- Synchronizes the changes.
Stage 3. The source and destination servers complete the move. The client is no longer involved in the process.