Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

2. The JBoss ON CLI Command Syntax

The JBoss ON CLI is a shell and interpreter so that commands and statements can be executed interactively against the JBoss ON server. Scripts stored in files can also be executed, so it is possible to automate operations for the JBoss ON server.

2.1. The CLI Script

The CLI script is run directly from its cli-install-dir/bin directory. There are two files associated with launching the JBoss ON CLI:
  • A script (rhq-cli.sh|bat)
  • A file of environment variables (rhq-cli-env.sh|bat)
    The environment variables in the rhq-cli-env.sh|bat file use defaults that are reasonable for most deployments, so this file usually does not need to be edited. It is possible to reset variables to point a server that doesn't follow the default installation, such as a virtual machine or a non-default JVM. The comments at the top of the rhq-cli-env.|bat file contain a detailed list of available environment variables.

    Important

    Do not edit the rhq-cli.sh|bat file. Only set environment variables through the terminal or in the rhq-cli-env.sh|bat file, not the script itself.

Note

Be sure to set the correct path to the Java 6 installation in the RHQ_CLI_JAVA_HOME or the RHQ_CLI_JAVA_EXE_FILE_PATH variable.
The rhq-cli.sh|bat script has the following general syntax: 
rhq-cli.sh|bat options
It is possible to launch the CLI script without any arguments, including specifying a username. This opens the CLI client without connecting to the server. 
[jsmith@server bin]$ cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh
RHQ - RHQ Enterprise Remote CLI 
unconnected$
While scripts can be executed without logging in, most of the functionality of the CLI is unavailable. To truly use the JBoss ON CLI, log into the server as a JBoss ON user, either by passing a username and password or by using the login command after starting the CLI. 
[jsmith@server bin]$ rhq-cli -u rhqadmin -p rhqadmin
The CLI provides two modes of operation: interactive and non-interactive.
Interactive mode executes an individual statement. Interactive mode provides a simple environment for prototyping, testing, learning, and discovering features of the CLI.
Non-interactive mode loads a specified script file and executes multiple commands in sequence. Non-interactive mode provides the capability to automate tasks such as collecting metrics on managed resources or executing a scheduled operation.

Important

These native commands, like quit, are available only in interactive mode. They cannot be used in a script when the CLI is used in non-interactive mode, such as when running a script from file. In these instances, use the Java method.
After logging in, any commands (covered in Section 2.3, “Interactive CLI Commands”) can be passed to the server.

Important

Whatever user you run the CLI as — meaning, whatever system user runs the rhq-cli.sh script — must have write access to the logs/ directory for the CLI.
If the CLI is installed as root, for example, then a regular user cannot run the CLI; it fails with write errors.

2.2. CLI Script Options

Both rhq-cli.bat and rhq-cli.sh scripts accept the options listed in Table 1, “Command-Line Options”.

Table 1. Command-Line Options

Short Option Long Option Description
-h --help Displays the help text of the command line options of the CLI.
-u --user The username used to log into the JBoss ON server.
-p --password The password used to log into the JBoss ON server.
-P Displays a password prompt where input is not echoed backed to the screen.
-s --host The JBoss ON server against which the CLI executes commands. Defaults to localhost.
-t --port The port on which the JBoss ON server is accepting HTTP requests. The default is 7080.
-c --command A command to be executed. The command must be encased in double quotes. The CLI will exit after the command has finished executing.
-f --file The full path and filename of a script to execute.
--args-style Indicates the style or format of arguments passed to the script.
-v --version Displays CLI and JBoss ON server version information once connected to the CLI.
--transport Determines whether or not SSL will be used for the communication layer protocol between the CLI and the JBoss ON server. If not specified the value is determined from the {port} option. If you use a port that ends in 443, SSL will be used. You only need to explicitly specify the transport when your JBoss ON server is listening over SSL on a port that does not end with 443.

2.3. Interactive CLI Commands

Some native commands are included in the org.rhq.enterprise.client.commands inside the CLI JAR itself. These commands are part of the CLI itself. Other input in the JBoss ON CLI is passed through the JavaScript interpreter to the server; these commands are passed to the CLI module.

Important

These native commands are available only in interactive mode. They cannot be used in a script when the CLI is used in non-interactive mode, such as when running a script from file. In these instances, you must use the Java method.

2.3.1. login

Logs into a JBoss ON server with the specified username and password.
Optionally, the hostname (or IP address) and port can be specified. The hostname defaults to localhost, and the port defaults to 7080.
It is also possible to specify a transport protocol, which sets whether to use SSL to communicate with the server. If the transport is not given, then the CLI evaluates the transport based on the port. A port ending in 443 automatically uses SSL, while all other ports use standard connections. The only reason to explicitly set a transport method is if the server is listening over SSL over a port which does not end in 443. 
login username password [host] [port]
The login command can be used in a module script or with the rhq-cli.sh --f option.

2.3.2. logout

Logs off of the JBoss ON server without existing from the CLI. 
logout
The logout command can be used in a module script or with the rhq-cli.sh --f option.

2.3.3. quit

Exits the CLI. 
quit
This only works when the CLI is running interactively. In a script, use java.lang.System.exit.

2.3.4. record

Records user input commands to a file. This is very useful if you are running the CLI interactively to test a new script that will later be run non-interactively in the CLI or as an alert server-side script. 
record [-b | -e] [-a] -f filename
Option Description
-b, --start
Specify this option to start recording.
-e, --end
Specify this option to stop recording.
-a, --append
Appends output to the end of a file. If not specified, output will be written starting at the beginning of the file.
-f, --file
The file where output will be written.

2.3.5. exec (deprecated)

Note

While an external script can be loaded into the CLI session using the exec command, this method of loading custom scripts and functions is deprecated. It is recommended that developers use a CommonJS module script. The default location for module scripts is cliRoot/rhq-remoting-cli-4.9.0.JON320GA/samples/modules.
Executes a statement or a script with the specified file name. A statement wraps onto multiple lines using backslashes.
Option Description
-f, --file
The full path filename of the script to execute. The full path must be given, or the CLI cannot locate the script.
-s, --style=named|indexed
Indicates the style or format of arguments passed to the script. It must have a value of either indexed or named.