headscale-backup

Overview

Headscale state is stored in SQLite (its database), config.yaml, policy.json, and TLS certificates. Regular backups are critical before upgrades, as database corruption or misconfiguration can result in complete loss of node registration and routing state. This skill provides three scripts covering the full lifecycle: backup, restore, and migration.

Backup Contents

A complete backup tarball includes:

• SQLite DB — Full node state, users, routes, pre-auth keys, API keys
• config.yaml — Headscale server configuration
• policy.json — ACL policy file (if present)
• Certs and keys — TLS certificate, private key, and node private key (/var/lib/headscale/)
• DERP map — DERP configuration file (if customized)

Backup Methods