244 lines
7.2 KiB
Markdown
244 lines
7.2 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 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 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
|
|
- **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 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
|
|
|
|
routeros:
|
|
commands:
|
|
- system package print detail without-paging
|
|
- / export terse
|
|
exclude:
|
|
- "^# ....-..-.. ..:..:.. by RouterOS" # Filter timestamp headers
|
|
- "^# .../../.... ..:..:.. by RouterOS" # Alternative date format
|
|
```
|
|
|
|
**Main configuration** (`config.yaml`):
|
|
```yaml
|
|
devices:
|
|
asw100:
|
|
user: admin
|
|
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: # Direct commands (no type)
|
|
- show version
|
|
- show ip route summary
|
|
```
|
|
|
|
### Configuration Fields
|
|
|
|
#### Types Section
|
|
- **`<type-name>`**: Device type name (e.g., `srlinux`, `eos`)
|
|
- **`commands`**: Array of CLI commands to execute
|
|
- **`exclude`** (optional): Array of regex patterns to filter out unwanted lines from output
|
|
|
|
#### Devices Section
|
|
- **`<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 Merging
|
|
|
|
Files are merged automatically using mergo. Later files override earlier ones:
|
|
|
|
```bash
|
|
# Load multiple files - later files override earlier ones
|
|
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml --yaml overrides.yaml
|
|
|
|
# Load files using glob patterns
|
|
ipng-router-backup --yaml "*.yaml"
|
|
ipng-router-backup --yaml "config/*.yaml"
|
|
```
|
|
|
|
## Output Filtering
|
|
|
|
The tool supports filtering unwanted lines from command output using regular expressions in the `exclude` field of device types.
|
|
|
|
### How Exclude Patterns Work
|
|
|
|
- **Regex matching**: Each line of command output is tested against all exclude patterns
|
|
- **Line removal**: Lines matching any pattern are completely removed from the output file
|
|
- **Per-device type**: Exclude patterns are defined at the device type level and apply to all devices of that type
|
|
|
|
### Common Use Cases
|
|
|
|
```yaml
|
|
types:
|
|
routeros:
|
|
commands:
|
|
- / export terse
|
|
exclude:
|
|
- "^# ....-..-.. ..:..:.. by RouterOS" # Remove timestamp headers
|
|
- "^# .../../.... ..:..:.. by RouterOS" # Alternative date format
|
|
|
|
cisco-ios:
|
|
commands:
|
|
- show running-config
|
|
exclude:
|
|
- "^Building configuration" # Remove config build messages
|
|
- "^Current configuration" # Remove current config headers
|
|
- "^!" # Remove comment lines
|
|
|
|
debug-device:
|
|
commands:
|
|
- show logs
|
|
exclude:
|
|
- "^DEBUG:" # Filter debug messages
|
|
- "^TRACE:" # Filter trace messages
|
|
```
|
|
|
|
## Command Line Usage
|
|
|
|
### Required Flags
|
|
- **`--yaml`**: Path to YAML configuration file(s) or glob patterns (can be repeated)
|
|
|
|
### Optional Flags
|
|
- **`--output-dir`**: Output directory (default: `/tmp`)
|
|
- **`--host`**: Specific hostname(s) or glob patterns to process (can be repeated)
|
|
- **`--password`**: SSH password
|
|
- **`--key-file`**: SSH private key file path
|
|
- **`--port`**: SSH port (default: `22`)
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Basic usage with glob patterns
|
|
ipng-router-backup --yaml "*.yaml"
|
|
|
|
# Multiple files
|
|
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml
|
|
|
|
# Devices matching patterns
|
|
ipng-router-backup --yaml config.yaml --host "asw*" --host "*switch*"
|
|
|
|
# Custom output directory
|
|
ipng-router-backup --yaml config.yaml --output-dir /backup/network
|
|
|
|
# With password authentication
|
|
ipng-router-backup --yaml config.yaml --password mypassword
|
|
```
|
|
|
|
## SSH Authentication
|
|
|
|
The tool supports multiple authentication methods in priority order:
|
|
|
|
### 1. SSH Agent (Recommended)
|
|
Automatically used when `SSH_AUTH_SOCK` is set:
|
|
```bash
|
|
eval "$(ssh-agent -s)"
|
|
ssh-add ~/.ssh/id_rsa
|
|
ipng-router-backup --yaml config.yaml
|
|
```
|
|
|
|
### 2. SSH Key File
|
|
```bash
|
|
# Explicit key file
|
|
ipng-router-backup --yaml config.yaml --key-file ~/.ssh/network_key
|
|
|
|
# Automatic detection from default locations:
|
|
# ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
|
|
ipng-router-backup --yaml config.yaml
|
|
```
|
|
|
|
### 3. Password Authentication
|
|
```bash
|
|
ipng-router-backup --yaml config.yaml --password mypassword
|
|
```
|
|
|
|
## SSH Configuration Integration
|
|
|
|
The tool automatically reads `~/.ssh/config` for each host:
|
|
|
|
```bash
|
|
# ~/.ssh/config
|
|
Host old-switch*
|
|
User admin
|
|
Port 2222
|
|
IdentityFile ~/.ssh/legacy_key
|
|
KexAlgorithms +diffie-hellman-group1-sha1
|
|
HostKeyAlgorithms +ssh-rsa
|
|
|
|
Host modern-router*
|
|
User netops
|
|
IdentityFile ~/.ssh/modern_key
|
|
```
|
|
|
|
**Supported options:** Hostname, Port, User, IdentityFile, KexAlgorithms, MACs, HostKeyAlgorithms
|
|
|
|
## Output Format
|
|
|
|
### File Naming
|
|
- Output files are named after the device hostname
|
|
- Device `asw100` → File `asw100`
|
|
|
|
### File Content
|
|
Each file contains all command outputs with headers:
|
|
```
|
|
## COMMAND: show version
|
|
Hostname : asw100
|
|
Software Version : v25.3.2
|
|
------------------------------------------------------------------------
|
|
## COMMAND: show platform linecard
|
|
+-------------+----+-------------+-------------------+
|
|
| Module Type | ID | Admin State | Operational State |
|
|
+=============+====+=============+===================+
|
|
| linecard | 1 | N/A | up |
|
|
+-------------+----+-------------+-------------------+
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
### 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 (all devices processed successfully)
|
|
- `1`: Configuration error, authentication failure, or connection issues
|
|
- `10`: Some devices failed
|
|
- `11`: All devices failed |