From 097206060d4d87ec382d47bcb9a00ca21e8a0154 Mon Sep 17 00:00:00 2001 From: Pim van Pelt Date: Sun, 6 Jul 2025 11:16:14 +0000 Subject: [PATCH] Add some README --- README.md | 81 +++++++++++ docs/DETAILS.md | 358 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 439 insertions(+) create mode 100644 README.md create mode 100644 docs/DETAILS.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..3fcb5b1 --- /dev/null +++ b/README.md @@ -0,0 +1,81 @@ +# IPNG Router Backup + +SSH-based network device configuration backup tool with support for multiple device types and flexible authentication methods. + +## Features + +- **Multi-device backup**: Configure multiple routers in YAML +- **Device type templates**: Reusable command sets per device type +- **Flexible authentication**: SSH agent, key files, or password +- **Selective execution**: Backup specific devices with `--host` flags +- **Professional CLI**: Standard flags, version info, and help + +## Quick Start + +### Installation + +```bash +# Install Debian package +sudo dpkg -i ipng-router-backup_X.Y.Z_amd64.deb + +# Or build from source +make build +``` + +### Basic Usage + +1. **Create configuration file** (`config.yaml`): + +```yaml +types: + srlinux: + commands: + - show version + - show platform linecard + - info flat from running + +devices: + asw100: + user: admin + type: srlinux + asw120: + user: admin + type: srlinux +``` + +2. **Run backup**: + +```bash +# Backup all devices +ipng-router-backup --config config.yaml --output-dir /backup + +# Backup specific devices +ipng-router-backup --config config.yaml --host asw100 --output-dir /backup +``` + +3. **Check output**: + +```bash +ls /backup/ +# asw100 asw120 + +cat /backup/asw100 +# ## COMMAND: show version +# Hostname : asw100 +# Software Version : v25.3.2 +# ... +``` + +## Authentication + +The tool automatically tries authentication methods in this order: + +1. **SSH Agent** (if `SSH_AUTH_SOCK` is set) +2. **SSH Key File** (`--key-file` or default locations) +3. **Password** (`--password` flag) + +## Documentation + +- **[Detailed Documentation](docs/DETAILS.md)** - Complete feature guide, configuration reference, and examples +- **[Manual Page](docs/router_backup.1)** - Unix manual page +- **[Changelog](debian/changelog)** - Version history and changes diff --git a/docs/DETAILS.md b/docs/DETAILS.md new file mode 100644 index 0000000..dc93b1e --- /dev/null +++ b/docs/DETAILS.md @@ -0,0 +1,358 @@ +# 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 + +```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 + +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. + +- **``**: 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. + +- **``**: 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 + +```bash +# 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. + +```bash +# 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. + +```bash +# 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. + +```bash +# 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: ` + +## Usage Examples + +### Basic Backup All Devices + +```bash +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`: + +```bash +# Backup only SR Linux devices +ipng-router-backup --config network.yaml --host asw100 --host asw120 --host asw121 +``` + +### Scheduled Backup with SSH Agent + +```bash +#!/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 + +```bash +# 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 + +```bash +#!/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 + +```yaml +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 + +```bash +#!/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 +``` \ No newline at end of file