niom-turn/docs/config/runtime.md

Runtime Configuration

Dateien

• appsettings.example.json: Beispiel mit Server-Bind und Test-Credentials.
• appsettings.json: Produktiverstellung (bind, TLS, Credentials).

Struktur

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 (siehe main.rs)

• Bind: 0.0.0.0:3478
• Single Test Credential: testuser / secretpassword

Runbook (Start & Betrieb)

1) Konfiguration anlegen

• Der Server lädt immer appsettings.json aus dem aktuellen Working Directory (siehe Config::load_default()).
• Als Basis kannst du appsettings.example.json nach appsettings.json kopieren und anpassen.

2) Server starten

# im Repo-Root
cargo run --bin niom-turn

Optional kannst du das Log-Level überschreiben:

RUST_LOG=info cargo run --bin niom-turn

Hinweise:

• Wenn server.enable_tls=true, aber server.tls_cert/server.tls_key fehlen, wird der TLS-Listener übersprungen (Info-Log).
• Beim Start loggt der Server, welche Listener aktiv sind und welche Relay-Optionen gelten.

3) Minimal-Konfig: UDP-only (einfachster 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-Konfig: UDP + TCP + TLS (für maximale WebRTC-Kompatibilität)

{
    "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" }
    ]
}

Betriebs-Checkliste (kurz):

• Firewall öffnen: UDP/3478, TCP/3478, TCP/5349 sowie den UDP-Relay-Portbereich (relay_port_min/max).
• Hinter NAT: relay.advertised_ip auf die öffentliche IP setzen.
• Für TURN REST Credentials: auth.rest_secret setzen und ggf. feste credentials leer lassen.

TODOs

• Shared Secret / REST API zur Credential-Verwaltung.
• Health-Port (HTTP) für Monitoring.
• Rate-Limits/Quota (pro Username) und Relay-Port-Range produktiv setzen.

Hinweise für produktiven Betrieb

• Wenn der Server hinter NAT läuft, setze relay.advertised_ip auf die öffentliche IP, damit Clients in XOR-RELAYED-ADDRESS eine erreichbare Adresse erhalten.

• Für Firewalls ist ein fester Relay-Port-Range sinnvoll (relay_port_min/max), damit nur dieser UDP-Bereich geöffnet werden muss.

• Allocations werden auch ohne Traffic periodisch auf Expiry geprüft und bereinigt (Housekeeping), damit Relay-Sockets/Tasks nicht dauerhaft hängen bleiben.