ipng/router-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update docs

Browse Source
This commit is contained in:
Pim van Pelt
2025-07-06 17:17:45 +02:00
parent e5f9e59601
commit a3d681e420
2 changed files with 157 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

61
README.md
View File

@ -4,9 +4,11 @@ SSH-based network device configuration backup tool with support for multiple dev
## Features ## Features
- **Multi-device backup**: Configure multiple devices in YAML, with `!include` directives - **Multi-device backup**: Configure multiple devices across multiple YAML files with automatic merging
- **Device type templates**: Reusable command sets per device type, overridable per individual device - **Device type templates**: Reusable command sets per device type, overridable per individual device
- **Flexible authentication**: SSH agent, key files, or password - **Flexible authentication**: SSH agent, key files, or password with SSH config support
- **SSH config integration**: Automatically uses `~/.ssh/config` settings for legacy device compatibility
- **Modular configuration**: Load and merge multiple YAML files for organized configuration management
## Quick Start ## Quick Start
@ -24,18 +26,7 @@ make build
1. **Create configuration files**: 1. **Create configuration files**:
**Main config** (`config.yaml`): **Device types** (`yaml/00-device-types.yaml`):
```yaml
devices:
asw100:
user: netops
type: srlinux
asw120:
user: netops
type: srlinux
```
**Device types** (`00-device-types.yaml`):
```yaml ```yaml
types: types:
srlinux: srlinux:
@ -43,16 +34,34 @@ make build
- show version - show version
- show platform linecard - show platform linecard
- info flat from running - info flat from running
centec:
commands:
- show version
- show running-config
```
**Device config** (`yaml/config.yaml`):
```yaml
devices:
asw100:
user: netops
type: srlinux
switch01:
user: admin
type: centec
``` ```
2. **Run backup**: 2. **Run backup**:
```bash ```bash
# Backup all devices # Backup all devices (multiple YAML files are automatically merged)
ipng-router-backup --yaml *.yaml --output-dir /backup ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/config.yaml --output-dir /backup
# Or use wildcards
ipng-router-backup --yaml yaml/*.yaml --output-dir /backup
# Backup specific devices # Backup specific devices
ipng-router-backup --yaml *.yaml --host asw100 --output-dir /backup ipng-router-backup --yaml yaml/*.yaml --host asw100 --output-dir /backup
``` ```
3. **Check output**: 3. **Check output**:
@ -73,9 +82,25 @@ cat /backup/asw100
The tool automatically tries authentication methods in this order: The tool automatically tries authentication methods in this order:
1. **SSH Agent** (if `SSH_AUTH_SOCK` is set) 1. **SSH Agent** (if `SSH_AUTH_SOCK` is set)
2. **SSH Key File** (`--key-file` or default locations) 2. **SSH Key File** (`--key-file` or from `~/.ssh/config`)
3. **Password** (`--password` flag) 3. **Password** (`--password` flag)
## SSH Configuration
The tool integrates with `~/.ssh/config` for seamless connection to legacy devices:
```bash
# ~/.ssh/config
Host old-router*
User admin
Port 2222
KexAlgorithms +diffie-hellman-group1-sha1
Ciphers aes128-cbc,aes192-cbc,aes256-cbc
HostKeyAlgorithms +ssh-rsa
```
This allows connecting to older routers that require legacy SSH algorithms while maintaining security for modern devices.
## Documentation ## Documentation
- **[Detailed Documentation](docs/DETAILS.md)** - Complete feature guide, configuration reference, and examples - **[Detailed Documentation](docs/DETAILS.md)** - Complete feature guide, configuration reference, and examples

178
docs/DETAILS.md
View File

@ -8,7 +8,8 @@ IPng Networks Router Backup is a SSH-based network device configuration backup t
- **Multi-device support**: Backup multiple routers in a single run - **Multi-device support**: Backup multiple routers in a single run
- **Device type templates**: Define command sets per device type - **Device type templates**: Define command sets per device type
- **Configuration includes**: Split large configurations into many files and merge them at runtime - **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 - **Flexible authentication**: SSH agent, key files, or password authentication
- **Selective execution**: Target specific devices with `--host` flags - **Selective execution**: Target specific devices with `--host` flags
- **Automatic file organization**: Output files named by hostname - **Automatic file organization**: Output files named by hostname
@ -17,8 +18,7 @@ IPng Networks Router Backup is a SSH-based network device configuration backup t
## Configuration File Format ## Configuration File Format
The tool uses a YAML configuration file with two main sections: `types` and `devices`. The 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.
configuration reading multiple files with the `--yaml` flag, merging their contents along the way.
### Complete Example ### Complete Example
@ -95,61 +95,48 @@ types:
- Type references must exist in the `types` section - Type references must exist in the `types` section
- Commands can be specified either via type reference or directly per device - Commands can be specified either via type reference or directly per device
### Include Directive Support ### Configuration Merging with Mergo
The configuration supports `!include` directives for splitting large configurations into multiple files: 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:
```yaml
# Main config.yaml
!include device-types.yaml
devices:
production-device:
user: admin
type: srlinux
```
**Include Features:**
- **One level deep**: Included files cannot contain their own `!include` directives
- **Relative paths**: Paths are relative to the including file's directory
- **Absolute paths**: Fully qualified paths are supported
- **Quoted paths**: Use quotes for paths containing spaces: `!include "file with spaces.yaml"`
- **Proper indentation**: Included content maintains correct YAML indentation
**Example file structure:** **Example file structure:**
``` ```
/etc/ipng-router-backup/ /etc/ipng-router-backup/
├── config.yaml # Main configuration with !include ├── yaml/
├── device-types.yaml # Device type definitions │ ├── 00-device-types.yaml # Device type definitions (loaded first)
└── devices/ │ ├── 10-production.yaml # Production device definitions
├── production.yaml # Production device definitions │ ├── 20-staging.yaml # Staging device definitions
└── lab.yaml # Lab device definitions │ └── 99-overrides.yaml # Environment-specific overrides
└── config.yaml # Simple single-file config
``` ```
**Usage patterns:** **Usage patterns:**
1. **Include device types at top level:** 1. **Load multiple files with automatic merging:**
```yaml ```bash
!include device-types.yaml ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/10-production.yaml
devices:
# device definitions here
``` ```
2. **Include under specific sections:** 2. **Use wildcards for directory-based loading:**
```yaml ```bash
types: ipng-router-backup --yaml yaml/*.yaml
!include types/network-devices.yaml
devices:
!include devices/production.yaml
``` ```
3. **Include files with spaces:** 3. **Override configurations per environment:**
```yaml ```bash
!include "device types/lab environment.yaml" # 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 Flags
### Required Flags ### Required Flags
@ -216,12 +203,15 @@ ipng-router-backup --yaml *.yaml
### 2. SSH Key File ### 2. SSH Key File
Specify a private key file with `--key-file` or use default locations. Specify a private key file with `--key-file`, use SSH config, or default locations.
```bash ```bash
# Explicit key file # Explicit key file
ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key 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: # Tool automatically checks these default locations:
# ~/.ssh/id_rsa # ~/.ssh/id_rsa
# ~/.ssh/id_ed25519 # ~/.ssh/id_ed25519
@ -233,6 +223,39 @@ ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key
- Proper permissions (600 recommended) - Proper permissions (600 recommended)
- Corresponding public key must be on target devices - 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) ### 3. Password Authentication (Lowest Priority)
Use `--password` flag for password-based authentication. Use `--password` flag for password-based authentication.
@ -360,41 +383,45 @@ ipng-router-backup \
## Advanced Usage ## Advanced Usage
### Configuration Organization with Includes ### Configuration Organization with Mergo
For large deployments, organize configurations using `!include` directives: For large deployments, organize configurations using multiple YAML files with automatic merging:
**Environment-based structure:** **Environment-based structure:**
```bash ```bash
network-backup/ network-backup/
├── config.yaml # Main config ├── yaml/
├── types/ │ ├── 00-device-types.yaml # All device types (loaded first)
│ ├── device-types.yaml # All device types │ ├── 10-common.yaml # Common settings
│ └── vendor-specific.yaml # Vendor-specific commands │ ├── 20-production.yaml # Production devices
├── environments/ │ ├── 30-staging.yaml # Staging devices
│ ├── production.yaml # Production devices │ ├── 40-lab.yaml # Lab devices
│ ├── staging.yaml # Staging devices │ ├── 50-east-datacenter.yaml # East datacenter devices
│ └── lab.yaml # Lab devices │ └── 60-west-datacenter.yaml # West datacenter devices
└── sites/ └── overrides/
├── datacenter-east.yaml # East datacenter devices ├── emergency.yaml # Emergency override settings
└── datacenter-west.yaml # West datacenter devices └── maintenance.yaml # Maintenance mode settings
``` ```
**Main configuration** (`config.yaml`): **Device types** (`yaml/00-device-types.yaml`):
```yaml ```yaml
!include types/device-types.yaml types:
srlinux:
commands:
- show version
- show platform linecard
- info flat from running
eos:
commands:
- show version
- show inventory
- show running-config
```
**Production devices** (`yaml/20-production.yaml`):
```yaml
devices: devices:
# Production environment
!include environments/production.yaml
# Lab environment
!include environments/lab.yaml
```
**Production devices** (`environments/production.yaml`):
```yaml
# Production SR Linux switches
prod-asw100: prod-asw100:
user: netops user: netops
type: srlinux type: srlinux
@ -403,12 +430,23 @@ prod-asw120:
user: netops user: netops
type: srlinux type: srlinux
# Production EOS devices
prod-core-01: prod-core-01:
user: netops user: netops
type: eos type: eos
``` ```
**Usage examples:**
```bash
# Load all standard configs
ipng-router-backup --yaml yaml/*.yaml
# Load with environment-specific overrides
ipng-router-backup --yaml yaml/*.yaml --yaml overrides/emergency.yaml
# Load only specific environments
ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/20-production.yaml
```
### Integration with Git ### Integration with Git
```bash ```bash