SDE Devices: settings reference
This article provides a comprehensive reference for settings related to SDE Devices, including configurations for the sde-redirector unit, gateway settings, and admin page options. It is aimed at engineers involved in deploying and managing SDE systems.
Every setting for SDE Devices: the sde-redirector unit's environment, the gateway's settings, the admin page's devices, profiles and rules, the agent installers and the sde-devlink command.
1. Unit environment
File: /var/glitch-units/sde-redirector/glitch/config/enviroment. After a change, recreate the unit: gl -d sde-redirector && gl -s sde-redirector. The admin page's Settings tab shows the values in use.
| Setting | What it does | Default | Notes |
|---|---|---|---|
SDE_REDIRECTOR_SHARED_SECRET | Secret the gateway's broker presents on its /v1 calls, and scripts on the admin API (header X-SDE-Devices-Secret). | None: the unit won't start without it | 16 characters or more. Same value as the gateway's SDE_DEVICES_SECRET. openssl rand -hex 32. |
SDE_REDIRECTOR_AGENT_KEY | Key every desktop agent presents. | Not set: no agent can connect, so no device can be connected | 16 characters or more. The same value goes into each agent's installer. |
SDE_REDIRECTOR_GUAC_URL | Guacamole, for admin sign-in. Only Guacamole administrators may sign in. | Not set: sign-in is off (the API still takes the shared secret) | Same as the gateway's SDE_GUAC_URL. |
SDE_REDIRECTOR_PUBLIC_URL | The redirector's public address, shown on the admin page and used in the agent install commands. | From the request | https://<portal>/sde-redirector |
SDE_REDIRECTOR_ADMIN_NETWORKS | Addresses the admin page may be used from. | Private ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7) | Comma-separated. Addresses in SDE_GUEST_NETWORKS are always refused. |
SDE_REDIRECTOR_V1_NETWORKS | Addresses that may call /v1 (the broker). | Not set: any address with the shared secret | For example the gateway's docker network, 172.16.0.0/12. /v1 is never proxied by nginx. |
SDE_REDIRECTOR_AGENT_NETWORKS | Addresses desktop agents may connect from. | Private ranges, as for admin networks | Where your session hosts live, for example 10.20.0.0/16. When set, SDE_GUEST_NETWORKS is added to it, so desktops on SDE Networks are still accepted. |
SDE_REDIRECTOR_TRUSTED_PROXIES | Proxies whose X-Forwarded-For header is believed for an agent's address. | 127.0.0.1/32, ::1/128, 172.16.0.0/12 | nginx on the host or the docker bridge. Agents are known by their address, so don't widen this. |
SDE_GUEST_NETWORKS | SDE Network guests: never "internal" to the admin page or /v1. | Not set | The SDE Network address block. sde-install sets it. |
SDE_REDIRECTOR_LISTEN | Address and port the unit listens on. | :8098 | Set in the image. |
SDE_REDIRECTOR_DATA | Data folder inside the container: catalogue, profiles, rules and history (state.json). | /opt/sde-redirector/data | Mapped to data/state, owned by uid 1001, mode 700. |
SDE_REDIRECTOR_DIST | Folder served at /sde-redirector/dist/: the agent installers and sde-devlink downloads. | /opt/sde-redirector/dist | Set in the image. |
2. Gateway settings
In the sde-gateway unit's environment. Recreate the gateway after a change (gl -d sde-gateway && gl -s sde-gateway).
| Setting | What it does | Default | Notes |
|---|---|---|---|
SDE_DEVICES_URL | Where the broker calls the redirector. | Not set: devices are off | http://<gateway-host>:8098. Needs SDE_DEVICES_SECRET too. |
SDE_DEVICES_SECRET | Secret for those calls. | Not set: devices are off | Same as SDE_REDIRECTOR_SHARED_SECRET. sde-install check compares them. |
SDE_DEVICES_PUBLIC_URL | The redirector's public address, given to laptops for the device link. | Not set | https://<portal>/sde-redirector |
3. Devices
Devices → Add device, or the pencil icon. The catalogue of kinds of device, by USB vendor and product ID.
| Setting | What it does | Default | Notes |
|---|---|---|---|
| Name | As admins and users see it. | Required | For example Arduino Uno. |
| ID | Short name used by profiles. | Made from the name | Lower-case letters, digits and dashes. Fixed once added. |
| Vendor ID | USB vendor ID. | Required | 4 hex digits, for example 2341. |
| Product ID | USB product ID. | * | 4 hex digits, or * for any of the vendor's products. |
| Notes | For admins. | Empty |
A device can't be deleted while a profile uses it. The catalogue starts with:
| Device | Vendor:Product |
|---|---|
| Arduino (genuine boards) | 2341:* |
| Arduino (arduino.org boards) | 2a03:* |
| CH340 USB serial (Arduino clones, many 3D printers) | 1a86:7523 |
| FTDI USB serial | 0403:6001 |
| Silicon Labs CP210x USB serial (ESP32 boards, printers) | 10c4:ea60 |
| Raspberry Pi Pico / RP2040 / RP2350 | 2e8a:* |
| BBC micro:bit | 0d28:0204 |
| Espressif ESP32-S2/S3/C3 (native USB) | 303a:* |
| Prusa 3D printers | 2c99:* |
4. Profiles
Profiles → Add profile. Groups of devices that rules allow together.
| Setting | What it does | Default | Notes |
|---|---|---|---|
| Name | As shown in rules. | Required | For example Microcontrollers. |
| ID | Short name used by rules. | Made from the name | Lower-case letters, digits and dashes. |
| Devices | The catalogue entries in the profile. | None | |
| Allow devices that include a storage drive | Lets a device with a mass-storage function through. | Off | Needed to flash a Pico or micro:bit by copying a file. A drive is also the easiest way for files to leave a secure session. |
Built-in profiles: Microcontrollers (Arduino, Arduino.org, CH340, FTDI, CP210x, Raspberry Pi Pico, micro:bit, Espressif) and 3D printers (Prusa, CH340, FTDI, CP210x). Neither allows drives. A profile can't be deleted while a rule uses it.
5. Rules
Rules → Add rule. Who may connect which profiles to which desktops. Nothing is allowed until a rule allows it. A device is allowed when any rule that's on matches the user, the desktop and the device.
| Setting | What it does | Default | Notes |
|---|---|---|---|
| Name | As shown in the list and the test result. | Required | For example Engineering students: microcontrollers. |
| ID | Short name. | Made from the name | Lower-case letters, digits and dashes. |
| On | Whether the rule applies. | On | A rule that's off shows Off in the list. |
| Profiles | Devices the rule allows. | None | At least one. |
| Groups | Guacamole user groups (synced from AD), one per line. | None | At least one group or user. Not case-sensitive. |
| Users | Usernames, one per line. | None | Not case-sensitive. |
| Desktops | Desktops the rule covers, one per line: host names, addresses, ranges (10.20.0.0/16) or patterns (vdi-*). | Empty: any desktop with the agent | A pattern matches the full name or the part before the first dot. |
6. Rules test
Rules → Test… answers "would this be allowed?" without a device. It shows Allowed with the rule, or Refused with the reason, and warns if that desktop has no agent connected.
| Field | Enter |
|---|---|
| User | A username, for example student1 |
| Their groups | Comma-separated groups |
| Desktop | A host name or address |
| Device (vendor:product) | For example 2341:0043 |
7. Never connected
These are refused whatever the rules say. The redirector checks the device it sees in the stream; a Linux desktop's agent also never switches on a keyboard, mouse or hub function.
| USB class | Why |
|---|---|
Keyboards, mice and other input devices (HID, class 03) | A small board can pretend to be a keyboard and type commands. |
USB hubs (class 09) | Connect the device itself. |
Wireless and Bluetooth adapters (class e0) | |
Storage (class 08) | Only when the profile ticks Allow devices that include a storage drive. |
8. Agent installers
Served by the redirector at https://<portal>/sde-redirector/dist/. The Agents tab shows the commands for your portal.
Linux: install-agent.sh
curl -fsSL https://<portal>/sde-redirector/dist/install-agent.sh | sudo SDE_DEVLINK_KEY=<agent key> sh| Setting | What it does | Default | Notes |
|---|---|---|---|
SDE_DEVLINK_KEY | The agent key. | Required | SDE_REDIRECTOR_AGENT_KEY |
SDE_DEVLINK_SERVER | The redirector's public address. | Where the script was downloaded from | https://<portal>/sde-redirector |
SDE_DEVLINK_INSECURE | 1 accepts a self-signed portal certificate. | 0 | Test sites only. |
It loads vhci-hcd now and at boot, installs /usr/local/bin/sde-devlink, writes the three settings to /etc/sde/devlink.conf (root only) and runs the sde-devlink-agent service, which restarts after 5 seconds if it stops.
Windows: install-agent.ps1
curl.exe -fsSLo $env:TEMP\i.ps1 https://<portal>/sde-redirector/dist/install-agent.ps1; powershell -ExecutionPolicy Bypass -File $env:TEMP\i.ps1 -Server https://<portal>/sde-redirector -Key <agent key>| Setting | What it does | Default | Notes |
|---|---|---|---|
-Server | The redirector's public address. | Required | |
-Key | The agent key. | Required | Saved in C:\ProgramData\SDE\devlink.key, readable by Administrators and SYSTEM only. |
-Insecure | Accepts a self-signed portal certificate. | Off | Test sites only. Use curl.exe -k for the download too. |
It needs usbip-win2 installed first, puts sde-devlink.exe in C:\Program Files\SDE, and creates the sde-devlink-agent service (SDE device agent, automatic, restarts on failure). The log is C:\ProgramData\SDE\devlink.log.
9. sde-devlink commands
One program for both ends: the agent on desktops, and sharing a device from a Linux laptop. Downloads: sde-devlink-linux-amd64, sde-devlink-linux-arm64, sde-devlink-windows-amd64.exe.
| Command | What it does | Options |
|---|---|---|
share | Laptop: signs in as you, lists your desktops and devices with the verdict for each, and connects one through the broker until Ctrl+C. Run with sudo. | -portal URL (required, for example https://sde.example.ac.uk), -user U (default: your login name), -desktop NAME (the connection name or part of it), -busid B, -lease ID (pool desktops: the lease ID SDE Remote shows), -insecure |
list | Lists the USB devices plugged in here, with bus IDs. | -json |
release | Linux: gives back devices a crashed share left held. Also done automatically on the next run. | |
agent | Desktop: the service that attaches devices the redirector sends. The installers set it up. | -server URL (required), -key K or -keyfile F, -name N (default: the host name), -log F, -insecure |
export | Laptop: shares one device with a ticket from the broker. Used by share. | -server URL -ticket T -busid B, -insecure |
connect | Testing: asks the redirector directly, as the broker would, then shares. Needs the shared secret. | -server URL -api URL -secret S -user U -host H -busid B, -groups G,G, -insecure |
version | Prints the version. |
| Setting | What it does | Default | Notes |
|---|---|---|---|
SDE_DEVLINK_KEY | Agent key, instead of -key. | Not set | |
SDE_PASSWORD | Password for share, instead of the prompt. | Not set: share asks | For scripted tests. |
SDE_DEVLINK_USERSPACE | 1: share from Linux through SDE's own USB/IP server (usbfs) instead of the kernel's usbip-host. | Used automatically when usbip-host isn't available | |
SDE_DEVLINK_USBIP | Windows agent: path to usbip.exe. | C:\Program Files\USBip\usbip.exe, then C:\Program Files\usbip-win2\usbip.exe | |
SDE_REDIRECTOR_SHARED_SECRET | Secret for connect, instead of -secret. | Not set | Testing only. |
list, export and share, through the UsbDk driver. This is being proven and isn't yet supported for users; the Devices panel in the SDE Remote app comes next.10. Limits and fixed values
| Item | Value |
|---|---|
| Tickets | Single-use; both sides must connect within 90 seconds |
| History kept | 2,000 connections (the page shows the latest 300; Export CSV for the rest) |
| Activity shown | The most recent 500 events (full log: docker logs sde-redirector) |
| Admin sign-in lasts | 8 hours |
| Agent reconnects | After 1 second, backing off to 30 seconds |
11. Admin page tabs
| Tab | What's there |
|---|---|
| Overview | Connected now (with Disconnect), desktops with the agent, connections and refusals in the last 24 hours, recent connections. Warns when there's no agent key, no rule or no agent. |
| Devices | The catalogue. |
| Profiles | Groups of devices, and which rules use them. |
| Rules | Who may connect what, where; Test…. |
| History | Every connection: user, device and serial number, desktop, state and reason, start, traffic. Filter, Export CSV. |
| Agents | Desktops with the agent connected (name, address, system, version, for how long) and the install commands. |
| Activity | Events, with a filter. |
| Settings | The values from the unit's environment (read-only). |
person people found this useful.
