From 5ec9776207446db4665e76e5b42c5382eb55607c Mon Sep 17 00:00:00 2001 From: Mike Mueller Date: Mon, 18 May 2026 18:23:21 +0200 Subject: [PATCH] Documentation of available strategy keys (Rustdesk Client) --- docs/STRATEGIES.md | 308 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 308 insertions(+) create mode 100644 docs/STRATEGIES.md diff --git a/docs/STRATEGIES.md b/docs/STRATEGIES.md new file mode 100644 index 0000000..c976464 --- /dev/null +++ b/docs/STRATEGIES.md @@ -0,0 +1,308 @@ +# Strategies — server-pushed client config + +Strategies let an admin push client configuration to peers centrally, +without touching each device. They are managed from the dashboard's +**Strategies** page (`/admin/#strategies`). + +--- + +## How it works + +1. **Storage.** A strategy is a row with a name and a `config_options` + JSON object (plus an `extra` object, reserved — currently always + `{}`). The Strategies page validates only that `config_options` is a + valid JSON **object**; it does **not** validate the keys inside it. +2. **Delivery.** On each peer heartbeat the server resolves the + applicable strategy and embeds it in the reply as + `strategy.config_options`. Changes propagate within ~15 s of the + strategy row's `modified_at` changing. +3. **Apply.** The client merges every key/value straight into its own + options map (the same store behind "advanced settings" and the + `--config` deploy blob). A strategy key is therefore *any* key the + RustDesk client reads via `Config::get_option`. + +### Resolution order (per peer) + +The first match wins: + +1. Direct peer-scoped assignment (`strategy_assignments.peer_id`) +2. Device-group assignment, via the peer's owner +3. User assignment + +If nothing matches, an empty config is pushed. + +### Value conventions + +- **All values are strings**, even numbers (`"30"`, not `30`). +- **Boolean keys** use `"Y"` (on) / `"N"` (off). Most default to off + when unset. +- **An empty string `""`** removes the override and lets the client + fall back to its built-in default. (If a built-in default settings + blob is present, an empty value instead keeps the key present.) +- Keys the client version doesn't recognize are stored, pushed, and + silently ignored — there is **no error feedback for typos**. Verify + against the `keys` module in `libs/hbb_common/src/config.rs` of the + client version you deploy. + +### Example + +```json +{ + "enable-keyboard": "N", + "enable-file-transfer": "N", + "access-mode": "view", + "image_quality": "best", + "whitelist": "192.168.1.0/24,10.0.0.0/8", + "verification-method": "use-permanent-password" +} +``` + +--- + +## Known config keys + +The keys below are the complete set defined in the client's `keys` +module (`libs/hbb_common/src/config.rs`). Not all are equally useful in +a server-managed strategy — UI-state keys (peer tabs, toolbar, floating +window) are listed for completeness but are normally per-user. + +### Access control & permissions + +| Key | Values | Effect | +|---|---|---| +| `access-mode` | `full` / `view` / `custom` | Overall permission preset for incoming sessions | +| `enable-keyboard` | `Y`/`N` | Allow remote keyboard input | +| `enable-clipboard` | `Y`/`N` | Allow clipboard sync | +| `enable-file-transfer` | `Y`/`N` | Allow file transfer | +| `enable-camera` | `Y`/`N` | Allow camera access | +| `enable-terminal` | `Y`/`N` | Allow terminal access | +| `terminal-persistent` | `Y`/`N` | Keep terminal sessions persistent | +| `enable-audio` | `Y`/`N` | Allow audio | +| `enable-tunnel` | `Y`/`N` | Allow TCP tunnelling | +| `enable-remote-restart` | `Y`/`N` | Allow remote restart of the host | +| `enable-record-session` | `Y`/`N` | Allow session recording | +| `enable-block-input` | `Y`/`N` | Allow blocking local input | +| `enable-privacy-mode` | `Y`/`N` | Allow privacy mode | +| `enable-perm-change-in-accept-window` | `Y`/`N` | Allow changing permissions in the accept dialog | +| `allow-remote-config-modification` | `Y`/`N` | Allow remote side to change this host's config | +| `allow-numeric-one-time-password` | `Y`/`N` | Permit numeric one-time passwords | +| `approve-mode` | `password` / `click` / `password-click` | How incoming connections are approved | +| `verification-method` | `use-temporary-password` / `use-permanent-password` / `use-both-passwords` | Password verification mode | +| `temporary-password-length` | `6` / `8` / `10` | Length of generated one-time passwords | +| `allow-only-conn-window-open` | `Y`/`N` | Only accept connections while the connection window is open | +| `allow-auto-disconnect` | `Y`/`N` | Auto-disconnect idle sessions | +| `auto-disconnect-timeout` | minutes | Idle timeout for auto-disconnect | +| `approve-mode` | see above | (alias note: stored as `approve-mode`) | +| `enable-trusted-devices` | `Y`/`N` | Enable the trusted-devices feature | +| `allow-logon-screen-password` | `Y`/`N` | Allow password entry on the logon screen | +| `disable-change-permanent-password` | `Y`/`N` | Prevent the user changing the permanent password | +| `disable-change-id` | `Y`/`N` | Prevent the user changing the device ID | +| `disable-unlock-pin` | `Y`/`N` | Disable the unlock PIN feature | + +### Network & connectivity + +| Key | Values | Effect | +|---|---|---| +| `custom-rendezvous-server` | host | ID/rendezvous server address | +| `relay-server` | host | Relay server address | +| `api-server` | URL | API server address | +| `key` | string | Server public key | +| `ice-servers` | string | ICE servers for WebRTC | +| `direct-server` | `Y`/`N` | Enable direct IP access listener | +| `direct-access-port` | port | Port for direct IP access | +| `enable-udp-punch` | `Y`/`N` | Enable UDP hole punching | +| `enable-ipv6-punch` | `Y`/`N` | Enable IPv6 hole punching | +| `disable-udp` | `Y`/`N` | Disable UDP (force TCP) | +| `allow-websocket` | `Y`/`N` | Allow WebSocket transport | +| `allow-insecure-tls-fallback` | `Y`/`N` | Allow falling back to insecure TLS | +| `enable-lan-discovery` | `Y`/`N` | Allow discovery on the local network | +| `whitelist` | IPs/CIDRs | Comma/space/`;`-separated allow-list; empty = allow all | +| `allow-https-21114` | `Y`/`N` | Use HTTPS on port 21114 | +| `use-raw-tcp-for-api` | `Y`/`N` | Use raw TCP for the API connection | +| `allow-hostname-as-id` | `Y`/`N` | Allow using the hostname as device ID | +| `proxy-url` | URL | Proxy server URL | +| `proxy-username` | string | Proxy username | +| `proxy-password` | string | Proxy password | + +### Display, codec & quality + +| Key | Values | Effect | +|---|---|---| +| `view_style` | `original` / `adaptive` | Remote display scaling | +| `scroll_style` | `scrollauto` / `scrollbar` | Scroll behaviour | +| `image_quality` | `best` / `balanced` / `low` / `custom` | Image quality preset | +| `custom_image_quality` | `10`–`4095` | Custom quality value | +| `custom-fps` | `5`–`120` | Custom frame rate | +| `codec-preference` | `auto` / `vp8` / `vp9` / `av1` / `h264` / `h265` | Preferred video codec | +| `enable-hwcodec` | `Y`/`N` | Enable hardware codec | +| `enable-abr` | `Y`/`N` | Enable adaptive bitrate | +| `i444` | `Y`/`N` | Use YUV 4:4:4 (true colour) | +| `av1-test` | `Y`/`N` | Enable AV1 test path | +| `zoom-cursor` | `Y`/`N` | Zoom the remote cursor | +| `show_remote_cursor` | `Y`/`N` | Show the remote cursor | +| `follow_remote_cursor` | `Y`/`N` | Follow the remote cursor | +| `follow_remote_window` | `Y`/`N` | Follow the remote active window | +| `show_quality_monitor` | `Y`/`N` | Show the quality monitor overlay | +| `show_monitors_toolbar` | `Y`/`N` | Show the monitors toolbar | +| `collapse_toolbar` | `Y`/`N` | Start with the toolbar collapsed | +| `view_only` | `Y`/`N` | Open sessions view-only by default | +| `touch-mode` | `Y`/`N` | Enable touch mode | +| `displays_as_individual_windows` | `Y`/`N` | Show each remote display in its own window | +| `use_all_my_displays_for_the_remote_session` | `Y`/`N` | Use all local displays for the session | +| `use-texture-render` | `Y`/`N` | Use texture rendering | +| `allow-d3d-render` | `Y`/`N` | Allow Direct3D rendering | +| `enable-directx-capture` | `Y`/`N` | Use DirectX for screen capture | +| `allow-always-software-render` | `Y`/`N` | Force software rendering | +| `allow-linux-headless` | `Y`/`N` | Allow headless mode on Linux | + +### Input + +| Key | Values | Effect | +|---|---|---| +| `reverse_mouse_wheel` | `Y`/`N` | Reverse mouse-wheel direction | +| `swap-left-right-mouse` | `Y`/`N` | Swap mouse buttons | +| `trackpad-speed` | `10`–`1000` | Trackpad speed (percent) | +| `edge-scroll-edge-thickness` | `20`–`150` | Edge-scroll trigger thickness | + +### Recording, files & clipboard + +| Key | Values | Effect | +|---|---|---| +| `allow-auto-record-incoming` | `Y`/`N` | Auto-record incoming sessions | +| `allow-auto-record-outgoing` | `Y`/`N` | Auto-record outgoing sessions | +| `video-save-directory` | path | Directory for recordings | +| `enable-file-copy-paste` | `Y`/`N` | Allow file copy/paste | +| `file-transfer-max-files` | number | Max files per transfer request | +| `one-way-file-transfer` | `Y`/`N` | Restrict file transfer to one direction | +| `sync-init-clipboard` | `Y`/`N` | Sync clipboard at session start | +| `disable_clipboard` | `Y`/`N` | Disable clipboard | +| `disable_audio` | `Y`/`N` | Disable audio | +| `one-way-clipboard-redirection` | `Y`/`N` | One-way clipboard redirection | +| `lock_after_session_end` | `Y`/`N` | Lock the host after a session ends | +| `privacy_mode` | `Y`/`N` | Enable privacy mode for the session | + +### Printer + +| Key | Values | Effect | +|---|---|---| +| `enable-remote-printer` | `Y`/`N` | Enable remote printing | +| `printer-incomming-job-action` | string | Action for incoming print jobs (note: key is spelled `incomming`) | +| `allow-printer-auto-print` | `Y`/`N` | Allow automatic printing | +| `printer-selected-name` | string | Selected printer name | + +### Update behaviour + +| Key | Values | Effect | +|---|---|---| +| `enable-check-update` | `Y`/`N` | Check for updates | +| `allow-auto-update` | `Y`/`N` | Allow automatic updates | + +### Power & session + +| Key | Values | Effect | +|---|---|---| +| `keep-screen-on` | string | Keep the screen on | +| `keep-awake-during-incoming-sessions` | `Y`/`N` | Keep host awake during incoming sessions | +| `keep-awake-during-outgoing-sessions` | `Y`/`N` | Keep client awake during outgoing sessions | +| `allow-ask-for-note` | `Y`/`N` | Prompt for a session note | +| `pre-elevate-service` | `Y`/`N` | Pre-elevate the service | +| `register-device` | `Y`/`N` | Register the device with the API server | + +### UI visibility / branding lockdown + +| Key | Values | Effect | +|---|---|---| +| `hide-security-settings` | `Y`/`N` | Hide the Security settings tab | +| `hide-network-settings` | `Y`/`N` | Hide the Network settings tab | +| `hide-server-settings` | `Y`/`N` | Hide the Server settings tab | +| `hide-proxy-settings` | `Y`/`N` | Hide the Proxy settings tab | +| `hide-remote-printer-settings` | `Y`/`N` | Hide remote-printer settings | +| `hide-websocket-settings` | `Y`/`N` | Hide WebSocket settings | +| `hide-stop-service` | `Y`/`N` | Hide the "stop service" control | +| `hide-tray` | `Y`/`N` | Hide the system-tray icon | +| `hide-powered-by-me` | `Y`/`N` | Hide "powered by" branding | +| `hide-username-on-card` | `Y`/`N` | Hide username on peer cards | +| `hide-help-cards` | `Y`/`N` | Hide help cards | +| `hideAbTagsPanel` | `Y`/`N` | Hide the address-book tags panel | +| `main-window-always-on-top` | `Y`/`N` | Keep the main window on top | +| `theme` | `light` / `dark` / `system` | UI theme | +| `lang` | language code | UI language | +| `remote-menubar-drag-left` | `Y`/`N` | Allow dragging the left remote menubar | +| `remote-menubar-drag-right` | `Y`/`N` | Allow dragging the right remote menubar | +| `enable-confirm-closing-tabs` | `Y`/`N` | Confirm before closing tabs | +| `enable-open-new-connections-in-tabs` | `Y`/`N` | Open new connections in tabs | +| `disable-group-panel` | `Y`/`N` | Hide the group panel | +| `disable-discovery-panel` | `Y`/`N` | Hide the discovery panel | + +### Address book + +| Key | Values | Effect | +|---|---|---| +| `sync-ab-with-recent-sessions` | `Y`/`N` | Sync address book with recent sessions | +| `sync-ab-tags` | `Y`/`N` | Sync address-book tags | +| `filter-ab-by-intersection` | `Y`/`N` | Filter address book by tag intersection | + +### Deep links + +| Key | Values | Effect | +|---|---|---| +| `allow-deep-link-password` | `Y`/`N` | Allow passwords in deep links | +| `allow-deep-link-server-settings` | `Y`/`N` | Allow server settings in deep links | + +### Preset values (deploy/provisioning) + +These pre-fill fields during enrollment/deploy rather than gating behaviour. + +| Key | Effect | +|---|---| +| `display-name` | Device display name | +| `avatar` | Device avatar | +| `default-connect-password` | Default connection password | +| `remove-preset-password-warning` | Suppress the preset-password warning | +| `preset-user-name` | Pre-fill username | +| `preset-strategy-name` | Pre-fill strategy name | +| `preset-device-group-name` | Pre-fill device group | +| `preset-device-username` | Pre-fill device username | +| `preset-device-name` | Pre-fill device name | +| `preset-note` | Pre-fill session note | +| `preset-address-book-name` | Pre-fill address-book name | +| `preset-address-book-tag` | Pre-fill address-book tag | +| `preset-address-book-alias` | Pre-fill address-book alias | +| `preset-address-book-password` | Pre-fill address-book password | +| `preset-address-book-note` | Pre-fill address-book note | + +### Android / mobile + +| Key | Values | Effect | +|---|---|---| +| `show-virtual-mouse` | `Y`/`N` | Show the virtual mouse | +| `show-virtual-joystick` | `Y`/`N` | Show the virtual joystick (also set `show-virtual-mouse`) | +| `disable-floating-window` | `Y`/`N` | Disable the floating window | +| `floating-window-size` | string | Floating-window size | +| `floating-window-untouchable` | `Y`/`N` | Make the floating window non-interactive | +| `floating-window-transparency` | number | Floating-window transparency | +| `floating-window-svg` | string | Floating-window SVG icon | +| `enable-android-software-encoding-half-scale` | `Y`/`N` | Half-scale Android software encoding | + +### UI state (normally per-user — listed for completeness) + +`remoteMenubarState`, `peer-sorting`, `peer-tab-index`, `peer-tab-order`, +`peer-tab-visible`, `peer-card-ui-type`, `current-ab-name`, +`enable-flutter-http-on-rust`, `allow-remote-cm-modification`. + +--- + +## Notes & caveats + +- The list above reflects the client `keys` module at documentation + time. Newer clients may add keys; older clients will ignore keys they + don't know. There is no negotiation — match the doc to the client + version you actually deploy. +- Some keys also exist as hbbs/hbbr command-line flags + (`custom-rendezvous-server`, `relay-server`, `key`, …). Pushing them + via a strategy overrides the client's local value; it does not change + the server. +- The `extra` object on a strategy row is reserved and currently always + `{}` — there is no UI to populate it. +- For the overall configuration picture see + [CONFIGURATION.md](CONFIGURATION.md#strategies-server-pushed-config).