DSMAINT.NLM version 4.91

 
The DSMAINT.NLM provides control of NetWare Directory Services
(NDS) when certain hardware maintenance operations are necessary. 
Because it deals with the Directory information on a specific
server, it is run from that server's console.  You may wish to
copy it to the SYS:\SYSTEM directory so it is available if
needed.

The DSMAINT utility provides functionality to address two
specific scenarios that NetWare administrators may experience.
Each specific situation is addressed by a pair of features in the
utility that work together.  One command begins a process;
another completes it.


Scenario One: NDS and Upgrading Server Hardware

There are times when a server requires an upgrade that does not
affect the server as a Directory object.  For example, the SYS:
volume may be physically located on an old hard disk drive that
needs to be upgraded.

In these situations, you no longer need to uninstall NDS from the
server.  You can use DSMAINT to prepare Directory information on
the server for the upgrade. Then, after the upgrade, you can
restore Directory information to the server with DSMAINT.

*** Please Note ***
 It is important to determine the usefulness of the Prepare and 
Restore options for the server being considered.  DSMAINT is very 
useful for an NDS master server containing a lot of partitions and 
replicas.  However, it might not be as helpful in a situation where 
the server only has a single or very few replicas.  The advantage of 
using DSMAINT is that object id's are maintained.  For an application
that is 100% NDS aware, this should not matter.  For a bindery based
application that keys off the object ID (i.e.  8 digit hex number), this 
can be critical.
*****************

The "Prepare NDS for a hardware upgrade" option prepares the
Directory information on this server for a planned hardware
upgrade of this server.  DSMAINT creates a file 
(SYS:\SYSTEM\BACKUP.DS) that stores all the Directory information
on this server, including replica information. This file should 
be included in backup procedures before bringing the server down.

The "Prepare NDS for a hardware upgrade" option locks and 
disables the Directory on this server, preventing any data 
change.  To other servers that normally communicate with this 
server, the server appears to be down.  Any Directory information 
that normally is sent to the locked server is stored by other 
servers in the Directory; the "stored" information is used to 
synchronize the server when it comes back online.

Because the global Directory is expecting the server to come back 
online quickly, you SHOULD NOT plan to take several days to 
upgrade the server.  Complete the upgrade PROMPTLY and restore 
Directory information on the server as soon as possible.

The "Restore NDS after a hardware upgrade" option uses the file 
created by the "Prepare..." option (SYS:\SYSTEM\BACKUP.DS) to 
restore Directory information on this server.  Before the 
Directory is restored, DSMAINT verifies that the server is in the 
same relative state as before the upgrade.  DSMAINT verifies that 
the server's object and authentication keys still exist and that 
the server still exists in all the replica rings for copies that 
were on this server before the upgrade.


****************** IMPORTANT ********************

- DSMAINT.NLM REQUIRES that partition and replica information be 
consistent during the entire Prepare and Restore process.  No
replicas should be added or removed.  No replica/partition types
should be changed.  No existing servers should be uninstalled and
reinstalled, and no new servers should be installed until the 
DSMAINT procedure is complete.  If consistency of the tree including
partitions, replicas and placement of replicas, and servers is violated,
the DSMAINT verification process will return a -601error during the 
RESTORE phase and the DSMAINT process CANNOT be completed.

- If you use backup software that needs to be logged in 
to the Directory, log it in before you use the "Prepare..." option.  
Because the option closes the Directory on the server, you cannot 
authenticate to the server after performing the "Prepare..." option.  
In addition, because DSMAINT effectively closes and temporarily
disables Directory Services on the candidate server, the resolve name 
algorithm will not function and trustees will not be backed up.  
You need to backup your volumes and file system before running 
DSMAINT.NLM as indicated by step 2.

- Be aware of the dependencies that other server currently have
on the server that is a candidate for DSMAINT.  Take into consideration
things such as TIMESYNC.  Is the server and integral part in the
time synchronization of the tree.  If so, resolve this prior to running
DSMAINT by possibly giving that function and responsibility to 
another server, and then checking to make sure the tree has
valid time synchronization status.

- Verify the integrity of the Tree and the partitions/replicas 
that the candidate server contains.  Use DSTRACE to verify the 
status and resolve any errors before continuing.

*************************************************


Procedure:

1. Log in your backup software or if you have a current backup
login from a client workstation as Admin.  The object of this step 
is to ensure that there is an authenticated connection with Admin 
rights to SYS:SYSTEM.

2. Backup volume(s) and file system(s) with the SMS compliant
backup.  For additional information on backup and restore, refer 
to the August 1995 Application Notes.

3. Load DSMAINT and use the "Prepare NDS for a hardware upgrade" 
option.  

4. Using the client workstation logged in as Admin or with Admin 
rights, copy BACKUP.DS and DSMAINT.NLM from the SYS:SYSTEM directory
to the client's hard drive.  OR,  backup the BACKUP.DS file located 
in SYS:SYSTEM with the SMS compliant backup.

5. Bring down the server and perform the hardware upgrade.

6. Use the INSTALL utility to reinstall NetWare and place a 
"temporary" Directory on the server.  You can use the same server name
and internal IPX address.  Because the private key is new, the servers
in the tree attempting to contact this server will be unable to authenticate
because the Public key will not match up with the Private key and hence 
receive an authentication error.   

********************************************************************
PLEASE NOTE:  Install the server to its OWN temporary Directory tree,
not your normal Directory tree.  This will allow client/backup
application access to the server volumes, specifically SYS:, to copy
the BACKUP.DS and DSMAINT.NLM to the SYS volume.   The temporary
Directory tree will be replaced in step 8. 
********************************************************************

7. Copy the DSMAINT.NLM and BACKUP.DS to the SYS:\SYSTEM directory 
either from the copy on the client workstation, or from the backup
as described in Step 4.

8. Use the INSTALL utility to remove NDS from this server.  This 
option is under INSTALL's "Directory options" menu.   ALSO, edit 
the AUTOEXEC.NCF file and verify the server name, internal IPX 
address and default time server type parameter to make sure 
they are correct.  These values should be the same as prior to DSMAINT
being run on the server.

9. Load DSMAINT.NLM at the server console and use the "Restore 
NDS after a hardware upgrade" option to restore the correct 
Directory information to the server.

10. Restore Data from backup performed in Step 3, to any volume/files 
that are affected by the hardware upgrade.

11. Run DSREPAIR to check volumes and trustees.  Use Advanced Options, 
Check volume objects and trustees.

IMPORTANT: This procedure may create trustee assignments that did 
not exist before the upgrade.  By default, the container object 
into which the server is installed receives Read and File Scan 
rights to the server's SYS:\PUBLIC directory.  If these rights 
were previously removed you will need to remove them again.


Scenario Two: Maintaining Server References during a Brief 
Shutdown

At times, it is necessary to remove a NetWare Server object from 
the Directory for a brief period of time.  For example, in the 
case of a corrupt authentication key, it is necessary to 
reinstall NDS on the server.  During the uninstall process, the 
NetWare Server object is removed from the Directory.  When the 
NetWare Server object is removed from the Directory, objects that 
reference it in their required attributes can become Unknown 
objects.  A similar type of problem can occur with services like 
printing that are associated with a physical server.

With DSMAINT, you can avoid losing objects and ease 
reinstallation by replacing references to the server with 
references to another object that you create for this purpose.  
After installing NDS on the server again, you can use DSMAINT to 
replace these references to the server in other objects' Host 
Server, Host Device, or Message (Default) Server attributes.

The "Replace server references" option searches the Directory and 
replaces references to this server's NetWare Server object in 
other objects' Host Server, Host Device, or Message (Default) 
Server attributes with a reference to another Directory object.

The "Restore server references" option restores references to 
this server in other objects' Host Server, Host Device, or 
Message (Default) Server attributes.  This option reverses the 
replacements made by the "Replace server references" option.

Procedure:

1. Begin by selecting an object for "holding" the references.  
This can be an existing User object, but must not be a NetWare 
Server object.  The user object you have logged in as would be 
appropriate.

2.  Now select the "Replace server references" option.  You are 
required to enter the full name of the container where you want 
to begin searching for objects that reference this server's 
NetWare Server object.  You also need to enter the full name of 
the object you want DSMAINT to use as a replacement value (such 
as a TEMP User object).  

3. At this point, you can uninstall and reinstall NetWare 
Directory Services.

4. Once NDS is properly operating, you can select the "Restore 
server references" option to reverse the replacements made by the 
"Replace server references" option.  You will again be required 
to provide the full name of the temporary object that is holding 
the references.

Note:  DSMAINT automatically removes volume IDs from the
physical volumes on the server so Volume objects are not removed
during an uninstall.


