Managing golden configurations

A 'golden' configuration is a configuration version that you can use in compliance management as a known valid master version to compare device SmartModel configurations against. You use a golden configuration to generate compliance evaluation XPaths (by associating the configuration's device with a compliance definition) for running against a target device's configuration.

Before you start

You must have 'Golden Configuration Management' user authority in order to create a golden configuration.

About golden configurations

A 'golden' configuration is a configuration version used in compliance management as an ideal configuration against which configurations from similar devices can be compared. Any differences found are by default recorded as compliance evaluation failures. You can use this feature to quickly compare many thousands of details without having to manually create any evaluations.

Note: Golden configurations used for compliance purposes can only be for devices that have SmartModel drivers.

You can mark a device configuration as one of two types:

Globally available golden configurations: A Golden Configuration that is globally available to all devices, and can be used for compliance-checking the configurations of other devices.
Device-specific golden configurations: A Golden Configuration that is locally available (to its own devices only), and restricted to compliance-checking against its own devices' current configuration.

Globally available golden configurations (option 1)

Golden configurations that are globally available for compliance checking are typically used where an ideal device configuration has been verified, and can then be used to compliance-check other target device configurations in the network. This ideal device configuration can be modified with regular expressions in order to allow for expected differences between the golden and target configurations. The modified golden configuration can be loaded into Netcool Configuration Manager using the file-based access method in the Resource Access Document.

With this option, you create a golden configuration compliance definition, which points to a device with a golden configuration. Compliance evaluations are then automatically created based on the commands specified in the golden configuration. These evaluations can be run against other devices by including the compliance definition in compliance rules, policies or processes.

In cases where a range of values is acceptable, you can edit the golden configuration to provide a regular expression, and evaluations are treated as failures only if the values found in the compared configurations do not satisfy the regular expression in the golden configuration.

If an imported configuration contains regex, it has an initial status of 'false'. If it does not contain regex, it has an initial status of 'has regex'.

Example scenario: You start with a text file of native configuration settings derived from multiple real device configurations with similar VTMOS.; You then add regular expressions to make the text file more generic.; Next, you create a virtual VTMOS-based device, edit the device's RAD to specify that configuration imports will be file-based, and import the configuration.; Once imported, you define the configuration as 'golden'.; You subsequently use the Netcool Configuration Manager - Compliance UI to use the feature.

Restriction:

The only supported mechanism for creating/updating configurations containing golden configuration regular expressions is to add the regular expressions to the golden configuration outside Netcool Configuration Manager, before importing the configurations using the 'file based access' method delivered in the Drivers 20 release. See the Drivers 20 documentation for more information.

Currently 'file based access' method does not support Alcatel OLT devices.

Only Alcatel and Cisco devices are supported for golden configurations with the regex syntax outlined below. Juniper JUNOS supports the older syntax. See the note below for more information.

With Alcatel routers and switches, the content of fields with regular expressions must be surrounded by double quotes.

The 'golden configuration' feature depends on the presence of SmartModel configurations.

Only a SmartModel configuration can be marked as a golden configuration.
Only target devices with SmartModel configurations can be validated using a golden configuration.
(Even though the regular expression mark-up shown in the examples here can be defined in the native configuration, the evaluations generated are SmartModel-based).

Restriction:

Configurations that contain regular expressions are subject to the following restrictions:

- SmartModel-related right-click actions, such as for 'Edit' of configuration, are disabled, both at the configuration and network resource level (if it is the current configuration).
- Showing 'Modelled View' differences is not supported.
- Command Set Application is not supported.
- The 'Re-discover' action is not available.
- The 'Trigger Config Backup' action is not available.

Tip: Separately validate a golden configuration before using it for compliance checking.

You can annotate textual command argument values in the native configuration with specific regular expression (regex) mark-up in order to affect the compliance evaluation XPaths that are generated.

Keywords

regex content: A valid regular expression syntax
valid value: An example valid value for the argument.; This is used to support applying the regex syntax to argument values of any type, such as text, integer, and others. It ensures that the argument is constructed correctly on the SmartModel configuration, and compliance evaluation XPath.; The surrounding parenthesis are part of the syntax.; The translated smartmodel XML will not show the valid value in the regex markup, unless the translation results in the markup being placed in an ARG.999 element.

The following mark-up is available:

@@@(valid value)@<regex content>@@@

The compliance evaluation XPath generated matches a single occurrence of the same command in the target configuration, where the target command's argument values satisfy the regular expression supplied in regex content.

In the following example, an evaluation is created that matches a single occurrence of interface Tunnel 64 where the argument value satisfies the regex 172.\d{2}.0.\d{2,3}. The example valid value is 172.25.0.34

!
interface Tunnel64
tunnel destination @@@(172.25.0.34)@172.\d{2}.0.\d{2,3}@@@

Below shows the SmartModel configuration XML that will be generated for the above. The example valid value is removed during the XML generation process.

<Tunnel>
   <ARG.001>64</ARG.001>
   <tunnel>
      <destination>
         <ARG.001>@@@172.\d{2}.0.\d{2,3}@@@</ARG.001>
      </destination>
   </tunnel>
</Tunnel>

@@@(valid value).@regex content@@@(non Juniper JUNOS-based network devices)

The compliance evaluation XPath generated matches multiple occurrences of the same command in the target configuration where the target command's argument values satisfy the regular expression supplied in regex content. When a match is found it also validates that any children in the golden configuration under the command with the regex are the same in the target configuration.

In the following example, an evaluation is created to confirm that all snmp-server hosts in the target configuration with a value starting with 'myhost' also have a udp-port value of '1620'. The example valid value is myhost123

snmp-server host 123.123.123.123 @@@(myhost123).@myhost.*@@@ udp-port 1620

The following example illustrates the dependency on SmartModels and what the resulting evaluation XPath would look like in compliance. The '@@@(valid value).@' regex markup would result in a contextual evaluation containing the following two SmartModel Xpath parts:

Context XPath : /configuration/snmp-server/host[matches(ARG.003,'myhost.*')]
Defined XPath : udp-port[ARG.001='1620']
Note: The '123.123.123.123' value is not included in the XPath as explained in more detail below. The 'ARG' values are part of the SmartModel configuration, for example:
```
<snmp-server>
	<host>
		<ARG.001>123.123.123.123</ARG.001>
		<ARG.003>@@@.@myhost.*@@@</ARG.003>
		<udp-port>
			<ARG.001>1620</ARG.001>
		</udp-port>
	</host>
	<snmp-server>
```
The example valid value is removed during the XML generation process.

@@@(valid value)P@<regex content>@@@

The compliance evaluation XPath generated matches multiple occurrences of the same command in the target configuration where the target command's argument values satisfy the regular expression supplied in regex content, such as @@@(uplink)@P@uplink.*@@@ to match a text value starting with 'uplink'. When a match is found it will also validate that any siblings in the golden configuration structure under the parent of the command with the regex are the same in the target configuration.

In the following example, evaluations are created to confirm that all xe interfaces with a description starting with ‘uplink’ in the target configuration also have the following VLAN values.

<interface>
    <name junos:key="key">xe-0/0/0</name>
    <description>@@@(uplink)@P@uplink.*@@@</description>
    <mtu>9192</mtu>
    <unit>
        <name junos:key="key">0</name>
        <family>
            <ethernet-switching>
                <port-mode>trunk</port-mode>
                <vlan>
                    <members junos:key="key">1234</members>
                </vlan>
            </ethernet-switching>
        </family>
    </unit>
</interface>

For the two multiple occurrence regex items described above, any non regex argument values at the same or higher level in a command (relative to the argument with the regex) will be ignored when generating an evaluation; that is, the regex will be the only filter. For example, in the '@@@(valid value)P@' mark-up configuration example, the '0/0/0' argument on the xe interfaces will be ignored when creating an evaluation filtering on the description field starting with 'uplink'. The example valid value is removed during the XML generation process.

Tip: For a description of 'Defined XPath (single occurrence) and 'Context XPath' (multiple occurrence), see 'Creating compliance definitions using Golden Configuration'.

For Juniper JUNOS golden configurations

The 'P@' mark-up will behave the same as the '.@' mark-up does for non-Juniper JUNOS configurations. This is to allow for differences in how Juniper JUNOS arguments are modeled.
See the note below for more information.

If none of the above regex mark-up is supplied at any level down to a command element in a golden configuration, then the compliance evaluation XPath generated will check for a single exact match, that is, a 'Defined XPath', for the element between the golden and target configuration.

Note: The new regex format above is not supported for:

Multi-line textual fields, such as ‘banner motd’ argument values
Juniper JUNOS golden configurations

For these, the older format, which only supports textual arguments that have no special format validation, should still be used.

The older format options are:

@@@regex content@@@
@@@.@regex content@@@,
@@@P@regex content@@@)

In all other cases the new '@@@(valid value)…' format outlined above should be used to ensure that the argument is constructed correctly on the SmartModel configuration.

Device-specific golden configurations (option 2)

Device-specific golden configurations are locally available and restricted to own devices. They would typically be used where a particular configuration version for a device contains the set of commands for the device that are not expected to be altered.

Compliance checks between the device-specific configuration and the current configuration for a device can be configured by marking a configuration version as ‘device-specific’, and including its device in the scope of a compliance process that contains one of two new ‘device-specific’ pre-defined compliance definitions. (See Creating compliance definitions using a 'device-specific' golden configuration).

Device-specific compliance definitions do not specify any evaluations. Evaluations are generated when compliance process or policy is running (based on the current and device golden configurations of the target device). There are fields with a configuration that would be expected to be different between configuration versions (such as a timestamp or password value). These types of fields are identified in the Driver schema for the device (the field will have a ‘NonComparable’ attribute). A new XML file is now delivered with the Drivers in order to support the ‘NonComparable’ checking, If the file is not present then an updated driver will have to be installed.

To set a configuration

You set a selected configuration as 'golden' or 'device-specific'.

Important: Before starting this task, add the Golden column to the columns displayed in the configurations tab. Due to Linux 'thick client' limitations, this must be done in Windows.

Any configuration containing the '@@@'’ mark-up initially has a value of 'has regex' in the Golden column after import. This value can be modified by the actions below and once it has been set to one of the states below it will not subsequently revert at any stage to 'has regex'.

Select the Resource Browser in the navigation tree.
Search for the SmartModel device you want to view.
Click the Configuration tab, then right-click the selected configuration.
Select the Make Golden option. A window opens displaying the details for the selected configuration, and a radio button to select one of the following compliance execution scopes for the configuration:
- Configuration is available to other devices
- Configuration is restricted to this device (device-specific)
If a configuration is already golden, the Make Golden option is disabled.

You can type a description of the change in the Configuration description field. The maximum number of characters is 1,000. The description is shown in the Description column of the Summary table. The Description column is not displayed by default.
Click Finish to complete the procedure.

The selected configuration is now marked as golden by displaying one of the following statuses:

golden without regex: If the scope is available to other devices and the configuration does not contain regex.
golden: If the scope is available to other devices and the configuration contains regex.
device-specific without regex: If the scope is restricted to this device and the configuration does not contain regex.
device-specific: If the scope is restricted to this device and the configuration contains regex.

Also, the configuration icon will have a gold mark in the top right corner. If another configuration for the device was already marked with one of the above four states, then that configuration is now unmarked, and has one of the following values in the Golden column:

previous golden without regex: If the scope is available to other devices and the configuration does not contain regex.
previous golden: If the scope is available to other devices and the configuration contains regex.
previous device-specific without regex: If the scope is restricted to this device and the configuration does not contain regex.
previous device-specific: If the scope is restricted to this device and the configuration contains regex.

To remove a golden configuration

You can remove the 'golden' status from a configuration, unless the associated device is included in a compliance golden definition.

Important: Before starting this task, add the Golden column to the columns displayed in the configurations tab. Due to Linux 'thick client' limitations, this must be done in Windows.

Note: If the configuration is marked Golden and the associated device is included in a compliance golden definition, it will not be possible to undo the Golden status until the device is removed from the compliance golden definition.

Select the Resource Browser in the navigation tree.
Search for the device you want to view.
Click the Configuration tab, then right-click the selected configuration. It will have the status of 'golden' or 'golden without regex' in the Golden column, and the configuration icon will have a gold mark in the top right corner.
Select the Undo Golden option. A window displays the details for the selected configuration.
Click Finish to complete the procedure.

The selected configuration is now unmarked as golden and displays one of the following values: 'previous golden', 'previous golden without regex', 'previous device-specific', or 'previous device-specific without regex' in the Golden column.

Possible values for the Golden state

The following table shows all allowed values for the Golden state. A configuration cannot move from one column to another. States can only change within the same column.

For configurations that have one of the states in the 'Configuration contains regex' column, the following restrictions apply:

- SmartModel-related right-click actions, such as for 'Edit' of configuration, are disabled, both at the configuration and network resource level (if it is the current configuration).
- Showing 'Modelled View' differences is not supported.
- Command Set Application is not supported.
- The 'Re-discover' action is not available.
- The 'Trigger Config Backup' action is not available.

It will still be possible to view the XML Configuration of a device in text format in the Compliance GUI. The '@@@...' mark-up is not supported for use with 'device-specific' or 'previous device-specific' configurations.

Action	Configuration contains regex	Configuration does not contain regex
Initial import	has regex	false
Mark golden	golden	golden without regex
Unmark golden	previous golden	previous golden without regex
Mark device specific	device specific	device specific without regex
Unmark device specific	previous device specific	previous device specific without regex