diff --git a/docs/about/features.md b/docs/about/features.md index 33b32618..14d484bc 100644 --- a/docs/about/features.md +++ b/docs/about/features.md @@ -19,7 +19,7 @@ provides on overview of Headscale's feature and compatibility with the Tailscale - [x] [Exit nodes](../ref/routes.md#exit-node) - [x] Dual stack (IPv4 and IPv6) - [x] Ephemeral nodes -- [x] Embedded [DERP server](https://tailscale.com/kb/1232/derp-servers) +- [x] Embedded [DERP server](../ref/derp.md) - [x] Access control lists ([GitHub label "policy"](https://github.com/juanfont/headscale/labels/policy%20%F0%9F%93%9D)) - [x] ACL management via API - [x] Some [Autogroups](https://tailscale.com/kb/1396/targets#autogroups), currently: `autogroup:internet`, diff --git a/docs/ref/derp.md b/docs/ref/derp.md new file mode 100644 index 00000000..a0189e10 --- /dev/null +++ b/docs/ref/derp.md @@ -0,0 +1,153 @@ +# DERP + +A [DERP (Designated Encrypted Relay for Packets) server](https://tailscale.com/kb/1232/derp-servers) is mainly used to +relay traffic between two nodes in case a direct connection can't be established. Headscale provides an embedded DERP +server to ensure seamless connectivity between nodes. + +## Configuration + +DERP related settings are configured within the `derp` section of the [configuration file](./configuration.md). The +following sections only use a few of the available settings, check the [example configuration](./configuration.md) for +all available configuration options. + +### Enable embedded DERP + +Headscale ships with an embedded DERP server which allows to run your own self-hosted DERP server easily. The embedded +DERP server is disabled by default and needs to be enabled. In addition, you should configure the public IPv4 and public +IPv6 address of your Headscale server for improved connection stability: + +```yaml title="config.yaml" hl_lines="3-5" +derp: + server: + enabled: true + ipv4: 198.51.100.1 + ipv6: 2001:db8::1 +``` + +Keep in mind that [additional ports are needed to run a DERP server](../setup/requirements.md#ports-in-use). Besides +relaying traffic, it also uses STUN (udp/3478) to help clients discover their public IP addresses and perform NAT +traversal. [Check DERP server connectivity](#check-derp-server-connectivity) to see if everything works. + +### Remove Tailscale's DERP servers + +Once enabled, Headscale's embedded DERP is added to the list of free-to-use [DERP +servers](https://tailscale.com/kb/1232/derp-servers) offered by Tailscale Inc. To only use Headscale's embedded DERP +server, disable the loading of the default DERP map: + +```yaml title="config.yaml" hl_lines="6" +derp: + server: + enabled: true + ipv4: 198.51.100.1 + ipv6: 2001:db8::1 + urls: [] +``` + +!!! warning "Single point of failure" + + Removing Tailscale's DERP servers means that there is now just a single DERP server available for clients. This is a + single point of failure and could hamper connectivity. + + [Check DERP server connectivity](#check-derp-server-connectivity) with your embedded DERP server before removing + Tailscale's DERP servers. + +### Customize DERP map + +The DERP map offered to clients can be customized with a [dedicated YAML-configuration +file](https://github.com/juanfont/headscale/blob/main/derp-example.yaml). Typical use-cases involve: + +- Running a fleet of [custom DERP servers](https://tailscale.com/kb/1118/custom-derp-servers) +- Excluding or choosing specific regions from the Tailscale's list of free-to-use [DERP + servers](https://tailscale.com/kb/1232/derp-servers) + +The following sample `derp.yaml` references two custom regions (`custom-east` with ID 900 and `custom-west` with ID 901) +with one custom DERP server in each region. Each DERP server offers DERP relay via HTTPS on tcp/443, support for captive +portal checks via HTTP on tcp/80 and STUN on udp/3478. See the definitions of +[DERPMap](https://pkg.go.dev/tailscale.com/tailcfg#DERPMap), +[DERPRegion](https://pkg.go.dev/tailscale.com/tailcfg#DERPRegion) and +[DERPNode](https://pkg.go.dev/tailscale.com/tailcfg#DERPNode) for all available options. + +```yaml title="derp.yaml" +regions: + 900: + regionid: 900 + regioncode: custom-east + regionname: My region (east) + nodes: + - name: 900a + regionid: 900 + hostname: derp900a.example.com + ipv4: 198.51.100.1 + ipv6: 2001:db8::1 + canport80: true + 901: + regionid: 901 + regioncode: custom-west + regionname: My Region (west) + nodes: + - name: 901a + regionid: 901 + hostname: derp901a.example.com + ipv4: 198.51.100.2 + ipv6: 2001:db8::2 + canport80: true +``` + +Use the following configuration to only serve the two DERP servers from the above `derp.yaml`: + +```yaml title="config.yaml" hl_lines="5 6" +derp: + server: + enabled: false + urls: [] + paths: + - /etc/headscale/derp.yaml +``` + +The embedded DERP server can also be enabled and is automatically added to the custom DERP map. + + +### Verify clients + +Access to DERP serves can be restricted to nodes that are members of your Tailnet. Relay access is denied for unknown +clients. + +=== "Embedded DERP" + + Client verification is enabled by default. + + ```yaml title="config.yaml" hl_lines="3" + derp: + server: + verify_clients: true + ``` + +=== "3rd-party DERP" + + Tailscale's `derper` provides two parameters to configure client verification: + + - Use the `-verify-client-url` parameter of the `derper` and point it towards the `/verify` endpoint of your + Headscale server (e.g `https://headscale.example.com/verify`). The DERP server will query your Headscale instance + as soon as a client connects with it to ask whether access should be allowed or denied. Access is allowed if + Headscale knows about the connecting client and denied otherwise. + - The parameter `-verify-client-url-fail-open` controls what should happen when the DERP server can't reach the + Headscale instance. By default, it will allow access if Headscale is unreachable. + +## Check DERP server connectivity + +Any Tailscale client may be used to introspect the DERP map and to check for connectivity issues with DERP servers. + +- Display DERP map: `tailscale debug derp-map` +- Check connectivity with the embedded DERP[^1]:`tailscale debug derp headscale` + +Additional DERP related metrics and information is available via the [metrics and debug +endpoint](./debug.md#metrics-and-debug-endpoint). + +[^1]: + This assumes that the default region code of the [configuration file](./configuration.md) is used. + +## Limitations + +- The embedded DERP server can't be used for Tailscale's captive portal checks as it doesn't support the `/generate_204` + endpoint via HTTP on port tcp/80. +- There are no speed or throughput optimisations, the main purpose is to assist in node connectivity. diff --git a/docs/ref/integration/reverse-proxy.md b/docs/ref/integration/reverse-proxy.md index 91ee8dfc..3586171f 100644 --- a/docs/ref/integration/reverse-proxy.md +++ b/docs/ref/integration/reverse-proxy.md @@ -13,7 +13,7 @@ Running headscale behind a reverse proxy is useful when running multiple applica The reverse proxy MUST be configured to support WebSockets to communicate with Tailscale clients. -WebSockets support is also required when using the headscale embedded DERP server. In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml). +WebSockets support is also required when using the Headscale [embedded DERP server](../derp.md). In this case, you will also need to expose the UDP port used for STUN (by default, udp/3478). Please check our [config-example.yaml](https://github.com/juanfont/headscale/blob/main/config-example.yaml). ### Cloudflare diff --git a/docs/setup/requirements.md b/docs/setup/requirements.md index 1c2450a2..627e24ed 100644 --- a/docs/setup/requirements.md +++ b/docs/setup/requirements.md @@ -22,10 +22,10 @@ The ports in use vary with the intended scenario and enabled features. Some of t - tcp/443 - Expose publicly: yes - HTTPS, required to make Headscale available to Tailscale clients[^1] - - Required if the built-in DERP server is enabled + - Required if the [embedded DERP server](../ref/derp.md) is enabled - udp/3478 - Expose publicly: yes - - STUN, required if the built-in DERP server is enabled + - STUN, required if the [embedded DERP server](../ref/derp.md) is enabled - tcp/50443 - Expose publicly: yes - Only required if the gRPC interface is used to [remote-control Headscale](../ref/remote-cli.md). diff --git a/mkdocs.yml b/mkdocs.yml index aa76a7d2..3881cabd 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -181,6 +181,7 @@ nav: - TLS: ref/tls.md - ACLs: ref/acls.md - DNS: ref/dns.md + - DERP: ref/derp.md - Remote CLI: ref/remote-cli.md - Debug: ref/debug.md - Integration: