Configuration Reference
This document explains every option available in turn-server.toml. All keys are written in TOML syntax.
| Key | Type | Default | Values | Description |
|---|---|---|---|---|
server.realm | string | "localhost" | Realm announced to TURN/STUN clients. See RFC 5766 §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 (Deprecated) | 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. TCP transport only — has no effect on UDP interfaces. | ||
server.interfaces.ssl.certificate-chain | path to PEM file | Certificate chain file for TLS on this interface. TCP transport only — has no effect on UDP interfaces. | ||
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. |
NOTE
Provide the server.interfaces.ssl.* fields to turn the interface into TLS. This is only supported on TCP interfaces; the UDP transport does not accept an ssl option. 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.