NetLock RMMNetLock RMM Docs
III — How-To Guides

Remote-control a device with the Relay App

Install the Relay App on the operator's machine, sign in with a relay API key and control a Windows, Linux or macOS device from its Screen Control tab: zoom, full screen, recording, the remote clipboard, pasting files, and anchored devices.

Remote-control a device with the Relay App

The Relay App is a desktop program for the operator's machine. Besides the relay tunnels of Chapter 9.2, it controls the screens of managed devices from its Screen Control tab, without a browser. NetLock RMM does not use VNC or RDP for this: the agent streams the device's screen as JPEG frames over the NetLock server, exactly as for the remote control window of the web console. This guide installs the app, opens a session and walks through the controls of the remote control window.

Before you start

  • A relay API key. Create it on the Relay Server page under Manage API Keys (permission relay_server_manage) and switch Screen control on for that key. The key belongs to your account; every screen session opened with it runs under that account.
  • Permissions of the account that owns the key: devices_remote_control and access to the device's tenant. Pasting files additionally needs devices_remote_file_browser.
  • The device is online. A macOS device needs agent 3.3.0.11 or later; a Linux device needs the packages of X.8.5.
  • The policy of the device allows remote screen control (Policy > Tray Icon > Remote Screen Control); whether the user has to accept the session is decided there as well.

Install the Relay App (operator machine)

The Relay App runs on the operator's machine — the technician who opens the session — not on the target device. Download it from https://netlockrmm.com/downloads, pick your OS and architecture, and unzip it.

The Relay App brings its own runtime, so nothing else has to be installed. On a Mac it needs macOS 12 or newer.

Interface language

The Relay App ships with nine interface languages: English, German, Spanish, French, Italian, Dutch, Polish, Portuguese and Chinese (Simplified). On first start it follows the operating system's display language and falls back to English when that language is not among the nine. Change it in the dropdown on the login screen or in the header of the sessions window, next to the theme buttons; the choice applies immediately, without restarting the app, and is remembered on that machine. Date, time and number formats keep following the operating system's regional settings and are not affected by this setting.

Verify the download

Compute the SHA-512 hash of the zip and compare it to the checksum shown on the download page:

OSCommand
Linuxsha512sum <zip>
macOSshasum -a 512 <zip>
WindowsCertUtil -hashfile <zip> SHA512

Steps

  1. Start the Relay App. On the first start enter the Backend Server URL, the API key and a password that encrypts the stored credentials on this machine, then Save & Connect. Later starts ask for that password only.
  2. Open the tab Screen Control in the sessions window. It lists the devices the key may control; search by name and filter the list as needed.
  3. Select the device and click Connect. The remote control window opens.
  4. Pick the user session. With exactly one active session the window starts it by itself; with several it offers them with the console session preselected; with none it offers Connect anyway.
  5. If the policy requires it, the user on the device accepts the request. The prompt on the device shows your name and, if you released your profile picture for end users, your picture — taken from the account that owns the key.

On a Linux Wayland device, the first connection shows the desktop's screen-sharing dialog on the device. The window says "Waiting for the user to accept screen sharing on the device." until someone at the device accepts it, then "Starting the screen capture on the device." until the picture arrives. Later connections are silent. See X.8.5 when this does not get past one of these states.

Anchored devices

On a device with endpoint protection, screen control needs an approval on a registered phone first (A.13.10). The request goes to the phone of the account that owns the key, and the window shows "Confirm the approval in the NetLock app on your phone." while it waits. When that account has no registered phone, the request goes to the approvers of the device instead and the window shows "Waiting for an approver of this device to confirm the request in the NetLock app." Cancel ends the attempt. After the approval the session starts as usual; a rejection, a request that nobody approved in time, or a device no phone may approve for is named in the window. An active work session of the account covers screen control without a request.

In the remote control window

  • Stream mode. Mode with Quality, Balanced (default), Performance, Auto and Custom, Advanced for frame rate, quality and chroma, Stats for the statistics panel. The choice is kept for the next sessions. See A.7.5.
  • Zoom. Fit fits the picture into the window; + and − step through 25 % to 300 %, and so does Ctrl+wheel (Command+wheel on a Mac). Zoomed in, scroll bars and the middle mouse button move the picture. The zoom wheel never reaches the device.
  • Full screen. F11 or the Full screen button. The toolbar stays visible. Esc goes to the device, so leave full screen with F11 or Exit full screen.
  • Mouse and keyboard. The pointer reaches the device while it moves over the picture, also without a pressed button. Ctrl and Shift go with clicks and the wheel; a horizontal wheel scrolls sideways on the device. See A.7.8.
  • Recording. The red REC chip shows a running recording, REC (forced) one that the setting Force session recording enforces. The recording button starts and stops a recording of your own; a forced recording cannot be stopped. See Recording in the viewers.
  • Clipboard. With the Clipboard checkbox on, Ctrl+V pastes your clipboard's text and Ctrl+C takes the device's. View remote clipboard shows the device's clipboard without changing it. See A.7.6.
  • Paste files. Drop files onto the picture, press Ctrl+V with files copied in your file manager, or use Send files. The window confirms once, shows the progress of every file and reports what the device did with them. Up to 100 files and 10 GB per transfer, no folders; it needs the agent 3.3.0.11 or later on the device and devices_remote_file_browser. See A.7.10 for what Windows, macOS and Linux devices do with the files.
  • Screenshot. Screenshot copies the current picture to the clipboard, Save as… writes it as a PNG file.
  • Session and screen. The user and screen pickers switch between user sessions and monitors; Send Text types a text as keystrokes, Elevate starts an elevated user process on a Windows device.

Verify it worked

  • The remote control window shows the device's desktop, and clicks and keys reach the device.
  • The audit log of the console lists Remote control session started (Relay key: <key name>) under the account that owns the key.

Troubleshooting

  • "Another technician is already connected to this device." Another viewer already holds a screen session on the device. The session still starts; agree with the other technician who works.
  • The session does not start. The window names the reason: device offline, device not found, other tenant, or Remote control is not allowed for this relay key or account when the key's Screen control switch is off or the account lacks devices_remote_control. The server cannot process the request right now means the server could not read the device's data; try again in a moment.
  • "Waiting for the first picture from the session." The device answers but sends no picture. When "The agent on the device may need an update." follows, update the agent.
  • "The remote screen is showing a black picture." The display of the device is off or the selected session draws nothing. Wake the display, or use Switch session to pick the session that owns the screen.
  • No signal. The last picture stays dimmed with the reason. Press Retry, or Switch session. On Linux and macOS devices the reason often names a missing permission or package; see X.8.5 and X.8.6.
  • Connection lost. After a short loss the window reconnects by itself and returns to the same user session and screen. It gives up after about two and a half minutes.