Troubleshooting Windows Subsystem For Linux (WSL)

Enabling WSL2 Support in Firewall Settings

Unlike WSL1 that shares the same IP addresses (including localhost) between Windows and Linux sides, WSL2 distros run inside separate lightweight virtual machines and cannot directly communicate to the Windows host unless explicitly enabled in firewall settings.

VisualGDB relies on the ability to communicate between the WSL target and Windows, hence in order to use WSL2 targets with VisualGDB, you would need to enable TCP/IP connections from WSL2 hosts. The easiest way to configure it is shown below:

  1. Locate PowerShell in the Start menu, right-click on it and select “Run as Administrator”.
  2. In the Administrative PowerShell Prompt run the following command:
    New-NetFirewallRule -DisplayName "WSL" -Direction Inbound  -InterfaceAlias "vEthernet (WSL)"  -Action Allow

  3. Now you can select WSL2 targets in VisualGDB dialogs and they will work out-of-the-box, just like WSL1 targets.

Troubleshooting WSL Launcher Problems

VisualGDB uses a special launcher application to run the WSL applications in their native environment and route their output back to VisualGDB. The launcher is complied from the C:\Program Files (x86)\Sysprogs\VisualGDB\TargetTools\LinuxAppLauncher.c file first time you use VisualGDB with WSL.

If the launcher does not build or start due to some reason, you can try troubleshooting it as shown below:

  1. If the launcher doesn’t build, try opening the WSL bash shell and building it manually:
    gcc -std=gnu99 <full path to LinuxAppLauncher.c> -o LinuxAppLauncher -lutil

    If the build fails due to missing GCC, or other errors, please fix them and run VisualGDB again.

  2. If the launcher fails to start, or VisualGDB fails to connect to it, please take the note of the command line shown by VisualGDB, e.g.:
    C:\WINDOWS\system32\wsl.exe -- /tmp/LinuxAppLauncher-v4 "/mnt/c/Users/test/AppData/Local/Temp/tmp1234.tmp" 12345

    The tmp1234.tmp file shown in the command line contains the launch parameters for the WSL command started with the launcher. Make sure the file still exists and try running the command line manually to see if WSL fails to run the launcher due to some reason.

  3. If the launcher manages to start, but doesn’t connect, double-check the IP address at the end of the command line ( in the example above). It should match the actual IP address of the Windows machine as seen from WSL. You can verify it by pinging that address from the WSL prompt, or running telnet from WSL to connect to a TCP port open from the Windows side.
  4. If the IP address is incorrect, double-check the names of the network interfaces. VisualGDB would use the address associated with the only network interface that has ” (WSL) ” in its name. If you have renamed the interface manually, you can configure VisualGDB to look for a different interface via the Tools->Options->VisualGDB->General->Other->Linux Subsystem Network Interface setting.

Technical Details

When VisualGDB launches the WSL command line (wsl.exe — /tmp/LinuxAppLauncher-vX /…/job.tmp <port> <IP>) the following events take place:

  1. The WSL launcher (wsl.exe) starts the VisualGDB’s WSL wrapper (LinuxAPpLauncher-vX).
  2. The WSL wrapper reads the job description (command line, environment) from the job file and launches the job.
  3. The WSL wrapper connects to the specified IP and port (opened by VisualGDB) and forwards the output from the job there using a simple protocol.

You can find the source code for LinuxAppLauncher.c in the <VisualGDB Directory>\TargetTools\LinuxAppLauncher.c.