- 31 Jul 2024
-
DarkLight
-
PDF
Golden Configuration (CLI)
- Updated on 31 Jul 2024
-
DarkLight
-
PDF
CLI Golden Configurations evaluate whether the running configuration for a device matches its node's baseline configuration. In this guide, you will learn how to:
- Create a baseline configuration.
- Add devices to a Golden Configuration node.
- Run compliance checks against those devices.
- Use compliance reports to take corrective action against any detected compliance violations.
How CLI Golden Configurations Work
Every node in a CLI Golden Configuration has an associated baseline configuration, which consists of:
- Lines of text that mimic the syntax used when configuring a device natively.
- Rules that determine how those lines are interpreted (e.g., whether the line should be present or absent from the device's running configuration).
Once a device has been added to a node, you can run compliance checks against it. The device's running configuration is compared against the node's baseline configuration, and any discrepancies are noted in the resultant compliance report.
Configuration Tab
Before devices can be managed on the current node, a baseline configuration for them to be compared against must be defined via the Configuration tab. Here, you can:
- Write configuration lines via text editor.
- Set the rules that are applied to each line.
- Define variables for use in the configuration.
Figure 1: Configuration Tab
Adding Configuration Lines
To begin writing a configuration, start typing in the text editor as if you were issuing commands on a device's native command-line interface (CLI). Alternatively, you can paste an existing configuration into the text editor from another source, or import it from an available device.
Importing a Device Configuration
To import a configuration from an available device into your Golden Configuration:
- Click the Import (
) button located on the text editor toolbar. The Import Device Configuration modal will appear.
- Find the device that you would like to import a configuration from and click the + button located next to it. The device's configuration will be appended to the bottom of the text editor.
Applying Rules to Configuration Lines
Configuration line behavior is determined by two rules, both assigned on a line-by-line basis. They are:
- Evaluation mode
- Severity type
Evaluation Mode
Evaluation mode determines how the presence or absence of a line from a device's running configuration is interpreted by compliance checks.
Mode | Delimiter | Description |
---|---|---|
Required | The default evaluation mode. The line must exist in the device's running configuration. | |
Disallowed | {d/} |
The line must not exist in the device's running configuration. |
Ignored | {i/} |
The line is to be ignored during compliance checks. |
To change a line's evaluation mode, prepend the relevant delimiter to the line, or:
- Hover over the Evaluation (
) icon located on the text editor toolbar. A menu will appear.
- Select the desired evaluation mode from the menu.
Severity Type
Each line violation is assigned a severity type that reflects a weight value used when calculating a device's configuration grade. In descending order of severity, they are:
- Warning (default)
- Error (delimited by
<e/>
) - Info (delimited by
<i/>
)
These values are useful for approximating the potential impact a line may have on a device's performance if it deviates from the baseline configuration. A line that defines the description field for an interface may be assigned Info, while a line that sets that interface's management IP address may be assigned Warning.
The steps to change a line's severity type are similar to those used to change its evaluation mode -- hover over the Severity (ⓘ) icon on the toolbar.
Figure 2: Adding and Editing Configuration Lines
Variable and Regular Expression Support
You can add more flexibility to your configuration by defining variables for values that may be dynamic (hostnames, interface numbers, etc). For example, you may wish to allow your configuration to be updated by other sources, such as workflows. Or maybe you'd like to define an IP address used throughout the configuration as a variable so that only one update needs to be made if that address changes in the future. To do this:
-
Click the Show Variables (X) button located at the upper-right corner of the text editor. The text editor will split vertically, with the variable editor being displayed on the right.
-
Using the variable editor, define your variables in JSON format. For example, to define the variable
hostname
with a value of"Itential"
:{ "hostname": "Itential" }
-
Click the Save button located at the upper-right corner of the variable editor.
Calling a Variable
To call a variable in your configuration, enclose its name in the {{ }}
delimiters:
hostname {{hostname}}
Using Regular Expressions
Configurations also support regular expressions. To use one, enclose it in the {/ /}
delimiters:
hostname {/[A-Za-z]/}
Figure 3: Defining Golden Configuration Variables
Devices & Groups Tab
The Devices & Groups tab contains all actions related to managing devices and device groups associated with the current node. From this tab, you can:
- Add devices or groups to the node.
- Run compliance checks against devices and groups.
- Perform basic remediation based on the results of these compliance checks.
Devices and groups are each managed under their own respective subtab. Click the subtabs to switch between them.
Figure 4: Devices & Device Groups Tab
Prior to IAP version 2023.1, the Devices & Groups tab was known simply as the Devices tab. It did not operate on device groups.
Adding Devices & Device Groups
To evaluate whether a device is compliant with your baseline configuration, you must first add it to the node:
- Click the Add Devices or Add Device Groups button located underneath the tab headers. The Add Devices or Add Device Groups modal will open, respectively.
- Select which items you would like to add to the node.
- Click the Add button located at the bottom of the modal. The modal will close and any selected devices or groups will be added to the node.
All devices and groups associated with the node are displayed in a table view on their respective subtab.
If your Golden Configuration uses a custom parser (OS Type) that employs operating system (OS) restrictions, you will only be able to add devices supported by that parser to the Golden Configuration.
Compliance
Once you have added a device or group to the node, you can run compliance checks against it:
- Click the menu (⋮) button of the device or group. A menu of actions that can be taken will appear.
- Select Run Compliance from the menu.
After the check is complete, you can view a report that details any detected compliance violations. The steps taken to view the report are similar between devices and groups, but there are slight differences.
To view a compliance report for a device:
- Click the menu (⋮) button of the device. A menu of actions that can be taken will appear.
- Select View Compliance from the menu. All available compliance reports for the device will be displayed.
- Select the compliance report that you would like to view.
To view a compliance report associated with a device group, click the menu (⋮) button of the group and select the Review Group option. A list of devices will be displayed -- from here, follow the instructions given above for viewing device compliance reports.
Figure 5: Compliance Actions
Performing Remediation
Compliance reports list any violations detected in a device's running configuration beneath the Configuration Errors header. To view more details about any item on the list, including potential remediation options, click its drop-down arrow. To apply one of the suggested remediation options to the device:
- Select the option via its radio button. An additional, context-sensitive button will appear to confirm the suggested remediation.
- Click the confirmation button. A check mark will appear to denote that the violation has been marked for remediation.
- Click the Apply button located at the bottom of the compliance report.
You can mark multiple violations for remediation before applying your changes.
By default, a backup of the device's running configuration will be made before any changes are applied; this behavior can be toggled via the Take backup before remediation switch.
Figure 6: Compliance Violations & Remediation Options
Define Severity Weight and Grade Benchmark Values
The grade a device's running configuration receives (Pass, Review, or Fail) in a compliance report can be influenced by changing:
- The default weight value assigned to each line severity type.
- The default benchmark value assigned to each grade.
The following sections detail how the grade of a running configuration is calculated and how you can change the values used in the calculation.
Calculating the Grade of a Device Configuration
When a compliance report is run against a running configuration, the following formula is used:
Score = (totalNumPassLines / ((numOfErrorLines * errorWeightValue) + (numOfWarnLines * warnWeightValue) + (numOfInfoLines * infoWeightValue) + totalNumPassLines)) * 100
The following severity type weight values are used in this formula by default:
- Error: 2
- Warning: 1
- Info: 0.5
The score returned by this formula is compared to the following grade benchmark values by default to assign a grade to the running configuration:
- Pass: 90
- Review: 80
- Fail: 0
If a configuration that is ten lines long has one non-compliant line assigned the error severity type, it would be scored 81.82:
81.82 = ((9 / ((1 * 2) + (0 * 1) + (0 * 0.5) + 9)) * 100)
As such, the configuration would be given a grade of Review.
Using a Workflow to Define Custom Values
You can use a workflow to run a compliance report with custom severity type weight and grade benchmark values:
- Add the gradeComplianceReport task to the workflow.
- Locate the options variable in the Task Configuration modal.
- Define the custom values in JSON object format.
To halve the default severity type weight and grade benchmark values (excluding the Fail grade), provide the following to the options variable:
{
"error": 1,
"warning": 0.5,
"info": 0.25,
"pass": 45,
"review": 40,
"fail": 0
}