Hierarchical Configuration (hier-config)

3.6.0 · active · verified Thu Apr 16

Hierarchical Configuration, or hier-config, is a Python library designed to query and compare network device configurations. It parses configuration text into a hierarchical tree to perform deterministic, line-level diffs that respect vendor syntax rules. This allows it to generate precise remediation commands to bring a device into compliance with an intended configuration. The library is actively maintained, with its current version being 3.6.0, and new releases occurring regularly.

Common errors

```
NameError: name 'Host' is not defined
```
cause Attempting to use the `Host` class from hier-config v2.x in a v3.x environment. The `Host` class was removed in v3.0.0.

fix Replace `from hier_config import Host` with `from hier_config import get_hconfig, Platform` and create configuration objects using `get_hconfig(Platform.<YOUR_PLATFORM>, config_text)`.
```
ValueError: 'ios_xr' is not a valid Platform
```
cause When creating an `HConfig` object, the platform argument expects a `Platform` enum member (e.g., `Platform.CISCO_IOS`), not a string.

fix Import `Platform` from `hier_config` and use its members, e.g., `get_hconfig(Platform.CISCO_IOSXR, config_text)`. Available platforms can be listed via `hier-config-cli list-platforms`.
```
FileNotFoundError: [Errno 2] No such file or directory: './my_config.conf'
```
cause The `read_text_from_file` utility function cannot find the specified configuration file at the given path.

fix Verify that the file path provided to `read_text_from_file` is correct and that the file exists at that location relative to your script, or provide an absolute path.

Warnings

breaking Version 3.x introduced significant breaking changes from version 2.x, primarily replacing the `Host` object with `get_hconfig` and `Platform` enums for creating configuration objects, and migrating from dictionary-based options to Pydantic driver models.
Fix: Migrate your code to use `get_hconfig(Platform.<YOUR_PLATFORM>, config_text)` instead of `Host(hostname=..., os=...)`. Review driver documentation for how to handle OS-specific options.
gotcha Juniper JunOS support is currently experimental and has not been extensively tested. It should be used with caution in production environments.
Fix: Exercise caution and thorough testing when using `Platform.JUNIPER_JUNOS`. Refer to the official documentation for updates on its stability.
gotcha Prior to v3.5.1, parsing IOS-XR configurations with indented '!' section separators could lead to a `DuplicateChildError`.
Fix: Upgrade to hier-config v3.5.1 or newer to resolve the `DuplicateChildError` when parsing IOS-XR configs with indented '!' section separators.
gotcha In versions prior to 3.4.1, BGP neighbor descriptions could be dropped in the future config output.
Fix: Upgrade to hier-config v3.4.1 or newer to ensure BGP neighbor descriptions are correctly preserved in future configuration predictions.

Install

pip install hier-config Install with pip

Imports

WorkflowRemediation

from hier_config import WorkflowRemediation

get_hconfig
```
from hier_config import get_hconfig
```
Platform
```
from hier_config import Platform
```

read_text_from_file

from hier_config.utils import read_text_from_file

Host
wrong:
```
from hier_config import Host
```
correct:
```
from hier_config import Host # For hier-config v2.x
```
The 'Host' class was used in hier-config v2.x. In v3.x, it has been replaced by 'get_hconfig' and 'Platform' for creating configuration objects.

Quickstart

This quickstart demonstrates how to load existing and intended device configurations, create hierarchical configuration objects, and then use `WorkflowRemediation` to generate the commands needed to bring the running configuration into compliance with the intended state. It simulates config files and cleans them up afterwards.

from hier_config import WorkflowRemediation, get_hconfig, Platform
from hier_config.utils import read_text_from_file
import os

# Create dummy config files for demonstration
running_config_content = '''
hostname DEVICE-RTR-01
!
interface GigabitEthernet0/1
 description Uplink to CORE
 ip address 10.0.0.1 255.255.255.0
 no shutdown
!
router bgp 65000
 neighbor 192.168.1.1 remote-as 65001
'''

intended_config_content = '''
hostname DEVICE-RTR-01-UPDATED
!
interface GigabitEthernet0/1
 description Uplink to CORE - Primary
 ip address 10.0.0.1 255.255.255.0
 no shutdown
!
router bgp 65000
 neighbor 192.168.1.1 remote-as 65001
 address-family ipv4 unicast
  neighbor 192.168.1.1 activate
'''

with open('running_config.conf', 'w') as f:
    f.write(running_config_content)

with open('intended_config.conf', 'w') as f:
    f.write(intended_config_content)

# Step 1: Load configurations from files
running_config_text = read_text_from_file('running_config.conf')
intended_config_text = read_text_from_file('intended_config.conf')

# Step 2: Create HConfig objects, specifying the device platform
running_hconfig = get_hconfig(Platform.CISCO_IOS, running_config_text)
intended_hconfig = get_hconfig(Platform.CISCO_IOS, intended_config_text)

# Step 3: Initialize WorkflowRemediation to compare and generate remediation
workflow = WorkflowRemediation(running_hconfig, intended_hconfig)

# Step 4: Print the remediation configuration
print('Remediation Configuration:')
for line in workflow.remediation_config:
    print(line.text)

# Clean up dummy files
os.remove('running_config.conf')
os.remove('intended_config.conf')

view raw JSON →