TREEINT.NLM: NDS Tree Integration Utility
Articles and Tips: article
Software Engineer Senior
Strategic Partner Engineering
01 Jan 2000
Integrating a new server with NDS installed on it into an existing NDS tree is not an easy task, and can only be done with existing tools if the trees being integrated have the same schema and are exactly alike. This article explores using the TREEINT utility as a solution. TREEINT was created to make the merging, or integration, of a single-server NDS tree into an existing NDS tree a quick and easy operation.
- Introduction
- The Problem
- The Solution
- General
- Comparison of TREEINT to DSMERGE
- Running the Utility
- Installing Licenses on the New Server after a Successful Integration
- Logging and Error Handling
- Treeint.prm File
- Summary
Introduction
Novell Directory Services (NDS) is becoming widespread in the industry as more and more businesses realize the importance of directory services and make the decision to purchase NDS. Once a business has NDS set up and running they can expand their NDS tree by purchasing more servers, installing NDS on them, and creating new organizations in NDS to store more information. However, integrating a new server with NDS installed on it into an existing NDS tree is not an easy task, and can only be done with existing tools if the trees being integrated have the same schema and are exactly alike. Also, the existing tools will only merge the trees at the root of the existing tree, making the integration somewhat inflexible.
This article examines this problem and explores using the TREEINT utility as a solution.
The Problem
So, I want to integrate, or merge, two NDS trees! What version of NetWare am I running on the servers? What version of NDS do I have? Have I changed the schema in my existing tree, so it no longer matches the version of NDS on the tree I want to put into my existing tree? Do I want to move the new tree's data to the root of the existing tree, or do I want it somewhere else?
These are all valid questions for an NDS administrator preparing to merge two NDS trees. Merging trees is a complex operation that must be done carefully, so as not to corrupt the data on the tree that will remain once the operation is completed. To successfully integrate two disparate trees, the schema must match exactly. That is, each class and attribute definition must be exactly the same in both trees. An administrator must ensure the schema in both trees matches before a merge. The only way to do that is to compare the two trees, and, if there are differences, the schema must be manually changed using schema management tools.
When merging the trees, an administrator may not want to put the new tree's data at the root of the existing tree, but down into the tree below another organization or organizational unit. With current tools there is no choice it must go into the root. Once there, the administrator may partition the new tree's data and move it manually, but it takes time and may not work if not done correctly.
To accomplish the tree merge with existing tools, the administrator must use several tools currently available. Some of the tools are server based, and some of them are client based. The whole process takes a lot of time and does not always prove to be successful.
The Solution
TREEINT was created to make the merging, or integration, of a single-server NDS tree into an existing NDS tree a quicker and easier operation to perform. It takes the operations found in other tools and combines them into one application that runs with little user intervention. When an administrator runs TREEINT, it goes out and analyzes both trees, backs up the new tree's data, compares and reconciles the schema, installs the new server into the existing tree, and restores all the data. TREEINT works only on source trees with a single server object in the tree, such as when a new server is setup with NetWare and NDS and is in testing prior to putting into production.
After the utility has completed successfully, the new tree, with its server, volumes and data intact, is now a part of the existing NDS tree.
General
This NLM will integrate two NDS trees together by merging the source tree's server and data into an existing NDS tree (see figures 1-4 below). The source tree may be placed at any location in the destination tree. The NLM uses a parameter file, treeint.prm, to gather the information about the source and destination trees. This information tells the NLM which tree and server are the sources, and which tree is the destination. It also specifies where, in the destination tree, the source is to be placed. This file must be created in plain text, with an ASCII editor such as Edit, Notepad, or WordPad, and copied to the source server's sys:system directory. With this information, the NLM then proceeds to integrate the two trees.
TREEINT runs from the source tree's server. It was designed and developed to integrate an NDS tree that has only one server installed in it into an existing NDS tree that may have many servers in it. A single-server NDS tree such as this may have been setup by a user testing new applications prior to putting the server into production.
Figure 1: Overview of NDS tree integration.
Figure 2: The source tree prior to the integration.
Figure 3: The destination tree prior to the integration.
Figure 4: The destination tree after integrating the source tree below the root at Dest_Container and reinstalling the license on the source server (JEEP).
Comparison of TREEINT to DSMERGE
DSMERGE is an NLM written to merge NDS trees. It has been shipping with NDS for several years. As alluded to in previous paragraphs, DSMERGE accomplishes NDS tree merges in a slightly different way than TREEINT. The main differences between the two NLMs are as follows:
DSMERGE uses low level APIs such as CIA. TREEINT uses DSAPIs only.
DSMERGE merges the source tree into the destination tree at the root. TREEINT can merge the source tree into the destination tree either at the root or below the root.
DSMERGE compares the schema in the two trees to ensure they are exact prior to doing the merge. If differences are present, the utility will warn you that it can't continue. TREEINT also compares the schema, and, if differences are found, will attempt to reconcile those differences by modifying the destination tree's schema to make it compatible. If reconciliation cannot be achieved, you are warned of this fact and given the choice to continue or end.
DSMERGE will merge any two NDS trees, regardless of tree size and the number of servers in either tree. TREEINT will merge a source tree of any size but that only contains a single server; however, it can merge that source tree into a destination tree of any size with any number of servers.
DSMERGE can recover from a merge stopped, due to error(s), by backing out the changes made through the transaction tracking system. TREEINT has no ability to undo or restore either the source or destination tree in the event that an error has occurred that caused the application to end before the integration is complete. The destination tree is not modified to the extent that the source tree is. If a problem occurs, the administrator may be able to use the management tools to restore the tree to its original state.
Running the Utility
From the source server console type "treeint" and press "Enter". The NLM will start and display the opening and main menu. The following will be displayed on screen:
Tree Integration NLM v1.00 Copyright(c) 1999 Novell, Inc. All Rights Reserved ----------------------------------------------------------------------------------------------------- 1) Begin Tree Integration 0) Exit Enter Option Number:
Entering a "0" will exit the NLM back to the server console. Entering a "1" will start the NLM. When the NLM begins the integration, it will first search the sys:system directory on the source server for a file named treeint.prm. This file provides all the information the NLM needs to attempt the integration. Information in the file includes such values as the source and destination tree names, the admin names, server locations, and so on. If the file exists, the information will be read in and used. If the file does not exist, you will be prompted to provide it. A summary of the information will then be displayed.
If the information came from the file, the following line will be displayed on screen:
Input Values Obtained from Parameter File: [\system\treeint.prm] -------------------------------------------------------------------------------------
If you enter the information manually, the following line will be displayed:
Input Values Obtained from User -------------------------------------------
Immediately following the "input values obtained" line, the following lines will be displayed:
SRCTREE =[SOURCE_TREE] SRCUSER =[CN=ADMIN.O=SRC_CONTAINER] SRCPASSWORD =[] SRCSERVERDN =[CN=SRC_SERVER.O=SRC_CONTAINER] SRCCONTEXT =[O=SRC_CONTAINER] SRCSRVRCONTEXT =[O=SRC_CONTAINER] DESTTREE =[DESTINATION_TREE] DESTTREEADDRESS =[123.456.78.910] DESTUSER =[CN=ADMIN.O=DEST_CONTAINER] DESTPASSWORD =[] DESTCONTEXT =[O=DEST_CONTAINER] DESTSRVRCONTEXT =[OU=SRC_CONTAINER.O=DEST_CONTAINER] Ready to proceed with NDS tree integration. Continue? (Y/N):
At this time, you review the information and enters "Y" to begin or "N" to not begin. If "N" is entered, the NLM will take you back to the main menu. If "Y" is entered, the NLM will begin execution. The information in the file (or entered on screen) that is displayed on screen prior to the integration will depend on whether the source tree is integrated at the destination tree's root or if it is integrated below the destination tree's root. As the NLM runs, messages will appear on the screen as each section of the application runs. This provides you with a status of the integration as it runs and visual feedback to ensure the application has not "gone south. If any errors occur during the integration they will be displayed on screen. At the same time, a log file is being kept, and all the information is being logged into that file so you may refer to it later.
The following examples show the information that is displayed during integration:
Example 1: Integrating the source tree into the destination tree at the root
Initializing... Logging into source tree... Checking rights on source tree... Backing up source tree schema... Backing up source tree objects... Installing server into destination tree... Initializing the NWI APIs... Removing NDS... Setting current tree to destination... Setting up for the server install... Checking for schema upgrade necessity... Extending the NDS schema... Installing the DIB... Extending the NDS schema... Setting the supervisor password... Checking and upgrading the volumes... Terminating the NWI APIs... Logging into destination tree... Checking rights on destination tree... Comparing schemas on source and destination trees... Updating the destination tree schema... Restoring the data into the destination tree... Modifying the server attributes in the destination tree... Removing unknown objects from destination context... Tree Integration Completed Successfully
Example 2: Integrating the source tree into the destination tree below the root
Initializing... Logging into source tree... Checking rights on source tree... Creating destination subtree on source... Reconciling container attributes... Creating partition on source tree... Mutating the organization to an unknown type... Merging subordinate partitions on source tree... Moving subtree on source... Changing naming attribute to OU... Mutating the unknown to an organizational unit... Backing up source tree schema... Backing up source tree objects... Installing server into destination tree... Initializing the NWI APIs... Removing NDS... Setting current tree to destination... Setting up for the server install... Checking for schema upgrade necessity... Extending the NDS schema... Installing the DIB... Extending the NDS schema... Setting the supervisor password... Checking and upgrading the volumes... Terminating the NWI APIs... Logging into destination tree... Checking rights on destination tree... Comparing schemas on source and destination trees... Updating the destination tree schema... Restoring the data into the destination tree... Modifying the server attributes in the destination tree... Removing unknown objects from destination context... Tree Integration Completed Successfully
When the integration is complete, you are taken back to the main menu where the application may be exited by pressing "0" and then the Enter key. You must complete one last step in order to finish the integration: install the license on the server that was just migrated. This is explained in the next section.
Installing Licenses on the New Server after a Successful Integration
After a successful completion of the integration, you must reinstall the license onto the server that was just integrated into the existing tree. This step is necessary because TREEINT does not backup and restore the license objects for the server, and they must exist for the server to function properly. License installation is performed by running the NWConfig.NLM on the server where TREEINT was run (the source server). From the main menu select "License Options". From the next menu select "Install licenses" and follow the ensuing directions. Performing this step will ensure that the NLS license product container and certificate objects are created in the container where the server was installed (DESTSRVRCONTEXT, see explanation below). This in turn will ensure that there are no problems with licensing issues on the newly installed server in the existing tree. Installing the license on the new server will have no affect on the existing licenses in the existing tree.
Logging and Error Handling
A directory and log file were created on the source server at initial execution of the NLM. The directory is created just off the root of the volume and is named treeintd. The NLM sends all output from the application to both the screen and the log file. All errors encountered will also be displayed and logged. If any errors occur during execution, the program will act accordingly. That is, if a fatal error occurs, the NLM will halt execution. For non-fatal errors, the NLM will display and log the error and continue operation. You may be prompted to continue in the case where an error has occurred, and the application cannot automatically determine the next course of action to take.
There are also other files created and stored in the \treeintd directory. These other files are used during the integration and hold application data. Two of the files are extremely important: the schema and object backup files. The schema backup file is a copy of the source tree's schema. It is used during the schema comparison operation where the source and destination tree's schemas are compared to ensure an exact match. The object backup file is a copy of the source tree's NDS data. This backup is made during the integration and, once NDS is removed from the source server, this is the only record of that data until it is restored onto the destination tree near the end of the integration process.
As stated previously, TREEINT does not provide an undo or restore feature in the event an error occurred, and the integration did not complete successfully. For the source tree, once NDS has been deleted off the server prior to the install into the destination tree, it is too late to recover the data without writing an application to manually restore the database and the data. For the destination tree, the only operations that may have affected its integrity are schema modifications that have failed. If the source server gets installed into the destination tree, it can always be deleted using the management tools. If the data from the source tree is restored into the destination tree, it also can be deleted. If schema modifications fail, no damage may have occurred at all. In that case, the tree is still intact. If any schema is damaged, it may require you to run DSREPAIR to fix it up.
Treeint.prm File
This file provides a mechanism for nearly unattended operation of the tree integration utility. You will be prompted to begin the integration, for the source and destination tree admin passwords, to continue execution after reviewing the tree information, and to exit the program.
As this file provides information for integrating the two trees, it is extremely important that the information is correct. This file must be created by you in an ASCII (plain text) editor and stored in the source server's sys:system directory. No information other than that shown below must exist in the file. No comments are allowed, and the format must be exactly as shown. The following sections will explain the file in detail.
File Layout
The file contains the information about the source and destination trees. There are twelve lines, and each line contains two entries: a tag and a value. The file layout is as shown below:
SRCTREE:value; SRCUSER:value; SRCPASSWORD:value; SRCSERVERDN:value; SRCCONTEXT:value; SRCSRVRCONTEXT:value; DESTTREE:value; DESTTREEADDRESS:value; DESTUSER:value; DESTPASSWORD:value; DESTCONTEXT:value; DESTSRVRCONTEXT:value;
These lines must be entered exactly as shown, with real values replacing each "value." The tags must be verbatim, followed by a colon. The colon is followed by a value. Each line is then ended with a semicolon. No spaces are allowed in the tag portion or between the colon and semicolon. Values may contain spaces in the value itself. Two examples of file entries follow.
Example 1: Treeint.prm file when moving the source tree to the root of the destination tree
SRCTREE:source_tree; SRCUSER:cn=admin.o=src_container; SRCPASSWORD:*; SRCSERVERDN:cn=src_server.o=src_container; SRCCONTEXT:[Root]; SRCSRVRCONTEXT:o=src_container; DESTTREE:destination_tree; DESTTREEADDRESS:123.456.78.910; DESTUSER:cn=admin.o=dest_container; DESTPASSWORD:*; DESTCONTEXT:[Root]; DESTSRVRCONTEXT:o=src_container;
Example 2: Treeint.prm file when moving the source tree below the root of the destination tree
SRCTREE:source_tree; SRCUSER:cn=admin.o=src_container; SRCPASSWORD:*; SRCSERVERDN:cn=src_server.o=src_container; SRCCONTEXT:o=src_container; SRCSRVRCONTEXT:o=src_container; DESTTREE:destination_tree; DESTTREEADDRESS:123.456.78.910; DESTUSER:cn=admin.o=dest_container; DESTPASSWORD:*; DESTCONTEXT:o=dest_container; DESTSRVRCONTEXT:ou=src_container.o=dest_container;
Tag and Value Explanation
The tags must be verbatim, as shown above. The values entered will depend on the actual tree and server names.
|
SRCTREE |
The name of the source tree. The source tree is the tree that will be merged into the other tree, and will no longer exist when the integration is complete. It is the name given to the source tree with no types preceding the name. |
|
SRCUSER |
The fully distinguished name (FDN) of the source tree's admin user. This name must be fully typed and contain the name and context where the admin user is located in the source tree. This admin must have rights at the root of the tree. |
|
SRCPASSWORD |
The source tree admin password. This value must be a single asterisk (*). Security policies prohibit us from placing the actual password in a file on the network. Do not put a password in this field. |
|
SRCSERVERDN |
The FDN of the source tree server being integrated into the destination tree. This name must be fully typed and contain the name and context where the server object is located in the source tree. |
|
SRCCONTEXT |
The FDN of the root container of the subtree that will be moved into the existing tree. If the source tree is being moved to the root of the destination tree, this entry must be [Root], as shown above in example 1. If the source tree is being moved down into the destination tree below the root, this entry is the starting container of the source subtree, as shown above in example 2. During the integration, this container is created in the destination tree automatically, so this container must not exist in the destination tree prior to the integration. |
|
SRCSRVRCONTEXT |
The FDN of the context in the source tree where the source server is located. This name must be fully typed and contain just the context where the server is located, not the server name. |
|
DESTTREE |
The name of the destination tree. The destination tree is the tree the source tree will be merged into. It will remain as is after the integration is complete. It is the name given to the destination tree with no types preceding the name. |
|
DESTTREEADDRESS |
The IP address of the destination server that holds the master replica of the root of the destination tree. The IP address must be entered exactly in the format shown. If this address is not correct, the integration will fail. This address must be an IP address. TREEINT will not work if using any protocol other than IP. |
|
DESTUSER |
The FDN of the destination tree's admin user. This name must be fully typed and contain the name and context where the admin user is located in the destination tree. This admin must have rights at the root of the tree. |
|
DESTPASSWORD |
The destination tree admin password. This value must be a single asterisk (*). Security policies prohibit us from placing the actual password in a file on the network. Do not put a password in this field. |
|
DESTCONTEXT |
The FDN of the container where the source tree will be placed. If the source tree is being moved to the root of the destination tree, this entry must be [Root], as shown above in example 1. If the source tree is being moved down into the destination tree below the root, this entry is the container that will be the parent container of the source tree, as shown above in example 2. During the integration, the SRCCONTEXT container is created in the destination tree below this container automatically, so the SRCCONTEXT container must not exist in the destination tree prior to the integration. |
|
DESTSRVRCONTEXT |
The FDN of the context in the destination tree where the source server object will be created. This name must be fully typed and contain just the context where the server will be located, not the server name. If moving the source tree to the root of the destination tree, this name will be the same as SRCSRVRCONTEXT (o=src_container) as shown above in example 1. If moving the source tree below the root of the destination tree, this name will be the source server context appended with a dot and the destination context (ou=src_container.o=dest_ container), as shown above in example 2. In this case, remember to change the type of the source server context in the DESTSRVRCONTEXT field to OU= instead of O=. |
Summary
TREEINT was created to provide a means to integrate a single-server NDS tree into an existing NDS tree by merging a source server and data into the existing NDS tree. The source and destination tree schemas are automatically compared and reconciled if necessary and possible, and the source tree may be placed anywhere in the destination tree. The NLM accomplishes this by performing the following steps:
Reads a file to gather information about the source and destination trees.
Analyzes both trees.
Prepares the source tree containers for integration into the destination tree.
Backs up the new tree's schema and data.
Installs the source server and volumes into the existing tree.
Compares and reconciles the schema.
Restores the data into the existing tree.
TREEINT runs as an NLM on a NetWare server. It uses only documented DS and other system APIs, so it is compatible with versions of NetWare and NDS that support those APIs.
* Originally published in Novell AppNotes
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.