Update docs

2025-07-06 17:17:45 +02:00
parent e5f9e59601
commit a3d681e420
2 changed files with 157 additions and 94 deletions
--- 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