Running the service via TLS (optional)¶
Bring your own certificate¶
Headscale can be configured to expose its web service via TLS. To configure the certificate and key file manually, set the tls.cert_path and tls.key_path configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
The certificate should contain the full chain, else some clients, like the Tailscale Android client, will reject it.
Let's Encrypt / ACME¶
To get a certificate automatically via Let's Encrypt, set tls.acme.hostname to the desired certificate hostname. This name must resolve to the IP address(es) headscale is reachable on (i.e., it must correspond to the server_url configuration parameter). The certificate and Let's Encrypt account credentials will be stored in the directory configured in tls.acme.cache_dir. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
tls:
acme:
hostname: ""
http_listen: ":http"
cache_dir: /var/lib/headscale/cache
challenge_type: HTTP-01
Challenge types¶
Headscale supports three values for tls.acme.challenge_type: HTTP-01 (default), TLS-ALPN-01 and DNS-01. DNS-01 publishes the challenge through the DNS provider in dns.challenge.provider.
HTTP-01¶
For HTTP-01, headscale must be reachable on port 80 for the Let's Encrypt automated validation, in addition to whatever port is configured in listen_addr. By default, headscale listens on port 80 on all local IPs for Let's Encrypt automated validation.
listen_addr cannot also be port 80
listen_addr and tls.acme.http_listen must not bind the same TCP socket. A common mistake is setting listen_addr: 0.0.0.0:80 together with tls.acme.hostname — both endpoints try to claim port 80, and the second bind fails with address already in use even though no other process is involved. Headscale validates this at startup and refuses to launch with a Fatal config error: listen_addr and tls.acme.http_listen would bind the same TCP socket message. Use listen_addr: 0.0.0.0:443 (or any non-80 port) when HTTP-01 is enabled.
If you need to change the ip and/or port used by headscale for the Let's Encrypt validation process, set tls.acme.http_listen to the appropriate value. This can be handy if you are running headscale as a non-root user (or can't run setcap). Keep in mind, however, that Let's Encrypt will only connect to port 80 for the validation callback, so if you change tls.acme.http_listen you will also need to configure something else (e.g. a firewall rule) to forward the traffic from port 80 to the ip:port combination specified in tls.acme.http_listen.
TLS-ALPN-01¶
For TLS-ALPN-01, headscale listens on the ip:port combination defined in listen_addr. Let's Encrypt will only connect to port 443 for the validation callback, so if listen_addr is not set to port 443, something else (e.g. a firewall rule) will be required to forward the traffic from port 443 to the ip:port combination specified in listen_addr.
Technical description¶
Headscale uses CertMagic, a Golang library providing ACME protocol verification, to facilitate certificate renewals via Let's Encrypt. Certificates will be renewed automatically, and the following can be expected:
- Certificates provided from Let's Encrypt have a validity of 3 months from date issued.
- Renewals start when a third of the validity remains.
- Renewal checks run every 10 minutes.
- Log lines from the library are logged with
logger=acme.
Checking certificate expiry¶
If you want to validate that certificate renewal completed successfully, this can be done either manually, or through external monitoring software. Two examples of doing this manually:
- Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
- Or, check remotely from CLI using
openssl: