Download PDF
Download page JBoss and Wildfly Startup Settings.
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
orstandalone.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 orrun.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.
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:
Open the
bin/standalone.sh
file.Add the following
javaagent
argument:export JAVA_OPTS="$JAVA_OPTS -javaagent:/agent_install_dir/javaagent.jar"
CODESpecify the argument above the following section of
standalone.sh
:... while true;do if [ "x$LAUNCH_JBOSS_IN_BACKGROUND" = "X" ]; then # Execute the JVM in the foreground eval \"$JAVA\" -D\"[Standalone]\"$JAVA_OPTS \ \"-Dorg.jboss.boot.log.file=$JBOSS_LOG_DIR/boot.log\" \ \"-Dlogging.configuration=file:$JBOSS_CONFIG_DIR/logging.properties\" \ -jar \"$JBOSS_HOME/jboss-modules.jar\" \
CODERestart the application server.
Add the following to the end of the
standalone.conf
file in theJAVA_OPTS
section.-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}} <path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
CODEJDK9 and above,
-Xbootclasspath/p
option has been removed; use-Xbootclasspath/a
instead.-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a: <path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
CODEReplace
<path_to_jboss_logmanager>
and<version>
with the path and log manager JAR filename for your system. See Making the LogManager Location Dynamic for information on making the path dynamic.Note
Step 5 and Step 6 are required only if the log manager errors manifest. Also, repeat Step 4 after this change.
In the
standalone.bat
file, add the following javaagent argument.set JAVA_OPTS=%JAVA_OPTS% -javaagent:\agent_install_dir\javaagent.jar
CODESpecify the argument above the following section in
standalone.bat
:RESTART "%JAVA%" %JAVA_OPTS% ^ "-Dorg.jboss.boot.log.file=%JBOSS_LOG_DIR%\server.log" ^ "-Dlogging.configuration=file:%JBOSS_CONFIG_DIR%/logging.properties" ^ -jar "%JBOSS_HOME%\jboss-modules.jar" ^ -mp "%JBOSS_MODULEPATH%" ^ -jaxpmodule "javax.xml.jaxp-provider" ^ org.jboss.as.standalone ^ "-Djboss.home.dir=%JBOSS_HOME%" ^ %SERVER_OPTS%
CODE- Restart the application server.
Add the following to the end of the
standalone.conf.bat
file in theJAVA_OPTS
section.-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/p:{{}} <path_to_jboss_logmanager>\jboss-logmanager-<version>.jar
CODEJDK9 and above,
-Xbootclasspath/p
option has been removed; use-Xbootclasspath/a
instead.-Djava.util.logging.manager=org.jboss.logmanager.LogManager -Xbootclasspath/a: <path_to_jboss_logmanager>/jboss-logmanager-<version>.jar
CODEReplace
<path_to_jboss_logmanager>
and<version>
with the path and log manager JAR filename for your system. See Making the LogManager Location Dynamic for information on making the path dynamic.Note
Step 4 and Step 5 are required only if the log manager errors manifest. Also, repeat Step 3 after this change.
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 thehost.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
- Locate and edit
domain.xml
for the domain. This is usually located under $JBOSS_HOME/domain/configuration/. Find the the
system-properties
element and add a property namedjboss.modules.system.pkgs
with a value ofcom.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>
CODEThis property tells the JBoss class loader to load the AppDynamics packages. This is required for the Java Agent to run.
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:
export JAVA_OPTS=""
env|grep JAVA_OPTS
JAVA_OPTS=
<You will see this message>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.