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 ~~~~~~~~~~~~~~~ diff --git a/docs/general/faq.rst b/docs/general/faq.rst new file mode 100644 index 000000000..9c0d3fbf2 --- /dev/null +++ b/docs/general/faq.rst @@ -0,0 +1,79 @@ +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``? +--------------------------------------------------------------------- + +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? +------------------------------ + +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? +----------------------------------------------------------- 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. 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