Remote debugging

Server side

Tomcat

This is applicable to Tomcat 7.x and 8.x versions.

You need to start Tomcat in JPDA mode using socket connection listening on a dedicated port (this is the defaut).

To do so you need to modify the default startup script startup.sh to launch catalina.sh with jpda start instead of just start:

(...)
exec "$PRGDIR"/"$EXECUTABLE" jpda start "$@"

By default the listening port is 8000 but you can change it to any port by setting the JPDA_ADDRESS to another value:

JPDA_ADDRESS=12345
export JPDA_ADDRESS

Just make sure that the chosen TCP port is not used by another process on the server.

Alternatively you can add following option to JVM arguments:

-agentlib:jdwp=transport=dt_socket,server=y,address=8000,suspend=n

Debugger side

We describe the particular case of the Eclipse IDE debugger, but the principle would be the same for other Java debuggers.

The server listening port must be reachable from the local machine running the debugger. This can be done by carefully opening this port thru the server firewall or by configuring a SSH tunner on this port which is definitely the best approach.

For instance:

ssh -L 8000:localhost:12345 <user>@<server>

will make the remote 12345 port available locally on local port 8000.

Note: Such tunnels can also easily be configured using SSH GUIs clients like PuTTY.

Then you can configure a remote debug configuration in Eclipse on localhost:8000 (or directly on <server>:12345 if you have chosen to open the remote port thru the server firewall) :

You need connect to remote server by clicking on the Debug button. Then you can set breakpoints and start debugging (of course the local sources must match the remote binaries).