# DebTik Full Configuration Backup & Restore

## Overview
DebTik includes a native **Full Configuration Backup & Disaster Recovery** system designed to export and restore the complete router appliance state into a single, portable `.zip` archive.

All router subsystem configurations, cryptographic credentials, network interfaces, and user databases are captured and restored atomically with automated fallback safety backups.

---

## Architecture & Archive Structure

A DebTik backup archive is a standard ZIP archive containing:
```
manifest.json
debtik/
  metadata.json                  # Interface metadata & roles
  services.json                  # Management services (SSH, Telnet, Web, etc.)
  users.json                     # System user accounts & roles (0600)
  reverse_proxy.json             # Reverse Proxy engine rules & upstreams
  bwtest.json                    # Bandwidth test settings
  bridge.json                    # Linux bridges & ports
  dhcp_clients.json              # DHCP client WAN configurations
  dhcp_server.json               # Local DHCP server pools & leases
  vrrp.json                      # VRRP virtual router instances
  ssh_host_ed25519_key           # Appliance SSH host private key (0600)
  dns/settings.json              # DNS forwarders & static cache
  routing/                       # Static routes, policy routing & BIRD dynamic routing
  vpn/                           # WireGuard, AeroTUN, PPPoE, L2TP, IPsec tunnels & secrets
  firewall/                      # Netfilter filter, NAT, mangle rules & GeoIP sets
  certs/                         # SSL/TLS certificates, CA chains, and private keys (0600)
network/
  interfaces.cfg                 # Debian /etc/network/interfaces.d/ interfaces
  vlans.cfg                      # Debian /etc/network/interfaces.d/ VLAN configurations
```

### Manifest Metadata (`manifest.json`)
The archive contains a root `manifest.json` file recording:
- `version`: Backup format specification version (`1.0`).
- `debtik_version`: DebTik controller release version (e.g. `1.6.0`).
- `hostname`: Router hostname at backup creation.
- `created_at`: UTC RFC3339 timestamp.
- `comment`: User-provided description or maintenance note.
- `files`: File list with relative paths, sizes, permission modes, and SHA-256 checksums.

---

## Security & Safety Safeguards

1. **Zip Slip Protection**:
   Strict path canonicalization prevents directory traversal attacks. Entries containing `..`, absolute paths, or unapproved prefixes are rejected immediately before extraction.
2. **Automated Pre-Restore Fallback Snapshot**:
   Before any restore operation modifies active router files, the system automatically creates a timestamped safety backup in `/var/lib/debtik/backups/pre-restore-<hostname>-<timestamp>.zip`. The latest 5 pre-restore backups are retained automatically.
3. **Permission Clamping**:
   Sensitive files (SSH private keys, user databases, TLS private keys, PPP secrets) are guaranteed `0600` permissions upon extraction regardless of external file permissions.
4. **Clean Synchronization**:
   Old or obsolete configuration files in `/etc/debtik` are cleanly pruned during restoration to ensure the router exactly matches the state of the restored snapshot without orphaned artifacts.
5. **Role-Based Access Control**:
   Backup export, inspection, and restoration require full administrator privileges (`auth.RoleFull`).

---

## RouterOS CLI Commands

### 1. Save Backup
```text
/system backup save [name=<filename.zip>] [comment="<note>"]
```
Example:
```text
/system backup save comment="Pre-upgrade snapshot"
```

### 2. Print Local Backups
```text
/system backup print
```
Example output:
```text
#   NAME                                       SIZE       CREATED              COMMENT
0   pre-restore-DebTik-20261102-150221.zip     142.5 KB   2026-11-02 15:02:21  Automatic pre-restore safety fallback
1   debtik-backup-DebTik-20261102-140000.zip   141.8 KB   2026-11-02 14:00:00  Pre-upgrade snapshot
```

### 3. Load / Restore Backup
```text
/system backup load name=<filename.zip>
```
Example:
```text
/system backup load name=debtik-backup-DebTik-20261102-140000.zip
```
Restores the configuration, creates a pre-restore fallback, and restarts the DebTik controller.

---

## REST API Endpoints

| Method | Endpoint | Description |
|---|---|---|
| `GET` | `/api/system/backup/export?comment=...` | Download full backup as `.zip` attachment |
| `POST` | `/api/system/backup/inspect` | Inspect uploaded archive and return `manifest.json` metadata |
| `POST` | `/api/system/backup/restore` | Upload and restore archive, automatically taking safety backup and reloading DebTik |
| `GET` | `/api/system/backups` | List local backups stored in `/var/lib/debtik/backups` |
| `GET` | `/api/system/backups/{filename}` | Download a local backup file |
| `POST` | `/api/system/backups/{filename}/restore` | Restore from a local backup file |

---

## Web UI

Navigate to **Settings** (`#settings`) -> **Backup & Restore**:
1. **Export Configuration Backup**: Enter an optional note and click **Download Backup (.zip)**.
2. **Restore Configuration**: Drag & drop or select a `.zip` archive. The UI automatically inspects and verifies the archive metadata (hostname, version, creation date, file count) before displaying a confirmation modal. Click **Yes, Restore & Reload** to apply.
3. **Stored Safety Fallback Backups**: View the history of pre-restore fallback snapshots, download them, or one-click restore them.