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

478
docs/DETAILS.md
View File

@ -2,26 +2,40 @@
## 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
- **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
- **Configuration merging**: Load and merge multiple YAML files using mergo
- **SSH config integration**: 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
- **IPv6 support**: Automatic IPv6 address detection and proper formatting
## 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
**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`):
```yaml
devices:
@ -29,203 +43,105 @@ devices:
user: admin
type: srlinux
asw120:
user: netops
type: srlinux
core-01:
user: admin
type: eos
address: 192.168.1.100 # Override connection address
ipv6-router:
user: netops
address: 2001:678:d78:500:: # IPv6 address support
edge-router:
user: operator
commands:
commands: # Direct commands (no type)
- show version
- 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
#### 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
- **`<type-name>`**: Device type name (e.g., `srlinux`, `eos`)
- **`commands`**: Array of CLI commands to execute
#### 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
- **`<hostname>`**: Device hostname (used for SSH config lookup and output filename)
- **`user`** (required): SSH username
- **`type`** (optional): Reference to a type definition
- **`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
- 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
Files are merged automatically using mergo. Later files override earlier ones:
### 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:**
```bash
ipng-router-backup --yaml etc/00-device-types.yaml --yaml etc/10-production.yaml
# Load multiple files - later files override earlier ones
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml --yaml overrides.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
## Command Line Usage
### Required Flags
- **`--yaml`**: Path to YAML configuration file(s)
- **`--yaml`**: Path to YAML configuration file(s) (can be repeated)
### Optional Flags
- **`--output-dir`**: Output directory for backup files (default: `/tmp`)
- **`--output-dir`**: Output directory (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
- **`--password`**: SSH password
- **`--key-file`**: SSH private key file path
- **`--port`**: SSH port (default: `22`)
### Flag Examples
### Examples
```bash
# Basic usage - all devices
ipng-router-backup --yaml /etc/ipng-router-backup/*.yaml
# Basic usage
ipng-router-backup --yaml config.yaml
# Custom output directory
ipng-router-backup --yaml *.yaml --output-dir /backup/network
# Multiple files
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml
# 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
ipng-router-backup --yaml *.yaml --host asw100 --host asw120 --host core-01
# Custom output directory
ipng-router-backup --yaml config.yaml --output-dir /backup/network
# 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
# With password authentication
ipng-router-backup --yaml config.yaml --password mypassword
```
## SSH Authentication Methods
## SSH Authentication
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.
The tool supports multiple authentication methods in priority order:
### 1. SSH Agent (Recommended)
Automatically used when `SSH_AUTH_SOCK` 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 --yaml *.yaml
ipng-router-backup --yaml 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`, use SSH config, or default locations.
```bash
# 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)
ipng-router-backup --yaml *.yaml
# Tool automatically checks these default locations:
# ~/.ssh/id_rsa
# ~/.ssh/id_ed25519
# ~/.ssh/id_ecdsa
# Automatic detection from default locations:
# ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
ipng-router-backup --yaml config.yaml
```
**Key File Requirements:**
- Must be in OpenSSH format
- Proper permissions (600 recommended)
- Corresponding public key must be on target devices
### 3. Password Authentication
```bash
ipng-router-backup --yaml config.yaml --password mypassword
```
### 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
# ~/.ssh/config
@ -234,273 +150,43 @@ Host old-switch*
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.
```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
**Supported options:** Hostname, Port, User, IdentityFile, KexAlgorithms, MACs, HostKeyAlgorithms
## Output Format
### File Naming
Output files are named after the device hostname:
- 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:
### File Content
Each 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
```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
+-------------+----+-------------+-------------------+
| Module Type | ID | Admin State | Operational State |
+=============+====+=============+===================+
| linecard | 1 | N/A | up |
+-------------+----+-------------+-------------------+
```
## 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
### Common Issues
- **Connection failures**: Check SSH connectivity and authentication
- **Configuration errors**: Validate YAML syntax and required fields
- **Permission issues**: Verify SSH key permissions (600) and output directory access
### 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:**
```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
```