1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
# Configuration Reference
This document explains every option available in `turn-server.toml`. All keys are written in [TOML](https://toml.io/en/) syntax.
---
| Key | Type | Default | Values | Description |
|-------------------------------------------|----------------------------------|------------------------|---------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server.realm` | string | `"localhost"` | | Realm announced to TURN/STUN clients. See [RFC 5766 §3](https://datatracker.ietf.org/doc/html/rfc5766#section-3) for the formal definition. |
| `server.port-range` | string (`"start..end"`) | 49152..65535 | Example: `"49152..65535"` | Inclusive range of relay ports the server is allowed to allocate. Keep the range inside the dynamic port interval (49152–65535) unless you fully control the host. |
| `server.max-threads` | integer | number of logical CPUs | | Upper bound for worker threads used by the async runtime. |
| `server.interfaces.transport` | string enum (required) | | `"udp"` or `"tcp"` | The transport protocol exposed on this interface. This table can be declared multiple times; every entry describes one listening endpoint. |
| `server.interfaces.listen` | string (`"IP:PORT"`) | | | Local socket address to bind. Use a specific NIC address when the machine is multi-homed; `0.0.0.0:3478` binds to all IPv4 interfaces. |
| `server.interfaces.external` | string (`"IP:PORT"`) | | | Publicly reachable address advertised to clients. Set this to the NAT/public IP when the bound address is not directly reachable. |
| `server.interfaces.idle-timeout` | integer (seconds) | 20 | | Maximum idle period before a transport connection is dropped. |
| `server.interfaces.mtu` | integer (bytes) | 1500 | | Desired MTU for TURN relayed packets. |
| `server.interfaces.ssl.private-key` | path to PEM file | | | Private key file for TLS on this interface. |
| `server.interfaces.ssl.certificate-chain` | path to PEM file | | | Certificate chain file for TLS on this interface. |
| `api.listen` | string (`"IP:PORT"`) | `"127.0.0.1:3000"` | | Bind address for the management gRPC server. |
| `api.timeout` | integer (seconds) | 5 | | Global timeout applied to API handlers. |
| `api.ssl.private-key` | path to PEM file | | | Private key file for TLS on the API endpoint. |
| `api.ssl.certificate-chain` | path to PEM file | | | Certificate chain file for TLS on the API endpoint. |
| `prometheus.listen` | string (`"IP:PORT"`) | `"127.0.0.1:9090"` | | Bind address for the Prometheus metrics exporter endpoint. Only enabled when the `prometheus` feature is compiled. |
| `prometheus.ssl.private-key` | path to PEM file | | | Private key file for TLS on the Prometheus endpoint. |
| `prometheus.ssl.certificate-chain` | path to PEM file | | | Certificate chain file for TLS on the Prometheus endpoint. |
| `hooks.endpoint` | string (URL) | | | Base URL of the external hook service used for dynamic auth and event callbacks.
| `hooks.timeout` | integer (seconds) | 5 | | Global timeout applied to API handlers. |
| `hooks.max-channel-size` | integer | 1024 | | Upper bound for buffered hook events. |
| `hooks.ssl.private-key` | path to PEM file | | | Private key file for TLS when communicating with the hook service. |
| `hooks.ssl.certificate-chain` | path to PEM file | | | Certificate chain file for TLS when communicating with the hook service. |
| `log.level` | string enum | `"info"` | `error,warn,info,debug` | Controls verbosity of the built-in logger. |
| `log.stdout` | boolean | `true` | | Enable or disable logging to standard output (stdout). If set to `true`, log messages will be printed to the console in addition to (or instead of) file logging. To disable logging to the console, set this option to `false`. |
| `log.file-directory` | string (optional) | | | If specified, log output will be written to this directory in a file named `turn-server-YYYY-MM-DD.log`. If not set, file logging is disabled. |
| `auth.enable-hooks-auth` | boolean | `false` | | Enable or disable hook-based dynamic authentication. |
| `auth.static-auth-secret` | string (optional) | | | Shared secret for TURN REST authentication. When provided, the server skips secret lookups through the hook API. |
| `auth.static-credentials` | table of `username = "password"` | | | Static user database used before falling back to hook authentication. Populate this map with long-term accounts that should always exist. |
Provide the `server.interfaces.ssl.*` fields to enable TLS for the interface. Certificates are loaded via `tokio-rustls` (AWS-LC backend when the `ssl` feature is enabled).
Optional TLS configuration applies to `api.ssl.*`, `prometheus.ssl.*`, and `hooks.ssl.*` entries.
### Security note
the management gRPC endpoint ships without authentication or TLS. Enable the SSL settings above or terminate TLS behind a proxy before exposing it to untrusted networks.
All settings are hot-reloaded on restart. Keep secrets (private keys, shared tokens) protected with standard filesystem permissions.