ipng/router-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rework and simplify the docs

Browse Source
This commit is contained in:
Pim van Pelt
2025-07-06 22:22:40 +02:00
parent 1afa1e6d43
commit f2c484e9c1
1 changed files with 84 additions and 398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

480
docs/DETAILS.md
View File

@ -2,26 +2,40 @@
## Overview ## 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. 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 ## Key Features
- **Multi-device support**: Backup multiple routers in a single run - **Multi-device support**: Backup multiple routers in a single run
- **Device type templates**: Define command sets per device type - **Device type templates**: Define command sets per device type
- **Configuration merging**: Load and merge multiple YAML files automatically using mergo - **Configuration merging**: Load and merge multiple YAML files using mergo
- **SSH config integration**: Automatically uses `~/.ssh/config` for legacy device compatibility - **SSH config integration**: Uses `~/.ssh/config` for legacy device compatibility
- **Flexible authentication**: SSH agent, key files, or password authentication - **Flexible authentication**: SSH agent, key files, or password authentication
- **Selective execution**: Target specific devices with `--host` flags - **Selective execution**: Target specific devices with `--host` flags
- **Automatic file organization**: Output files named by hostname - **IPv6 support**: Automatic IPv6 address detection and proper formatting
- **Command identification**: Each command output prefixed with command name
- **Version synchronization**: Automatic version sync between package and binary
## Configuration File Format ## 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. The tool uses YAML configuration files with two main sections: `types` and `devices`. Multiple YAML files can be loaded and merged automatically.
### Complete Example ### Complete Example
**Device types** (`00-device-types.yaml`):
```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`): **Main configuration** (`config.yaml`):
```yaml ```yaml
devices: devices:
@ -29,203 +43,105 @@ devices:
user: admin user: admin
type: srlinux type: srlinux
asw120:
user: netops
type: srlinux
core-01: core-01:
user: admin user: admin
type: eos type: eos
address: 192.168.1.100 # Override connection address
ipv6-router:
user: netops
address: 2001:678:d78:500:: # IPv6 address support
edge-router: edge-router:
user: operator user: operator
commands: commands: # Direct commands (no type)
- show version - show version
- show ip route summary - show ip route summary
``` ```
**Device types file** (`00-device-types.yaml`):
```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 ### Configuration Fields
#### Types Section #### Types Section
- **`<type-name>`**: Device type name (e.g., `srlinux`, `eos`)
**`types`**: Define reusable command sets for different device types. - **`commands`**: Array of CLI commands to execute
- **`<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 Section
- **`<hostname>`**: Device hostname (used for SSH config lookup and output filename)
**`devices`**: Define individual network devices to backup. - **`user`** (required): SSH username
- **`type`** (optional): Reference to a type definition
- **`<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) - **`commands`** (optional): Direct command list (overrides type commands)
- **`address`** (optional): IP address or hostname to connect to (overrides hostname)
### Configuration Validation ### Configuration Merging
- Each device must have a `user` field Files are merged automatically using mergo. Later files override earlier ones:
- 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 ```bash
# Load multiple files - later files override earlier ones
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: ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml --yaml overrides.yaml
**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:** ## Command Line Usage
1. **Load multiple files with automatic merging:**
```bash
ipng-router-backup --yaml etc/00-device-types.yaml --yaml etc/10-production.yaml
```
2. **Use wildcards for directory-based loading:**
```bash
ipng-router-backup --yaml etc/*.yaml
```
3. **Override configurations per environment:**
```bash
# 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 ### Required Flags
- **`--yaml`**: Path to YAML configuration file(s) (can be repeated)
- **`--yaml`**: Path to YAML configuration file(s)
### Optional Flags ### Optional Flags
- **`--output-dir`**: Output directory (default: `/tmp`)
- **`--output-dir`**: Output directory for backup files (default: `/tmp`)
- **`--host`**: Specific hostname(s) to process (can be repeated) - **`--host`**: Specific hostname(s) to process (can be repeated)
- **`--password`**: SSH password for authentication - **`--password`**: SSH password
- **`--key-file`**: Path to SSH private key file - **`--key-file`**: SSH private key file path
- **`--port`**: SSH port number (default: `22`) - **`--port`**: SSH port (default: `22`)
- **`--help`**: Show help information
- **`--version`**: Show version information
### Flag Examples ### Examples
```bash ```bash
# Basic usage - all devices # Basic usage
ipng-router-backup --yaml /etc/ipng-router-backup/*.yaml ipng-router-backup --yaml config.yaml
# Custom output directory # Multiple files
ipng-router-backup --yaml *.yaml --output-dir /backup/network ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml
# Specific devices only # Specific devices only
ipng-router-backup --yaml *.yaml --host asw100 --host core-01 ipng-router-backup --yaml config.yaml --host asw100 --host core-01
# Multiple specific devices # Custom output directory
ipng-router-backup --yaml *.yaml --host asw100 --host asw120 --host core-01 ipng-router-backup --yaml config.yaml --output-dir /backup/network
# Custom SSH port # With password authentication
ipng-router-backup --yaml *.yaml --port 2222 ipng-router-backup --yaml config.yaml --password mypassword
# 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 ## SSH Authentication
The tool supports multiple SSH authentication methods in the following priority order: The tool supports multiple authentication methods in priority order:
### 1. SSH Agent (Highest Priority)
Automatically used when the `SSH_AUTH_SOCK` environment variable is set.
### 1. SSH Agent (Recommended)
Automatically used when `SSH_AUTH_SOCK` is set:
```bash ```bash
# Start SSH agent and add keys
eval "$(ssh-agent -s)" eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa ssh-add ~/.ssh/id_rsa
ipng-router-backup --yaml config.yaml
# 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 ### 2. SSH Key File
Specify a private key file with `--key-file`, use SSH config, or default locations.
```bash ```bash
# Explicit key file # Explicit key file
ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key ipng-router-backup --yaml config.yaml --key-file ~/.ssh/network_key
# SSH config integration (IdentityFile from ~/.ssh/config) # Automatic detection from default locations:
ipng-router-backup --yaml *.yaml # ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
ipng-router-backup --yaml config.yaml
# Tool automatically checks these default locations:
# ~/.ssh/id_rsa
# ~/.ssh/id_ed25519
# ~/.ssh/id_ecdsa
``` ```
**Key File Requirements:** ### 3. Password Authentication
- Must be in OpenSSH format ```bash
- Proper permissions (600 recommended) ipng-router-backup --yaml config.yaml --password mypassword
- Corresponding public key must be on target devices ```
### SSH Configuration Integration ## SSH Configuration Integration
The tool automatically reads `~/.ssh/config` for each host, supporting: The tool automatically reads `~/.ssh/config` for each host:
```bash ```bash
# ~/.ssh/config # ~/.ssh/config
@ -234,273 +150,43 @@ Host old-switch*
Port 2222 Port 2222
IdentityFile ~/.ssh/legacy_key IdentityFile ~/.ssh/legacy_key
KexAlgorithms +diffie-hellman-group1-sha1 KexAlgorithms +diffie-hellman-group1-sha1
Ciphers aes128-cbc,aes192-cbc,aes256-cbc
HostKeyAlgorithms +ssh-rsa HostKeyAlgorithms +ssh-rsa
Host modern-router* Host modern-router*
User netops User netops
Port 22
IdentityFile ~/.ssh/modern_key IdentityFile ~/.ssh/modern_key
``` ```
**Supported SSH config options:** **Supported options:** Hostname, Port, User, IdentityFile, KexAlgorithms, MACs, HostKeyAlgorithms
- `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.
```bash
# 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 ## Output Format
### File Naming ### File Naming
- Output files are named after the device hostname
Output files are named after the device hostname:
- Device `asw100` → File `asw100` - 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:
### File Content
Each file contains all command outputs with headers:
``` ```
## COMMAND: show version ## COMMAND: show version
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Hostname : asw100 Hostname : asw100
Chassis Type : 7220 IXR-D4
Software Version : v25.3.2 Software Version : v25.3.2
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- ------------------------------------------------------------------------
## COMMAND: show platform linecard ## COMMAND: show platform linecard
+-------------+----+-------------+-------------------+---------------------------------+ +-------------+----+-------------+-------------------+
| Module Type | ID | Admin State | Operational State | Model | | Module Type | ID | Admin State | Operational State |
+=============+====+=============+===================+=================================+ +=============+====+=============+===================+
| linecard | 1 | N/A | up | imm28-100g-qsfp28+8-400g-qsfpdd | | linecard | 1 | N/A | up |
+-------------+----+-------------+-------------------+---------------------------------+ +-------------+----+-------------+-------------------+
```
### 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
```bash
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`:
```bash
# Backup only SR Linux devices
ipng-router-backup --yaml 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 \
--yaml /etc/ipng-router-backup/*.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 \
--yaml emergency.yaml \
--host core-router-01 \
--password emergency123 \
--output-dir /tmp/emergency-backup
``` ```
## Error Handling ## Error Handling
### Common Issues and Solutions ### Common Issues
- **Connection failures**: Check SSH connectivity and authentication
**Device Connection Failures:** - **Configuration errors**: Validate YAML syntax and required fields
- Check SSH connectivity: `ssh user@hostname` - **Permission issues**: Verify SSH key permissions (600) and output directory access
- 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 ### Exit Codes
- `0`: Success - `0`: Success
- `1`: Configuration error, authentication failure, or connection issues - `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:**
```bash
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`):
```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`):
```yaml
devices:
prod-asw100:
user: netops
type: srlinux
prod-asw120:
user: netops
type: srlinux
prod-core-01:
user: netops
type: eos
```
**Usage examples:**
```bash
# 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
```bash
#!/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
```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 --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
```