diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 32. Advanced Networking +title: Chapter 33. Advanced Networking part: IV. Network Communication prev: books/handbook/firewalls next: books/handbook/partv @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 32 +:sectnumoffset: 33 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/book.adoc b/documentation/content/en/books/handbook/book.adoc --- a/documentation/content/en/books/handbook/book.adoc +++ b/documentation/content/en/books/handbook/book.adoc @@ -70,6 +70,8 @@ include::{chapters-path}x11/_index.adoc[leveloffset=+1] +include::{chapters-path}wayland/_index.adoc[leveloffset=+1] + // Section two include::{chapters-path}partii.adoc[] diff --git a/documentation/content/en/books/handbook/boot/_index.adoc b/documentation/content/en/books/handbook/boot/_index.adoc --- a/documentation/content/en/books/handbook/boot/_index.adoc +++ b/documentation/content/en/books/handbook/boot/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 13. The FreeBSD Booting Process +title: Chapter 14. The FreeBSD Booting Process part: Part III. System Administration prev: books/handbook/config next: books/handbook/security @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 13 +:sectnumoffset: 14 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 12. Configuration and Tuning +title: Chapter 13. Configuration and Tuning part: Part III. System Administration prev: books/handbook/partiii next: books/handbook/boot @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 12 +:sectnumoffset: 13 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 24. Updating and Upgrading FreeBSD +title: Chapter 25. Updating and Upgrading FreeBSD part: Part III. System Administration prev: books/handbook/l10n next: books/handbook/dtrace @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 24 +:sectnumoffset: 25 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/desktop/_index.adoc b/documentation/content/en/books/handbook/desktop/_index.adoc --- a/documentation/content/en/books/handbook/desktop/_index.adoc +++ b/documentation/content/en/books/handbook/desktop/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 6. Desktop Applications +title: Chapter 7. Desktop Applications part: Part II. Common Tasks prev: books/handbook/partii next: books/handbook/multimedia @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 6 +:sectnumoffset: 7 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/disks/_index.adoc b/documentation/content/en/books/handbook/disks/_index.adoc --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 18. Storage +title: Chapter 19. Storage part: Part III. System Administration prev: books/handbook/audit next: books/handbook/geom @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 18 +:sectnumoffset: 19 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/dtrace/_index.adoc b/documentation/content/en/books/handbook/dtrace/_index.adoc --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 25. DTrace +title: Chapter 26. DTrace part: Part III. System Administration prev: books/handbook/cutting-edge next: books/handbook/usb-device-mode @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 25 +:sectnumoffset: 26 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/filesystems/_index.adoc b/documentation/content/en/books/handbook/filesystems/_index.adoc --- a/documentation/content/en/books/handbook/filesystems/_index.adoc +++ b/documentation/content/en/books/handbook/filesystems/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 21. Other File Systems +title: Chapter 22. Other File Systems part: Part III. System Administration prev: books/handbook/zfs next: books/handbook/virtualization @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 21 +:sectnumoffset: 22 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/firewalls/_index.adoc b/documentation/content/en/books/handbook/firewalls/_index.adoc --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 31. Firewalls +title: Chapter 32. Firewalls part: IV. Network Communication prev: books/handbook/network-servers next: books/handbook/advanced-networking @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 31 +:sectnumoffset: 32 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/geom/_index.adoc b/documentation/content/en/books/handbook/geom/_index.adoc --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -1,5 +1,5 @@ --- -title: "Chapter 19. GEOM: Modular Disk Transformation Framework" +title: "Chapter 20. GEOM: Modular Disk Transformation Framework" part: Part III. System Administration prev: books/handbook/disks next: books/handbook/zfs @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 19 +:sectnumoffset: 20 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 15. Jails +title: Chapter 16. Jails part: Part III. System Administration prev: books/handbook/security next: books/handbook/mac @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 15 +:sectnumoffset: 16 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/kernelconfig/_index.adoc b/documentation/content/en/books/handbook/kernelconfig/_index.adoc --- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc +++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 8. Configuring the FreeBSD Kernel +title: Chapter 9. Configuring the FreeBSD Kernel part: Part II. Common Tasks prev: books/handbook/multimedia next: books/handbook/printing @@ -17,8 +17,8 @@ :toclevels: 1 :icons: font :sectnums: -:sectnumlevels: 6 -:sectnumoffset: 8 +:sectnumlevels: 9 +:sectnumoffset: 9 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/l10n/_index.adoc b/documentation/content/en/books/handbook/l10n/_index.adoc --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 23. Localization - i18n/L10n Usage and Setup +title: Chapter 24. Localization - i18n/L10n Usage and Setup part: Part III. System Administration prev: books/handbook/virtualization next: books/handbook/cutting-edge @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 23 +:sectnumoffset: 24 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/linuxemu/_index.adoc b/documentation/content/en/books/handbook/linuxemu/_index.adoc --- a/documentation/content/en/books/handbook/linuxemu/_index.adoc +++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 10. Linux Binary Compatibility +title: Chapter 11. Linux Binary Compatibility part: Part II. Common Tasks prev: books/handbook/printing next: books/handbook/wine @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 10 +:sectnumoffset: 11 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/mac/_index.adoc b/documentation/content/en/books/handbook/mac/_index.adoc --- a/documentation/content/en/books/handbook/mac/_index.adoc +++ b/documentation/content/en/books/handbook/mac/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 16. Mandatory Access Control +title: Chapter 17. Mandatory Access Control part: Part III. System Administration prev: books/handbook/jails next: books/handbook/audit @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 16 +:sectnumoffset: 17 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/mail/_index.adoc b/documentation/content/en/books/handbook/mail/_index.adoc --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 29. Electronic Mail +title: Chapter 30. Electronic Mail part: IV. Network Communication prev: books/handbook/ppp-and-slip next: books/handbook/network-servers @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 29 +:sectnumoffset: 30 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/multimedia/_index.adoc b/documentation/content/en/books/handbook/multimedia/_index.adoc --- a/documentation/content/en/books/handbook/multimedia/_index.adoc +++ b/documentation/content/en/books/handbook/multimedia/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 7. Multimedia +title: Chapter 8. Multimedia part: Part II. Common Tasks prev: books/handbook/desktop next: books/handbook/kernelconfig @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 7 +:sectnumoffset: 8 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/network-servers/_index.adoc b/documentation/content/en/books/handbook/network-servers/_index.adoc --- a/documentation/content/en/books/handbook/network-servers/_index.adoc +++ b/documentation/content/en/books/handbook/network-servers/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 30. Network Servers +title: Chapter 31. Network Servers part: IV. Network Communication prev: books/handbook/mail next: books/handbook/firewalls @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 30 +:sectnumoffset: 31 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc --- a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc +++ b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 28. PPP +title: Chapter 29. PPP part: IV. Network Communication prev: books/handbook/serialcomms next: books/handbook/mail @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 28 +:sectnumoffset: 29 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/printing/_index.adoc b/documentation/content/en/books/handbook/printing/_index.adoc --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 9. Printing +title: Chapter 10. Printing part: Part II. Common Tasks prev: books/handbook/kernelconfig next: books/handbook/linuxemu @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 9 +:sectnumoffset: 10 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/security/_index.adoc b/documentation/content/en/books/handbook/security/_index.adoc --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 14. Security +title: Chapter 15. Security part: Part III. System Administration prev: books/handbook/boot next: books/handbook/jails @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 14 +:sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc --- a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc +++ b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 26. USB Device Mode / USB OTG +title: Chapter 27. USB Device Mode / USB OTG part: Part III. System Administration prev: books/handbook/dtrace next: books/handbook/partiv @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 26 +:sectnumoffset: 27 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/virtualization/_index.adoc b/documentation/content/en/books/handbook/virtualization/_index.adoc --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 22. Virtualization +title: Chapter 23. Virtualization part: Part III. System Administration prev: books/handbook/filesystems next: books/handbook/l10n @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 22 +:sectnumoffset: 23 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/wine/_index.adoc b/documentation/content/en/books/handbook/wine/_index.adoc --- a/documentation/content/en/books/handbook/wine/_index.adoc +++ b/documentation/content/en/books/handbook/wine/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 11. WINE +title: Chapter 12. WINE part: Part II. Common Tasks prev: books/handbook/linuxemu next: books/handbook/partiii @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 11 +:sectnumoffset: 12 :partnums: :source-highlighter: rouge :experimental: 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 @@ -1640,641 +1640,3 @@ 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 graphical user interfaces, 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. - -[NOTE] -==== -The current NVidia driver should work with most wl-roots 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. - -[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 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: - -[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 package:x11/wf-shell[] which may be replaced with other panels if desired by the user. - -=== 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 - -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 '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 `Xwayland` binary should have been installed unless Wayland was built without X11 support. -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; -} -.... diff --git a/documentation/content/en/books/handbook/zfs/_index.adoc b/documentation/content/en/books/handbook/zfs/_index.adoc --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -1,5 +1,5 @@ --- -title: Chapter 20. The Z File System (ZFS) +title: Chapter 21. The Z File System (ZFS) part: Part III. System Administration prev: books/handbook/geom next: books/handbook/filesystems @@ -18,7 +18,7 @@ :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 20 +:sectnumoffset: 21 :partnums: :source-highlighter: rouge :experimental: diff --git a/handbook/wayland/_index.adoc b/handbook/wayland/_index.adoc --- /dev/null +++ b/handbook/wayland/_index.adoc @@ -0,0 +1,693 @@ +--- +title: Chapter 6. Wayland +part: Part I. Getting Started +prev: books/handbook/ports +next: books/handbook/partii +description: This chapter describes how to install and configure Wayland and compositors on FreeBSD, which provides a graphical user environment +tags: ["Wayland", "XWayland", "KDE", "Plasma", "Xfce", "Gnome", "Intel", "AMD", "NVIDIA", "Wayfire", "Sway", "Hikari"] +showBookMenu: true +weight: 7 +path: "/books/handbook/" +--- + +[[wayland]] += Wayland on FreeBSD +:doctype: book +:toc: macro +:toclevels: 1 +:icons: font +:sectnums: +:sectnumlevels: 6 +:sectnumoffset: 6 +:partnums: +:source-highlighter: rouge +:experimental: +:images-path: books/handbook/wayland/ + +ifdef::env-beastie[] +ifdef::backend-html5[] +:imagesdir: ../../../../images/{images-path} +endif::[] +ifndef::book[] +include::shared/authors.adoc[] +include::shared/mirrors.adoc[] +include::shared/releases.adoc[] +include::shared/attributes/attributes-{{% lang %}}.adoc[] +include::shared/{{% lang %}}/teams.adoc[] +include::shared/{{% lang %}}/mailing-lists.adoc[] +include::shared/{{% lang %}}/urls.adoc[] +toc::[] +endif::[] +ifdef::backend-pdf,backend-epub3[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] +endif::[] + +ifndef::env-beastie[] +toc::[] +include::../../../../../shared/asciidoctor.adoc[] +endif::[] + +[[wayland-synopsis]] +== Wayland Synopsis +Wayland is a new software for supporting graphical user interfaces, 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. + +[NOTE] +==== +The current NVidia driver should work with most wl-roots 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. + +[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. + +[[wayland-wayfire]] +== 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 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: + +[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 package:x11/wf-shell[] which may be replaced with other panels if desired by the user. + +[[wayland-hikari]] +== 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 +---- + +[[wayland-sway]] +== 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. +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 '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 +---- + +[[wayland-xwayland]] +== Using Xwayland + +When installing Wayland, the `Xwayland` binary should have been installed unless Wayland was built without X11 support. +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. + +[[wayland-remotedesktop]] +== 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-ly]] +== 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. + +[[wayland-utilities]] +== 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; +} +....