Friday, December 26, 2014

How to setup remote JBoss debugging with Intellij

Prepare JBoss

  • edit standalone.conf.bat, uncomment JDPA settings

rem # Sample JPDA settings for remote socket debugging
set "JAVA_OPTS=%JAVA_OPTS% -Xrunjdwp:transport=dt_socket,address=5678,server=y,suspend=n"

  • add management user using <jboss home>/bin/add-user.bat

C:\Program Files\Hewlett-Packard\CSA\jboss-as-7.1.1.Final\bin>add-user.bat
JAVA_HOME is not set. Unexpected results may occur.
Set JAVA_HOME to the directory of your local JDK to avoid this message.
What type of user do you wish to add?
a) Management User (
b) Application User (
Enter the details of the new user to add.
Realm (ManagementRealm) :
Username : ccue3
Password :
Re-enter Password :
About to add user 'ccue3' for realm 'ManagementRealm'
Is this correct yes/no?

  • edit standalone.xml and make sure the management is listening to all interface

  <interface name="management">
    <inet-address value="${}"/>
  <interface name="public">
    <inet-address value="${jboss.bind.address:}"/>

  • make sure you can login to the admin console using the created user (note the port number.  it's the management-http port in standalone.xml, not the management-native.)

Setup Firewall (Linux)

if using linux, esp our Propel stack, ports are not opened by default.  Need to open the native management port (default 9999) and debug port (default 8787).  HTTP management port (default 9990) can also be open to verify if the management user is setup correctly.
iptables -I INPUT -p tcp --dport 9999 -j ACCEPT
iptables -I INPUT -p tcp --dport 9990 -j ACCEPT
iptables -I INPUT -p tcp --dport 8787 -j ACCEPT
service iptables save
service iptables restart

Setup Intellij

  • create a new remove jboss server run/debug configuration
  • remote connection settings and jboss server settings is the management-native port on stanalone.xml.  also put in the username/password.

  • also make sure the port is the one set in the standalone.conf.bat.  (make sure you click on debug)

That's it.  you should be able to connect to this instance.  one more thing is, if you somehow connected to it but failed, you'll have to restart jboss.

you should see 2 messages.  Connected to server means it succesfully connected to the management port and Connected to the target VM is the debug port.

I find using SSH tunneling faster and more stable than opening the ports in firewall.  here's how.  step is pretty much the same as before
  1. no need to change the management port in standalone.xml (no need to change anything in the standalone.xml at all)
  2. no need to add firewall rules (again, no need to do any iptables call at all)
  3. execute the follow on your LOCAL machine
    ssh -f root@hostname -L 8787:localhost:8787 -N
    ssh -f root@hostname -L 9999:localhost:9999 -N
    ssh -f root@hostname -L 9990:localhost:9990 -N
    assuming 8787 is the debug port specified in the JDPA setting, 9999 is the management port and 9990 is the management http port (no need if you're not accessing the admin console remotely)
    and hostname is the hostname of the remote machine
    the ssh command is to connect to hostname as root and map local port 8787 (the first one) to remote port and make it appears as localhost on port 8787 and keep it running.  so from now on, accessing localhost:8787 on your local machine is the same as accessing localhost:8787 on the remote machine. 
  4. when setting up intellij, use localhost instead of remote machine hostname.