Chapter 9. Embedding a Server for Offline Configuration
You can embed a JBoss EAP standalone server or host controller process inside the management CLI process. This allows you to configure the server without it being visible on the network. A common use of this feature is for initial configuration of the server, such as managing security-related settings or avoiding port conflicts, prior to the server being online.
This direct, local administration of a JBoss EAP installation through the management CLI does not require a socket-based connection. You can use the management CLI with the embedded server in a way that is consistent with interacting with a remote JBoss EAP server. All of the standard management CLI commands that you can use to administer a remote server are available.
Start an Embedded Standalone Server
You can launch a standalone server locally using the management CLI to modify standalone configuration without launching an additional process or opening network sockets.
The following procedure launches the management CLI, starts an embedded standalone server, modifies configuration, and then stops the embedded server.
Launch the management CLI.
$ EAP_HOME/bin/jboss-cli.sh
Launch the embedded standalone server.
Passing in the
--std-out=echo
parameter prints the standard output to the terminal.embed-server --std-out=echo
Perform the desired operations.
/socket-binding-group=standard-sockets/socket-binding=management-http:write-attribute(name=port,value=9991)
Stop the embedded server.
stop-embedded-server
This stops the embedded server and returns you to your management CLI session. If you want to exit the management CLI session as well, you can use the
quit
command.
Specifying the Server Configuration
By default, the embedded server will use the standalone.xml
configuration file. You can use the --server-config
parameter to specify a different configuration file to use.
embed-server --server-config=standalone-full-ha.xml
Starting in Admin-only Mode
By default, the embedded server is started in admin-only
mode, which will start services related to server administration, but will not start other services or accept end-user requests. This is useful for the initial configuration of the server.
You can start the embedded server in the normal running mode by setting the --admin-only
parameter to false.
embed-server --admin-only=false
You can also change the running mode using the reload
command.
reload --start-mode=normal
Controlling Standard Output
You can control how to handle standard output from the embedded server. By default, standard output is discarded, but you could find the output in the server log. You can pass in --std-out=echo
to have server output appear with the management CLI output.
embed-server --std-out=echo
Boot Timeout
By default, the embed-server
command blocks indefinitely waiting for the embedded server to fully start. You can specify the time to wait in seconds using the --timeout
parameter. A value less than 1
will return as soon as the embedded server reaches a point where it can be managed by the CLI.
embed-server --timeout=30
Starting with a Blank Configuration
When starting an embedded server, you can specify to start with an empty configuration. This is useful if you want to build the entire server configuration using management CLI commands.
embed-server --server-config=my-config.xml --empty-config
This command will fail if the file already exists, which helps to avoid the accidental deletion of a configuration file. You can specify to remove any existing configuration by passing in the --remove-existing
parameter.
embed-server --server-config=my-config.xml --empty-config --remove-existing
Start an Embedded Host Controller
You can launch a host controller locally using the management CLI to modify domain and host controller configuration without launching additional processes or opening network sockets.
An embedded host controller does not start any of its servers. Additionally, you can not use the --admin-only
parameter when starting an embedded host controller. It will always be launched as if it is in admin-only
mode.
The following procedure launches the management CLI, starts an embedded host controller, modifies configuration, and then stops the embedded host controller.
Launch the management CLI.
$ EAP_HOME/bin/jboss-cli.sh
Launch the embedded host controller.
Passing in the
--std-out=echo
parameter prints the standard output to the terminal.embed-host-controller --std-out=echo
Perform the desired operations.
/host=HOST_NAME:write-attribute(name=name,value=NEW_HOST_NAME)
Stop the embedded host controller.
stop-embedded-host-controller
Specifying the Host Controller Configuration
By default, the embedded host controller will use domain.xml
for domain configuration and host.xml
for host configuration. You can use the --domain-config
and --host-config
parameters to specify different configuration files to use.
embed-host-controller --domain-config=other-domain.xml --host-config=host-slave.xml
Depending on which alternative configuration file you use, you may need to set certain properties when launching the management CLI. For example,
$ EAP_HOME/bin/jboss-cli.sh -Djboss.domain.master.address=127.0.0.1
Controlling Standard Output
You can control how to handle standard output from the embedded host controller. By default, standard output is discarded, but you could find the output in the host controller’s log. You can pass in --std-out=echo
to have host controller output appear with the management CLI output.
embed-host-controller --std-out=echo
Boot Timeout
By default, the embed-host-controller
command blocks indefinitely waiting for the embedded host controller to fully start. You can specify the time to wait in seconds using the --timeout
parameter. A value less than 1
will return as soon as the embedded host controller reaches a point where it can be managed by the CLI.
embed-host-controller --timeout=30
Non-Modular Class Loading with the Management CLI
Using the EAP_HOME/bin/jboss-cli.sh
script to launch the management CLI uses a modular class loading environment. If you use the EAP_HOME/bin/client/jboss-cli-client.jar
to run the management CLI in a non-modular class loading environment, you will need to specify the root JBoss EAP installation directory.
Launch the management CLI.
$ java -jar EAP_HOME/bin/client/jboss-cli-client.jar
Start the embedded server, specifying the root installation directory.
embed-server --jboss-home=/path/to/EAP_HOME
NoteTo embed a host controller, use the
embed-host-controller
command.The embedding logic will set up an appropriate modular class loading environment for the server. The module path for the modular class loader will have a single element:
EAP_HOME/modules
.
No matter which way you launch the management CLI, the embedded server will run in a modular class loading environment.