Subsystems

August 21, 2026 · View on GitHub

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.

Client Module: feature implementation loaded by the client, it interfaces with the corresponding "Client Connection Module" on the server side
Client Connection Module: for each connection with a client, the server will instantiate a handler
Server Module: feature implemented by the server, it may interact with multiple "Client Connection Modules"

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

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

display is auto-enabled when any of window, keyboard or pointer is enabled — it is the union of those features rather than a prerequisite.
notification requires dbus on Linux, but has native code paths on Windows and macOS (shown as dashed via DBus).
tray requires gtk and (for the system tray icon on X11) the systray extension.
The ICC, bell server and systray subsystems are loaded only on X11 sessions, and require both x11 and the corresponding feature flag.
pulseaudio and av_sync are strict refinements of audio, which itself requires gstreamer.

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