diff --git a/documentation/content/en/books/handbook/x11/_index.adoc b/documentation/content/en/books/handbook/x11/_index.adoc index 316c82acab..5015d74bad 100644 --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -1622,3 +1622,649 @@ The most common would be: 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 does not include an X server; it is only a protocol that acts as an intermediary between clients. +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 managers that do not yet support Wayland will require that `Xwayland` is not started with the `-rootless` parameter to provide proper X server-style 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. + +[NOTE] +==== +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: +`ck-launch-session dbus-run-session startplasma-wayland` +to get it working. +==== + +For compositors, a kernel supporting the man:evdev[4] driver must exist to utilize the keybinding functionality. +This is built into the [.filename]#GENERIC kernel by default; however, if it has been customized and man:evdev[4] support was stripped out, the man: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: + +[source,shell] +---- +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 package:[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: + +[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=/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 [.filename]#~/.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. + +[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 `tmpfs` for the [.filename]#/var/run# directory. +In this case, the `tmpfs` file system is used for [.filename]#/var/run# and mounted through the command `mount -t tmpfs tmpfs /var/run` command and then make this change persist across reboots through [.filename]#/etc/fstab#. +The XDG_RUNTIME_DIR environment variable could be configured to use [.filename]#/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: + +[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`, 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: + +[source,shell] +---- +% 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: + +[.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. +nless 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 package:x11/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 -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 [.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, as of the time of this writing, has been abandoned. +This documentation will focus on using the lavalauncher package which will require the following changes in [.filename]#wayfire.ini#. +In this 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] +---- +% 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 [.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. +To start Hikari, use the following command: + +[source,shell] +---- +% hikari -c ~/.config/hikari/hikari.conf +---- + +=== 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/nvidia-driver[] should be used if possible, and even still, they may not be stable enough for end users. +Volunteers to help work on the NVidia DRM are requested. +=== + +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: + +[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 ~/.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: + +[.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 ck-launch-session '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. +To start Sway, issue the following command: + +[source,shell] +---- +% sway -c ~/.config/sway/config +---- + +=== Using Xwayland + +When installing Wayland, the package:x11-servers/xwayland-devel[] package should have also been installed. +If the [.filename]#/usr/local/bin/Xwayland# file does not exist, install it using the following command: + +[source,shell] +---- +# pkg install xwayland-devel +---- + +[NOTE] +==== +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 [.filename]#wayfire.ini# file: + +[.programlisting] +.... +xwayland = true +.... + +For the Sway compositor, `Xwayland` should be enabled by default. +Even so, it is recommened to manually add a configuration line in the [.filename]#~/.config/sway/config# like the following: + +[.programlisting] +..... +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: + +[source,shell] +---- +% env | grep DISPLAY +---- + +[.programlisting] +.... +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` intitialization and it may need reinstalled: + +[.programlisting] +.... +Error: Cannot open display wayland-0 +.... + +[WARNING] +==== +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: + +[source,shell] +---- +% env | grep DISPLAY +---- + +[.programlisting] +.... +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: + +[source,shell] +---- +% sockstat | grep x11 +---- + +There should be something similar to the following information: + +[.programlisting] +.... +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: + +[source,shell] +---- +% Xwayland +---- + +If an X11 socket is already available, the following error should be presented to the user: + +[.programlisting +.... +(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 package:mail/claws-mail[] as the application which needs the `Xwayland` service: + +[source,shell] +---- +export DISPLAY=:0 +---- + +After this change, the package:mail/claws-mail[] application should now start using `Xwayland` and function as expected. + +=== 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]#~/.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: + +[source,shell] +---- +% wayvnc -C ~/.config/wayvnc/config +---- + +[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. +==== + +=== Wayland Login Manager +While several login managers exist and are slowly migrating to Wayland, one option is the package: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: + +[source,shell] +---- +# pkg install ly +---- + +There will be some configuration hints presented, the import steps are to add the following lines to [.filename]#/etc/gettytab#: + +[programlisting] +.... +Ly:\ + :lo=/usr/local/bin/ly:\ + :al=root: +.... + +And then modify the ttyv1 line in [.filename]#/etc/ttys# to match the following line: + +[programlisting] +.... +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 [.filename]#/usr/local/etc/ly/config.ini#. +At minimal, this file should have the designated tty that was previously specified in [.filename]#/etc/ttys#. + +[NOTE] +==== +If setting ttyv0 up as the login terminal, it may be required to press the kbd:[alt] and kbd:[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. + + +=== 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: + +[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 ~/.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: + +[source,shell] +---- +mkdir ~/.config/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[mouse-left] = /usr/local/bin/firefox; + } + button { + image-path = /usr/local/share/pixmaps/thunderbird.png; + command[mouse-left] = /usr/local/bin/thunderbird; +} +....