9.32. Paravirtualized debugging

9.32.1. Hyper-V debug options

• A VM configured for Hyper-V paravirtualization running a Windows Vista or newer Windows guest. You may check the effective paravirtualization provider for your VM from the output of the following VBoxManage command:

  VBoxManage showvminfo "VM name"

• A sufficiently up-to-date version of the Microsoft WinDbg debugger required to debug the version of Windows in your VM.

• While Windows 8 and newer Windows guests ship with Hyper-V debug support, Windows 7 and Vista do not. To use Hyper-V debugging with a Windows 7 or Vista guest, copy the file kdvm.dll from a Windows 8.0 installation^[45]. This file is typically located in C:\Windows\System32. Copy it to the same location in your Windows 7/Vista guest. Make sure you copy the 32-bit or 64-bit version of the DLL which matches your guest OS.

1. Power off the VM.

2. Enable the debug options by executing the following VBoxManage command:

   VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1"

   The above command assumes your debugger will connect to your host machine on UDP port 50000. However, if you need to run the debugger on a remote machine you may specify the remote address and port here, e.g. using:

   VBoxManage modifyvm "VM name" --paravirtdebug "enabled=1,address=192.168.32.1,port=55000"

   Refer Section 9.32.1, “Hyper-V debug options” for the complete set of options.

3. Start the VM.

4. In the guest, start an elevated command prompt and execute the following commands:

   • For a Windows 8 or newer Windows guest:

     bcdedit /dbgsettings net hostip:5.5.5.5 port:50000 key:1.2.3.4

   • For a Windows 7 or Vista guest:

     bcdedit /set loadoptions host_ip=5.5.5.5,host_port=50000,encryption_key=1.2.3.4

     bcdedit /set dbgtransport kdvm.dll

     The IP address and port in the bcdedit command are ignored when using the Hyper-V debug transport. Any valid IP and a port number greater than 49151 and lower than 65536 can be entered.

     The encryption key in the bcdedit command is relevant and must be valid. The key "1.2.3.4" used in the above example is valid and may be used if security is not a concern. If you do not specify any encryption key, bcdedit will generate one for you and you will need to copy this key to later enter in Microsoft WinDbg on the remote end. This encryption key is used to encrypt the debug data exchanged between Windows and the debugger.

   • Execute one or more of the following commands to enable debugging for the appropriate phase or component of your Windows guest:

     bcdedit /set debug on

     bcdedit /set bootdebug on

     bcdedit /set {bootmgr} bootdebug on

     Please note that the bootdebug options are only effective on Windows 8 or newer when using the Hyper-V debug transport. Refer to Microsoft Windows documentation for detailed explanation of bcdedit options.

5. Start Microsoft WinDbg on your host machine or remote host.

   From the "File" menu, select "Kernel debug". Under the "NET" tab, specify the UDP port number you used in the paravirtdebug options. If you didn't specify any, leave it as 50000. Ensure that the UDP port is not blocked by a firewall or other security software.

   In the "Key" field, enter 1.2.3.4 or the encryption key from the bcdedit command in your Windows guest.

   Now press "OK" to start listening for connections. Microsoft WinDbg typically shows a "Waiting to reconnect" message during this phase.

   Alternatively, launch WinDbg from the command line to directly start a debug session:

   windbg.exe -k net:port=50000,key=1.2.3.4

   Please refer to the WinDbg documentation for complete command line syntax.

6. Reboot your Windows guest and it should then connect as a debuggee with Microsoft WinDbg.