From 7d8da55b39a41d10f6b869c36606cb3cf44ec205 Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Thu, 18 Jul 2024 18:17:49 -0400 Subject: [PATCH 1/5] docs/general/binary-releases: add anchors for linking --- docs/general/binary-releases.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/general/binary-releases.rst b/docs/general/binary-releases.rst index 8d6c5980a..dd11c3ad9 100644 --- a/docs/general/binary-releases.rst +++ b/docs/general/binary-releases.rst @@ -9,6 +9,8 @@ include the built-in EFI stub and may be directly bootable (provided the UEFI im arguments, including the path to the associated initramfs image, to the kernel) or loaded by a boot manager. In addition, the separate components may be booted by any standard BIOS boot loader (*e.g.*, syslinux) on legacy hardware. +.. _release-images: + Release images ~~~~~~~~~~~~~~ @@ -20,6 +22,8 @@ The extra tooling includes: .. include:: _include/release.rst +.. _recovery-images: + Recovery images ~~~~~~~~~~~~~~~ From 96f75e937e64483935a621446990763a3ca6b987 Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Thu, 18 Jul 2024 18:18:18 -0400 Subject: [PATCH 2/5] docs/index: add new pages --- docs/index.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index cd8ccc81f..d37b2036b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -47,6 +47,8 @@ :includehidden: :hidden: + general/faq + general/hardware-quirks general/binary-releases general/bootenvs-and-you general/container-building From 75759a48c24b50fca0d5c6814ecef539a77cd654 Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Thu, 18 Jul 2024 18:19:48 -0400 Subject: [PATCH 3/5] docs/general/hardware-quirks: migrate from wiki --- docs/general/hardware-quirks.rst | 59 ++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 docs/general/hardware-quirks.rst diff --git a/docs/general/hardware-quirks.rst b/docs/general/hardware-quirks.rst new file mode 100644 index 000000000..dff856691 --- /dev/null +++ b/docs/general/hardware-quirks.rst @@ -0,0 +1,59 @@ +Hardware Quirks +=============== + +.. contents:: Contents + :depth: 1 + :local: + :backlinks: none + + +Some computers have issues running ZFSBootMenu, or issues with hardware after +booting into a boot environment with ``kexec``. + +Contributions to this page with additional hardware quirks and solutions are encouraged. + +.. + Template: + + Hardware + -------- + + Symptoms + ^^^^^^^^ + Describe how to detect the problem + + Solution + ^^^^^^^^ + Describe how to resolve the issue + +HP Omen 16 2022 +--------------- + +Symptoms +^^^^^^^^ + +Non-functional touchpad, this log entry:: + + kernel: i2c_designware AMDI0010:03: Unknown Synopsys component type: 0xffffffff + +Solution +^^^^^^^^ + +If the driver is compiled into your kernel: append ``initcall_blacklist=dw_i2c_init_driver,dw_i2c_driver_init`` to the ZFSBootMenu kernel command line. + +If the driver is compiled as module: blacklist the module in ZFSBootMenu by appending ``i2c_designware_pci.blacklist=yes`` to the ZFSBootMenu kernel command line. + +Dell Servers +------------ + +Symptoms +^^^^^^^^ + +The ZFSBootMenu EFI image does not boot, either directly or via rEFInd, with the message:: + + Execution of embedded linux image failed: Out of Resources + +Solution +^^^^^^^^ + +Use rEFInd to boot the Components format (kernel and initramfs) of ZFSBootMenu. From 079aa0edccff3da63524c932751eb466d8bcca1d Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Thu, 18 Jul 2024 18:20:06 -0400 Subject: [PATCH 4/5] docs/general/faq: add page --- docs/general/faq.rst | 73 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/general/faq.rst diff --git a/docs/general/faq.rst b/docs/general/faq.rst new file mode 100644 index 000000000..004d75fa4 --- /dev/null +++ b/docs/general/faq.rst @@ -0,0 +1,73 @@ +Frequently Asked Questions +========================== + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: none + +Why don't the installation guides contain ? +---------------------------------------------- + +ZFSBootMenu's installation guides are designed to cover the general procedure +for installing Linux with ZFS as the root filesystem and ZFSBootMenu as the +bootloader. + +The guides can easily accomodate multi-disk pools by modifying the pool creation +arguments as described in :manpage:`zpool-create(8)`. + +Additional packages and configuration can be added at your choice. Consult your +distribution's documentation for more information. + +How can I send a snapshot to ZFSBootMenu? +----------------------------------------- + +Sending a snapshot to ZFSBootMenu is one way to bootstrap a new system, or restore +from a backup. This can be done using :manpage:`zfs-send(8)`, :manpage:`zfs-recv(8)`, +and :manpage:`mbuffer`, which are all available in the published :ref:`recovery-images`. + +Why doesn't ZFSBootMenu support having a separate pool for ``/boot``? +--------------------------------------------------------------------- + +Why can't my computer boot ZFSBootMenu? +--------------------------------------- + +How can I get more information from ZFSBootMenu for debugging? +-------------------------------------------------------------- + +What's with this hostid stuff? +------------------------------ + +What ZFS features does ZFSBootMenu support? +------------------------------------------- + +How can I edit ZFSBootMenu's kernel commandline? +------------------------------------------------ + +How can I edit my boot environment's kernel commandline? +-------------------------------------------------------- + +How can I boot ZFSBootMenu via PXE/netboot? +------------------------------------------- + +Why doesn't ZFSBootMenu support or have feature? +-------------------------------------------------------- + +Maybe we haven't thought of it yet, maybe we don't want the feature. Maybe something +else. First, search the `issue tracker `_ +and `discussions `_, then +you can create a new `feature request `_ +or bring it up on IRC (``#zfsbootmenu`` on ``irc.libera.chat``). + +How can I get support for ZFSBootMenu? +-------------------------------------- + +First, search the `issue tracker `_ +and `discussions `_. If your +questions are not answered, you can create a new +`discussion `_ +or ask on IRC (``#zfsbootmenu`` on ``irc.libera.chat``). + + +Why is ZFSBootMenu written in bash and not a real language? +----------------------------------------------------------- From 4461017a53720bce4ca93bf3b3bca1c446ca7cd5 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Thu, 31 Oct 2024 18:24:29 -0500 Subject: [PATCH 5/5] docs/general/faq: add answers to a few questions --- docs/general/faq.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/general/faq.rst b/docs/general/faq.rst index 004d75fa4..9c0d3fbf2 100644 --- a/docs/general/faq.rst +++ b/docs/general/faq.rst @@ -29,12 +29,18 @@ and :manpage:`mbuffer`, which are all available in the published :ref:`recovery- Why doesn't ZFSBootMenu support having a separate pool for ``/boot``? --------------------------------------------------------------------- +Boot pools are a by-product of GRUB not supporting most OpenZFS feature flags. They serve no purpose on a system with a modern version of OpenZFS in the bootloader. + Why can't my computer boot ZFSBootMenu? --------------------------------------- +Dude, you got a Dell :( + How can I get more information from ZFSBootMenu for debugging? -------------------------------------------------------------- +Use ``zreport`` from the recovery shell to access system information and pool/dataset details. + What's with this hostid stuff? ------------------------------