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

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

Optional kannst du das Log-Level überschreiben:

```bash
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)

```json
{
    "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)

```json
{
    "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.