In JBoss EAP 6 and WildFly, managing the server is a challenge. Especially with large teams, it’s important to know that everyone is working with the same server configuration, even when not all of us have access to tools like Docker or Vagrant yet.
Enter the JBoss CLI. The JBoss CLI is a batch script which can be found in %JBOSS_HOME%\bin\jboss-cli.bat (or .sh for Linux) and simplifies this task by giving a consistent way to keep configurations the same easily, both for development teams and production environments.
The CLI will start disconnected, but typing “connect” will connect it to the local running instance using default connection options. An alternative option is to supply the options “--connect” or simply “-c” when starting the CLI from the command line:
%JBOSS_HOME%\bin\jboss-cli.bat --connect %JBOSS_HOME%\bin\jboss-cli.bat -c
Other start parameters include:
|--controller=HOST:PORT||Specifies the location of the JBoss to connect to. Any standalone JBoss server or domain controller can be connected to. The default is localhost:9999.|
|--gui||Starts the CLI in GUI mode. More on this below.|
|--file=/path/to/script.cli||Specifies the path to the CLI script to run. The “cli" extension is just a convention, it could be anything.|
|--user=USERNAME||The username for the JBoss management user. This is not needed when connecting locally, only for remote servers.|
|--password=PASSWORD||The password for the JBoss management user. This is not needed when connecting locally, only for remote servers.|
|--command=CMD||This option lets you execute a single command against the CLI, without entering interactive mode.|
|--commands=CMD1,CMD2||This option (note the “s”) allows you to run multiple commands in a comma separated list. There can be no whitespace between them.|
The CLI can be used like most shells and provides tab completion. Pressing tab without having started to type a command will list available options.
A more visual way to interact with the CLI is available by supplying the --gui start parameter:
In the screenshot below, I have right-clicked the data-source=* node, and I have been presented with a list of command options. Whenever a “resource=*” is shown, that is not a real resource but a generic representation of a resource which may be created.
CLI commands generally take the following form:
First you have the CLI resource path. This can be several levels deep, so I could address the ExampleDS datasource as follows:
Following the resource path is the operation name. For ExampleDS, this could be either “write-attribute” or “undefined-attribute”.
On the second line are the operation parameters, which would just be the name of the attribute and the value to set it to.
So, for example, to set the max-pool-size of the ExampleDS, the command would be:
This can be done using the GUI too. After typing in the right value to the write-attribute operation, the cmd> box will be filled with the command:
Pressing the Submit button will open the Output tab to show the same output that you would get if run from the command line:
Note: To see the changed value, the resources attributes need to be refreshed by closing and opening the node
One “best practice” strategy for making best use of the GUI might be:
1. Use the GUI to create the appropriate commands
2. Copy and paste the commands into a new file.cli
3. Bundle commands together logically; for example, group all the JDBC related commands into a single file, then all the JMS commands into a separate file.
4. Commit the CLI script to a VCS system (e.g. Git)
This method isn't prescriptive, but may be useful to create books of grouped commands which can be shared with a team.
The CLI has a batch mode which can be used either in a script or in interactive mode. This can be used as follows:
# Remove H2 data source and driver batch /subsystem=datasources/data-source=ExampleDS:remove /subsystem=datasources/jdbc-driver=h2:remove /subsystem=datasources:remove holdback-batch h2 # Remove EJB3 batch /subsystem=ejb3:remove /extension=org.jboss.as.ejb3:remove holdback-batch ejb3 # Run batches batch h2 run-batch batch ejb3 run-batch
In the above example, it can be seen that the “batch” command starts a new batch. This batch will be an atomic transaction which means that, should any command fail, the whole batch will fail and be rolled back.
The command “holdback-batch $name” will save the commands entered in the batch to a named batch called $name, which can then be recalled by entering “batch $name”. This will recall the $name batch, and more commands can even be added at this stage, but the likely next step is to execute the batch with “run-batch”
The advantage of batches is not just their atomicity; they can also be used to group commands together logically and then re-order them very simply to make sure that prerequisite commands are run in the correct order.
Sometimes, the correct command isn’t always known ahead of time. Using the “filter” box at the bottom of the GUI is helpful, but in cases where the GUI is not available, a community user has created a reference for JBoss EAP and WildFly:
In addition, there is help available for any command by typing “$command --help” at the interactive console, for example:
There is certainly more that can be said for the JBoss CLI, but writing more blogs is still not as useful as getting hands-on and trying it out. What makes this approach to configuration so powerful is the potential for combining with DevOps tooling, like Chef, which can build out a whole environment in domain or standalone mode in minutes and with an exact, known configuration.