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

6.4.1. Start Script Discovery and Settings

As part of discovering a JBoss EAP 6 server (domain controller or standalone server), JBoss ON attempts to discover the environment that the server is running in. Specifically, the discovery process attempts to identify and recreate the runtime environment:
  • The discovery process identifies, or attempts to identify, the start script used, including custom start scripts.
  • 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 detect 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 with the start script itself.
  • Discovery attempts to detect what user the script is running as and assign a prefix command to use with the start script. For example, if the start script is running as the jboss user and the JBoss ON agent is running as jonagent, then the discovery script automatically assigns a sudo command, sudo -u jboss -g jboss, to pass with the start script.
The discovered settings are stored in the Start Script Environment Variables and Start Script Arguments connection settings for the EAP 6 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 6 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, 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 6 connection settings configuration are deterministic.

6.4.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 Section 6.12, “Controlling Configuration Drift” and 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 6 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, as in Section 6.13, “Tracking and Reverting Configuration Changes”. This keeps the system properties and Java settings trackable and remediable.

Example 6.1. System Properties Without Violating the Drift Definition

Tim the IT Guy creates one specific set of configuration that all production EAP 6 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 6 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.

6.4.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 6 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 area.
  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 6 server.
    • To use a custom start script, one other than domain.sh or standalone.sh, enter the path and script name.
    • Optionally, enter a prefix to use with the script when running the start script.
      When the start script is discovered, the agent tries to determine the user the script is running as and assign a prefix command to use with the start script. For example, if the start script is running as the jboss user and the JBoss ON agent is running as jonagent, then the discovery script automatically assigns a sudo command, sudo -u jboss -g jboss, to pass with the start script.
      Additionally, JBoss ON assigns the nohup command as a prefix so that if the JBoss EAP/AS server is started by the agent and the agent process dies, the JBoss EAP/AS server process continues running.
    • 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. Some useful system properties for EAP 6 are listed with the JBoss AS7 project documentation.
      The EAP 6 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.