Looking Into the Directory Services Trace (DSTrace) Options

Articles and Tips: article

Kevin Burnett
Software Engineer
DNU/Appnotes

01 Aug 2001

A year ago I was part of a development group at Novell that had several engineers working on DirXML drivers. The drivers were being developed for Lotus Notes, Windows NT, Netscape, and JDBC/Database connectivity. I was personally involved in creating a graphical installation utility for the JDBC driver and I was also working on a demonstration of the driver for BrainShare.

A lot has changed at Novell since that demo, including the formation of a development team to concentrate on writing DirXML drivers. During that early time in the development of DirXML drivers, I learned the importance of having good tools that aid in debugging. One such tool is provided with every version of eDirectory that ships. That tool is DSTrace.

The DSTrace Basics

For the next few issues, we will discuss DSTrace in this column, going over the available commands one by one. Directory Services Trace (DSTrace) is available as an NLM on NetWare and as a utility on the NT and Solaris versions of eDirectory. DSTrace is typically used as a troubleshooting aid to help debug problems with eDirectory and projects that utilize Novell Directory Services (NDS). DSTrace was originally used by the NDS engineers to aid in the development process. DSTrace has since been included with all shipping versions of NDS and eDirectory.

Let's start with the basics and then move to the more advanced topics. On a NetWare 4.x and above server, you start the DSTrace NLM by typing "DSTRACE" at the console prompt.

Note: Although this article uses the NetWare 5.x server as its basis, the same commands will work with Windows and Solaris versions of DSTrace as well.

To start the eDirectory trace screen, type the following at the console prompt:

SET DSTRACE=ON

The server will respond with the following:

DSTrace is set to: ON

On a NetWare 5.x server, you will need to switch to the screen titled "Directory Services" on the server console to see the DSTrace output. To do this, press the Ctrl+Esc keys to bring up the "Current Screen" window that lists all of the console screens that are available: you will then need to select the number corresponding to the "Directory Services" screen. Or you can press the Alt+Esc keys to toggle through the active console screens to the "Directory Services" screen. If you are running on Windows NT, you will have a separate window that will show the output.

Since the amount of eDirectory activity on your NetWork could easily fill up the DSTrace screen, causing it to scroll off the screen, there is an option to save the information to a file. By default this information is saved to the DSTRACE.DBG file located in the SYS:SYSTEM directory. To start saving DSTrace information to the DSTRACE.DBG file, enter the following commands at the NetWare 5.x console prompt:

SET DSTRACE=ON (Turns the trace screen on)

SET TTF=ON (Causes the output to be sent to the DSTRACE.DBG file, and the screen)

SET DSTRACE=*R (Resets the trace file, overwriting any old information)

After you have performed the actions you wanted to record in the DSTRACE.DBG file, make sure you turn it off. If you don't turn the Trace To File (TTF) function off, the DSTRACE.DBG file has a tendency to become very large, thus filling up your SYS volume over time. Type "SET TTF=OFF" at the server console prompt to turn off the TTF functionality.

While running, the DSTrace utility creates a small amount of overhead, especially when performing complex filtering. It is therefore not recommended to turn on DSTrace and leave it running indefinitely. Typically you will just run it long enough to troubleshoot problems with eDirectory or for help with development of NDS-compatible products. To deactivate DSTrace, type "SET DSTRACE=OFF" at the console prompt.

On a NetWare 5.x server, type "UNLOAD DSTRACE" to unload DSTace, thereby freeing up the memory used by the utility.

Before I get into the actual DSTrace commands, we need to discuss one other DSTrace SET command. To cause all of DSTrace's monitoring flags to be set at one time, type the following at your server console prompt:

SET DSTRACE=ALL

After typing this command, and assuming that DSTrace is ON, switching to the "Directory Services" server screen will show a lot of information. You will see any and all eDirecotry errors; you will see eDirectoy synchronization status; you will also see the status of all of the eDirectory hidden processes such as the janitor and limber processes.

To turn this "ALL" functionality off, type "SET DSTRACE=OFF" at your server console prompt.

DSTrace Asterisk Commands and Flags

The heart of the functionality of DSTrace is accessed by using asterisk (*) commands or flags. The remainder of this article and future columns will cover these asterisk commands. You can use these commands to start background processes and tune eDirectory processes, as well as to interact and monitor eDirectory processes. We will cover these commands in alphabetical order.

DSTrace uses the following syntax for these commands:

SET DSTRACE = <Flag>

Below is a chart listing the flag commands, as well as some of the actions that can be performed with each of the commands.

Flag (Command)	Action Performed
*B	This action instructs eDirectory to schedule the Backlinker background process to begin execution on the source server in one second.
*C	This action instructs eDirectory to display the statistics information for the source server's outbound connections to other servers. These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.
*CT	This action instructs eDirectory to display the source server's outbound connection table, as well as the current statistical information for the table. These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.
*CI	This action instructs eDirectory to display the source server's outbound connection table, the current statistical information for that table, and the idle information for the entries in that table. These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.
*CR	This action instructs eDirectory to display the source server's outbound connection table, the current statistical information for that table, and the IPX routing infromation being used. These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.
*CE	This action instructs eDirectory to display the source server's outbound connection table, the current statistical information for that table, and the WAN Manager expiration information for each connection in the table. These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.
*C0 (Asterisk-C-Zero)	This action instructs eDirectory to display the source server's outbound connection table and the current statistical information for that table, and then to reset the statistical information (after being displayed). These statistics do not reflect any information pertaining to the inbound connections that other servers or clients have to the source server.

Conclusion

Next month we will continue looking at the DSTrace asterisk flag commands. You may want to bring up your version of DSTrace and experiment using these commands.

* 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.