Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

Chapter 32. Managing JBoss EAP 5

32.1. Discovering JBoss EAP/AS 5 Servers

Most JBoss Enterprise Application Platforms are configured in a way that allows them and their child resources to be discovered and monitored without any additional configuration. When the agent attempts to discover and then manage resources, it uses certain assumptions based on common configuration to identify and connect to those resources. If for some reason the JBoss Enterprise Application Platform has configuration that differs from those assumptions, then JBoss ON may not be able to manage that system fully.
This section describes configuration settings that are required to discover or manage certain JBoss Enterprise Application Platform resource types.

32.1.1. Discovering and Managing the JBoss AS/EAP 5 JVM

For the JBoss ON agent to discover the JVM resource and its subsystems (such as memory, threading, and logging) for a JBoss EAP resource, the JBoss EAP instance must be configured to use the platform MBean server as the location where it registers its MBeans.
If necessary, edit the JBoss Enterprise Application Platform start script so that it uses the platform MBean server.
  1. Open the run.conf file. For example, on Red Hat Enterprise Linux: 
    [root@server ~]# vim jbossInstallDir/bin/run.conf
  2. Add the JAVA_OPTS settings to use the platform MBean server.
    On Red Hat Enterprise Linux: 
    JAVA_OPTS="$JAVA_OPTS -Djboss.platform.mbeanserver"
    On Windows: 
    set JAVA_OPTS=%JAVA_OPTS% -Djboss.platform.mbeanserver
  3. Restart the JBoss Enterprise Application Platform.

32.1.2. Enabling Remote Access to JMX and Profile Service

Management tasks like monitoring and running operations require that the agent is able to connect to the JMX server for the JBoss EAP/AS instance. This means that remote JMX access must be enabled.
  1. Verify that the JBoss Naming Protocol server (JNP) is deployed. (It is deployed by default.)
    Open the jboss-service.xml file: 
    [root@server ~]# vim jbossInstallDir/server/config/conf/jboss-service.xml
    Then, make sure that there is a line enabling the JNP connector. 
    <mbean code="org.jboss.naming.NamingService"> ... </mbean>
  2. While not required, it is recommended that you enable authentication for the JNP service. (This is enabled by default.)
    1. Open the jmx-invoker-service.xml file. 
      [root@server ~]# vim jbossInstallDir/server/config/deploy/jmx-invoker-service.xml
    2. Add a line for the JMX connector authentication. 
      <interceptor code="org.jboss.jmx.connector.invoker.AuthenticationInterceptor"
                     securityDomain="java:/jaas/jmx-console"/>
    3. Make sure that the admin user is listed in the JMX users properties file. When a new JBoss EAP resource is discovered, the agent reads the JMX username and password from this file and stores them in the discovered JBoss EAP resource's connection settings. These settings are then used to connect to the EAP server's JNP service. 
      [root@server ~]# vim jbossInstallDir/server/config/conf/props/jmx-console-users.properties
    4. Uncomment or add the user information. This is a simple key/value pair, username=password. For example: 
      admin=admin
  3. Restart the JBoss Enterprise Application Platform.

32.1.3. Setting Start Script Arguments, Environment Variables, and JAVA_OPTS

32.1.3.1. Start Script Discovery and Settings

As part of discovering a JBoss EAP 5 server, JBoss ON attempts to discover the environment that the server is running in. Specifically, the discovery process attempts to discover the runtime environment:
  • The discovery process identifies, or attempts to identify, the start script that was used to start the EAP server, whether it was run.sh|bat or a custom start script.
  • Discovery detects a subset of environment variables set in the run.conf file or parent process that are required for the start script to work.

    Note

    Although the discovery process does detect some environment variables, the discovery scan does not JAVA_OPTS values.
    The connection properties for the start script intentionally defer to the run.conf file for JAVA_OPTS values.
  • Discovery attempts to detect any arguments passed to the start script itself.
The discovered settings are stored in the Start Script Environment Variables and Start Script Arguments connection settings for the EAP 5 resource.
If the discovery scan cannot detect some of the script settings (such as the agent is running as a different user than the EAP 5 server and cannot read the parent process), it fails gracefully. It simply gathers whatever information it can and ignores blank values.

Note

The Start Script Environment Variables and Start Script Arguments connection settings are only discovered once, when the resource is initially discovered. After that, the connection settings can be changed in the connection settings configuration, but any changes made on the local system will not be detected. For example, if the server is discovered with a particular value (like -XX:PermSize=256M), the argument value will not be updated if the server is restarted later with a different setting value.
The script arguments and environment variables are the only ones used by the agent when it runs the start script. These arguments and environment variables are not added to other configuration settings or the parent process. The start script settings in the EAP 5 connection settings are deterministic.
In previous versions of the plug-in, the EAP/AS 5 server had a Java home directory setting and bind address (hostname or IP) that was used by the agent as part of identifying and running the start scripts.
If the Script Arguments field is empty, then the bind address and Java home directory[7] are still used for invoking the start script. If any script arguments are set, then the bind address and Java home values are ignored.
The script arguments value overrides any other start script connection settings.

32.1.3.2. Start Script Arguments and Drift Monitoring

JBoss ON can monitor directories or specific files to check for configuration drift, which means configuration changes that move away from a designated configuration state. This is described in more detail in the drift chapters of "Managing Resource Configuration."
While drift monitoring is critical for administrators to manage important resources, there may be times when it is necessary or beneficial from that configuration in a few settings. The start script arguments can be used to override the defined configuration for an EAP 5 server without triggering a drift alert.
Since the start script options are all connection settings, every change is recorded in a change history and can be easily viewed and reverted. This keeps the system properties and Java settings trackable and remediable.

Example 32.1. System Properties Without Violating the Drift Definition

Tim the IT Guy creates one specific set of configuration that all production EAP 5 servers should use an environment. He then creates a drift definition template for monitoring and associates or pins that blessed configuration to the template.
Every EAP 5 server which uses that drift template must conform to those configuration settings. Tim the IT Guy creates an alert that informs him if any production server drifts away from that specified configuration. This is an important safety measure for Example Co.'s production application servers.
However, a couple of the production servers have slightly different hardware and other applications running on them, so they require different heap sizes to run effectively.
If Tim the TI Guy adds a system property to use a different heap size, he is going to receive constant drift alerts or his edited configuration could be overwritten if he runs an automatic server-side script to remediate drift configuration.
By setting different heap settings through the start script, Tim can apply the right settings for that system without editing a configuration file, so there is no alert-able configuration drift.

32.1.3.3. Changing Start Script Configuration

  1. Click the Inventory tab in the top menu.
  2. Select Servers - Top Level Imports in the Resources menu table on the left. Select the JBoss EAP 5 server.
  3. In the inventory tree, select the top resource entry for the server.
  4. Open the Inventory tab, and select the Connection Settings subtab.
  5. Expand the Operations section.
  6. Change or add start script settings. These are the scripts and settings that the JBoss ON agent uses when running a start or restart operation on the EAP 5 server.
    • To use a custom start script, enter the path and script name.
    • Optionally, enter a prefix to use with the script when running the start script.
    • Set any environment variables, one per line.
    • Set any script arguments, one per line. For regular JAVA_OPTS, these arguments usually are -X, -D, or -P. Some useful -XX arguments are listed in the JVM options documentation from Sun.
      The EAP 5 default start scripts use a run.sh-style script, so the arguments use that format. A custom script can use different arguments or options.
  7. Click the Save button at the top of the page.

[7] The JBoss EAP/AS 5 server's Java home setting overrides the agent Java setting, if that start script value is set.