The following chapters will focus on the high level management use cases that are available through the CLI and the web interface. For a detailed description of each subsystem configuration property, please consult the respective component reference.
![]() | Schema Location The configuration schemas can found in $JBOSS_HOME/docs/schema. |
EE Subsystem Configuration
Overview
The EE subsystem provides common functionality in the Java EE platform, such as the EE Concurrency Utilities (JSR 236) and @Resource injection. The subsystem is also responsible for managing the lifecycle of Java EE application's deployments, that is, .ear files.
The EE subsystem configuration may be used to:
- customise the deployment of Java EE applications
- create EE Concurrency Utilities instances
- define the default bindings
The subsystem name is ee and this document covers EE subsystem version 2.0, which XML namespace within WildFly XML configurations is urn:jboss:domain:ee:2.0. The path for the subsystem's XML schema, within WildFly's distribution, is docs/schema/jboss-as-ee_2_0.xsd.
Subsystem XML configuration example with all elements and attributes specified:
Java EE Application Deployment
The EE subsystem configuration allows the customisation of the deployment behaviour for Java EE Applications.
Global Modules
Global modules is a set of JBoss Modules that will be added as dependencies to the JBoss Module of every Java EE deployment. Such dependencies allows Java 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 Module name, the slot attribute defaults to main, and both define the JBoss 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.
EAR Subdeployments Isolation
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).
![]() | This flag has no effect on the isolated classloader of the .war file(s), i.e. irrespective of whether this flag is set to true or false, the .war within a .ear will have a isolated classloader, and other subdeployments within that .ear will not be able to access classes from that .war. This is as per spec. |
Property Replacement
The EE subsystem configuration includes flags to configure whether system property replacement will be done on XML descriptors and Java Annotations included in Java EE deployments.
![]() | System properties etc are resolved in the security context of the application server itself, not the deployment that contains the file. This means that if you are running with a security manager and enable this property, a deployment can potentially access system properties or environment entries that the security manager would have otherwise prevented. |
Spec Descriptor Property Replacement
Flag indicating whether system property replacement will be performed on standard Java EE XML descriptors. If not configured this defaults to true, however it is set to false in the standard configuration files shipped with WildFly.
JBoss Descriptor Property Replacement
Flag indicating whether system property replacement will be performed on WildFly proprietary XML descriptors, such as jboss-app.xml. This defaults to true.
Annotation Property Replacement
Flag indicating whether system property replacement will be performed on Java annotations. The default value is false.
EE Concurrency Utilities
EE Concurrency Utilities (JSR 236) were introduced with Java EE 7, to ease the task of writing multithreaded Java EE applications. Instances of these utilities are managed by WildFly, and the related configuration provided by the EE subsystem.
Context Services
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 Java 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:
Managed Thread Factories
The Managed Thread Factory allows Java EE applications to create new threads. WildFly Managed Thread Factory instances may also, optionally, use a Context Service instance to propagate the Java 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:
Managed Executor Services
The Managed Executor Service is the Java EE adaptation of Java SE Executor Service, providing to Java 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. A value of 0 means there is no limit.
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:
- If queue-length is 0, or queue-length is Integer.MAX_VALUE (2147483647) and core-threads is 0, direct handoff queuing strategy will be used and a synchronous queue will be created.
- If queue-length is Integer.MAX_VALUE but core-threads is not 0, an unbounded queue will be used.
- For any other valid value for queue-length, a bounded queue wil be created.
The optional hung-task-threshold defines a threshold value, in milliseconds, to hung a possibly blocked task. A value of 0 will never hung a task, and is the default.
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:
Managed Scheduled Executor Services
The Managed Scheduled Executor Service is the Java EE adaptation of Java SE Scheduled Executor Service, providing to Java 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 threshold value, in milliseconds, to hung a possibly blocked task. A value of 0 will never hung a task, and is the default.
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, orRETRY_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:
Default EE Bindings
The Java EE Specification mandates the existence of a default instance for each of the following resources:
- Context Service
- Datasource
- JMS Connection Factory
- Managed Executor Service
- Managed Scheduled Executor Service
- Managed Thread Factory
The EE subsystem looks up the default instances from JNDI, using the names in the default bindings configuration, before placing those in the standard JNDI names, such as java:comp/DefaultManagedExecutorService:
![]() | The default bindings are optional, if the jndi name for a default binding is not configured then the related resource will not be available to Java EE applications. |
Naming
Overview
The Naming subsystem provides the JNDI implementation on WildFly, and its configuration allows to:
- bind entries in global JNDI namespaces
- turn off/on the remote JNDI interface
The subsystem name is naming and this document covers Naming subsystem version 2.0, which XML namespace within WildFly XML configurations is urn:jboss:domain:naming:2.0. The path for the subsystem's XML schema, within WildFly's distribution, is docs/schema/jboss-as-naming_2_0.xsd.
Subsystem XML configuration example with all elements and attributes specified:
Global Bindings Configuration
The Naming subsystem configuration allows binding entries into the following global JNDI namespaces:
- java:global
- java:jboss
- java:
![]() | If WildFly is to be used as a Java EE application server, then it's recommended to opt for java:global, since it is a standard (i.e. portable) namespace. |
Four different types of bindings are supported:
- Simple
- Object Factory
- External Context
- Lookup
In the subsystem's XML configuration, global bindings are configured through the <bindings /> XML element, as an example:
Simple Bindings
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:
Object Factories
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:
External Context Federation
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:
11:31:49,047 ERROR org.jboss.resource.adapter.jms.inflow.JmsActivation (default-threads -1) javax.naming.InvalidNameException: Only support CompoundName names at com.tibco.tibjms.naming.TibjmsContext.lookup(TibjmsContext.java:504) at javax.naming.InitialContext.lookup(InitialContext.java:421) |
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:
Remote JNDI Configuration
The Naming subsystem configuration may be used to (de)activate the remote JNDI interface, which allows clients to lookup entries present in a remote WildFly instance.
![]() | Only entries within the java:jboss/exported context are accessible over remote JNDI. |
In the subsystem's XML configuration, remote JNDI access bindings are configured through the <remote-naming /> XML element:
Management clients, such as the WildFly CLI, may be used to add/remove the remote JNDI interface. An example to add and remove the one in the XML example above:
Data sources
Datasources are configured through the datasource subsystem. Declaring a new datasource consists of two separate steps: You would need to provide a JDBC driver and define a datasource that references the driver you installed.
JDBC Driver Installation
The recommended way to install a JDBC driver into WildFly 8 is to deploy it as a regular JAR deployment. The reason for this is that when you run WildFly in domain mode, deployments are automatically propagated to all servers to which the deployment applies; thus distribution of the driver JAR is one less thing for you to worry about!
Any JDBC 4-compliant driver will automatically be recognized and installed into the system by name and version. A JDBC JAR is identified using the Java service provider mechanism. Such JARs will contain a text a file named META-INF/services/java.sql.Driver, which contains the name of the class(es) of the Drivers which exist in that JAR. If your JDBC driver JAR is not JDBC 4-compliant, it can be made deployable in one of a few ways.
Modify the JAR
The most straightforward solution is to simply modify the JAR and add the missing file. You can do this from your command shell by:
- Change to, or create, an empty temporary directory.
- Create a META-INF subdirectory.
- Create a META-INF/services subdirectory.
- Create a META-INF/services/java.sql.Driver file which contains one line - the fully-qualified class name of the JDBC driver.
- Use the jar command-line tool to update the JAR like this:
For a detailed explanation how to deploy JDBC 4 compliant driver jar, please refer to the chapter "Application Deployment".
Datasource Definitions
The datasource itself is defined within the subsystem datasources:
(See standalone/configuration/standalone.xml)
As you can see the datasource references a driver by it's logical name.
You can easily query the same information through the CLI:
![]() | Using the web console or the CLI greatly simplifies the deployment of JDBC drivers and the creation of datasources. |
The CLI offers a set of commands to create and modify datasources:
Using security domains
Information can be found at https://community.jboss.org/wiki/JBossAS7SecurityDomainModel
Component Reference
The datasource subsystem is provided by the IronJacamar project. For a detailed description of the available configuration properties, please consult the project documentation.
- IronJacamar homepage: http://ironjacamar.org/
- Project Documentation: http://ironjacamar.org/documentation.html
- Schema description: http://www.ironjacamar.org/doc/userguide/1.1/en-US/html_single/index.html#deployingds_descriptor
Logging
Overview
The overall server logging configuration is represented by the logging subsystem. It consists of four notable parts: handler configurations, logger, the root logger declarations (aka log categories) and logging profiles. Each logger does reference a handler (or set of handlers). Each handler declares the log format and output:
Attributes
The root resource contains two notable attributes add-logging-api-dependencies and use-deployment-logging-config.
add-logging-api-dependencies
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.
use-deployment-logging-config
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.
Per-deployment Logging
Per-deployment logging allows you to add a logging configuration file to your deployment and have the logging for that deployment configured according to the configuration file. In an EAR the configuration should be in the META-INF directory. In a WAR or JAR deployment the configuration file can be in either the META-INF or WEB-INF/classes directories.
The following configuration files are allowed:
- logging.properties
- jboss-logging.properties
- log4j.properties
- log4j.xml
- jboss-log4j.xml
You can also disable this functionality by changing the use-deployment-logging-config attribute to false.
Logging Profiles
Logging profiles are like additional logging subsystems. Each logging profile constists of three of the four notable parts listed above: handler configurations, logger and the root logger declarations.
You can assign a logging profile to a deployment via the deployments manifest. Add a Logging-Profile entry to the MANIFEST.MF file with a value of the logging profile id. For example a logging profile defined on /subsystem=logging/logging-profile=ejbs the MANIFEST.MF would look like:
A logging profile can be assigned to any number of deployments. Using a logging profile also allows for runtime changes to the configuration. This is an advantage over the per-deployment logging configuration as the redeploy is not required for logging changes to take affect.
Default Log File Locations
Managed Domain
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:
Process | Log File |
---|---|
Host Controller | ./domain/log/host-controller.log |
Process Controller | ./domain/log/process-controller.log |
"Server One" | ./domain/servers/server-one/log/server.log |
"Server Two" | ./domain/servers/server-two/log/server.log |
"Server Three" | ./domain/servers/server-three/log/server.log |
Standalone Server
The default log files for a standalone server can be found in the log subdirectory of the distribution:
Process | Log File |
---|---|
Server | ./standalone/log/server.log |
Filter Expressions
Filter Type | Expression | Description | Parameter(s) | Examples |
---|---|---|---|---|
accept | accept | Accepts all log messages. | None | accept |
deny | deny | enies all log messages. | None | deny |
not | not(filterExpression) | Accepts a filter as an argument and inverts the returned value. | The expression takes a single filter for it's argument. | not(match("JBAS")) |
all | all(filterExpressions) | A filter consisting of several filters in a chain. If any filter find the log message to be unloggable, the message will not be logged and subsequent filters will not be checked. | The expression takes a comma delimited list of filters for it's argument. | all(match("JBAS"), match("WELD")) |
any | any(filterExpressions) | A filter consisting of several filters in a chain. If any filter fins the log message to be loggable, the message will be logged and the subsequent filters will not be checked. | The expression takes a comma delimited list of filters for it's argument. | any(match("JBAS"), match("WELD")) |
levelChange | levelChange(level) | A filter which modifies the log record with a new level. | The expression takes a single string based level for it's argument. | levelChange(WARN) |
levels | levels(levels) | A filter which includes log messages with a level that is listed in the list of levels. | The expression takes a comma delimited list of string based levels for it's argument. | levels(DEBUG, INFO, WARN, ERROR) |
levelRange | levelRange([minLevel,maxLevel]) | A filter which logs records that are within the level range. | The filter expression uses a "[" to indicate a minimum inclusive level and a "]" to indicate a maximum inclusive level. Otherwise use "(" or ")" respectively indicate exclusive. The first argument for the expression is the minimum level allowed, the second argument is the maximum level allowed. |
|
match | match("pattern") | A regular-expression based filter. The raw unformatted message is used against the pattern. | The expression takes a regular expression for it's argument. match("JBAS\d+") | |
substitute | substitute("pattern", "replacement value") | A filter which replaces the first match to the pattern with the replacement value. | The first argument for the expression is the pattern the second argument is the replacement text. | substitute("JBAS", "EAP") |
substituteAll | substituteAll("pattern", "replacement value") | A filter which replaces all matches of the pattern with the replacement value. | The first argument for the expression is the pattern the second argument is the replacement text. | substituteAll("JBAS", "EAP") |
List Log Files and Reading Log Files
Log files can be listed and viewed via management operations. The log files allowed to be viewed are intentionally limited to files that exist in the jboss.server.log.dir and are associated with a known file handler. Known file handler types include file-handler, periodic-rotating-file-handler and size-rotating-file-handler. The operations are valid in both standalone and domain modes.
List Log Files
The logging subsystem has a log-file resource off the subsystem root resource and off each logging-profile resource to list each log file.
Read Log File
The read-log-file operation is available on each log-file resource. This operation has 4 optional parameters.
Name | Description |
---|---|
encoding | the encoding the file should be read in |
lines | the number of lines from the file. A value of -1 indicates all lines should be read. |
skip | the number of lines to skip before reading. |
tail | true to read from the end of the file up or false to read top down. |
FAQ
Why is there a logging.properties file?
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.
![]() | The logging.properties file is overwritten at boot and with each change to the logging subsystem. Any changes made to the file are not persisted. Any changes made to the XML configuration or via management operations will be persisted to the logging.properties file and used on the next boot. |
Web (Undertow)
Web subsystem was replaced in WildFly 8 with Undertow.
There are two main parts to the undertow subsystem, which are server and Servlet container configuration, as well as some ancillary items. Advanced topics like load balancing and failover are covered on the "High Availability Guide". The default configuration does is suitable for most use cases and provides reasonable performance settings.
Required extension:
Basic subsystem configuration example:
Dependencies on other subsystems:
IO Subsystem
Buffer cache configuration
The buffer cache is used for caching content, such as static files. Multiple buffer caches can be configured, which allows for separate servers to use different sized caches.
Buffers are allocated in regions, and are of a fixed size. If you are caching many small files then using a smaller buffer size will be better.
The total amount of space used can be calculated by multiplying the buffer size by the number of buffers per region by the maximum number of regions.
Attribute | Description |
---|---|
buffer-size | The size of the buffers. Smaller buffers allow space to be utilised more effectively |
buffers-per-region | The numbers of buffers per region |
max-regions | The maximum number of regions. This controls the maximum amount of memory that can be used for caching |
Server configuration
A server represents an instance of Undertow. Basically this consists of a set of connectors and some configured handlers.
Attribute | Description |
---|---|
default-host | the virtual host that will be used if an incoming request as no Host: header |
servlet-container | the servlet container that will be used by this server, unless is is explicitly overriden by the deployment |
Connector configuration
Undertow provides HTTP, HTTPS and AJP connectors, which are configured per server.
Common settings
The following settings are common to all connectors:
Attribute | Description |
---|---|
socket-binding | The socket binding to use. This determines the address and port the listener listens on. |
worker | A reference to an XNIO worker, as defined in the IO subsystem. The worker that is in use controls the IO and blocking thread pool. |
buffer-pool | A reference to a buffer pool as defined in the IO subsystem. These buffers are used internally to read and write requests. In general these should be at least 8k, unless you are in a memory constrained environment. |
enabled | If the connector is enabled. |
max-post-size | The maximum size of incoming post requests that is allowed. |
buffer-pipelined-data | If responses to HTTP pipelined requests should be buffered, and send out in a single write. This can improve performance if HTTP pipe lining is in use and responses are small. |
max-header-size | The maximum size of a HTTP header block that is allowed. Responses with to much data in their header block will have the request terminated and a bad request response send. |
max-parameters | The maximum number of query or path parameters that are allowed. This limit exists to prevent hash collision based DOS attacks. |
max-headers | The maximum number of headers that are allowed. This limit exists to prevent hash collision based DOS attacks. |
max-cookies | The maximum number of cookies that are allowed. This limit exists to prevent hash collision based DOS attacks. |
allow-encoded-slash | Set this to true if you want the server to decode percent encoded slash characters. This is probably a bad idea, as it can have security implications, due to different servers interpreting the slash differently. Only enable this if you have a legacy application that requires it. |
decode-url | If the URL should be decoded. If this is not set to true then percent encoded characters in the URL will be left as is. |
url-charset | The charset to decode the URL to. |
always-set-keep-alive | If the 'Connection: keep-alive' header should be added to all responses, even if not required by spec. |
disallowed-methods | A comma separated list of HTTP methods that are not allowed. HTTP TRACE is disabled by default. |
HTTP Connector
Attribute | Description |
---|---|
certificate-forwarding | If this is set to true then the HTTP listener will read a client certificate from the SSL_CLIENT_CERT header. This allows client cert authentication to be used, even if the server does not have a direct SSL connection to the end user. This should only be enabled for servers behind a proxy that has been configured to always set these headers. |
redirect-socket | The socket binding to redirect requests that require security too. |
proxy-address-forwarding | If this is enabled then the X-Forwarded-For and X-Forwarded-Proto headers will be used to determine the peer address. This allows applications that are behind a proxy to see the real address of the client, rather than the address of the proxy. |
HTTPS listener
Https listener provides secure access to the server. The most important configuration option is security realm which defines SSL secure context.
Attribute | Description |
---|---|
security-realm | The security realm to use for the SSL configuration. See Security realm examples for how to configure it: Examples |
verify-client | One of either NOT_REQUESTED, REQUESTED or REQUIRED. If client cert auth is in use this should be either REQUESTED or REQUIRED. |
enabled-cipher-suites | A list of cypher suit names that are allowed. |
AJP listener
Host configuration
The host element corresponds to a virtual host.
Attribute | Description |
---|---|
name | The virtual host name |
alias | A whitespace separated list of additional host names that should be matched |
default-web-module | The name of a deployment that should be used to serve up requests that do not match anything. |
Servlet container configuration
The servlet-container element corresponds to an instance of an Undertow Servlet container. Most servers will only need a single servlet container, however there may be cases where it makes sense to define multiple containers (in particular if you want applications to be isolated, so they cannot dispatch to each other using the RequestDispatcher. You can also use multiple Servlet containers to serve different applications from the same context path on different virtual hosts).
Attribute | Description |
---|---|
allow-non-standard-wrappers | The Servlet specification requires applications to only wrap the request/response using wrapper classes that extend from the ServletRequestWrapper and ServletResponseWrapper classes. If this is set to true then this restriction is relaxed. |
default-buffer-cache | The buffer cache that is used to cache static resources in the default Servlet. |
stack-trace-on-error | Can be either all, none, or local-only. When set to none Undertow will never display stack traces. When set to All Undertow will always display them (not recommended for production use). When set to local-only Undertow will only display them for requests from local addresses, where there are no headers to indicate that the request has been proxied. Note that this feature means that the Undertow error page will be displayed instead of the default error page specified in web.xml. |
default-encoding | The default encoding to use for requests and responses. |
use-listener-encoding | If this is true then the default encoding will be the same as that used by the listener that received the request. |
JSP configuration
Session Cookie Configuration
This allows you to change the attributes of the session cookie.
Attribute | Description |
---|---|
name | The cookie name |
domain | The cookie domain |
comment | The cookie comment |
http-only | If the cookie is HTTP only |
secure | If the cookie is marked secure |
max-age | The max age of the cookie |
Persistent Session Configuration
Persistent sessions allow session data to be saved across redeploys and restarts. This feature is enabled by adding the persistent-sessions element to the server config. This is mostly intended to be a development time feature.
If the path is not specified then session data is stored in memory, and will only be persistent across redeploys, rather than restarts.
Attribute | Description |
---|---|
path | The path to the persistent sessions data |
relative-to | The location that the path is relevant to |
Messaging
The JMS server configuration is done through the messaging-activemq subsystem. In this chapter we are going outline the frequently used configuration options. For a more detailed explanation please consult the Artemis user guide (See "Component Reference").
Required Extension
The configuration options discussed in this section assume that the the org.wildfly.extension.messaging-activemq extension is present in your configuration. This extension is not included in the standard standalone.xml and standalone-ha.xml configurations included in the WildFly distribution. It is, however, included with the standalone-full.xml and standalone-full-ha.xml configurations.
You can add the extension to a configuration without it either by adding an <extension module="org.wildfly.extension.messaging-activemq"/> element to the xml or by using the following CLI operation:
Connectors
There are three kind of connectors that can be used to connect to WildFly JMS Server
- in-vm-connector can be used by a local client (i.e. one running in the same JVM as the server)
- remote-connector can be used by a remote client (and uses Netty over TCP for the communication)
- http-connector can be used by a remote client (and uses Undertow Web Server to upgrade from a HTTP connection)
JMS Connection Factories
There are three kinds of basic JMS connection-factory that depends on the type of connectors that is used.
There is also a pooled-connection-factory which is special in that it is essentially a configuration facade for both the inbound and outbound connectors of the the Artemis JCA Resource Adapter. An MDB can be configured to use a pooled-connection-factory (e.g. using @ResourceAdapter). In this context, the MDB leverages the inbound connector of the Artemis JCA RA. Other kinds of clients can look up the pooled-connection-factory in JNDI (or inject it) and use it to send messages. In this context, such a client would leverage the outbound connector of the Artemis JCA RA. A pooled-connection-factory is also special because:
- It is only available to local clients, although it can be configured to point to a remote server.
- As the name suggests, it is pooled and therefore provides superior performance to the clients which are able to use it. The pool size can be configured via the max-pool-size and min-pool-size attributes.
- It should only be used to send (i.e. produce) messages when looked up in JNDI or injected.
- It can be configured to use specific security credentials via the user and password attributes. This is useful if the remote server to which it is pointing is secured.
- Resources acquired from it will be automatically enlisted any on-going JTA transaction. If you want to send a message from an EJB using CMT then this is likely the connection factory you want to use so the send operation will be atomically committed along with the rest of the EJB's transaction operations.
To be clear, the inbound connector of the Artemis JCA RA (which is for consuming messages) is only used by MDBs and other JCA-based components. It is not available to traditional clients.
Both a connection-factory and a pooled-connection-factory reference a connector declaration.
A remote-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.
- A connection-factory referencing a remote-connector is suitable to be used by a remote client to send messages to or receive messages from the server (assuming the connection-factory has an appropriately exported entry).
- A pooled-connection-factory looked up in JNDI or injected which is referencing a remote-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.
- A pooled-connection-factory used by an MDB which is referencing a remote-connector is suitable to consume messages from a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.
An in-vm-connector is associated with a server-id which tells the client using the connection-factory where to connect (since multiple Artemis servers can run in a single JVM).
- A connection-factory referencing an in-vm-connector is suitable to be used by a local client to either send messages to or receive messages from a local server.
- A pooled-connection-factory looked up in JNDI or injected which is referencing an in-vm-connector is suitable to be used by a local client only to send messages to a local server.
- A pooled-connection-factory used by an MDB which is referencing an in-vm-connector is suitable only to consume messages from a local server.
A http-connector is associated with the socket-binding that represents the HTTP socket (by default, named http).
- A connection-factory referencing a http-connector is suitable to be used by a remote client to send messages to or receive messages from the server by connecting to its HTTP port before upgrading to the messaging protocol.
- A pooled-connection-factory referencing a http-connector is suitable to be used by a local client to send messages to a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.
- A pooled-connection-factory used by an MDB which is referencing a http-connector is suitable only to consume messages from a remote server granted the socket-binding references an outbound-socket-binding pointing to the remote server in question.
The entry declaration of a connection-factory or a pooled-connection-factory specifies the JNDI name under which the factory will be exposed. Only JNDI names bound in the "java:jboss/exported" namespace are available to remote clients. If a connection-factory has an entry bound in the "java:jboss/exported" namespace a remote client would look-up the connection-factory using the text after "java:jboss/exported". For example, the "RemoteConnectionFactory" is bound by default to "java:jboss/exported/jms/RemoteConnectionFactory" which means a remote client would look-up this connection-factory using "jms/RemoteConnectionFactory". A pooled-connection-factory should not have any entry bound in the "java:jboss/exported" namespace because a pooled-connection-factory is not suitable for remote clients.
Since JMS 2.0, a default JMS connection factory is accessible to EE application under the JNDI name java:comp/DefaultJMSConnectionFactory. WildFly messaging subsystem defines a pooled-connection-factory that is used to provide this default connection factory. Any parameter change on this pooled-connection-factory will be take into account by any EE application looking the default JMS provider under the JNDI name java:comp/DefaultJMSConnectionFactory.
(See standalone/configuration/standalone-full.xml)
JMS Queues and Topics
JMS queues and topics are sub resources of the messaging-actively subsystem. One can define either a jms-queue or jms-topic. Each destination must be given a name and contain at least one entry in its entries element (separated by whitespace).
Each entry refers to a JNDI name of the queue or topic. Keep in mind that any jms-queue or jms-topic which needs to be accessed by a remote client needs to have an entry in the "java:jboss/exported" namespace. As with connection factories, if a jms-queue or or jms-topic has an entry bound in the "java:jboss/exported" namespace a remote client would look it up using the text after "java:jboss/exported". For example, the following jms-queue "testQueue" is bound to "java:jboss/exported/jms/queue/test" which means a remote client would look-up this {{kms-queue} using "jms/queue/test". A local client could look it up using "java:jboss/exported/jms/queue/test", "java:jms/queue/test", or more simply "jms/queue/test":
(See standalone/configuration/standalone-full.xml)
JMS endpoints can easily be created through the CLI:
A number of additional commands to maintain the JMS subsystem are available as well:
Dead Letter & Redelivery
Some of the settings are applied against an address wild card instead of a specific messaging destination. The dead letter queue and redelivery settings belong into this group:
(See standalone/configuration/standalone-full.xml)
Security Settings for Artemis addresses and JMS destinations
Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.
(See standalone/configuration/standalone-full.xml)
Security Domain for Users
By default, Artemis will use the "other" JAAS security domain. This domain is used to authenticate users making connections to Artemis and then they are authorized to perform specific functions based on their role(s) and the security-settings described above. This domain can be changed by using the security-domain, e.g.:
Using the Elytron Subsystem
You can also use the elytron subsystem to secure the messaging-activemq subsystem.
To use an Elytron security domain:
- Undefine the legacy security domain.
- Set an Elytron security domain.
![]() | You can only define either security-domain or elytron-domain, but you cannot have both defined at the same time. If neither is defined, WildFly will use the security-domain default value of other, which maps to the other legacy security domain. |
Cluster Authentication
If the Artemis server is configured to be clustered, it will use the cluster's user and password attributes to connect to other Artemis nodes in the cluster.
If you do not change the default value of <cluster-password>, Artemis will fail to authenticate with the error:
To prevent this error, you must specify a value for <cluster-password>. It is possible to encrypt this value by following this guide.
Alternatively, you can use the system property jboss.messaging.cluster.password to specify the cluster password from the command line.
Deployment of -jms.xml files
Starting with WildFly 8, you have the ability to deploy a -jms.xml file defining JMS destinations, e.g.:
![]() |
This feature is primarily intended for development as destinations deployed this way can not be managed with any of the provided management tools (e.g. console, CLI, etc). |
JMS Bridge
The function of a JMS bridge is to consume messages from a source JMS destination, and send them to a target JMS destination. Typically either the source or the target destinations are on different servers.
The bridge can also be used to bridge messages from other non Artemis JMS servers, as long as they are JMS 1.1 compliant.
The JMS Bridge is provided by the Artemis project. For a detailed description of the available configuration properties, please consult the project documentation.
Modules for other messaging brokers
Source and target JMS resources (destination and connection factories) are looked up using JNDI.
If either the source or the target resources are managed by another messaging server than WildFly, the required client classes must be bundled in a module. The name of the module must then be declared when the JMS Bridge is configured.
The use of a JMS bridges with any messaging provider will require to create a module containing the jar of this provider.
Let's suppose we want to use an hypothetical messaging provider named AcmeMQ. We want to bridge messages coming from a source AcmeMQ destination to a target destination on the local WildFly messaging server. To lookup AcmeMQ resources from JNDI, 2 jars are required, acmemq-1.2.3.jar, mylogapi-0.0.1.jar (please note these jars do not exist, this is just for the example purpose). We must not include a JMS jar since it will be provided by a WildFly module directly.
To use these resources in a JMS bridge, we must bundle them in a WildFly module:
in JBOSS_HOME/modules, we create the layout:
We define the module in module.xml:
Configuration
A JMS bridge is defined inside a jms-bridge section of the `messaging-activemq` subsystem in the XML configuration files.
The source and target sections contain the name of the JMS resource (connection-factory and destination) that will be looked up in JNDI.
It optionally defines the user and password credentials. If they are set, they will be passed as arguments when creating the JMS connection from the looked up ConnectionFactory.
It is also possible to define JNDI context properties in the source-context and target-context sections. If these sections are absent, the JMS resources will be looked up in the local WildFly instance (as it is the case in the target section in the example above).
Management commands
A JMS Bridge can also be managed using the WildFly command line interface:
You can also see the complete JMS Bridge resource description from the CLI:
Component Reference
The messaging-activemq subsystem is provided by the Artemis project. For a detailed description of the available configuration properties, please consult the project documentation.
- Artemis Homepage: http://activemq.apache.org/artemis/
- Artemis User Documentation: http://activemq.apache.org/artemis/docs.html
Security
The security subsystem is the subsystem that brings the security services provided by PicketBox to the WildFly 8 server instances.
If you are looking to secure the management interfaces for the management of the domain then you should read the Securing the Management Interfaces chapter as the management interfaces themselves are not run within a WildFly process so use a custom configuration.
Structure of the Security Subsystem
When deploying applications to WildFly most of the time it is likely that you would be deploying a web application or EJBs and just require a security domain to be defined with login modules to verify the users identity, this chapter aims to provide additional detail regarding the architecture and capability of the security subsystem however if you are just looking to define a security domain and leave the rest to the container please jump to the security-domains section.
The security subsystem operates by using a security context associated with the current request, this security context then makes available to the relevant container a number of capabilities from the configured security domain, the capabilities exposed are an authentication manager, an authorization manager, an audit manager and a mapping manager.
Authentication Manager
The authentication manager is the component that performs the actual authentication taking the declared users identity and their credential so that the login context for the security domain can be used to 'login' the user using the configured login module or modules.
Authorization Manager
The authorization manager is a component which can be obtained by the container from the current security context to either obtain information about a users roles or to perform an authorization check against a resource for the currently authenticated user.
Audit Manager
The audit manager from the security context is the component that can be used to log audit events in relation to the security domain.
Mapping Manager
The mapping manager can be used to assign additional principals, credentials, roles or attributes to the authenticated subject.
Security Subsystem Configuration
By default a lot of defaults have already been selected for the security subsystem and unless there is a specific implementation detail you need to change, these defaults should not require modification. This chapter describes all of the possible configuration attributes for completeness but do keep in mind that not all will need to be changed.
The security subsystem is enabled by default by the addition of the following extension: -
<extension module="org.jboss.as.security"/>
The namespace used for the configuration of the security subsystem is urn:jboss:domain:security:1.0, the configuration is defined within the <subsystem> element from this namespace.
The <subsystem> element can optionally contain the following child elements.
- security-management
- subject-factory
- security-domains
- security-properties
security-management
This element is used to override some of the high level implementation details of the PicketBox implementation if you have a need to change some of this behaviour.
The element can have any or the following attributes set, all of which are optional.
authentication-manager-class-name | Specifies the AuthenticationManager implementation class name to use. |
deep-copy-subject-mode | Sets the copy mode of subjects done by the security managers to be deep copies that makes copies of the subject principals and credentials if they are cloneable. It should be set to true if subject include mutable content that can be corrupted when multiple threads have the same identity and cache flushes/logout clearing the subject in one thread results in subject references affecting other threads. Default value is "false". |
default-callback-handler-class-name | Specifies a global class name for the CallbackHandler implementation to be used with login modules. |
authorization-manager-class-name | Attribute specifies the AuthorizationManager implementation class name to use. |
audit-manager-class-name | Specifies the AuditManager implementation class name to use. |
identity-trust-manager-class-name | Specifies the IdentityTrustManager implementation class name to use. |
mapping-manager-class-name | Specifies the MappingManager implementation class name to use. |
subject-factory
The subject factory is responsible for creating subject instances, this also makes use of the authentication manager to actually verify the caller. It is used mainly by JCA components to establish a subject. It is not likely this would need to be overridden but if it is required the "subject-factory-class-name" attribute can be specified on the subject-factory element.
security-domains
This portion of the configuration is where the bulk of the security subsystem configuration will actually take place for most administrators, the security domains contain the configuration which is specific to a deployment.
The security-domains element can contain numerous <security-domain> definitions, a security-domain can have the following attributes set:
name |
The unique name of this security domain. |
|
Although version 1.0 of the security subsystem schema contained an 'extends' attribute, security domain inheritance is not supported and this attribute should not be used. |
cache-type |
The type of authentication cache to use with this domain. If this attribute is removed no cache will be used. Allowed values are "default" or "infinispan" |
The following elements can then be set within the security-domain to configure the domain behaviour.
authentication
The authentication element is used to hold the list of login modules that will be used for authentication when this domain is used, the structure of the login-module element is:
The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:
Code |
Classname |
---|---|
Client |
org.jboss.security.ClientLoginModule |
Certificate |
org.jboss.security.auth.spi.BaseCertLoginModule |
CertificateUsers |
org.jboss.security.auth.spi.BaseCertLoginModule |
CertificateRoles |
org.jboss.security.auth.spi.CertRolesLoginModule |
Database |
org.jboss.security.auth.spi.DatabaseServerLoginModule |
DatabaseCertificate |
org.jboss.security.auth.spi.DatabaseCertLoginModule |
DatabaseUsers |
org.jboss.security.auth.spi.DatabaseServerLoginModule |
Identity |
org.jboss.security.auth.spi.IdentityLoginModule |
Ldap |
org.jboss.security.auth.spi.LdapLoginModule |
LdapExtended |
org.jboss.security.auth.spi.LdapExtLoginModule |
RoleMapping |
org.jboss.security.auth.spi.RoleMappingLoginModule |
RunAs |
org.jboss.security.auth.spi.RunAsLoginModule |
Simple |
org.jboss.security.auth.spi.SimpleServerLoginModule |
ConfiguredIdentity |
org.picketbox.datasource.security.ConfiguredIdentityLoginModule |
SecureIdentity |
org.picketbox.datasource.security.SecureIdentityLoginModule |
PropertiesUsers |
org.jboss.security.auth.spi.PropertiesUsersLoginModule |
SimpleUsers |
org.jboss.security.auth.spi.SimpleUsersLoginModule |
LdapUsers |
org.jboss.security.auth.spi.LdapUsersLoginModule |
Kerberos |
com.sun.security.auth.module.Krb5LoginModule |
SPNEGOUsers |
org.jboss.security.negotiation.spnego.SPNEGOLoginModule |
AdvancedLdap |
org.jboss.security.negotiation.AdvancedLdapLoginModule |
AdvancedADLdap |
org.jboss.security.negotiation.AdvancedADLoginModule |
UsersRoles |
org.jboss.security.auth.spi.UsersRolesLoginModule |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
See Authentication Modules for further details on the various modules listed above.
authentication-jaspi
The authentication-jaspi is used to configure a Java Authentication SPI (JASPI) provider as the authentication mechanism. A security domain can have either a <authentication> or a <authentication-jaspi> element, but not both. We set up JASPI by configuring one or more login modules inside the login-module-stack element and setting up an authentication module. Here is the structure of the authentication-jaspi element:
The login-module-stack-ref attribute value must be the name of the login-module-stack element to be used. The sub-element login-module is configured just like in the authentication part
authorization
Authorization in the AS container is normally done with RBAC (role based access control) but there are situations where a more fine grained authorization policy is required. The authorization element allows definition of different authorization modules to used, such that authorization can be checked with JACC (Java Authorization Contract for Containers) or XACML (eXtensible Access Control Markup Language). The structure of the authorization element is:
The code attribute is used to specify the implementing class of the policy module which can either be the full class name or one of the abbreviated names from the following list:
Code |
Classname |
---|---|
DenyAll |
org.jboss.security.authorization.modules.AllDenyAuthorizationModule |
PermitAll |
org.jboss.security.authorization.modules.AllPermitAuthorizationModule |
Delegating |
org.jboss.security.authorization.modules.DelegatingAuthorizationModule |
Web |
org.jboss.security.authorization.modules.WebAuthorizationModule |
JACC |
org.jboss.security.authorization.modules.JACCAuthorizationModule |
XACML |
org.jboss.security.authorization.modules.XACMLAuthorizationModule |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The flag attribute is used to specify the JAAS flag for this module and should be one of required, requisite, sufficient, or optional.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
mapping
The mapping element defines additional mapping of principals, credentials, roles and attributes for the subject. The structure of the mapping element is:
The type attribute reflects the type of mapping of the provider and should be one of principal, credential, role or attribute. By default "role" is the type used if the attribute is not set.
The code attribute is used to specify the implementing class of the login module which can either be the full class name or one of the abbreviated names from the following list:
Code |
Classname |
---|---|
PropertiesRoles |
org.jboss.security.mapping.providers.role.PropertiesRolesMappingProvider |
SimpleRoles |
org.jboss.security.mapping.providers.role.SimpleRolesMappingProvider |
DeploymentRoles |
org.jboss.security.mapping.providers.DeploymentRolesMappingProvider |
DatabaseRoles |
org.jboss.security.mapping.providers.role.DatabaseRolesMappingProvider |
LdapRoles |
org.jboss.security.mapping.providers.role.LdapRolesMappingProvider |
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded. Specifying it is not necessary if one of the abbreviated names in the above list is used.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
audit
The audit element can be used to define a custom audit provider. The default implementation used is org.jboss.security.audit.providers.LogAuditProvider. The structure of the audit element is:
The code attribute is used to specify the implementing class of the provider module.
The module attribute specifies the name of the JBoss Modules module from which the class specified by the code attribute should be loaded.
The module-option element can be repeated zero or more times to specify the module options as required for the login module being configured. It requires the name and value attributes.
jsse
The jsse element defines configuration for keystores and truststores that can be used for SSL context configuration or for certificate storing/retrieving.
The set of attributes (all of them optional) of this element are:
keystore-password | Password of the keystore |
keystore-type | Type of the keystore. By default it's "JKS" |
keystore-url | URL where the keystore file can be found |
keystore-provider | Provider of the keystore. The default JDK provider for the keystore type is used if this attribute is null |
keystore-provider-argument | String that can be passed as the argument of the keystore Provider constructor |
key-manager-factory-algorithm | Algorithm of the KeyManagerFactory. The default JDK algorithm of the key manager factory is used if this attribute is null |
key-manager-factory-provider | Provider of the KeyManagerFactory. The default JDK provider for the key manager factory algorithm is used if this attribute is null |
truststore-password | Password of the truststore |
truststore-type | Type of the truststore. By deafult it's "JKS" |
truststore-url | URL where the truststore file can be found |
truststore-provider | Provider of the truststore. The default JDK provider for the truststore type is used if this attribute is null |
truststore-provider-argument | String that can be passed as the argument of the truststore Provider constructor |
trust-manager-factory-algorithm | Algorithm of the TrustManagerFactory. The default JDK algorithm of the trust manager factory is used if this attribute is null |
trust-manager-factory-provider | Provider of the TrustManagerFactory. The default JDK provider for the trust manager factory algorithm is used if this attribute is null |
client-alias | Alias of the keystore to be used when creating client side SSL sockets |
server-alias | Alias of the keystore to be used when creating server side SSL sockets |
service-auth-token | Validation token to enable third party services to retrieve a keystore Key. This is typically used to retrieve a private key for signing purposes |
client-auth | Flag to indicate if the server side SSL socket should require client authentication. Default is "false" |
cipher-suites | Comma separated list of cipher suites to be used by a SSLContext |
protocols | Comma separated list of SSL protocols to be used by a SSLContext |
The optional additional-properties element can be used to include other options. The structure of the jsse element is:
security-properties
This element is used to specify additional properties as required by the security subsystem, properties are specified in the following format:
The property element can be repeated as required for as many properties need to be defined.
Each property specified is set on the java.security.Security class.
Web services
JBossWS components are provided to the application server through the webservices subsystem. JBossWS components handle the processing of WS endpoints. The subsystem supports the configuration of published endpoint addresses, and endpoint handler chains. A default webservice subsystem is provided in the server's domain and standalone configuration files.
Structure of the webservices subsystem
Published endpoint address
JBossWS supports the rewriting of the <soap:address> element of endpoints published in WSDL contracts. This feature is useful for controlling the server address that is advertised to clients for each endpoint.
The following elements are available and can be modified (all are optional):
Name | Type | Description |
---|---|---|
modify-wsdl-address |
boolean | This boolean enables and disables the address rewrite functionality. When modify-wsdl-address is set to true and the content of <soap:address> is a valid URL, JBossWS will rewrite the URL using the values of wsdl-host and wsdl-port or wsdl-secure-port. When modify-wsdl-address is set to false and the content of <soap:address> is a valid URL, JBossWS will not rewrite the URL. The <soap:address> URL will be used. When the content of <soap:address> is not a valid URL, JBossWS will rewrite it no matter what the setting of modify-wsdl-address. If modify-wsdl-address is set to true and wsdl-host is not defined or explicitly set to 'jbossws.undefined.host' the content of <soap:address> URL is use. JBossWS uses the requester's host when rewriting the <soap:address> When modify-wsdl-address is not defined JBossWS uses a default value of true. |
wsdl-host |
string | The hostname / IP address to be used for rewriting <soap:address>. If wsdl-host is set to jbossws.undefined.host, JBossWS uses the requester's host when rewriting the <soap:address> When wsdl-host is not defined JBossWS uses a default value of 'jbossws.undefined.host'. |
wsdl-port |
int | Set this property to explicitly define the HTTP port that will be used for rewriting the SOAP address. Otherwise the HTTP port will be identified by querying the list of installed HTTP connectors. |
wsdl-secure-port |
int | Set this property to explicitly define the HTTPS port that will be used for rewriting the SOAP address. Otherwise the HTTPS port will be identified by querying the list of installed HTTPS connectors. |
wsdl-uri-scheme | string |
This property explicitly sets the URI scheme to use for rewriting <soap:address> . Valid values are http and https. This configuration overrides scheme computed by processing the endpoint (even if a transport guarantee is specified). The provided values for wsdl-port and wsdl-secure-port (or their default values) are used depending on specified scheme. |
wsdl-path-rewrite-rule | string |
This string defines a SED substitution command (e.g., 's/regexp/replacement/g') that JBossWS executes against the path component of each <soap:address> URL published from the server. When wsdl-path-rewrite-rule is not defined, JBossWS retains the original path component of each <soap:address> URL. When 'modify-wsdl-address' is set to "false" this element is ignored. |
Predefined endpoint configurations
JBossWS enables extra setup configuration data to be predefined and associated with an endpoint implementation. Predefined endpoint configurations can be used for JAX-WS client and JAX-WS endpoint setup. Endpoint configurations can include JAX-WS handlers and key/value properties declarations. This feature provides a convenient way to add handlers to WS endpoints and to set key/value properties that control JBossWS and Apache CXF internals (see Apache CXF configuration).
The webservices subsystem provides schema to support the definition of named sets of endpoint configuration data. Annotation, org.jboss.ws.api.annotation.EndpointConfig is provided to map the named configuration to the endpoint implementation.
There is no limit to the number of endpoint configurations that can be defined within the webservices subsystem. Each endpoint configuration must have a name that is unique within the webservices subsystem. Endpoint configurations defined in the webservices subsystem are available for reference by name through the annotation to any endpoint in a deployed application.
WildFly ships with two predefined endpoint configurations. Standard-Endpoint-Config is the default configuration. Recording-Endpoint-Config is an example of custom endpoint configuration and includes a recording handler.
![]() | The Standard-Endpoint-Config is a special endpoint configuration. It is used for any endpoint that does not have an explicitly assigned endpoint configuration. |
Endpoint configs
Endpoint configs are defined using the endpoint-config element. Each endpoint configuration may include properties and handlers set to the endpoints associated to the configuration.
A new endpoint configuration can be added as follows:
Handler chains
Each endpoint configuration may be associated with zero or more PRE and POST handler chains. Each handler chain may include JAXWS handlers. For outbound messages the PRE handler chains are executed before any handler that is attached to the endpoint using the standard means, such as with annotation @HandlerChain, and POST handler chains are executed after those objects have executed. For inbound messages the POST handler chains are executed before any handler that is attached to the endpoint using the standard means and the PRE handler chains are executed after those objects have executed.
* Server inbound messages Client --> ... --> POST HANDLER --> ENDPOINT HANDLERS --> PRE HANDLERS --> Endpoint * Server outbound messages Endpoint --> PRE HANDLER --> ENDPOINT HANDLERS --> POST HANDLERS --> ... --> Client
The protocol-binding attribute must be used to set the protocols for which the chain will be triggered.
A new handler chain can be added as follows:
Handlers
JAXWS handler can be added in handler chains:
![]() | Endpoint-config handler classloading The class attribute is used to provide the fully qualified class name of the handler. At deploy time, an instance of the class is created for each referencing deployment. For class creation to succeed, the deployment classloader must to be able to load the handler class. |
Runtime information
Each web service endpoint is exposed through the deployment that provides the endpoint implementation. Each endpoint can be queried as a deployment resource. For further information please consult the chapter "Application Deployment". Each web service endpoint specifies a web context and a WSDL Url:
Component Reference
The web service subsystem is provided by the JBossWS project. For a detailed description of the available configuration properties, please consult the project documentation.
- JBossWS homepage: http://www.jboss.org/jbossws
- Project Documentation: https://docs.jboss.org/author/display/JBWS
Resource adapters
Resource adapters are configured through the resource-adapters subsystem. Declaring a new resource adapter consists of two separate steps: You would need to deploy the .rar archive and define a resource adapter entry in the subsystem.
Resource Adapter Definitions
The resource adapter itself is defined within the subsystem resource-adapters:
Note, that only JNDI bindings under java:/ or java:jboss/ are supported.
(See standalone/configuration/standalone.xml)
Using security domains
Information about using security domains can be found at https://community.jboss.org/wiki/JBossAS7SecurityDomainModel
Automatic activation of resource adapter archives
A resource adapter archive can be automatically activated with a configuration by including an META-INF/ironjacamar.xml in the archive.
The schema can be found at http://docs.jboss.org/ironjacamar/schema/ironjacamar_1_0.xsd
Component Reference
The resource adapter subsystem is provided by the IronJacamar project. For a detailed description of the available configuration properties, please consult the project documentation.
- IronJacamar homepage: http://www.jboss.org/ironjacamar
- Project Documentation: http://www.jboss.org/ironjacamar/docs
- Schema description: http://docs.jboss.org/ironjacamar/userguide/1.0/en-US/html/deployment.html#deployingra_descriptor
Batch
Overview
The batch subsystem is used to configure an environment for running batch applications. WildFly uses JBeret for it's batch implementation. Specific information about JBeret can be found in the user guide. The resource path, in CLI notation, for the subsystem is subsystem=batch-jberet.
Default Subsystem Configuration
For up to date information about subsystem configuration options see http://wildscribe.github.io/.
Security
A new security-domain attribute was added to the batch-jberet subsystem to allow batch jobs to be executed under that security domain. Jobs that are stopped as part of a suspend operation will be restarted on execution of a resume with the original user that started job.
There was a org.wildfly.extension.batch.jberet.deployment.BatchPermission added to allow a security restraint to various batch functions. The following functions can be controlled with this permission.
- start
- stop
- restart
- abandon
- read
The read function allows users to use the getter methods from the javax.batch.operations.JobOperator or read the batch-jberet deployment resource, for example /deployment=my.war/subsystem=batch-jberet:read-resource.
Deployment Descriptors
There are no deployment descriptors for configuring a batch environment defined by the JSR-352 specification. In WildFly you can use a jboss-all.xml deployment descriptor to define aspects of the batch environment for your deployment.
In the jboss-all.xml deployment descriptor you can define a named job repository, a new job repository and/or a named thread pool. A named job repository and named thread pool are resources defined on the batch subsystem. Only a named thread pool is allowed to be defined in the deployment descriptor.
Deployment Resources
Some subsystems in WildFly register runtime resources for deployments. The batch subsystem registers jobs and executions. The jobs are registered using the job name, this is not the job XML name. Executions are registered using the execution id.
The batch subsystem resource on a deployment also has 3 operations to interact with batch jobs on the selected deployment. There is a start-job, stop-job and restart-job operation. The execution resource also has a stop-job and restart-job operation.
![]() | Pro Tip You can filter jobs by an attribute on the execution resource with the query operation. View all stopped jobs |
As with all operations you can see details about the operation using the :read-operation-description operation.
![]() | Tab completion Don't forget that CLI has tab completion which will complete operations and attributes (arguments) on operations. |
JSF
- Overview
- Installing a new JSF implementation manually
- Add a module slot for the new JSF implementation JAR
- Add a module slot for the new JSF API JAR
- Add a module slot for the JSF injection JAR
- For MyFaces only - add a module for the commons-digester JAR
- Start the server
- Changing the default JSF implementation
- Configuring a JSF app to use a non-default JSF implementation
Overview
JSF configuration is handled by the JSF subsystem. The JSF subsystem allows multiple JSF implementations to be installed on the same WildFly server. In particular, any version of Mojarra or MyFaces that implements spec level 2.1 or higher can be installed. For each JSF implementation, a new slot needs to be created under com.sun.jsf-impl, javax.faces.api, and org.jboss.as.jsf-injection. When the JSF subsystem starts up, it scans the module path to find all of the JSF implementations that have been installed. The default JSF implementation that WildFly should use is defined by the default-jsf-impl-slot attribute.
Installing a new JSF implementation manually
A new JSF implementation can be manually installed as follows:
Add a module slot for the new JSF implementation JAR
- Create the following directory structure under the WILDFLY_HOME/modules directory:
WILDFLY_HOME/modules/com/sun/jsf-impl/<JSF_IMPL_NAME>-<JSF_VERSION>
For example, for Mojarra 2.2.11, the above path would resolve to:
WILDFLY_HOME/modules/com/sun/jsf-impl/mojarra-2.2.11
- Place the JSF implementation JAR in the <JSF_IMPL_NAME>-<JSF_VERSION> subdirectory. In the same subdirectory, add a module.xml file similar to the Mojarra or MyFaces template examples. Change the resource-root-path to the name of your JSF implementation JAR and fill in appropriate values for ${jsf-impl-name} and ${jsf-version}.
Add a module slot for the new JSF API JAR
- Create the following directory structure under the WILDFLY_HOME/modules directory:
WILDFLY_HOME/modules/javax/faces/api/<JSF_IMPL_NAME>-<JSF_VERSION>
- Place the JSF API JAR in the <JSF_IMPL_NAME>-<JSF_VERSION> subdirectory. In the same subdirectory, add a module.xml file similar to the Mojarra or MyFaces template examples. Change the resource-root-path to the name of your JSF API JAR and fill in appropriate values for ${jsf-impl-name} and ${jsf-version}.
Add a module slot for the JSF injection JAR
- Create the following directory structure under the WILDFLY_HOME/modules directory:
WILDFLY_HOME/modules/org/jboss/as/jsf-injection/<JSF_IMPL_NAME>-<JSF_VERSION>
- Copy the wildfly-jsf-injection JAR and the weld-core-jsf JAR from WILDFLY_HOME/modules/system/layers/base/org/jboss/as/jsf-injection/main to the <JSF_IMPL_NAME>-<JSF_VERSION> subdirectory.
- In the <JSF_IMPL_NAME>-<JSF_VERSION> subdirectory, add a module.xml file similar to the Mojarra or MyFaces template examples and fill in appropriate values for ${jsf-impl-name}, ${jsf-version}, ${version.jboss.as}, and ${version.weld.core}. (These last two placeholders depend on the versions of the wildfly-jsf-injection and weld-core-jsf JARs that were copied over in the previous step.)
For MyFaces only - add a module for the commons-digester JAR
- Create the following directory structure under the WILDFLY_HOME/modules directory:
WILDFLY_HOME/modules/org/apache/commons/digester/main
- Place the commons-digester JAR in WILDFLY_HOME/modules/org/apache/commons/digester/main. In the main subdirectory, add a module.xml file similar to this template. Fill in the appropriate value for ${version.commons-digester}.
Start the server
After starting the server, the following CLI command can be used to verify that your new JSF implementation has been installed successfully. The new JSF implementation should appear in the output of this command.
Changing the default JSF implementation
The following CLI command can be used to make a newly installed JSF implementation the default JSF implementation used by WildFly:
A server restart will be required for this change to take effect.
Configuring a JSF app to use a non-default JSF implementation
A JSF app can be configured to use an installed JSF implementation that's not the default implementation by adding a org.jboss.jbossfaces.JSF_CONFIG_NAME context parameter to its web.xml file. For example, to indicate that a JSF app should use MyFaces 2.2.12 (assuming MyFaces 2.2.12 has been installed on the server), the following context parameter would need to be added:
If a JSF app does not specify this context parameter, the default JSF implementation will be used for that app.
JMX
The JMX subsystem registers a service with the Remoting endpoint so that remote access to JMX can be obtained over the exposed Remoting connector.
This is switched on by default in standalone mode and accessible over port 9990 but in domain mode is switched off so needs to be enabled - in domain mode the port will be the port of the Remoting connector for the WildFly instance to be monitored.
To use the connector you can access it in the standard way using a service:jmx URL:
You also need to set your classpath when running the above example. The following script covers Linux. If your environment is much different, paste your script when you have it working.
!/bin/bash
# specify your WildFly folder
export YOUR_JBOSS_HOME=~/WildFly
java -classpath $YOUR_JBOSS_HOME/bin/client/jboss-client.jar:./ JMXExample
You can also connect using jconsole.
![]() | If using jconsole use the jconsole.sh and jconsole.bat scripts included in the /bin directory of the WildFly distribution as these set the classpath as required to connect over Remoting. |
In addition to the standard JVM MBeans, the WildFly MBean server contains the following MBeans:
JMX ObjectName | Description |
---|---|
jboss.msc:type=container,name=jboss-as | Exposes management operations on the JBoss Modular Service Container, which is the dependency injection framework at the heart of WildFly. It is useful for debugging dependency problems, for example if you are integrating your own subsystems, as it exposes operations to dump all services and their current states |
jboss.naming:type=JNDIView | Shows what is bound in JNDI |
jboss.modules:type=ModuleLoader,name=* | This collection of MBeans exposes management operations on JBoss Modules classloading layer. It is useful for debugging dependency problems arising from missing module dependencies |
Audit logging
Audit logging for the JMX MBean server managed by the JMX subsystem. The resource is at /subsystem=jmx/configuration=audit-log and its attributes are similar to the ones mentioned for /core-service=management/access=audit/logger=audit-log in Audit logging.
Attribute | Description |
---|---|
enabled | true to enable logging of the JMX operations |
log-boot | true to log the JMX operations when booting the server, false otherwise |
log-read-only | If true all operations will be audit logged, if false only operations that change the model will be logged |
Then which handlers are used to log the management operations are configured as handler=* children of the logger. These handlers and their formatters are defined in the global /core-service=management/access=audit section mentioned in Audit logging.
JSON Formatter
The same JSON Formatter is used as described in Audit logging. However the records for MBean Server invocations have slightly different fields from those logged for the core management layer.
It includes an optional timestamp and then the following information in the json record
Field name | Description |
---|---|
type | This will have the value jmx meaning it comes from the jmx subsystem |
r/o | true if the operation has read only impact on the MBean(s) |
booting | true if the operation was executed during the bootup process, false if it was executed once the server is up and running |
version | The version number of the WildFly instance |
user | The username of the authenticated user. |
domainUUID | This is not currently populated for JMX operations |
access | This can have one of the following values: *NATIVE - The operation came in through the native management interface, for example the CLI *HTTP - The operation came in through the domain HTTP interface, for example the admin console *JMX - The operation came in through the JMX subsystem. See JMX for how to configure audit logging for JMX. |
remote-address | The address of the client executing this operation |
method | The name of the called MBeanServer method |
sig | The signature of the called called MBeanServer method |
params | The actual parameters passed in to the MBeanServer method, a simple Object.toString() is called on each parameter. |
error | If calling the MBeanServer method resulted in an error, this field will be populated with Throwable.getMessage() |
Deployment Scanner
The deployment scanner is only used in standalone mode. Its job is to monitor a directory for new files and to deploy those files. It can be found in standalone.xml:
You can define more deployment-scanner entries to scan for deployments from more locations. The configuration showed will scan the JBOSS_HOME/standalone/deployments directory every five seconds. The runtime model is shown below, and uses default values for attributes not specified in the xml:
The attributes are
Name | Type | Description |
---|---|---|
name | STRING | The name of the scanner. default is used if not specified |
path | STRING | The actual filesystem path to be scanned. Treated as an absolute path, unless the 'relative-to' attribute is specified, in which case the value is treated as relative to that path. |
relative-to | STRING | Reference to a filesystem path defined in the "paths" section of the server configuration, or one of the system properties specified on startup. In the example above jboss.server.base.dir resolves to JBOSS_HOME/standalone |
scan-enabled | BOOLEAN | If true scanning is enabled |
scan-interval | INT | Periodic interval, in milliseconds, at which the repository should be scanned for changes. A value of less than 1 indicates the repository should only be scanned at initial startup. |
auto-deploy-zipped | BOOLEAN | Controls whether zipped deployment content should be automatically deployed by the scanner without requiring the user to add a .dodeploy marker file. |
auto-deploy-exploded | BOOLEAN | Controls whether exploded deployment content should be automatically deployed by the scanner without requiring the user to add a .dodeploy marker file. Setting this to 'true' is not recommended for anything but basic development scenarios, as there is no way to ensure that deployment will not occur in the middle of changes to the content. |
auto-deploy-xml | BOOLEAN | Controls whether XML content should be automatically deployed by the scanner without requiring a .dodeploy marker file. |
deployment-timeout | LONG | Timeout, in seconds, a deployment is allows to execute before being canceled. The default is 60 seconds. |
Deployment scanners can be added by modifying standalone.xml before starting up the server or they can be added and removed at runtime using the CLI
You can also change the attributes at runtime, so for example to turn off scanning you can do
Core Management
Overview
The core management subsystem is composed services used to manage the server or monitor its status.
The core management subsystem configuration may be used to:
- register a listener for a server lifecycle events.
- list the last configuration changes on a server.
Lifecycle listener
You can create an implementation of org.wildfly.extension.core.management.client.ProcessStateListener which will be notified on running and runtime configuration state changes thus enabling the developer to react to those changes.
In order to use this feature you need to create your own module then configure and deploy it using the core management subsystem.
For example let's create a simple listener :
To compile it you need to depend on the org.wildfly.core:wildfly-core-management-client maven module. Now let's add the module to the wildfly modules :
module add --name=org.simple.lifecycle.events.listener --dependencies=org.wildfly.extension.core-management-client --resources=/home/ehsavoie/dev/demo/simple-listener/target/simple-process-state-listener.jar
Now we can register or listener :
/subsystem=core-management/process-state-listener=simple-listener:add(class=org.simple.lifecycle.events.listener.SimpleListener, module=org.simple.lifecycle.events.listener, properties={file=/home/wildfly/tmp/events.txt})
Configuration changes
You can use the core management subsystem to enable and configure an in-memory history of the last configuration changes.
For example to track the last 5 configuration changes let's active this :
/subsystem=core-management/service=configuration-changes:add(max-history=5)
Now we can list the last configuration changes :
/subsystem=core-management/service=configuration-changes:list-changes() { "outcome" => "success", "result" => [{ "operation-date" => "2016-12-05T11:05:12.867Z", "access-mechanism" => "NATIVE", "remote-address" => "/127.0.0.1", "outcome" => "success", "operations" => [{ "address" => [ ("subsystem" => "core-management"), ("service" => "configuration-changes") ], "operation" => "add", "max-history" => 5, "operation-headers" => { "caller-type" => "user", "access-mechanism" => "NATIVE" } }] }] }
Simple configuration subsystems
The following subsystems currently have no configuration beyond its root element in the configuration
The presence of each of these turns on a piece of functionality:
Name | Description |
---|---|
jaxrs | Enables the deployment and functionality of JAX-RS applications |
jdr | Enables the gathering of diagnostic data for use in remote analysis of error conditions. Although the data is in a simple format and could be useful to anyone, primarily useful for JBoss EAP subscribers who would provide the data to Red Hat when requesting support |
pojo | Enables the deployment of applications containing JBoss Microcontainer services, as supported by previous versions of JBoss Application Server |
sar | Enables the deployment of .SAR archives containing MBean services, as supported by previous versions of JBoss Application Server |