diff --git a/README.md b/README.md index ddd26d7..b407e15 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,11 @@ SSH-based network device configuration backup tool with support for multiple dev ## 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 -- **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 @@ -24,18 +26,7 @@ make build 1. **Create configuration files**: - **Main config** (`config.yaml`): - ```yaml - devices: - asw100: - user: netops - type: srlinux - asw120: - user: netops - type: srlinux - ``` - - **Device types** (`00-device-types.yaml`): + **Device types** (`yaml/00-device-types.yaml`): ```yaml types: srlinux: @@ -43,16 +34,34 @@ make build - show version - show platform linecard - 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**: ```bash -# Backup all devices -ipng-router-backup --yaml *.yaml --output-dir /backup +# Backup all devices (multiple YAML files are automatically merged) +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 -ipng-router-backup --yaml *.yaml --host asw100 --output-dir /backup +ipng-router-backup --yaml yaml/*.yaml --host asw100 --output-dir /backup ``` 3. **Check output**: @@ -73,9 +82,25 @@ cat /backup/asw100 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) +2. **SSH Key File** (`--key-file` or from `~/.ssh/config`) 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 - **[Detailed Documentation](docs/DETAILS.md)** - Complete feature guide, configuration reference, and examples diff --git a/docs/DETAILS.md b/docs/DETAILS.md index 92a6beb..d68a40e 100644 --- a/docs/DETAILS.md +++ b/docs/DETAILS.md @@ -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 - **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 - **Selective execution**: Target specific devices with `--host` flags - **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 -The tool uses a YAML configuration file with two main sections: `types` and `devices`. The -configuration reading multiple files with the `--yaml` flag, merging their contents along the way. +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. ### Complete Example @@ -95,61 +95,48 @@ types: - Type references must exist in the `types` section - 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: - -```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 +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: **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 +├── yaml/ +│ ├── 00-device-types.yaml # Device type definitions (loaded first) +│ ├── 10-production.yaml # Production device definitions +│ ├── 20-staging.yaml # Staging device definitions +│ └── 99-overrides.yaml # Environment-specific overrides +└── config.yaml # Simple single-file config ``` **Usage patterns:** -1. **Include device types at top level:** - ```yaml - !include device-types.yaml - - devices: - # device definitions here +1. **Load multiple files with automatic merging:** + ```bash + ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/10-production.yaml ``` -2. **Include under specific sections:** - ```yaml - types: - !include types/network-devices.yaml - - devices: - !include devices/production.yaml +2. **Use wildcards for directory-based loading:** + ```bash + ipng-router-backup --yaml yaml/*.yaml ``` -3. **Include files with spaces:** - ```yaml - !include "device types/lab environment.yaml" +3. **Override configurations per environment:** + ```bash + # 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 ### Required Flags @@ -216,12 +203,15 @@ ipng-router-backup --yaml *.yaml ### 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 # Explicit key file 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: # ~/.ssh/id_rsa # ~/.ssh/id_ed25519 @@ -233,6 +223,39 @@ ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key - Proper permissions (600 recommended) - 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) Use `--password` flag for password-based authentication. @@ -360,53 +383,68 @@ ipng-router-backup \ ## 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:** ```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 +├── yaml/ +│ ├── 00-device-types.yaml # All device types (loaded first) +│ ├── 10-common.yaml # Common settings +│ ├── 20-production.yaml # Production devices +│ ├── 30-staging.yaml # Staging devices +│ ├── 40-lab.yaml # Lab devices +│ ├── 50-east-datacenter.yaml # East datacenter devices +│ └── 60-west-datacenter.yaml # West datacenter devices +└── overrides/ + ├── emergency.yaml # Emergency override settings + └── maintenance.yaml # Maintenance mode settings ``` -**Main configuration** (`config.yaml`): +**Device types** (`yaml/00-device-types.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: - # Production environment - !include environments/production.yaml + prod-asw100: + user: netops + type: srlinux - # Lab environment - !include environments/lab.yaml + prod-asw120: + user: netops + type: srlinux + + prod-core-01: + user: netops + type: eos ``` -**Production devices** (`environments/production.yaml`): -```yaml -# Production SR Linux switches -prod-asw100: - user: netops - type: srlinux +**Usage examples:** +```bash +# Load all standard configs +ipng-router-backup --yaml yaml/*.yaml -prod-asw120: - user: netops - type: srlinux +# Load with environment-specific overrides +ipng-router-backup --yaml yaml/*.yaml --yaml overrides/emergency.yaml -# Production EOS devices -prod-core-01: - user: netops - type: eos +# Load only specific environments +ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/20-production.yaml ``` ### Integration with Git