router-backup/docs/DETAILS.md

# IPng Networks Router Backup - Detailed Documentation

## Overview

IPng Networks Router Backup is a SSH-based network device configuration backup tool written in Go. It connects to multiple network devices defined in YAML configuration files, executes commands via SSH, and saves the output to local files.

## Key Features

- **Multi-device support**: Backup multiple routers in a single run
- **Device type templates**: Define command sets per device type
- **Configuration merging**: Load and merge multiple YAML files using mergo
- **SSH config integration**: Uses `~/.ssh/config` for legacy device compatibility
- **Flexible authentication**: SSH agent, key files, or password authentication
- **Selective execution**: Target specific devices with `--host` flags
- **IPv6 support**: Automatic IPv6 address detection and proper formatting

## Configuration File Format

The tool uses YAML configuration files with two main sections: `types` and `devices`. Multiple YAML files can be loaded and merged automatically.

### Complete Example

**Device types** (`00-device-types.yaml`):
```yaml
types:
  srlinux:
    commands:
      - show version
      - show platform linecard
      - info flat from running

  eos:
    commands:
      - show version
      - show inventory
      - show running-config
```

**Main configuration** (`config.yaml`):
```yaml
devices:
  asw100:
    user: admin
    type: srlinux

  core-01:
    user: admin
    type: eos
    address: 192.168.1.100    # Override connection address

  ipv6-router:
    user: netops
    address: 2001:678:d78:500::    # IPv6 address support

  edge-router:
    user: operator
    commands:                      # Direct commands (no type)
      - show version
      - show ip route summary
```

### Configuration Fields

#### Types Section
- **`<type-name>`**: Device type name (e.g., `srlinux`, `eos`)
  - **`commands`**: Array of CLI commands to execute

#### Devices Section
- **`<hostname>`**: Device hostname (used for SSH config lookup and output filename)
  - **`user`** (required): SSH username
  - **`type`** (optional): Reference to a type definition
  - **`commands`** (optional): Direct command list (overrides type commands)
  - **`address`** (optional): IP address or hostname to connect to (overrides hostname)

### Configuration Merging

Files are merged automatically using mergo. Later files override earlier ones:

```bash
# Load multiple files - later files override earlier ones
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml --yaml overrides.yaml
```

## Command Line Usage

### Required Flags
- **`--yaml`**: Path to YAML configuration file(s) (can be repeated)

### Optional Flags
- **`--output-dir`**: Output directory (default: `/tmp`)
- **`--host`**: Specific hostname(s) to process (can be repeated)
- **`--password`**: SSH password
- **`--key-file`**: SSH private key file path
- **`--port`**: SSH port (default: `22`)

### Examples

```bash
# Basic usage
ipng-router-backup --yaml config.yaml

# Multiple files
ipng-router-backup --yaml 00-device-types.yaml --yaml config.yaml

# Specific devices only
ipng-router-backup --yaml config.yaml --host asw100 --host core-01

# Custom output directory
ipng-router-backup --yaml config.yaml --output-dir /backup/network

# With password authentication
ipng-router-backup --yaml config.yaml --password mypassword
```

## SSH Authentication

The tool supports multiple authentication methods in priority order:

### 1. SSH Agent (Recommended)
Automatically used when `SSH_AUTH_SOCK` is set:
```bash
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa
ipng-router-backup --yaml config.yaml
```

### 2. SSH Key File
```bash
# Explicit key file
ipng-router-backup --yaml config.yaml --key-file ~/.ssh/network_key

# Automatic detection from default locations:
# ~/.ssh/id_rsa, ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa
ipng-router-backup --yaml config.yaml
```

### 3. Password Authentication
```bash
ipng-router-backup --yaml config.yaml --password mypassword
```

## SSH Configuration Integration

The tool automatically reads `~/.ssh/config` for each host:

```bash
# ~/.ssh/config
Host old-switch*
  User admin
  Port 2222
  IdentityFile ~/.ssh/legacy_key
  KexAlgorithms +diffie-hellman-group1-sha1
  HostKeyAlgorithms +ssh-rsa

Host modern-router*
  User netops
  IdentityFile ~/.ssh/modern_key
```

**Supported options:** Hostname, Port, User, IdentityFile, KexAlgorithms, MACs, HostKeyAlgorithms

## Output Format

### File Naming
- Output files are named after the device hostname
- Device `asw100` → File `asw100`

### File Content
Each file contains all command outputs with headers:
```
## COMMAND: show version
Hostname             : asw100
Software Version     : v25.3.2
------------------------------------------------------------------------
## COMMAND: show platform linecard
+-------------+----+-------------+-------------------+
| Module Type | ID | Admin State | Operational State |
+=============+====+=============+===================+
| linecard    | 1  | N/A         | up                |
+-------------+----+-------------+-------------------+
```

## Error Handling

### Common Issues
- **Connection failures**: Check SSH connectivity and authentication
- **Configuration errors**: Validate YAML syntax and required fields
- **Permission issues**: Verify SSH key permissions (600) and output directory access

### Exit Codes
- `0`: Success
- `1`: Configuration error, authentication failure, or connection issues