diff --git a/CHANGELOG.md b/CHANGELOG.md index 040bf7ae1..98283d233 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,27 @@ # 2026-02-21 +## (BC Break) coturn is no longer auto-enabled by default + +By default, the [coturn](./docs/configuring-playbook-turn.md) TURN server component is no longer enabled for every deployment. + +This reduces resources and attach surface for deployments which: + +- either don't need calls at all +- or use the modern [Matrix RTC](docs/configuring-playbook-matrix-rtc.md)/[Element Call](docs/configuring-playbook-element-call.md) stack. + +Coturn is still auto-enabled when [Jitsi](./docs/configuring-playbook-jitsi.md) is enabled (`jitsi_enabled: true`), because Jitsi still depends on TURN for legacy Matrix integration. + +Additionally, Coturn (when enabled) now defaults to using automatic IP detection of your server's external IP address, instead of assuming your Ansible inventory (`ansible_host`) points to a public address and using it for configuring `coturn_turn_external_ip_address`. + +To restore the old behavior (needed for legacy call setups), add the following configuration to your `vars.yml`: + +```yml +coturn_enabled: true + +# If you'd like explicit control over the external IP address (like before), keep this too. +coturn_turn_external_ip_address: "{{ ansible_host }}" +``` + ## LiveKit TURN TLS is now automatically fronted by playbook-managed Traefik For deployments that use the playbook-managed Traefik reverse-proxy, LiveKit TURN over TCP is now SSL-terminated at Traefik and passed as plain TCP to LiveKit (`turn.external_tls = true`) by default. diff --git a/README.md b/README.md index 7fb937636..7beadd224 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ Services that run on the server to make the various parts of your installation w | Name | Default? | Description | Documentation | | ---- | -------- | ----------- | ------------- | | [PostgreSQL](https://www.postgresql.org/)| ✅ | Database for Synapse. [Using an external PostgreSQL server](docs/configuring-playbook-external-postgres.md) is also possible. | [Link](docs/configuring-playbook-external-postgres.md) | -| [coturn](https://github.com/coturn/coturn) | ✅ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) | +| [coturn](https://github.com/coturn/coturn) | ❌ | STUN/TURN server for WebRTC audio/video calls | [Link](docs/configuring-playbook-turn.md) | | [Traefik](https://doc.traefik.io/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. [Using your own webserver](docs/configuring-playbook-own-webserver.md) is also possible. | [Link](docs/configuring-playbook-traefik.md) | | [Let's Encrypt](https://letsencrypt.org/) | ✅ | Free SSL certificate, which secures the connection to all components | [Link](docs/configuring-playbook-ssl-certificates.md) | | [Exim](https://www.exim.org/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) | [Link](docs/configuring-playbook-email.md) | diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index 6c035dee4..ea9d7cd02 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -18,6 +18,9 @@ SPDX-License-Identifier: AGPL-3.0-or-later The playbook can install and configure the [Jitsi](https://jitsi.org/) video-conferencing platform for you. +Because Jitsi still requires a TURN server, enabling Jitsi +automatically enables coturn (`coturn_enabled: true`) unless you explicitly disable it. + Jitsi is an open source video-conferencing platform. It can not only be integrated with Element clients ([Element Web](configuring-playbook-client-element-web.md)/Desktop, Android and iOS) as a widget, but also be used as standalone web app. 💡 If you're into experimental technology, you may also be interested in trying out [Element Call](configuring-playbook-element-call.md) - a native Matrix video conferencing application. diff --git a/docs/configuring-playbook-turn.md b/docs/configuring-playbook-turn.md index 42fc80787..d9d0c3be0 100644 --- a/docs/configuring-playbook-turn.md +++ b/docs/configuring-playbook-turn.md @@ -13,34 +13,48 @@ SPDX-License-Identifier: AGPL-3.0-or-later # Configuring a TURN server (optional, advanced) -By default, this playbook installs and configures the [coturn](https://github.com/coturn/coturn) as a TURN server, through which clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks. It also configures the Synapse chat server by default, so that it points to the coturn TURN server installed by the playbook. If that's okay, you can skip this document. +By default, the [coturn](https://github.com/coturn/coturn) TURN server component is enabled automatically only when [Jitsi](configuring-playbook-jitsi.md) is enabled. If you're not using Jitsi, coturn is not enabled by default. -If you'd like to stop the playbook installing the server, see the section [below](#disabling-coturn) to check the configuration for disabling it. +If you explicitly need coturn while not using Jitsi, enable it with: + +```yaml +coturn_enabled: true +``` + +and configure its IP-related settings in the section below. + +If you'd like coturn to stay disabled even when Jitsi is enabled, or if you prefer to use an external TURN provider, see [disabling coturn](#disabling-coturn) section below. + +When Coturn is not enabled, homeservers (like Synapse) would not point to TURN servers and *legacy* audio/video call functionality may fail. If you're using [Matrix RTC](configuring-playbook-rtc.md) (for [Element Call](configuring-playbook-element-call.md)), you likely don't have a need to enable coturn. + +## Adjusting firewall rules + +To ensure Coturn functions correctly, the following firewall rules and port forwarding settings are required when coturn is enabled: + +- `3478/tcp`: STUN/TURN over TCP +- `3478/udp`: STUN/TURN over UDP +- `5349/tcp`: TURN over TCP +- `5349/udp`: TURN over UDP +- `49152-49172/udp`: TURN/UDP relay range + +💡 Docker configures the server's internal firewall for you. In most cases, you don't need to do anything special on the host itself. ## Adjusting the playbook configuration ### Define public IP manually (optional) -In the `hosts` file we explicitly ask for your server's external IP address when defining `ansible_host`, because the same value is used for configuring coturn. - -If you'd rather use a local IP for `ansible_host`, add the following configuration to your `vars.yml` file. Make sure to replace `YOUR_PUBLIC_IP` with the pubic IP used by the server. +If you enable coturn (either via Jitsi or manually), we recommend that you configure the public IP addresses of your server in the `vars.yml` file: ```yaml -coturn_turn_external_ip_address: "YOUR_PUBLIC_IP" +# You can define multiple IP addresses if your server has multiple external IP addresses +coturn_turn_external_ip_addresses: ["YOUR_PUBLIC_IP"] ``` -If you'd like to rely on external IP address auto-detection (not recommended unless you need it), set an empty value to the variable. The playbook will automatically contact an [echoip](https://github.com/mpolden/echoip)-compatible service (`https://ifconfig.co/json` by default) to determine your server's IP address. This API endpoint is configurable via the `coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable. +If you'd like to rely on external IP address auto-detection (not recommended unless you need it), avoid configuring this variable. The playbook will automatically contact an [echoip](https://github.com/mpolden/echoip)-compatible service (`https://ifconfig.co/json` by default) to determine your server's IP address. This API endpoint is configurable via the `coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable. >[!NOTE] > You can self-host the echoip service by using the [Mother-of-All-Self-Hosting (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook) Ansible playbook. See [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/echoip.md) for the instruction to install it with the playbook. If you are wondering how to use it for your Matrix server, refer to [this page](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/setting-up-services-on-mdad-server.md) for the overview. -If your server has multiple external IP addresses, the coturn role offers a different variable for specifying them: - -```yaml -# Note: coturn_turn_external_ip_addresses is different than coturn_turn_external_ip_address -coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7'] -``` - ### Change the authentication mechanism (optional) The playbook uses the [`auth-secret` authentication method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L186-L199) by default, but you may switch to the [`lt-cred-mech` method](https://github.com/coturn/coturn/blob/873cabd6a2e5edd7e9cc5662cac3ffe47fe87a8e/README.turnserver#L178) which [some report](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3191) to be working better. @@ -119,14 +133,14 @@ Take a look at: ## Disabling coturn -If, for some reason, you'd like for the playbook to not install coturn (or to uninstall it if it was previously installed), add the following configuration to your `vars.yml` file: +Coturn is only enabled by default when [Jitsi](configuring-playbook-jitsi.md) is enabled. In most instances, you don't need to explicitly disable it. + +To force the playbook to not install Coturn (even when Jitsi is enabled), add the following configuration to your `vars.yml` file: ```yaml coturn_enabled: false ``` -In that case, Synapse would not point to any coturn servers and audio/video call functionality may fail. - ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/faq.md b/docs/faq.md index 662a7e55d..6d662cff6 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -311,10 +311,6 @@ You can disable some not-so-important services to save on memory. # Disabling this will prevent email-notifications and other such things from working. exim_relay_enabled: false -# You can also disable this to save more RAM, -# at the expense of audio/video calls being unreliable. -coturn_enabled: false - # This makes Synapse not keep track of who is online/offline. # # Keeping track of this and announcing such online-status in federated rooms with diff --git a/docs/prerequisites.md b/docs/prerequisites.md index 5ed76ad2c..b9c5f441f 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -57,12 +57,7 @@ We will be using `example.com` as the domain in the following instruction. Pleas - `80/tcp`: HTTP webserver - `443/tcp` and `443/udp`: HTTPS webserver - - `3478/tcp`: STUN/TURN over TCP (used by [coturn](./configuring-playbook-turn.md)) - - `3478/udp`: STUN/TURN over UDP (used by [coturn](./configuring-playbook-turn.md)) - - `5349/tcp`: TURN over TCP (used by [coturn](./configuring-playbook-turn.md)) - - `5349/udp`: TURN over UDP (used by [coturn](./configuring-playbook-turn.md)) - `8448/tcp` and `8448/udp`: Matrix Federation API HTTPS webserver. Some components like [Matrix User Verification Service](configuring-playbook-user-verification-service.md#open-matrix-federation-port) require this port to be opened **even with federation disabled**. - - the range `49152-49172/udp`: TURN over UDP - potentially some other ports, depending on the additional (non-default) services that you enable in the **configuring the playbook** step (later on). Consult each service's documentation page in `docs/` for that. --------------------------------------------- diff --git a/examples/hosts b/examples/hosts index 7099f1fa4..4204b60d8 100644 --- a/examples/hosts +++ b/examples/hosts @@ -1,6 +1,3 @@ -# We explicitly ask for your server's external IP address, because the same value is used for configuring coturn. -# If you'd rather use a local IP here, make sure to set up `coturn_turn_external_ip_address`. -# # To connect using a non-root user (and elevate to root with sudo later), # replace `ansible_ssh_user=root` with something like this: `ansible_ssh_user=username ansible_become=true ansible_become_user=root`. # If sudo requires a password, either add `ansible_become_password=PASSWORD_HERE` to the host line @@ -18,4 +15,4 @@ # to the host line below. [matrix_servers] -matrix.example.com ansible_host= ansible_ssh_user=root +matrix.example.com ansible_host= ansible_ssh_user=root diff --git a/examples/vars.yml b/examples/vars.yml index 727346aa1..302c7eea2 100644 --- a/examples/vars.yml +++ b/examples/vars.yml @@ -52,19 +52,3 @@ devture_systemd_docker_base_ipv6_enabled: true # Changing this value subsequently requires manual work. # The value used here must be shorter than 100 characters. postgres_connection_password: '' - -# By default, we configure coturn's external IP address using the value specified for `ansible_host` in your `inventory/hosts` file. -# If this value is an external IP address, you can skip this section. -# -# If `ansible_host` is not the server's external IP address, you have 2 choices: -# 1. Uncomment the line below, to allow IP address auto-detection to happen (more on this below) -# 2. Uncomment and adjust the line below to specify an IP address manually -# -# By default, auto-detection will be attempted using the `https://ifconfig.co/json` API. -# Default values for this are specified in `coturn_turn_external_ip_address_auto_detection_*` variables in the coturn role -# (see `roles/galaxy/coturn/defaults/main.yml`). -# -# If your server has multiple IP addresses, you may define them in another variable which allows a list of addresses. -# Example: `coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']` -# -# coturn_turn_external_ip_address: '' diff --git a/group_vars/matrix_servers b/group_vars/matrix_servers index e980cd99a..c69422fb2 100755 --- a/group_vars/matrix_servers +++ b/group_vars/matrix_servers @@ -3497,7 +3497,9 @@ matrix_rageshake_container_labels_traefik_tls_certResolver: "{{ traefik_certReso # ###################################################################### -coturn_enabled: true +# Coturn is enabled by default only when Jitsi is enabled because Jitsi still +# depends on legacy TURN integration for compatibility. +coturn_enabled: "{{ jitsi_enabled | bool }}" coturn_identifier: matrix-coturn @@ -3513,11 +3515,6 @@ coturn_container_image_registry_prefix_upstream: "{{ matrix_container_global_reg coturn_container_image_self_build: "{{ matrix_architecture not in ['amd64', 'arm32', 'arm64'] }}" -# We make the assumption that `ansible_host` points to an external IP address, which may not always be the case. -# Users are free to set `coturn_turn_external_ip_address` to an empty string -# to allow auto-detection (via an echoip service) to happen at runtime. -coturn_turn_external_ip_address: "{{ ansible_host }}" - # By default, we use the official public instance. coturn_turn_external_ip_address_auto_detection_echoip_service_url: https://ifconfig.co/json