From c3fb5c6a2c3b8a104de76c116d73b0ae8a1b86a5 Mon Sep 17 00:00:00 2001
From: Aine <aine@etke.cc>
Date: Tue, 22 Sep 2026 17:28:19 +0100
Subject: [PATCH] livekit: expose ALPN protocols for s/turn via
 playbook-managed-traefik

---
 CHANGELOG.md                                | 14 ++++++++++++++
 docs/configuring-playbook-livekit-server.md |  8 ++++++++
 group_vars/matrix_servers                   | 13 +++++++++++++
 roles/custom/matrix-base/defaults/main.yml  |  5 +++++
 4 files changed, 40 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c5ac098cf..f8cbafc5d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,17 @@
+# 2026-09-22
+
+## LiveKit's TURN over TLS works for clients that advertise an ALPN protocol
+
+This only affects you if you have [LiveKit Server](./docs/configuring-playbook-livekit-server.md) with TURN enabled.
+
+LiveKit Server's embedded TURN server speaks TURN over TLS, and the playbook lets Traefik terminate that TLS. Traefik's default TLS options allow only `h2`, `http/1.1` and `acme-tls/1` as ALPN protocols, and Traefik aborts the handshake when the client's advertised protocols don't intersect with them. TURN clients advertising `stun.turn` (see [RFC 7443](https://datatracker.ietf.org/doc/html/rfc7443)) got a TLS alert instead of a relay.
+
+The playbook now defines a `livekit-turn` Traefik TLS option that also allows `stun.turn` and `stun.nat-discovery`, and attaches it to the LiveKit TURN/TLS router. Chrome does not advertise an ALPN protocol for TURN, so nothing changes for it.
+
+Deployments using `other-traefik-container` need to define an equivalent TLS option in their own Traefik instance and point `livekit_server_container_labels_turn_traefik_tls_options` at it. See [TURN/TLS clients advertising an ALPN protocol](./docs/configuring-playbook-livekit-server.md#turntls-clients-advertising-an-alpn-protocol) for details.
+
+Re-running the playbook (`just install-all`) regenerates the configuration and applies it.
+
 # 2026-09-19
 
 ## Maubot's plugin webhooks and management interface work again
diff --git a/docs/configuring-playbook-livekit-server.md b/docs/configuring-playbook-livekit-server.md
index a06ccb3f8..0e9a6feca 100644
--- a/docs/configuring-playbook-livekit-server.md
+++ b/docs/configuring-playbook-livekit-server.md
@@ -61,6 +61,14 @@ livekit_server_container_labels_turn_traefik_entrypoints: "<your-livekit-turn-tr
 
 and configuring their own Traefik TCP entrypoint dedicated to LiveKit TURN traffic.
 
+### TURN/TLS clients advertising an ALPN protocol
+
+Traefik's default TLS options allow only `h2`, `http/1.1` and `acme-tls/1` as ALPN protocols, and Traefik aborts the TLS handshake when the client's advertised protocols don't intersect with that list. TURN clients advertising `stun.turn` (see [RFC 7443](https://datatracker.ietf.org/doc/html/rfc7443)) therefore could not use TURN over TLS at all.
+
+The playbook defines a `livekit-turn` Traefik TLS option (see `traefik_config_tls_options_auto` in `group_vars/matrix_servers`) that also allows `stun.turn` and `stun.nat-discovery`, and attaches it to the TURN router. This applies whenever TURN TLS handling is active (see above).
+
+If you use `other-traefik-container` or [another reverse-proxy](./configuring-playbook-own-webserver.md), define an equivalent TLS option in the Traefik instance that terminates TURN TLS and point `livekit_server_container_labels_turn_traefik_tls_options` at it (for example, `livekit-turn@file`). TLS options cannot be defined through container labels, so the role can only reference an option that your Traefik configuration defines itself.
+
 ## TURN access controls
 
 LiveKit's embedded TURN server enforces a credential TTL and restricts which peer CIDRs it will relay to. The playbook leaves these at the role's secure defaults, which are appropriate for typical deployments where TURN peers live on the public Internet.
diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers
index e5fddcefe..a35865bc3 100755
--- a/group_vars/matrix_servers
+++ b/group_vars/matrix_servers
@@ -6384,6 +6384,18 @@ traefik_additional_entrypoints_auto: |
     ([matrix_playbook_livekit_turn_traefik_entrypoint_definition] if matrix_playbook_livekit_turn_traefik_entrypoint_enabled else [])
   }}
 
+# A TLS option for the LiveKit TURN/TLS router: Traefik's default TLS options reject the `stun.turn` ALPN protocol.
+traefik_config_tls_options_auto: |
+  {{
+    (
+      {
+        matrix_playbook_livekit_turn_traefik_tls_options_name: {
+          'alpnProtocols': matrix_playbook_livekit_turn_traefik_tls_options_alpn_protocols,
+        }
+      } if livekit_server_container_labels_turn_traefik_enabled else {}
+    )
+  }}
+
 traefik_config_providers_docker_endpoint: "{{ container_socket_proxy_endpoint if container_socket_proxy_enabled else 'unix:///var/run/docker.sock' }}"
 
 traefik_container_image_registry_prefix_upstream: "{{ matrix_container_global_registry_prefix_override if matrix_container_global_registry_prefix_override else traefik_container_image_registry_prefix_upstream_default }}"
@@ -6571,6 +6583,7 @@ livekit_server_container_labels_traefik_tls_certResolver: "{{ traefik_certResolv
 livekit_server_container_labels_turn_traefik_enabled: "{{ matrix_playbook_livekit_turn_traefik_entrypoint_enabled }}"
 livekit_server_container_labels_turn_traefik_entrypoints: "{{ matrix_playbook_livekit_turn_traefik_entrypoint_name }}"
 livekit_server_container_labels_turn_traefik_tls_certResolver: "{{ traefik_certResolver_primary }}"
+livekit_server_container_labels_turn_traefik_tls_options: "{{ (matrix_playbook_livekit_turn_traefik_tls_options_name + '@file') if livekit_server_container_labels_turn_traefik_enabled else '' }}"
 
 livekit_server_container_labels_public_metrics_middleware_basic_auth_enabled: "{{ matrix_metrics_exposure_http_basic_auth_enabled }}"
 livekit_server_container_labels_public_metrics_middleware_basic_auth_users: "{{ matrix_metrics_exposure_http_basic_auth_users }}"
diff --git a/roles/custom/matrix-base/defaults/main.yml b/roles/custom/matrix-base/defaults/main.yml
index d7195f066..1a3baf51f 100644
--- a/roles/custom/matrix-base/defaults/main.yml
+++ b/roles/custom/matrix-base/defaults/main.yml
@@ -457,6 +457,11 @@ matrix_playbook_livekit_turn_traefik_entrypoint_definition:
   host_bind_port: "{{ matrix_playbook_livekit_turn_traefik_entrypoint_host_bind_port }}"
   config: "{{ matrix_playbook_livekit_turn_traefik_entrypoint_config }}"
 
+# Controls the name of the Traefik TLS option attached to the LiveKit TURN/TLS router (see `tls.options`).
+matrix_playbook_livekit_turn_traefik_tls_options_name: livekit-turn
+# Traefik's default ALPN protocols reject TURN clients that advertise stun.turn (RFC 7443).
+matrix_playbook_livekit_turn_traefik_tls_options_alpn_protocols: ["stun.turn", "stun.nat-discovery", "h2", "http/1.1", "acme-tls/1"]
+
 # Variables to Control which parts of our roles run.
 run_postgres_import: true
 run_postgres_upgrade: true