Novell is now a part of Micro Focus

Using the DSREPAIR Utility Appropriately

Novell Cool Solutions: Feature
By Jim Henderson

Digg This - Slashdot This

Posted: 19 Apr 2005

As Novell's Directory Services products have evolved, so have the tools that are used for administering, monitoring, and fixing those products. In this article, we will examine the correct and incorrect uses of the venerable DSREPAIR utility.

The History of DSREPAIR

DSREPAIR was first released with NetWare 4.0 back in 1993. Its designed purpose back then still holds true today ? to check and fix consistency issues in the Directory Services Database (DIB) at both a physical and a logical level. DSREPAIR has evolved from a simple white-on-black NetWare utility with a very limited set of functionality into a tool that is capable of doing a lot of different things ranging from checking time synchronization status to forcibly removing a server from the tree.

Over the years, DSREPAIR has been updated to address problems found in various releases of NDS and eDirectory. This gives the utility a very long and complex history. Many of the advanced switches available in DSREPAIR today addressed issues that have long since been resolved in the core Directory Services code.

Historically, there were a few recommendations to run DSREPAIR outside of situations where you needed to fix a problem. A couple of these recommendations included:

  • Running a health check
  • Running as regular maintenance on the database (for example, on a weekly basis)

However, there were other ways in which Novell's customers have used (and continue to use) this utility that are not appropriate when running modern versions of eDirectory.


In order to understand how the DSREPAIR utility works, it is necessary to understand how normal directory operations work. In the X.500 Directory Model, there are a number of components, shown in Figure 1:

Figure 1: The X.500 Directory Model

From the standpoint of DSREPAIR, the components of the X.500 model that you need to understand are the Directory System Agent (DSA) and the Directory Information Base (DIB). As you can see in Figure 1, the only access to the directory for external DSAs (as well as the DUAs) is through the DSA on the server that holds the data in question.

The DSREPAIR utility bypasses the DSA and operates through a different set of interfaces used by the eDirectory tools. These tools provide lower-level access in order to check and fix the physical and logical structures in the database. Through direct manipulation of database tables, DSREPAIR makes decisions about database consistency and enforces consistency checks on any data that fall outside of those checks.

For example, say an object in your directory had flags indicating that the object was present and that the object was purgeable. If you understand how the obituary process operates, you will know that there are intermediate steps between the time an object is deleted and the time it is purged from the system, so an object that is not present and purgeable is a valid state. However, an object that is present and purgeable is not a valid state and DSREPAIR will likely change the presence flag from On to Off in order to make that object consistent.

What DSREPAIR Does Not Do

DSREPAIR is not capable of recovering lost data in the directory. For example, if you delete a critical object from the directory, DSREPAIR is not able to recover that object. It also cannot recreate a deleted administrative object from the tree--that would create obvious security issues.

The DSREPAIR utility should not be used for routine management tasks. While it has options to remove replicas from servers, it should not be used to do this unless the proper administration tool like iManager will not work. For example, if your server holding the Master replica of a partition has crashed and is not recoverable, you would use the DSREPAIR options to designate a server as the Master replica, because iManager, ConsoleOne, and NDS Manager will not change a read/write replica to a Master if the Master is not available.

Similarly, you should only use advanced switches when it is necessary to do so. A very large number of administrators always load DSREPAIR with the -A switch. This became a habit because in order to report on obituary status, you needed to start DSREPAIR with the -A switch and run the external reference check option to display the current obituaries in the system.

The -A switch (or -Ad on Unix and Linux) enables other functionality in other parts of the utility as well. For example, it allows you to designate a subordinate reference replica as a Master replica. This is not something you want to do when there are readable replicas in the replica ring because this action can corrupt objects in the partition. Think of it this way; you would not use the -XK2 switch (which destroys all replicas on the server) every time you run DSREPAIR; for similar reasons you should not use the -A switch.

How Should I Use DSREPAIR?

The simple answer to this question is "as infrequently as possible." Past recommendations were to run DSREPAIR regularly to correct various core code issues that Novell engineering was working on; these issues are now resolved and have been resolved for some time. A healthy directory can run for a very long time without needing "regular DSREPAIR maintenance."

The best way to use DSREPAIR is when troubleshooting eDirectory database problems? but not as a first step in that troubleshooting process. DSREPAIR is, by its very nature, a destructive tool. Many of the things that the utility does is to look at redundant information in the data and then make a decision as to which piece of information is authoritative. In most cases, something loses in that decision.

It's important to know why you are running DSREPAIR rather than just running it blindly. In the support forums, we have seen customers run DSREPAIR because clients were reporting -601 (object not found) errors ? an error that can easily be caused by a user mistyping their user name in the authentication dialog.

Under very few circumstances should the "Unattended Full Repair" option be used; this option is the sledgehammer of repair options. If you think you need to run the unattended full repair, stop and either ask a question in the forums or log a support call with Novell Technical Services. This particular option is most often used by administrators who think "something's wrong," but they are not sure what it is or how to find out. If you find yourself in this situation, it's time to ask for help.

Always start the troubleshooting process with non-invasive tools. There are much better tools available today to diagnose directory problems; DSTRACE has been around as long as DSREPAIR and is much less invasive; but learning how to read DSTRACE log files can take some time.

With the release of eDirectory 8.5, Novell included a tool called iMonitor. The iMonitor utility is the best non-invasive tool available to run health checks against the directory and it integrates with DSREPAIR to provide the proper DSREPAIR functionality when it finds a problem. In future articles, we will look at both DSTRACE and iMonitor in more depth.

By using appropriate tools to troubleshoot your eDirectory database before running a repair, you can tell whether the repair tool is even going to affect the problem. In many cases, running DSREPAIR has no effect on the problem, but just wastes time that would be better spent identifying and resolving the issues.

Novell Cool Solutions (corporate web communities) are produced by WebWise Solutions.

© Copyright Micro Focus or one of its affiliates