Chapter 6. Configuring the Management CLI

Certain aspects of the management CLI can be customized in its configuration file, jboss-cli.xml. This file must be located either in the EAP_HOME/bin directory or in a custom directory specified with the jboss.cli.config system property.

The following elements can be configured in the jboss-cli.xml file.

default-protocol
The default protocol to use when controller addresses are supplied without one. The default is remote+http. If port 9990 is used and no protocol is specified, the protocol will automatically default to remoting unless you set the use-legacy-override attribute to false.
default-controller

Configuration of the controller to which to connect if the connect command is executed without any parameters. If the management CLI is started with the argument --controller= or controller=, then the value specified in the argument overrides the default-controller definition from the configuration.

  • protocol - Protocol name of the controller. If one is not provided, the value of default-protocol will be used.
  • host - Host name of the controller. The default is localhost.
  • port - Port number on which to connect to the controller. The default value is 9990.
controllers

You can define connection controller aliases in the jboss-cli.xml file. For example:

<!-- The default controller to connect to when 'connect' command is executed w/o arguments -->
<default-controller>
    <host>localhost</host>
    <port>9990</port>
</default-controller>
<!-- CLI connection controller aliases -->
<controllers>
    <controller name="ServerOne">
        <protocol>remoting</protocol>
        <host>192.168.3.45</host>
        <port>9990</port>
    </controller>
    <controller name="ServerTwo">
        <protocol>http-remoting</protocol>
        <host>192.168.3.46</host>
    </controller>
</controllers>

The name attribute of controller element should be used as a value to --controller= argument. For example, --controller=ServerTwo.

validate-operation-requests
Whether to validate the parameter list of operation requests before sending the requests to the controller for execution. The default is true.
history

The configuration for the CLI command history log.

  • enabled - Whether or not the history is enabled. The default is true.
  • file-name - The file name in which the history will be stored. The default is .jboss-cli-history.
  • file-dir - The directory in which the history is to be stored. The default is the user’s home directory.
  • max-size - The maximum number of commands stored in the history file. The default is 500.
resolve-parameter-values
Whether to resolve system properties specified as command argument (or operation parameter) values before sending the operation request to the controller. The default is false.
connection-timeout
The time in milliseconds allowed to establish a connection with the controller. The default is 5000.
ssl

The configuration for the keystores and truststores used for SSL.

Warning

Red Hat recommends that SSLv2, SSLv3, and TLSv1.0 be explicitly disabled in favor of TLSv1.1 or TLSv1.2 in all affected packages.

  • vault - The vault configuration. If neither code nor module is specified, the default implementation will be used. If code is specified but not module, it will look for the specified class in the Picketbox module. If module and code are specified, it will look for the class specified by code in the module specified by 'module'.
  • key-store - The keystore.
  • key-store-password - The keystore password.
  • alias - The alias.
  • key-password - The key password.
  • trust-store - The truststore.
  • trust-store-password - The truststore password.
  • modify-trust-store - If set to true, the CLI will prompt the user when unrecognized certificates are received and allow them to be stored in the truststore. The default is true.
silent
Whether to write informational and error messages to the terminal. The default is false.
access-control
Whether the management-related commands and attributes should be filtered for the current user based on the permissions the user has been granted. For example, if true, tab completion will hide commands and attributes that the user is not allowed to access. The default is true.
echo-command
Whether to include the prompt and command in the output for commands executed in non-interactive mode. The default is false.
command-timeout
The maximum time, in seconds, to wait for a command to complete. A value of 0 means no timeout. By default, there is no timeout.
output-json
Whether to display operation responses in pure JSON format. By default, operation responses are displayed in DMR format.
color-output

Whether to print the CLI log output in color based on the log message output type. The available colors are black, blue, cyan, green, magenta, red, white, and yellow.

  • enabled - Whether or not the color output is enabled. The default is true.
  • error-color - Defaults to red.
  • warn-color - Defaults to yellow.
  • success-color - Defaults to default, which is the terminal’s default foreground color.
  • required-color - Defaults to magenta.
  • workflow-color - Defaults to green.
  • prompt-color - Defaults to blue.

6.1. Property Substitution

JBoss EAP supports the use of preset element and property expressions in the management CLI. These expressions will be resolved to their defined values during the execution of the command.

You can substitute expressions for the following properties:

  • the operation address part of the operation request (for example, node types or names)
  • operation name
  • operation parameter names
  • header names and values
  • command names
  • command argument names

By default, the management CLI performs property substitution for every line except for argument or parameter values. Argument and parameter values are resolved in the server at runtime. If you require property substitution for argument or parameter values to occur in the management CLI and have it send the resolved values to the server, complete the following steps.

  1. Edit the management CLI configuration file: EAP_HOME/bin/jboss-cli.xml.
  2. Set the resolve-parameter-values parameter to true (the default is false).

    <resolve-parameter-values>true</resolve-parameter-values>

This element only affects operation request parameter values and command argument values. It does not impact the rest of the command line. This means system properties present on the command line will be resolved during the parsing of the line regardless of what the value of resolve-parameter-values element is, unless it is a parameter/argument value.

System property values used in management CLI commands must have already been defined in order to be resolved. You must either pass in a properties file (--properties=/path/to/file.properties) or property value pairs (-Dkey=value) when starting your management CLI instance. The properties file uses a standard KEY=VALUE syntax.

Property keys are denoted in your management CLI commands using the ${MY_VAR} syntax, for example:

/host=${hostname}/server-config=${servername}:add(group=main-server-group)

See Configuring the Management CLI for other jboss-cli.xml configuration options.

6.2. Creating Aliases

You can define aliases for the CLI commands and operations during a CLI session using the alias command.

The following example creates a new CLI command alias named read_undertow to read the resources in the undertow subsystem using the alias command:

alias read_undertow='/subsystem=undertow:read-resource'
Note

Alias names can only contain alphanumeric characters and underscores.

To test the creation of read_undertow alias, type the alias name in the management CLI:

read_undertow

The result will be:

{
    "outcome" => "success",
    "result" => {
        "default-security-domain" => "other",
        "default-server" => "default-server",
        "default-servlet-container" => "default",
        "default-virtual-host" => "default-host",
        "instance-id" => expression "${jboss.node.name}",
        "statistics-enabled" => false,
        "buffer-cache" => {"default" => undefined},
        "configuration" => {
            "filter" => undefined,
            "handler" => undefined
        },
        "server" => {"default-server" => undefined},
        "servlet-container" => {"default" => undefined}
    }
}

To view a list of all available aliases, use the alias command:

alias

The result will be:

alias read_undertow='/subsystem=undertow:read-resource'

To remove an alias, use the unalias command:

unalias read_undertow
Note

The aliases are stored in the .aesh_aliases file within the user’s home folder.

6.3. .jbossclirc Configuration File

JBoss EAP contains the runtime configuration .jbossclirc file, which helps you to initialize the environment when a new session is launched. This file is located in EAP_HOME/bin/ directory. The example provided in the file can be used as a template for user-specific environment setup. The .jbossclirc file is ideal for storing global CLI variables.

The content of the .jbossclirc file is a list of CLI supported commands and operations. This file is executed when a new management CLI session is launched but before the control is given to the user. If there are system properties specified with --properties argument, then the .jbossclirc file is executed after the properties have been set.

Example .jbossclirc File

set console=/subsystem=logging/console-handler=CONSOLE
Note

When using the --connect or -c argument, .jbossclirc is executed before the client is actually connected to the server.

The following locations will be checked for the presence of the .jbossclirc file in the following order:

  1. If the system property jboss.cli.rc is defined, its value will be considered a path to the file.
  2. User’s working directory as defined by the user.dir system property.
  3. The EAP_HOME/bin directory.

6.4. Using Variables

Using the Set Command

You can define a certain path of the server model to a variable using the set command. For example:

set s1=/host=master/server=server-one

This is useful in a managed domain as you can include references to host and profiles using variables to easily replicate scripts on different servers. For example:

$s1/subsystem=datasources/data-source=ExampleDS:test-connection-in-pool
Note

The variables are referenced using $.

Using the Unset Command

You can remove the variable by using the unset command:

unset prod_db

Using the jbossclirc File

To use the variable across CLI session, you can include these variables in the .jbossclirc file. This file is located in the EAP_HOME/bin/ directory.

For example:

set s1=/host=master/server=server-one
set s2=/host=master/server=server-two

Now, restart the management CLI and issue a set command to check the available variables:

set

The output will be:

s1=/host=master/server=server-one
s2=/host=master/server=server-two

The variables may appear in any part of a command line and resolved during the command line parsing phase. In this example, the prod_db variable will be resolved to a datasource:

$prod_db/statistics=jdbc:read-resource

Using the Echo Command

Use the echo command to check the value of a variable:

echo $prod_db

The output will be:

/subsystem=datasources/data-source=ExampleDS

Example

The following general examples show where the variables may appear and that the entire command line may consist of variables:

$prod_db:$op($param=$param_value)
$cmd --$param=$param_value
Note

The variables help you in CLI scripting.