grdctl

grdctl [--headless | --system] command [subcommand] [arguments]

grdctl configures GNOME Remote Desktop, the RDP and VNC server built into GNOME. It writes the same settings as Settings > System > Remote Desktop and, when a backend is enabled or disabled, enables or stops the matching systemd unit.With no mode flag it configures remote assistance: sharing the desktop that is already logged in. Locking that screen closes the remote connection. --headless configures a single-user headless session (`gnome-remote-desktop-headless.service` on the user bus). --system configures the system daemon used for remote login through GDM (`gnome-remote-desktop.service` on the system bus). That mode is RDP only. The system credential unlocks the login screen; each person still signs in with their own account afterwards.RDP listens on port 3389 by default and, unless port negotiation is turned off, tries the next 10 ports when that one is taken. VNC listens on port 5900 and does not negotiate unless asked. Both backends start view-only, so a client can see the screen but cannot move the pointer or type until view-only is disabled.

--headless

Configure the headless user daemon instead of screen sharing.

Configure the system remote-login daemon. grdctl re-executes itself through pkexec as the gnome-remote-desktop user.

Print every command.

status [--show-credentials]

Print the systemd unit state and, for each backend, whether it is enabled, its port, TLS paths, view-only flag, and credentials. Credentials are shown as `(hidden)` or `(empty)` unless --show-credentials is given.

Turn the RDP backend on and enable and start its systemd unit.

Turn the RDP backend off. The unit is stopped only when VNC is off as well.

Absolute path to the RDP TLS certificate.

Absolute path to the RDP TLS private key. RDP will not accept clients until both this and the certificate are set.

Store the RDP username and password. Omit either argument to be prompted. The password prompt does not echo.

Remove the stored RDP username and password.

Comma-separated list of credentials and kerberos. At least one method is required. kerberos works in screen-share and headless modes only.

Absolute path to a keytab whose TERMSRV principal authenticates Kerberos clients.

Port to listen on. The default is 3389.

If the chosen port is busy, try the next 10 ports. This is the default.

Bind only the configured port.

Refuse keyboard and pointer input from RDP clients.

Let RDP clients control the session. View-only is the default.

Turn the VNC backend on and enable and start its systemd unit. Not available with --system.

Turn the VNC backend off. The unit is stopped only when RDP is off as well.

password checks the stored VNC password. prompt asks the person at the machine to approve each connection. prompt is the default.

Store the VNC password. Omit it to be prompted. Passwords longer than 8 characters are rejected.

Remove the stored VNC password.

Port to listen on. The default is 5900.

If the chosen port is busy, try the next 10 ports.

Bind only the configured port. This is the default.

Refuse keyboard and pointer input from VNC clients. This is the default.

Let VNC clients control the session.

Certificate, key, and keytab paths must already be absolute when grdctl sees them. A shell expands ~ before the program runs; a path that still starts with ~ is rejected.A password passed on the command line is visible to other users in the process list. Leave it off and let grdctl prompt.--system stores credentials for the gnome-remote-desktop account, separate from any desktop user. Those credentials only open the remote login screen.The system daemon has no VNC backend. Headless remote login through GDM is RDP only.

grdctl was added to GNOME Remote Desktop in 2022, when the Settings panel stopped exposing every backend option and a shell tool was needed to configure VNC and RDP. Later releases taught it to prompt for credentials, report the TLS fingerprint, and enable the user, headless, and system units itself.

xfreerdp(1), vncviewer(1), remmina(1), systemctl(1)

Source code · Documentation