mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-02-04 06:14:57 +01:00
Update files for coturn (#3953)
* Update docs/configuring-playbook-turn.md: add a section for description about installing Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-turn.md and a related file - Edit the introducion based on docs/configuring-playbook-client-element-web.md - Adopt the commont format by creating the section "Adjusting the playbook configuration" - Add the section "Extending the configuration" - Move the section "Disabling Coturn" to the bottom Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Fix capitalization: Coturn → coturn See: https://github.com/coturn/coturn. Note that "coturn" is not capitalized even on the start of a sentence, except some rare cases like on the releases page: https://github.com/coturn/coturn/releases Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
GitHub
parent
96dbb98b37
commit
2773c053d0
38
CHANGELOG.md
38
CHANGELOG.md
@ -536,7 +536,7 @@ For 6 years, `matrix-nginx-proxy` has been the front-most reverse-proxy in our s
|
||||
To us, `matrix-nginx-proxy` was:
|
||||
|
||||
- an [nginx](https://nginx.org/)-based reverse-proxy
|
||||
- an Ansible role organizing the work of [certbot](https://certbot.eff.org/) - retrieving free [Let's Encrypt](https://letsencrypt.org/) SSL certificates for `matrix-nginx-proxy` and for the [Coturn TURN server](./docs/configuring-playbook-turn.md)
|
||||
- an Ansible role organizing the work of [certbot](https://certbot.eff.org/) - retrieving free [Let's Encrypt](https://letsencrypt.org/) SSL certificates for `matrix-nginx-proxy` and for the [coturn TURN server](./docs/configuring-playbook-turn.md)
|
||||
- a central component for reverse-proxying to the [long list of services](./docs/configuring-playbook.md) supported by the playbook. As such, it became a dependency that all these services had to inject themselves into during runtime
|
||||
- an intermediary through which addons (bridges, bots) communicated with the homeserver. Going through an intermediary (instead of directly talking to the homeserver) is useful when certain components (like [matrix-media-repo](./docs/configuring-playbook-matrix-media-repo.md) or [matrix-corporal](./docs/configuring-playbook-matrix-corporal.md)) are enabled, because it lets these services "steal routes" from the homeserver
|
||||
- a webserver for serving the `/.well-known/matrix` static files (generated by the `matrix-base` role until now)
|
||||
@ -1200,7 +1200,7 @@ Switching to Traefik will obtain new SSL certificates from Let's Encrypt (stored
|
||||
|
||||
Treafik directly reverse-proxies to **some** services right now, but for most other services it goes through `matrix-nginx-proxy` (e.g. Traefik -> `matrix-nginx-proxy` -> [Ntfy](docs/configuring-playbook-ntfy.md)). So, even if you opt into Traefik, you'll still see `matrix-nginx-proxy` being installed in local-only mode. This will improve with time.
|
||||
|
||||
Some services (like [Coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool.
|
||||
Some services (like [coturn](docs/configuring-playbook-turn.md) and [Postmoogle](docs/configuring-playbook-bridge-postmoogle.md)) cannot be reverse-proxied to directly from Traefik, so they require direct access to SSL certificate files extracted out of Traefik. The playbook does this automatically thanks to a new [com.devture.ansible.role.traefik_certs_dumper](https://github.com/devture/com.devture.ansible.role.traefik_certs_dumper) role utilizing the [traefik-certs-dumper](https://github.com/ldez/traefik-certs-dumper) tool.
|
||||
|
||||
Our Traefik setup mostly works, but certain esoteric features may not work. If you have a default setup, we expect you to have a good experience.
|
||||
|
||||
@ -1260,29 +1260,29 @@ Other roles which aren't strictly related to Matrix are likely to follow this fa
|
||||
|
||||
# 2023-01-26
|
||||
|
||||
## Coturn can now use host-networking
|
||||
## coturn can now use host-networking
|
||||
|
||||
Large Coturn deployments (with a huge range of ports specified via `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`) experience a huge slowdown with how Docker publishes all these ports (setting up firewall forwarding rules), which leads to a very slow Coturn service startup and shutdown.
|
||||
Large coturn deployments (with a huge range of ports specified via `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`) experience a huge slowdown with how Docker publishes all these ports (setting up firewall forwarding rules), which leads to a very slow coturn service startup and shutdown.
|
||||
|
||||
Such deployments don't need to run Coturn within a private container network anymore. Coturn can now run with host-networking by using configuration like this:
|
||||
Such deployments don't need to run coturn within a private container network anymore. coturn can now run with host-networking by using configuration like this:
|
||||
|
||||
```yaml
|
||||
matrix_coturn_container_network: host
|
||||
```
|
||||
|
||||
With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time Coturn starts and stops. This, however, means that **you will need to ensure these ports are open** in your firewall yourself.
|
||||
With such a configuration, **Docker no longer needs to configure thousands of firewall forwarding rules** each time coturn starts and stops. This, however, means that **you will need to ensure these ports are open** in your firewall yourself.
|
||||
|
||||
Thanks to us [tightening Coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running Coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
|
||||
Thanks to us [tightening coturn security](#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues), running coturn with host-networking should be safe and not expose neither other services running on the host, nor other services running on the local network.
|
||||
|
||||
## (Backward Compatibility) Tightening Coturn security can lead to connectivity issues
|
||||
## (Backward Compatibility) Tightening coturn security can lead to connectivity issues
|
||||
|
||||
**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default Coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
|
||||
**TLDR**: users who run and access their Matrix server on a private network (likely a small minority of users) may experience connectivity issues with our new default coturn blocklists. They may need to override `matrix_coturn_denied_peer_ips` and remove some IP ranges from it.
|
||||
|
||||
Inspired by [this security article](https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/), we've decided to make use of Coturn's `denied-peer-ip` functionality to prevent relaying network traffic to certain private IP subnets. This ensures that your Coturn server won't accidentally try to forward traffic to certain services running on your local networks. We run Coturn in a container and in a private container network by default, which should prevent such access anyway, but having additional block layers in place is better.
|
||||
Inspired by [this security article](https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/), we've decided to make use of coturn's `denied-peer-ip` functionality to prevent relaying network traffic to certain private IP subnets. This ensures that your coturn server won't accidentally try to forward traffic to certain services running on your local networks. We run coturn in a container and in a private container network by default, which should prevent such access anyway, but having additional block layers in place is better.
|
||||
|
||||
If you access your Matrix server from a local network and need Coturn to relay to private IP addresses, you may observe that relaying is now blocked due to our new default `denied-peer-ip` lists (specified in `matrix_coturn_denied_peer_ips`). If you experience such connectivity problems, consider overriding this setting in your `vars.yml` file and removing certain networks from it.
|
||||
If you access your Matrix server from a local network and need coturn to relay to private IP addresses, you may observe that relaying is now blocked due to our new default `denied-peer-ip` lists (specified in `matrix_coturn_denied_peer_ips`). If you experience such connectivity problems, consider overriding this setting in your `vars.yml` file and removing certain networks from it.
|
||||
|
||||
We've also added `no-multicast-peers` to the default Coturn configuration, but we don't expect this to cause trouble for most people.
|
||||
We've also added `no-multicast-peers` to the default coturn configuration, but we don't expect this to cause trouble for most people.
|
||||
|
||||
|
||||
# 2023-01-21
|
||||
@ -2059,9 +2059,9 @@ Additional details are available in [Setting up Heisenbridge bouncer-style IRC b
|
||||
|
||||
# 2021-04-16
|
||||
|
||||
## Disabling TLSv1 and TLSv1.1 for Coturn
|
||||
## Disabling TLSv1 and TLSv1.1 for coturn
|
||||
|
||||
To improve security, we've [removed TLSv1 and TLSv1.1 support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/999) from our default [Coturn](https://github.com/coturn/coturn) configuration.
|
||||
To improve security, we've [removed TLSv1 and TLSv1.1 support](https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/999) from our default [coturn](https://github.com/coturn/coturn) configuration.
|
||||
|
||||
If you need to support old clients, you can re-enable both (or whichever one you need) with the following configuration:
|
||||
|
||||
@ -3184,11 +3184,11 @@ We've also started building our own Docker image of Ansible ([devture/ansible](h
|
||||
|
||||
# 2019-03-19
|
||||
|
||||
## TLS support for Coturn
|
||||
## TLS support for coturn
|
||||
|
||||
We've added TLS support to the Coturn TURN server installed by the playbook by default. The certificates from the Matrix domain will be used for the Coturn server.
|
||||
We've added TLS support to the coturn TURN server installed by the playbook by default. The certificates from the Matrix domain will be used for the coturn server.
|
||||
|
||||
This feature is enabled by default for new installations. To make use of TLS support for your existing Matrix server's Coturn, make sure to rebuild both Coturn and Synapse:
|
||||
This feature is enabled by default for new installations. To make use of TLS support for your existing Matrix server's coturn, make sure to rebuild both coturn and Synapse:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-coturn,setup-synapse,start
|
||||
@ -3198,9 +3198,9 @@ People who have an extra firewall (besides the iptables firewall, which Docker m
|
||||
|
||||
People who build their own custom playbook from our roles should be aware that:
|
||||
|
||||
- the `matrix-coturn` role and actually starting Coturn (e.g. `--tags=start`), requires that certificates are already put in place. For this reason, it's usually a good idea to have the `matrix-coturn` role execute after `matrix-nginx-proxy` (which retrieves the certificates).
|
||||
- the `matrix-coturn` role and actually starting coturn (e.g. `--tags=start`), requires that certificates are already put in place. For this reason, it's usually a good idea to have the `matrix-coturn` role execute after `matrix-nginx-proxy` (which retrieves the certificates).
|
||||
|
||||
- there are a few variables that can help you enable TLS support for Coturn. See the `matrix-coturn` section in [group_vars/matrix-servers](./group_vars/matrix-servers).
|
||||
- there are a few variables that can help you enable TLS support for coturn. See the `matrix-coturn` section in [group_vars/matrix-servers](./group_vars/matrix-servers).
|
||||
|
||||
|
||||
# 2019-03-12
|
||||
|
||||
@ -72,7 +72,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 [is possible](docs/configuring-playbook-own-webserver.md) | [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) |
|
||||
|
||||
@ -52,7 +52,7 @@ Hopefully, Synapse defaults would also change the same way and we'd see the numb
|
||||
|
||||
With this configuration change in place, projects like [MatrixRooms.info](https://matrixrooms.info/) (made by [etke.cc](https://etke.cc/)) and potentially others in the future, can discover, index the metadata (room address, title, topic, number of users, etc.) and make public rooms browsable & searchable across the whole Matrix Federation. It'd be great if users joining Matrix could more easily find interesting communities that match their interests!
|
||||
|
||||
On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [Coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
|
||||
On the **media side of things**, besides Jitsi getting better Matrix integration (via the aforementioned Matrix User Verification Service), we've also had some [coturn security tightening](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#backward-compatibility-tightening-coturn-security-can-lead-to-connectivity-issues) as well as [performance optimizations](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/850078b7e37401ce91a0f9b686f60b945f6c3a96/CHANGELOG.md#coturn-can-now-use-host-networking) for configurations exposing lots of network ports.
|
||||
|
||||
[Element Call](https://github.com/element-hq/element-call) seems to have become a nice and polished product lately (as proclaimed in [The Matrix Holiday Update 2023](https://matrix.org/blog/2023/12/25/the-matrix-holiday-update-2023/)), so 2024 is likely the year we'll see support for it in the playbook. Element Call depends on the [LiveKit](https://livekit.io/) streaming server (which is also useful to developers even by itself), so the first step is likely to see LiveKit support in mash-playbook via a reusable Ansible role. Such a LiveKit Ansible role could later easily land in matrix-docker-ansible-deploy and an Element Call static website could be hooked to it.
|
||||
|
||||
|
||||
@ -1,61 +1,53 @@
|
||||
# Adjusting TURN server configuration (optional, advanced)
|
||||
# Configuring a TURN server (optional, advanced)
|
||||
|
||||
The playbook installs a [Coturn](https://github.com/coturn/coturn) TURN server by default, so that clients can make audio/video calls even from [NAT](https://en.wikipedia.org/wiki/Network_address_translation)-ed networks.
|
||||
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 Synapse chat server is configured, so that it points to the Coturn TURN server installed by the playbook.
|
||||
If you'd like to stop the playbook installing the server, see the section [below](#disabling-coturn) to check the configuration for disabling it.
|
||||
|
||||
## Disabling Coturn
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
If, for some reason, you'd like to prevent the playbook from installing Coturn, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
### Define public IP manually (optional)
|
||||
|
||||
```yaml
|
||||
matrix_coturn_enabled: false
|
||||
```
|
||||
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.
|
||||
|
||||
In that case, Synapse would not point to any Coturn servers and audio/video call functionality may fail.
|
||||
|
||||
## Manually defining your public IP
|
||||
|
||||
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`, make sure to set up `matrix_coturn_turn_external_ip_address` replacing `YOUR_PUBLIC_IP` with the pubic IP used by the server.
|
||||
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.
|
||||
|
||||
```yaml
|
||||
matrix_coturn_turn_external_ip_address: "YOUR_PUBLIC_IP"
|
||||
```
|
||||
|
||||
If you'd like to rely on external IP address auto-detection (not recommended unless you need it), set `matrix_coturn_turn_external_ip_address` to an empty value. 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 `matrix_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), 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 `matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url` variable.
|
||||
|
||||
If your server has multiple external IP addresses, the Coturn role offers a different variable for specifying them:
|
||||
If your server has multiple external IP addresses, the coturn role offers a different variable for specifying them:
|
||||
|
||||
```yaml
|
||||
# Note: matrix_coturn_turn_external_ip_addresses is different than matrix_coturn_turn_external_ip_address
|
||||
matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']
|
||||
```
|
||||
|
||||
## Changing the authentication mechanism
|
||||
### 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.
|
||||
|
||||
To do so, add this override to your configuration:
|
||||
To do so, add the following configuration to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_coturn_authentication_method: lt-cred-mech
|
||||
```
|
||||
|
||||
Regardless of the selected authentication method, the playbook generates secrets automatically and passes them to the homeserver and Coturn.
|
||||
Regardless of the selected authentication method, the playbook generates secrets automatically and passes them to the homeserver and coturn.
|
||||
|
||||
If you're using [Jitsi](./configuring-playbook-jitsi.md), note that switching to `lt-cred-mech` will remove the integration between Jitsi and your own Coturn server, because Jitsi only seems to support the `auth-secret` authentication method.
|
||||
If [Jitsi](configuring-playbook-jitsi.md) is installed, note that switching to `lt-cred-mech` will disable the integration between Jitsi and your coturn server, as Jitsi seems to support the `auth-secret` authentication method only.
|
||||
|
||||
## Using your own external Coturn server
|
||||
### Use your own external coturn server (optional)
|
||||
|
||||
If you'd like to use another TURN server (be it Coturn or some other one), you can configure the playbook like this:
|
||||
If you'd like to use another TURN server (be it coturn or some other one), add the following configuration to your `vars.yml` file. Make sure to replace `HOSTNAME_OR_IP` with your own.
|
||||
|
||||
```yaml
|
||||
# Disable integrated Coturn server
|
||||
# Disable integrated coturn server
|
||||
matrix_coturn_enabled: false
|
||||
|
||||
# Point Synapse to your other Coturn server
|
||||
# Point Synapse to your other coturn server
|
||||
matrix_synapse_turn_uris:
|
||||
- turns:HOSTNAME_OR_IP?transport=udp
|
||||
- turns:HOSTNAME_OR_IP?transport=tcp
|
||||
@ -63,13 +55,42 @@ matrix_synapse_turn_uris:
|
||||
- turn:HOSTNAME_OR_IP?transport=tcp
|
||||
```
|
||||
|
||||
If you have or want to enable [Jitsi](configuring-playbook-jitsi.md), you might want to enable the TURN server there too. If you do not do it, Jitsi will fall back to an upstream service.
|
||||
If you have or want to enable Jitsi, you might want to enable the TURN server there too. If you do not do it, Jitsi will fall back to an upstream service.
|
||||
|
||||
```yaml
|
||||
jitsi_web_stun_servers:
|
||||
- stun:HOSTNAME_OR_IP:PORT
|
||||
```
|
||||
You can put multiple host/port combinations if you like.
|
||||
|
||||
## Further variables and configuration options
|
||||
To see all the available configuration options, check roles/custom/matrix-coturn/defaults/main.yml
|
||||
You can put multiple host/port combinations if you'd like to.
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
There are some additional things you may wish to configure about the TURN server.
|
||||
|
||||
Take a look at:
|
||||
|
||||
- `roles/custom/matrix-coturn/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
|
||||
|
||||
## 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:
|
||||
|
||||
```yaml
|
||||
matrix_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:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
|
||||
|
||||
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too.
|
||||
|
||||
@ -40,7 +40,7 @@ For a more custom setup, see the [Other configuration options](#other-configurat
|
||||
- Server components:
|
||||
- [Using an external PostgreSQL server](configuring-playbook-external-postgres.md)
|
||||
|
||||
- [Adjusting TURN server configuration](configuring-playbook-turn.md) (advanced)
|
||||
- [Configuring a TURN server](configuring-playbook-turn.md) (advanced)
|
||||
|
||||
- [Configuring the Traefik reverse-proxy](configuring-playbook-traefik.md) (advanced)
|
||||
|
||||
|
||||
@ -30,7 +30,7 @@ Services that run on the server to make the various parts of your installation w
|
||||
| Service | Container image | Default? | Description |
|
||||
| ------- | --------------- | -------- | ----------- |
|
||||
| [PostgreSQL](configuring-playbook-external-postgres.md) | [postgres](https://hub.docker.com/_/postgres/) | ✅ | Database for Synapse. [Using an external PostgreSQL server](configuring-playbook-external-postgres.md) is also possible. |
|
||||
| [Coturn](configuring-playbook-turn.md) | [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) | ✅ | STUN/TURN server for WebRTC audio/video calls |
|
||||
| [coturn](configuring-playbook-turn.md) | [coturn/coturn](https://hub.docker.com/r/coturn/coturn/) | ✅ | STUN/TURN server for WebRTC audio/video calls |
|
||||
| [Traefik](configuring-playbook-traefik.md) | [Traefik](https://hub.docker.com/_/traefik/) | ✅ | Web server, listening on ports 80, 443 and 8448 - standing in front of all the other services. Using your own webserver [is possible](configuring-playbook-own-webserver.md) |
|
||||
| [Let's Encrypt](configuring-playbook-ssl-certificates.md) | [certbot/certbot](https://hub.docker.com/r/certbot/certbot/) | ✅ | The [certbot](https://certbot.eff.org/) tool for obtaining SSL certificates from [Let's Encrypt](https://letsencrypt.org/) |
|
||||
| [Exim](configuring-playbook-email.md) | [devture/exim-relay](https://hub.docker.com/r/devture/exim-relay/) | ✅ | Mail server, through which all Matrix services send outgoing email (can be configured to relay through another SMTP server) |
|
||||
|
||||
@ -83,17 +83,17 @@ traefik_environment_variables_additional_variables: |
|
||||
traefik_certResolver_primary: dns
|
||||
```
|
||||
|
||||
## Adjust Coturn's configuration
|
||||
## Adjust coturn's configuration
|
||||
|
||||
The last step is to alter the generated Coturn configuration.
|
||||
The last step is to alter the generated coturn configuration.
|
||||
|
||||
By default, Coturn is configured to wait on the certificate for the `matrix.` subdomain using an [instantiated systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates) using the domain name as the parameter for this service. However, we need to serve the wildcard certificate, which is incompatible with systemd, it will try to expand the `*`, which will break and prevent Coturn from starting.
|
||||
By default, coturn is configured to wait on the certificate for the `matrix.` subdomain using an [instantiated systemd service](https://www.freedesktop.org/software/systemd/man/systemd.service.html#Service%20Templates) using the domain name as the parameter for this service. However, we need to serve the wildcard certificate, which is incompatible with systemd, it will try to expand the `*`, which will break and prevent coturn from starting.
|
||||
|
||||
We also need to indicate to Coturn where the wildcard certificate is.
|
||||
We also need to indicate to coturn where the wildcard certificate is.
|
||||
|
||||
⚠️ **Warning** : On first start of the services, Coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the Coturn service (`just start-group coturn`).
|
||||
⚠️ **Warning** : On first start of the services, coturn might still fail to start because Traefik is still in the process of obtaining the certificates. If you still get an error, make sure Traefik obtained the certificates and restart the coturn service (`just start-group coturn`).
|
||||
|
||||
This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the Coturn service is setup to restart periodically.
|
||||
This should not happen again afterwards as Traefik will renew certificates well before their expiry date, and the coturn service is setup to restart periodically.
|
||||
|
||||
```yaml
|
||||
# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
|
||||
@ -159,7 +159,7 @@ traefik_environment_variables_additional_variables: |
|
||||
CF_DNS_API_TOKEN=redacted
|
||||
LEGO_DISABLE_CNAME_SUPPORT=true
|
||||
|
||||
# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart Coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
|
||||
# Only depend on docker.service, this removes the dependency on the certificate exporter, might imply the need to manually restart coturn on the first installation once the certificates are obtained, afterwards, the reload service should handle things
|
||||
matrix_coturn_systemd_required_services_list: ['docker.service']
|
||||
|
||||
# This changes the path of the loaded certificate, while maintaining the original functionality, we're now loading the wildcard certificate.
|
||||
|
||||
@ -48,10 +48,10 @@ 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`: TURN over TCP (used by Coturn)
|
||||
- `3478/udp`: TURN over UDP (used by Coturn)
|
||||
- `5349/tcp`: TURN over TCP (used by Coturn)
|
||||
- `5349/udp`: TURN over UDP (used by Coturn)
|
||||
- `3478/tcp`: TURN over TCP (used by coturn)
|
||||
- `3478/udp`: TURN over UDP (used by coturn)
|
||||
- `5349/tcp`: TURN over TCP (used by coturn)
|
||||
- `5349/udp`: TURN over UDP (used by coturn)
|
||||
- `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.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# We explicitly ask for your server's external IP address, because the same value is used for configuring Coturn.
|
||||
# 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 `matrix_coturn_turn_external_ip_address`.
|
||||
#
|
||||
# To connect using a non-root user (and elevate to root with sudo later),
|
||||
|
||||
@ -44,7 +44,7 @@ traefik_config_certificatesResolvers_acme_email: ''
|
||||
# using this superuser account.
|
||||
postgres_connection_password: ''
|
||||
|
||||
# By default, we configure Coturn's external IP address using the value specified for `ansible_host` in your `inventory/hosts` file.
|
||||
# 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:
|
||||
@ -52,7 +52,7 @@ postgres_connection_password: ''
|
||||
# 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 `matrix_coturn_turn_external_ip_address_auto_detection_*` variables in the Coturn role
|
||||
# Default values for this are specified in `matrix_coturn_turn_external_ip_address_auto_detection_*` variables in the coturn role
|
||||
# (see `roles/custom/matrix-coturn/defaults/main.yml`).
|
||||
#
|
||||
# If your server has multiple IP addresses, you may define them in another variable which allows a list of addresses.
|
||||
|
||||
@ -257,12 +257,12 @@ matrix_homeserver_sliding_sync_url: "{{ matrix_sliding_sync_base_url if matrix_s
|
||||
# - so that addon services (starting later) can communicte with the homeserver via Traefik's internal entrypoint
|
||||
# (see `matrix_playbook_internal_matrix_client_api_traefik_entrypoint_enabled`)
|
||||
# - core services (the homeserver) get a level of ~1000
|
||||
# - services that the homeserver depends on (database, Redis, ntfy, Coturn, etc.) get a lower level - between 500 and 1000
|
||||
# - Coturn gets a higher level if `devture_systemd_service_manager_service_restart_mode == 'one-by-one'` to intentionally delay it, because:
|
||||
# - services that the homeserver depends on (database, Redis, ntfy, coturn, etc.) get a lower level - between 500 and 1000
|
||||
# - coturn gets a higher level if `devture_systemd_service_manager_service_restart_mode == 'one-by-one'` to intentionally delay it, because:
|
||||
# - starting services one by one means that the service manager role waits for each service to fully start before proceeding to the next one
|
||||
# - if Coturn has a lower priority than the homeserver, it would be started before it
|
||||
# - since Coturn is started before the homeserver, there's no container label telling Traefik to get a `matrix.example.com` certificate
|
||||
# - thus, Coturn would spin and wait for a certificate until it fails. We'd get a playbook failure due to it, but service manager will proceed to start all other services anyway.
|
||||
# - if coturn has a lower priority than the homeserver, it would be started before it
|
||||
# - since coturn is started before the homeserver, there's no container label telling Traefik to get a `matrix.example.com` certificate
|
||||
# - thus, coturn would spin and wait for a certificate until it fails. We'd get a playbook failure due to it, but service manager will proceed to start all other services anyway.
|
||||
# - only later, when the homeserver actually starts, would that certificate be fetched and dumped
|
||||
# - reverse-proxying services get level 3000
|
||||
# - Matrix utility services (bridges, bots) get a level of 2000/2200, so that:
|
||||
@ -3691,7 +3691,7 @@ jitsi_web_stun_servers: |
|
||||
# The Jitsi instance installed by this playbook is meant for embedding into Matrix clients, so framing is allowed.
|
||||
jitsi_web_framing_enabled: true
|
||||
|
||||
# Jitsi (Prosody) only seems to support authenticating with Coturn using `auth-secret`, not `lt-cred-mech`.
|
||||
# Jitsi (Prosody) only seems to support authenticating with coturn using `auth-secret`, not `lt-cred-mech`.
|
||||
# See: https://prosody.im/doc/coturn
|
||||
jitsi_turn_credentials: "{{ matrix_coturn_turn_static_auth_secret if (matrix_coturn_enabled and matrix_coturn_authentication_method == 'auth-secret') else '' }}"
|
||||
jitsi_turn_host: "{{ ('turn.' + matrix_server_fqn_matrix) if matrix_coturn_enabled else '' }}"
|
||||
|
||||
@ -14,9 +14,9 @@ matrix_coturn_docker_image: "{{ matrix_coturn_docker_image_name_prefix }}coturn/
|
||||
matrix_coturn_docker_image_name_prefix: "{{ 'localhost/' if matrix_coturn_container_image_self_build else matrix_container_global_registry_prefix }}"
|
||||
matrix_coturn_docker_image_force_pull: "{{ matrix_coturn_docker_image.endswith(':latest') }}"
|
||||
|
||||
# The Docker network that Coturn would be put into.
|
||||
# The Docker network that coturn would be put into.
|
||||
#
|
||||
# Because Coturn relays traffic to unvalidated IP addresses,
|
||||
# Because coturn relays traffic to unvalidated IP addresses,
|
||||
# using a dedicated network, isolated from other Docker (and local) services is preferrable.
|
||||
#
|
||||
# Setting up deny/allow rules with `matrix_coturn_allowed_peer_ips`/`matrix_coturn_denied_peer_ips` is also
|
||||
@ -24,7 +24,7 @@ matrix_coturn_docker_image_force_pull: "{{ matrix_coturn_docker_image.endswith('
|
||||
#
|
||||
# Setting `matrix_coturn_container_network` to 'host' will run the container with host networking,
|
||||
# which will drastically improve performance when thousands of ports are opened due to Docker not having to set up forwarding rules for each port.
|
||||
# Running with host networking can be dangerous, as it potentially exposes your local network and its services to Coturn peers.
|
||||
# Running with host networking can be dangerous, as it potentially exposes your local network and its services to coturn peers.
|
||||
# Regardless of the networking mode, we apply a deny list which via `matrix_coturn_denied_peer_ips`,
|
||||
# which hopefully prevents access to such private network ranges.
|
||||
# When running in host-networking mode, you need to adjust the firewall yourself, so that ports are opened.
|
||||
@ -51,17 +51,17 @@ matrix_coturn_container_additional_volumes: []
|
||||
# A list of extra arguments to pass to the container
|
||||
matrix_coturn_container_extra_arguments: []
|
||||
|
||||
# Controls whether the Coturn container exposes its plain STUN port (tcp/3478 and udp/3478 in the container).
|
||||
# Controls whether the coturn container exposes its plain STUN port (tcp/3478 and udp/3478 in the container).
|
||||
#
|
||||
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:3478"), or empty string to not expose.
|
||||
matrix_coturn_container_stun_plain_host_bind_port: "{{ '3478' if matrix_coturn_container_network != 'host' else '' }}"
|
||||
|
||||
# Controls whether the Coturn container exposes its TLS STUN port (tcp/5349 and udp/5349 in the container).
|
||||
# Controls whether the coturn container exposes its TLS STUN port (tcp/5349 and udp/5349 in the container).
|
||||
#
|
||||
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:5349"), or empty string to not expose.
|
||||
matrix_coturn_container_stun_tls_host_bind_port: "{{ '5349' if matrix_coturn_container_network != 'host' else '' }}"
|
||||
|
||||
# Controls whether the Coturn container exposes its TURN UDP port range and which interface to do it on.
|
||||
# Controls whether the coturn container exposes its TURN UDP port range and which interface to do it on.
|
||||
#
|
||||
# Takes an interface "<ip address>" (e.g. "127.0.0.1"), or empty string to listen on all interfaces.
|
||||
# Takes a null/none value (`~`) or 'none' (as a string) to prevent listening.
|
||||
@ -93,7 +93,7 @@ matrix_coturn_lt_cred_mech_username: ""
|
||||
# A password used authentication when `matrix_coturn_authentication_method` is `lt-cred-mech`.
|
||||
matrix_coturn_lt_cred_mech_password: ""
|
||||
|
||||
# The external IP address of the machine where Coturn is.
|
||||
# The external IP address of the machine where coturn is.
|
||||
# If do not define an IP address here or in `matrix_coturn_turn_external_ip_addresses`, auto-detection via an EchoIP service will be done.
|
||||
# See `matrix_coturn_turn_external_ip_address_auto_detection_enabled`
|
||||
matrix_coturn_turn_external_ip_address: ''
|
||||
@ -117,11 +117,11 @@ matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_retries_del
|
||||
matrix_coturn_allowed_peer_ips: []
|
||||
|
||||
# We block loopback interfaces and private networks by default to prevent private resources from being accessible.
|
||||
# This is especially important when Coturn does not run within a container network (e.g. `matrix_coturn_container_network: host`).
|
||||
# This is especially important when coturn does not run within a container network (e.g. `matrix_coturn_container_network: host`).
|
||||
#
|
||||
# Learn more: https://www.rtcsec.com/article/cve-2020-26262-bypass-of-coturns-access-control-protection/
|
||||
#
|
||||
# If you're running Coturn for local network peers, you may wish to override these rules.
|
||||
# If you're running coturn for local network peers, you may wish to override these rules.
|
||||
matrix_coturn_denied_peer_ips:
|
||||
- 0.0.0.0-0.255.255.255
|
||||
- 10.0.0.0-10.255.255.255
|
||||
|
||||
@ -32,7 +32,7 @@
|
||||
- ansible.builtin.set_fact:
|
||||
matrix_coturn_turn_external_ip_address: "{{ result_matrix_coturn_turn_external_ip_address_auto_detection_echoip_response.json.ip }}"
|
||||
|
||||
- name: Ensure Matrix Coturn path exists
|
||||
- name: Ensure Matrix coturn path exists
|
||||
ansible.builtin.file:
|
||||
path: "{{ item.path }}"
|
||||
state: directory
|
||||
@ -43,7 +43,7 @@
|
||||
- {path: "{{ matrix_coturn_docker_src_files_path }}", when: "{{ matrix_coturn_container_image_self_build }}"}
|
||||
when: "item.when | bool"
|
||||
|
||||
- name: Ensure Coturn image is pulled
|
||||
- name: Ensure coturn image is pulled
|
||||
community.docker.docker_image:
|
||||
name: "{{ matrix_coturn_docker_image }}"
|
||||
source: "{{ 'pull' if ansible_version.major > 2 or ansible_version.minor > 7 else omit }}"
|
||||
@ -57,7 +57,7 @@
|
||||
|
||||
- when: "matrix_coturn_container_image_self_build | bool"
|
||||
block:
|
||||
- name: Ensure Coturn repository is present on self-build
|
||||
- name: Ensure coturn repository is present on self-build
|
||||
ansible.builtin.git:
|
||||
repo: "{{ matrix_coturn_container_image_self_build_repo }}"
|
||||
dest: "{{ matrix_coturn_docker_src_files_path }}"
|
||||
@ -67,7 +67,7 @@
|
||||
become_user: "{{ matrix_user_username }}"
|
||||
register: matrix_coturn_git_pull_results
|
||||
|
||||
- name: Ensure Coturn Docker image is built
|
||||
- name: Ensure coturn Docker image is built
|
||||
community.docker.docker_image:
|
||||
name: "{{ matrix_coturn_docker_image }}"
|
||||
source: build
|
||||
@ -78,7 +78,7 @@
|
||||
path: "{{ matrix_coturn_docker_src_files_path }}"
|
||||
pull: true
|
||||
|
||||
- name: Ensure Coturn configuration path exists
|
||||
- name: Ensure coturn configuration path exists
|
||||
ansible.builtin.file:
|
||||
path: "{{ matrix_coturn_base_path }}"
|
||||
state: directory
|
||||
@ -94,7 +94,7 @@
|
||||
owner: "{{ matrix_user_username }}"
|
||||
group: "{{ matrix_user_groupname }}"
|
||||
|
||||
- name: Ensure Coturn network is created in Docker
|
||||
- name: Ensure coturn network is created in Docker
|
||||
when: matrix_coturn_container_network not in ['', 'host']
|
||||
community.docker.docker_network:
|
||||
name: "{{ matrix_coturn_container_network }}"
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
---
|
||||
|
||||
- name: (Deprecation) Catch and report renamed Coturn settings
|
||||
- name: (Deprecation) Catch and report renamed coturn settings
|
||||
ansible.builtin.fail:
|
||||
msg: >-
|
||||
Your configuration contains a variable, which now has a different name.
|
||||
@ -15,7 +15,7 @@
|
||||
Invalid authentication method specified in `matrix_coturn_authentication_method`
|
||||
when: "matrix_coturn_authentication_method not in ['auth-secret', 'lt-cred-mech']"
|
||||
|
||||
- name: Fail if required Coturn settings not defined
|
||||
- name: Fail if required coturn settings not defined
|
||||
ansible.builtin.fail:
|
||||
msg: >-
|
||||
You need to define a required configuration setting (`{{ item.name }}`).
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
#jinja2: lstrip_blocks: "True"
|
||||
[Unit]
|
||||
Description=Matrix Coturn server
|
||||
Description=Matrix coturn server
|
||||
{% for service in matrix_coturn_systemd_required_services_list %}
|
||||
Requires={{ service }}
|
||||
After={{ service }}
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user