System Tools - KDVMWARE

KDVMWARE

Fast kernel debugging of VMWARE virtual machines

Kernel Debugging for VMWARE

System developers, who use kernel debugging for analyzing their drivers or applications, have two options:

Use a separate computer as testing workstation, and do kernel debugging over serial cable, USB cable or 1394 (FireWire)
Use virtual machine (VMWARE) as testing workstation, configure virtual serial port to write data to named pipe and attach WinDbg to the naped pipe.

For those who decided for the latter option, you need to do these steps to make it working. This way of kernel debugging is quite comfortable. However, VMWARE emulates serial port with all its limitations, including its slow speed. So far, there is no builtin way how to speed the debugging up.

On his webpage, Skywing published a way how to combine VMWARE's internal communication channel, VMWARE-VMX's RPC dispatch hooking and DLL injection to create a fast kernel debugging. My KDVMWARE project has been inspired by Skywing's work, and uses vast majority of his know-how. The aim of my project is not to publish his work under different name, but rather to make kernel debugging configuration easier and more comfortable, especially when there are many virtual machines used, with various operating systems. Also, I wanted to summarize configuration of various guest operating systems.

Components

KDVMWARE consists of three components:

Kdvmware.dll - This is transport DLL for debugee, and it's the provider of the speed debugging itself. It must be present on each guest operating system that can (and will) use speed kernel debugging. Kernel debugger transport DLLs are supported by Windows XP or newer, both 32-bit and 64-bit. Kdvmware.dll needs to be copied to %WINDIR%\System32.
KdClient.dll - This is a DLL that is to be injected into VMWARE-VMX.exe. After injection, KdClient.dll checks for configuration of the virtual machine. Based on the configuration, it either uses built-in VMWARE's capability to write data from serial port to a named pipe, or it creates a new entry in the VMWARE-VMX.exe's RPC dispatch table in order to handle data sent by debug transport DLL. After that, it makes shared section where VM name and pipe name are provided. Those are read by KdVMware.exe and used to launch debugger.
Kdvmware.exe - This is VMWARE Kernel Debugging Assistant and needs to be copied somewhere on the host operating system, together with KdClient.dll. Once executed, it watches for running virtual machines. As soon as a virtual machine is executed (i.e. a process named VMWARE-VMX.exe is found), Kdvmware.exe injects KdClient.dll into it and automatically executes WinDbg.exe with predefined workspace and VM title. When the VM exits, Kdvmware.exe automatically closes Windbg.exe that was debugging it.

The following picture explains how the entire system works:

How to make it work ?

KDVMWARE has been tested on Windows 2000, Windows XP, Windows 2003 Server, Windows Vista and Windows Seven. It was tested with VMWARE Workstation version 6.5.3 and should work on earlier versions as well. The following table summarizes steps needed to make KDVMWARE work.

Guest side (Windows 2000 or older)

Download KDVMWARE and save it somewhere on your hard drive, like C:\KDVMWARE.
Set-up kernel debugging in your virtual machine, as explained here. Windows 2000 doesn't support debug transport DLLs, so Kdvmware.exe needs to use VMWARE's built-in capability of writing data from serial port to a named pipe.

Guest side (Windows XP)

Download KDVMWARE and save it somewhere on your hard drive, like C:\KDVMWARE.
Pick 32-bit or 64-bit version of Kdvmware.dll, depending on your guest operating system and copy it to %WINDIR%\System32.

Add a new line to your C:\Boot.ini:

multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Microsoft Windows XP Professional" /fastdetect /debug /debugport=VMWARE

Do not create virtual serial port, and make sure there is no serial port configured to write data to named pipe.

Guest side (Windows Vista and Windows Seven)

Download KDVMWARE and save it somewhere on your hard drive, like C:\KDVMWARE.
Pick 32-bit or 64-bit version of Kdvmware.dll, depending on your guest operating system and copy it to %WINDIR%\System32.
Create a new debug configuration, using Bcdedit.exe. Alternatively, you can also use BellaVista tool.
```
bcdedit /copy {current} /d "Name of new configuration"
```
For the newly created debug configuration, enable test-signing mode:
```
bcdedit.exe /set {GUID} testsigning on
```
For the newly created debug configuration, set debug transport DLL:
```
bcdedit.exe /set {GUID} dbgtransport kdvmware.dll
```
Do not enable debugging, as it would override using debug transport DLL.
Do not create virtual serial port, and make sure there is no serial port configured to write data to named pipe.

Guest side - Network debugging (Windows 8 or newer)

Network debugging doesn't use the fast VMWARE port communication, because it's far faster than default serial port debugging. You will need Windows 8 and also WinDbg of version 6.2.9200.16384 or newer. To setup network kernel debugging, please, follow these steps:

Create a new debug configuration, using Bcdedit.exe. Alternatively, you can also use BellaVista tool.
```
bcdedit /copy {current} /d "Name of new configuration"
```
For the newly created debug configuration, set network debugging:
```
bcdedit.exe /dbgsettings NET HOSTIP:###.###.###.### PORT:50000
```
Note that the IP address present after "HOSTIP" is the IP address of the machine with debugger. You can also select different port number.
Copy the network key that comes as output of BCDEDIT.exe. If you are using BellaVista, the key will be shown in the GUI.
In the directory where the virtual machine is, create a file named "kdvmware-debugging-type.txt" (without quotes, case-insensitive). The name must be exact. Place the following content into the file:
```
DEBUGGING_TYPE = "NETWORK"
NETWORK_KEY = "3qzaabt20d4f5.tn8fg2zqown7.2dw5f83zzw71.anwldd839"
NETWORK_PORT = "50000"
```
Replace the above shown network key with your own. Also set the correct port number.
The virtual machine is now ready for kernel debugging.

Host side (All operating systems)

For host side, it doesn't matter which operating system are you running inside the virtual machine. Follow these steps:

Make sure you have Debugging Tools for Windows installed. Kdvmware looks for Windbg.exe in C:\Program Files directory.
Select either 32-bit or 64-bit version of Kdvmware.exe, depending on the host operating system. It's recommended to make shortcut, either on your desktop, Quick Launch or Start menu.
To start kernel debugging, run Kdvmware.exe before any virtual machine is started. It shows an icon in the system tray and waits for a virtual machine to be executed.
Start a virtual machine which yuo want to debug. As soon as a virtual machine is turned on (or if a virtual machine was already running at the moment of start of Kdvmware.exe), Kdvmware shows an information about virtual machine name and pipe name. Subsequently, it runs Windbg.exe with the appropriate parameters, so it automatically starts kernel debugging. The virtual machine needs to be booted up with /debug.
If the virtual machine is restarted, Kdvmware.exe automatically reconnects kernel debugger.
If the virtual machine is shut down or turned off, Windbg.exe is automatically closed.
If Windbg.exe is exited, Kdvmware.exe shows an information line about it. If you double-click the line, Windbg.exe will be restarted and reconnected to the virtual machine.

Download

KDVMWARE v 1.5.0.8 for Windows 2000 - Windows Seven (32-bit and 64-bit, English version, 188 KB)

References

Virtual Machine KD Extensions published by Skywing
Projekt VirtualKD