Red Hat Training

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

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.
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>
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)
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.
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)
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);