Certain types of Resources can be configured via RHQ. For example, a Postgres Server's postgresql.conf file or a JBossAS Datasource's ds.xml file can be viewed or edited using RHQ. RHQ will also maintain a history of configuration revisions and allow the user to view or rollback to previous revisions. This page will describe in detail how to use the Configuration subsystem in RHQ.
Some, but not all, Resources are configurable via RHQ. Whether a Resource is configurable or not, and what aspects of a Resource are configurable, are determined by the corresponding plugin's Plugin Descriptor.
Resources (or, more appropriately said, Resource types) that support configuration will either show a "Configure" tab when the Resource is selected or a 'C' quicknav icon (or edit icon in RHQ 1.2 or later) on the Browse Resources page in the UI. Starting in RHQ 1.2, configurations can also be viewed or edited for compatible groups of configurable Resources. For more information on group configurations, see Group Configuration.
As already stated, this very much depends on the individual Resource type and how the plugin writer implemented it for that specific Resource type.
In general the steps are always the same:
- RHQ presents the user with the current configuration
- The user changes the configuration and submits it
- RHQ 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
Configurable properties come in different types, that are configured in the plugin descriptor for each resource type. Those are e.g.
RHQ will check the entered data when submitting the configuration update form.
For some properties you will see a "Unset" mark as in the following example:
The semantics of a property being unset is that RHQ will not submit any value to the managed resource, but relies on the value from the managed resource. This is useful for 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 any data. An example for this would be credentials for an unsecured JBoss AS resource.
RHQ 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.
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 RHQ server is restarted. So if e.g. the last revision id was 7 before the restart, it could be 50 after the restart.
In order to configure a resource, the correct access rights need to be present if required. 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 RHQ Agent needs to be able to read and write the PostgreSQL configuration files.
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.
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.
Some groups with seldom-used properties are collapsed by default.
Clicking "EDIT" at the top will allow you to change properties and present you with a "SAVE" button at the bottom of the page.
When "SAVE" is clicked you will be forwarded to the history view where you will see a message that your configuration request has been forwarded to the agent for processing.
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.
For each revision you see when it was submitted, when the change was completed, if it succeeded or failed and who triggered the change. If the RHQ 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 get some more information 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 above.
The revision id with the asterisk (*) next to it is the current configuration.