Network Device Backup

This feature was added in version 6.1.
Features marked with EE badge require Enterprise Edition.

Network device backup provides centralized visibility into configuration backups of network devices managed by NetXMS. Administrators can view backup status, browse configuration history, compare configuration versions, and trigger on-demand backups directly from the management console.

NetXMS uses a pluggable provider interface for device configuration backup. Only one provider can be active at a time. The following providers are available:

Provider Edition Description

Built-in

Enterprise

Native backup engine that uses device drivers to collect configurations via SSH and stores them in the NetXMS database.

Unimus

Enterprise

Integration with Unimus network device backup service.

Oxidized

Community

Integration with Oxidized open-source network device configuration backup tool.

Concepts

Provider Interface

When a backup provider module is loaded, the server registers a DEVBACKUP component and the management console shows a Device Backup section on node overview pages and a Configuration Backup view for registered nodes.

Device Registration

Before a device can be backed up, it must be registered with the backup provider. Registration creates a mapping between the NetXMS node and the corresponding device in the backup system. Once registered, the node displays backup status information and provides access to configuration history.

Devices are registered automatically during configuration poll using the Hook::RegisterForConfigurationBackup NXSL script. The script receives the node object as $node and should return true to register the device or false to skip it. Fresh NetXMS databases ship this hook predefined as:

return $node.isSNMP;

so by default only SNMP-capable devices are registered. Modify the script to change the selection; only if the script is deleted are all eligible nodes registered automatically.

For already-registered devices, the hook is re-evaluated on each configuration poll. If the script returns false, the device is unregistered.

Configuration Change Detection

Each time a backup is retrieved, NetXMS computes a SHA-256 hash of the configuration content. By comparing hashes between consecutive backups, the built-in backup provider detects configuration changes and generates events:

  • SYS_RUNNING_CONFIG_CHANGED — generated when the running configuration changes between backups (parameters: previousHash, newHash)

  • SYS_STARTUP_CONFIG_CHANGED — generated when the startup configuration changes between backups (parameters: previousHash, newHash)

These events can be used in event processing policies to send notifications or create alarms when device configurations change unexpectedly. Only the built-in provider generates these events; the Oxidized and Unimus providers do not, and the hashes shown for their backups are for display only.

Using Device Backup

Viewing Backup Status

Once a device is registered, the node overview page shows a Device Backup section with:

  • Registered — whether the device is registered for backup

  • Last job status — the result of the most recent backup attempt (Successful, Failed, or Unknown)

  • Last job time — when the last backup was attempted

  • Failure reason — if the last backup failed, the reason is displayed

Browsing Configuration History

To view the configuration backup history for a registered device:

  1. Open the node in the management console.

  2. Select the Configuration Backup view.

  3. The backup list shows all available configuration versions with:

    • Timestamp — when the backup was taken

    • Last Check — when the configuration was last retrieved and found unchanged

    • Running Config — size of the running configuration

    • Startup Config — size of the startup configuration (if available)

    • Status — change indicator: R if running config changed, S if startup config changed, R S if both changed, Initial for the first backup

  4. Select a backup to view its content. The view provides three tabs:

    • Running Config — the running configuration text

    • Startup Config — the startup configuration text (if available)

    • Diff — a diff comparing the selected backup with another backup version

Viewing backup content requires the "Read device configuration" object access right on the node. Without it, the view still lists available backups, but instead of the configuration text the message "You do not have permission to view backup content on this node" is displayed, and the export, copy, and restore actions are unavailable.

The following actions are available from the view:

  • Export Running Config / Export Startup Config — save the selected backup’s configuration to a file

  • Copy to Clipboard — copy the displayed configuration text

  • Restore Running Config on Node…​ / Restore Startup Config on Node…​ — apply the configuration from the selected backup to a device. The configuration is merged line by line into the target device’s configuration and saved to its startup configuration. The target can be a different node than the backup source; a warning is shown if the target node uses a different device driver. The restore actions require the "Upload device configuration" object access right on the target node.

Triggering an On-Demand Backup

To trigger an immediate backup for a registered device, open the Configuration Backup view and click the Backup Now button in the view toolbar.

Built-in Backup Provider EE

The built-in backup provider (devbackup.nxm) is a native NetXMS module. It connects directly to network devices using device drivers to retrieve configurations via SSH, and stores them in the NetXMS database.

How It Works

  1. The module runs a background scheduler that checks all registered nodes against their configured backup interval.

  2. When a node is due for backup, the scheduler submits a backup job to the thread pool.

  3. The backup job uses the node’s device driver to retrieve the running and startup configurations via SSH (interactive or command channel).

  4. If the configuration has changed since the previous backup (determined by SHA-256 hash comparison), a new backup record is stored in the database and change events are fired.

  5. If the configuration has not changed, only the last check timestamp is updated on the existing record.

  6. Old backups are automatically cleaned up by the housekeeper based on the configured retention period.

Supported Devices

The built-in provider uses device drivers to collect configurations. The following drivers currently support configuration backup:

Driver Method Notes

Cisco IOS

SSH interactive

Running and startup configs via show running-config / show startup-config

Cisco Nexus

SSH interactive

Running and startup configs

Juniper JunOS

NETCONF (falls back to SSH CLI)

Running config retrieved in native XML format via NETCONF; CLI fallback if NETCONF is not available

MikroTik RouterOS

SSH command or interactive

Running config via /export

Hirschmann Classic

SSH interactive

Running and startup configs via show running-config / show startup-config

Hirschmann HiOS

SSH interactive

Running and startup configs

HPE ProCurve

SSH interactive

Running and startup configs via show running-config / show config

HPE Comware

SSH interactive

Running and startup configs via display current-configuration / display saved-configuration

HPE Aruba switch

SSH interactive

Running config via show running-config

Dell PowerConnect

SSH interactive

Running config via show running-config

Devices must have SSH credentials configured in NetXMS for the driver to connect.

Setting Up Built-in Provider

Add the following to the NetXMS server configuration file (netxmsd.conf):

Module = devbackup.nxm

The module reads its configuration from server configuration variables:

Server Configuration Variable Default Description

DeviceConfigBackup.Interval

86400

Backup interval in seconds (default 24 hours). Can be overridden per node by setting the SysConfig:DeviceConfigBackup.Interval custom attribute.

DeviceConfigBackup.MaxJobs

10

Maximum number of concurrent backup jobs.

DeviceConfigBackup.RetentionDays

90

Number of days to keep backup history. Older backups are deleted by the housekeeper.

These variables are not registered in the server configuration and do not appear in the Server Configuration view; to change the defaults, create the variables manually.

Restart the NetXMS server after changing the configuration. Check the server log for the message:

Network device backup interface is provided by module DEVBACKUP

Unimus Integration EE

Unimus is a commercial network device backup and configuration management service. The NetXMS Unimus integration module (unimus.nxm) connects to a Unimus instance via its REST API, allowing administrators to manage device backup registration and view backup data from within the NetXMS management console.

How It Works

  1. The administrator configures the Unimus module with the Unimus API URL and authentication token.

  2. When a device is registered for backup, NetXMS checks if the device already exists in Unimus by IP address. If found, the existing Unimus device is linked. If not, a new device is created in Unimus.

  3. Unimus handles all device connectivity, configuration collection, and scheduling independently.

  4. When an administrator views backup data in NetXMS, the module retrieves it from the Unimus API on demand.

Setting Up Unimus Integration

Add the following to the NetXMS server configuration file (netxmsd.conf):

Module = unimus.nxm

[UNIMUS]
BaseURL = http://unimus-host:8085
Token = your-api-token
Parameter Required Default Description

BaseURL

No

http://127.0.0.1:8085

Base URL of the Unimus instance.

Token

Yes

Unimus API authentication token.

Restart the NetXMS server after changing the configuration.

Oxidized Integration

Oxidized is an open-source network device configuration backup tool. It connects to network devices via SSH or Telnet, retrieves their configurations, and stores them in a Git repository with full version history.

The NetXMS Oxidized integration module (oxidized.nxm) connects to an Oxidized instance via its REST API. NetXMS acts as an HTTP source for Oxidized, providing the list of devices to back up. This means device registration is managed from NetXMS and automatically synchronized to Oxidized. This module is available in the Community Edition.

How It Works

  1. The administrator configures the Oxidized module in the NetXMS server configuration file with the Oxidized REST API URL and credentials.

  2. On startup, NetXMS loads the module and registers a REST API endpoint (/oxidized/nodes) that Oxidized uses as its HTTP source to retrieve the list of devices to back up.

  3. When the administrator registers a node for backup, NetXMS resolves the Oxidized model name for the node (see Model Resolution).

  4. Oxidized periodically polls the /oxidized/nodes endpoint to get the current list of registered devices, then connects to each device on its configured schedule to retrieve and store configurations.

  5. When an administrator views backup data in NetXMS, the module retrieves it from the Oxidized REST API on demand.

The /oxidized/nodes endpoint returns a JSON array with the following fields for each registered node: name (node ID), ip, model, group, username, and password (from the node’s SSH credentials).

Prerequisites

  • A running Oxidized instance with the REST API enabled (oxidized-web gem)

  • Network connectivity from the NetXMS server to the Oxidized REST API

  • Network connectivity from the Oxidized instance to the NetXMS REST API (for the HTTP source)

  • Network connectivity from Oxidized to the managed network devices

Setting Up Oxidized Integration

Configuring the NetXMS Server

Add the following to the NetXMS server configuration file (netxmsd.conf):

Module = oxidized.nxm

[OXIDIZED]
BaseURL = http://oxidized-host:8888
Login = admin
Password = secret
DefaultModel = ios

See Oxidized Configuration Reference for a full list of configuration parameters.

Restart the NetXMS server after changing the configuration. On startup, the module writes the message Oxidized integration module version <version> initialized at debug level 2, so it is not visible in the log by default. If the Oxidized instance is reachable, the log will show:

Oxidized server responded successfully (N nodes)

Configuring Oxidized to Use NetXMS as Source

Configure Oxidized to use NetXMS as its HTTP source. The /oxidized/nodes endpoint requires authentication. You must create an API token in NetXMS and use it in the Oxidized configuration as a Bearer key. The token must be granted the oxydized scope (note the spelling used by the current implementation).

In the Oxidized configuration file (typically ~/.config/oxidized/config):

source:
  default: http
  http:
    url: https://netxms-server/oxidized/nodes
    headers:
      Authorization: Bearer your-api-token
    map:
      name: name
      ip: ip
      model: model
      group: group
      username: username
      password: password

Replace netxms-server with the hostname or IP address of the NetXMS server and your-api-token with a valid API token.

After updating the Oxidized configuration, restart the Oxidized service.

Oxidized Configuration Reference

The following parameters are available in the [OXIDIZED] section of netxmsd.conf:

Parameter Required Default Description

BaseURL

No

http://127.0.0.1:8888

Base URL of the Oxidized REST API.

Login

No

(empty)

Username for HTTP Basic authentication to the Oxidized API.

Password

No

(empty)

Password for HTTP Basic authentication to the Oxidized API.

DefaultModel

No

(empty)

Default Oxidized model to use when no other resolution tier produces a model (see Model Resolution). If not set and no model can be resolved, device registration will fail.

These are the only parameters accepted in the [OXIDIZED] section. To override the model for an individual device, set the oxidized.model custom attribute on the node (see Model Resolution).

Model Resolution

When a device is registered for backup, NetXMS resolves the Oxidized model name for the node by checking the following tiers in order. The first tier that produces a model wins; all matching is case-insensitive.

  1. oxidized.model custom attribute — if set on the node, its value is used as-is. This is the per-device override for cases where automatic resolution picks the wrong model.

  2. Network device driver name — the name of the network device driver selected for the node is looked up in a built-in driver-to-model table (see below). The GENERIC driver is skipped at this tier.

  3. sysDescr substring match — the node’s SNMP system description is matched against a built-in list of substrings (see below). This distinguishes OS variants that share a driver or vendor, such as Cisco ASA, IOS XR, and NX-OS.

  4. Vendor name — the node’s vendor string is looked up in a built-in vendor-to-model table (see below). This is the fallback for devices using the GENERIC driver.

  5. DefaultModel — the value of the DefaultModel configuration parameter, if set.

If no tier produces a model, device registration fails.

Driver-to-Model Mappings

Network Device Driver Oxidized Model

CISCO-GENERIC, CATALYST-GENERIC, CATALYST-2900XL, CISCO-ESW

ios

CISCO-NEXUS

nxos

CISCO-SB

ciscosmb

CISCO-WLC

aireos

JUNIPER

junos

NETSCREEN

screenos

MIKROTIK

routeros

HUAWEI-SW, OPTIX

vrp

FORTIGATE

fortios

ARUBA-SW

aoscx

PROCURVE, HPSW

procurve

H3C

comware

EXTREME

xos

DELL-PWC

powerconnect

UBNT-AIRMAX

airos

UBNT-EDGESW

edgeswitch

HIRSCHMANN-HIOS, HIRSCHMANN-CLASSIC

hirschmann

DLINK

dlink

TPLINK

tplink

ELTEX

eltex

EDGECORE-ESW

edgecos

TELTONIKA

openwrt

sysDescr Mappings

sysDescr Contains Oxidized Model

Adaptive Security Appliance

asa

IOS-XR, IOS XR

iosxr

NX-OS

nxos

Dell EMC Networking OS10, OS10 Enterprise

os10

Force10, FTOS

ftos

Vendor-to-Model Mappings

Vendor Oxidized Model

Cisco / Cisco Systems Inc.

ios

Juniper Networks

junos

MikroTik

routeros

Huawei

vrp

Fortinet

fortios

HPE Aruba Networking

arubaos

Hewlett Packard Enterprise

procurve

Extreme Networks

xos

D-Link

dlink

TP-Link

tplink

Dell

powerconnect

Ubiquiti

edgeos

Ubiquiti, Inc.

airos

Eltex Ltd.

eltex

Moxa

moxa

Hirschmann

hirschmann

Teltonika

openwrt

Edgecore

edgecos

Debugging

To enable detailed logging for backup providers, set the appropriate debug tag in netxmsd.conf or via the server console:

# Built-in backup provider
DebugTag = devbackup:7

# Unimus integration
DebugTag = unimus:7

# Oxidized integration
DebugTag = oxidized:7