dbf98e2f22
- 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
108 lines
2 KiB
Markdown
108 lines
2 KiB
Markdown
# 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
|
|
# 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`:
|
|
|
|
```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 <ID>
|
|
```
|
|
|
|
If expired, create a new one and update the secrets file.
|