Setting up debugging with XDebug 3 and WSL2

First of all, you're running an old IDE version: 2020.2.4. A series of fixes were released since then both aiming at XDebug 3 & WSL configuration so I would suggest testing this on latest IDE version.

Next, please check if debugging works with "phone" button toggled to "listen":

Also: is your IDE installed on the Windows host or inside WSL?

Ok, Dmitry Tronin thought so. Will update the IDE. Kept myself from updating because most features that I wanted were working as expected. Also noticed that in recent updates some required features were breaking. 

- The phone button is toggled to Listen.

- Using on WIndows. Any benefits to using the IDE on WSL? Would want to be able to run projects on both Windows and WSL. 

Thanks!

Updated the IDE to the latest version 2021.2.2. The debugging now works. Had to additionally set the settings here:

Had not found this in the documentation. Probably my oversight or documentation does not have it. 

When the internet is turned off it stops working. Can you suggest a workaround for the same?

Thanks!

Dmitry Tronin Any insights on the above?

1) We don't have WSL-specific instructions for XDebug yet, unfortunately. The options you set in the Interpreter Configuration options could as well be set in a php.ini. Didn't that work for you initially?

2) Regarding the broken debug after turning off the internet. Looks like a firewall issue. Try granting PhpStorm an access at Control Panel\System and Security\Windows Defender Firewall\Allowed apps

Dmitry Tronin

- PhpStorm is an allowed app. Despite that debugging fails when there is no internet connectivity.

- When connecting to a VPN from Windows, XDebug fails. 

Command executed when turned VPN Off:

[\\wsl$\Ubuntu-18.04]:/usr/bin/php --distribution Ubuntu-18.04 --exec /bin/sh -c "export XDEBUG_CONFIG=idekey=13541 && cd /mnt/c/Users/syste/AppData/Roaming/JetBrains/PhpStorm2021.2/scratches && /usr/bin/php -dxdebug.mode=debug -dxdebug.client_port=9000 -dxdebug.client_host=127.0.0.1 -dxdebug.client_host=192.168.29.249 -dxdebug.client_port=9000 /mnt/c/Users/syste/AppData/Roaming/JetBrains/PhpStorm2021.2/scratches/scratch_118.php"

Command executed when turned VPN On:

[\\wsl$\Ubuntu-18.04]:/usr/bin/php --distribution Ubuntu-18.04 --exec /bin/sh -c "export XDEBUG_CONFIG=idekey=19439 && cd /mnt/c/Users/syste/AppData/Roaming/JetBrains/PhpStorm2021.2/scratches && /usr/bin/php -dxdebug.mode=debug -dxdebug.client_port=9000 -dxdebug.client_host=127.0.0.1 -dxdebug.client_host=192.168.29.249 -dxdebug.client_port=9000 /mnt/c/Users/syste/AppData/Roaming/JetBrains/PhpStorm2021.2/scratches/scratch_118.php"

XDebug Logs:

[11297] Log opened at 2021-11-09 11:29:31.022228
[11297] [Step Debug] INFO: Connecting to configured address/port: 192.168.29.249:9000.
[11297] [Step Debug] ERR: Time-out connecting to debugging client, waited: 200 ms. Tried: 192.168.29.249:9000 (through xdebug.client_host/xdebug.client_port) :-(
[11297] Log closed at 2021-11-09 11:29:31.224974

The `idekey` appears different, but I am not changing that anywhere. Had also replaced this IP 192.168.29.249 with the VPN's IP in both xdebug config and IDE, it did not help. IDE Restart after change also did not help.

System Info

PhpStorm 2021.2.2
Build #PS-212.5284.49, built on September 16, 2021
Licensed to Nikhil Ranka
Subscription is active until xx 3, 20xx.
Runtime version: 11.0.12+7-b1504.28 amd64
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
Windows 10 10.0
GC: ParNew, ConcurrentMarkSweep
Memory: 1951M
Cores: 8
Registry: run.processes.with.pty=TRUE, editor.distraction.free.mode=true, ide.balloon.shadow.size=0
Non-Bundled Plugins: com.intellij.properties (212.4746.57), String Manipulation (8.15.203.000.3), net.seesharpsoft.intellij.plugins.csv (2.17.1), com.intellij.ideolog (203.0.27.0), dev.meanmail.plugin.nginx-intellij-plugin (2021.2-212), nl.deschepers.laraveltinker (2.2.1), ru.adelf.idea.dotenv (2021.3.0.212)

Can you help resolve the above two issues?

Looking forward to your response.

Random IDEKEY doesn't really affect the behavior in that case.

Regarding the failed connection: are you able to telnet from inside the WSL to your host? You can run telnet 192.168.29.249 on any listening port on your machine, e.g. 22 or 80. To find what ports are listening on your machine you can run netstat -nba | find "LISTEN" in cmd run as administrator.

Resulting command would look like telnet 192.168.29.249 80

Dmitry Tronin

Thanks for the detailed steps. 

Output of  netstat

PS C:\Users\syste> netstat -nba | find """LISTEN"""
TCP 0.0.0.0:135 0.0.0.0:0 LISTENING
TCP 0.0.0.0:445 0.0.0.0:0 LISTENING
TCP 0.0.0.0:5040 0.0.0.0:0 LISTENING
TCP 0.0.0.0:5700 0.0.0.0:0 LISTENING
TCP 0.0.0.0:9000 0.0.0.0:0 LISTENING
TCP 0.0.0.0:9003 0.0.0.0:0 LISTENING
TCP 0.0.0.0:10137 0.0.0.0:0 LISTENING
TCP 0.0.0.0:20080 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49664 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49665 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49666 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49667 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49668 0.0.0.0:0 LISTENING
TCP 0.0.0.0:49671 0.0.0.0:0 LISTENING
TCP 10.49.0.4:139 0.0.0.0:0 LISTENING
TCP 127.0.0.1:6942 0.0.0.0:0 LISTENING
TCP 127.0.0.1:7706 0.0.0.0:0 LISTENING
TCP 127.0.0.1:8884 0.0.0.0:0 LISTENING
TCP 127.0.0.1:9012 0.0.0.0:0 LISTENING
TCP 127.0.0.1:15292 0.0.0.0:0 LISTENING
TCP 127.0.0.1:15393 0.0.0.0:0 LISTENING
TCP 127.0.0.1:16494 0.0.0.0:0 LISTENING
TCP 127.0.0.1:44950 0.0.0.0:0 LISTENING
TCP 127.0.0.1:44960 0.0.0.0:0 LISTENING
TCP 127.0.0.1:45623 0.0.0.0:0 LISTENING
TCP 127.0.0.1:49716 0.0.0.0:0 LISTENING
TCP 127.0.0.1:51981 0.0.0.0:0 LISTENING
TCP 127.0.0.1:59072 0.0.0.0:0 LISTENING
TCP 127.0.0.1:59073 0.0.0.0:0 LISTENING
TCP 127.0.0.1:59233 0.0.0.0:0 LISTENING
TCP 127.0.0.1:63342 0.0.0.0:0 LISTENING
TCP 172.26.224.1:139 0.0.0.0:0 LISTENING
TCP 192.168.29.249:139 0.0.0.0:0 LISTENING
TCP [::]:135 [::]:0 LISTENING
TCP [::]:445 [::]:0 LISTENING
TCP [::]:5700 [::]:0 LISTENING
TCP [::]:9000 [::]:0 LISTENING
TCP [::]:9003 [::]:0 LISTENING
TCP [::]:10137 [::]:0 LISTENING
TCP [::]:20080 [::]:0 LISTENING
TCP [::]:49664 [::]:0 LISTENING
TCP [::]:49665 [::]:0 LISTENING
TCP [::]:49666 [::]:0 LISTENING
TCP [::]:49667 [::]:0 LISTENING
TCP [::]:49668 [::]:0 LISTENING
TCP [::]:49671 [::]:0 LISTENING
TCP [::1]:49669 [::]:0 LISTENING

Output extract from ipconfig command on Windows

Windows IP Configuration

Unknown adapter VPN: (IP when connecting to VPN)
IPv4 Address. . . . . . . . . . . : 10.49.0.4

Ethernet adapter Ethernet:
IPv4 Address. . . . . . . . . . . : 192.168.29.249 (Device IP)

Ethernet adapter vEthernet (WSL):
IPv4 Address. . . . . . . . . . . : 172.26.224.1 (IP when starting WSL)

Here's how the debugging experience is when using the different IPs.

When using the IP under 'Ethernet adapter vEthernet (WSL)'  (shown after connecting to WSL - changes everytime computer restarts)

1. Works when VPN is turned off
2. Works when the Internet is turned on, or, off
3. Does NOT work when VPN is turned on.

When using the IP under 'Ethernet adapter Ethernet' (IP remains the same)

1. Works when VPN is turned off
2. Does NOT work when VPN is turned on.
3. Does NOT work when the internet is turned off.

When using the IP under 'Unknown adapter' (shown in ipconfig after connecting to VPN)

1. Works when VPN is turned on
2. Does NOT work when VPN is turned off.
3. Does NOT work when the internet is turned off.

Important note:

Since the suggested telnet command was not working, while debugging landed on this link. Post implementing the suggestion here, the telnet command started working - connection to windows was successful.

Looks like something fundamental is being missed here. Ideally, with a developer-friendly, well developed IDE like PHPStorm there should be a way to debug apps running in WSL2, irrespective of the internet connection status and VPN usage. 

Would be great if you can help me implement the same.

Thanks!

1) what solution exactly did you apply? The one about the firewall?

2) Isn't 192.168.29.249 - a result of grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'? Btw, here's the same article from MS: https://docs.microsoft.com/en-us/windows/wsl/networking#accessing-windows-networking-apps-from-linux-host-ip

3) What's the XDebug version you're using right now? What are the xdebug.remote_host or xdebug.client_host values right now?

Here are the details:

1. The firewall setting involved adding an inbound rule. Full details are here in the link (same as posted earlier).
2. The IP that this command grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}' gives changes with every restart of the PC - which requires a change in the config as well. This is the IP 192.168.29.249 of the device, I assume (reattaching the o/p)
   

   Output extract from ipconfig command on Windows

   Windows IP Configuration
   
   Unknown adapter VPN: (IP when connecting to VPN)
   IPv4 Address. . . . . . . . . . . : 10.49.0.4
   
   Ethernet adapter Ethernet:
   IPv4 Address. . . . . . . . . . . : 192.168.29.249 (Device IP)
   
   Ethernet adapter vEthernet (WSL):
   IPv4 Address. . . . . . . . . . . : 172.26.224.1 (IP when starting WSL)

   Can you recheck my previous comment for more details on how using different IPs change the debugging experience?
3. Xdebug version is v3.1.1. Full details here:
   

   nik@DESKTOP-B3CS5F7:~$ php -v
   PHP 7.4.25 (cli) (built: Oct 22 2021 12:33:59) ( NTS )
   Copyright (c) The PHP Group
   Zend Engine v3.4.0, Copyright (c) Zend Technologies
   with Zend OPcache v7.4.25, Copyright (c), by Zend Technologies
   with Xdebug v3.1.1, Copyright (c) 2002-2021, by Derick Rethans

Let me know if any additional info is required.

Thanks!

Dmitry Tronin

Honestly, I don't see how this is a PhpStorm issue at all: it's a pure networking problem that can't be addressed from inside IDE.

Here's a quick test to confirm/deny this: download Xdebug dbgpClient (search for "Command Line Debug Client" links) & launch it. Then turn on VPN & check if your WSL app can connect to it.

I've also just tested this on my end: turning on/off VPN connection doesn't affect WSL debugging here:

There must be something specific to your environment causing this. E.g. what VPN software you're using?

Might something generic like https://github.com/microsoft/WSL/issues/5068

Here's a quick test to confirm/deny this: download Xdebug dbgpClient (search for "Command Line Debug Client" links) & launch it. Then turn on VPN & check if your WSL app can connect to it.

Dmitry Tronin

With VPN turned on/off, after starting the dbgpClient in Windows Powershell(PS) and initiating the script from WSL2, there was nothing printed in the Powershell. However, when initiating the debug session from PHPStorm it was working as expected. Turning on the VPN leads to issues though.

Q1. Any ideas on how to get the dbgpClient in Windows PS to receive the connections from WSL2?

I've also just tested this on my end: turning on/off VPN connection doesn't affect WSL debugging here:

Thanks for testing and verifying. Yet to get it working with the VPN on  and internet off.

There must be something specific to your environment causing this. E.g. what VPN software you're using?

Using AlgoVPN setup by the IT admin on an AWS server.

Thanks!

How exactly did you launch the script? Probably debug session wasn't initiated or xdebug parameters were incorrect. This depends on your XDebug configuration. You can share the output of php -i | grep xdebug launched inside WSL here or elsewhere just to doulbecheck your xdebug settings. If essential settings  are incorrect or "start_with_request" isn't enabled - then it's expected that debugging session isn't triggering.

Alternatively you can launch your script passing the arguments via cmd, see https://www.jetbrains.com/help/phpstorm/debugging-a-php-cli-script.html#c56b6638. Note that you would need to replace the arguments with corresponding values for your environment.

As for AlgoVPN & AWS: just to confirm - are we talking about local debugging where both IDE & WSL running on the same machine?

> well developed IDE like PHPStorm there should be a way to debug apps running in WSL2, irrespective of the internet connection status and VPN usage. 

Sorry, as advised, that's a pure OS networking problem - IDE can't affect the way things work there.

> Curious to know if you are able to get debugging working irrespective of internet connection status or VPN being on or off

Checked again, debugging WSL app with VPN on & internet off still works:

You can also do this: run in CMD (run as Administrator): netstat -nba | find "LISTEN". Find a port that your localhost is listening on.

Then reproduce the environment when debugging doesn't work (internet off, right?), and try to telnet <IP returned by grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}'> <port from a previous step> from inside the WSL disitrib.

Dmitry Tronin

Will experiment with the setup as advised above.

However, can you share the steps taken at all levels - PHPStorm, WSL2, Windows 10/11, on your end to get the debugging working? This would help in recognizing what was missed during setup - assuming that debugging works on your end irrespective of the internet's/VPN's connection status.

Thanks!

Sure. First of all, xdebug settings for my WSL distro:

I've highlighted the most important parts here & there.

Debugging a web app works by simply opening a corresponding webpage. localhost/wordpress in my case:

Debugging a PHP Script differs a bit, you need to create a PHP | Server config for the WSL distro, or alternatively enable Settings (Preferences on macOS) | PHP | Debug | Break at first line in PHP scripts. I've created a config called wsl2localhost & enabled path mappings:

Then I've exported a "PHP_IDE_CONFIG" env variable for IDE to understand what config should it use:

Without it IDE would complain like this:

Thanks, Dmitry Tronin for the detailed response. Got engaged in other activities. The steps you mentioned worked - irrespective of the internet/VPN connection.

Wanted clarity on a couple of items:

1. On every restart the IP of WSL2 changes. Wrote a temporary bash script to update the IP in XDebug. Any other approaches to handle this?

2. For the first debug attempt after a restart the following error is thrown. Any ideas on resolving this?

PS: Having this on the documentation website would certainly help many others.

1. Not that I know of, sorry.

2. Can't advise about that one by just looking at the screenshot. I would need to check IDE + XDebug logs for that. You can send them over to me using Help | Contact Support.

The info about setting up XDebug in WSL2 is being updated in our docs right now.

1. No problem. Although Windows config is not related to PHPStorm, given that there is a tight overlap having information about this in the documentation would help.
2. Shared the PHPStorm logs. https://intellij-support.jetbrains.com/hc/en-us/requests/3790781
   XDebug Logs:
   

   [2312] Log opened at 2022-01-28 04:42:26.624650
   [2312] [Step Debug] INFO: Connecting to configured address/port: 172.27.208.1:9000.
   [2312] [Step Debug] ERR: Time-out connecting to debugging client, waited: 200 ms. Tried: 172.27.208.1:9000 (through xdebug.client_host/xdebug.client_port) :-(
   [2312] Log closed at 2022-01-28 04:42:27.612214

    

From the IP 172.27.208.1 in the logs, looks like PHPStorm caches the config and attempts to connect with the old WSL IP.
ipconfig output on Windows:

Ethernet adapter vEthernet (WSL):

   Connection-specific DNS Suffix  . :
   Link-local IPv6 Address . . . . . : fe80::18dd:55db:866:9d53%46
   IPv4 Address. . . . . . . . . . . : 172.22.144.1
   Subnet Mask . . . . . . . . . . . : 255.255.240.0
   Default Gateway . . . . . . . . . :

`hostname -I` output on WSL2: 172.22.146.156

Looks like recaching the config would resolve this issue.

Thanks!

Would it help if you refresh the PHP interpreter info in IDE? See https://i.gyazo.com/91161862cf02ee2491cc88de476ee778.mp4

Will attempt this Dmitry Tronin. After the first failure post restart, an option to reload the config (not the same wordings as shown) appears. On opting for that, debugging works. 

So, looking for ways on how to prevent the first error. Do you not notice something similar on your device?

Does grep -m 1 nameserver /etc/resolv.conf | awk '{print $2}' return different address after every PC restart? This is not something I observe on my end.

The only issue I've faced is the one described here: https://youtrack.jetbrains.com/issue/WI-64944 - hope it would get addressed soon.

Yes, the IP address changed after every PC restart. Most likely this is because of the way WSL operates.

Relevant portion of output of ipconfig from powershell

Ethernet adapter vEthernet (WSL):

   Connection-specific DNS Suffix  . :
   Link-local IPv6 Address . . . . . : fe80::e869:235c:4b9a:71b6%46
   IPv4 Address. . . . . . . . . . . : 172.30.0.1
   Subnet Mask . . . . . . . . . . . : 255.255.240.0
   Default Gateway . . . . . . . . . :

172.30.0.1 is the IP address. Some resources suggest config changes to ensure the IP does not change. Yet to test a solution. However, not experimenting now because of its potential to break existing working features. You are probably running a different version of Windows, or have some config change that prevents this. Would be interesting to know what it is.

Thanks!

Dmitry Tronin Any insights here?

Sorry, can't advise on this yet. You can submit this issue (IDE passing outdated IP address during WSL CLI debugging) to our tracker at https://youtrack.jetbrains.com/newIssue for it to not get lost

Hello,

Very interresting thread, I got the same problem but I think it's a network problem between Windows Host and WSL2 when VPN is up (from my side I use Anyconnect and it's work with full tunnel).

I open an issue here: https://github.com/microsoft/WSL/issues/8019

Maybe it will help your problem...

Thanks Jocelyn Tonnelier for sharing the link. The problem of not being able to connect to the internet was resolved after I changed the VPN from WireGuard to OpenVPN.

And using the recent suggestions by Dmitry Tronin, configured PHPStorm such that debugging will work irrespective of the internet connection.

Dmitry Tronin

Sure, will file an issue when time permits. Curious if you also face the same issue and did you manage to resolve it?

No, I don't have this problem here for some reason. 

That's surprising Dmitry Tronin. Did the attached logs point toward something?

Hoping that enhancements to both the IDE and documentation are made sooner than later wrt working with WSL2