mirror of
https://forgejo.ellis.link/continuwuation/continuwuity.git
synced 2026-11-15 13:16:56 +00:00
docs(turn,livekit): Small changes
* Small wording changes on calls.mdx * Add env var sample for livekit foci * Simplify TURNS-over-443 Caddyfile (livekit + turn) * Improve TURNS-over-443 wordings (livekit + turn) * Link to MRTC room on turn documentation
This commit is contained in:
stratself authored and 
Ellis Git committed
1 parent
e14a86026a
commit
a73cdbeff2
3 files changed
+55
-59
No files matched your search
+29
-42
@@ -2,7 +2,11 @@
|
||||
|
||||
[TURN][turn] and [STUN][stun] are used as a component in many calling systems. Matrix uses them directly for legacy calls and indirectly for MatrixRTC via Livekit.
|
||||
|
||||
Continuwuity recommends using [Coturn][coturn] as your TURN/STUN server, which is available as a Docker image or a distro package.
|
||||
Continuwuity recommends using [Coturn][coturn] as your TURN/STUN server, which is available as a Docker image or a distro package. This guide assumes that you are using docker compose for deployment.
|
||||
|
||||
:::tip
|
||||
You can find help setting up TURN/STUN in our MatrixRTC room - [#matrixrtc:continuwuity.org](https://matrix.to/#/%23matrixrtc%3Acontinuwuity.org)
|
||||
:::
|
||||
|
||||
[turn]: https://en.wikipedia.org/wiki/Traversal_Using_Relays_around_NAT
|
||||
[stun]: https://en.wikipedia.org/wiki/STUN
|
||||
@@ -50,8 +54,6 @@ Next, we will start the Coturn container with the [official image][coturn-image]
|
||||
[coturn-image]: https://hub.docker.com/r/coturn/coturn
|
||||
[coturn-docker-docs]: https://github.com/coturn/coturn/blob/master/docker/coturn/README.md#why-so-many-ports-opened
|
||||
|
||||
#### With Docker Compose (recommended)
|
||||
|
||||
Create a `docker-compose.yml` file as follows and run `docker compose up -d`:
|
||||
|
||||
```yaml
|
||||
@@ -68,15 +70,6 @@ services:
|
||||
- /path/to/certs:/etc/letsencrypt
|
||||
```
|
||||
|
||||
#### With Docker
|
||||
|
||||
```bash
|
||||
docker run -d --network=host \
|
||||
-v $(pwd)/coturn.conf:/etc/coturn/turnserver.conf \
|
||||
-v /path/to/certs:/etc/letsencrypt # replace this with actual paths to your certificates
|
||||
coturn/coturn
|
||||
```
|
||||
|
||||
### 4. Opening ports
|
||||
|
||||
By default, coturn uses the following ports:
|
||||
@@ -165,9 +158,9 @@ You should receive a response like this:
|
||||
"username": "1752792167:@jade:example.com",
|
||||
"password": "KjlDlawdPbU9mvP4bhdV/2c/h65=",
|
||||
"uris": [
|
||||
"turns:coturn.example.com?transport=tcp",
|
||||
"turn:coturn.example.com?transport=udp",
|
||||
"turn:coturn.example.com?transport=tcp"
|
||||
"turns:coturn.example.com:3478?transport=tcp",
|
||||
"turn:coturn.example.com:3478?transport=udp",
|
||||
"turn:coturn.example.com:5349?transport=tcp"
|
||||
],
|
||||
"ttl": 86400
|
||||
}
|
||||
@@ -187,10 +180,13 @@ If you see `relay` candidates in the results, your TURN/STUN server is working c
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
To gather debug logs while troubleshooting Coturn, add `verbose` to your `coturn.conf`. You can then view these logs with `docker-compose logs --follow coturn`.
|
||||
|
||||
### Errors with Trickle ICE
|
||||
|
||||
- `code=701` - the TURN server is not reachable
|
||||
- Verify firewall rules allow the necessary ports (3478, 5349, and your media port range)
|
||||
- Verify via logs that coturn is exposed on the correct addresses and interfaces
|
||||
- Check that DNS resolves correctly for your TURN domain
|
||||
- `code=401` - unauthorized credentials
|
||||
- Ensure your `turn_secret` matches coturn's `static-auth-secret`
|
||||
@@ -227,11 +223,11 @@ If you instead prefer to use [eturnal][eturnal], you can refer to the guides bel
|
||||
|
||||
### TURNS-over-443
|
||||
|
||||
In very restrictive networks where UDP traffic and non-standard ports are disallowed, normal TURN servers are not reachable. To establish connectivity in these scenarios, a common solution is to host a TURN-over-TLS server on port 443, and allow clients to connect to it like any other web traffic.
|
||||
Normally, TURN would work on their default setups. However, there are situations where clients are in very restrictive networks that disallows non-standard ports and UDP. In these cases, a TURN-over-TLS server on port :443 could be employed to relay traffic for them.
|
||||
|
||||
However, port 443 is usually utilized by other HTTPS services. Therefore, one would need to **multiplex** both the TURN and the HTTPS services, and filter packets to them via **SNI routing**. A layer-4 load balancer such as caddy-l4 can serve this function.
|
||||
However, port 443 is usually utilized by other HTTPS services. Therefore, one would need to **multiplex** both TURN HTTPS on these ports, and filter packets to them via **SNI routing**.
|
||||
|
||||
Below are Caddyfile examples to multiplex both the TURNS service and LiveKit on port 443. It requires the [caddy-l4][caddy-l4] plugin to be compiled with your Caddy binary.
|
||||
Below are examples to multiplex Coturn and [LiveKit](./livekit.mdx) on port 443, using [caddy-l4][caddy-l4] on the host system.
|
||||
|
||||
<details>
|
||||
|
||||
@@ -248,20 +244,16 @@ Please note that all traffic from Coturn's perspective will be coming from caddy
|
||||
{
|
||||
servers {
|
||||
listener_wrappers {
|
||||
|
||||
# intercept packets meant for the TURN domain first
|
||||
# before forwarding other packets to "normal" HTTP listeners
|
||||
layer4 {
|
||||
@turn {
|
||||
tls {
|
||||
sni turn.example.com
|
||||
}
|
||||
}
|
||||
@turn tls sni turn.example.com
|
||||
route @turn {
|
||||
proxy {
|
||||
upstream 127.0.0.1:5349 # forward to normal TURNS port
|
||||
}
|
||||
proxy 127.0.0.1:5349 # forward to normal TURNS port
|
||||
}
|
||||
}
|
||||
|
||||
tls
|
||||
}
|
||||
}
|
||||
@@ -296,7 +288,6 @@ First, enable coturn's PROXY-protocol accepting port by adding this:
|
||||
```ini
|
||||
# in coturn.conf
|
||||
tcp-proxy-port=5555
|
||||
|
||||
```
|
||||
|
||||
Then, in the Caddyfile:
|
||||
@@ -305,14 +296,12 @@ Then, in the Caddyfile:
|
||||
{
|
||||
servers {
|
||||
listener_wrappers {
|
||||
|
||||
# intercept packets meant for the TURN domain first
|
||||
# before forwarding other packets to "normal" HTTP listeners
|
||||
layer4 {
|
||||
@turn {
|
||||
tls {
|
||||
sni turn.example.com
|
||||
}
|
||||
}
|
||||
@turn tlssni turn.example.com
|
||||
|
||||
route @turn {
|
||||
tls # terminate TLS for the turn.example.com packets
|
||||
proxy {
|
||||
@@ -320,7 +309,6 @@ Then, in the Caddyfile:
|
||||
upstream 127.0.0.1:5555
|
||||
proxy_protocol v2
|
||||
}
|
||||
|
||||
}
|
||||
}
|
||||
tls
|
||||
@@ -337,27 +325,30 @@ https://livekit.example.com {
|
||||
reverse_proxy http://127.0.0.1:7880
|
||||
}
|
||||
|
||||
|
||||
# placeholder server block to obtain certs for turn.example.com
|
||||
# placeholder block to obtain certs for turn.example.com
|
||||
https://turn.example.com {
|
||||
respond "OK" 200
|
||||
}
|
||||
```
|
||||
|
||||
**Note**: the setup will disable TURN-over-TLS functionality on port 5349/tcp.
|
||||
|
||||
</details>
|
||||
|
||||
After configuration and spin-up, the destination `turns:turn.example.com:443?transport=tcp` should work with Trickle ICE tests. You can now advertise it as an address in your `turn_uris` as well as LiveKit.
|
||||
After configuration and spin-up, the destination `turns:turn.example.com:443?transport=tcp` should work with Trickle ICE tests. You can now advertise it as an address in your `turn_uris` as well as [LiveKit](./livekit#additional-turns-over-443-configuration).
|
||||
|
||||
[caddy-l4]: https://github.com/mholt/caddy-l4
|
||||
|
||||
### Unsafe TURN setups (not recommended)
|
||||
|
||||
These TURN setups are available, but **not recommended** due to security issues. They are only included for completeness.
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Using static credentials</summary>
|
||||
|
||||
:::caution
|
||||
Static credentials are less secure than shared secrets because they don't expire and must be configured in coturn separately. It is strongly advised you use [shared secret authentication](#2-configuration).
|
||||
:::
|
||||
|
||||
If you prefer static username/password credentials instead of shared secrets:
|
||||
|
||||
```ini
|
||||
@@ -382,8 +373,4 @@ turn_username = "your_username"
|
||||
turn_password = "your_password"
|
||||
```
|
||||
|
||||
:::caution
|
||||
Static credentials are less secure than shared secrets because they don't expire and must be configured in coturn separately. It is strongly advised you use shared secret authentication.
|
||||
:::
|
||||
|
||||
</details>
|
||||
Reference in new issue
Block a user