niom-turn/docs/config/runtime.md

Runtime Configuration

Files

• appsettings.example.json: example config with server binds and test credentials.
• appsettings.json: production config (binds, TLS, credentials).

Schema

Config {
    server: ServerOptions {
        bind: String,
        udp_bind: Option<String>,
        tcp_bind: Option<String>,
        tls_bind: String,
        enable_udp: bool,
        enable_tcp: bool,
        enable_tls: bool,
        tls_cert: Option<String>,
        tls_key: Option<String>,
    },
    relay: RelayOptions {
        relay_port_min: Option<u16>,
        relay_port_max: Option<u16>,
        relay_bind_ip: Option<String>,
        advertised_ip: Option<String>,
    },
    logging: LoggingOptions {
        default_directive: Option<String>,
    },
    limits: LimitsOptions {
        max_allocations_per_ip: Option<u32>,
        max_permissions_per_allocation: Option<u32>,
        max_channel_bindings_per_allocation: Option<u32>,

        unauth_rps: Option<u32>,
        unauth_burst: Option<u32>,
        binding_rps: Option<u32>,
        binding_burst: Option<u32>,
    },
    credentials: Vec<CredentialEntry> {
        username: String,
        password: String,
    }
}

Default fallbacks (see main.rs)

• bind: 0.0.0.0:3478
• single test credential: testuser / secretpassword

Runbook (start & operations)

1) Create the configuration

• The server currently always loads appsettings.json from the current working directory (see Config::load_default()).
• As a starting point, copy appsettings.example.json to appsettings.json and adjust it.

2) Start the server

# from the repo root
cargo run --bin niom-turn

Optionally override the log level:

RUST_LOG=info cargo run --bin niom-turn

Notes:

• If server.enable_tls=true but server.tls_cert/server.tls_key are missing, the TLS listener is skipped (info log).
• On startup, the server logs which listeners are enabled and which relay options are in effect.

3) Minimal config: UDP-only (simplest start)

{
    "server": {
        "bind": "0.0.0.0:3478",
        "enable_udp": true,
        "enable_tcp": false,
        "enable_tls": false,
        "tls_cert": null,
        "tls_key": null
    },
    "relay": {
        "relay_bind_ip": "0.0.0.0",
        "advertised_ip": null,
        "relay_port_min": null,
        "relay_port_max": null
    },
    "logging": {
        "default_directive": "warn,niom_turn=info"
    },
    "limits": {
        "max_allocations_per_ip": null,
        "max_permissions_per_allocation": null,
        "max_channel_bindings_per_allocation": null,

        "unauth_rps": null,
        "unauth_burst": null,
        "binding_rps": null,
        "binding_burst": null
    },
    "credentials": [
        { "username": "testuser", "password": "secretpassword" }
    ],
    "auth": {
        "realm": "niom-turn.local",
        "nonce_secret": null,
        "nonce_ttl_seconds": 300,
        "rest_secret": null,
        "rest_max_ttl_seconds": 600
    }
}

4) Minimal config: UDP + TCP + TLS (best WebRTC compatibility)

{
    "server": {
        "bind": "0.0.0.0:3478",
        "tls_bind": "0.0.0.0:5349",
        "enable_udp": true,
        "enable_tcp": true,
        "enable_tls": true,
        "tls_cert": "/etc/niom-turn/tls/fullchain.pem",
        "tls_key": "/etc/niom-turn/tls/privkey.pem"
    },
    "relay": {
        "relay_bind_ip": "0.0.0.0",
        "advertised_ip": "203.0.113.10",
        "relay_port_min": 49152,
        "relay_port_max": 49252
    },
    "logging": {
        "default_directive": "warn,niom_turn=info"
    },
    "limits": {
        "max_allocations_per_ip": 50,
        "max_permissions_per_allocation": 200,
        "max_channel_bindings_per_allocation": 50,

        "unauth_rps": 5,
        "unauth_burst": 20,
        "binding_rps": 50,
        "binding_burst": 200
    },
    "credentials": [
        { "username": "testuser", "password": "secretpassword" }
    ]
}

Operations checklist (short):

• open firewall: UDP/3478, TCP/3478, TCP/5349 and the UDP relay port range (relay_port_min/max).
• behind NAT: set relay.advertised_ip to the public IP.
• for TURN REST credentials: set auth.rest_secret and optionally leave static credentials empty.

TODOs

• Shared secret / REST API for credential management.
• Health endpoint (HTTP) for monitoring.
• Rate limits/quotas (per username) and production relay port range settings.

Production notes

• If the server runs behind NAT, set relay.advertised_ip to the public IP so clients receive a reachable address in XOR-RELAYED-ADDRESS.

• A fixed relay port range (relay_port_min/max) is recommended so you only need to open that UDP range.

• Allocations are periodically checked for expiry and pruned (housekeeping) even without traffic, so relay sockets/tasks do not linger indefinitely.