Remote debugging via SSH tunnel
This tutorial describes how to use an SSH tunnel (also known as SSH port forwarding) to set up a secure connection between a remote server running Xdebug and your development machine running PhpStorm. This can be useful for debugging code on a remote machine when there are firewalls in between, or a NAT router prevents direct connection, or the ISP or network infrastructure does not allow incoming TCP connections to the developer machine.
![SSH tunnel diagram SSH tunnel diagram](https://resources.jetbrains.com/help/img/idea/2024.3/ssh-tunnel-explained.png)
When the remote server can connect to the developer machine directly (for example, with a Vagrant machine), an SSH tunnel may not be needed.
Before you start debugging, make sure that you have a debugging engine installed and configured properly on the web server where your PHP application is executed.
PhpStorm supports debugging with two most popular tools: Xdebug and Zend Debugger. These tools cannot be used simultaneously because they block each other. To avoid this problem, you need to update the php.ini file of the relevant PHP interpreter as described in Configure Xdebug and Configure Zend Debugger.
For example, with Xdebug, make sure that the following settings are specified in php.ini on the server:
[xdebug]
zend_extension="<path to xdebug extension>"
xdebug.mode=debug
xdebug.client_host=127.0.0.1
xdebug.client_port="<the port (9003 by default) to which Xdebug connects>"
[xdebug]
zend_extension="<path to xdebug extension>"
xdebug.remote_enable=1
xdebug.remote_host=127.0.0.1
xdebug.remote_port="<the port (9000 by default) to which Xdebug connects>"
zend_extension
: the setting indicating that the Xdebug debugging engine shall be used. Set toxdebug
or use the full path to thexdebug.so
file, such as/usr/lib/php/20190902/xdebug.so
.xdebug.mode
: the setting controlling which Xdebug features are enabled. Set todebug
for debugging.xdebug.client_host
: the IP address or hostname at which PhpStorm is running and listening for incoming connections from Xdebug.xdebug.client_port
: the port to which Xdebug tries to connect on the host where PhpStorm runs. The default port is9003
.
In PhpStorm, enable listening to incoming debug connections by doing any of the following:
Click
on the toolbar/the status bar.
Select Run | Start Listening for PHP Debug Connections in the main menu.
This ensures that PhpStorm reacts when a debugging session is started on the web server and opens the Debug tool window automatically. Before starting a debugging session, make sure that either a breakpoint is set or the Break at first line in PHP scripts option is enabled on the Debug page of the Settings dialog CtrlAlt0S.
When you start a debugging session, it's Xdebug that initiates a TCP connection from the remote server to the port on the developer machine where PhpStorm is listening to it.
The idea of SSH port forwarding is to create a "virtual" TCP port on the remote server that sends its traffic to a TCP port on your developer machine, tunneling traffic over SSH.
tip
If you are on Windows, and your operating system version doesn't have built-in SSH support, use the PuTTy SSH client instead of the command line.
To set up SSH port forwarding, run the following ssh
command on the command line:
ssh -R 9003:localhost:9003 username@hostname
ssh -R 9000:localhost:9000 username@hostname
ssh -R 10137:localhost:10137 username@hostname
9003:
in9003:localhost:9003
is the port on the SSH server (the forwarding host) from which Xdebug connections will be forwarded tolocalhost
.localhost:9003
in9003:localhost:9003
is the IP address of the SSH client (the machine running PhpStorm) and the port on it to which Xdebug connections will be forwarded.localhost
is essentially the machine where you are running thisssh
command from.username@hostname
is the address of the SSH server (the forwarding host) and the username required for SSH authentication on it.
note
To test direct connection, run the
telnet host 9003
(for Xdebug 3) or thetelnet host 10137
(for Zend Debugger) command on the remote server and ensure that connection is established. Here,host
is the IP address of the local machine PhpStorm is running on.To check for opened inbound ports, you can use canyouseeme.org or a similar service.
To check that an SSH tunnel has been successfully set up, start a debugging session on the remote server by using PhpStorm bookmarklets, a Browser Debugging Extension, or the techniques outlined in Debugging PHP CLI scripts with PhpStorm. As soon as PhpStorm detects the incoming connection, it displays the Incoming Connection from Xdebug dialog prompting you to accept it.
![Incoming debugger connection Xdebug Incoming debugger connection Xdebug](https://resources.jetbrains.com/help/img/idea/2024.3/ps_incoming_debugger_connection.png)
For more information about the debugging process in PhpStorm, see Zero-configuration debugging and Examine a suspended program.
When a remote PHP interpreter is properly configured, it's possible to create a run/debug configuration taking advantage of the remote PHP interpreter for debugging.
When the SSH tunnel is up and running, we can also debug PHP CLI scripts. Since the debugger runs on a remote machine, starting a CLI debugging session can be done by using PHP command line switches or using environment variables (on the remote machine). This workflow is not the officially recommended way of debugging, though it might be useful in some cases when the debugging session is needed to be established from the remote server side.
When the debugger never connects or refuses the connection, check the following:
Make sure Xdebug is configured to connect to 127.0.0.1 and port 9000 (for Xdebug 2) or port 9003 (for Xdebug 3).
When using Zend Debugger, make sure the PhpStorm bookmarklets or Browser Debugging Extension is configured to connect to 127.0.0.1.
Make sure PhpStorm is listening for incoming debugger connections prior to setting up the SSH tunnel.
When a machine is rebooted or the connection is lost, the SSH tunnel has to be reestablished.
In some cases, the debugger can connect, but we get the error messages indicating that no mapping between the remote and project files is defined. This means that PhpStorm cannot determine which local file corresponds to the file being debugged.
![No mappings configured No mappings configured](https://resources.jetbrains.com/help/img/idea/2024.3/ps_debug_no_mapping.png)
We can solve this problem by clicking Click to set up path mappings and providing the necessary path mappings. Additionally, we can configure these mappings using the techniques outlined in Connect to a web server.
note
Path mappings cannot be set for project files or folders that are marked as excluded.
Thanks for your feedback!