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
|
||||
|
||||
Reference in New Issue
Block a user