docs: document host UDP buffer sysctl tuning

LiveKit's startup warning about UDP receive buffer being too small
(default 212992 bytes vs suggested 5000000) is easy to overlook, but
under load — especially when many clients are forced through the TURN
relay — it causes dtls timeouts on publisher transports and asymmetric
black-tile / no-media symptoms. The fix has to be on the host because
net.core.rmem_max / wmem_max are read when LiveKit opens its UDP sockets
and can't be raised from inside the container.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Linus Gasser
2026-05-29 10:45:27 +02:00
co-authored by Claude Opus 4.7
parent caf772f76c
commit 802a96e849
+33
View File
@@ -103,6 +103,39 @@ This recipe publishes ports directly on the host for WebRTC media transport. The
Your firewall must allow inbound traffic on these ports. Your firewall must allow inbound traffic on these ports.
### Host kernel tuning
LiveKit logs a warning at startup if the kernel's UDP socket buffers are too small:
```
WARN livekit rtcconfig/rtc_unix.go:31 UDP receive buffer is too small for a production set-up {"current": 425984, "suggested": 5000000}
```
The Linux default (`net.core.rmem_max = 212992`) is well under what LiveKit needs once
several participants are forced through the TURN relay path. The resulting packet
loss shows up as `dtls timeout: read/write timeout: context deadline exceeded` on
publisher transports, intermittent media stalls, or one peer seeing a black tile
while the other sees video.
These sysctls are read by LiveKit when it opens its UDP sockets, so they must be
set on the **host** (not in the container) before the LiveKit container starts.
On the host, create `/etc/sysctl.d/99-livekit.conf`:
```
net.core.rmem_max = 7500000
net.core.wmem_max = 7500000
```
Then apply and restart the service:
```
sudo sysctl --system
docker service update --force <stack>_livekit
```
The warning should be gone from the LiveKit boot log.
### TURN server ### TURN server
TURN is enabled by default and helps users behind CGNAT/symmetric NAT connect to video calls. To disable it, remove `compose.turn.yml` from `COMPOSE_FILE` in your app config and set `LIVEKIT_TURN_ENABLED=false`. TURN is enabled by default and helps users behind CGNAT/symmetric NAT connect to video calls. To disable it, remove `compose.turn.yml` from `COMPOSE_FILE` in your app config and set `LIVEKIT_TURN_ENABLED=false`.