Remote microservice debugging via SSH under VPN in 4 turns

There is a situation when you need to fix a complex case on a remote machine, but access to the server is only under VPN with restrictions on open ports. In the article I want to share with my colleagues a small “discussion” on the topic of remote debugging via SSH under VPN in order to save valuable time on setup. I consider the mission accomplished if this man is useful to someone.

The server was deployed to Ubuntu, respectively, further all server settings will be under Ubuntu. On the local machine - Mac, but here we only need the SSH client and IDE with a debugger for xdebug, so the settings are relatively universal.


So, there is a remote server behind a protected circuit. On the server in the docker, a microservice with xdebug turned on. There is access from outside only via SSH and via VPN.


Purpose: to start remote debugging of a microservice locally through xdebug.


1. Configure sshd on a remote server

The first thing you should pay attention to is that you need to configure sshd on the server so that it allows you to accept connections from any IP, not just By default, this option is disabled.

This is where root is needed. We will assume that you have it :-)

sudo echo "GatewayPorts yes" >> /etc/ssh/sshd_config
sudo service ssh restart

2. Find out the address of the host machine in the docker network

Since xdebug runs in docker and connects itself to the local machine (and in my case this IP does not resolve, because it is a VPN connection), it is useful to know the IP of the host machine on the docker network. This can be done using the command (run on the server):

ip -4 addr show docker0 | grep -Po 'inet \K[\d.]+'

Suppose the team issued ""

3. We register the IP of the remote host in the xdebug settings in the container

An example of a replacement through sed, but you can also use pens in the editor, as you prefer:

sed -i 's/xdebug.remote_host=.*/xdebug.remote_host=' /usr/local/etc/php/conf.d/xdebug.ini

Without departing from the cash register, we prescribe the "correct" port for debugging. In my case, the microservice is raised on a bunch of nginx & php-fpm and usually port 9000 is busy under php-fpm , and therefore I use port 9001 for debugging.

sed -i 's/xdebug.remote_port=.*/xdebug.remote_port=9001/' /usr/local/etc/php/conf.d/xdebug.ini

It is worth checking here that remote debugging is, in principle, enabled: "xdebug.remote_enable = 1"

grep xdebug.remote_enable /usr/local/etc/php/conf.d/xdebug.ini

Typically, these settings are wired to the Dockerfile or mounted via volume.

Everything is ready on the server. Now we are transferred to the local machine to build a tunnel.

4. Forward the SSH tunnel to the remote server

The tunnel is raised by the command (run on the local machine):

SSH -R 9001: user@remote_server

In this place magical music sounds. The main setup is done, then only the debugging environment.

IDE Setup

Usually I use vscode, so the debugger via port listening starts without problems. I will give an example of a config for vscode (just add a node to launch.json):

            "name": "Listen for XDebug",
            "type": "php",
            "request": "launch",
            "port": 9001,
            "cwd": "${workspaceFolder}",
            "pathMappings": {
                "/repo": "${workspaceRoot}"

“PathMappings” is the rule for mapping directories of the local and remote machines, where “/ repo” is the directory with the debugged code in the docker. The debugger needs to be able to navigate the files and breakpoints.

PS Well, potest?

Run the netcat on the local machine and listen:

nc -l 9001

Run the single-line script in the docker and print:

php -r 'print("Hi!" . PHP_EOL);'

On the local machine, we should see the call signs xdebug:

Ура! Все готово.

Теперь можно в IDE отлаживать любимый код на удаленной машине. В описанном методе есть очевидный минус: реконфигурация sshd на сервере. Возможно, есть более «тихий» способ. В любом случае буду рад вашим комментариям и советам.

Спасибо за внимание!

Also popular now: