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.
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.
Go…
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 127.0.0.1. By default, this option is disabled.
This is where root is needed. We will assume that you have it :-)
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):
Suppose the team issued "172.17.0.1"
An example of a replacement through sed, but you can also use pens in the editor, as you prefer:
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.
It is worth checking here that remote debugging is, in principle, enabled: "xdebug.remote_enable = 1"
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.
The tunnel is raised by the command (run on the local machine):
In this place magical music sounds. The main setup is done, then only the debugging environment.
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):
“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.
Run the netcat on the local machine and listen:
Run the single-line script in the docker and print:
On the local machine, we should see the call signs xdebug:
Spoiler
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.
Introductory
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.
goal
Purpose: to start remote debugging of a microservice locally through xdebug.
Go…
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 127.0.0.1. 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 "172.17.0.1"
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=172.17.0.1/' /usr/local/etc/php/conf.d/xdebug.iniWithout 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.iniIt 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.iniTypically, 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:0.0.0.0:9001 user@remote_serverIn 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 9001Run 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 на сервере. Возможно, есть более «тихий» способ. В любом случае буду рад вашим комментариям и советам.
Спасибо за внимание!