Add some README
This commit is contained in:
81
README.md
Normal file
81
README.md
Normal file
@ -0,0 +1,81 @@
|
||||
# IPNG Router Backup
|
||||
|
||||
SSH-based network device configuration backup tool with support for multiple device types and flexible authentication methods.
|
||||
|
||||
## Features
|
||||
|
||||
- **Multi-device backup**: Configure multiple routers in YAML
|
||||
- **Device type templates**: Reusable command sets per device type
|
||||
- **Flexible authentication**: SSH agent, key files, or password
|
||||
- **Selective execution**: Backup specific devices with `--host` flags
|
||||
- **Professional CLI**: Standard flags, version info, and help
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Install Debian package
|
||||
sudo dpkg -i ipng-router-backup_X.Y.Z_amd64.deb
|
||||
|
||||
# Or build from source
|
||||
make build
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
1. **Create configuration file** (`config.yaml`):
|
||||
|
||||
```yaml
|
||||
types:
|
||||
srlinux:
|
||||
commands:
|
||||
- show version
|
||||
- show platform linecard
|
||||
- info flat from running
|
||||
|
||||
devices:
|
||||
asw100:
|
||||
user: admin
|
||||
type: srlinux
|
||||
asw120:
|
||||
user: admin
|
||||
type: srlinux
|
||||
```
|
||||
|
||||
2. **Run backup**:
|
||||
|
||||
```bash
|
||||
# Backup all devices
|
||||
ipng-router-backup --config config.yaml --output-dir /backup
|
||||
|
||||
# Backup specific devices
|
||||
ipng-router-backup --config config.yaml --host asw100 --output-dir /backup
|
||||
```
|
||||
|
||||
3. **Check output**:
|
||||
|
||||
```bash
|
||||
ls /backup/
|
||||
# asw100 asw120
|
||||
|
||||
cat /backup/asw100
|
||||
# ## COMMAND: show version
|
||||
# Hostname : asw100
|
||||
# Software Version : v25.3.2
|
||||
# ...
|
||||
```
|
||||
|
||||
## Authentication
|
||||
|
||||
The tool automatically tries authentication methods in this order:
|
||||
|
||||
1. **SSH Agent** (if `SSH_AUTH_SOCK` is set)
|
||||
2. **SSH Key File** (`--key-file` or default locations)
|
||||
3. **Password** (`--password` flag)
|
||||
|
||||
## Documentation
|
||||
|
||||
- **[Detailed Documentation](docs/DETAILS.md)** - Complete feature guide, configuration reference, and examples
|
||||
- **[Manual Page](docs/router_backup.1)** - Unix manual page
|
||||
- **[Changelog](debian/changelog)** - Version history and changes
|
||||
358
docs/DETAILS.md
Normal file
358
docs/DETAILS.md
Normal file
@ -0,0 +1,358 @@
|
||||
# IPNG Router Backup - Detailed Documentation
|
||||
|
||||
## Overview
|
||||
|
||||
IPNG 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
|
||||
```
|
||||
Reference in New Issue
Block a user