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

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

Optionally override the log level:

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

```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 config: UDP + TCP + TLS (best WebRTC compatibility)

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

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.