Set Up RDP Access to Windows

You want to access a Windows PC (office desktop, home office laptop, Windows Server) via Remote Desktop from outside. This guide shows how to set that up cleanly through GateControl — with encrypted credential storage, Wake-on-LAN, maintenance windows and a 1-click launcher in the GateControl desktop client.

RDP is a Pro feature. In the Community plan the wizard is locked.

Two variants — which do you want?

Variant A — Direct peer (VPN client on the target machine)

The target machine has the GateControl client installed, builds its own WireGuard tunnel and gets a VPN IP (10.8.0.x).

Good for: laptops that are integrated into the VPN anyway, home office machines with a permanent VPN profile.

Not good for: office PCs you don't want to touch, LAN devices without installable software, Windows Servers where you aren't supposed to / don't want to install a VPN client.

Variant B — Via home gateway (recommended default case)

The Windows machine has nothing installed. In the same LAN a home gateway container runs (see first-gateway-setup.md), which maintains the tunnel to the server and forwards the RDP port into the LAN.

Good for: everything office and NAS environment. No agent installation on the target machine.

The further steps below apply to both variants — the wizard asks in Step 1 which one you want.

Don't confuse: under RDP settings there is additionally a field for Microsoft RD Gateway (TSGateway). That is a Windows Server role, not a GateControl feature, and only relevant if you sit in an enterprise AD that tunnels RDP through an MS-RDG proxy. For home and small office setups, ignore.

Preparation on the Windows machine

Before you click anything in the wizard:

Enable RDP: Settings → System → Remote Desktop → on. On Home editions of Windows 10/11 RDP is locked; either activate Pro or use a third-party solution.
Leave NLA (Network Level Authentication) active — the wizard default is NLA on.
Firewall: the Windows firewall rule "Remote Desktop" is automatically active as soon as RDP is enabled. If a 3rd-party firewall (GData, ESET etc.) is running: allow TCP 3389.
Test access in the LAN: from another machine in the same LAN mstsc /v:192.168.1.20 — if that already doesn't work, it certainly won't work through GateControl.
Note the LAN IP (for variant B) or note the VPN IP (for variant A, e.g. 10.8.0.23).
Note the MAC address, in case you want to use Wake-on-LAN: getmac /v. Prefer the wired card's MAC — WLAN WoL is finicky.

Create the RDP route

In the admin UI on RDP (sidebar).
+ New RDP route at the top right.
The wizard opens with 6 steps.

Step 1 — Connection

Name: pc-office or laptop-marco. Used as display name in the client.
Description: free text, optional.
Host: for variant A the VPN IP (10.8.0.23), for variant B the LAN IP (192.168.1.20).
RDP port: 3389 (default), or custom if you changed the Windows port.
Access mode:
- VPN only (internal) — variant A, client must be in the VPN to connect.
- Public port forward — variant A, but additionally reachable via public IP:port.
- Both (internal + external) — variant A with both access paths.
- Via home gateway — variant B. Two extra fields appear:
  - Home gateway peer: dropdown with all gateway peers.
  - Public listen port: port on the server through which the client reaches the gateway. Default 3389, but if the server already has 3389 occupied for another machine, set something else (e.g. 3390).
Microsoft RD Gateway (TSGateway) — only fill in if in an enterprise AD there is a TSGateway in front. Otherwise leave empty.

Step 2 — Authentication

This is where the RDP login credentials (Windows user + password) go.

Username: DOMAIN\user or user@domain or just user locally.
Password: is stored E2EE in the client (not in plaintext on the server). How it works:
- Server has a keypair (public key is public).
- Your GateControl client fetches the server public key and encrypts the RDP password with it.
- Server only stores the ciphertext, never can decrypt it.
- On connect your client derives the password from an ECDH shared secret.
Credential-Rotation: optional. If active, GateControl requests a new password entry after X days (e.g. 90 days = corp policy).

Step 3 — Session experience

UI convenience settings that end up in the .rdp file:

Resolution (e.g. 1920x1080, Dynamic).
Colour depth (16/24/32 bit).
Audio mode: local, target, off.
Clipboard sync: on/off.
File sharing (mount local drives in RDP): on/off.
Printer redirect: on/off.
Smartcard redirect: on/off.
USB redirect: on/off.

For most setups: leave the defaults, clipboard on, audio on "local", drives off (otherwise the RDP host mounts your laptop C:\).

Step 4 — Security & behaviour

Session timeout: after X minutes of inactivity the server ends the tracking session.
Bandwidth limit: soft, hint to the client.
Health check: TCP check on 3389. Route only counts as online when the check passes.
Screenshot at session start: optional, audit feature.

Step 5 — WoL & tags

Wake-on-LAN active: tick if you want WoL.
MAC address: from getmac /v, format AA:BB:CC:DD:EE:FF.
Maintenance window: time windows in which the route is blocked (Windows Update reboots, maintenance). The server actively blocks — the client may still attempt connect, server responds with 423 Locked. The client then shows a hint.
Tags: for grouping in the client UI.

Step 6 — Access & summary

Permissions: which admin users may see and use this RDP route.
Peer ACL: which peers (= client devices) may use the route.
Review: final check, then Save.

When saving, the server creates two things:

The RDP route itself (with the credential vault entry).
For access mode "Via home gateway": automatically a companion L4 route (route_type=l4, target_kind=gateway) that opens the listen port on the server and forwards to the gateway.

Client side: establishing the connection

On the admin/user machine you need the GateControl desktop client (Windows, Pro edition). Download and pairing guide see ../USER-GUIDE.md#desktop-client.

As soon as the client is paired with the server:

Client shows the new route under RDP.
Double-click → client does:
- Credential handshake with server (fetches encrypted password, derives shared secret).
- Checks maintenance window (would abort on 423 Locked with hint).
- Checks reachability — if TCP connect fails and WoL is on: Magic Packet → wait 15 sec → retry.
- Generates a temporary .rdp file.
- Starts mstsc (on Windows) or the platform-native RDP client.
RDP session runs, .rdp file is deleted after disconnect.

For Android/iOS clients the flow is analogous; there a third-party RDP client (RD Client, Remmina etc.) is triggered and pre-filled.

Special case: credential rotation after master key change

If the server-side master key is rotated (e.g. after a security incident, scheduled rotation): all stored RDP credentials become invalid. The ciphertext blobs in the DB were encrypted with the old public key and can no longer be derived after rotation.

Symptoms:

Client shows "Credential Error" on connect.
Admin UI dashboard shows the block "Home gateway needs re-pairing" (also applies to RDP creds).

Fix flow for RDP:

RDP → open the affected route → Edit.
The wizard shows at the beginning "Rotation pending — re-enter password". Technically: GET /api/v1/rdp/rotation/pending lists the affected routes.
Re-fill the password field in Step 2.
Save triggers POST /api/v1/rdp/:id/rotation/ack and writes the new ciphertext (under the new master key).
Route works again.

Troubleshooting

"Connection hangs after login, then drops"

Classic MTU/MSS problem. Symptom type: RDP handshake works, NLA passes, then after 2–5 seconds drop. Cause: within the WireGuard tunnel RDP frames don't fit into the MTU, and somewhere TCP MSS clamping is missing.

Check steps:

On the gateway host (variant B): check MTU of the WG interface:
```
ip link show wg0 | grep mtu
```
Should be 1380 or lower (not 1500).

MSS clamping active on the gateway?

iptables -t mangle -L FORWARD -v -n | grep TCPMSS

On the Windows machine, try switching off RDP "WAN optimization" (registry key fDisableUDPTransport=1), to force the UDP fallback transports.

For known connection drops at app connect (signatures like "Connection disconnected — no license server"): WG MTU 1380, clamp TCP MSS to 1280, then test.

"Credential Error" even though password is correct

Master key rotated? See section above — re-enter password.
Username format wrong? DOMAIN\user vs. user@DOMAIN — RDP is picky, try both.
"Login only for administrators" in Windows policy? Only admins may use RDP, unless the Remote Desktop Users group is maintained.

WoL does not trigger

MAC address correct? Format separated with : or -, no spaces. Check again with getmac /v.
Layer 2 connectivity: the gateway host must be in the same subnet as the target PC — Magic Packet is broadcast and does not pass a router.
BIOS: WoL must be enabled in BIOS/UEFI, and in the network driver ("Wake on Magic Packet" on).
Power saving: Windows hard-powers some network cards in S5 (shutdown). Disable Fast Startup (Control Panel → Power options).
ARP cache on the gateway: after reboot the gateway must have the IP of the target machine in its ARP table. If it only knows the MAC but no IP, our Magic Packet logic still works — we broadcast to the LAN broadcast address 255.255.255.255:9.

"Route is down" even though RDP runs internally

Health check disabled in Step 4? Then "down" is the default.
Firewall blocks the health probe from the server host to the VPN IP / from the gateway to the LAN IP.
NLA strict mode — some Windows versions reject the TCP connect without a complete NLA handshake, then the route appears "down" even though it works. Solution: set health check type to "TCP probe only", not "RDP handshake".