Red Hat Summitこのコンテンツは選択した言語では利用できません。
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:
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
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.shscript is run. - By using the
commandin 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
rhq-cli.sh -u rhqadmin -p rhqadmin -s 192.168.1.100 -t 70443Example 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.
Copy to Clipboard
Copied!
Toggle word wrap
Toggle overflow
rhq-cli.sh -u rhqadmin -P
rhq-cli.sh -u rhqadmin -P6.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:
To truly manage resources, the
ProxyFactory creates a resource proxy object.
Example 4. Defining a Platform Proxy Resource
var rhelServerOne = ProxyFactory.getResource(10001)
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.
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.)
Alternatively, simply get a list of metrics with their current values using the
measurements method:
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:
Then, run the given operation method.
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:
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:
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")
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")
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
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
cliRoot/rhq-remoting-cli-4.9.0.JON320GA/bin/rhq-cli.sh -f /export/myScripts/my_script.jsExample 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:
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:
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
[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.
This simple script echoes the given x and y values.
Be aware of the following:
- Explicitly specify that you are using named arguments with the
--args-styleoption. - The values of the named arguments are still accessible through the implicit args array.
- The named arguments, such as
xandy, 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
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.
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.
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
[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.jsExample 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.
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
[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 3Example 17. Executing a Script with Named Arguments
Script arguments can be indexed or named.
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
[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=36.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:
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< ....
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:
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)
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)
rhqadmin@localhost:7080$ exporter.setTarget('csv', 'output.csv')
rhqadmin@localhost:7080$ exporter.write(resources)
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}