Skip to end of metadata
Go to start of metadata

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. This defaults to true, however it is disabled in the default configurations.

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.

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 8 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:

  1. Change to, or create, an empty temporary directory.
  2. Create a META-INF subdirectory.
  3. Create a META-INF/services subdirectory.
  4. Create a META-INF/services/java.sql.Driver file which contains one line - the fully-qualified class name of the JDBC driver.
  5. 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

Deployment of -ds.xml files

Starting with WildFly 8, you have the ability to deploy a -ds.xml file following the schema:

http://www.ironjacamar.org/doc/schema/datasources_1_1.xsd

It is mandatory to use a reference to an already deployed / defined <driver> entry.

This feature is primarily intended for development, and thus has a few limitations to be aware of. It can not be altered in any of the management interfaces (consle, CLI, etc). Only limited runtime information is available. Also, password vaults and security domains are not deployable, so these can not be bundled with a datasource deployment.

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.

Messaging

The JMS server configuration is done through the messaging subsystem. In this chapter we are going outline the frequently used configuration options. For a more detailed explanation please consult the HornetQ user guide (See "Component Reference"). 

Connectors

There are three kind of connectors that can be used to connect to WildFly JMS Server

  • invm-connector can be used by a local client (i.e. one running in the same JVM as the server)
  • netty-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 HornetQ 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 HornetQ 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 HornetQ 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 HornetQ 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 netty-connector is associated with a socket-binding which tells the client using the connection-factory where to connect.

  • A connection-factory referencing a netty-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 netty-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.
  • pooled-connection-factory used by an MDB which is referencing a netty-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 HornetQ servers can run in a single JVM).

  • 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.  
  • 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.
  • 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.
  • 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 subsystem.  They are defined in the jms-destinations section.  One can define either a jms-queue or jms-topic.  Each destination must be given a name and contain at least one entry element.

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 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 jms-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 HornetQ addresses and JMS destinations

Security constraints are matched against an address wildcard, similar to the DLQ and redelivery settings.  Note: Multiple roles are separated by spaces.

(See standalone/configuration/standalone-full.xml)

Security Domain for Users

By default, HornetQ will use the "other" JAAS security domain.  This domain is used to authenticate users making connections to HornetQ 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 security-domain, e.g.:

Cluster Authentication

If the HornetQ server is configured to be clustered (<clustered>true</clustered>), it will use the <cluster-user> and <cluster-password> attributes to connect to other HornetQ nodes in the cluster.

If you do not change the default value of <cluster-password>, HornetQ 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 HornetQ JMS servers, as long as they are JMS 1.1 compliant.

The JMS Bridge is provided by the HornetQ 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` 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 context section. If the context section is 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 subsystem is provided by the HornetQ project. For a detailed description of the available configuration properties, please consult the project documentation.

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.
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

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.

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.
  • minimum level must be less than ERROR and the maximum level must be greater than DEBUG

    levelRange(ERROR, DEBUG)

  • minimum level must be less than or equal to ERROR and the maximum level must be greater than DEBUG

    levelRange[ERROR, DEBUG)

  • minimum level must be less than or equal to ERROR and the maximum level must be greater or equal to INFO

    levelRange[ERROR, INFO]
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, periodic-size-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.

CLI command and output

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.
CLI command and output

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.

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.
extends
The optional name of a security domain extended by this security domain.
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.

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 8 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 8 folder
export YOUR_JBOSS_HOME=~/WildFly8

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 8 distribution as these set the classpath as required to connect over Remoting.

In addition to the standard JVM MBeans, the WildFly 8 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 8. 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()

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.

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.
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

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
Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.