JBoss Operations

Network 2.1
Feature Guide
The JBoss ON product consists of subsystems devoted to
different aspects of systems management and operations.

JBoss ON Team
Feature Guide

JBoss Operations Network 2.1 Feature Guide

The JBoss ON product consists of subsystems devoted to
different aspects of systems management and operations.
Edition 1

Author JBoss ON Team

Copyright © 2009 Red Hat, Inc.

Copyright © 2009 Red Hat, Inc.. This material may only be distributed subject to the terms and
conditions set forth in the Open Publication License, V1.0 or later (the latest version of the OPL is
presently available at http://www.opencontent.org/openpub/).

Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United
States and other countries.

All other trademarks referenced herein are the property of their respective owners.

1801 Varsity Drive

Raleigh, NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919 754 3701
PO Box 13588 Research Triangle Park, NC 27709 USA

The JBoss ON product consists of subsystems devoted to different aspects of systems management
and operations.
Preface vii
1. Document Conventions .................................................................................................. vii
1.1. Typographic Conventions .................................................................................... vii
1.2. Pull-quote Conventions ....................................................................................... viii
1.3. Notes and Warnings ............................................................................................ ix
2. We need feedback .......................................................................................................... x

1. Overview 1
1.1. Inventory ...................................................................................................................... 1
1.2. Configuration ................................................................................................................ 1
1.3. Monitoring .................................................................................................................... 2
1.4. Alerts ........................................................................................................................... 3
1.5. Operations ................................................................................................................... 3
1.6. Content (Packages) ...................................................................................................... 3
1.7. Groups ........................................................................................................................ 3
1.8. Security Model ............................................................................................................. 4
1.9. Administration .............................................................................................................. 4
1.10. Events ....................................................................................................................... 4

2. Inventory 5
2.1. Overview ..................................................................................................................... 5
2.2. Concepts ..................................................................................................................... 5
2.2.1. Resource Types ................................................................................................ 5
2.2.2. Resources ......................................................................................................... 6
2.2.3. Inventory states ................................................................................................. 6
2.3. Controlling Inventory ..................................................................................................... 7
2.3.1. Autodiscovery Portlet ......................................................................................... 7
2.3.2. Manual discovery .............................................................................................. 8
2.4. User Interface (Inventory Tab) ...................................................................................... 8
2.4.1. General section ................................................................................................. 8
2.4.2. Child resources ................................................................................................. 9
2.4.3. Group membership .......................................................................................... 11
2.4.4. Agent information ............................................................................................ 11
2.5. Creating New Resources ............................................................................................ 11
2.5.1. Overview ......................................................................................................... 11
2.5.2. Child Resource types ....................................................................................... 13

3. Configuration 17
3.1. Concepts ................................................................................................................... 17
3.1.1. Supported Resources ...................................................................................... 17
3.1.2. How Does Configuration Work? ........................................................................ 17
3.1.3. Property types ................................................................................................. 17
3.1.4. Revisions and History ...................................................................................... 18
3.1.5. Access Rights ................................................................................................. 18
3.2. The Configure Tab ..................................................................................................... 18
3.2.1. Current (Edit) View .......................................................................................... 18
3.2.2. History View .................................................................................................... 19

4. Monitoring 21
4.1. Concepts ................................................................................................................... 21
4.1.1. What Can Be Monitored ................................................................................... 21
4.1.2. Metrics versus Traits versus Response Time ..................................................... 21
4.1.3. Collection Schedules ........................................................................................ 22

iii
Feature Guide

4.2. The Monitor Tab ........................................................................................................ 23

4.2.1. Visibility Subtab ............................................................................................... 23
4.2.2. Events Subtab ................................................................................................. 25
4.2.3. Timeline subtab ............................................................................................... 25
4.2.4. Configure Subtab ............................................................................................. 25
4.3. Metric Chart ............................................................................................................... 25
4.3.1. Baseline .......................................................................................................... 26
4.4. Problem Metrics ......................................................................................................... 26
4.5. Data Storage .............................................................................................................. 27
4.6. Changes with regard to JON 1.x ................................................................................. 27
4.7. Response Times ........................................................................................................ 27
4.7.1. Concepts ......................................................................................................... 27
4.7.2. Enabling Response Time measurement ............................................................ 27
4.7.3. Monitor Tab ..................................................................................................... 29
4.7.4. Response Time Filter ....................................................................................... 30

5. Alerts 35
5.1. Overview .................................................................................................................... 35
5.2. Concepts and Terminology ......................................................................................... 35
5.2.1. Action Filter ..................................................................................................... 35
5.2.2. Alert ................................................................................................................ 35
5.2.3. Alert Definition ................................................................................................. 35
5.2.4. Alert Condition ................................................................................................. 35
5.2.5. Alert Dampening .............................................................................................. 36
5.2.6. Alert Notification .............................................................................................. 37
5.2.7. Condition Expression ....................................................................................... 38
5.2.8. Condition Log .................................................................................................. 38
5.2.9. Condition Set .................................................................................................. 38
5.2.10. Enable and Disable ........................................................................................ 38
5.2.11. Recovery ....................................................................................................... 39
5.3. Integrations ................................................................................................................ 39
5.3.1. Availability ....................................................................................................... 39
5.3.2. Measurement .................................................................................................. 40
5.3.3. Operations ...................................................................................................... 41
5.3.4. Traits .............................................................................................................. 42
5.3.5. Events ............................................................................................................. 42
5.4. Templates .................................................................................................................. 42
5.5. SNMP Traps .............................................................................................................. 42
5.5.1. How to set up sending of Traps ....................................................................... 43
5.5.2. The RHQ alert mib .......................................................................................... 43
5.5.3. Receiving of Traps and forwarding as Events .................................................... 44

6. Operations 45
6.1. Overview .................................................................................................................... 45
6.2. Concepts ................................................................................................................... 45
6.2.1. Supported Operations ...................................................................................... 45
6.2.2. Arguments ....................................................................................................... 45
6.2.3. Results ............................................................................................................ 45
6.2.4. Scheduling ...................................................................................................... 45
6.2.5. Operation State Management ........................................................................... 46
6.2.6. History ............................................................................................................ 47
6.3. Resource User Interface ............................................................................................. 47

iv
 6.3.1. New ................................................................................................................ 47
6.3.2. Scheduled ....................................................................................................... 48
6.3.3. History ............................................................................................................ 49
6.4. Resource Group User Interface ................................................................................... 49
6.4.1. New ................................................................................................................ 49
6.4.2. Scheduled ....................................................................................................... 50
6.4.3. History ............................................................................................................ 52
6.5. Script Execution ......................................................................................................... 53
6.5.1. Connection Properties ...................................................................................... 53
6.5.2. Executing Scripts ............................................................................................. 53
6.5.3. Results ............................................................................................................ 54
6.5.4. Tips and Tricks ................................................................................................ 54

7. Content (Packages) 55
7.1. Overview .................................................................................................................... 55
7.2. Concepts and Terminology ......................................................................................... 55
7.2.1. Package .......................................................................................................... 55
7.2.2. Package Type ................................................................................................. 55
7.2.3. Package Version ............................................................................................. 56
7.2.4. Package Bits ................................................................................................... 56
7.2.5. Installed Package ............................................................................................ 56
7.2.6. Content Source ............................................................................................... 56
7.2.7. Channel .......................................................................................................... 56
7.3. Package Discovery ..................................................................................................... 57
7.4. User Functions ........................................................................................................... 57
7.5. Applying JBoss Patches ............................................................................................. 57
7.5.1. Enabling the default JBoss Patch Content Source .............................................. 58
7.5.2. Subscribing Resources to the default JBoss Patch Channel ................................ 59
7.5.3. Applying a Patch ............................................................................................. 60

8. Groups 63
8.1. Overview .................................................................................................................... 63
8.2. Concepts and Terminology ......................................................................................... 63
8.2.1. Mixed Group ................................................................................................... 63
8.2.2. Compatible Group ............................................................................................ 64
8.3. Defining Groups ......................................................................................................... 64
8.3.1. Group Inventory ............................................................................................... 65
8.3.2. Implicit vs. Explicit Revisited ............................................................................. 66
8.3.3. Defining Groups via Group Definitions .............................................................. 66
8.4. Removing_Groups ...................................................................................................... 66
8.5. Groups and Availability ............................................................................................... 66
8.6. Groups and Connection Properties .............................................................................. 67
8.7. Group Connection Properties ...................................................................................... 67
8.7.1. Step 1 Viewing Group Connection Properties .................................................... 67
8.7.2. Step 2 Editing Group Connection Properties .................................................... 67
8.7.3. Step 3 Asynchronous Update Begins ................................................................ 68
8.7.4. Step 4 View History of Updates ........................................................................ 69
8.7.5. Step 5 View Update Details ............................................................................. 69
8.7.6. Step 6 View Group Update Results .................................................................. 70
8.8. Group Definitions and Dynamic Groups ....................................................................... 70
8.8.1. Introduction ..................................................................................................... 70
8.8.2. Subsystem Integrations .................................................................................... 71

v
Feature Guide

8.8.3. Syntax References .......................................................................................... 71

8.8.4. A Not-So-Short Tutorial .................................................................................... 73
8.8.5. Hints, Tips, and Tricks ..................................................................................... 75
8.8.6. Examples ........................................................................................................ 76
9. Security Model 79
10. Administration 83
10.1. Content Sources and Channels ................................................................................. 84
10.1.1. View All Content Sources ............................................................................... 84
10.1.2. View All Channels .......................................................................................... 85
10.2. High Availability ........................................................................................................ 85
10.2.1. List Servers ................................................................................................... 85
10.2.2. List Agents .................................................................................................... 86
10.2.3. List Affinity Groups ........................................................................................ 86
10.2.4. List Partition Events ....................................................................................... 87
10.3. Manage JON license ................................................................................................ 89
10.3.1. View Current License ..................................................................................... 89
10.3.2. Update License .............................................................................................. 89
10.4. Manage Plugins ....................................................................................................... 89
10.5. Monitoring Defaults ................................................................................................... 89
10.5.1. Metric Templates ........................................................................................... 90
10.5.2. Alert Templates ............................................................................................. 90
10.6. Roles ....................................................................................................................... 92
10.6.1. New Role ...................................................................................................... 92
10.6.2. List Roles ...................................................................................................... 93
10.6.3. View Role ...................................................................................................... 93
10.7. Server Configuration ................................................................................................. 93
10.7.1. JON Base URL Configuration Properties ......................................................... 93
10.7.2. Data Manager Configuration Properties ........................................................... 93
10.7.3. Automatic Baseline Configuration Properties .................................................... 94
10.7.4. LDAP Configuration Properties ....................................................................... 94
10.7.5. SNMP Server Configuration Properties ............................................................ 96
10.8. Users ....................................................................................................................... 96
10.8.1. New User ...................................................................................................... 96
10.8.2. List Users ...................................................................................................... 97
10.8.3. View User ..................................................................................................... 97
11. Events 99
11.1. Concepts .................................................................................................................. 99
11.2. Defining Event sources ............................................................................................. 99
11.2.1. Notes and Examples .................................................................................... 101
11.3. Viewing Events ....................................................................................................... 102
11.3.1. Visibility tab ................................................................................................. 102
11.3.2. Events tab ................................................................................................... 103
11.3.3. Timeline tab ................................................................................................. 104
11.4. Defining Alerts on Events ........................................................................................ 105
A. Revision History 107
Index 109

vi
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
1
In PDF and paper editions, this manual uses typefaces drawn from the Liberation Fonts set. The
Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not,
alternative but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes
the Liberation Fonts set by default.

1.1. Typographic Conventions

Four typographic conventions are used to call attention to specific words and phrases. These
conventions, and the circumstances they apply to, are as follows.

Mono-spaced Bold

Used to highlight system input, including shell commands, file names and paths. Also used to highlight
key caps and key-combinations. For example:

To see the contents of the file my_next_bestselling_novel in your current

working directory, enter the cat my_next_bestselling_novel command at the
shell prompt and press Enter to execute the command.

The above includes a file name, a shell command and a key cap, all presented in Mono-spaced Bold
and all distinguishable thanks to context.

Key-combinations can be distinguished from key caps by the hyphen connecting each part of a key-
combination. For example:

Press Enter to execute the command.

Press Ctrl+Alt+F1 to switch to the first virtual terminal. Press Ctrl+Alt+F7 to

return to your X-Windows session.

The first sentence highlights the particular key cap to press. The second highlights two sets of three
key caps, each set pressed simultaneously.

If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in Mono-spaced Bold. For example:

File-related classes include filesystem for file systems, file for files, and dir for
directories. Each class has its own associated set of permissions.

Proportional Bold

This denotes words or phrases encountered on a system, including application names; dialogue
box text; labelled buttons; check-box and radio button labels; menu titles and sub-menu titles. For
example:
1
https://fedorahosted.org/liberation-fonts/

vii
Preface

Choose System > Preferences > Mouse from the main menu bar to launch Mouse
Preferences. In the Buttons tab, click the Left-handed mouse check box and click
Close to switch the primary mouse button from the left to the right (making the mouse
suitable for use in the left hand).

To insert a special character into a gedit file, choose Applications > Accessories
> Character Map from the main menu bar. Next, choose Search > Find… from the
Character Map menu bar, type the name of the character in the Search field and
click Next. The character you sought will be highlighted in the Character Table.
Double-click this highlighted character to place it in the Text to copy field and then
click the Copy button. Now switch back to your document and choose Edit > Paste
from the gedit menu bar.

The above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in Proportional Bold and
all distinguishable by context.

Note the > shorthand used to indicate traversal through a menu and its sub-menus. This is to avoid
the difficult-to-follow 'Select Mouse from the Preferences sub-menu in the System menu of the main
menu bar' approach.

Mono-spaced Bold Italic or Proportional Bold Italic

Whether Mono-spaced Bold or Proportional Bold, the addition of Italics indicates replaceable or
variable text. Italics denotes text you do not input literally or displayed text that changes depending on
circumstance. For example:

To connect to a remote machine using ssh, type ssh [email protected] at

a shell prompt. If the remote machine is example.com and your username on that
machine is john, type ssh [email protected].

The mount -o remount file-system command remounts the named file

system. For example, to remount the /home file system, the command is mount -o
remount /home.

To see the version of a currently installed package, use the rpm -q package
command. It will return a result as follows: package-version-release.

Note the words in bold italics above — username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.

Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:

When the Apache HTTP Server accepts requests, it dispatches child processes
or threads to handle them. This group of child processes or threads is known as
a server-pool. Under Apache HTTP Server 2.0, the responsibility for creating and
maintaining these server-pools has been abstracted to a group of modules called
Multi-Processing Modules (MPMs). Unlike other modules, only one module from the
MPM group can be loaded by the Apache HTTP Server.

1.2. Pull-quote Conventions

Two, commonly multi-line, data types are set off visually from the surrounding text.

viii
 Notes and Warnings

Output sent to a terminal is set in Mono-spaced Roman and presented thus:

books Desktop documentation drafts mss photos stuff svn

books_tests Desktop1 downloads images notes scripts svgs

Source-code listings are also set in Mono-spaced Roman but are presented and highlighted as
follows:

package org.jboss.book.jca.ex1;

import javax.naming.InitialContext;

public class ExClient

{
public static void main(String args[])
throws Exception
{
InitialContext iniCtx = new InitialContext();
Object ref = iniCtx.lookup("EchoBean");
EchoHome home = (EchoHome) ref;
Echo echo = home.create();

System.out.println("Created Echo");

System.out.println("Echo.echo('Hello') = " + echo.echo("Hello"));

}

1.3. Notes and Warnings

Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.

Note
A note is a tip or shortcut or alternative approach to the task at hand. Ignoring a note
should have no negative consequences, but you might miss out on a trick that makes your
life easier.

Important
Important boxes detail things that are easily missed: configuration changes that only
apply to the current session, or services that need restarting before an update will apply.
Ignoring Important boxes won't cause data loss but may cause irritation and frustration.

ix
Preface

Warning
A Warning should not be ignored. Ignoring warnings will most likely cause data loss.

2. We need feedback
To see all outstanding issues regarding this guide, please visit: https://jira.jboss.org/jira/browse/JOPR

If you find a typographical error in the Features Guide, or if you have thought of a way to make this
manual better, we would love to hear from you! Please submit a report in JIRA: https://jira.jboss.org/
jira/browse/JOPR against the component Documentation.

If you do have a suggestion for improving the documentation, try and be as specific as possible
when describing it. If you have found an error, please include the section number and some of the
surrounding text so we can find it easily.

x
Chapter 1.

Overview
The JBoss ON product consists of subsystems devoted to different aspects of systems management
and operations.

1.1. Inventory
Inventory is responsible for finding and tracking the platforms, servers and services that will be
managed using JBoss ON. This system provides auto-discovery for easier deployment and thorough
models of deployed systems and applications. It provides the central administrator the ability to
configure which features will be used on which targeted services.

1.2. Configuration
Configuration supports reading, updating, and tracking changes to the settings for servers and
processes. These configuration changes can be tracked historical and even detect changes made
outside the system while providing an audited history and the ability to roll back to previous versions
for supported services.

1
Chapter 1. Overview

1.3. Monitoring
Monitoring manages the collection of statistics and state for managed products and the setup of
collection intervals and details. This system also provides running baselines to show metrics that go
out of their normal ranges.

2
 Alerts

1.4. Alerts
Alerts integrates with other subsystems to provide notifications of user defined conditions. This can
be utilized to notify administrators of performance problems or failed operations. Complex conditions
allow for detailed alert situations to be modelled while dampening allows for the right semantics before
starting of events.

1.5. Operations
Operations offer the ability to execution actions against resources in the inventory. These operations
depend on the resource, but can include actions such as stop, start and restart as well as clearing
caches or gathering detailed operation information.

1.6. Content (Packages)

The artifact subsystem is a mechanism through which a plugin can expose specific pieces of content
on a resource. This related content comes in the form of files such as executables, configurations,
or log files. The artifact subsystem will record these files in the inventory and capture metadata on
different revisions of the artifact and allow for deployment of new versions or content.

1.7. Groups
Groups deliver an important ability to aggregate detailed service models into components users can
understand. They also provide the underlying mechanism for application of access control semantics
with the security model.

3
Chapter 1. Overview

1.8. Security Model

The fine grained security model provides the ability to define specific levels of visibility, control
capability and access to any set of resources in inventory and users. It can be utilized to provide
visibility for coordination between groups while limiting risky change control to a exclusive set of users
devoted to a specific application or environment.

1.9. Administration

1.10. Events
Events are a type of measurement data, that unlike Metrics (see Chapter 11, Events) are not collected
at fixed intervals, but that occur at random points in time.

JBossON is able to pick up those events, filter them by severity, display them in the user interface and
have alerts sent based on defined event conditions.

4
Chapter 2.

Inventory
2.1. Overview
The "inventory" is the term for the central repository that houses items JBoss ON manages and
monitors (see Chapter 4, Monitoring). Before an item can take advantage of the feature set that JBoss
ON provide, it must first be imported into the inventory.

2.2. Concepts

2.2.1. Resource Types

A resource type is defined on a per-plugin basis, but a single plugin may define multiple resource
types. A resource type is a fairly generic concept that tries to identify and delineate a construct,
whether that be an entire operating system, a program running in some operation system, or a tiny
little service running inside that program. All resources have exactly one resource type, usually just
referred to as its type.

2.2.1.1. Resource Category

As indicated above, there are three major categories that any resource type falls into: an operating
system, a program, or a service. The vocabulary JBoss ON uses for these three groups is platform,
server, and service, respectively. Each of these resource categories is discussed in more detail below
in the context of how they are arranged hierarchically.

2.2.1.2. Resource Hierarchies

The resource hierarchy attempts to mimic, as closely as possible, how programs and processes are
physically and/or programmatically structured on a platform. Below are the supported ways resources
can be related by category.

Although a picture is worth a thousand words, below is a full text description for those that want to
know precisely what this one illustrates:

5
Chapter 2. Inventory

• A server can be a child of a platform (e.g. JBoss AS on Linux)

• A platform can have many children servers

• A service can be a child of a server or a platform (e.g. JMS Queue on JBoss AS)

• A platform can have many children services

• A server can have many children services

• A server can be a child of another server (e.g. Tomcat embedded in JBoss AS)

• A server can have many children services

• A service can be a child of another service (e.g. Table inside a Database)

• A service can have many children services

It's worth mentioning that a resource can only have one parent. Thus, the resource hierarchy we're
dealing with in JBoss ON actually takes the form of a directed, acyclic graph (DAG). The graph's root
is its platform, and the servers and services beneath it help to form a shallow, yet relatively wide tree.

2.2.2. Resources
Each resource is a concrete instance of one of the plugin-defined resource types. Thus, each resource
will have exactly one resource type. Resources are the actual instances of the platforms, servers, and
services that are installed on the boxes where the JBoss ON Agents reside.

2.2.3. Inventory states

Resources can be in the following states within JBoss ON

2.2.3.1. NEW
• most resources will be automatically discovered by JBoss ON

• the auto-discovery portlet on the dashboard will show discovered resources that have not yet been
either ignored or imported (a.k.a committed)

2.2.3.2. IGNORED
• this state is used to "hide" one or more auto-discovered resources; instead of being imported into
inventory, these resources can instead be "ignored"

• this feature is useful if the discovery process found servers that you're not interested in managing /
monitoring at this time

• resources in this state will not show up in inventory nor in the auto-discovery portlet

• to see resources that have previously been ignored (as well as to unignore them), click the "View
All..." button of the auto-discovery portlet

• unignoring a resource will put it back into the NEW state

• a resource must be unignored before it can be imported into inventory

6
 Controlling Inventory

Warning
It is currently not possible to ignore a resource until the platform has at least one
committed resource beneath it (thus implicitly commits the platform itself). It doesn't make
sense to ignore the platform, because then what was the point of installing an agent
on that box in the first place? If you ignore the platform, then you are ignoring all of the
children servers and services beneath it, so you might as well just not install the agent on
that box at all. Thus, for each new agent in the system, just make sure you commit at least
one resource; then you can ignore any and all other resources under that platform.

2.2.3.3. COMMITTED
• resources that have been imported successfully are marked as committed

• note: importing a resource will implicitly import (a.k.a commit) all of it's children resources
recursively

• when using the resource browser, only committed resources will be shown

2.3. Controlling Inventory

2.3.1. Autodiscovery Portlet

The usual way of taking resources into inventory is by using the autodiscovery portlet. As soon as you
connect a new JON Agent to the JON Server, it will send information about the platform and servers
it discovers (usually via a process table scan). This scan is performed when the JON Agent first starts
up, and then is done periodically to discover newly added resources in the system.

The discovered resources will be shown in the autodiscovery portlet on the Dashboard:

From here you can press the import button to commit the resource and take it into inventory. For each
platform or server committed, it will trigger another type of scan which will search recursively for all
nested servers and services.

The time it takes to find all of the nested resources beneath a parent resource may vary; it largely
depends on the number of resources there are to be discovered. Each server or service scanned in
this way will be automatically committed beneath its respective parent resource.

2.3.1.1. Autodiscovery queue

When you click on "View all..." you will be transferred to a list of all resources that are either new
or ignored. This auto-discovery queue is useful when dealing with larger inventories, as the auto-
discovery portlet doesn't wield very much screen real estate on the dashboard.

7
Chapter 2. Inventory

Here you can unignore resources or import any resources that are in new state.

2.3.2. Manual discovery

If for some reason it is not possible to auto-detect some resource in your enterprise, you still have the
option of manually adding it to inventory.

To add a new resource, use the resource browser to find what should be its logical parent resource.
Remember, since the resource browser only shows committed resources, you must first import the
parent in order to manually add a child resource to the inventory.

Click over to the inventory tab of this parent resource. The drop-down menu item labelled "Manually
add..." is the first step towards bringing a resource into inventory manually; select the type of resource
you want to add.

The next page will display all properties that the plugin requires (each resource type in the system has
a different set of required properties) in order to uniquely identify and successfully connect to this new
resource.

After submitting the form, the resource will start in the committed state, and thus be available for
viewing in the resource browser.

Warning
It is illegal to manually discover a resource unless the plugin can successfully connect to
the resource. With the properties that you were prompted to specify, the resource should
have a green availability icon next to it (meaning that it's UP).

Now the resource is ready to be monitored and managed like any other auto discovered resource.

2.4. User Interface (Inventory Tab)

You can reach the inventory tab for a resource by clicking its 'I' icon in the Browse Resources page.

This page is split into a few sections:

2.4.1. General section

This section shows general information about the resource like when it was taken into inventory, last
changed and its description.

8
 Child resources

Clicking the edit button lets you change the resource's name, description and location field.

2.4.2. Child resources

This section shows the children of current resource with their availability. The quick link icons known
from the Browse Resources page are available as well

2.4.2.1. Manually add child resources

Below the list of children you see the "Manually add" section referred to above in Section 2.3.2,
“Manual discovery”. This function serves to add child resources that were not autodiscovered.

The drop down menu will contain all resource types that can be manually added for this parent.
Selecting a type and clicking "OK" will lead to a template selection page:

9
Chapter 2. Inventory

Here you can select a template that fills in some default values. After this you will be forwarded to a
page where you can fill in the remaining values.

Please refer to Section 3.1.3, “Property types” to learn more about possible property types.

2.4.2.2. Create new child resources

Some resources also allow creation of new children. This means that the new child resource will be
created on the target resource as a new child. This way you can e.g. create a new JMS destination
directly from your JBoss ON console. If the managed resource allows the creation of child resources,
you will also see a "Create new" button.

As with manually adding a child resource, you will be forwarded to pages that are specific to the
respective resource type.

A more in-depth discussion can be found in Section 2.5, “Creating New Resources”.

2.4.2.3. Deleting resources

It is possible for some resource types to be physically deleted through JBoss ON. This is defined in the
Plugin Descriptor of the plugin handling the resource.

If a resource can be deleted, it will show a checkbox in front of it:

Checking the box will enable the "Delete selected" button. When you press it, you will be presented
with a warning where you can cancel the action or proceed the operation.

Clicking on "ok" will start the following operations:

• the resource will be removed from inventory (along with any metric history, operational history, etc)

10
 Group membership

• all of its child resource will also be removed from inventory (along with all history too)

• the resource and its children will be removed from any resource groups they are in

• the agent will delete the physical entity on the managed box

2.4.3. Group membership

This section shows the list of groups that this resource is part of.

In the example it is a compatible group named "Macs" with 1 member. The group availability is up (i.e.
all members are up).

Clicking on the 'I' icon or on the group name will open a new page where you can view the group
members and more group-specific items. See Chapter 8, Groups for more information.

2.4.4. Agent information

The last section on this page shows information about the agent that is managing this resource. This
will help you debug cases where you for example set up everything correctly but don't receive metric
data for monitoring

The section lists the IP address of the agent along with the port the agent is listening on for commands
from the server.

2.5. Creating New Resources

2.5.1. Overview
The "Create New" feature is used to create and deploy new child resources including EAR files, WAR
files, datasources, connection properties, JMS queues and JMS Topics. The process for creating each
of these resources is similar for all resource types. This is outlined below:

2.5.1.1. Create
1. Use the Browse Resources link to navigate to the parent resource

11
Chapter 2. Inventory

2. Click the "I" shortcut to access the Inventory tab.

3. Scroll to the bottom of the Child Resources table (midway down the page) to the Create New drop
down menu item. Select the resource type you'd like to create and click OK.

4. Enter the information for the resource to be deployed and click CREATE

5. Results

• A message indicating whether the request to deploy this resource was successfully sent to the
agent or not will be displayed at the top of the page.

• The success or failure of the actual deployment attempt will be listed in the "History of Create
Child Resource Requests" table at the bottom of the Child Resources table.

• Reload the page in order to get an updated status of the deployment

2.5.1.2. Delete
1. Use the Browse Resources link to navigate to the parent resource

2. Click the "I" shortcut to access the Inventory tab.

3. Check the box next to each WAR or EAR application that you'd like to undeploy in the Child
Resources table

4. Click the DELETE button.

Warning
Undeploying a resource with the DELETE button will actually remove the resource
from the disk.

5. Results:

• A message indicating whether the request to delete this resource was successfully sent to the
agent or not will be displayed at the top of the page.

• The success or failure of the actual undeploy attempt will be listed in the "History of Delete Child
Resource Requests" table at the bottom of the Child Resources table.

• Reload the page in order to get an updated status of the undeploy

12
 Child Resource types

2.5.2. Child Resource types

2.5.2.1. EAR and WAR

Both Enterprise Application Archives (EARs) and Web Application Archives (WARs) are child
resources of a JBossAS Server resource. As with other child resources, they are deployed via the
"Create New" feature on the Inventory tab.

1. Follow the instructions detailed in Section 2.5.1.1, “Create”, browsing to the JBossAS Server
resource you'd like to deploy the archive to.

2. Select the Create New drop down menu item for either a "- Web Application (WAR)" or "-
Enterprise Application (EAR)" and click OK

3. Enter the information for the application to be deployed

Property Definition Example

Resource Name This is the name that this Foo web app
resource will be listed as in
the JON inventory
Package Name This is the name of the file (or foo.war
directory) that the EAR/WAR
will be deployed as. The name
should end in ".ear" or ".war"
Package Architecture For EAR/WAR deployment, noarch
the package architecture
should always be "noarch"
File The full path to the file to be /home/user/applications/
deployed foo.war
Deploy zipped "Yes" if the file should remain no
zipped upon deployment, "No"
if the file should be exploded
Deploy directory (Version 2.0) The directory (Version 2.0) deploy (Version
to deploy the file to, either 2.0.1) deploy/myapplications
"deploy" or "farm" (Version
2.0.1) Path relative to the AS
configuration set directory into
which to deploy. This cannot
be an absolute path nor can it
refer to a parent directory (e.g.
using ..).
Table 2.1. EAR and WAR properties

13
Chapter 2. Inventory

4. Follow the instructions detailed in Section 2.5.1.1, “Create” to determine the result of the resource
creation

2.5.2.2. Datasource
Datasources are a child resource of a JBossAS Server resource. As with other child resources, they
are deployed via the "Create New" feature on the Inventory tab.

1. Follow the instructions detailed in the Section 2.5.1.1, “Create” section of this document, browsing
to the JBossAS Server resource you'd like to deploy the archive to.

2. Then select the Create New drop down box for "- Datasource" and click OK

3. Datasource templates can be used to pre-populate a datasource with common information.

Choose the template you'd like to use:

Template Description
Default template An empty template, use this for Postgres,
MySQL or other datasources
Oracle Local TX An Oracle-specific template used for a
datsource with local transactions
Oracle XA An Oracle-specific template used for a
datasource with XA transactions

4. Enter the information for the resource to be deployed

Property Definition Example

Type The type of datasource No TX Datasource
to create, either No TX
Datasource, Local TX
Datasource or XA Datasource
JNDI Name A unique JNDI name under MyNewDS
which the DataSource
wrapper will be bound.
Driver Class The fully qualified name of the org.postgresql.Driver
JDBC driver or datasource
class
Connection URL The JDBC driver connection jdbc:postgresql://127.0.0.1:5432/
URL string foo
Username The username to connect to foobar
the datasource with (if any)
Password The password to connect to foobar
the datasource with (if any)
Min Pool Size The minimum connection pool 10
size for this datasource
Max Pool Size The maximum connection 50
pool size for this datasource

14
 Child Resource types

Property Definition Example

Advanced Settings all other settings are detailed
in the JON Server Guide.

5. Follow the instructions detailed in the Section 2.5.1.1, “Create”> section of this document to
determine the result of the resource creation

2.5.2.3. Connection Factories

Connection Factories are a child resource of a JBossAS Server resource. As with other child
resources, they are deployed via the "Create New" feature on the Inventory tab.

1. Follow the instructions detailed in the Section 2.5.1.1, “Create” section of this document, browsing
to the JBossAS Server resource you'd like to deploy the archive to.

2. Select the Create New drop down box for "- Connection Factory" and click OK

3. Enter the information for the resource to be deployed

Property Definition Example

Resource Name The name the resource will be My Connection Factory
listed as in the inventory
Connection Factory Type Either Transaction or No- no-tx-connection-factory
Transaction
JNDI Name A unique JNDI name under MyNewDS
which the DataSource
wrapper will be bound.
Username The username to connect to foobar
the datasource with (if any)
Password The password to connect to foobar
the datasource with (if any)
Min Pool Size The minimum connection pool 10
size for this datasource
Max Pool Size The maximum connection 50
pool size for this datasource
Advanced Settings all other settings are detailed :
in the JON Server Guide.

4. Follow the instructions detailed in the Section 2.5.1.1, “Create” section of this document to
determine the result of the resource creation

2.5.2.4. JMS Queues and Topics

JMS Queues and JMS Topics are child resource of a JBossMQ Service or JBossMessaging Service
resource (which itself is a child of a JBossAS Server). As with other child resources, they are deployed
via the "Create New" feature on the Inventory tab.

1. Follow the instructions detailed in the Section 2.5.1.1, “Create” section of this document, browsing
to the JBossMQ Service resource you'd like to deploy the archive to.

15
Chapter 2. Inventory

2. Then select the Create New drop down box for "- JMQ JMS Topic" or "- JMQ JMS Queue" and
click OK

3. Enter the information for the resource to be deployed

Property Definition Example

Resource Name The name the resource will be My JMS Queue resource
listed as in the inventory
Queue Name or Topic Name Name of the queue or topic MyQueue
to be used as the JMX object
name
JNDI Name A unique JNDI name under MyQueueJNDI
which the queue or topic will
be bound.
Advanced Settings all other advanced settings
are detailed in the Managed
Resources - JMQ JMS Queue

and Managed Resources -

JMQ JMS Topic pages

4. Follow the instructions detailed in the Section 2.5.1.1, “Create” section of this document to
determine the result of the resource creation

16
Chapter 3.

Configuration
3.1. Concepts

3.1.1. Supported Resources

Some, but not all resources are configurable via JBoss ON. Whether a resource is configurable or not,
and what aspects of a resource are configurable, are determined by the plugin's Plugin Descriptor.

Resources (or, more appropriately said, resource types Section 2.2.1, “Resource Types”) that support
configuration will either show a "Configure" tab when the resource is selected or a little 'C' icon on the
Browse Resources page in the User Interface (UI).

3.1.2. How Does Configuration Work?

As already stated, this depends on the individual resource type and how the plugin writer implemented
it for the specific resource.

In general the steps are always the same:

• JBoss ON presents the user with the current configuration

• The user changes the configuration and submits it

• JBoss ON sends the configuration update asynchronously to the agent managing the specific
resource

• The agent applies the configuration changes and reports success or failure along with the now
current configuration back to the server

• The server lists the new configuration revision on the history page

3.1.3. Property types

Configurable properties come in different types, that are configured in the Plugin descriptor for each
resource type. Those are e.g.

• String

• Number

• Lists

JBoss ON will check the entered data when submitting the configuration update form.

Unset properties

For some properties, you will see an "Unset" checkbox just to the right of the property name, as in the
following example:

17
Chapter 3. Configuration

Such properties are considered optional properties. That is, they do not require a value to be specified.
If a property is marked unset, JBoss ON will not submit any value for that property to the managed
resource, which tells the managed resource to use its default value for that property (which may or
may not be null).

There are often properties on the configure tab or also when manually taking a resource into inventory
where you don't want or don't need to specify values (refer to Section 2.4.2.1, “Manually add child
resources”. An example of this is the username and password properties for a JBossAS resource; for
a JBossAS instance with an unsecured JNP server, these properties should be unset.

3.1.4. Revisions and History

JBoss ON saves configurations in a history table. This allows you to look at past versions. It also
allows you to see who has changed a configuration for auditing purposes.

Revision IDs

Revisions are keyed by a numeric id. The id numbers are shared between all configurable resources.
This means that if you e.g. have two resources A and B and you first configure A and then B and then
A again, A will most likely have revision numbers 1,2 and 5,6 while B will have numbers 3 and 4 for its
configuration revisions.

Revision ids will also advance by a bigger number when the JON server is restarted. So if for example
the last revision id was 7 before the restart, it could be 50 after the restart.

3.1.5. Access Rights

In order to configure a resource, the correct access rights need to be present. The exact rights needed
depend on the resource type. For the PostgreSQL database as an example you need to have both of:

• correct database superuser credentials

• the JBoss ON Agent needs to be able to read and write the postgres configuration files.

3.2. The Configure Tab

The configure tab shows by default the current configuration. At the top of it is a little "History" button
to switch to the history view.

3.2.1. Current (Edit) View

The current view shows the properties grouped together. What properties are grouped together are
defined in the Plugin Descriptor. Each group contains a name (e.g. General or Plugin Container)
shown in the group header. Clicking on the group header will collapse or expand it.

18
 History View

Some groups with seldom used properties are collapsed by default.

Clicking "Edit" at the top will allow you to change properties and display a "save" button at the bottom
of the page.

When "save" is invoked you will be forwarded to the history view where a message indicating that your
configuration request has been forwarded to the agent for processing will be displayed.

3.2.2. History View

The history view is split into two parts:

• on the top you will find some basic information about the current configuration

• below is a list of recorded configurations.

19
Chapter 3. Configuration

For each revision you can see when it was submitted, when the change was completed, if it
succeeded or failed and who triggered the change. If the JON system provided the revision (e.g. when
initially reading the configuration from the managed resource) the user field will be empty.

In case of a failure, you may click on the failure status and view details on why the request failed.

Clicking on a revision id will add a panel below that shows the properties of the selected revision. This
panel looks like the current view shown in Section 3.2.1, “Current (Edit) View”.

The revision id with the asterisk (*) next to it is the current configuration.

20
Chapter 4.

Monitoring
Monitoring is about gathering metric information from resources in order to graph them or to define
Alerts (Chapter 5, Alerts) on them.

Metric data is the information JBoss ON collects for a given platform, server or service. The data
JBoss ON collects depends on what type of server or service is being monitored. For instance, if
you monitor a Linux platform, you can see metric data about total, used, and free swap, total, used,
shared, and free memory, total, idle, and user CPU, and more. For an instance of Tomcat, you can
view details such as the JVM total memory, active thread count and thread group count, uptime,
process shared memory time, and more.

4.1. Concepts
This section identifies what can be monitored, the types of metrics and the collection intervals for the
metrics.

4.1.1. What Can Be Monitored

In principle everything that can be obtained through a Java program can be monitored. Currently there
are restrictions in the way that JON 2 can only monitor numerical or string based values. Values as
part of a bigger structure (like an array of values) need to be decomposed into individual values before
they can be monitored.

The data that finally is collected is defined in the Plugin Descriptor by the plugin writer.

4.1.2. Metrics versus Traits versus Response Time

JON 2 currently distinguishes between three different kinds of metrics:

• Numerical metrics

• Traits

• Response times.

4.1.2.1. Numerical Metrics (or metrics for short)

Metrics represent numerical values like e.g milliseconds passed, kilobytes transferred or rows in a
database table. These values are taken at regular intervals (for changing those intervals see below)
and sent to the server. The server stores them in the database and processes alert-able conditions on
them.

Metrics can be viewed as graphs or as numerical values on the Monitor tab of the application.

4.1.2.2. Traits
Traits are rarely expected and are treated as text. This therefore means that they cannot be graphed.
Instead, current trait values for a resource are always shown at the top of a page below the general
properties of that resource as illustrated in the following screen shot.

21
Chapter 4. Monitoring

Here the Inet4Address marked in green (for this example) is a trait of this network adapter with name
"Inet4Address" and value "172.31.7.7"

This display at the top of the page is only enabled if a trait has displayType=summary in its Plugin
Descriptor.

Traits values are also gathered by the Agent on regular intervals, but only changed traits are sent to
the server, stored and processed for alert-able conditions. All traits and a history of the trait values can
be viewed on the monitor tab.

4.1.2.3. Response Times

Response times denote the time it takes to serve a web request or a EJB method call. Response
times are described on their own page, but some concepts like the metric schedules shown below
apply for response times as well and will not be repeated.

4.1.3. Collection Schedules

The gathering of metrics is done on a regular basis. The plugin developer defines the default intervals
for a metric in the Plugin Descriptor. If they are too low, then they are increased as follows:

• metric: 5 minutes for displayType=summary, 10 minutes otherwise

• trait : 10 minutes for displayType=summary, 30 minutes otherwise

Please note that you can also modify the scheduled intervals to your requirements. You can either
change the default for all metrics of a certain resource type or only for a selected metric.

4.1.3.1. Default Schedules

The defaults for all resources of a certain resource type can be changed from the Administration
screen. Refer to Chapter 10, Administration, where you will find a section called "Monitoring defaults".

You see two links:

• Utilized types only: This will show a list of resource types that are in utilized by resources in the
inventory.

• All types: This will show a list of all defined resources, whether or not they are actually in use.

22
 The Monitor Tab

Clicking on "Edit metric template will then show a list of all metrics for that resource type.

The list contains the name of the metric and a description, its type, sampling interval and whether it is
turned on by default.

To modify the interval or enable/disable the collection of data, select the checkbox on the row and
enter the new data on the settings displayed.

The modified settings will if you click "Update schedules for existing resources of marked type" (the
default), not only be applied to new resources that are taken in to inventory, but also to existing
resources.

4.1.3.2. Schedules per Metric

On the monitor tab, there is a Configure subtab Section 4.2.4, “Configure Subtab” where you can
modify the schedule for an individual resource. This will be described below.

4.2. The Monitor Tab

This tab, reachable through the 'M' icon on the Browse Resources page, displays all resource
monitoring information.

4.2.1. Visibility Subtab

The visibility subtab provides monitoring information for a resource at a glance. It is divided into
various sections.

4.2.1.1. Resources List

This list shows direct children of the current resource and their Availability. If a row only shows one
single resource, a single click will display its monitoring tab. This is not possible in JBossON 2 beta1 if
the row shows a group of combined resources (indicated by the 'three little cubes' icon).

23
Chapter 4. Monitoring

The network adapter row specifies a set of resources while the other three are single resources.

4.2.1.2. Indicators
This tab shows graphs for metrics that were marked as "summary" in the Plugin Descriptor. The little
graphs refresh at regular intervals showing the latest data.

The graph shows the values in the given display timeframe and the current values for min, max and
average for that timeframe. If you click on the title of the graph, you will be directed to Section 4.3,
“Metric Chart” where you can see a more detailed graph of this metric.

On top of the indicators, you will see a line with colored dots. Those dots show the Availability of the
resource in the given Display timeframe Section 4.2.1.4, “Display Timeframe”.

This availability strip will always show 60 dots. So if you choose to display a 10 minute timeframe,
every dot shows the availability within a 10 seconds interval. The percentage given in the title also
applies to the timeframe selected.

4.2.1.3. Metric Data

This tab shows the data of all values gathered. The Metric data tab is divided into two parts: at the
bottom, you can view the numerical data and below this the trait data.

If you click on the name of a metric, it will be graphed on a larger graph display.

To view a trait's change history, click on its name.

4.2.1.4. Display Timeframe

At the bottom of the pages that display metrics, you will find a section called "Metric Display Range".
This serves to select the timeframe of the data that is displayed. It will also allow you to drill into
historical data.

24
 Events Subtab

Important
The timeframe setting is sticky. If you for example select the metric for a certain day,
you will from there on only view the data for that specific day until you explicitly select a
different time frame. This stickyness applies to metrics.

4.2.2. Events Subtab

Events are discussed in Chapter 11, Events.

4.2.3. Timeline subtab

The timeline is also discussed in Chapter 11, Events.

4.2.4. Configure Subtab

This page allows you to change the individual schedule for the selected single resource. This can
be handy if you e.g. don't want to count rows of database tables in general, but are interested in this
metric for one important table.

The screen shown is the same as shown above in Section 4.1.3.1, “Default Schedules”, except that
you can not apply the values to other resources.

4.3. Metric Chart

This chart gives you more information about a single metric

At the top you find a panel to select the data that you want to be displayed in the graph. Section 4.3.1,
“Baseline” related items can only be selected if a baseline has already been computed for that value.

Below you can find the actual graph:

25
Chapter 4. Monitoring

This example contains the blue bars for the measurement values, the horizontal lines for the minimum,
maximum and average for the timeframe shown.

4.3.1. Baseline
At the bottom of the page you'll find a panel to select and display the baseline and an expected value
range

A metric baseline is a value that represents the norm for a particular metric. JBoss ON automatically
calculates the baselines for dynamic metrics currently being collected for a resource. The baseline is
the average value of a metric based on a time range that you specify (see administration section). In
addition, the high and low range values are also calculated for the metric. You can also simply specify
the expected mean, high, and low range values. You can set and chart these values when you chart a
metric for a resource.

The use of a baseline as an analysis method compares changes in actual data against a baseline
value. This functionality allows you to perform trending analysis, manage SLAs, and monitor overall
application health as a form of fault management.

When you click on "Change value" you can set the baseline to a new auto computed value and the
expected ones to new minimum and maximum values respectively.

It is possible to define Alerts (Chapter 5, Alerts) that refer to Baselines or expected values.

4.4. Problem Metrics

JBoss ON automatically tracks the occurrences of the metric value collected for any given metric
falling outside (i.e. out-of-bounds, or O.O.B.) of the high and low range set in the base lining process
(either automatic or user-defined), and will report the given metric as a problem metric. In addition,

26
 Data Storage

when an alert occurs as a result of a metric value collected, the alerting event is also tracked as a
problem metric occurrence for that metric.

Resources with problem metrics are shown in the Problem Metric portlet on the Dashboard.

4.5. Data Storage

Measurement data is stored in the JBoss ON database. For numerical data, this will be compressed
and purged at regular intervals.

Detailed data will be compressed in cascades into tables for 1 hour, 6 hours and 1 day values, where
for each interval the minimum, maximum and average values are kept. This way data is saved at
smaller resolution for up to one year. The timeframe for which raw data is kept, can be defined on the
admin screen under server configuration.

4.6. Changes with regard to JON 1.x

• Availability is no longer considered a metric

• The concept of traits is new

• New Schedule defaults can be applied to new and existing resources

4.7. Response Times

4.7.1. Concepts
Response times denote the time it takes to serve a web request or a EJB method call. Unlike the
numerical metrics, this is most of the time an array of data in the sense that the one metric you enable
brings you min/avg/max data for all methods of a Session Bean or all URLs of a web application.

4.7.2. Enabling Response Time measurement

Before response times can be gathered or displayed, they first need to be enabled

4.7.2.1. EJB Call Times

In order to gather EJB call times you need to go to the configure section of the Monitor tab and enable
the collection of the call times:

Please refer to Section 4.1.3, “Collection Schedules” for more information about collection schedules
and defaults.

4.7.2.2. Web Application Response Times

In order to gather response times from web applications, you need to instrument the servlet container.
This process is described in Section 4.7.4, “Response Time Filter”.

27
Chapter 4. Monitoring

Note
The JBossON server is already instrumented.

After the filter is installed, you need to open the inventory tab of the web application and specify the full
path to the logfile:

There are two more properties that you can set:

• URL Excludes: Specifies URLs that should not be taken into account for the response time metrics.
Examples are e.g. static files like CSS files or images. Entries are regular expressions separated by
spaces. For example to exclude gif, jpg, and png files, use:

(?i)\.(jpg|gif)$

• URL Transforms: If a page is called with a different parameter, you may decide to show them as
separate URLs or as one URL only. The transform allows you to rewrite URLs to e.g. strip off those
parameters. Entries are substitution expressions separated by spaces. A substitution expression
has the syntax:

|<regular expression>|<replacement text>|

For example, to remove all query strings, use:

|(.*)\?.*|$1|

For WARs, the functioning of URL transforms depends on the settings of the Response Time Filter
(Section 4.7.4, “Response Time Filter”); particularly the chopQueryString parameter.

After this is done, you need to open the configure section of the Monitor tab and enable the collection
of the response times:

28
 Monitor Tab

Please refer to the Section 4.1.3, “Collection Schedules” for more information.

4.7.3. Monitor Tab

For resources that can collect response times, you will see another subtab on the monitor tab named
"Response time":

When you select it you will see two sections

• on the left the raw data table with the resource, number of calls and times

• on the right the call times visualized as bar diagrams

29
Chapter 4. Monitoring

4.7.4. Response Time Filter

In order to measure response times from web applications, you need to install a servlet filter on the
target web container

4.7.4.1. Generic Install

The installation consists of two parts:

• add an additional java library

• Update the servlet container configuration

4.7.4.1.1. Library installation

For the library installation, you need to copy the file rhq-rtfilter-1.1.0.jar to a directory in the classpath
of your servlet container. The specifics for containers are described below. This library can be found in
your agent distribution within the product_connectors/ directory.

4.7.4.1.2. Configuration update

The configuration update consists of two additions to the servlet container configuration. For different
JBoss AS versions, the file is identified in the servlet containers table below.

The two parts are a <filter/> and <filter-mapping/> directive. For the <filter/> directive,
you can just use the first one if you are happy with the defaults. If you want to modify the parameters,
you can use the enhanced one. Please use only one of the two options.

Previous to Servlet version 2.4 you must be careful to put the directives next to other directives of the
same kind. Filter related directives go in front of the <servlet/> sections.

Important
You may want to put the <filter/> in front of other filters so that the On Response Time
Filter can take their delay into account as well.

Simplest <filter/> section

<filter>
<filter-name>RhqRtFilter </filter-name>
<filter-class>org.rhq.helpers.rtfilter.filter.RtFilter </filter-class>
</filter>

Enhanced <filter/> section

<filter>
<filter-name>RhqRtFilter </filter-name>
<filter-class>org.rhq.helpers.rtfilter.filter.RtFilter </filter-class>
<init-param>
<description>Shall the filter directly chop off the query parameters from
the URL? Default is true. </description>

30
 Response Time Filter

<param-name>chopQueryString </param-name>
<param-value>true </param-value>
</init-param>
<init-param>
<description>Directory where logs are written to </description>
<param-name>logDirectory </param-name>
<param-value>/tmp </param-value>
</init-param>
<init-param>
<description>Prefix to written logfile names </description>
<param-name>logFilePrefix </param-name>
<param-value>localhost_7080_ </param-value>
</init-param>
<init-param>
<description>Patterns that should not be logged </description>
<param-name>dontLogRegEx </param-name>
<param-value> </param-value>
</init-param>
<init-param>
<description>Should the dontLog pattern be applied to the URI only? </
description>
<param-name>matchOnUriOnly </param-name>
<param-value>true </param-value>
</init-param>
<init-param>
<description>How many seconds between auto flushes of the logfile </
description>
<param-name>timeBetweenFlushesInSec </param-name>
<param-value>73 </param-value>
</init-param>
<init-param>
<description>How many lines shall be written to the logfiles before a
flush </description>
<param-name>flushAfterLines </param-name>
<param-value>13 </param-value>
</init-param>
<init-param>
<description>The maximum allowed size, in bytes, of the logfiles; if a
logfile exceeds this limit, the filter will truncate it; the default value
is 5242880 (5 MB) </description>
<param-name>maxLogFileSize </param-name>
<param-value>5242880 </param-value>
</init-param>
</filter>

and

<filter-mapping>
<filter-name>RhqRtFilter </filter-name>
<url-pattern>/* </url-pattern>
</filter-mapping>

31
Chapter 4. Monitoring

If your Servlet container's Servlet version is below Servlet 2.4, you will need to place it in the correct
section/order in the file - otherwise your servlet container will not start.

4.7.4.2. Description of init parameters

Parameter Description
chopQueryString Only the URI part of a query will be logged if this
parameter is set to true. Otherwise the whole
query line will be logged. Default is true.
logDirectory The directory where the logfiles will be written to.
Default setting is {jboss.server.log.dir}/
rt/ (usually server/xxx/log/rt). If
this property is not defined, the fallback is
{java.io.tmpdir}/rt/ (/tmp/ on Unix, and
~/Application Data/Local Settings/
Temp – check the TEMP environment variable)
is used. If you specify this init parameter, no
directory rt/ will be created, but the directory
you have provided will be taken literally.
logFilePrefix A prefix that is put in front of the logfile names.
Default is the empty string.
dontLogRegEx A regular expression that is applied to query
strings. See java.util.regex.Pattern. If the
parameter is not given or an empty string, no
pattern is applied.
matchOnUriOnly Should the dontLogRegEx be applied to the URI
part of the query (true) or to the whole query
string (false). Default is true.
timeBetweenFlushesInSec Log lines are buffered by default. When the
given number of seconds have passed and a
new request is received, the buffered lines will
be flushed to disk even if the number of lines to
flush after (see next point) is not yet reached..
Default value is 60 seconds (1 Minute).
flushAfterLines Log lines are buffered by default. When the given
number of lines have been buffered, they are
flushed to disk. Default value is 10 lines.
maxLogFileSize The maximum allowed size, in bytes, of the log
files; if a log file exceeds this limit, the filter will
truncate it; the default value is 5242880 (5 MB).

4.7.4.3. Specific install instructions for various containers

4.7.4.3.1. JBoss AS with embedded Servlet containers

Copy the jar file to the lib directory at $JBOSS_HOME/server/<config>/lib/

32
 Response Time Filter

Servlet container version Example Filter configuration file

Tomcat 6 JBoss 4.2, JBoss EAP $JBOSS_HOME/server/
<config>/deploy/jboss-
web.deployer/conf/
web.xml
Tomcat 5.5 JBoss 4.0.2 $JBOSS_HOME/server/
<config>/deploy/
jbossweb-tomcat55.sar/
conf/web.xml
Tomcat 5.0 JBoss 3.2.6 $JBOSS_HOME/server/
<config>/deploy/
jbossweb-tomcat50.sar/
conf/web.xml
Tomcat 4.1 JBoss 3.2.3 $JBOSS_HOME/server/
<config>/deploy/
jbossweb-tomcat41.sar/
web.xml

33
34
Chapter 5.

Alerts
5.1. Overview
Alerting is all about auditing events that happen across the system. After raw events are generated,
they are sent through the alerts processing engine. Here, they might be transformed, filtered, or
even correlated with data from other parts of the system. If some event makes it through all of those
gates successfully, then it is recorded permanently - the act of which might consequently trigger a
notification to various interested parties.

5.2. Concepts and Terminology

Since this a relatively large subsystem with a lot of unique concepts and constructs, and especially
because there have been a non-trivial number of changes to the alerts subsystem in JBoss ON 2.0,
it's important to begin with a set of terminology that will allow the rest of the alerts documentation to be
written more concisely.

5.2.1. Action Filter

Filters that are applied to an alert definition (Section 5.2.3, “Alert Definition”) after it triggers an alert
are referred to as action filters. These filters can, in theory, perform a wide range of post-processing
activities. They might change the preset notification policy for the definition, or they may even change
the state of the definition itself. Below is a quick discussion of each of the available action filters:

This definition, upon firing an alert, will disable itself. This prevents it from triggering any more alerts
while the problem that arose (and caused this alert to fire in the first place) is remedied either by
developers or system administrators.

5.2.2. Alert
An alert is a form of auditing data that tells you that some alert condition (Section 5.2.4, “Alert
Condition”) were known to be true at some point for some resource in inventory. Alerts are the end
product of an alert definition (Section 5.2.3, “Alert Definition”). An alert will tell you specifically which
conditions on the alert definition were true at the time it fired, and it will specify which parties were
notified at that time.

5.2.3. Alert Definition

Each resource in inventory may have zero or many alert definitions. An alert definition defines
how a specific list of alert conditions (Section 5.2.4, “Alert Condition”) (known as a condition set
(Section 5.2.9, “Condition Set”)) is evaluated, whether or not any filtering should take place, and what
notifications (Section 5.2.6, “Alert Notification”) to send to whom if an alert is fired from this definition.

5.2.4. Alert Condition

The alert condition is the main UI-facing construct that is used to integrate alerts with the other
systems. See Section 5.2.6, “Alert Notification” for more information.

35
Chapter 5. Alerts

5.2.5. Alert Dampening

Dampening is a form of filtering that occurs before an alert is fired. It is entirely based on the condition
set (Section 5.2.9, “Condition Set”) construct. Instead of being alerted each and every time the
processing engine finds the condition set to be true, you now have a the option to suppress it in
several ways. The available dampening options are discussed below:

This is the default option, and indicates that no dampening should take place. In other words, every
single time the condition set is known to be true, an alert will fire.

This form of dampening is good to use when you have a system that spikes a lot. If you know that your
CPU will often momentarily hit some high point but then should return to normal processing levels,
then you can use this dampening option to ensure that you only get an alert if the CPU remains spiked
for 2 or 3 consecutive measurement collections.

Setting the X option for this dampening rule to a high number is not recommended (though there are
a few valid use cases to do so) because you may likely want to be notified sooner rather than later if
one of your systems is experiencing such sustained problems. Remember, this option only needs the
condition set to be found false once for it to reset the counter. Therefore using too high a number may
effectively prevents alerts from ever being generated if you have just a few negative evaluations of
your condition set in between lots of positive ones.

This dampening rule is very similar to the last one, but it's not as restrictive. This option allows for the
condition set to be evaluated to false several times over a long span of evaluations and will still fire an
alert.

This could be useful when alerting on memory usage. If you want to set up an alert definition check
whether your free memory is being released periodically, you might use this dampening rule with X=5,
Y=10. So, the alerts processing engine will look back at the last ten evaluations, and if at least half
of them were positive, this might indicate that your process is having trouble releasing memory back
down to acceptable levels, and further investigation should be performed.

This option is nearly identical to the previous one, except that it is based on time instead of the number
of evaluations. This time-based evaluation, however, can be dangerous because the effects are not
always obvious.

36
 Alert Notification

Since the measurement subsystem is defined in terms of collection intervals, the alert processing
engine is thus restricted to the same concept when computing condition sets.

Assuming that you use this dampening rule and set the options to X=5, Y=30minutes. If the collection
interval is currently 5minutes, then Y=30minutes effectively becomes Y=6collections. However, if you
change your collection interval to 10 minutes, then Y=3collections. This might not seem so bad if the
person responsible for setting the collections intervals on this resource is the same as the person
responsible for creating all alert definitions too, but that is not always the case. Here, if someone
comes along and changes the collection interval for some measurement, he or she may inadvertently
and implicitly change how one or more alert definitions are dampened, resulting in either too many, too
few, or no alerts at all.

5.2.6. Alert Notification

After an alert is fired, the notification list for an alert definition is processed. Although alerts are always
recorded in the JBoss ON system, the user will never know of them until he or she logs into the
application, goes to a specific resource, and looks at the alerts that have been fired for that resource.

Instead of requiring users to perform this relatively slow method of checking on their alerts, JBoss ON
supports the concept of notifications. Notifications may be sent via SNMP traps or via email. The email
addressed can be registered against an alert definition in one of three ways: by direct email address,
by role, or by user. Each of these is discussed in the following sections. In addition it is possible to run
an operation when the alert fires.

5.2.6.1. Email Notification

This type is used to specify a list of direct email addresses to notify if an alert is fired on some alert
definition.

5.2.6.2. Role Notification

This type is used to specify a list of JBoss ON roles to notify if an alert is fired on some alert definition.
Processing works here by finding the list of JBoss ON users in each role, and notifying each user in
turn using the email address specified in that user's account.

5.2.6.3. User Notification

This type is used to specify a list of JBoss ON users to notify if an alert is fired on some alert definition.
Processing works here by obtaining the email addresses from the users' accounts, and sending the
notification email to each.

5.2.6.4. SNMP Trap

This option is only available if SNMP support has been enabled in the main administration link to the
Server Configurations page. When enabled, the alert will send a trap for each firing to the defined trap
listener.

5.2.6.5. Run Operations

For Resource types that allow Operations it is also possible to trigger those actions when an alert fires.
This allows e.g. to restart an application when its availability goes down. The operations section is
below the tabs for the other notifications. Choose Edit... to select the respective operation.

37
Chapter 5. Alerts

If the resource type does not allow operations, the selection will only have one option of "none".

Note that it is currently only possible to run the predefined operations on the resource itself. It is not
possible to e.g. restart a Web application (WAR) when the CPU is at 100% usage.

5.2.7. Condition Expression

5.2.7.1. ALL
Regardless of the size of the condition set, all alert conditions need to be true before an alert will fire.
It doesn't matter if one condition is known to be true several times in a row. The last known value
for each condition must be true simultaneously before this alert definition will fire an alert. This is
convenient when you have a system where individual events may happen frequently, but not actually
indicate a problem. Here, you can specify that multiple conditions must be true before the system
takes further action.

5.2.7.2. ANY
Regardless of the size of the condition set, only one alert condition needs to be true before an alert will
fire. This is really a convenience option for administrators. Instead of having to define 5 different alert
definitions, each with one condition based on the 5 different things that could happen in the system,
you only have to define one alert definition with 5 conditions and set the processing to ANY to get the
same effect.

5.2.8. Condition Log

A condition log is a piece of auditing data responsible for recording the time when a particular alert
condition was met, as well as the specific runtime value that made the condition true.

5.2.9. Condition Set

A condition set is the entire list of alert conditions specified under some alert definition. It is the key
construct used in alert dampening. To better understand the alert dampening options, you must
first understand what it means for a condition set to be true, which depends entirely on the type of
condition expression you selected for the alert definition.

5.2.10. Enable and Disable

When an alert definition is enabled (or active), it means that it is currently being checked by the alerts
processing engine to see if its condition set and dampening rules (Section 5.2.5, “Alert Dampening”)
have been met, and whether or not it should fire an alert off. If an alert is disabled (or inactive), it

38
 Recovery

will be hidden from the alerts processing engine, and will never fire an alert until it is re-enabled /
activated.

An alert definition can always be disabled manually via the UI. However, alert definitions will
sometimes be disabled by a post-processing action filter. Regardless of how an alert definition is
disabled, it can always be re-enabled manually via the UI. However, an automated recovery process
can also kick in to re-enable an alert definition too.

5.2.11. Recovery
Sometimes it is necessary to have two alert definitions work in tandem to provide a more intelligent
dampening scenario. For instance, if some condition set becomes true, it may indicate some system
state which cannot be automatically recovered from (i.e. human intervention is needed). Therefore an
alert is fired off when the original condition set is met, and using an action filter this alert definition is
automatically disabled.

A systems administrator gets the alert notification, and takes some manual intervention to correct
the problem. Once the issue is resolved (and conditions return to normal), another alert definition is
triggered. This second definition is the "Recovery Alert" definition for the one that was disabled above.
Thus, when this second definition fires, it will automatically re-enable the first one again.

Since recovery alert definitions are mainly used to indicate healthy scenarios, and in theory healthy
scenarios should ensue as close to 100% of the time as possible, one should be hard pressed to find
a good reason to add even one notification to this type of alert definition. Nonetheless, the option is
there.

5.3. Integrations
The alerts subsystem is a funnel for all different kinds of events that happen in the various other
subsystems of JBoss ON. To date, alerts are integrated with and can record events that happen to the
following types of data:
• Availability

• Measurement

• Operations

• Traits

• Events

5.3.1. Availability
The integration with availability data is fairly straight forward. Since the availability of a resource can
only ever be in one of two states - UP or DOWN - these are precisely the two states that the alerts
subsystem uses.

However, being in one of these states is not as import as moving between these states. In other
words, it doesn't make much sense to constantly be notified that some resource is UP...the resource is
UP...the resource is UP, etc. Likewise, after a resource goes DOWN, notifications past that point while
it is still down would be redundant.

For availability therefore, you can only be notified if the resource changes its state. Below is a
screenshot of what this part of the UI looks like:

39
Chapter 5. Alerts

Notice this is different from how JBoss ON 1.x processed availability. Instead of being a number
(where 1 means UP, 0 means down) the availability states are now a true enumeration. In 1.x,
administrators had to indicate they wanted to be notified of a 'downed' resource by saying "availability
< 1.00". The enumerated, state-based method that JBoss ON 2.0 uses is much more straightforward
and precise.

5.3.2. Measurement
The integration with measurement data is the most feature-rich integration to date. Here, you're
given several options for how you want the alerts processing engine to operate on the incoming
measurement data.

First, no matter which alert condition option you choose, you must first select a specific measurement
to operate against. The list of measurement choices are derived from the type of resource you are
looking at. Below is an image that shows the available measurements for a Platform:

Let's take the "Used Physical Memory" above as an example when describing the rest of the
measurement-related alert condition options:

5.3.2.1. Absolute
This option is a comparison of the most recently collected used physical memory value against an
absolutely specified value chosen by the user.

Here, the comparison can use any of the following three operators: "greater than", "less than", or
"equal to". For "equal to" comparison, since we're dealing with floating point numbers, if the values are
within 10e-9 of one another, they are considered equal.

40
 Operations

5.3.2.2. Percentage
For the example, the option is a comparison of the most recently collected used physical memory
value against a percentage of its known baseline. This alert condition option lets you choose whether
you want the comparison to be made against the minimum, mean, or maximum baseline value
currently recorded in the system. Notice how the last drop-down menu will show the current min,
mean, and max baseline values; this gives the users all the information they need on a single page,
enabling them to create the entire alert definition without having to navigate around to other parts of
the UI.

Again, you can again choose any of the following three operators: "greater than", "less than", or "equal
to". And, again, for "equal to" comparison, since we're dealing with floating point numbers, values are
considered equal if they are within 10e-9 of each other.

5.3.2.3. Relative
This option is a comparison of the most recently collected used physical memory value against its last
known value.

The user interface portion for this option is shown above, though it's rather dull.

5.3.3. Operations
To date, the integration with operations deals only with the current state of some operation, not its
operational data (arguments and results). The image below depicts what the UI will look like when
creating / editing an alert definition for a JON Agent resource type:

On the left-hand side you can view the list of operations for your resource. On the right-hand side, you
can view the list of all the states an operation can possibly be in. Each state is discussed below:

• INPROGRESS - this is the only begin state, all operations move through this en route to being
processed

41
Chapter 5. Alerts

• SUCCESS - this is a terminating state, operations move into this if no errors have occurred during
processing

• FAILURE - this is a terminating state, operations move into this if any error has occurred during
processing

• CANCELLED - this is a terminating state, operations move into this only if they are successfully
cancelled via the UI

5.3.4. Traits
The integration with traits is a subset of the functionality offered for measurement integration. Whereas
measurement data is always numeric and tends to change very frequently, trait data is rather static
and rarely changes. Thus, only relative comparison operations are supported for traits, which simply
compares the latest value collected for that trait to its last known value.

Above is an image that shows the available traits that you can monitor for a Platform.

5.3.5. Events
The integration with Events (Chapter 11, Events) is done in form of matching Severity and optionally a
string match on the Events detail.

5.4. Templates
It is possible to define alert templates that get applied to existing or new resources. Please refer to the
Monitoring Defaults page for details.

5.5. SNMP Traps

The JBossON server can send SNMP traps to other management stations and systems. The data
transmitted contains the name of the alert, the resource the alert is on among other details. This data
is defined in the MIB, which you can find in etc/RHQ-mib.txt within your server distribution.

42
 How to set up sending of Traps

5.5.1. How to set up sending of Traps

Before you can enable sending of traps, you need to generally enable SNMP trap sending in the
Server Configuration page within the administration GUI (refer to Section 10.7, “Server Configuration”.
If this is done, you can go to the individual alert definitions (or template) and define sending of traps.

5.5.1.1. General setup on the administration page

First choose the SNMP protocol version you want to use. This will open a panel with more information:

Depending on the protocol you, need to provide more information. In SNMPv1, the generic trap id
should be 6 to conform to the standard. You might choose a specific trap id to suit your requirements.

The agent address should be set to the IP address of your JBossON server.

For the other fields, you can also specify values that suit your requirements.

5.5.1.2. Specific setup per Alert

Now that the SNMP Traps are enabled in general, it is possible to define the target management
station for alerts. Please load the alert definition and then to the 'Notifications' section. On the
'Notifications' page, select the "SNMP Trap" tab as illustrated below:

Fields are as follows:

• Host: hostname of the management station

• Port: target port of the management station - this is currently UDP only

• OID: The base OID for the values sent by this trap. If you want to use the RHQ MIB, this has to be
1.3.6.1.4.1.18016.2.1 as described below.

5.5.2. The RHQ alert mib

The MIB file can be found in $JBOSS_ON_SERVER/etc/RHQ-mib.txt.

The base OID for this is 1.3.6.1.4.1.18016.2.1 (org.dod.internet.private.enterprise.jboss.rhq.alert)

Fields that are sent with each trap are:

• rhq.alert.1 - Name of the alert definition

43
Chapter 5. Alerts

• rhq.alert.2 - Name of the resource where the alert happened

• rhq.alert.3 - Name of the platform the resource is hosted on

• rhq.alert.4 - Conditions that led to the alert

• rhq.alert.5 - Severity of the Alert generating this trap

• rhq.alert.6 - URL of the alert detail

5.5.3. Receiving of Traps and forwarding as Events

RHQ has an experimental snmptrapd plugin. You can learn more on the respective RHQ plugin page
at http://support.rhq-project.org/x/SgAf.

44
Chapter 6.

Operations
6.1. Overview
Operations are all about executing functions against resources in inventory. Some of these operations
could change the operational state of a resource (such as start, stop, or restart commands), while
others can be purely informational (obtain some report data, or get a list of deployments).

The latest version of JBoss ON brings with it a lot of new features in the operations subsystem. In
1.x, operations (previously referred to as control actions) did not support complex results, and did not
support arguments at all. In 2.0, operations support arbitrarily complex arguments and results

6.2. Concepts

6.2.1. Supported Operations

Operations are defined by the plugin. More specifically, an operation is defined primarily by the type of
resource you're talking about, but it may be limited to specific versions of that type.

So, if you have two JBoss AS instances in inventory that were the exact same version (same
4.0.5.GA), they will support the exact same operations. However, a JBoss AS 4.0.2 instance may have
a slightly different list of supported operations than JBoss AS 4.2.1.

6.2.2. Arguments
Operational arguments actually piggyback on top of the same underlying constructs used to support
arbitrarily complex resource configuration data. Consequently, arguments are strongly typed, can
be required or optional, and inherit support for validation. Thus, regardless of how complicated the
arguments to a function might be, they can still be supported structurally as well as displayed in the UI.

6.2.3. Results
Operational results also piggyback on the same underlying constructs used to support resource
configuration data. Thus, regardless of how complicated the results from a function are, they can still
be supported structurally as well as displayed in the UI.

As with arguments, results too will be strongly typed, and inherit support for validation. Result
validation is a more complex way in which a plugin might determine whether an operation was
successful or not.

6.2.4. Scheduling
An operation can be executed immediately, or it can be deferred for future execution. A deferred
execution can be invoked once, or it can be invoked on a repeating interval. An interval can be
unbounded (i.e., the operation will be repeatedly invoked on the specified interval infinitely), or it can
have a termination date.

Regardless of which options are chosen, all operations necessarily go through the scheduler - even
ones marked to execute immediately. The scheduler has the responsibility for creating new operation

45
Chapter 6. Operations

schedules, managing the repeat intervals of each, knowing when to fire each scheduled operation,
and unscheduling operations as appropriate.

However, the scheduler does not have any responsibility for actually executing the operations
themselves. For this, it communicates with the operation manager.

6.2.5. Operation State Management

State management of an operation is separate from its scheduling. When the operation manager
gets the hand-off from the scheduler, it will create a new operation history record and set its state to
INPROGRESS. An asynchronous message is sent down to the agent telling it to invoke a specific
operation on a particular resource with the arguments that were specified when the schedule was
created. On a per resource basis, the agent queues up these operations; this prevents more than one
operation from being executed on any single resource at the same time.

The user interface will show this history item as a pending operation, at which point the user has the
opportunity to cancel it. If it is cancelled, another message is sent to the agent. If the message gets
there before the agent begins the operation, the agent will remove it from the queue, and tell the
server that its state can be set to CANCELLED.

On the other hand, once the agent has started the operation on the managed resource, it can no
longer be cancelled. In other words, even if the user attempts to cancel this operation in the UI, the
cancel request will effectively be ignored once the operation has begun. At first glance, this may seem
like a rather restrictive semantic; however, it was deemed as necessary because it would be next to
impossible for a plugin to know precisely what intermediate state the managed resource was in when
the operation was forcibly cancelled (assuming it was even possible to forcibly cancel it). So, instead
of coming up with a potentially very complex mechanism for determining what semi-completed state a
forcibly cancelled resource was in, no operation can be cancelled once it has been started.

Eventually, the operation will complete on the managed resource and pass its raw value back to the
plugin communicating with it. This plugin must analyze the raw output from the managed resource and
modify, transform, or craft an entirely different response message depending on the raw result. The
raw result will never be sent directly to the server, it must be wrapped in an object that matches the
expect result type as defined by the plugin for that operation.

Regardless of the details of the response, a non-cancelled operation can only ever wind up in two
states: SUCCESS or FAILURE. Operations that fail may be accompanied by a detailed error message
explaining the failure.

Occasionally, the server may be unable to communicate with the agent that is managing the
target resource. In this case, the operation will immediately be put into the FAILURE state, and the
accompanying error message will explain the details of the connectivity issues.

6.2.5.1. Timeouts
Occasionally, there are instances where an operation will "hang" on a managed resource. This would
normally spell trouble for the plugin because it cannot start the next operation on the resource until the
current operation completes.

Luckily, each plugin supports a timeout for invocations that don't complete in a timely fashion. Once
the timeout period expires, the operation is forcibly halted, the operation is marked as FAILURE, and
the error message will contain details of the timeout.

46
 History

The above is exactly what we were trying to avoid by not supporting forced cancellations of operation.
Halting an operation abruptly could potentially leave the resource in an inconsistent state. Though,
when an invocation is hung, there isn't much more that can be done other can a forcible termination of
the execution. This scenario is expected to be very rare.

Unfortunately, there are yet more risks in this scenario. The issue past this point is if there were other
operations waiting in the queue. If so, as soon as the currently executed operation is halted and
removed from the queue, the next operation proceeds as if nothing bad has happened. If the forced
cancellation was "safe", there should be no problem; but if the resource is in an inconsistent state, it
might cause a cascade failure of all operations executed against this resource in the future (perhaps
until the resource is restarted). Though if the administrator is using JBoss ON assiduously, he or she
should immediately be alerted that there have been consecutive operation execution failures, and that
manual intervention is probably needed to fix the problem.

6.2.6. History
The outcomes of all operations executed on a resource are recorded. The operation history is a way
to audit the results of these executions. When the scheduler deems that an operation needs to be
executed against some managed resource, it creates an operation history element and sets it state to
INPROGRESS. Items in this state are put in the pending operations table.

All other states of an operation - CANCELLED, SUCCESS, and FAILURE - are termination states.
Operations in any one of these states are shown in the completed operations table.

Completed operation data is never automatically purged, but a JBoss ON user can delete specific
elements that may be out-of-date or no longer relevant.

6.3. Resource User Interface

The operations tab has three sub tabs that are described below.

6.3.1. New
This tab presents you with a list of possible operations for the selected resource

When you choose one by clicking on it, it will be marked with a little asterisk and an option panel will
be displayed as illustrated below:

47
Chapter 6. Operations

You need to fill all required fields and decide if the operation should be scheduled for immediate (one
time) execution.

If you want to schedule the execution to happen at a different time or to recur, you need to select the
textbox. JON will present you with additional fields about the recurrence of the operation.

The "Other options" section lets you set a timeout and some notes.

Clicking "Schedule" schedules the operation.

Depending on when you scheduled the operation, you will be transferred to the "Schedule" or "History"
subtab.

6.3.2. Scheduled
This tab lists all operations scheduled for the future along with notes you entered when creating the
schedule and the owner of this scheduled operation

48
 History

Clicking on the operation name provides you with the schedule information like recurrence and
operation parameters.

You can also cancel a scheduled operation by selecting the operation in the list and clicking on
"unschedule" at the bottom.

6.3.3. History
The history view consists of two parts:

• operations in progress: an operation that is running is shown here

• completed operations: an operation that is completed is shown here

Both panels show the name of the operation, when it was submitted and completed and by whom as
well as its status. In case of failure you can click on the failure link to see why the operation failed (e.g.
missing permissions).

6.4. Resource Group User Interface

6.4.1. New
Supports everything that a resource supports, but adds one additional section entitled "Resource
Operation Ordering".

49
Chapter 6. Operations

This section allows you to choose whether you want to execute the operation against all group
members simultaneously, or define an ordering between them. If the ordering is selected, then JON
will execute one at a time, and wait for some return value (success or failure), before executing the
next operation.

In the "other options" section, you can choose to immediately halt the processing if the operation fails
on any resource.

6.4.2. Scheduled
Missing from JON 1.x was the ability to save the ordering between group members for execution. In
JON 2.x the ordering is saved as part of a scheduled operation.

One handy use of this is for server/service clusters. For example, let's assume that you want to restart
a cluster. You might have to shutdown the resources in a particular order, and then restart them in the
reverse order. You can create two schedules - one for startup, one for shutdown - and schedule those
operations to occur at a sufficiently advanced date/time. This way, the schedule will be created but will
not immediately fire.

At some later point in time you may come back to the group operations UI and want to execute that
saved operation. JON 2.x now supports an "Execute Now" button on the schedules page.

50
 Scheduled

However, if you want to make sure that you've selected the proper operation before executing it, click
on the appropriate row in the group operation schedule table, and view it's details. You can confirm
that the ordering is still as desired, and then click the "Execute Now" button from the schedule details
page.

51
Chapter 6. Operations

6.4.3. History
This section supports everything that a resource supports, but includes additional auditing data to be
able to show the operation results of each resource member in the group.

52
 Script Execution

6.5. Script Execution

JBoss AS Server has a service type called Scripts. The Script service will discover shell scripts within
the JBoss AS server's bin directory. You can also manually discover scripts through the JBoss AS
Server resource's Inventory page, even scripts in other directories.

Depending on the OS, the script types discovered are

• .bat for windows

• .sh and .pl scripts for Unix/Linux. (Scripts need to have the x-bit set)

Scripts are auto-discovered when JBoss AS server is discovered, or every 24 hours thereafter. If you
just dropped a script into the AS bin directory, it might be faster to manually discover the script. Or you
can force a discovery through the Agent Command Prompt using discovery -f (refer to the Agent
Command Line Options section in the JON Agent Guide)

While the script is a service of the JBoss AS, it does not mean that the script has to be JBoss App
Server specific. It can also be other OS scripts that you want to run. For instance, if you want a script
to clean out hanging processes nightly, you can create a script that will run at midnight each night that
will search for processes and kill them.

6.5.1. Connection Properties

Each Script service will have two connection properties.

1. Absolute path to the script.

2. Environment Variables

The environment variables that will be passed to the script; each variable must be on a new
line and have the syntax name=value; the variable's value can contain properties with the
syntax %propertyName% the script plugin will interpolate these with the current values of the
corresponding properties from the script's parent JBossAS server's connection properties.

You can edit the connection properties under the Inventory page for the script service.

6.5.2. Executing Scripts

1. Go to the Operations tab for the script service,

2. Select "execute script"

3. Enter any Command Line Arguments values you wish to pass to the script.

4. schedule an execution of the script

a. Select Immediate, if you want to run the script immediately.

b. If you wish to enter a specific start time enter the date and time and leave recur selected to
"never"

c. if you wish for the execution to recur, select "every" and choose how often you want the script
to recur. and finally choose a recurrence end, if you wish the recurrence to occur up to a
specific date.

53
Chapter 6. Operations

6.5.3. Results
All output that would appear in a console from running the script, will be viewable after running the
script by looking at the operations history details. To view the details, click on the name of the script in
the operations history list.

There you will see the details of the execution of the script including Name of the script, date and
submitted and date executed, the requester and the status. You will also see the command line
arguments that were passed, if any. and then Exit Code followed by the output. If you have a lot of
information expected in the output section, you might find it easier to view by selecting the text field's
contents and pasting it in your favourite text editor.

6.5.4. Tips and Tricks

• specify @echo off for windows scripts to prevent echo of the commands being executed being
interlaced with the execution results

• when adding a new environment variable to be used as the value for some operation argument
remember to:

• change the environment on the managed server (as opposed to the JON server), and

• restart the agent managing that server (otherwise the new variable will not be propagated, and will
not resolve during the operation execution)

54
Chapter 7.

Content (Packages)
7.1. Overview
The content subsystem is a mechanism through which a plugin can expose specific pieces of content
on a resource. Typically, this content comes in the form of files related to the resource, including
executable, configuration, or log files. The content subsystem will record these files in the inventory
and capture metadata on different revisions of the artifact.

7.2. Concepts and Terminology

7.2.1. Package
A package refers to an arbitrary piece of content exposed by a plugin. In most cases, this comes in the
form of a file, such as a JBoss AS JAR file or an installable package on a Linux platform. However, it is
possible that a plugin writer would choose to expose a chunk of data that did not directly tied to a file.

7.2.2. Package Type

A package type is defined in a plugin's descriptor. It is associated with a particular resource type.
Each package type is defined by the following attributes:

• Name - The programmatic name of the package type.

• Display Name (optional) - A user interface friendly name of the package type.

• Description (optional) - Describes the type of content found in package of this type.

• Category - One of four enumerated options:

• Executable Script - An executable text (potentially editable) file.

• Executable Binary - An executable binary (non-editable) file.

• Configuration - A file that is used to configure an aspect of the resource.

• Deployable - A piece of content that is deployed into the resource.

• Discovery Interval (optional) - Defines the time between package discovery scans for this type;
different packages types can be configured with intervals to represent the likelihood of the package
inventory changing.

• Creation Type Flag (optional) - If set to true, a package of this type is used when creating
resources of the enclosing resource type. An example of this situation is a Java EAR file. There is
an EAR resource type that represents the enterprise application in JBoss ON. Under that resource
type, there is a package type defined to represent the EAR file itself. This package type is flagged
as a creation type; when creating a new EAR resource, the EAR file must be created at the same
time. The default for this attribute is false, as typically packages will not represent the creation of a
new resource. See Chapter 2, Inventory for more information.

• Configuration (optional) - The configuration element allows the plugin to define an open-ended
set of attributes about the package type. These values will be populated during package discovery,

55
Chapter 7. Content (Packages)

and if not marked as read only can be specified by the user at artifact creation time. An example
of a property in this configuration element is a boolean that describes if an EAR file is deployed as
exploded or zipped. When EAR files are discovered, this flag will be populated and carry package
type specified information. Additionally, when deploying a new EAR file through JBoss ON, this flag
can be set to indicate how the package should be deployed on the AS instance.

7.2.3. Package Version

A Package defines a kind of package that can be installed (e.g. the "Emacs Editor" package or
the "Pet Store EAR application" package). A package version defines one particular version of a
package. For example, the package "Pet Store EAR Application" could have three associated package
versions - version "1.0.0", "1.2.0" and "2.0.1". A package version has Package Bits - that is, the actual
content of a package version. When a package version is downloaded from a remote Content Source
repository (see below), the downloaded bytes are stored and can be later retrieved for subsequent
installation by an agent on managed resources.

7.2.4. Package Bits

The actual content of a package version - the bytes themselves - are known as its package bits. A
package version's bits are stored in the server by either file uploading them, having an agent to auto-
discover them or having a Content Source download them from a remote repository.

7.2.5. Installed Package

Everywhere that a Package Version is installed in your environment is represented by an installed
package. An installed package is simply a package version that is installed on a particular resource.
One package version can have more than one installed package associated with it - for example, if
"Pet Store EAR Application version 1.0.0" is installed on three JBossAS server resources somewhere
in your environment, you will have three installed packages associated with the one Pet Store EAR
package version.

7.2.6. Content Source

A content source is a local or remote repository that can provide the "package bits" for content. More
specifically, a content source is a place where the actual bytes of a package can be downloaded.
Content sources can be remote Yum repositories (e.g. to provide RHEL rpm packages), an RSS feed
(e.g. the JBoss CSP to provide JBossAS patches) or even a mounted CD-ROM that locally provides
Linux installation RPMs. You can write your own server-side content source plugin if you wish to
support your own kind of content source in conjunction with your own agent plugin.

More information about defining a Content Source of the type "JBossASPatchSource" can be found in
Section 7.5, “Applying JBoss Patches”.

7.2.7. Channel
A channel is an aggregator of package versions. Users define channels and associate package
versions with their channels (note that you can associate package versions that came from different
content sources to the same channel). You can then subscribe resources to one or more channels.
This allows users to determine which package versions a resource can view and install.

56
 Package Discovery

7.3. Package Discovery

A package is inventoried into JBoss ON through a recurring package discovery scan. For each
inventoried resource against which packages are defined, the plugin will be queried for artifacts of
a particular type. The interval at which this discovery happens may be overridden in the package's
definition in a plugin's descriptor (additionally, the default value if none is specified can be found in the
plugin schema file).

Once inventoried in JBoss ON, the following data identifies each package:

• Name - When a plugin discovers a package, it assigns a descriptive name of what the package
represents in the system.

• Version - Identifies the specific version of the package.

• Type - The package is defined as being of a particular type. Multiple packages can have the same
name as long as they are of different package types.

• Architecture - Identifies the architecture of the package, if applicable. This is required, however
there is a noarch option when the package is not built against a specific architecture.

Additionally, the following data are recorded for each package. All of these are optional and provided if
applicable. It is up to the plugin to decide which of these to populate:

• Content Retrieval Time - Time stamp at which the revision was discovered.

• MD5 - MD5 checksum of the package file.

• SHA256 - SHA256 checksum of the package file.

• Length - Size of the package.

• Owner - Owner of the package (for the case of a file, the file system user who owns the file).

• Creation Date - Date the package was created.

• Last Modified Date - Date the package was last modified.

• Last Accessed Date - Date the package was last accessed.

7.4. User Functions

JBoss ON users with the appropriate content related permissions can perform create, update, and
delete operations.

7.5. Applying JBoss Patches

The Content system is used to apply patches to JBoss AS, JBoss EAP and JBoss SOA instances. By
default, your JON server comes pre-configured with the JBoss Patch Content Source and JBoss Patch
Channel.

As was explained above, a Content Source connects your JON server to all the JBoss patches. A
Channel maps a Content Source to the resources in your inventory that you want to apply the patches
to.

57
Chapter 7. Content (Packages)

7.5.1. Enabling the default JBoss Patch Content Source

1. Go to Administration and then View All Content Sources

2. Click the JBoss Patch Content Source

3. Before the Content Source can be used, you must provide your CSP (Customer Support Portal)
Username and Password, and activate the Content source. The following table details all the
settings for this Content Source, as well as which values you must modify.

Click the Edit button to modify this Content Source

Field Description Value

Name Name of the content source JBoss Patch Content Source
Description Description of the content All patches provided by the
source JBoss Subscription
Sync Schedule Synchronization schedule, 003**?
defined using the Quartz Cron
1
Synax ; "0 0 3 * * ?" means
"once a day at 3am"
Lazy Load check if all patches should be checked
downloaded only when they
are installed;

unchecked if all patches

should be downloaded
immediately
Download Mode Database
2
Feed URL The URL for the JBoss copy this link address
subscription software feed
Username The username for the Add your CSP user name
Customer Support Portal here
Password The password for the Add your CSP password
Customer Support Portal here
Activate Yes if this Content Source Yes, activate this feed
should be activated, No if it
should not
Proxy URL URL for the proxy server (if
any)
Proxy port Port for the proxy server (if
any)
Table 7.1. Content Source Settings

Important
We recommend that you keep the Lazy Load checkbox activated, otherwise all
patches defined in the RSS feed (a total of over 1GB of data) will be pre-emptively
downloaded by the JON Server.

58
 Subscribing Resources to the default JBoss Patch Channel

4. After editing the form, click Save.

5. Use the Test Connection button to verify that the connection details are valid.

6. Alternatively, you can use Synchronize button to force the content source to pull down the latest
RSS Feed and synchronize it with the local data. They history of synchronization attempts is listed
in the Synchronization Results section.

7.5.2. Subscribing Resources to the default JBoss Patch Channel

The channel is associated with a content source (the patches that can be applied) and resources are
then subscribed to this channel (where the patches can be applied to).

1. Click the "Go To All Channels View" at the bottom of the Content Sources list.

Alternately, go to Administration and then View All Channels.

2. Click the JBoss Patch Channel

By default, a channel has been created with the following values:

Field Description Value

Name Name of the channel "JBoss Patch Channel"
Description Description of the Channel "JBoss Subscription Channel"

3. By default, the channel has already been associated with the "JBoss Patch Content". However,
if you needed to associate the channel to another content source, you'd do so through the
ASSOCIATE button.

4. Click the SUBSCRIBE button to subscribe JBoss resources you'd like to patch.

• Change the Available Resources drop down to "Server"

• select all the JBossAS Server resources to subscribe to this channel.

• Once you've done this, you should see a screen similar to this, where the content source,
resources, and available packages are listed

59
Chapter 7. Content (Packages)

7.5.3. Applying a Patch

1. Browse to the Subscribed resource you'd like to patch (Use the Browse Resources link and then
go to the Servers tab).

2. Select the Packages tab.

3. Verify that this resource is subscribed to a channel by clicking the Subscriptions subtab.

4. Click the New subtab. If any patches are available for this resource, they will be listed on this tab.

Important
JBoss Cumulative Patches are, as the name infers, cumulative. So all the fixes found
in CP03, CP02 and CP01 are included in CP04.

For this reason, it is recommended that you simply install the latest CP available for
your resource.

Due to the nature of Cumulative Patches, you will only be allowed to install one CP at
a time

5. Mark the checkbox for the CP to be installed and click Deploy Selected.

6. Review the details of the CP through the VIEW link or click CONTINUE to install the patch.

60
 Applying a Patch

7. The Packages History subtab will be displayed. Once the patch has been installed, it will move
from "Currently Executing Requests" to the "Completed Requests", clicking the VIEW button will
load the audit trail for this package deployment request

61
62
Chapter 8.

Groups
A group contains one or more resources and can be used in different ways. This page discusses the
different kinds of groups JBoss ON supports and how to create groups.

8.1. Overview
You can group resources together within JBoss ON, making them easier to work with and to provide
security controls around the members of groups. There are different kinds of groups you can create, to
support different group models and functionality.

8.2. Concepts and Terminology

One important use of groups is within the JBoss ON security model. You can group resources and
assign that group to a role, effectively limiting access to the resources in the group to only those users
assigned that role. The role also limits what the users can do to the group member resources. Refer to
Chapter 9, Security Model for more information.

Another important application is to see the (combined) availability of all group members at a glance
(Section 8.5, “Groups and Availability”).

There are two types of groups that you can create:

• Mixed Group

• Compatible Group

These are explained below.

8.2.1. Mixed Group

A mixed group 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 used mainly for security purposes - if
you have a set of resources that you want to give limited access to for a set of users, please put those
resources in a mixed group. For example, if you have an application that is running on a platform that
consists of a JBoss Application Server and a Hibernate service, you can put the platform, JBossAS
server and the Hibernate service in a single mixed group. You can then create a role and assign the
mixed group and a set of application administrator users to the role. If those users do not have access
to any other roles in the JBoss ON system, those users will only view or be able to manage their
applications; they will not have access to any other resources within JBoss ON.

8.2.1.1. Recursive Membership

Mixed groups can be defined as "recursive" meaning if you explicitly add a resource to the group, all
child resources of that resource will implicitly be members of the group, too. If a group is not marked
as recursive, only resources that you explicitly add to it will be members of that group.

This is very useful in case you want to give an administrator full access to a JBoss Application Server.
You can create a mixed group, define it as a "recursive" group and add the JBoss Application Server
resource to it. At this point, the mixed group will now not only have the JBoss Application Server
resource as a member, but it will also have all of that server's child services as members too (which
would include all EJB, DataSource, JMX, etc. service resources).

63
Chapter 8. Groups

8.2.1.2. Consequences of implicit (recursive) group membership

When you add a root of a resource tree into a recursive group, then all child resources will be implicitly
added to the group. If you delete the root of a resource tree (that got added explicitly) all child
resources will be removed from the group as well.

Implicitly added resources cannot be manually deleted from a recursive group.

8.2.2. Compatible Group

A compatible group is similar to a mixed group, except it can only have resources that are of the same
resource type. Because a compatible group limits membership to only resources of identical types,
you can perform group operations on the members of the group. The JON GUI Console provides
a way in which you can select a compatible group and execute an operation on that group. The
operations you can choose from come from the list that are valid for the particular resource type
associated with the compatible group.

8.3. Defining Groups

Groups can be defined at various points within the system - whenever you see the "New group" icon:

Clicking on it will open a page where you can enter the name of a group and a description for it.

Important
Only users with the global SECURITY or INVENTORY permission can create groups.
Since users without those permissions can only access resources in groups assigned
to their roles, and since new groups are not assigned to any roles initially, then such a
user would not even be able to use a group he created (since it will not exist in any of that
user's roles). For this reason, groups can only be created by those users that were given
explicit permission to see any and all resources and groups (i.e. those with SECURITY or
INVENTORY permission).

In the lower panel, you can select if you want a mixed or compatible group. For mixed groups it will
enable the "recursive" checkbox to enable recursive groups. For compatible groups you will see a drop
down menu to select the resource type that this group can contain (Section 2.2.1, “Resource Types”).

Important
Once you have chosen the type of group, if it is recursive or what resource types it
contains, you cannot change its properties. You have to delete the group on the Browse
Resources page and create a new group with the desired type instead. Please refer to
Removing groups below for details.

The next section displays the inventory of a group:

64
 Group Inventory

8.3.1. Group Inventory

This page is divided into three parts: at the top you can view general information about the group: its
name, when it was created and last modified. Pressing the Edit... button lets you change the group
name, description and location fields.

The middle section lists the resource types contained in the group along with the number of resources
of the given type.

The individual resources are listed at the bottom. In the header you will see if it is a compatible or
mixed group along with the resource type for a compatible group (Jon Agent for the previous screen
shot).

There is also an Add to list... button that lets you select new members for the groups. Next to it is a
Remove from list button to remove explicitly added members from a list.

The next screen shot shows a resources of a mixed group.

Only the "JON Agent JVM" has a checkbox in front meaning that only this resource got explicitly
added. All other resources were implicitly added as children.

65
Chapter 8. Groups

8.3.2. Implicit vs. Explicit Revisited

As you have seen in the previous diagram implicitly added resources show no checkbox in front
of them. There is another consequence to this: when you add members to the group, you will be
presented again with members that are already on the group. When you select and add them again,
they will show the check box as well.

When you now remove the root of the implicit group, all members implicitly added will vanish, but
those explicitly added will stay in the group, even if the have also been added implicitly.

8.3.3. Defining Groups via Group Definitions

In JBoss ON 2 it is also possible to define groups in a more script like way by specifying properties
that define groups. You can learn more about this in Section 8.8, “Group Definitions and Dynamic
Groups”.

8.4. Removing_Groups
Groups can be removed by going to the Browse Resources page, selecting the type of group and
then the group you want to delete and pressing the delete button at the bottom of the page:

Removing the group does not remove any resource from inventory.

8.5. Groups and Availability

On the Browse Resources page you can see the groups at a glance with the number of members
and availabilities as illustrated in the screen shot below.

Group availability is computed as follows:

• RED: all members of the group are down

• YELLOW: some members of the group are up and some are down

• GREEN: all group members are up

• GREY: availability of the group members is unknown

66
 Groups and Connection Properties

8.6. Groups and Connection Properties

It is possible to set connection properties for members of a compatible group. You can learn more
about this in Section 8.7, “Group Connection Properties”.

8.7. Group Connection Properties

8.7.1. Step 1 Viewing Group Connection Properties

If you navigate to the Inventory tab of a compatible group, you will see a section labeled "Group
Connection Properties". Since a compatible group must only contain members of the same
ResourceType, it is possible to see an aggregate view or "average" of all of their individual connection
properties.

The screen shot below displays a compatible group of JMS Queue resources.

As mentioned above, this is an "average" of the individual connection properties on each of the
corresponding members of the group. The rules are as follows:

• If all of the resources in the group have identical values for some property, the group connection
property will be that exact value

• If even one resource has a different value than the rest of the resources in the group, then that
property will have a special marker value of "~ Mixed Values ~" (without quotes)

8.7.2. Step 2 Editing Group Connection Properties

Clicking the Edit... button takes you to a new page where you can choose to update one or more
connection properties across the entire group en masse. However, it is often the case that you only
want to update one or two properties at a time. The "override" column allows you to do this.

If override is checked, that property will be passed along to the resource for updating. If the override
box is left blank, then that property will remain untouched on all resources - regardless of whether the
value was already the same across all resources or had mixed values.

67
Chapter 8. Groups

In the screenshot above, you'll notice that the only row that has the override box checked is
Description Template. Therefore, this is the only property that will be affected when this change is
pushed out to the members of the group.

8.7.3. Step 3 Asynchronous Update Begins

While the update to the connection properties for a single resource is done synchronously at the
time the user clicks the "OK" button, group updates are not. Had they been, it would have created a
very unresponsive UI when updating the connection properties across groups containing dozens of
resources. It would have seemed as if the UI was "frozen" until the update on all group members was
complete. So, to remedy that problem, group connection property updates are pushed across your
enterprise asynchronously.

As shown above, on clicking 'OK' you will be redirected back to the Inventory tab of the resource group
and notified through a message at the top of the page that the asynch update is currently in progress.

Important
At this point, if you refresh the Inventory tab page, you may see the group connection
properties at the bottom of the Inventory tab change to values you may not be expecting.
Please ignore these values as they are expected.

When you press the refresh button, the JON Server goes out and finds the current
values of the connection properties for each resource in the group. If the asynchronous
update has not yet completed, but if it has successfully changed some of the resource's

68
 Step 4 View History of Updates

connection properties, you might see some "intermediate" values. Again please ignore
these values. Please wait until the asynch update completes, then refresh the page to see
the final results.

8.7.4. Step 4 View History of Updates

From the group Inventory tab, scroll down to the Group Connection Properties section again. Click the
"View History" button this time. It will take you to a page that will show you all of the changes you have
made to connection properties via this group.

In this case, you can see that three updates were made to this group recently, and that all updates
succeeded. In general, an update can be in one of three states:

• In Progress - there is at least one resource in this group that hasn't completed the update to its
connection properties yet

• Failed - the group update is complete, but at least one resources connection properties could not be
updated for some reason

• Success - the group update is complete, and the connection properties of all resources in the group
were successfully updated

8.7.5. Step 5 View Update Details

If you wish to see the details of what the update actually did, click on the hyperlink in the Date Created
column of the "plugin Configuration Update History section shown above. This will load a page
similar to the following:

69
Chapter 8. Groups

The upper section labelled Group Configuration Update Details will show you the details of what
you pushed out to all of the resources in the group. Remember, only the columns with the override box
checked are actually being pushed out to each resource in the group.

The lower section labelled Resource Configuration Updates Results will show whether and which
resource's connection properties failed to be updated. The failure reason will be listed in the Details
column. Clicking on the hyperlink in the Date Created column of this lower section will take you to
the Inventory tab for the corresponding resource. In almost every case, if there was some problem
connecting to the resource in question (because some value in the connection properties didn't make
sense), there will be an informational message at the top of the Inventory tab for the resource. You
can use the displayed information to fix localized issues first, then retry the group update later.

8.7.6. Step 6 View Group Update Results

Once the most recent group update completes, which again you can see by clicking on the "View
History" button, the Group Connection Properties section at the bottom of the Inventory tab will
reflect the new "average" (according to the rules listed in Section 8.7.1, “Step 1 Viewing Group
Connection Properties”).

8.8. Group Definitions and Dynamic Groups

This is a new set of features in JON 2.0 that attempts to further automate the management of
inventories, especially large ones.

8.8.1. Introduction
A group definition is a rich, expressive "short-hand" for resource groups. At a high-level, a definition
tells the system how to create a group; the details are handled by specifying a list of rules that tell the
system how to find and aggregate the appropriate resources to add as members of the group.

Think of all the ways you might want to group resources in an enterprise: by cluster identifier, by
broadcast group or some other network-level means, by logical service layer, by geographical location,
by security domain, e.t.c.

Any individual resource may fall into multiple "buckets", and thus could potentially be a member of
multiple groups. However this becomes a problem and more evident in large inventories. Do you really
want to spend hours and hours creating hundreds of groups for thousands of resources across dozens
of attributes?

70
 Subsystem Integrations

It might not seem so bad if you only had to do it once, but nowadays enterprises are changing every
day. Machines are stood up, reach an end of life, repurposed or upgraded (hardware or software).
With enterprises changing so rapidly, who really has the time to sit and make sure all of the hundreds
of resource groups have accurate memberships?

Whereas in JON 1.x you had to create and populate all of your compatible and mixed groups, now you
can leverage group definitions to do that tedious work for you. So what exactly can you do with this
rich, expressive short-hand?

8.8.2. Subsystem Integrations

This section describes all the different attributes of a resource that you can leverage to write your
definition. Please note that this section does not describe how to use group definitions (this is
discussed later in this chapter). This section can serve as a quick reference for the terms that are
supported when building up expressions.

Subsystem Major Type Supported Attributes

Inventory resource id, name, version, parent-
resource, grandparent-resource
resourceType plugin, name, category
(platform, server, service)
Configuration pluginConfiguration <any-plugin-configuration>
resourceConfiguration <any-resource-configuration>
Measurement traits <any-trait>

8.8.3. Syntax References

8.8.3.1. Quick Summary

A group definition is a collection of one or more valid expressions, and each expression must follow
one of the following two formats:

• <resource-expression> [ <string-match-expression> ] = <value>

• "groupby" <resource-expression>

The first format is called a simple expression; the latter, a pivoted expression. A group definition that
contains only simple expressions (the first format) will only create one child group. A group definition
that contains even one pivoted expression, has the potential to create many groups (see the other
"Syntax References" sections for more information).

8.8.3.2. EBNF Grammar

For those who like to refer to concise documentation
1
See – http://en.wikipedia.org/wiki/Extended_BackusNaur_form

Extended Backus Naur form was used in favor of its more classical predecessor primarily to take
advantage of the more concise and natural representation for repetition and grouping.
1
http://en.wikipedia.org/wiki/Extended_Backus-Naur_form

71
Chapter 8. Groups

<group-definition> = { <expression> } ;
<expression> = ( <simple-expression> | <pivoted-expression> ) ;
<simple-expression> = <simple-lhs-expression>, [ <string-match-
expression> ], "=", <value-expression> ;
<simple-lhs-expression> = <resource-expression> ;
<value-expression> = ? all visible characters ? ;
<pivoted-expression> = "groupby" <simple-lhs-expression> ;
<string-match-expression> = ".", ( "startsWith" | "endsWith" |
"contains" ) ;
<resource-expression> = "resource.", ( <parent-expression> | <grand-
parent-expression> | <resource-attributes-expression> ) ;
<parent-expression> = "parent.", <resource-attributes-expression> ;
<grand-parent-expression> = "grandParent.", <resource-attributes-
expression> ;
<resource-attributes-expression> = "id" | "name" | "version" |
<resource-type-expression> | <configuration-expression> | <measurement-
expression> ;
<resource-type-expression> = "type.", <resource-type-attributes-
expression> ;
<resource-type-attributes-expression> = "plugin" | "name" |
"category" ;
<configuration-expression> = ( "pluginConfiguration" |
"resourceConfiguration" ), <property-expression> ;
<measurement-expression> = "trait", <property-expression> ;
<property-expression> = "[", <property-name>, "]" ;
<property-name> = { <alpha-numeric-character> + "-" + "." } ;

8.8.3.3. The "Unrolled" Grammar

This section describes the <resource-expression> element in a much more explicit way. It contains
every single unique path expression that can be formed by "unrolling" the current grammar.

resource.id
resource.name
resource.version
resource.type.plugin
resource.type.name
resource.type.category
resource.parent.id
resource.parent.name
resource.parent.version
resource.parent.type.plugin
resource.parent.type.name
resource.parent.type.category
resource.grandParent.id
resource.grandParent.name
resource.grandParent.version
resource.grandParent.type.plugin
resource.grandParent.type.name
resource.grandParent.type.category

72
 A Not-So-Short Tutorial

resource.pluginConfiguration[<property-name>]
resource.resourceConfiguration[<property-name>]
resource.trait[<property-name>]

Remember, each of these expressions can either be:

• prefixed with "groupby" (if you want to form a pivoted expression), or

• suffixed with "= <value>" (if you want to form a simple expression)

Note
Simple expressions can match on a portion of the name using the optional <string-match-
expression> element above. (see the example entitled "Just the raw measurement tables"
below for sample usage)

8.8.3.4. Property Names

Unfortunately, JON does not yet have an easy way to look up what the valid property names are for
the pluginConfiguration, resourceConfiguration, or the traits. However, there is a way to navigate the
resource type hierarchy using a special JSP page available only to administrators.

1. Login as the administrator account ('rhqadmin', by default)

2. Start by going to the following URL – http://<JON_BASE_URL>/admin/browser.jsp

3. From there, navigate down to resource.ResourceType, and click it

4. Then select from some resource type in the list (such as "JBossAS Server"), and click it

5. In the "Simple Properties" table, click the pluginConfigurationDefinition link

6. On this page, the names of all of the valid elements are in the "propertyDefinitions" section of the
table

• For "JBossAS Server", you should see things like namingURL, principal, credentials,
jbossHomeDir, configurationPath, configurationSet, etc

You can follow this same procedure to find the names of the resourceConfiguration properties too, just
click the resourceConfigurationDefinition in step 5 instead of pluginConfigurationDefinition.

8.8.4. A Not-So-Short Tutorial

In each "unrolled" case above, the expression could have taken on one of two types - a pivoted
expression, or a simple expression. A simple expression requires that you specify exactly one value
that the expression must match. An example of this would be:

resource.parent.type.category = Platform

This means that you want to search your entire inventory and find any resources that have a parent
which happens to be a platform. In other words, you intend to create a single group, and put all of the
direct children resources of any platform in your inventory into it. You can also take a further step and
add another filter to the one above:

73
Chapter 8. Groups

resource.parent.type.category = Platform
resource.name.contains = JBossAS

This compound expression (each part of which must be on a separate line) will now search the entire
inventory as above, but this time it will only add resources to the group if they also have "JBossAS"
anywhere in their name.

Unfortunately for large inventories, this would almost certainly create a group with a very large
membership. So, from a practical standpoint, it starts to lose its luster. Luckily, we still have a few
tricks up our group definition sleeves...

Pivoted expressions are where the real power of group definitions shines through. Their features are
described below. As an example, if we had a pivoted expression like:

groupby resource.parent.name

The above expression would first take the portion after the "groupby" text, and ask the inventory
for ALL unique "resource.parent.name" results. In other words, it is going to find one result for each
uniquely named resource in the system, as long as that resource has one or more children resources.
For each unique result, it would create one group, and put any resource into it that matched that
criteria.

So let's say our inventory looked like:

• ResourceParentA

• ResourceChildA1

• ResourceChildA2

• ResourceGrandChildA2a

• ResourceGrandChildA2b

• ResourceChildA3

• ResourceParentB

• ResourceChildB1

• ResourceChildB2

• ResourceChildB3

• ResourceChildB4

The first part of the expression would find all the unique names of the parent resources, in this case:

• ResourceParentA (which has 3 direct children)

• ResourceChildA2 (which has 2 direct children, which are the grandchildren of its parent)

• ResourceParentB (which has 4 direct children)

Then, it will create one group for each of them, and populate them as necessary to satisfy the
expression. The group members would be as follows:

74
 Hints, Tips, and Tricks

With only a few characters we have now automated the creation of three groups (but this would be
more in larger inventories), and the memberships of those groups (which, again, in this case was
small, but would normally be on the order of dozens).

The above is only an introduction to pivoted expressions. JBoss ON also supports compound pivoted
expressions, which look very similar to the compound simple expression discussed at the beginning of
this tutorial. An example of a compound pivoted expression might be:

groupby resource.type.plugin
groupby resource.type.name
groupby resource.parent.name

The "groupby" text is required in the front of each expression that you want to make a pivot. This
compound expression creates a compatible group - since we know that the members of a compatible
group all have the same type, we've pivoted on both the plugin that defined the type as well as the
type name itself to ensure that we will automatically get one group for each unique type currently
known to the system.

And if that wasn't powerful enough we took the pivot concept one step further. Instead of having one
gigantic compatible group of, say, EJB3 Session Beans across your entire enterprise, we are also
pivoting on the parent. We will therefore get one group for each collection of Session Beans that share
the same parent.

As you can see, pivoted expressions give us the ability to create extremely fine-grained, automatically
managed, divisions of our resources. For a small inventory, this is handy tool; for a large inventory,
this is a priceless tool.

And if that weren't enough, we also support the mixing and matching of pivoted and non-pivoted
expressions in the same group definition. Let's use our last example, but filter the results even more
precisely as follows:

resource.type.category = server groupby

resource.type.plugin groupby
resource.type.name groupby
resource.parent.name

This compound, mixed expression would constrain the search a bit. Instead of creating one compatible
group for every single resource type known in the system, it would only create compatible groups for
every unique resource type that is also a server.

8.8.5. Hints, Tips, and Tricks

8.8.5.1. Expressions can be in any order (with restrictions).

For example, the following two expressions are processed in exactly the same way:

exprA1 exprA2 groupby exprB1 groupby exprB2

exprA2 exprA1 groupby exprB2 groupby exprB1

75
Chapter 8. Groups

But the following two are not:

exprA1 groupby exprB1

groupby exprB1 exprA1

Unfortunately, in JON 2.0.0 there was a restriction that all grouped expressions had to come at the
end of the list. If you try to put the grouped expression at the top of the list, or even in the middle, you
will see odd results. So, feel free to change the ordering as you see fit, within these restrictions. This
was fixed, and released in the 2.0.1 version of the product. Refer to http://jira.rhq-project.org/browse/
RHQ-471 for details on this issue.

8.8.5.2. Expressions can have empty lines

For the purposes of readability, you are allowed to insert blank lines into a group definition to help
visually separate or aggregate related expressions together. For example, the following is allowed:

exprA1 exprA2 exprB

8.8.5.3. Expressions will not create empty groups

If a definition is so restrictive that it creates groups which end up having no resource members that
match the filters, the group will not be created. This happens when you try to create extremely fine-
grained groups of resources that match a very specific set of properties. Instead of creating a few
empty groups, which could consequently make managing large numbers resource groups more
difficult, the system will suppress their creation. This is yet another convenience that was added to
make managing large inventories more intuitive.

8.8.6. Examples

8.8.6.1. JBoss Clusters

resource.type.plugin = JBossAS
resource.type.name = JBossAS Server groupby
resource.trait[partitionName]

8.8.6.2. Each OS type

resource.type.plugin = Platforms
resource.type.category = PLATFORM groupby
resource.type.name

76
 Examples

8.8.6.3. All auto-groups (like types under the same parent)

Note
Note: this could create very many groups in large inventories

groupby resource.type.plugin
groupby resource.type.name
groupby resource.parent.name

8.8.6.4. Just the raw measurement tables

resource.type.plugin= Postgres
resource.type.name = Table
resource.parent.name = rhq Database
resource.name.contains = rhq_meas_data_num_

8.8.6.5. Just agents configured with multi-cast server detection

resource.type.plugin= RHQAgent
resource.type.name = RHQ Agent
resource.resourceConfiguration[rhq.communications.multicast-
detector.enabled] = true

8.8.6.6. Just Windows boxes with event tracking turned on

resource.type.plugin= Platforms
resource.type.name = Windows
resource.pluginConfiguration[eventTrackingEnabled] = true

8.8.6.7. All JBossAS servers grouped by the machines they are running
on

groupby resource.parent.trait[Trait.hostname]
resource.type.plugin = JBossAS
resource.type.name = JBossAS Server

77
78
Chapter 9.

Security Model
JON 2.0 simplified the security model, as compared to JON 1.x. In the process, many bugs and design
flaws in the previous release were fixed. Rather than have a confusing (and often times useless) array
of permissions, JON 2.0 now supports the following set of permissions:

• GLOBAL

• Security

• Inventory

• Settings

• RESOURCE

• Modify

• Delete

• Create Child

• Alerts

• Measurements

• Content

• Control

• Configure

Permissions are set on a role. In addition to having permissions, a role also has:

1. One or more groups associated with it

2. One or more users associated with it

A role, therefore, authorizes its associated users with a fixed set of permissions to operate on its
associated groups of resources.

You will notice the permissions are separated into two types - global and resource.

Global permissions apply across the entire JON system. Resource permissions give authorization to
do things, but only to resources found in groups assigned to the role.

Here's a definition of what these permissions authorize:

• Global Permissions

• Security

• Allows the user to modify security settings (e.g. create, modify delete and assign roles) and it
allows the user to create, modify and delete other users. This is considered the "superuser" role
because once a user is given the security global permission, that user essentially has or can
have access to the entire system (because, even if the user doesn't currently have any other
permission or role assigned to him, he is free to add himself to any role and assign himself any

79
Chapter 9. Security Model

other permission). Because of this, you must be very restrictive on who is authorized with this
global security permission. Typically, if you give a user this global security permission, you also
give that user all other global permissions.

• Inventory

• Allows the user to perform any task on any resource. Having a role with this permission grants
the user to add, delete, configure, control and modify any resource, regardless of what other
roles and associated groups of resources the user has been given access to. This is also the
permission required in order to be able to import new resources into inventory.

• Settings

• Allows the user to view or modify the JON Server's administration settings.

• Resource Permissions

• Modify

• Allows the user to change information about the resource (its name, for example). This does
not include being able to modify the configuration of the managed resource itself, this is only
to modify the JON resource as it is represented in the JON inventory. (see the Configure
permission below)

• Delete

• Allows the user to delete a resource from inventory.

• Create Child

• Allows the user to create child resources under another resource.

• Alerts

• Allows the user to create and modify alerts for a resource.

• Measurements

• Allows the user to modify the way measurements are collected for a resource.

• Content

• Allows the user to manipulate content related to a resource.

• Control

• Allows the user to execute operations (aka control actions) on a resource.

• Configure

• Allows the user to view and modify the configuration of the actual managed resource. This
is different from Modify permission in that this permission actually allows you to change the
settings within the actual remote resource being managed (for example, "Modify" permission
would allow me to change the name of my JBossAS Data Source service resource as it
appears in the JON GUI Console; the "Configure" permission allows me to change the actual
JNDI name of my Data Source as it is deployed in the JBoss Application Server).

80
By default, there is a rhqadmin user that is a member of a system superuser role that provides full
access to everything. This role cannot be modified.

There is also an all resources role which provides full access to all resources in inventory. However, it
cannot modify users, roles or JON settings.

These predefined roles are built-in to include all resources, without the need for adding groups.

When creating your own roles, you will need to create your own groups to associate to your roles. It is
important to assign a group to a role in order to see resources. If you create a user and role, but do not
assign a group of resources, you will not be able to see any resources, and in two cases, you will see
an error appear in the Dashboard UI. The first is displayed in the lower left below the Summary Counts
portlet. The second is displayed where the Auto-Discovery portlet should be.

81
82
Chapter 10.

Administration
The Administration section allows you to modify the JON Server configuration. You can access it only
if you are assigned to a role that has the Administer JON Server settings and/or the Manage security
(users/roles) option enabled.

Authentication/Authorization
• Users

• The List Users page allows you to view all users.

• The New User page allows you to create a new user.

• Roles

• The List Roles page allows you to view all roles.

• The New Role page allows you to create a new role.

JON Server Settings

• The Server Configuration page allows you to modify many of the current configuration settings for
the JON server.

• The two Monitoring Defaults pages allow you to modify which metrics are monitored by default, you
can modify the available metrics for either the resource types being utilized by your system, or all
resource types.

• The Manage JON license page allows you to view and update your current JON license.

• The Manage Plugins page allows you to view which plugins are currently deployed on your JON
system

Content Sources and Channels

• The View All Content Sources page allows you to create and edit content sources in order to deploy
packages such as JBoss AS patches

• The View All Channels page allows you to create and edit channels that map content sources to
resources in your inventory.

High Availability Administration Console (HAAC)

• The List Servers page allows you to view and manage your installed servers, access server details,
and inspect agent and affinity group assignments.

• The List Agents page allows you to view your registered agent definitions, access agent details and
inspect server and affinity group assignments.

• The List Affinity Groups page allows you to view and manage your affinity groups, access affinity
group details, and inspect assignments.

83
Chapter 10. Administration

• The List Partition Events page allows you to view the audit of events affecting agent-server
assignment (partitioning of agents to servers).

10.1. Content Sources and Channels

10.1.1. View All Content Sources

A content source is part of the Content subsystem (Chapter 7, Content (Packages)) and is used as a
repository to deploy new packages on to a resource.

From this page, you can view all of your content sources, create new ones, and edit existing ones.

Currently, the only supported Content Source type is "JBossASPatchSource", this source allows you
to apply Cumulative patches to JBossAS Server resources. More information about applying patches
to a JBoss Application Server resource can be found in the Section 7.5, “Applying JBoss Patches”.

Field Description
Name Name of the content source
Description Description of the content source
Sync Schedule Synchronization schedule, defined using the
1
Quartz Cron Synax
Lazy Load yes if all packages should be downloaded only
when they are installed;

no if all patches should be downloaded

immediately
Download Mode method to store the packages downloaded from
the repository. DATABASE, FILESYSTEM or
NEVER

Note, if the Download Mode is NEVER, the

lazyload setting is ignored
Feed URL The URL for the JBoss subscription software
feed
Username The username for the Customer Support Portal
Password The password for the Customer Support Portal
Proxy URL URL for the proxy server (if any)

The Test Connection button will test the connection settings for this content source. The result of the
test will be displayed at the top of the page, such as:

• "Failed the attempt to connect to the remote repository for [foobar] Check the configuration and
make sure the remote repository is up."

• "The test passed - the remote repository for [foobar] is available."

The Synchronize button will synchronize the meta data from the content source with the local
repository. The result of this action will be listed in the Synchronization Results table on this page.

84
 View All Channels

10.1.2. View All Channels

A channel maps a many to many relationship between content sources and resources.

After creating a channel via the Create New button, select the channel by clicking on its name.

• Use the ASSOCIATE button to associate a Content Source with this channel. Alternately, you can
associate the content source to this channel from the edit content source page.

• Use the SUBSCRIBE button to subscribe a Resource to this channel. Alternately, you can subscribe
a resource to this channel by browsing to that resource's package tab and select the subscription
sub-tab.

10.2. High Availability

The following pages make up what is commonly referred to as the High Availability Administration
Console (HAAC). However, these pages, particularly Section 10.2.1, “List Servers”List Servers are still
relevant in a 1-Server configuration. For more information about HA environments, see:

• High Availability Design located at http://support.rhq-project.org/display/RHQ/High+Availability+-

+Agent+Failover

• The High Availability Configurations chapter in the Installation Guide

10.2.1. List Servers

This list will display an entry for each Server installed against the current Database. There will always
be at least one Server entry, and potentially several in an HA Server Cloud. See High Availability
Design (http://support.rhq-project.org/display/RHQ/High+Availability+-+Agent+Failover) for details of
values or fields displayed, beyond what is described here.

Actions

Set NORMAL

Select Servers in MAINTENANCE mode and click this Button to return them to NORMAL mode. Once
in normal operation mode Agents can once again initiate connections. Agents for whom this is their
primary Server will begin to migrate back incrementally.

Set MAINTENANCE

Select Servers in NORMAL or DOWN Mode and click this Button to set them to MAINTENANCE
Mode. Agents will no longer be able to communicate with the Servers and will attempt to fail over to an
available Server.

Remove

Select Servers in MAINTENANCE or DOWN Mode and click this Button to remove them from the HA
Server Cloud. Changing the size of the Server Cloud forces a repartition of agent-server assignments,
generating new server lists for each Agent. To return a removed Server to the cloud it will need to be
reinstalled.

View/Edit Server Detail

85
Chapter 10. Administration

Click on the Server Name to go to the Server Detail Page. This page displays the Server definition and
lists the connected Agents, which link to the Agent definitions.

Edit

Click this button to edit the Server definition. Here you can update the Server's endpoint information if
it changes after installation.

10.2.2. List Agents

This list will display an entry for each Agent registered against the current Database. See High
2
Availability Design for details of values or fields displayed, beyond what is described here.

Field Description
Name Unique Agent Name.
Connected Server The Server currently connected to by this Agent.
Down Agents may display the Server last
connected to.
Agent Bind Address The address used by the Server to communicate
with the Agent. Should be reachable by all
Servers.
Agent Bind Port Together with the Bind Address used by Servers
to communicate with the Agent.
Last Availability Report The time the last resource availability report was
received by the Server. This is a good indicator
of an active Agent.
Affinity Group The Affinity Group this Server is assigned to, if
any.

View/Edit Agent Detail

Click on the Agent Name to go to the Agent Detail Page. This page displays the Agent definition and
lists the Agent's Server List.

Server List (a.k.a. Failover List)

The Server List is ordered with the primary Server listed at the top. The currently connected Server
is listed in the Agent properties. In general the connected Server should be the primary Server, but in
failover situations another Server in the list may be servicing the Agent.

10.2.3. List Affinity Groups

This list will display an entry for each Affinity Group defined against the current Database. See High
3
Availability Design for details of values or fields displayed, beyond what is described here.

Field Description
Name Unique Affinity Group name.

2
http://support.rhq-project.org/display/RHQ/High+Availability+-+Agent+Failover
3
http://support.rhq-project.org/display/RHQ/High+Availability+-+Agent+Failover

86
 List Partition Events

Field Description
Agent Count The number of Agents assigned to this Affinity
Group. This count does not reflect active
connections in any way, only a count of
assignments.
Server Count The number of Servers assigned to this
Affinity Group. This count does not reflect
active connections in any way, only a count of
assignments.

Actions

Create New

This defines a new Affinity Group with the given name. It does not initially have any Agent or Server
membership but will bring up the Affinity Group Detail page, which provides the assignment capability.

Remove Selected

This removes the selected Affinity Groups. Server an Agent Assignments will be lost. Affinity Group
removal forces a repartition of Agent-Server assignments, generating new server lists for each Agent.

View/Edit Affinity Group Detail

Click on the Affinity Group Name to go to the Agent Detail Page. This page displays the Agent and
Server assignments for the Affinity Group. It also allows editing of the Affinity Group name.

Assigning Affinity Groups to Servers and Agents

Only Agents and Servers not currently assigned to an Affinity Group are eligible for assignment. So,
moving an Agent or Server from one group to another is a two step process of unassignment followed
by assignment.

To Add or Remove Agents or Servers to or from an Affinity Group, respectively, use the Affinity
Group's Detail page. The page is navigable from Section 10.2.3, “List Affinity Groups”, Section 10.2.1,
“List Servers”, and Section 10.2.2, “List Agents”. Once there you have two options:

Edit Group Agents

The Detail Page displays a list of currently assigned Agents. Click on the Edit Group Agents button to
add or remove Agents to or from the group respectively.

Edit Group Servers

The Detail Page displays a list of currently assigned Servers. Click on the Edit Group Servers button to
add or remove Agents to or from the group respectively.

Return to Section 10.2.3, “List Affinity Groups” to see the assignment breakdown.

10.2.4. List Partition Events

This list will displays the audit history of all events related to agent-server assignment, commonly
known as partition events as they relate to the partitioning Agents across Servers. Following the

87
Chapter 10. Administration

timeline it is possible to inspect the changes in the agent-server topology. See High Availability
4
Design for details of values or fields displayed, beyond what is described here.

Field Description
Execution Time The time of the partition event.
Type The partition event type. This indicates what
happened in the system affecting Agent partition.
This can be filtered to focus on specific types of
partition events.
Details Detailed information regarding the partition
event. Varies based on the partition event
type. This can be filtered to focus on specific
information, like an Agent or Server name.
Initiated By The user initiating the action generating
the partition event. "admin" if system
initiated.Together with the Bind Address used by
Servers to communicate with the Agent.
Execution Status See Below for status descriptions. This can be
filtered to focus on specific execution status, like
Completed.

Execution Status Description

Audit This partition event is only for auditing and did
not affect Agent Server List generation in any
way.
Immediate This partition event may have generated at least
one Agent Server List and it was done at the time
of the event. Click on the associated type to see
the Primary Server assignments made, if any.
Requested This partition event requested a deferred
partitioning processing, typically full repartition.
It will be processed on the next execution of
the Cloud Manager Job, typically in less than a
minute.
Completed This partition event's requested partitioning has
been completed. Click on the associated type
to see the Primary Server assignments made, if
any.

Clean up the audit history by removing the selected partition events.

Purge All

Remove all partition events. Useful for overall maintenance.

Force Repartition
4
http://support.rhq-project.org/display/RHQ/High+Availability+-+Agent+Failover

88
 Manage JON license

If for whatever reason the administrator wants to regenerate the Server lists for all Agents outside
of performing a HAAC action that would otherwise do so, then clicking this button will request a full
repartition.

10.3. Manage JON license

10.3.1. View Current License

You can view the current license used with your JBossON server by going to the "Chapter 10,
Administration | Manage JON License" page.

The following information is displayed:

User the user who owns this license.

Email the email address of this user.
Phone the phone number of this user.
License Expiration the date the license expires.
Platform Limit the maximum number of platforms this JON
server will inventory.
Monitoring Features "enabled" if the monitoring features can be used,
"disabled" if the monitoring features can not be
used.

10.3.2. Update License

From the View current license page, clicking the "Update License" link will allow you to apply a
5
new license to the JON console. Simply download a license from the Customer Support Portal as
explained on the license installation chapter in the Installation Guide, and upload it through the "update
license" dialog.

10.4. Manage Plugins

The manage plugins page lists all the plugins currently deployed on you JON system.

10.5. Monitoring Defaults

To access the Monitoring Defaults page, go to the Administration page through the link in the upper
right of the UI. You can access the defaults for all possible types, or only the types currently in use.

The JON Monitoring Defaults Configuration page allows you to specify the default settings for metrics
that are enabled by default and for alerts that are defined for resources of a given type. This can be
very useful for users with very large environments in order to keep the metrics being collected and the
alerts being fired consistent throughout their network.

The settings include whether or not a metric should be enabled by default and what its default
collection interval is. The configuration is applied to the resource type, and only affects new resources
that get imported or configured. To modify the settings, click on the EDIT METRIC TEMPLATE button
next to the resource type name.
5
http://support.redhat.com/jbossnetwork

89
Chapter 10. Administration

10.5.1. Metric Templates

Go To Administration | Monitoring Defaults, then click the Edit Metric Template button for the
resource type you want to modify. This will load a page displaying all the metrics available for that
resource type along with details on if those metrics are collected by default and at what interval.

To enable metrics for collection by default and/or modify the collection interval:

Name name of the measurement

Description description of the measurement
Category the type of measurement this is (i.e Performance,
Trait, e.t.c.)
Collection Enabled whether or not the metric is enabled by default
Collection Interval what the collection interval is, if the metric is to
be collected by default

1. select the metrics you want by checking the checkbox(es) next to the metric name(s).

2. enter the value you want in the Collection Interval for Selected field, selecting a time unit from the
drop-down list next to the field.

3. click the right arrow button to enable the metrics with the specified collection interval you specified.

To disable metrics for collection by default

1. select the metrics you want to disable by checking the checkbox(es) next to the metric name(s)

2. click the DISABLE COLLECTION button to prevent the metric(s) from being enabled when a new
resource of the specified type is imported, created, or configured.

Important
By default, the template will only be applied to NEW resources that are added to
the inventory after this template is defined. Use the Update schedules for existing
resources of marked type checkbox if this template should be applied to ALL
resources that are currently in inventory as well as resources added in the future.

See Chapter 4, Monitoring for more information about metric collection.

10.5.2. Alert Templates

Similar to how Metric Templates can be used to make metric collection consistent across resource
types in your environment, Alert Templates can be used to make alert definitions consistent.

Defining an Alert Template

Go To Administration | Monitoring Defaults, then click the Edit Alert Template button for the
resource type for which you want to create an alert.

The Alert Templates itself is defined just as individual alerts are defined.

90
 Alert Templates

See Chapter 5, Alerts for more information on alert definitions.

Editing an Alert

Once an alert template has been defined, it can be modified on an individual-resource-level by

browsing to a particular resource and editing the alert definition there.

If you browse your page to a resource that has an alert template defined, you will notice (as shown
below) that alerts defined via a template are listed alongside individually defined alerts, but they are
denoted with a "Vew Template" link.

You can modify the individual instance of an alert template by editing it here, however, if the original
alert template is later modified, the changes to the individual alert definition will be overridden by the
alert template changes.

91
Chapter 10. Administration

10.6. Roles

10.6.1. New Role

Properties

• Name : a simple name used to identify this role. (required)

• Description : a description of this role.

Global Permissions

Global permissions apply to the entire JON console, not to a particular resource.

• Manage security (users/roles) : allows a user to create, update and delete users and roles

• Manage inventory (resources/groups) : allows a user to import resources into the inventory and
to delete resource from the inventory. Users with this permission can also create, update and delete
groups.

• Administer JON Server settings : allows a user to modify the JON Server console settings.

Resource Permissions

Resource permissions apply to all resources that are in the Groups (Chapter 8, Groups) associated
with this role.

• Modify : allows a user to modify a resource's properties.

• Delete : allows a user to delete a resource from inventory.

• Create Children : allows a user to create child resources for the given resource.

• Alert : allows a user to define and modify alerts for a resource.

• Measure : allows a user to modify the measurements that are collected for a resource.

• Update Software : allows a user to install software updates for a resource.

• Control : allows a user to perform control actions on a resource.

• Configure : allows a user to modify a resource's configuration.

• Artifacts : allows a user to modify a resource's artifacts.

92
 List Roles

Add Users to Role

All the available users are listed on the left, all the users assigned to the role are listed on the right.

To assign a user to a role, simply select the user on the left with a checkbox. Use the arrow in the
center of the page to move it to the right. Then click OK

Add Groups to Role

Similar to the "Add Users to Role" screen, all the available groups are listed on the left. All the groups
assigned to the role are listed on the right.

To assign a group to a role, simply select the group on the left with a checkbox. Use the arrow in the
middle of the page to move it to the right. Then click OK

10.6.2. List Roles

You can view this page by clicking on the "Administration | List Roles" option. No specific permission is
needed to view this page.

The List roles page displays all the roles that have been configured for this JON instance. Clicking on
the role name loads the View Role page.

10.6.3. View Role

You can view this page through the "Administration | List Users" option and selecting clicking the
particular username you want to view. No specific permission is needed to view this page.

From this page you can view the permissions information for each role, as defined on the New Role
screen.

You can also view the user(s) and group(s) associated with this role. If you have the Manage security
(user/roles) permission, you will be able to modify the role's users and groups by clicking on the Add to
List and Remove from List buttons.

10.7. Server Configuration

10.7.1. JON Base URL Configuration Properties

GUI Console URL

The URL that is used to access the JON GUI Console. This is also the URL used in the alert emails
that are sent to users (the URLs in alert emails will allow users to click the link directly from their email
client and get to the information on the alert). The GUI Console URL does not need to be changed
unless your JBoss ON installation connects through a proxy server.

10.7.2. Data Manager Configuration Properties

JBoss ON stores monitoring data using a tiered model to reduce the amount of data that is stored and
still provide the necessary granularity to provide useful historical metric data.

The following outlines the main steps JBoss ON uses to archive its metric data:

• Raw metrics get aggregated over a one-hour window producing minimum, average and maximum
values.

93
Chapter 10. Administration

• Those one hour values get aggregated across a six hour window.

• Finally six hour values get aggregated across a 24 hour window.

Old data gets deleted according to the following schedule:

• Raw metric data which has been aggregated and is older than 7 days

• One hour data which has been aggregated and is older than 14 days

• Six hour data which has been aggregated and is older than 31 days

• 24 hour data which is older than 365 days

The following settings can be defined in this section:

Name Description Default

Run Database Maintenance (applicable when using a 1 hour
Every Postgres DB)
Delete Response Time Data specifies the amount of time 31 days
Older Than used when purging response
times (Section 4.1.2, “Metrics
versus Traits versus Response
Time”) in days
Delete Alerts Older Than specifies the amount of 31 days
time used when purging
Alerts(Chapter 5, Alerts), in
days
Delete Events Older Than specifies the amount of time 31 days
used when purging Events
(Chapter 11, Events), in days
Reindex Metric Data Tables yes or no yes
Nightly

10.7.3. Automatic Baseline Configuration Properties

JBoss ON's baselining feature allows for configuration of three main properties that contribute to the
automatic calculation of metric baselines.

Baseline Frequency allows configuration of how often baselines are

automatically calculated in days (default is 3
days).
Baseline Dataset allows configuration of the time interval used to
calculate the baseline in days (default is 7 days).

10.7.4. LDAP Configuration Properties

By default JBoss Operations Network uses its own database for storing information about users.
JBoss ON also allows an external LDAP directory to be used, in addition to its own database, for
authenticating users.

To enable LDAP-based authentication, check the Use LDAP Authentication checkbox.

94
 LDAP Configuration Properties

If LDAP authentication is enabled, it must be configured using the remaining settings, which are
described below.

URL the URL the JON Server will use to connect

to the LDAP directory (e.g. "ldap://
localhost/"); if no port is specified in the
URL, 389 is used, or 636 if is SSL is enabled
(required)
SSL enable this boolean property if the LDAP
directory requires SSL connections (required)
Username the LDAP distinguished name (DN) of the
username to connect to the LDAP server
and perform the JON user search (e.g.
"cn=Manager, dc=jboss, dc=com");
this user must have permission to search the
subtree of the directory rooted at the Search
Base(required)
Password the password to be used in conjunction with the
above username (required)
Search Base the DN of the LDAP entry which is the root of the
subtree to be searched (e.g. e.g., "o=JBoss,
c=US" or "ou=People, dc=jboss, dc=com");
this value is also commonly known as the suffix;
if you are unsure of this setting, consult your
LDAP administrator (required)
Search Filter an LDAP filter, in the syntax defined by RFC
6
2254 , to apply when doing the LDAP user
search; this is useful if the population to
authenticate can be identified via the values of
one or more LDAP attributes. For example:

(JONUser=TRUE)

or

(|(memberOf=CN=JBoss
Administrators,OU=Server Service
Accounts,OU=Servers,OU=Information
Systems,
DC=xyz,DC=com)
(memberOf=CN=Development
Department,OU=Development,OU=Information
Systems,DC=xyz,DC=com))

Login Property the LDAP attribute that contains the value that
should be used by JON as the user name (e.g.
"cn" or "uid"); if multiple matches are found, the
first entry found is used (required)

95
Chapter 10. Administration

Your settings can be verified by logging out of JBoss ON using the Logout link at the top of the page.
Log in using a user from the configured LDAP directory (i.e. the username should equal the value of
the Login Property attribute in a directory entry within the subtree rooted at the Search Base entry).
Upon successful authentication, JBoss ON will ask for additional information about that user (full
name, email address, etc.); this information will be persisted to the JBoss ON database.

Important
As with all new users in JBoss ON, LDAP users are not assigned to any roles by default
and therefore they will not be able to see any resources in the ON GUI until they have
been added to one or more roles. A JBoss ON administrator will need to add a new LDAP
user to one or more JON roles after the user has logged in for the first time.

10.7.5. SNMP Server Configuration Properties

To enable the option to emit SNMP traps as an alert notification mechanism, specify the SNMP
protocol version that is implemented by the server that will be the destination for traps emitted by
JBoss ON. JBoss ON supports SNMP versions 1, 2c, and 3.

If SNMP is enabled, it must be configured using the remaining settings. The settings vary depending
on which version of SNMP has been selected.

10.8. Users

10.8.1. New User

View this page by going to "Administration | New User...". In order to access this page, you must have
the "Manage security (users/roles)" permission.

General Properties

Define all the required fields to define a user. Once completed click the OK and Assign User to
Roles button.

• Name: the first and last name of this user. (required)

• Email: the email address of this user, used to send email alert notifications. (required)

• Password: a 6-letter case-sensitive password for this user, used to login to the console. (required)

• Username: the username for this user, used to login to the console. (required)

• Phone: a phone number for this user, informational only - this data is not used by JON.

• Department: the department for this user, informational only - this data is not used by JON.

• Enable Login: there are two options to this yes (if the user should be able to login to the console)
and no (if not authorised).

Add Roles to User

All the available roles are listed on the left while all the roles assigned to the user are listed on the
right.

96
 List Users

To assign a role to a user, simply select the role on the left with a checkbox. Use the arrow in the
centre of the page to move it to the right. Then click OK

10.8.2. List Users

View this page by going to "Administration | List Users". No specific permission is needed to view this
page.

The List users page displays all the users that have been configured for this JON instance. Clicking on
the username loads the View User page.

10.8.3. View User

View this page by going to "Administration | List Users", and clicking the username for a particular
user. No specific permission is needed to view this page.

From this page you can view the basic information for each user, as defined on the New User screen.

You can also view the role(s) assigned to this user. If you have the Manage security (user/roles)
permission, you will be able to modify the user's roles via the Add to List and Remove from List
buttons.

97
98
Chapter 11.

Events
Events are a sort of measurement data, that unlike Metrics (see Chapter 4, Monitoring) are not
collected at fixed intervals, but that occur at random points in time. JBossON is able to pick up those
events, filter them by severity, display them in the user interface and have Chapter 5, Alerts sent
based on some event conditions.

Events are currently supported by the following resource types:

• Windows Platform (Windows events)

• Apache Server (log files)

• JBossAS Server (log files)

11.1. Concepts
An EventSource is attached to a particular resource and defines the origin of incoming events. Typical
EventSource support is for logfiles but it is anticipated that sources such as incoming SNMP traps or
JMX notifications will be utilized as future EventSources.

As an EventSource is attached to a resource it is defined via that resource's Inventory page, under
Connection Properties - Events. The generated events are viewed via that resource's Monitor -
Events page.

An Event is triggered each time the conditions of an EventSource are met and reports the values
matching the criteria. For example, when a log entry matches defined severity and regex constraints
for an EventSource defined for a particular logfile.

Each Event has a Severity associated with it. Severities can be in the range of Debug, Info, Warn,
Error, Fatal and are oriented along the severities of the log4j framework.

11.2. Defining Event sources

To define an EventSource, you need to go the the inventory tab of the resource that you want to define
the events on. Click on Edit... below the connection properties and then scroll down to the Events
section. The event's properties may differ depending on the resource type. The example below is for
the JBossAS Server type.

Important
Resources, when auto-detected, may predefine an EventSource for a standard log file
found in a default location. For example, for a JBossAS Server resource an EventSource
will be predefined for the server.log. Although defined it will be disabled initially and must
be explicitly enabled. Note that the RHQ JBossAS Server resource will not predefine this
EventSource because the log file is not in the standard JBossAS location.

To enable a predefined EventSource select it from the Log Event Sources list. Or, to add a new log
EventSource:

99
Chapter 11. Events

On clicking the Add new button, a new page will be displayed, where you can specify the properties of
the log file EventSource:

• Log File Path: An absolute path to the logfile. The logfile does not need to exist at any given time,
but the path must be well formed.

• Enabled: When enabled event generation is active for the logfile and will affect log entries generated
from the activation time forward. When disabled no events will be reported.

• Date Format: Specify an uncommon date format here. For typical log4j based logfiles this is left
unset.

• Includes Pattern: A Pattern used to limit log entries that trigger events. When a pattern is specified
only log entries with a substring matching the pattern will trigger an event. The pattern can span
multiple lines in a logfile, for example, in the case of a stack trace. If left unset only Minimum
Severity will constrain event generation. For more information, please refer to the Section 11.2.1,
“Notes and Examples”.

100
 Notes and Examples

• Minimum Severity: Specifies the minimum log entry severity necessary to trigger an event. This
allows for severity-based events. It is recommended to set this as high as possible to avoid
excessive event generation.

Click on OK to complete the operation.

You can then choose to define another EventSource, edit or delete existing ones or to finish
configuring the EventSources by clicking OK again.

11.2.1. Notes and Examples

The includes pattern is specified as a Java regular expression, and will be interpreted as-is. We do
not assume you wanted any special processing such as case-insensitive matching or even multi-line
matching. Below are a few of the most common flags that you'll want to add to your pattern to get
these alternate effects:

Name Flag Description

DOTALL (?s) Process the NEWLINE character
as if it were a regular character,
i.e. multi-line match
CASE INSENSITIVE (?i) Ignore the casing of the
characters, matching on the
character value only
Table 11.1. Flags

Below are a few examples to help you get familiar with these options:

As an example, your log file entry may be similar to:

Log Entry Includes Pattern Match? Why

"this is a single-line "this.*pattern" Yes data starts with "this" &
pattern" ends with "pattern"
"This is a single-line "this.*pattern" No "This" is capitalized
pattern"
"This is a single-line "(?i)this.*pattern" Yes "This" is capitalized,
pattern" but case-insensitive
match
"This is a \n multi-line "(?i)this.*pattern" No Input is multi-line,
pattern" default is single-line
matching
"This is a \n multi-line "(?s)this.*pattern" No Input & match are
pattern" multi-line, but "This" is
capitalized

101
Chapter 11. Events

Log Entry Includes Pattern Match? Why

"This is a \n multi-line "(?s)(?i)this.*pattern" Yes performing case-
pattern" insensitive, multi-line
match
"This is a \n multi-line "(?si)this.*pattern" Yes same as above, but
pattern" used a simpler syntax
"This is a \n multi-line "(?is)this.*pattern" Yes same as above, order
pattern" of flags do not matter
Table 11.2. Log file entry
1
For a full list of embedded flags expressions, please see the javadocs for regular expressions

11.3. Viewing Events

To view Events, you need to open the Monitor tab of a resource. Events are displayed in three
sections in various levels of detail and context

• at the bottom of the Visibility tab (the default tab when you enter the monitoring pages)

• the Events tab, that shows events in great detail

• the Timeline tab, that shows Events in conjucntion with other things that happened on that particular
resource.

These will be discussed below.

11.3.1. Visibility tab

Scroll down to the bottom of the indicator charts. This shows a strip with colored squares that
represent Events in the relevant time range (refer to the Section 4.2.1.2, “Indicators” within the
monitoring tab for a discussion about how much time a square/dot represents).

The color of a square indicates the most severe event that got recorded in that time. So if you have an
Event at debug level and one at warn level, the square will show yellow for the warning.

Severities and matching colors are:

• Debug: blue

• Info: green

• Warn: yellow

• Error: light red

• Fatal: dark red

1
http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html

102
 Events tab

Clicking on a colored square will show a box with details of corresponding events:

In this case it is only one event. You can dismiss this box by clicking its close button in the top right
corner. You can investigate further by clicking the event id at the start of the event line, bringing you to
the Events tab.

11.3.2. Events tab

Click on the Monitor tab's Events tab to go to the Events view:

This will show you a screen with two sections:

• Top: Event List view with filtering controls.

• Bottom: Event detail view for full display of a selected event.

11.3.2.1. Events filter controls

The next screenshot shows the filter controls. Filtering can be done by Severity, Source and/or an
arbitrary Search String. In addition you can select the time range for the events that you are interested
in. The time range is the usual time range found throughout the gui. Events will be filtered by all criteria
given. If no Severity is given (as shown on the screenshot), all Severities will match. The same applies
for the Source and Search String.

Below those controls, you get the list of matching events:

In this example we have three events in the time range. The details are only partially visible. Along
with the Event Id, you see its severity, the EventSource, the time the event occurred and if any user

103
Chapter 11. Events

has acknowledged the event (event 11 shows an acknowledgement). Note that Time occurred is the
time stamp of the log entry, not the time the event was generated. Ordering by Time occurred will
present events in logging order, ordering by Id is a better representation of the order in which events
were stored by the system.

The list can be sorted by clicking on the relevant column header.

Clicking on Detail of an event in the list will populate the Event Detail view with its information.

To acknowledge an Event click on Ack!. The column should immediately change to show that the
Event got acknowledged.

11.3.2.2. The detail view

By default, the detail view shows a message to click on a detail in the above list to see the details.

Clicking on an Event detail (here the event with id 11) shows its full details:

11.3.3. Timeline tab

Click on the Monitor tab's Timeline tab to go to the Timeline view:

The timeline view presents a timeline at the bottom. Within the view resource events are shown.
The resource events are shown amid other resource happenings, such as Chapter 6, Operations
executions.

104
 Defining Alerts on Events

You can click and drag to scroll around in the timeline changing the visible time range. The vertical
purple bar always shows the time when the Timeline tab was invoked.

Clicking on an item in the timeline will display detailed information for the selected item on a new
window:

11.4. Defining Alerts on Events

Defining Alerts for events works as described in the Chapter 5, Alerts section of this manual.

Alert conditions for events can be defined on Severity and/or an optional expression on the event
detail:

105
Chapter 11. Events

Note that the Severity setting is an exact match, not a Minimum Severity as specified in the
EventSource.

To learn more about conditions please refer to Section 5.3, “Integrations”

106
Appendix A. Revision History
Revision 1.0 Wed Jan 21 2009 Sarah Meehan [email protected]
First Conversion from wiki to docbook

107
108
Index
F
feedback
contact information for this manual, x

109
110