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 -- located in the 4.0x subdirectory) 
  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.89c  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 located in the 4.0x subdirectory created by 
     the 41NDS6.EXE file.

     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.89c 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.89c 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 <Enter>
        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 (located in the 4.0x subdirectory)
        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.

