6. Common Actions with JBoss ON CLI Scripts

Important

The remote API cannot be run from a client inside an application server. For example, the remote API cannot be run from a client inside an EAP instance; it fails with errors like the following: 
Caused by: java.lang.IllegalArgumentException: interface
org.rhq.enterprise.server.auth.SubjectManagerRemote is not visible from class
loader
at java.lang.reflect.Proxy.getProxyClass(Proxy.java:353)
at java.lang.reflect.Proxy.newProxyInstance(Proxy.java:581)
at
org.rhq.enterprise.client.RemoteClientProxy.getProcessor(RemoteClientProxy.java:69)

6.1. Logging In

The CLI actually connects to the JBoss ON server, much like connecting through the GUI. This means that you have to log into the server before you can perform most tasks.
There are two ways to log into the server through the CLI:
  • By passing user credentials when the rhq-cli.sh script is run.
  • By using the command in a script or after starting the CLI without connecting to the server.
When logging into the server, other connection information, such as a server name and port number, can be passed with the login command.

Example 2. Logging in to a Specified Server

This connects to the CLI and logs into the JBoss ON server on 192.168.1.100 over port 70443. Because the port number ends with 443, the CLI automatically attempts to connect over SSL. 
rhq-cli.sh -u rhqadmin -p rhqadmin -s 192.168.1.100 -t 70443

Example 3. Prompting for a Password

Instead of sending the password in clear text, it is possible to have the server prompt for a password. This is probably unnecessary when connecting to a server on the local host, but it is useful if the target JBoss ON server is on a different system. 
rhq-cli.sh -u rhqadmin -P

6.2. Using Resource Proxies

The JBoss ON CLI interacts directly with the JBoss ON server through remote APIs for handling resource objects and through the domain APIs for tasks like searches.
The JBoss ON CLI itself provides another API layer that can make it easier to perform common operations. The CLI can create a resource proxy object in the CLI, and then that object uses the classes available in the ProxyFactory to interact with the remote and domain API.
One thing to remember is that proxy resources still use the remote and domain API. The proxy API just provides a simpler and clearer API on top of the remote and domain APIs that can make it easier to script many operations.

Note

The ProxyFactory is available to the JBoss ON CLI in interactive mode or when using a script file. It is also available to server scripts, such as scripts used for alerting.
The ProxyFactory gets information about a resource, which is identified in the getResource() method with the resource's ID number.
At its simplest, ProxyFactory can return a complete summary of information about the specified resource, such as its current monitoring data and traits, resource name, available metrics, available operations, content information, and child inventory, all dependent on the resource type. For example: 
rhqadmin@localhost:7080$ ProxyFactory.getResource(10001)
ResourceClientProxy_$$_javassist_0:
                               OSName: Linux
                            OSVersion: 2.6.32-220.4.1.el6.x86_64
                         architecture: x86_64
                             children:
                         contentTypes: {rpm=RPM File}
                          createdDate: Mon Feb 06 11:24:50 EST 2012
                          description: Linux Operating System
                     distributionName: Red Hat Enterprise Linux Server
                  distributionVersion: release 6.2 (Santiago)
                           freeMemory: 16.7GB
                        freeSwapSpace: 25.6GB
                              handler:
                             hostname: server.example.com
                                   id: 10001
                                 idle: 70.8%
                         measurements: [Wait Load, Used Memory, System Load, Distribution Version, Total Memory, OS Name, Free Memory, Hostname, Architecture, Distribution Name, Idle, Total Swap Space, Used Swap Space, User Load, OS Version, Free Swap Space]
                         modifiedDate: Mon Feb 06 11:24:50 EST 2012
                                 name: server.example.com
                           operations: [viewProcessList, cleanYumMetadataCache, manualAutodiscovery]
                  pluginConfiguration:
        pluginConfigurationDefinition: ConfigurationDefinition[id=10009, name=Linux]
                         resourceType: Linux
                           systemLoad: 0.0%
                          totalMemory: 23.5GB
                       totalSwapSpace: 25.6GB
                           usedMemory: 6.8GB
                        usedSwapSpace: 0.0B
                             userLoad: 15.8%
                              version: Linux 2.6.32-220.4.1.el6.x86_64
                             waitLoad: 0.0%
To truly manage resources, the ProxyFactory creates a resource proxy object.

Example 4. Defining a Platform Proxy Resource

var rhelServerOne = ProxyFactory.getResource(10001)
The methods that are available to a resource proxy depend on the resource type and the resource's own configuration. There are five major types of operations that can be performed on resource proxies:
  • Viewing basic information about the resource, such as its children
  • Getting measurement information
  • Running operations
  • Changing resource and plug-in configuration
  • Updating and retrieving content
For each resource type, methods are exposed which allow you to find and use specific information about the resource. Additionally, the proxy API includes "shortcuts" which provide one-word methods, without requiring any parameters, to perform common remote API tasks, like getting monitoring information.
The proxy API for common resource types is listed in Section 5.2, “Methods Available to Proxy Resources”.

Note

Use tab-complete in the interactive CLI to find the specific methods available for a resource type or to get the method signatures for individual methods.

Example 5. Viewing a Resource's Children

ProxyFactory has a method for all proxy objects, children, which lists all of the children for the proxy resource. 
var rhelServerOne = ProxyFactory.getResource(10001)

rhqadmin@localhost:7080$ platform.children
Array of org.rhq.bindings.client.ResourceClientProxy
[10027] Bundle Handler - Ant (Ant Bundle Handler::AntBundlePlugin)
[10026] CPU 6 (CPU::Platforms)
[10025] CPU 0 (CPU::Platforms)
[10024] CPU 5 (CPU::Platforms)
[10023] CPU 1 (CPU::Platforms)
[10022] CPU 4 (CPU::Platforms)
[10021] CPU 2 (CPU::Platforms)
[10020] CPU 3 (CPU::Platforms)
[10019] CPU 7 (CPU::Platforms)
[10018] /boot (File System::Platforms)
[10017] / (File System::Platforms)
[10016] /dev/shm (File System::Platforms)
[10015] /home (File System::Platforms)
[10014] eth1 (Network Adapter::Platforms)
[10013] eth2 (Network Adapter::Platforms)
[10012] eth0 (Network Adapter::Platforms)
[10011] lo (Network Adapter::Platforms)
[10004] postgres (Postgres Server::Postgres)
[10003] AS server.example.com RHQ Server (JBossAS Server::JBossAS)
[10002] RHQ Agent (RHQ Agent::RHQAgent)

Example 6. Viewing Resource Metrics

ProxyFactory provides a set of shortcut metrics for each individual measurement for a resource type. This corresponds to the findLiveData() method in the remote API, but it is much easier to get monitoring information quickly and it is simpler to identify what metrics are available.
To get a single measurement value, use the method for that resource type. (Get a list of all methods for a proxy object using tab-complete.) 
var jbossas = ProxyFactory.getResource(14832)
	
rhqadmin@localhost:7080$ jbossas.JVMTotalMemory
Measurement:
                name: JVM Total Memory
        displayValue: 995.3MB
	description: The total amount of memory currently available in the app server JVM for current and fut...
Alternatively, simply get a list of metrics with their current values using the measurements method: 
var rhelServerOne = ProxyFactory.getResource(10001)

rhqadmin@localhost:7080$ rhelServerOne.measurements
Array of org.rhq.bindings.client.ResourceClientProxy$Measurement
name                 displayValue                         description
-----------------------------------------------------------------------------------------------------------------------
Wait Load            0.0%                                 Percentage of all CPUs waiting on I/O
Used Memory          6.3GB                                The total used system memory
System Load          0.0%                                 Percentage of all CPUs running in system mode
Distribution Version release 6.2 (Santiago)               version of the Linux distribution
Total Memory         31.4GB                               The total system memory
OS Name              Linux                                Name that the operating system is known as
Free Memory          25.2GB                               The total free system memory
Hostname             server.example.com                   Name that this platform is known as
Architecture         x86_64                               Hardware architecture of the platform
Distribution Name    Red Hat Enterprise Linux Server      name of the Linux distribution
Idle                 92.6%                                Idle percentage of all CPUs
Total Swap Space     33.6GB                               The total system swap
Used Swap Space      0.0B                                 The total used system swap
User Load            16.7%                                Percentage of all CPUs running in user mode
OS Version           2.6.32-220.4.2.el6.x86_64            Version of the operating system
Free Swap Space      33.6GB                               The total free system swap
16 rows

Example 7. Running Operations on a Proxy

ProxyFactory has a shortcut method for every operation available for a resource.
First, get the list of operations available for the resource type using the operations method: 
var rhelServerOne = ProxyFactory.getResource(10001)

rhqadmin@localhost:7080$ rhelServerOne.operations
Array of org.rhq.bindings.client.ResourceClientProxy$Operation
name                  description
-----------------------------------------------------------------------------------------------------------------------
viewProcessList       View running processes on this system
cleanYumMetadataCache Deletes all cached package metadata
manualAutodiscovery   Run an immediate discovery to search for resources
3 rows
Then, run the given operation method. 
rhqadmin@localhost:7080$ rhelServerOne.viewProcessList();
Invoking operation viewProcessList
Configuration [11951] - null
  processList [305] {
pid   name                                        size       userTime kernelTime
------------------------------------------------------------------------------------------------------------------
1     init                                        19865600   150      10050
....
26285 httpd                                       214618112  90       80
26286 httpd                                       214618112  90       80
26288 httpd                                       214618112  110      70
26289 httpd                                       214618112  90       80
27357 java                                        4734758912 1289650  373890
30458 postgres                                    218861568  1820     27440
30460 postgres                                    180985856  1210     5330
30462 postgres                                    218984448  13080    42200
30463 postgres                                    218861568  3970     26940
30464 postgres                                    219328512  10600    15320
30465 postgres                                    181407744  18680    78760
30482 httpd                                       185905152  1660     7520
32410 bash                                        108699648  0        10
32420 java                                        6024855552 3890240  669810
305 rows
}

Example 8. Changing Configuration Properties

If the resource type supports resource configuration editing or if the resource type has plug-in connection properties, then the resource proxy has methods — editResourceConfiguration() and editPluginConfiguration(), respectively — to edit those properties.
The current configuration can be printed using the get*Configuration). For example, for the plug-in configuration: 
var rhelServerOne = ProxyFactory.getResource(10001)			 
			 
rhqadmin@localhost:7080$ rhelServerOne.getPluginConfiguration()
Configuration [10793] - null
  metadataCacheTimeout = 1800
  enableContentDiscovery = false
  yumPort = 9080
  enableInternalYumServer = false
  logs [0] {
  }
The edit*Configuration() method brings up a configuration wizard that goes through all of the properties individually and prompts to keep or change each value. The properties are even grouped according to the same organization that the JBoss ON web UI uses. For example: 
rhqadmin@localhost:7080$ rhelServerOne.editPluginConfiguration();
Non-Grouped Properties:
Group: Content
enableContentDiscovery[false]:
enableInternalYumServer[false]:
yumPort[9080]:
metadataCacheTimeout[1800]:
Group: Event Logs
[R]eview, [E]dit, Re[V]ert [S]ave or [C]ancel:
...
After each group, you have the option to revert or save the changes. Once the changes are saved, they are immediately updated on the JBoss ON server.
Keys Action
return Selects the default or existing value for a property.
ctrl-d The same as selecting the unset checkbox in the configuration UI.
ctrl-k Exits the configuration wizard.
ctrl-e Displays the help description for the current property.

Example 9. Managing Content on Resources

Some types of resources have content associated with them. These are typically EAR or WAR resources within an application server. The content file actually associated with that EAR/WAR resource is called backing content. These are usually JARs.
This content can be updated or downloaded from the resource.
To retrieve backing content (meaning, to download the JAR/EAR/WAR file), specify the filename and file path on the application server. For example: 
var contentResource = ProxyFactory.getResource(14932)
contentResource.retrieveBackingContent("/resources/backup/original.war")
To update the content for the resource, use the updateBackingContent method and specify the filename with the path on the application server to put the content and the version number of the content. For example: 
contentResource.updateBackingContent("/resources/current/new.war", "2.0")

6.3. Passing Command and Script Arguments

When connecting to the CLI using rhq-cli.sh, commands or full scripts can be passed simultaneously. This is a non-interactive way to connect to the CLI, since the CLI runs the specified command or script and then exits, rather than staying connected in interactive mode.

Example 10. Passing Variables to the Server

A single command can be passed to the CLI by using the -c. In this example, the server searches for and prints all supported resource types for the server and prints the results to resource_types.txt 
rhq-cli.sh -u rhqadmin -p rhqadmin -c "pretty.print(ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()))" > resource_types.txt
The ResourceTypeManager.findResourceTypesByCriteria(new ResourceTypeCriteria()) class invokes the findResourceTypesByCriteria operation on ResourceTypeManager. A new ResourceTypeCriteria object is passed as the argument.
Nothing has been specified on the criteria object so all resource types will be returned.
pretty is an implicit object made available to commands and scripts by the CLI. This is useful for outputting objects in a readable, tabular format which is designed for domain objects.
This single command provides a nicely formatted, text-based report of the resource types in the inventory.

Example 11. Running a Script

This executes the script file, my_script.js. The CLI terminates immediately after the script has finished executing. 
cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -f /export/myScripts/my_script.js

Example 12. Handling Script Arguments

A feature common to most 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 takes a String array as an argument. That array holds any arguments passed to the program. Similarly, arguments can be passed to CLI scripts. Arguments passed to a script can be accessed in the implicit args array: 
if (args.length < 2) {
    throw "Not enough arguments!";
}
		
for (i in args) {
     println('args[' + i + '] = ' + args[i]);
}
The custom args variable is only available if it is explicitly defined in a CLI script or if it is added as a module in the cliRoot/rhq-remoting-cli-4.9.0.JON320GA/samples/modules directory.
In addition to the traditional style of indexed-based arguments, named arguments can also be passed to a script: 
[jsmith@server ~]$ cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -s jon-server.example.com -u rhqadmin -p rhqadmin -t 7080 echo_args.js --args-style=named x=1 y=2
The echo_args.js, for example, is written to accept the two named option with the script invocation, x and y. 
for (i in args) {
     println('args[' + i + '] = ' + args[i]);
}
println('named args...');
println('x = ' + x);
println('y = ' + y);
This simple script echoes the given x and y values. 
args[0] = 1
args[1] = 2
named args...
		
x = 1
y = 2
Be aware of the following:
  • Explicitly specify that you are using named arguments with the --args-style option.
  • The values of the named arguments are still accessible through the implicit args array.
  • The named arguments, such as x and y, are bound into the script context as variables.

Example 13. Executing a Single Statement

When running the CLI interactively, commands can still be passed and executed, same as using the -c option with rhq-cli.sh. 
localhost:7080> var x = 1

Example 14. Executing a Multi-Line Statement

The CLI is a Java shell interpreter, and it can handle multi-line statements properly. To indicate a new line in the same statement, use the backslash (\) character. 
localhost:7080(rhqadmin)> for (i = 1; i < 3; ++i) { \
localhost:7080(rhqadmin)>    println(i); \
localhost:7080(rhqadmin)> }
1
2
		
localhost:7080(rhqadmin)>

Example 15. Executing a Script

To run a script from a file, use the -f option with the rhq-cli.sh|bat script.
The -f option must give the absolute location of the script, even if it is in the same directory as the rhq-cli.sh script. The CLI will not find a script with only a relative path. 
[jsmith@server ~]$ cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -u rhqadmin -p rhqadmin -s jon-server.example.com -t 7080 -f /absolute/path/to/myscript.js

Example 16. Executing a Script with Arguments

A script can be written to accept or require arguments; this is described more in Section 6.3, “Defining Arguments and Other Parameters for the CLI Scripts”. Indexed arguments can be passed simply by supplying them in the proper order, as specified in the JavaScript file. 
[jsmith@server ~]$ cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -u rhqadmin -p rhqadmin -s jon-server.example.com -t 7080 -f /absolute/path/to/myscript.js 1 2 3

Example 17. Executing a Script with Named Arguments

Script arguments can be indexed or named. 
[jsmith@server ~]$ cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -u rhqadmin -p rhqadmin -s jon-server.example.com -t 7080 --args-style=named -f /absolute/path/to/myscript.js x=1 y=2 y=3

6.4. Displaying Pretty-Print Output

The JBoss ON CLI has a special class that formats JBoss ON information into table-style output. This class (TabularWriter) is implicit for all CLI commands, so almost all output is properly formatted automatically. This class is also available as an implicit variable called pretty, which is useful when writing scripts.
For example: 
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
pretty formats any object defined in the domain (org.rhq.core.domain) package.
Simply printing the output is much less readable: 
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], 
.... 8< ....
For a single object, pretty checks for the summary information (@Summary), so that it only displays a subset of information. It then prints the summary information for the single object as a formatted list. For example: 
rhqadmin@localhost:7080$ pretty.print(resources.get(0))
Resource:
	          id: 11373
	        name: service-alpha-8
	     version: 1.0
	resourceType: service-alpha

6.5. Exporting Output

export is another implicit script variable that writes output to a specified file. exporter uses pretty.print to output all of the information to a plaintext file that matches the table-style formatting used in the interactive display. 
rhqadmin@localhost:7080$ exporter.setTarget('raw', 'output.txt')
rhqadmin@localhost:7080$ exporter.write(resources)
File IO operations like opening or closing the file are not a problem because exporter handles the IO operations.
Alternatively, exporter can write the raw resource or other information to a CSV file: 
rhqadmin@localhost:7080$ exporter.setTarget('csv', 'output.csv')
rhqadmin@localhost:7080$ exporter.write(resources)