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. | |
rpc.listen | string ("IP:PORT") | "127.0.0.1:3000" | Bind address for the management HTTP server. It serves gRPC and, when built with the prometheus feature, GET /metrics. | |
rpc.timeout | integer (seconds) | 5 | Global timeout applied to API handlers. | |
rpc.ssl.private-key | path to PEM file | Private key file for TLS on the API endpoint. | ||
rpc.ssl.certificate-chain | path to PEM file | Certificate chain file for TLS on the API 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. | ||
log.vector.endpoint | string ("IP:PORT") | Optional Vector TCP endpoint. Logs are sent as newline-delimited JSON (message, level, target, file). Use a Vector socket source with mode = "tcp" and decoding.codec = "json". The server connects at startup. | ||
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
Optional TLS configuration applies to rpc.ssl.* (gRPC and /metrics) and hooks.ssl.* entries. Certificates are loaded via rustls with the AWS-LC backend.
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.