Configure xrdp on Linux: 6 Proven Black Screen Fixes
xrdp lets you connect to a Linux desktop with any RDP client, including the Remote Desktop app built into Windows. Installing it takes one package. When you configure xrdp, getting a working desktop after you log in is where most people get stuck, and the usual fixes found online (a .xsession file, SELinux commands) often target the wrong problem. I set up xrdp 0.10.1 with xorgxrdp and a minimal XFCE desktop on Debian 13, logged in with FreeRDP 3.15 to see what really happens on success and on failure, and checked the SELinux side on Fedora 45 with xrdp 0.10.6.

Contents
Install xrdp and a desktop
xrdp needs two parts: the xrdp server and a backend that runs the X session. On Debian and Ubuntu that backend is the xorgxrdp package. You also need a desktop environment, because xrdp starts a new graphical session for each user rather than sharing the screen of someone already logged in. The lab used:
apt-get install -y -qq xrdp xorgxrdp xfce4-session xfwm4 xfce4-panel dbus-x11 freerdp3-x11 xvfb procps iproute2
On a normal installation you would install a full desktop environment and let systemd start the services; in the container I started xrdp-sesman and xrdp by hand. On Fedora the package is simply xrdp (0.10.6.1 on Fedora 45). The versions in the lab:
freerdp3-x11 3.15.0+dfsg-2.1+deb13u3
xorgxrdp 1:0.10.2-1
xrdp 0.10.1-3.1+deb13u2
Configure xrdp: what xrdp.ini sets by default
To configure xrdp you edit /etc/xrdp/xrdp.ini. The values that matter for security were:
port=3389
security_layer=negotiate
crypt_level=high
xrdp listens on 3389, the standard RDP port, and negotiates the transport security with the client. The xrdp.ini manual describes the other options. Notice what is not there: an IP restriction. xrdp listened on all addresses (*:3389 in ss -ltnp), so the firewall decides who can reach it.
Create the user with adduser, not useradd
Before you configure xrdp sessions, create the user properly. The earlier version of this post created the RDP user with sudo useradd rdpuser. On Debian that creates an account with no home folder, and everything after that fails:
$ ls -ld /home/rdpuser /home/anna 2>&1
ls: cannot access '/home/rdpuser': No such file or directory
drwx------. 1 anna anna 84 Nov 18 14:23 /home/anna
$ su - rdpuser -c 'echo xfce4-session > ~/.xsession' 2>&1
su: warning: cannot change directory to /home/rdpuser: No such file or directory
-sh: 1: cannot create /home/rdpuser/.xsession: Directory nonexistent
The RDP login for rdpuser was accepted ("Received sys login status for rdpuser : logged in"), but the session never got further than sh, xauth and xrdp-sesexec: no X server, no desktop, and the client sat on a blank connection until my 20-second timeout. If an xrdp user gets a black or empty screen right after a successful login, check that the home folder exists first. adduser anna (or useradd -m) creates it.
Choose the desktop with ~/.xsession
The usual way to configure xrdp for a specific desktop is the .xsession trick from the old post, and it is correct, for a user who has a home folder:
$ su - anna -c 'echo xfce4-session > ~/.xsession && cat ~/.xsession'
xfce4-session
Then I connected with FreeRDP from the same container and checked the processes 15 seconds later:
anna Xorg
anna xfce4-session
anna xfwm4
An Xorg server, the XFCE session and its window manager all ran as anna. The session manager log shows the steps:
[2026-11-18T14:23:41.608+0000] [INFO ] Received sys login status for anna : logged in
[2026-11-18T14:23:41.609+0000] [INFO ] Received request from xrdp to create a session for user anna
[2026-11-18T14:23:41.618+0000] [INFO ] Starting X server on display 10: /usr/lib/xorg/Xorg :10 -auth .Xauthority -config xrdp/xorg.conf -noreset -nolisten tcp -logfile .xorgxrdp.%s.log
[2026-11-18T14:23:42.632+0000] [INFO ] Session in progress on display :10. Waiting until the window manager (pid 10285) exits to end the session
Use the session command of your desktop: xfce4-session for XFCE, and the matching command for MATE, KDE or others.
Reading failed logins in the xrdp logs
When you configure xrdp, plan where failed logins will show up. With a wrong password, the client did not get an error. It stayed on xrdp's login screen until the timeout (exit code 124). The reason was only in the server logs:
[2026-11-18T14:38:46.166+0000] [INFO ] xrdp_wm_log_msg: User does not exist, or could not be authenticated
[2026-11-18T14:38:46.165+0000] [INFO ] AUTHFAIL: user=anna ip=::ffff:127.0.0.1 time=1795012726
The AUTHFAIL line in /var/log/xrdp-sesman.log includes the client address, which makes it the line to feed into fail2ban or your log monitoring. Also note that FreeRDP's /auth-only option does not help here: with xrdp it ended with "Authentication only, exit status 1" for the right and the wrong password alike, because xrdp checks the password on its own login screen after the connection is set up.
A careful way to configure xrdp is to restrict who may log in at all. The session manager log said "TerminalServerUsers group tsusers doesn't exist. Access granted for rdpuser". The sesman.ini manual explains: only members of the TerminalServerUsers group may log in, but "If unset or set to an invalid or non-existent group, login for all users is enabled." Create the group (tsusers by default) and add only the RDP users, or set AlwaysGroupCheck to require membership. The same manual lists AllowRootLogin and MaxLoginRetry (3 by default).
Firewall and SELinux
After you configure xrdp, open 3389/tcp only to the addresses that need it. The old post's commands are fine for that (firewall-cmd --permanent --add-port=3389/tcp or ufw allow 3389/tcp), but limit the source if you can. Better still, keep 3389 closed and reach it through an SSH tunnel; see how to SSH tunnel in Linux.
On Fedora, many guides that configure xrdp include an SELinux step; the old post suggested chcon --type=bin_t on the xrdp binaries. On Fedora 45 those files already have that label by default:
/usr/sbin/xrdp system_u:object_r:bin_t:s0
/usr/sbin/xrdp-sesman system_u:object_r:bin_t:s0
So that command changes nothing. Many people also search for an rdp_port_t type. In the Fedora 45 policy (selinux-policy-targeted 45.24) there is none; port 3389 belongs to GNOME's own remote desktop:
gnome_remote_desktop_port_t tcp 3389-3399
The xrdp package installed no SELinux module of its own. If you run both GNOME Remote Desktop and xrdp, only one of them can listen on 3389, so move one to another port. For SELinux denials in general, use the audit log as shown in master SELinux commands instead of relabelling files by hand.
Configure xrdp: troubleshooting checklist
- Install
xrdp,xorgxrdp(Debian/Ubuntu) and a full desktop. - Create users with a home folder (
adduseroruseradd -m). - Put the desktop's session command in
~/.xsession. - Blank screen after login: check the home folder, then
/var/log/xrdp-sesman.log. - Login screen never goes away: look for
AUTHFAILin the session manager log. - Limit logins with a
TerminalServerUsersgroup, and limit 3389 at the firewall.
These steps configure xrdp the same way on most distributions. xrdp is developed at neutrinolabs/xrdp on GitHub. For SSH access to the same server, the enable SSH on Ubuntu guide covers key login and firewall rules.
Comments
Post a Comment