3.4. The Management CLI

3.4.1. About the Management Command Line Interface (CLI)

The Management Command Line Interface (CLI) is a command line administration tool for JBoss EAP 6.
Use the Management CLI to start and stop servers, deploy and undeploy applications, configure system settings, and perform other administrative tasks. Operations can be performed in batch mode, allowing multiple tasks to be run as a group.

3.4.2. Launch the Management CLI

Procedure 3.7. Launch CLI in Linux or Microsoft Windows Server

    • Launch the CLI in Linux

      Run the EAP_HOME/bin/jboss-cli.sh file by entering the following at a command line:
      $ EAP_HOME/bin/jboss-cli.sh
    • Launch the CLI in Microsoft Windows Server

      Run the EAP_HOME\bin\jboss-cli.bat file by double-clicking it, or by entering the following at a command line:
      C:\>EAP_HOME\bin\jboss-cli.bat

3.4.3. Quit the Management CLI

From the Management CLI, enter the quit command:
[domain@localhost:9999 /] quit

3.4.4. Connect to a Managed Server Instance Using the Management CLI

Procedure 3.8. Connect to a Managed Server Instance

  • Run the connect command

    From the Management CLI, enter the connect command:
    [disconnected /] connect
    Connected to domain controller at localhost:9999
    • Alternatively, to connect to a managed server when starting the Management CLI on a Linux system, use the --connect parameter:
      $ EAP_HOME/bin/jboss-cli.sh --connect
    • The --connect parameter can be used to specify the host and port of the server. To connect to the address 192.168.0.1 with the port value 9999 the following would apply:
      $ EAP_HOME/bin/jboss-cli.sh --connect --controller=192.168.0.1:9999

3.4.5. Obtain Help with the Management CLI

Summary

Sometimes you might need guidance if you need to learn a CLI command or feel unsure about what to do. The Management CLI features a help dialog with general and context-sensitive options. (Note that the help commands dependent on the operation context require an established connection to either a standalone or domain controller. These commands will not appear in the listing unless the connection has been established.)

  1. For general help

    From the Management CLI, enter the help command:
    [standalone@localhost:9999 /] help
  2. Obtain context-sensitive help

    From the Management CLI, enter the help -commands extended command:
    [standalone@localhost:9999 /] help --commands
  3. For a more detailed description of a specific command, enter the command, followed by --help.
    [standalone@localhost:9999 /] deploy --help
Result

The CLI help information is displayed.

3.4.6. Use the Management CLI in Batch Mode

Summary

Batch processing allows a number of operation requests to be grouped in a sequence and executed together as a unit. If any of the operation requests in the sequence fail, the entire group of operations is rolled back.

Note

Batch mode does not support conditional statements.

Procedure 3.9. Batch Mode Commands and Operations

  1. Enter batch mode

    Enter batch mode with the batch command.
    [standalone@localhost:9999 /] batch
    Batch mode is indicated by the hash symbol (#) in the prompt.
  2. Add operation requests to the batch

    Once in batch mode, enter operation requests as normal. The operation requests are added to the batch in the order they are entered.
    Refer to Section 3.4.8, “Use Operations and Commands in the Management CLI” for details on formatting operation requests.
  3. Run the batch

    Once the entire sequence of operation requests is entered, run the batch with the run-batch command.
    [standalone@localhost:9999 / #] run-batch
    The batch executed successfully.
    Refer to Section 3.4.7, “CLI Batch Mode Commands” for a full list of commands available for working with batches.
  4. Batch commands stored in external files

    Frequently run batch commands can be stored in an external text file and can either be loaded by passing the full path to the file as an argument to the batch command or executed directly by being an argument to the run-batch command.
    You can create a batch command file using a text editor. Each command must be on a line by itself and the CLI should be able to access it.
    The following command will load a myscript.txt file in the batch mode. All commands in this file will now be accessible to be edited or removed. New commands can be inserted. Changes made in this batch session do not persist to the myscript.txt file.
    [standalone@localhost:9999 /] batch --file=myscript.txt
    The following will instantly run the batch commands stored in the file myscript.txt
    [standalone@localhost:9999 /] run-batch --file=myscript.txt
Result

The entered sequence of operation requests is completed as a batch.

3.4.7. CLI Batch Mode Commands

This table provides a list of valid batch commands that can be used in the JBoss EAP 6 CLI. These commands can only be used to work with batches.

Table 3.2. CLI Batch Mode Commands

Command Name Description
list-batch List of the commands and operations in the current batch.
edit-batch-line line-number edited-command Edit a line in the current batch by providing the line number to edit and the edited command. Example: edit-batch-line 2 data-source disable --name=ExampleDS.
move-batch-line fromline toline Re-order the lines in the batch by specifying the line number you want to move as the first argument and its new position as the second argument. Example: move-batch-line 3 1.
remove-batch-line linenumber Remove the batch command at the specified line. Example: remove-batch-line 3.
holdback-batch [batchname]
You can postpone or store a current batch by using this command. Use this if you want to suddenly execute something in the CLI outside the batch. To return to this heldback batch, simply type batch again at the CLI command line.
If you provide a batchname while using holdback-batch command the batch will be stored under that name. To return to the named batch, use the command batch batchname. Calling the batch command without a batchname will start a new (unnamed) batch. There can be only one unnamed heldback batch.
To see a list of all heldback batches, use the batch -l command.
discard-batch Dicards the currently active batch.

3.4.8. Use Operations and Commands in the Management CLI

Procedure 3.10. Create, Configure and Execute Requests

  1. Construct the operation request

    Operation requests allow for low-level interaction with the management model. They provide a controlled way to edit server configurations. An operation request consists of three parts:
    • an address, prefixed with a slash (/).
    • an operation name, prefixed with a colon (:).
    • an optional set of parameters, contained within parentheses (()).
    1. Determine the address

      The configuration is presented as a hierarchical tree of addressable resources. Each resource node offers a different set of operations. The address specifies which resource node to perform the operation on. An address uses the following syntax:
      /node-type=node-name
      • node-type is the resource node type. This maps to an element name in the configuration XML.
      • node-name is the resource node name. This maps to the name attribute of the element in the configuration XML.
      • Separate each level of the resource tree with a slash (/).
      Refer to the configuration XML files to determine the required address. The EAP_HOME/standalone/configuration/standalone.xml file holds the configuration for a standalone server and the EAP_HOME/domain/configuration/domain.xml and EAP_HOME/domain/configuration/host.xml files hold the configuration for a managed domain.

      Note

      Running the CLI commands in Domain Mode requires host and server specification. For example, /host=master/server=server-one/subsystem=logging

      Example 3.5. Example operation addresses

      To perform an operation on the logging subsystem, use the following address in an operation request:
      /subsystem=logging
      To perform an operation on the Java datasource, use the following address in an operation request:
      /subsystem=datasources/data-source=java
    2. Determine the operation

      Operations differ for each different type of resource node. An operation uses the following syntax:
      :operation-name
      • operation-name is the name of the operation to request.
      Use the read-operation-names operation on any resource address in a standalone server to list the available operations.

      Example 3.6. Available operations

      To list all available operations for the logging subsystem, enter the following request for a standalone server:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-names
      {
          "outcome" => "success",
          "result" => [
              "add",
              "read-attribute",
              "read-children-names",
              "read-children-resources",
              "read-children-types",
              "read-operation-description",
              "read-operation-names",
              "read-resource",
              "read-resource-description",
              "remove",
              "undefine-attribute",
              "whoami",
              "write-attribute"
          ]
      }
    3. Determine any parameters

      Each operation may require different parameters.
      Parameters use the following syntax:
      (parameter-name=parameter-value)
      • parameter-name is the name of the parameter.
      • parameter-value is the value of the parameter.
      • Multiple parameters are separated by commas (,).
      To determine any required parameters, perform the read-operation-description command on a resource node, passing the operation name as a parameter. Refer to Example 3.7, “Determine operation parameters” for details.

      Example 3.7. Determine operation parameters

      To determine any required parameters for the read-children-types operation on the logging subsystem, enter the read-operation-description command as follows:
      [standalone@localhost:9999 /] /subsystem=logging:read-operation-description(name=read-children-types)
      {
          "outcome" => "success",
          "result" => {
              "operation-name" => "read-children-types",
              "description" => "Gets the type names of all the children under the selected resource",
              "reply-properties" => {
                  "type" => LIST,
                  "description" => "The children types",
                  "value-type" => STRING
              },
              "read-only" => true
          }
      }
  2. Enter the full operation request

    Once the address, operation, and any parameters have been determined, enter the full operation request.

    Example 3.8. Example operation request

    [standalone@localhost:9999 /] /subsystem=web/connector=http:read-resource(recursive=true)
Result

The management interface performs the operation request on the server configuration.

3.4.9. Use if-else Control Flow with the Management CLI

The Management CLI supports if-else control flow, which allows you to choose which set of commands and operations to execute based on a condition. The if condition is a boolean expression which evaluates the response of the management command or operation specified after the of keyword.
Expressions can contain any of the following items:
  • Conditional operators (&&, ||)
  • Comparison operators (>, >=, <, <=, ==, !=)
  • Parentheses to group and prioritize expressions

Example 3.9. Using an if statement with Management CLI commands

This example attempts to read the system property test. If outcome is not success (meaning that the property does not exist), then the system property will be added and set to true.
if (outcome != success) of /system-property=test:read-resource
    /system-property=test:add(value=true)
end-if
The condition above uses outcome, which is returned when the CLI command after the of keyword is executed, as shown below:
[standalone@localhost:9999 /] /system-property=test:read-resource
{
    "outcome" => "failed",
    "failure-description" => "JBAS014807: Management resource '[(\"system-property\" => \"test\")]' not found",
    "rolled-back" => true
}

Example 3.10. Using an if-else statement with Management CLI commands

This example checks the launch type of the server process (STANDALONE or DOMAIN) and issues the appropriate CLI command to enable the ExampleDS datasource.
if (result == STANDALONE) of /:read-attribute(name=launch-type)
    /subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true)
else
    /profile=full/subsystem=datasources/data-source=ExampleDS:write-attribute(name=enabled, value=true)
end-if
Management CLI commands with if-else control flow can be specified in a file (one per line) and passed to the jboss-cli.sh script to be executed non-interactively.
EAP_HOME/bin/jboss-cli.sh --connect --file=CLI_FILE

Note

The use of nested if-else statements is not supported.

3.4.10. Management CLI Configuration Options

The Management CLI configuration file - jboss-cli.xml - is loaded each time the CLI is started. It must be located either in the directory $EAP_HOME/bin or a directory specified in the system property jboss.cli.config.
default-controller
Configuration of the controller to which to connect if the connect command is executed without any parameters.

default-controller Parameters

host
Hostname of the controller. Default: localhost.
port
Port number on which to connect to the controller. Default: 9999.
validate-operation-requests
Indicates whether the parameter list of the operation requests is to be validated before the requests are sent to the controller for execution. Type: Boolean. Default: true.
history
This element contains the configuration for the commands and operations history log.

history Parameters

enabled
Indicates whether or not the history is enabled. Type: Boolean. Default: true.
file-name
Name of the file in which the history is to be stored. Default = .jboss-cli-history.
file-dir
Directory in which the history is to be stored. Default = $USER_HOME
max-size
Maximum size of the history file. Default: 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 or let the resolution happen on the server side. Type: Boolean. Default = false.
connection-timeout
The time allowed to establish a connection with the controller. Type: Integer. Default: 5000 seconds.
ssl
This element contains the configuration for the Key and Trust stores used for SSL.

Warning

Red Hat recommends that you explicitly disable SSL in favor of TLSv1.1 or TLSv1.2 in all affected packages.

ssl Parameters

vault
Type: vaultType
key-store
Type: string.
key-store-password
Type: string.
alias
Type: string
key-password
Type: string
trust-store
Type: string.
trust-store-password
Type: string.
modify-trust-store
If set to true, the CLI will prompt the user when unrecognised certificates are received and allow them to be stored in the truststore. Type: Boolean. Default: true.

vaultType

If neither code nor module are 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 codein the module specified by 'module'.
code
Type: String.
module
Type: String
silent
Specifies if informational and error messages are to be output to the terminal. Even if the false is specified, the messages will still be logged using the logger if its configuration allows and/or if the output target was specified as part of the command line using >. Default: False.

3.4.11. Reference of Management CLI Commands

Summary

The topic Section 3.4.5, “Obtain Help with the Management CLI” describes how to access the Management CLI help features, including a help dialogue with general and context sensitive options. The help commands are dependent on the operation context and require an established connection to either a standalone or domain controller. These commands will not appear in the listing unless the connection has been established.

Table 3.3. 

Command Description
batch Starts the batch mode by creating a new batch or, depending on the existing held back batches, re-activates one. If there are no held back batches this command, when invoked without arguments, will start a new batch. If there is an unnamed held back batch, this command will re-activate it. If there are named held back batches, they can be activated by executing this command with the name of the held back batch as the argument.
cd Changes the current node path to the argument. The current node path is used as the address for operation requests that do not contain the address part. If an operation request does include the address, the included address is considered relative to the current node path. The current node path may end on a node-type. In that case, to execute an operation specifying a node-name would be sufficient, such as logging:read-resource.
clear Clears the screen.
command Allows you to add new, remove and list existing generic type commands. A generic type command is a command that is assigned to a specific node type and which allows you to perform any operation available for an instance of that type. It can also modify any of the properties exposed by the type on any existing instance.
connect Connects to the controller on the specified host and port.
connection-factory Defines a connection factory.
data-source Manages JDBC datasource configurations in the datasource subsystem.
deploy Deploys the application designated by the file path or enables an application that is pre-existing but disabled in the repository. If executed without arguments, this command will list all the existing deployments.
echo
Available from JBoss EAP 6.4, the echo command outputs to the console the specified text. The text is output verbatim so the use of variables is not available.
Example:
echo Phase one complete
help Displays the help message. Can be used with the --commands argument to provide context sensitive results for the given commands.
history Displays the CLI command history in memory and displays a status of whether the history expansion is enabled or disabled. Can be used with arguments to clear, disable and enable the history expansion as required.
jms-queue Defines a JMS queue in the messaging subsystem.
jms-topic Defines a JMS topic in the messaging subsystem.
ls List the contents of the node path. By default the result is printed in columns using the whole width of the terminal. Using the -l switch will print results on one name per line.
pwd Prints the full node path of the current working node.
quit Terminates the command line interface.
read-attribute Prints the value and, depending on the arguments, the description of the attribute of a managed resource.
read-operation Displays the description of a specified operation, or lists all available operations if none is specified.
undeploy Undeploys an application when run with the name of the intended application. Can be run with arguments to remove the application from the repository also. Prints the list of all existing deployments when executed without an application specified.
version Prints the application server version and environment information.
xa-data-source Manages JDBC XA datasource configuration in the datasource subsystem.

3.4.12. Reference of Management CLI Operations

Exposing operations in the Management CLI

Operations in the Management CLI can be exposed by using the read-operation-names operation described in the topic Section 3.5.5, “Display the Operation Names using the Management CLI”. The operation descriptions can be exposed by using the read-operation-descriptions operation described in the topic Section 3.5.4, “Display an Operation Description using the Management CLI”.

Table 3.4. Management CLI operations

Operation Name Description
add-namespace Adds a namespace prefix mapping to the namespaces attribute's map.
add-schema-location Adds a schema location mapping to the schema-locations attribute's map.
delete-snapshot Deletes a snapshot of the server configuration from the snapshots directory.
full-replace-deployment Add previously uploaded deployment content to the list of content available for use, replace existing content of the same name in the runtime, and remove the replaced content from the list of content available for use. Refer to link for further information.
list-snapshots Lists the snapshots of the server configuration saved in the snapshots directory.
read-attribute Displays the value of an attribute for the selected resource.
read-children-names Displays the names of all children under the selected resource with the given type.
read-children-resources Displays information about all of a resource's children that are of a given type.
read-children-types Displays the type names of all the children under the selected resource.
read-config-as-xml Reads the current configuration and displays it in XML format.
read-operation-description Displays the details of an operation on the given resource.
read-operation-names Displays the names of all the operations for the given resource.
read-resource Displays a model resource's attribute values along with either basic or complete information about any child resources.
read-resource-description Displays the description of a resource's attributes, types of children and operations.
reload Reloads the server by shutting all services down and restarting.
remove-namespace Removes a namespace prefix mapping from the namespaces attribute map.
remove-schema-location Removes a schema location mapping from the schema-locations attribute map.
replace-deployment Replace existing content in the runtime with new content. The new content must have been previously uploaded to the deployment content repository.
resolve-expression Operation that accepts an expression as input or a string that can be parsed into an expression, and resolves it against the local system properties and environment variables.
resolve-internet-address Takes a set of interface resolution criteria and finds an IP address on the local machine that matches the criteria, or fails if no matching IP address can be found.
server-set-restart-required Puts the server into a restart-required mode
shutdown Shuts down the server via a call to System.exit(0).
start-servers Starts all configured servers in a Managed Domain that are not currently running.
stop-servers Stops all servers currently running in a Managed Domain.
take-snapshot Takes a snapshot of the server configuration and saves it to the snapshots directory.
upload-deployment-bytes Indicates that the deployment content in the included byte array should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
upload-deployment-stream Indicates that the deployment content available at the included input stream index should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
upload-deployment-url Indicates that the deployment content available at the included URL should be added to the deployment content repository. Note that this operation does not indicate the content should be deployed into the runtime.
validate-address Validates the operation's address.
write-attribute Sets the value of an attribute for the selected resource.

3.4.13. Property Substitution in the Management CLI

JBoss EAP 6 supports the use of preset element and property expressions in the Management Commmand Line Interface. These expressions will be resolved to their defined values during the execution of the command.
The following properties can be substituted with expressions:
  • the operation address part of the operation request (as node types and/or names);
  • operation name;
  • operation parameter names;
  • header names and values;
  • command names;
  • command argument names.
By default, the 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 client and have it send the resolved values to the server, complete the following procedure.

Procedure 3.11. Enable Property Substitution in the Management CLI

  1. Open the file EAP_HOME/bin/jboss-cli.xml.
  2. Locate the resolve-parameter-values parameter and change the value to true (the default is false).
    <!-- whether to resolve system properties specified as command argument or operation parameter values in the Management CLI VM before sending the operation requests to the controller -->
        <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.
Refer to Section 3.4.10, “Management CLI Configuration Options” for other Management CLI configuration options.
Be aware that system values used in Management CLI commands must have already been defined. You must include the --properties=/path/to/file.properties argument or one or more -Dkey=VALUE parameters, 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 syntax ${MY_VAR}.

Example 3.11. Example: Using properties in Management CLI commands

/subsystem=datasources/data-source=${datasourcename}:add(connection-url=jdbc:oracle:thin:@server:1521:ora1, jndi-name=java:/jboss/${name}, driver-name=${drivername})