Introduction: How to Setup a Windows Kernel Debugger Over Your Network

Debugging is a popular tool used to get to the root cause of a bug. A bug can maninfest itself in many different ways. it can cause a system crash (blue screen/BSOD), it can cause an application crash, it can cause your system to freeze to name a few issues. The root cause can be in the OS, a device driver or even a hardware issue. This guide will provide details on how to setup a debugger using Debugging Tools For Windows and hence is only focused on debugging with the Windows OS. I will not go into how to analyze the issue captured in the debugger.

A couple things to take note of:
  • This instruction set is designed for advanced computer users and the author has assumed that with these instructions.
  • For privacy sake some information has been obscured.

First thing we will go over are the items you'll need to setup your debugger.

Step 1: What You'll Need

What You'll Need
  • 2 Windows Computers
    • The Host computer which you’ll use for debugging. This computer must have Windows XP or newer installed
    • The Target computer which you’ll be debugging. This computer must have Windows 8 or newer installed. It must also have one of the network adapters found in the list here. http://msdn.microsoft.com/en-us/library/windows/h...
  • 1 Network Switch/Router (something that will assign IP addresses to the computers on the network)
  • 2 Cat5 cables
  • Debugging Tools for Windows which you need to install on the Host computer (http://msdn.microsoft.com/en-US/windows/desktop/bg162891)

Next we will go over what you'll need to do to set your computers up.

Step 2: Preparing Your Computers

The Host Computer
The Target Computer
  • Make sure you are using Windows 8 or newer
  • Make sure you are using a network adapter from this list http://msdn.microsoft.com/en-us/library/windows/hardware/dn337009(v=vs.85).aspx
  • Connect the computer to your Switch/Router

Now that we have the computers setup we'll need to connect them, starting with the target computer.

Step 3: Setting Up the Target Computer

You need a couple things to get your target computer ready. You need the IP address of your Host computer. You can obtain this by using the ping tool. Here is how to do this...

  1. Open a command prompt
  2. Type "ping -4 HostComputerName." You'll get something like the following...
ping HostComputerName
Pinging HostComputerName [192.166.0.123] with 32 bytes of data:
Reply from 192.166.0.123: bytes=32 time=2268ms TTL=128
Reply from 192.166.0.123: bytes=32 time=10ms TTL=128
Reply from 192.166.0.123: bytes=32 time=19ms TTL=128
Reply from 192.166.0.123: bytes=32 time=1ms TTL=128

Ping statistics for 192.166.0.123:
Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 1ms, Maximum = 2268ms, Average = 574ms

*Keep this windows open. You'll need it later.


Next you need to make some changes to the boot configuration. The changes to your boot configuration file will tell your target computer how to connect to the host computer. In order to do this you'll need to open a command prompt with administrator (elevated) permissions. Here is how you do that.

  1. Right click on the command prompt on the taskbar
  2. Right click on command prompt again
  3. Click "Run As Administrator" (User Account Control will ask if you would like to allow this program to make changes on your computer, click Yes)

Now you need to set the boot configuration settings for network debugging. You will do this by using the bcdedit tool. This tool is built into the OS and can be run from any elevated command prompt. The following steps show how you make these setting changes

  1. In this new command window run the following...
  2. bcdedit /dbgsettings net hostip=192.166.0.123 port=XXXXX key=z.z.z.z
  3. where the hostip equals the IP address you obtained when you ran the ping command, XXXXX equals any number between 50000 and 50099, and z is any alphanumeric combination. Here is an example ...
bcdedit /dbgsettings net hostip=192.166.0.123 port:50002 key=a1b.2c3.d4e.5f6


Remember the key that you created. You'll need this when you set up your host computer.

Now you need to turn the debugger on. You can use the same elevated command prompt that you were using before or open a new one. To turn debugging on run the following bcdedit command

  1. bcdedit /debug on
  2. restart the computer

Please reference the picture above which shows examples of all of the commands in this step.

Now that we have the target computer set up we can prepare the host computer to look for our target computer on the network.

Step 4: Setting Up the Host Computer

If you haven't already, the first thing you should do on the host computer is install "Debugging Tools For Windows" (http://msdn.microsoft.com/en-US/windows/desktop/bg... which was provided in an earlier step. Once this is installed you may proceed to the following steps.

To use the debugger from the command prompt.
  1. Open an elevated command prompt window
  2. Browse to the Debuggers directory where you installed the debugger. The default location looks like this. C:\Program Files (x86)\Windows Kits\8.0\Debuggers\
  3. If your host computer is running a 64 bit operating system, change directory to the x64 directory. If you are running a 32bit operating system on your host computer, change directory to the x86 directory.
  4. Type in the following command. kd - k net:port=XXXXX,key=z.z.z.z (Where XXXXX is the port you set on the target computer and z.z.z.z is the key you set on the target computer)
  5. Hit Enter

To run the debugger using windbg.
  1. run windbg from the directory you installed the debugger from. The default location looks like this. C:\Program Files (x86)\Windows Kits\8.0\Debuggers\.
  2. If your host computer is running a 64 bit operating system, change directory to the x64 directory. If you are running a 32bit operating system on your host computer, change directory to the x86 directory.
  3. Double click on windbg.exe
  4. Click on File
  5. Click Kernel Debug
  6. Select the Net tab
  7. Enter the port number you set on the target computer
  8. Enter the key you set on the target computer.
  9. Hit Okay

Please reference the pictures above which shows examples of all of the commands in this step.

Now that we have the host and target computers set up we can connect the two.

Step 5: Connecting to the Debugger

If everything is set up correctly this part is really easy. In fact after you set up the host computer you may have noticed a lot of text appear in the window. If so, you are done. If not, all you need to do is restart the target computer. As the target computer boots you'll start to see a stream of text in your debugging window (kd or windbg depending on which you use) on the host computer. It will looks something like the pictures above.

Step 6: In Conclusion

Now that you have successfully connected your computers with a debugger you can begin to help solve all the worlds computer problems. This is only the first step in a long road to getting to the root cause of any computer issue. Look for more articles in the future where I tackle how to begin investigating the many different problems that you may encounter.