Red Hat Training
A Red Hat training course is available for Red Hat JBoss Operations Network
Using JBoss Operations Network for Monitoring, Deploying, and Managing Resources
Recommendations and Procedures for Maintaining an Efficient JBoss and IT Infrastructure
Abstract
Chapter 1. Using the JBoss ON Web Interface
1.1. Supported Web Browsers
- Firefox 17 or later
- Internet Explorer 9
1.2. Logging into the JBoss ON Web UI
rhq-server.properties
file, JBoss ON is completely administered through its web interface.
http://server.example.com:7080
Figure 1.1. Logging into JBoss ON

1.3. Configuring Internet Explorer
- In Internet Explorer, click the gear icon in the upper right corner and select Internet options.
- Open the Security tab, and select the Local intranet icon.
- Click the Sites button.
- Click the Advanced button at the bottom of the pop-up window.
- Enter the JBoss ON server hostname or IP address in the Add this webiste to the zone: field, and click the Add.
- Close out the options windows.
1.4. A High Level Walk-Through
- The top menu
- The left menu tables
- The dashboard
- Resource-based tables, which can be for the resource inventory, a summary report, or the results of a search
- Configuration pages which both provide details for and access to elements in JBoss ON, including resources, groups, plug-ins, and JBoss ON server settings
Figure 1.2. UI Elements All Together

1.4.1. The Top Menu
Figure 1.3. The Top Menu

- The Dashboard contains a global overview of JBoss ON and its resources. Different, configurable snapshot summaries (called portlets) show different aspects of the resources and server, such as the discovery queue, recent alerts, recent operations, and resource counts.
- The Inventory tab shows both resources and groups.
- The Reports tab shows pre-defined reports. These are slightly different from the Dashboard, which focuses exclusively on resource information: the reports focus on the current actions of the different subsystem (or major functional areas) of JBoss ON, such as alerts, operations, metric collection, and configuration history.
- The Bundles tab opens the provisioning and content functional area. This is for uploading and deploying content bundles that are used to provision new applications.
- Administration goes to all areas related to configuring the JBoss ON server itself. This includes server settings, plug-ins, users and security, and agent settings.
1.4.2. The Left Menu
Figure 1.4. The Left Menu

Figure 1.5. Collapsing the Left Menu

1.4.3. Dashboard
Figure 1.6. Dashboard View

1.4.4. Inventory Browsers and Summaries
- Tabs for different areas, with subtabs that further break down information
- A table of results
- Icons that open a configuration or task option for that specific entity
- Buttons that perform actions (create, delete, or some other specific action) on the entries; some of these buttons aren't active unless an entry is selected
Figure 1.7. Inventory Browser

1.4.5. Entry Details Pages
Figure 1.8. Resource Tree

Figure 1.9. Tabs for a Resource Entry

Figure 1.10. Editable Areas for a Resource Entry

1.4.6. Shortcuts in the UI
- The Message Center shows all notifications that have been sent by the JBoss ON server. This includes alerts, configuration changes, changes to the inventory, or error messages for the server or UI.
- The Favorites button can be used to navigate to selected resources and groups quickly, while the little blue ribbon on resource pages can be used to add that resource to the favorites list.
- The resource availability is shown as a green check mark if the resource is available and a red X if the resource is down.
Figure 1.11. Shortcuts

1.4.7. Red Hat Access Menu
- Conveniently access exclusive Red Hat knowledge and solutions.
- Search error codes, messages, and other information, as well as view related knowledge from the Red Hat Customer Portal.
- Create new and view existing support cases as well as attach JBoss Diagnostic Reporter (JDR) reports collected from JBoss Enterprise Application Platform 6 instances and other files to those cases
1.4.7.1. Basic Usage


1.4.7.2. Search


1.4.7.3. Support
1.4.7.4. Opening a New Support Case


1.4.7.5. Opening a New Support Case Against a Product on Supported Application Servers



1.4.7.6. View Existing Support Cases

1.4.7.7. Editing a Case



1.5. Getting Notifications in the Message Center
Figure 1.12. Message Center

1.6. Sorting and Changing Table Displays
Figure 1.13. Basic Table Sorting on the Partition Events List

Figure 1.14. Basic Table Sorting on the Server Resources List

Figure 1.15. Advanced Table Sorting on the Server Resources List

Figure 1.16. Changing the Sort Method

1.7. Customizing the Dashboard
1.7.1. Editing Portlets
Figure 1.17. Portlet Icons

1.7.2. Adding and Editing Dashboards
Figure 1.18. Tabbed Dashboards

- Click the New Dashboard button in the far right of the main Dashboard.NoteThe process of editing and adding Dashboards is very similar. The only difference is that to edit a Dashboard, you click the Edit Mode button.
- The new Dashboard opens in the edit mode. Enter a name for the new Dashboard.
- Add the desired portlets to the Dashboard. If necessary, change the number of columns to fit the number of portlets.
1.8. Setting Favorites
Figure 1.19. Favorites Icon

Figure 1.20. Favorites List

1.9. Deleting Entries
Figure 1.21. Delete Button in the Area Browser

Chapter 2. Dynamic Searches for Resources and Groups
2.1. About Search Suggestions
- Saved searches, which contain previous custom search strings and a count of resources which match that search
- Query searches, which provide prompts for available resource traits
- Text searches, which provide a list of resources based on some property in the resource which matches the text prompt
Figure 2.1. Types of Search Suggestions

Figure 2.2. Highlighting Search Terms

2.2. About the Dynamic Search Syntax
[search_area].[search_property] operator value operator additional_search
Figure 2.3. Searching by Resources Traits

2.2.1. Basic String Searches
Figure 2.4. Matching the Search Term

postgres table myexampletable
"My Compatible Group" 'test box' plugin=jboss 123.4.5.6 trait[partitionName]='my example group' server.example.com
name="Production's Main Group"
resource.xml:id=^100
script$
Table 2.1. String Operators
Operator | Description |
---|---|
string | The string can occur anywhere in the result string. |
^string | The given string must appear at the beginning of the result value. |
string$ | The given string must appear at the end of the result value. |
^string$ | The result must be an exact match of the given string, with no leading or trailing characters. |
resource.trait[Database.startTime] = null
name = "null"
2.2.2. Property Searches
resource.type.plugin = Postgres
Table 2.2. Resource Search Contexts
Property | Description |
---|---|
resource.id | The resource ID number assigned by JBoss ON. |
resource.name | The resource name, which is displayed in the UI. |
resource.version | The version number of the resource. |
resource.type.plugin | The resource type, defined by the plug-in used to manage the resource. |
resource.type.name | The resource type, by name. |
resource.type.category | The resource type category (platform, server, or service). |
resource.availability | The resource availability, either UP or DOWN. |
resource.pluginConfiguration[property-name] | The value of any possible configuration entry in a plug-in. |
resource.resourceConfiguration[property-name] | The value of any possible configuration entry in a resource. |
resource.trait[property-name] | The value of any possible measurement trait for a resource. |
Table 2.3. Group Search Contexts
Property | Description |
---|---|
group.name | The name of the group. |
group.plug-in | For a compatible group, the plug-in which defines the resource type for this group. |
group.type | For a compatible group, the resource type for this group. |
group.category | The resource type category (platform, server, or service). |
group.kind | The type of group, either mixed or compatible. |
group.availability | The availability of resource in the group, either UP or DOWN. |
Table 2.4. Search String Operators
Operator | Description |
---|---|
= | Case-insensitive match. |
== | Case-exact match. |
!= | Case-insensitive negative match (meaning, the value is not the string). |
!== | Case-exact negative match (meaning, the value is not the string). |
2.2.3. Complex AND and OR Searches
postgres server myserver
postgres AND server AND myserver
postgres | jbossas
a | b c
(a | b) (c | d)
(a) (b | (c d))
2.3. Saving, Reusing, and Deleting Dynamic Searches
- Run the search.
- Click the star in the right of the search bar. When the field comes up, enter the name for the new search.The search name is then displayed in green.


Chapter 3. Viewing and Exporting Reports
3.1. Types of Reports
Figure 3.1. Inventory Summary Report

Table 3.1. Types of Reports
Report Name | Description | Has Filters? |
---|---|---|
Subsystem Reports | ||
Suspect Metrics | Lists any metrics outside the established baselines for a given resource. All suspect metrics for all resources are listed, but the baselines which mark the metric may be different for each resource, even different between resources of the same type. | No |
Configuration History | Lists all configuration changes, for all resources. Version numbers are incremented globally, not per resource. The configuration history shows the version number for the change, the date it was submitted and completed, its status, and the type of change (individual or through a group). | No |
Recent Operations | Lists all operations for all resources, by date that the operation was submitted (not necessarily run), the operation type, and its status. | Yes |
Recent Alerts | Lists every fired alert for all resources, with the name of the resource, the alert definition which was fired, and the alerting condition. | Yes |
Alert Definitions | Lists all configured alert definitions, for all resources, with their priority and whether they are enabled. | No |
Recent Drift | Contains a list of all snapshots, for all resources and drift definitions. | Yes |
Inventory Reports | ||
Inventory Summary | Contains a complete list of resources currently in the inventory, broken down by resource type and version number. | No |
Platform Utilization | Shows the current CPU percentage, actual used memory, and swap space. | No |
Drift Compliance | Shows a list of all resource types which support drift and then shows how many drift definitions are configured and whether the group is compliant. Clicking on a resource type shows the list of resources configured for drift and their individual compliance status. | No |
3.2. Exporting Report Data to CSV
Figure 3.2. Exported Inventory Summary

Figure 3.3. Report with Date Filters

Part I. Inventory, Resources, and Groups
Chapter 4. Interactions with System Users for Agents and Resources
- JBoss EAP servers
- PostgreSQL databases
- Tomcat servers
- Apache servers
- Generic JVMs
Table 4.1. Cheat Sheet for Agent and Resource Users
Resource | User Information |
---|---|
PostgreSQL |
No effect for monitoring and discovery.
The agent user must have read/write permissions to the PostgreSQL configuration file for configuration viewing and editing.
|
Apache |
No effect for monitoring and discovery.
The agent user must have read/write permissions to the Apache configuration file for configuration viewing and editing.
|
Tomcat | Must use the same user or the agent can not be discovered. |
JMX server or JVM | Different users are fine when using JMX remoting; cannot be discovered with different users and the attach API. |
JBoss AS/EAP |
EAP 5 and earlier: Different users are all right, but require read permissions on
run.jar and execute and search permission on all ancestor directories for run.jar .
EAP 6 and later:: The user running the agent must have read permissions to the application server's configuration files.
|
4.1. The Agent User
4.2. Agent Users and Discovery
- For JBoss EAP resources, the agent must have read permissions to the
run.jar
file, plus execute and search permissions for every directory in the path to therun.jar
file. - When a JBoss EAP 6 instance is installed from an RPM, the agent user must belong to the same system group which runs the EAP instance. This is jboss, by default.
- Tomcat servers can only be discovered if the JBoss ON agent and the Tomcat server are running as the same user. Even if the agent is running as root, the Tomcat server cannot be discovered if it is running as a different user than the agent.
- If a JVM or JMX server is running with JMX remoting, then it can be discovered if the agent is running as a different user. However, if it is running with using the attach API, it has to be running as the same user as the agent for the resource to be discovered.
4.3. Users and Management Tasks
- Discovery
- Deploying applications
- Executing scripts
- Running start, stop, and restart operations
- Creating child resources through the JBoss ON UI
- Viewing and editing resource configuration
4.4. Using sudo with JBoss ON Operations
- There can be no required interaction from the user, including no password prompts.
- It should be possible for the agent to pass variables to the script.
- Grant the JBoss ON agent user sudo rights to the specific script or command. For example, to run a script as the jbossadmin user:
[root@server ~]# visudo jbosson-agent hostname=(jbossadmin) NOPASSWD: /opt/jboss-eap/jboss-as/bin/*myScript*.sh
Using the NOPASSWD option runs the command without prompting for a password.ImportantJBoss ON passes command-line arguments with the start script when it starts an EAP instance. This can be done either by including the full command-line script (including arguments) in thesudoers
entry or by using the sudo -u user command in a wrapper script or a script prefix.The second option has a simplersudoers
entry - Create or edit a wrapper script to use. Instead of invoking the resource's script directly, invoke the wrapper script which uses sudo to run the script.NoteFor the EAP start script, it is possible to set a script prefix in the connection settings, instead of creating a separate wrapper script:
/usr/bin/sudo -u jbosson-agent
For example, for a start script wrapper,start-myScript.sh
:#!/bin/sh # start-myScript.sh # Helper script to execute start-myConfig.sh as the user jbosson-agent # sudo -u jbosson-agent /opt/jboss-eap/jboss-as/bin/start-myConfig.sh
- Create the start script, with any arguments or settings to pass with the
run.sh
script. For example, forstart-myConfig.sh
:nohup ./run.sh -c MyConfig -b jonagent-host 2>&1> jboss-MyConfig.out &
Chapter 5. Managing the Resource Inventory
5.1. About the Inventory: Resources
5.1.1. Managed Resources: Platforms, Servers, and Services
- Platforms (operating systems)
- Servers
- Services
Figure 5.1. An Example Resource Hierarchy

- A resource can only have one parent.
- A server can be a child of a platform (such as JBoss AS on Linux) or another server (such as Tomcat embedded in JBoss AS).
- A service can be a child of a platform, a server (such as the JMS queue on JBoss AS), or another service (e.g. a table inside a database).
- Platforms, servers, and services can have many children services.
5.1.2. Content-Backed Resources
5.1.3. Resources in the Inventory Used by JBoss ON
5.2. Discovering Resources
5.2.1. Finding New Resources: Discovery
5.2.2. Running Discovery Scans Manually
- Click the Inventory tab in the top menu.
- Select Platforms from the left menu, then the platform on which a scan should run.
- Open the Operations tab. In the Schedules sub-tab, click the New button.
- Open the Servers - Top Level Resources link on the left, and select the agent resource.
- Select the Manual Discovery operation from the drop-down menu, and select whether to run a detailed discovery (servers and services) or a simple discovery (servers only).
- In the Schedule area, select the radio button to run the operation immediately.
- Click the Schedule button to set up the operation.
5.2.3. Importing Resources from the Discovery Queue
- Click the Inventory tab in the top menu.
- In the Resources menu on the left, select Discovery Queue.
- Select the checkbox of the resources to be imported. Selecting a parent resource (such as a platform) gives the option to automatically import all of its children, too.
- Click the Import button at the bottom of the UI.
5.2.4. Ignoring Discovered Resources
- Select Inventory from the top menu.
- Select the Discovery Queue item under the Resources menu on the left side of the screen.
- Select the checkbox of the resource to be ignored. Selecting a parent resource automatically selects all of its children.
- Click the Ignore button at the bottom of the page.
5.2.5. Ignoring Imported Resources
- Inventory Resources pages,
- the Inventory page of the parent resource, or
- the resource Groups inventory page.
5.2.5.1. Ignoring Resources from a Resources page
- From the Inventory menu, select the relevant resource view under Resources. For example;
- Inventory > Resources > All Resources, or
- Inventory > Resources > Services.
- Select the row containing the resource to ignore. Multiple resources can be selected if required.
- Click the Ignore button at the bottom of the page.
5.2.5.2. Ignoring resources from the Inventory page of the parent resource
- From the Inventory menu, select the relevant resource view under Resources. For example;
- Inventory > Resources > All Resources, or
- Inventory > Resources > Services.
- Locate and select the parent resource from the resource list.
- Within the parent resource page, select the Inventory tab.
- From the parent resources Inventory tab, select the Child Resources sub-tab.
- Select the row containing the resource to be ignored from the Child Resources list. Multiple rows can be selected if required.
- Click the Ignore button at the bottom of the page.
5.2.5.3. Ignoring resources from a Groups page
- From the Inventory menu, select the relevant resource group under Groups. For example;
- Inventory > Groups > All Groups, or
- Inventory > Groups > Compatible Groups
- Locate the resource group that contains the resource to be ignored.
- Within the resource group page, select the Inventory tab.
- From the resource groups Inventory tab, select the Members sub-tab.
- Select the row containing the resource to be ignored from the Members list. Multiple rows can be selected if required.
- Click the Ignore button at the bottom of the page.
5.2.6. Ignoring an Entire Resource Type
- In the top menu, click the Administration tab.
- In the Configuration menu table on the left, select the Ignored Resource Types item.
- Every available resource type, based on the loaded agent plug-ins, is listed in the Ignored Resource Types page. To ignore a resource, click the pencil icon.That toggles whatever the current enabled/disabled setting is for ignoring the resource. If a resource type is enabled, then it will be discovered by the agent. If it is disabled, it will be ignored.
- Scroll to the bottom of the page and click the Save button.
5.3. Resources That Require Additional Configuration for Discovery
5.3.1. Configuring the Agent to Discover EAP Instances
- For JBoss EAP 5 and earlier, the agent must have read permissions to the
run.jar
file, plus execute and search permissions for every directory in the path to therun.jar
file. - For JBoss EAP 6 and 7, the agent must have read permissions to the application server's configuration files.
- When a JBoss EAP instance is installed from an RPM, the agent user must belong to the same system group which runs the EAP instance. This is jboss, by default.
5.3.2. Configuring Tomcat/EWS Servers for Discovery (Windows)
- Run regedit.
- Navigate to Java preferences key for the Tomcat server,
HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Procrun2.0\Tomcat
Ver#\Parameters\Java
. - Edit the Options attribute, and add these parameters:
-Dcom.sun.management.jmxremote.port=9876 -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.authenticate=false
- Restart the Tomcat service.
5.4. Importing New Resources Manually
- Click the Inventory tab in the top menu.
- Search for the parent resource of the new resource.Chapter 2, Dynamic Searches for Resources and Groups has information on searching for resources using dynamic searches.
- Click the Inventory tab of the parent resource.
- Click the Import button in the bottom of the Inventory tab, and select the type of child resource. The selection menu lists the possible types of child resources for that parent.
- Fill in the properties to identify and connect to the new resource. Each resource type in the system has a different set of required properties.
5.5. Creating Child Resources
- Click the Inventory tab in the top menu.
- Search for the parent resource of the new resource.Chapter 2, Dynamic Searches for Resources and Groups has information on searching for resources using dynamic searches.
- Click the Inventory tab of the parent resource.
- Click the Create Child button in the bottom of the Inventory tab, and select the type of child resource. The selection menu lists the possible types of child resources for that parent.
- Give the name and description for the new resource.
- Fill in the properties to identify and connect to the new resource. Each resource type in the system has a different set of required properties.
5.6. Viewing and Editing Resource Information
Figure 5.2. Expanding Resource Entry Details



5.7. Managing Connection Settings
- Click the Inventory tab in the top menu.
- Search for the resource.Chapter 2, Dynamic Searches for Resources and Groups has information on searching for resources using dynamic searches.
- Click the name of the resource to go to its entry page.
- Open the Inventory tab for the resource, and click the Connection Settings subtab.
- Change the connection information for the resource.If a field is not editable immediately, select the Unset checkbox, and then enter new information in the field.
- Click the Save button.
5.8. Uninventorying and Deleting Resources
5.8.1. A Comparison of Uninventorying and Deleting Resources
5.8.2. Use Caution When Removing Resources
Uninventory Irrevocably Deletes the Resource History and Data
Uninventorying a resource removes all of the data that JBoss ON has for that resource: its metric data and historical monitoring data, alerts, drift and configuration history, operation history, and other data. Once the resource is uninventoried, its data can never be recovered.
Uninventorying or Deleting a Resource Removes All of Its Children
If a parent resource is removed from JBoss ON, then all of its children are also removed. Removing an EAP server, for example, removes all of its deployed web applications from the JBoss ON inventory. Removing a platform removes all servers, services, and resources on that platform.
Uninventoried Resources Can Still Be Discovered
Even though a resource is uninventoried and all of its data in JBoss ON is permanently removed, the underlying resource still exists. This means that the resource can still be discovered. To prevent the resource from being discovered and re-added to the inventory, ignore the resource, as in Section 5.2.4, “Ignoring Discovered Resources”.
Anything Depending on a Deleted Resource Could Fail
Some resource types can be deleted, meaning the resource itself is removed from the machine, not just from the JBoss ON inventory. Anything that relies on that resource can experience failures because the resource is deleted. For example, if a datasource for an EAP server is deleted, that datasource is removed from the EAP server itself. Any application which attempts to connect to that datasource will then stop working, since it does not exist anymore.
5.8.3. Uninventorying through the Inventory Tab
- Click the Inventory tab in the top menu.
- Select the resource category in the Resources table on the left, and, if necessary, filter for the resource.
- Select the resource to uninventory from the list, and click the Uninventory button.
- When prompted, confirm that the resource should be uninventoried.
- To prevent the resource from being re-imported into the inventory, ignore it when it is discovered in the next discovery scan. This is covered in Section 5.2.4, “Ignoring Discovered Resources”.
5.8.4. Uninventorying through the Parent Inventory
- Click the Inventory tab in the top menu.
- Search for the parent resource of the resource.Chapter 2, Dynamic Searches for Resources and Groups has information on searching for resources using dynamic searches.
- Click the Inventory tab for the parent resource.
- Click on the line of the child resource to uninventory. To select multiple entries, use the Ctrl key.
- Click the Uninventory button.
- When prompted, confirm that the resource should be uninventoried.
- To prevent the resource from being re-imported into the inventory, ignore it when it is discovered in the next discovery scan. This is covered in Section 5.2.4, “Ignoring Discovered Resources”.
5.8.5. Uninventorying through a Group Inventory
- In the Inventory tab in the top menu, select the compatible or mixed groups item in the Groups menu on the left.
- Click the name of the group.
- Open the Inventory tab for the group, and open the Members submenu.
- Click on the line of the group member to uninventory. To select multiple entries, use the Ctrl key.
- Click the Uninventory button.
- When prompted, confirm that the resource should be uninventoried.
- To prevent the resource from being re-imported into the inventory, ignore it when it is discovered in the next discovery scan. This is covered in Section 5.2.4, “Ignoring Discovered Resources”.
5.8.6. Deleting a Resource
- Deletes the resource from the underlying machine.
- Removes the resource from the inventory.
- Removes any child resources from JBoss ON.
- Preserves the inventory information in JBoss ON for the resource, including alerts, drift definitions, metric data, and configuration and operation histories.
- Click the Inventory tab in the top menu.
- Search for the parent resource of the resource to delete.Chapter 2, Dynamic Searches for Resources and Groups has information on searching for resources using dynamic searches.
- Click the Inventory tab of the parent resource.
- Select the resource to delete from the list of children.
- Click the Delete button in the bottom of the Inventory tab.
5.9. Viewing Inventory Summary Reports
- Resource type
- The JBoss ON server plug-in which manages the resource
- The JBoss ON category for the resource (platform, server, or service)
- The version number or numbers for resource of the resource type in inventory
- The total number of resources of that type in the inventory
- In the top menu, click the Reports tab.
- In the Inventory menu box in the menu table on the left, select the Inventory Summary report.
- Click the name of any resource type to go to the inventory list for that resource type.
inventorySummary.csv
.
Chapter 6. Managing Groups
6.1. About Groups
Table 6.1. Types of Groups
Type | Description | Static or Dynamic |
---|---|---|
Mixed groups | Contains resources of any resource type. There is no limit to how many or what types of resources can be placed into a mixed group. Mixed groups are useful for granting access permissions to users for a set of grouped resources. | Static |
Compatible groups | Contains only resources of the same type. Compatible groups make it possible to perform an operation against every member of the group at the same time, removing the need to individually upgrade multiple resources of the same type, or perform other operations one at a time on resources across the entire enterprise. | Static |
Recursive groups | Includes all the descendant, or child, resources of resources within the group. Recursive groups show both the explicit member availability and the child resource availability. | Static (members) and dynamic (children) |
Autogroups | Shows every resource as part of a resource hierarchy with the platform at the top, and child and descendant resources below the platform. Child resources of the same type are automatically grouped into an autogroup. | Dynamic |
6.1.1. Dynamic and Static Groups
6.1.2. About Autogroups
Figure 6.1. PostgreSQL Autogroup

6.1.3. Comparing Compatible and Mixed Groups
Figure 6.2. Compatible Group Entry

Figure 6.3. Mixed Group Entry

6.1.4. Leveraging Recursive Groups
6.2. Creating Groups
- Click the Inventory tab in the top menu.
- In the Groups box in the left menu, select the type of group to create, either compatible or mixed.Compatible groups have resources all of the same type, while mixed groups have members of different types. The differences in the types of members means that there are different ways that compatible and mixed groups can be managed, as covered in Section 6.1.3, “Comparing Compatible and Mixed Groups”.
- Enter a name and description for the group.Marking groups recursive can make it easier to manage resources, particularly when setting role access controls. For example, administrators can grant users access to the group and automatically include any child resources of the member resources.
- Select the group members. It is possible to filter the choices based on name, type, and category.
6.3. Changing Group Membership
- In the Inventory tab in the top menu, select the compatible or mixed groups item in the Groups menu on the left.
- Click the name of the group.
- Open the Inventory tab for the group, and open the Members submenu.
- Click the Update Membership button at the bottom of the page.
- Select the resources to add to the group from the box on the left; to remove members, select them from the box on the right. Use the arrows to move the selected resources. To select multiple resources, use Ctrl+click.
- Click the Save button.
6.4. Editing Compatible Group Connection Properties
- If all of the resources in the group have identical values for a property, the group connection property is that exact value.
- If even one resource has a different value than the rest of the resources in the group, that property will have a special marker value of ~ Mixed Values ~.
- In the Inventory tab in the top menu, select the Compatible Groups item in the Groups menu on the left.
- Click the name of the compatible group.
- Open the Inventory tab for the group, and click the Connection Settings sub-item.
- To edit a property, click the pencil by the field.
- To change all resources to the same value, click the Unset checkbox for the field Set all values to.... To change a specific resource, click the Unset checkbox for that resource and then give the new value.
Chapter 7. Using Dynamic Groups
7.1. About Dynamic Groups Syntax
7.1.1. General Expression Syntax
- By a specific resource attribute or value (a simple expression)
- By the resource type (a pivoted expression)
- By membership in another group (a narrowing expression)
expression 1 exprA1 exprA2 groupby exprB1 groupby exprB2 expression 2 exprA2 exprA1 groupby exprB2 groupby exprB1
Table 7.1. Dynamic Group Properties
Type | Supported Attributes | ||||||
---|---|---|---|---|---|---|---|
Related to the resource itself | |||||||
resource
|
| ||||||
Related to the resource type | |||||||
resourceType
|
| ||||||
Related to the resource configuration | |||||||
plug-inConfiguration
|
Any plugin configuration property
| ||||||
resourceConfiguration
|
Any resource configuration property
| ||||||
Related to the resource monitoring data | |||||||
traits
|
Any monitoring trait
| ||||||
availability
|
The current state, either UP or DOWN
|
resource.id = 10001
resource.parent.id = 10001
- resource
- resource.child
- resource.parent
- resource.grandParent
7.1.2. Simple Expressions: Looking for a Value
resource.attribute[string-expression] = value
resource.parent.type.category = Platform
resource.trait
is the generic resource attribute, and a sub-attribute like partitionName
identifies the actual parameter.
empty resource.attribute[string-expression]
not empty resource.attribute[string-expression]
7.1.3. Pivot Expressions: Grouping by an Attribute
groupby resource.attribute
parent.name
attribute creates a unique group based on every parent resource.
groupby resource.parent.name
Figure 7.1. Resources and Parents

7.1.4. Narrowing Expressions: Members of a Group
memberof = "Dev Resource Group" groupby resource.type.name
7.1.5. Compound Expressions
resource.parent.type.category = Platform
resource.parent.type.category = Platform resource.name.contains = JBossAS
groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
resource.type.category = server groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
resource.type.plugin = JBossAS resource.type.name = JBossAS Server empty resource.pluginConfiguration[principal]
7.1.6. Unsupported Expressions
All expressions must be in the same configuration area.
All given configuration properties in an expression must be only from the resource configuration or only from the plug-in configuration. Expressions cannot be taken from both.
Each property must only be used once.
A property can only be used once in a dynagroup definition.
valid resource.trait[x] = foo not valid resource.trait[x] = foo resource.trait[y] = bar
resource.grandParent.trait[Trait.hostname].contains = stage resource.parent.type.plugin = JBossAS5 resource.type.name = Web Application (WAR)
resource.grandParent.trait[Trait.hostname].contains = stage resource.parent.type.plugin = JBossAS5 resource.type.name = Web Application (WAR) resource.trait[contextRoot] = jmx-console
There was a problem calculating the results: java.lang.IllegalArgumentException: org.hibernate.QueryParameterException: could not locate named parameter [arg2]
resource.parent.trait[x] = foo resource.grandParent.trait[y] = bar
7.1.7. Dynagroup Expression Examples
Example 7.1. JBoss Clusters
resource.type.plugin = JBossAS resource.type.name = JBossAS Server groupby resource.trait[partitionName]
Example 7.2. A Group for Each Platform Type
resource.type.plugin = Platforms resource.type.category = PLATFORM groupby resource.type.name
Example 7.3. Autogroups
groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
Example 7.4. Raw Measurement Tables
resource.type.plugin= Postgres resource.type.name = Table resource.parent.name = rhq Database resource.name.contains = rhq_meas_data_num_
Example 7.5. Only Agents with Multicast Detection
resource.type.plugin= RHQAgent resource.type.name = RHQ Agent resource.resourceConfiguration[rhq.communications.multicast-detector.enabled] = true
Example 7.6. Only Windows Platforms with Event Tracking
resource.type.plugin= Platforms resource.type.name = Windows resource.pluginConfiguration[eventTrackingEnabled] = true
Example 7.7. JBoss AS Servers by Machine
groupby resource.parent.trait[Trait.hostname] resource.type.plugin = JBossAS resource.type.name = JBossAS Server
7.2. Creating Dynamic Groups
- Click the Inventory tab in the top menu.
- In the Groups menu box on the left, click the Dynagroup Definitions link.
- Click the New button to open the dynamic group definition form.
- Fill in the name and description for the dynamic group. The name can be important because it is prepended to any groups created by the definition, as a way of identifying the logic used to create the group.
- Fill in the search expressions. This can be done by entering expressions directly in the Expression box or by using a saved expression.Saved expressions are have a wizard to help build and validate the expressions. To create a saved expression, click the button by the drop-down menu. Several options for the expression are active or inactive depending on the other selections; this prevents invalid expressions.The Expression box at the top shows the currently created expression.
- After entering the expressions, set whether the dynamic group is recursive.
- Set an optional recalculation interval. By default, dynamic groups do not recalculate their members automatically, meaning the recalculation value is set to 0. To recalculate the group membership, set the Recalculation interval to the time frequency, in milliseconds.NoteRecalculating a group definition across large inventories could be resource-intensive for the JBoss ON server, so be careful when setting the recalculation interval. For large inventories, set a longer interval, such as an hour, to avoid affecting the JBoss ON server performance.
7.3. Recalculating Group Members
- Click the Inventory tab in the top menu.
- In the Groups menu on the left, click the Dynagroup Definitions link.
- In the list of dynagroups, select the row of the dynagroup definition to calculate.
- Click the Recalculate button at the bottom of the table.
Chapter 8. Creating User Accounts
8.1. Managing the rhqadmin Account
- Click the Administration tab in the top menu.
- In the Security table on the left, select Users.
- Click the name of rhqadmin.
- In the edit user form, change the password to a new, complex value.
8.2. Creating a New User
- Click the Administration tab in the top menu.
- In the Security table on the left, select Users.
- Click the NEW button at the bottom of the list of current users.
- Fill in description of the new user. The Enable Login value must be set to Yes for the new user account to be active.
- Select the required role from the Available Roles area, and then click the arrow pointing to the Assigned Roles to assign the role.
- Click the Save button to save the new user with the role assigned.
8.3. Editing User Entries
- Click the Administration tab in the top menu.
- From the Security menu, select Users.
- Click the name of the user whose entry will be edited.
- In the edit user form, change whatever details need to be changed, and save.
8.4. Disabling User Accounts
- Click the Administration tab in the top menu.
- In the Security table on the left, select Users.
- Click the name of the user whose entry will be edited.
- In the edit user form, change the Enable Login radio button to No.
- Click the Save button to save the new user with the role assigned.
8.5. Changing Role Assignments for Users
- Click the Administration tab in the top menu.
- From the Security menu, select Users.
- Click the name of the user to edit.
- To add a role to a user, select the required role from the Available Roles area, click the arrow pointing to the Assigned Roles area. To remove a role, select the assigned role on the right and click the arrow pointing to the left.
- Click Save to save the role assignments.
Chapter 9. Managing Roles and Access Control
9.1. Security in JBoss ON
9.1.1. Access Control and Permissions
- Global permissions apply to JBoss ON server configuration. This covers administrative tasks, like creating users, editing roles, creating groups, importing resources into the inventory, or changing JBoss ON server properties.
- Resource-level permissions apply to actions that a user can perform on specific resources in the JBoss ON inventory. These cover actions like creating alerts, configuring monitoring, and changing resource configuration. Resource-level permissions are tied to the subsystem areas within JBoss ON.
Figure 9.1. Read Access Option

Table 9.1. JBoss ON Access Control Definitions
Access Control Type | Description |
---|---|
Global Permissions | |
Manage Security |
Equivalent to a superuser. Security permissions grant the user the rights to create and edit any entries in JBoss ON, including other users, roles, and resources, to change JBoss ON server settings, and to control inventory.
Warning
The Security access control level is extremely powerful, so be cautious about which users are assigned it. Limit the number of superusers to as few as necessary.
|
Manage Inventory | Allows any operation to be performed on any JBoss ON resource, including importing new resources. |
Manage Settings | Allows a user to add or modify any settings in the JBoss ON server configuration itself. This includes operations like deploying plug-ins or using LDAP authentication. |
Manage Bundle Groups |
Allows a user to add and remove members of a bundle group; implicitly, it includes the permission to view bundles. This is analogous to the Manage Inventory permission for resources.
Note
This permission is required for all bundle-level create, deploy, and delete permissions.
|
Deploy Bundles to Groups | Allows a user to deploy a bundle to any resource group to which the user has access. |
View Bundles | Allows a user to view all bundles, regardless of the bundle group assignment. |
Create Bundles | Allows a user to create and update bundle versions. When a bundle is created, it must be assigned to bundle group, unless the user has the View Bundles permission; in that case, a user can create a bundle and leave it unassigned. |
Delete Bundles | Allows a user to delete any bundle which he has permission to view. |
Manage Bundles (Deprecated) |
Allows a user to upload and manage bundles (packages) used for provisioning resources.
This permission has been deprecated. It is included for backward-compatibility with older bundle configuration and user roles. However, this permission offered no ability to limit access to certain bundles, groups, or resources (for deployment); without this fine-grained control, this permission could only be applied to high-level administrators to maintain security.
|
Manage Repositories | Allows a user to access any configured repository, including private repositories and repositories without specified owners. Users with this right can also associated content sources with repositories. |
View Users | Allows a user to view the account details (excluding role assignments) for other users in JBoss ON. |
Resource-Level Permissions | |
Inventory | Allows a user to edit resource details and connection settings — meaning the information about the resource in the JBoss ON inventory. This does not grant rights to edit the resource configuration. |
Manage Measurements | Allows the user to configure monitoring settings for the resource. |
Manage Alerts | Allows the user to create alerts and notifications on a resource. Configuring new alert senders changes the server settings and is therefore a function of the global Settings permissions. |
Control | Allows a user to run operations (which are also called control actions) on a resource. |
Configure |
Allows users to change the configuration settings on the resource through JBoss ON.
Note
The user still must have adequate permissions on the resource to allow the configuration changes to be made.
This access area has two options:
If one of these permissions is not granted to a role, then the users in the role are denied any access to the resource configuration.
|
Manage Drift | Allows the user to create, modify, and delete resource and template drift definitions. It also allows the user to manage drift information, such as viewing and comparing snapshots. |
Manage Content | Allows the user to manage content providers and repositories that are available to resources. |
Create Child Resources | Allows the user to manually create a child resource for the specified resource type. |
Delete Child Resources | Allows the user to delete or uninventory a child resource for the specified resource type. |
Bundle-Level Permissions | |
Assign Bundles to Group | Allows a user to add bundles to a group. For explicit bundle groups, this is the only permission required. To add bundles to the unassigned group (which essentially removes it from all group membership), this also requires the global View Bundles permission. |
Unassign Bundles from Group | Allows a user to remove bundles from a group. |
View Bundles in Group | Allows a user to view any bundle within a group to which the user has permissions. |
Create Bundles in Group | Allows a user to create a new bundle within a bundle group to which he has permission. This also allows a user to update the version of an existing bundle within the bundle group. |
Delete Bundles from Group | Allows a user to delete both bundle versions and entire bundles from the server, so long as they belong to a group to which the user has permissions. |
Deploy Bundles to Group | Allows a user to deploy any bundle which he can view (regardless of create and delete permissions) to any resource within a resource group to which he has permissions. |
9.1.2. Access and Roles
- A superuser role provides complete access to everything in JBoss ON. This role cannot be modified or deleted. The user created when the JBoss ON server was first installed is automatically a member of this role.
- An all resources role exists that provides full permissions to every resource in JBoss ON (but not to JBoss ON administrative functions like creating users). This is a useful role for IT users, for example, who need to be able to change the configuration or set up alerts for resources managed by JBoss ON but who don't require access over JBoss ON server or agent settings.
9.1.3. Access and Groups
Two Roles to Define Access for a Single User to Resources and Bundles
Bundle Group A Resource Group A | | V V Role 1 <--- User A ---> Role 2 ^ ^ | | Permissions Permissions - view bundles in group - deploy bundles to group - create bundles
9.2. Creating a New Role
- Create any resources groups which will be associated with the role. Creating groups is described in Section 6.2, “Creating Groups”.By default, JBoss ON uses only resource groups to associate with a role, and these are required. However, optional user groups from an LDAP directory can also be assigned to a role, so that the group members are automatically treated as role members. LDAP groups must be configured in the server settings, as described in Section 10.3.2, “Associating LDAP User Groups to Roles”.
- In the top menu, click the Administration tab.
- In the Security menu table on the left, select the Roles item.
- The list of current roles comes up in the main task window. Click the New button at the bottom of the list.
- Give the role a descriptive name. This makes it easier to manage permissions across roles.
- Global permissions grant permissions to areas of the JBoss ON server and configuration.
- Resource permissions grant permissions for managing resources.
The specific access permissions are described in Section 9.1.1, “Access Control and Permissions”.- Move the required groups from the Available Resource Groups area on the left to the Assigned Resource Groups on the right as required.
- At the bottom, click the Save button.
- Select the Users tab to assign users to the role.Move the required user from the Available Users area on the left, to the Assigned Users on the right as required.
- Click the arrow in the upper right to close the create window.
9.3. Extended Example: Read-Only Access for Business Users
The Setup
Example Co. needs some of its management team to be able to read and access JBoss ON data to track infrastructure performance and maintenance, define incident response procedures, and plan equipment upgrades. While these business users need to view JBoss ON information, they should not be able to edit any of the configuration, which is handled by the IT and development departments.
The Plan
Tim the IT Guy first defines what actions the business users need to perform, and they need to be able to see everything:
- View resources in the inventory and histories for adding and deleting resources.
- View monitoring information, including measurements and events.
- View alerts.
- View content and bundles and any deployments to resources.
- View configuration drift.
- View all resource histories for configuration and operations.
- View user details to get information for auditing actions.
The Results
Business users are given access to all of the information they need, without being able to change any configuration or inventory accidentally.
9.4. Extended Example: View All Resources, Edit Some Resources
The Setup
Example Corp. has three major groups associated with its IT infrastructure: development, QE, and production. Each group requires information from the other teams to help maintain their configuration, manage performance settings, and roll out new applications, but they should only be able to manage their own systems.
The Plan
Tim the IT Guy first defines the different relationships that need to be expressed within the access controls:
- Everyone needs to be able to view performance data for all stacks within the infrastructure.
- The individual divisions need write access to their own systems.
- At least some administrators within each group require the ability to update system configuration.
- At least some administrators within each group require the ability to create and deploy bundles to manage applications within their own groups.
- A mixed group which contains all of the resources within each given stack environment. The stacks include platforms, Postgres databases, EAP servers, web contexts, and other resources used to manage the production environment.This results in three groups: Dev Stack, QE Stack, and Production Stack.
- An "all stacks" nested group which includes all three stack groups.This group is not for all resources — it only includes the stack groups, excluding JBoss ON-related resources and other managed resources not relevant to those stacks.
- Since these environments include application development, each organization also requires its own bundle group to maintain deployments.
- There has to be a mechnism to promote bundles between environments. Tim the IT Guy creates "Promote Bundles" group where bundles can be added when they are ready to be moved into a different environment.
- View-only rights to all resources, including configuration view-only rights
- Edit rights to resources within the stacks for monitoring, alerts, drift, operations, and inventory
- Edit rights to resources within the stacks for configuration
- View bundle rights within the stacks
- Create and deploy bundle rights within the stacks
- Regular users
- Administrators which manage resource configuration
- Administrators which can create (promote) bundles between groups
Dev Stack
Bundle Group
|
Role BG1
|
V
Regular Joe
^ ^
| |
Role RG1 Role RG2
| |
"All Stack" Dev Stack
Resource Resource
Group Group
^ | Role RG1 <------Permissions | | "All Stack" View.alerts Resource View.inventory Group View.measurements View.etc... View.configuration
^ | Role RG2 <------Permissions | | Dev Stack Edit.alerts Resource Edit.inventory Group Edit.measurements Edit.etc... Deploy.bundles
Dev Stack Bundle Group | Role BG1 <-----Permissions | | V View.bundles Create.bundles
"Regular Joe" roles | V Group Lead <------Role RG3 | Permissions | Edit.configuration
Dev Stack Permission: Bundle Group Create.Bundles \ / \ / Role BG1 | V Role BG2 ----> Group Lead <---- Role BG3 / \ / \ / \ / \ QE Stack Permission: Prod Stack Permission: Bundle Group Create.Bundles Bundle Group Create.Bundles
The Result
Users within each group are granted access to view whatever performance and configuration information they need, but they can only make changes to resources within their specified group. Only administrators within each group can make configuration changes.
Chapter 10. Integrating LDAP Services for Authentication and Authorization
10.1. Supported Directory Services
- Red Hat Directory Server 8.1, 8.2, and 9.0
- Microsoft Active Directory 2003 and 2008
10.2. LDAP for User Authentication
10.2.1. About LDAP Authentication and Account Creation
10.2.2. Issues Related to Using LDAP for a User Store
Figure 10.1. LDAP Groups, JBoss ON Roles, and Role Members

- Only create regular user accounts in one place. If LDAP should be used for authentication, then only add or delete user accounts in the LDAP directory.
- Ideally, limit JBoss ON user accounts to special, administrative users and rely on the LDAP directory for regular accounts.
- Try to design roles around LDAP groups, meaning that JBoss ON user accounts in those roles should be limited to admin accounts or avoided altogether.
10.2.3. Configuring LDAP User Authentication
- In the top menu, click the Administration tab.
- In the Configuration menu table on the left, select the System Settings item.
- Jump to the LDAP Configuration Properties area.
- Check the Use LDAP Authentication checkbox so that JBoss ON will use the LDAP user directory as its identity store.
- Configure the connection settings to connect to the specific LDAP directory.
- Give the LDAP URL of the LDAP server. This has the format ldap://hostname[:port]. For example:
ldap://server.example.com:389
By default, this connects to the localhost over port 389 (standard LDAP port) or 636 (secure LDAP port, if SSL is selected). - To use a secure connection, check the Use SSL checkbox. When using SSL, make sure that the LDAP directory is actually running over SSL, and make sure that the connection URL points to the appropriate SSL port and protocol:
ldap
s
://server.example.com:636
- Give the bind credentials to use to connect to the server. The username is the full LDAP distinguished name of the user as whom JBoss ON binds to the directory.NoteThe user must exist in the LDAP directory before configuring the LDAP settings in JBoss ON. Otherwise, login attempts to the JBoss ON server will fail.Also, make sure that the JBoss ON user has appropriate read and search access to the user and group subtrees in the LDAP directory.By default, users created without roles are able to login. For more information on roles see Section 9.1.2, “Access and Roles”.NoteBy default, users created without roles are able to login. This has an impact since users may exist in LDAP but do not have an assigned role in JBoss ON. For more information on roles see Section 9.1.2, “Access and Roles”.
- Set the search parameters that JBoss ON uses when searching the LDAP directory for matching user entries.
- The search base is the point in the directory tree where the server begins looking for entries. If this is used only for user authentication or if all JBoss ON-related entries are in the same subtree, then this can reference a specific subtree:
ou=user,ou=JON,dc=example,dc=com
If the users or groups are spread across the directory, then select the base DN:dc=example,dc=com
- Optionally, set a search filter to use to search for a specific subset of entries. This can improve search performance and results, particularly when all JBoss ON-related entries share a common LDAP attribute, like a custom
JonUser
attribute. The filter can use wild cards (objectclass=*) or specific values (JonUser=true). - Set the LDAP naming attribute; this is the element on the farthest left of the full distinguished name. For example, in uid=jsmith,ou=people,dc=example,dc=com, the far left element is uid=jsmith, and the naming attribute is
uid
.The default naming attribute in Active Directory iscn
. In Red Hat Directory Server, the default naming attribute isuid
.
- Save the LDAP settings.NoteThe Group Filter and Member Property fields aren't required for user authentication. They're used for configuring LDAP groups to be assigned to roles, as in Section 10.3.2, “Associating LDAP User Groups to Roles”.
10.3. Roles and LDAP User Groups
10.3.1. About Group Authorization
Figure 10.2. Groups Assigned to a Role

- An LDAP directory server connection has to be configured.
- There has to be an LDAP attribute given to search for group entries.For Active Directory, this is generally the group object class. For Red Hat Directory Server, this is generally groupOfUniqueNames. Other standard object classes are available, and it is also possible to use a custom, even JBoss ON-specific, object class.
- There has to be an LDAP attribute given to identify members in the group.Common member attributes are
member
anduniqueMember
.
(&(group_filter)(member_attribute=user_DN))
member
attribute on an Active Directory group:
ldapsearch -h server.example.com -x -D "cn=Administrator,cn=Users,dc=example,dc=com" -W -b "dc=example,dc=com" -x '(&(objectclass=group)(member=CN=John Smith,CN=Users,DC=example,DC=com))'
uniqueMember
attribute on groupOfUniqueNames groups more commonly than member
and group
. For example:
/usr/lib64/mozldap6/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "ou=People,dc=example,dc=com" -s sub "(&(objectclass=groupOfUniqueNames)(uniqueMember=uxml:id=jsmith,ou=People,dc=example,dc=com))"
10.3.2. Associating LDAP User Groups to Roles
- In the top menu, click the Administration tab.
- In the Configuration menu table on the left, select the System Settings item.
- Jump to the LDAP Configuration Properties area.
- Set up the LDAP connections, as described in Section 10.2.3, “Configuring LDAP User Authentication”. It is not required that the LDAP directory be used as the identity store in order to configure LDAP authorization, but it is recommended.
- Set the parameters to use for the server to use to search for LDAP groups and their members.The search filter that JBoss ON constructs looks like this:
(&(group_filter)(member_attribute=user_DN))
- The Group Search Filter field sets how to search for the group entry. This is usually done by specifying the type of group to search for through its object class:
(objectclass=groupOfUniqueNames)
- The Group Member Filter field gives the attribute that the specified group type uses to store member distinguished names. For example:
uniqueMember
The user_DN is dynamically supplied by JBoss ON when a user logs into the UI. - Save the LDAP settings.
10.4. Extended Example: memberOf and LDAP Configuration
The Setup
Authentication is the process of verifying someone's identity. Authorization is the process of determining what access permissions that identity has. Users are authorized to perform tasks based on the permissions granted to their role assignments.
The Plan
There are two things to configure: how to identify users for authentication and how to organize users for authorization.
- A single group to identify JBoss ON users in the LDAP directory
- Multiple, existing LDAP groups which are used to determine different levels of access to JBoss ON
memberOf
attribute is automatically added to user entries to indicate a group that the user belongs to.
memberOf
attribute to user entries as members are added and removed to the group. Tim the IT Guy only has to use the memberOf
attribute on those user accounts as the search filter for authentication.
dn: uid=jsmith,ou=people,dc=example,dc=com uid: jsmith cn: John Smith ... memberOf: cn=JON User Group,ou=groups,dc=example,dc=com memberOf: cn=IT Administrators,ou=groups,dc=example,dc=com
memberOf
attribute for that specific JBoss ON group:
memberOf='cn=JON User Group,ou=groups,dc=example,dc=com'
- IT Administrators Group is mapped to a role with manage inventory permissions.
- IT Manager Group is mapped to a role with view (but no write) permissions for all of the resources and with view users permissions.
- Business Manager Group is mapped to a role with permissions to read all resource configuration, bundles, drift, measurements, operations, and alerts, but no write permissions.
The Results
Tim the IT Guy only has to create and manage one LDAP group, the JON Users Group, to set up all authentication and users for JBoss ON. He does not have to change the LDAP schema or even modify user entries directly.
Part II. Managing Resource Configuration
Chapter 11. Executing Resource Operations
11.1. Operations: An Introduction
11.1.1. A Summary of Operation Benefits
- They allow additional parameters (depending on how the operation is defined in the plug-in), such as command arguments and environment variables.
- They validate any operation parameters, command-line arguments, or environment variables much as JBoss ON validates resource configuration changes.
- They can be run on group of resources as long as they are all of the same type.
- Operations can be ordered to run on group resources in a certain order.
- They can be run on a recurrently schedule or one specific time.
- Operations keep a history of both successes and failures, so that it is possible to audit the operations executed on a resource both for operations run for that specific resource and done on that resources as part of a group.
11.1.2. About Scheduling Operations
- Using the calendar setting to select a time. There are three different ways to schedule an operation using the calendar: immediately, at a set point in the future, or on a recurring schedule. The recurring schedules can be indefinite or run within a specific time period.
- Using a cron expression. This is used almost exclusively for recurring jobs and can be used to set very complex execution schedules.
Figure 11.1. A Scheduled Operation


11.1.3. About Operation Histories
11.2. Managing Operations: Procedures
11.2.1. Scheduling Operations
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Operations tab.
- In the Schedules tab, click the New button.The types of operations that are available vary, depending on the specific type of resource.NoteThe Schedules tab shows a list of scheduled operations, meaning operations which are configured but have not yet been run. If there are no scheduled operations, then the tab has a description that reads No items to show. That does not mean that there are no operations available for the resource; it only means that no operations have been scheduled.
- Fill in all of the required information about the operation, such as port numbers, file locations, or command arguments.
- In the Schedule area, set when to run the operation.When using the Calendar, the operation can run immediately, at a specified time, or on a repeatable schedule, as selected from the date widget.The Cron Expression is used for recurring jobs, based on a cron job. These expressions have the format min hour day-of-month month day-of-week, with the potential values of 0-59 0-23 1-31 1-12 1-7; using an asterisk means that any value can be set.
- Set other rules for the operations, like a timeout period and notes on the operation itself.
- Click the Schedule button to set up the operation.
11.2.2. Viewing the Operation History
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Operations tab.
- Click the History subtab.Every completed or in progress operation is listed, with an icon indicating its current status.
- Click the name of the operation to view further details. The history details page shows the start and end times of the operation, the stdout output of the operation or other operation messages, as well as the name of the user who scheduled the operation.
11.2.3. Canceling Pending Operations
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Operations tab.
- In the Schedules tab, click the line of the operation to cancel.
- Click Delete, and confirm the action.
11.2.4. Ordering Group Operations
- In the Inventory tab in the top menu, select the Compatible Groups item in the Groups menu on the left.
- Click the name of the group to run the operation on.
- Configure the operation, as in Section 11.2.1, “Scheduling Operations”.
- In the Resource Operation Order area, set the operation to execute on all resources at the same time (in parallel) or in a specified order. If the operation must occur in resources in a certain order, then all of the group members are listed in the Member Resources box, and they can be rearranged by dragging and dropping them into the desired order.Optionally, select the Halt on failure checkbox to stop the group queue for the operation if it fails on any resource.
11.2.5. Running Scripts as Operations for JBoss Servers
.bat
for Windows.sh
for Unix and Linux.pl
scripts for Unix and Linux
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Operations tab.
- In the Schedules tab, click the New button.
- Select Execute CLI script as the operation type from the Operation drop-down menu.NoteThe Execute script option is only available for JBoss AS and JBoss AS 5 resources, by default, and only if a script is available to execute.
- Enter any command-line arguments in the Parameters text box.Each new argument has the format name=value; and is added on a new line. If the variable's value contains properties with the syntax
%propertyName%
, then JBoss ON interprets the value as the current values of the corresponding properties from the script's parent resource's connection properties. - Finish configuring the operation, as in Section 11.2.1, “Scheduling Operations”.
11.2.6. Setting an Operation Timeout Default
- Open the
rhq-server.properties
file.vim serverRoot/jon-server-3.3.0.GA/bin/rhq-server.properties
- Change or add the value of the
rhq.server.operation-timeout
parameter to the amount of time, in seconds, for the server to wait before an operation times out.rhq.server.operation-timeout=60
11.2.7. Operation History Report
Figure 11.2. Operation History Report

configurationHistory.csv
.
Chapter 12. Summary: Using JBoss ON to Make Changes in Resource Configuration
- Directly edit resource configuration. JBoss ON can edit the configuration files of a variety of different managed resources through the JBoss ON UI.
- Audit and revert resource configuration changes. For the specific configuration files that JBoss ON manages for supported resources, you can view individual changes to the configuration properties and revert them to any previous version.
- Define and monitor configuration drift. System configuration is a much more holistic entity than specific configuration properties in specific configuration files. Multiple files for an application or even an entire platform work together to create an optimum configuration. Drift is the (natural and inevitable) deviation from that optimal configuration. Drift management allows you to define what the baseline, desired configuration is and then tracks all changes from that baseline.
12.1. Easy, Structured Configuration
key1 = value1 key2 value2
<default-configuration> <ci:list-property name="my-list"> <c:simple-property name="element" type="string"/> <ci:values> <ci:simple-value value="a"/> <ci:simple-value value="b"/> <ci:simple-value value="c"/> </ci:values> </ci:list-property> </default-configuration>
Figure 12.1. Configuration Form for a Samba Server

- There is instant validation on the format of properties that are set through the UI.
- Audit trails for all configuration changes can be viewed in the resource history for both external and JBoss ON-initiated configuration changes.
- Configuration changes can be reverted to a previous stable state if an error occurs.
- Configuration changes can be made to groups of resource of the same type, so multiple resources (even on different machines) can be changed simultaneously.
- Alerts can be used in conjunction with configuration changes, either to send automatic announcements of any configuration changes or to initiate operations or scripts on related resources as configuration changes are made.
- Access control rules are in effect for configuration changes, so JBoss ON users can be prevented from viewing or initiating changes on certain resources.
12.2. Identifying What Configuration Properties Can Be Changed
Figure 12.2. Configuration Tab

12.3. Auditing and Reverting Resource Configuration Changes
12.4. Tracking Configuration Drift
- Drift looks at whole files within a directory, including added and deleted files and binary files.
- Drift supports user-defined templates which can be applied to any resource which supports drift monitoring.
- Drift can keep a running history of changes where each changeset (snapshot) is compared against the previous set of changes. Alternatively, JBoss ON can compare each change against a defined baseline snapshot.
- System password changes
- System ACL changes
- Database and server URL changes
- JBoss settings changes
- Changed JAR, WAR, and other binary files used by applications
- Script changes
Chapter 13. Changing the Configuration for a Resource
13.1. Changing the Configuration on a Single Resource
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Open the Configuration tab for the resource.
- Click the Current subtab.
- To edit a field, make sure the Unset checkbox is not selected. The Unset checkbox means that JBoss ON won't submit any values for that resource and any values are taken from the resource itself.Then, make any changes to the configuration.The list of available configuration properties, and their descriptions, are listed for each resource type in the Resource Reference: Monitoring, Operation, and Configuration Options.
- Click the Save button at the top of the properties list.
13.2. Changing the Configuration for a Compatible Group
- The group members must all be the same resource type.
- All group member resources must be available (UP).
- No other configuration update requests can be in progress for the group or any of its member resources.
- The current member configurations must be successfully retrieved from the agents.
- Click the Inventory tab in the top menu.
- In the Groups box in the left menu, select the Compatible Group link.
- Select the group to edit.
- Open the Configuration tab.
- Click the Current subtab.
- To edit a field, make sure the Unset checkbox is not selected. The Unset checkbox means that JBoss ON won't submit any values for that resource and any values are taken from the resource itself.Then, make any changes to the configuration.The list of available configuration properties, and their descriptions, are listed for each resource type in the Resource Reference: Monitoring, Operation, and Configuration Options.NoteIt is possible to change the configuration for all members by editing the form directly, but it is also possible to change the configuration for a subset of the group members. Click the green pencil icon, and then change the configuration settings for the members individually.
- Click the Save button at the top of the form.
13.3. Editing Script Environment Variables
- Click the Inventory tab in the top menu.
- Search for the script resource.
- Open the Configuration tab for the script resource.
- Click the plus sign (+) to add an environment variable.
- Enter the environment variable. Each new environment variable has the format name=value; and is added on a new line.If the variable's value contains properties with the syntax
%propertyName%
, then JBoss ON interprets the value as the current values of the corresponding properties from the script's parent resource's connection properties. - After resetting an environment variable, restart the JBoss ON agent to propagate the changes. If the agent isn't restarted, new variables will not be propagated to the resource and will not resolve when the script is next executed, even if the configuration is correct.
@echo off
in Windows scripts to prevent echoing the executed commands along with the execution results.
13.4. Configuring Apache for Configuration Management (Deprecated)
13.4.1. Considerations and Notes for Apache Configuration Management
Deprecated Augeas Plug-in
Apache configuration management is supported through a special Augeas agent plug-in, which connects with and manages the Augeas lens on the Linux instance. The Augeas agent plug-in is deprecated in JBoss ON 3.1.1 and may be removed in a later release.
Augeas and Apache Monitoring
The Augeas lens is not required for Apache monitoring. It is only used for Apache configuration management. An Apache resource can be monitored, with alerting, operations, and all other management tasks available without any additional configuration. The Augeas lens is used only for editing the Apache configuration files and virtual hosts through JBoss ON.
Supported Platforms for Apache Configuration
Apache configuration management is only supported for Apache instances installed on Linux.
Disabling noexec Options for Apache Directories
If the /tmp
directory is configured a noexec in the fstab
file, the agent throws exceptions because it cannot properly initialize the Augeas lens. In that case, the Configuration tab is unavailable for the Apache resource.
/tmp
directory does not have noexec set as an option.
#
# /etc/fstab
#
tmpfs /dev/shm tmpfs defaults 0 0
devpts /dev/pts devpts gid=5,mode=620 0 0
sysfs /sys sysfs defaults 0 0
proc /proc proc defaults 0 0
13.4.2. Enabling Configuration Management
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then search for the Apache resource.
- Click the IP address of the Apache instance.
- Open the Inventory tab, then click the Connections subtab.
- Jump to the Augeas Configuration section.
- Select the Yes radio button to enable the Augeas lens.
Chapter 14. Tracking Resource Configuration Changes
14.1. Tracking and Comparing Configuration Changes
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Open the Configuration tab for the resource.
- Click the History subtab.
- Select the line of the configuration version to view or compare. Use the Ctrl key to select multiple versions. The current (most recent successful) configuration state is marked by a green check mark.
- Click the Compare button.
- The pop-up window shows all of the changes in a directory-style layout, with each of the configuration areas as a high-level directory. Any changes are marked in red, and the values are shown for each selected version.
14.2. Reverting Configuration Changes
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Open the Configuration tab for the resource.
- Click the History subtab.
- Select the line of the configuration version to roll back to. The current (most recent successful) configuration state is marked by a green check mark.
- Click the Rollback button.
14.3. Viewing the Configuration History Report
Figure 14.1. Configuration History Report

configurationHistory.csv
.
Chapter 15. Managing Configuration Drift
15.1. Understanding Drift
- What directories (and files within those directories) matter for drift monitoring? Even though a drift definition is defined for a resource, the actual drift detection is performed at the directory level. Drift monitoring, then, can hit anywhere on a platform — even outside resources managed by JBoss ON.
- How do you identify a change? Do you compare it to the version immediately before it or to an established baseline?
15.1.1. Drift Definitions and Detection
- From the plug-in configuration (pluginConfiguration). This means, it can be taken from any of the connection properties for the resource. Connection properties can include log files, deployment directories, and installation directories, depending on the resource type.
- From the resource configuration (resourceConfiguration). This means, it can be taken from any of the configurable properties for the resource.
- From a trait (measurementTrait). Traits are informational measurement properties for the resource.
- An explicit filesystem location. If none of the resource properties have the proper location or if a different location should be used for drift, then the directory can be specified in the fileSystem property.
/etc/
that only includes changes to *.conf
files, the elements in the drift definition are:
Value context: fileSystem Value name: /etc Includes: **/*.conf
Table 15.1. Combinations to Include Specific Files
Files to Monitor for Drift | 'Includes' Path | 'Includes' Pattern |
---|---|---|
/etc and all its subdirectories | Blank | Blank |
For *.conf files in /etc and all subdirectories | . | **/*.conf [a] |
For *.conf files only in the /etc directory, with no subdirectories (/etc/*.conf) | . | *.conf |
For *.conf files only in a subdirectory one level below /etc (/etc/*/*.conf) | Not possible | Not possible |
For any file in a specific subdirectory (yum.repos.d/) below /etc | yum.repos.d (subdirectory name) | Blank |
[a]
This must have a double asterisk for the directory part. It will not work with a single asterisk.
|
15.1.2. Snapshots, Deltas, and Baseline Images
- It can compare against the next-most recent version of the files.
- It can compare against a defined, stable baseline.
Figure 15.1. Rolling Snapshots

Figure 15.2. Pinned Snapshots

15.1.3. Destination Directories with Special File Types
ln -ls /home/dev/libs /usr/share/jbossas/server/libs
libs/
directory in the JBoss Enterprise Application Platform home directory, it will follow the symlink back to /home/dev/libs
, and include all of those files in the drift snapshot.
Table 15.2. Drift Definitions and Unix File Types
File Type | Supported by Drift? |
---|---|
File | Yes |
Directory | Yes |
Symbolic link | Yes |
Pipe | No |
Socket | No |
Device | No |
15.1.4. Drift and Resource Types
rhq-plugin.xml
descriptor, then that resource type supports drift. The template is a starting point (not an enforced configuration, like alert or metric collection templates).
- All platforms
- JBoss EAP 6 (AS 7), and all resources which use the JBoss AS 5 plug-in
- JBoss AS/EAP 5, and all resources which use the JBoss AS 5 plug-in
- JBoss AS/EAP 4 (deprecated)
15.1.5. Space Considerations for Drift Monitoring
- The size of the directory being monitored. In some cases, it may be better to monitor multiple smaller subdirectories rather than one large, high-level directory.
- The frequency of drift detection runs, balancing the need to capture changes versus the number of backup copies.
- How long drift snapshots are stored. By default, unused snapshots (meaning, unpinned snapshots) are stored for 31 days and then deleted. Changing how long snapshots are stored can help manage the database size.
15.1.6. Back to Drift Monitoring
Drift Monitoring
Drift monitoring is the ability to track changes to target locations. The JBoss ON GUI allows you to view snapshots all together, compare changes for individual files between snapshots, view the current configuration, and view change details. It also provides inventory and drift reports and indicates, at a glance, whether a resource is compliant with an associated pinned snapshot.
Drift Alerting
A specific alert condition exists that will trigger an alert whenever there is drift. For rolling snapshots, this will send an alert once (and only once) for each drift snapshot. For pinned snapshots, the drift alert is fired for every detection run for as long as the resource is out of compliance, even if there are no subsequent changes.
15.2. Adding a Drift Definition for a Resource
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Open the Drift tab for the resource.
- Click the New at the bottom to add a new definition.
- Select the template to use to as the basis for the new definition.Plug-in defined templates are defined in the platform and JBoss server resources, as well as any other resource which supports drift monitoring. Additional, user-defined templates can be also be created and applied.
- Give a unique name to the definition. The name and the base directory are combined to identify the definition within JBoss ON.
- Define the settings for the definition, like the interval and whether it is associated with the template. The properties are listed in Table 15.3, “Drift Definition Properties”.
- Set the base directory. This is the top-most directory where drift detection is run for the definition, and the scan recourses down.The template itself defines an initial directory, but it may be useful to set a more specific directory to use.
- Click the button with the green plus (+) sign to add a subdirectory to include or exclude. The directory can be the base directory by specifying a period (.) as the directory. The pattern identifies which files within the directory to recognize by the service, either to explicitly include or explicitly exclude.The filters support Ant-like FilePatterns, using a path and pattern. The patterns support asterisks (*) as wildcards for any number of characters and question marks (?) for single character wild cards. For example, **/*.conf can be used to include only
.conf
files in any subdirectory.There can be multiple include/exclude filters. Each directory and pattern can be added separately.
Table 15.3. Drift Definition Properties
Property | Description |
---|---|
Name | A name for the drift detection definition. The name and the base directory, together, uniquely identify the definition. |
Base Directory: Value Context |
The type of configuration property which is used to identify the base directory. This identifies what type of element in the resource supplies the value. There are four options:
|
Base Directory: Value Name | The actual value for the drift detection definition to use for the base directory context. For example, if this is a file system context, then the value name is the directory path. |
Includes |
Explicitly includes directories, files, or files and directories matching a pattern, relative to the base directory, in the drift detection.
The filters support Ant-like FilePatterns, using a path and pattern. The patterns support asterisks (*) as wildcards for any number of characters and question marks (?) for single character wild cards.
If a pattern is used, then a path must be specified, even if the path is the base directory. For example, to include only
.conf files in the base directory, the pattern is *.conf and the path is a period (. ) to indicate the local directory.
|
Excludes |
Explicitly excludes directories, files, or files and directories matching a pattern, relative to the base directory, from the drift detection.
The filters support Ant-like FilePatterns, using a path and pattern. The patterns support asterisks (*) as wildcards for any number of characters and question marks (?) for single character wild cards.
If a pattern is used, then a path must be specified, even if the path is the base directory. For example, to include only
.conf files in the base directory, the pattern is *.conf and the path is a period (. ) to indicate the local directory.
|
Enabled | Enables or disables the definition. Disabling a definition means that no detection scans are run. |
Interval | Sets the frequency, in seconds, where the definition is eligible for a detection run. This is not a hard setting. Because load or other scheduled operations for the agent, the detection run is not guaranteed to run at the specified interval. |
Pinned |
Sets whether drift is determined in a rolling way or if it is associated (pinned) with a baseline snapshot. If this is set when the definition is created, then the initial snapshot is used as the baseline.
Definitions attached to a pinned template cannot be unpinned. Definitions which are attached to an unpinned template or which are not attached to a template can be pinned or unpinned freely.
|
Drift Handling Mode | Sets whether drift changes are treated as events which trigger an alert (the default) or as expected, so that no alerts are triggered. |
Attached to Template |
Sets whether the resource-level definition is subordinate to a template. If it is attached to a template, then any changes to the template are reflected in the resource definition, including if the template is deleted.
By default, definitions are attached to the template from which they are created.
|
Description | A simple text description of the definition. |
15.3. Creating a Drift Definition Template
15.3.1. About Resources and Drift Definition Templates
Example 15.1. A JBoss Server Drift Definition Template
<drift-definition name="Template-Base Files" description="Monitor base application server files for drift. It defines monitoring for some standard sub-directories of the HOME directory. Note, it is not recommeded to monitor all files for an application server. There are many files, and many temp files."> <basedir> <value-context>pluginConfiguration</value-context> <value-name>homeDir</value-name> </basedir> <includes> <include path="bin" /> <include path="lib" /> <include path="client" /> </includes> </drift-definition>
- Drift templates are not automatically applied to a resource, unlike other template types in JBoss ON. Drift templates are used as the basis for creating resource-level definitions.
- Default drift templates are defined for resources as part of their plug-in descriptor. Custom, user-defined templates can be added along with those defaults.
- Every drift definition is based on a template initially, even if that definition is not attached to that template post-creation.
- Snapshots (the file sets associated with drift definitions) always originate on a resource with a drift definition first. For any content to be associate with a template, the resource-level snapshot has to be promoted up to the template. Drift templates do not generate snapshots or files and then push that down to the resource.
15.3.2. Creating a Drift Definition Template
- Click the Administration tab in the top menu.
- Select the Drift Definition Templates menu table on the left.
- Click the pencil icon for the resource type to add the template to. Not all resources support drift, so they cannot be selected.
- Click the New at the bottom to add a new template.
- Select the template to use to as the basis for the new template.Plug-in defined templates are defined in the platform and JBoss server resources, as well as any other resource which supports drift monitoring. Additional, user-defined templates can be also be created and applied.
- Give a unique name to the template. The name and the base directory are combined to identify the definition within JBoss ON.
- Define the settings for the definition, like the interval and whether it is enabled by default. The properties are listed in the table in Section 15.2, “Adding a Drift Definition for a Resource”.
- Set the base directory. This is the top-most directory where drift detection is run for the definition, and the scan recourses down.
- Click the button with the green plus (+) sign to add a subdirectory to include or exclude. The directory can be the base directory by specifying a period (.) as the directory. The pattern identifies which files within the directory to recognize by the service, either to explicitly include or explicitly exclude.The filters support Ant-like FilePatterns, using a path and pattern. The patterns support asterisks (*) as wildcards for any number of characters and question marks (?) for single character wild cards. For example, **/*.conf can be used to include only
.conf
files in any subdirectory.
15.4. Editing Drift Definitions

15.5. Viewing Snapshots and Changes
15.5.1. Viewing the Snapshot Carousel
Figure 15.3. Viewing Snapshots

- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab for the resource.
- Click the name of the drift definition.
- The snapshot carousel shows, by default, the four most recent snapshots.
- Optionally, filter the snapshots to view. There are two elements that can be used to search for snapshots:
- The change type within the snapshot, whether a file was added, deleted, or modified.
- The path of a change within the snapshot. This path filter is a substring filter based on the paths and files in the drift entries.
15.5.2. Comparing Drift Changes
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab for the resource.
- Click the name of the drift definition.
- Click the names of the files to compare.
- Click Compare.
Figure 15.4. Change Set Diffs

15.5.3. Viewing Snapshot Details
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab for the resource.
- Click the name of the drift definition.
- In the snapshot carousel, click the magnifying glass by the name of the snapshot to view.
- Expand the directory to show the list of changes for that snapshot.
- To see the details of a specific change, click the (view) link.
- The details for that file shows links to display the immediate previous version of the file, the changed version of the file, and a diff between the two.When clicking the view link, the page title has the version number along with the file name. For example, when viewing version 6 of
myfile.txt
, the title is myfile.txt:6.
15.5.4. Seeing Drift Events in the Timeline
- Click the Inventory tab in the top menu.
- Search for the resource.
- In the Summary tab, click the Timeline subtab.
- The detection runs where drift was detected show up in the timeline as Drift Detected. To see only drift events in the timeline, clear all but the Drift checkbox.The time interval can be reset to adjust the span of the timeline.
15.5.5. Checking Drift Snapshot Reports
- Click the Reports tab in the top navigation menu.
- Select the Recent Drift report from the Subsystems report list.
- Every drift instance is listed, sorted by the snapshot creation time.
- Optionally, filter the list of drift changes. There are four filter options:
- The definition name
- The snapshot number (which crosses drift definitions)
- The change type within the snapshot, whether a file was added, deleted, or modified.
- The path of a change within the snapshot. This path can be a directory, a specific file name, or a search expression.
recentDrift.csv
.
15.6. Pinning Snapshots and Managing Compliance
15.6.1. More About Pinning Snapshots
- It removes any snapshots that were created before that snapshot. For example, if an administrator decides to pin Snapshot 7, Snapshot 0 (the initial image) through Snapshot 6 are all deleted, and Snapshot 7 becomes the new Snapshot 0.
- It creates a baseline image that every change is compared against rather than keeping a moving tally of changes.
- It changes the behavior of drift alerts (Section 15.8, “Defining Drift Alerts”) so that alerts are sent continually until the system configuration is back in compliance with the pinned snapshot.
- The definition it is pinned to cannot be deleted until the snapshot is unpinned.
- If a snapshot is pinned to a template, then all of the resource-level definitions attached to that template automatically use the pinned snapshot as their baseline.
- Any new file added after a snapshot is pinned (or any file deleted) is going to be reported as a new file in every subsequent snapshot. This is because the new snapshot is always compared against the baseline snapshot, so the file is always new to the baseline.There is some logic to prevent drift from reporting the same change incessantly. If
file1.txt
is added, the agent creates snapshot 1. When the agent does its next detection run, it recognizes thatfile1.txt
is not in the baseline, but as long as the SHA forfile1.txt
has not changed, the agent does not report it as new drift and does not take a new snapshot. Iffile1.txt
is modified, however, the agent notices the new SHA and sends a new snapshot — with the modifiedfile1.txt
still listed as a new file, because it is compared against the baseline, not the previous version.
15.6.2. When to Pin to a Resource and When to Pin to a Template
- Pinning a snapshot to a resource-level definition establishes a baseline for that resource alone. This makes sense while you are still developing an ideal baseline image or for unique environments that may not transition over to other resources.Pinning to a resource definition allows a lot of flexibility. It is easy to pin and unpin and select a new snapshot as the baseline, to let administrators develop an ideal configuration with a minimal impact on drift events, alerting, and monitoring because the changes are contained.
- Pinning a snapshot to a template means that baseline can be applied to every resource that uses that template; it allows that one single snapshot to be used across multiple resources. This is makes sense for any kind of repeatable configuration areas and for production or critical systems which must have consistent configuration.Pinning to a template is very powerful for maintaining consistency across an entire infrastructure once an ideal configuration has been developed.
15.6.3. Pinning to a Resource-Level Definition
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab.
- Click the name of the drift definition.
- In the snapshot carousel, click the magnifying glass by the name of the snapshot to pin.NoteThe initial snapshot is not displayed in the carousel. To pin the initial snapshot, click the thumbtack icon in the Pinned column of the drift definition list. That opens the initial snapshot.If a snapshot has already been pinned, then clicking the thumbtack icon opens the pinned snapshot.
- At the bottom of the change list, click the Pin to Definition button.
15.6.4. Pinning to a Template
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab.
- Click the name of the drift definition.
- In the snapshot carousel, click the magnifying glass by the name of the snapshot to pin.NoteThe initial snapshot is not displayed in the carousel. To pin the initial snapshot, click the thumbtack icon in the Pinned column of the drift definition list. That opens the initial snapshot.If a snapshot has already been pinned, then clicking the thumbtack icon opens the pinned snapshot.
- At the bottom of the change list, click the Pin to Template button.
- If the resource-level template is based on or attached to an existing template, then you can associate the snapshot with that existing template. If the base directory for the resource-level snapshot does not match any existing drift template, then you must create a new template.
- Create the drift template, as in Section 15.3, “Creating a Drift Definition Template”.
15.6.5. Checking Drift Compliance Reports
- Click the Reports tab in the top navigation menu.
- Select the Drift Compliance report from the Inventory report list.
- Every resource with a drift definition is listed by type and with an icon to indicate whether it is compliant (
) or non-compliant (
).
- To get information about the specific resources, click the resource type name; this opens a second inventory report under the main report. All of the resources of that type are listed with their compliance state.
driftCompliance.csv
.
15.6.6. Unpinning a Snapshot
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab.
- Click the pin icon for the drift definition.
15.7. Extended Example: Defining Required EAP Configuration
The Setup
Tim the IT Guy at Example Corp. has one EAP server running in his production environment. Because of the production load, the EAP server was routinely running out of memory, which was degrading its performance and causing downtime for Example Corp.'s website.
What to Do
There are three things that Tim wants to accomplish to maintain his EAP performance:
- Find a way to consistently apply configuration to EAP instances.He defines a template for JBoss EAP instances (Section 15.3, “Creating a Drift Definition Template”). To maintain consistency, the template sets the Attach to template value to true, and each resource-level drift definition will preserve that settings. This ensures that any changes to the template are automatically applied to the JBoss resource drift definitions.
- Use his current production settings as a basis for future EAP instances.He pins his latest snapshot, with the higher heap settings, to the template definition (Section 15.6.4, “Pinning to a Template”). Every EAP instance is going to be compared against that baseline, so any with the wrong heap setting will immediately be marked out of compliance.
- Be made aware of specific differences between his current EAP settings and his preferred settings.He creates an alert definition (Section 15.8, “Defining Drift Alerts”) which specifically targets the
bin/run.conf
file. This way, he knows precisely whether the heap settings and other JVM settings are wrong for his new instance. He can even use alerts to gather more information about how his EAP instance configuration is different, like using a CLI script to compare the current EAP configuration against the pinned snapshot and then send him the diff.
Expected Results
Tim brings a new server online, with a new EAP instance for the production environment. He applies the drift template to the new resource and, within a few minutes, receives a notification that his run.conf
file is not compliant with his preferred configuration. He changes the heap settings on the new EAP instance without having to wait for performance degradation to remember the change.
15.8. Defining Drift Alerts
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the resource name in the list.
- Click the Alerts tab for the resource.
- In the Definitions subtab, click the New button to create the new alert.
- In the General Properties tab, give the basic information about the alert.It may be useful to set a Priority if the drift definition contains critical configuration files.
- In the Conditions tab, select the Drift Detection option from the conditions list. To use the alert for all drift changes, leave the fields blank. Otherwise, enter the specific drift definition name and (optionally) the directories or files that must be modified for the alert to be triggered.NoteThere can be more than one condition set to trigger an alert, meaning that you can use the same alert for multiple drift definitions or files.
- In the Notifications tab, click Add to set a notification for the alert.Select the method to use to send the alert notification in the Sender option, and fill in the required information.The Sender option first sets the specific type of alert method (such as email or SNMP) and then opens the appropriate form to fill in the details for that specific method.
- Optionally, in the Dampening tab, give the dampening (or frequency) rule on how often to send notifications for drift.NoteFor pinned snapshots, it can be useful to use dampening rules to keep from getting a flood of alerts before a drift problem is remedied.Dampening only makes sense for a definition with a pinned snapshot. A pinned definition will fire alerts with every alert scan (every 10 minutes) for as long as it is out of compliance, even if there are no further changes. A rolling definition only fires an alert once, when drift is detected.Any of the dampening rules can be used. The ultimate goal is to limit the number of times that the same alert is set for a resource that is out of compliance with a pinned definition. For example, Time period sets a limit on the number of times in a given time period that an alert is issued if the alert condition occurs. Setting the occurrence to 1 and the time period to 4 hours means that when drift is detected once, the server sends an alert and then waits another 4 hours before sending the next alert.
- Click OK to save the alert definition.
15.9. Extended Example: Reverting a JBoss Server to Its Original Configuration Using Bundles and Server Scripts
The Setup
In Section 15.7, “Extended Example: Defining Required EAP Configuration”, Tim the IT Guy at Example Corp. set up drift templates and alerts to help manage the configuration on his production EAP servers. However, his resolution was done manually. When the drift alert notified him that his EAP server was out of compliance, he edited the run.conf
directly to adjust the heap size.
What to Do
The goal is to have JBoss ON respond intelligently to drift without requiring any action from Tim the IT Guy. There are two features that allow automated responses:
- Using bundles to provision updated files or applications. A bundle is a ZIP file that contains an Ant recipe and any required content (such as configuration files or JARs) for an application. JBoss ON can provision this content on a platform or a JBoss server in a specified directory.
- Launching JBoss ON CLI scripts in response to an alert. One of the possible alert notifications is a server-side alert sender. A JBoss ON CLI script is loaded as content and stored in the JBoss ON server; when the alert fires, it initiates the specified, stored CLI script.
- Create a bundle file based on the pinned snapshot configuration. The content of the bundle depends on the needs of the deployment. It can be specific configuration files, like
bin/run.conf
, or it can be a full EAP server.NoteIf the bundle contains the full EAP server, then it can be used to create the initial EAP server. - Deploy the bundle with the full EAP server to create the new EAP instance. (Or, if the bundle only has configuration files, create the EAP instances.)
- Set up the drift definitions, based on the previously configured template (Section 15.7, “Extended Example: Defining Required EAP Configuration”), for the new EAP instance.
- Create a JBoss ON CLI script (in JavaScript) that will automatically deploy the specified bundle to the appropriate destination. An example is in Example 15.2, “fix-eap.js Script”; in that script, replace the
destinationId
andbundleVersionId
with the real ID numbers for the destination entry and bundle version entry in JBoss ON. - Create an alert definition that triggers on the drift detection condition and uses the CLI script notification type, pointing to the JavaScript file that you created.
Expected Results
Any time drift is detected on the EAP server, it triggers an alert, same as in Section 15.7, “Extended Example: Defining Required EAP Configuration”. This time, the alert launches the CLI script in response and automatically deploys the bundle — which already has the approved EAP configuration — to the resource. This means that the EAP server is never more than a few minutes out of compliance, roughly the length of one alert scan. All without requiring intervention from Tim the IT Guy.
Example 15.2. fix-eap.js Script
/** * If obj is a JS array or a java.util.Collection, each element is passed to * the callback function. If obj is a java.util.Map, each map entry is passed * to the callback function as a key/value pair. If obj is none of the * aforementioned types, it is treated as a generic object and each of its * properties is passed to the callback function as a name/value pair. */ function foreach(obj, fn) { if (obj instanceof Array) { for (i in obj) { fn(obj[i]); } } else if (obj instanceof java.util.Collection) { var iterator = obj.iterator(); while (iterator.hasNext()) { fn(iterator.next()); } } else if (obj instanceof java.util.Map) { var iterator = obj.entrySet().iterator() while (iterator.hasNext()) { var entry = iterator.next(); fn(entry.key, entry.value); } } else { // assume we have a generic object for (i in obj) { fn(i, obj[i]); } } } /** * Iterates over obj similar to foreach. fn should be a predicate that evaluates * to true or false. The first match that is found is returned. */ function find(obj, fn) { if (obj instanceof Array) { for (i in obj) { if (fn(obj[i])) { return obj[i] } } } else if (obj instanceof java.util.Collection) { var iterator = obj.iterator(); while (iterator.hasNext()) { var next = iterator.next(); if (fn(next)) { return next; } } } else if (obj instanceof java.util.Map) { var iterator = obj.entrySet().iterator(); while (iterator.hasNext()) { var entry = iterator.next(); if (fn(entry.key, entry.value)) { return {key: entry.key, value: entry.value}; } } } else { for (i in obj) { if (fn(i, obj[i])) { return {key: i, value: obj[i]}; } } } return null; } /** * Iterates over obj similar to foreach. fn should be a predicate that evaluates * to true or false. All of the matches are returned in a java.util.List. */ function findAll(obj, fn) { var matches = java.util.ArrayList(); if ((obj instanceof Array) || (obj instanceof java.util.Collection)) { foreach(obj, function(element) { if (fn(element)) { matches.add(element); } }); } else { foreach(obj, function(key, value) { if (fn(theKey, theValue)) { matches.add({key: theKey, value: theValue}); } }); } return matches; } /** * A convenience function to convert javascript hashes into RHQ's configuration * objects. * <p> * The conversion of individual keys in the hash follows these rules: * <ol> * <li> if a value of a key is a javascript array, it is interpreted as PropertyList * <li> if a value is a hash, it is interpreted as a PropertyMap * <li> otherwise it is interpreted as a PropertySimple * <li> a null or undefined value is ignored * </ol> * <p> * Note that the conversion isn't perfect, because the hash does not contain enough * information to restore the names of the list members. * <p> * Example: <br/> * <pre><code> * { * simple : "value", * list : [ "value1", "value2"], * listOfMaps : [ { k1 : "value", k2 : "value" }, { k1 : "value2", k2 : "value2" } ] * } * </code></pre> * gets converted to a configuration object: * Configuration: * <ul> * <li> PropertySimple(name = "simple", value = "value") * <li> PropertyList(name = "list") * <ol> * <li>PropertySimple(name = "list", value = "value1") * <li>PropertySimple(name = "list", value = "value2") * </ol> * <li> PropertyList(name = "listOfMaps") * <ol> * <li> PropertyMap(name = "listOfMaps") * <ul> * <li>PropertySimple(name = "k1", value = "value") * <li>PropertySimple(name = "k2", value = "value") * </ul> * <li> PropertyMap(name = "listOfMaps") * <ul> * <li>PropertySimple(name = "k1", value = "value2") * <li>PropertySimple(name = "k2", value = "value2") * </ul> * </ol> * </ul> * Notice that the members of the list have the same name as the list itself * which generally is not the case. */ function asConfiguration(hash) { config = new Configuration; for(key in hash) { value = hash[key]; if (value == null) { continue; } (function(parent, key, value) { function isArray(obj) { return typeof(obj) == 'object' && (obj instanceof Array); } function isHash(obj) { return typeof(obj) == 'object' && !(obj instanceof Array); } function isPrimitive(obj) { return typeof(obj) != 'object'; } //this is an anonymous function, so the only way it can call itself //is by getting its reference via argument.callee. Let's just assign //a shorter name for it. var me = arguments.callee; var prop = null; if (isPrimitive(value)) { prop = new PropertySimple(key, new java.lang.String(value)); } else if (isArray(value)) { prop = new PropertyList(key); for(var i = 0; i < value.length; ++i) { var v = value[i]; if (v != null) { me(prop, key, v); } } } else if (isHash(value)) { prop = new PropertyMap(key); for(var i in value) { var v = value[i]; if (value != null) { me(prop, i, v); } } } if (parent instanceof PropertyList) { parent.add(prop); } else { parent.put(prop); } })(config, key, value); } return config; } /** * Opposite of <code>asConfiguration</code>. Converts an RHQ's configuration object * into a javascript hash. * * @param configuration */ function asHash(configuration) { ret = {} iterator = configuration.getMap().values().iterator(); while(iterator.hasNext()) { prop = iterator.next(); (function(parent, prop) { function isArray(obj) { return typeof(obj) == 'object' && (obj instanceof Array); } function isHash(obj) { return typeof(obj) == 'object' && !(obj instanceof Array); } var me = arguments.callee; var representation = null; if (prop instanceof PropertySimple) { representation = prop.stringValue; } else if (prop instanceof PropertyList) { representation = []; for(var i = 0; i < prop.list.size(); ++i) { var child = prop.list.get(i); me(representation, child); } } else if (prop instanceof PropertyMap) { representation = {}; var childIterator = prop.getMap().values().iterator(); while(childIterator.hasNext()) { var child = childIterator.next(); me(representation, child); } } if (isArray(parent)) { parent.push(representation); } else if (isHash(parent)) { parent[prop.name] = representation; } })(ret, prop); } (function(parent) { })(configuration); return ret; } /** * A simple function to create a new bundle version from a zip file containing * the bundle. * * @param pathToBundleZipFile the path to the bundle on the local file system * * @return an instance of BundleVersion class describing what's been created on * the RHQ server. */ function createBundleVersion(pathToBundleZipFile) { var bytes = getFileBytes(pathToBundleZipFile) return BundleManager.createBundleVersionViaByteArray(bytes) } /** * This is a helper function that one can use to find out what base directories * given resource type defines. * <p> * These base directories then can be used when specifying bundle destinations. * * @param resourceTypeId * @returns a java.util.Set of ResourceTypeBundleConfiguration objects */ function getAllBaseDirectories(resourceTypeId) { var crit = new ResourceTypeCriteria; crit.addFilterId(resourceTypeId); crit.fetchBundleConfiguration(true); var types = ResourceTypeManager.findResourceTypesByCriteria(crit); if (types.size() == 0) { throw "Could not find a resource type with id " + resourceTypeId; } else if (types.size() > 1) { throw "More than one resource type found with id " + resourceTypeId + "! How did that happen!"; } var type = types.get(0); return type.getResourceTypeBundleConfiguration().getBundleDestinationBaseDirectories(); } /** * Creates a new destination for given bundle. Once a destination exists, * actual bundle versions can be deployed to it. * <p> * Note that this only differs from the <code>BundleManager.createBundleDestination</code> * method in the fact that one can provide bundle and resource group names instead of their * ids. * * @param destinationName the name of the destination to be created * @param description the description for the destination * @param bundleName the name of the bundle to create the destination for * @param groupName name of a group of resources that the destination will handle * @param baseDirName the name of the basedir definition that represents where inside the * deployment of the individual resources the bundle will get deployed * @param deployDir the specific sub directory of the base dir where the bundles will get deployed * * @return BundleDestination object */ function createBundleDestination(destinationName, description, bundleName, groupName, baseDirName, deployDir) { var groupCrit = new ResourceGroupCriteria; groupCrit.addFilterName(groupName); var groups = ResourceGroupManager.findResourceGroupsByCriteria(groupCrit); if (groups.empty) { throw "No group called '" + groupName + "' found."; } var group = groups.get(0); var bundleCrit = new BundleCriteria; bundleCrit.addFilterName(bundleName); var bundles = BundleManager.findBundlesByCriteria(bundleCrit); if (bundles.empty) { throw "No bundle called '" + bundleName + "' found."; } var bundle = bundles.get(0); return BundleManager.createBundleDestination(bundle.id, destinationName, description, baseDirName, deployDir, group.id); } /** * Tries to deploy given bundle version to provided destination using given configuration. * <p> * This method blocks while waiting for the deployment to complete or fail. * * @param destination the bundle destination (or id thereof) * @param bundleVersion the bundle version to deploy (or id thereof) * @param deploymentConfiguration the deployment configuration. This can be an ordinary * javascript object (hash) or an instance of RHQ's Configuration. If it is the former, * it is converted to a Configuration instance using the <code>asConfiguration</code> * function from <code>util.js</code>. Please consult the documentation of that method * to understand the limitations of that approach. * @param description the deployment description * @param isCleanDeployment if true, perform a wipe of the deploy directory prior to the deployment; if false, * perform as an upgrade to the existing deployment, if any * * @return the BundleDeployment instance describing the deployment */ function deployBundle(destination, bundleVersion, deploymentConfiguration, description, isCleanDeployment) { var destinationId = destination; if (typeof(destination) == 'object') { destinationId = destination.id; } var bundleVersionId = bundleVersion; if (typeof(bundleVersion) == 'object') { bundleVersionId = bundleVersion.id; } var deploymentConfig = deploymentConfiguration; if (!(deploymentConfiguration instanceof Configuration)) { deploymentConfig = asConfiguration(deploymentConfiguration); } var deployment = BundleManager.createBundleDeployment(bundleVersionId, destinationId, description, deploymentConfig); deployment = BundleManager.scheduleBundleDeployment(deployment.id, isCleanDeployment); var crit = new BundleDeploymentCriteria; crit.addFilterId(deployment.id); while (deployment.status == BundleDeploymentStatus.PENDING || deployment.status == BundleDeploymentStatus.IN_PROGRESS) { java.lang.Thread.currentThread().sleep(1000); var dps = BundleManager.findBundleDeploymentsByCriteria(crit); if (dps.empty) { throw "The deployment disappeared while we were waiting for it to complete."; } deployment = dps.get(0); } return deployment; } var destinationId = 10002; var bundleVersionId = 10002; var deploymentConfig = null; var description = "redeploy due to drift"; // NOTE: It's essential that isCleanDeployment=true, otherwise files that have drifted will not be replaced with their // original versions from the bundle. var isCleanDeployment = true; deployBundle(10002, 10002, deploymentConfig, description, true);
15.10. Running Drift Detection Manually
- Click the Inventory tab in the top menu.
- Search for the resource.
- Click the Drift tab.
- Select the drift definition to run the scan for.
- Click the Detect Now button.
15.11. Setting Planned Changes or Disabling Drift Definitions
- Set the drift handling mode to planned changes. This keeps running drift detection scans and records changes. Since the changes are expected, though, it doesn't trigger a drift detection event, so it does not issue a drift alert.
- Actually disable the drift definition. This suspends the drift detection runs for the definition, not just drift events.
Figure 15.5. Drift Handling Mode and Enable Options

15.12. Changing How Long Drift Snapshots Are Stored
- In the Configuration menu, select the System Settings item.
- Scroll to the Data Manager Configuration Properties section.
- Change the storage times for the drift snapshots. Unused snapshots are not pinned or a baseline, while orphaned snapshots are related to disabled definitions.
15.13. Understanding Drift and JBoss ON Agents and Servers
15.13.1. Drift Inventory
agentRoot/rhq-agent/data/
directory. The information in this directory is deleted if the agent is started with new configuration (--cleanconfig
) or it can be intentionally purged (--purgedata
). If the drift information is lost, then the agent requests the last snapshot from the JBoss ON server.
15.13.2. The Drift Server Plug-in
Part III. Monitoring
Chapter 16. Introduction: Monitoring and Responding to Resource Activity
16.1. Monitoring and Types of Data
- Availability or "up and down" monitoring
- This is both basic and critical. Availability is status information about the resource, whether it is running or stopped.
- Numeric metrics
- Metrics are the core performance data for a resource. Almost every software product exposes some sort of information about itself, some measurable facet that can be checked. This is usually This numeric information is collected by JBoss ON, on defined schedules.Metric information is processed by the server. There are three states of the monitoring data used:
- Raw data, which are the readings collected on schedule by the agent and sent to the server
- Aggregated data, which is compressed data processed by the server into 1-hour, 6-hour, and 24-hour averages and used to calculate baselines and normal operating ranges for resources. These aggregated data are the information displayed in the monitoring graphs and returned in the CLI as metrics.
- Live values, which are ad hoc requests for the current value of a metric.Metric values are rolling live-streams of the resource state; they are essentially snapshots that the agent takes of the readings on predefined schedules. Those data are then aggregated into means and averages to use to track resource performance.Live values are immediate, aggregated, current readings of a metric value.
Metric information is especially important because it is collected and stored long-term. This allows for historical views on resource performance, as well as recent views. - Logfile messages (events)
- While JBoss ON is not a log viewer, it can monitor specified logs and check for important log messages based on severity or strings within the log messages. This is event monitoring, and it allows JBoss ON to identify incidents for a resource and to send an alert notification and, if necessary, take corrective action based on dynamic information outside normal metrics.
- Response time metrics
- Certain types of resources (URLs for web servers or session beans) depend on responsiveness as a component of overall performance. Response time or call-time data tracks how quickly the URL or session bean responds to client requests and helps determine that the overall application is performant.
- Descriptive strings (traits)
- Most resources have some relatively static information that describe the resource itself, such as an instance name, build date, or version number. This information is a trait. As with other attributes for a resource, this can be monitored. Traits are useful to identify changes to the underlying application, like a version update.
16.2. Alerts and Responses to Changing Conditions
- Alerts communicate that there has been a problem, based on parameters defined by an administrator.
- Alerts respond to incidents automatically. Administrators can automatically initiate an operation, run a JBoss ON CLI script to change JBoss ON or resource configuration, redeploy content, or run a shell script, all in response to an alert condition.Automatic, administrator-defined responses to alerts make it significantly easier for administrators to address infrastructure problems quickly, and can mitigate the effect of outages.
16.3. Potential Impact on Server Performance
- Database performance, which is the primary factor in most environments
- Network bandwidth
- Up to 30,000 metrics can be collected per minute
- Up to 100,000 alerts can be fired per day (roughly 70 per minute)
16.4. Differences with Monitoring Based on Different Resource Types
Chapter 17. Monitoring Reports and Data
- Dashboards with metrics portlets for individual resources, compatible groups, and the main dashboard
- Timelines, which aggregate all collected data, events, configuration, operations, and other changes for a resource
- Resource-level charts and tables for metrics
- A suspect metrics report for outlier or out-of-bounds metrics
17.1. Dashboards and Portlets
17.1.1. Resource-Level Dashboards
Figure 17.1. Resource Summary Tab

17.1.2. Main Dashboard
- Platform Utilization, which shows free memory, CPU usage, and other metrics related to platform performance.
- Alerted or Unavailable Resources, which shows a list of the most recent five resources which have issued an alert or been reported as down.
- Recent Alerts and Events that can be filtered by Date/Time, Name and Priority.
- A graph for a specific metric for a compatible group.
- A graph for a specific metric for a resource.
Figure 17.2. Dashboard Portlets with MOnitoring Data

17.1.3. Adding Monitoring Metrics to the Main Dashboard
Procedure 17.1. To add monitoring metrics to the dashboard
- Click the Inventory tab in the top menu, and navigate to the Resource.
- In the Monitoring tab, select the Metrics sub-tab.
- Select the metric from the list, and then click Add to Dashboard

17.2. Summary Timelines
Figure 17.3. Summary Timeline

17.3. Resource-Level Metrics Charts
- Section 19.2, “Viewing Metrics and Baseline Charts” for graphs and tables of the same metrics information
Figure 17.4. Metrics Chart

Figure 17.5. Hovering over a Data Point

Figure 17.6. Selecting a Subset of the Graph

17.4. Suspect Metrics Report

Figure 17.7. Out of Bounds Portlet

Figure 17.8. Suspect Metrics Reports

suspectMetrics.csv
.
17.5. Platform Utilization Report
- Current CPU percentage
- The actual memory usage, based on the available physical memory, buffer, and cache
- Swap
Figure 17.9. Platform Utilization Report

platformUtilization.csv
.
Chapter 18. Availability
18.1. Core "Up and Down" Monitoring
Figure 18.1. Resource Availability

Figure 18.2. Availability Uptime Percentage

18.1.1. Long Scan Times and Async Availability Collection
AvailabilityCollectorRunnable
class in the JBoss ON plug-in API. Details for this class are available in the Plug-in API and Writing Custom Plug-ins Guides.
rhq-agent-env.sh
file:
RHQ_AGENT_ADDITIONAL_JAVA_OPTS="$RHQ_AGENT_ADDITIONAL_JAVA_OPTS -Drhq.agent.plugins.availability-scan.timeout=15000"
18.1.2. Synchronous Availability
18.1.3. Availability States
Table 18.1. Availability States
State | Description | Icon |
---|---|---|
Available (UP) | The resource is running and responding to availability status checks. | ![]() |
Down | The resource is not responding to availability checks. | ![]() |
Unknown | The agent does not have a record of the resource's state. This could be because the resource has been newly added to the inventory and has not had its first availability check or because the agent is down. | ![]() |
Disabled | The resource has been administratively marked as unavailable. The resource (in reality) could be running or stopped. Disabling a resource means that the server ignores the availability reports from the agent to prevent unnecessary alerts based on a (known) down or cycling state. | ![]() |
Mixed (For groups only.) [a]
| The resources in a group have different availability states. | ![]() |
[a]
A similar warning sign can be displayed next to the resource availability at the top of the resource details page. That warning indicates that an error message or suspect metric has been returned for that resource, not that the resource's availability is in a warning state.
|
18.1.4. Parent-Child States and Backfilling
18.1.5. Collection Intervals and Agent Scan Periods
- An agent heartbeat ping (analogous to the platform's availability) is sent to the server every minute.
- Server availability is checked every minute.
- Service availability is checked every 10 minutes.
> avail -- force
18.2. Viewing a Resource's Availability Charts
- Click the Inventory tab in the top menu.
- Select the resource category, such as servers or services, in the Resources menu table on the left. Then browse or search for the resource.
- Click the name of the resource in the list.
- Open the resource's Monitoring tab.
Figure 18.3. Availability Charts

18.3. Detailed Discussion: Availability Duration and Performance
Figure 18.4. Availability Counts

- Total time in up, down, and disabled states
- Percentage of time time in up, down, and disabled states
- The number of times the resource has been in a down or disabled state
- The mean time between failures (MTBF) and mean time to recovery (MTTR)
Figure 18.5. Up and Down Monitoring

Figure 18.6. Availability Duration Alert

18.4. Detailed Discussion: "Not Up" Alert Conditions
- Up
- Down
- Unknown
- Disabled
Figure 18.7. Availability Change Conditions

18.5. Viewing Group Availability
- Click the Inventory tab in the top menu.
- Select the compatible or mixed groups item in the Groups menu on the left.
- Click the name of the group.
- Click the Inventory tab for the group.
Figure 18.8. Group Availability

Table 18.2. Group Availability States
If the Resource States Are .... | ... the Group State Is ... |
---|---|
Empty Group (Unknown) | Empty |
All Red (Down) | Red (Down) |
Some Down or Unknown | Yellow (Mixed) |
Some Orange (Disabled) | Orange (Disabled) |
All Green (Up) | Green (Up) |
18.6. Disabling Resources for Maintenance
- If the agent is still up, then the resource availability is still reported. It is just ignored by the JBoss ON server, and is not included in any availability calculations.
- Disabling a parent resource automatically disables all of its children, too.
- Click the Inventory tab in the top menu.
- Select the resource category, such as servers or services, in the Resources menu table on the left. Then browse or search for the resource.
- Select the resource in the list.
- Click the Disable button at the bottom of the page.
- When prompted, confirm that the resource should be disabled.
Figure 18.9. Disabled Resource

18.7. Allowing Plug-ins to Disable and Enable Resources Automatically
AvailabilityContext.disable()
and AvailabilityContext.enable()
methods as part of its availability definition in its component JAR files.
18.8. Changing the Availability Check Interval
- Click the Inventory tab in the top menu.
- Select the resource category, such as servers or services, in the Resources menu table on the left. Then browse or search for the resource.
- Click the Monitoring tab on the resource entry.
- Click the Schedules subtab.
- Select the availability metric, and enter the desired collection period in the Collection Interval field, with the appropriate time unit (seconds, minutes, or hours).NoteAvailability schedules can be set on compatible groups or resource type templates. Setting it at the group or resource type level changes multiple resources simultaneously.
- Click Set.
18.9. Changing the Agent's Availability Scan Period
- Open the agent configuration file.
vim agentRoot/rhq-agent/conf/agent-configuration.xml
- Uncomment the lines in the XML file, and set the new scan time (in seconds).
<entry key="rhq.agent.plugins.availability-scan.period-secs" value="60"/>
- Restart the agent in the foreground of a terminal. Use the
--cleanconfig
option to force the agent to read the new configuration from the configuration file.agentRoot/rhq-agent/bin/rhq-agent.sh --cleanconfig
Chapter 19. Metrics and Measurements
19.1. Direct Information about Resources
Figure 19.1. Metric Graph

19.1.1. Raw Metrics, Displayed Metrics, and Storing Data
19.1.2. Current Values
Figure 19.2. Live Values Column

19.1.3. Counting Metrics: Dynamic Values and Trend Values
- Dynamic values show a momentary and changeable value, a current state. This includes things like the current number of connections to an application server or the CPU usage on a platform.
- Trend values are cumulative counts, totals since the resource was started or over its lifetime. These values only progress in a single direction (usually, but not always, higher)
Figure 19.3. Dynamic and Trend Values for Metrics

19.1.4. Baselines and Out-of-Bounds Metrics
Figure 19.4. Suspect Metrics Reports

Figure 19.5. Out-of-Bound Factors

19.1.5. Collection Schedules
19.1.6. Metric Schedules and Resource Type Templates
19.2. Viewing Metrics and Baseline Charts
- The resource-level Summary
- Graphs
- Tables

Figure 19.6. Individual Metric Graph

Figure 19.7. Metrics Table

Figure 19.8. Metric Graph within the Table

19.3. Defining Metrics Collection
19.3.1. Setting Baseline Calculation Properties
- In the Configuration menu, select the System Settings item.
- Scroll to the Automatic Baseline Configuration Properties section.
- Change the settings to define the window used for calculation.
- Baseline Frequency sets the interval, in days, for how often baselines are recalculated. The default is three days.
- Baseline Dataset sets the time interval, in days, used to calculate the baseline. The default is seven days.
19.3.2. Setting Collection Intervals for a Specific Resource
- Click the Inventory tab in the top menu.
- Select the resource category, such as servers or services, in the Resources menu table on the left. Then browse or search for the resource.
- Click the Monitoring tab on the resource entry.
- Click the Schedules subtab.
- Select the metric for which to change the monitoring frequency. Multiple metrics can be selected, if they will all be changed to the same frequency.
- Enter the desired collection period in the Collection Interval field, with the appropriate time unit (seconds, minutes, or hours).
- Click Set.
19.3.3. Enabling and Disabling Metrics for a Specific Resource
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Monitoring tab on the resource entry.
- Click the Schedules sub tab.
- Select the metrics to enable or disable.
- Click the Enable or Disable button.
19.3.4. Changing Metrics Templates
- In the top navigation, open the Administration menu, and then the Configuration menu.
- Select the Metric Collection Templates menu item. This opens a long list of resource types, both for platforms and server types.
- Locate the type of resource for which to create the template definition.
- Click the pencil icon to edit the metric collection schedule templates.
- Select the required metrics to enable or disable, and click the Enable or Disable button.
- To edit the frequency that a metric is collected, select the Update schedules for existing resources of marked type checkbox, and then enter the desired time frame into the Collection Interval for Selected: field.
- Click the Set button.
19.3.5. Adding a PostgreSQL Query as a Metric
- metricColumn
- count(id)
SELECT 'metricColumn', count(id) FROM my_application_user WHERE is_logged_in = true
- Click the Inventory tab in the top menu.
- Search for the PostgreSQL resource.
- Click the Inventory tab for the PostgreSQL database.
- Click the Import button in the bottom of the Inventory tab, and select Query.
- Fill in the properties for the query metric. Three fields are particularly important:
- The Table gives which table within the database contains the data; this is whatever is in the FROM statement in the query.
- The Metric Query contains the full query to run. The SELECT statement must be 'metricColumn',count(id) to format the query properly for the JBoss ON agent to interpret it as a metric.
SELECT 'metricColumn', count(id) FROM my_application_user WHERE is_logged_in = true
- The Name field is not important in configuring the metric, but it is important identifying the metric later.
Figure 19.9. Query: Total Logged-in User Count

Chapter 20. Events
20.1. Events, Logs, and Resources
- Linux (syslog)
- Windows (Windows event logs)
- Apache server (log files)
- JBoss EAP server (log files)
20.2. Event Date Formatting
date severity [class] message
YYYY-mm-dd HH:mm:ss,SSS HH:mm:ss,SSS dd MM yyyy HH:mm:ss,SSS
date SEVERITY [org.foo.bar] my message date [SEVERITY] [org.foo.bar] my message date ( SEVERITY ) [org.foo.bar] my message
20.3. Defining a New Event
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Inventory tab on the resource entry.
- Select the Connection Settings subtab.
- Click the plus icon under the Events Log section to add a log instance to monitor.
- Enable event log collection.
- Set the parameters for the event log collection.Depending on the resource being configured, there are slightly different options for the event log configuration. All of the resources all allow different filters to identify which log messages to include:
- A minimum severity of any error message.
- A regular expression or pattern to use on log message strings.
Additionally, the application servers and Linux allow different log locations to be specified. (The Windows resource uses its System Event Log.) Along with accommodating custom log locations, it also allows for other logging services to be used. For Linux, this allows both platform and program logs to be monitored; for application services, this allows logs within a messaging service to be checked.As discussed in Section 20.2, “Event Date Formatting”, there are different potential date formats that can be used in logging; if anything other than log4j is used, the pattern can be specified so that the agent can read the log entries.Figure 20.1. EAP Event Log Configuration
Unlike either the application servers or Windows, Linux systems can log events in a system file or in a listener. If an rsyslog server or local syslog listener is configured, then it is possible to select a listener (rather than a local file) and to add the listener port and bind address for a remote server.Figure 20.2. Linux Event Log Configuration
20.4. Viewing Events
- Click the Inventory tab in the top menu.
- Select the resource type in the Resources menu table on the left, and then browse or search for the resource.
- Click the Events tab on the resource entry. Events can be filtered by severity (debug, info, warn, error, and fatal).
- Click the specific event for further details.
20.5. Detailed Discussion: Event Correlation
Figure 20.3. Resource Timeline Cluster

Chapter 21. URL Response Time Monitoring
21.1. Call-Time (or Response Time) Monitoring for URLs
- Session beans, for EJB method calls.
- Web servers (standalone or embedded in an application server), for URL responses. Web servers require an additional response time filter with configuration on what URL resources to measure for response times.
21.2. Viewing Call Time Metrics
Figure 21.1. URL Metrics for a Web Server

21.3. Extended Example: Website Performance
The Setup
A significant amount of Example Co.'s business, services, and support is tied to its website. Customers have to be able to access the site to purchase products, schedule training or consulting, and to receive most support and help. If the site is slow or if some resources are inaccessible, customers immediately have a negative experience.
What to Do
Tim the IT Guy identifies three different ways that he can capture web application performance information:
- Response times for individual URLs
- Throughput information like total number of requests and responses
- Counts for critical HTTP response codes
- If there are poor response times and a high number of HTTP error 500 responses, then the alert can be configured with an operation to restart the web server (Section 25.3.2, “Detailed Discussion: Initiating an Operation”).
- If there are poor response times and a high number of HTTP error 404 response (meaning that resources may not be delivered properly), then the alert is configured to restart the database.
- If there are poor response times and a high number of total requests per minute, then it may mean that there is simply too much load on the server. The alert can be configured to create another web server instance to help with load balancing; using a JBoss ON CLI script allows the JBoss ON server to create new resources as necessary and deploy bundles of the appropriate web apps (Section 25.3.3, “Detailed Discussion: Initiating Resource Scripts”).

21.4. Configuring EJB Call-Time Metrics
- Click the Inventory tab in the top menu.
- Select the Services menu table on the left, and then navigate to the EJB resource.NoteIt is probably easier to search for the session bean by name, if you know it.
- Click the Monitoring tab on the EJB resource entry.
- Click the Schedules subtab.
- Select the Method Execution Time metric. This metric is the calltime type.
- Click the Enable at the bottom of the list.