JBoss and Wildfly Startup Settings

This page describes how to install the AppDynamics Java Agent on Red Hat JBoss Enterprise Application Server and JBoss Wildfly. 

Before You Install

To install the agent on JBoss or Wildfly, you add the Java Agent and log manager packages to the server startup routine.

The configured location varies based on your framework version:

• In Linux, add the settings to standalone.conf or standalone.sh.
• In Windows, add the settings to standalone.conf.bat.
• If using JBoss 4.x or 5.x, add the configuration to run.sh for Linux or run.bat for Windows.

Initialize the JVM

To install the Java Agent on JBoss EAP or JBoss Wildfly, you need to initialize the JVM. Run this parameter:

JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity"

If you do not initialize the JVM, the installation generates a "class not found" exception. 

Ensure that the property jboss.modules.system.pkgs is available in the environment. If the property is present, then add com.singularity to it.

For example: 

-Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity

If the property is not present, then configure a new one:

-Djboss.modules.system.pkgs=com.singularity

Standalone Mode Agent Installation

These instructions assume the use of Red Hat JBoss (Application Server 7.x or Enterprise Application Server >= 6.x). 

To install the Java Agent on JBoss Standalone:

Dynamic LogManager Location

On standalone JBoss instances, instead of hard coding the path and name of the log manager JAR, you can use glob pattern matching techniques to make the path to the log manager file dynamic, so that it is resilient to change or variances among systems. 

The exact steps to accomplish this varies by environment. These sections provide an example of this configuration on Windows and Linux systems, and are meant as a starting point for your own implementation. 

Windows

In Windows, the standalone.conf.bat gets this additional snippet:

...
rem jboss.modules.system.pkgs
set JAVA_OPTS=%JAVA_OPTS% -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity,org.jboss.logmanager

rem java.util.logging 
set JAVA_OPTS=%JAVA_OPTS% -Djava.util.logging.manager=org.jboss.logmanager.LogManager

rem bootclasspath
set LOGMANAGER= 
for /f %%i in ('dir /b "%JBOSS_HOME%\modules\system\layers\base\org\jboss\logmanager\main\jboss-logmanager-*.jar"') do ( 
   set LOGMANAGER_JAR=%JBOSS_HOME%\modules\system\layers\base\org\jboss\logmanager\main\%%i 
) 
set JAVA_OPTS=%JAVA_OPTS% -Xbootclasspath/p:%LOGMANAGER_JAR%

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly. 

Linux

In Linux, you can populate the path dynamically with the following code: 

JBOSS_MODULES_SYSTEM_PKGS ="org.jboss.byteman,com.singularity,org.jboss.logmanager"

JAVA_OPTS="$JAVA_OPTS -Djava.util.logging.manager=org.jboss.logmanager.LogManager"
JAVA_OPTS="$JAVA_OPTS -Xbootclasspath/p:$(ls ${JBOSS_HOME}/modules/system/layers/base/org/jboss/logmanager/main/jboss-logmanager-*.jar)"

If using the ${JBOSS_HOME} variable, as in the example, be sure to set the variable to the directory to the JBoss installation directory on your system. 

The path to the LogManager JAR file under the JBoss home can vary by JBoss version. Be sure to check your system and adjust the path as shown in the example accordingly. 

Domain Mode Agent Installation

For domain mode, the location in which you need to configure the settings depends upon specifics for your environment. Keep in mind that a domain is made up of these components:

• A domain controller, the administration and configuration server. The domain.xml configuration file is the global configuration for the managed hosts. 
• Host controllers, which manage a particular host containing one or more application server nodes. There can be any number of host controllers and nodes. The hosts.xml file contains settings for the nodes on that host machine. 
   

Where you put the configuration, therefore, varies as follows:

• domain.xml: Settings that can be identical for all hosts in the managed domain (i.e., the log manager and agent files are at the same location on all machines) can go into the domain.xml file for the Domain Controller. 
• host.xml: Settings that need to be specialized for individual hosts (for example, if the paths to relevant files on hosts vary) need to go into the host.xml file. 

You can add configuration settings to both domain.xml and host.xml, depending on which are global and which are host-specific. The following sections show an example of adding general settings to the domain configuration and node name setting to the host configuration. 

Domain.xml Configuration

1. Locate and edit domain.xml for the domain. This is usually located under $JBOSS_HOME/domain/configuration/.

2. Find the the system-properties element and add a property named jboss.modules.system.pkgs with a value of com.singularity to the existing system properties. For example:

   <system-properties>
           <!-- IPv4 is not required, but setting this helps avoid unintended use of IPv6 -->
           <property name="java.net.preferIPv4Stack" value="true"/>
           <property name="jboss.modules.system.pkgs" value="com.singularity"/>
   </system-properties>
   

   CODE

   This property tells the JBoss class loader to load the AppDynamics packages. This is required for the Java Agent to run.

   Ensure that the property jboss.modules.system.pkgs is available in the environment. If the property is present, then add com.singularity to it.

   For example: 

   -Djboss.modules.system.pkgs=org.jboss.byteman,com.singularity

   CODE

   If the property is not present, then configure a new one:

   -Djboss.modules.system.pkgs=com.singularity

   CODE

3. Under the server group name where you want to enable your agents, add the JVM options using the appropriate values for your agent location, JBoss application name, and tier name.

   <server-group name="main-server-group" profile="full">
       <jvm name="default">
            <heap size="1303m" max-size="1303m"/>
            <permgen max-size="256m"/>
            <jvm-options>
               <option value="-javaagent:<agent_install_dir>/javaagent.jar"/> 
               <option value="-Dappdynamics.agent.applicationName=JBOSS-EAP-APP"/>
               <option value="-Dappdynamics.agent.tierName=JBOSS-EAP-TIER"/>
            </jvm-options>
       </jvm>
       <socket-binding-group ref="full-sockets"/>
    </server-group>

   CODE

Changes to the domain.xml file require a restart of the management host to take effect. The changes are not propagated to server hosts until they are restarted as well.

Host.xml Configuration

For each host, specify the AppDynamics node name in the host.xml file, usually located under $JBOSS_HOME/domain/configuration/.

Add the -Dappdynamics.agent.nodeName JVM option to specify the node name for this instance:

<servers>
    <server name="server-one" group="main-server-group"> 
            <jvm name="default">
              <jvm-options>
                <option value="-agentlib:jdwp=transport=dt_socket,address=8787,server=y,suspend=n"/>
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-1"/>
              </jvm-options>
            </jvm>
     </server>
     <server name="server-two" group="main-server-group" auto-start="true">
            <socket-bindings port-offset="150"/>
            <jvm name="default">
              <jvm-options>
                <option value="-Dappdynamics.agent.nodeName=JBOSS-EAP-NODE-2"/>
              </jvm-options>
            </jvm>
      </server>
      <server name="server-three" group="other-server-group" auto-start="false">
            <socket-bindings port-offset="250"/>
      </server>
</servers>

For brevity, comments have been removed from the sample. 

Troubleshooting JBoss Startup Issues

Most issues installing the Java Agent on JBoss result from conflicts between startup arguments. That is, settings you add for the Java Agent may be overridden or conflict in other ways with existing arguments. Such issues are not always easy to detect.

The best way to begin troubleshoot such startup issues is to print and inspect the startup arguments that JBoss actually gets when attempting to start. To do this, view JBoss process information during startup using the following command. You need to issue this command while the start up attempt is occurring but before it fails.   

ps -ef | grep [o]rg.jbossas | tr ' ' '\n' | sed -e '/^$/d' 

Troubleshooting JBoss Shutdown Issues

When enabling the JMXremote features of the JVM on a JBoss 5.1.2 server configuration, the following error is generated when calling the /bin/shutdown.sh:

javax.management.JMRuntimeException: Failed to load MBeanServerBuilder class org.jboss.system.server.jmx.MBeanServerBuilderImpl: 
java.lang.ClassNotFoundException: org.jboss.system.server.jmx.MBeanServerBuilderImpl

Resolution

Sometimes, there is JAVA_OPTS parameter in the environment, and it affects to a java process when the JVM start.
From the reason that EAP uses JAVA_OPTS parameter internally, it should not be in the environment.

To clear the parameter in the environment, executing the following from a console:

1. export JAVA_OPTS=""

2. env|grep JAVA_OPTS
JAVA_OPTS= <You will see this message>

3. shutdown.sh -s jnp://localhost:1099 -u USER -p PASSWORD

Root Cause

JMX related options should not be set in JAVA_OPTS when calling shutdown.sh. Ensure JAVA_OPTS is only set when starting JBoss EAP, not when running.