Tuesday, January 4, 2011

Remote debugging webapp in Tomcat (Rhel) through Eclipse (Ubuntu)

Background to my current issue:
There appears to be something odd going on the server side of our network code. Our server is a virtual machine hosted on GoGrid and the oddness is only occurring in release 1.14 and later of our network code.  The current trunk of our code is 1.16-SNAPSHOT and the network code on the vm is 1.15 (release).

I've spent the better of today getting right set of convocations together for my particular set of system set ups.  Specifically:
* Ubuntu 10.04 (Lucid Lynx)
* Eclipse 3.5

Server Side
* Rhel 5.4
* Tomcat 6

Hopefully the following represents an accurate list of steps to assist anyone else with setting up a remote debugging of a webapp running on a Tomcat elsewhere through Eclipse on your local machine.

  • Setting up tomcat to start up in debug mode:
    • Most of the websites I came across suggest adding a command after the script:

       [host]$ catalina.sh jpda start 
      (Mulesoft's blog)
    • For my particular set up, I did not have a catalina.sh script file to manipulate.  Instead, Rhel's installation of Tomcat6 creates a conf folder and a conf file where the options are set.  In my case, the specific file name is tomcat6.conf and was found in ~tomcat6/conf/
      • In this file, I added the following lines after setting where the installation lives (noting that this should be the first JAVA_OPTS set):
         # Java option to turn on debugger FIRST
        JAVA_OPTS="-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n" 

        NB: that there can not be any spaces around the initial "=". The above is NOT equivalent to:
        JAVA_OPTS = "-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n" 

    • Now it's time to restart (bounce) the tomcat for the tomcat to pick up the changes in the JVM arguements:
      [host]$ /etc/init.d/tomcat6 restart 

  •  Setting up the server to listen to the port that has been designated in the above step for the debugger (in this example, 8000, see the numbers after "address")
    • Now the appropriate ports need to be opened on the iptables:
      [host]$ vim /etc/sysconfig/iptables 

      And add this line into the file and save it:
      -A RH-Firewall-1-INPUT -p tcp -m state --state NEW -m tcp --dport 8000 -j ACCEPT

      This line should go along with the other similar statements in the file. Once the file has been saved, the iptables need to be restarted for the changes to take affect:
      [host]$ /etc/init.d/iptables restart

  • Since my server is hosted on GoGrid, I know that they have a firewall in place. The next step is to create an ssh tunnel to my server. For the sake of usability, I installed "Gnome SSH Tunnel Manager - a front-end to ssh tunneling" and added the information for my server and opened up the tunnel with the followinig for the properties:
    • Name: GoGrid 252 [This can be anything that is easy for you to recognize]
    • Login: me [This is the login you would use to login to the server]
    • Host: ###.##.###.252 [This is the IP address of the server]
    • Port: 22 [This is the port that you have designated on your server as your ssh port, default is 22]

  • Finally, on my local machine in Eclipse, I had to do the following:
    • I needed the specific version of the code base project opened that the server was running.  In this case, I had been working on 1.16 SNAPSHOT, which I needed to close and open up the 1.15 release that is running on the server.
    • Click on any file in the project that contains the webapp code
    • From the Eclipse menu, navigate: Run -> Debug Configurations
    • In the left handle panel, navigate up to Remote Java Applications, right click over it and select New from the pop-up menu.
    • In the right hand panel you should now see 3 tabs and a name field.  The name field is for your reference and will show up on the left hand panel for you to select later.  Under the Connect tab you should fill in the following:
      • Project: [The project containing the source code for the webapp you are trying to debug in the remote Tomcat]
      • Connection Type: Standard (Socket Attach)
      • Host: ###.##.###.252 [This is the IP address of the server]
      • Port: 8000 [This is the designated debugging port that was set up on the server]
    • Click Apply and then Debug

  • In the source code for the webapp, put a breakpoint somewhere that you know will be hit and then send a request to your tomcat.  You should see be able to now debug in Eclipse.

And that summarizes up what I did to get the debugging to work on my local machine for a remote webapp on Tomcat.

Here are some links to blogs which assisted me in getting to this point:


Hope this helps :).


  1. Nice article , just to add I would suggest start up script to put JVM debug parameter and use a variable e.g. isDebugEnabled and also REMOTE_DEBUG_PORT in the script and export this variable when you want to remote debug your Java application. This will be very handy and will require just one time setup work.

    How to setup remote debugging in Eclipse

  2. this is really helped me. However, to restart the tomcat I have to move out the JAVA_OPTS line from the tocmat6.conf. Any solutions ?

  3. Hi Ojitha,

    Maybe you can try creating a bash profile and setting the JAVA_OPTS there. I think tomcat6.conf concatenates to existing JAVA_OPTS, if it exists.