If you set up an environment for Windows kernel debugging the first time, it can be a bit confusing. So here is a small and hopefully simple tutorial for setting things up with VirtualBox and Windows 10 as a host OS. (Other Windows versions should work as hosts, too.)
Things you need:
- VirtualBox (You can use VMWare, KVM or whatever, but that is not described here.)
- A virtual machine with the Windows version you want to debug. This tutorial should work for debugging Windows 7 and higher. (A good source for free and legal Windows images is Microsoft itself.) I’m using a 32-bit Windows 7 version as an example.
- WinDbg and / or WinDbg64, depending on whether you choose to debug a 32-bit or 64-bit Windows. Both are part of the Windows Development Kit (WKD).
Setting it up
Install WinDbg (I suppose you are able to do that on your own) and get a VirtualBox image of your target - called “Debuggee” - installed in VirtualBox. Then open the virtual machine configuration and activate a serial port (COM1).
In the “Serial Ports” configuration select Portnumber COM1, Port mode “Host Pipe” and choose a name for the path, i.e.
\\.\pipe\windebugpipe. (You can replace ‘windebugpipe’ by another name here but keep it consistent in the following steps and make sure you keep the
\\.\pipe\prefix.) Leave the box “Connect to existing pipe/socket” unchecked.
- Start up the virtual machine. Now we need to set our virtual Windows in debug mode. Open a command prompt within the virtual machine as Administrator (right click on the command prompt symbole in the Task-Menu and chose “Run as Administrator” ). Enter
bcdedit /debug ON
- Now, on the Host, also open a command prompt as Administrator and fire up WinDbg.
Windbg -b -k com:pipe,port=\\.\pipe\windebugpipe,resets=0,reconnect
Note that the
portparameter should match your path in the VM settings. This should bring up WinDbg: WinDbg is now waiting for a connection to the debuggee.
- Restart the virtual machine. The VM should connect to your debugger. The debugger will probably already kick in in the boot process and stop the VM while windows is still starting up, so don’t be irritated if it stops loading. Press “g” and Enter in the Debugger command prompt to let Windows continue booting. If the debugger doesn’t kick in the first time, try to reboot the VM.
Now you are (hopefully) up and running for getting started with Windows kernel debugging. Your next steps would be to load the debugging symbols from Microsoft’s symbol server, e.g. via entering
in the debugger’s command prompt. Then figure out about basic WinDbg commands.
Troubleshooting / FAQ
1. The debugger doesn’t connect to the VM
Make sure that you set up everything right. If you open up a command prompt in the VM (Administrator) and enter
you should get the following output:
If not, try to specify the debug connection settings explicitly via:
bcdedit /dbgsettings serial debugport:1 baudrate:115200
and restart your VM. If you are still having problems, consult Microsoft’s documentation.
2. My debugger seems to hang
It takes some time for the debugger to connect and in some cases I had to wait a few minutes before everything was working as expected. So don’t give up too early. If it really blocks for 5 Minutes or more, restart the debugger and the VM (in this order). If your debugger hangs while loading symbols or executing some debugging commands, try pressing Ctrl+Break or select “Debug”->”Break” from the top menu of WinDbg.
3. I want to debug Windows XP or earlier
In this case, you won’t have bcdedit to set Windows into debug mode. Instead you have to play with the boot.ini file.
4. I’m using a different host OS than Windows
If you can run virtualization software like VirtualBox or VMWare on your OS, then you can (probably) use it to debug Windows. You just need one VM with a Windows running WinDbg and another VM with the Windows version you want to debug. As this case is already described in numerous blogposts, just consult your favourite searchengine.