Setup Xdebug for remote debug over SSH

If you have PHP application you need to debug, and there is a firewall between you and the hosting server, One can use SSH to tunnel the traffic from the remote site to the local machine.

This is my notes about how to setup Netbeans with xdebug over ssh.

Setup Xdebug on the remote host

Make sure you have this lines in the xdebug.ini file

Usually on a default installation you’ll see only the first line.

Setup Netbeans for using Xdebug

Under the menu Tools > Options > PHP > Debugging  change the default port if needed (e.g if port 9000 which the default is used by another application)


Setup the SSH tunel to the remote host

Next we will run a tunnel to allow xdebug to connect back to the local Netbeans.

ssh user@remote-machine -R9000:

This tells ssh to redirect the remote port 9000 (which is the default port for xdebug) to my local machine into port 9002 (I had some other service running on my machine on port 9000).

The why it works is that Netbeans start a debug session and waits for connection (in my example on port 9002) from xdebug on the remote machines, the remote xdebug is configured to connected to IP over port 9000, which our SSH tunnel will redirect to our local port  9002.

Xdebug Connection work flow

Xdebug Connection work flow Source:


Waiting for connection (SELinux)

This one is mostly a remainder for my self, as I’m using Fedora with SELinux Enabled/Enforcing. After starting the debugger it stuck on “Waiting for connection” and nothing happens.

In the audit log file you will see this error message.

type=AVC msg=audit(1439320998.319:3092): avc:  denied  { name_connect } for  pid=24358 comm="php-fpm" dest=9999 scontext=system_u:system_r:httpd_t:s0 tcontext=system_u:object_r:jboss_management_port_t:s0 tclass=tcp_socket permissive=1

which translate to “SELinux is preventing php-fpm from name_connect access on the tcp_socket port 9999.”

One why to resolve this is run this command

setsebool -P httpd_can_network_connect 1

Or you can grep the error from the log file and pipe it into audit2allow which will help you with other suggestions to how resolve this problem.


You may also like...

1 Response

  1. Ronan Hughes says:

    Thank you… The key was your command “ssh user@remote-machine -R9000:” which is missing from other blogs I’ve read, but it did the trick for me.

Leave a Reply

Your email address will not be published. Required fields are marked *