66 lines
2.4 KiB
Markdown
66 lines
2.4 KiB
Markdown
# Headscale
|
|
|
|
Headscale is an open-source, self-hosted implementation of the Tailscale control plane. It lets you run your own private WireGuard-based mesh VPN using the Tailscale client.
|
|
|
|
## Configuration
|
|
|
|
Key settings in `config.yaml`:
|
|
|
|
- **domain** - Where the Headscale control plane API is accessible
|
|
- **vpnBaseDomain** - Base domain for MagicDNS hostnames assigned to nodes (default: `vpn.{your-cloud-domain}`)
|
|
- **storage** - Persistent volume size (default: `2Gi`)
|
|
|
|
## First-Time Setup
|
|
|
|
1. Add and deploy the app:
|
|
```bash
|
|
wild app add headscale
|
|
wild app deploy headscale
|
|
```
|
|
|
|
2. Create a user (namespace) in Headscale:
|
|
```bash
|
|
kubectl exec -n headscale deploy/headscale -- headscale users create <username>
|
|
```
|
|
|
|
3. Generate a pre-auth key for that user:
|
|
```bash
|
|
kubectl exec -n headscale deploy/headscale -- headscale preauthkeys create --user <user-id> --reusable --expiration 24h
|
|
```
|
|
Note: `--user` requires the numeric user ID, not the username. Run `headscale users list` to get the ID.
|
|
|
|
4. On each device you want to join the VPN, install the Tailscale client and connect it to your Headscale instance:
|
|
```bash
|
|
tailscale up --login-server https://<your-headscale-domain> --authkey <preauthkey>
|
|
```
|
|
|
|
## Registering Nodes via Browser Auth
|
|
|
|
If a Tailscale client connects without a pre-auth key, it shows an auth URL in its logs. Register that node with:
|
|
```bash
|
|
kubectl exec -n headscale deploy/headscale -- headscale nodes register --auth-id <hskey-authreq-XXXX> --user <username>
|
|
```
|
|
Note: `--user` here accepts the username string (not the numeric ID).
|
|
|
|
## Useful Commands
|
|
|
|
```bash
|
|
# List users
|
|
kubectl exec -n headscale deploy/headscale -- headscale users list
|
|
|
|
# List connected nodes
|
|
kubectl exec -n headscale deploy/headscale -- headscale nodes list
|
|
|
|
# Create a pre-auth key (requires numeric user ID)
|
|
kubectl exec -n headscale deploy/headscale -- headscale preauthkeys create --user <id> --reusable
|
|
|
|
# Delete a node
|
|
kubectl exec -n headscale deploy/headscale -- headscale nodes delete --identifier <node-id>
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Headscale uses SQLite by default — no external database dependency
|
|
- Configuration is managed via a ConfigMap (`headscale-config`) — changes require restarting the pod
|
|
- In Headscale v0.29+, different commands accept different user identifier types: `preauthkeys` and `users destroy` require the numeric ID, while `nodes register` accepts the username string
|