Configuring JBoss/Wildfly, Part 1

Manual Editing

Because the JBoss configuration files are in XML format and human-readable, it’s tempting to power up vi or any other text editor of your choice and modify the configuration manually. This may be a viable option if only one JBoss server instance need to be managed, for example in a developer’s environment. But as soon as many application servers have to be managed, this approach becomes daunting and error-prone. This is especially true if the application servers host different applications and need different configurations.

Because JBoss/Wildfly writes the configuration on every (regular) shutdown, manual editing of the configuration requires that the server is stopped beforehand. Otherwise manual changes are likely overwritten.

The drawbacks of manually changing the JBoss configuration files becomes even more obvious, when the application servers are upgraded to incorporate bug and security fixes. Given that the upgraded installation starts with a fresh new up-to-date JBoss/Wildfly installation package, the manual editing must be conducted again ^[2].

Because the version of the JBoss subsystems and as consequence the structure of the JBoss configuration file is different from one version to another, it’s advised against taking over the configuration file from the initial installation - doing so might work, but is never guaranteed.

JBoss CLI

The JBoss CLI is included in the JBoss/Wildfly distribution and can be found in $JBOSS_HOME/bin of the installation folder.

For the following demonstration examples, the Wildfly/JBoss server must run.

Usage

The CLI can be used interactively. For that purpose the JBoss command line can be started:

  $ cd $JBOSS_HOME

  $ ./bin/jboss-cli.sh --connect
  [standalone@localhost:9990 /] ls deployment
  rest-api.war

  [standalone@localhost:9990 /] exit
  $

The --connect option causes that the CLI to connect to the already running application server. The JBoss CLI then enters a REPL (read-evaluate-print-loop) and outputs a prompt showing the connected server. The ls deployment is an sample CLI command which lists the applications deployed to the server. The exit command leaves the JBoss CLI tool.

Commands don’t have to be typed in manually. It’s also possible to directly provide commands when calling the CLI:

$ ./bin/jboss-cli.sh --connect --command="ls deployment"
rest-api.war
$

As soon as the command is executed the JBoss CLI ends.

Alternatively to providing CLI commands on the command line, the commands can also be provided in a file. In this case it’s easy to execute a sequence of commands, which are listed in the file, e.g.:

$ ./bin/jboss-cli.sh -c --file=./commands.cli

If all CLI commands to provision a server for a specific application are provided in a file and applied by a script, we can call it Infrastructure-as-Code (IaC). This way the provisioning of JBoss/Wildfly application servers can be fully automated.

More on the usage of the JBoss/Wildfly CLI can be find in official Wildfly documentation.

CLI Commands

Sometimes it can be hard, in particular if you start with the CLI, to find the proper commands to configure the application server as desired. Sometimes articles on the Web or Cookbooks like the JBoss CLI Recipes may help. But often the proper commands are not obvious and applying the "trial and error" method may become tedious. In such situations the JBoss CLI GUI can be a great help.

Please note, that the GUI mode of JBoss CLI also requires that the application server is running. It can be started by providing the --gui parameter:

$ $JBOSS_HOME/bin/jboss-cli.sh --gui

The GUI looks (on Linux) like:

The shown example is about disabling the scanning of deployment directory, which is BTW recommended for production environments. The command in the cmd> field can be executed directly by hitting the Submit button or copied over to a command file for later execution.

After execution of the sample command:

[standalone@localhost:9990 /] /subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=false)
{"outcome" => "success"}

[standalone@localhost:9990 /]

…the application server configuration in standalone.xml contains:

...
<subsystem xmlns="urn:jboss:domain:deployment-scanner:2.0">
     <deployment-scanner path="deployments"
                         relative-to="jboss.server.base.dir"
                         scan-enabled="false"
                         scan-interval="5000"
                         runtime-failure-causes-rollback="${jboss.deployment.scanner.rollback.on.failure:false}"/>
 </subsystem>
 ...

The standalone.xml comes with XML attribute scan-enabled=true by default.

Embedded Server

The CLI tool provides a command named embed-server. This command starts an embedded server running together with the CLI. This server is started in admin-only mode, i.e. no actual applications are started and no network ports are occupied. By default the embedded server uses the standalone.xml configuration, which can be changed by --server-config or --empty-config option.

Due to the fact that no network ports are occupied by the embedded server, many parallel instances of embedded servers can run on the system, which means that many different application servers can be provisioned on the same server at the same time.

Let’s start with an example:

$ $JBOSS_HOME/bin/jboss-cli.sh
You are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.
[disconnected /] embed-server --std-out=echo
11:24:05,367 INFO  [org.jboss.modules] (CLI command executor) JBoss Modules version 2.0.0.Final
11:24:05,387 INFO  [org.jboss.as] (MSC service thread 3-4) WFLYSRV0049: WildFly Full 26.0.1.Final (WildFly Core 18.0.4.Final) starting
11:24:05,852 WARN  [org.wildfly.extension.elytron] (MSC service thread 3-5) WFLYELY00023: KeyStore file 'C:\programme\wildfly-26.0.1.Final\standalone\configuration\application.keystore' does not exist. Used blank.
11:24:05,858 INFO  [org.jboss.as.patching] (MSC service thread 3-2) WFLYPAT0050: WildFly Full cumulative patch ID is: base, one-off patches include: none
11:24:05,912 WARN  [org.wildfly.extension.elytron] (MSC service thread 3-7) WFLYELY01084: KeyStore C:\programme\wildfly-26.0.1.Final\standalone\configuration\application.keystore not found, it will be auto generated on first use with a self-signed certificate for host localhost
11:24:05,995 INFO  [org.jboss.as.server] (Controller Boot Thread) WFLYSRV0212: Resuming server
11:24:06,034 INFO  [org.jboss.as] (Controller Boot Thread) WFLYSRV0025: WildFly Full 26.0.1.Final (WildFly Core 18.0.4.Final) started in 663ms - Started 50
of 73 services (24 services are lazy, passive or on-demand)

The echo configuration of --std-out option causes the output of the embedded server to standard out, which is reasonable in an interactive session. Other possible configuration value and default is discard which wipes out the output of the embedded server. The CLI is automatically connected with the embedded server, so that we can interact with the server immediately:

[standalone@embedded /] /subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=false)
{"outcome" => "success"}

[standalone@embedded /]
[standalone@embedded /] stop-embedded-server
17:13:34,369 INFO  [org.jboss.as] (MSC service thread 1-4) WFLYSRV0050: WildFly Full 26.1.0.Final (WildFly Core 18.1.0.Final) stopped in 44ms
[disconnected /] exit
$

The provided sample command turns off scanning of the deployment folder. Then the command stop-embedded-server and exit stops the embedded application server and exits the CLI.

Embedding the server inside the CLI allows the configuration of the application server installation without starting the server.

Scripted Configuration

The embedded server can be useful for configuration from a prepared file of CLI commands as well. If we collect the CLI commands to configure JBoss/Wildfly server configuration for a specific application in a file commands.cli, scripting the configuration could looks as follows:

$ cat commands.cli
embed-server
/subsystem=deployment-scanner/scanner=default/:write-attribute(name=scan-enabled,value=false)
stop-embedded-server

$ $JBOSS_HOME/bin/jboss-cli.sh --file=commands.cli
{"outcome" => "success"}
$

Bootable JAR

The configuration of JBoss/Wildfly with the embedded server in admin-only mode is also used to set up applications packaged as Bootable JAR. See Blog Post "Wildfly Bootable JAR" if you’re interested in a detailed introduction into the Bootable JAR packaging of JBoss/Wildfly.

Conclusion

Nowadays, the JBoss CLI is the standard way to configure JBoss/Wildfly application servers. Compared to manual editing configuration files the advantages are compelling:

Keeping the logs of scripted server configuration make the provisioning process Traceable
The scripted configuration also makes the provisioning process Repeatable, e.g. for different environments or when a new release of the application sever comes up

Therefore manual editing should be the exception and the JBoss CLI always preferred.

In the next part of this mini-series, we have a closer look at some configuration options, that are lesser known but may be handy in non-standard use cases.

1. For sake of simplicity we focus on standalone server configurations, clustered application servers host their configuration under $JBOSS_HOME/domain/configuration.

2. The alternative is to upgrade the existing JBoss installation, which is possible on-premises, but not for containerized deployments into the cloud

Configuring JBoss/Wildfly, Part 1

Manual Editing

JBoss CLI

Usage

CLI Commands

Embedded Server

Scripted Configuration

Bootable JAR

Conclusion

Links