Data source configuration file overview

The ncwDataSourceDefinitions.xml file controls the data source definitions, connections, failover, self-monitoring, and the cleanup of the cache. After a fresh installation and initial configuration, this file contains only the information that you specified in the OMNIbus Web GUI Configuration Tool. After an upgrade, the elements are migrated to be compatible with the current version of the product.

Sample data source configuration file
Additional code for DSD configuration

Sample data source configuration file

The following example is a data source configuration file for a single failover pair.

Tip: For more samples, see the files in WEBGUI_HOME/etc/default/datasources/.

[1]<ncwDataSourceDefinitions>
[2]	<ncwDefaultDataSourceList>
[3]		<ncwDataSourceEntry name="NCOMS"/>
[4]	</ncwDefaultDataSourceList>
[5]	<ncwDataSourceDefinition type="singleServerOSDataSource" name="NCOMS">
[6]	<results-cache>
[7]		<chart maxAge="60" enabled="false" cleantime="120"/>
[8]		<config maxAge="3600"/>
[9]		<eventList maxAge="60" enabled="false" cleantime="120"/>
[10]		<eventSummary maxAge="10" enabled="true" cleantime="20"/>
[11]		<metric maxAge="10" enabled="true" cleantime="20"/>
[12]	</results-cache>
[13]	<ncwDataSourcePollingParameters>
[14]		<ncwFailOverPollingParameters backOffMultiplier="2" basePollingTime="10"/>
[14]		<ncwHeartBeatParameters basePollingTime="15"/>
[15]	</ncwDataSourcePollingParameters>
[16]	<ncwConnectionParameters 
[17]		<ncwStatementParameters
[18]			<ncwQueryTimeout baseTime="60"/>
[19]		</ncwStatementParameters>
[20]	</ncwConnectionParameters>
[21]	<ncwDataSourceCredentials password="" userName="root" encrypted="false"/>
[22]	<self-monitor enabled="false" granularity="300">		
[23]	<service name="DataSourceCommand" monitor="true" info="false" deduplicateinfo="true">
[24]			<threshold value="5" severity="3"/>
[25]			<threshold value="15" severity="4"/>
[26]			<threshold value="30" severity="5"/>
[27]		</service>	
[28]		<service name="ResultsCache" monitor="true" info="false" deduplicateinfo="true">
[29]			<threshold value="20" severity="3"/>
[30]			<threshold value="10" severity="4"/>
[31]		</service>
[32]		<service name="EventData" monitor="true" info="false" deduplicateinfo="true">
[33]			<threshold value="5" severity="3"/>
[34]			<threshold value="15" severity="4"/>
[35]			<threshold value="30" severity="5"/>
[36]		</service>
[37]		<service name="EventSummaryData" monitor="true" info="false" deduplicateinfo="true">
[38]			<threshold value="5" severity="3"/>
[39]			<threshold value="15" severity="4"/>
[40]			<threshold value="30" severity="5"/>
[41]		</service>
[42]		<service name="MetricData" monitor="true" info="false" deduplicateinfo="true">
[43]			<threshold value="5" severity="3"/>
[44]			<threshold value="15" severity="4"/>
[45]			<threshold value="30" severity="5"/>
[46]		</service>
[47]		<service name="SecurityRepository" monitor="true" info="false" deduplicateinfo="true">
[48]			<threshold value="5" severity="3"/>
[49]			<threshold value="15" severity="4"/>
[50]			<threshold value="30" severity="5"/>
[51]		</service>
[52]		<service name="JVM" monitor="true" info="false" deduplicateinfo="true">
[53]			<threshold value="85" severity="3"/>
[54]			<threshold value="90" severity="4"/>
[55]			<threshold value="95" severity="5"/>
[56]		</service>
[57]            <service name="VMM" monitor="true" info ="true" deduplicateinfo="true">
[58]                    <threshold value="5" severity="3"/>
[59]                    <threshold value="15" severity="4"/>
[60]                    <threshold value="30" severity="5"/>
[61]            </service>
[62]	</self-monitor>
[63]	<ncwFailOverPairDefinition>
[64]		<ncwPrimaryServer>
[65]			<ncwOSConnection host="192.168.0.1" port="4100"/>
[66]		</ncwPrimaryServer>
[67]		</ncwFailOverPairDefinition>
[68]	</ncwDataSourceDefinition>  
[69]</ncwDataSourceDefinitions>

Explanation of the XML elements

The following explanations describe how the code works line by line.

Line 1: <ncwDataSourceDefinitions>

This line opens the top-level <ncwDataSourceDefinitions> element and initiates the file.

Lines 2-4: <ncwDefaultDataSourceList>

The <ncwDefaultDataSourceList> element contains a list of one or more <ncwDataSourceEntry> elements. The first <ncwDataSourceEntry> is the default data source. The configuration file must contain at least one <ncwDataSourceEntry> element. The data source that is named in the <ncwDefaultDataSourceList> element must also be defined in a <ncwDataSourceDefinition> element. For more information, see Line 5: <ncwDataSourceDefinition>.

If communications with the default data source cannot be established, the next <ncwDataSourceEntry> element in the list is contacted, if one is present. User passwords and administrator passwords can differ between data sources.

Line 5: <ncwDataSourceDefinition>

The <ncwDataSourceDefinition> element contains the configuration and communication parameters for a single data source. The configuration file must contain at least one <ncwDataSourceDefinition> element. The element has the following attributes:

name: A user-defined that is also referred to by the <ncwDataSourceEntry> element. This attribute must be a unique alphanumeric string that contains no spaces or special characters.
type: Defines the data source as single ObjectServer and optional backup server, or a dual-server desktop (DSD) configuration. For more information, about DSD, see Additional code for DSD configuration.

Lines 6-12: <results-cache>

The <results-cache> element specifies whether data source data caching is enabled. This element has the following child elements:

<chart>

Defines caching for chart results. This element has the following attributes:

enabled: Set this attribute to TRUE to enable caching.
maxAge: Specifies the expiry time, in seconds, for the cache.
cleantime: Specifies the time interval, in seconds, at which cache entries are checked and removed. Cache data that exceeds the time imposed by the maxAge attribute is removed.

<config>

Defines caching for data source configuration data, for example event severity colors and conversions. This element has the following attribute:

maxAge: Specifies the expiry time, in seconds, for the cache.

<eventList>

Defines caching for results in the event lists. This element has the following attributes:

enabled: Set this attribute to TRUE to enable caching.
maxAge: Specifies the expiry time, in seconds, for the cache.
cleantime: Specifies the time interval, in seconds, at which cache entries are checked and removed. Cache data that exceeds the time imposed by the maxAge attribute is removed.

<eventSummary>

Defines caching for event summary results, such as maps and Event Dashboards. This element has the following attributes:

enabled: Set this attribute to TRUE to enable caching.
maxAge: Specifies the expiry time, in seconds, for the cache.
cleantime: Specifies the time interval, in seconds, at which cache entries are checked and removed. Cache data that exceeds the time imposed by the maxAge attribute is removed.

<metric>

Defines caching for metric results, that is, metric gauges. This element has the following attributes:

enabled: Set this attribute to TRUE to enable caching.
maxAge: Specifies the expiry time, in seconds, for the cache.
cleantime: Specifies the time interval, in seconds, at which cache entries are checked and removed. Cache data that exceeds the time imposed by the maxAge attribute is removed.

Lines 13-15: <ncwDataSourcePollingParameters>

The <ncwDataSourcePollingParameters> element contains the elements that control failover and data source heartbeat polling. The <ncwFailOverPollingParameters> child element has the following attributes:

basePollingTime: Specifies the time interval at which the data source is polled if a failover occurs.
backOffMultiplier: Contains the multiplier for the algorithm used by the Web GUI to calculate the polling backoff time during a failover. This example is not configured for failover so the attribute is ignored.

The <ncwHeartBeatParameters> child element has the following attribute:

basePollingTime: Specifies the time interval for the Web GUI to poll an active data source.

Lines 16-20: <ncwConnectionParameters>

The <ncwConnectionParameters> element specifies the connection parameters for the data source. The <ncwQueryTimeout> child element has the following attribute:

baseTime: Specifies the time, in seconds, before a query sent to the data source times out. If a query times out, the Web GUI attempts to reconnect to the data source.

Line 21: <ncwDataSourceCredentials>

The <ncwDataSourceCredentials> element contains the login information that is required by the Web GUI to access the data source. It has the following attributes:

userName: The user name that is used to access the data source. By default, the user name is not encrypted.
password: The password for the user. By default, the password is not encrypted.
encrypted: Permits the user name and password to be encrypted by the nco_g_crypt encryption utility can be used. To permit encryption, set the attribute to TRUE. The default is FALSE.

Important: For security, set the file permissions of the ncwDataSourceDefinitions.xml to restrict access to only the required users.

Note: When Advanced Encryption Standard (AES) is defined as the encryption method for the ObjectServer, only local users are supported.

Line 22: <self-monitor>

Enables self-monitoring, which records statistics about your Web GUI environment and raises self-monitoring events in the primary data source. Self-monitoring events are divided into problem events, which are raised when specific threshold is reached (see Table 1) and information events, which summarize the monitored service. Problem events are always raised and information events are optional. The attributes of this element are as follows:

enabled: Switches self-monitoring on or off.
granularity: Specifies the frequency, in seconds at which self-monitoring events are inserted into the data source.

After you enable self-monitoring, an entry is written to the ncw.0.log to this effect.

Lines 23-61: <service>

The self-monitoring functionality measures specific services. A service is defined by a <service> element. This element has the following attributes:

name: Declares which service is being monitored. Do not change the names of this attribute. Possible values are in Table 1.
monitor: Switches on monitoring for the service. Each service is switched on or off separately.
info: If enabled, raises information events in the data source at the frequency that is defined by the granularity attribute of the <self-monitoring> element. The information messages contain a summary of the monitored service. They have a default severity of 2 (warning).
deduplicateInfo: Deduplicates the information events, to reduce the number of events in the event lists.

Each service has one or more thresholds, which are defined by <threshold> child elements. When threshold values are reached, problem events of specific severities are raised. The following table describes each service and the default thresholds.

Table 1. Services that can be monitored by the <self-monitoring> element
Service name	Description	Notes
DataSourceCommand	Monitors the response times, in seconds, of the data source to all queries.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds.
ResultsCache	Monitors the efficiency of the cache by measuring the number of queries that are answered by cached data. The lower the percentages of queries that can be answered by the cache, the less efficient the cache is.	By default, a major event is raised when the percentage falls below 10%. A minor event is raised when the percentage falls below 20%.
EventData	Monitors the response time, in seconds, of the data source to queries for event data, for example, for Event Viewers and Active Event Lists.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds.
EventSummaryData	Monitors the response time, in seconds, of the data source to queries for event summary data, such as maps and event dashboards.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds.
MetricData	Monitors the response time, in seconds, of the data source to queries for metrics data, which is used to populate gauges.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds.
SecurityRepository	Monitors the response time, in seconds, of the security repository. The security repository is defined as the ObjectServer that is used as the user registry, or the file-based repository or LDAP directory.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds.
JVM	Monitors the utilization of the Java Virtual Memory (JVM). Events are raised when the utilization reaches specific thresholds.	By default, a critical event is raised when utilization reaches 95%. A major event is raised when the reaches exceeds 90%. A minor event is raised when the utilization reaches 85%.
VMM	Monitors the events inserted into the configured datasource's acting primary ObjectServer, based on the configured thresholds for the VMM service.	By default, a critical event is raised when the response time reaches 30 seconds. A major event is raised when the response time reaches 15 seconds. A minor event is raised when the response time reaches 5 seconds. Note: The VMM monitor does not insert any monitoring events if VMM sync is turned off (users.credentials.sync=false) in the server.init file.

Lines 63-67: <ncwFailOverPairDefinition>

The <ncwFailOverPairDefinition> element contains the server communication information for the primary data source and optionally a secondary data source for failover.

Specify the communication information of the primary data source in the <ncwPrimaryServer> element. This element has a child element that is called <ncwOSConnection >. In this element, specify the IP address or host name, and port number of the primary data source.

To configure a failover pair, add an <ncwBackUpServer> element to the <ncwFailOverPairDefinition> element. The <ncwBackUpServer> element also has a child element <ncwOSConnection>. In this element, specify the IP address or host name, and port number of the failover data source. For example:

<ncwBackUpServer>
           <ncwOSConnection host="host" port="port"/>
</ncwBackUpServer>

Ensure that the user names and field names (in the alerts tables) in the back up ObjectServer are identical to those on the primary server, and that each ObjectServer contains an equal number of fields. If the fields do not correspond, failover does not occur. If the users do not match, users cannot log in.

The backup ObjectServer is constantly polled for availability, so that the Web GUI can switch to the backup server if the primary server fails. During a failover, the Web GUI is aware that it is connected to the backup server and automatically checks for the recovery of the primary server in the failover pair. After it is established that the primary server has recovered, the Web GUI switches back to the primary server.

Line 68 </ncwDataSourceDefinition>

This line contains the element that closes the <ncwDataSourceDefinition> element. Additional data sources are contains in subsequent <ncwDataSourceDefinition> elements.

Line 69: </ncwDataSourceDefinitions>

This line closes the <ncwDataSourceDefinitions> element and the file.

Additional code for DSD configuration

If an ObjectServer is configured for a DSD environment, the following code defines the display ObjectServer or ObjectServers. This code is inserted after the closing </ncwFailOverPairDefinition> element (line 26).

<ncwReadCloudDefinition>  
               <ncwOSConnection host="host" port="port"/>
</ncwReadCloudDefinition>

Use one <ncwOSConnection> element for each display ObjectServer. An ObjectServer cannot have more than one <ncwReadCloudDefinition> element.