KRdp (KDE Remote Desktop Protocol)

repository·master·Indexed 41 days ago

https://github.com/kde/krdp

A library and set of examples for creating an RDP server on Linux, specifically designed for KDE environments. It includes the krdpserver binary for hosting sessions with support for NLA security, H.264 video streaming via VAAPI, and multiple operation modes including RemoteAccess, SharedAccess, and AdditionalDisplay.

Tokens
5.7K
Snippets
17
Records
23
Agent score
53%

What's inside KRdp

  1. Configure TLS certificates for krdpserver

    master
    A valid TLS certificate and key are required to encrypt communication. By default, the server looks for server.crt and server.key in the current working directory. You can specify custom paths using the --certificate and --certificate-key command line options. If no valid certificate is found, the server will generate a temporary self-signed certificate.
  2. Run the krdpserver example server

    master

    To run the krdpserver example, you must provide a username and password via command line arguments. The server listens on all interfaces on port 3389 by default. Use -u or --username for the login name and -p or --password for the password.

    Note that the username is case-sensitive.

    krdpserver -u user -p pass
  3. Configure krdpserver via CLI (Headless Setup)

    master

    If you are managing the server via SSH, you can configure it using the following steps:

    1. Authorize the server via Flatpak permissions.
    2. Generate a self-signed certificate using OpenSSL.
    3. Configure the krdpserverrc file to use the new certificates and enable system user authentication.
    4. Manage the systemd service to enable or restart the server.
    # Authorize the krdpserver for remote desktop access
    flatpak permission-set kde-authorized remote-desktop org.kde.krdpserver yes
    
    # Generate a server certificate
    mkdir --parents "$HOME/.local/share/krdpserver"
    certificatePath="$HOME/.local/share/krdpserver/krdp.crt"
    certificateKeyPath="$HOME/.local/share/krdpserver/krdp.key"
    openssl req -nodes -new -x509 -keyout "$certificateKeyPath" -out "$certificatePath" -days 1 -batch
    
    # Configure the certificate and enable system user authentication
    kwriteconfig6 --file krdpserverrc --group General --key Certificate "$certificatePath"
    kwriteconfig6 --file krdpserverrc --group General --key CertificateKey "$certificateKeyPath"
    kwriteconfig6 --file krdpserverrc --group General --key SystemUserEnabled true
    
    # Enable/restart the systemd service
    systemctl --user enable --now app-org.kde.krdpserver.service
    systemctl --user restart app-org.kde.krdpserver.service
  4. Configure SDDM Autologin for RDP access

    master

    Since SDDM does not support RDP, you must either be already logged in or configure SDDM to autologin to your user.

    Warning: Autologin means your session starts physically unlocked on your PC. When you log in remotely, the physical session will also be unlocked.

    To configure autologin for the current user and enable automatic relogin on logout:

    # Configure autologin for your current user
    user=$(whoami)
    sudo kwriteconfig6 --file /etc/sddm.conf.d/kde_settings.conf --group Autologin --key User $user
    
    # Enable automatic relogin on logout to avoid scenarios where the system is stuck on sddm
    sudo kwriteconfig6 --file /etc/sddm.conf.d/kde_settings.conf --group Autologin --key Relogin true
    
    # Restart sddm to force an autologin (do not run if already logged in)
    # systemctl restart sddm.service
  5. Configure Virtual Monitors in krdpserver

    master

    Instead of streaming an existing physical monitor, you can create a new virtual output using the --virtual-monitor flag. The format must follow WIDTHxHEIGHT@SCALE (e.g., 1920x1080@1). This mode is incompatible with the --monitor flag.

    # Create a 4K virtual monitor with scale 2
    krdpserver --virtual-monitor 3840x2160@2
  6. Configure krdpserver Operation Modes

    master

    The krdpserver supports three distinct operation modes via the --mode flag. These modes determine how the remote session interacts with the local desktop:

    1. RemoteAccess: Typically used for exclusive control.
    2. SharedAccess: Allows multiple users to view/interact with the same session.
    3. AdditionalDisplay: Used to provide a new virtual output for the remote client.
    # Set mode to SharedAccess
    krdpserver --mode SharedAccess
  7. Known issues and limitations of KRdp

    master

    Protocol and Feature Limitations

    • Security: Only the NLA (Network Level Authentication) security type is supported.
    • Authentication: Only one username and password combination is supported for login.
    • Capabilities: Only video streaming and remote input are supported.
    • Video Extension: Only the RDP "Graphics Pipeline" extension is implemented. This requires clients that support H.264 via this extension.

    Hardware and Encoding

    • H.264 Encoding: Uses VAAPI for hardware encoding. NVidia hardware is not supported for hardware encoding and will fall back to software encoding. Software encoding may ignore the --quality slider due to encoder limitations.

    Desktop Environment Integration

    • Monitor Selection: Due to limitations in the Plasma 5.27 Remote Desktop portal, you cannot select a specific screen via the portal. Use the --monitor <index> CLI option instead.
    • High DPI: Input may be offset on high DPI screens (fix available in Plasma 5.27.8+).
  8. Connect to the krdpserver using FreeRDP

    master

    The FreeRDP client is a confirmed working client. To connect, use the following command structure, ensuring you provide the correct username, password, and IP address. If testing on the same machine, use localhost as the IP address.

    Note: The username is case-sensitive.

    xfreerdp /u:<username> /p:<password> -clipboard /v:<ip_address>:3389
  9. Known working and non-working RDP clients

    master

    Working Clients

    • XFreeRDP and wlFreeRDP (FreeRDP project)
    • Remmina (GNOME remote desktop client)
    • Thincast Remote Desktop Client
    • Windows Remote Desktop client (recent Windows 10 versions)

    Non-working Clients

    • Microsoft Remote Desktop client for Android (fails to enable H.264 support).
  10. Reference: krdpserver command line options

    master

    The following options are available for the krdpserver binary:

    OptionArgumentDescription
    -u, --username<username>Required. The username for client login.
    -p, --password<password>Required. The password for client login.
    --port<port>The port to listen on. Defaults to 3389.
    --certificate<certificate>Path to a TLS certificate file. If not found, a self-signed cert is generated.
    --certificate-key<certificate-key>Path to the TLS certificate key matching the certificate.
    --monitor<monitor>The index of the monitor to stream. Defaults to the whole workspace.
    --mode<mode>Operation mode: RemoteAccess, SharedAccess, or AdditionalDisplay.
    --quality<quality>Video quality from 0 (lowest) to 100 (highest).
  11. Use the RdpConnection class to manage RDP sessions

    master

    The KRdp::RdpConnection class represents an active RDP session between a client and the server. It manages the RDP communication protocol and operates in its own dedicated thread.

    Developers can interact with the session through several component handlers:

    • inputHandler(): Manages user input from the client.
    • videoStream(): Handles the video data stream.
    • cursor(): Manages the remote cursor.
    • clipboard(): Manages clipboard synchronization.
    • displayControl(): Controls display settings.
    • networkDetection(): Monitors network conditions.

    Monitoring the session lifecycle is done via the state() method and the stateChanged(State newState) signal.

    // Example of observing session state
    connect(rdpConnection, &KRdp::RdpConnection::stateChanged, [](KRdp::RdpConnection::State newState) {
        if (newState == KRdp::RdpConnection::State::Running) {
            qDebug() << "Session is now running";
        }
    });
    
    KRdp::RdpConnection::State currentState = rdpConnection->state();
  12. Configure PAM authentication in KRdp::Server

    master

    You can configure the server to authenticate users against the system's PAM (Pluggable Authentication Modules) instead of using the internal user list. This allows the server to use the credentials of the user running the daemon.

    Use setUsePAMAuthentication(bool usePAM) to enable or disable this behavior.