UPGRADE.TXT ________________________________________________________________ This readme is for installations migrating from NetWare versions prior to 4.1, especially when a mixed 4.0x/4.1 environment might be maintained for a period of time. If all servers have been upgraded to NetWare 4.1 this information is unnecessary. This readme contains the following sections: I. Summary II. General Upgrade Hints III. Run DSREPAIR Before You Upgrade IV. Strategy for Migration V. Installing the New DS.NLM on Existing NetWare 4.1 Servers VI. Running a Mixed Environment for an Extended Time VII. Supplement to "Introduction to NetWare Directory Services" I. SUMMARY Part of the upgrade procedure is a check to be sure that there are no data inconsistencies in the current Directory Services data. Although Novell recommends that customers upgrade all servers to NetWare 4.1, a mixed environment will function properly if you use this procedure. To ensure that your upgrade is smooth, Novell recommends the following: - Run the DSREPAIR utility (version 2.23) on each NetWare 4.0x server before you upgrade the server. Note the instructions in section III of this readme. This file is supplied as REPAIR.NLM. - Upgrade all versions of NetWare 4.0x to NetWare 4.1 as soon as it is practical. - Install DS.NLM version 4.89 onto all NetWare 4.1 servers. This version of NDS is more tolerant of data inconsistencies in previous NetWare 4.0x NDS databases, and will provide better mixed environment interoperability. - Whenever possible, upgrade all servers in a partition at the same time. (When you upgrade NetWare 3.x servers, add them to partitions where all other servers have been upgraded to NetWare 4.1.) If you must maintain NetWare 4.0x servers, or if you must upgrade gradually, Novell recommends the strategy outlined in this readme. NetWare 4.1 has a more accurate means of tracking objects, containers, and other items in the NetWare Directory Services (NDS) tree using the time-and-date stamp. Because the time-and-date stamps on NetWare 4.0x servers might have been altered, there can be inconsistencies in the NetWare 4.0x data which may impact upgrades. The DSREPAIR part of the process will correct or identify data problems which could impede the upgrade process. Even if you are not ready to upgrade, you can use this DSREPAIR to correct data defects in the Directory Services database. II. GENERAL UPGRADE HINTS During your upgrade process you will be running in a mixed 4.0x/4.1 environment. Until all servers in the NDS tree are running NetWare 4.1, you won't fully realize the benefits of increased speed or reliability, nor can you use all 4.1 features. The following hints will help you with the upgrade process: - Read the errata that is found in the NetWare 4.1 box. - Read and follow the README.41 file. Install lets you read this document, but you should review it BEFORE you actually begin the installation. This ASCII text file is found in the \NW410\INSTALL\ENGLISH\README directory on the 4.1 CDROM and can be copied from the CDROM or read directly. The README.41 file covers important limitations of having a mixed 4.0x/4.1 tree. The most important parts of that document are included at the end of this readme as "VII. Supplement to "Introduction to NetWare Directory Services." III. RUN DSREPAIR BEFORE YOU UPGRADE A. POSSIBLE INCONSISTENCIES IN OLD TREE DATA NetWare 4.1 has many improvements to ensure reliable, stable use of Directory Services. Much work was done to ensure that the data contained in older versions of NetWare Directory Services would migrate easily to the current release. To optimize NetWare 4.1 NDS performance, check for possible NDS database inconsistencies before upgrading. The version of DSREPAIR included in this package has features which make it a useful tool to check a NetWare 4.0x NDS database before upgrading to NetWare 4.1. The DSREPAIR.NLM is named REPAIR.NLM in this package. Because running DSREPAIR before upgrading ensures that NetWare 4.1 will perform as designed, run DSREPAIR version 2.23 on EACH 4.0x server before you upgrade that server. This DSREPAIR will run only on NetWare 4.0x servers and is not intended for NetWare 4.1 servers. Although this DSREPAIR will correct most NDS Database inconsistencies, there may be a few conditions where you will need to contact Novell. Those conditions are indicated in the special DSREPAIR instructions below and are indicated by the code [PBD]. Contact Novell to resolve these problems before upgrading. You should contact Novell through your standard support channel, such as your reseller, distributor or consultant. B. RUNNING DSREPAIR The document, REPAIR.DOC, has the general operating instructions for this version of DSREPAIR. The following are specific instructions and a summary of some of the features in this version of DSREPAIR that have proven useful to some of our upgrading customers. This version of DSREPAIR will allow the user to more quickly resolve possible issues and upgrade easily. To use this DSREPAIR, copy it to SYS:SYSTEM on the NetWare 4.0x server or run it from a diskette. By running the various options, and appending to the LOGFILE, you will obtain a record in the file SYS:\SYSTEM\DSREPAIR.LOG that can be viewed in an editor or printed. DSREPAIR will correct many errors automatically, but you must manually correct some errors before upgrading. After correcting the errors, re-run DSREPAIR to make sure you have not missed any. - Communication errors: All servers must be properly synchronized before you can perform an upgrade. If a server is down, or is not communicating properly, this condition will be reported in the error log. You must resolve the communication link or bring the server up and allow synchronization to complete. If the server has been removed from the network but still exists within the Directory Services database, follow the instructions in the DSREPAIR.DOC. You won't complete a smooth upgrade if you are experiencing communications problems. - Same name Siblings: With NetWare 4.0x, objects with duplicate names but of different types were allowed. For example, in NetWare 4.0x a container and a user could have the same name. This is not permitted in NetWare 4.1 (to simplify use and prepare for future applications). Before you upgrade, rename (or delete) the leaf object (user in this example). This version of DSREPAIR locates and report siblings of the same name for you. If you see an entry indicating a duplicate name, as in Duplicate or ambiguous name: [objectname] go to NWADMIN (or NETADMIN) and rename one of the objects. - Duplicate Time Stamps: No two objects should have the same time stamp. Previous problems with your time synchronization could have caused incorrect time stamps. This condition results in a [PBD] timestamp entry in the error log. If you receive a [PBD] Timestamp in the error log, you must delete one of the objects. Following, allow time for synchronization and then rerun DSREPAIR to verify that no duplicate timestamps exist. If both objects are container objects, and both have a significant number of leaf objects below them, deleting and recreating one of the objects manually could be very time consuming. WARNING: If the LOGFILE contains any messages with the prefix [PBD], as in [PBD] Duplicate creation time stamps DO NOT UPGRADE the server. Contact Novell to assist in resolving the problem before upgrading. You may continue to operate the server as a NetWare 4.0x server until this data is corrected. - Backlinks and External references: External references are pointers used when object information must be maintained where the object itself does not exist. For example, an external reference would be used when a user has rights to a file on a server that does not contain a replica of the partition where the user object is located. Directory Services maintains these pointers and they must be properly back linked (associated with real object) before you upgrade. To verify that the external references are correct, from the main DSREPAIR menu choose option "8". External references that might not properly match the real object will be corrected. If improper external references are found and cannot be corrected they will be identified in the LOGFILE. If the LOGFILE contains any messages with the prefix [PBD] as in [PBD] TIMESTAMP: External reference .... DO NOT UPGRADE the server. Contact Novell to assist in resolving the problem before upgrading. You may continue to operate the server as a NetWare 4.0x server until this data is corrected. IV. STRATEGY FOR MIGRATION Upgrading from NetWare 4.0x to 4.1 is a fast process. In general, the process consists of copying new NetWare 4.1 files to the server and restarting. Unless WAN links are involved, this process should take less than 30 minutes. Although you can upgrade several servers at once, if many servers are involved the upgrade could still take some time. If you will not be running in a mixed environment for an extended period of time, the order of upgrade may not be significant. It is generally best to upgrade all servers in a given partition. Until all servers in a given partition are 4.1, the full benefits will not be realized. When upgrading NetWare 3.x servers to NetWare 4.1 it is best to upgrade it into a partition in which all servers are running 4.1. This ensures proper migration of the bindery information into the Directory Services database with no chance for data inconsistencies. V. INSTALLING THE NEW DS.NLM ON EXISTING NETWARE 4.1 SERVERS The 4.89 version of NetWare Directory Services is more tolerant of data inconsistencies in previous NetWare 4.0x NDS databases, and will provide better mixed environment interoperability. Although version 4.89 is designed for mixed environments, all NetWare 4.1 servers will benefit from running this version. DS.NLM is normally installed as part of a server upgrade or new install. It also may be loaded and activated on existing NetWare 4.1 servers without downing the server. Procedure To install the new DS.NLM: 1. Log into the network as ADMIN or a user with rights to the SYS:SYSTEM of a newly installed or upgraded file server. Locate the file SYS:\SYSTEM\DS.NLM 2. Copy the file to the SYS:SYSTEM directory of the NetWare 4.1 file server to be upgraded and overwrite the existing file. 3. At the file server console of the server being upgraded (or using RCONSOLE) toggle to the system console screen. 4. Enter the command "SET DSTRACE = *." and press to reload the Directory Services without downing the server. 5. Repeat the process for each 4.1 server in the network which may be running the older version. VI. RUNNING A MIXED ENVIRONMENT FOR AN EXTENDED TIME The remainder of this document applies only to customers who plan to run NetWare 4.0x and NetWare 4.1 servers on the same network for an extended time (weeks or months). A number of situations could delay completion of your upgrade. These might include: - Circumstances which prevent you from taking certain servers off-line, even for short periods, until specifically scheduled. - Organizational issues where different parts of the tree are controlled by different people. - Running incompatible software that might prevent upgrading the server in a timely manner. Although the suggested order below may be used for all upgrades, it is very important when the upgrade will occur over an extended time period. A. SUGGESTED UPGRADE ORDER 1. List all servers to be upgraded and verify that you have access rights to each one. 2. For each server, determine if any associated software must also be upgraded. 3. For each server, list all replicas on the server, indicating if it is a master or a read/write replica. 4. Make a list of all partitions. For each partition, list all servers which have a replica. Note which server is the master. 5. Note which partitions have a large number of replicas (more than four or five). Removing these extra copies can make the process much faster and simplify your planning. Nevertheless, consider any fault tolerance or bindery services issues that may exist. Add the copies again after the upgrade is complete. 6. Starting at the BOTTOM of your tree structure, select a partition to be upgraded. Remember that the benefits of NetWare 4.1 are not fully realized until all servers that hold a replica of the partition are upgraded. 7. Select a server with a read/write replica as your first server. Using the process detailed above, run the DSREPAIR version 2.23 to ensure that the Directory Services data is consistent. If necessary, correct errors and rerun DSREPAIR. Upgrade the server. 8. Upgrade the remaining servers in the partition (running DSREPAIR first), upgrading the server holding the master replica last. You want to maintain the MASTER replica on a NetWare 4.0x server until all servers are upgraded to NetWare 4.1. 9. Select another partition near the bottom of the tree structure and upgrade all servers in that partition in the same manner. If several partitions are at the same level in the tree, select the one with the fewest replicas to do first. 10. Continue working up the tree. Because servers in one partition will likely contain replicas of another partition base your selections so as to complete all servers in a partition whenever possible. 11. If a server which cannot be upgraded quickly contains the master replica of a partition, consider moving the master replica to a different server (one which will be maintained at NetWare 4.0x). NOTE: - Partitions not fully upgraded are subject to some limitations in further partitioning (as detailed in the "VII. Supplement to 'Introduction to NetWare Directory Services" section. - Servers which hold no partition replicas can be upgraded at any time. - NetWare 3.x servers can be upgraded to 4.1 at any time as long as the partition to which they are being added has been completely upgraded to NetWare 4.1. B. EXAMPLE In this example, each server can only be out of service late at night on a weekend. Therefore, the upgrade would be performed over a period of several weeks or months. [root] | | | cn=A +---- ou=ONE This plus root is a partition | + | | cn=F | | +---- ou=THREE Containers TWO, THREE, and | + FOUR are a partition | | cn=C | | +---- ou=TWO + | cn=B | +---- ou=FOUR | | +---- ou=FIVE Container Five is a partition + | cn=D | cn=E PARTITION SERVER ONE TWO FIVE A R/W __ __ B M M __ C R/W R/W R/W D __ R/W R/W E __ R/W M F __ __ __ Example Procedures 1. Select partition five, at the bottom of the tree. Run DSREPAIR on server "D" and upgrade it. NOTE: This server has a replica of partition TWO which is now partially upgraded. 2. Move the Master of FIVE from "E" to "C" and upgrade server "E". This only affects partition TWO and FIVE. Upgrading server "C" would also affect partition ONE because of the placement of the MASTER replica. 3. Perhaps upgrade "F" now, if convenient. 4. Upgrade server "C." 5. Since partition FIVE is complete, but TWO is partially complete, next select partition TWO. (All but server "B" have been upgraded.) 6. Move the Master replica of partition ONE from "B" to "A." This must be done before server "B" is upgraded. After server "B" is upgraded to NetWare 4.1, you cannot move the MASTER replica to server "A" which is still a NetWare 4.0x server. 7. Upgrade server "B." 8. Complete the upgrade with server "A." NOTE: moving the master replica is only necessary if there is any possibility that partition operations might need to be done unexpectedly before you complete the upgrade. Once a partition is fully upgraded there are no partition limitations and the full benefits of 4.1 are realized. VII. SUPPLEMENT TO "INTRODUCTION TO NETWARE DIRECTORY SERVICES" A. PARTITIONING RULES FOR MIXED NETWARE 4.1 AND 4.0x NETWORKS If, when upgrading a NetWare 4.0x Directory tree to NetWare 4.1, you are unable to upgrade all servers to 4.1 at the same time, the following partitioning rules apply to Add, Split, Join, and Remove Partition and Change Replica Type operations. 1. If the Master replica of a partition resides on a NetWare 4.0x server, then all partition related operations can be performed in a mixed environment. 2. Once the Master replica of a partition has been moved to a 4.1 server, the Master replica cannot be moved back to a 4.0x server. Also Add, Split, and Join partition operations no longer works for that partition until all servers have been upgraded to 4.1 or the 4.0x servers containing replicas of the partition have had their replicas removed. 3. A subtle problem occurs with Subordinate References on 4.0x servers. If a master replica of a partition resides on a 4.1 server, the Add, Split and Join partition operations will not work if a 4.0x server contains a Subordinate Reference of the partition in question. 4. The Remove Partition operation will always work regardless of where the Master replica of the partition exists. 5. The Change Replica Type operation will always work in a mixed environment except in the case where the Master replica has been moved to a 4.1 server. In this case the master replica can only be moved to another 4.1 server. However, any 4.0x servers with replicas of the partition can be changed to Read Write or Read only. The following matrix shows what partition operations are possible in a mixed environment. The Master column indicates the version of the server containing the master replica of the partition. Partition Operation Server Versions Master 4.01 4.02 4.1 _______________________________________________________ Add Replica | 4.01 OK OK OK | 4.02 OK OK OK | 4.1 (NOT OK) (NOT OK) OK Split Partition | 4.01 OK OK OK | 4.02 OK OK OK | 4.10 (NOT OK) (NOT OK) OK Join Partition | 4.01 OK OK OK | 4.02 OK OK OK | 4.10 (NOT OK) (NOT OK) OK Remove Partition | 4.01 OK OK OK | 4.02 OK OK OK | 4.10 OK OK OK Change Replica Type | 4.01 | 4.02 ( See number 5 above) | 4.10 B. THE DISTINGUISHED NAME OF AN OBJECT CANNOT EXCEED 256 CHARACTERS When leaf objects are created, they are checked to ensure that the maximum name length of the Distinguished Name is not exceeded. However, it is possible to go back and rename a leaf object with a longer name and cause the Distinguished Name to exceed 256 characters. The following is an example of a Distinguished Name: CN=Morty Hansen.OU=Toy Sales Department.OU=Sales Department.O=Fun Toys 4 U.C=US.TOYS_TREE Each ".OU=" is counted in the total character count, including the name of the NDS tree. C. INACCURATE ILLUSTRATION OF PARTITION REPLICATION Figures 6-2 and 6-3 in Chapter 6, of "Introduction to NetWare Directory Services" indicate that more than one Master replica can exist for a particular partition. The figures should illustrate that only one Master replica can exist per partition. D. DSMERGE If you merge several trees together, you will need to reassign administrative rights to the supervisor of the first tree. For example, if Tree1 is merged into Tree2, which is then merged into Tree3, the ADMIN on Tree1 loses its administrative rights. Using the ADMIN from Tree2 or Tree3, reassign administrative rights to ADMIN on Tree1. ================================================================ Disclaimer Novell, Inc. makes no representations or warranties with respect to the contents or use of this document, and specifically disclaims any express or implied warranties of merchantability or fitness for any particular purpose. Further, Novell, Inc. reserves the right to revise this publication and to make changes to its content, at any time, without obligation to notify any person or entity of such revisions or changes. Novell, Inc., makes no representations or warranties with respect to any NetWare software, and specifically disclaims any express or implied warranties of merchantability, title, or fitness for a particular purpose. Distribution of any NetWare software is forbidden without the express written consent of Novell, Inc. Further, Novell reserves the right to discontinue distribution of any NetWare software. Novell is not responsible for lost profits or revenue, loss of use of the software, loss of data, costs of recreating lost data, the cost of any substitute equipment or program, or claims by any party other than you. Novell strongly recommends a backup be made before any software is installed. Technical support for this software may be provided at the discretion of Novell. Trademarks Novell, Inc. has attempted to supply trademark information about company names, products, and services mentioned in this document. The following list of trademarks was derived from various sources. Novell and NetWare are registered trademarks NetWare 4.01, NetWare 4.02, NetWare 4, NetWare Client, NetWare Directory Services and NDS, and N.M. are trademarks of Novell, Inc. All other products and company names are trademarks or registered trademarks of their respective holders.