This page covers common configuration steps for Headscale deployments and adds a practical minimal production baseline.
Typical config file location:
/etc/headscale/config.yaml
config.yaml Baselineserver_url: https://headscale.example.com
listen_addr: 0.0.0.0:8080
metrics_listen_addr: 127.0.0.1:9090
private_key_path: /var/lib/headscale/private.key
noise:
private_key_path: /var/lib/headscale/noise_private.key
ip_prefixes:
v4: 100.64.0.0/10
v6: fd7a:115c:a1e0::/48
derp:
server:
enabled: false
urls:
- https://controlplane.tailscale.com/derpmap/default
auto_update_enabled: true
update_frequency: 24h
dns_config:
override_local_dns: true
nameservers:
- 1.1.1.1
- 9.9.9.9
db_type: sqlite3
db_path: /var/lib/headscale/db.sqlite
acl_policy_path: /etc/headscale/acl.hujson
log:
level: info
format: text
server_url)ip_prefixes)derp)dns_config)db_type, db_path)acl_policy_path)server_url; changing it later can break client trust/registration flows.ip_prefixes consistent once clients are enrolled.acl.hujson){
"groups": {
"group:admins": ["alice@example.com"]
},
"acls": [
{
"action": "accept",
"src": ["group:admins"],
"dst": ["*:*" ]
}
]
}
Restart Headscale after config updates:
sudo systemctl restart headscale
Check service health and node visibility:
sudo systemctl status headscale
sudo headscale nodes list
sudo headscale users list
Validate config and policy files in your deployment workflow before reload.
headscale binary and clients on compatible versions./var/lib/headscale and ACL policy files regularly.