How do I use a remote Linux system to debug an application that’s running on Windows?

I’m working on contributing to Descent 3. The pull request that I’m currently working on has a Windows-only bug. I would like to use a debugger in order to help me track down the bug.

The bug that I’m currently working on involves cutscenes that play after the user starts a new game from the main menu. Unfortunately, Descent 3 always uses 640x480 for cutscenes and the main menu. Additionally, Descent 3 will only play certain cutscenes if the user is running the game in fullscreen.

As a result, I want to be able to debug the Windows version of Descent 3 while the game is running in fullscreen and my screen resolution is set to 640x480. While it’s awkward, I am able Alt+Tab out of Descent 3 and use WinDbg or CDB, even when the game is running at 640x480. Where I really get stuck is when the game hits a breakpoint. When the game hits a breakpoint, I can still Alt+Tab out of the game, but I can’t use my mouse cursor (the game keeps a lock on the mouse cursor until I run the g command).

While it’s probably technically possible to use WinDbg or CDB at 640x480 without a mouse, there has to be a better way to debug the Windows version of Descent 3. WinDbg’s documentation talks about how you can use multiple Windows machines in order to debug an application remotely. At the moment, I only have one machine that runs Windows (the rest of them only run Linux). Even if I had another machine that ran Windows, I would still prefer to use a Linux machine as the debug client.

I found a lot of similar Stack Overflow questions, but none of them quite match my situation.

Debugging Windows Kernel from Linux — This one is about kernel-mode debugging, not user-mode debugging.
Kernel-Debugging a windows guest system from a linux system - Setup not working — This one is also about kernel-mode debugging.
How to debug windows executable in Linux — In this question, the asker wants to run a Windows application on Linux and then use Linux to debug it. I want to run a Windows application on Windows and then use Linux to debug it.

Also, I found a lot of questions (and even official documentation) about debugging an application that’s running on Linux using a remote Windows system, but that’s the opposite of what I want to do. I want to debug an application that’s running on Windows using a remote Linux system.

Solution

I figured it out! The solution is to run both a CDB server and a CDB client on the same Windows system. The Linux system effectively gets used as a terminal for controlling the CDB client:

Make sure that the OpenSSH server is installed on the Windows machine. See here for details.
On the Windows machine, open a PowerShell window.
On the Windows machine, make sure that the OpenSSH server is running. In the PowerShell window, run this command:
```
Start-Process -Wait -Verb RunAs -FilePath powershell -ArgumentList @('-Command', 'Start-Service sshd')
```
On the Windows machine, start a CDB server. In the PowerShell window, run this command:
```
& <path-to-cdb> -server npipe:Pipe=MyCDBServer -o <path-to-executable-to-debug>
```
On my Windows 11 system with Visual Studio 2022, the path to CDB is C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\cdb.exe. It may be different for you.
SSH into the Windows system from the Linux system. On the Linux system, run this command:
```
ssh <windows-user>@<windows-address>
```
Start the CDB client. On the Linux system, run this command:
```
<path-to-cdb> -remote npipe:Pipe=MyCDBServer,Server=.
```