Red Hat

OpenSSL support with WildFly

The upcoming WildFly 11 release includes support for OpenSSL. This provides two main advantages over JSSE:

  • Support for ALPN on all JDK’s

  • Significantly improved performance compared to JSSE

Setting up OpenSSL

In general for Linux based systems all that is required is to install a recent version of OpenSSL using your systems package manager. The OpenSSL support will search the library path, and use whatever version of OpenSSL it finds. The same applies to MacOS when OpenSSL has been installed using brew (the system default OpenSSL installation is too old).

For windows and for custom OpenSSL locations you need to specify the location via a system property, org.wildfly.openssl.path. If this is set then Wildfly will search for OpenSSL in the directory specified. If you have multiple versions of OpenSSL in the same directory and need to specify the precise file to use you can instead use org.wildfly.openssl.path.ssl and org.wildfly.openssl.path.crypto to specify the path to libssl and libcrypto respectively.

As Wildfly uses dynamic linking this should work with any OpenSSL version from 1.0.1 onwards (however for security reasons it is recommended to always use the most up to date 1.1.x or 1.0.x version that is available, as older versions may have unpatched vulnerabilities).

Setting up Wildfly with Security Realms

As Wildfly supports SSL out of the box with dynamically generated self signed certificates all that is required is to change the protocol in use. Doing this is as simple as running a single command in the CLI:

/core-service=management/security-realm=ApplicationRealm/server-identity=ssl:write-attribute(name=protocol, value=openssl.TLS)

Other valid values are openssl.TLSv1.1 and openssl.TLSv1.2, which limit the minimum TLS version to 1.1 and 1.2 respectively.

Once this is done you can use OpenSSL by simply pointing your browser to https://localhost:8443. You should see the following message in the log that tells you that OpenSSL is in use:

09:01:04,150 INFO  [org.wildfly.openssl.SSL] (MSC service thread 1-6) WFOPENSSL0002 OpenSSL Version OpenSSL 1.0.2l  25 May 2017

Setting up Wildfly with Elytron

As Elytron is not used by default there is a little bit more work involved in setting it up. Elytron does not support auto generation of SSL certificates, so for the sake of this example I am going to assume that the keystore is located at standalone/configuration/application.keystore (the same location that the auto generated keystore is placed, if you just want a self signed certificate for testing purposes you can simply connect to https://localhost:8443 with the default configuration and one will be generated for you).

In order to set up SSL using Elytron run the following commands (note that this is just to use JSSE, the OpenSSL config will come later).

/subsystem=elytron/key-store=server:add(path=application.keystore, relative-to=jboss.server.config.dir, credential-reference={clear-text=password}, type=jks)
/subsystem=elytron/key-manager=server:add(key-store=server, credential-reference={clear-text=password}, algorithm=SunX509)
/subsystem=elytron/server-ssl-context=server:add(key-manager=server, protocols=[TLSv1.2])
/subsystem=undertow/server=default-server/https-listener=https:write-attribute(name=ssl-context, value=server)

If you point your browser at https://localhost:8443 you should now have a working Elytron based SSL config. Once you have verified that this has worked we now need to change it to use OpenSSL. To do this we change the ordering of the providers in the elytron combined-providers, which means that OpenSSL will now take precedence:

/subsystem=elytron/aggregate-providers=combined-providers:list-add(index=0, name=providers, value=openssl)
/subsystem=elytron/aggregate-providers=combined-providers:list-remove(index=2, name=providers)

You should now have OpenSSL working with Elytron.

Messaging features in WildFly 11

WildFly 11 is integrating Apache ActiveMQ Artemis 1.5 to provides its messaging features.

New features

With the integration of Artemis 1.5, WildFly has udpated its messaging-activemq subsystem to provides new Artemis features through WildFly management model.

The two new main features are the JDBC Store and the configuration for ActiveMQ client thread pools.

JDBC Store

The JDBC store is an alternative to Artemis File journal that uses a SQL database to store broker state (messages, addresses and other application state) instead of files.

It relies on a data-source resource configured in the datasources subsystem to connect to the database.

To use a JDBC store in WildFly, you need to configure the journal-datasource attribute on its server resource that corresponds to a JDBC DataSource configured in the datasources subsystem:

[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default:write-attribute(name=journal-datasource, value=ExampleDS)

Configuration of ActiveMQ client thread pools

Artemis uses thread pools for its clients that are running inside the application server. They can now be configured in the messaging-activemq subsystem to ensure that their sizes fit the application deployed in WildFly:

<subsystem xmlns="urn:jboss:domain:messaging-activemq:1.1">
  <global-client thread-pool-max-size="${}"
    scheduled-thread-pool-max-size="${}" />
  <server ...>
By default, the maximum size for client thread pool is not defined. In that case, Artemis will configure them to be 8 x the number of available processors.

Message-Driven Beans Features

We have also added new features for Message-Driven Beans (MDBs) related to their use in a cluster of Artemis brokers.

Full support for Clustered Singleton MDB

When an MDB is identified as a clustered singleton and deployed in a cluster, it will always be active only on one node at a time. When the server node fails or is shut down, the clustered singleton MDB is activated on a different node and starts consuming messages on that node.

The messaging-clustering-singleton quickstart demonstrates how to setup and configure MDB to support clustered singleton.

Rebalancing of all inbound MDB connections

WildFly 11 provides the rebalanceConnections activation configuration property for MDBs. This parameter allows for rebalancing of all inbound MDB connections when the underlying Artemis cluster topology changes so that when nodes are added/removed from the cluster, the MDB can connect to them instead of being stuck to the topology when the MDB initially connected to the cluster. This property can also be configured on the messaging-activemq’s `pooled-connection-factory resources using the rebalance-connections attribute:

[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-ra:write-attribute(name=rebalance-connections, value=true)

Generic JMS Resource Adapter 2.0

WildFly supports messaging with Artemis out of the box. It also provides the Generic JMS Resource Adapter that allows to use out of the box JMS brokers that does not provides a resource adapter (such as TIBCO EMS for example). MDBs can the connect to these external JMS brokers through the use of the Generic JMS RA. This component has been updated to support the JMS 2.0 API (provided that the external JMS broker behind it supports it).


There were also many improvements to the messaging features that were in WildFly 10.

Monitoring of JMS pooled connections

The messaging-activemq pooled-connection-factory resources now offers statistics on their pools. They must first be enabled by setting the statistics-enabled attribute to true:

[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-ra:write-attribute(name=statistics-enabled, value=true)

Once statistics are enabled, the pooled-connection-factory resource will have a statistics=pool child resource that will returns metrics on the pool used by the pooled-connection-factory:

[standalone@localhost:9990 /] /subsystem=messaging-activemq/server=default/pooled-connection-factory=activemq-ra/statistics=pool:read-resource(include-runtime)
    "outcome" => "success",
    "result" => {
        "ActiveCount" => 15,
        "AvailableCount" => 20,

Web console improvements

The management Web console that is bundled with WildFly 11 has been substantially improved to be able to manage messaging resources more efficiently.

  • JMS Bridges can now be added and managed using the Web console.

  • The Web console now displays prepared transactions for integrated Artemis brokers. You can then commit or rollback these prepared transactions from the Web console too.

Elytron integration with the messaging-activemq subsystem

The WildFly Elytron project is a security framework used to unify security across the entire application server. The elytron subsystem enables a single point of configuration for securing both applications and the management interfaces and replaces the legacy security subsystem.

The messaging-activemq subsystem has been integrated with Elytron to provide its security features (authentication and authorization).

Bug fixes

There were also many many messaging bug fixes since last WildFly release. However if you find any new issues or want to request enhancements, do not hesitate to use WildFly issue tracker.

Management Model Referential Integrity and Suggestions

A significant improvement in WildFly 11 is much better support for referential integrity when one resource in your configuration refers to another resource. Going beyond just checking that your references are correct, the server provides reference information that our CLI and the HAL web console are able to use to suggest valid values to you as you set up your configuration.

Configuration references

When you are configuring a WildFly server, a common thing you need to do is configure attributes whose value refers to the name of some other resource. A common example of this is a resource that includes a socket-binding attribute:

[standalone@localhost:9999 /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)

When you do this, it’s because the services managed by the resource you are configuring need some capabilities provided by another resource. What you’re doing is configuring which one to use. But what kind of resource that socket-binding attribute refers to may not be obvious, and what the valid values are is also not obvious. And before the rollout of improved reference support, if you got it wrong the failure you’d see could be difficult to understand.

Here, using WildFly 9 with a config where the previously unused 'ajp' socket binding config had been removed, we try and add an AJP listener to the web container:

[standalone@localhost:9990 /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)
    "outcome" => "failed",
    "failure-description" => {"WFLYCTL0180: Services with missing/unavailable dependencies" => ["jboss.undertow.listener.ajp is missing [jboss.binding.ajp]"]},
    "rolled-back" => true

That error message says nothing about where to go to correct the mistake.

Worse, if you made that mistake when working with a server started in admin-only mode, that bad reference would not be detected when you entered it.

[standalone@localhost:9990 /] reload --admin-only=true
[standalone@localhost:9990 /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)
{"outcome" => "success"}

The configuration would be updated and the problem would only be detected when the server was reloaded or restarted not in admin-only mode. The server would boot but would not function correctly.

Referential Integrity Checks and Reference Suggestions

Starting in WildFly 10 and greatly expanded in WildFly 11, we’ve added reference description metadata to our resources and attributes, and we use that to proactively ensure that management operations that violate referential integrity fail immediately.

The same incorrect operation shown above will now fail immediately, with a message that gives a hint as to where you can configure the missing resource:

[standalone@embedded /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)
    "outcome" => "failed",
    "failure-description" => "WFLYCTL0369: Required capabilities are not available:; Possible registration points for this capability:
    "rolled-back" => true

The same failure will happen if the server is running in admin-only mode (with some exceptions; see "Referential Integrity Checks in an admin-only Process" below.)

If you think the resource you need already exists, but you’re not sure of its name, you can use CLI tab completion to get a list of suggestions:

[standalone@embedded /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=
http  https  management-http  management-https  txn-recovery-environment  txn-status-manager
[standalone@embedded /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=

Once the needed socket binding resource is added, it is available in the tab completion results.

[standalone@embedded /] /socket-binding-group=standard-sockets/socket-binding=ajp:add(port=8009)
{"outcome" => "success"}
[standalone@embedded /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=
ajp                       https                     management-https          txn-status-manager
http                      management-http           txn-recovery-environment
[standalone@embedded /] /subsystem=undertow/server=default-server/ajp-listener=ajp:add(socket-binding=ajp)
{"outcome" => "success"}

The HAL console will also suggest valid values by means of a pull-down:

choose socket binding

If you try and remove a resource whose capabilities are depended upon by other resources, that will also result in a failed operation:

[standalone@embedded /] /socket-binding-group=standard-sockets/socket-binding=ajp:remove
    "outcome" => "failed",
    "failure-description" => "WFLYCTL0367: Cannot remove capability '' as it is required by other capabilities:
capability 'org.wildfly.undertow.listener.ajp' requires it for attribute 'socket-binding' at address '/subsystem=undertow/server=default-server/ajp-listener=ajp'",
    "rolled-back" => true

Referential Integrity Checks in an admin-only Process

If your xml configuration file contains invalid references and you start the server normally, the server will fail to boot and the log will have an error message describing the problem. However, if you start the server with the --admin-only flag, the server boot will not fail. This is because starting in admin-only and manipulating the configuration via the CLI is the recommended way of correcting your configuration. If we didn’t allow the server to boot, the user would have no alternative to manually editing the xml.

When the server is started in this state, no operation will be rejected due to an invalid reference until all referential integrity problems have been corrected. Once the configuration reaches a state where there are no integrity issues, thereafter any changes that break integrity will be rejected. If a server is started in admin-only and has no integrity problems at boot, any changes that break integrity will be rejected. So, leniency in integrity checks is only enabled when the server’s configuration at boot has problems.

Further Work

The referential integrity functionality discussed here first began to appear in WildFly 10, but it’s use was greatly expanded in WildFly 11, and the use of it to drive CLI tab completion and HAL pulldowns is new in 11. But still, we don’t yet have complete coverage of all capabilities subsystems provide, although the bulk of cases are covered, particularly those involve configuration attributes. Rollout of the use of capabilities will continue in future WildFly releases.

More Information

If you are interested in learning more about how the capabilities and requirements system works from the point of view of someone working on developing WildFly, please see the Working with WildFly Capabilities document in the WildFly documentation.

back to top