Chapter 6. Wayland | FreeBSD Documentation Portal
Description: This chapter describes how to install and configure Wayland and compositors on FreeBSD, which provides a graphical user environment
Keywords: Wayland,XWayland,KDE,Plasma,Xfce,Gnome,Intel,AMD,NVIDIA,Wayfire,Sway,Hikari

# Chapter 6. Wayland

## 6.1. Synopsis

An installation of FreeBSD using bsdinstall does not automatically install a graphical user interface. This chapter describes how to select, install, and configure a Wayland compositor, which provides a graphical environment.

Before reading this chapter:

- Know how to install additional third-party software.

- Know how to identify and configure drivers for the graphics hardware.

Read this chapter to learn:

- How to configure FreeBSD to host a Wayland graphical environment.

- How to install and configure a Wayland compositor.

- How to run programs designed for the older X Window System.

- How to configure remote desktop access to a Wayland graphical environment.

## 6.2. Wayland Overview

Wayland is a communication protocol that can replace a display server such as Xorg. It differs from Xorg in several important ways. First, Wayland is only a protocol that acts as an intermediary between clients using a mechanism which removes the dependency on an X server. Xorg includes both the X11 protocol, used to run remote displays, and the X server, used to accept connections and display windows. Under Wayland, the compositor or window manager provides the display server instead of a traditional X server.

Since Wayland is not an X server, traditional X screen connections will need to utilize other methods such as VNC or RDP for remote desktop management. Second, Wayland can manage composite communications between clients and a compositor as a separate entity which does not need to support the X protocols.

Wayland is relatively new, and not all software has been updated to run natively without `Xwayland` support. Because Wayland does not provide the X server, and expects compositors to provide that support, X11 window managers that do not yet support Wayland will require that `Xwayland` is not started with the `-rootless` parameter. The `-rootless` parameter, when removed, will restore X11 window manager support.

| The current NVIDIA® driver should work with most wlroots compositors, but it may be a little unstable and not support all features at this time. Volunteers to help work on the NVIDIA® DRM are requested.

Currently, a lot of software will function with minimal issues on Wayland, including Firefox. And a few desktops are also available, such as the Compiz Fusion replacement, known as Wayfire, and the i3 window manager replacement, Sway.

| As of May, 2021, plasma5-kwin does support Wayland on FreeBSD. To use Plasma under Wayland, use the `startplasma-wayland` parameter to `ck-launch-session` and tie in dbus with: `dbus-launch --exit-with-x11 ck-launch-session startplasma-wayland` to get it working.

For compositors, a kernel supporting the evdev(4) driver must exist to utilize the keybinding functionality. This is built into the GENERIC kernel by default; however, if it has been customized and evdev(4) support was stripped out, the evdev(4) module will need to be loaded. In addition, users of `Wayland` will need to be members of the `video` group. To quickly make this change, use the `pw` command:

    pw groupmod video -m user

Installing Wayland is simple; there is not a great deal of configuration for the protocol itself. Most of the composition will depend on the chosen compositor. By installing `seatd` now, a step is skipped as part of the compositor installation and configuration as `seatd` is needed to provide non-root access to certain devices.

All of the compositors described here should work with graphics/drm-kmod open source drivers; however, the NVIDIA® graphics cards may have issues when using the proprietary drivers. Begin by installing the following packages:

    # pkg install wayland seatd

Once the protocol and supporting packages have been installed, a compositor must create the user interface. Several compositors will be covered in the following sections. All compositors using Wayland will need a runtime directory defined in the environment. Since FreeBSD 14.1, this is created and defined automatically. For previous versions, this is achieved with the following command in the bourne shell:

    % export XDG_RUNTIME_DIR=/var/run/user/`id -u`

It is important to note that most compositors will search the XDG_RUNTIME_DIR directory for the configuration files. In the examples included here, a parameter will be used to specify a configuration file in ~/.config to keep temporary files and configuration files separate. It is recommended that an alias be configured for each compositor to load the designated configuration file.

| It has been reported that ZFS users may experience issues with some Wayland clients because they need access to `posix_fallocate()` in the runtime directory. While the author could not reproduce this issue on their ZFS system, a recommended workaround is not to use ZFS for the runtime directory and instead use `tmpfs` for the /var/run directory. In this case, the `tmpfs` file system is used for /var/run and mounted through the command `mount -t tmpfs tmpfs /var/run` command and then make this change persist across reboots through /etc/fstab. The XDG_RUNTIME_DIR environment variable could be configured to use /var/run/user/$UID and avoid potential pitfalls with ZFS. Consider that scenario when reviewing the configuration examples in the following sections.

The seatd daemon helps manage access to shared system devices for non-root users in compositors; this includes graphics cards. For traditional X11 managers, `seatd` is not needed, such as both Plasma and GNOME, but for the Wayland compositors discussed here, it will need enabled on the system and be running before starting a compositor environment. To enable and start the `seatd` daemon now, and on system initialization:

    # sysrc seatd_enable="YES"
    # service seatd start

Afterward, a compositor, which is similar to an X11 desktop, will need to be installed for the GUI environment. Three are discussed here, including basic configuration options, setting up a screen lock, and recommendations for more information.

## 6.3. The Wayfire Compositor

Wayfire is a compositor that aims to be lightweight and customizable. Several features are available, and it brings back several elements from the previously released Compiz Fusion desktop. All of the parts look beautiful on modern hardware. To get Wayfire up and running, begin by installing the required packages:

    # pkg install wayfire wf-shell alacritty swaylock-effects swayidle wlogout kanshi mako wlsunset

The `alacritty` package provides a terminal emulator. Still, it is not completely required as other terminal emulators such as `kitty`, and XFCE-4 `Terminal` have been tested and verified to work under the Wayfire compositor. Wayfire configuration is relatively simple; it uses a file that should be reviewed for any customizations. To begin, copy the example file over to the runtime environment configuration directory and then edit the file:

    % mkdir ~/.config/wayfire
    % cp /usr/local/share/examples/wayfire/wayfire.ini ~/.config/wayfire

The defaults for most users should be fine. Within the configuration file, items like the famous `cube` are pre-configured, and there are instructions to help with the available settings. A few primary settings of note include:

    [output]
    mode = 1920x1080@60000
    position = 0,0
    transform = normal
    scale = 1.000000

In this example, from the configuration file, the screen’s output should be the listed mode at the listed hertz. For example, the mode should be set to `widthxheight@refresh_rate`. The position places the output at a specific pixel location specified. The default should be fine for most users. Finally, transform sets a background transform, and scale will scale the output to the specified scale factor. The defaults for these options are generally acceptable; for more information, see the documentation.

As mentioned, Wayland is new, and not all applications work with the protocol yet. At this time, `sddm` does not appear to support starting and managing compositors in Wayland. The `swaylock` utility has been used instead in these examples. The configuration file contains options to run `swayidle` and `swaylock` for idle and locking of the screen.

This option to define the action to take when the system is idle is listed as:

    idle = swaylock

And the lock timeout is configured using the following lines:

    [idle]
    toggle = <super> KEY_Z
    screensaver_timeout = 300
    dpms_timeout = 600

The first option will lock the screen after 300 seconds, and after another 300, the screen will shut off through the `dpms_timeout` option.

One final thing to note is the <super> key. Most of the configuration mentions this key, and it is the traditional `Windows` key on the keyboard. Most keyboards have this super key available; however, it should be remapped within this configuration file if it is not available. For example, to lock the screen, press and hold the super key, the `shift` key, and press the `escape` key. Unless the mappings have changed, this will execute the swaylock application. The default configuration for `swaylock` will show a grey screen; however, the application is highly customizable and well documented. In addition, since the swaylock-effects is the version that was installed, there are several options available such as the blur effect, which can be seen using the following command:

    % swaylock --effect-blur 7x5

There is also the `--clock` parameter which will display a clock with the date and time on the lock screen. When x11/swaylock-effects was installed, a default pam.d configuration was included. It provides the default options that should be fine for most users. More advanced options are available; see the PAM documentation for more information.

At this point, it is time to test Wayfire and see if it can start up on the system. Just type the following command:

    % wayfire -c ~/.config/wayfire/wayfire.ini

The compositor should now start and display a background image along with a menu bar at the top of the screen. Wayfire will attempt to list installed compatible applications for the desktop and present them in this drop-down menu; for example, if the XFCE-4 file manager is installed, it will show up in this drop-down menu. If a specific application is compatible and valuable enough for a keyboard shortcut, it may be mapped to a keyboard sequence using the wayfire.ini configuration file. Wayfire also has a configuration tool named Wayfire Config Manager. It is located in the drop-down menu bar but may also be started through a terminal by issuing the following command:

    % wcm

Various Wayfire configuration options, including the composite special effects, maybe enabled, disabled, or configured through this application. In addition, for a more user-friendly experience, a background manager, panel, and docking application may be enabled in the configuration file:

    panel = wf-panel
    dock = wf-dock
    background = wf-background

| Changes made through `wcm` will overwrite custom changes in the wayfire.ini configuration file. The wayfire.ini file is highly recommended to be backed up so any essential changes may be restored.

Finally, the default launcher listed in the wayfire.ini is x11/wf-shell which may be replaced with other panels if desired by the user.

## 6.4. The Hikari Compositor

The Hikari compositor uses several concepts centered around productivity, such as sheets, workspaces, and more. In that way, it resembles a tiling window manager. Breaking this down, the compositor starts with a single workspace, which is similar to virtual desktops. Hikari uses a single workspace or virtual desktop for user interaction. The workspace is made up of several views, which are the working windows in the compositor grouped as either sheets or groups. Both sheets and groups are made up of a collection of views; again, the windows that are grouped together. When switching between sheets or groups, the active sheet or group will become known collectively as the workspace. The manual page will break this down into more information on the functions of each but for this document, just consider a single workspace utilizing a single sheet. Hikari installation will comprise of a single package, x11-wm/hikari, and a terminal emulator `alacritty`:

    # pkg install hikari alacritty

| Other shells, such as `kitty` or the Plasma `Terminal`, will function under Wayland. Users should experiment with their favorite terminal editor to validate compatibility.

Hikari uses a configuration file, hikari.conf, which could either be placed in the XDG_RUNTIME_DIR or specified on startup using the `-c` parameter. An autostart configuration file is not required but may make the migration to this compositor a little easier. Beginning the configuration is to create the Hikari configuration directory and copy over the configuration file for editing:

    % mkdir ~/.config/hikari
    % cp /usr/local/etc/hikari/hikari.conf ~/.config/hikari

The configuration is broken out into various stanzas such as ui, outputs, layouts, and more. For most users, the defaults will function fine; however, some important changes should be made. For example, the $TERMINAL variable is normally not set within the user’s environment. Changing this variable or altering the hikari.conf file to read:

    terminal = "/usr/local/bin/alacritty"

Will launch the `alacritty` terminal using the bound key press. While going through the configuration file, it should be noted that the capital letters are used to map keys out for the user. For example, the `L` key for starting the terminal `L`+`Return` is actually the previously discussed super key or Windows logo key. Therefore, holding the `L/super/Windows` key and pressing `Enter` will open the specified terminal emulator with the default configuration. Mapping other keys to applications require an action definition to be created. For this, the action item should be listed in the actions stanza, for example:

    actions {
      terminal = "/usr/local/bin/alacritty"
      browser = "/usr/local/bin/firefox"
    }

Then an action may be mapped under the keyboard stanza, which is defined within the bindings stanza:

    bindings {
      keyboard {
    SNIP
        "L+Return" = action-terminal
        "L+b" = action-browser
    SNIP

After Hikari is restarted, holding the Windows logo button and pressing the `b` key on the keyboard will start the web browser. The compositor does not have a menu bar, and it is recommended the user set up, at minimal, a terminal emulator before migration. The manual page contains a great deal of documentation it should be read before performing a full migration. Another positive aspect about Hikari is that, while migrating to the compositor, Hikari can be started in the Plasma and GNOME desktop environments, allowing for a test-drive before completely migrating.

Locking the screen in Hikari is easy because a default pam.d configuration file and unlock utility are bundled with the package. The key binding for locking the screen is `L` (Windows logo key)+ `Shift` + `Backspace`. It should be noted that all views not marked public will be hidden. These views will never accept input when locked but beware of sensitive information being visible. For some users, it may be easier to migrate to a different screen locking utility such as swaylock-effects, discussed in this section. To start Hikari, use the following command:

    % hikari -c ~/.config/hikari/hikari.conf

## 6.5. The Sway Compositor

The Sway compositor is a tiling compositor that attempts to replace the i3 windows manager. It should work with the user’s current i3 configuration; however, new features may require some additional setup.

Before starting the Sway installation, ensure that a graphics card (GPU) is installed and configured correctly. Refer to the section drivers for the graphics hardware for guidance. This step is essential for the Sway compositor to function properly.

In the forthcoming examples, a fresh installation without migrating any i3 configuration will be assumed. To install Sway and valuable components, issue the following command as the root user:

    # pkg install sway swayidle swaylock-effects alacritty dmenu-wayland dmenu

For a basic configuration file, issue the following commands and then edit the configuration file after it is copied:

    % mkdir ~/.config/sway
    % cp /usr/local/etc/sway/config ~/.config/sway

The base configuration file has many defaults, which will be fine for most users. Several important changes should be made like the following:

    # Logo key. Use Mod1 for Alt.
    input * xkb_rules evdev
    set $mod Mod4
    # The preferred terminal emulator
    set $term alacritty
    set $lock swaylock -f -c 000000
    output "My Workstation" mode 1366x768@60Hz position 1366 0
    output * bg ~/wallpapers/mywallpaper.png stretch
    ### Idle configuration
    exec swayidle -w \
              timeout 300 'swaylock -f -c 000000' \
              timeout 600 'swaymsg "output * dpms off"' resume 'swaymsg "output * dpms on"' \
              before-sleep 'swaylock -f -c 000000'

In the previous example, the `xkb` rules for evdev(4) events are loaded, and the $mod key is set to the Windows logo key for the key bindings. Next, the terminal emulator was set to be `alacritty`, and a screen lock command was defined; more on this later. The output keyword, the mode, the position, a background wallpaper, and Sway is also told to stretch this wallpaper to fill out the screen. Finally, `swayidle` is set to daemonize and lock the screen after a timeout of 300 seconds, placing the screen or monitor into sleep mode after 600 seconds. The locked background color of 000000, which is black, is also defined here. Using swaylock-effects, a clock may also be displayed with the `--clock` parameter. See the manual page for more options. The sway-output(5) manual page should also be reviewed; it includes a great deal of information on customing the output options available.

While in Sway, to bring up a menu of applications, hold the Windows logo key (mod) and press the `d` key. The menu may be navigated using the arrow keys on the keyboard. There is also a method to manipulate the layout of the bar and add a tray; read the sway-bar(5) manual page for more information. The default configuration adds a date and time to the upper right-hand corner. See the `Bar` stanza in the configuration file for an example. By default, the configuration does not include locking the screen outside of the example above, enabling a lockout timer. Creating a lock key binding requires the following line to the `Key bindings` section:

    # Lock the screen manually
    bindsym $mod+Shift+Return exec $lock

Now the screen may be locked using the combination of holding the Windows logo key, pressing and holding shift, and finally pressing return. When Sway is installed, whether from a package or the FreeBSD Ports Collection, a default file for pam.d was installed. The default configuration should be acceptable for most users, but more advanced options are available. Read through the PAM documentation for more information.

Finally, to exit Sway and return to the shell, hold the Windows logo key, the shift key, and press the `e` key. A prompt will be displayed with an option to exit Sway. During migration, Sway can be started through a terminal emulator on an X11 desktop such as Plasma. This makes testing different changes and key bindings a little easier prior to fully migrating to this compositor. To start Sway, issue the following command:

    % sway -c ~/.config/sway/config

## 6.6. Using Xwayland

When installing Wayland, the `Xwayland` binary should have been installed unless Wayland was built without X11 support. If the /usr/local/bin/Xwayland file does not exist, install it using the following command:

    # pkg install xwayland

| The development version of Xwayland is recommended and was most likely installed with the Wayland package. Each compositor has a method of enabling or disabling this feature.

Once `Xwayland` has been installed, configure it within the chosen compositor. For Wayfire, the following line is required in the wayfire.ini file:

    xwayland = true

For the Sway compositor, `Xwayland` should be enabled by default. Even so, it is recommended to manually add a configuration line in the ~/.config/sway/config like the following:

    xwayland enable

Finally, for Hikari, no changes are needed. Support for `Xwayland` is build in by default. To disable that support, rebuild the package from the ports collection and disable Xwayland support at that time.

After these changes are made, start the compositor at the command line and execute a terminal from the key bindings. Within this terminal, issue the `env` command and search for the `DISPLAY` variables. If the compositor was able to properly start the Xwayland X server, these environment variables should look similar to the following:

    % env | grep DISPLAY

    WAYLAND_DISPLAY=wayland-1
    DISPLAY=:0

In this output, there is a default Wayland display and a display set for the Xwayland server. Another method to verify that `Xwayland` is functioning properly is to use install and test the small package:[x11/eyes] and check the output. If the `xeyes` application starts and the eyes follow the mouse pointer, Xwayland is functioning properly. If an error such as the following is displayed, something happened during the `Xwayland` initialization and it may need reinstalled:

    Error: Cannot open display wayland-0

| A security feature of Wayland is that, without running an X server, there is not another network listener. Once `Xwayland` is enabled, this security feature is no longer applicable to the system.

For some compositors, such as Wayfire, `Xwayland` may not start properly. As such, `env` will show the following information for the `DISPLAY` environment variables:

    % env | grep DISPLAY

    DISPLAY=wayland-1
    WAYLAND_DISPLAY=wayland-1

Even though `Xwayfire` was installed and configured, X11 applications will not start giving a display issue. To work around this, verify that there is already an instance of `Xwayland` using a UNIX socket through these two methods. First, check the output from `sockstat` and search for X11-unix:

    % sockstat | grep x11

There should be something similar to the following information:

    trhodes  Xwayland   2734  8  stream /tmp/.X11-unix/X0
    trhodes  Xwayland   2734  9  stream /tmp/.X11-unix/X0
    trhodes  Xwayland   2734  10 stream /tmp/.X11-unix/X0
    trhodes  Xwayland   2734  27 stream /tmp/.X11-unix/X0_
    trhodes  Xwayland   2734  28 stream /tmp/.X11-unix/X0

This suggests the existence of an X11 socket. This can be further verified by attempting to execute `Xwayland` manually within a terminal emulator running under the compositor:

    % Xwayland

If an X11 socket is already available, the following error should be presented to the user:

    (EE)
    Fatal server error:
    (EE) Server is already active for display 0
    	If this server is no longer running, remove /tmp/.X0-lock
    	and start again.
    (EE)

Since there is an active X display available using display zero, the environment variable was just set improperly, to fix this, change the `DISPLAY` environment variable to `:0` and attempt to execute the application again. The following example uses mail/claws-mail as the application which needs the `Xwayland` service:

    export DISPLAY=:0

After this change, the mail/claws-mail application should now start using `Xwayland` and function as expected.

## 6.7. Remote Desktop Using VNC

Earlier in this document it was noted that Wayland does not provide the same X server style access as Xorg provides. Instead, users are free to pick and choose a remote desktop protocol such as RDP or VNC. The FreeBSD Ports collection includes the `wayvnc`, which will support wlroots based compositors such as the ones discussed here. This application may be installed using:

    # pkg install wayvnc

Unlike some other packages, `wayvnc` does not come with a configuration file. Thankfully, the manual page documents the important options and they may be extrapolated into a simple configuration file:

    address=0.0.0.0
    enable_auth=true
    username=username
    password=password
    private_key_file=/path/to/key.pem
    certificate_file=/path/to/cert.pem

The key files will need to be generated, and it is highly recommended they be used for increased security of the connection. When invoked, wayvnc will search for the configuration file in ~/.config/wayvnc/config. This could be overwritten using the `-C configuration_file` option when starting the server. Thus, to start the `wayvnc` server, issue the following command:

    % wayvnc -C ~/.config/wayvnc/config

| At the time of this writing, there is no rc.d script to start `wayvnc` on system initialization. If that functionality is desired, a local startup file will need to be created. This is probably a feature request for the port maintainer.

## 6.8. Wayland Login Manager

While several login managers exist and are slowly migrating to Wayland, one option is the x11/ly text user interface (TUI) manager. Needing minimal configuration, `ly` will start Sway, Wayfire, and others by presenting a login window on system initialization. To install `ly`, issue the following command:

    # pkg install ly

There will be some configuration hints presented, the import steps are to add the following lines to /etc/gettytab:

    Ly:\
      :lo=/usr/local/bin/ly:\
      :al=root:

And then modify the ttyv1 line in /etc/ttys to match the following line:

    ttyv1 "/usr/libexec/getty Ly" xterm onifexists secure

After a system reboot, a login should appear. To configure specific settings, such as language and edit /usr/local/etc/ly/config.ini. At minimal, this file should have the designated tty that was previously specified in /etc/ttys.

| If setting ttyv0 up as the login terminal, it may be required to press the `alt` and `F1` keys to properly see the login window.

When the login window appears, using the left and right arrows will swap through different, supported, window managers.

## 6.9. Useful Utilities

One useful Wayland utility which all compositors can make use of is the waybar. While Wayfire does come with a launch menu, an easy-to-use and fast taskbar is a good accessory for any compositor or desktop manager. A Wayland compatible taskbar that is fast and easy to configure is waybar. To install the package and a supporting audio control utility, issue the following command:

    # pkg install pavucontrol waybar

To create the configuration directory and copy over a default configuration file, execute the following commands:

    % mkdir ~/.config/waybar
    % cp /usr/local/etc/xdg/waybar/config ~/.config/waybar

The `lavalauncher` utility provides a launch bar for various applications. There is no example configuration file provided with the package, so the following actions must be taken:

    mkdir ~/.config/lavalauncher

An example configuration file that only includes Firefox, and is placed on the right, is below:

    global-settings {
    	watch-config-file = true;
    }

    bar {
    	output            = eDP-1;
    	position          = bottom;
    	background-colour = "#202020";

    	# Condition for the default configuration set.
    	condition-resolution = wider-than-high;

    	config {
    		position = right;
    	}

    	button {
    		image-path          =     /usr/local/lib/firefox/browser/chrome/icons/default/default48.png;
    		command[mouse-left] =     /usr/local/bin/firefox;
    	}
    	button {
    	  image-path           =   /usr/local/share/pixmaps/thunderbird.png;
    	  command[mouse-left]  =   /usr/local/bin/thunderbird;
    }

Last modified on: August 28, 2025 by Benedict Reuschling

Prev
Home
Next