diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -1622,3 +1622,324 @@ This is usually the case when you upgrade Xorg. You will need to reinstall the package:x11/nvidia-driver[] package so glx is built again. + +[[x-wayland]] +== Wayland on FreeBSD +Wayland is a new software for supporting desktops, but it differs from Xorg in several important ways. First, Wayland is not an X server; it is a protocol that acts as an intermediary between clients such as the X server and applications that run in the graphical environment. 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, it can manage composite communications as a completely separate entity that does not need to support the X protocols. The adage of doing one thing and do it well seems to be a primary goal of the developers. + +Wayland is relatively new, and not all software has been updated to fully utilize the feature set if it runs on Wayland at all. 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 is known as wayfire and the i3 window manager replacement, Sway. + +A kernel supporting the man:evdev[4] driver must exist to utilize the Wayland functionality. This is built into the [.filename]#GENERIC` kernel by default; however, if it has been customized and the man:evdev[4] support was stripped out, the man:evdev[4] module will need to be loaded. + +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. Everything was tested and known to function on an Intel graphics card; however, the NVidia graphics cards should work fine as long as the proper driver has been installed. Begin by installing the following packages + +[source,shell] +---- +# 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, which can be achieved with the following command in the bourne shell: + +[source,shell] +---- +% export XDG_RUNTIME_DIR=~/.config +---- + +It is important to note that if any compositor is configured in a virtual desktop, such as Plasma, the XDG_RUNTIME_DIR may be overridden by the desktop manager. For example, using Plasma with `sddm`, the XDG_RUNTIME_DIR will be modified, pointing to a directory in [.filename]#/var/run/user/$UID#. As such, migration to a compositor may run into issues when attempting to locate a configuration file or files needed for initialization. Consider this as changing this environment variable in the middle of running a desktop may either break currently running applications or cause temporary files to be created in the .config directory and linger until removed. + +[WARNING] +==== +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 [.filename]#/tmp#. In this case, the tmpfs file system is used for [.filename]#/tmp# and mounted through the command `mount -t tmpfs tmpfs /tmp` command and then make this change persist across reboots through [.filename]#/etc/fstab#. The XDG_RUNTIME_DIR environment variable could then be configured to use [.filename]#/tmp# and avoid potential pitfalls with ZFS. Consider that scenario when reviewing the configuration examples in the following sections. +==== + +The seatd daemon manages access to shared system devices for non-root users; this includes graphics cards. To enable and start the `seatd` daemon now, and on system initialization: + +[source,shell] +---- +# 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. + +=== 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: + +[source,shell] +---- +# pkg install wayfire 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`, Plasma `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: + +[source,shell] +---- +% cp /usr/local/share/examples/wayfire/wayfire.ini $XDG_RUNTIME_DIR/.config +---- + +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: + +[.programlisting] +.... +[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: + +[.programlisting] +.... +idle = swaylock +.... + +And the lock timeout is configured using the following lines: + +[.programlisting] +.... +[idle] +toggle = 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 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 kbd:[shift] key, and press the kbd:[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: + +[source,shell] +---- +% 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 swaylock-effects was installed, a default [.filename]#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: + +[source,shell] +---- +% wayfire +---- + +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 [.filename]#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: + +[source,shell] +---- +% 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: + +[.programlisting] +.... +panel = wf-panel +dock = wf-dock +background = wf-background +.... + +[WARNING] +==== +Changes made through `wcm` will overwrite custom changes in the [.filename]#wayfire.ini# configuration file. The [.filename]#wayfire.ini# file is highly recommended to be backed up so any essential changes may be restored. +==== + +Finally, the default launcher listed in the [.filename]#wayfire.ini# is `wofi`, which is not available on FreeBSD. This can be changed to any Wayland supporting launcher. The following line needs to be updated inside of [.filename]#wayfire.ini#. In this next example, the launcher has been changed to `lavalauncher`. An example configuration file for `lavalauncher` is available at the end of this section. + +[.programlisting] +.... +command_launcher = lavalauncher +.... + +=== 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, package:x11-wm/hikari[], and a terminal emulator `alacritty`: + +[source,shell] +---- +# pkg install hikari alacritty +---- + +[NOTE] +==== +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, [.filename]#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: + +[source,shell] +---- +% export XDG_RUNTIME_DIR=~/.config +% mkdir $XDG_RUNTIME_DIR/hikari +% cp /usr/local/etc/hikari/hikari.conf $XDG_RUNTIME_DIR/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 [.filename]#hikari.conf# file to read: + +[.programlisting] +.... +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 kbd:[L] key for starting the terminal kbd:[L+Return] is actually the previously discussed super key or Windows logo key. Therefore, holding the kbd:[L/super/Windows] key and pressing kbd:[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: + +[.programlisting] +.... +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: + +[.programlisting] +.... +bindings { + keyboard { +SNIP + "L+Return" = action-terminal + "L+b" = action-browser +SNIP +.... + +After Hikari is restarted, holding the Windows logo button and pressing the kbd:[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 [.filename]#pam.d# configuration file and unlock utility are bundled with the package. The key binding for locking the screen is kbd:[L] (Windows logo key)+ kbd:[Shift] + kbd:[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. + +=== The Sway Compositor + +[NOTE] +=== +The Sway window manager is not expected to work on propriety NVidia drivers. This is an upstream choice, so the package:x11-drivers/xf86-video-nv[] should be used if possible. +=== + +The Sway compositor is a tiling compositor that attempts to replace the i3 windows manager. It should work 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: + +[source,shell] +---- +# 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: + +[source,shell] +---- +% mkdir $XDG_RUNTIME_DIR/sway +% cp /usr/local/etc/sway/config $XDG_RUNTIME_DIR/sway +---- + +The base configuration file has many defaults, which will be fine for most users. Several important changes should be made like the following: + +[.programlisting] +.... +# Logo key. Use Mod1 for Alt. +input * xkb_rules evdev +set $mod Mod4 +# Your preferred terminal emulator +set $term alacritty +set $lock swaylock -f -c 000000 +output "My Workstation" mode 1366x786@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 man: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 man: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 kbd:[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 man: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: + +[.programlising] +.... +# 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 [.filename]#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 kbd:[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. + +=== 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: + +[source,shell] +---- +# 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: + +[.programlisting] +.... +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 [.filename]#$XDG_RUNTIME_DIR/wayvnc/config#. This could be overwritten using the `-C configuration_file` option when starting the server. + +[NOTE] +==== +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. +==== + +=== Useful Utilities + +One useful Wayland utility which all compositors can make use of is the waybar. While Wayfire does come with its 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: + +[source,shell] +---- +# pkg install pavucontrol waybar +---- + +To create the configuration directory and copy over a default configuration file, execute the following commands: + +[source,shell] +---- +% mkdir $XDG_RUNTIME_DIR/waybar +% cp /usr/local/etc/xdg/waybar/config $XDG_RUNTIME_DIR/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: + +[source,shell] +---- +mkdir $XDG_RUNTIME_DIR/lavalauncher +---- + +An example configuration file that only includes Firefox, and is placed on the right, is below: + +[.programlising] +.... +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 = /usr/local/bin/firefox; + } +} +....