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

  1. Launch the management CLI. 

    $ EAP_HOME/bin/jboss-cli.sh

  2. Launch the embedded standalone server.

    Passing in the --std-out=echo parameter prints the standard output to the terminal. 

    embed-server --std-out=echo

  3. Perform the desired operations. 

    /socket-binding-group=standard-sockets/socket-binding=management-http:write-attribute(name=port,value=9991)

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

  1. Launch the management CLI. 

    $ EAP_HOME/bin/jboss-cli.sh

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

  3. Perform the desired operations. 

    /host=HOST_NAME:write-attribute(name=name,value=NEW_HOST_NAME)

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

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.

  1. Launch the management CLI. 

    $ java -jar EAP_HOME/bin/client/jboss-cli-client.jar

  2. Start the embedded server, specifying the root installation directory. 

    embed-server --jboss-home=/path/to/EAP_HOME
    Note

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