diff options
40 files changed, 791 insertions, 731 deletions
diff --git a/documentation/content/en/books/handbook/advanced-networking/_index.adoc b/documentation/content/en/books/handbook/advanced-networking/_index.adoc index a966aabcf8..08bc6af194 100644 --- a/documentation/content/en/books/handbook/advanced-networking/_index.adoc +++ b/documentation/content/en/books/handbook/advanced-networking/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 32. Advanced Networking +title: Chapter 33. Advanced Networking part: IV. Network Communication prev: books/handbook/firewalls next: books/handbook/partv description: "Advanced networking in FreeBSD: basics of gateways and routes, CARP, how to configure multiple VLANs on FreeBSD, etc" tags: ["Advanced Networking", "Handbook", "gateway", "routes", "wireless", "tethering", "bluetooth", "bridging", "ipv6", "CARP", "VLAN"] showBookMenu: true -weight: 37 +weight: 38 path: "/books/handbook/" aliases: ["/en/books/handbook/network-routing/","/en/books/handbook/network-wireless/","/en/books/handbook/network-usb-tethering/","/en/books/handbook/network-bluetooth/","/en/books/handbook/network-bridging/","/en/books/handbook/network-aggregation/","/en/books/handbook/network-diskless/","/en/books/handbook/network-ipv6/","/en/books/handbook/carp/","/en/books/handbook/network-vlan/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/network-routing/","/en/books/handbook/network-wire :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 32 +:sectnumoffset: 33 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/audit/_index.adoc b/documentation/content/en/books/handbook/audit/_index.adoc index 3fe0aa79d2..a0cd834008 100644 --- a/documentation/content/en/books/handbook/audit/_index.adoc +++ b/documentation/content/en/books/handbook/audit/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 17. Security Event Auditing +title: Chapter 18. Security Event Auditing part: Part III. System Administration prev: books/handbook/mac next: books/handbook/disks description: FreeBSD security event auditing supports reliable, fine-grained, and configurable logging of a variety of security-relevant system events, including logins, configuration changes, and file and network access tags: ["audit", "terms", "configuration", "guide", "audit trails"] showBookMenu: true -weight: 21 +weight: 22 path: "/books/handbook/" aliases: ["/en/books/handbook/audit-inline-glossary/","/en/books/handbook/audit-config/","/en/books/handbook/audit-administration/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/audit-inline-glossary/","/en/books/handbook/audit- :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 17 +:sectnumoffset: 18 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/bibliography/_index.adoc b/documentation/content/en/books/handbook/bibliography/_index.adoc index fcdb2ef741..66af09677b 100644 --- a/documentation/content/en/books/handbook/bibliography/_index.adoc +++ b/documentation/content/en/books/handbook/bibliography/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/eresources description: FreeBSD Handbook Bibliography tags: ["appendix", "bibliography", "handbook", "books", "guides", "security", "periodicals", "journals", "magazines"] showBookMenu: true -weight: 40 +weight: 41 path: "/books/handbook/" aliases: ["/en/books/handbook/bibliography-userguides/","/en/books/handbook/bibliography-adminguides/","/en/books/handbook/bibliography-programmers/","/en/books/handbook/bibliography-osinternals/","/en/books/handbook/bibliography-security/","/en/books/handbook/bibliography-hardware/","/en/books/handbook/bibliography-history/","/en/books/handbook/bibliography-journals/"] --- diff --git a/documentation/content/en/books/handbook/book.adoc b/documentation/content/en/books/handbook/book.adoc index 48e624eb9c..3b27da0223 100644 --- a/documentation/content/en/books/handbook/book.adoc +++ b/documentation/content/en/books/handbook/book.adoc @@ -70,6 +70,8 @@ include::{chapters-path}ports/_index.adoc[leveloffset=+1] 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 index d7c161b3eb..58069f900b 100644 --- a/documentation/content/en/books/handbook/boot/_index.adoc +++ b/documentation/content/en/books/handbook/boot/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: An introduction to the FreeBSD Booting Process, demonstrates how to customize the FreeBSD boot process, including everything that happens until the FreeBSD kernel has started, probed for devices, and started init tags: ["boot", "boot process", "device hints", "x86", "amd64", "MBR", "GPT", "UEFI", "bsdlabel", "boot0", "Single-User Mode", "Multi-User Mode"] showBookMenu: true -weight: 17 +weight: 18 path: "/books/handbook/" aliases: ["/en/books/handbook/boot-introduction/","/en/books/handbook/boot-splash/","/en/books/handbook/device-hints/","/en/books/handbook/boot-shutdown/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/boot-introduction/","/en/books/handbook/boot-splas :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 13 +:sectnumoffset: 14 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/colophon.adoc b/documentation/content/en/books/handbook/colophon.adoc index 576df53fd4..877cdd0a7c 100644 --- a/documentation/content/en/books/handbook/colophon.adoc +++ b/documentation/content/en/books/handbook/colophon.adoc @@ -3,7 +3,7 @@ title: Colophon prev: books/handbook/glossary description: FreeBSD Handbook Colophon showBookMenu: true -weight: 44 +weight: 45 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc index 41f7a54660..be1b87125f 100644 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: This chapter explains much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system. tags: ["configuration", "tuning", "services", "cron", "virtual hosts", "logging", "configuration files", "sysctl", "tuning disks", "kernel limits", "swap", "power management"] showBookMenu: true -weight: 16 +weight: 17 path: "/books/handbook/" aliases: ["/en/books/handbook/configtuning-starting-services/","/en/books/handbook/configtuning-cron/","/en/books/handbook/configtuning-rcd/","/en/books/handbook/config-network-setup/","/en/books/handbook/configtuning-virtual-hosts/","/en/books/handbook/configtuning-syslog/","/en/books/handbook/configtuning-configfiles/","/en/books/handbook/configtuning-sysctl/","/en/books/handbook/configtuning-disk/","/en/books/handbook/configtuning-kernel-limits/","/en/books/handbook/adding-swap-space/","/en/books/handbook/acpi-overview/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/configtuning-starting-services/","/en/books/handbo :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 index 6d122c2ae7..7ad3692bc1 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: Information about how to keep a FreeBSD system up-to-date with freebsd-update or Git, how to rebuild and reinstall the entire base system, etc tags: ["updating", "upgrading", "documentation", "FreeBSD-STABLE", "FreeBSD-CURRENT", "Security Patches"] showBookMenu: true -weight: 28 +weight: 29 path: "/books/handbook/" aliases: ["/en/books/handbook/updating-upgrading-freebsdupdate/","/en/books/handbook/updating-upgrading-documentation/","/en/books/handbook/current-stable/","/en/books/handbook/makeworld/","/en/books/handbook/small-lan/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/updating-upgrading-freebsdupdate/","/en/books/hand :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 index 9a3c59cc21..09b108ac25 100644 --- a/documentation/content/en/books/handbook/desktop/_index.adoc +++ b/documentation/content/en/books/handbook/desktop/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 6. Desktop Applications +title: Chapter 7. Desktop Applications part: Part II. Common Tasks prev: books/handbook/partii next: books/handbook/multimedia description: This chapter demonstrates how to install numerous desktop applications, including web browsers, productivity software, document viewers, and financial software tags: ["desktop", "browsers", "firefox", "chromium", "productivity", "calligra", "AbiWord", "LibreOffice", "GIMP", "Xpdf", "gv", "Geeqie", "ePDFView", "okular", "Finance", "GnuCash", "Gnumeric", "KMyMoney"] showBookMenu: true -weight: 9 +weight: 10 path: "/books/handbook/" aliases: ["/en/books/handbook/desktop-browsers/","/en/books/handbook/desktop-productivity/","/en/books/handbook/desktop-viewers/","/en/books/handbook/desktop-finance/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/desktop-browsers/","/en/books/handbook/desktop-pro :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 index 6c8e1a1fbe..a81e915556 100644 --- a/documentation/content/en/books/handbook/disks/_index.adoc +++ b/documentation/content/en/books/handbook/disks/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 18. Storage +title: Chapter 19. Storage part: Part III. System Administration prev: books/handbook/audit next: books/handbook/geom description: This chapter covers the use of disks and storage media in FreeBSD. This includes SCSI and IDE disks, CD and DVD media, memory-backed disks, and USB storage devices. tags: ["storage", "disks", "gpart", "mount", "quotas", "encrypt", "GPT", "cdrecord", "NTFS", "quotas", "swap", "HAST", "CD", "DVD", "resizing", "growing"] showBookMenu: true -weight: 22 +weight: 23 path: "/books/handbook/" aliases: ["/en/books/handbook/disks-adding/","/en/books/handbook/disks-growing/","/en/books/handbook/usb-disks/","/en/books/handbook/creating-cds/","/en/books/handbook/creating-dvds/","/en/books/handbook/floppies/","/en/books/handbook/backup-basics/","/en/books/handbook/disks-virtual/","/en/books/handbook/snapshots/","/en/books/handbook/quotas/","/en/books/handbook/disks-encrypting/","/en/books/handbook/swap-encrypting/","/en/books/handbook/disks-hast/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/disks-adding/","/en/books/handbook/disks-growing/" :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 index b0b64eae67..d4d32250c8 100644 --- a/documentation/content/en/books/handbook/dtrace/_index.adoc +++ b/documentation/content/en/books/handbook/dtrace/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 25. DTrace +title: Chapter 26. DTrace part: Part III. System Administration prev: books/handbook/cutting-edge next: books/handbook/usb-device-mode description: This chapter explains how to use DTrace in FreeBSD tags: ["DTrace", "features", "guide", "tutorial", "kldload"] showBookMenu: true -weight: 29 +weight: 30 path: "/books/handbook/" aliases: ["/en/books/handbook/dtrace-implementation/","/en/books/handbook/dtrace-enable/","/en/books/handbook/dtrace-using/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/dtrace-implementation/","/en/books/handbook/dtrace :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 25 +:sectnumoffset: 26 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/eresources/_index.adoc b/documentation/content/en/books/handbook/eresources/_index.adoc index 242430a65f..569086c609 100644 --- a/documentation/content/en/books/handbook/eresources/_index.adoc +++ b/documentation/content/en/books/handbook/eresources/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/pgpkeys description: FreeBSD additional resources on internet like websites, mailing lists, mirrors, etc tags: ["eresources", "Websites", "Mailing Lists", "Usenet", "Newsgroups"] showBookMenu: true -weight: 41 +weight: 42 path: "/books/handbook/" aliases: ["/en/books/handbook/eresources-mail/","/en/books/handbook/eresources-news/","/en/books/handbook/eresources-web/"] --- diff --git a/documentation/content/en/books/handbook/filesystems/_index.adoc b/documentation/content/en/books/handbook/filesystems/_index.adoc index 7bd7cc8e8b..20f67375db 100644 --- a/documentation/content/en/books/handbook/filesystems/_index.adoc +++ b/documentation/content/en/books/handbook/filesystems/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: This chapter shows the other filesystems supported by FreeBSD tags: ["filesystem", "ext2", "ext3", "ext4", "ext2fs"] showBookMenu: true -weight: 25 +weight: 26 path: "/books/handbook/" aliases: ["/en/books/handbook/filesystems-linux/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/filesystems-linux/"] :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 index 5def3126ee..99d8a50ed6 100644 --- a/documentation/content/en/books/handbook/firewalls/_index.adoc +++ b/documentation/content/en/books/handbook/firewalls/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 31. Firewalls +title: Chapter 32. Firewalls part: IV. Network Communication prev: books/handbook/network-servers next: books/handbook/advanced-networking description: "FreeBSD has three firewalls built into the base system: PF, IPFW, and IPFILTER. This chapter covers how to define packet filtering rules, the differences between the firewalls built into FreeBSD and how to use them" tags: ["firewall", "pf", "ipfw", "ipfilter", "blacklistd", "filtering"] showBookMenu: true -weight: 36 +weight: 37 path: "/books/handbook/" aliases: ["/en/books/handbook/firewalls-concepts/","/en/books/handbook/firewalls-pf/","/en/books/handbook/firewalls-ipfw/","/en/books/handbook/firewalls-ipf/","/en/books/handbook/firewalls-blacklistd/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/firewalls-concepts/","/en/books/handbook/firewalls :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 index 00156eeeba..f58cb82b66 100644 --- a/documentation/content/en/books/handbook/geom/_index.adoc +++ b/documentation/content/en/books/handbook/geom/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: In FreeBSD, the GEOM framework permits access and control to classes, such as Master Boot Records and BSD labels, through the use of providers, or the disk devices in /dev. tags: ["GEOM", "RAID", "RAID0", "RAID1", "RAID3", "Striping", "bsdlabel", "newfs", "labelling", "UFS", "journaling"] showBookMenu: true -weight: 23 +weight: 24 path: "/books/handbook/" aliases: ["/en/books/handbook/geom-striping/","/en/books/handbook/geom-mirror/","/en/books/handbook/geom-raid3/","/en/books/handbook/geom-graid/","/en/books/handbook/geom-ggate/","/en/books/handbook/geom-glabel/","/en/books/handbook/geom-gjournal/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/geom-striping/","/en/books/handbook/geom-mirror/", :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 19 +:sectnumoffset: 20 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/glossary.adoc b/documentation/content/en/books/handbook/glossary.adoc index b6fab1a47f..745929f36b 100644 --- a/documentation/content/en/books/handbook/glossary.adoc +++ b/documentation/content/en/books/handbook/glossary.adoc @@ -4,7 +4,7 @@ prev: books/handbook/pgpkeys next: books/handbook/colophon description: FreeBSD Handbook Glossary showBookMenu: true -weight: 43 +weight: 44 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/jails/_index.adoc b/documentation/content/en/books/handbook/jails/_index.adoc index 5b2d469e0b..fea4c5fd0f 100644 --- a/documentation/content/en/books/handbook/jails/_index.adoc +++ b/documentation/content/en/books/handbook/jails/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 15. Jails +title: Chapter 16. Jails part: Part III. System Administration prev: books/handbook/security next: books/handbook/mac description: Jails improve on the concept of the traditional chroot environment in several ways tags: ["jails", "creating", "managing", "updating", "ezjail"] showBookMenu: true -weight: 19 +weight: 20 path: "/books/handbook/" aliases: ["/en/books/handbook/jails-terms/","/en/books/handbook/jails-build/","/en/books/handbook/jails-tuning/","/en/books/handbook/jails-application/","/en/books/handbook/jails-ezjail/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/jails-terms/","/en/books/handbook/jails-build/","/ :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 index 9d60e80b12..a16db8cd37 100644 --- a/documentation/content/en/books/handbook/kernelconfig/_index.adoc +++ b/documentation/content/en/books/handbook/kernelconfig/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: This chapter covers how to configure the FreeBSD Kernel. When to build a custom kernel, how to take a hardware inventory, how to customize a kernel configuration file, etc tags: ["configuring", "kernel", "custom kernel", "hardware requirements", "pciconf"] showBookMenu: true -weight: 11 +weight: 12 path: "/books/handbook/" aliases: ["/en/books/handbook/kernelconfig-custom-kernel/","/en/books/handbook/kernelconfig-devices/","/en/books/handbook/kernelconfig-config/","/en/books/handbook/kernelconfig-building/","/en/books/handbook/kernelconfig-trouble/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/kernelconfig-custom-kernel/","/en/books/handbook/k :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 8 +: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 index 3c9fd677de..63defa74d0 100644 --- a/documentation/content/en/books/handbook/l10n/_index.adoc +++ b/documentation/content/en/books/handbook/l10n/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: FreeBSD supports localization into many languages, allowing users to view, input, or process data in non-English languages tags: ["i18n", "L10n", "localization", "Locale", "LANG", "MM_CHARSET", "cap_mkdb"] showBookMenu: true -weight: 27 +weight: 28 path: "/books/handbook/" aliases: ["/en/books/handbook/using-localization/","/en/books/handbook/l10n-compiling/","/en/books/handbook/lang-setup/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/using-localization/","/en/books/handbook/l10n-comp :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 index abc5018877..a420ef75e8 100644 --- a/documentation/content/en/books/handbook/linuxemu/_index.adoc +++ b/documentation/content/en/books/handbook/linuxemu/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: FreeBSD provides binary compatibility with Linux, allowing users to install and run most Linux binaries on a FreeBSD system without having to first modify the binary tags: ["linux", "linuxulator", "emulation", "binary", "compatibility"] showBookMenu: true -weight: 13 +weight: 14 path: "/books/handbook/" aliases: ["/en/books/handbook/linuxemu-lbc-install/","/en/books/handbook/linuxemu-advanced/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/linuxemu-lbc-install/","/en/books/handbook/linuxem :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 index f9c038505e..549ee7989e 100644 --- a/documentation/content/en/books/handbook/mac/_index.adoc +++ b/documentation/content/en/books/handbook/mac/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: "This chapter focuses on the MAC framework and the set of pluggable security policy modules FreeBSD provides for enabling various security mechanisms" tags: ["MAC", "labels", "security", "configuration", "nagios"] showBookMenu: true -weight: 20 +weight: 21 path: "/books/handbook/" aliases: ["/en/books/handbook/mac-inline-glossary/","/en/books/handbook/mac-understandlabel/","/en/books/handbook/mac-planning/","/en/books/handbook/mac-policies/","/en/books/handbook/mac-userlocked/","/en/books/handbook/mac-implementing/","/en/books/handbook/mac-troubleshoot/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/mac-inline-glossary/","/en/books/handbook/mac-unde :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 index 9f4fd08ab9..0c7563255f 100644 --- a/documentation/content/en/books/handbook/mail/_index.adoc +++ b/documentation/content/en/books/handbook/mail/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: This chapter provides a basic introduction to running a mail server on FreeBSD, as well as an introduction to sending and receiving email using FreeBSD tags: ["mail", "sendmail", "MTA", "SMTP", "user agents", "fetchmail", "procmail", "alpine", "mut"] showBookMenu: true -weight: 34 +weight: 35 path: "/books/handbook/" aliases: ["/en/books/handbook/mail-using/","/en/books/handbook/sendmail/","/en/books/handbook/mail-changingmta/","/en/books/handbook/mail-trouble/","/en/books/handbook/mail-advanced/","/en/books/handbook/outgoing-only/","/en/books/handbook/SMTP-dialup/","/en/books/handbook/SMTP-Auth/","/en/books/handbook/mail-agents/","/en/books/handbook/mail-fetchmail/","/en/books/handbook/mail-procmail/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/mail-using/","/en/books/handbook/sendmail/","/en/b :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 29 +:sectnumoffset: 30 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/mirrors/_index.adoc b/documentation/content/en/books/handbook/mirrors/_index.adoc index 34a866c3b1..56f81269bd 100644 --- a/documentation/content/en/books/handbook/mirrors/_index.adoc +++ b/documentation/content/en/books/handbook/mirrors/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/bibliography description: "How to get FreeBSD: CD and DVD sets, FTP sites and how to install and use Git" tags: ["Obtaining", "CD", "DVD", "FTP", "Git"] showBookMenu: true -weight: 39 +weight: 40 path: "/books/handbook/" aliases: ["/en/books/handbook/mirrors-ftp/","/en/books/handbook/svn/","/en/books/handbook/mirrors-rsync/"] --- diff --git a/documentation/content/en/books/handbook/multimedia/_index.adoc b/documentation/content/en/books/handbook/multimedia/_index.adoc index d9c3d90eca..17fffb9ea4 100644 --- a/documentation/content/en/books/handbook/multimedia/_index.adoc +++ b/documentation/content/en/books/handbook/multimedia/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 7. Multimedia +title: Chapter 8. Multimedia part: Part II. Common Tasks prev: books/handbook/desktop next: books/handbook/kernelconfig description: FreeBSD supports a wide variety of sound cards, allowing users to enjoy high fidelity output from a FreeBSD system tags: ["multimedia", "sound card", "MP3", "MythTV", "scanner", "SANE"] showBookMenu: true -weight: 10 +weight: 11 path: "/books/handbook/" aliases: ["/en/books/handbook/sound-setup/","/en/books/handbook/sound-mp3/","/en/books/handbook/video-playback/","/en/books/handbook/tvcard/","/en/books/handbook/mythtv/","/en/books/handbook/scanners/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/sound-setup/","/en/books/handbook/sound-mp3/","/en :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 index 0b405b4562..8e63d6c90b 100644 --- a/documentation/content/en/books/handbook/network-servers/_index.adoc +++ b/documentation/content/en/books/handbook/network-servers/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 30. Network Servers +title: Chapter 31. Network Servers part: IV. Network Communication prev: books/handbook/mail next: books/handbook/firewalls description: This chapter covers some of the more frequently used network services on UNIX systems tags: ["network", "servers", "inetd", "NFS", "NIS", "LDAP", "DHCP", "DNS", "Apache HTTP", "FTP", "Samba", "NTP", "iSCSI"] showBookMenu: true -weight: 35 +weight: 36 path: "/books/handbook/" aliases: ["/en/books/handbook/network-inetd/","/en/books/handbook/network-nfs/","/en/books/handbook/network-nis/","/en/books/handbook/network-ldap/","/en/books/handbook/network-dhcp/","/en/books/handbook/network-dns/","/en/books/handbook/network-apache/","/en/books/handbook/network-ftp/","/en/books/handbook/network-samba/","/en/books/handbook/network-ntp/","/en/books/handbook/network-iscsi/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/network-inetd/","/en/books/handbook/network-nfs/", :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 30 +:sectnumoffset: 31 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/partii.adoc b/documentation/content/en/books/handbook/partii.adoc index 2558af057a..4d2526bb5d 100644 --- a/documentation/content/en/books/handbook/partii.adoc +++ b/documentation/content/en/books/handbook/partii.adoc @@ -1,9 +1,9 @@ --- title: Part II. Common Tasks -prev: books/handbook/x11 +prev: books/handbook/wayland next: books/handbook/desktop showBookMenu: true -weight: 8 +weight: 9 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partiii.adoc b/documentation/content/en/books/handbook/partiii.adoc index a2277e833f..77b0b12f0e 100644 --- a/documentation/content/en/books/handbook/partiii.adoc +++ b/documentation/content/en/books/handbook/partiii.adoc @@ -3,7 +3,7 @@ title: Part III. System Administration prev: books/handbook/linuxemu next: books/handbook/config showBookMenu: true -weight: 15 +weight: 16 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partiv.adoc b/documentation/content/en/books/handbook/partiv.adoc index 82ca5a561d..5ccdb202c5 100644 --- a/documentation/content/en/books/handbook/partiv.adoc +++ b/documentation/content/en/books/handbook/partiv.adoc @@ -3,7 +3,7 @@ title: Part IV. Network Communication prev: books/handbook/usb-device-mode next: books/handbook/serialcomms showBookMenu: true -weight: 31 +weight: 32 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/partv.adoc b/documentation/content/en/books/handbook/partv.adoc index 9bd4e82b40..bc547b0e86 100644 --- a/documentation/content/en/books/handbook/partv.adoc +++ b/documentation/content/en/books/handbook/partv.adoc @@ -3,7 +3,7 @@ title: Part V. Appendices prev: books/handbook/advanced-networking next: books/handbook/mirrors showBookMenu: true -weight: 38 +weight: 39 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/pgpkeys/_index.adoc b/documentation/content/en/books/handbook/pgpkeys/_index.adoc index a28e097bdc..3b5bbdde39 100644 --- a/documentation/content/en/books/handbook/pgpkeys/_index.adoc +++ b/documentation/content/en/books/handbook/pgpkeys/_index.adoc @@ -6,7 +6,7 @@ next: books/handbook/glossary description: List of OpenPGP keys of the FreeBSD officers are shown here tags: ["OpenGPG", "keys", "officers"] showBookMenu: true -weight: 42 +weight: 43 path: "/books/handbook/" --- diff --git a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc index 5cbeb6c645..a59b5786ef 100644 --- a/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc +++ b/documentation/content/en/books/handbook/ppp-and-slip/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 28. PPP +title: Chapter 29. PPP part: IV. Network Communication prev: books/handbook/serialcomms next: books/handbook/mail description: FreeBSD supports the Point-to-Point (PPP) protocol which can be used to establish a network or Internet connection using a dial-up modem tags: ["PPP", "PPPoE", "PPPoA", "modem"] showBookMenu: true -weight: 33 +weight: 34 path: "/books/handbook/" aliases: ["/en/books/handbook/userppp/","/en/books/handbook/ppp-troubleshoot/","/en/books/handbook/pppoe/","/en/books/handbook/pppoa/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/userppp/","/en/books/handbook/ppp-troubleshoot/"," :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 index 9ca74bf04b..e69a8d6863 100644 --- a/documentation/content/en/books/handbook/printing/_index.adoc +++ b/documentation/content/en/books/handbook/printing/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 9. Printing +title: Chapter 10. Printing part: Part II. Common Tasks prev: books/handbook/kernelconfig next: books/handbook/linuxemu description: This chapter covers the printing system in FreeBSD tags: ["printing", "CUPS", "LPD", "PostScript", "PDLs", "HPLIP", "LPRng"] showBookMenu: true -weight: 12 +weight: 13 path: "/books/handbook/" aliases: ["/en/books/handbook/printing-connections/","/en/books/handbook/printing-pdls/","/en/books/handbook/printing-direct/","/en/books/handbook/printing-lpd/","/en/books/handbook/printing-other/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/printing-connections/","/en/books/handbook/printin :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 index d700fd0565..c4c5d44506 100644 --- a/documentation/content/en/books/handbook/security/_index.adoc +++ b/documentation/content/en/books/handbook/security/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 14. Security +title: Chapter 15. Security part: Part III. System Administration prev: books/handbook/boot next: books/handbook/jails description: Hundreds of standard practices have been authored about how to secure systems and networks, and as a user of FreeBSD, understanding how to protect against attacks and intruders is a must tags: ["security", "one-time passwords", "TCP Wrapper", "Kerberos", "OpenSSL", "IPsec", "OpenSSH", "ACL", "advisories", "sudo", "doas", "monitoring"] showBookMenu: true -weight: 18 +weight: 19 path: "/books/handbook/" aliases: ["/en/books/handbook/security-intro/","/en/books/handbook/one-time-passwords/","/en/books/handbook/tcpwrappers/","/en/books/handbook/kerberos5/","/en/books/handbook/openssl/","/en/books/handbook/ipsec/","/en/books/handbook/openssh/","/en/books/handbook/fs-acl/","/en/books/handbook/security-pkg/","/en/books/handbook/security-advisories/","/en/books/handbook/security-accounting/","/en/books/handbook/security-resourcelimits/","/en/books/handbook/security-sudo/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/security-intro/","/en/books/handbook/one-time-pass :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 14 +:sectnumoffset: 15 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/serialcomms/_index.adoc b/documentation/content/en/books/handbook/serialcomms/_index.adoc index f9a72195b2..83562bab2d 100644 --- a/documentation/content/en/books/handbook/serialcomms/_index.adoc +++ b/documentation/content/en/books/handbook/serialcomms/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 27. Serial Communications +title: Chapter 28. Serial Communications part: Part IV. Network Communication prev: books/handbook/partiv next: books/handbook/ppp-and-slip description: This chapter covers some of the ways serial communications can be used on FreeBSD tags: ["serial", "communications", "terminal", "modem", "console"] showBookMenu: true -weight: 32 +weight: 33 path: "/books/handbook/" aliases: ["/en/books/handbook/serial/","/en/books/handbook/term/","/en/books/handbook/dialup/","/en/books/handbook/dialout/","/en/books/handbook/serialconsole-setup/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/serial/","/en/books/handbook/term/","/en/books/han :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 27 +:sectnumoffset: 28 :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 index 085cb9b995..7a7e2113a7 100644 --- a/documentation/content/en/books/handbook/usb-device-mode/_index.adoc +++ b/documentation/content/en/books/handbook/usb-device-mode/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: This chapter covers the use of USB Device Mode and USB On The Go (USB OTG) in FreeBSD tags: ["OTG", "USB"] showBookMenu: true -weight: 30 +weight: 31 path: "/books/handbook/" aliases: ["/en/books/handbook/usb-device-mode-terminals/","/en/books/handbook/usb-device-mode-network/","/en/books/handbook/usb-device-mode-storage/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/usb-device-mode-terminals/","/en/books/handbook/us :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 index bdb5570ce9..78daa5799d 100644 --- a/documentation/content/en/books/handbook/virtualization/_index.adoc +++ b/documentation/content/en/books/handbook/virtualization/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 22. Virtualization +title: Chapter 23. Virtualization part: Part III. System Administration prev: books/handbook/filesystems next: books/handbook/l10n description: Virtualization software allows multiple operating systems to run simultaneously on the same computer tags: ["virtualization", "Parallels", "VMware", "VirtualBox", "bhyve", "XEN"] showBookMenu: true -weight: 26 +weight: 27 path: "/books/handbook/" aliases: ["/en/books/handbook/virtualization-guest-parallels/","/en/books/handbook/virtualization-guest-virtualpc/","/en/books/handbook/virtualization-guest-vmware/","/en/books/handbook/virtualization-guest-virtualbox/","/en/books/handbook/virtualization-host-virtualbox/","/en/books/handbook/virtualization-host-bhyve/","/en/books/handbook/virtualization-host-xen/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/virtualization-guest-parallels/","/en/books/handbo :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 22 +:sectnumoffset: 23 :partnums: :source-highlighter: rouge :experimental: diff --git a/documentation/content/en/books/handbook/wayland/_index.adoc b/documentation/content/en/books/handbook/wayland/_index.adoc new file mode 100644 index 0000000000..0e7387ad5d --- /dev/null +++ b/documentation/content/en/books/handbook/wayland/_index.adoc @@ -0,0 +1,696 @@ +--- +title: Chapter 6. Wayland +part: Part I. Getting Started +prev: books/handbook/x11 +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: 8 +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 display server, but it differs from Xorg in several important ways. +First, Wayland is only a protocol that acts as an intermediary between clients using a different mechanism which removes the dependency on an X server. +Xorg includes both the X11 protocol, used to run remote displays and the X server will accept connections and display windows. +Under Wayland, the compositor or window manager provides the display server instead of a traditional X server. + +Since Wayland is not an X server, traditional X screen connections will need to utilize other methods such as VNC or RDP for remote desktop management. +Second, Wayland can manage composite communications between clients and a compositor as a separate entity which does not need to support the X protocols. + +Wayland is relatively new, and not all software has been updated to run natively without `Xwayland` support. +Because Wayland does not provide the X server, and expects compositors to provide that support, X11 window managers that do not yet support Wayland will require that `Xwayland` is not started with the `-rootless` parameter. +The `-rootless` parameter, when removed, will restore X11 window manager support. + +[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 = <super> KEY_Z +screensaver_timeout = 300 +dpms_timeout = 600 +.... + +The first option will lock the screen after 300 seconds, and after another 300, the screen will shut off through the `dpms_timeout` option. + +One final thing to note is the <super> key. +Most of the configuration mentions this key, and it is the traditional `Windows` key on the keyboard. +Most keyboards have this super key available; however, it should be remapped within this configuration file if it is not available. +For example, to lock the screen, press and hold the super key, the 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; +} +.... diff --git a/documentation/content/en/books/handbook/wine/_index.adoc b/documentation/content/en/books/handbook/wine/_index.adoc index 1a336b53e8..69754488c5 100644 --- a/documentation/content/en/books/handbook/wine/_index.adoc +++ b/documentation/content/en/books/handbook/wine/_index.adoc @@ -1,12 +1,12 @@ --- -title: Chapter 11. WINE +title: Chapter 12. WINE part: Part II. Common Tasks prev: books/handbook/linuxemu next: books/handbook/partiii description: This chapter will describe how to install WINE on a FreeBSD system and how to configure WINE tags: ["WINE", "emulation", "guide", "tutorial"] showBookMenu: true -weight: 14 +weight: 15 path: "/books/handbook/" aliases: ["/en/books/handbook/wine-overview-concepts/","/en/books/handbook/installing-wine-on-freebsd/","/en/books/handbook/running-first-wine-program/","/en/books/handbook/configuring-wine-installation/","/en/books/handbook/wine-management-guis/","/en/books/handbook/wine-in-multi-user-os-installations/","/en/books/handbook/wine-on-os-faq/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/wine-overview-concepts/","/en/books/handbook/insta :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 index d297b1eb17..51a581553d 100644 --- a/documentation/content/en/books/handbook/x11/_index.adoc +++ b/documentation/content/en/books/handbook/x11/_index.adoc @@ -2,7 +2,7 @@ title: Chapter 5. The X Window System part: Part I. Getting Started prev: books/handbook/ports -next: books/handbook/partii +next: books/handbook/wayland description: This chapter describes how to install and configure Xorg on FreeBSD, which provides the open source X Window System used to provide a graphical environment tags: ["X11", "Xorg", "TrueType", "DE", "KDE", "Plasma", "Xfce", "Gnome", "XDM", "SDDM", "GDM", "KMS", "Intel", "AMD", "NVIDIA", "Anti-Aliased"] showBookMenu: true @@ -1641,641 +1641,3 @@ 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 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 = <super> KEY_Z -screensaver_timeout = 300 -dpms_timeout = 600 -.... - -The first option will lock the screen after 300 seconds, and after another 300, the screen will shut off through the `dpms_timeout` option. - -One final thing to note is the <super> key. -Most of the configuration mentions this key, and it is the traditional `Windows` key on the keyboard. -Most keyboards have this super key available; however, it should be remapped within this configuration file if it is not available. -For example, to lock the screen, press and hold the super key, the 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 index c7d451265d..5400afa7b5 100644 --- a/documentation/content/en/books/handbook/zfs/_index.adoc +++ b/documentation/content/en/books/handbook/zfs/_index.adoc @@ -1,12 +1,12 @@ --- -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 description: ZFS is an advanced file system designed to solve major problems found in previous storage subsystem software tags: ["ZFS", "filesystem", "administration", "zpool", "features", "terminology", "RAID-Z"] showBookMenu: true -weight: 24 +weight: 25 path: "/books/handbook/" aliases: ["/en/books/handbook/zfs-quickstart/","/en/books/handbook/zfs-zpool/","/en/books/handbook/zfs-zfs/","/en/books/handbook/zfs-zfs-allow/","/en/books/handbook/zfs-advanced/","/en/books/handbook/zfs-links/","/en/books/handbook/zfs-term/"] --- @@ -19,7 +19,7 @@ aliases: ["/en/books/handbook/zfs-quickstart/","/en/books/handbook/zfs-zpool/"," :icons: font :sectnums: :sectnumlevels: 6 -:sectnumoffset: 20 +:sectnumoffset: 21 :partnums: :source-highlighter: rouge :experimental: |