WildFly Admin Guide

Each "Host" box in the above diagram represents a physical or virtual host. A physical host can contain zero, one or more server instances.

When the domain.sh or domain.bat script is run on a host, a process known as a Host Controller is launched. The Host Controller is solely concerned with server management; it does not itself handle application server workloads. The Host Controller is responsible for starting and stopping the individual application server processes that run on its host, and interacts with the Domain Controller to help manage them.

Each Host Controller by default reads its configuration from the domain/configuration/host.xml file located in the unzipped WildFly installation on its host’s filesystem. The host.xml file contains configuration information that is specific to the particular host. Primarily:

One Host Controller instance is configured to act as the central management point for the entire domain, i.e. to be the Domain Controller. The primary responsibility of the Domain Controller is to maintain the domain’s central management policy, to ensure all Host Controllers are aware of its current contents, and to assist the Host Controllers in ensuring any running application server instances are configured in accordance with this policy. This central management policy is stored by default in the domain/configuration/domain.xml file in the unzipped WildFly installation on Domain Controller’s host’s filesystem.

A domain.xml file must be located in the domain/configuration directory of an installation that’s meant to run the Domain Controller. It does not need to be present in installations that are not meant to run a Domain Controller; i.e. those whose Host Controller is configured to contact a remote Domain Controller. The presence of a domain.xml file on such a server does no harm.

The domain.xml file includes, among other things, the configuration of the various "profiles" that WildFly instances in the domain can be configured to run. A profile configuration includes the detailed configuration of the various subsystems that comprise that profile (e.g. an embedded JBoss Web instance is a subsystem; a JBoss TS transaction manager is a subsystem, etc). The domain configuration also includes the definition of groups of sockets that those subsystems may open. The domain configuration also includes the definition of "server groups":

A server group is set of server instances that will be managed and configured as one. In a managed domain each application server instance is a member of a server group. (Even if the group only has a single server, the server is still a member of a group.) It is the responsibility of the Domain Controller and the Host Controllers to ensure that all servers in a server group have a consistent configuration. They should all be configured with the same profile and they should have the same deployment content deployed.

The domain can have multiple server groups. The above diagram shows two server groups, "ServerGroupA" and "ServerGroupB". Different server groups can be configured with different profiles and deployments; for example in a domain with different tiers of servers providing different services. Different server groups can also run the same profile and have the same deployments; for example to support rolling application upgrade scenarios where a complete service outage is avoided by first upgrading the application on one server group and then upgrading a second server group.

An example server group definition is as follows:

A server-group configuration includes the following required attributes:

In addition, the following optional elements are available:

Each "Server" in the above diagram represents an actual application server instance. The server runs in a separate JVM process from the Host Controller. The Host Controller is responsible for launching that process. (In a managed domain the end user cannot directly launch a server process from the command line.)

The Host Controller synthesizes the server’s configuration by combining elements from the domain wide configuration (from domain.xml ) and the host-specific configuration (from host.xml ).

By default, these are in the $JBOSS_HOME/bin directory. However, you can set the STANDALONE_CONF environment variable for standalone servers or DOMAIN_CONF environment variable for domain servers with a value of the absolute path to the file.

Starting with WildFly 23, common configuration files were introduced. These files are invoked from every script in the $JBOSS_HOME/bin directory. While these configuration files are not present in the directory by default, they can be added. You can simply just add the common.conf configuration file for the script type you want to execute and all scripts in the directory will invoke the configuration script.

You can also set the COMMON_CONF environment variable to have this configuration script live outside the $JBOSS_HOME/bin directory.

It is possible to override the value of any simple attribute by providing an environment variable with a name that maps to the attribute (and its resource).

If there is an environment variable with such a name, the management resource will use the value of this environment variable when the management resource validates and sets the attribute value. This takes place before the attribute value is resolved (if it contains an expression) or corrected.

The structure of the managed resource tree is quite close to the structure of the standalone.xml configuration file.

In a managed domain, the structure of the managed resource tree spans the entire domain, covering both the domain wide configuration (e.g. what’s in domain.xml, the host specific configuration for each host (e.g. what’s in host.xml, and the resources exposed by each running application server. The Host Controller processes in a managed domain provide access to all or part of the overall resource tree. How much is available depends on whether the management client is interacting with the Host Controller that is acting as the Domain Controller. If the Host Controller is the Domain Controller, then the section of the tree for each host is available. If the Host Controller is a secondary Host Controller to a remote Domain Controller, then only the portion of the tree associated with that host is available.

In interactive mode, when a timeout occurs, an error message is displayed then the console prompt is made available to type new commands. In non interactive mode (executing a script or a list of commands), when a timeout occurs, an exception is thrown and the CLI execution is stopped. In both modes (interactive and non interactive), when a timeout occurs, the CLI will make a best effort to cancel the associated server side activities.

Once the CLI is running, the timeout can be adjusted to cope with the commands to execute. For example a batch command will need a longer timeout than a non batch one. The command command-timeout allows to get, set and reset the command timeout.

The command command-timeout get displays the current timeout in seconds. A timeout of 0 means no timeout.

The command command-timeout set update the timeout value to a number of seconds. If a timeout has been set via configuration (XML file or option), it is overridden by the set action.

The command command-timeout reset \{config|default} allows to set the timeout to its configuration value (XML file or option) or default value (0 second). If no configuration value is set, resetting to the configuration value sets the timeout to its default value (0 seconds).

Operation requests might not always have the address part or the parameters. E.g.

which will list all the node types for the current node.

To syntactically disambiguate between the commands and operations, operations require one of the following prefixes:

To execute an operation against the current node, e.g.

To execute an operation against a child node of the current node, e.g.

To execute an operation against the root node, e.g.

The operation types can be distinguished between common operations that exist on any node and specific operations that belong to a particular configuration resource (i.e. subsystem). The common operations are:

For a list of specific operations (e.g. operations that relate to the logging subsystem) you can always query the model itself. For example, to read the operations supported by the logging subsystem resource on a standalone server:

As you can see, the logging resource offers four additional operations, namely root-logger-assign-handler, root-logger-unassign-handler, set-root-logger and remove-root-logger.

Further documentation about a resource or operation can be retrieved through the description:

Full model

When you start a managed domain process, a Host Controller instance is launched, and it parses its own configuration file to determine its own configuration, how it should integrate with the rest of the domain, any host-specific values for settings in the domain wide configuration (e.g. IP addresses) and what servers it should launch. This information is contained in the host-specific configuration file, the default version of which is domain/configuration/host.xml.

Each host will have its own variant host.xml, with settings appropriate for its role in the domain. WildFly ships with three standard variants:

Which host-specific configuration should be used can be controlled via the _ --host-config_ command line argument:

Once a Host Controller has processed its host-specific configuration, it knows whether it is configured to act as the Domain Controller. If it is, it must parse the domain wide configuration file, by default located at domain/configuration/domain.xml. This file contains the bulk of the settings that should be applied to the servers in the domain when they are launched – among other things, what subsystems they should run with what settings, what sockets should be used, and what deployments should be deployed.

Which domain-wide configuration should be used can be controlled via the _ --domain-config_ command line argument:

That argument is only relevant for hosts configured to act as the Domain Controller.

A secondary Host Controller does not usually parse the domain wide configuration file. A secondary Host Controller gets the domain wide configuration from the remote Domain Controller when it registers with it. A secondary Host Controller also will not persist changes to a domain.xml file if one is present on the filesystem. For that reason it is recommended that no domain.xml be kept on the filesystem of hosts that will only run as secondary Host Controllers.

A secondary Host Controller can be configured to keep a locally persisted copy of the domain wide configuration and then use it on boot (in case the Domain Controller is not available.) See --backup and --cached-dc under Command line parameters.

When adding application users in addition to adding the user with their pre-hashed password it is also now possible to define the roles of the user.

The seven standard roles are divided into two broad categories, based on whether the role can deal with items that are considered to be "security sensitive". Resources, attributes and operations that may affect administrative security (e.g. security realm resources and attributes that contain passwords) are "security sensitive".

Four roles are not given permissions for "security sensitive" items:

Three roles are granted permissions for security sensitive items:

The Auditor and Administrator roles are meant for organizations that want a separation of responsibilities between those who audit normal administrative actions and those who perform them, with those who perform most actions (Administrator role) not being able to read or alter the auditing configuration.

The following factors are used to determine whether a given role is granted a permission:

The first three of these factors are non-configurable; the latter three allow some customization. See " Configuring constraints" for details.

As mentioned above, permissions are granted to perform one of three actions, addressing a resource, reading it, and modifying. The latter two actions are fairly self-explanatory. But what is meant by "addressing" a resource?

"Addressing" a resource refers to taking an action that allows the user to determine whether a resource at a given address actually exists. For example, the "read-children-names" operation lets a user determine valid addresses. Trying to read a resource and getting a "Permission denied" error also gives the user a clue that there actually is a resource at the requested address.

Some resources may include sensitive information as part of their address. For example, security realm resources include the realm name as the last element in the address. That realm name is potentially security sensitive; for example it is part of the data used when creating a hash of a user password. Because some addresses may contain security sensitive data, a user needs permission to even "address" a resource. If a user attempts to address a resource and does not have permission, they will not receive a "permission denied" type error. Rather, the system will respond as if the resource does not even exist, e.g. excluding the resource from the result of the "read-children-names" operation or responding with a "No such resource" error instead of "Permission denied" if the user is attempting to read or write the resource.

Another term for "addressing" a resource is "looking up" the resource.

The easiest way to map individual users to roles is to use the web-based admin console.

Navigate to the "Administration" tab and the "Users" subtab. From there individual user mappings can be added, removed, or edited.

The CLI can also be used to map individuals users to roles.

First, if one does not exist, create the parent resource for all mappings for a role. Here we create the resource for the Administrator role.

Once this is done, map a user to the role:

Now if user jsmith authenticates to any security domain associated with the management interface they are using, he will be mapped to the Administrator role.

A "group" is an arbitrary collection of users that may exist in the end user environment. They can be named whatever the end user organization wants and can contain whatever users the end user organization wants. Some of the authentication store types supported by WildFly security realms include the ability to access information about what groups a user is a member of and associate this information with the Subject produced when the user is authenticated. This is currently supported for the following authentication store types:

Groups are convenient when it comes to associating a user with a role, since entire groups can be associated with a role in a single mapping.

The easiest way to map groups to roles is to use the web-based admin console.

Navigate to the "Administration" tab and the "Groups" subtab. From there group mappings can be added, removed, or edited.

The CLI can also be used to map groups to roles. The only difference to individual user mapping is the value of the type attribute should be GROUP instead of USER.

It’s possible to specify that all authenticated users should be mapped to a particular role. This could be used, for example, to ensure that anyone who can authenticate can at least have Monitor privileges.

In the web based admin console, navigate to the "Administration" tab, "Roles" subtab, highlight the relevant role, click the "Edit" button and click on the "Include All" checkbox:

The same change can be made using the CLI:

It is also possible to explicitly exclude certain users and groups from a role. Exclusions take precedence over inclusions, including cases where the include-all attribute is set to true for a role.

In the admin console, excludes are done in the same screens as includes. In the add dialog, simply change the "Type" pulldown to "Exclude".

In the CLI, excludes are identical to includes, except the resource address has exclude instead of include as the key for the last address element:

It is possible that a given user will be mapped to more than one role. When this occurs, by default the user will be granted the union of the permissions of the two roles. This behavior can be changed on a global basis to instead respond to the user request with an error if this situation is detected:

Note that no reload is required; the change takes immediate effect.

To restore the default behavior, set the value to "permissive":

The privileges for a server-group scoped role are constrained to resources associated with one or more server groups. Server groups are often associated with a particular application or set of applications; organizations that have separate teams responsible for different applications may find server-group scoped roles useful.

A server-group scoped role is equivalent to the default role upon which it is based, but with privileges constrained to target resources in the resource trees rooted in the server group resources. The server-group scoped role can be configured to include privileges for the following resources trees logically related to the server group:

Resources in the profile, socket binding group, server config and server portions of the tree that are not logically related to a server group associated with the server-group scoped role will not be addressable by a user in that role. So, in a domain with server groups "a" and "b", a user in a server-group scoped role that grants access to "a" will not be able to address /server-group=b. The system will treat that resource as non-existent for that user.

In addition to these privileges, users in a server-group scoped role will have non-sensitive read privileges (equivalent to the Monitor role) for resources other than those listed above.

The easiest way to create a server-group scoped role is to use the admin console. But you can also use the CLI to create a server-group scoped role.

Once the role is created, users or groups can be mapped to it the same as with the seven standard roles.

The privileges for a host-scoped role are constrained to resources associated with one or more hosts. A user with a host-scoped role cannot modify the domain wide configuration. Organizations may use host-scoped roles to give administrators relatively broad administrative rights for a host without granting such rights across the managed domain.

A host-scoped role is equivalent to the default role upon which it is based, but with privileges constrained to target resources in the resource trees rooted in the host resources for one or more specified hosts.

In addition to these privileges, users in a host-scoped role will have non-sensitive read privileges (equivalent to the Monitor role) for domain wide resources (i.e. those not in the /host=* section of the tree.)

Resources in the /host=* portion of the tree that are unrelated to the hosts specified for the Host Scoped Role will not be visible to users in that host-scoped role. So, in a domain with hosts "a" and "b", a user in a host-scoped role that grants access to "a" will not be able to address /host=b. The system will treat that resource as non-existent for that user.

The easiest way to create a host-scoped role is to use the admin console. But you can also use the CLI to create a host scoped role.

Once the role is created, users or groups can be mapped to it the same as with the seven standard roles.

Both server-group and host scoped roles can be added, removed or edited via the admin console. Select "Scoped Roles" from the "Administration" tab, "Roles" subtab:

When adding a new scoped role, use the dialogue’s "Type" pull down to choose between a host scoped role and a server-group scoped role. Then place the names of the relevant hosts or server groups in the "Scope" text are.

"Sensitivity" constraints are about restricting access to security-sensitive data. Different organizations may have different opinions about what is security sensitive, so WildFly provides configuration options to allow users to tailor these constraints.

The standard Deployer role has its write permissions limited to resources that are considered to be "application resources"; i.e. conceptually part of an application and not part of the general server configuration. By default, only deployment resources are considered to be application resources. However, different organizations may have different opinions on what qualifies as an application resource, so for resource types that subsystems authors consider potentially to be application resources, WildFly provides a configuration option to declare them as such. Such resources will be annotated with an "application classification".

For example, the mail subsystem provides such a classification:

Use read-resource or read-children-resources to see what resources have this classification applied:

This indicates that this classification, intuitively enough, only applies to mail subsystem mail-session resources.

To make resources with this classification writeable by users in the Deployer role, set the configured-application attribute to true.

The admin console takes great pains to provide a good user experience even when the user has reduced permissions. Resources the user is not permitted to see will simply not be shown, or if appropriate will be replaced in the UI with an indication that the user is not authorized. Interaction units like "Add" and "Remove" buttons and "Edit" links will be suppressed if the user has no write permissions.

The CLI is a much more unconstrained tool than the admin console is, allowing users to try to execute whatever operations they wish, so it’s more likely that users who attempt to do things for which they lack necessary permissions will receive failure messages. For example, a user in the Monitor role cannot read passwords:

If the user isn’t even allowed to address the resource then the response would be as if the resource doesn’t exist, even though it actually does:

This prevents unauthorized users fishing for sensitive data in resource addresses by checking for "Permission denied" type failures.

Users who use the read-resource operation may ask for data, some of which they are allowed to see and some of which they are not. If this happens, the request will not fail, but inaccessible data will be elided and a response header will be included advising on what was not included. Here we show the effect of a Monitor trying to recursively read the elytron subsystem configuration:

The response-headers section includes access control data in a list with one element per relevant resource. (In this case there’s just one.) The absolute and relative address of the resource is shown, along with the fact that the value of the deep-copy-subject-mode attribute has been filtered (i.e. undefined is shown as the value, which may not be the real value) as well as the fact that child resources of type security-domain have been filtered.

metadata

The management model descriptive metadata returned from operations like read-resource-description and read-operation-description can be configured to include information describing the access control constraints relevant to the resource, This is done by using the access-control parameter. The output will be tailored to the caller’s permissions. For example, a user who maps to the Monitor role could ask for information about a resource in the mail subsystem:

Because trim-descriptions was used as the value for the access-control parameter, the typical "description", "attributes", "operations" and "children" data is largely suppressed. (For more on this, see below.) The access-constraints field indicates that this resource is annotated with an application constraint. The access-control field includes information about the permissions the current caller has for this resource. The default section shows the default settings for resources of this type. The read and write fields directly under default show that the caller can, in general, read this resource but cannot write it. The attributes section shows the individual attribute settings. Note that Monitor cannot read the username and password attributes.

There are three valid values for the access-control parameter to read-resource-description and read-operation-description:

With the CLI, run-as capability is on a per-request basis. It is done by using the "roles" operation header, the value of which can be the name of a single role or a bracket-enclosed, comma-delimited list of role names.

Example with a low level operation:

Example with a CLI command:

Here we show the effect of switching to a role that isn’t granted the necessary permission.

Admin console users can change the role in which they operate by clicking on their name in the top right corner and clicking on the "Run as…​" link.

Then select the role in which you wish to operate:

The console will need to be restarted in order for the change to take effect.

This "run-as" capability is available even if the "simple" access control provider is used. When the "simple" provider is used, any authenticated administrator is treated the same as if they would map to SuperUser when the "rbac" provider is used.
However, the "simple" provider actually understands all of the "rbac" provider configuration settings described above, but only makes use of them if the "run-as" capability is used for a request. Otherwise, the SuperUser role has all permissions, so detailed configuration is irrelevant.

Using the run-as capability with the "simple" provider may be useful if an administrator is setting up an rbac provider configuration before switching the provider to rbac to make that configuration take effect. The administrator can then run-as different roles to see the effect of the planned settings.

The WildFly filesystem deployment scanner operates in one of two different modes, depending on whether it will directly monitor the deployment content in order to decide to deploy or redeploy it.

Auto-deploy mode:

The scanner will directly monitor the deployment content, automatically deploying new content and redeploying content whose timestamp has changed. This is similiar to the behavior of previous AS releases, although there are differences:

Manual deploy mode:

The scanner will not attempt to directly monitor the deployment content and decide if or when the end user wishes the content to be deployed. Instead, the scanner relies on a system of marker files, with the user’s addition or removal of a marker file serving as a sort of command telling the scanner to deploy, undeploy or redeploy content.

Auto-deploy mode and manual deploy mode can be independently configured for zipped deployment content and exploded deployment content. This is done via the "auto-deploy" attribute on the deployment-scanner element in the standalone.xml configuration file:

By default, auto-deploy of zipped content is enabled, and auto-deploy of exploded content is disabled. Manual deploy mode is strongly recommended for exploded content, as exploded content is inherently vulnerable to the scanner trying to auto-deploy partially copied content.

The marker files always have the same name as the deployment content to which they relate, but with an additional file suffix appended. For example, the marker file to indicate the example.war file should be deployed is named example.war.dodeploy. Different marker file suffixes have different meanings.

The relevant marker file types are:

All examples assume variable $JBOSS_HOME points to the root of the WildFly distribution.

Note that the behavior of 'touch' and 'echo' are different but the differences are not relevant to the usages in the examples above.

Global modules is a set of JBoss Modules that will be added as dependencies to the JBoss Modules module of every Jakarta EE deployment. Such dependencies allows Jakarta EE deployments to see the classes exported by the global modules.

Each global module is defined through the module resource, an example of its XML configuration:

The only mandatory attribute is the JBoss Modules module name, the slot attribute defaults to main, and both define the JBoss Modules module ID to reference.

The optional annotations attribute, which defaults to false, indicates if a pre-computed annotation index should be imported from META-INF/jandex.idx

The optional services attribute indicates if any services exposed in META-INF/services should be made available to the deployments class loader, and defaults to false.

The optional meta-inf attribute, which defaults to true, indicates if the Module’s META-INF path should be available to the deployment’s class loader.

Global modules can be used to share common libraries across all deployed applications, but it could be impractical if the name of a shared library changes very often or if there are many libraries you want to share. Both cases will require changes in the underlying module.xml that represents this global module.

The EE subsystem allows the configuration of a global directory, which represents a directory tree scanned automatically to include .jar files and resources as a single additional dependency. This module dependency is added as a system dependency on each deployed application. Basically, with a global directory, you will be relying on WildFly to automate the maintenance and configuration of a JBoss Modules module that represents the jar files and resources of a specific directory.

You can configure a global directory using the following operation:

The following attributes are available on the global-directory resource:

When a global-directory is created, the server establishes a JBoss Modules module with one Path Resource Loader created using 'path' and 'relative-to' attributes and one Jar Resource loader for each jar file included in this directory and its subdirectories.

The 'Path Resource Loader' will make available any file as a resource to the application. The 'Jar Resource loader' will make available any class inside of the jar file to the applications.

For example, suppose you have configured one global directory pointing to the following directory tree:

The JBoss Modules module generated after scanning this global-directory will be equivalent to the following module.xml:

The name of the generated module follows the pattern deployment.external.global-directory.{global-directory-name} and as such, it can be excluded selectively using your deployment-structure.xml.

All resources will be available from the application class loader. For example, you could access the above property files using the context ClassLoader of your current thread:

All classes inside of each jar file will also be available, and the order of how the resource-root are created internally will govern the order of the class loading. The jar resources of the generated module will be created iterating over all jar files found in the directory tree. Each directory is scanned alphabetically starting from the root, and on each level, each subdirectory is also explored alphabetically until visiting all the branch. Files found on each level are also added in alphabetical order.

Notice you should know which classes are exposed on each .jar file and avoid conflicts including the same class twice with incompatible binary change. In those cases, classloading errors are likely to occur. Specifically, you should not add classes that interfere with the classes the server already makes available for your application; the goal of a global directory is not to override and replace existing library versions shipped with the server. It is a facility that will allow moving common frameworks you usually add to your application libs to a common place to facilitate maintenance.

The module created from the shared directory is loaded as soon as the first application is deployed in the server after creating the global-directory. That means, if the server is started/restarted and there are no applications deployed, then the global directory is neither scanned nor the module loaded. Any change in any of the contents of the global-directory will require a server reload to make them available to the deployed applications.

In case of domain mode or distributed environments, it is the user responsibility to make the content of the configured global directory consistent across all the server instances, as well as distribute the jar files that they contain.

A flag indicating whether each of the subdeployments within a .ear can access classes belonging to another subdeployment within the same .ear. The default value is false, which allows the subdeployments to see classes belonging to other subdeployments within the .ear.

For example:

If the ear-subdeployments-isolated is set to false, then the classes in web.war can access classes belonging to ejb1.jar and ejb2.jar. Similarly, classes from ejb1.jar can access classes from ejb2.jar (and vice-versa).

The EE subsystem configuration includes flags to configure whether system property replacement will be done on XML descriptors and Java Annotations included in Jakarta EE deployments.

The Context Service is a concurrency utility which creates contextual proxies from existent objects. WildFly Context Services are also used to propagate the context from a Jakarta EE application invocation thread, to the threads internally used by the other EE Concurrency Utilities. Context Service instances may be created using the subsystem XML configuration:

The name attribute is mandatory, and it’s value should be a unique name within all Context Services.

The jndi-name attribute is also mandatory, and defines where in the JNDI the Context Service should be placed.

The optional use-trasaction-setup-provider attribute indicates if the contextual proxies built by the Context Service should suspend transactions in context, when invoking the proxy objects, and its value defaults to true.

Management clients, such as the WildFly CLI, may also be used to configure Context Service instances. An example to add and remove one named other:

The Managed Thread Factory allows Jakarta EE applications to create new threads. WildFly Managed Thread Factory instances may also, optionally, use a Context Service instance to propagate the Jakarta EE application thread’s context to the new threads. Instance creation is done through the EE subsystem, by editing the subsystem XML configuration:

The name attribute is mandatory, and it’s value should be a unique name within all Managed Thread Factories.

The jndi-name attribute is also mandatory, and defines where in the JNDI the Managed Thread Factory should be placed.

The optional context-service references an existent Context Service by its name. If specified then thread created by the factory will propagate the invocation context, present when creating the thread.

The optional priority indicates the priority for new threads created by the factory, and defaults to 5.

Management clients, such as the WildFly CLI, may also be used to configure Managed Thread Factory instances. An example to add and remove one named other:

The Managed Executor Service is the Jakarta EE adaptation of Java SE Executor Service, providing to Jakarta EE applications the functionality of asynchronous task execution. WildFly is responsible to manage the lifecycle of Managed Executor Service instances, which are specified through the EE subsystem XML configuration:

The name attribute is mandatory, and it’s value should be a unique name within all Managed Executor Services.

The jndi-name attribute is also mandatory, and defines where in the JNDI the Managed Executor Service should be placed.

The optional context-service references an existent Context Service by its name. If specified then the referenced Context Service will capture the invocation context present when submitting a task to the executor, which will then be used when executing the task.

The optional thread-factory references an existent Managed Thread Factory by its name, to handle the creation of internal threads. If not specified then a Managed Thread Factory with default configuration will be created and used internally.

The mandatory core-threads provides the number of threads to keep in the executor’s pool, even if they are idle. If this is not defined or is set to 0, the core pool size will be calculated based on the number of available processors.

The optional queue-length indicates the number of tasks that can be stored in the input queue. The default value is 0, which means the queue capacity is unlimited.

The executor’s task queue is based on the values of the attributes core-threads and queue-length:

The optional hung-task-threshold defines a runtime threshold value, in milliseconds, for tasks to be considered hung by the executor. A value of 0 will never consider tasks to be hung.

The optional hung-task-termination-period defines the period, in milliseconds, for attempting the termination of hung tasks, by cancelling their execution, and interrupting their executing threads. Please note that the termination of a cancelled hung task is not guaranteed. A value of 0, which is the default, deactivates the periodic cancellation of hung tasks. Management clients, such as the WildFly CLI, may still be used to manually attempt the termination of hung tasks:

The optional long-running-tasks is a hint to optimize the execution of long running tasks, and defaults to false.

The optional max-threads defines the the maximum number of threads used by the executor, which defaults to Integer.MAX_VALUE (2147483647).

The optional keepalive-time defines the time, in milliseconds, that an internal thread may be idle. The attribute default value is 60000.

The optional reject-policy defines the policy to use when a task is rejected by the executor. The attribute value may be the default ABORT, which means an exception should be thrown, or RETRY_ABORT, which means the executor will try to submit it once more, before throwing an exception.

Management clients, such as the WildFly CLI, may also be used to configure Managed Executor Service instances. An example to add and remove one named other:

The Managed Scheduled Executor Service is the Jakarta EE adaptation of Java SE Scheduled Executor Service, providing to Jakarta EE applications the functionality of scheduling task execution. WildFly is responsible to manage the lifecycle of Managed Scheduled Executor Service instances, which are specified through the EE subsystem XML configuration:

The name attribute is mandatory, and it’s value should be a unique name within all Managed Scheduled Executor Services.

The jndi-name attribute is also mandatory, and defines where in the JNDI the Managed Scheduled Executor Service should be placed.

The optional context-service references an existent Context Service by its name. If specified then the referenced Context Service will capture the invocation context present when submitting a task to the executor, which will then be used when executing the task.

The optional thread-factory references an existent Managed Thread Factory by its name, to handle the creation of internal threads. If not specified then a Managed Thread Factory with default configuration will be created and used internally.

The mandatory core-threads provides the number of threads to keep in the executor’s pool, even if they are idle. A value of 0 means there is no limit.

The optional hung-task-threshold defines a runtime threshold value, in milliseconds, for tasks to be considered hung by the executor. A value of 0 will never consider tasks to be hung.

The optional hung-task-termination-period defines the period, in milliseconds, for attempting the termination of hung tasks, by cancelling their execution, and interrupting their executing threads. Please note that the termination of a cancelled hung task is not guaranteed. A value of 0, which is the default, deactivates the periodic cancellation of hung tasks. Management clients, such as the WildFly CLI, may still be used to manually attempt the termination of hung tasks:

The optional long-running-tasks is a hint to optimize the execution of long running tasks, and defaults to false.

The optional keepalive-time defines the time, in milliseconds, that an internal thread may be idle. The attribute default value is 60000.

The optional reject-policy defines the policy to use when a task is rejected by the executor. The attribute value may be the default ABORT, which means an exception should be thrown, or RETRY_ABORT, which means the executor will try to submit it once more, before throwing an exception.

Management clients, such as the WildFly CLI, may also be used to configure Managed Scheduled Executor Service instances. An example to add and remove one named other:

A simple binding is a primitive or java.net.URL entry, and it is defined through the simple XML element. An example of its XML configuration:

The name attribute is mandatory and specifies the target JNDI name for the entry.

The value attribute is mandatory and defines the entry’s value.

The optional type attribute, which defaults to java.lang.String, specifies the type of the entry’s value. Besides java.lang.String, allowed types are all the primitive types and their corresponding object wrapper classes, such as int or java.lang.Integer, and java.net.URL.

Management clients, such as the WildFly CLI, may be used to configure simple bindings. An example to add and remove the one in the XML example above:

The Naming subsystem configuration allows the binding of javax.naming.spi.ObjectFactory entries, through the object-factory XML element, for instance:

The name attribute is mandatory and specifies the target JNDI name for the entry.

The class attribute is mandatory and defines the object factory’s Java type.

The module attribute is mandatory and specifies the JBoss Module ID where the object factory Java class may be loaded from.

The optional environment child element may be used to provide a custom environment to the object factory.

Management clients, such as the WildFly CLI, may be used to configure object factory bindings. An example to add and remove the one in the XML example above:

Federation of external JNDI contexts, such as a LDAP context, are achieved by adding External Context bindings to the global bindings configuration, through the external-context XML element. An example of its XML configuration:

The name attribute is mandatory and specifies the target JNDI name for the entry.

The class attribute is mandatory and indicates the Java initial naming context type used to create the federated context. Note that such type must have a constructor with a single environment map argument.

The optional module attribute specifies the JBoss Module ID where any classes required by the external JNDI context may be loaded from.

The optional cache attribute, which value defaults to false, indicates if the external context instance should be cached.

The optional environment child element may be used to provide the custom environment needed to lookup the external context.

Management clients, such as the WildFly CLI, may be used to configure external context bindings. An example to add and remove the one in the XML example above:

Some JNDI providers may fail when their resources are looked up if they do not implement properly the lookup(Name) method. Their errors would look like:

To work around their shortcomings, the org.jboss.as.naming.lookup.by.string property can be specified in the external-context’s environment to use instead the lookup(String) method (with a performance degradation):

Binding Aliases

The Naming subsystem configuration allows the binding of existent entries into additional names, i.e. aliases. Binding aliases are specified through the lookup XML element. An example of its XML configuration:

The name attribute is mandatory and specifies the target JNDI name for the entry.

The lookup attribute is mandatory and indicates the source JNDI name. It can chain lookups on external contexts. For example, having an external context bounded to java:global/federation/ldap/example, searching can be done there by setting lookup attribute to java:global/federation/ldap/example/subfolder.

Management clients, such as the WildFly CLI, may be used to configure binding aliases. An example to add and remove the one in the XML example above:

The connection factory requires a reference to a driver (see agroal-driver-installation). With a java.sql.Driver the preferred way to 'point' to the database is to specify an url attribute while for javax.sql.DataSource and javax.sql.XADataSource the preferred way is to specify connection-properties.

Other features provided by the connection-factory definition include the possibility of executing a SQL statement right after the connection has been created and to specify the isolation level of transactions in the database.

The main attributes of the connection-pool definition are the ones that control it’s size. While the initial size attribute is only taken into account while bootstrapping the pool, min size and max size are always enforced and can be changed at any time without requiring a reload of the server.

Another important attribute of the connection-pool is the blocking timeout that defines the maximum amount of time a thread will wait for a connection. If that time elapses and still no connection is available an exception is thrown. Keep in mind that the default value is 0, meaning that a thread will wait forever for a connection to become available. Changing this setting does not require a reload of the server.

The connection pool provides other convenient features like background validation of connections on the pool, removal of idle connections from the pool and detection of connections held for too long by one thread. All these features are disabled by default and can be enabled by specifying an interval of time on the corresponding attribute.

All datasources in Agroal have a name that’s used to locate them in the WildFly runtime model and are bound to a JNDI name.

The attribute statistics-enabled allow the collection of metrics regarding the pool that can be queried in the runtime model

The available statistics include the number of created / destroyed connections and the number of connections in use / available in the pool. There are also statistics for the time it takes to create a connection and for how long have threads been blocked waiting for a connection.

In addition to all the common attributes, a datasource definition may disable the Jakarta Transactions integration.

Deferred enlistment is not supported, meaning that if Jakarta Transactions is enabled a connection must always be obtained within the scope of a transaction. The connection will always be enlisted with that transaction (lazy enlistment is not supported).

At the moment there are no attributes specific to a XADataSource definition.

The add-logging-api-dependencies controls whether or not the container adds implicit logging API dependencies to your deployments. If set to true, the default, all the implicit logging API dependencies are added. If set to false the dependencies are not added to your deployments.

The use-deployment-logging-config controls whether or not your deployment is scanned for per-deployment logging. If set to true, the default, per-deployment logging is enabled. Set to false to disable this feature.

In a managed domain two types of log files do exist: Controller and server logs. The controller components govern the domain as whole. It’s their responsibility to start/stop server instances and execute managed operations throughout the domain. Server logs contain the logging information for a particular server instance. They are co-located with the host the server is running on.

For the sake of simplicity we look at the default setup for managed domain. In this case, both the domain controller components and the servers are located on the same host:

The default log files for a standalone server can be found in the log subdirectory of the distribution:

The logging subsystem has a log-file resource off the subsystem root resource and off each logging-profile resource to list each log file.

The read-log-file operation is available on each log-file resource. This operation has 4 optional parameters.

You may have noticed that there is a logging.properties file in the configuration directory. This is logging configuration is used when the server boots up until the logging subsystem kicks in. If the logging subsystem is not included in your configuration, then this would act as the logging configuration for the entire server.

A formatter used to format log messages in JSON.

A formatter used to format log messages in plain text. The following table describes the format characters for the pattern formatter.

You can also modify the format by placing the optional format modifier between the percent sign and the symbol.

A formatter used to format log messages in XML.

A custom formatter to be used with handlers. Note that most log records are formatted in the printf format. Formatters may require invocation of the org.jboss.logmanager.ExtLogRecord#getFormattedMessage() for the message to be properly formatted.

Handlers define how log messages are recorded. If a message is said to be {oracle-javadocs}/java.logging/java/util/logging/Logger.html#isLoggable-java.util.logging.Level-[loggable] by a logger the message is then processed by the log handler.

The following are the available handlers for WildFly Full;

To change a handlers log level:

Changing the level on a log category is the same:

If you want to use your own log4j2 implementation, such as log4j-core, then you need to do the following two steps.

Loggers are used to log messages. A logger is defined by a category generally consisting of a package name or a class name.

A logger is the first step to determining if a messages should be logged or not. If a logger is defined with a level, the level of the message must be greater than the level defined on the logger. The filter is then checked next and the rules of the filter will determine whether or not the messages is said to be loggable.