Devices and Device Groups - limuhua-backup/corten-desk GitHub Wiki

Devices and device groups

Every machine running a RustDesk client that points at CortenDesk as its API Server appears here. Devices register themselves β€” you do not add them by hand, though you can pre-register one before it ever connects.

How a device appears

The client sends a heartbeat to CortenDesk roughly every 15 seconds, and a sysinfo payload with its hostname, platform and version. A device CortenDesk has never seen is created on its first heartbeat.

If nothing shows up, the client's API Server is not set or cannot reach the console. See Troubleshooting.

Presence

A device counts as online when its last heartbeat is inside the online window β€” online_window, 60 seconds by default, in Settings β†’ Server. Raise it if you have flaky links and devices flicker between states.

The summary chips above the list are filters β€” click Online or Offline to narrow the list, Devices to clear it. The active one is outlined. A Pending chip appears when the approval gate is holding something. Since 1.8.0; before that the chips were display-only.

The status dropdown in the toolbar does the same thing, and the recycle bin has its own link above the table.

Choosing columns

Since 1.1.0.

The table opens with ID, Device, Alias, Group, Owner, Version, Last Seen and Status. Columns (above the table) adds more: OS, User, IP, LAN IP, CPU, Memory, UUID and First Seen, or removes ones you don't need. ID, Status and the action links are always present. LAN IP comes from the ID server; see Server access control. LAN IP since 1.10.0.

Click a column heading to sort, again to reverse; blanks sort last, and the choice is saved to your account. Since 1.6.0. The Device cell's small print only shows what has no column of its own on screen β€” enable OS and User and it is just the hostname. Since 1.8.0.

The selection is saved to your account, so it survives signing out and follows you between browsers. Defaults puts the original set back. The Owner column is admin-only. On phones the card list keeps its fixed layout regardless.

CPU, memory and the rest arrive from the client's sysinfo report, so a freshly pre-registered device shows them empty until it first connects.

Exporting to CSV

Since 1.1.0.

Export CSV downloads the list as a spreadsheet β€” exactly the current view, so the search box, the status/group/owner filters and your own device visibility all apply. A non-administrator exports only the devices they can see, and every export is recorded in the console audit log.

The first fifteen columns match the device export of lejianwen/rustdesk-api byte for byte:

row_id, id, cpu, hostname, memory, os, username, uuid, version,
last_online_time, last_online_ip, group_id, alias, created_at, updated_at

so tooling built against that format keeps working unchanged. CortenDesk appends group_name, owner, status, note, registered_ip, incoming_only, lan_ip and lan_ip_seen_at after them. A value that a spreadsheet would run as a formula gets an apostrophe in front; see Audit logs.

For scripted, repeated pulls prefer the Automation API β€” device payloads carry the same inventory as JSON.

Bulk actions

Since 1.1.0.

Tick the checkbox on a row β€” or the header checkbox for the whole page β€” and a bulk bar appears with these actions:

  • Add to Address Book… opens a picker listing your personal book plus any shared book you can add entries to (read/write or better under its share rules). Each new entry carries the device's alias, hostname, platform and user; devices already in the chosen book are skipped, and the result tells you how many of each.

  • Move to Group… puts the selection in one device group you can access, or in no group. Since 1.8.1.

  • Incoming only and Allow outgoing stop the selected devices starting sessions, or let them again. See Server access control. Since 1.10.0.

  • Delete moves the selection to the recycle bin after one confirmation for the batch. See Deleting a device.

Selection is deliberately scoped to the page you are looking at: it clears whenever you change filters, search or pages, so a bulk delete can never touch rows that are not in front of you. It composes with the filters β€” filter to a group, select the page, add it to a book.

The device detail page

Since 1.8.0.

Click a device's name or alias (or the eye icon on its row) for the full picture: OS, CPU, memory, client version and user, last IP, LAN IP, whether it may start sessions, the address it registered from, the full UUID, first and last seen, group, owner and strategy. The note is editable in place. Below that: which address books carry the device, and its recent connections (with session notes), file transfers, alarms and notifications, each linking into the full log filtered to this device.

Since 1.10.0 the page has Edit and Delete buttons, which open the same editor and delete dialog as the device list. Under Address books you can add the device to a book or remove it from one, limited to books you can write to. The alias in the device list links here, and read-only roles get the eye icon too.

The activity sections follow the audit permission, like the log screens they excerpt. Registered from is the address the device first appeared from β€” captured once and never rewritten, unlike the IP column, which tracks the current address. Devices that registered before 1.8.0 show it blank.

Editing a device

Open a device to set:

Field Notes
Alias A friendly name. Shown instead of the hostname throughout the console.
Device group The "folder" it belongs to. Drives access β€” see below.
Assigned user The owner. A non-admin sees their own devices.
Strategy A device policy pinned to this device.
Note Free text, up to 500 characters.
Can start sessions Off makes the device incoming only. Since 1.10.0.

The RustDesk ID itself is only editable when pre-registering.

Clicking a device ID opens rustdesk://connection/new/<id>, which hands off to the installed desktop client. The web client is launched from the same row.

The ID travels in the path because the client lowercases the part right after rustdesk://; the old rustdesk://<id> form broke IDs with capitals. A client built with rdgen under another app name registers its own scheme, such as level1-tech-support://; set it in Settings β†’ Server β†’ Client URL scheme. Since 1.14.0.

Device groups

Device groups are folders and the unit of access control. A device belongs to at most one group.

Access is granted two ways:

  • directly to a user, or
  • to a user group, which grants it to every member

An administrator always sees everything. A non-administrator sees their own assigned devices plus any device group granted to them or to a user group they belong to. This scoping applies to the console and to the RustDesk client API, so a user's client only ever receives devices they are entitled to.

Read Users and access scoping before designing your group layout β€” the two features only make sense together.

Pre-registration

Create a device before it exists by entering its RustDesk ID. Set the alias, group, owner and strategy up front. When the real client first heartbeats with that ID it adopts the record instead of creating a new one.

Useful when you image machines and want them landing in the right folder with the right policy from their first connection.

The approval gate

Settings β†’ Server β†’ Require device approval, off by default.

With it on, a device that registers for the first time is created with status pending instead of active. Pending devices are held in a separate tab and do not appear in the normal list until an administrator approves them. Rejecting one removes it.

Turn this on when you do not want an unknown machine appearing in the fleet just because someone pointed a client at your server. Devices already approved are unaffected when you toggle it.

Approve when the device's user signs in (since 1.13.0, under the gate switch, off by default) approves a pending device the moment the RustDesk client on it signs in to this console with a user account, and makes that user the device's owner. The order does not matter: the device can register first and the user sign in later, or the user can sign in before the first heartbeat lands. A device whose client is not signed in still waits in Pending. A disabled account does not approve anything, and an owner already set is kept.

Default group for new devices

Since 1.13.0. Settings β†’ Server β†’ Default group for new devices, none by default. Every device that appears for the first time, pending or not, is placed in that group. Devices in no group are visible only to administrators, so this is how support staff get to see new machines without an administrator filing each one: give their user group access to the default group. Existing devices are not moved, and a --assign that names a group still wins. Deleting the group turns the setting off.

Possible duplicates

Since 1.12.0. RustDesk gives a machine a new ID after a reinstall, a cloned image or a UUID mismatch, which leaves two entries for one machine: the old one goes quiet and the new one reports in. CortenDesk flags pairs that look like this:

  • the same machine UUID on two IDs, or
  • the same hostname, signed-in user and platform. Generic hostnames (localhost, ubuntu, MacBook-Pro and the like) and phones are left out, because unrelated devices share them.

Flagged devices get a badge on the list, and the Possible duplicates chip lists only them, with each pair together. The device page names the other device and offers Open, Delete and Not a duplicate. If both still report in, they are probably two machines cloned from one image: mark them Not a duplicate and the flag goes away for that pair. Devices in the recycle bin or waiting for approval are not checked, and you only see pairs inside the devices you can see.

Deleting a device

Delete on a row, in the bulk bar or on the device page asks once before moving the device to the recycle bin. Since 1.10.0 the dialog also offers Also remove from address books, with the number of entries the device has across all books, ticked when there are any. Only books you can edit are changed, and the result says how many entries were removed and how many were kept in books you cannot edit. Each book changed gets a console audit entry.

Restoring the device does not put its address book entries back.

The Automation API deletes permanently and leaves address books alone unless you pass remove_from_address_books=true.

Recycle bin

Deleting a device is a soft delete. It moves to the recycle bin, where it can be restored or permanently deleted.

A recycled device stays invisible to the console and its heartbeats are deliberately ignored β€” the client keeps running and keeps trying, but presence is not recorded and nothing is created. That is what stops a deleted machine reappearing on its own 15 seconds later. Restore it and presence resumes.

Related