How to Remote Debug a Java Application with IntelliJ IDEA using SSH Tunneling

Debugging a Java application is a crucial process for software engineers to identify and fix issues in their code. However, there are times when debugging an application locally is not possible, and we need to connect to a remote application to debug it. In such cases, it can be challenging to debug the Java code on a remote host due to network restrictions that prevent a direct connection. Fortunately, IntelliJ IDEA can help you remotely debug your Java code over an SSH tunnel.
In this article, we’ll guide you through setting up an SSH tunnel and configuring IntelliJ IDEA for remote debugging, allowing you to debug your Java application running on a remote host with ease.

Debugging a Java Application on a Remote Host

Debugging a Java application on a remote host can be challenging if the host is not directly accessible due to network restrictions. You may need to use SSH tunneling to establish a secure connection between your local machine and the remote host to debug the Java application.
SSH tunneling allows you to forward traffic from a local port to a remote port through an encrypted SSH connection.

Setting Up an SSH Tunnel for Remote Debugging

To set up an SSH tunnel for remote debugging, you need to open a terminal on your local machine and run the following command:

ssh -L <local_port>:localhost:<remote_port> <username>@<remote_host>

Replace <local_port> with a port number of your choice on your local machine (e.g. 5005), <remote_port> with the port number on which the remote JVM is listening for the debugger to connect, <username> with your remote username, and <remote_host> with the hostname or IP address of the remote machine.

For example, if the remote JVM is listening on port 5005 and your remote username is user and the remote host IP is 123.456.789.0, you can use the following command:

ssh -L 5005:localhost:5005 [email protected]

This command forwards all traffic from <local_port> on your local machine to <remote_port> on the remote machine through the SSH tunnel.

Configuring IntelliJ IDEA for Remote Debugging over SSH

Once you have set up the SSH tunnel, you can configure IntelliJ IDEA for remote debugging over SSH. Here’s how:

1. Open your Java project in IntelliJ IDEA.
2. Click on the Run menu and select Edit Configurations.
3. In the left pane, select Remote Debug (or Remote).
4. In the right pane, click on the + button to add a new configuration.
5. Give the configuration a name (e.g. “Remote Debug over SSH”) and set the following properties:

Host: set to localhost
Port: set to the <local_port> you chose in step 1 (e.g. 5005).
Transport: set to Socket.

6. Click on the OK button to save the configuration.
7. In the toolbar, select the configuration you just created (e.g. “Remote Debug over SSH”) and click on the Debug button to start the debugger.
8. The debugger will connect to the local port on your machine, which will be forwarded through the SSH tunnel to the remote JVM. You can now set breakpoints, step through the code, inspect variables, and so on, just as if you were debugging locally.

Conclusion

Remote debugging a Java application can be challenging, but with SSH tunneling and IntelliJ IDEA, it’s easier than ever to debug Java code on a remote host. By following the steps outlined in this article, you can set up an SSH tunnel and configure IntelliJ IDEA for remote debugging over SSH.
Happy debugging!