MidnightBSD: The BSD For Everyone

Wayland

Wayland

Introduction

Wayland is a modern display server protocol designed to replace the X Window System (Xorg). Rather than routing all display communication through a central X server, Wayland compositors act as both the display server and the window manager, communicating directly with client applications and the kernel's Direct Rendering Manager (DRM). This architecture reduces latency, improves security by isolating application windows from each other, and eliminates many of the legacy layers in the X11 stack.

Wayland support on MidnightBSD is functional but still maturing. Users comfortable with configuring BSD systems manually will find it workable. Those who prefer a more polished out-of-the-box experience may wish to continue using Xorg until support matures further. Some hardware and some applications may still require Xorg or XWayland compatibility.

Prerequisites

Before setting up Wayland, ensure the following is in place:

• A supported GPU with KMS (Kernel Mode Setting) support. Intel integrated graphics, AMD GPUs, and some NVIDIA configurations are supported. See GPU Drivers below.
• The dbus message bus, which is required by most Wayland compositors and desktop components.
• Your user account must be a member of the video group to access DRM devices.

Add your user to the video group as root:

Enable dbus in /etc/rc.conf and start it:

GPU Drivers

Wayland requires kernel-level GPU support through DRM and KMS. The drm-kmod package provides the necessary kernel modules for Intel and AMD GPUs.

Install drm-kmod from mports:

Enable the appropriate module for your GPU in /etc/rc.conf.

For Intel integrated graphics (Haswell and newer):

For AMD GPUs (Southern Islands and newer):

For older AMD GPUs (pre-Southern Islands):

Load the module immediately without rebooting:

After loading, verify the DRM device nodes are present:

You should see entries such as card0 and renderD128. If /dev/dri/ is empty or missing, the GPU module did not load correctly. Check dmesg for errors.

NVIDIA GPUs are not currently supported through the open DRM path. NVIDIA users should use Xorg with the proprietary nvidia driver from mports.

Seat Management

Wayland compositors need permission to open DRM and input devices without running as root. On MidnightBSD, this is handled by seatd, a lightweight seat management daemon. It grants compositors privileged device access on behalf of logged-in users.

Install seatd from mports:

Enable and start seatd:

Add your user to the _seatd group so the compositor can communicate with the daemon:

You must log out and log back in for group membership changes to take effect.

Set the LIBSEAT_BACKEND environment variable so compositors use seatd:

Add this to your shell startup file (~/.profile, ~/.bashrc, or ~/.zshrc) so it is set automatically at login.

Compositors

A Wayland compositor combines the roles of display server and window manager. Several compositors are available in mports. The right choice depends on whether you prefer a tiling or stacking (floating) window layout.

Sway

Sway is a tiling Wayland compositor that is a drop-in replacement for the i3 window manager. It is the most widely used and tested Wayland compositor on BSD systems. Sway arranges windows automatically in a non-overlapping tiled layout and is configured through a plain text file.

Install sway and its status bar:

Copy the default configuration as a starting point:

Start sway from the console:

The default configuration sets the Super (Windows) key as the modifier. Key bindings of note from the default config:

• Super+Return — open a terminal (foot or xterm)
• Super+d — open the application launcher (dmenu or wofi)
• Super+Shift+q — close the focused window
• Super+Shift+e — exit sway
• Super+Arrow — move focus between windows
• Super+Shift+Arrow — move windows within the layout
• Super+number — switch to workspace

The sway configuration file at ~/.config/sway/config uses the same syntax as i3. Refer to man 5 sway for all available options.

Wayfire

Wayfire is a stacking (floating) compositor with a plugin-based architecture and visual effects. It is suitable for users who prefer a more traditional desktop layout where windows can overlap freely.

Install Wayfire from mports:

Copy the example configuration:

Start Wayfire from the console:

Wayfire is configured through ~/.config/wayfire.ini. Plugins for window decorations, a panel, a background, and other features are enabled and configured in this file. Refer to man wayfire and the project documentation for the full list of available plugins.

labwc

labwc is a lightweight stacking compositor modeled after Openbox. It uses XML configuration files in the same format as Openbox and is well suited for users migrating from an Openbox-based setup or who want a minimal, traditional floating window manager under Wayland.

Install labwc from mports:

Create the configuration directory and copy the default files:

Start labwc from the console:

Weston

Weston is the reference Wayland compositor maintained by the Wayland project. It is primarily intended as a demonstration and testing environment rather than a daily-use desktop, but it is stable and useful for verifying that your Wayland setup is working correctly before configuring a more full-featured compositor.

Install Weston from mports:

Start Weston from the console:

Weston can also be started with a specific backend if needed, for example to run inside an existing X session for testing:

XWayland

XWayland is an X server that runs as a Wayland client, providing backward compatibility for applications that have not yet been ported to Wayland. It allows X11 applications to run inside a Wayland compositor session without a separate Xorg server. Most compositors start XWayland automatically when an X11 application requests it.

Install XWayland from mports:

In sway, XWayland can be disabled if you do not need X11 application support, which reduces the attack surface. Add to ~/.config/sway/config:

To force a specific application to use XWayland even within a Wayland session, set GDK_BACKEND=x11 for GTK applications or QT_QPA_PLATFORM=xcb for Qt applications before launching them.

Environment Variables

Several environment variables must be set for a Wayland session to work correctly. Add these to your shell startup file (~/.profile for login shells) so they are available in all applications launched from the compositor.

Required

XDG_RUNTIME_DIR points to a per-user directory for runtime files such as the Wayland socket. It must be set before starting a compositor:

Create the directory if it does not exist and set the correct permissions:

The Wayland compositor sets WAYLAND_DISPLAY automatically. It is typically wayland-0 and points to the compositor's socket inside XDG_RUNTIME_DIR.

Toolkit Integration

Tell GTK applications to use the Wayland backend:

Tell Qt applications to use the Wayland platform plugin:

Tell SDL2 applications to use Wayland:

Enable native Wayland rendering in Firefox:

Enable Wayland rendering in Electron applications such as VS Code:

Enable Wayland rendering in Chromium and Chromium-based browsers:

Seat Management

Application Compatibility

Most GTK3, GTK4, and Qt5/Qt6 applications support Wayland natively. Applications still using older toolkits or hardcoded X11 calls will run through XWayland automatically as long as XWayland is installed and enabled.

Terminal emulators with native Wayland support available in mports include:

• foot — a lightweight, fast terminal designed for Wayland
• alacritty — a GPU-accelerated terminal with Wayland support
• kitty — a feature-rich GPU terminal with Wayland support

Application launchers compatible with Wayland:

• wofi — a Wayland-native launcher similar to rofi
• bemenu — a Wayland-compatible dynamic menu library and program
• fuzzel — a lightweight application launcher for Wayland

Status bars for use with sway and other wlroots compositors:

• waybar — a highly customizable Wayland bar
• swaybar — the built-in status bar included with sway

Screen capture and screenshot tools:

• grim — a screenshot tool for Wayland compositors
• slurp — select a region on a Wayland display (used with grim)
• wf-recorder — screen recording for wlroots-based compositors

Clipboard management:

• wl-clipboard — provides wl-copy and wl-paste command-line clipboard tools for Wayland

Troubleshooting

Compositor fails to start: no DRM device

If the compositor exits immediately with an error about DRM or KMS, the GPU kernel module may not be loaded. Verify with:

If /dev/dri/ is empty, load the appropriate module manually and check for errors:

Permission denied on /dev/dri or /dev/input

Ensure your user is a member of the video group and that seatd is running. Group changes require logging out and back in to take effect.

XDG_RUNTIME_DIR not set or wrong permissions

The directory must exist, be owned by your user, and have mode 700. Check with:

If it is missing, create it:

X11 applications show a blank window or crash

Ensure XWayland is installed and that the compositor has started it. Check for a Wayland socket and an X display socket in the runtime directory:

You should see both wayland-0 and a file like .X0-lock when XWayland is running.

Enabling verbose logging

Start sway with debug logging to diagnose startup failures:

For weston, verbose output is enabled with: