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

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

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

Command Line Usage

Required Flags

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

Optional Flags

• --output-dir: Output directory (default: /tmp)
• --host: Specific hostname(s) to process (can be repeated)
• --password: SSH password
• --key-file: SSH private key file path
• --port: SSH port (default: 22)

Examples

# Basic usage
ipng-router-backup --yaml config.yaml

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

# Specific devices only
ipng-router-backup --yaml config.yaml --host asw100 --host core-01

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

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

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