Remote Desktop

OpsNexus can open a Windows server's desktop in a browser tab. It uses Remote Desktop (RDP) through Apache Guacamole's guacd proxy. As with the SSH terminal, OpsNexus signs in for you: the password stays in the secret store and never reaches the browser.

#How it works

Browser --WebSocket--> OpsNexus API --Guacamole protocol (TCP 4822)--> guacd --RDP--> Windows server:3389

• The browser draws the desktop with the Guacamole JavaScript client.
• The OpsNexus API acts as the tunnel. It does the handshake with guacd itself and fills in the username and password from the secret store.
• guacd opens the RDP connection to your server.
• Sessions use the same single-use 60-second ticket, idle timeout, maximum length, session history and audit log as SSH terminals.

#Requirements

#The guacd service

guacd ships as a service in docker-compose.yml:

guacd:
  image: guacamole/guacd:1.5.5
  restart: unless-stopped

It has no published port. Only the API talks to it. If it isn't running, connecting fails with a message that the remote desktop gateway isn't reachable. Start it with:

docker compose up -d guacd

The API finds guacd with two settings. The defaults match the compose file, so you only change them if you run guacd somewhere else.

GUACD_HOST=guacd
GUACD_PORT=4822

#The Windows server

• Remote Desktop is turned on, and RDP listens on its port (3389 unless you changed it).
• guacd can reach that port. guacd makes the RDP connection, so firewalls and security groups must allow traffic from the machine that runs OpsNexus.
• The account you sign in with is allowed to sign in over Remote Desktop.
• The account signs in with a password. RDP servers can't use an SSH key.

#Add a Windows server

You need modify access to the Cloud module.

1. Open Servers & SSH and click + Add server.

2. Choose Remote Desktop (RDP). The port changes to 3389.

3. Fill in the fields:

   Field	What to enter
   Name	A unique name in this project, for example win-app-1.
   Tags	Optional, comma-separated.
   Host name or IP	Reachable from the OpsNexus server.
   RDP port	Defaults to 3389.
   Username	For example Administrator. DOMAIN\user and user@domain.local also work.
   Domain	Optional, for example CORP. Leave empty for local accounts or when the username already includes the domain.
   Security	See the table below.
   Accept the server certificate without checking it	On by default, because most Windows servers use a self-signed certificate. Turn it off only if the certificate is trusted.

4. Under Sign in with, choose Saved credential (a Username with password credential from Secrets & variables) or Password.

5. Click Add server.

6. Click Test. For RDP servers, the test only checks that the RDP port answers. The sign-in itself is checked when the desktop opens.

#Connect

1. On Servers & SSH, click Connect on the Windows server's row.
2. The desktop opens in a new tab. The header shows the server, the address and the state: Connecting, Connected, Disconnected or Failed.

The desktop starts at the size of the browser window, and follows the window when you resize it. Until the server applies the new size, the picture is scaled to fit.

#Toolbar

If a session is open, the browser asks before you close the tab.

#Full screen

In full screen the toolbar hides. Move the mouse to the top edge of the screen to bring it back.

In Chromium-based browsers, full screen also locks the keyboard: keys such as Esc and the Windows key go to the server instead of your computer. Hold Esc to leave full screen.

#Keyboard

While the desktop tab has focus, everything you type goes to the server. When the tab loses focus, held keys are released so that no key stays stuck on the server.

Toolbar buttons give up focus after a click, so your next key press goes to the server and doesn't "click" the button again.

#Clipboard

• Server to you. Text you copy on the server lands on your local clipboard automatically.
• You to server. Click Paste to server to send your clipboard text to the server's clipboard. Then paste on the server as usual.

The browser must allow clipboard access for the OpsNexus site. If it blocks access, the desktop shows "The browser blocked clipboard access". Allow it in the browser's site settings, or type the text.

Only text is copied. Files and images are not transferred through the clipboard.

#Session limits and audit

Remote Desktop sessions follow the same rules as SSH terminals:

• A session closes after TERMINAL_IDLE_MINUTES (default 30) without keyboard, mouse, touch or clipboard activity.
• A session closes after TERMINAL_MAX_HOURS (default 8) in any case.
• Each person can have up to 10 terminals and desktops open at once.
• People with full access can end anyone's session from the Sessions tab.

Every session appears on the Sessions tab of Servers & SSH, with who, from which IP, when, how long, data in and out, and why it ended. The audit log records terminal.session.start and terminal.session.end in the Remote access category, plus server changes. See Servers & SSH for the full list.

OpsNexus records session metadata only. It doesn't record the screen.

#Limits

• Sign-in is by username and password only.
• There is no file transfer and no drive redirection.
• Clipboard sync is text only.
• The desktop is between 320×240 and 8192×8192 pixels.
• Host key pinning doesn't apply to RDP. Certificate checking is controlled by the Accept the server certificate without checking it switch.

#Troubleshooting

For more, see Troubleshooting.