steffen dbf98e2f22 add .gitignore, fix headscale CLI to use numeric user IDs

- Add .gitignore for nix build result symlinks
- Fix all headscale CLI commands: --user now requires numeric ID,
  not username (changed in newer headscale versions)
- Add 'headscale users list' step to docs where preauth keys are created

2026-03-14 12:28:47 +01:00

2 KiB

Raw Blame History

Headplane

Headplane is a web-based admin interface for Headscale.

References

GitHub

Setup

DNS

Set a CNAME record for headplane.cryodev.xyz pointing to your main domain.

Generate Secrets

Cookie Secret (for session management):

nix-shell -p openssl --run 'openssl rand -hex 16'

Agent Pre-Auth Key (for Headplane's built-in agent):

# First, create a dedicated user
sudo headscale users create headplane-agent
# Find the user ID
sudo headscale users list
# Then create a reusable pre-auth key (use the ID of headplane-agent)
sudo headscale preauthkeys create --expiration 99y --reusable --user <ID>

Add to Secrets

Edit hosts/cryodev-main/secrets.yaml:

sops hosts/cryodev-main/secrets.yaml

headplane:
  cookie_secret: "your-generated-hex-string"
  agent_pre_authkey: "your-preauth-key"

Configuration

# hosts/cryodev-main/services/headplane.nix
{ config, ... }:
{
  sops.secrets."headplane/cookie_secret" = { };
  sops.secrets."headplane/agent_pre_authkey" = { };
  
  services.headplane = {
    enable = true;
    settings = {
      server = {
        cookie_secret_file = config.sops.secrets."headplane/cookie_secret".path;
      };
      headscale = {
        url = "https://headscale.cryodev.xyz";
      };
      agent = {
        enable = true;
        authkey_file = config.sops.secrets."headplane/agent_pre_authkey".path;
      };
    };
  };
}

Usage

Access Headplane at https://headplane.cryodev.xyz.

Features

View and manage users
View connected nodes
Manage routes and exit nodes
View pre-auth keys

Troubleshooting

Check Service Status

sudo systemctl status headplane

View Logs

sudo journalctl -u headplane -f

Agent Not Connecting

Verify the agent pre-auth key is valid:

sudo headscale preauthkeys list --user <ID>

If expired, create a new one and update the secrets file.

2 KiB Raw Blame History