JBoss Operations Network 3.1.2

Writing JBoss ON Command-Line Scripts

using the JBoss ON CLI and remote API

Edition 3.1.2

Ella Deon Lackey

Legal Notice

Copyright © 2012 Red Hat, Inc..
This document is licensed by Red Hat under the Creative Commons Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it, you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified, all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack Logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.
January 23, 2013


JBoss Operations Network provides its own command shell that can interact directly with the JBoss ON server. This CLI uses the JBoss ON remote API to perform most of the tasks available in the JBoss ON GUI, as well as additional operations like importing and exporting server configuration and exporting historic metric data. The CLI allows administrators to script and automate their JBoss ON deployment, which makes it easier to manage their infrastructure.
This guide covers the basics of installing and using the JBoss ON CLI and provides examples of scripts for common tasks. It is intended primarily for administrators who will be using the default JBoss ON CLI to manage JBoss ON. This manual has a secondary audience for plug-in writers and developers who intend to write custom applications which leverage the remote API.
About This Guide
1. Audience and Intent
2. Giving Feedback
3. Document History
I. Getting Started
1. Understanding How Scripts Work with the JBoss ON Server and CLI
1.1. A Summary of JBoss ON Public APIs
1.2. The JBoss ON Server and Its Interfaces
1.3. JBoss ON CLI Scripts and JBoss ON Server Scripts
1.4. Differences Between the JBoss ON CLI and JBoss ON GUI Operations
1.5. Using Other Clients
1.6. Additional Resources
2. Installing the JBoss ON CLI
2.1. Installing the CLI
2.2. Setting CLI Environment Variables
2.3. CLI Files and Directories
II. Basic Examples for Running JBoss ON Scripts Through the CLI
Commands and Options with the CLI
1. Compatible CLI and Server Versions
2. The JBoss ON CLI Command Syntax
2.1. The CLI Script
2.2. CLI Script Options
2.3. Interactive CLI Commands
3. Available Implicit Variables in the JBoss ON API
4. Methods Specific to the JBoss ON CLI
4.1. Methods Available to the CLI and Server Scripts
4.2. Methods Available to Proxy Resources
5. Common Actions with JBoss ON CLI Scripts
5.1. Logging In
5.2. Using Resource Proxies
5.3. Passing Command and Script Arguments
5.4. Displaying Pretty-Print Output
5.5. Exporting Output
6. Tips and Tricks for Using the CLI
6.1. Using Tab Complete
6.2. Differences Between Running the CLI Interactively and with Files
6.3. API Differences Between Resources Types and Versions
6.4. Available Utility and Sample Scripts
6.5. Defining Custom Functions
6.6. Script Dependencies and Loading Functions
6.7. Scheduling Script Runs with Cron
6.8. Using Wrapper Scripts
6.9. Permissions and Setup for JBoss ON Users
Short Examples
1. Searches
1.1. Setting Basic Search Criteria
1.2. Using Sorting
1.3. Using Filtering
1.4. Fetching Associations
1.5. Setting Page Sizes
2. Getting the JBoss ON ID for an Object
3. Getting Data for Single and Multiple Resources
4. Setting Method Variables to String
5. Resources and Groups
5.1. Creating and Updating Content-Backed Resources (Web Apps)
5.2. Creating a Resource Group and Adding Members
6. Resource Configuration
6.1. Viewing Current Configuration
6.2. Changing Simple Configuration Properties
7. Operations
7.1. Starting and Stopping a Resource
7.2. Scheduling Operations
7.3. Retrieving the Results of an Operation
7.4. Checking a Resource's Operations History
8. Monitoring
8.1. Getting Resource Availability
8.2. Getting Specific Metrics
8.3. Exporting Metric Data for a Resource
8.4. Getting Baseline Calculations
9. Alerts
9.1. Using Alerts with Scripts
9.2. Acknowledging Alerts
9.3. Enabling or Disabling Alert Definitions
10. Users and Roles
10.1. Creating Roles
10.2. Creating Users
III. Extended Examples and Use Scenarios
Example Workflows
1. Example: Scripts to Manage Inventory (All Resource Types)
1.1. Automatically Import New Resources: autoimport.js
1.2. Simple Inventory Count: inventoryCount.js
1.3. Uninventory a Resource After an Alert: uninventory.js
2. Example: Scripts to Manage Resources of a Specific Type
3. Example: Scripting Resource Deployments (JBoss EAP 5)
3.1. Declaring Custom Functions
3.2. Checking the JBoss ON Groups and Inventory
3.3. Deploying the New Resource
4. Example: Deploying an Application with Bundles (JBoss EAP 4, 5, and 6)
4.1. Creating a New Application
4.2. Updating Applications
5. Example: JNDI Lookups After an Alert (JBoss EAP 5)
6. Example: Managing Grouped Servers (JBoss EAP 5)
6.1. The Plan for the Scripts
6.2. Creating the Wrapper Script and .conf File
6.3. Defining Arguments and Other Parameters for the CLI Scripts
6.4. Creating a Group: group.js
6.5. Adding Resources to a Group: addMember.js
6.6. Getting Inventory and Status Information: status.js
6.7. Starting, Stopping, and Restarting the Server: restart.js
6.8. Deploying Applications to the Group Members: deploy.js
6.9. Scheduling an Availability Operation: avail.js
6.10. Gathering Metric Data of Managed Servers: metrics.js
7. Example: Deploying a Standalone Server to a Cluster (JBoss EAP 6)
7.1. Adding a Standalone EAP 6 Server to a Cluster
7.2. Copying Deployed Applications Between Standalone Servers
8. Example: Deploying Applications Through Bundles (General)
8.1. Setting up Bundle Versions and Destinations
8.2. Deploying Bundles
8.3. Reverting a Bundle
9. Example: Remedying Resource Drift
9.1. The Plan for the Scripts
9.2. Setting up the Drift Definition and Preparing the Bundle
9.3. Remedying Drift
10. Example: Managing JBoss ON Server Configuration
10.1. Simple Export/Import Synchronization
10.2. Changing Server Configuration Before Importing
11. Example: Writing a Custom Java Client
11.1. Creating SampleLdapClientMain.class
11.2. Sample LDAP Script