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

11.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[2] 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.

11.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 11.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.

11.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.


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