# 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

  routeros:
    commands:
      - system package print detail without-paging
      - / export terse
    exclude:
      - "^# ....-..-.. ..:..:.. by RouterOS"    # Filter timestamp headers
      - "^# .../../.... ..:..:.. by RouterOS"   # Alternative date format
```

**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
  - **`exclude`** (optional): Array of regex patterns to filter out unwanted lines from output

#### 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

# Load files using glob patterns
ipng-router-backup --yaml "*.yaml"
ipng-router-backup --yaml "config/*.yaml"
```

## Output Filtering

The tool supports filtering unwanted lines from command output using regular expressions in the `exclude` field of device types.

### How Exclude Patterns Work

- **Regex matching**: Each line of command output is tested against all exclude patterns
- **Line removal**: Lines matching any pattern are completely removed from the output file
- **Per-device type**: Exclude patterns are defined at the device type level and apply to all devices of that type

### Common Use Cases

```yaml
types:
  routeros:
    commands:
      - / export terse
    exclude:
      - "^# ....-..-.. ..:..:.. by RouterOS"    # Remove timestamp headers
      - "^# .../../.... ..:..:.. by RouterOS"   # Alternative date format

  cisco-ios:
    commands:
      - show running-config
    exclude:
      - "^Building configuration"               # Remove config build messages
      - "^Current configuration"                # Remove current config headers
      - "^!"                                   # Remove comment lines

  debug-device:
    commands:
      - show logs
    exclude:
      - "^DEBUG:"                             # Filter debug messages
      - "^TRACE:"                             # Filter trace messages
```

## Command Line Usage

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

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

### Examples

```bash
# Basic usage with glob patterns
ipng-router-backup --yaml "*.yaml"

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

# Devices matching patterns
ipng-router-backup --yaml config.yaml --host "asw*" --host "*switch*"

# 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 (all devices processed successfully)
- `1`: Configuration error, authentication failure, or connection issues
- `10`: Some devices failed
- `11`: All devices failed