More On Using the DSTRACE Command
Articles and Tips: article
DeveloperNet University
01 Sep 2001
Last month we discussed how to get DSTRACE up and running. We also covered some of the basic DSTRACE commands. This time, lets get our hands dirty by doing something useful with the utility.
In the v4.x versions of NetWare, Novell engineers created a bunch of SET commands that were available on the server console. These SET commands were NDS debugging commands and they called it DSTRACE. With the introduction of NetWare 5 and later, the functionality of these SET commands, and a bit more technology, have been grouped into an NLM called DSTRACE.
When running DSTRACE from NDS eDirectory for Windows NT, just highlight dstrace.dlm, in the NDS Services control box. Then, click the start button to bring up the DSTRACE window.
Executing DSTRACE
For this month's column, I'm going to use NDS eDirectory on Windows NT as the basis for using DSTRACE. When you execute DSTRACE, the screen will look like Figure 1.
DSTRACE NLM Loaded on Windows NT console
Click on the Edit menu and then the Options submenu. This will bring up the NDS Trace Options screen, as seen in Figure 2. This screen shows all of the available NDS processes that you can monitor. By default, DSAgent, Initialization, Replication Process and Sync Incoming are checked.
DSTRACE Options Screen
Each of the checkable boxes represents a different NDS event or process that can be monitored by DSTRACE. For example, with the default events checked, you will be able to see status messages and error reports concerning inbound requests from other servers and clients (DSAgent), status messages and error reports concerning the NDS Database Initialization background process (Initialization), status and error reports concerning the NDS Replication process (Replication Process) and status and error reports for incoming synchronization events (Sync Incoming), as shown in Figure 3.
DSTRACE output with default settings
Let's look at this output step by step. The first line indicates that the DSTRACE utility is up and running. The next nine lines, down to the (-603) error are calls to internal NDS functions. They are all being called on behalf of connection 2, which is a system connection.
DSAResolveName resolves the specified name to an entry ID. In this case the name was sent from a client. DSARead returns the attribute values for a given NDS object, which was from the client attached at connection 2.
Now look at line 10, where NDS attempts a DSARead and gets a -603 error back. This error indicates that NDS was not able to read a requested attribute of the requested object. This could happen if the attribute doesn't exist or if there are insufficient rights to read the attribute.
The next block of code is similar to the first (lines 11 through 21), so I will not elaborate on these. Jumping to line 22, we see a request to start a partition sync. This process causes NDS to update all NDS partitions with the most current information available.
Line 23 indicates that the partition sync process was successful. Line 24 indicates that the partition has been updated. If the "All processed = YES" were to say "All processed = NO," then somewhere between lines 22 and 24 would be an error such as:
Agent: [07/31/01 xx:xx:xx]: SYNC: failed to communicate with server <xxx> ERROR: -625
If this was a real error, it would indicate that there are some synchronization problems on the server. This could be as simple as not being able to get to the requested server due to network problems, to as complex as a corrupt partition in NDS.
Saving DSTRACE Information
You may be interested in saving this output without using some sort of screen capture utility. DSTRACE has a mechanism that allows you to write the DSTRACE output to a log file. The log file is stored in the following directory, typically on your C:\ drive:
Novell\NDS\DIBFiles\nds00001.log
The filename will always be nds00001.log. One thing to be aware of is that the first part of the log file looks like garbage. This data is binary data and can be ignored. The rest of the file will be text output of your DSTRACE session, readable by any text editor such as Notepad.
The Janitor Process
Lets look at another example, this time the Janitor process. The Janitor process is an internal NDS process that cleans up NDS information. This process begins when an object is deleted or moved from NDS.
The Janitor Process in DSTRACE
The Janitor process determines which object was moved or deleted, marks the object in each NDS replica with an obituary state, and then purges the deleted or moved entries and values that have been synchronized with all the replicas. Additionally, the Janitor process does the following:
Checks the Status attribute of the server's object.
Checks all of the identities of the replicas on the server.
Automatically registers with another server to receive schema updates (if the server does not currently have any replicas.
Executes the flat cleaner process.
Performs optimizations of the NDS database.
Notifies the NetWare operating system when synthetic time is being used on a partition.
Updates inherited ACL attributes on the root partition objects.
Typically the Janitor process will be scheduled to run immediately after the NDS database is initialized (after bringing NDS up), and then is scheduled to run every 2 minutes.
Looking at figure 4, the first line of the Janitor process is the note that indicates the Begin Janitor . In the second and third lines lock the resource which is going to be cleaned up. Lastly, on lines four and five, the resource is cleaned up.
NCP Client and the NCP Engine Events of NDS for NT
The last area we will look at for this column is the NCP Client and the NCP Engine events of NDS for NT. Both of these events can be monitored by DSTRACE. NDS for NT is built upon the same core code as NDS for NetWare, NDS for Unix, etc. In order for NDS for NT to properly interact with the other versions of NDS, it needs to support a small subset of NetWare Core Protocols (NCPs). This is handled by a program called DHost. DHost sits beneath NDS and provides functionality on non-NetWare platforms that the NetWare operating system provides naturally. DHost provides the following NetWare oriented services:
NCP Engine
Watchdog
Connection Table
Event System
Thread Pool
NCP Extensions
Message Digest
Executable Module Manager
Memory Manager
NCP Request/Reply
Referencing Figure 5, there are two parts to typical NCP communication, a request and a reply. In this example, the request is the Calling DS Ping conn:2 for client . (This request is sending a DS_PING_TREE_NAME. This will return the tree name of the immediate server.) The reply is usually returned immediately after, but not always. In this example, it is returned sequentially. The response packet contains the requested information, which is the tree name FRESH_AIRE .
Conclusion
In summary, we have covered bringing up DSTRACE on a Windows NT server, introduced you to the events options available in DSTRACE and covered using some of these events. The events we have covered include DSAgent, Initialization, Replication Process, Sync Incoming, NCP Client and NCP Engine. We also touched on the NDS internal process Janitor.
Next month we will dive in deeper by discovering how to use DSTRACE to help in setting up/debugging a DirXML driver.
* 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.