Skip to end of metadata
Go to start of metadata

Introduction

The RHQ CLI is a standalone Java application. It uses the Java Scripting API, and therefore requires Java 6 or later. The CLI offers a way to interact with RHQ programmatically, allowing developers and administrators to further integrate RHQ into their environments. Java 6 ships with the Rhino JavaScript engine, and as such, JavaScript is the supported scripting language in the CLI. A large subset of RHQ functionality is exposed in the CLI including,

Running the RHQ CLI

The CLI is a shell/interpreter that allows you to execute statements in an interactive fashion. This can be useful for prototyping. Scripts, stored in files, can be executed as well, providing the capability to develop more fully automated solutions.

Running on Windows

The RHQ CLI can be run from within a console window.

Setting Environment Variables

The rhq-cli-env.bat file, located in the <cli-install-dir>\bin directory, contains a detailed listing of the environment variables that the CLI requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important, however, to set the correct path to your Java installation.

You should not edit rhq-cli.bat - if you need to customize the launch parameters of the RHQ CLI, edit the environment variable values in rhq-cli-env.bat.

Running in a Windows Console

To run the RHQ CLI, execute the rhq-cli.bat located in <cli-install-dir>\bin directory of the installation. You can pass in any of the RHQ CLI Command Line Options.

The rhq-cli.bat script looks for specific environment variables during its execution. These variables can be modified to suit your system requirements. For example, you can point the RHQ CLI at a new JVM or you can define VM options. Note that you should not edit the rhq-cli.bat file. If you need to customize the launch parameters of the RHQ CLI, either set the environment variables at the command prompt, or edit the values in rhq-cli-env.bat. The comments at the top of the rhq-cli-env.bat file contain a detailed list of these environment variables. You do not have to set any specific variables to get the RHQ CLI to run; sensible defaults are used.

Running on Linux/Unix

The RHQ CLI can be run from within a shell of a terminal window.

Setting Environment Variables

The rhq-cli-env.sh file, located in the <cli-install-dir>/bin/ directory, contains a detailed list of the environment variables that the RHQ CLI requires to run. For most variables, sensible defaults are used and therefore do not need editing. It is important however, to set the correct path to your Java installation. Before starting the RHQ CLI, it is best to ensure that either the RHQ_CLI_JAVA_HOME or the RHQ_CLI_JAVA_EXE_FILE_PATH variable is set appropriately.

You should not edit rhq-cli.sh - if you need to customize the launch parameters of the RHQ CLI, edit the environment variable values in rhq-cli-env.sh.

Running in a Shell

To run the RHQ CLI, run the rhq-cli.sh script located in the <cli-install-dir>/bin directory of the installation. You can pass in any of the RHQ CLI Command Line Options.

RHQ CLI Command Line Options

Both rhq-cli.bat and rhq-cli.sh accept the following command line options.

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 RHQ server
-p, --password The password used to log into the RHQ server
-P Display a password prompt where input is not echoed backed to the screen
-s, --host The RHQ server against which the CLI will execute commands. Defaults to localhost.
-t, --port The port on which the RHQ server is accepting HTTP requests. Defaults to 7080.
-c, --command A command to be executed. The command must be surrounded in double quotes. The CLI will exit after the command has finished executing.
-f, --file The pathname of a script to execute. See Executing Scripts for additional information on running scripts.
-v, --version Causes the CLI and RHQ server version information to be displayed once connected to the the CLI.
--transport Determines whether or not SSL will be used for the communication layer protocol between the CLI and the RHQ 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 RHQ server is listening over SSL on a port that does not end with 443.
--args-style Indicates the style or format of arguments passed to the script. See Executing Scripts for additional information.

Examples

Below are some examples of various ways that the CLI can be invoked.

This is the simplest way to start the CLI, without any options. You will be connected to the CLI but not logged into the RHQ server. While not logged in you can execute scripts and script commands; however, most of the RHQ functionality is not available until you are logged in.


This will connect to the CLI and attempt to log you in with the specified credentials on the RHQ server running on localhost.


This will connect to the CLI, attempt to log you into the RHQ server on 192.168.1.100 that is listening on port 70443. Because the port number ends with 443, the CLI will attempt to communicate with the RHQ server over SSL using the sslservlet transport strategy.


This will connect to the CLI and prompt the user for a password.


This connects to the CLI, logs you into the RHQ server running on localhost, executes the command in quotes, redirecting the output to the file resource_types.txt. There is a quite a bit going on with that single command. Let's start with ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()). This invokes the findResourceTypesByCriteria operation on ResourceTypeManager. A new ResourceTypeCriteria object is passed as the argument. Because nothing has been specified on the criteria object, all resource types will be returned. Now let's looks at the pretty.print(...) portion. pretty is an implicit object made available to commands and scripts by the CLI. It is very useful for outputting objects in a readable, tabular format, designed with enhanced capabilities for domain objects. In review, this single command gives us a nicely formatted,text-based report of the resource types in our inventory.


This connects to the CLI and executes the script file, my_script.js. The CLI terminates immediately after the script has finished executing.

Built-in Commands

As previously stated, the CLI is built using the Java Scripting API that was introduced in Java 6. The majority of commands and scripts that you write will be executed by the underlying script engine. Built-in commands however, are native Java code and not executed by the underlying script engine. This is similar to other interpreters like Python where some modules are implemented in C and built right into the interpreter. This distinction is important because built-in commands cannot be processed by the script engine. Objects though, providing hooks into the built-in commands, are exposed to the scripting environment.

The following is a list of built-in commands along with the options and arguments that they accept. Each of the built-in commands takes a help option. Using the short form, <command> -h, will display the command syntax and a short description. Using its long form, <command> --help, will display the command syntax and a more detailed description.

login

Syntax
login <username> <password> [host port [transport]]

Description
Log into a RHQ server with the specified username and password. The host name (or IP address) and port can be optionally specified. The host name defaults to localhost and the port defaults to 7080. The transport argument is optional. It determines whether or not SSL will be used for the communication layer protocol between the CLI and the RHQ server. If not specified the value is determined from the port argument.. If you use a port that ends in 443, SSL will be used. You only need to explicitly specify the transport when your RHQ server is listening over SSL on a port that does not end with 443.

logout

Syntax
logout

Description
Log out from the RHQ server but does not exit from the CLI interpreter.

quit

Syntax
quit

Description
Exits the CLI interpreter.

version

Syntax
version

Description
Displays detailed version information about the CLI.

exec

Syntax
exec <statement> | [--args-style=<indexed|named>] -f <file> [args]

Description
Executes a statement or a script with the specified file name. A statement wraps onto multiple lines using backslashes. See below for an example.

Options

Option Description
-f, --file The file name of the script to execute. A valid file name must be specified.
--args-style Indicates the style or format of arguments passed to the script. Must have a value of either indexed or named.

Examples

executing a single statement


executing a multi-line statement


executing a named script without arguments


executing a named script with arguments


executing a named script with named arguments

record

Syntax
record [-b | -e] [-a] -f <file>

Description
Records user input commands to a file.

Options

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.

Working with the CLI

The CLI provides two modes of operation - interactive and non-interactive. In interactive mode, you can execute an individual statement, whereas in non-interactive mode, you execute an entire batch of commands in the form of a script. Non-interactive mode provides the capability to automate tasks such as collecting metrics on managed resources or executing a scheduled operation. Interactive mode provides a rich environment for prototyping, testing, learning and discovering features of the CLI, and more. In the following sections, we will take a close look at some of the features and functionality in the CLI. Unless stated otherwise, it can be assumed that the following features and functionality discussed are available in both modes of operation.

The API

The CLI makes available the entire Remote API as well as enhanced Proxy objects for writing scripts.

Implicit Variables

There are a number of variables that are bound to the script context. A number of those variables though, are available only after you have logged in. Implicit variables are listed in the table below. The last column in the table indicates whether or not accessing the variable requires login.

Variable Type Description Access reqiures login
subject org.rhq.core.domain.auth.Subject Represents the current, logged in user. For security purposes, all remote service invocations require the subject to be passed; however, the CLI will implicitly pass the subject for you. YES
pretty org.rhq.enterprise.client.TabularWriter Provides for tabular-formatted output and handles converting objects, particularly domain objects in the packages under org.rhq.core.domain, into a format suitable for display in the console. NO
unlimitedPC org.rhq.core.domain.util.PageControl TODO NO
pageControl org.rhq.core.domain.util.PageControl Used to specify paging and sorting on data retrieval operations NO
exporter org.rhq.enterprise.client.Exporter Used to export output to a file. Supported formats are plain text in tabular format and CSV. NO
ProxyFactory org.rhq.enterprise.client.utility.ResourceClientProxy.Factory TODO
rhq org.rhq.enterprise.client.Controller Exposes methods (of the same name) for the built-in commands - login, logout, quit. NO
scriptUtil org.rhq.enterprise.client.utility.ScriptUtil Provides various methods that may be useful when writing scripts NO
AlertManager org.rhq.enterprise.server.alert.AlertManagerRemote Provides an interface into the alerts subsystem YES
AlertDefinitionManager org.rhq.enterprise.server.alert.AlertDefinitionManagerRemote Provides an interface into the alerts definition subsystem YES
AvailabilityManager org.rhq.enterprise.server.measurement.AvailabilityManagerRemote Provides an interface into the measurement subsytem that can be used to determine resources' availability YES
CallTimeDataManager org.rhq.enterprise.server.measurement.CallTimeDataManagerRemote Provides an interface into the measurement subsystem for retrieving call-time metric data YES
ChannelManager org.rhq.enterprise.server.content.ChannelManagerRemote Provides an interface into the content subsystem for working with channels YES
ConfigurationManager org.rhq.enterprise.server.configuration.ConfigurationManagerRemote Provides an interface into the configuration subsystem YES
DataAccessManager org.rhq.enterprise.server.report.DataAccessRemote Provides an interface for executing user-defined queries YES
EventManager org.rhq.enterprise.server.event.EventManagerRemote Provides an interface into the events subsystem YES
MeasurementBaselineManager org.rhq.enterprise.server.measurement.MeasurementBaselineManagerRemote Provides an interface into the measurement subsystem for working with measurement baselines YES
MeasurementDataManager org.rhq.enterprise.server.measurement.MeasurementDataManagerRemote Provides an interface into the measurement subsystem for working with measurement data YES
MeasurementDefinitionManager org.rhq.enterprise.server.measurement.MeasurementDefinitionManagerRemote Provides an interface into the measurement subsystem for working with measurement definitions YES
MeasurementScheduleManager org.rhq.enterprise.server.measurement.MeasurementScheduleManagerRemote Provides an interface into the measurement subsystem for working with measurement schedules YES
OperationManager org.rhq.enterprise.server.operation.OperationManagerRemote Provides an interface into the operation subsystem YES
ResourceManager org.rhq.enterprise.server.resource.ResourceManagerRemote Provides an interface into the resource subsystem YES
ResourceGroupManager org.rhq.enterprise.server.resource.group.ResourceGroupManagerRemote Provides an interface into the resource group subsystem YES
ResourceTypeManager org.rhq.enterprise.server.resource.ResourceTypeManagerRemote Provides an interface into the resource subsystem for working with resource types YES
RoleManager org.rhq.enterprise.server.authz.RoleManagerRemote Provides an interface into the security subsystem for working with security rules and roles YES
SubjectManager org.rhq.enterprise.server.auth.SubjectManagerRemote Provides an interface into the security subsystem for working with users YES
SupportManager org.rhq.enterprise.server.support.SupportManagerRemote Provides an interface into the reporting subsystem for getting reports of managed resources YES

Auto-Imported Packages

In the Java programming language, you do not have to import classes in the java.lang package. They are automatically made available. Classes in other packages however, have to be explicitly imported. In the CLI, there are a number of classes from various packages that you are likely to use on a routine basis. For example, if I want to query resources, then I am likely use the class org.rhq.core.domain.critiera.ResourceCriteria. The CLI automatically imports packages under and including org.rhq.core.domain. This means that while we can write,

we can more succinctly write,

Auto Completor

A feature that is common to Unix and Linux shells like Bash is that of auto completion of commands. I can start typing the first few letters of a command, press the tab key, and the shell will finish it for me. The CLI provides the Auto Completor which is similar in nature.

The Auto Complete is only available in interactive mode.

The Auto Completor provides tab-completion for any object bound in the script context. In fact, if you want to see a listing of objects bound in the script context, simply press that tab key. I can also use the Auto Completor to see a list of available methods for a particular object. At the CLI prompt, type ResourceManager. followed by the tab key and you should see something like,

rhqadmin@localhost:7080$ ResourceManager.

findResourceComposites    findResourceLineage       findResourcesByCriteria   getResource
resource                  toString                  uninventoryResources

Then enter ResourceManager.f followed by the tab key. You should see something like,

rhqadmin@localhost:7080$ ResourceManager.findResource

findResourceComposites    findResourceLineage       findResourcesByCriteria
rhqadmin@localhost:7080$ ResourceManager.findResource

In the snippet above, the command prompt is displaying findResource because the Auto Complete was able to complete the line to that point. Then it displays a list of available methods. The Auto Completor can be extremely useful for discovering objects and their methods. It will also save you a lot of typing.

Script Arguments

A feature common to nearly (if not) all programming languages is the ability to pass arguments to the program to be executed. In Java, the entry point into a program is a class's main method, and it take a String array as an argument. That array holds any arguments passed to the program. In a similar fashion, arguments can be passed to CLI scripts. Arguments passed to a script can be accessed in the implict args array.

Handling Script Arguments
The args variable is only available when executing a script in non-interactive mode or with exec -f.

In addition to the traditional style of indexed-based arguments, you can also pass named arguments to a script as demonstrated in the following example.

echo_args.js

And that produces that following output,

args[0] = 1
args[1] = 2
named args...

x = 1
y = 2

There are a few key things to point out.

  • You have to explicitly specify that you are using named arguments via the --args-style option
  • The values of the named arguments are still accessible via the implicit args array
  • The named arguments, x and y, are bound into the script context as variables

Criteria Searching

All of the managers define operations for retrieving data. Most of the managers define criteria-based operations for data retrieval. The Criteria API provides a flexible framework for fine-tuned query operations. The criteria classes reside in the org.rhq.core.domain.criteria package. We will jump right into some examples to illustrate how to work with the criteria APIs. Suppose we want to look up resources in our inventory.

Basic Criteria

In this example the first thing to note is that we do not have to import the ResourceCriteria class. Recall from the Auto-Imported Packages section that the org.rhq.core.domain.criteria package is automatically imported for us. Next, take note of the method, findResourcesByCriteria. All of the criteria-based query operations are of the form findXXXByCriteria. This basic criteria search is translated into the following JPA-QL query,


As we can see from the JPA-QL query, this will fetch all committed resources in our inventory.

Sorting

Next we will modify our criteria a bit to sort the resources by plugin.


This criteria is translated into the following JPA-QL query,


To add sorting, we call criteria.addSortPluginName(). To add sorting to any criteria, you will use methods of the form addSortXXX(PageOrdering order).

Filtering

Now let's add some filtering to refine our search results. We will filter on the resource type name.

To add filtering to any criteria, you will use methods of the form addFilterXXX(). The resulting JPA-QL quyery is,


This little bit of code is all that is needed to retrieve all JBoss servers in our inventory. Let's further refine our criteria to find JBoss servers that have been registered by a particular agent.


This generates the following JPA-QL query,

Fetching Associations

After we have retrieved resources, let's look at how we can drill down into and view child resources. Consider this code,

This code will indeed print the string no child resources even if the JBoss server has child resources, which is likely. The reason for this is that lazy loading is used throughout the domain layer for one-to-many and many-to-many associations. If you are not familiar with lazy loading, take a look at the article, Some explanations on lazy loading. Since child resources are lazily loaded, we need to specify in the criteria that they should be fetched.

As you see with the call to criteria.fetchChildResources(true), all criteria methods that specify that a particular lazy association should be fetched are of the form, fetchXXX(). The output from the above is,

rhqadmin@localhost:7080$ if (resource.childResources == null) print('no child resources'); else pretty.print(resource.childResources)
id  name                                                 versio resourceType
--------------------------------------------------------------------------------------------------------
222 AlertManagerBean                                            EJB3 Session Bean
222 SchedulerBean                                               EJB3 Session Bean
222 AlertDefinitionManagerBean                                  EJB3 Session Bean
222 AlertConditionConsumerBean                                  EJB3 Session Bean
222 PartitionEventManagerBean                                   EJB3 Session Bean
222 AlertTemplateManagerBean                                    EJB3 Session Bean
223 RHQ Server Group Definition / DynaGroups Subsystem          RHQ Server Group Definition / DynaGrou
222 DiscoveryTestBean                                           EJB3 Session Bean
222 PerspectiveManagerBean                                      EJB3 Session Bean
222 ResourceAvailabilityManagerBean                             EJB3 Session Bean
222 AlertDampeningManagerBean                                   EJB3 Session Bean
218 localhost.localdomain  Embedded JBossWeb Server 2.0. 2.0.1. Embedded Tomcat Server
222 ResourceGroupManagerBean                                    EJB3 Session Bean
222 FailoverListManagerBean                                     EJB3 Session Bean
222 ResourceFactoryManagerBean                                  EJB3 Session Bean
222 AccessBean                                                  EJB3 Session Bean
222 MeasurementTestBean                                         EJB3 Session Bean
223 wstools.sh                                                  Script
222 EventManagerBean                                            EJB3 Session Bean
222 ContentSourceManagerBean                                    EJB3 Session Bean
223 RHQ Server Alerts Engine Subsystem                          RHQ Server Alerts Engine Subsystem
222 AlertConditionManagerBean                                   EJB3 Session Bean
222 ResourceMetadataManagerBean                                 EJB3 Session Bean
222 ResourceManagerBean                                         EJB3 Session Bean
222 GroupDefinitionExpressionBuilderManagerBean                 EJB3 Session Bean
222 MeasurementViewManagerBean                                  EJB3 Session Bean
218 JmsXA Connection Factory                                    ConnectionFactory
222 ResourceTypeManagerBean                                     EJB3 Session Bean
223 JBoss Cache subsystem                                1.0    JBossCacheSubsystem
218 NoTxRHQDS Datasource                                        Datasource
222 DataAccessBean                                              EJB3 Session Bean
222 AlertConditionCacheManagerBean                              EJB3 Session Bean
222 MeasurementProblemManagerBean                               EJB3 Session Bean
222 ServerManagerBean                                           EJB3 Session Bean
222 OperationHistorySubsystemManagerBean                        EJB3 Session Bean
222 ClusterManagerBean                                          EJB3 Session Bean
222 run.sh                                                      Script
...

The actual output you see will vary depending on what you have inventoried. These are the child resources of my RHQ server. The JPA-QL query that is generated looks like,


TODO Add a link to more examples (when the example docs are written)

Displaying Output

TabularWriter

TabularWriter provides for tabular-formatted output. In addition to formatting, it handles converting objects, particularly domain objects in the packages under org.rhq.core.domain, into a format suitable for display in the interactive console. Let's look at an example to illustrate the utility of TabularWriter.

rhqadmin@localhost:7080$ criteria = ResourceCriteria()
rhqadmin@localhost:7080$ criteria.addFilterResourceTypeName('service-alpha')
rhqadmin@localhost:7080$ criteria.addFilterParentResourceName('server-omega-0')
rhqadmin@localhost:7080$ resources = ResourceManager.findResourcesByCriteria(criteria)
id    name            version resourceType
----------------------------------------------------------------------------------------------------------------------
11373 service-alpha-8 1.0     service-alpha
11374 service-alpha-1 1.0     service-alpha
11375 service-alpha-0 1.0     service-alpha
11376 service-alpha-4 1.0     service-alpha
11377 service-alpha-2 1.0     service-alpha
11378 service-alpha-3 1.0     service-alpha
11379 service-alpha-5 1.0     service-alpha
11380 service-alpha-9 1.0     service-alpha
11381 service-alpha-6 1.0     service-alpha
11382 service-alpha-7 1.0     service-alpha
10 rows

The TabularWriter instance that is bound in the script context under the name pretty is implicitly invoked to display the results of ResourceManager.findResourcesByCriteria. The returned resources are displayed in very readable, tabular format. Now let's look at the output if we do not use TabularWriter.

rhqadmin@localhost:7080$ println(resources)
PageList[Resource[id=11373, type=service-alpha, key=service-alpha-8, name=service-alpha-8, version=1.0],
Resource[id=11374, type=service-alpha, key=service-alpha-1, name=service-alpha-1, version=1.0],
Resource[id=11375, type=service-alpha, key=service-alpha-0, name=service-alpha-0, version=1.0],
Resource[id=11376, type=service-alpha, key=service-alpha-4, name=service-alpha-4, version=1.0],
Resource[id=11377, type=service-alpha, key=service-alpha-2, name=service-alpha-2, version=1.0],
Resource[id=11378, type=service-alpha, key=service-alpha-3, name=service-alpha-3, version=1.0],
Resource[id=11379, type=service-alpha, key=service-alpha-5, name=service-alpha-5, version=1.0],
Resource[id=11380, type=service-alpha, key=service-alpha-9, name=service-alpha-9, version=1.0],
Resource[id=11381, type=service-alpha, key=service-alpha-6, name=service-alpha-6, version=1.0],
Resource[id=11382, type=service-alpha, key=service-alpha-7, name=service-alpha-7, version=1.0]]

For display purposes, this output is not very usable. Let's look at one more example in which we display a single entity.

rhqadmin@localhost:7080$ pretty.print(resources.get(0))
Resource:
	          id: 11373
	        name: service-alpha-8
	     version: 1.0
	resourceType: service-alpha

Notice that the formatting is different when displaying a single object. Lastly, it should be pointed out that only a subset of the properties in the Resource class are displayed. TabularWriter determines the properties to display via the Summary annotation. If a field of an entity has the @Summary annotation, TabularWriter will include it in the output.

Exporter

exporter is an implicit script variable that can assist with writing output to a file. Under the covers it uses TabularWriter; however, in addition to writing plain text in a tabular format, it also supports CSV-formatting. First, we will look at an example of exporting to a file as plain text.

rhqadmin@localhost:7080$ exporter.setTarget('raw', 'output.txt')
rhqadmin@localhost:7080$ exporter.write(resources)

Note that we do not have to worry about file IO operations like opening or closing the file. Exporter handles the IO operations for us. Now we will export the results to a CSV file.

rhqadmin@localhost:7080$ exporter.setTarget('csv', 'output.csv')
rhqadmin@localhost:7080$ exporter.write(resources)

Proxy

Resource Proxies are custom objects generated in the CLI context that simplify interacting with the remote and domain APIs. Proxies are obtained through the ProxyFactory by calling getResource() and providing a resource identifier.

From there the proxy will exhibit the behavior of a custom local interface for that resource. It will expose methods to invoke operations. There will be properties for viewing metrics that connect to the live metric system. There is also support for viewing and editing current configurations and updating and deploying content.

Running Operations

To run an operation on the proxy call the bound method representing that operation.

Configurations

The resource proxy offers access to both the connection properties and the configuration of the resource itself. Configuration data for a resource such as a datasource can be viewed and edited live.

The proxy also integrates with the resource configuration editing wizard to update configurations via a question and answer session. This interactive wizard will ask for the values of each configuration property and has some special keystrokes to simplify editing. Pressing return will select the default or existing value for a property. Pressing ctrl-d is equivalent to setting the "unset" checkbox in the configuration UI. Pressing ctrl-k will exit out of the wizard at any point. Pressing ctrl-e will display the help description for the current property. At the end of the wizard you can choose to review, save, cancel or edit the configuration again. Once you select save the configuration will be updated live on the remote resource.

Content

For resources that support backing content such as JBoss Application Server EAR and WAR resources the content features will be exposed to the proxy allowing you to retrieve or update the content behind that deployed resource.

The following will retrieve the EAR file from the agent and download it to the cli saving it as a file with the same name as the deployed file. You can also pass in a relative or fully qualified path to save the content to.

You can send a new version of the content via the following command by passing in the name of the file to send. This will deploy a new version of your custom application content and automatically increment the internal version tracking.

References

Labels:
s s Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.