Red Hat Training

A Red Hat training course is available for Red Hat JBoss Enterprise Application Platform

Chapter 14. JVM

14.1. About JVM

14.1.1. About JVM Settings

Configuration of Java Virtual Machine (JVM) settings varies between the managed domain and standalone server instances. In a managed domain, the JVM settings are declared in host.xml and domain.xml configuration files, and determined by the domain controller components responsible for starting and stopping server processes. In a standalone server instance, the server startup processes can pass command line settings at startup. These can be declared from the command line or via the System Properties screen in the Management Console.

Note

System properties not configured in JAVA_OPTS cannot be used for properties used by JBoss Modules at boot time, nor can it be used for other JVM properties such as java.util.logging.manager.
Managed Domain

An important feature of the managed domain is the ability to define JVM settings at multiple levels. You can configure custom JVM settings at the host level, by server group, or by server instance. The more specialized child elements will override the parent configuration, allowing for the declaration of specific server configurations without requiring exclusions at the group or host level. This also allows the parent configuration to be inherited by the other levels until settings are either declared in the configuration files or passed at runtime.

Example 14.1. JVM settings in the domain configuration file

The following example shows a JVM declaration for a server group in the domain.xml configuration file. 
<server-groups>
       <server-group name="main-server-group" profile="default">
           <jvm name="default">
               <heap size="64m" max-size="512m"/>
           </jvm>
           <socket-binding-group ref="standard-sockets"/>
       </server-group>
       <server-group name="other-server-group" profile="default">
           <jvm name="default">
               <heap size="64m" max-size="512m"/>
           </jvm>
           <socket-binding-group ref="standard-sockets"/>
       </server-group>
</server-groups>
In this instance a server group called main-server-group is declaring a heap size of 64 megabytes, and a maximum heap size of 512 megabytes. Any server that belongs to this group will inherit these settings. You can change these settings for the group as a whole, by the host, or the individual server.

Example 14.2. Domain settings in the host configuration file

The following example shows a JVM declaration for a server group in the host.xml configuration file. 
<servers>
  <server name="server-one" group="main-server-group" auto-start="true">
    <jvm name="default"/>
  </server>
  <server name="server-two" group="main-server-group" auto-start="true">
    <jvm name="default">
      <heap size="64m" max-size="256m"/>
    </jvm>
    <socket-bindings port-offset="150"/>
  </server>
  <server name="server-three" group="other-server-group" auto-start="false">
    <socket-bindings port-offset="250"/>
  </server>
</servers>
In this instance, a server named server-two belongs to the server group named main-server-group, inheriting the JVM settings from the default JVM group. In the previous example, the main heap size for main-server-group was set at 512 megabytes. By declaring the lower maximum heap size of 256 megabytes, server-two can override the domain.xml settings to fine-tune performance as desired.
Standalone server settings at runtime

The JVM settings for standalone server instances can be declared at runtime by setting the JAVA_OPTS environment variable before starting the server. An example of setting the JAVA_OPTS environment variable at the Linux command-line is: 

[user@host bin]$ export JAVA_OPTS="-Xmx1024M"
The same setting can be used in a Microsoft Windows environment, as follows: 
C:\> set JAVA_OPTS="Xmx1024M"
Alternatively, JVM settings can be added to the standalone.conf file found in the EAP_HOME/bin folder, which contains examples of options to pass to the JVM.

Warning

Setting the JAVA_OPTS environment variable will re-define the default values for the JAVA_OPTS environment variable. This can break or terminate the start of JBoss EAP.
Report a bug

14.1.2. Display the JVM Status in the Management Console

Prerequisites

Java Virtual Machine (JVM) status can be displayed in the Management Console for either the standalone server or a managed domain. The console shows the heap usage, non heap usage, and thread usage of the server. While the statistics are not displayed in real-time, you can refresh the console display to provide an up-to-date overview of JVM resources.
The JVM status shows the following values.

Table 14.1. JVM Status Attributes

Type Description
Max The maximum amount of memory that can be used for memory management. The maximum availabe memory is shown by the light grey bar.
Used The amount of used memory. The amount of used memory is shown by the dark grey bar.
Committed The amount of memory that is committed for the Java virtual machine to use. The committed memory is shown by the dark grey bar.

Procedure 14.1. Display the JVM Status in the Management Console

    • Display the JVM status for a standalone server instance

      Select the Runtime tab from the top of the screen. Expand the Status menu, then expand the Platform menu. Select JVM.

    • Display the JVM status for a managed domain

      Select the Runtime tab from the top of the screen. Expand the Server Status menu, then expand the Platform menu. Select JVM.
  2. The managed domain can provide visibility of all server instances in the server group, but will only allow you to view one server at a time by selecting from the server menu. To view the status of other servers in your server group, click Change Server left of the screen to select from the host and servers displayed in your group. Select the required server or host and the JVM details will change. Click Close to finish.
Result

The status of the JVM settings for the server instance are displayed.

Report a bug

14.1.3. Configuring JVM

The <jvm></jvm> tags support the usage of <jvm-options></jvm-options>, which can be used to add parameters to the JVM configuration using the <option value="VALUE"/> tag.

Example 14.3. Use of <jvm-options>

<jvm name="default">
  <heap size="1303m" max-size="1303m"/>
  <permgen max-size="256m"/>
  <jvm-options>
    <option value="-XX:+UseCompressedOops"/>
  </jvm-options>
</jvm>
Configuring JVM Using CLI

To configure JVM using CLI, use the following syntax: 

# cd /server-group=main-server-group/jvm=default

# :add-jvm-option(jvm-option="-XX:+UseCompressedOops")
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {"master" => {
        "server-one" => {"response" => {
            "outcome" => "success",
            "response-headers" => {
                "operation-requires-restart" => true,
                "process-state" => "restart-required"
            }
        }},
        "server-two" => {"response" => {
            "outcome" => "success",
            "response-headers" => {
                "operation-requires-restart" => true,
                "process-state" => "restart-required"
            }
        }}
    }}}}
}

# :read-resource

# Expected Result:

[domain@localhost:9999 jvm=default] :read-resource                                      
  {
    "outcome" => "success",
    "result" => {
    "agent-lib" => undefined,
    "agent-path" => undefined,
    "env-classpath-ignored" => undefined,
    "environment-variables" => undefined,
    "heap-size" => "1303m",
    "java-agent" => undefined,
    "java-home" => undefined,
    "jvm-options" => ["-XX:+UseCompressedOops"],
    "max-heap-size" => "1303m",
    "max-permgen-size" => "256m",
    "permgen-size" => undefined,
    "stack-size" => undefined,
    "type" => undefined
  }
}

Removing jvm-options Entry

To remove jvm-options entry, use the following syntax: 

# cd /server-group=main-server-group/jvm=default

# :remove-jvm-option(jvm-option="-XX:+UseCompressedOops")

# Expected Result:

[domain@localhost:9999 jvm=default] :remove-jvm-option(jvm-option="-XX:+UseCompressedOops")
{
    "outcome" => "success",
    "result" => undefined,
    "server-groups" => {"main-server-group" => {"host" => {"master" => {
        "server-one" => {"response" => {
            "outcome" => "success",
            "response-headers" => {
                "operation-requires-restart" => true,
                "process-state" => "restart-required"
            }
        }},
        "server-two" => {"response" => {
            "outcome" => "success",
            "response-headers" => {
                "operation-requires-restart" => true,
                "process-state" => "restart-required"
            }
        }}
    }}}}
}

Specifying 32-Bit or 64-Bit Architecture

In some environments, such as Hewlett-Packard HP-UX and Solaris, the -d32 or -d64 switch is used to specify whether to run in a 32-bit or 64-bit JVM respectively. The default is 32-bit if neither option is indicated.

Procedure 14.2. Specifying 64-Bit Architecture for a Standalone Server

  1. Open the EAP_HOME/bin/standalone.conf file.
  2. Add the following line to append the -d64 option to JAVA_OPTS. 
    JAVA_OPTS="$JAVA_OPTS -d64"

Procedure 14.3. Specifying 64-Bit Architecture for a Managed Domain

When running in a managed domain, you can specify the 64-bit environment for host and process controllers in addition to server instances.
  1. Set the host and process controllers to run in the 64-bit JVM.
    1. Open the EAP_HOME/bin/domain.conf file.
    2. Add the following line to append the -d64 option to JAVA_OPTS. Ensure that this is inserted before PROCESS_CONTROLLER_JAVA_OPTS and HOST_CONTROLLER_JAVA_OPTS are set. 
      JAVA_OPTS="$JAVA_OPTS -d64"

      Example 14.4. JVM options in domain.conf

      #  
# Specify options to pass to the Java VM.  
#  
if [ "x$JAVA_OPTS" = "x" ]; then  
  JAVA_OPTS="-Xms64m -Xmx512m -XX:MaxPermSize=256m -Djava.net.preferIPv4Stack=true"  
  JAVA_OPTS="$JAVA_OPTS -Djboss.modules.system.pkgs=$JBOSS_MODULES_SYSTEM_PKGS -Djava.awt.headless=true"  
  JAVA_OPTS="$JAVA_OPTS -Djboss.modules.policy-permissions=true"  
  JAVA_OPTS="$JAVA_OPTS -d64"  
else  
  echo "JAVA_OPTS already set in environment; overriding default settings with values: $JAVA_OPTS"  
fi
  2. Set the server instances to run in the 64-bit JVM.
    1. Add -d64 as a JVM option in the appropriate host.xml configuration files.

      Example 14.5. JVM options in host.xml

      <jvms>  
  <jvm name="default">  
    <heap size="64m" max-size="256m"/>  
    <permgen size="256m" max-size="256m"/>  
    <jvm-options>  
      <option value="-server"/>  
      <option value="-d64"/>  
    </jvm-options>  
  </jvm>  
</jvms>

      Note

      The -d64 option can be added for the appropriate hosts using the Management CLI with the following command: 
      /host=HOST_NAME/jvm=default:add-jvm-option(jvm-option="-d64")
Report a bug

14.1.4. About the Java Security Manager

The Java Security Manager is a class that manages the external boundary of the Java Virtual Machine (JVM) sandbox, controlling how code executing within the JVM can interact with resources outside the JVM. When the Java Security Manager is activated, the Java API checks with the security manager for approval before executing a wide range of potentially unsafe operations. The Java Security Manager uses a security policy to determine whether a given action will be allowed or denied.
Report a bug

14.1.5. About Java Security Policies

A Java Security policy is a set of defined permissions for different classes of code. The Java Security Manager compares actions requested by applications against the security policy. If an action is allowed by the policy, the Security Manager will permit that action to take place. If the action is not allowed by the policy, the Security Manager will deny that action. The security policy can define permissions based on the location of code, on the code's signature, or based on the subject's principals.
Security policy grant entries consist of the following configuration elements:
CodeBase
The URL location (excluding the host and domain information) where the code originates from. This parameter is optional.
SignedBy
The alias used in the keystore to reference the signer whose private key was used to sign the code. This can be a single value or a comma-separated list of values. This parameter is optional. If omitted, presence or lack of a signature has no impact on the Java Security Manager.
Principals
A list of principal_type/principal_name pairs, which must be present within the executing thread's principal set. The Principals entry is optional. If it is omitted, it signifies that the principals of the executing thread will have no impact on the Java Security Manager.
Permissions
A permission is the access which is granted to the code. Many permissions are provided as part of the Java Enterprise Edition 6 (Java EE 6) specification.
Report a bug

14.1.6. Write a Java Security Policy

An application called policytool is included with most JDK and JRE distributions, for the purpose of creating and editing Java security policies. Detailed information about policytool is linked from http://docs.oracle.com/javase/6/docs/technotes/tools/. Alternatively, you can also write a security policy using a text editor.

Procedure 14.4. Setup a new Java Security Manager Policy

  1. Start policytool.

    Start the policytool tool in one of the following ways.

    • Red Hat Enterprise Linux

      From your GUI or a command prompt, run /usr/bin/policytool.

    • Microsoft Windows Server

      Run policytool.exe from your Start menu or from the bin\ of your Java installation. The location can vary.

  2. Create a policy.

    To create a policy, select Add Policy Entry. Add the parameters you need, then click Done.

    Note

    Use VFS to specify paths for applications deployed on JBoss EAP. On Linux the path is: vfs:/content/application.war. On Microsoft Windows it is: vfs:/${user.dir}/content/application.war .
    For example: 
    grant codeBase "vfs:/content/application.war/-" {
permission java.util.PropertyPermission "*", "read";
};

  3. Edit an existing policy

    Select the policy from the list of existing policies, and select the Edit Policy Entry button. Edit the parameters as needed.

  4. Delete an existing policy.

    Select the policy from the list of existing policies, and select the Remove Policy Entry button.
Report a bug

14.1.7. Run JBoss EAP 6 Within the Java Security Manager

From JBoss EAP 6.4 and onwards, running JBoss EAP 6 within the Java Security Manager (JSM) is done using the secmgr option.

Important

Direct usage of the -Djava.security.manager Java system property is no longer possible. This previous method used in older versions of JBoss EAP 6 to enable the Java Security Manager is now only supported as a fallback mechanism in the JBoss EAP startup scripts.

Note

From JBoss EAP 6.4 and onwards, custom security managers cannot be used.
The following procedure guides you through the steps of configuring your JBoss EAP 6 instance to run within the Java Security Manager using a specified security policy.

Prerequisites

  • Before you follow this procedure, you need to write a security policy using the policytool application which is included in the Java Development Kit (JDK) or the Java SE Runtime Environment (JRE). Alternatively, you can write a security policy using a text editor.
    Security policies will be needed for any user deployments that require permissions. This procedure assumes that your policy is located at EAP_HOME/bin/server.policy.
  • The domain or standalone server must be completely stopped before you edit any configuration files.
If you are using JBoss EAP 6 in a Managed Domain, you must perform the following procedure on each physical host or instance in your domain.

Procedure 14.5. Configure the Java Security Manager for JBoss EAP 6

  1. Open the Configuration File

    Open the configuration file for editing. The configuration file you need to edit depends on whether you use a Managed Domain or standalone server, as well as your operating system.

    • Managed Domain

      • For Linux: EAP_HOME/bin/domain.conf
      • For Windows: EAP_HOME\bin\domain.conf.bat

    • Standalone Server

      • For Linux: EAP_HOME/bin/standalone.conf
      • For Windows: EAP_HOME\bin\standalone.conf.bat

  2. Enable the Java Security Manager

    Use one of the methods below to enable the Java Security Manager:
    • Use the -secmgr option with your JBoss EAP 6 server startup script.
    • Uncomment the SECMGR="true" line in the configuration file:

      • On Linux:

        # Uncomment this to run with a security manager enabled
SECMGR="true"

      • On Windows:

        rem # Uncomment this to run with a security manager enabled
set "SECMGR=true"

  3. Specify the Java Security Policy

    You can use -Djava.security.policy to specify the exact location of your security policy. It should go onto one line only, with no line break. Using == when setting -Djava.security.policy specifies that the security manager will use only the specified policy file. Using = specifies that the security manager will use the specified policy combined with the policy set in the policy.url section of JAVA_HOME/jre/lib/security/java.security.
    In your relevant JBoss EAP 6 configuration file, add your security policy Java options. If you are using a Managed Domain, ensure that this is inserted before where PROCESS_CONTROLLER_JAVA_OPTS and HOST_CONTROLLER_JAVA_OPTS are set.

    • On Linux:

      JAVA_OPTS="$JAVA_OPTS -Djava.security.policy==EAP_HOME/bin/server.policy -Djboss.home.dir=EAP_HOME"

    • On Windows:

      set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.policy==EAP_HOME\bin\server.policy -Djboss.home.dir=EAP_HOME"

  4. Start the Domain or Server

    Start the domain or server as normal.
Report a bug

14.1.8. IBM JDK and the Java Security Manager

Some versions of the IBM JDK use a default policy provider which does not work correctly with a JBoss EAP security policy. If you are having problems using an IBM JDK to host JBoss EAP with the Java Security Manager enabled, you must change the JRE configuration to use the standard policy provider.
To modify the JRE configuration for the IBM JDK, edit the JAVA_HOME/jre/lib/security/java.security file, and set the policy.provider value to sun.security.provider.PolicyFile. 
policy.provider=sun.security.provider.PolicyFile
Report a bug

14.1.9. Debug Security Manager Policies

You can enable debugging information to help you troubleshoot security policy-related issues. The java.security.debug option configures the level of security-related information reported. The command java -Djava.security.debug=help will produce help output with the full range of debugging options. Setting the debug level to all is useful when troubleshooting a security-related failure whose cause is completely unknown, but for general use it will produce too much information. A sensible general default is access:failure.

Procedure 14.6. Enable general debugging

  • This procedure will enable a sensible general level of security-related debug information.

    Add the following line to the server configuration file.
    • If the JBoss EAP 6 instance is running in a managed domain, the line is added to the bin/domain.conf file for Linux or the bin\domain.conf.bat file for Windows.
    • If the JBoss EAP 6 instance is running as a standalone server, the line is added to the bin/standalone.conf file for Linux, or the bin\standalone.conf.bat file for Windows.
Linux 
JAVA_OPTS="$JAVA_OPTS -Djava.security.debug=access:failure"
Windows 
set "JAVA_OPTS=%JAVA_OPTS% -Djava.security.debug=access:failure"
Result

A general level of security-related debug information has been enabled.

Report a bug