ipng/router-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
949799acdcad1f056ca568cf5e0525029c471a28
router-backup/docs/DETAILS.md
Pim van Pelt 372d7125a1 Update path to etc/
2025-07-06 17:55:11 +02:00

14 KiB
Raw Blame History

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 a YAML configuration file, 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 automatically using mergo
  • SSH config integration: Automatically uses ~/.ssh/config for legacy device compatibility
  • Flexible authentication: SSH agent, key files, or password authentication
  • Selective execution: Target specific devices with --host flags
  • Automatic file organization: Output files named by hostname
  • Command identification: Each command output prefixed with command name
  • Version synchronization: Automatic version sync between package and binary

Configuration File Format

The tool uses YAML configuration files with two main sections: types and devices. Multiple YAML files can be loaded simultaneously using the --yaml flag, and their contents are automatically merged using the mergo library. Later files override earlier ones, allowing for flexible configuration organization.

Complete Example

Main configuration (config.yaml):

devices:
  asw100:
    user: admin
    type: srlinux

  asw120:
    user: netops
    type: srlinux

  core-01:
    user: admin
    type: eos

  edge-router:
    user: operator
    commands:
      - show version
      - show ip route summary

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

types:
  srlinux:
    commands:
      - show version
      - show platform linecard
      - show platform fan-tray
      - show platform power-supply
      - info flat from running

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

  centec:
    commands:
      - show version | exc uptime
      - show boot images
      - show transceiver
      - show running-config

Configuration Fields

Types Section

types: Define reusable command sets for different device types.

  • <type-name>: Arbitrary name for the device type (e.g., srlinux, eos)
    • commands: Array of CLI commands to execute on devices of this type

Devices Section

devices: Define individual network devices to backup.

  • <hostname>: Device hostname or IP address
    • user (required): SSH username for authentication
    • type (optional): Reference to a type definition for commands
    • commands (optional): Direct command list (overrides type commands)

Configuration Validation

  • Each device must have a user field
  • Each device must have either a type field (referencing a valid type) or a commands field
  • Type references must exist in the types section
  • Commands can be specified either via type reference or directly per device

Configuration Merging with Mergo

The tool automatically merges multiple YAML files using the mergo library. Files specified later in the --yaml flag override values from earlier files, enabling flexible configuration organization:

Example file structure:

/etc/ipng-router-backup/
├── etc/
│   ├── 00-device-types.yaml    # Device type definitions (loaded first)
│   ├── 10-production.yaml      # Production device definitions
│   ├── 20-staging.yaml         # Staging device definitions
│   └── 99-overrides.yaml       # Environment-specific overrides
└── config.yaml                 # Simple single-file config

Usage patterns:

  1. Load multiple files with automatic merging:

    ipng-router-backup --yaml etc/00-device-types.yaml --yaml etc/10-production.yaml

  2. Use wildcards for directory-based loading:

    ipng-router-backup --yaml etc/*.yaml

  3. Override configurations per environment:

    # Base config + production overrides
ipng-router-backup --yaml base.yaml --yaml production-overrides.yaml

# Base config + development overrides  
ipng-router-backup --yaml base.yaml --yaml dev-overrides.yaml

Merging behavior:

  • Maps are merged: Device and type definitions from multiple files are combined
  • Arrays are replaced: Later files completely replace arrays from earlier files
  • Values are overridden: Later files override individual values from earlier files
  • Types are preserved: Device types from any file can be referenced by devices in any other file

Command Line Flags

Required Flags

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

Optional Flags

  • --output-dir: Output directory for backup files (default: /tmp)
  • --host: Specific hostname(s) to process (can be repeated)
  • --password: SSH password for authentication
  • --key-file: Path to SSH private key file
  • --port: SSH port number (default: 22)
  • --help: Show help information
  • --version: Show version information

Flag Examples

# Basic usage - all devices
ipng-router-backup --yaml /etc/ipng-router-backup/*.yaml

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

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

# Multiple specific devices
ipng-router-backup --yaml *.yaml --host asw100 --host asw120 --host core-01

# Custom SSH port
ipng-router-backup --yaml *.yaml --port 2222

# Using password authentication
ipng-router-backup --yaml *.yaml --password mypassword

# Using specific SSH key
ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key

SSH Authentication Methods

The tool supports multiple SSH authentication methods in the following priority order:

1. SSH Agent (Highest Priority)

Automatically used when the SSH_AUTH_SOCK environment variable is set.

# Start SSH agent and add keys
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

# Run backup (will use SSH agent automatically)
ipng-router-backup --yaml *.yaml

Advantages:

  • Most secure (keys remain in memory)
  • No password prompts
  • Works with hardware security modules
  • Single sign-on experience

2. SSH Key File

Specify a private key file with --key-file, use SSH config, or default locations.

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

# SSH config integration (IdentityFile from ~/.ssh/config)
ipng-router-backup --yaml *.yaml

# Tool automatically checks these default locations:
# ~/.ssh/id_rsa
# ~/.ssh/id_ed25519
# ~/.ssh/id_ecdsa

Key File Requirements:

  • Must be in OpenSSH format
  • Proper permissions (600 recommended)
  • Corresponding public key must be on target devices

SSH Configuration Integration

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

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

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

Supported SSH config options:

  • Hostname: Target hostname override
  • Port: SSH port override
  • User: Username override (command line takes precedence)
  • IdentityFile: SSH key file path
  • KexAlgorithms: Key exchange algorithms (explicit lists only, + syntax ignored for compatibility)
  • Ciphers: Encryption ciphers (filtered for Go SSH library compatibility)
  • MACs: Message authentication codes
  • HostKeyAlgorithms: Host key algorithms (explicit lists only, + syntax ignored for compatibility)

Legacy device compatibility: The tool is designed to work with older network devices that require legacy SSH algorithms while maintaining security for modern devices.

3. Password Authentication (Lowest Priority)

Use --password flag for password-based authentication.

# Command line password (not recommended for scripts)
ipng-router-backup --yaml *.yaml --password mypassword

# Interactive password prompt (when no other auth available)
ipng-router-backup --yaml *.yaml
# Output: "No SSH key found. Enter SSH password: "

Security Considerations:

  • Passwords visible in process lists
  • Not suitable for automation
  • Consider using key-based authentication instead

Output Format

File Naming

Output files are named after the device hostname:

  • Device asw100 → File asw100
  • Device 192.168.1.1 → File 192.168.1.1

File Content Structure

Each output file contains all command outputs with headers:

## COMMAND: show version
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Hostname             : asw100
Chassis Type         : 7220 IXR-D4
Software Version     : v25.3.2
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## COMMAND: show platform linecard
+-------------+----+-------------+-------------------+---------------------------------+
| Module Type | ID | Admin State | Operational State |              Model              |
+=============+====+=============+===================+=================================+
| linecard    | 1  | N/A         | up                | imm28-100g-qsfp28+8-400g-qsfpdd |
+-------------+----+-------------+-------------------+---------------------------------+

File Behavior

  • New runs: Files are truncated and recreated
  • Multiple commands: All outputs concatenated in single file
  • Command identification: Each command prefixed with ## COMMAND: <command>

Usage Examples

Basic Backup All Devices

ipng-router-backup --yaml /etc/backup/*.yaml --output-dir /backup/$(date +%Y%m%d)

Backup Specific Device Types

Create a config with only the devices you want, or use --host:

# Backup only SR Linux devices
ipng-router-backup --yaml network.yaml --host asw100 --host asw120 --host asw121

Scheduled Backup with SSH Agent

#!/bin/bash
# /etc/cron.daily/network-backup

# Start SSH agent
eval "$(ssh-agent -s)"
ssh-add /root/.ssh/network_backup_key

# Run backup
BACKUP_DIR="/backup/network/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

ipng-router-backup \
  --yaml /etc/ipng-router-backup/*.yaml \
  --output-dir "$BACKUP_DIR"

# Kill SSH agent
ssh-agent -k

Emergency Single Device Backup

# Quick backup of single device with password
ipng-router-backup \
  --yaml emergency.yaml \
  --host core-router-01 \
  --password emergency123 \
  --output-dir /tmp/emergency-backup

Error Handling

Common Issues and Solutions

Device Connection Failures:

  • Check SSH connectivity: ssh user@hostname
  • Verify authentication method
  • Check firewall rules and network connectivity

Configuration Errors:

  • Validate YAML syntax: yamllint config.yaml
  • Check that all referenced types exist
  • Ensure all devices have required fields

Permission Issues:

  • Verify SSH key permissions (600)
  • Check output directory write permissions
  • Ensure user has SSH access to target devices

Exit Codes

  • 0: Success
  • 1: Configuration error, authentication failure, or connection issues

Advanced Usage

Configuration Organization with Mergo

For large deployments, organize configurations using multiple YAML files with automatic merging:

Environment-based structure:

network-backup/
├── etc/
│   ├── 00-device-types.yaml      # All device types (loaded first)
│   ├── 10-common.yaml            # Common settings
│   ├── 20-production.yaml        # Production devices
│   ├── 30-staging.yaml           # Staging devices
│   ├── 40-lab.yaml               # Lab devices
│   ├── 50-east-datacenter.yaml   # East datacenter devices
│   └── 60-west-datacenter.yaml   # West datacenter devices
└── overrides/
    ├── emergency.yaml             # Emergency override settings
    └── maintenance.yaml           # Maintenance mode settings

Device types (etc/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

Production devices (etc/20-production.yaml):

devices:
  prod-asw100:
    user: netops
    type: srlinux

  prod-asw120:
    user: netops
    type: srlinux

  prod-core-01:
    user: netops
    type: eos

Usage examples:

# Load all standard configs
ipng-router-backup --yaml etc/*.yaml

# Load with environment-specific overrides
ipng-router-backup --yaml etc/*.yaml --yaml overrides/emergency.yaml

# Load only specific environments
ipng-router-backup --yaml etc/00-device-types.yaml --yaml etc/20-production.yaml

Integration with Git

#!/bin/bash
# Backup and commit to git repository

BACKUP_DIR="/backup/network-configs"
cd "$BACKUP_DIR"

# Run backup
ipng-router-backup --yaml config.yaml --output-dir .

# Commit changes
git add .
git commit -m "Network backup $(date '+%Y-%m-%d %H:%M:%S')"
git push origin main

Custom Command Sets per Environment

types:
  production-srlinux:
    commands:
      - show version
      - show system information
      - info flat from running

  lab-srlinux:
    commands:
      - show version
      - show interface brief

devices:
  prod-asw100:
    user: readonly
    type: production-srlinux

  lab-asw100:
    user: admin
    type: lab-srlinux

Monitoring and Alerting

#!/bin/bash
# Backup with monitoring

if ipng-router-backup --yaml config.yaml --output-dir /backup; then
    echo "Backup completed successfully" | logger
else
    echo "Backup failed!" | logger
    # Send alert email
    echo "Network backup failed at $(date)" | mail -s "Backup Alert" admin@company.com
fi