Wayland: Difference between revisions

Latest revision as of 20:33, 11 February 2026

Wayland is a new display protocol that aims to replace X11. Wayland requires a seat manager to work.

The setup-wayland-base script installs and enables elogind as seat manager besides enabling community repository and eudev.

Compositors

Display servers that implement the Wayland display server protocol are also called Wayland compositors because they additionally perform the task of a compositing window manager.

Multiple compositor implementations exist, including Sway, Mutter (GNOME's compositor) and Kwin (KDE's compositor). The following compositors are available in Alpine Linux.

XWayland

XWayland is an X server that can be instructed to run under Wayland so as to enable certain native X11 applications that have not been fully upgraded for Wayland. However, XWayland is a compatibility layer that is still not sufficiently effective to run native X11 graphical applications that still require running as root without advanced configuration, such as gparted, as XWayland does not have root permissions as per Wayland protocols and for the sake of enhanced security.

Although the X11 protocol design seeks to include flexibility and network transparency, consider that the use of XWayland reintroduces certain X11 design vulnerabilities into a Wayland session that was originally designed to avoid them, potentially including keylogging (capturing keystrokes)/taking screenshots/moving/resizing of other windows, although patches are applied where possible.

xwayland is typically bundled with compositors. To check performance without XWayland, attempt to disable it on the compositor first (this can be achieved, for example, in Sway, by adding the line xwayland disable, say, near the top of the ~/.config/sway/config file). If performance for your packages appears satisfactory, the package could be attempted to be removed in various compositors, including Sway, but it is a dependency on others, such as Labwc, river-classic, Cagebreak; ensure that apk does not indicate that it is a dependency to a given package when removing it:

$ doas apk del xwayland

Wayback

Wayback is another X11 compatibility layer, but unlike XWayland, it enables hosting a full X11 desktop environment on Wayland by enabling XWayland to run in rootful mode (future plans include enabling Wayback rootless mode). This enables Xfce and MATE to run fully under Wayland. However, as of December 2025, Wayback is still in alpha quality and thus not recommended for production.

XDG_RUNTIME_DIR

As per the protocol specifications, Wayland compositors require the XDG_RUNTIME_DIR variable to be set. When setting paths for XDG_RUNTIME_DIR, at all times they should follow XDG specifications.

Note: XDG_RUNTIME_DIR MUST be initialised before the Wayland compositor and the D-Bus session instances are started.

For techniques on properly initialising this variable, see XDG_RUNTIME_DIR.

Troubleshooting

error: XDG_RUNTIME_DIR is invalid or not set in the environment

The above error message appears when starting services/applications that require the environment variable XDG_RUNTIME_DIR to be set. Fix it using one of the above methods before proceeding.

@@ Line 9: / Line 9: @@
 Multiple compositor implementations exist, including [[Sway]], [https://en.wikipedia.org/wiki/Mutter%20(software) Mutter] ([[GNOME]]'s compositor) and [https://en.wikipedia.org/wiki/KWin Kwin] ([[KDE]]'s compositor). The following [[:Category:Compositor|compositors]] are available in Alpine Linux.
-== XDG_RUNTIME_DIR ==
+== XWayland ==
-As per the protocol spec, Wayland compositors require the <code>XDG_RUNTIME_DIR</code> variable to be set.
+XWayland is an X server that can be instructed to run under Wayland so as to enable certain native X11 applications that have not been fully upgraded for Wayland.  However, XWayland is a compatibility layer that is still not sufficiently effective to run native X11 graphical applications that still require running as root without advanced configuration, such as '''gparted''', as XWayland does not have root permissions as per Wayland protocols and for the sake of enhanced security.
-=== With elogind ===
+Although the X11 protocol design seeks to include flexibility and network transparency, consider that the use of XWayland reintroduces certain [https://biggo.com/news/202511040138_X11-Wayland-Security-Debate X11 design vulnerabilities] into a Wayland session that was originally designed to avoid them, potentially including ''keylogging'' (capturing keystrokes)/taking screenshots/moving/resizing of other windows, although patches are applied where possible.
-When using [[elogind]] as a seat manager, it exports <code>XDG_RUNTIME_DIR</code> and other XDG environment variables automatically for each session. No further configuration is required.
+{{Pkg|xwayland}} is typically bundled with compositors.  To check performance without XWayland, attempt to disable it on the compositor first (this can be achieved, for example, in [[Sway]], by adding the line {{ic|xwayland disable}}, say, near the top of the {{Path|~/.config/sway/config}} file).  If performance for your packages appears satisfactory, the package could be attempted to be removed in various compositors, including '''Sway''', but it is a dependency on others, such as '''Labwc''', '''river-classic''', '''Cagebreak''';   ensure that '''apk''' does not indicate that it is a dependency to a given package when removing it:
+{{Cmd|$ doas apk del xwayland}}
-=== With pam_rundir ===
+== Wayback ==
+{{Main|Wayback}}
-[https://github.com/jjk-jacky/pam_rundir pam_rundir] is a [[PAM]] module that provides the runtime directory variable. Installing the package {{pkg|pam-rundir}} takes care of dependencies and no further configuration is required.
+Wayback is another X11 compatibility layer, but unlike XWayland, it enables hosting a full X11 desktop environment on Wayland by enabling XWayland to run in rootful mode (future plans include enabling Wayback rootless mode).  This enables [[Xfce]] and [[MATE]] to run fully under Wayland.  However, as of December 2025, Wayback is still in alpha quality and thus not recommended for production.
-{{Note| <code>XDG_RUNTIME_DIR</code> variable MUST be initialised before the Wayland compositor, and also before the D-Bus session instance is started in your startup script/file for both the methods listed below.}}
+== XDG_RUNTIME_DIR ==
-=== With mkrundir ===
-[https://git.sr.ht/~whynothugo/mkrundir mkrundir] is an executable that can be used to initialise the runtime directory explicitly by each user. To use <code>mkrundir</Code>, install the package {{pkg|mkrundir}} available in [[Repositories#Testing|testing]] repository. In your shell init script (e.g.: {{Path|~/.profile}} include an entry as follows at the '''top''' of the file {{Cat|~.profile|...
-export XDG_RUNTIME_DIR{{=}}$(mkrundir)
-...}}
-As per [https://git.sr.ht/~whynothugo/mkrundir mkrundir] website, this might have issues inside containers, due to privilege escalation.
+As per the protocol specifications, Wayland compositors require the <code>XDG_RUNTIME_DIR</code> variable to be set. When setting paths for {{ic|XDG_RUNTIME_DIR}}, at all times they should follow [https://specifications.freedesktop.org/basedir/latest/#variables '''XDG specifications'''].
-=== Creating and exporting XDG_RUNTIME_DIR manually ===
+{{Note|<code>XDG_RUNTIME_DIR</code> MUST be initialised before the Wayland compositor and the D-Bus session instances are started.}}
-Generally, care should be taken when configuring the <code>XDG_*</code> variables manually as this configuration may have errors or conflict with other utilities that do this automatically. Use this only on a system that's not using [[elogind]] and other solutions outlined above cannot handle this.
+For techniques on properly initialising this variable, see [[XDG_RUNTIME_DIR]].
-The <code>XDG_RUNTIME_DIR</code> can be initialised manually by adding below snippet to shell init scripts (e.g.: {{Path|~/.profile}}):
+== Troubleshooting ==
-{{Cat|~/.profile|<nowiki>if [ -z "$XDG_RUNTIME_DIR" ]; then
+=== error: XDG_RUNTIME_DIR is invalid or not set in the environment ===
-	XDG_RUNTIME_DIR="/tmp/$(id -u)-runtime-dir"
-	mkdir -pm 0700 "$XDG_RUNTIME_DIR"
+The above error message appears when starting services/applications that require the environment variable [[XDG_RUNTIME_DIR]] to be set. Fix it using one of the above methods before proceeding.
-	export XDG_RUNTIME_DIR
-fi
-</nowiki>}}
 == See also ==
+* [[Kodi]]
 * [https://wiki.archlinux.org/title/Wayland Wayland - Arch Wiki]
 * [https://wiki.gentoo.org/wiki/Wayland Wayland - Gentoo Wiki]