Summary

Error Messages

Steps to Reproduce

Root Cause

JBoss in recent versions introduced a 'Native Management Interface' which used the JBoss Remoting protocol instead of Java Remote Method Invocation (RMI). Consequently, the JMX connection through RMI is no longer enabled by default.

Resolution

1. Native management  (default port:9999 – default security realm: ManagementRealm)
2. Remoting (default port: 4447 – default security realm: ApplicationRealm)

Only one of the former ports will listen at runtime depending on the JBoss running mode.

However, no JMX client (SMA included) can connect to an instance of JBoss remotely through an RMI connector anymore.

For this, use the new JMX connector, developed by JBoss, which uses the JBoss Remoting protocol. These changes do not require modification to the SMA archive.

JMX Connection String:

To connect to the remote instance, use a different connection string which has the following format:

service:jmx:remoting-jmx://{host_name}:{port}

The Service URL always begins with the service:jmx: followed by the protocol, host, and port.

The protocol is JBoss specific and is named remoting-jmx.

The port and the user must be customized for authentication depending on the selected running mode,

Standalone mode:

Where {port} is the Native Management Interface of the JBoss installation being monitored (default=9999).
For authentication, use the credentials of the Management User in the Management Realm (the credentials used to log in to the JBoss Console).

Domain mode:

Where {port} is the  JMX subsystem interface of the JBoss installation being monitored (first server=4447, port-offset=150 next server).
For authentication, use the credentials of the Application User created in the Application Realm (the user created in the PegaDiagnosticUser group should suffice).

Test:

The first test is to be able to open a remote connection from the JConsole with the remoting-jmx url:

1. Launch the JConsole with the jconsole(.bat|.sh) script provided in the JBoss Bin directory (this script adds to the classpath, the JBoss client Jars).
2. Open the new Connection form.
3. Select Remote Process.
4. Insert the JMX connection string as described above.
5. Provide the username and password as described above.
   
   
    

   If the connection is successful, the user must be able to navigate to the MBeans and the below screen must display:
   
   

Classpath:

The libraries implementing the JBoss Remoting connector must be added to the client application classpath that wants to open a JMX Remote Connection.

Without the correct JARS on the classpath, if the JBoss Remoting connection string is used in the System Management Application (SMA), the below exception occurs:

Stack Trace:

com.pega.jmx.ui.util.JMXClientException: Cannot connect to the server with specified settings 
Unsupported protocol: remoting-jmx
       at com.pega.jmx.ui.util.JMXClientException.wrap(JMXClientException.java:49)
       at com.pega.jmx.ui.action.AuthenticateAction.execute(AuthenticateAction.java:346)
       at com.pega.jmx.ui.action.AuthenticateAction.executeWithoutValidation(AuthenticateAction.java:86)

Add the JBoss Remoting JMX connector to the SMA classpath:

Below are the two ways to achieve this goal.

The first one is the most immediate and does not require changes to the SMA archive; however, adding the JMX libraries to the shared classpath may not be applicable in all cases.

The second method has an effect only on SMA, but it requires adding a specific deployment descriptor to the SMA archive.

Method 1: Add the JBoss Remoting module to the list of global modules in the JBoss EE subsystem

Global modules in JBoss's recent versions are a way to support the concept of a common Library where shared libraries are included for use by all the deployed applications.

This approach,  successfully tested with JBoss EAP 6.3.0.GA, (but it is not guaranteed to work with other versions) can be achieved in two ways:

1. Using the JBoss console (as explained in the RedHat, 7.3. Add a module to all deployments)
2. Manually editing the $JBOSS_HOME/standalone/configuration/standalone(-full).xml file as below:
    
   <subsystem xmlns="urn:jboss:domain:ee:1.2">  
               <global-modules>  
                 <!-- Oracle JDBC Driver needed by PRPC SQLGeneratorOracle -->  
                   <module name="com.oracle" slot="main"/>  
                 <!-- Jboss Remoting JMX Connector -->  
                   <!-- For earlier JBoss versions the module name was org.jboss.remoting3 -->  
                   <!-- Check the module name that fits in your case -->  
                   <module name="org.jboss.remoting-jmx" slot="main"/>  
               </global-modules>  
   </subsystem>

Method 2: Add the jboss-deployment-structure.xml to the prsysmgmt_jboss.war archive

To  add the JMX libraries only to the SMA classpath, add the jboss-deployment-structure.xml file in the SMA archive:

The jboss-deployment-structure.xml is a JBoss specific deployment descriptor that is used to control the class loading.

It should be placed in the top level deployment, in META-INF (or WEB-INF for web deployments).

1. Unzip the original prsysmgmt_jboss.war archive in a directory.
2. Create a file with name jboss-deployment-structure.xml in the WEB-INF directory with the following content:
    
   <jboss-deployment-structure xmlns="urn:jboss:deployment-structure:1.1">  
     <deployment>  
     <dependencies>  
       <!-- For earlier JBoss versions the module name was org.jboss.remoting3 -->  
       <!-- Check the module name that fits in your case -->  
       <module name="org.jboss.remoting-jmx" services="import"/>  
     </dependencies>  
     </deployment>  
   </jboss-deployment-structure>  
     
3. Zip the directory  and rename it to prsysmgmt_jboss.war.
4. Deploy it in JBoss.

Define the remote connection in SMA:

Add a new connection providing the following details.

Update the IP address, ports, username, and password accordingly (reuse the values provided in the JConsole test executed before).



The user can now connect to the new defined remote node.