mirror of
https://github.com/juanfont/headscale.git
synced 2024-12-20 19:09:07 +01:00
8c7d8ee34f
* Setup mkdocs-redirects * Restructure existing documentation * Move client OS support into the documentation * Move existing Client OS support table into its own documentation page * Link from README.md to the rendered documentation * Document minimum Tailscale client version * Reuse CONTRIBUTING.md" in the documentation * Include "CONTRIBUTING.md" from the repository root * Update FAQ and index page and link to the contributing docs * Add configuration reference * Add a getting started page and explain the first steps with headscale * Use the existing "Using headscale" sections and combine them into a single getting started guide with a little bit more explanation. * Explain how to get help from the command line client. * Remove duplicated sections from existing installation guides * Document requirements and assumptions * Document packages provided by the community * Move deb install guide to official releases * Move manual install guide to official releases * Move container documentation to setup section * Move sealos documentation to cloud install page * Move OpenBSD docs to build from source * Simplify DNS documentation * Add sponsor page * Add releases page * Add features page * Add help page * Add upgrading page * Adjust mkdocs nav * Update wording Use the term headscale for the project, Headscale on the beginning of a sentence and `headscale` when refering to the CLI. * Welcome to headscale * Link to existing documentation in the FAQ * Remove the goal header and use the text as opener * Indent code block in OIDC * Make a few pages linter compatible Also update ignored files for prettier * Recommend HTTPS on port 443 Fixes: #2164 * Use hosts in acl documentation thx @efficacy38 for noticing this Ref: #1863 * Use mkdocs-macros to set headscale version once
77 lines
4.4 KiB
Markdown
77 lines
4.4 KiB
Markdown
# 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_cert_path` configuration parameters. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
|
|
|
|
```yaml
|
|
tls_cert_path: ""
|
|
tls_key_path: ""
|
|
```
|
|
|
|
## Let's Encrypt / ACME
|
|
|
|
To get a certificate automatically via [Let's Encrypt](https://letsencrypt.org/), set `tls_letsencrypt_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_letsencrypt_cache_dir`. If the path is relative, it will be interpreted as relative to the directory the configuration file was read from.
|
|
|
|
```yaml
|
|
tls_letsencrypt_hostname: ""
|
|
tls_letsencrypt_listen: ":http"
|
|
tls_letsencrypt_cache_dir: ".cache"
|
|
tls_letsencrypt_challenge_type: HTTP-01
|
|
```
|
|
|
|
### Challenge types
|
|
|
|
Headscale only supports two values for `tls_letsencrypt_challenge_type`: `HTTP-01` (default) and `TLS-ALPN-01`.
|
|
|
|
#### 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.
|
|
|
|
If you need to change the ip and/or port used by headscale for the Let's Encrypt validation process, set `tls_letsencrypt_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_letsencrypt_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_letsencrypt_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 [autocert](https://pkg.go.dev/golang.org/x/crypto/acme/autocert), a Golang library providing [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) verification, to facilitate certificate renewals via [Let's Encrypt](https://letsencrypt.org/about/). 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 are only attempted by headscale when 30 days or less remains until certificate expiry.
|
|
- Renewal attempts by autocert are triggered at a random interval of 30-60 minutes.
|
|
- No log output is generated when renewals are skipped, or successful.
|
|
|
|
#### 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:
|
|
|
|
1. Open the URL for your headscale server in your browser of choice, and manually inspecting the expiry date of the certificate you receive.
|
|
2. Or, check remotely from CLI using `openssl`:
|
|
|
|
```bash
|
|
$ openssl s_client -servername [hostname] -connect [hostname]:443 | openssl x509 -noout -dates
|
|
(...)
|
|
notBefore=Feb 8 09:48:26 2024 GMT
|
|
notAfter=May 8 09:48:25 2024 GMT
|
|
```
|
|
|
|
#### Log output from the autocert library
|
|
|
|
As these log lines are from the autocert library, they are not strictly generated by headscale itself.
|
|
|
|
```plaintext
|
|
acme/autocert: missing server name
|
|
```
|
|
|
|
Likely caused by an incoming connection that does not specify a hostname, for example a `curl` request directly against the IP of the server, or an unexpected hostname.
|
|
|
|
```plaintext
|
|
acme/autocert: host "[foo]" not configured in HostWhitelist
|
|
```
|
|
|
|
Similarly to the above, this likely indicates an invalid incoming request for an incorrect hostname, commonly just the IP itself.
|
|
|
|
The source code for autocert can be found [here](https://cs.opensource.google/go/x/crypto/+/refs/tags/v0.19.0:acme/autocert/autocert.go)
|