Red Hat Training

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

2.4. Configuration Files

2.4.1. About JBoss EAP 6 Configuration Files

The configuration for JBoss EAP 6 has changed considerably from previous versions. One of the most obvious differences is the use of a simplified configuration file structure, which includes one or more of the files listed below.

Table 2.3. Configuration File Locations

Server mode Location Purpose
domain.xml EAP_HOME/domain/configuration/domain.xml This is the main configuration file for a managed domain. Only the domain master reads this file. On other domain members, it can be removed.
host.xml EAP_HOME/domain/configuration/host.xml This file includes configuration details specific to a physical host in a managed domain, such as network interfaces, socket bindings, the name of the host, and other host-specific details. The host.xml file includes all of the features of both host-master.xml and host-slave.xml, which are described below. This file is not present for standalone servers.
host-master.xml EAP_HOME/domain/configuration/host-master.xml This file includes only the configuration details necessary to run a server as a managed domain master server. This file is not present for standalone servers.
host-slave.xml EAP_HOME/domain/configuration/host-slave.xml This file includes only the configuration details necessary to run a server as a managed domain slave server. This file is not present for standalone servers.
standalone.xml EAP_HOME/standalone/configuration/standalone.xml This is the default configuration file for a standalone server. It contains all information about the standalone server, including subsystems, networking, deployments, socket bindings, and other configurable details. This configuration is used automatically when you start your standalone server.
standalone-full.xml EAP_HOME/standalone/configuration/standalone-full.xml This is an example configuration for a standalone server. It includes support for every possible subsystem except for those required for high availability. To use it, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-full.xml
standalone-ha.xml EAP_HOME/standalone/configuration/standalone-ha.xml This example configuration file enables all of the default subsystems and adds the mod_cluster and JGroups subsystems for a standalone server, so that it can participate in a high-availability or load-balancing cluster. This file is not applicable for a managed domain. To use this configuration, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-ha.xml
standalone-full-ha.xml EAP_HOME/standalone/configuration/standalone-full-ha.xml This is an example configuration for a standalone server. It includes support for every possible subsystem, including those required for high availability. To use it, stop your server and restart using the following command: EAP_HOME/bin/standalone.sh -c standalone-full-ha.xml
These are only the default locations. You can specify a different configuration file at runtime.

Note

For information about how to backup JBoss EAP 6 configuration data, refer Section 2.4.2, “Back up JBoss EAP Configuration Data” .
Report a bug

2.4.2. Back up JBoss EAP Configuration Data

Summary

This topic describes the files that must be backed up in order to later restore the JBoss EAP server configuration.

Procedure 2.13. Back Up the Configuration Data

  1. To keep user and profile data, domain, host, slave, and logging configuration, back up the entire contents of the following directories.
    • EAP_HOME/standalone/configuration/
    • EAP_HOME/domain/configuration
  2. Back up any custom modules created in the EAP_HOME/modules/system/layers/base/ directory.
  3. Back up any welcome content in the EAP_HOME/welcome-content/ directory.
  4. Back up any custom scripts created in the EAP_HOME/bin/ directory.
Report a bug

2.4.3. Descriptor-based Property Replacement

Application configuration - for example, datasource connection parameters - typically varies between development, testing, and production deployments. This variance is sometimes accommodated by build system scripts, as the Java EE specification does not contain a method to externalize these configurations. With JBoss EAP 6 you can use descriptor-based property replacement to manage configuration externally.
Descriptor-based property replacement substitutes properties based on descriptors, allowing you to remove assumptions about the environment from the application and the build chain. Environment-specific configurations can be specified in deployment descriptors rather than annotations or build system scripts. You can provide configuration in files or as parameters at the command line.
Descriptor-based property replacement is enabled globally through standalone.xml or domain.xml:

Example 2.9. Descriptor-based property replacement

<subsystem xmlns="urn:jboss:domain:ee:1.2">
  <spec-descriptor-property-replacement>
    true
  </spec-descriptor-property-replacement>
  <jboss-descriptor-property-replacement>
    true
  </jboss-descriptor-property-replacement>
</subsystem>
Java EE descriptor replacement is disabled by default. When enabled, descriptors can be replaced in the following configuration files: ejb-jar.xml and persistence.xml.
JBoss-specific descriptor replacement is enabled by default. When enabled, descriptors can be replaced in the following configuration files:
  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml
For example, given a Bean with the following annotation:

Example 2.10. Example annotation

@ActivationConfigProperty(propertyName = "connectionParameters", propertyValue = "host=192.168.1.1;port=5445")
With descriptor-based property replacement enabled, the connectionParameters can be specified via the command-line as: 
./standalone.sh -DconnectionParameters='host=10.10.64.1;port=5445'
To accomplish the same via system properties you use an expression in place of the literal value. Expressions take the format ${parameter:default}. Where an expression is used in configuration, the value of that parameter takes its place. If the parameter does not exist then the specified default value is used instead.

Example 2.11.  Using an Expression in a Descriptor 

<activation-config>
  <activation-config-property>
    <activation-config-property-name>
      connectionParameters
      </activation-config-property-name>
    <activation-config-property-value>
      ${jms.connection.parameters:'host=10.10.64.1;port=5445'}
    </activation-config-property-value>
  </activation-config-property>
</activation-config>
The expression ${jms.connection.parameters:'host=10.10.64.1;port=5445'} allows the connection parameters to be overridden by a command-line supplied parameter, while providing a default value.
Report a bug

2.4.4. Enabling or Disabling Descriptor Based Property Replacement

Summary

Finite control over descriptor property replacement was introduced in jboss-as-ee_1_1.xsd. This task covers the steps required to configure descriptor based property replacement.

Prerequisites

Descriptor based property replacement flags have boolean values:
  • When set to true, property replacements are enabled.
  • When set to false, property replacements are disabled.

Procedure 2.14. jboss-descriptor-property-replacement

jboss-descriptor-property-replacement is used to enable or disable property replacement in the following descriptors:
  • jboss-ejb3.xml
  • jboss-app.xml
  • jboss-web.xml
  • *-jms.xml
  • *-ds.xml
The default value for jboss-descriptor-property-replacement is true.
  1. In the Management CLI, run the following command to determine the value of jboss-descriptor-property-replacement: 
    /subsystem=ee:read-attribute(name="jboss-descriptor-property-replacement")
  2. Run the following command to configure the behavior: 
    /subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)

Procedure 2.15. spec-descriptor-property-replacement

spec-descriptor-property-replacement is used to enable or disable property replacement in the following descriptors:
  • ejb-jar.xml
  • persistence.xml
  • application.xml
  • web.xml
The default value for spec-descriptor-property-replacement is false.
  1. In the Management CLI, run the following command to confirm the value of spec-descriptor-property-replacement: 
    /subsystem=ee:read-attribute(name="spec-descriptor-property-replacement")
  2. Run the following command to configure the behavior: 
    /subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)
Result

The descriptor based property replacement tags have been successfully configured.

Report a bug

2.4.5. Nested Expressions

Expressions may be nested, which allows for more advanced use of expressions in place of fixed values. The format of a nested expression is like that of a normal expression, but one expression is embedded in the other, for example:

Example 2.12. Nested expression

${system_value_1${system_value_2}}
Nested expressions are evaluated recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Nested expressions are permitted anywhere that expressions are permitted, with the exception of Management CLI commands.
As for normal expressions, the supported sources for resolving nested expressions are: system properties, environment variables and the Vault. For deployments only, the source can be properties listed in a META-INF/jboss.properties file in the deployment archive. In an EAR or other deployment type that supports subdeployments, the resolution is scoped to all subdeployments if the META-INF/jboss.properties is in the outer deployment (e.g. the EAR) and is scoped to a subdeployment if META-INF/jboss.properties is in the subdeployment archive (e.g. a WAR inside an EAR.)

Example 2.13.  Use a Nested Expression in a Configuration File

A real-life application of a nested expression is in a datasource definition. If the password used in a datasource definition is masked, the resulting line in the datasource definition might be as follows: 
<password>${VAULT::ds_ExampleDS::password::1}</password>
Using a nested expression, the value of ds_ExampleDS could be replaced with a system property. If a system property datasource_name is assigned the value ds_ExampleDS, the line in the datasource definition could instead be as follows: 
<password>${VAULT::${datasource_name}::password::1}</password>
JBoss EAP would first evaluate the expression ${datasource_name}, then input this to the larger expression and evaluate the resulting expression. The advantage of this configuration is that the name of the datasource is abstracted from the fixed configuration.
Expressions may also be recursive, where an expressions resolves to an expression which is then resolved. Nested expressions and recursive expressions are a form of indirection. Note that recursive expressions are not permitted in Management CLI commands.

Example 2.14.  Recursive Expression

Continuing the previous example, you might use the expression ${foo} which resolves to the expression ${VAULT::ds_ExampleDS::password::1}, which then resolves to a value contained in the Vault: secret.
Report a bug

2.4.6. Configuration File History

The application server configuration files include standalone.xml, as well as the domain.xml and host.xml files. While these files may be modified by direct editing, the recommended method is to configure the application server model with the available management operations, including the Management CLI and the Management Console.
To assist in the maintenance and management of the server instance, the application server creates a timestamped version of the original configuration file at the time of startup. Any additional configuration changes made by management operations result in the original file being automatically backed up, and a working copy of the instance being preserved for reference and rollback. This archival functionality extends to saving, loading and deleting snapshots of the server configuration to allow for recall and rollback scenarios.
Report a bug

2.4.7. Start the Server with a Previous Configuration

The following example shows how to start the application server with a previous configuration in a standalone server with standalone.xml. The same concept applies to a managed domain with domain.xml and host.xml respectively.
This example recalls a previous configuration saved automatically by the application server as management operations modify the server model.

Example 2.15. Start the server with a saved configuration

  1. Identify the backed up version that you want to start. This example will recall the instance of the server model prior to the first modification after successfully booting up. 
    EAP_HOME/standalone/configuration/standalone_xml_history/current/standalone.v1.xml
  2. Start the server with this configuration of the backed up model by passing in the relative filename under jboss.server.config.dir. 
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/current/standalone.v1.xml
Result

The application server starts with the selected configuration.

Note

The domain configuration history is located in EAP_HOME/domain/configuration/domain_xml_history/current/domain.v1.xml
Start the server with this configuration of the backed up model by passing the relative filename under jboss.domain.config.dir.
To start the domain with this configuration: 
EAP_HOME/bin/domain.sh --domain-config=domain_xml_history/current/domain.v1.xml
Report a bug

2.4.8. Save a Configuration Snapshot Using the Management CLI

Summary

Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator.

The following example uses the standalone.xml configuration file, but the same process applies to the domain.xml and host.xml configuration files.

Prerequisites

Procedure 2.16. Take a Configuration Snapshot and Save It

  • Save a snapshot

    Run the take-snapshot operation to capture a copy of the current server configuration. 
    [standalone@localhost:9999 /] :take-snapshot
{
    "outcome" => "success",
    "result" => "/home/User/EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-172258657standalone.xml"
Result

A snapshot of the current server configuration has been saved.

Report a bug

2.4.9. Load a Configuration Snapshot Using the Management CLI

Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator. The process of loading snapshots is similar to the method used to Section 2.4.7, “Start the Server with a Previous Configuration”, running from the command line rather than the Management CLI interface used to create, list and delete snapshots.
The following example uses the standalone.xml file, but the same process applies to the domain.xml and host.xml files.

Procedure 2.17. Load a Configuration Snapshot

  1. Identify the snapshot to be loaded. This example will recall the following file from the snapshot directory. The default path for the snapshot files is as follows. 
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110812-191301472standalone.xml
    The snapshots are expressed by their relative paths, by which the above example can be written as follows. 
    jboss.server.config.dir/standalone_xml_history/snapshot/20110812-191301472standalone.xml
  2. Start the server with the selected configuration snapshot by passing in the filename. 
    EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20110913-164449522standalone.xml
Result

The server restarts with the configuration selected in the loaded snapshot.

Report a bug

2.4.10. Delete a Configuration Snapshot Using Management CLI

Prerequisites

Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator.
The following examples use the standalone.xml file, but the same process applies to the domain.xml and host.xml files.

Procedure 2.18. Delete a Specific Snapshot

  1. Identify the snapshot to be deleted. This example will delete the following file from the snapshot directory. 
    EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20110630-165714239standalone.xml
  2. Run the :delete-snapshot command to delete a specific snapshot, specifying the name of the snapshot as in the example below. 
    [standalone@localhost:9999 /] :delete-snapshot(name="20110630-165714239standalone.xml")
{"outcome" => "success"}
Result

The snapshot has been deleted.

Procedure 2.19. Delete All Snapshots

  • Run the :delete-snapshot(name="all") command to delete all snapshots as in the example below. 
    [standalone@localhost:9999 /] :delete-snapshot(name="all")
{"outcome" => "success"}
Result

All snapshots have been deleted.

Report a bug

2.4.11. List All Configuration Snapshots Using Management CLI

Prerequisites

Configuration snapshots are a point-in-time copy of the current server configuration. These copies can be saved and loaded by the administrator.
The following example uses the standalone.xml file, but the same process applies to the domain.xml and host.xml files.

Procedure 2.20. List All Configuration Snapshots

  • List all snapshots

    List all of the saved snapshots by running the :list-snapshots command. 
    [standalone@localhost:9999 /] :list-snapshots
{
    "outcome" => "success",
    "result" => {
        "directory" => "/home/hostname/EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
        "names" => [
            "20110818-133719699standalone.xml",
            "20110809-141225039standalone.xml",
            "20110802-152010683standalone.xml",
            "20110808-161118457standalone.xml",
            "20110912-151949212standalone.xml",
            "20110804-162951670standalone.xml"
        ]
    }
}
Result

The snapshots are listed.

Report a bug