DEV Community

Cover image for How to Install XRDP on Debian 12 & 13: Remote Desktop That Works
FlatlinerAtheist | CLI-NERDS
FlatlinerAtheist | CLI-NERDS

Posted on Originally published at clinerds.com

How to Install XRDP on Debian 12 & 13: Remote Desktop That Works

#networking #debian #remote #xrdp

Need a graphical desktop on a headless Debian server? XRDP is the open-source answer: it speaks Microsoft's RDP protocol, so you can connect to your Debian machine from the built-in Remote Desktop client on Windows, Remmina on Linux, or any RDP app on macOS — no extra software on the server beyond one package.

This guide installs XRDP on Debian 12 (Bookworm) and Debian 13 (Trixie) with a lightweight desktop, fixes the two errors everyone hits (black screen and polkit password prompts), and shows you how to reach the machine safely without exposing RDP to the internet.

What you need

  • A Debian 12 or 13 machine with sudo access
  • About 1 GB of free disk space for the desktop environment
  • A user account to log in with — do not plan to use root over RDP

Step 1 — Install a desktop environment

Most Debian servers have no graphical environment at all, and XRDP needs one to present. GNOME is heavy for a server; Xfce is the classic lightweight choice and the most reliable with XRDP:

sudo apt update
sudo apt install -y xfce4 xfce4-goodies dbus-x11
Enter fullscreen mode Exit fullscreen mode

The dbus-x11 package prevents a class of session errors later, so do not skip it.

Step 2 — Install XRDP 

sudo apt install -y xrdp
sudo systemctl enable --now xrdp
Enter fullscreen mode Exit fullscreen mode

XRDP runs as its own user and needs to read the TLS certificate used for RDP encryption. Add it to the ssl-cert group, or the service starts but every connection fails:

sudo adduser xrdp ssl-cert
sudo systemctl restart xrdp
Enter fullscreen mode Exit fullscreen mode

Verify it is listening:

sudo ss -tlnp | grep 3389
Enter fullscreen mode Exit fullscreen mode

Step 3 — Point XRDP at Xfce

Without this, clients connect and immediately get a blank or black screen. Create a session file for your user:

echo "startxfce4" > ~/.xsession
Enter fullscreen mode Exit fullscreen mode

Then edit /etc/xrdp/startwm.sh and make sure the last lines launch the session cleanly. Comment out the generic test -x /etc/X11/Xsession && exec /etc/X11/Xsession / exec /bin/sh /etc/X11/Xsession lines and add above them:

unset DBUS_SESSION_BUS_ADDRESS
unset XDG_RUNTIME_DIR
. ~/.profile
Enter fullscreen mode Exit fullscreen mode

Restart after editing: sudo systemctl restart xrdp.

Step 4 — Silence the polkit password popups

Right after login, Xfce may spam "Authentication is required to create a color managed device" dialogs. Create /etc/polkit-1/rules.d/45-allow-colord.rules:

polkit.addRule(function(action, subject) {
  if ((action.id == "org.freedesktop.color-manager.create-device" ||
       action.id == "org.freedesktop.color-manager.create-profile" ||
       action.id == "org.freedesktop.color-manager.delete-device" ||
       action.id == "org.freedesktop.color-manager.delete-profile" ||
       action.id == "org.freedesktop.color-manager.modify-device" ||
       action.id == "org.freedesktop.color-manager.modify-profile") &&
      subject.isInGroup("users")) {
    return polkit.Result.YES;
  }
});
Enter fullscreen mode Exit fullscreen mode

JavaScript polkit rules work the same on Debian 12 and 13; just make sure the file is world-readable: sudo chmod 644 /etc/polkit-1/rules.d/45-allow-colord.rules.

Step 5 — Connect from your machine

  • Windows: press Win + R, type mstsc, enter the server's IP or hostname, log in with your Debian username and password.
  • Linux: use Remmina (sudo apt install remmina) — protocol RDP, same credentials.
  • macOS: the free "Windows App" (formerly Microsoft Remote Desktop) from the App Store.

You should land in a full Xfce desktop. Clipboard sharing, drive redirection, and audio forwarding are all supported if you enable them in your client.

Do not expose port 3389 to the internet

RDP is one of the most-scanned, most-attacked protocols on the public internet. Keep 3389 closed in your firewall and cloud security group, and reach the desktop through an SSH tunnel instead:

ssh -L 3389:localhost:3389 user@your-server
Enter fullscreen mode Exit fullscreen mode

Then point your RDP client at localhost:3389. The session is encrypted by SSH and the port never faces the internet. Our SSH port forwarding and tunneling guide walks through local, remote, and dynamic tunnels in detail.

If the machine must serve RDP on a LAN, at least restrict it:

sudo ufw allow from 192.168.1.0/24 to any port 3389 proto tcp
Enter fullscreen mode Exit fullscreen mode

Troubleshooting the three classic failures

Black screen after login. Almost always a missing or wrong ~/.xsession, or the unset DBUS_SESSION_BUS_ADDRESS lines missing from startwm.sh. Check ~/.xsession-errors and /var/log/xrdp-sesman.log.

Connection refused or immediate drop. Confirm sudo adduser xrdp ssl-cert was run and check sudo systemctl status xrdp. On Debian 13 also verify the certificate files in /etc/xrdp/ are readable by the xrdp user.

Login works, password correct, but session loops back to the login screen. Your user already has a graphical session running on the console. Log out there, or use a different account for RDP — XRDP cannot attach to an already-running local session.

Wrapping up

You now have remote graphical access to a Debian server using nothing but the tools your laptop already ships with. Keep port 3389 off the internet, tunnel in over SSH, and the setup is both convenient and safe. If you are hardening the rest of the machine, our guides on the first 30 minutes on a new Linux server and locking down SSH are the natural next reads.

Top comments (0)