Using the Debug Symbols

DEPRECATED Since we have built-in crash detection in 0.4.x this is no longer required. You can still use this route but the simpler option is to use the crash dump file...

About this guide

This guide is not for the faint of heart. It is to introduce the windows debbugung kit and help you get started with debugging NSCloient++. Now why would you want to do that? The reason, and the only reason, is that you have a NSClient++ crash. Though rare they happen and this guide is to help you get the information I need to fix the issue.

You have to understand that the tools used here (windbg) are not something you casually install in your production enviornment. It is neither something you play with for fun. SO if you don't have a crashing NSClient++ stop reading here! :P

Now what this guide can help you with is not resolve the issues it is mainly to help you collect information so I can resolve the issue. This means that you dont need to know "programming" to follow this but I think it will help you a lot if you do. Another note is that this guide is more of a "getting started" then a complete walkthrough so expect to do this "again" after I analyze the first batch of the results.

WARNING I cannot stress this enough: This is not something you want to do inproduction

Getting the tools

There are some tools you need to do this. The first and most obvious one is windbg which comes (for free) with the Windows Debugging Kit (WDK). The second thing you need is the debug symbols for NSClient++ and finally you also need the NSClient++ sources.

1. Getting the Windows Debugging Kit

The Windows Debugging Kit is provided by Microsoft and can be downloaded from their page here ​http://www.microsoft.com/whdc/DevTools/Debugging/default.mspx. And you need the one for the specific platform you have (Win32/x64).

After you download it launch the installer and...

... click next...

Presumably the only thing you need is the debuggers but I tend to install everything since you never know.

Then once it is done click finish and you are done.

2. Getting the "debug version" of NSClient++

The debug version is actually just exactly the same version as the regular version with one addition along the the exe/dll/* files comes a set of pdb files which contain the debug symbols. To get the debug version download the "zipped" version of NSClient++ from the download page. You can either copy the pdb files to your installation from the zip or you use the binaries from the same zip. The benefit of using the binaries from the zip is that you know they are the exact same version. If you copy you have to copy from the accompaning zip from the version you have installed (it has to be the exact same version).

So I would use the zip distribution as is. It wont matter where you unzip the files but you need to remember where and as long as you don't run NSClient++ /install it wont "add" anything else so it is safe to delete the files afterward.

Once you have the files unzipped to a directory of your choice you need to copy the configuration file (nsc.ini) from your old distribution to this folder to get your specific settings.

3. Getting the sources

The sources are even easier just grab the sources zip and unzip to a directory of your choice. I tend to use \sources relative the debug symbols build installation since it is simpler to have it all in once place.

Using the tools

Now we have everything installed and setup and we are getting ready to start using the tools. And the general idea is to just launch NSClient++ in "test" mode (or possibly as a service but that requires you to "install" the debug symbol build). Now this guide wont do it like that since it is "harder" and we will instead launch everything from windbg in a step by step fashion. We will also not actually do much useful things except try to illustrate how this will work in a real word scenario.

4. Starting windbg

Start windbg like all other programs...

• Start button
• All Programs
• Debugging Tools for Windows (x86)
• WinDbg?

5. Loading NSClient++

The next step is to load NSClient++ and set a command line option to start it in test mode.

Start by clicking the "Open Executable..."

The next thing to do is to browse for NSClient++.exe BUT DON'T CLICK OPEN YET. It is very important here to type in "/test" in "Arguments" text box since without it NSCLient++ will think it is running as service (which it is not) so it wont work.

Also remember to use the "debug symbols enabled" version and not the "old" one as the regular installation lacks debug symbols and thus wont be very useful to debug.

Now we have loaded NSClient++ and hopefully everything is "ok" so far.

6. Starting NSClient++

What you have when NSClient++ has been loaded is three windows:

1. NSClient++ windows (the black window with no text)
2. WinDbg? COmmand window (the middle window wit a lot of text in it).
3. WindDg? main window (the bottom one we also had before).

The next step is to launch NSClient++ this is done by clicking the "go" button like so:

And finally this is how it looks when it is started. Notice that we now have "text" in the black NSClient++ window.

Now this window works just like regular "NSClient++ /test" so you are able to observe what goes on in the service as well as run commands and play around with NSClient++.

7. Crashing NSClient++

Not that we have NSClient++ up and running in the debugger we need a way to make it crash so we can see that it works. And this might seem a bit tricky at first but since I planed ahead I have added a command which will crash NSClient++ and that command is "assert". The code looks like so:

				} else if (s == _T("assert")) {
					throw "test";

Now the name is a bit misleading since it is in fact not an assertion fault instead it throws an exception. But not catching thrown exception is a valid fault so this will trigger a breakpoint inside WinDbg?.

So go ahead and type assert and hit enter.

Now this might not be what you expected, nothing happened?

Well, if we look in the command window (and log) we can see that something did happen. And what happened was that we triggered a "first chance" and then a "second chance" and then a break.

8. Analyzing Crashes

The first thing we need to do now is fire up the "stack trace" windows which will show us where the crash occurred. So click the "Call Stack" window to fire up the call stack.

In the call stack window we need to find the "NSClient++ location" which will (hopefully) be fairly easy to find usually something like c:\source\nscp\ or something like that. Now if you double click that line it will not be able to see the source (as you first need to point out the source files). But usualy when you double click a line in the stack trace window you will directly go to the line in question in the source view.

To define the source path first click "File" -> "Source file path".

In the window that pops up you need to add the folder you used before when you unzipped the sources.

Now go back to the stack trace window and double click the line highlighted here:

This time it worked out splendidly and we went to the corresponding line in the source view. Now if you know your way around programming (and C++) you will know that an exception comes from a throw. And as you can see in the screen shot below there is no throw here. Which at first glance might seem like an error. But the problem here is actually not the exception, throwing exceptions is just fine. The problem here is that we did 'not catch' the exception.Which is what we do just before we "exit" the program. And that is the line we end up on. Or actually we end up at the line "after" the return statement since the error occur just "after" the return.

Hopefully by now you have a slight understanding of how to use the Windows Debugging Kit to debug NSClient++ but it is important to understand that debugging applications is hard and this is just the first of many many steps but it is an important one because you now have the tools you need. But you have to understand you are most likely not going to find "your problem" this easy.