-
Language:
English
-
Language:
English
Red Hat Training
A Red Hat training course is available for Red Hat JBoss Operations Network
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
andy
, 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)