router-backup/docs/DETAILS.md

IPng Networks Router Backup - Detailed Documentation

Overview

IPng Networks Router Backup is a SSH-based network device configuration backup tool written in Go. It connects to multiple network devices defined in YAML configuration files, executes commands via SSH, and saves the output to local files.

Key Features

• Multi-device support: Backup multiple routers in a single run
• Device type templates: Define command sets per device type
• Configuration merging: Load and merge multiple YAML files using mergo
• SSH config integration: Uses ~/.ssh/config for legacy device compatibility
• Flexible authentication: SSH agent, key files, or password authentication
• Selective execution: Target specific devices with --host flags
• IPv6 support: Automatic IPv6 address detection and proper formatting

Configuration File Format

The tool uses YAML configuration files with two main sections: types and devices. Multiple YAML files can be loaded and merged automatically.

Complete Example

Device types (00-device-types.yaml):

types:
  srlinux:
    commands:
      - show version
      - show platform linecard
      - info flat from running

  eos:
    commands:
      - show version
      - show inventory
      - show running-config

  routeros:
    commands:
      - system package print detail without-paging
      - / export terse
    exclude:
      - "^# ....-..-.. ..:..:.. by RouterOS"    # Filter timestamp headers
      - "^# .../../.... ..:..:.. by RouterOS"   # Alternative date format

Main configuration (config.yaml):

devices:
  asw100:
    user: admin
    type: srlinux

  core-01:
    user: admin
    type: eos
    address: 192.168.1.100    # Override connection address

  ipv6-router:
    user: netops
    address: 2001:678:d78:500::    # IPv6 address support

  edge-router:
    user: operator
    commands:                      # Direct commands (no type)
      - show version
      - show ip route summary

Configuration Fields

Types Section

• <type-name>: Device type name (e.g., srlinux, eos)
  • commands: Array of CLI commands to execute
  • exclude (optional): Array of regex patterns to filter out unwanted lines from output

Devices Section

• <hostname>: Device hostname (used for SSH config lookup and output filename)
  • user (required): SSH username
  • type (optional): Reference to a type definition
  • commands (optional): Direct command list (overrides type commands)
  • address (optional): IP address or hostname to connect to (overrides hostname)

Configuration Merging

Files are merged automatically using mergo. Later files override earlier ones:

# Load multiple files - later files override earlier ones
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml --yaml overrides.yaml

# Load files using glob patterns
ipng-router-backup --yaml "*.yaml"
ipng-router-backup --yaml "config/*.yaml"

Output Filtering

The tool supports filtering unwanted lines from command output using regular expressions in the exclude field of device types.

How Exclude Patterns Work

• Regex matching: Each line of command output is tested against all exclude patterns
• Line removal: Lines matching any pattern are completely removed from the output file
• Per-device type: Exclude patterns are defined at the device type level and apply to all devices of that type

Common Use Cases

types:
  routeros:
    commands:
      - / export terse
    exclude:
      - "^# ....-..-.. ..:..:.. by RouterOS"    # Remove timestamp headers
      - "^# .../../.... ..:..:.. by RouterOS"   # Alternative date format

  cisco-ios:
    commands:
      - show running-config
    exclude:
      - "^Building configuration"               # Remove config build messages
      - "^Current configuration"                # Remove current config headers
      - "^!"                                   # Remove comment lines

  debug-device:
    commands:
      - show logs
    exclude:
      - "^DEBUG:"                             # Filter debug messages
      - "^TRACE:"                             # Filter trace messages

Command Line Usage

Required Flags

• --yaml: Path to YAML configuration file(s) or glob patterns (can be repeated)

Optional Flags

• --output-dir: Output directory (default: /tmp)
• --host: Specific hostname(s) or glob patterns to process (can be repeated)
• --password: SSH password
• --key-file: SSH private key file path
• --port: SSH port (default: 22)
• --parallel: Maximum number of devices to process in parallel (default: 10)

Examples

# Basic usage with glob patterns
ipng-router-backup --yaml "*.yaml"

# Multiple files
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml

# Devices matching patterns
ipng-router-backup --yaml config.yaml --host "asw*" --host "*switch*"

# Custom output directory
ipng-router-backup --yaml config.yaml --output-dir /backup/network

# With password authentication
ipng-router-backup --yaml config.yaml --password mypassword

# Process more devices in parallel
ipng-router-backup --yaml config.yaml --parallel 20

SSH Authentication

The tool supports multiple authentication methods in priority order:

1. SSH Agent (Recommended)

Automatically used when SSH_AUTH_SOCK is set:

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
ipng-router-backup --yaml config.yaml

2. SSH Key File

# Explicit key file
ipng-router-backup --yaml config.yaml --key-file ~/.ssh/network_key

# Automatic detection from default locations:
# ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
ipng-router-backup --yaml config.yaml

3. Password Authentication

ipng-router-backup --yaml config.yaml --password mypassword

SSH Configuration Integration

The tool automatically reads ~/.ssh/config for each host:

# ~/.ssh/config
Host old-switch*
  User admin
  Port 2222
  IdentityFile ~/.ssh/legacy_key
  KexAlgorithms +diffie-hellman-group1-sha1
  HostKeyAlgorithms +ssh-rsa

Host modern-router*
  User netops
  IdentityFile ~/.ssh/modern_key

Supported options: Hostname, Port, User, IdentityFile, KexAlgorithms, MACs, HostKeyAlgorithms

Output Format

File Naming

• Output files are named after the device hostname
• Device asw100 → File asw100

File Content

Each file contains all command outputs with headers:

## COMMAND: show version
Hostname             : asw100
Software Version     : v25.3.2
------------------------------------------------------------------------
## COMMAND: show platform linecard
+-------------+----+-------------+-------------------+
| Module Type | ID | Admin State | Operational State |
+=============+====+=============+===================+
| linecard    | 1  | N/A         | up                |
+-------------+----+-------------+-------------------+

Error Handling

Common Issues

• Connection failures: Check SSH connectivity and authentication
• Configuration errors: Validate YAML syntax and required fields
• Permission issues: Verify SSH key permissions (600) and output directory access

Exit Codes

• 0: Success (all devices processed successfully)
• 1: Configuration error, authentication failure, or connection issues
• 10: Some devices failed
• 11: All devices failed