Chapter 3. JBoss EAP Management
JBoss EAP uses a simplified configuration, with one configuration file per standalone server or managed domain. Default configuration for a standalone server is stored in the EAP_HOME/standalone/configuration/standalone.xml
file and default configuration for a managed domain is stored in the EAP_HOME/domain/configuration/domain.xml
file. Additionally, the default configuration for a host controller is stored in the EAP_HOME/domain/configuration/host.xml
file.
JBoss EAP can be configured using the command-line management CLI, web-based management console, Java API, or HTTP API. Changes made using these management interfaces persist automatically, and the XML configuration files are overwritten by the Management API. The management CLI and management console are the preferred methods, and it is not recommended to edit the XML configuration files manually.
JBoss EAP supports the modification of XML configuration for standalone servers using YAML files. For more information, see Update standalone server configuration using YAML files.
YAML configuration is not supported for servers in a managed domain.
3.1. About Subsystems, Extensions, and Profiles
Different aspects of JBoss EAP functionality are configured in different subsystems. For example, application and server logging are configured in the logging
subsystem.
An extension is a module that extends the core functionality of the server. Extensions are loaded as they are needed by deployments, and are unloaded when they are no longer needed. See the JBoss EAP Management CLI Guide for how to add and remove extensions.
A subsystem provides configuration options for a particular extension. For more information on the available subsystems, see Overview of JBoss EAP Subsystems.
A collection of subsystem configurations makes up a profile, which is configured to satisfy the needs for the server. A standalone server has a single, unnamed profile. A managed domain can define many profiles for use by server groups in the domain.
Using the Management Console or the Management CLI
Both the management console and the management CLI are valid, supported ways of updating the configuration of a JBoss EAP instance. Deciding between the two is a matter of preference. Those who prefer to use a graphical, web-based interface should use the management console. Those who prefer a command-line interface should use the management CLI.
3.2. Management Users
The default JBoss EAP configuration provides local authentication so that a user can access the management CLI on the local host without requiring authentication.
However, you must add a management user if you want to access the management CLI remotely or use the management console, which is considered remote access even if the traffic originates on the local host. If you attempt to access the management console before adding a management user, you will receive an error message.
If JBoss EAP is installed using the graphical installer, then a management user is created during the installation process.
This guide covers simple user management for JBoss EAP using the add-user
script, which is a utility for adding new users to the properties files for out-of-the-box authentication.
For more advanced authentication and authorization options, such as LDAP or Role-Based Access Control (RBAC), see the Core Management Authentication section of the JBoss EAP Security Architecture.
3.2.1. Adding a Management User
Run the
add-user
utility script and follow the prompts.$ EAP_HOME/bin/add-user.sh
NoteFor Windows Server, use the
EAP_HOME\bin\add-user.bat
script.Press
ENTER
to select the default optiona
to add a management user.This user will be added to the ManagementRealm and will be authorized to perform management operations using the management console or management CLI. The other choice,
b
, adds a user to the ApplicationRealm, which is used for applications and provides no particular permissions.Enter the desired username and password. You will be prompted to confirm the password.
NoteUser names can only contain the following characters, in any number and in any order:
- Alphanumeric characters (a-z, A-Z, 0-9)
- Dashes (-), periods (.), commas (,), at sign (@)
- Backslash (\)
- Equals (=)
By default, JBoss EAP allows weak passwords but will issue a warning.
See Setting Add-User Utility Password Restrictions for details on changing this default behavior.
-
Enter a comma-separated list of groups to which the user belongs. If you do not want the user to belong to any groups, press
ENTER
to leave it blank. -
Review the information and enter
yes
to confirm. Determine whether this user represents a remote JBoss EAP server instance. For a basic management user, enter
no
.One type of user that may need to be added to the ManagementRealm is a user representing another instance of JBoss EAP, which must be able to authenticate to join as a member of a cluster. If this is the case, then answer
yes
to this prompt and you will be given a hashed secret value representing the user’s password, which will need to be added to a different configuration file.
Users can also be created non-interactively by passing parameters to the add-user
script. This approach is not recommended on shared systems, because the passwords will be visible in log and history files. For more information, see Running the Add-User Utility Non-Interactively.
3.2.2. Running the Add-User Utility Non-Interactively
You can run the add-user
script non-interactively by passing in arguments on the command line. At a minimum, the username and password must be provided.
This approach is not recommended on shared systems, because the passwords will be visible in log and history files.
Create a User Belonging to Multiple Groups
The following command adds a management user, mgmtuser1
, with the guest
and mgmtgroup
groups.
$ EAP_HOME/bin/add-user.sh -u 'mgmtuser1' -p 'password1!' -g 'guest,mgmtgroup'
Specify an Alternative Properties File
By default, user and group information created using the add-user
script are stored in properties files located in the server configuration directory.
User information is stored in the following properties files:
-
EAP_HOME/standalone/configuration/mgmt-users.properties
-
EAP_HOME/domain/configuration/mgmt-users.properties
Group information is stored in the following properties files:
-
EAP_HOME/standalone/configuration/mgmt-groups.properties
-
EAP_HOME/domain/configuration/mgmt-groups.properties
These default directories and properties file names can be overridden. The following command adds a new user, specifying a different name and location for the user properties files.
$ EAP_HOME/bin/add-user.sh -u 'mgmtuser2' -p 'password1!' -sc '/path/to/standaloneconfig/' -dc '/path/to/domainconfig/' -up 'newname.properties'
The new user was added to the user properties files located at /path/to/standaloneconfig/newname.properties
and /path/to/domainconfig/newname.properties
. Note that these files must already exist or you will see an error.
For a complete listing of all available add-user
arguments and their purposes, use the --help
argument or see the Add-user arguments section.
3.2.3. Add-User Utility Password Restrictions
The password restrictions for the add-user
utility script can be configured using the EAP_HOME/bin/add-user.properties
file.
The add-user.properties
file is an unprotected plain-text file and must be secured to avoid unwarranted access to its contents.
To avoid setting an unintentional password, check that your keyboard’s system keymap is correct. The default system keymap is en-qwerty
. If you change this default setting and create a new password, you must check that the password meets the criteria located in the class SimplePasswordStrengthChecker
.
By default, JBoss EAP allows weak passwords but issues a warning. To reject passwords that do not meet the minimum requirements specified, set the password.restriction
property to REJECT
.
The following table describes the additional password requirement settings that can be configured in the EAP_HOME/bin/add-user.properties
file:
Attribute | Description |
---|---|
|
The minimum number of characters for a password. For example, |
| Sets the threshold that a password must meet to be valid. Valid threshold entries include:
*
*
*
*
*
*
*
The default value is
NOTE: If you do not specify a threshold value, |
|
The minimum number of alphabetic characters set for a password. For example, |
|
The minimum number of numeric characters set for a password. For example, |
|
The minimum number of symbols set for a password. For example, |
|
Restricts a user from setting an easily determined password, such as root. For example, |
|
Restricts the user from setting their user name as the password. For example, |
Additional Resources
See the Configuring Basic System Settings guide on the Red Hat Customer Portal.
3.2.4. Updating a Management User
You can update the settings for an existing management user using the add-user
utility script by entering the username when prompted.
$ EAP_HOME/bin/add-user.sh
What type of user do you wish to add?
a) Management User (mgmt-users.properties)
b) Application User (application-users.properties)
(a): a
Enter the details of the new user to add.
Using realm 'ManagementRealm' as discovered from the existing property files.
Username : test-user
User 'test-user' already exists and is enabled, would you like to...
a) Update the existing user password and roles
b) Disable the existing user
c) Type a new username
(a):
When you enter a username that already exists, you are presented with several options:
-
Type
a
to update the password for the existing user. -
Type
b
to disable the existing user. -
Type
c
to enter a new username.
When updating a user using the add-user
script non-interactively, the user is updated automatically with no confirmation prompt.
3.3. Optimizing the JBoss EAP Server Configuration
Once you have installed the JBoss EAP server, and you have created a management user, you can optimize your server configuration.
Make sure you review information in the Performance Tuning Guide for information about how to optimize the server configuration to avoid common problems when deploying applications in a production environment. Common optimizations include setting ulimits, enabling garbage collection, creating Java heap dumps, and adjusting the thread pool size.
It is also a good idea to apply any existing patches for your release of the product. Each patch for EAP contains numerous bug fixes. For more information, see Patching JBoss EAP in the Patching and Upgrading Guide for JBoss EAP.
3.4. Management Interfaces
3.4.1. Management CLI
The management command-line interface (CLI) is a command-line administration tool for JBoss EAP.
Use the management CLI to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch mode, allowing multiple tasks to be run as a group.
Many common terminal commands are available, such as ls
, cd
, and pwd
. The management CLI also supports tab completion.
For detailed information on using the management CLI, including commands and operations, syntax, and running in batch mode, see the JBoss EAP Management CLI Guide.
Launch the Management CLI
$ EAP_HOME/bin/jboss-cli.sh
For Windows Server, use the EAP_HOME\bin\jboss-cli.bat
script.
Connect to a Running Server
connect
Or you can launch the management CLI and connect in one step by using the EAP_HOME/bin/jboss-cli.sh --connect
command.
Display Help
Use the following command for general help.
help
Use the --help
flag on a command to receive instructions on using that specific command. For instance, to receive information on using deploy
, the following command is executed.
deploy --help
Quit the Management CLI
quit
View System Settings
The following command uses the read-attribute
operation to display whether the example datasource is enabled.
/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled) { "outcome" => "success", "result" => true }
When running in a managed domain, you must specify which profile to update by preceding the command with /profile=PROFILE_NAME
.
/profile=default/subsystem=datasources/data-source=ExampleDS:read-attribute(name=enabled)
Update System Settings
The following command uses the write-attribute
operation to disable the example datasource.
/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled,value=false)
Start Servers
The management CLI can also be used to start and stop servers when running in a managed domain.
/host=HOST_NAME/server-config=server-one:start
3.4.2. Management Console
The management console is a web-based administration tool for JBoss EAP.
Use the management console to start and stop servers, deploy and undeploy applications, tune system settings, and make persistent modifications to the server configuration. The management console also has the ability to perform administrative tasks, with live notifications when any changes performed by the current user require the server instance to be restarted or reloaded.
In a managed domain, server instances and server groups in the same domain can be centrally managed from the management console of the domain controller.
For a JBoss EAP instance running on the local host using the default management port, the management console can be accessed through a web browser at http://localhost:9990/console/index.html. You will need to authenticate with a user that has permissions to access the management console.
The management console provides the following tabs for navigating and managing your JBoss EAP standalone server or managed domain.
- Home
- Learn how to accomplish several common configuration and management tasks. Take a tour to become familiar with the JBoss EAP management console.
- Deployments
- Add, remove, and enable deployments. In a managed domain, assign deployments to server groups.
- Configuration
- Configure available subsystems, which provide capabilities such as web services, messaging, or high availability. In a managed domain, manage the profiles that contain different subsystem configurations.
- Runtime
- View runtime information, such as server status, JVM usage, and server logs. In a managed domain, manage your hosts, server groups, and servers.
- Patching
- Apply patches to your JBoss EAP instances.
- Access Control
- Assign roles to users and groups when using Role-Based Access Control.
3.4.2.1. Updating Attributes in the Management Console
Once you have navigated to the appropriate section of the management console for the resource that you want to modify, you can edit its attributes as long as you have the proper permissions.
- Click the Edit link.
Make the desired changes.
Required fields are marked with an asterisk (*). You can view attribute descriptions by clicking the Help link.
NoteDepending on the attribute type, the input field can be a text field, ON/OFF field, or drop down. In some text fields, as you type, values from elsewhere in the configuration may appear as suggestions.
- Click Save to save the changes.
If necessary, reload the server for the changes to take effect.
A popup appears when saving changes that require a reload in order to take effect. To reload a standalone server, click the Reload link in the popup. To reload a server in a managed domain, click the Topology link, select the appropriate server, and click the Reload drop down option.
To view the history of recent configuration actions you have performed, click the notification icon in the top-right of the management console.
3.4.2.2. Enable/Disable Management Console
You can enable or disable the management console by setting the console-enabled
boolean attribute of the /core-service=management/management-interface=http-interface
resource. For the master host in domain mode, use /host=master/core-service=management/management-interface=http-interface
.
For example, to enable:
/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=true)
For example, to disable:
/core-service=management/management-interface=http-interface:write-attribute(name=console-enabled,value=false)
3.4.2.3. Change the Language of the Management Console
By default, the language settings of the management console is English. You can choose to use one of the following languages instead:
- German (de)
- Simplified Chinese (zh-Hans)
- Brazilian Portuguese (pt-BR)
- French (fr)
- Spanish (es)
- Japanese (ja)
To Change the Language of the Management Console
- Log in to the management console.
- Click the Settings link in the lower-right corner of the management console.
- Select the required language from the Locale selection box.
- Select Save. A confirmation box informs you that you need to reload the application.
- Click Yes. The system refreshes your web browser automatically to use the selected locale.
3.4.2.4. Customizing the Management Console Title
You can customize the management console title so that each of your JBoss EAP instances can be identified at a quick glance.
To customize the management console title:
- Log in to the management console.
- Click Settings in the lower-right corner of the management console.
- In the Settings window, modify the title in the Title field.
Click Save.
A confirmation box informs you that you must reload the management console.
Click Yes.
The system refreshes your web browser automatically and the new title is displayed on the tab header.
3.5. Management APIs
3.5.1. HTTP API
The HTTP API endpoint is the entry point for management clients that rely on the HTTP protocol to integrate with the JBoss EAP management layer.
The HTTP API is used by the JBoss EAP management console but offers integration capabilities for other clients as well. By default, the HTTP API is accessible at http://HOST_NAME:9990/management
. This URL will display the raw attributes and values exposed to the API.
Read Resources
While you can read, write, or perform other operations using the HTTP POST
method, you can perform some read operations using a GET
request. The HTTP GET
method uses the following URL format.
http://HOST_NAME:9990/management/PATH_TO_RESOURCE?operation=OPERATION&PARAMETER=VALUE
Be sure to replace all of the replaceable values with those that are appropriate for your request. The following values are the available options for the OPERATION
replaceable value:
Value | Description |
---|---|
attribute |
Performs the |
operation-description |
Performs the |
operation-names |
Performs the |
resource |
Performs the |
resource-description |
Performs the |
snapshots |
Performs the |
The following example URLs show how to perform read operations using the HTTP API.
Example: Read All Attributes and Values for a Resource
http://HOST_NAME:9990/management/subsystem/undertow/server/default-server/http-listener/default
This displays all attributes and their values for the default
HTTP listener.
The default operation is read-resource
.
Example: Read the Value of an Attribute for a Resource
http://HOST_NAME:9990/management/subsystem/datasources/data-source/ExampleDS?operation=attribute&name=enabled
This reads the value of the enabled
attribute for the ExampleDS
datasource.
Update Resources
You can use the HTTP POST
method to update configuration values or perform other operations using the HTTP API. You must provide authentication for these operations.
The following examples show how to update resources using the HTTP API.
Example: Update the Value of an Attribute for a Resource
$ curl --digest http://HOST_NAME:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"write-attribute", "address":["subsystem","datasources","data-source","ExampleDS"], "name":"enabled", "value":"false", "json.pretty":"1"}'
This updates the value of the enabled
attribute for the ExampleDS
datasource to false
.
Example: Issue an Operation to the Server
$ curl --digest http://localhost:9990/management --header "Content-Type: application/json" -u USERNAME:PASSWORD -d '{"operation":"reload"}'
This reloads the server.
See Deploying Applications Using the HTTP API for information on how to deploy applications to JBoss EAP using the HTTP API.
3.5.1.1. Custom-constant HTTP headers
The HTTP management endpoint of JBoss EAP returns a predefined set of HTTP headers in all the responses that are sent to clients. You can define custom-constant HTTP headers to be returned in addition to this predefined set of HTTP headers.
JBoss EAP applies custom-constant HTTP headers to requests as follows:
JBoss EAP applies the custom-constant HTTP headers by matching a configured prefix against the request path.
For example, you can map custom-constant HTTP headers to requests on the request path such as
/
or/management
.If a request matches multiple prefixes, JBoss EAP applies the custom-constant HTTP headers from all of the mappings.
For example, a request to the path
/management
matches mappings for both/
and/management
. JBoss EAP applies headers from both of the mappings.At the end of processing a request, before a response returns to a client, by overriding headers set by the corresponding endpoint.
For example, the management endpoint sets an
X-Frame-Options
header in each response. If you define a custom-constant HTTP header with the nameX-Frame-Options
, the custom-constant HTTP header overrides the default header.
You can define multiple custom-constant HTTP headers to be returned in the response on a single mapping.
The following are the rules for defining custom-constant HTTP headers:
- The custom-constant HTTP headers can only contain the characters that are supported in RFC-7231 - Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content.
You cannot override the following predefined HTTP headers:
-
Connection
-
Content-Length
-
Content-Type
-
Date
-
Transfer-Encoding
Attempting to override any of these predefined headers results in an error.
For example, if you attempt to set a custom-constant HTTP header with the name
Date
, the following error is returned:{ "outcome" => "failed", "failure-description" => "WFLYCTL0458:Disallowed HTTP Header name 'Date'", "rolled-back" => true }
-
Important considerations when creating custom-constant HTTP headers:
- JBoss EAP does not verify whether the specified path is reachable.
- Subsystems can dynamically add contexts that the HTTP management interface supports.
- Custom-constant HTTP headers do not alter how an endpoint handles a response to a request.
3.5.1.2. Defining custom-constant HTTP headers
Define a custom-constant HTTP header to be returned in every response to requests on the required path prefix.
Before creating custom-constant HTTP headers, you must understand the following considerations:
- JBoss EAP does not verify whether the specified path is reachable.
- Subsystems can dynamically add contexts that the HTTP management interface supports.
- Custom-constant HTTP headers do not alter how an endpoint handles a response to a request.
Procedure
Define a custom-constant HTTP header:
/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="PATH_PREFIX",headers=[{name="HEADER_NAME",value="HEADER_VALUE"}]}])
ImportantBy using the
write-attribute
operation, you’ll receive areload-required
prompt.Reload the server for the changes to take effect:
reload
Requests to the HTTP management interface now return HTTP header HEADER_NAME with the value HEADER_VALUE in addition to the predefined set of HTTP headers.
Example custom-constant HTTP header X-Help
/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path="/",headers=[{name="X-Help",value="http://mywebsite.com/help"}]}])
Verification steps
Send a request to the HTTP management interface:
$ curl -s -D - -o /dev/null --digest http://localhost:9990/management/ -u USERNAME:PASSWORD
Sample response for the example custom-constant HTTP header
X-Help
:admin:redhat HTTP/1.1 200 OK Connection: keep-alive X-Frame-Options: SAMEORIGIN Content-Type: application/json; charset=utf-8 Content-Length: 3312 X-Help: http://mywebsite.com Date: Tue, 27 Oct 2020 08:13:17 GMT
The response contains the
X-HELP
custom-constant HTTP header.
Additional resources
3.5.1.3. CLI commands for defining custom-constant HTTP headers
The following CLI commands define custom-constant HTTP headers in standalone and managed domain modes.
- standalone mode
To define a single custom-constant HTTP header, use the following command:
/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADERVALUE}]}])
The command results in the following XML configuration:
<management-interfaces> <http-interface security-realm="ManagementRealm"> <http-upgrade enabled="true"/> <socket-binding http="management-http"/> <constant-headers> <header-mapping path="/PREFIX"> <header name="X-HEADER" value="HEADERVALUE"/> </header-mapping> </constant-headers> </http-interface> </management-interfaces>
To define multiple custom-constant HTTP headers, use the following command:
/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX1,headers=[{name=X-HEADER,value=HEADERVALUE-FOR-X}]},{path=/PREFIX2,headers=[{name=Y-HEADER,value=HEADERVALUE-FOR-Y}]}])
- domain mode
To define a single custom-constant HTTP header, use the following command:
/host=master/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[{path=/PREFIX,headers=[{name=X-HEADER,value=HEADER-VALUE}]}])
The command results in the following XML configuration:
<management-interfaces> <http-interface security-realm="ManagementRealm"> <http-upgrade enabled="true"/> <socket interface="management" port="${jboss.management.http.port:9990}"/> <constant-headers> <header-mapping path="/PREFIX"> <header name="X-HEADER" value="HEADER-VALUE"/> </header-mapping> </constant-headers> </http-interface> </management-interfaces>
To define multiple custom-constant HTTP headers, use the following command:
/host=master/core-service=management/management-interface=http-interface:write-attribute(name=constant-headers,value=[ {path=/PREFIX-1,headers=[{name=X-HEADER,value=HEADER-VALUE-FOR-X}]},{path=/PREFIX-2,headers=[{name=Y-HEADER,value=HEADER-VALUE-FOR-Y}]}])
Additional resources
3.5.2. Native API
The native API endpoint is the entry point for management clients that rely on the native protocol to integrate with the JBoss EAP management layer. The native API is used by the JBoss EAP management CLI but offers integration capabilities for other clients as well.
The following Java code shows an example of how to execute management operations from Java code using the native API.
You must add the required JBoss EAP libraries, found in the EAP_HOME/bin/client/jboss-cli-client.jar
file, to your class path.
Example: Using the Native API to Read Resources
// Create the management client ModelControllerClient client = ModelControllerClient.Factory.create("localhost", 9990); // Create the operation request ModelNode op = new ModelNode(); // Set the operation op.get("operation").set("read-resource"); // Set the address ModelNode address = op.get("address"); address.add("subsystem", "undertow"); address.add("server", "default-server"); address.add("http-listener", "default"); // Execute the operation and manipulate the result ModelNode returnVal = client.execute(op); System.out.println("Outcome: " + returnVal.get("outcome").toString()); System.out.println("Result: " + returnVal.get("result").toString()); // Close the client client.close();
3.6. Configuration Data
3.6.1. Standalone Server Configuration Files
The standalone configuration files are located in the EAP_HOME/standalone/configuration/
directory. A separate file exists for each of the five predefined profiles (default, ha, full, full-ha, load-balancer).
Configuration File | Purpose |
---|---|
| This standalone configuration file is the default configuration that is used when you start your standalone server. It contains all information about the server, including subsystems, networking, deployments, socket bindings, and other configurable details. It does not provide the subsystems necessary for messaging or high availability. |
|
This standalone configuration file includes all of the default subsystems and adds the |
|
This standalone configuration file includes all of the default subsystems and adds the |
| This standalone configuration file includes support for every possible subsystem, including those for messaging and high availability. |
| This standalone configuration file includes the minimum subsystems necessary to use the built-in mod_cluster front-end load balancer to load balance other JBoss EAP instances. |
By default, starting JBoss EAP as a standalone server uses the standalone.xml
file. To start JBoss EAP with a different configuration, use the --server-config
argument. For example,
$ EAP_HOME/bin/standalone.sh --server-config=standalone-full.xml
3.6.1.1. Update standalone server configuration using YAML files
Using YAML files to configure your standalone server externalizes the customization process and improves the rate of server upgrades. When using this feature, the server starts in read-only mode. This means that changes to the configuration do not persist after the server is restarted.
YAML configuration is not supported for servers in a managed domain.
Users can modify various resources in the YAML files. The following resources are supported in YAML files:
-
core-service
-
interface
-
socket-binding-group
-
subsystem
-
system-property
The following resources are not supported in YAML files:
-
extension
: Adds an extension to the server. This element is not supported because it might require modules that are missing. -
deployment
: Adds deployments to the server. This element is not supported because it requires more extensive changes in addition to configuration. -
deployment-overlay
: Adds deployment-overlays to the server. This element is not supported because it requires more extensive changes in addition to configuration. -
path
: Already defined when the YAML files are parsed.
The YAML root node is wildfly-configuration
. You can follow the model tree to modify resources. If a resource already exists (created by the XML configuration file or a previous YAML file), you can update it using the model tree. If the resource does not exist, you can create it using the model tree.
Example YAML configuration file defining a new PostGresql datasource
wildfly-configuration: subsystem: datasources: jdbc-driver: postgresql: driver-name: postgresql driver-xa-datasource-class-name: org.postgresql.xa.PGXADataSource driver-module-name: org.postgresql.jdbc data-source: PostgreSQLDS: enabled: true exception-sorter-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter jndi-name: java:jboss/datasources/PostgreSQLDS jta: true max-pool-size: 20 min-pool-size: 0 connection-url: "jdbc:postgresql://localhost:5432}/demo" driver-name: postgresql user-name: postgres password: postgres validate-on-match: true background-validation: false background-validation-millis: 10000 flush-strategy: FailingConnectionOnly statistics-enable: false stale-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker valid-connection-checker-class-name: org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker transaction-isolation: TRANSACTION_READ_COMMITTED
The above example defines a jdbc-driver
called postgresql and a data-source
called PostgreSQLDS.
You cannot use the YAML configuration file to manage modules. Instead, you need to create or provision the org.postgresql.jdbc
module manually or using the management CLI.
3.6.1.2. YAML file operations using tags
You can perform several operations on YAML configuration files using tags.
!undefine
: undefine an attributeUndefine
CONSOLE
logger level YAML configuration file examplewildfly-configuration: subsystem: logging: console-handler: CONSOLE: level: !undefine
!remove
: remove the resourceRemove embedded Artemis broker and connect to a remote broker YAML configuration file example
wildfly-configuration: socket-binding-group: standard-sockets: remote-destination-outbound-socket-binding: remote-artemis: host: localhost port: 61616 subsystem: messaging-activemq: server: default: !remove remote-connector: artemis: socket-binding: remote-artemis pooled-connection-factory: RemoteConnectionFactory: connectors: - artemis entries: - "java:jboss/RemoteConnectionFactory" - "java:jboss/exported/jms/RemoteConnectionFactory" enable-amq1-prefix: false user: admin password: admin ejb3: default-resource-adapter-name: RemoteConnectionFactory ee: service: default-bindings: jms-connection-factory: "java:jboss/RemoteConnectionFactory"
!list-add
: Add an element to a list (with an optional index)Add a
RemoteTransactionPermission
to a permissions list YAML configuration file examplewildfly-configuration: subsystem: elytron: permission-set: default-permissions: permissions: !list-add - class-name: org.wildfly.transaction.client.RemoteTransactionPermission module: org.wildfly.transaction.client target-name: "*" index: 0
NoteIf an
index
attribute is not defined, the entry is appended to the end of the list.
3.6.1.3. Starting a standalone server using YAML files
You can start a standalone server using YAML configuration files.
Procedure
- Open your terminal.
Use the following command to start a standalone server with YAML files:
./standalone.sh -y=/home/ehsavoie/dev/wildfly/config2.yml:config.yml -c standalone-full.xml
The
--yaml
or-y
argument allows you to pass a list of YAML files. You must separate each YAML file path using a semicolon (;) for Windows Server or a colon (:) for Mac and Unix-based operating systems. You can use an absolute path, a path relative to the current execution directory, or a path relative to the standalone configuration directory.
The operations are applied in the order that the files are defined and after the initial operations are defined by the XML configuration.
3.6.2. Managed Domain Configuration Files
The managed domain configuration files are located in the EAP_HOME/domain/configuration/
directory.
Configuration File | Purpose |
---|---|
| This is the main configuration file for a managed domain. Only the domain master reads this file. This file contains the configurations for all of the profiles (default, ha, full, full-ha, load-balancer). |
|
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 |
| This file includes only the configuration details necessary to run a server as the master domain controller. |
| This file includes only the configuration details necessary to run a server as a managed domain host controller. |
By default, starting JBoss EAP in a managed domain uses the host.xml
file. To start JBoss EAP with a different configuration, use the --host-config
argument. For example,
$ EAP_HOME/bin/domain.sh --host-config=host-master.xml
3.6.3. Backing Up Configuration Data
In order to later restore the JBoss EAP server configuration, items in the following locations should be backed up:
EAP_HOME/standalone/configuration/
- Back up the entire directory to save user data, server configuration, and logging settings for standalone servers.
EAP_HOME/domain/configuration/
- Back up the entire directory to save user and profile data, domain and host configuration, and logging settings for managed domains.
EAP_HOME/modules/
- Back up any custom modules.
EAP_HOME/welcome-content/
- Back up any custom welcome content.
EAP_HOME/bin/
- Back up any custom scripts or startup configuration files.
3.6.4. Configuration File Snapshots
To assist in the maintenance and management of the server, JBoss EAP creates a timestamped version of the original configuration file at the time of startup. Any additional configuration changes made by management operations will result in the original file being automatically backed up, and a working copy of the instance being preserved for reference and rollback. Additionally, configuration snapshots can be taken, which are point-in-time copies of the current server configuration. These snapshots can be saved and loaded by an administrator.
The following examples use the standalone.xml
file, but the same process applies to the domain.xml
and host.xml
files.
Take a Snapshot
Use the management CLI to take a snapshot of the current configurations.
:take-snapshot
{
"outcome" => "success",
"result" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot/20151022-133109702standalone.xml"
}
List Snapshots
Use the management CLI to list all snapshots that have been taken.
:list-snapshots
{
"outcome" => "success",
"result" => {
"directory" => "EAP_HOME/standalone/configuration/standalone_xml_history/snapshot",
"names" => [
"20151022-133109702standalone.xml",
"20151022-132715958standalone.xml"
]
}
}
Delete a Snapshot
Use the management CLI to delete a snapshot.
:delete-snapshot(name=20151022-133109702standalone.xml)
Start the Server with a Snapshot
The server can be started using a snapshot or an automatically-saved version of the configuration.
-
Navigate to the
EAP_HOME/standalone/configuration/standalone_xml_history
directory and identify the snapshot or saved configuration file to be loaded. Start the server and point to the selected configuration file. Pass in the file path relative to the configuration directory,
EAP_HOME/standalone/configuration/
.$ EAP_HOME/bin/standalone.sh --server-config=standalone_xml_history/snapshot/20151022-133109702standalone.xml
When running in a managed domain, use the --host-config
argument instead to specify the configuration file.
3.6.5. View Configuration Changes
JBoss EAP 7 provides the ability to track configuration changes made to the running system. This allows administrators to view a history of configuration changes made by other authorized users.
Changes are stored in memory and are not persisted between server restarts. This feature is not a replacement for management audit logging.
You can enable tracking and view configuration changes from either the management CLI or the management console.
Track and View Configuration Changes from the Management CLI
To enable tracking of configuration changes, use the following management CLI command. You can specify how many entries to store using the max-history
attribute.
/subsystem=core-management/service=configuration-changes:add(max-history=20)
In a managed domain, configuration changes are tracked at the host level for host and server-related modifications. Enabling configuration changes for a host controller enables it for all of its managed servers. You can track configuration changes per host using the following command.
/host=HOST_NAME/subsystem=core-management/service=configuration-changes:add(max-history=20)
To view the list of most recent configuration changes, use the following management CLI command.
/subsystem=core-management/service=configuration-changes:list-changes
In a managed domain, you can list the configuration changes for a host using the following command.
/host=HOST_NAME/subsystem=core-management/service=configuration-changes:list-changes
You can list the configuration changes that affect a particular server using the following command.
/host=HOST_NAME/server=SERVER_NAME/subsystem=core-management/service=configuration-changes:list-changes
This lists each configuration change made, with the date, origin, outcome, and operation details. For example, the below output from the list-changes
command shows configuration changes, with the most recent displayed first.
{ "outcome" => "success", "result" => [ { "operation-date" => "2016-02-12T18:37:00.354Z", "access-mechanism" => "NATIVE", "remote-address" => "127.0.0.1/127.0.0.1", "outcome" => "success", "operations" => [{ "address" => [], "operation" => "reload", "operation-headers" => { "caller-type" => "user", "access-mechanism" => "NATIVE" } }] }, { "operation-date" => "2016-02-12T18:34:16.859Z", "access-mechanism" => "NATIVE", "remote-address" => "127.0.0.1/127.0.0.1", "outcome" => "success", "operations" => [{ "address" => [ ("subsystem" => "datasources"), ("data-source" => "ExampleDS") ], "operation" => "write-attribute", "name" => "enabled", "value" => false, "operation-headers" => { "caller-type" => "user", "access-mechanism" => "NATIVE" } }] }, { "operation-date" => "2016-02-12T18:24:11.670Z", "access-mechanism" => "HTTP", "remote-address" => "127.0.0.1/127.0.0.1", "outcome" => "success", "operations" => [{ "operation" => "remove", "address" => [ ("subsystem" => "messaging-activemq"), ("server" => "default"), ("jms-queue" => "ExpiryQueue") ], "operation-headers" => {"access-mechanism" => "HTTP"} }] } ] }
This example lists the details of three operations performed that impacted the configuration:
- Reloading the server from the management CLI.
-
Disabling the
ExampleDS
datasource from the management CLI. -
Removing the
ExpiryQueue
queue from the management console.
Track and View Configuration Changes from the Management Console
To enable tracking of configuration changes from the management console, select to the Runtime tab, navigate to the server or host to track changes for and select Configuration Changes from the drop down. Click Enable Configuration Changes and provide a maximum history value.
The table on this page then lists each configuration change made, with the date, origin, outcome, and operation details.
3.6.6. Property Replacement
JBoss EAP allows you to use expressions to define replaceable properties in place of literal values in the configuration. Expressions use the format ${PARAMETER:DEFAULT_VALUE}
. If the specified parameter is set, then the parameter’s value will be used. Otherwise, the default value provided will be used.
The supported sources for resolving 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. For deployment types that support subdeployments, the resolution is scoped to all subdeployments if the properties file is in the outer deployment, for example the EAR. If the properties file is in the subdeployment, then the resolution is scoped just to that subdeployment.
The example below from the standalone.xml
configuration file sets the inet-address
for the public
interface to 127.0.0.1
unless the jboss.bind.address
parameter is set.
<interface name="public"> <inet-address value="${jboss.bind.address:127.0.0.1}"/> </interface>
The jboss.bind.address
parameter can be set when starting EAP as a standalone server with the following command:
$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=IP_ADDRESS
Nested Expressions
Expressions can 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:
${SYSTEM_VALUE_1${SYSTEM_VALUE_2}}
Nested expressions are evaluated recursively, so the inner expression is first evaluated, then the outer expression is evaluated. Expressions may also be recursive, where an expression resolves to another expression, which is then resolved. Nested expressions are permitted anywhere that expressions are permitted, with the exception of management CLI commands.
An example of where a nested expression might be used is if the password used in a datasource definition is masked. The configuration for the datasource might have the following line:
<password>${VAULT::ds_ExampleDS::password::1}</password>
The value of ds_ExampleDS
could be replaced with a system property (datasource_name
) using a nested expression. The configuration for the datasource could instead have the following line:
<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.
Descriptor-Based Property Replacement
Application configuration, such as datasource connection parameters, typically varies between development, testing, and production environments. This variance is sometimes accommodated by build system scripts, as the Jakarta EE specification does not contain a method to externalize these configurations. With JBoss EAP, 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.
There are several flags in the ee
subsystem that control whether property replacement is applied.
JBoss-specific descriptor replacement is controlled by the jboss-descriptor-property-replacement
flag and is enabled by default. When enabled, properties can be replaced in the following deployment descriptors:
-
jboss-ejb3.xml
-
jboss-app.xml
-
jboss-web.xml
-
jboss-permissions.xml
-
*-jms.xml
-
*-ds.xml
The following management CLI command can be used to enable or disable property replacement in JBoss-specific descriptors:
/subsystem=ee:write-attribute(name="jboss-descriptor-property-replacement",value=VALUE)
Jakarta EE descriptor replacement controlled by the spec-descriptor-property-replacement
flag and is disabled by default. When enabled, properties can be replaced in the following deployment descriptors:
-
ejb-jar.xml
-
permissions.xml
-
persistence.xml
-
application.xml
-
web.xml
The following management CLI command can be used to enable or disable property replacement in Jakarta EE descriptors:
/subsystem=ee:write-attribute(name="spec-descriptor-property-replacement",value=VALUE)
3.6.7. Using Git to Manage Configuration Data
As of JBoss EAP 7.3, you can use Git to manage and persist your server configuration data, properties files, and deployments. This not only allows you to manage the version history for these files, but it also allows you to share server and application configurations across multiple servers and nodes using one or more Git repositories. This feature only works for standalone servers that use the default configuration directory layout.
You can choose to use configuration data in a local Git repository or you can pull the data from a remote Git repository. The Git repository is configured in the jboss.server.base.dir
directory, which is the base directory for standalone server content. Once the jboss.server.base.dir
directory is configured to use Git, JBoss EAP automatically commits every update you make to the configuration using the management CLI or management console. Any changes made outside of the server by manually editing the configuration files are not committed or persisted; however, you can use the Git CLI to add and commit manual changes. You can also use the Git CLI to view the commit history, manage branching, and manage the content.
To use this feature, pass one or more of the following arguments on the command line when you start the server.
Argument | Description |
---|---|
--git-repo |
The location of the Git repository that is used to manage and persist server configuration data. This can be |
--git-branch | The branch or tag name in the Git repository to use. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches. Tag names are read-only and are normally used when you need to replicate a configuration across several nodes. |
--git-auth |
The URL to an Elytron configuration file that contains the credentials to be used when connecting to a remote Git repository. This argument is required if your remote Git repository requires authentication. This argument is not used with a |
Using a Local Git Repository
To use a local Git repository, start the server with the --git-repo=local
argument. You can also specify an optional branch or tag name in the remote repository by adding the --git-branch=GIT_BRANCH_NAME
argument when you start the server. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches.
The following is an example of a command to start the server using the 1.0.x
branch of the local
repository.
$ EAP_HOME/bin/standalone.sh --git-repo=local --git-branch=1.0.x
If you start the server with the argument to use a local
Git repository, JBoss EAP checks whether the jboss.server.base.dir
directory is already configured for Git. If not, JBoss EAP creates and initializes the Git repository in the jboss.server.base.dir
directory using the existing configuration content. JBoss EAP checks out a branch name passed by the --git-branch
argument. If that argument is not passed, it checks out the master
branch. After initialization, you should see a .git/
directory and a .gitignore
file in the base directory for standalone server content.
Using a Remote Git Repository
To use a remote Git repository, start the server with the --git-repo=REMOTE_REPO
argument. The value of the argument can be a URL or a remote alias that you have manually added to the local Git configuration.
You can also specify an optional branch or tag name in the remote repository by adding the --git-branch=GIT_BRANCH_NAME
argument when you start the server. This argument should name an existing branch or tag name as it will not be created if it does not exist. If you use a tag name, you put the repository in a detached HEAD state, meaning future commits are not attached to any branches.
If your Git repository requires authentication, you must also add the --git-auth=AUTH_FILE_URL
argument when you start the server. This argument should be the URL to an Elytron configuration file containing the credentials required to connect to the Git repository. The following is an example of an Elytron configuration file that can be used for authentication.
<?xml version="1.0" encoding="UTF-8"?> <configuration> <authentication-client xmlns="urn:elytron:client:1.2"> <authentication-rules> <rule use-configuration="test-login"> </rule> </authentication-rules> <authentication-configurations> <configuration name="test-login"> <sasl-mechanism-selector selector="BASIC" /> <set-user-name name="eap-user" /> <credentials> <clear-password password="my_api_key" /> </credentials> <set-mechanism-realm name="testRealm" /> </configuration> </authentication-configurations> </authentication-client> </configuration>
The following is an example of a command to start the server with the full profile, using the 1.0.x
branch of the remote eap-configuration
repository, and passing the URL to an Elytron configuration file containing authentication credentials.
$ EAP_HOME/bin/standalone.sh --git-repo=https://github.com/MY_GIT_ID/eap-configuration.git --git-branch=1.0.x --git-auth=file:///home/USER_NAME/github-wildfly-config.xml --server-config=standalone-full.xml
If you start the server with the argument to use a remote Git repository, JBoss EAP checks whether the jboss.server.base.dir
directory is already configured for Git. If not, JBoss EAP deletes the existing configuration files in the jboss.server.base.dir
directory and replaces them with the remote Git configuration data. JBoss EAP checks out a branch name passed by the --git-branch
argument. If that argument is not passed, it checks out the master
branch. Once this process is complete, you should see a .git/
directory and a .gitignore
file in the base directory for standalone server content.
If you later start the server passing a different --git-repo
URL or --git-branch
name than was originally used, you will see the error message java.lang.RuntimeException: WFLYSRV0268: Failed to pull the repository GIT_REPO_NAME
when you attempt to start the server. This is because JBoss EAP attempts to pull configuration data from a different repository and branch than the one that is currently configured in the jboss.server.base.dir
directory and the Git pull results in conflicts.
Using a remote Git SSH repository
For SSH authentication, you can configure an elytron configuration file by specifying SSH credentials. After you specify SSH credentials in this file, you can start your standalone server instance and have a remote Git SSH repository manage your server configuration file history.
You can also use the WildFly Elytron tool, which you can access using the elytron-tool.sh
script, to generate an SSH keypair and store it in a credential store. The WildFly Elytron tool is useful to use if you have not previously specified SSH credentials for your server.
When you add your credentials to the elytron
configuration file, you can connect to the remote Git SSH repository.
Prerequisite
-
You have added your credentials to the
elytron
configuration file. See Use a stored key pair in theelytron
configuration file and see Using OpenSSH keys in the elytron configuration file.
Procedure
Connect to the remote git SSH repository by issuing the following command in your terminal:
$ <eap_home_path>/bin/standalone.sh --git-repo=<git_repository_url> --git-auth=<elytron_configuration_file_url>
Your standalone server starts and the configuration file history of the server is now managed by the remote Git SSH repository.
Additional resources
-
For more information about generating an SSH key pair with the
elytron-tool.sh
script, see Manage key pairs in the credential store by using the WildFly Elytron tool in the How to Configure Server Security guide. -
For more information about generating and using an OpenSSH key pair, see Using OpenSSH keys in the
elytron
configuration file.
Using OpenSSH keys in the elytron
configuration file
The elytron
subsystem supports SSH key pairs generated by using the OpenSSH command-line tool. This tool uses RSA, DSA, and ECDSA algorithms.
You can generate an SSH key pair with the ssh-keygen
command.
Additionally, you can use one of three element types to specify your password:
-
clear-password
-
masked-password
-
credential-store-reference
Prerequisites
You have generated an SSH key pair. The following example shows the generation of an ECDSA key of size
256
megabytes. The passphrase is set assecret
.[~/.ssh]$ ssh-keygen -t ecdsa -b 256 Generating public/private ecdsa key pair. Enter file in which to save the key (/home/user/.ssh/id_ecdsa): Enter passphrase (empty for no passphrase): secret Enter same passphrase again: secret Your identification has been saved in /home/user/.ssh/id_ecdsa. Your public key has been saved in /home/user/.ssh/id_ecdsa.pub.
Procedure
Specify your key pair in the
elytron
configuration file by choosing one of the following two methods:Use a key pair credential to specify your key pair in the configuration file. For example:
<authentication-configurations> <configuration name="example"> <credentials> <key-pair> <openssh-private-key pem="-----BEGIN OPENSSH PRIVATE KEY----- b3BlbnNzaC1rZXktdjEAAAAACmFlczI1Ni1jdHIAAAAGYmNyeXB0AAAAGAAAABDaZzGpGV 922xmrL+bMHioPAAAAEAAAAAEAAABoAAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlz dHAyNTYAAABBBIMTU1m6pmpnSTZ2k/cbKnxXkRpXUmWwqN1SSNLpRswGsUhmLG2H21br1Z lEHRiRn6zQmA4YCtCw2hLuz8M8WVoAAADAQk+bMNWFfaI4Ej1AQdlLl6v4RDa2HGjDS3V4 39h0pOx4Ix7YZKydTN4SPkYRt78CNK0AhhtKsWo2lVNwyfh8/6SeqowhgCG9MJYW8yRR1R 3DX/eQTx6MV/gSSRLDTpcVWUY0jrBGpMaEvylKoNcabiEo44flkIYlG6E/YtFXsmXsoBsj nFcjvmfE7Lzyin5Fowwpbqj9f0XOARu9wsUzeyJVAwT7+YCU3mWJ3dnO1bOxK4TuLsxD6j RB7bJemsfr -----END OPENSSH PRIVATE KEY-----"> <clear-password password="secret"/> </openssh-private-key> </key-pair> </credentials> </configuration> </authentication-configurations>
The example shows the key pair in OpenSSH format. A passphrase of
secret
is set as aclear-password
type, and it is required to decrypt the private key.ImportantThe
elytron
subsystem supports key pairs inPKCS8
format. However, you must not encrypt key pairs in thePKCS8
format with a passphrase, because you might experience issues when you need to decrypt the key pair back to its original format.Specify the location of a file that contains your private key in the
<ssh-credential>
element of your configuration file. For example:<authentication-configurations> <configuration name="example"> <credentials> <ssh-credential ssh-directory="/user/home/example/.ssh" private-key-file="id_test_ecdsa" known-hosts-file="known_hosts_test"> 1 2 3 <clear-password password="secret"/> </ssh-credential> </credentials> </configuration> </authentication-configurations>
Additional resources
- For information about OpenSSH and its features, see the OpenSSH documentation.
Publishing Remote Configuration Data When Using Git
You can push your Git repository changes to the remote repository using the management CLI publish-configuration
operation. Because JBoss EAP pulls the configuration from the remote Git repository during the boot process when you start the server, this allows you to share the configuration data across multiple servers. You can only use this operation with a remote repository. It does not work for a local repository.
The following management CLI operation publishes the configuration data to the remote eap-configuration
repository.
:publish-configuration(location="=https://github.com/MY_GIT_ID/eap-configuration.git")
{"outcome" => "success"}
Using Snapshots with Git
In addition to using the Git commit history to track configuration changes, you can also take snapshots to preserve a configuration at a specific point in time. You can list the snapshots and delete them.
Taking Snapshots When Using Git
Snapshots are stored as tags in Git. You specify the snapshot tag name and commit message as arguments on the take-snapshot
operation.
The following management CLI operation takes a snapshot and names the tag "snapshot-01".
:take-snapshot(name="snapshot-01", comment="1st snapshot") { "outcome" => "success", "result" => "1st snapshot" }
Listing Snapshots When Using Git
You can list all of the snapshot tags using the list-snapshots
operation.
The following management CLI operation lists the snapshot tags.
:list-snapshots { "outcome" => "success", "result" => { "directory" => "", "names" => [ "snapshot : 1st snapshot", "refs/tags/snapshot-01", "snapshot2 : 2nd snapshot", "refs/tags/snapshot-02" ] } }
Deleting Snapshots When Using Git
You can delete a specific snapshot by passing the tag name on the delete-snapshot
operation.
The following management CLI operation deletes the snapshot with the tag name "snapshot-01".
:delete-snapshot(name="snapshot-01") {"outcome" => "success"}
3.7. File System Paths
JBoss EAP uses logical names for file system paths. Other areas of the configuration can then reference the paths using their logical name, avoiding the need to use absolute paths for each instance and allowing specific host configurations to resolve to universal logical names.
For example, the default logging
subsystem configuration declares jboss.server.log.dir
as the logical name for the server log directory.
Example: Relative Path Example for the Server Log Directory
<file relative-to="jboss.server.log.dir" path="server.log"/>
JBoss EAP automatically provides a number of standard paths without any need for the user to configure them in a configuration file.
Property | Description |
---|---|
java.home | The Java installation directory |
jboss.controller.temp.dir |
A common alias for standalone servers and managed domains. The directory to be used for temporary file storage. Equivalent to |
jboss.domain.base.dir | The base directory for domain content. |
jboss.domain.config.dir | The directory that contains the domain configuration. |
jboss.domain.data.dir | The directory that the domain will use for persistent data file storage. |
jboss.domain.log.dir | The directory that the domain will use for persistent log file storage. |
jboss.domain.temp.dir | The directory that the domain will use for temporary file storage. |
jboss.domain.deployment.dir | The directory that the domain will use for storing deployed content. |
jboss.domain.servers.dir | The directory that the domain will use for storing outputs of the managed domain instances. |
jboss.home.dir | The root directory of the JBoss EAP distribution. |
jboss.server.base.dir | The base directory for standalone server content. |
jboss.server.config.dir | The directory that contains the standalone server configuration. |
jboss.server.data.dir | The directory the standalone server will use for persistent data file storage. |
jboss.server.log.dir | The directory the standalone server will use for log file storage. |
jboss.server.temp.dir | The directory the standalone server will use for temporary file storage. |
jboss.server.deploy.dir | The directory that the standalone server will use for storing deployed content. |
user.dir | The user’s current working directory. |
user.home | The user home directory. |
You can override a standard path or add a custom path.
3.7.1. View File System Paths
Use the following management CLI command to list the file system paths:
ls /path
In a managed domain, you can list the file system paths for a specific server using the following management CLI command:
ls /host=HOST_NAME/server=SERVER_NAME/path
Use the following management CLI command to read the value of a file system path:
/path=PATH_NAME:read-resource
In a managed domain, you can read the value of a file system path for a specific server using the following management CLI command:
/host=HOST_NAME/server=SERVER_NAME/path=PATH_NAME:read-resource
3.7.2. Override a Standard Path
You can override the default locations of the standard paths that begin with jboss.server.*
or jboss.domain.*
. This can be done in one of two ways:
Pass in the command-line argument when you start the server. For example:
$ EAP_HOME/bin/standalone.sh -Djboss.server.log.dir=/var/log
Modify the
JAVA_OPTS
variable in the server configuration file, eitherstandalone.conf
ordomain.conf
, to contain the new location. For example:JAVA_OPTS="$JAVA_OPTS -Djboss.server.log.dir=/var/log"
Overriding a Managed Domain’s Standard Paths
In this example, the objective is to store domain files in the /opt/jboss_eap/domain_data
directory, and give each top-level directory a custom name. The default directory grouping, by-server
, is used.
-
Log files are to be stored in the
all_logs
subdirectory -
Data files are to be stored in the
all_data
subdirectory -
Temporary files are to be stored in the
all_temp
subdirectory -
Servers' files are to be stored in the
all_servers
subdirectory
To achieve this configuration, you would override several system properties when starting JBoss EAP.
$ EAP_HOME/bin/domain.sh -Djboss.domain.temp.dir=/opt/jboss_eap/domain_data/all_temp -Djboss.domain.log.dir=/opt/jboss_eap/domain_data/all_logs -Djboss.domain.data.dir=/opt/jboss_eap/domain_data/all_data -Djboss.domain.servers.dir=/opt/jboss_eap/domain_data/all_servers
The resulting path structure will be as follows:
/opt/jboss_eap/domain_data/ ├── all_data ├── all_logs ├── all_servers │ ├── server-one │ │ ├── data │ │ ├── log │ │ └── tmp │ └── server-two │ ├── data │ ├── log │ └── tmp └── all_temp
3.7.3. Add a Custom Path
You can add a custom file system path using the management CLI or the management console.
From the management CLI, you can add a new path using the following management CLI command.
/path=my.custom.path:add(path=/my/custom/path)
- From the management console, you can configure file system paths by navigating to the Configuration tab, selecting Paths, and clicking View. From there, you can add, modify, and remove paths.
You can then use this custom path in your configuration. For example, the below log handler uses a custom path for its relative path.
<subsystem xmlns="urn:jboss:domain:logging:6.0"> ... <periodic-rotating-file-handler name="FILE" autoflush="true"> <formatter> <named-formatter name="PATTERN"/> </formatter> <file relative-to="my.custom.path" path="server.log"/> <suffix value=".yyyy-MM-dd"/> <append value="true"/> </periodic-rotating-file-handler> ... </subsystem>
3.8. Directory Grouping
In a managed domain, each server’s files are stored in the EAP_HOME/domain
directory. You can specify how to organize the subdirectories for servers using the host controller’s directory-grouping
attribute. Directories can be grouped either by server or by type. By default, directories are grouped by server.
Directory Grouping by Server
By default, directories are grouped by server. If your administration is server-centric, this configuration is recommended. For example, it allows backups and log file handling to be configured per server instance.
If JBoss EAP is installed using the ZIP installation method, the default directory structure (grouped by server) will be as follows.
EAP_HOME/domain
└─ servers
├── server-one
│ ├── data
│ ├── tmp
│ └── log
└── server-two
├── data
├── tmp
└── log
To group domain directories by server, enter the following management CLI command:
/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-server)
This will update the host controller’s host.xml
configuration file:
<servers directory-grouping="by-server"> <server name="server-one" group="main-server-group"/> <server name="server-two" group="main-server-group" auto-start="true"> <socket-bindings port-offset="150"/> </server> </servers>
Directory Grouping by Type
Instead of grouping directories by server, you can instead group by file type. If your administration is file type-centric, this configuration is recommended. For example, this would allow you to easily back up only data
files.
If JBoss EAP is installed using the ZIP installation method and the domain’s files are grouped by type, the directory structure will be as follows.
EAP_HOME/domain
├── data
│ └── servers
│ ├── server-one
│ └── server-two
├── log
│ └── servers
│ ├── server-one
│ └── server-two
└── tmp
└── servers
├── server-one
└── server-two
To group domain directories by type, enter the following management CLI command:
/host=HOST_NAME:write-attribute(name=directory-grouping,value=by-type)
This will update the host controller’s host.xml
configuration file:
<servers directory-grouping="by-type"> <server name="server-one" group="main-server-group"/> <server name="server-two" group="main-server-group" auto-start="true"> <socket-bindings port-offset="150"/> </server> </servers>
3.9. System Properties
You can use Java system properties to configure many JBoss EAP options, as well as set any name-value pair for use within the application server.
System properties can be used to override default values in the JBoss EAP configuration. For example, the following XML configuration for the public interface bind address shows that it can be set by the jboss.bind.address
system property, but if the system property is not provided, it will default to 127.0.0.1
.
<inet-address value="${jboss.bind.address:127.0.0.1}"/>
There are a few ways you can set system properties in JBoss EAP, including:
If you use a JBoss EAP managed domain, system properties can be applied to either the whole domain, a specific server group, a specific host and all its server instances, or just to one specific server instance. As with most other JBoss EAP domain settings, a system property set at a more specific level will override a more abstract one. See the Domain Management chapter for more information.
Passing a System Property to the Startup Script
You can pass a system property to the JBoss EAP startup script by using the -D
argument. For example:
$ EAP_HOME/bin/standalone.sh -Djboss.bind.address=192.168.1.2
This method of setting the system property is especially useful for JBoss EAP options that need to be set before JBoss EAP starts.
Setting a System Property Using the Management CLI
Using the management CLI, you can set a system property using the following syntax:
/system-property=PROPERTY_NAME:add(value=PROPERTY_VALUE)
For example:
/system-property=jboss.bind.address:add(value=192.168.1.2)
When setting system properties using the management CLI, some JBoss EAP options, including the above example of jboss.bind.address
, will only take effect after the next server restart.
For a managed domain, the above example configures a system property for the entire domain, but you can also set or override system properties at more specific levels of the domain configuration.
Setting a System Property Using the Management Console
- For a standalone JBoss EAP server, you can configure system properties in the management console under the Configuration tab. Select System Properties, and click the View button.
For a managed domain:
- Domain-level system properties can be set in the Configuration tab. Select System Properties, and click the View button.
- Server group and server-level system properties can be set in the Runtime tab. Select the server group or server you want to configure, click the View button next to the server group or server name, and select the System Properties tab.
- Host-level system properties can be set in the Runtime tab. Select the host you want to configure, then using the drop-down menu next to the host name, select Properties.
Setting a System Property Using JAVA_OPTS
System properties can also be configured using the JAVA_OPTS
environment variable. There are many ways to modify JAVA_OPTS
, but JBoss EAP provides a configuration file for setting JAVA_OPTS
that is used by the JBoss EAP process.
For a standalone server, this file is EAP_HOME/bin/standalone.conf
, or, for a managed domain, it is EAP_HOME/bin/domain.conf
. For Microsoft Windows systems these files have a .bat
extension.
For an RPM installation, the RPM service configuration file is the preferred location to modify JAVA_OPTS
to configure system properties. For more information, see Configure RPM Service Properties.
Add your system property definition to JAVA_OPTS
in the relevant configuration file. The examples below demonstrate setting the bind address on a Red Hat Enterprise Linux system.
For
standalone.conf
, add yourJAVA_OPTS
system property definition at the end of the file. For example:... # Set the bind address JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2"
For
domain.conf
,JAVA_OPTS
must be set before the process controllerJAVA_OPTS
setting. For example:... # Set the bind address JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=192.168.1.2" # The ProcessController process uses its own set of java options if [ "x$PROCESS_CONTROLLER_JAVA_OPTS" = "x" ]; then ...
Add Java Agents using MODULE_OPTS environment variable
You can use the MODULE_OPTS=-javaagent:my-agent.jar
environment variable to add Java agents to JBoss Modules directly without editing the startup script. This initializes your agent after you configure logging. Previously, the log manager was required on the boot class path.
In a standalone server, you can set the MODULE_OPTS
environment variable in the following files:
-
On RHEL, the startup script uses
EAP_HOME/bin/standalone.conf
file. -
On your Windows server, at the command prompt, use the
EAP_HOME\bin\standalone.bat
file. -
On your Windows server, at the PowerShell, use the
EAP_HOME\bin\standalone.ps1
file.
For servers in a domain, you can add the module-options
attribute to a host JVM configuration or a server JVM configuration.
3.10. Management Audit Logging
You can enable audit logging for the management interfaces, which will log all operations performed using the management console, management CLI, or custom application that uses the Management API. Audit log entries are stored in JSON format. By default, audit logging is disabled.
You can configure audit logging to output to a file or to a syslog server.
Login and logout events cannot be audited as there is no authenticated session in JBoss EAP. Instead, audit messages are logged when an operation is received from the user.
Standalone Server Audit Logging
Though disabled by default, the default audit logging configuration writes to a file.
<audit-log> <formatters> <json-formatter name="json-formatter"/> </formatters> <handlers> <file-handler name="file" formatter="json-formatter" path="audit-log.log" relative-to="jboss.server.data.dir"/> </handlers> <logger log-boot="true" log-read-only="false" enabled="false"> <handlers> <handler name="file"/> </handlers> </logger> </audit-log>
This configuration can be read using the following management CLI command.
/core-service=management/access=audit:read-resource(recursive=true)
See Enable Audit Logging to enable audit logging for a standalone server.
Managed Domain Audit Logging
Though disabled by default, the default audit logging configuration writes a file for each host and for each server.
<audit-log> <formatters> <json-formatter name="json-formatter"/> </formatters> <handlers> <file-handler name="host-file" formatter="json-formatter" relative-to="jboss.domain.data.dir" path="audit-log.log"/> <file-handler name="server-file" formatter="json-formatter" relative-to="jboss.server.data.dir" path="audit-log.log"/> </handlers> <logger log-boot="true" log-read-only="false" enabled="false"> <handlers> <handler name="host-file"/> </handlers> </logger> <server-logger log-boot="true" log-read-only="false" enabled="false"> <handlers> <handler name="server-file"/> </handlers> </server-logger> </audit-log>
This configuration can be read using the following management CLI command.
/host=HOST_NAME/core-service=management/access=audit:read-resource(recursive=true)
See Enable Audit Logging to enable audit logging for a managed domain.
3.10.1. Enable Management Audit Logging
JBoss EAP is preconfigured with file handlers for audit logging, though audit logging is disabled by default. The management CLI command to enable audit logging depends on whether you are running as a standalone server or in a managed domain. See Management Audit Logging Attributes for file handler attributes.
The following instructions enable NATIVE
and HTTP
audit logging. To configure Jakarta Management audit logging, see Enable Jakarta Management Management Audit Logging.
To set up syslog audit logging, see Send Management Audit Logging to a Syslog Server.
Enable Standalone Server Audit Logging
Audit logging can be enabled using the following command.
/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
By default, this will write the audit log to EAP_HOME/standalone/data/audit-log.log
.
Enable Managed Domain Audit Logging
The default audit logging configuration for a managed domain is preconfigured to write an audit log for each host and each server.
Audit logging for each host can be enabled using the following command.
/host=HOST_NAME/core-service=management/access=audit/logger=audit-log:write-attribute(name=enabled,value=true)
By default, this will write the audit logs to EAP_HOME/domain/data/audit-log.log
.
Audit logging for each server can be enabled using the following command.
/host=HOST_NAME/core-service=management/access=audit/server-logger=audit-log:write-attribute(name=enabled,value=true)
By default, this will write the audit logs to EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log
.
3.10.2. Enable Jakarta Management Management Audit Logging
JBoss EAP is preconfigured with file handlers for Jakarta Management audit logging, though these logs are disabled by default. The management CLI command to enable audit logging depends on whether you are running as a standalone server or a managed domain.
To configure NATIVE
or HTTP
audit logging, see Enable Management Audit Logging.
Enable Standalone Server Jakarta Management Audit Logging
Jakarta Management audit logging can be enabled for a standalone server using the following commands.
/subsystem=jmx/configuration=audit-log:add() /subsystem=jmx/configuration=audit-log/handler=file:add()
This enables Jakarta Management audit logging, and then uses the defined file
handler to write these logs to EAP_HOME/standalone/data/audit-log.log
.
Enable Managed Domain Jakarta Management Audit Logging
Jakarta Management audit logging can be enabled for each host and profile in a managed domain.
Enable Jakarta Management Audit Logging for a Host
Enable audit logging in the host’s
jmx
subsystem./host=HOST_NAME/subsystem=jmx/configuration=audit-log:add()
Once audit logging for the
jmx
subsystem has been enabled, a handler can be defined for the host with the following command./host=HOST_NAME/subsystem=jmx/configuration=audit-log/handler=host-file:add()
By default, this will write the Jakarta Management audit logs to
EAP_HOME/domain/data/audit-log.log
.
Enable Jakarta Management Audit Logging for a Profile
Enable audit logging in the profile’s
jmx
subsystem./profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log:add()
Once audit logging for the
jmx
subsystem has been enabled, a handler can be defined for the profile with the following command./profile=PROFILE_NAME/subsystem=jmx/configuration=audit-log/handler=server-file:add()
By default, this will write the Jakarta Management audit logs to
EAP_HOME/domain/servers/SERVER_NAME/data/audit-log.log
.
3.10.3. Send Management Audit Logging to a Syslog Server
A syslog handler specifies the parameters by which audit log entries are sent to a syslog server, specifically the syslog server’s host name and the port on which the syslog server is listening. Sending audit logging to a syslog server provides more security options than logging to a local file or local syslog server. Multiple syslog handlers can be defined and be active at the same time.
By default, audit logging is preconfigured to output to a file when enabled. Use the following steps to set up and enable audit logging to a syslog server. See Management Audit Logging Attributes for syslog handler attributes.
Add a syslog handler.
Create the syslog handler, specifying the host and port of the syslog server. In a managed domain, you must precede the
/core-service
commands with/host=HOST_NAME
.batch /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME:add(formatter=json-formatter) /core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=udp:add(host=HOST_NAME,port=PORT) run-batch
NoteThe parameters to pass in differ depending on the protocol specified.
To configure the handler to use TLS to communicate securely with the syslog server, you must also configure the authentication, for example:
/core-service=management/access=audit/syslog-handler=SYSLOG_HANDLER_NAME/protocol=tls/authentication=truststore:add(keystore-path=PATH_TO_TRUSTSTORE,keystore-password=TRUSTSTORE_PASSWORD)
Add a reference to the syslog handler.
In a managed domain, you must precede this command with
/host=HOST_NAME
./core-service=management/access=audit/logger=audit-log/handler=SYSLOG_HANDLER_NAME:add
Enable audit logging.
See Enable Management Audit Logging to enable audit logging.
Enabling audit logging to a syslog server in JBoss EAP will not work unless logging is enabled in the operating system as well.
For more information on rsyslog
configurations on Red Hat Enterprise Linux, see the Basic Configuration of Rsyslog section of the System Administrator’s Guide for Red Hat Enterprise Linux at https://access.redhat.com/documentation/en/red-hat-enterprise-linux/.
3.10.4. Read Audit Log Entries
Audit log entries output to files are best viewed with a text viewer, while those output to a syslog server are best viewed using a syslog viewer application.
Using a text editor for viewing log files is not recommended as some may prevent further log entries being written to the log file.
The audit log entries are stored in JSON format. Each log entry begins with an optional timestamp, followed by the fields in the below table.
Field Name | Description |
---|---|
access | This can have one of the following values:
|
booting |
Has the value |
domainUUID | An ID to link together all operations as they are propagated from the domain controller to its servers, slave host controllers, and slave host controller servers. |
ops | The operations being executed. This is a list of the operations serialized to JSON. At boot, this is the operations resulting from parsing the XML. Once booted, the list typically contains a single entry. |
r/o |
Has the value |
remote-address | The address of the client executing this operation. |
success |
Has the value |
type |
This can have the value |
user |
The username of the authenticated user. If the operation occurred using the management CLI on the same machine as the running server, the special user |
version | The version number of the JBoss EAP instance. |
3.11. Server Lifecycle Event Notifications
You can set up notifications for server lifecycle events using the JBoss EAP core-management
subsystem or Jakarta Management. A change in server runtime configuration state or server running state will trigger a notification.
The server runtime configuration states for JBoss EAP are STARTING
, RUNNING
, RELOAD_REQUIRED
, RESTART_REQUIRED
, STOPPING
, and STOPPED
.
The server running states for JBoss EAP are STARTING
, NORMAL
, ADMIN_ONLY
, PRE_SUSPEND
, SUSPENDING
, SUSPENDED
, STOPPING
, and STOPPED
.
3.11.1. Monitor Server Lifecycle Events Using the Core Management Subsystem
You can register a listener to the JBoss EAP core-management
subsystem to monitor for server lifecycle events. The following steps show how to create and register an example listener that logs the events to a file.
Create the listener.
Create an implementation of
org.wildfly.extension.core.management.client.ProcessStateListener
, like the example below.Example: Listener Class
package org.simple.lifecycle.events.listener; import java.io.File; import java.io.FileWriter; import java.io.IOException; import org.wildfly.extension.core.management.client.ProcessStateListener; import org.wildfly.extension.core.management.client.ProcessStateListenerInitParameters; import org.wildfly.extension.core.management.client.RunningStateChangeEvent; import org.wildfly.extension.core.management.client.RuntimeConfigurationStateChangeEvent; public class SimpleListener implements ProcessStateListener { private File file; private FileWriter fileWriter; private ProcessStateListenerInitParameters parameters; public void init(ProcessStateListenerInitParameters parameters) { this.parameters = parameters; this.file = new File(parameters.getInitProperties().get("file")); try { fileWriter = new FileWriter(file, true); } catch (IOException e) { e.printStackTrace(); } } public void cleanup() { try { fileWriter.close(); } catch (IOException e) { e.printStackTrace(); } finally { fileWriter = null; } } public void runtimeConfigurationStateChanged(RuntimeConfigurationStateChangeEvent evt) { try { fileWriter.write(String.format("Runtime configuration state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState())); fileWriter.flush(); } catch (IOException e) { e.printStackTrace(); } } public void runningStateChanged(RunningStateChangeEvent evt) { try { fileWriter.write(String.format("Running state change for %s: %s to %s\n", parameters.getProcessType(), evt.getOldState(), evt.getNewState())); fileWriter.flush(); } catch (IOException e) { e.printStackTrace(); } } }
NoteKeep the following in mind when implementing the listener.
- In the event of a server reload, listeners stop listening while the server attempts to stop, and the listeners are reloaded when the server starts. Because of this, implementations must ensure that they can be loaded, initialized, and removed properly several times inside the same JVM.
- Notifications to the listeners are blocking to allow reactions to server state changes. Implementations must ensure that they do not block or deadlock.
- Each listener instance is executed in its own thread and the order is not guaranteed.
Compile the class and package it into a JAR.
Note that to compile, you need to depend on the
org.wildfly.core:wildfly-core-management-client
Maven module.Add the JAR as a JBoss EAP module.
Use the following management CLI command and provide the module name and path to the JAR.
module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/path/to/simple-listener-0.0.1-SNAPSHOT.jar
ImportantUsing the
module
management CLI command to add and remove modules is provided as Technology Preview only. This command is not appropriate for use in a managed domain or when connecting to the management CLI remotely. Modules should be added and removed manually in a production environment.Technology Preview features are not supported with Red Hat production service level agreements (SLAs), might not be functionally complete, and Red Hat does not recommend to use them for production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.
See Technology Preview Features Support Scope on the Red Hat Customer Portal for information about the support scope for Technology Preview features.
Register the listener.
Add the listener to the
core-management
subsystem using the following management CLI command. Specify the class, module, and file location to log the server lifecycle events./subsystem=core-management/process-state-listener=my-simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener,properties={file=/path/to/my-listener-output.txt})
Now, server lifecycle events will be logged to the my-listener-output.txt
file based on the SimpleListener
class above. For example, issuing a :suspend
command in the management CLI will output the following to the my-listener-output.txt
file.
Running state change for STANDALONE_SERVER: normal to suspending Running state change for STANDALONE_SERVER: suspending to suspended
This shows that the running state changed from normal
to suspending
, and then from suspending
to suspended
.
3.11.2. Monitor Server Lifecycle Events Using Jakarta Management Notifications
You can register a Jakarta Management notification listener to monitor for server lifecycle events. The following steps show how to create and add an example listener that logs events to a file.
Create the listener.
Create an implementation of
javax.management.NotificationListener
, like the example below.Example: Listener Class
import java.io.BufferedWriter; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; import java.nio.file.StandardOpenOption; import javax.management.AttributeChangeNotification; import javax.management.Notification; import javax.management.NotificationListener; import org.jboss.logging.Logger; public class StateNotificationListener implements NotificationListener { public static final String RUNTIME_CONFIGURATION_FILENAME = "runtime-configuration-notifications.txt"; public static final String RUNNING_FILENAME = "running-notifications.txt"; private final Path targetFile; public StateNotificationListener() { this.targetFile = Paths.get("notifications/data").toAbsolutePath(); init(targetFile); } protected Path getRuntimeConfigurationTargetFile() { return this.targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME); } protected Path getRunningConfigurationTargetFile() { return this.targetFile.resolve(RUNNING_FILENAME); } protected final void init(Path targetFile) { try { Files.createDirectories(targetFile); if (!Files.exists(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME))) { Files.createFile(targetFile.resolve(RUNTIME_CONFIGURATION_FILENAME)); } if (!Files.exists(targetFile.resolve(RUNNING_FILENAME))) { Files.createFile(targetFile.resolve(RUNNING_FILENAME)); } } catch (IOException ex) { Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex); } } @Override public void handleNotification(Notification notification, Object handback) { AttributeChangeNotification attributeChangeNotification = (AttributeChangeNotification) notification; if ("RuntimeConfigurationState".equals(attributeChangeNotification.getAttributeName())) { writeNotification(attributeChangeNotification, getRuntimeConfigurationTargetFile()); } else { writeNotification(attributeChangeNotification, getRunningConfigurationTargetFile()); } } private void writeNotification(AttributeChangeNotification notification, Path path) { try (BufferedWriter in = Files.newBufferedWriter(path, StandardCharsets.UTF_8, StandardOpenOption.APPEND)) { in.write(String.format("%s %s %s %s", notification.getType(), notification.getSequenceNumber(), notification.getSource().toString(), notification.getMessage())); in.newLine(); in.flush(); } catch (IOException ex) { Logger.getLogger(StateNotificationListener.class).error("Problem handling JMX Notification", ex); } } }
Register the notification listener.
Add the notification listener to the
MBeanServer
.Example: Add a Notification Listener
MBeanServer server = ManagementFactory.getPlatformMBeanServer(); server.addNotificationListener(ObjectName.getInstance("jboss.root:type=state"), new StateNotificationListener(), null, null);
- Package and deploy to JBoss EAP.
Server lifecycle events are now logged to a file based on the StateNotificationListener
class above. For example, issuing a :suspend
command in the management CLI outputs the following to the running-notifications.txt
file.
jmx.attribute.change 5 jboss.root:type=state The attribute 'RunningState' has changed from 'normal' to 'suspending' jmx.attribute.change 6 jboss.root:type=state The attribute 'RunningState' has changed from 'suspending' to 'suspended'
This shows that the running state changed from normal
to suspending
, and then from suspending
to suspended
.