add yaml include feature
This commit is contained in:
167
docs/DETAILS.md
167
docs/DETAILS.md
@ -8,6 +8,7 @@ IPng Networks Router Backup is a SSH-based network device configuration backup t
|
||||
|
||||
- **Multi-device support**: Backup multiple routers in a single run
|
||||
- **Device type templates**: Define command sets per device type
|
||||
- **Configuration includes**: Split large configurations with `!include` directives
|
||||
- **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
|
||||
@ -16,10 +17,35 @@ IPng Networks Router Backup is a SSH-based network device configuration backup t
|
||||
|
||||
## Configuration File Format
|
||||
|
||||
The tool uses a YAML configuration file with two main sections: `types` and `devices`.
|
||||
The tool uses a YAML configuration file with two main sections: `types` and `devices`. The configuration supports `!include` directives for organizing large configurations across multiple files.
|
||||
|
||||
### Complete Example
|
||||
|
||||
**Main configuration** (`config.yaml`):
|
||||
```yaml
|
||||
!include device-types.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** (`device-types.yaml`):
|
||||
```yaml
|
||||
types:
|
||||
srlinux:
|
||||
@ -29,39 +55,20 @@ types:
|
||||
- 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
|
||||
@ -89,6 +96,61 @@ devices:
|
||||
- Type references must exist in the `types` section
|
||||
- Commands can be specified either via type reference or directly per device
|
||||
|
||||
### Include Directive Support
|
||||
|
||||
The configuration supports `!include` directives for splitting large configurations into multiple files:
|
||||
|
||||
```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:**
|
||||
```
|
||||
/etc/ipng-router-backup/
|
||||
├── config.yaml # Main configuration with !include
|
||||
├── device-types.yaml # Device type definitions
|
||||
└── devices/
|
||||
├── production.yaml # Production device definitions
|
||||
└── lab.yaml # Lab device definitions
|
||||
```
|
||||
|
||||
**Usage patterns:**
|
||||
|
||||
1. **Include device types at top level:**
|
||||
```yaml
|
||||
!include device-types.yaml
|
||||
|
||||
devices:
|
||||
# device definitions here
|
||||
```
|
||||
|
||||
2. **Include under specific sections:**
|
||||
```yaml
|
||||
types:
|
||||
!include types/network-devices.yaml
|
||||
|
||||
devices:
|
||||
!include devices/production.yaml
|
||||
```
|
||||
|
||||
3. **Include files with spaces:**
|
||||
```yaml
|
||||
!include "device types/lab environment.yaml"
|
||||
```
|
||||
|
||||
## Command Line Flags
|
||||
|
||||
### Required Flags
|
||||
@ -109,7 +171,7 @@ devices:
|
||||
|
||||
```bash
|
||||
# Basic usage - all devices
|
||||
ipng-router-backup --config /etc/network-backup/config.yaml
|
||||
ipng-router-backup --config /etc/ipng-router-backup/config.yaml
|
||||
|
||||
# Custom output directory
|
||||
ipng-router-backup --config config.yaml --output-dir /backup/network
|
||||
@ -163,7 +225,7 @@ 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_ed25519
|
||||
# ~/.ssh/id_ecdsa
|
||||
```
|
||||
|
||||
@ -255,7 +317,7 @@ BACKUP_DIR="/backup/network/$(date +%Y%m%d)"
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
|
||||
ipng-router-backup \
|
||||
--config /etc/network-backup/config.yaml \
|
||||
--config /etc/ipng-router-backup/config.yaml \
|
||||
--output-dir "$BACKUP_DIR"
|
||||
|
||||
# Kill SSH agent
|
||||
@ -299,6 +361,55 @@ ipng-router-backup \
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Configuration Organization with Includes
|
||||
|
||||
For large deployments, organize configurations using `!include` directives:
|
||||
|
||||
**Environment-based structure:**
|
||||
```bash
|
||||
network-backup/
|
||||
├── config.yaml # Main config
|
||||
├── types/
|
||||
│ ├── device-types.yaml # All device types
|
||||
│ └── vendor-specific.yaml # Vendor-specific commands
|
||||
├── environments/
|
||||
│ ├── production.yaml # Production devices
|
||||
│ ├── staging.yaml # Staging devices
|
||||
│ └── lab.yaml # Lab devices
|
||||
└── sites/
|
||||
├── datacenter-east.yaml # East datacenter devices
|
||||
└── datacenter-west.yaml # West datacenter devices
|
||||
```
|
||||
|
||||
**Main configuration** (`config.yaml`):
|
||||
```yaml
|
||||
!include types/device-types.yaml
|
||||
|
||||
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:
|
||||
user: netops
|
||||
type: srlinux
|
||||
|
||||
prod-asw120:
|
||||
user: netops
|
||||
type: srlinux
|
||||
|
||||
# Production EOS devices
|
||||
prod-core-01:
|
||||
user: netops
|
||||
type: eos
|
||||
```
|
||||
|
||||
### Integration with Git
|
||||
|
||||
```bash
|
||||
@ -324,9 +435,9 @@ types:
|
||||
production-srlinux:
|
||||
commands:
|
||||
- show version
|
||||
- show system information
|
||||
- show system information
|
||||
- info flat from running
|
||||
|
||||
|
||||
lab-srlinux:
|
||||
commands:
|
||||
- show version
|
||||
@ -336,7 +447,7 @@ devices:
|
||||
prod-asw100:
|
||||
user: readonly
|
||||
type: production-srlinux
|
||||
|
||||
|
||||
lab-asw100:
|
||||
user: admin
|
||||
type: lab-srlinux
|
||||
|
||||
@ -5,64 +5,29 @@
|
||||
# Copy this file to a location of your choice and modify for your environment.
|
||||
#
|
||||
# Usage: ipng-router-backup --config /path/to/your/config.yaml
|
||||
#
|
||||
# YAML !include Support:
|
||||
# You can split large configurations into multiple files using !include directives.
|
||||
# Examples:
|
||||
# !include device-types.yaml
|
||||
# !include devices/production.yaml
|
||||
# !include "devices/lab environment.yaml" # Use quotes for paths with spaces
|
||||
|
||||
# Device Types Section
|
||||
# Define reusable command sets for different types of network equipment
|
||||
types:
|
||||
# Nokia SR Linux devices
|
||||
srlinux:
|
||||
commands:
|
||||
- show version # System version and build info
|
||||
- show platform linecard # Line card information
|
||||
- show platform fan-tray # Fan status and health
|
||||
- show platform power-supply # Power supply status
|
||||
- info flat from running # Full running configuration
|
||||
# Include device types from separate file
|
||||
!include device-types.yaml
|
||||
|
||||
# Arista EOS devices
|
||||
eos:
|
||||
commands:
|
||||
- show version # System version information
|
||||
- show inventory # Hardware inventory
|
||||
- show env power # Power supply status
|
||||
- show running-config # Complete running configuration
|
||||
|
||||
# Centec switches
|
||||
centec:
|
||||
commands:
|
||||
- show version | exc uptime # Version info without uptime line
|
||||
- show boot images # Boot image information
|
||||
- show transceiver # SFP/transceiver status
|
||||
- show running-config # Running configuration
|
||||
|
||||
# Cisco IOS/IOS-XE devices
|
||||
cisco-ios:
|
||||
commands:
|
||||
- show version # IOS version and hardware info
|
||||
- show inventory # Hardware inventory details
|
||||
- show running-config # Complete configuration
|
||||
- show ip interface brief # Interface IP summary
|
||||
- show cdp neighbors # CDP neighbor information
|
||||
|
||||
# Juniper devices
|
||||
junos:
|
||||
commands:
|
||||
- show version # Software and hardware version
|
||||
- show chassis hardware # Chassis hardware details
|
||||
- show configuration | display set # Configuration in set format
|
||||
- show interfaces terse # Interface status summary
|
||||
|
||||
# Devices Section
|
||||
# Devices Section
|
||||
# Define individual network devices to backup
|
||||
devices:
|
||||
# Core switches (SR Linux)
|
||||
asw100:
|
||||
user: admin # SSH username
|
||||
type: srlinux # Reference to type above
|
||||
|
||||
|
||||
asw120:
|
||||
user: netops # Different user per device if needed
|
||||
type: srlinux
|
||||
|
||||
|
||||
asw121:
|
||||
user: admin
|
||||
type: srlinux
|
||||
@ -71,16 +36,16 @@ devices:
|
||||
csw150:
|
||||
user: admin
|
||||
type: centec
|
||||
|
||||
|
||||
csw151:
|
||||
user: admin
|
||||
user: admin
|
||||
type: centec
|
||||
|
||||
# Edge routers (Arista EOS)
|
||||
edge-01:
|
||||
user: automation
|
||||
type: eos
|
||||
|
||||
|
||||
edge-02:
|
||||
user: automation
|
||||
type: eos
|
||||
@ -100,7 +65,7 @@ devices:
|
||||
type: cisco-ios
|
||||
|
||||
# Configuration Tips:
|
||||
#
|
||||
#
|
||||
# 1. Authentication Priority (automatic):
|
||||
# - SSH Agent (if SSH_AUTH_SOCK environment variable is set)
|
||||
# - SSH Key file (--key-file flag or default locations)
|
||||
@ -109,10 +74,10 @@ devices:
|
||||
# 2. Running the backup:
|
||||
# # Backup all devices
|
||||
# ipng-router-backup --config /etc/ipng-router-backup/config.yaml
|
||||
#
|
||||
# # Backup specific devices only
|
||||
#
|
||||
# # Backup specific devices only
|
||||
# ipng-router-backup --config config.yaml --host asw100 --host edge-01
|
||||
#
|
||||
#
|
||||
# # Custom output directory
|
||||
# ipng-router-backup --config config.yaml --output-dir /backup/$(date +%Y%m%d)
|
||||
#
|
||||
@ -130,4 +95,4 @@ devices:
|
||||
# 5. Error handling:
|
||||
# - If a device is unreachable, the tool continues with other devices
|
||||
# - Check tool output for connection or authentication failures
|
||||
# - Use --host flag to test individual devices
|
||||
# - Use --host flag to test individual devices
|
||||
Reference in New Issue
Block a user