# 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 a YAML configuration file, 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 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
- **Command identification**: Each command output prefixed with command name
- **Version synchronization**: Automatic version sync between package and binary

## Configuration File Format

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

**Main configuration** (`config.yaml`):
```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** (`00-device-types.yaml`):
```yaml
types:
  srlinux:
    commands:
      - show version
      - show platform linecard
      - 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
```

### Configuration Fields

#### Types Section

**`types`**: Define reusable command sets for different device types.

- **`<type-name>`**: Arbitrary name for the device type (e.g., `srlinux`, `eos`)
  - **`commands`**: Array of CLI commands to execute on devices of this type

#### Devices Section

**`devices`**: Define individual network devices to backup.

- **`<hostname>`**: Device hostname or IP address
  - **`user`** (required): SSH username for authentication
  - **`type`** (optional): Reference to a type definition for commands
  - **`commands`** (optional): Direct command list (overrides type commands)

### Configuration Validation

- Each device must have a `user` field
- Each device must have either a `type` field (referencing a valid type) or a `commands` field
- Type references must exist in the `types` section
- Commands can be specified either via type reference or directly per device

### Configuration Merging with Mergo

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/
├── 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. **Load multiple files with automatic merging:**
   ```bash
   ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/10-production.yaml
   ```

2. **Use wildcards for directory-based loading:**
   ```bash
   ipng-router-backup --yaml yaml/*.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

- **`--yaml`**: Path to YAML configuration file(s)

### Optional Flags

- **`--output-dir`**: Output directory for backup files (default: `/tmp`)
- **`--host`**: Specific hostname(s) to process (can be repeated)
- **`--password`**: SSH password for authentication
- **`--key-file`**: Path to SSH private key file
- **`--port`**: SSH port number (default: `22`)
- **`--help`**: Show help information
- **`--version`**: Show version information

### Flag Examples

```bash
# Basic usage - all devices
ipng-router-backup --yaml /etc/ipng-router-backup/*.yaml

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

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

# Multiple specific devices
ipng-router-backup --yaml *.yaml --host asw100 --host asw120 --host core-01

# Custom SSH port
ipng-router-backup --yaml *.yaml --port 2222

# Using password authentication
ipng-router-backup --yaml *.yaml --password mypassword

# Using specific SSH key
ipng-router-backup --yaml *.yaml --key-file ~/.ssh/network_key
```

## SSH Authentication Methods

The tool supports multiple SSH authentication methods in the following priority order:

### 1. SSH Agent (Highest Priority)

Automatically used when the `SSH_AUTH_SOCK` environment variable is set.

```bash
# Start SSH agent and add keys
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_rsa

# Run backup (will use SSH agent automatically)
ipng-router-backup --yaml *.yaml
```

**Advantages:**
- Most secure (keys remain in memory)
- No password prompts
- Works with hardware security modules
- Single sign-on experience

### 2. SSH Key File

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
# ~/.ssh/id_ecdsa
```

**Key File Requirements:**
- Must be in OpenSSH format
- 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.

```bash
# Command line password (not recommended for scripts)
ipng-router-backup --yaml *.yaml --password mypassword

# Interactive password prompt (when no other auth available)
ipng-router-backup --yaml *.yaml
# Output: "No SSH key found. Enter SSH password: "
```

**Security Considerations:**
- Passwords visible in process lists
- Not suitable for automation
- Consider using key-based authentication instead

## Output Format

### File Naming

Output files are named after the device hostname:
- Device `asw100` → File `asw100`
- Device `192.168.1.1` → File `192.168.1.1`

### File Content Structure

Each output file contains all command outputs with headers:

```
## COMMAND: show version
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Hostname             : asw100
Chassis Type         : 7220 IXR-D4
Software Version     : v25.3.2
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
## COMMAND: show platform linecard
+-------------+----+-------------+-------------------+---------------------------------+
| Module Type | ID | Admin State | Operational State |              Model              |
+=============+====+=============+===================+=================================+
| linecard    | 1  | N/A         | up                | imm28-100g-qsfp28+8-400g-qsfpdd |
+-------------+----+-------------+-------------------+---------------------------------+
```

### File Behavior

- **New runs**: Files are truncated and recreated
- **Multiple commands**: All outputs concatenated in single file
- **Command identification**: Each command prefixed with `## COMMAND: <command>`

## Usage Examples

### Basic Backup All Devices

```bash
ipng-router-backup --yaml /etc/backup/*.yaml --output-dir /backup/$(date +%Y%m%d)
```

### Backup Specific Device Types

Create a config with only the devices you want, or use `--host`:

```bash
# Backup only SR Linux devices
ipng-router-backup --yaml network.yaml --host asw100 --host asw120 --host asw121
```

### Scheduled Backup with SSH Agent

```bash
#!/bin/bash
# /etc/cron.daily/network-backup

# Start SSH agent
eval "$(ssh-agent -s)"
ssh-add /root/.ssh/network_backup_key

# Run backup
BACKUP_DIR="/backup/network/$(date +%Y%m%d)"
mkdir -p "$BACKUP_DIR"

ipng-router-backup \
  --yaml /etc/ipng-router-backup/*.yaml \
  --output-dir "$BACKUP_DIR"

# Kill SSH agent
ssh-agent -k
```

### Emergency Single Device Backup

```bash
# Quick backup of single device with password
ipng-router-backup \
  --yaml emergency.yaml \
  --host core-router-01 \
  --password emergency123 \
  --output-dir /tmp/emergency-backup
```

## Error Handling

### Common Issues and Solutions

**Device Connection Failures:**
- Check SSH connectivity: `ssh user@hostname`
- Verify authentication method
- Check firewall rules and network connectivity

**Configuration Errors:**
- Validate YAML syntax: `yamllint config.yaml`
- Check that all referenced types exist
- Ensure all devices have required fields

**Permission Issues:**
- Verify SSH key permissions (600)
- Check output directory write permissions
- Ensure user has SSH access to target devices

### Exit Codes

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

## Advanced Usage

### Configuration Organization with Mergo

For large deployments, organize configurations using multiple YAML files with automatic merging:

**Environment-based structure:**
```bash
network-backup/
├── 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
```

**Device types** (`yaml/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
```

**Production devices** (`yaml/20-production.yaml`):
```yaml
devices:
  prod-asw100:
    user: netops
    type: srlinux

  prod-asw120:
    user: netops
    type: srlinux

  prod-core-01:
    user: netops
    type: eos
```

**Usage examples:**
```bash
# Load all standard configs
ipng-router-backup --yaml yaml/*.yaml

# Load with environment-specific overrides
ipng-router-backup --yaml yaml/*.yaml --yaml overrides/emergency.yaml

# Load only specific environments
ipng-router-backup --yaml yaml/00-device-types.yaml --yaml yaml/20-production.yaml
```

### Integration with Git

```bash
#!/bin/bash
# Backup and commit to git repository

BACKUP_DIR="/backup/network-configs"
cd "$BACKUP_DIR"

# Run backup
ipng-router-backup --yaml config.yaml --output-dir .

# Commit changes
git add .
git commit -m "Network backup $(date '+%Y-%m-%d %H:%M:%S')"
git push origin main
```

### Custom Command Sets per Environment

```yaml
types:
  production-srlinux:
    commands:
      - show version
      - show system information
      - info flat from running

  lab-srlinux:
    commands:
      - show version
      - show interface brief

devices:
  prod-asw100:
    user: readonly
    type: production-srlinux

  lab-asw100:
    user: admin
    type: lab-srlinux
```

### Monitoring and Alerting

```bash
#!/bin/bash
# Backup with monitoring

if ipng-router-backup --yaml config.yaml --output-dir /backup; then
    echo "Backup completed successfully" | logger
else
    echo "Backup failed!" | logger
    # Send alert email
    echo "Network backup failed at $(date)" | mail -s "Backup Alert" admin@company.com
fi
```