Remote desktop

Take control of a graphical workstation in the fleet to help its user, without installing anything permanently and without entering a password.

just rd clemence            # observation only (default)
just rd clemence rw         # take control
just rd clemence login      # your own session, via GDM

ro and rw attach to the session already open on the host: if no one is logged in, the command stops with an error. login does the opposite and opens your own session behind a GDM login screen, whether or not someone is at the machine. See Open your own session (login).

Enabling a host

Remote desktop is an explicit opt-in. It is enabled via the feature remote-desktop in etc/config.yaml :

  - hostname: "clemence"
    profile: "umi"
    features: ["remote-desktop", "nfs-client"]

Then just generate and just apply clemence. A host without this feature cannot be troubleshooted, and the configuration explicitly lists which ones can.

Templated host groups

A feature is inherited by all hosts in a range: or hosts: group, which covers an entire family of identical machines in a single line:

  - hostname: "fd-%'02s"
    profile: "desktop"
    range: [1, 2]
    features: ["monitoring-node", "nfs-client", "remote-desktop"]

This is why features was chosen over services: the services: block of a templated group is not propagated to the generated hosts.

This is not trivial

Connecting to a session means seeing (and controlling in rw) the screen of someone who is most likely sitting right in front of it. GNOME displays a sharing indicator for the entire duration, but nothing asks for the user’s consent. Reserve activation for machines where this is the intended use.

The three modes

Mode	Effect	Applied by
ro (default)	You see the user’s screen, your inputs are ignored	The remote server
rw	Same screen, keyboard and mouse forwarded	The remote server
login	A GDM login screen, then a session of your own

The ro/rw filtering is done on the host side, not by the client: a modified client cannot turn ro into rw.

ro and rw never open a session

With no one connected, they have no screen to reflect and fail outright. Asking to observe a user must not silently drop you elsewhere without telling you: it is login, and only login, that opens a new session.

Window shortcuts

The client is sdl-freerdp. Its shortcuts use Right Shift as the modifier, unlike the old X11 client which used Ctrl+Alt :

Shortcut	Effect
Right Shift + Enter	Full screen (and back)
Right Shift + G	Keyboard/mouse capture. When captured, Alt+Tab and other shortcuts are sent to the remote machine; when released, they return to yours
Right Shift + R	Allow / block window resizing
Right Shift + M	Minimize the window
Right Shift + D	Disconnect cleanly

Getting back to your machine

In full screen with keyboard capture active, Right Shift is always intercepted locally: Right Shift + Enter brings you back, no matter what. Closing the window disarms the session on the host.

Resolution and sharpness

The window opens at the native resolution of the remote screen: one remote pixel per local pixel, so no resampling and no blurring.

Any other size goes through scaling, which softens the image; this is the price of free resizing. To restore 1:1:

• Right Shift + Enter: full screen is exact if your monitor has the same resolution as the remote one;
• otherwise, bring the window back to its original size.

If the remote screen is larger than yours, the window overflows and your window manager constrains it: the image is then downscaled and therefore softened. Full screen remains the best compromise in this case.

Opening your own session (login)

just rd <host> login arms the system daemon of gnome-remote-desktop and presents you with the GDM login screen. You authenticate with your usual account, and GDM opens a session for you. This is the mode to use when no one is logged in on the machine, but it also works just as well when someone is, without changing anything displayed on the monitor.

The system daemon is already installed and inert on every GNOME host, exactly like the user daemon: nothing new is added, it is armed then disarmed. It is also the only one that can work without an unlocked keyring, which a machine with no one logged in obviously cannot provide.

This is not the machine’s screen

GDM opens a new, screenless session alongside whatever is displayed on the monitor. You are therefore not seeing the physical screen: you are on your own machine, not on someone else’s. To troubleshoot a user, you need ro or rw.

Reflecting the GDM greeter itself is not possible: the user daemon only accepts credentials from a keyring, and the greeter session does not have one.

Worth knowing: that session uses a virtual monitor that the server can resize. So it is your client that imposes the resolution, and the display is 100 % sharp without any adjustment.

What actually happens

1. The command connects to the host via SSH as the nix identity, like all fleet administration commands.
2. It arms the session on the host: RDP server configuration, ephemeral TLS certificate, random one-time credentials.
3. It sets up an SSH tunnel to the RDP port, which remained closed to the network.
4. It launches the FreeRDP client under your own account, on 127.0.0.1.
5. On window close, everything is disarmed and the host’s original configuration is restored.

Nothing is ever exposed on the network: the fleet firewall remains deny-by-default, no rule is added, not even temporarily. The RDP server only listens for the duration of the session, and the only way to reach it is through the tunnel.

The certificate is self-signed and regenerated on every session, in the machine’s volatile memory. Its fingerprint is captured over SSH and pinned in the client: the machine’s identity is therefore guaranteed by the SSH channel itself, binding it more tightly than a certified domain name ever could.

On the login screen, the fingerprint is not pinned: the system daemon hands off to the login session, which presents its own certificate. Pinning the first one would break the second step. It is then the tunnel, and the tunnel alone, that carries the trust.

Automatic shutdown

The host disarms itself after 60 minutes (adjustable with darkone.graphic.remote-desktop.timeout). This safeguard covers the case where your machine shuts down, the network goes down, or the command is killed brutally: access cannot stay open by accident.

The three engines

The requested mode and the type of the open session determine the engine.

Situation	Engine	What you see
ro/rw, open GNOME Wayland session	gnome-remote-desktop, user daemon	The user’s screen
ro/rw, open Cinnamon X11 session (UMI workstations)	freerdp-shadow-cli on the existing display	The user’s screen
login	gnome-remote-desktop, system daemon	GDM, then your own session

In all three cases: same RDP protocol, same client, same tunnel, same port.

Known limitations

• One session at a time per host. A second attempt is refused until the first one is closed.
• Multiple graphical sessions open on the same host: in ro/rw, the command refuses to guess and lists what it found. login is not affected, it does not look at existing sessions.
• Screen sharing already active on the target session: the command does not touch it and stops. This is intentional: a manually applied configuration must not be overwritten then “restored” incorrectly.
• No sound, no shared clipboard, no file transfer.
• Manual window resizing does not preserve proportions. The opening size, however, is correct.
• gnome-remote-desktop is rebuilt on the affected hosts (see next section). The build is cached, but a just update that bumps GNOME may cause the patch to fail, noisily.

The user’s pointer

As shipped, gnome-remote-desktop transmits the shape of the cursor but never its position when reflecting a physical screen: the client therefore draws the remote cursor at the location of your mouse. In rw this is not visible since you are driving it, but in ro you cannot see at all where the user is pointing, which defeats the purpose of observing.

DNF fixes this by patching the server to ask mutter to embed the pointer in the image (embedded cursor mode, already used upstream for virtual monitors). A single line of code, and cursor metadata stops being emitted, so no spurious second cursor.

The trade-off is a local rebuild of gnome-remote-desktop on each host that can be troubleshooted. To opt out:

darkone.graphic.remote-desktop.embedCursor = false;

Troubleshooting

Symptom	Likely cause
nobody is logged in	No one is logged in: ro/rw have nothing to reflect, use login
could not arm a … session	The remote-desktop feature is not declared on this host, or the host has not been redeployed
Failed to enable service: … EROFS	Host not redeployed since the login mode was added: just apply <host>
screen sharing is already enabled	GNOME sharing was manually enabled on this session
several active graphical sessions	Multiple accounts have an active session on the same workstation
a support session is already open	A session is still actually armed on the host: close it first
no DISPLAY among the processes of session …	X11 session whose X server has disappeared (session closing): try again
the shadow server did not get port …	The RDP port is already occupied on the host by something else
The window opens then immediately closes	Verify that the host is reachable and that the tunnel could be established

To inspect host-side state:

just enter clemence
sudo dnf-remote-desktop probe    # which session would be chosen
sudo dnf-remote-desktop stop     # manually disarm