Headscale

The following third-party tools, client libraries, and scripts are maintained by the community and are not officially supported by the headscale authors:

• Kubernetes Management: headscale-operator (Headscale Kubernetes Operator).
• Routing: tailscale-manager (Dynamically manage Tailscale route advertisements).
• Database Migration: headscalebacktosqlite (Migrate headscale from PostgreSQL back to SQLite).
• Identity & Group Management: headscale-pf (Populates user groups based on user groups in Jumpcloud or Authentik).
• Development: headscale-client-go (A Go client implementation for the Headscale HTTP API).
• Monitoring:
  • headscale-zabbix (A Zabbix Monitoring Template for the Headscale Service).
  • tailscale-exporter (A Prometheus exporter for Headscale that provides network-level metrics using the Headscale API).

Headscale aims to support the last 10 releases of the Tailscale client across all supported operating systems. While most platforms work out of the box, some require specific configurations to connect to a Headscale server.

Supported Operating Systems

Tailscale clients use a custom protocol that requires the reverse proxy to support WebSockets with two specific requirements:

1. The POST method must be used to upgrade the WebSocket connection.
2. The Upgrade header value must be tailscale-control-protocol.

If your proxy only supports standard WebSocket upgrades, the Tailscale Control Protocol will fail.

When using variables across multiple EventuallyWithT blocks, you must declare them at the function scope. Inside the block, use the assignment operator = instead of the short declaration operator :=. Using := inside the block creates a shadowed variable that is invisible to the outer scope.

var nodes []*v1.Node
var err error
assert.EventuallyWithT(t, func(c *assert.CollectT) {
    nodes, err = headscale.ListNodes()   // Use = not :=
    assert.NoError(c, err)
    assert.Len(c, nodes, 2)
}, 10*time.Second, 500*time.Millisecond, "nodes should have expected routes")

// nodes is accessible here because it was declared at function scope

Headscale supports two ACME challenge types for Let's Encrypt validation:

HTTP-01 (Default)

Headscale must be reachable on port 80 for automated validation. By default, Headscale listens on port 80 on all local IPs for this purpose.

If you are running Headscale as a non-root user and cannot use setcap, you can change the validation address using tls_letsencrypt_listen. However, you must then configure a firewall or proxy to forward traffic from port 80 to the address specified in tls_letsencrypt_listen.

TLS-ALPN-01

Headscale listens for validation on the IP:port combination defined in listen_addr. Let's Encrypt will only connect to port 443 for the validation callback. If your listen_addr is not port 443, you must use a firewall rule or proxy to forward traffic from port 443 to your listen_addr.

Headscale provides endpoints to introspect the Go runtime, memory usage, connected nodes, pending registrations, active policies (including SSH), the current DERPMap, and Prometheus metrics.

• Metrics: http://localhost:9090/metrics (default)
• Debug Overview: http://localhost:9090/debug/ (default)

Security Warning

Keep these endpoints private. By default, they listen on localhost:9090. Do not expose them to the public internet.

• To change the address/port, use metrics_listen_addr in the configuration file.
• To disable the endpoints completely, set metrics_listen_addr: null.

DERP access can be restricted to nodes belonging to your Tailnet.

Embedded DERP

Client verification is enabled by default for the embedded server. You can explicitly set it in config.yaml:

derp:
  server:
    verify_clients: true

3rd-party DERP

If you are running a standalone Tailscale derper instance, you can configure it to verify clients against Headscale:

• Use the -verify-client-url flag pointing to your Headscale /verify endpoint (e.g., https://headscale.example.com/verify).
• Use the -verify-client-url-fail-open flag to control behavior when the Headscale instance is unreachable. By default, it allows access if Headscale is unreachable.

Community packages for various Linux distributions often provide improved OS integration, such as:

• Setting up a dedicated local user account to run headscale
• Providing a default configuration
• Installing headscale as a system service

Warning: Community packages might be outdated or unmaintained. If you require the current stable version or wish to test pre-releases, use the official releases.