# 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 includes**: Split large configurations with `!include` directives
- **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 a YAML configuration file with two main sections: `types` and `devices`. The configuration supports `!include` directives for organizing large configurations across multiple files.

### Complete Example

**Main configuration** (`config.yaml`):
```yaml
!include device-types.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** (`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

### Include Directive Support

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

**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
```

**Usage patterns:**

1. **Include device types at top level:**
   ```yaml
   !include device-types.yaml

   devices:
     # device definitions here
   ```

2. **Include under specific sections:**
   ```yaml
   types:
     !include types/network-devices.yaml

   devices:
     !include devices/production.yaml
   ```

3. **Include files with spaces:**
   ```yaml
   !include "device types/lab environment.yaml"
   ```

## Command Line Flags

### Required Flags

- **`--config`**: Path to YAML configuration file

### 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 --config /etc/ipng-router-backup/config.yaml

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

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

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

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

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

# Using specific SSH key
ipng-router-backup --config config.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 --config config.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` or use default locations.

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

# 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

### 3. Password Authentication (Lowest Priority)

Use `--password` flag for password-based authentication.

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

# Interactive password prompt (when no other auth available)
ipng-router-backup --config config.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 --config /etc/backup/network.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 --config 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 \
  --config /etc/ipng-router-backup/config.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 \
  --config 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 Includes

For large deployments, organize configurations using `!include` directives:

**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
```

**Main configuration** (`config.yaml`):
```yaml
!include types/device-types.yaml

devices:
  # Production environment
  !include environments/production.yaml

  # Lab environment
  !include environments/lab.yaml
```

**Production devices** (`environments/production.yaml`):
```yaml
# Production SR Linux switches
prod-asw100:
  user: netops
  type: srlinux

prod-asw120:
  user: netops
  type: srlinux

# Production EOS devices
prod-core-01:
  user: netops
  type: eos
```

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