Chapter 6. Wayland

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, you should:

After reading this chapter, you will know:

Wayland is a new display server, but it differs from Xorg in several important ways. First, Wayland is only a protocol that acts as an intermediary between clients using a different mechanism which removes the dependency on an X server. Xorg includes both the X11 protocol, used to run remote displays and the X server will 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.

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.

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:

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:

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:

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.

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:

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.

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:

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:

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:

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:

And the lock timeout is configured using the following lines:

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:

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:

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:

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:

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.

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:

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:

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:

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:

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

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:

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. 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:

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

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

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, swaylock 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:

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:

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:

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

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:

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:

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:

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

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:

There should be something similar to the following information:

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:

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

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:

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

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:

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:

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:

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:

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

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

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.

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

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:

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

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:

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