# RustDesk Server (hbbs) — Configuration Guide

This document covers the runtime flags exposed by `hbbs`, the file formats
it reads (notably `oidc.toml`), and the operator workflows that string
those together — bootstrap admin, OIDC sign-in, TOTP, address books,
strategies, recordings, the admin dashboard.

The matching desktop-client API surface is documented separately in the
`rustdesk` repo at `docs/CONSOLE_API.md`.

---

## CLI flags

Pass flags directly on the command line. There is no config file for
hbbs itself (only the optional `oidc.toml` referenced from a flag).

### Networking & rendezvous

| Flag | Default | Purpose |
|---|---|---|
| `--port=<NUM>` | `21116` | TCP/UDP rendezvous port. |
| `--rendezvous-servers=<HOSTS>` | unset | Peer rendezvous servers (comma-separated). |
| `--relay-servers=<HOSTS>` | unset | Default relay hosts handed to clients. |
| `--rmem=<BYTES>` | platform default | UDP recv buffer size. Bump along with `net.core.rmem_max`. |
| `--mask=<CIDR>` | unset | LAN mask (e.g. `192.168.0.0/16`) used to flag local connections. |
| `--key=<B64>` | derived from `id_ed25519` | Force a specific public key; clients must match. Leave unset to auto-load `id_ed25519` next to the binary. |

### HTTP API & dashboard

| Flag | Default | Purpose |
|---|---|---|
| `--http-port=<NUM>` | `21114` | HTTP API port (`/api/*`) and admin dashboard (`/admin/*`). `0` disables both. |
| `--admin-ui-dir=<PATH>` | `./admin_ui` | Hint at where the dashboard's static HTML lives. The HTML is *embedded* in the binary; this flag is informational. Setting it to empty (`--admin-ui-dir=`) disables the dashboard entirely. |
| `--public-base-url=<URL>` | unset | The externally-reachable HTTP base of this server, e.g. `https://rustdesk.example.com:21114`. **Required when OIDC is enabled** — used to build `/oidc/callback` redirect URIs. |

### Bootstrap admin

| Flag | Purpose |
|---|---|
| `--bootstrap-admin-username=<USER>` | On first startup, if the `users` table is empty *and* both flags are set, insert one admin user. Subsequent restarts ignore these flags (no overwrite). |
| `--bootstrap-admin-password=<PASS>` | Same. Bcrypt-hashed at insert time. |

If you forget to bootstrap, hbbs logs a warning at startup ("no users in users table"); recover by either restarting with the flags or `INSERT INTO users` directly via `sqlite3`.

### Address books

| Flag | Default | Purpose |
|---|---|---|
| `--ab-legacy-mode=<on\|off>` | `off` | When `on`, `/api/ab/personal` returns 404. Forces clients into the legacy single-blob AB mode. |
| `--ab-max-peers-per-book=<NUM>` | `100` | Surfaced via `/api/ab/settings.max_peer_one_ab`. Soft cap; the client uses it for UI hints. |

### Recordings

| Flag | Default | Purpose |
|---|---|---|
| `--recording-dir=<PATH>` | `./recordings` | Root for `/api/record` uploads. One subdirectory per peer. |
| `--recording-max-size-mb=<NUM>` | unset (=unlimited) | Per-file ceiling. Aborts oversized parts. |

> **Note:** Stock OSS RustDesk clients **do not upload** recordings to `/api/record` — the uploader's `ENABLE` flag at `src/hbbs_http/record_upload.rs` has no setter in OSS source. Server-side recording requires a custom client build that flips that flag. The `Recordings` admin tab will stay empty for stock clients; the endpoint is provided for wire parity with Pro clients.

### Audit retention

| Flag | Default | Purpose |
|---|---|---|
| `--audit-retention-days=<NUM>` | `0` (=keep forever) | Hourly task deletes `audit_conn` / `audit_file` / `audit_alarm` rows older than N days. |

### Email-code login (`/api/login` with `type:"email_code"`)

| Flag | Default | Purpose |
|---|---|---|
| `--smtp-host=<HOST>` | unset | If unset, codes are *logged to stdout* (dev mode) instead of mailed. The `email_code` login option is also dropped from `/api/login-options` until SMTP is configured. |
| `--smtp-port=<NUM>` | `587` | |
| `--smtp-user=<USER>` | unset | Omit for unauthenticated relays. |
| `--smtp-pass=<PASS>` | unset | |
| `--smtp-from=<ADDR>` | `noreply@<smtp-host>` | From: header. |
| `--smtp-tls=<on\|off>` | `on` | STARTTLS on the SMTP transport. |

### OIDC

| Flag | Purpose |
|---|---|
| `--oidc-config=<PATH>` | TOML file (see below). Providers are upserted into `oidc_providers` at startup. Re-run with a different file to change providers; rows missing from the new file remain in the DB but can be `enabled=0`'d via SQL. |
| `--public-base-url=<URL>` | **Required** if any provider is configured. Determines the redirect URI registered with the IdP. |

---

## OIDC integration

The server speaks standard OIDC Authorization Code flow with discovery
(`/.well-known/openid-configuration`). Tested against Zitadel; should work
with any standards-compliant IdP (Keycloak, Auth0, Google, Okta, Authelia,
Dex, etc.).

Two entry points are wired:

1. **Desktop client** — `/api/login-options` advertises `oidc/<name>` per enabled provider. The Flutter login dialog renders a button per advertised name. Clicking starts the device-flow polling cycle (`/api/oidc/auth` → browser → `/oidc/callback` → `/api/oidc/auth-query` poll).
2. **Admin dashboard** — `/admin/login.html` fetches `/admin/oidc/providers` and renders a "Sign in with X" button per provider. Clicking jumps the browser to `/admin/login/oidc/<name>` which 302-redirects to the IdP. After the IdP returns to `/oidc/callback`, the server detects the admin-flow sentinel and finishes by setting the dashboard session cookie + redirecting to `/admin/`.

### `oidc.toml` schema

Pass via `--oidc-config /path/to/oidc.toml`.

```toml
[[providers]]
# Slug used in URLs (`/admin/login/oidc/<name>`, `/api/login-options`
# advertises `oidc/<name>`). Lowercase, no spaces.
name          = "zitadel"

# Display label on the sign-in button.
display_name  = "Sign in with Zitadel"

# Optional. Square icon URL shown next to the label (not used yet by all
# UIs; reserved for future button rendering).
# icon_url    = "https://example.com/zitadel.svg"

# OIDC issuer. The server fetches `<issuer_url>/.well-known/openid-configuration`
# and caches the discovery doc in-process. Trailing slash is stripped.
issuer_url    = "https://idp.example.com"

# Application credentials from the IdP.
client_id     = "..."
client_secret = "..."

# Scopes requested at the authorization endpoint. Most setups want
# "openid email profile". Zitadel additionally needs the project audience
# scope to receive role claims (see Role-based admin sync below).
scopes        = "openid email profile"

# Optional. If unset, computed as `<--public-base-url>/oidc/callback`.
# Override only when you reverse-proxy under a different host.
# redirect_url = "https://rustdesk.example.com/oidc/callback"

# Optional. Defaults to true.
enabled       = true

# --- Role-based admin sync (optional) ---
# When `admin_role` is set, every successful sign-in via this provider
# evaluates the userinfo claim at `roles_claim` and forces the local
# user's `is_admin` to (role present in claim). Promotion AND demotion
# at the IdP propagate. Leave both unset to manage admin status manually
# from the dashboard.
# admin_role  = "admin"
# roles_claim = "roles"   # or e.g. "urn:zitadel:iam:org:project:roles"
```

`oidc.toml` may contain multiple `[[providers]]` blocks for multi-IdP setups.

### Walk-through: Zitadel

#### In Zitadel

1. **Project → New project** (or pick an existing one).
2. **New application** under the project:
   - Type: **Web**
   - Authentication flow: **Code** (Authorization Code with client secret)
   - Auth method: **Basic** *or* **Post** (server sends `client_id` + `client_secret` in the form body — both modes accept that)
   - **Redirect URIs**: `<public-base-url>/oidc/callback` — character-exact, including scheme. Zitadel rejects `http://` redirects on non-localhost unless dev mode is on, so use TLS in production.
3. **Authorizations** — assign the project's roles to whichever users you want to be admins.
4. **Project → General**: turn on **"Assert Roles On Authentication"** so roles flow into the userinfo response.
5. Copy **Client ID** and **Client Secret** from the application's overview page.

#### `oidc.toml`

```toml
[[providers]]
name          = "zitadel"
display_name  = "Sign in with Zitadel"
issuer_url    = "https://your-instance.zitadel.cloud"
client_id     = "PASTE_FROM_ZITADEL"
client_secret = "PASTE_FROM_ZITADEL"
# `urn:zitadel:iam:org:project:id:zitadel:aud` is required for the project's
# roles to be included in the userinfo response.
scopes        = "openid email profile urn:zitadel:iam:org:project:id:zitadel:aud"
admin_role    = "admin"
roles_claim   = "urn:zitadel:iam:org:project:roles"
```

#### `hbbs` flags

```sh
./hbbs --http-port 21114 \
       --public-base-url 'https://rustdesk.example.com:21114' \
       --oidc-config /etc/rustdesk/oidc.toml
```

#### Verify

After hbbs starts, look for:

```
oidc: provider "zitadel" configured
oidc: loaded 1 providers from /etc/rustdesk/oidc.toml
```

Then:

```sh
# 1. Provider visible to the desktop client
curl -s http://127.0.0.1:21114/api/login-options
#   expect a list including "oidc/zitadel"

# 2. Provider visible to the admin dashboard
curl -s http://127.0.0.1:21114/admin/oidc/providers
#   expect [{"name":"zitadel","display_name":"Sign in with Zitadel",...}]

# 3. Discovery is reachable (IdP-side)
curl -s https://your-instance.zitadel.cloud/.well-known/openid-configuration | jq .issuer
```

### Role-based admin sync

When `admin_role` is set on a provider, every successful sign-in evaluates
the userinfo claim at `roles_claim` (defaults to `"roles"` if unset) and
forces `users.is_admin` accordingly. **Promotion and demotion at the IdP
propagate on the next login.**

Two claim shapes are supported:

- **Object** (Zitadel default at `urn:zitadel:iam:org:project:roles`): role names are keys.
  ```json
  "urn:zitadel:iam:org:project:roles": {
      "admin": {"123": "myorg"},
      "user":  {"123": "myorg"}
  }
  ```
- **Array of strings** (generic, common with Keycloak, Auth0 custom claims):
  ```json
  "roles": ["admin", "user"]
  ```

Set `admin_role = "admin"` and either set `roles_claim` to the exact claim
name (Zitadel) or omit it to default to `"roles"` (generic).

> **Sharp edge:** when role-sync is configured, manually-granted admin
> rights in the dashboard get **revoked** on the next OIDC login if the
> role isn't present at the IdP. This is the correct contract for a
> single source of truth, but surprising if you forget. Manage admin
> status in *one* place at a time.

### Troubleshooting OIDC

- **"Sign-in complete" page in browser but desktop client stays at "Waiting account auth"**: usually a state mismatch between server and client. Check `hbbs.log` — the poll endpoint logs every tick at INFO. If you see `status=success` lines that don't stop, suspect a wire-shape mismatch. (This was a real bug we hit and fixed; see git log for `oidc envelope`.)
- **Browser shows "identity provider returned an error"**: check `oidc_sessions.error` for the row that just failed. Most common: `redirect_uri` mismatch between Zitadel and `--public-base-url`.
- **No "Sign in with X" button in the dashboard or desktop client**: check `oidc_provider_list_enabled()` returns rows. If `--public-base-url` is empty, `/admin/oidc/providers` and `/api/login-options` both suppress OIDC entries (the redirect URI would be unbuildable).
- **Admin landing on the "no admin access" error after first OIDC sign-in**: expected if `admin_role` isn't configured. Either configure role-sync (preferred), or have the user sign in once to create their row, then promote them on the Users page. The next OIDC sign-in resolves to that row.

---

## TOTP / 2FA

Per-user TOTP is enrolled from the dashboard:

1. Sign in as an admin → **Users** page.
2. Pick a user → action menu → **Enroll TOTP**.
3. Scan the QR code into an authenticator (1Password, Authy, Google Authenticator, etc.). The secret is shown once and stored in `user_totp_secrets`.

After enrollment, the next desktop-client login flow is:

1. Username + password → server returns `{"type":"email_check","tfa_type":"tfa_check","secret":<nonce>}`.
2. Client opens its verification-code dialog → user enters the 6-digit code → re-POSTs `/api/login` with `type:"email_code"` (yes, that's what the desktop client sends for both email and TOTP second legs), `tfaCode` set, `secret` echoed back.
3. Server verifies the code against `user_totp_secrets`, mints an access token, returns `{"type":"access_token", ...}`.

For dashboard logins, the inline form at `/admin/login.html` shows the TOTP field after the first password submit returns the prompt fragment.

---

## Strategies (server-pushed config)

Strategies push `config_options` to peers via heartbeat replies. They are
managed entirely from the dashboard's **Strategies** page. Resolution
order per peer:

1. Direct peer-scoped assignment (`strategy_assignments.peer_id`)
2. Device-group assignment via the peer's owner
3. User assignment

The peer's `Config::get_option` calls reflect the resolved values within
~15 s of any change to `modified_at` on the strategy row.

---

## Address books

- **Personal books** are owned per-user and managed from the user's desktop client. The dashboard surfaces them read-only.
- **Shared books** are server-side artifacts. Create from the dashboard's **Address books** page → "Manage shares" → grant per-user `read` / `read+write` / `full` access. Clients pick up shared books on their next AB sync (~30 s).

If you set `--ab-legacy-mode=on`, `/api/ab/personal` 404s and clients fall back to the single-blob `/api/ab` path. Use only if a stock client misbehaves on the modern path.

---

## Admin dashboard URLs

| Path | Auth | What |
|---|---|---|
| `/admin/`, `/admin/index.html` | none (login page redirects in JS) | Single-page shell |
| `/admin/login.html` | none | Sign-in form (password / TOTP / OIDC buttons) |
| `/admin/login` | none (POST form) | Password+TOTP submit → sets `rd_admin_session` cookie |
| `/admin/logout` | cookie | Clears cookie |
| `/admin/me` | cookie | Sidebar's logged-in-as widget |
| `/admin/oidc/providers` | none | JSON list of enabled providers, used by login.html |
| `/admin/login/oidc/:name` | none | Starts admin OIDC flow (302s to IdP) |
| `/admin/pages/users` | cookie + admin | Users page fragment |
| `/admin/pages/devices` | cookie + admin | Devices (incl. delete) |
| `/admin/pages/groups` | cookie + admin | Device groups |
| `/admin/pages/strategies` | cookie + admin | Strategy management |
| `/admin/pages/address-books` | cookie + admin | Personal + shared books |
| `/admin/pages/oidc` | cookie + admin | Read-only OIDC provider listing |
| `/admin/pages/audit` | cookie + admin | Audit log browser |
| `/admin/pages/recordings` | cookie + admin | Recording file listing |
| `/admin/pages/deploy` | cookie + admin | `--config` blob + renamed-installer generator |

The session cookie (`rd_admin_session`) is HttpOnly + SameSite=Strict.
The middleware accepts the same cookie *or* `Authorization: Bearer …`,
so the same auth covers `/api/*` for the desktop client and `/admin/*`
for the dashboard with no separate session model.

---

## Web client

Admins can remote-control any peer directly from the browser — no desktop
RustDesk install required. The Devices page row dropdown surfaces a
**Connect** button that opens `/admin/connect/<peer_id>` in a new tab.
The page is a TypeScript SPA bundled into hbbs (`include_bytes!` from
`web_client/dist/`), so there's no separate process or service to run.

### Routes

| Route | Auth | Purpose |
|---|---|---|
| `/admin/connect/:peer_id` | cookie + admin | Server-rendered HTML wrapper that injects per-request config (rendezvous host, relay host, server pk, peer id, admin display name) into a `<script id="custom-config">` tag, then loads `bundle.js`. |
| `/admin/connect/assets/bundle.js` | cookie + admin | The compiled SPA. ~535 KB, ~75 KB gzipped. |
| `/admin/connect/assets/bundle.css` | cookie + admin | Minimal dark theme + reconnect overlay. |

### How it talks to peers

The browser opens **WebSockets directly** to the existing rendezvous
(`hbbs:21118`, the `ws_port`) and relay (`hbbr:21119`, `port + 2`)
sockets. The wire shape — protobuf `RendezvousMessage` + secretbox-
encrypted `Message` stream — is identical to what the desktop client
uses; the SPA is just a from-scratch reimplementation of the protocol
talking through WS frames instead of TCP.

Browsers can't do UDP NAT-punching, so the SPA always sets `force_relay
= true` in `PunchHoleRequest` and follows the `RelayResponse` branch
unconditionally. **Direct peer-to-peer is never attempted.**

### Browser requirements

- **Secure context** — page must be served over HTTPS or `http://localhost`. WebCodecs `VideoDecoder` / `AudioDecoder` are gated to secure contexts. Plain `http://lan-ip:21114` will fail; either use TLS in front of hbbs or do `ssh -L 21114:localhost:21114 hbbs-host` and connect via `http://localhost:21114`.
- **Browser version** — Chrome 94+, Edge 94+, Firefox 130+, Safari 16.4+. Older browsers lack WebCodecs and will throw "VideoDecoder unavailable" on session start.
- **Clipboard permission** — Firefox refuses `navigator.clipboard.readText()` by default, so admin → host paste is silently no-op there. Host → admin paste works (it uses `writeText`, which only needs a recent click). Chrome/Safari prompt once.

### Network requirements

- The **relay host** advertised to clients (`--relay-servers=<HOSTS>` on hbbs) must resolve and be reachable from the end-user's browser on port 21119. The relay is what carries the actual session bytes — if a user's browser can't open `ws://<relay-host>:21119/`, the session dies after the rendezvous step. A common gotcha: setting `--relay-servers=hbbr-internal.local` works for desktop clients on the LAN but breaks for browsers off-LAN.
- **Reverse proxies** must forward the WebSocket upgrade for both 21118 (rendezvous) and 21119 (relay). Caddy: `reverse_proxy /ws/* hbbs:21118` plus equivalent for 21119; nginx: the standard `proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade";` block.
- Audit rows are written under the admin's cookie via the existing `/api/audit/conn` endpoint; no new server endpoint.

### Features

| Feature | Status |
|---|---|
| Video (VP8 / VP9 / H.264) | ✅ — preference is VP8 (lightest software encoder; H.264 path also implemented for hosts with hwcodec) |
| Audio (Opus) | ✅ |
| Mouse + keyboard input | ✅ — Legacy keyboard mode; Translate mode silently drops Unicode/ControlKey payloads on the host |
| Text clipboard sync (both directions) | ✅ — handles both single-format `Clipboard` and `MultiClipboards` (peers ≥ 1.3.0) |
| Multi-monitor switching | ✅ — `SwitchDisplay` + `CaptureDisplays` two-message dance for hosts ≥ 1.2.4; mouse coords offset by display's virtual-desktop origin |
| Image quality presets (Low/Balanced/Best) | ✅ |
| Custom FPS (15/30/60) | ✅ — host caps at 30 unless `allow_more_fps` is advertised |
| Mute toggle | ✅ — also tells host to stop encoding audio (saves CPU + relay bandwidth) |
| Ctrl+Alt+Del | ✅ — Windows hosts only (server-side `#[cfg(windows)]`) |
| Auto-reconnect on transient drops | ✅ — up to 10 attempts, exponential backoff 1s → 30s, dim overlay during retry, user options re-applied on success |
| File transfer | ❌ deferred — separate `FileAction` family, double the surface area |
| AV1 / H.265 decode | ❌ deferred — VP8/VP9/H.264 covers the common cases |
| IME / compose input | ❌ deferred — needs `compositionend` + `KeyEvent.seq` |
| Touch gestures | ❌ deferred |
| Cursor sprite rendering | ❌ deferred — host-side cursor visible in the video; we don't draw a separate one |

### Codec selection

The SPA advertises VP8/VP9/H.264 decode and prefers VP8. The host's
codec picker (`libs/scrap/src/common/codec.rs`) honours the preference
when the host has the matching encoder available, else falls back to
its "auto" path (H.265 → H.264 → AV1/VP9/VP8).

VP8 is the default because it's the cheapest software encoder; on a
host without hwcodec, VP9 software-encode caps screen sharing at single
digits FPS, while VP8 keeps headroom for the screen-capture pipeline.
On a host *with* hwcodec H.264 (nvenc/qsv on most Windows boxes), flip
the preference in `web_client/src/transport/session.ts` to
`PreferCodec.H264` — the SPA's H.264 path parses SPS to derive the
correct `avc1.PPCCLL` codec string for WebCodecs.

### Performance gotchas

The HUD shows three live numbers: `recv` (frames/sec arriving from the
relay), `dec` (frames/sec the browser decoded), `draw` (frames/sec
painted to canvas). Use them to localise FPS issues:

- All three low → host is encoding slowly. Either CPU-bound (no
  hwcodec, VP9 chosen) or QoS-throttled by host based on `TestDelay`
  RTT measurements.
- `recv` high, `dec` low → browser fell back to software decode. Check
  the codec string at the end of the HUD line; mismatched profile/level
  (e.g. `avc1.42E01E` for a high-profile stream) forces software.
- `dec` high, `draw` low → main thread is overwhelmed (very rare with
  hardware decode).

### Building the bundle

The bundle is committed under `web_client/dist/` so a Cargo build
doesn't need a Node toolchain. To regenerate after editing the SPA:

```sh
cd web_client
npm install        # one-time
npm run build      # → dist/bundle.{js,css}
git add dist/
cd .. && cargo build --release -p hbbs
```

To regenerate protobuf bindings after a `libs/hbb_common/protos/*.proto`
change:

```sh
cd web_client && npm run protogen
```

---

## Database

SQLite, file `db_v2.sqlite3` in hbbs's working directory. Tables created
at startup with `CREATE TABLE IF NOT EXISTS`; column additions use
`ALTER TABLE ADD COLUMN` guarded by a duplicate-column-name swallower
(SQLite < 3.35 lacks `ADD COLUMN IF NOT EXISTS`).

Backup is a plain file copy while hbbs is stopped, or `sqlite3
db_v2.sqlite3 .dump > backup.sql` while running. There is no
multi-instance HA; run a single hbbs against a single SQLite file.

---

## Security checklist before exposing to the internet

- TLS in front of `--http-port` (Caddy / nginx / Traefik). Required for OIDC redirect URIs in production.
- `--public-base-url` set to the *externally* reachable URL, including the scheme.
- `--bootstrap-admin-password` rotated immediately after first login (Users page → reset password).
- `--key` / `id_ed25519` not committed to source control. Treat the private key as a deploy secret.
- Audit retention (`--audit-retention-days`) set to a value that matches your data-retention policy.
- If running behind a reverse proxy: forward the original `Host:` header so OIDC redirect-URI validation matches.