Red Hat Training

A Red Hat training course is available for Red Hat JBoss Operations Network

6.4. Synchronizing Server Configuration

Even in different environments, JBoss ON servers can share a lot of the same configuration. For example, different JBoss ON servers may manage a development environment, staging environment, and production environment, yet on all three, the servers use similar metric templates and configuration settings.
To simplify managing separate but similar environments, JBoss ON can export the configuration for a server and then import that configuration into another server.
Any user with permissions to manage settings can export the server configuration. There are two categories of data:
  • System settings, which include how long alerts, events, and monitoring metrics are stored; the baseline calculation schedule; and the LDAP server configuration.
  • Metric collection settings for each resource types.
The information is exported to dumped to a gzipped XML file, which can be easily edited before being imported into another server.
Note
Syncing server configuration is only necessary when servers use different backend databases. Servers which share a database (in the high availability cloud) already share their configuration.
Import and export operations are only done through the JBoss ON CLI. See the JBoss ON API Documentation on the Customer Portal for more information.
Report a bug

6.4.1. Exporting a Server's Configuration

  1. Log into the JBoss ON CLI. 
    [root@server bin]#  installDir/bin/rhq-cli.sh -u rhqadmin -p rhqadmin
  2. Export the data to a database object: 
    rhqadmin@localhost:7080$ var ex = SynchronizationManager.exportAllSubsystems();
  3. Convert that object into an export file. The file extension should be .xml.gz because the export format is a GZIP'ed XML file. 
    rhqadmin@localhost:7080$ saveBytesToFile(ex.exportFile, 'export.xml.gz');
Note
The user must have the manage settings permission to export the server data.
Report a bug

6.4.2. Importing a Server's Configuration

Server configuration is exported into an XML file. Administrators can edit this file to control what kind of information is imported into the other JBoss ON servers, so there is a lot of adaptability in the import process. When the file is imported, it first runs through a series of validation tests to make sure that the configuration data can actually be imported into the server. Then, two classes or synchronizers, one for system settings and one for metric templates, are used to import the data.
The import process can be changed by administrators, so there are several common import scenarios:
  • The configuration data are imported directly into the server, using all of the default settings.
  • The XML file can be edited so that the configuration values are adapted to the target JBoss ON servers.
  • The synchronizer behavior is changed, which changes what data elements are imported.
Report a bug

6.4.2.1. Editing the XML Import File

All of the data are dumped to a single XML file, which contains the system settings, metric settings for each resource type, and some processing instructions.
The configuration entries all defined in two large <entities> elements.
Metric templates list each metric separately in individual <entity> elements, with the metric itself identified by its name, resource type, and plug-in as arguments for the element. The entity ID identifies the template in the JBoss ON database, but is ignored during import because the IDs do not need to match between servers. 
<entities id="org.rhq.enterprise.server.sync.MetricTemplateSynchronizer">
 <entity>
  <data>
   <metricTemplate 
    enabled="false" 
    defaultInterval="300000"
    perMinute="false" 
    metricName="trap_count" 
    resourceTypePlugin="snmptrapd"
    resourceTypeName="SnmpTrapd" 
    referencedEntityId="10001">
   </metricTemplate>
  </data>
 </entity>
 .....
System settings, on the other hand, are all defined in a single <entity> element, and each configuration parameter is given as a key on the entry. Not all of these keys are imported into the target server; the keys which are imported depend on the synchronizer configuration. 
<entities id="org.rhq.enterprise.server.sync.SystemSettingsSynchronizer">
 <entity>
  <data>
   <systemSettings referencedEntityId="0">
    <entry key="CAM_BASE_URL">http://10.16.65.121:7080/</entry>
    <entry key="CAM_DATA_PURGE_6H">2678400000</entry>
    <entry key="CAM_LDAP_BIND_DN"></entry>
    .....
   </systemSettings>
  </data>
 </entity>
</entities>
Report a bug

6.4.2.2. Changing the Synchronizer Configuration

JBoss ON uses synchronizers to set what elements — like what metric schedules — are imported into the JBoss ON server and how to apply them to the server. The synchronizer has a default template which applies configuration changes programmatically to every import operation. There is also synchronizer configuration in the exported XML file, which are applied to that specific import operation.
Note
Custom settings in the XML file override the programmatic template settings. Programmatic settings passed with the CLI commands override the settings in the XML file.
To print the configuration for a specific synchronizer, specify the synchronizer name in SynchronizationManager.getImportConfigurationDefinition(). For example: 
rhqadmin@localhost:7080$ var configDef = SynchronizationManager.getImportConfigurationDefinition('org.rhq.enterprise.server.sync.SystemSettingsSynchronizer')
To print all of the configuration for both synchronizers: 
rhqadmin@localhost:7080$ var configDefs = SynchronizationManager.importConfigurationDefinitionOfAllSynchronizers 
rhqadmin@localhost:7080$ configDef = configDefs.get(0)

rhqadmin@localhost:7080$ pretty.print(configDef.configurationDefinition.defaultTemplate.configuration)
Report a bug
6.4.2.2.1. Changing the Synchronizer Settings in the XML File
The simplest way to customize the synchronizer configuration is to change the configuration in the exported XML file. The settings and metrics synchronizers use XML elements that are very similar to the resource plug-in configuration. The root element for a synchronizer is <default-configuration>, and the configuration settings are listed as properties within that element.
The settings synchronizer has the simplest configuration. It has a single <ci:simple-property> element, and the list of settings to import is given in the value= flag on the <ci:simple-property> element. 
<default-configuration>
    <ci:simple-property value="AGENT_MAX_QUIET_TIME_ALLOWED, ENABLE_AGENT_AUTO_UPDATE, ENABLE_DEBUG_MODE, ENABLE_EXPERIMENTAL_FEATURES, 
CAM_DATA_PURGE_1H, CAM_DATA_PURGE_6H, CAM_DATA_PURGE_1D, CAM_DATA_MAINTENANCE, DATA_REINDEX_NIGHTLY, RT_DATA_PURGE, ALERT_PURGE, EVENT_PURGE, 
TRAIT_PURGE, AVAILABILITY_PURGE, CAM_BASELINE_FREQUENCY, CAM_BASELINE_DATASET" type="string" name="propertiesToImport">
        <c:description>The names of the properties that should be imported. Note that these are the INTERNAL names as used in the RHQ database</c:description>
    </ci:simple-property>
</default-configuration>
Note
The values for the settings are the names used in the JBoss ON database for the server settings.
The metrics schedules settings are much more complex because the potential metrics schedules are different for each resource. A metric schedule can be defined in any of three ways (or a combination):
  • A simple list, which has a <ci:list-property> list members defined by a property (<ci:simple-property>) and a list of values 
    <default-configuration>
    <ci:list-property name="my-list">
        <c:simple-property name="element" type="string"/>
        <ci:values>
           <ci:simple-value value="a"/>
           <ci:simple-value value="b"/>
           <ci:simple-value value="c"/>
        </ci:values>
    </ci:list-property>
</default-configuration>
  • A map of values, which is very similar to a simple list in that it uses a list of properties (<ci:simple-property>) and a corresponding list of values (<ci:simple-value>), except that each value corresponds to a single, specified property based on the name 
    <default-configuration>
    <ci:map-property name="my-map">
        <c:simple-property name="prop1" type="integer"/>
        <c:simple-property name="prop2" type="string"/>
        <c:simple-property name="prop3" type"boolean"/>
        <ci:values>
            <ci:simple-value property-name="prop1" value="1"/>
            <ci:simple-value property-name="prop2" value="abc"/>
            <ci:simple-value property-name="prop3" value="true"/>
        </ci:values>
    </ci:map-property>
</default-configuration>
  • A table, which is a list of maps. Each set of maps specifies one table in the row. 
    <default-configuration>
    <ci:list-property name="table">
        <c:map-property name="row">
            <c:simple-property name="column1" type="integer"/>
            <c:simple-property name="column2" type="boolean"/>
            <c:simple-property name="column3" type="string"/>
        </c:map-property>
        <ci:values>
            <ci:map-value>
               <ci:simple-value property-name="column1" value="1"/>
               <ci:simple-value property-name="column2" value="true"/>
               <ci:simple-value property-name="column3" value="a"/>
            </ci:map-value>
            <ci:map-value>
               <ci:simple-value property-name="column1" value="2"/>
               <ci:simple-value property-name="column2" value="true"/>
               <ci:simple-value property-name="column3" value="b"/>
            </ci:map-value>
            <ci:map-value>
               <ci:simple-value property-name="column1" value="3"/>
               <ci:simple-value property-name="column2" value="false"/>
               <ci:simple-value property-name="column3" value="c"/>
            </ci:map-value>
        </ci:values>
    </ci:list-property>
</default-configuration>
For example, this uses a map to import only the metric schedule for the free memory metric for a JBoss AS 5 server: 
<default-configuration>
    <ci:simple-property value="false" type="boolean" name="updateAllSchedules" />
    <ci:list-property name="metricUpdateOverrides">
        <c:map-property summary="false" required="true" readOnly="false" name="metricUpdateOverride">
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="metricName" />
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="resourceTypeName" />
            <c:simple-property type="string" summary="false" required="true" readOnly="false" name="resourceTypePlugin" />
            <c:simple-property type="boolean" summary="false" required="true" readOnly="false" name="updateSchedules" />
        </c:map-property>
        <ci:values>
           <ci:map-value>
               <ci:simple-value name="metricName" value="MCBean|ServerInfo|*|freeMemory"/>
               <ci:simple-value name="resourceTypeName" value="JBoss AS Server"/>
               <ci:simple-value name="resourceTypePlugin" value="JBossAS5"/>
               <ci:simple-value name="updateSchedules" value="true"/>
           </ci:map-value>
        </ci:values>
    </ci:list-property>
</default-configuration>
To update all metrics schedules, set the <ci:simple-property> element to name="updateAllSchedules".
To update a single metric schedule, then set the property element's name to metricUpdateOverride and set the updateSchedules property value to true.
Report a bug
6.4.2.2.2. Changing the Synchronizer Settings Programmatically
To change the configuration, create a new instance of the default and use the setValue configuration object to add or remove keys from the list. For the settings synchronizer, this lists the key name to import: 
configurationObject.getSimple('propertiesToImport').setValue(defaultSettingsToImport + ', keyName')
For metrics schedules, it lists the metric schedule per resource type, based on a properties list or a properties map: 
var update = new PropertyMap('metricUpdateOverrides')
update.put(new PropertySimple('propertyName', 'resourcePluginName'))
  1. Get the default definition. 
    rhqadmin@localhost:7080$ var systemSettingsImportConfigurationDefinition = SynchronizationManager.getImportConfigurationDefinition('org.rhq.enterprise.server.sync.SystemSettingsSynchronizer')
  2. Create a new configuration instance. 
    rhqadmin@localhost:7080$ var configurationObject = systemSettingsImportConfigurationDefinition.configurationDefinition.defaultTemplate.createConfiguration()

rhqadmin@localhost:7080$ var systemSettingsImportConfiguration = new ImportConfiguration(systemSettingsImportConfigurationDefinition.synchronizerClassName, configurationObject)
  3. Change the settings in the new instance.
    For example, for the server settings synchronizer: 
    rhqadmin@localhost:7080$ var defaultSettingsToImport = configurationObject.getSimple('propertiesToImport').stringValue
 
rhqadmin@localhost:7080$ configurationObject.getSimple('propertiesToImport').setValue(defaultSettingsToImport + ', CAM_BASE_URL')
    For the metrics template synchronizer: 
    configurationObject.getSimple('updateAllSchedules').setBooleanValue(true)
var updateList = new PropertyList('metricUpdateOverrides')
var update = new PropertyMap('metricUpdateOverride')
update.put(new PropertySimple('metricName', 'MCBean|ServerInfo|*|freeMemory'))
update.put(new PropertySimple('resourceTypeName', 'JBossAS Server'))
update.put(new PropertySimple('resourceTypePlugin', 'JBossAS5'))
update.put(new PropertySimple('updateSchedules', 'true'))

updateList.add(update)

configurationObject.put(updateList)
Report a bug

6.4.2.3. Importing the Configuration

  1. Log into the JBoss ON CLI. 
    [root@server bin]#  installDir/bin/rhq-cli.sh -u rhqadmin -p rhqadmin
  2. Import the XML file containing the configuration: 
    rhqadmin@localhost:7080$ var data = getFileBytes('export.xml.gz');
rhqadmin@localhost:7080$  SynchronizationManager.importAllSubsystems(ex, null);
    The null parameter means that the import process uses the default settings in the XML file or, if the defaults are missing from the XML, that it uses the settings defined on the target server. If alternate settings were constructed in Section 6.4.2.2, “Changing the Synchronizer Configuration”, then they can be specified programmatically instead. For example: 
    rhqadmin@localhost:7080$ var configsToImport = new java.util.ArrayList()
rhqadmin@localhost:7080$ configsToImport.add(systemSettingsImportConfiguration);
rhqadmin@localhost:7080$ configsToImport.add(metricTemplatesImportConfiguration);
rhqadmin@localhost:7080$ SynchronizationManager.importAllSubsystems(ex, configToImport);
Report a bug