# Headplane

Headplane is a web-based admin interface for Headscale.

## References

- [GitHub](https://github.com/tale/headplane)

## Setup

### DNS

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

### Generate Secrets

**Cookie Secret** (for session management):

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

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

```bash
# First, create a dedicated user
sudo headscale users create headplane-agent

# Then create a reusable pre-auth key
sudo headscale preauthkeys create --expiration 99y --reusable --user headplane-agent
```

### Add to Secrets

Edit `hosts/cryodev-main/secrets.yaml`:

```bash
sops hosts/cryodev-main/secrets.yaml
```

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

### Configuration

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

```bash
sudo systemctl status headplane
```

### View Logs

```bash
sudo journalctl -u headplane -f
```

### Agent Not Connecting

Verify the agent pre-auth key is valid:

```bash
sudo headscale preauthkeys list --user headplane-agent
```

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