XRDP fails to start the MATE session on Ubuntu 22.04 because the default configuration attempts to launch a new Xsession that conflicts with the existing desktop environment or lacks the correct session manager binaries. The most reliable fix involves editing the
xrdp-startwm.sh script to explicitly invoke the MATE session manager, ensuring the remote connection mirrors the local desktop experience without crashing or dropping back to a black screen.
Understanding the Root Cause
When you install XRDP on Ubuntu MATE, it typically comes with a generic startup script located at
/etc/xrdp/startwm.sh. This script is designed to be distribution-agnostic, meaning it tries to detect and start a standard X11 session. However, Ubuntu MATE uses the
mate-session-manager rather than the generic
startxfce4 or
startlxde commands often found in default configurations.
If the script does not find a compatible session starter, it may exit silently, leaving you with a disconnected session or a black screen after authentication. Additionally, if another user is already logged into the physical console, XRDP might try to share that session, leading to resource conflicts. Understanding this separation between the display manager (LightDM) and the session manager (MATE) is crucial for troubleshooting. You are essentially telling XRDP which graphical shell to load once the TCP connection is established.
Step-by-Step Fix: Editing the Startup Script
The primary solution requires modifying the XRDP initialization file to point directly to the MATE session binary. Follow these steps carefully to ensure the changes persist across reboots.
- Backup the original configuration: Before making any changes, create a backup of the current startup script. This allows you to revert if something goes wrong. Open your terminal and run:
sudo cp /etc/xrdp/startwm.sh /etc/xrdp/startwm.sh.bak
- Edit the startup script: Use a text editor with root privileges to modify the file. We recommend using
nano for its simplicity:
sudo nano /etc/xrdp/startwm.sh
- Locate the session launch section: Scroll to the bottom of the file. You will likely see lines attempting to source
/etc/X11/Xsession or calling startxfce4. These are the lines causing the conflict.
- Replace with MATE specific commands: Comment out the existing session launching lines by adding a
# at the beginning of each line. Then, add the following two lines at the very end of the file:
unset SESSION_MANAGER
unset DBUS_SESSION_BUS_ADDRESS
exec mate-session-manager
This ensures that no conflicting session managers are inherited from the parent process and forces the start of the MATE desktop environment specifically.
- Save and exit: If using
nano, press Ctrl+O then Enter to save, followed by Ctrl+X to exit.
After saving the file, you must restart the XRDP service for the changes to take effect. Run the following command:
sudo systemctl restart xrdp
You can now attempt to connect again using your RDP client. If you were previously connected, disconnect and reconnect. The session should now load the full MATE interface.
Handling Multiple Sessions and Port Conflicts
Sometimes, the issue is not just about which session manager is called, but how XRDP handles multiple simultaneous connections. By default, XRDP listens on port 3389. If you have multiple users trying to connect, or if a previous session did not terminate cleanly, you might encounter "Connection Refused" errors or black screens even after fixing the script.
To address this, you can configure XRDP to allow multiple sessions by editing the
xrdp.ini file. However, a simpler immediate fix is to ensure that the local display manager is not interfering. If you are logging in via SSH and then starting XRDP, ensure that no other instance of
mate-session-manager is running unexpectedly. You can check for zombie processes with:
ps aux | grep mate-session
If you see multiple instances, kill them before restarting the service. For a more robust setup involving security, consider setting up an X11 SSH Tunnel for Remote Desktop Access as described in our guide on securing remote connections. This adds an extra layer of encryption over the RDP protocol.
Verifying the Installation and Permissions
Ensure that the XRDP service is enabled to start on boot. Run:
sudo systemctl enable xrdp
Also, verify that the user account you are connecting with has permission to access the X server. In some cases, especially with newer versions of Ubuntu, the
xrdp-sesman service needs to be restarted alongside the main daemon to clear cached session data.
sudo systemctl restart xrdp-sesman
If you still experience issues, check the system logs for specific error messages related to MATE components. Look at
/var/log/xrdp-sesman.log for clues regarding why the session manager failed to initialize. This log will tell you if a specific MATE plugin is crashing during startup.
For those experiencing lag after successfully connecting, refer to our article on eliminating lag when connecting to Ubuntu Server via xRDP with Remmina to optimize performance settings.
Frequently Asked Questions
Why do I get a black screen after entering my password?
A black screen usually indicates that the session manager started but failed to render the desktop environment. This is often caused by missing dependencies in the
startwm.sh script. Ensure you have added
exec mate-session-manager to the end of the script and removed conflicting entries like
startxfce4.
Can I use XRDP with other desktop environments on Ubuntu?
Yes, but you must change the command in
startwm.sh to match your specific desktop environment. For GNOME, use
gnome-session; for KDE, use
startplasma-x11; and for XFCE, use
startxfce4. Each environment has its own session manager binary that XRDP needs to call explicitly.
Does XRDP work with Wayland on Ubuntu 22.04?
No, XRDP is designed for X11. Ubuntu 22.04 defaults to Wayland for GNOME, but MATE typically uses X11. If you switch your system to Wayland, XRDP will fail to connect. You must ensure your system is booting into the Xorg session, which is usually the fallback option in the login screen if Wayland is unavailable or disabled.
How do I fix "Connection Refused" errors on port 3389?
This error often means the firewall is blocking the port or the service is not running. First, check if XRDP is active with
systemctl status xrdp. Then, ensure your UFW firewall allows incoming traffic on port 3389 by running
sudo ufw allow 3389/tcp. Restarting the service after opening the port often resolves the issue.
Is it safe to run XRDP on a production server?
While XRDP is functional, it is generally recommended to use SSH for secure command-line access and reserve XRDP for administrative tasks requiring a GUI. Always restrict XRDP access to trusted IP addresses using firewall rules. For enhanced security, tunneling XRDP over SSH is a best practice to encrypt the remote desktop traffic.