Subsystems

This documentation refers to individual protocol features, it links to the implementation and technical documentation for each subsystem.

Each subsystem should be using its own prefix for capabilities and packet types. (most already do)

Most modules are optional, see security considerations.

See the display server data inventory for the non-framebuffer data that can be retrieved from display servers and associated desktop-session services.

Concepts

Subsystems are independently loaded feature modules with matching client and server-side responsibilities.

A client or server may choose to completely disable a subsystem.
When this is the case, it will not load the module into memory and will not know how to handle requests for this feature.

Most subsystems are independent of each other. The diagram below shows the dependencies enforced at subsystem load time (see xpra/server/features.py). Solid arrows mark a hard requirement — the dependent subsystem cannot be enabled unless its parent is also enabled. Dashed arrows mark soft or alternative dependencies — the subsystem can use the parent if it is available, or has an alternative code path on some platforms.

Dependency graph

Dependency graph showing Xpra subsystem groups and their hard or soft dependencies

The SVG is generated from the Graphviz source; click the diagram to open it at full size.

View original Mermaid source
graph LR
    classDef core fill:#fde,stroke:#a04,stroke-width:2px,color:#000;
    classDef group fill:#eef,stroke:#446,color:#000;

    Core["Server core<br/>(sockets, auth, dispatch)"]:::core

    subgraph Backend["Display backend (mutually exclusive)"]
        X11[x11]
        Wayland[wayland]
    end

    subgraph Surface["Display surface"]
        Window[window]
        Keyboard[keyboard]
        Pointer[pointer]
        Display[display]
        Cursor[cursor]
        OpenGL[opengl]
        Bell[bell]
        BellSrv[bell server]
    end
    Window --> Display
    Keyboard --> Display
    Pointer --> Display
    Display --> Cursor
    Display --> OpenGL
    Display --> Bell
    Bell --> BellSrv

    subgraph Media["Media pipeline"]
        GStreamer[gstreamer]
        Audio[audio]
        Pulseaudio[pulseaudio]
        AVSync[av_sync]
        Webcam[webcam]
        Encoding[encoding]
    end
    GStreamer --> Audio
    Audio --> Pulseaudio
    Audio --> AVSync
    GStreamer -.-> Webcam
    GStreamer -.-> Encoding

    subgraph X11Ext["X11-only extensions"]
        ICC[icc]
        SysTray[systray]
    end
    X11 --> ICC
    Display --> ICC
    X11 --> SysTray
    X11 --> BellSrv
    Wayland --> BellSrv

    subgraph UI["UI / lifecycle"]
        GTK[gtk]
        Tray[tray]
        Watcher[watcher]
        Power[power]
        Suspend[suspend]
        Idle[idle]
        Debug[debug]
        Splash[splash]
    end
    GTK --> Tray
    SysTray -.-> Tray

    subgraph Net["Network / transport"]
        SSL[ssl]
        SSH[ssh]
        HTTP[http]
        MDNS[mdns]
        RFB[rfb]
        Control[control]
        SSHAgent[ssh_agent]
    end
    SSL -.-> HTTP
    SSH --> SSHAgent

    subgraph Session["Session features"]
        Clipboard[clipboard]
        FileT[file]
        Printer[printer]
        Notification[notification]
        Command[command]
        Logging[logging]
        Ping[ping]
        Bandwidth[bandwidth]
        Shell[shell]
        MMap[mmap]
        DBus[dbus]
        Encryption[encryption]
        Sharing[sharing]
        ClientSession[client_session]
        Settings[settings]
    end
    Printer --> FileT
    DBus --> Notification
    DBus -.-> Tray

    Core --> Backend
    Core --> Surface
    Core --> Media
    Core --> UI
    Core --> Net
    Core --> Session

    class Backend,Surface,Media,X11Ext,UI,Net,Session group;

Graph notes

Protocol subsystems

These subsystems involve communication between client and server.

| Subsystem | Client Module | Server Module | Client Connection Module | User Documentation | |---------------------------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------|-------------------------------------------------------| | Audio | audio | audio | audio | audio feature | | Bandwidth | bandwidth | bandwidth | bandwidth | n/a | | Clipboard | clipboard | clipboard | clipboard | clipboard feature | | Command | command | command | none | n/a | | Cursor | cursor | cursor | cursor | n/a | | Display | display | display | display | Automatically configured | | Encoding | encoding | encoding | encoding | Automatically configured | | Encryption | n/a | encryption | n/a | encryption | | File | n/a | file | file | file transfers | | Info | server_info | info | n/a | | | Keyboard | keyboard | keyboard | keyboard | keyboard feature | | Logging | logging | logging | none | logging usage | | Menu | n/a | menu | menu | n/a | | MMAP | mmap | mmap | mmap | enabled automatically | | Notification | notification | notification | notification | notifications feature | | Ping | ping | ping | ping | n/a | | Pointer | pointer | pointer | pointer | | | Power | power | power | n/a | | | Printer | n/a | printer | printer | printing feature | | Sharing | n/a | sharing | sharing | n/a | | Shell | n/a | shell | shell | n/a | | Socket | socket | n/a | n/a | | | SSH Agent | ssh_agent | ssh_agent | none | n/a | | Tray | tray | tray | none | n/a | | Webcam | webcam | webcam | webcam | webcam usage | | Window | window | window | window | |

Server-only subsystems

These subsystems handle server-side infrastructure and have no corresponding client module or client connection module.

| Subsystem | Server Module | User Documentation | |----------------|----------------------------------------------------------------------------------------------------|--------------------------------------------------| | Auth | auth | authentication | | ClientSession | client_session | n/a | | Control | control | n/a | | Daemon | daemon | n/a | | DBUS | dbus | n/a | | Debug | debug | n/a | | DRM | drm | n/a | | GTK | gtk | n/a | | HTTP | http | n/a | | ID | id | n/a | | Idle | idle | n/a | | MDNS | mdns | multicast DNS | | OpenGL | opengl | OpenGL usage | | Platform | platform | n/a | | Process | process | n/a | | PulseAudio | pulseaudio | audio feature | | RFB | rfb | n/a | | SessionFiles | sessionfiles | n/a | | Settings | settings | n/a | | Shutdown | shutdown | n/a | | Splash | splash | n/a | | Suspend | suspend | n/a | | Version | version | n/a | | Watcher | watcher | n/a | | Xvfb | xvfb | n/a |