Config Snapshots

Overview

Config snapshots capture the running configuration of network devices at a specific point in time. Unlike traditional backups that simply store files, NetStacks snapshots are structured records stored in PostgreSQL with hash-based change detection, device metadata, and collection status tracking.

Snapshots serve multiple purposes:

• Configuration backup — Preserve known-good configurations for disaster recovery and rollback reference.
• Change detection — Compare consecutive snapshots to identify what changed, when, and on which devices.
• Compliance auditing — Prove that device configurations match organizational standards at specific dates.
• Fleet-wide captures — Snapshot collections capture configs from multiple devices in a single operation, useful for pre/post maintenance window verification.

How It Works

Config Collection Process

When NetStacks captures a device configuration, it follows this process:

1. Retrieves the device's assigned credential from the encrypted vault and decrypts it using the master key.
2. Establishes an SSH connection to the device using the credential and the device type's platform driver.
3. Sends the platform-specific paging disable command (e.g., terminal length 0 for Cisco IOS) followed by the config capture command (e.g., show running-config).
4. Captures the full command output, strips prompt lines and command echoes, and stores the clean configuration text.
5. Computes a SHA-256 hash of the config text for change detection.
6. Records the backup with metadata: timestamp, line count, byte size, collection method, credential used, and status.

Hash-Based Change Detection

Every config backup stores a config_hash (SHA-256) of the configuration text. When you view a device's backup history, NetStacks compares consecutive hashes to identify when the configuration actually changed. Identical hashes mean the config is unchanged, regardless of when the backup was captured. This makes it easy to spot the exact moment a change occurred without reading through thousands of config lines.

Snapshot Collections

A snapshot collection targets multiple devices at once. When you create a snapshot, you specify:

• Name — A descriptive label (e.g., "Pre-maintenance 2026-03-10" or "Weekly production backup").
• Device filter — Which devices to include, filtered by site, device type, or tags.
• Snapshot type — manual for on-demand captures or scheduled for automated captures triggered by tasks.

Collection runs concurrently using a configurable concurrency limit (semaphore) to avoid overwhelming the network. Each device collection runs independently — if one device fails, others continue. The snapshot tracks total, successful, and failed device counts.

Credential Resolution

When collecting configs, NetStacks resolves credentials in priority order:

1. Per-request credential override (specified in the collect API call).
2. Device default credential (default_credential_id on the device record).
3. Global collection settings default credential.

If no credential is found at any level, the device backup is marked as failed with "No credential configured".

Step-by-Step Guide

Take a Manual Snapshot of a Single Device

1. Navigate to Devices and select the target device.
2. On the device detail page, click Actions → Capture Config.
3. Choose the configuration type (running or startup) and optionally add a description.
4. Click Capture. NetStacks connects to the device, retrieves the configuration, and stores it as a backup.
5. The backup appears in the device's Backups tab with the capture timestamp, size, line count, and config hash.

Create a Snapshot Collection Across Multiple Devices

1. Navigate to Snapshots in the Admin UI.
2. Click Create Snapshot.
3. Enter a name (e.g., "Pre-maintenance window March 2026").
4. Configure device filters to select the target devices — for example, all devices at site dc-east or all devices with tag production.
5. Click Create to create the snapshot record.
6. Click Collect to trigger config collection. NetStacks connects to each matching device concurrently and captures their configs.
7. Monitor the snapshot status as it progresses from pending to running to completed. The summary shows successful and failed device counts.

Schedule Automatic Snapshots

1. Navigate to Automation → Scheduled Tasks.
2. Create a new task of type Config Backup.
3. Set the schedule using cron syntax (e.g., 0 2 * * * for daily at 2:00 AM).
4. Configure the target devices by tag (e.g., all devices tagged production).
5. Click Save. The task creates a new snapshot and triggers collection at the scheduled time.

View and Browse Snapshot History

1. Navigate to a device's detail page and click the Backups tab.
2. Browse the backup history sorted by date. Each entry shows the timestamp, size, line count, and config hash.
3. Click a backup to view the full configuration text with syntax highlighting.
4. Identical consecutive hashes indicate the config was unchanged between captures.

Code Examples

Create a Snapshot via API

curl -X POST http://localhost:3000/api/devices/snapshots \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pre-maintenance 2026-03-10",
    "description": "Capture all DC East configs before OSPF migration",
    "snapshot_type": "manual",
    "device_filter": {
      "site": "dc-east",
      "device_type": "cisco_ios"
    }
  }'

Trigger Config Collection

# Trigger collection for a snapshot (runs in background)
curl -X POST http://localhost:3000/api/devices/snapshots/${SNAPSHOT_ID}/collect \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "credential_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timeout_seconds": 60
  }'

# Response:
# {
#   "message": "Config collection started",
#   "snapshot_id": "...",
#   "devices_queued": 24
# }

View Snapshot Backups

# List all backups captured during a snapshot
curl -s http://localhost:3000/api/devices/snapshots/${SNAPSHOT_ID}/backups \
  -H "Authorization: Bearer ${TOKEN}" | jq '.backups[] | {
    device_name,
    size_bytes,
    line_count,
    config_hash,
    status,
    backed_up_at
  }'

Example Captured Config (Cisco IOS)

! Last configuration change at 14:32:07 UTC Tue Mar 10 2026
version 17.9
service timestamps debug datetime msec
service timestamps log datetime msec
service password-encryption
!
hostname core-rtr-01
!
boot-start-marker
boot-end-marker
!
aaa new-model
aaa authentication login default local
aaa authorization exec default local
!
ip domain name dc-east.company.com
ip name-server 10.0.0.53
ip name-server 10.0.0.54
!
interface GigabitEthernet0/0/0
 description Uplink to dist-sw-01
 ip address 10.1.0.1 255.255.255.252
 ip ospf 1 area 0
 no shutdown
!
interface GigabitEthernet0/0/1
 description Uplink to dist-sw-02
 ip address 10.1.0.5 255.255.255.252
 ip ospf 1 area 0
 no shutdown
!
router ospf 1
 router-id 10.255.0.1
 network 10.1.0.0 0.0.0.3 area 0
 network 10.1.0.4 0.0.0.3 area 0
 passive-interface default
 no passive-interface GigabitEthernet0/0/0
 no passive-interface GigabitEthernet0/0/1
!
ip access-list extended MGMT-ACCESS
 permit tcp 10.0.0.0 0.0.0.255 any eq 22
 permit tcp 10.0.0.0 0.0.0.255 any eq 443
 deny   ip any any log
!
line con 0
 logging synchronous
line vty 0 4
 access-class MGMT-ACCESS in
 transport input ssh
!
end

List Device Backup History

# Get all backups for a specific device
curl -s "http://localhost:3000/api/devices/${DEVICE_ID}/backups?limit=10" \
  -H "Authorization: Bearer ${TOKEN}" | jq '.backups[] | {
    id,
    backed_up_at,
    size_bytes,
    line_count,
    config_hash,
    backup_method,
    status
  }'

# Example output:
# {
#   "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
#   "backed_up_at": "2026-03-10T14:32:15Z",
#   "size_bytes": 12847,
#   "line_count": 342,
#   "config_hash": "a7f3b2c1d4e5f6...",
#   "backup_method": "scheduled",
#   "status": "success"
# }

Questions & Answers

Q: How do I take a config snapshot?

A: For a single device, navigate to the device detail page and click Actions → Capture Config. For multiple devices, create a snapshot under Snapshots, configure device filters, and click Collect. You can also trigger collection via the API with POST /api/devices/snapshots/{id}/collect.

Q: How does change detection work?

A: Every config backup stores a SHA-256 hash of the configuration text. When browsing backup history, NetStacks compares consecutive hashes. If the hash changed, the configuration was modified. If the hash is identical, the config is unchanged regardless of when the backup was taken. This lets you identify the exact capture where a change first appeared without reading through the full config.

Q: How often should I take snapshots?

A: Best practice is daily backups of production devices using scheduled tasks, with additional manual snapshots before and after maintenance windows. High-change environments may benefit from more frequent captures (every 4-6 hours). The hash-based deduplication means that unchanged configs add minimal storage overhead.

Q: What happens if a device is unreachable during a snapshot collection?

A: The snapshot collection continues for all other devices. Unreachable devices are recorded as failed with an error message (e.g., "SSH connection timeout"). The snapshot summary shows the total, successful, and failed device counts. You can retry the collection later or investigate the failed devices individually.

Q: How long are snapshots retained?

A: Config backups are retained indefinitely by default. There is no automatic purge policy. You can delete individual backups or entire snapshots through the UI or API when they are no longer needed. For large deployments, monitor PostgreSQL disk usage and implement a retention policy based on your compliance requirements.

Q: Can I export snapshots?

A: You can view and copy the full configuration text from any backup through the UI. The API provides the raw config text via GET /api/devices/{deviceId}/backups/{backupId}. You can script exports using the API to download configs and save them to a file system or version control repository.

Troubleshooting

Snapshot capture fails with SSH timeout

The default SSH timeout for config collection is 30 seconds. Large configurations (e.g., firewalls with thousands of ACL rules) may exceed this. Increase the timeout using the timeout_seconds parameter when triggering collection via the API, or adjust the global collection settings.

# Increase timeout to 120 seconds for large configs
curl -X POST http://localhost:3000/api/devices/snapshots/${SNAPSHOT_ID}/collect \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"timeout_seconds": 120}'

Backup fails with "privilege level insufficient"

Some devices require enable mode to run show running-config. Ensure the credential assigned to the device includes an enable password, or configure the device to allow show running-config at privilege level 1 with:

! On Cisco IOS - allow show run at privilege 1
privilege exec level 1 show running-config

Config capture returns wrong device type output

If the captured config looks malformed or contains unexpected output, the device type is probably wrong. The platform driver sends the wrong config capture command. Navigate to the device, verify the device type matches the actual platform, and recapture.

"No credential configured" error

The device has no default_credential_id set, and no credential was provided in the collection request. Either assign a credential to the device in the device settings, or pass a credential_id in the collect API call.

Related Features

Config snapshots integrate with comparison, automation, and device management features:

• Config Diff & History — Compare snapshots side-by-side to identify configuration changes
• Adding Devices — Devices must exist in the inventory before snapshots can be captured
• Scheduled Tasks — Automate periodic config captures with cron schedules
• Device Types — Platform drivers determine which commands are used for config capture