358 lines
9.3 KiB
Markdown
358 lines
9.3 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
|
|
- **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.
|
|
|
|
- **`<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
|
|
|
|
## 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: <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
|
|
``` |