ipng/router-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
7e91564f37cfb557c65a0ab01c846f1649b6c709
router-backup/docs/DETAILS.md
Pim van Pelt 097206060d Add some README
2025-07-06 11:16:14 +00:00

9.3 KiB
Raw Blame History

IPNG Router Backup - Detailed Documentation

Overview

IPNG 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
  • 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 a YAML configuration file with two main sections: types and devices.

Complete Example

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

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

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

Command Line Flags

Required Flags

  • --config: Path to YAML configuration file

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 --config /etc/network-backup/config.yaml

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

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

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

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

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

# Using specific SSH key
ipng-router-backup --config config.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 --config config.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 or use default locations.

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

# 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

3. Password Authentication (Lowest Priority)

Use --password flag for password-based authentication.

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

# Interactive password prompt (when no other auth available)
ipng-router-backup --config config.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 --config /etc/backup/network.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 --config 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 \
  --config /etc/network-backup/config.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 \
  --config 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

Integration with Git

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

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

# Run backup
ipng-router-backup --config 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 --config 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