diff --git a/latest/deprecation_policy.html b/latest/deprecation_policy.html
index e380dbf28d..505d1bb7ec 100644
--- a/latest/deprecation_policy.html
+++ b/latest/deprecation_policy.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/cas.html b/latest/development/cas.html
index f1933efb7c..d1afe72f5a 100644
--- a/latest/development/cas.html
+++ b/latest/development/cas.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/contributing_guide.html b/latest/development/contributing_guide.html
index 766f722109..a4183e11e3 100644
--- a/latest/development/contributing_guide.html
+++ b/latest/development/contributing_guide.html
@@ -76,7 +76,7 @@
@@ -355,7 +355,16 @@ Here is how to run your local Synapse checkout against your local Complement che
The above will run a monolithic (single-process) Synapse with SQLite as the database. For other configurations, try:
- Passing
POSTGRES=1
as an environment variable to use the Postgres database instead.
-- Passing
WORKERS=1
as an environment variable to use a workerised setup instead. This option implies the use of Postgres.
+- Passing
WORKERS=1
as an environment variable to use a workerised setup instead. This option implies the use of Postgres.
+
+- If setting
WORKERS=1
, optionally set WORKER_TYPES=
to declare which worker
+types you wish to test. A simple comma-delimited string containing the worker types
+defined from the WORKERS_CONFIG
template in
+here.
+A safe example would be WORKER_TYPES="federation_inbound, federation_sender, synchrotron"
.
+See the worker documentation for additional information on workers.
+
+
To increase the log level for the tests, set SYNAPSE_TEST_LOG_LEVEL
, e.g:
SYNAPSE_TEST_LOG_LEVEL=DEBUG COMPLEMENT_DIR=../complement ./scripts-dev/complement.sh -run TestImportHistoricalMessages
diff --git a/latest/development/database_schema.html b/latest/development/database_schema.html
index f751907446..5d830745e0 100644
--- a/latest/development/database_schema.html
+++ b/latest/development/database_schema.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/demo.html b/latest/development/demo.html
index e845b6be79..131c66d4ae 100644
--- a/latest/development/demo.html
+++ b/latest/development/demo.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/dependencies.html b/latest/development/dependencies.html
index 7559d61c5c..a0823a71c6 100644
--- a/latest/development/dependencies.html
+++ b/latest/development/dependencies.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/experimental_features.html b/latest/development/experimental_features.html
index 696cf0b781..4293989190 100644
--- a/latest/development/experimental_features.html
+++ b/latest/development/experimental_features.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/git.html b/latest/development/git.html
index 436b6cb0c7..1a2a3ed0ed 100644
--- a/latest/development/git.html
+++ b/latest/development/git.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/internal_documentation/index.html b/latest/development/internal_documentation/index.html
index 0bc42d3181..14b78ce1ce 100644
--- a/latest/development/internal_documentation/index.html
+++ b/latest/development/internal_documentation/index.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/releases.html b/latest/development/releases.html
index 01faa600fc..8e73776887 100644
--- a/latest/development/releases.html
+++ b/latest/development/releases.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/reviews.html b/latest/development/reviews.html
index 0e14676fb8..661d0cd7d3 100644
--- a/latest/development/reviews.html
+++ b/latest/development/reviews.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/room-dag-concepts.html b/latest/development/room-dag-concepts.html
index 0ad287c56f..687941d5d2 100644
--- a/latest/development/room-dag-concepts.html
+++ b/latest/development/room-dag-concepts.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/saml.html b/latest/development/saml.html
index de94332fbe..e21d487d0a 100644
--- a/latest/development/saml.html
+++ b/latest/development/saml.html
@@ -76,7 +76,7 @@
diff --git a/latest/development/synapse_architecture/cancellation.html b/latest/development/synapse_architecture/cancellation.html
index 3283f78c91..43ad7d2b41 100644
--- a/latest/development/synapse_architecture/cancellation.html
+++ b/latest/development/synapse_architecture/cancellation.html
@@ -76,7 +76,7 @@
diff --git a/latest/federate.html b/latest/federate.html
index 3c69cebf85..cf1af3a0ce 100644
--- a/latest/federate.html
+++ b/latest/federate.html
@@ -76,7 +76,7 @@
diff --git a/latest/index.html b/latest/index.html
index 8ce56c0da5..e240352bac 100644
--- a/latest/index.html
+++ b/latest/index.html
@@ -76,7 +76,7 @@
diff --git a/latest/jwt.html b/latest/jwt.html
index bfe015e698..fe60824bc5 100644
--- a/latest/jwt.html
+++ b/latest/jwt.html
@@ -76,7 +76,7 @@
diff --git a/latest/log_contexts.html b/latest/log_contexts.html
index 83a6dafb1f..4cea47c12f 100644
--- a/latest/log_contexts.html
+++ b/latest/log_contexts.html
@@ -76,7 +76,7 @@
diff --git a/latest/manhole.html b/latest/manhole.html
index 4113fd523a..e826691f01 100644
--- a/latest/manhole.html
+++ b/latest/manhole.html
@@ -76,7 +76,7 @@
diff --git a/latest/media_repository.html b/latest/media_repository.html
index d053d174e6..d7a86ba6e9 100644
--- a/latest/media_repository.html
+++ b/latest/media_repository.html
@@ -76,7 +76,7 @@
diff --git a/latest/message_retention_policies.html b/latest/message_retention_policies.html
index ebd3f2d21a..214e862ab4 100644
--- a/latest/message_retention_policies.html
+++ b/latest/message_retention_policies.html
@@ -76,7 +76,7 @@
diff --git a/latest/metrics-howto.html b/latest/metrics-howto.html
index 62f4307dde..46cf8a2bd9 100644
--- a/latest/metrics-howto.html
+++ b/latest/metrics-howto.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/account_data_callbacks.html b/latest/modules/account_data_callbacks.html
index b6c10aa3ff..1a7d4497f5 100644
--- a/latest/modules/account_data_callbacks.html
+++ b/latest/modules/account_data_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/account_validity_callbacks.html b/latest/modules/account_validity_callbacks.html
index f5ff160ed3..1c8deed4b6 100644
--- a/latest/modules/account_validity_callbacks.html
+++ b/latest/modules/account_validity_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/background_update_controller_callbacks.html b/latest/modules/background_update_controller_callbacks.html
index 31c0dcaf9d..9a007d1287 100644
--- a/latest/modules/background_update_controller_callbacks.html
+++ b/latest/modules/background_update_controller_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/index.html b/latest/modules/index.html
index 9e2e86535e..391bc33f73 100644
--- a/latest/modules/index.html
+++ b/latest/modules/index.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/password_auth_provider_callbacks.html b/latest/modules/password_auth_provider_callbacks.html
index 7a9c84e322..b87f318ff7 100644
--- a/latest/modules/password_auth_provider_callbacks.html
+++ b/latest/modules/password_auth_provider_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/porting_legacy_module.html b/latest/modules/porting_legacy_module.html
index b58f3f33aa..4765b94e84 100644
--- a/latest/modules/porting_legacy_module.html
+++ b/latest/modules/porting_legacy_module.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/presence_router_callbacks.html b/latest/modules/presence_router_callbacks.html
index 7d36b48176..5b4e40a0db 100644
--- a/latest/modules/presence_router_callbacks.html
+++ b/latest/modules/presence_router_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/spam_checker_callbacks.html b/latest/modules/spam_checker_callbacks.html
index 7b20101fb3..fde6e6fb76 100644
--- a/latest/modules/spam_checker_callbacks.html
+++ b/latest/modules/spam_checker_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/third_party_rules_callbacks.html b/latest/modules/third_party_rules_callbacks.html
index aedda2061f..b8f0a9fcda 100644
--- a/latest/modules/third_party_rules_callbacks.html
+++ b/latest/modules/third_party_rules_callbacks.html
@@ -76,7 +76,7 @@
diff --git a/latest/modules/writing_a_module.html b/latest/modules/writing_a_module.html
index 97c97f87f7..5922ee854b 100644
--- a/latest/modules/writing_a_module.html
+++ b/latest/modules/writing_a_module.html
@@ -76,7 +76,7 @@
diff --git a/latest/openid.html b/latest/openid.html
index cd0faad571..bc42e6c8c8 100644
--- a/latest/openid.html
+++ b/latest/openid.html
@@ -76,7 +76,7 @@
diff --git a/latest/opentracing.html b/latest/opentracing.html
index 6113cc9972..40c589cae0 100644
--- a/latest/opentracing.html
+++ b/latest/opentracing.html
@@ -76,7 +76,7 @@
diff --git a/latest/other/running_synapse_on_single_board_computers.html b/latest/other/running_synapse_on_single_board_computers.html
index 2b945712ea..05247caa4e 100644
--- a/latest/other/running_synapse_on_single_board_computers.html
+++ b/latest/other/running_synapse_on_single_board_computers.html
@@ -76,7 +76,7 @@
diff --git a/latest/password_auth_providers.html b/latest/password_auth_providers.html
index 449b750472..57f2b60371 100644
--- a/latest/password_auth_providers.html
+++ b/latest/password_auth_providers.html
@@ -76,7 +76,7 @@
diff --git a/latest/postgres.html b/latest/postgres.html
index 7ab14c569e..60245b3ce3 100644
--- a/latest/postgres.html
+++ b/latest/postgres.html
@@ -76,7 +76,7 @@
diff --git a/latest/print.html b/latest/print.html
index d540eab919..565af5df9d 100644
--- a/latest/print.html
+++ b/latest/print.html
@@ -77,7 +77,7 @@
@@ -919,6 +919,9 @@ reverse proxy is using.
# Nginx by default only allows file uploads up to 1M in size
# Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
client_max_body_size 50M;
+
+ # Synapse responses may be chunked, which is an HTTP/1.1 feature.
+ proxy_http_version 1.1;
}
}
@@ -1155,17 +1158,163 @@ TURN.
allows the homeserver to generate credentials that are valid for use on the
TURN server through the use of a secret shared between the homeserver and the
TURN server.
-The following sections describe how to install coturn (which implements the TURN REST API) and integrate it with synapse.
+This documentation provides two TURN server configuration examples:
+
-For TURN relaying with coturn
to work, it must be hosted on a server/endpoint with a public IP.
+For TURN relaying to work, the TURN service must be hosted on a server/endpoint with a public IP.
Hosting TURN behind NAT requires port forwaring and for the NAT gateway to have a public IP.
However, even with appropriate configuration, NAT is known to cause issues and to often not work.
+Afterwards, the homeserver needs some further configuration.
+
+Your homeserver configuration file needs the following extra keys:
+
+turn_uris
+turn_shared_secret
+turn_user_lifetime
+turn_allow_guests
+
+As an example, here is the relevant section of the config file for matrix.org
. The
+turn_uris
are appropriate for TURN servers listening on the default ports, with no TLS.
+turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
+turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
+turn_user_lifetime: 86400000
+turn_allow_guests: True
+
+After updating the homeserver configuration, you must restart synapse:
+
+- If you use synctl:
+
# Depending on how Synapse is installed, synctl may already be on
+# your PATH. If not, you may need to activate a virtual environment.
+synctl restart
+
+
+- If you use systemd:
+
systemctl restart matrix-synapse.service
+
+
+
+... and then reload any clients (or wait an hour for them to refresh their
+settings).
+
+The normal symptoms of a misconfigured TURN server are that calls between
+devices on different networks ring, but get stuck at "call
+connecting". Unfortunately, troubleshooting this can be tricky.
+Here are a few things to try:
+
+-
+
Check that you have opened your firewall to allow TCP and UDP traffic to the
+TURN ports (normally 3478 and 5349).
+
+-
+
Check that you have opened your firewall to allow UDP traffic to the UDP
+relay ports (49152-65535 by default).
+
+-
+
Try disabling TLS/DTLS listeners and enable only its (unencrypted)
+TCP/UDP listeners. (This will only leave signaling traffic unencrypted;
+voice & video WebRTC traffic is always encrypted.)
+
+-
+
Some WebRTC implementations (notably, that of Google Chrome) appear to get
+confused by TURN servers which are reachable over IPv6 (this appears to be
+an unexpected side-effect of its handling of multiple IP addresses as
+defined by
+draft-ietf-rtcweb-ip-handling
).
+Try removing any AAAA records for your TURN server, so that it is only
+reachable over IPv4.
+
+-
+
If your TURN server is behind NAT:
+
+-
+
double-check that your NAT gateway is correctly forwarding all TURN
+ports (normally 3478 & 5349 for TCP & UDP TURN traffic, and 49152-65535 for the UDP
+relay) to the NAT-internal address of your TURN server. If advertising
+both IPv4 and IPv6 external addresses via the external-ip
option, ensure
+that the NAT is forwarding both IPv4 and IPv6 traffic to the IPv4 and IPv6
+internal addresses of your TURN server. When in doubt, remove AAAA records
+for your TURN server and specify only an IPv4 address as your external-ip
.
+
+-
+
ensure that your TURN server uses the NAT gateway as its default route.
+
+
+
+-
+
Enable more verbose logging, in coturn
via the verbose
setting:
+verbose
+
+or with eturnal
with the shell command eturnalctl loglevel debug
or in the configuration file (the service needs to reload for it to become effective):
+ ## Logging configuration:
+ log_level: debug
+
+... and then see if there are any clues in its logs.
+
+-
+
If you are using a browser-based client under Chrome, check
+chrome://webrtc-internals/
for insights into the internals of the
+negotiation. On Firefox, check the "Connection Log" on about:webrtc
.
+(Understanding the output is beyond the scope of this document!)
+
+-
+
You can test your Matrix homeserver TURN setup with https://test.voip.librepush.net/.
+Note that this test is not fully reliable yet, so don't be discouraged if
+the test fails.
+Here is the github repo of the
+source of the tester, where you can file bug reports.
+
+-
+
There is a WebRTC test tool at
+https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. To
+use it, you will need a username/password for your TURN server. You can
+either:
+
+-
+
look for the GET /_matrix/client/r0/voip/turnServer
request made by a
+matrix client to your homeserver in your browser's network inspector. In
+the response you should see username
and password
. Or:
+
+-
+
Use the following shell commands for coturn
:
+secret=staticAuthSecretHere
+
+u=$((`date +%s` + 3600)):test
+p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64)
+echo -e "username: $u\npassword: $p"
+
+or for eturnal
+eturnalctl credentials
+
+
+-
+
Or (coturn only): Temporarily configure coturn
to accept a static
+username/password. To do this, comment out use-auth-secret
and
+static-auth-secret
and add the following:
+lt-cred-mech
+user=username:password
+
+Note: these settings will not take effect unless use-auth-secret
+and static-auth-secret
are disabled.
+Restart coturn after changing the configuration file.
+Remember to restore the original settings to go back to testing with
+Matrix clients!
+
+
+If the TURN server is working correctly, you should see at least one relay
+entry in the results.
+
+
+
+The following sections describe how to install coturn (which implements the TURN REST API).
The TURN daemon coturn
is available from a variety of sources such as native package managers, or installation from source.
-
+
Just install the debian package:
-apt install coturn
+sudo apt install coturn
This will install and start a systemd service called coturn
.
@@ -1185,7 +1334,7 @@ for this purpose.
Build and install it:
make
-make install
+sudo make install
@@ -1207,13 +1356,13 @@ sent to clients as part of the authentication flow.) It is conventional to
set it to be your server name.
-You will most likely want to configure coturn to write logs somewhere. The
+
You will most likely want to configure coturn
to write logs somewhere. The
easiest way is normally to send them to the syslog:
syslog
(in which case, the logs will be available via journalctl -u coturn
on a
-systemd system). Alternatively, coturn can be configured to write to a
-logfile - check the example config file supplied with coturn.
+systemd system). Alternatively, coturn
can be configured to write to a
+logfile - check the example config file supplied with coturn
.
Consider your security settings. TURN lets users request a relay which will
@@ -1286,7 +1435,7 @@ for the UDP relay.)
If your TURN server is behind NAT, the NAT gateway must have an external,
-publicly-reachable IP address. You must configure coturn to advertise that
+publicly-reachable IP address. You must configure coturn
to advertise that
address to connecting clients:
external-ip=EXTERNAL_NAT_IPv4_ADDRESS
@@ -1295,7 +1444,7 @@ address that is mapped by NAT to the external address:
listening-ip=INTERNAL_TURNSERVER_IPv4_ADDRESS
If your NAT gateway is reachable over both IPv4 and IPv6, you may
-configure coturn to advertise each available address:
+configure coturn
to advertise each available address:
external-ip=EXTERNAL_NAT_IPv4_ADDRESS
external-ip=EXTERNAL_NAT_IPv6_ADDRESS
@@ -1309,164 +1458,152 @@ IPv6 address that is mapped by NAT to the external IPv6 address.
-
If you used the Debian package (or have set up a systemd unit yourself):
-systemctl restart coturn
+sudo systemctl restart coturn
-
-
If you installed from source:
-bin/turnserver -o
+If you built from source:
+/usr/local/bin/turnserver -o
-
-Your homeserver configuration file needs the following extra keys:
+
+The following sections describe how to install eturnal
+(which implements the TURN REST API).
+
+
+The eturnal
TURN server implementation is available from a variety of sources
+such as native package managers, binary packages, installation from source or
+container image. They are
+all described here.
+Quick-Test instructions in a Linux Shell
+or with Docker
+are available as well.
+
+After installation, eturnal
usually ships a default configuration file
+here: /etc/eturnal.yml
(and, if not found there, there is a backup file here:
+/opt/eturnal/etc/eturnal.yml
). It uses the (indentation-sensitive!) YAML
+format. The file contains further explanations.
+Here are some hints how to configure eturnal on your host machine
+or when using e.g. Docker.
+You may also further deep dive into the reference documentation.
+eturnal
runs out of the box with the default configuration. To enable TURN and
+to integrate it with your homeserver, some aspects in eturnal
's default configuration file
+must be edited:
-- "
turn_uris
": This needs to be a yaml list of public-facing URIs
-for your TURN server to be given out to your clients. Add separate
-entries for each transport your TURN server supports.
-- "
turn_shared_secret
": This is the secret shared between your
-homeserver and your TURN server, so you should set it to the same
-string you used in turnserver.conf.
-- "
turn_user_lifetime
": This is the amount of time credentials
-generated by your homeserver are valid for (in milliseconds).
-Shorter times offer less potential for abuse at the expense of
-increased traffic between web clients and your homeserver to
-refresh credentials. The TURN REST API specification recommends
-one day (86400000).
-- "
turn_allow_guests
": Whether to allow guest users to use the
-TURN server. This is enabled by default, as otherwise VoIP will
-not work reliably for guests. However, it does introduce a
-security risk as it lets guests connect to arbitrary endpoints
-without having gone through a CAPTCHA or similar to register a
-real account.
-
-As an example, here is the relevant section of the config file for matrix.org
. The
-turn_uris
are appropriate for TURN servers listening on the default ports, with no TLS.
-turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
-turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
-turn_user_lifetime: 86400000
-turn_allow_guests: True
-
-After updating the homeserver configuration, you must restart synapse:
-
-- If you use synctl:
-
# Depending on how Synapse is installed, synctl may already be on
-# your PATH. If not, you may need to activate a virtual environment.
-synctl restart
+-
+
Homeserver's turn_shared_secret
+and eturnal's shared secret
for authentication
+Both need to have the same value. Uncomment and adjust this line in eturnal
's
+configuration file:
+secret: "long-and-cryptic" # Shared secret, CHANGE THIS.
-
-- If you use systemd:
-
systemctl restart matrix-synapse.service
+One way to generate a secret
is with pwgen
:
+pwgen -s 64 1
-
-... and then reload any clients (or wait an hour for them to refresh their
-settings).
-
-The normal symptoms of a misconfigured TURN server are that calls between
-devices on different networks ring, but get stuck at "call
-connecting". Unfortunately, troubleshooting this can be tricky.
-Here are a few things to try:
-
--
-
Check that you have opened your firewall to allow TCP and UDP traffic to the
-TURN ports (normally 3478 and 5349).
-
--
-
Check that you have opened your firewall to allow UDP traffic to the UDP
-relay ports (49152-65535 by default).
-
--
-
Try disabling coturn
's TLS/DTLS listeners and enable only its (unencrypted)
-TCP/UDP listeners. (This will only leave signaling traffic unencrypted;
-voice & video WebRTC traffic is always encrypted.)
-
-
-
Some WebRTC implementations (notably, that of Google Chrome) appear to get
-confused by TURN servers which are reachable over IPv6 (this appears to be
-an unexpected side-effect of its handling of multiple IP addresses as
-defined by
-draft-ietf-rtcweb-ip-handling
).
-Try removing any AAAA records for your TURN server, so that it is only
-reachable over IPv4.
-
--
-
If your TURN server is behind NAT:
-
--
-
double-check that your NAT gateway is correctly forwarding all TURN
-ports (normally 3478 & 5349 for TCP & UDP TURN traffic, and 49152-65535 for the UDP
-relay) to the NAT-internal address of your TURN server. If advertising
-both IPv4 and IPv6 external addresses via the external-ip
option, ensure
-that the NAT is forwarding both IPv4 and IPv6 traffic to the IPv4 and IPv6
-internal addresses of your TURN server. When in doubt, remove AAAA records
-for your TURN server and specify only an IPv4 address as your external-ip
.
-
--
-
ensure that your TURN server uses the NAT gateway as its default route.
-
-
-
--
-
Enable more verbose logging in coturn via the verbose
setting:
-verbose
+Public IP address
+If your TURN server is behind NAT, the NAT gateway must have an external,
+publicly-reachable IP address. eturnal
tries to autodetect the public IP address,
+however, it may also be configured by uncommenting and adjusting this line, so
+eturnal
advertises that address to connecting clients:
+relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
-... and then see if there are any clues in its logs.
+If your NAT gateway is reachable over both IPv4 and IPv6, you may
+configure eturnal
to advertise each available address:
+relay_ipv4_addr: "203.0.113.4" # The server's public IPv4 address.
+relay_ipv6_addr: "2001:db8::4" # The server's public IPv6 address (optional).
+
+When advertising an external IPv6 address, ensure that the firewall and
+network settings of the system running your TURN server are configured to
+accept IPv6 traffic, and that the TURN server is listening on the local
+IPv6 address that is mapped by NAT to the external IPv6 address.
-
-
If you are using a browser-based client under Chrome, check
-chrome://webrtc-internals/
for insights into the internals of the
-negotiation. On Firefox, check the "Connection Log" on about:webrtc
.
-(Understanding the output is beyond the scope of this document!)
+Logging
+If eturnal
was started by systemd, log files are written into the
+/var/log/eturnal
directory by default. In order to log to the journal
+instead, the log_dir
option can be set to stdout
in the configuration file.
-
-
You can test your Matrix homeserver TURN setup with https://test.voip.librepush.net/.
-Note that this test is not fully reliable yet, so don't be discouraged if
-the test fails.
-Here is the github repo of the
-source of the tester, where you can file bug reports.
-
--
-
There is a WebRTC test tool at
-https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/. To
-use it, you will need a username/password for your TURN server. You can
-either:
-
--
-
look for the GET /_matrix/client/r0/voip/turnServer
request made by a
-matrix client to your homeserver in your browser's network inspector. In
-the response you should see username
and password
. Or:
+Security considerations
+Consider your security settings. TURN lets users request a relay which will
+connect to arbitrary IP addresses and ports. The following configuration is
+suggested as a minimum starting point, see also the official documentation:
+## Reject TURN relaying from/to the following addresses/networks:
+blacklist: # This is the default blacklist.
+ - "127.0.0.0/8" # IPv4 loopback.
+ - "::1" # IPv6 loopback.
+ - recommended # Expands to a number of networks recommended to be
+ # blocked, but includes private networks. Those
+ # would have to be 'whitelist'ed if eturnal serves
+ # local clients/peers within such networks.
+
+To whitelist IP addresses or specific (private) networks, you need to add a
+whitelist part into the configuration file, e.g.:
+whitelist:
+ - "192.168.0.0/16"
+ - "203.0.113.113"
+ - "2001:db8::/64"
+
+The more specific, the better.
+
+-
+
TURNS (TURN via TLS/DTLS)
+Also consider supporting TLS/DTLS. To do this, adjust the following settings
+in the eturnal.yml
configuration file (TLS parts should not be commented anymore):
+listen:
+ - ip: "::"
+ port: 3478
+ transport: udp
+ - ip: "::"
+ port: 3478
+ transport: tcp
+ - ip: "::"
+ port: 5349
+ transport: tls
+
+## TLS certificate/key files (must be readable by 'eturnal' user!):
+tls_crt_file: /etc/eturnal/tls/crt.pem
+tls_key_file: /etc/eturnal/tls/key.pem
+
+In this case, replace the turn:
schemes in homeserver's turn_uris
settings
+with turns:
. More is described here.
+We recommend that you only try to set up TLS/DTLS once you have set up a
+basic installation and got it working.
+NB: If your TLS certificate was provided by Let's Encrypt, TLS/DTLS will
+not work with any Matrix client that uses Chromium's WebRTC library. This
+currently includes Element Android & iOS; for more details, see their
+respective
+issues as well as the underlying
+WebRTC issue.
+Consider using a ZeroSSL certificate for your TURN server as a working alternative.
-
-
Use the following shell commands:
-secret=staticAuthSecretHere
-
-u=$((`date +%s` + 3600)):test
-p=$(echo -n $u | openssl dgst -hmac $secret -sha1 -binary | base64)
-echo -e "username: $u\npassword: $p"
-
-Or:
+Firewall
+Ensure your firewall allows traffic into the TURN server on the ports
+you've configured it to listen on (By default: 3478 and 5349 for TURN
+traffic (remember to allow both TCP and UDP traffic), and ports 49152-65535
+for the UDP relay.)
-
-
Temporarily configure coturn to accept a static username/password. To do
-this, comment out use-auth-secret
and static-auth-secret
and add the
-following:
-lt-cred-mech
-user=username:password
+Reload/ restarting eturnal
+Changes in the configuration file require eturnal
to reload/ restart, this
+can be achieved by:
+eturnalctl reload
-Note: these settings will not take effect unless use-auth-secret
-and static-auth-secret
are disabled.
-Restart coturn after changing the configuration file.
-Remember to restore the original settings to go back to testing with
-Matrix clients!
-
-
-If the TURN server is working correctly, you should see at least one relay
-entry in the results.
+eturnal
performs a configuration check before actually reloading/ restarting
+and provides hints, if something is not correctly configured.
-
+
+
+eturnal
offers a handy operations script
+which can be called e.g. to check, whether the service is up, to restart the service,
+to query how many active sessions exist, to change logging behaviour and so on.
+Hint: If eturnalctl
is not part of your $PATH
, consider either sym-linking it (e.g. ´ln -s /opt/eturnal/bin/eturnalctl /usr/local/bin/eturnalctl´) or call it from the default eturnal
directory directly: e.g. /opt/eturnal/bin/eturnalctl info
In the following documentation, we use the term server_name
to refer to that setting
in your homeserver configuration file. It appears at the ends of user ids, and tells
@@ -1624,6 +1761,11 @@ dpkg -i matrix-synapse-py3_1.3.0+stretch1_amd64.deb
+
+
+In line with our deprecation policy, we've dropped
+support for PostgreSQL 10, as it is no longer supported upstream.
+This release of Synapse requires PostgreSQL 11+.
As announced with the release of Synapse 1.69.0, the deprecated generate_short_term_login_token
module method has been removed.
@@ -3303,7 +3445,7 @@ release of Synapse.
private federation, there is a script in the demo
directory. This is mainly
useful just for development purposes. See
This section contains information on tweaking Synapse via the various options in the configuration file. A configuration
file should have been generated when you installed Synapse.
Whether TLS should be used for talking to the HTTP replication port on the main
+Synapse process.
+The main Synapse process defines this with the tls
option on its listener that
+has the replication
resource enabled.
+This API returns the running Synapse version and the Python version
on which Synapse is being run. This is useful when a Synapse instance
@@ -14961,7 +15142,16 @@ Here is how to run your local Synapse checkout against your local Complement che
The above will run a monolithic (single-process) Synapse with SQLite as the database. For other configurations, try: