507 lines
14 KiB
Markdown
507 lines
14 KiB
Markdown
# 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 merging**: Load and merge multiple YAML files automatically using mergo
|
|
- **SSH config integration**: Automatically 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
|
|
|
|
## 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.
|
|
|
|
### Complete Example
|
|
|
|
**Main configuration** (`config.yaml`):
|
|
```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`):
|
|
```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
|
|
|
|
### 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
|
|
```
|
|
|
|
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
|
|
|
|
- **`--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
|
|
|
|
```bash
|
|
# 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.
|
|
|
|
```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
|
|
```
|
|
|
|
**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
|
|
|
|
# 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
|
|
```
|
|
|
|
**Key File Requirements:**
|
|
- Must be in OpenSSH format
|
|
- Proper permissions (600 recommended)
|
|
- Corresponding public key must be on target devices
|
|
|
|
### SSH Configuration Integration
|
|
|
|
The tool automatically reads `~/.ssh/config` for each host, supporting:
|
|
|
|
```bash
|
|
# ~/.ssh/config
|
|
Host old-switch*
|
|
User admin
|
|
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
|
|
|
|
## 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
|
|
|
|
```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
|
|
|
|
### 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 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
|
|
```
|