matrix-docker-ansible-deploy/roles/custom/matrix-coturn/defaults/main.yml

# SPDX-FileCopyrightText: 2019 - 2025 Slavi Pantaleev
# SPDX-FileCopyrightText: 2019 Stuart Mumford
# SPDX-FileCopyrightText: 2019 Sylvia van Os
# SPDX-FileCopyrightText: 2020 - 2021 Dan Arnfield
# SPDX-FileCopyrightText: 2020 Horvath Gergely
# SPDX-FileCopyrightText: 2021 - 2022 MDAD project contributors
# SPDX-FileCopyrightText: 2021 Ahmad Haghighi
# SPDX-FileCopyrightText: 2022 - 2023 Nikita Chernyi
# SPDX-FileCopyrightText: 2022 Hefty Zauk
# SPDX-FileCopyrightText: 2022 Marko Weltzer
# SPDX-FileCopyrightText: 2023 Samuel Meenzen
# SPDX-FileCopyrightText: 2025 Suguru Hirahara
#
# SPDX-License-Identifier: AGPL-3.0-or-later

---
# Project source code URL: https://github.com/coturn/coturn

matrix_coturn_enabled: true

matrix_coturn_hostname: ""

matrix_coturn_container_image_self_build: false
matrix_coturn_container_image_self_build_repo: "https://github.com/coturn/coturn"
matrix_coturn_container_image_self_build_repo_version: "docker/{{ matrix_coturn_version }}"
matrix_coturn_container_image_self_build_repo_dockerfile_path: "docker/coturn/alpine/Dockerfile"

# renovate: datasource=docker depName=coturn/coturn versioning=loose
matrix_coturn_version: 4.8.0
matrix_coturn_docker_image: "{{ matrix_coturn_docker_image_registry_prefix }}coturn/coturn:{{ matrix_coturn_version }}-alpine"
matrix_coturn_docker_image_registry_prefix: "{{ 'localhost/' if matrix_coturn_container_image_self_build else matrix_coturn_docker_image_registry_prefix_upstream }}"
matrix_coturn_docker_image_registry_prefix_upstream: "{{ matrix_coturn_docker_image_registry_prefix_upstream_default }}"
matrix_coturn_docker_image_registry_prefix_upstream_default: docker.io/
matrix_coturn_docker_image_force_pull: "{{ matrix_coturn_docker_image.endswith(':latest') }}"

# The Docker network that coturn would be put into.
#
# Because coturn relays traffic to unvalidated IP addresses,
# using a dedicated network, isolated from other Docker (and local) services is preferable.
#
# Setting up deny/allow rules with `matrix_coturn_allowed_peer_ips`/`matrix_coturn_denied_peer_ips` is also
# possible for achieving such isolation, but is more complicated due to the dynamic nature of Docker networking.
#
# 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.
# 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.
matrix_coturn_container_network: "matrix-coturn"

matrix_coturn_container_additional_networks: "{{ matrix_coturn_container_additional_networks_auto + matrix_coturn_container_additional_networks_custom }}"
matrix_coturn_container_additional_networks_auto: []
matrix_coturn_container_additional_networks_custom: []

matrix_coturn_base_path: "{{ matrix_base_data_path }}/coturn"
matrix_coturn_docker_src_files_path: "{{ matrix_coturn_base_path }}/docker-src"
matrix_coturn_config_path: "{{ matrix_coturn_base_path }}/turnserver.conf"

# List of systemd services that matrix-coturn.service depends on
matrix_coturn_systemd_required_services_list: "{{ matrix_coturn_systemd_required_services_list_default + matrix_coturn_systemd_required_services_list_auto + matrix_coturn_systemd_required_services_list_custom }}"
matrix_coturn_systemd_required_services_list_default: "{{ [devture_systemd_docker_base_docker_service_name] if devture_systemd_docker_base_docker_service_name else [] }}"
matrix_coturn_systemd_required_services_list_auto: []
matrix_coturn_systemd_required_services_list_custom: []

# A list of additional "volumes" to mount in the container.
# This list gets populated dynamically at runtime. You can provide a different default value,
# if you wish to mount your own files into the container.
# Contains definition objects like this: `{"type": "bind", "src": "/outside", "dst": "/inside", "options": "readonly"}.
# See the `--mount` documentation for the `docker run` command.
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 in the container) over TCP.
#
# 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_tcp: "{{ '3478' if matrix_coturn_container_network != 'host' else '' }}"

# Controls whether the coturn container exposes its plain STUN port (udp/3478 in the container) over UDP.
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:3478"), or empty string to not expose.
#
# Ideally, we'd like to set this to "" to avoid exposing this port and decrease the risk of DDoS amplification attacks.
# See: https://stormwall.network/resources/blog/protect-against-ddos-based-on-stun-exploit
# In practice, old Element clients only support talking to the STUN port over UDP, not TCP, so we need to keep this enabled for now.
matrix_coturn_container_stun_plain_host_bind_port_udp: "{{ '3478' if matrix_coturn_container_network != 'host' else '' }}"

# Controls whether the coturn container exposes its TLS STUN port (tcp/5349 in the container) over TCP.
#
# 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_tcp: "{{ '5349' if matrix_coturn_container_network != 'host' else '' }}"

# Controls whether the coturn container exposes its TLS STUN port (udp/5349 in the container) over UDP.
#
# Takes an "<ip>:<port>" or "<port>" value (e.g. "127.0.0.1:5349"), or empty string to not expose.
#
# This is enabled by default, unlike `matrix_coturn_container_stun_plain_host_bind_port_udp`,
# because the risk of DDoS amplification attacks is lower for TLS
# due to the handshake requiring two-way authentication and being generally more expensive.
matrix_coturn_container_stun_tls_host_bind_port_udp: "{{ '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.
#
# 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.
#
# The UDP port-range itself is specified using `matrix_coturn_turn_udp_min_port` and `matrix_coturn_turn_udp_max_port`.
matrix_coturn_container_turn_range_listen_interface: "{{ '' if matrix_coturn_container_network != 'host' else 'none' }}"

# UDP port-range to use for TURN
matrix_coturn_turn_udp_min_port: 49152
matrix_coturn_turn_udp_max_port: 49172

# Controls the `realm` configuration option
matrix_coturn_realm: "turn.{{ matrix_coturn_hostname }}"

# Controls which authentication method to enable.
#
# lt-cred-mech likely provides better compatibility,
# as described here: https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/3191
# but those claims are unverified.
#
# For now, we still default to `auth-secret` like we've always done.
#
# Known values: auth-secret, lt-cred-mech
matrix_coturn_authentication_method: auth-secret

# A shared secret used for authentication when `matrix_coturn_authentication_method` is `auth-secret`.
# You can put any string here, but generating a strong one is preferred. You can create one with a command like `pwgen -s 64 1`.
matrix_coturn_turn_static_auth_secret: ""

# A username used authentication when `matrix_coturn_authentication_method` is `lt-cred-mech`.
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.
# 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: ""
matrix_coturn_turn_external_ip_addresses: "{{ [matrix_coturn_turn_external_ip_address] if matrix_coturn_turn_external_ip_address != '' else [] }}"

# Controls whether external IP address auto-detection should be attempted.
# We try to do this if there is no external IP address explicitly configured and if an EchoIP service URL is specified.
# See matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url
matrix_coturn_turn_external_ip_address_auto_detection_enabled: "{{ matrix_coturn_turn_external_ip_addresses | length == 0 and matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url != '' }}"

# Specifies the address of the EchoIP service (https://github.com/mpolden/echoip) to use for detecting the external IP address.
# By default, we use the official public instance.
matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url: https://ifconfig.co/json

# Controls whether SSL certificates will be validated when contacting the EchoIP service (matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_url)
matrix_coturn_turn_external_ip_address_auto_detection_echoip_validate_certs: true

matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_retries_count: "{{ devture_playbook_help_geturl_retries_count }}"
matrix_coturn_turn_external_ip_address_auto_detection_echoip_service_retries_delay: "{{ devture_playbook_help_geturl_retries_delay }}"

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`).
#
# 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.
matrix_coturn_denied_peer_ips:
  - 0.0.0.0-0.255.255.255
  - 10.0.0.0-10.255.255.255
  - 100.64.0.0-100.127.255.255
  - 127.0.0.0-127.255.255.255
  - 169.254.0.0-169.254.255.255
  - 172.16.0.0-172.31.255.255
  - 192.0.0.0-192.0.0.255
  - 192.0.2.0-192.0.2.255
  - 192.88.99.0-192.88.99.255
  - 192.168.0.0-192.168.255.255
  - 198.18.0.0-198.19.255.255
  - 198.51.100.0-198.51.100.255
  - 203.0.113.0-203.0.113.255
  - 240.0.0.0-255.255.255.255
  - ::1
  - 64:ff9b::-64:ff9b::ffff:ffff
  - ::ffff:0.0.0.0-::ffff:255.255.255.255
  - 100::-100::ffff:ffff:ffff:ffff
  - 2001::-2001:1ff:ffff:ffff:ffff:ffff:ffff:ffff
  - 2002::-2002:ffff:ffff:ffff:ffff:ffff:ffff:ffff
  - fc00::-fdff:ffff:ffff:ffff:ffff:ffff:ffff:ffff
  - fe80::-febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff

matrix_coturn_user_quota: null
matrix_coturn_total_quota: null

# Controls whether `no-tcp-relay` is added to the configuration
# Learn more here: https://github.com/coturn/coturn/blob/242eb78227f66442ba1573c00ec4552faae23eed/examples/etc/turnserver.conf#L419-L422
matrix_coturn_no_tcp_relay_enabled: true

# Controls whether `no-multicast-peers` is added to the configuration
# Learn more here: https://github.com/coturn/coturn/blob/242eb78227f66442ba1573c00ec4552faae23eed/examples/etc/turnserver.conf#L629-L632
matrix_coturn_no_multicast_peers_enabled: true

# Controls whether `no-rfc5780` is added to the configuration
# Learn more here: https://github.com/coturn/coturn/blob/242eb78227f66442ba1573c00ec4552faae23eed/examples/etc/turnserver.conf#L770-L781
matrix_coturn_no_rfc5780_enabled: true

# Controls whether `no-stun-backward-compatibility` is added to the configuration
# Learn more here: https://github.com/coturn/coturn/blob/242eb78227f66442ba1573c00ec4552faae23eed/examples/etc/turnserver.conf#L783-L789
matrix_coturn_no_stun_backward_compatibility_enabled: true

# Controls whether `response-origin-only-with-rfc5780` is added to the configuration
# Learn more here: https://github.com/coturn/coturn/blob/242eb78227f66442ba1573c00ec4552faae23eed/examples/etc/turnserver.conf#L791-L796
matrix_coturn_response_origin_only_with_rfc5780_enabled: true

# Additional configuration to be passed to turnserver.conf
# Example:
# matrix_coturn_additional_configuration: |
#   simple-log
#   aux-server=1.2.3.4
#   relay-ip=4.3.2.1
matrix_coturn_additional_configuration: ""

# To enable TLS, you need to provide paths to certificates.
# Paths defined in `matrix_coturn_tls_cert_path` and `matrix_coturn_tls_key_path` are in-container paths.
# Files on the host can be mounted into the container using `matrix_coturn_container_additional_volumes`.
matrix_coturn_tls_enabled: false
matrix_coturn_tls_cert_path: ~
matrix_coturn_tls_key_path: ~

matrix_coturn_tls_v1_enabled: false
matrix_coturn_tls_v1_1_enabled: false

# systemd calendar configuration for the reload job
# the actual job may run with a delay (see matrix_coturn_reload_schedule_randomized_delay_sec)
matrix_coturn_reload_schedule: "*-*-* 06:30:00"
# the delay with which the systemd timer may run in relation to the `matrix_coturn_reload_schedule` schedule
matrix_coturn_reload_schedule_randomized_delay_sec: 1h