README

LibreNMS package for viewing historical Oxidized configuration history directly from local Oxidized Git repositories.

This package adds a Historical Config device tab in LibreNMS. It is intended for environments where Oxidized stores configuration history in Git repositories and LibreNMS should be able to view older saved configurations without modifying LibreNMS core or Oxidized itself.

Status

Alpha release.

The current release line uses a local Git history provider and a LibreNMS-native configuration history workflow.

The package reads Oxidized Git repositories directly from PHP. No separate companion service, Ruby daemon, HTTP listener, or bearer token is required.

What it does

Adds a LibreNMS device tab named Historical Config
Uses a LibreNMS-style configuration history interface
Reads historical config versions directly from local Oxidized Git repositories
Shows available config versions for the selected device
Loads saved configurations without reloading the page
Uses LibreNMS configuration syntax highlighting
Shows structured line-by-line diffs between saved versions
Supports copying and downloading saved configurations
Can request an immediate backup through the existing LibreNMS Oxidized integration
Automatically refreshes the backup list after a requested backup completes
Distinguishes between a new Git revision and a successful backup with no new revision
Shows backend status in the normal view
Restricts detailed backend diagnostics to LibreNMS administrators
Uses LibreNMS Oxidized group mapping where available
Can discover the Oxidized group from local Git history when mapping is missing
Does not modify LibreNMS core
Does not require modifications to Oxidized

Requirements

LibreNMS with Composer package support
PHP 8.2 or newer
Git available on the LibreNMS server
Oxidized configuration history stored in Git repositories
The LibreNMS user must be able to read the Oxidized Git repository path

Configuration

The package reads configuration from config/oxidized-history.php.

Default local Git storage root:

/opt/librenms/.config/oxidized

With the default layout, the package expects one Git repository per Oxidized group, for example:

/opt/librenms/.config/oxidized/cisco.git
/opt/librenms/.config/oxidized/dell.git
/opt/librenms/.config/oxidized/paloalto.git

The package resolves the Oxidized group for a device in this order:

LibreNMS oxidized.maps.group
Local Git history discovery
Package fallback map from group_os_map
LibreNMS or package default_group

Local Git history discovery means the package can scan readable local Oxidized Git repositories and use the repository that actually contains history for the device node. This helps with devices that are no longer present in the active Oxidized source list but still have saved Git history.

group_os_map is only a fallback. Prefer defining OS-to-group mapping in LibreNMS oxidized.maps.group when possible.

Optional environment overrides:

OXIDIZED_HISTORY_GIT_STORAGE_ROOT=/opt/librenms/.config/oxidized
OXIDIZED_HISTORY_GIT_REPO_MODE=group_repos
OXIDIZED_HISTORY_MAX_VERSIONS=200
OXIDIZED_HISTORY_MAX_CONFIG_BYTES=2000000

OXIDIZED_HISTORY_MAX_CONFIG_BYTES limits the size of stored configurations that the plugin will load. The same limit is checked before generating diffs, preventing oversized configuration blobs from being loaded or diffed.

Example LibreNMS Oxidized group mapping:

ios   -> cisco
iosxe -> cisco
panos -> paloalto

Example node lookup:

LibreNMS device: 192.0.2.10
Resolved group: cisco
Git node path:  cisco/192.0.2.10
Repository:     /opt/librenms/.config/oxidized/cisco.git

Installation

This plugin is installed as a Composer package.

Manual copy-based installation is not the recommended installation method.

Install from Packagist

Recommended installation method:

cd /opt/librenms

sudo -u librenms ./lnms plugin:add wizballesy/librenms-oxidized-history v0.1.0-alpha.9
sudo -u librenms php artisan optimize
sudo -u librenms php artisan config:clear

Replace v0.1.0-alpha.9 with the version you want to install.

After installation, open a LibreNMS device and select the Historical Config tab.

Updating

To update to a specific release:

cd /opt/librenms

sudo -u librenms ./lnms plugin:add wizballesy/librenms-oxidized-history v0.1.0-alpha.9
sudo -u librenms php artisan optimize
sudo -u librenms php artisan config:clear

Replace v0.1.0-alpha.9 with the version you want to install.

Permissions and security

Viewing configuration history follows LibreNMS configuration-access permissions.

Requesting an immediate Oxidized backup additionally requires the LibreNMS oxidized.refresh permission.

Detailed backend diagnostics, including local Git storage information and detected repository names, are restricted to LibreNMS administrators.

Security recommendations:

Keep Oxidized Git repositories readable only by trusted local users.
Do not expose Oxidized Git repositories through the web server.
Do not commit real device configuration data, secrets, SNMP communities, private keys, or organization-specific configuration data.
Use normal filesystem permissions to control which local users can read historical configuration backups.

LibreNMS validate note

Installing LibreNMS plugin packages modifies:

composer.json
composer.lock

LibreNMS validate may warn that these files are locally modified after installing or updating third-party plugin packages. This is expected because the plugin is installed as a Composer dependency inside the LibreNMS application directory.

Do not run ./scripts/github-remove unless you intentionally want to remove local Composer changes.

Troubleshooting

Check which backend the plugin is using:

cd /opt/librenms

sudo -u librenms php artisan tinker --execute='
$contract = \WizballEsy\LibreNmsOxidizedHistory\Contracts\HistoryProvider::class;
$provider = app($contract);

echo "provider=" . get_class($provider) . PHP_EOL;
'

Check that the LibreNMS user can read the Oxidized Git repositories:

sudo -u librenms ls -ld /opt/librenms/.config/oxidized
sudo -u librenms find /opt/librenms/.config/oxidized -maxdepth 1 -type d -name "*.git" -print

Check one repository manually:

sudo -u librenms git --git-dir=/opt/librenms/.config/oxidized/cisco.git log -1

License

GPL-3.0-or-later

wizballesy / librenms-oxidized-history

Maintainers

Package info

Statistics

Security