Aside from some minor configuration in its rhq-server.properties file, JBoss ON is completely administered through its web interface.

By default, the JBoss ON server listens over port 7080. (A different port can be configured when the server is installed, and the port number can be changed in the server configuration.) To connect to the server, then, simply open a standard HTTP page with a URL in the format hostname:port. For example:

http://server.example.com:7080

Then, log in using any valid username/password combination. The default administrative user has the name and password rhqadmin.

The JBoss ON UI is very rich — there are a lot of small elements that are all layered together to provide a very detailed and flexible interface for interacting with the JBoss ON servers and resources. To maximize its use of space, JBoss ON uses top navigation menus, tabbed browsing with subtabs, active links, and navigation trees to establish relationships between JBoss ON resources and JBoss ON functionality. In a very general view, several types of visual elements that work together to comprise the UI:

All of these elements fit together in a repeated and reliable pattern.

Understanding the type of page that you're on can make it easier to navigate through the JBoss ON UI and can help you more completely understand what you can accomplish in JBoss ON.

The Message Center shows all of the messages that have been returned by the GUI for the current browser session. This includes any actions taken in the UI — like adding resources to the inventory, configuring resources, or uploading content — and it also includes any error messages that may have been returned during the session.

Almost all of the information in JBoss ON is displayed in tables, from the resource inventory to the list of plug-ins for the agent. The SmartGWT UI has some versatility in how that table information is sorted and displayed.

A few tables use a very simple ascending/descending order based on the column being sorted, either numerically or alphabetically.

Most areas in the UI allow a more complex method of displaying information. As with basic tables, simply clicking a column name will sort that column in ascending/descending order. However, advanced GWT tables also have an option to change the table layout and sort options, by clicking a menu arrow at the right of the column.

When a menu arrow is selected, the sort order for that column can be changed, or any other column. You can also change the column sizing and even the types of columns displayed. The options are generated dynamically, depending on what kind of entry is contained in the table.

The sort order can even be prioritized by specifying multiple criteria. For example, resources can be sorted by name, then by plug-in, then by ID. Since resources have standardized names, sorting by name or parent alone may not be specific enough to give a meaningful order to the entries; providing multiple, prioritized criteria can make the table display more accurate.

The Dashboard is configurable. It is composed of individual portlets, and these portlets can be rearranged or independently refreshed through the icon menu displayed on each portlet. There can even be multiple Dashboards, with different portlets, which can be used to give different and specific views into JBoss ON and its resources.

Using favorites makes it easy to navigate to resources that administrators need to access routinely for configuration updates, monitoring, or alerting.

Each resource has a small ribbon icon in the upper right corner of its details page. Clicking that icon automatically adds it to the resource favorites list.

The resource and group favorites are listed in the Favorites in the shortcuts on the right of the top menu. Clicking a resource on that list automatically opens its details page without having to search for the resource. Because multiple resources may share a name or some properties, the Favorites list includes a hover with more details about the resource so you can select the right one.

Resource-related entries can be deleted through the inventory browser or group browser. Most JBoss ON server configuration entries cannot be deleted. Only user-supplied elements, like plug-ins, content, roles, and users, can be deleted.

If an item can be deleted, then a delete button is available in the table list or details page for that item.

Dynamic searches are extremely powerful, past simply finding resources. Dynamic searches can run through values in a number of different resource traits, not only the resource name. Dynamic searches can even be saved, so they're repeatable and can be used as ad hoc reporting.

Dynamic searches are easy to use because of search suggestions. A drop-down menu for every search provides three different types of suggestions:

When search terms are entered in the field, the matching substrings in possible matching resources are highlighted. By default, the suggestions can match any substring in the resource or in resource configuration traits. The suggestions can be limited to match the string at the beginning or end of the matching attribute using different operators (covered in Section 2.2, “About the Dynamic Search Syntax”).

JBoss ON has its own search syntax for dynamic searches. The syntax is supposed to be relatively simple while covering a wide array of search-able items and allowing different phrases to be coupled together.

The basic dynamic search matched whatever text is entered in the search box in a general substring search. The search can allow a more detailed and targeted syntax, in this form:

[search_area].[search_property] operator value operator additional_search

The search_area identifies what type of entry — resource or group — is being searched for. This is an optional value because the search area is implied by the location of the search; i.e., searching in the Resources area implies a resource search, so it's not necessary to include the resource. part of the search.

postgres table myexampletable

"My Compatible Group"
'test box'
plugin=jboss 123.4.5.6
trait[partitionName]='my example group' server.example.com

name="Production's Main Group"

resource.id=^100

script$

resource.trait[Database.startTime] = null

name = "null"

resource.type.plugin = Postgres

postgres server myserver

postgres AND server AND myserver

postgres | jbossas

a | b c

(a | b) (c | d)

(a) (b | (c d))

Dynamic searches can be saved, which makes it much easier to reuse complex or common searches. To save a search:

Saved searches are listed with other search results whenever the dynamic search criteria match any part of the saved search string and immediately whenever the dynamic search field is active, before search parameters are entered. The name of the search is shown in bright green. The drop-down option shows the string used in the saved search in black text beneath the name, to make it clear what the parameters for the search are.

To edit a saved search, select the search from the list of suggestions and then click the gold star. This deletes the search, but leaves the previous search settings in the search box. This allows the search parameters to be edited and then re-saved.

To delete a search, simply click the gold star or the trashcan icon by the search name when it is highlighted in the list. It is immediately removed from the saved searches list.

The JBoss ON inventory is the central list of every managed resource that is recognized by the JBoss ON server.

Before any application or platform can be managed by JBoss ON, it must be imported into the inventory. There are different ways of adding resources to the inventory, depending on how the resource was discovered.

Discovery scans are run on a defined schedule. There may be an instance where you add a new server or service on a platform and want to add it immediately to the JBoss ON inventory, before the next scheduled discovery run. It is possible to add that new child resource manually by importing it into the inventory of the parent resource — without waiting for the next discovery scan.

Tomcat servers are discovered automatically on Linux and Unix systems, but they require additional configuration before they can be discovered on Windows systems.

After a few minutes, the Tomcat instance should show up in the Discovery Queue.

JBoss ON can create certain types of children resources for parent resources. For example, a Postgres server can allow JBoss ON to create Postgres users. Not every allowed child resource type for a resource can be created through the JBoss ON UI; these children are usually limited to resource types that can be configured simply and remotely, such as scripts, WAR/EAR files, and server users.

Every resource has details about the server or service that can be viewed, such as its name, description, and version. (The specific information is different for each resource type.) These details are usually hidden when viewing the resource, but they can be viewed by clicking the arrow by the resource name to expand the details area.

Any fields with green text can be edited. This allows administrators to use more specific or useful information in areas that are supplied by the agent discovery, like the resource name, or to add information, like a description or, for example, a platform's physical location.

To edit a field, hover the cursor over the name and click the pencil icon that appears.

When the edits are made, click the green check mark to save the changes.

A resource can be removed from the JBoss ON inventory after it has been imported.

A resource is removed from the inventory by editing the inventory settings in a parent entry. This can be the inventory for the resource's parent entry or a group to which the resource belongs.

One quick management tool in JBoss ON is an inventory report. The report summarizes the resources currently in the inventory, grouped by resource type and five summaries:

To generate the inventory report:

Groups are simply a means to organize resources within the JBoss ON inventory. JBoss ON has several different kinds of groups, listed in Table 6, “Types of Groups”, which allows an administrator to manage resources in different, flexible ways.

A dynamic groups specifies a search term to use to search the inventory and identify matching resources to belong to the group. Since the search results change automatically as results are added and removed from the inventory, the group membership is always changing and always current. Using dynamic groups helps automate management tasks for large inventories.

Enterprise resources can be grouped by cluster identifier, broadcast group, logical service layer, geographical location, security domain, or any other logical grouping.

Individual resources can potentially belong to multiple groups, in large inventories it is important to know how different group definitions will affect the enterprises resources.

expression 1
exprA1 
exprA2 
groupby exprB1 
groupby exprB2

expression 2
exprA2 
exprA1 
groupby exprB2 
groupby exprB1

resource.id = 10001

resource.parent.id = 10001

resource.attribute[string-expression] = value

resource.parent.type.category = Platform

empty resource.attribute[string-expression]

not empty resource.attribute[string-expression]

groupby resource.attribute

groupby resource.parent.name

resource.parent.type.category = Platform

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

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

resource.type.category = server groupby 
resource.type.plugin groupby 
resource.type.name groupby 
resource.parent.name

resource.type.plugin = JBossAS
resource.type.name = JBossAS Server
empty resource.pluginConfiguration[principal]

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

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

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

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

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

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

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

A user must have the global security or inventory permission to create groups.

Compatible and mixed groups both have static members, which means that resources are manually assigned to the group rather than being assigned dynamically based on some attribute. The group membership can be changed as the resources in the JBoss ON inventory change.

Compatible groups manage the connection properties of the group members as part of the inventory. Since a compatible group can only contain members of the same resource type, it is possible to see an aggregate view or average of all of their individual connection properties. The connection settings define how the agent or server connects to the resource.

The rules are for the values of compatible group connections are simple:

To edit the connection properties:

The Connection Settings History sub-item shows the changes made to the connection properties. If there is a failure, clicking the hyperlink in the Date Created column opens any relevant error messages.

When JBoss ON is installed, there is a default superuser already created, rhqadmin. This superuser has the default password rhqadmin.

When you first log into JBoss ON after installation, change the superuser password.

All users can edit their own account details, and users with administrative rights (who belong to a role which grants them rights over user entries) can edit other users' entries.

User accounts can be temporarily disabled. This can be done for a security review or when there is some kind of breach, but users don't need to be deleted. The Enable Login property can prevent the user from logging into the JBoss ON UI and managing resources or making configuration changes.

The user account can be re-enabled at any time by changing the Enable Login value back to Yes.

In JBoss Operations Network, security is achieved by establishing precise relationships between users, resources, and the tasks users can perform. Interactions between users and resources are ordered by including or excluding those users and resources (through groups) in defined roles, and then granting the role the ability to perform tasks.

When a user is allowed to perform a certain operation, that is called a permission. All permissions must be explicitly granted to explicit resources. If a user is not given permission to a specific resource group, then the user, by default, has no access to that group — even if the user has permission to perform a task. Likewise, if a user has access to a group but has no permissions assigned, then the user cannot perform any tasks.

Any permissions set in JBoss ON are given to a role, and the members of the role inherit those permissions. Allowing or restricting permissions is access controls.

In JBoss ON, there are two categories where access control is given:

All JBoss ON permissions are listed in Table 9, “JBoss ON Access Control Definitions”.

For resource-level rights, all of the rights granted are explicit modify rights. This means that giving the right allows users to do something on the resource. For the most part, the ability to view that area (read rights) are granted implicitly. For example, any user can view the operations history of a resource or view the configured alerts for a resource within the role even if that role has not been given edit access to those subsystem areas. The read access is implied. There is one exception to that rule: resource configuration. Resource configuration can be considered a security risk, and some administrators may want to restrict read access to configuration. If write access is given to resource configuration, then read access is automatically granted. However, read-only access must be explicitly granted to a role; otherwise, read access is denied by default.

JBoss ON handles access to both resources and JBoss ON configuration through roles. A role has certain permissions assigned to it, meaning things that members of the role are allowed to do.

Only two types of JBoss ON identities can belong to a role: users and groups.

Users are assigned to a role to be granted those permissions. Users can be added to a role individually or be added as a member of an LDAP group.

Resource groups are assigned to a role to provide a list of resources that those users can perform actions on. Another way of looking at it is that users can only manage resources that they are expressly given access to. Roles define that access.

One convenient feature of roles is that users can be automatically assigned to roles by assigning an LDAP group to the role (Section 7.5, “Associating LDAP User Groups to Roles in JBoss ON”). All of the LDAP users who belong to that group are automatically members of the role. (This is similar to the simplicity of using LDAP user to create JBoss ON users by enabling LDAP authentication, in Section 7.3, “Configuring LDAP User Authentication”.)

There are two roles already configured in JBoss ON by default:

All of the role configuration — including the access rights set for the roles and the groups and users assigned to the role — can be changed after the role is created. The edit options for a role are exactly the same as the creation options in Section 6.2, “Creating a New Role”, even to changing the name of the role.

JBoss ON supports major directory servers for user authentication and group authorization:

By default, JBoss ON stores authentication information in its internal database. JBoss ON can also use an external LDAP repository to store this user information. With LDAP authentication, the JBoss ON server sends all login requests to the LDAP directory to process.

First, the JBoss ON server searches the LDAP directory for a matching username, and then it attempts to log into (bind to) the LDAP server using the given username and password. If the bind attempt is successful, then the user is successfully authenticated to the JBoss ON server.

After the JBoss ON server is configured to use LDAP for authentication, all login attempts are authenticated against the LDAP server.

The JBoss ON server constructs the LDAP entry name to look for based on the JBoss ON username and information about the LDAP directory, like the parent distinguished name in the directory tree and the naming attribute used for user entries; from there, it dynamically constructs a search filter every time someone logs into JBoss ON. Custom attributes can be added to the LDAP schema, such as JONUser=true, which can make it easier and more precise to locate entries.

The LDAP directory only verifies the login credentials. The LDAP server doesn't store any other JBoss ON user data, and it doesn't create, delete, or edit entries in JBoss ON. Likewise, JBoss ON doesn't create, delete, or edit entries in the LDAP directory. The only attributes in the LDAP database that relate to JBoss ON user accounts are the username and password. Other settings in the JBoss ON user entry are stored in the JBoss ON internal database (like the user's first name and surname, email address, and role assignments).

Because the LDAP directory doesn't store other attributes related to JBoss ON, it can't store a user certificate. This means that JBoss ON cannot use an LDAP directory for certificate-based authentication.

The first problem is simply determining which datastore to use to authenticate users. Even after LDAP authentication is enabled, JBoss ON still checks credentials against its own user store — and it checks its own database first. This means that a user can authenticate to JBoss ON without that request being sent to the LDAP database. All of the security features of the LDAP directory — particularly password policies and account inactivation — are lost because that is not the primary authentication mechanism.

Second, using two resources for user accounts introduces the problem of erroneously mapping JBoss ON and LDAP user accounts, creating duplicate entries, or allowing ghost entries. For example, John Smith is added as a user manually to JBoss ON and also has an LDAP user account. First, he has two duplicate, separately-managed user entries. Then, John Smith goes to a different division, and his LDAP entry is automatically deleted, but his JBoss ON user account remains because JBoss ON user accounts and LDAP user accounts aren't linked. He could still log into JBoss ON. Having duplicate user accounts can introduce other problems if there are accounts with identical names. For example, Jane Smith logs into JBoss ON with her JBoss ON user account (jsmith) and password, but is improperly assigned the JBoss ON role membership of LDAP user John Smith (LDAP UID jsmith) because her JBoss ON user ID was the same as his LDAP user ID, and her account was incorrectly mapped to his LDAP account and, therefore, his LDAP group membership.

Trying to maintain user accounts in both locations also impacts roles, at least in an administrative way. LDAP groups are added as members to the role, and then the group members are listed as user members for the role. However, the list of users assigned to the role does not show where those users came from. This means that the user list can be a mix of LDAP group members and JBoss ON members who were manually added to the list. Ultimately, it becomes difficult to add or remove users because it's not clear where the role users are coming from. Limiting role membership to LDAP groups simplifies maintenance; the roles are automatically updated when users are added or deleted to the groups on the LDAP side and those changes are synchronized over to the JBoss ON role dynamically.

What all of this means is that there are three things to consider when using LDAP services for authentication or authorization:

Authentication is the process of verifying the identity of an entity who attempts to access a server. JBoss ON uses simple authentication, meaning it uses simple username-password pairs to verify identity.

Many LDAP directories already contain organizational groups with users who will need to access resources in JBoss ON. Configuring JBoss ON to connect to these directories allows JBoss ON to assign LDAP groups to roles and then pull in those member lists dynamically, so the roles are populated with pre-existing member lists. All of the LDAP users automatically inherit the permissions of that role.

In the role details page, these LDAP user groups are separated from the resource groups, so it's easy to distinguish which types of group are being added to the role.

JBoss ON determines what LDAP groups a user belongs to with a simple search. Whenever a user logs into JBoss ON and an LDAP connection is configured, JBoss ON maps that JBoss ON username to a user entry in the LDAP directory server. The specific LDAP distinguished name (DN) for the user is used as part of a search to find matching member attributes in LDAP group entries. That is, the LDAP server can check the member lists in group entries to see what groups the person with that DN belongs to.

For LDAP groups to be added to roles, three things are required:

JBoss ON constructs an LDAP search based on the group object class and member attribute in the server configuration, plus the DN of the user given when the user logs in.

(&(group_filter)(member_attribute=user_DN))

For example, this looks for the member attribute on an Active Directory group:

ldapsearch -h server.example.com -x -D "cn=Administrator,cn=Users,dc=example,dc=com" -W -b "dc=example,dc=com" -x '(&(objectclass=group)(member=CN=John Smith,CN=Users,DC=example,DC=com))'

Red Hat Directory Server uses the uniqueMember attribute on groupOfUniqueNames groups more commonly than member and group. For example:

/usr/lib64/mozldap6/ldapsearch -D "cn=directory manager" -w secret -p 389 -h server.example.com -b "ou=People,dc=example,dc=com" -s sub "(&(objectclass=groupOfUniqueNames)(uniqueMember=uid=jsmith,ou=People,dc=example,dc=com))"

This search returns a list of all groups to which the user is a member. If any of these LDAP groups is assigned to a JBoss ON role, then that user is also automatically a member of that JBoss ON role.

Authentication is the process of verifying someone's identity. Authorization is the process of determining what access permissions that identity has. Users are authorized to perform tasks based on the permissions granted to their role assignments.

Section 7.3, “Configuring LDAP User Authentication” describes how an LDAP directory server can be used to authenticate users to JBoss ON. Any time a user attempts to log in, that request — with the username and password — is simply forwarded to the specified LDAP directory server to see if the credentials are correct.

Members of LDAP groups can be pulled in, automatically, as members of JBoss ON roles. The LDAP group is associated with a JBoss ON role and then the group members are authorized to do whatever the JBoss ON role is configured to allow. Any changes made in the LDAP group members are automatically reflected in JBoss ON, without having to edit the JBoss ON role.

If there is any error in this Basic Admin Guide or there is any way to improve the documentation, please let us know. Bugs can be filed against the documentation for the community-based RHQ Project in Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible, so we can be more effective in correcting any issues:

We appreciate receiving any feedback — requests for new sections, corrections, improvements, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at docs@redhat.com.