ipng/router-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e5f9e59601aff096e705a1f2658e430a4313e328
router-backup/docs/DETAILS.md

12 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 includes: Split large configurations into many files and merge them at runtime
  • 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. The configuration reading multiple files with the --yaml flag, merging their contents along the way.

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

Include Directive Support

The configuration supports !include directives for splitting large configurations into multiple files:

# Main config.yaml
!include device-types.yaml

devices:
  production-device:
    user: admin
    type: srlinux

Include Features:

  • One level deep: Included files cannot contain their own !include directives
  • Relative paths: Paths are relative to the including file's directory
  • Absolute paths: Fully qualified paths are supported
  • Quoted paths: Use quotes for paths containing spaces: !include "file with spaces.yaml"
  • Proper indentation: Included content maintains correct YAML indentation

Example file structure:

/etc/ipng-router-backup/
├── config.yaml              # Main configuration with !include
├── device-types.yaml        # Device type definitions
└── devices/
    ├── production.yaml      # Production device definitions
    └── lab.yaml            # Lab device definitions

Usage patterns:

  1. Include device types at top level:

    !include device-types.yaml

devices:
  # device definitions here

  2. Include under specific sections:

    types:
  !include types/network-devices.yaml

devices:
  !include devices/production.yaml

  3. Include files with spaces:

    !include "device types/lab environment.yaml"

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 or use default locations.

# Explicit key file
ipng-router-backup --yaml *.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 --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 Includes

For large deployments, organize configurations using !include directives:

Environment-based structure:

network-backup/
├── config.yaml                    # Main config
├── types/
│   ├── device-types.yaml         # All device types
│   └── vendor-specific.yaml      # Vendor-specific commands
├── environments/
│   ├── production.yaml           # Production devices
│   ├── staging.yaml              # Staging devices
│   └── lab.yaml                  # Lab devices
└── sites/
    ├── datacenter-east.yaml      # East datacenter devices
    └── datacenter-west.yaml      # West datacenter devices

Main configuration (config.yaml):

!include types/device-types.yaml

devices:
  # Production environment
  !include environments/production.yaml

  # Lab environment
  !include environments/lab.yaml

Production devices (environments/production.yaml):

# Production SR Linux switches
prod-asw100:
  user: netops
  type: srlinux

prod-asw120:
  user: netops
  type: srlinux

# Production EOS devices
prod-core-01:
  user: netops
  type: eos

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