docs FAQ/hardware quirks

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
 ~~~~~~~~~~~~~~~
 

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 <X>?
+----------------------------------------------
+
+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 <X> or have <X> feature?
+--------------------------------------------------------
+
+Maybe we haven't thought of it yet, maybe we don't want the feature. Maybe something
+else. First, search the `issue tracker <https://github.com/zbm-dev/zfsbootmenu/issues>`_
+and `discussions <https://github.com/zbm-dev/zfsbootmenu/discussions>`_, then
+you can create a new `feature request <https://github.com/zbm-dev/zfsbootmenu/discussions/new?category=feature-requests>`_
+or bring it up on IRC (``#zfsbootmenu`` on ``irc.libera.chat``).
+
+How can I get support for ZFSBootMenu?
+--------------------------------------
+
+First, search the `issue tracker <https://github.com/zbm-dev/zfsbootmenu/issues>`_
+and `discussions <https://github.com/zbm-dev/zfsbootmenu/discussions>`_. If your
+questions are not answered, you can create a new
+`discussion <https://github.com/zbm-dev/zfsbootmenu/discussions/new?category=questions>`_
+or ask on IRC (``#zfsbootmenu`` on ``irc.libera.chat``).
+
+
+Why is ZFSBootMenu written in bash and not a real language?
+-----------------------------------------------------------

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.

docs/index.rst

@@ -47,6 +47,8 @@
   :includehidden:
   :hidden:
 
+  general/faq
+  general/hardware-quirks
   general/binary-releases
   general/bootenvs-and-you
   general/container-building