From d9634f0f487f8768bdd041cc9bddc24fc7f3c0eb Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Wed, 17 May 2023 09:00:19 -0500 Subject: [PATCH 01/33] docs/guides/debian/: add initial bookworm guide --- docs/guides/debian.rst | 3 +- .../_include/bookworm/distro-install.rst | 99 +++++++++++++++++++ .../_include/bookworm/live-environment.rst | 41 ++++++++ .../_include/bullseye/distro-install.rst | 99 +++++++++++++++++++ .../_include/bullseye/live-environment.rst | 41 ++++++++ .../debian/{uefi.rst => bookworm-uefi.rst} | 8 +- docs/guides/debian/bullseye-uefi.rst | 46 +++++++++ 7 files changed, 332 insertions(+), 5 deletions(-) create mode 100644 docs/guides/debian/_include/bookworm/distro-install.rst create mode 100644 docs/guides/debian/_include/bookworm/live-environment.rst create mode 100644 docs/guides/debian/_include/bullseye/distro-install.rst create mode 100644 docs/guides/debian/_include/bullseye/live-environment.rst rename docs/guides/debian/{uefi.rst => bookworm-uefi.rst} (83%) create mode 100644 docs/guides/debian/bullseye-uefi.rst diff --git a/docs/guides/debian.rst b/docs/guides/debian.rst index 9c794759e..2d6f41f75 100644 --- a/docs/guides/debian.rst +++ b/docs/guides/debian.rst @@ -4,4 +4,5 @@ Debian .. toctree:: :titlesonly: - debian/uefi + debian/bullseye-uefi + debian/bookworm-uefi diff --git a/docs/guides/debian/_include/bookworm/distro-install.rst b/docs/guides/debian/_include/bookworm/distro-install.rst new file mode 100644 index 000000000..ffe55622b --- /dev/null +++ b/docs/guides/debian/_include/bookworm/distro-install.rst @@ -0,0 +1,99 @@ +Install Debian +-------------- + +.. code-block:: bash + + debootstrap bookworm /mnt + +Copy files into the new install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. group-tab:: Unencrypted + + .. code-block:: bash + + cp /etc/hostid /mnt/etc + cp /etc/resolv.conf /mnt/etc + + .. group-tab:: Encrypted + + .. code-block:: bash + + cp /etc/hostid /mnt/etc/hostid + cp /etc/resolv.conf /mnt/etc/ + mkdir /mnt/etc/zfs + cp /etc/zfs/zroot.key /mnt/etc/zfs + +Chroot into the new OS +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + mount -t proc proc /mnt/proc + mount -t sysfs sys /mnt/sys + mount -B /dev /mnt/dev + mount -t devpts pts /mnt/dev/pts + chroot /mnt /bin/bash + +Basic Debian Configuration +-------------------------- + +Set a hostname +~~~~~~~~~~~~~~ + +.. code-block:: bash + + echo 'YOURHOSTNAME' > /etc/hostname + echo -e '127.0.1.1\tYOURHOSTNAME' >> /etc/hosts + +Set a root password +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + passwd + +Configure ``apt``. Use other mirrors if you prefer. + +.. code-block:: bash + + cat < /etc/apt/sources.list + deb http://deb.debian.org/debian bookworm main contrib + deb-src http://deb.debian.org/debian bookworm main contrib + + deb http://deb.debian.org/debian-security bookworm-security main contrib + deb-src http://deb.debian.org/debian-security/ bookworm-security main contrib + + deb http://deb.debian.org/debian bookworm-updates main contrib + deb-src http://deb.debian.org/debian bookworm-updates main contrib + + deb http://deb.debian.org/debian bookworm-backports main contrib + deb-src http://deb.debian.org/debian bookworm-backports main contrib + EOF + +Update the repository cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + apt update + +Install additional base packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + apt install locales keyboard-configuration console-setup + +Configure packages to customize local and console properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + dpkg-reconfigure locales tzdata keyboard-configuration console-setup + +.. note:: + + You should always enable the `en_US.UTF-8` locale because some programs require it. diff --git a/docs/guides/debian/_include/bookworm/live-environment.rst b/docs/guides/debian/_include/bookworm/live-environment.rst new file mode 100644 index 000000000..7ca3f549c --- /dev/null +++ b/docs/guides/debian/_include/bookworm/live-environment.rst @@ -0,0 +1,41 @@ +Configure Live Environment +-------------------------- + +Switch to a root shell +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + sudo -i + +.. include:: ../_include/os-release.rst + +Configure and update APT +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + cat < /etc/apt/sources.list + deb http://deb.debian.org/debian bookworm main contrib + deb-src http://deb.debian.org/debian bookworm main contrib + EOF + apt update + +.. note:: + + You may see faster downloads replacing ``deb.debian.org`` with a local mirror. If you want to use HTTPS transport, make + sure that the ``ca-certificates`` and ``apt-transport-https`` packages are installed and your mirror has a valid + certificate; otherwise, apt will refuse to use the mirror. + +Install helpers +~~~~~~~~~~~~~~~ + +.. code-block:: + + apt install debootstrap gdisk dkms linux-headers-$(uname -r) + apt install zfsutils-linux + +.. include:: ../_include/zgenhostid.rst + +.. + vim: softtabstop=2 shiftwidth=2 textwidth=120 diff --git a/docs/guides/debian/_include/bullseye/distro-install.rst b/docs/guides/debian/_include/bullseye/distro-install.rst new file mode 100644 index 000000000..b92205a95 --- /dev/null +++ b/docs/guides/debian/_include/bullseye/distro-install.rst @@ -0,0 +1,99 @@ +Install Debian +-------------- + +.. code-block:: bash + + debootstrap bullseye /mnt + +Copy files into the new install +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. tabs:: + + .. group-tab:: Unencrypted + + .. code-block:: bash + + cp /etc/hostid /mnt/etc + cp /etc/resolv.conf /mnt/etc + + .. group-tab:: Encrypted + + .. code-block:: bash + + cp /etc/hostid /mnt/etc/hostid + cp /etc/resolv.conf /mnt/etc/ + mkdir /mnt/etc/zfs + cp /etc/zfs/zroot.key /mnt/etc/zfs + +Chroot into the new OS +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + mount -t proc proc /mnt/proc + mount -t sysfs sys /mnt/sys + mount -B /dev /mnt/dev + mount -t devpts pts /mnt/dev/pts + chroot /mnt /bin/bash + +Basic Debian Configuration +-------------------------- + +Set a hostname +~~~~~~~~~~~~~~ + +.. code-block:: bash + + echo 'YOURHOSTNAME' > /etc/hostname + echo -e '127.0.1.1\tYOURHOSTNAME' >> /etc/hosts + +Set a root password +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + passwd + +Configure ``apt``. Use other mirrors if you prefer. + +.. code-block:: bash + + cat < /etc/apt/sources.list + deb http://deb.debian.org/debian bullseye main contrib + deb-src http://deb.debian.org/debian bullseye main contrib + + deb http://deb.debian.org/debian-security bullseye-security main contrib + deb-src http://deb.debian.org/debian-security/ bullseye-security main contrib + + deb http://deb.debian.org/debian bullseye-updates main contrib + deb-src http://deb.debian.org/debian bullseye-updates main contrib + + deb http://deb.debian.org/debian bullseye-backports main contrib + deb-src http://deb.debian.org/debian bullseye-backports main contrib + EOF + +Update the repository cache +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + apt update + +Install additional base packages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + apt install locales keyboard-configuration console-setup + +Configure packages to customize local and console properties +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + dpkg-reconfigure locales tzdata keyboard-configuration console-setup + +.. note:: + + You should always enable the `en_US.UTF-8` locale because some programs require it. diff --git a/docs/guides/debian/_include/bullseye/live-environment.rst b/docs/guides/debian/_include/bullseye/live-environment.rst new file mode 100644 index 000000000..8dc405bf5 --- /dev/null +++ b/docs/guides/debian/_include/bullseye/live-environment.rst @@ -0,0 +1,41 @@ +Configure Live Environment +-------------------------- + +Switch to a root shell +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + sudo -i + +.. include:: ../_include/os-release.rst + +Configure and update APT +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + cat < /etc/apt/sources.list + deb http://deb.debian.org/debian bullseye main contrib + deb-src http://deb.debian.org/debian bullseye main contrib + EOF + apt update + +.. note:: + + You may see faster downloads replacing ``deb.debian.org`` with a local mirror. If you want to use HTTPS transport, make + sure that the ``ca-certificates`` and ``apt-transport-https`` packages are installed and your mirror has a valid + certificate; otherwise, apt will refuse to use the mirror. + +Install helpers +~~~~~~~~~~~~~~~ + +.. code-block:: + + apt install debootstrap gdisk dkms linux-headers-$(uname -r) + apt install zfsutils-linux + +.. include:: ../_include/zgenhostid.rst + +.. + vim: softtabstop=2 shiftwidth=2 textwidth=120 diff --git a/docs/guides/debian/uefi.rst b/docs/guides/debian/bookworm-uefi.rst similarity index 83% rename from docs/guides/debian/uefi.rst rename to docs/guides/debian/bookworm-uefi.rst index 1ac2b64fa..4058576fd 100644 --- a/docs/guides/debian/uefi.rst +++ b/docs/guides/debian/bookworm-uefi.rst @@ -1,4 +1,4 @@ -Bullseye UEFI +Bookworm (12) UEFI ============= .. |distribution| replace:: debian @@ -16,12 +16,12 @@ It assumes the following: * Your system is x86_64 * You're mildly comfortable with ZFS, EFI and discovering system facts on your own (``lsblk``, ``dmesg``, ``gdisk``, ...) -Download the latest `Debian Bullseye (11) Live image `_, write it to a USB drive and +Download the latest `Debian Bookworm (12) Live image `_, write it to a USB drive and boot your system in EFI mode. .. include:: ../_include/efi-boot-check.rst -.. include:: _include/live-environment.rst +.. include:: _include/bookworm/live-environment.rst .. include:: ../_include/define-env.rst @@ -31,7 +31,7 @@ boot your system in EFI mode. .. include:: ../_include/create-filesystems.rst -.. include:: _include/distro-install.rst +.. include:: _include/bookworm/distro-install.rst .. include:: _include/zfs-config.rst diff --git a/docs/guides/debian/bullseye-uefi.rst b/docs/guides/debian/bullseye-uefi.rst new file mode 100644 index 000000000..f64122f3a --- /dev/null +++ b/docs/guides/debian/bullseye-uefi.rst @@ -0,0 +1,46 @@ +Bullseye (11) UEFI +============= + +.. |distribution| replace:: debian + +.. contents:: Contents + :depth: 2 + :local: + :backlinks: none + +This guide can be used to install Debian onto a single disk with or without ZFS encryption. + +It assumes the following: + +* Your system uses UEFI to boot +* Your system is x86_64 +* You're mildly comfortable with ZFS, EFI and discovering system facts on your own (``lsblk``, ``dmesg``, ``gdisk``, ...) + +Download the latest `Debian Bullseye (11) Live image `_, write it to a USB drive and +boot your system in EFI mode. + +.. include:: ../_include/efi-boot-check.rst + +.. include:: _include/bullseye/live-environment.rst + +.. include:: ../_include/define-env.rst + +.. include:: ../_include/disk-preparation.rst + +.. include:: ../_include/pool-creation.rst + +.. include:: ../_include/create-filesystems.rst + +.. include:: _include/bullseye/distro-install.rst + +.. include:: _include/zfs-config.rst + +.. include:: ../_include/zbm-setup.rst + +.. include:: ../_include/setup-esp.rst + +.. include:: _include/zbm-install.rst + +.. include:: _include/efi-boot-method.rst + +.. include:: ../_include/cleanup.rst From 50ee82ec3e1eff54f0c357744b048c998fda4b49 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Mon, 12 Jun 2023 15:49:56 -0500 Subject: [PATCH 02/33] guides/void-linux/: prefer prebuilt EFI over package --- docs/guides/void-linux/_include/zbm-install.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guides/void-linux/_include/zbm-install.rst b/docs/guides/void-linux/_include/zbm-install.rst index 7900060a1..533d44c32 100644 --- a/docs/guides/void-linux/_include/zbm-install.rst +++ b/docs/guides/void-linux/_include/zbm-install.rst @@ -3,6 +3,14 @@ Install ZFSBootMenu .. tabs:: + .. group-tab:: Prebuilt + + .. code-block:: bash + + xbps-install -S curl + + .. include:: ../_include/zbm-install-prebuilt.rst + .. group-tab:: Package .. code-block:: @@ -12,11 +20,3 @@ Install ZFSBootMenu .. include:: ../_include/configure-gen-zbm.rst .. include:: ../_include/gen-initramfs.rst - - .. group-tab:: Prebuilt - - .. code-block:: bash - - xbps-install -S curl - - .. include:: ../_include/zbm-install-prebuilt.rst From b212b23bfb790f185076d3a196988e19b06a13d6 Mon Sep 17 00:00:00 2001 From: Andrew Gunnerson Date: Wed, 14 Jun 2023 19:45:13 -0400 Subject: [PATCH 03/33] zbm-builder.sh: add mount-options argument, document use A new `-M` option for `zbm-builder.sh` provides a means to specify mount options for the `/build` and (if specified) `/zbm` volumes in the build container. Using, for example, `-M z` allows images to be built on hosts with SELinux enabled. This change is documented, along with extra considerations for building Dracut-based images in containers when SELinux is enabled on the host. Signed-off-by: Andrew Gunnerson Closes: #433. --- docs/guides/general/container-building.rst | 15 +++++++++++++++ zbm-builder.sh | 22 +++++++++++++++++++--- 2 files changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/guides/general/container-building.rst b/docs/guides/general/container-building.rst index 4707efb60..254438d28 100644 --- a/docs/guides/general/container-building.rst +++ b/docs/guides/general/container-building.rst @@ -118,6 +118,18 @@ The default behavior of ``zbm-builder.sh`` will: 2. If ``./config.yaml`` exists, inform the builder to use that custom configuration instead of the default 3. Run the internal build script to produce output in the ``./build`` subdirectory +.. note:: + + Building on hosts with SELinux enabled may require that volumes mounted by the build container be properly labeled. + This can be accomplished by specifying the argument ``-M z`` to ``zbm-builder.sh``. This will persistently relabel the + build directory and, if specified, the ZFSBootMenu source directory. As an alternative to conf, it may be possible to + disable SELinux entirely by invoking ``zbm-builder.sh`` with the argument ``-O --security-opt=label=disable``. + + When Dracut is used to build an image under the constraints of SELinux, ``zbm-builder.sh`` should additionally be + invoked with the argument ``-O --env=DRACUT_NO_XATTR=1`` to prevent Dracut from setting extended attributes on + temporary files it creates within the container. Without this option, Dracut may try, but fail, to set the + ``security.selinux`` attribute on files. + Custom ZFSBootMenu Hooks ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -174,3 +186,6 @@ command-line options that are described in the output of ``zbm-builder.sh -h``. Before adjusting these command-line options, seek a thorough understanding of the :zbm:`image build process ` and the command sequence of ``zbm-builder.sh`` itself. + +.. + vim: softtabstop=2 shiftwidth=2 textwidth=120 diff --git a/zbm-builder.sh b/zbm-builder.sh index 25f4ae00b..d954de831 100755 --- a/zbm-builder.sh +++ b/zbm-builder.sh @@ -40,6 +40,18 @@ OPTIONS: -d Force use of docker instead of podman + -M + Provide a comma-separated list of options to use for volume + mounts of the build directory and (if specified) ZFSBootMenu + source tree within the build container. For example, specify + + zbm-builder -M z + + to label the volumes for use with SELinux. + + NOTE: An 'ro' option is always added to the volume mounted from + the ZFSBootMenu source tree. + -O Provide an option to 'podman run' or 'docker run'; if the argument accepts one or more options, use a form with no spaces @@ -76,6 +88,7 @@ EOF SKIP_HOSTID= REMOVE_HOST_FILES= +MOUNT_FLAGS= # By default, use the latest upstream build container image BUILD_IMG="ghcr.io/zbm-dev/zbm-builder:latest" @@ -101,7 +114,7 @@ else PODMAN="docker" fi -CMDOPTS="b:dhi:l:c:O:HR" +CMDOPTS="b:dhi:l:c:M:O:HR" # First pass to get build directory and configuration file while getopts "${CMDOPTS}" opt; do @@ -156,6 +169,9 @@ while getopts "${CMDOPTS}" opt; do l) BUILD_REPO="${OPTARG}" ;; + M) + MOUNT_FLAGS="${OPTARG}" + ;; O) RUNTIME_ARGS+=( "${OPTARG}" ) ;; @@ -181,7 +197,7 @@ if ! command -v "${PODMAN}" >/dev/null 2>&1; then fi # Always mount a build directory at /build -RUNTIME_ARGS+=( "-v" "${BUILD_DIRECTORY}:/build" ) +RUNTIME_ARGS+=( "-v" "${BUILD_DIRECTORY}:/build${MOUNT_FLAGS:+:${MOUNT_FLAGS}}" ) # Only mount a local repo at /zbm if specified if [ -n "${BUILD_REPO}" ]; then @@ -190,7 +206,7 @@ if [ -n "${BUILD_REPO}" ]; then exit 1 fi - RUNTIME_ARGS+=( "-v" "${BUILD_REPO}:/zbm:ro" ) + RUNTIME_ARGS+=( "-v" "${BUILD_REPO}:/zbm:ro${MOUNT_FLAGS:+,${MOUNT_FLAGS}}" ) fi # Remove existing hostid From bd37ec5918c7783fb22c935a548a089b748bad01 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Tue, 20 Jun 2023 14:36:45 -0500 Subject: [PATCH 04/33] docs/guides/debian/: fix sphinx warnings --- docs/guides/debian/bookworm-uefi.rst | 2 +- docs/guides/debian/bullseye-uefi.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/debian/bookworm-uefi.rst b/docs/guides/debian/bookworm-uefi.rst index 4058576fd..5cf5ade73 100644 --- a/docs/guides/debian/bookworm-uefi.rst +++ b/docs/guides/debian/bookworm-uefi.rst @@ -1,5 +1,5 @@ Bookworm (12) UEFI -============= +================== .. |distribution| replace:: debian diff --git a/docs/guides/debian/bullseye-uefi.rst b/docs/guides/debian/bullseye-uefi.rst index f64122f3a..625137a71 100644 --- a/docs/guides/debian/bullseye-uefi.rst +++ b/docs/guides/debian/bullseye-uefi.rst @@ -1,5 +1,5 @@ Bullseye (11) UEFI -============= +================== .. |distribution| replace:: debian From 00596f54ccd1e659e11c4ce9517f6ba915e30c01 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Tue, 27 Jun 2023 10:23:11 -0400 Subject: [PATCH 05/33] docs/guides/alpine/: remove problematic eudev commands --- docs/guides/alpine/_include/live-environment.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/guides/alpine/_include/live-environment.rst b/docs/guides/alpine/_include/live-environment.rst index 018a7ce80..6ba4e4e3f 100644 --- a/docs/guides/alpine/_include/live-environment.rst +++ b/docs/guides/alpine/_include/live-environment.rst @@ -19,9 +19,8 @@ Setup additional tools .. code-block:: - apk add zfs sgdisk wipefs eudev + apk add zfs sgdisk wipefs modprobe zfs - setup-devd udev .. include:: ../_include/zgenhostid.rst From 528b5e0ed4e58cbe1af45fe22f44fa4513f21ec9 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Tue, 27 Jun 2023 10:34:39 -0400 Subject: [PATCH 06/33] docs/guides/: separate udev manipulation, omit from Alpine guide --- docs/guides/_include/create-filesystems.rst | 7 ------- docs/guides/_include/update-devices.rst | 6 ++++++ docs/guides/alpine/_include/distro-install.rst | 2 -- docs/guides/debian/bookworm-uefi.rst | 2 ++ docs/guides/debian/bullseye-uefi.rst | 2 ++ docs/guides/fedora/uefi.rst | 2 ++ docs/guides/opensuse/uefi.rst | 2 ++ docs/guides/ubuntu/uefi.rst | 2 ++ docs/guides/void-linux/syslinux-mbr.rst | 2 ++ docs/guides/void-linux/uefi.rst | 2 ++ 10 files changed, 20 insertions(+), 9 deletions(-) create mode 100644 docs/guides/_include/update-devices.rst diff --git a/docs/guides/_include/create-filesystems.rst b/docs/guides/_include/create-filesystems.rst index 7663e29e7..84b2cc09b 100644 --- a/docs/guides/_include/create-filesystems.rst +++ b/docs/guides/_include/create-filesystems.rst @@ -55,10 +55,3 @@ Verify that everything is mounted correctly # **mount | grep mnt** zroot/ROOT/\ |distribution| on /mnt type zfs (rw,relatime,xattr,posixacl) zroot/home on /mnt/home type zfs (rw,relatime,xattr,posixacl) - -Update device symlinks -~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: - - udevadm trigger diff --git a/docs/guides/_include/update-devices.rst b/docs/guides/_include/update-devices.rst new file mode 100644 index 000000000..12198318b --- /dev/null +++ b/docs/guides/_include/update-devices.rst @@ -0,0 +1,6 @@ +Update device symlinks +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: + + udevadm trigger diff --git a/docs/guides/alpine/_include/distro-install.rst b/docs/guides/alpine/_include/distro-install.rst index 1f717e81e..5a6e195b0 100644 --- a/docs/guides/alpine/_include/distro-install.rst +++ b/docs/guides/alpine/_include/distro-install.rst @@ -56,5 +56,3 @@ Enable startup targets rc-update add hwdrivers sysinit rc-update add networking rc-update add hostname - apk add udev - setup-devd udev diff --git a/docs/guides/debian/bookworm-uefi.rst b/docs/guides/debian/bookworm-uefi.rst index 5cf5ade73..60d4267f3 100644 --- a/docs/guides/debian/bookworm-uefi.rst +++ b/docs/guides/debian/bookworm-uefi.rst @@ -31,6 +31,8 @@ boot your system in EFI mode. .. include:: ../_include/create-filesystems.rst +.. include:: ../_include/update-devices.rst + .. include:: _include/bookworm/distro-install.rst .. include:: _include/zfs-config.rst diff --git a/docs/guides/debian/bullseye-uefi.rst b/docs/guides/debian/bullseye-uefi.rst index 625137a71..7ca541412 100644 --- a/docs/guides/debian/bullseye-uefi.rst +++ b/docs/guides/debian/bullseye-uefi.rst @@ -31,6 +31,8 @@ boot your system in EFI mode. .. include:: ../_include/create-filesystems.rst +.. include:: ../_include/update-devices.rst + .. include:: _include/bullseye/distro-install.rst .. include:: _include/zfs-config.rst diff --git a/docs/guides/fedora/uefi.rst b/docs/guides/fedora/uefi.rst index 29c88ead4..7d4426b97 100644 --- a/docs/guides/fedora/uefi.rst +++ b/docs/guides/fedora/uefi.rst @@ -31,6 +31,8 @@ Download `Fedora Workstation Live Date: Wed, 28 Jun 2023 10:28:36 -0400 Subject: [PATCH 07/33] docs/guides/alpine/: add missing mdev rescan --- docs/guides/alpine/_include/device-rescan.rst | 6 ++++++ docs/guides/alpine/uefi.rst | 4 ++-- 2 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 docs/guides/alpine/_include/device-rescan.rst diff --git a/docs/guides/alpine/_include/device-rescan.rst b/docs/guides/alpine/_include/device-rescan.rst new file mode 100644 index 000000000..17be09e94 --- /dev/null +++ b/docs/guides/alpine/_include/device-rescan.rst @@ -0,0 +1,6 @@ +Rescan Device Nodes +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: bash + + mdev -s diff --git a/docs/guides/alpine/uefi.rst b/docs/guides/alpine/uefi.rst index a478d88ea..2c4013b32 100644 --- a/docs/guides/alpine/uefi.rst +++ b/docs/guides/alpine/uefi.rst @@ -17,8 +17,6 @@ It assumes the following: * You're mildly comfortable with ZFS, EFI and discovering system facts on your own (``lsblk``, ``dmesg``, ``gdisk``, ...) -.. include:: ../_include/intro.rst - Download the latest `Alpine Extended ISO `_, write it to USB drive and boot your system in EFI mode. @@ -30,6 +28,8 @@ system in EFI mode. .. include:: ../_include/disk-preparation.rst +.. include:: _include/device-rescan.rst + .. include:: ../_include/pool-creation.rst .. include:: ../_include/create-filesystems.rst From 56f9189d5845c80ebcf64342c6658af9cacccea2 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Thu, 6 Jul 2023 09:16:50 -0500 Subject: [PATCH 08/33] guides/fedora: update ZFS RPM repo URL --- docs/guides/fedora/_include/live-environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/fedora/_include/live-environment.rst b/docs/guides/fedora/_include/live-environment.rst index e4bd587d5..75ea0671d 100644 --- a/docs/guides/fedora/_include/live-environment.rst +++ b/docs/guides/fedora/_include/live-environment.rst @@ -16,7 +16,7 @@ Install updated ZFS packages .. code-block:: rpm -e --nodeps zfs-fuse - dnf install -y https://zfsonlinux.org/fedora/zfs-release-2-2$(rpm --eval "%{dist}").noarch.rpm + dnf install -y https://zfsonlinux.org/fedora/zfs-release-2-3$(rpm --eval "%{dist}").noarch.rpm dnf install -y https://dl.fedoraproject.org/pub/fedora/linux/releases/${VERSION_ID}/Everything/x86_64/os/Packages/k/kernel-devel-$(uname -r).rpm dnf install -y zfs modprobe zfs From fa4dcf1bf36ba1ca01a0b748818888386a04d506 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Thu, 6 Jul 2023 11:26:27 -0500 Subject: [PATCH 09/33] docs/guides/fedora: update to Workstation 38 Closes #442 --- docs/guides/fedora/_include/zbm-install-deps.rst | 1 + docs/guides/fedora/_include/zfs-config.rst | 2 +- docs/guides/fedora/uefi.rst | 4 ++-- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/fedora/_include/zbm-install-deps.rst b/docs/guides/fedora/_include/zbm-install-deps.rst index c4b9a697a..5f1dbe9c8 100644 --- a/docs/guides/fedora/_include/zbm-install-deps.rst +++ b/docs/guides/fedora/_include/zbm-install-deps.rst @@ -3,6 +3,7 @@ Install all packages required to build a ZFSBootMenu image on Fedora: .. code-block:: bash dnf install -y \ + systemd-boot-unsigned \ perl-YAML-PP \ perl-Sort-Versions \ perl-boolean \ diff --git a/docs/guides/fedora/_include/zfs-config.rst b/docs/guides/fedora/_include/zfs-config.rst index 70dbeda6b..1dd8cabd3 100644 --- a/docs/guides/fedora/_include/zfs-config.rst +++ b/docs/guides/fedora/_include/zfs-config.rst @@ -39,6 +39,6 @@ Install required packages dnf install -y https://dl.fedoraproject.org/pub/fedora/linux/releases/${VERSION_ID}/Everything/x86_64/os/Packages/k/kernel-devel-$(uname -r).rpm dnf --releasever=${VERSION_ID} install -y \ - https://zfsonlinux.org/fedora/zfs-release-2-2$(rpm --eval "%{dist}").noarch.rpm + https://zfsonlinux.org/fedora/zfs-release-2-3$(rpm --eval "%{dist}").noarch.rpm dnf install -y zfs zfs-dracut diff --git a/docs/guides/fedora/uefi.rst b/docs/guides/fedora/uefi.rst index 7d4426b97..ed7257219 100644 --- a/docs/guides/fedora/uefi.rst +++ b/docs/guides/fedora/uefi.rst @@ -1,4 +1,4 @@ -Workstation 37 UEFI +Workstation 38 UEFI =================== .. |distribution| replace:: fedora @@ -16,7 +16,7 @@ It assumes the following: * Your system is x86_64 * You're mildly comfortable with ZFS, EFI and discovering system facts on your own (``lsblk``, ``dmesg``, ``gdisk``, ...) -Download `Fedora Workstation Live `_ +Download `Fedora Workstation Live `_ , write it to a USB drive and boot your system in EFI mode. .. include:: ../_include/efi-boot-check.rst From 4efb1c190a53215dabe390d7586db57aca6ace2c Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Sat, 22 Jul 2023 05:39:30 -0400 Subject: [PATCH 10/33] docs/guides/general: move mkinitcpio setup to its own guide having it in the remote access guide was too confusing and hidden --- docs/guides/general.rst | 1 + docs/guides/general/container-example.rst | 2 +- docs/guides/general/mkinitcpio.rst | 44 +++++++++++++++++++++++ 3 files changed, 46 insertions(+), 1 deletion(-) create mode 100644 docs/guides/general/mkinitcpio.rst diff --git a/docs/guides/general.rst b/docs/guides/general.rst index 32f91b9e5..70b998f44 100644 --- a/docs/guides/general.rst +++ b/docs/guides/general.rst @@ -8,6 +8,7 @@ General general/container-building general/native-encryption general/uefi-booting + general/mkinitcpio general/remote-access general/portable diff --git a/docs/guides/general/container-example.rst b/docs/guides/general/container-example.rst index f0448da46..2b2c2ee47 100644 --- a/docs/guides/general/container-example.rst +++ b/docs/guides/general/container-example.rst @@ -158,7 +158,7 @@ ZFSBootMenu images is largely the same as the :doc:`process for host-built images `, but care must be taken to ensure that all necessary components are available within the build directory. -- The :ref:`core configuration changes ` should be **ignored**. They are unnecessary with the +- The :doc:`core configuration changes ` should be **ignored**. They are unnecessary with the container configuration described above. - The :ref:`basic network access ` and :ref:`dropbear ` instructions diff --git a/docs/guides/general/mkinitcpio.rst b/docs/guides/general/mkinitcpio.rst new file mode 100644 index 000000000..3eabe0195 --- /dev/null +++ b/docs/guides/general/mkinitcpio.rst @@ -0,0 +1,44 @@ +Building with mkinitcpio +======================== + +ZFSBootMenu also supports the `mkinitcpio `_ initramfs +generator used by Arch Linux and available for Void Linux, but it must be configured first. + +Since `version 2.0.0 `_, ZFSBootMenu will install a standard +:zbm:`mkinitcpio.conf ` in the ``/etc/zfsbootmenu`` configuration directory. This file +is generally the same as a standard ``mkinitcpio.conf``, except some additional declarations may be added to control +aspects of the ``zfsbootmenu`` mkinitcpio module. The configuration file includes extensive inline documentation in the +form of comments; configuration options specific to ZFSBootMenu are also described in the +:ref:`zfsbootmenu(7) ` manual page. + +ZFSBootMenu still expects to use Dracut by default. To override this behavior and instead use mkinitcpio, edit +``/etc/zfsbootmenu/config.yaml`` and add the following options: + +.. code-block:: yaml + + Global: + InitCPIO: true + ## NOTE: The following three lines are OPTIONAL + InitCPIOHookDirs: + - /etc/zfsbootmenu/initcpio + - /usr/lib/initcpio + +.. note:: + + In some ZFSBootMenu guides, like :doc:`remote-access`, some mkinitcpio modules will be installed to + ``/etc/zfsbootmenu/initcpio`` to keep them isolated from system-installed modules. To accommodate this non-standard + installation, ``InitCPIOHookDirs`` must be defined in ``/etc/zfsbootmenu/config.yaml``. Furthermore, because + overriding the hook directory causes mkinitcpio to ignore its default module path, the default ``/usr/lib/initcpio`` + must be manually specified. If all hooks are installed in ``/usr/lib/initcpio`` or ``/etc/initcpio``, the ZFSBootMenu + configuration does **not** need to specify ``InitCPIOHookDirs``. + +Without further changes, running ``generate-zbm`` should now produce a ZBM image based on mkinitcpio rather than Dracut. + +Whenever ``generate-zbm`` is run to generate images based on mkinitcpio, it forcefully adds the the required +``zfsbootmenu`` hook after any hooks defined in the ``HOOKS`` array of ``/etc/zfsbootmenu/mkinitcpio.conf``. The default +configuration file explicitly includes the ``zfsbootmenu`` hook in the array as a visual reminder that it will be +included (strictly speaking, this will cause mkinitcpio to add the hook **twice**, but because the ``zfsbootmenu`` hook +completely takes over execution of its initramfs image, it will only ever run once). If any custom configuration requires +additional hooks be added to the ZFSBootMenu initramfs image, make sure that these hooks are included **before** any +occurrence of ``zfsbootmenu`` in ``HOOKS``. Better still, just remove the ``zfsbootmenu`` hook from +``/etc/zfsbootmenu/mkinitcpio.conf`` when making any edits to ``HOOKS`` to minimize the chance of configuration errors. From 3986b42ee9a1ef9811f600e7819194cd9fd2a8bd Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Sat, 22 Jul 2023 05:40:24 -0400 Subject: [PATCH 11/33] docs/guides/general/remote-access: refactor for easier reading also make a few things consistent between dracut and mkinitcpio --- docs/guides/general/remote-access.rst | 405 ++++++++++++-------------- 1 file changed, 182 insertions(+), 223 deletions(-) diff --git a/docs/guides/general/remote-access.rst b/docs/guides/general/remote-access.rst index fbd365662..94090fbd5 100644 --- a/docs/guides/general/remote-access.rst +++ b/docs/guides/general/remote-access.rst @@ -11,303 +11,262 @@ your boot environments reside in encrypted filesystems, SSH access is necessary when you are not physically present. Because ZFSBootMenu supports Dracut and mkinitcpio, any mechanism that can provide remote access to a Dracut or mkinitcpio initramfs will work. -Dracut ------- +Enabling Network Access +----------------------- -The `dracut-crypt-ssh `_ provides a straightforward approach to -configuring and launching an SSH server in Dracut images. The module is packaged in Void and does not rely on -``systemd`` within the initramfs. If you run a distribution that does not package ``dracut-crypt-ssh``, you will need to -track down its dependencies. The ``dracut-network`` module and ``dropbear`` are required to provide network access and -an SSH server, respectively; other prerequisites are probably already installed on your system. +.. tabs:: -Simplified Installation Instructions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. group-tab:: Dracut -The ``dracut-crypt-ssh`` package comes with a few helper utilities in the ``module/60crypt-ssh/helper`` directory that -are designed to simplify providing passwords and snooping console output so that you can interact with unlock processes -that are already running in the initramfs. These components are not required for ZFSBootMenu and do not provide a lot of -value. If you have no problems installing the package as intended, it is OK to leave the helpers installed. If your -distribution has trouble compiling the helpers, just copy the contents of the ``60crypt-ssh`` directory, less the -``helper`` directory and ``Makefile``, to the modules directory for Dracut. This will most likely be -``/usr/lib/dracut/modules.d/60crypt-ssh``. + The `dracut-crypt-ssh `_ module provides a straightforward + approach to configuring and launching an SSH server in Dracut images. This module is packaged on several distributions, + but if you run a distribution that does not package ``dracut-crypt-ssh``, you will need to track down its dependencies: + the ``dracut-network`` module for network access and ``dropbear`` for the SSH server; other prerequisites are probably + already installed on your system. -If you do not install the contents of ``helper``, you may wish to edit the ``module-setup.sh`` script provided by the -package to remove references to installing the helper. At the time of writing, these references consist of the last four -lines (five, if you count the harmless comment) of the ``install()`` functioned. Removing these lines should not be -critical, as Dracut should happily continue the initramfs creation process even if those installation commands fail. + .. note:: + The ``dracut-crypt-ssh`` module comes with a few helper utilities in the ``module/60crypt-ssh/helper`` directory that + are designed to simplify providing passwords and snooping console output so that you can interact with unlock processes + that are already running in the initramfs. These components are not required for ZFSBootMenu and do not provide a lot of + value. If you have no problems installing the module as intended, it is okay to leave the helpers installed. If your + distribution has trouble compiling the helpers, just copy the contents of the ``60crypt-ssh`` directory, except for the + ``helper`` directory and ``Makefile``, to the modules directory for Dracut. This will most likely be + ``/usr/lib/dracut/modules.d/60crypt-ssh``. -If you use Dracut to produce the initramfs images in your boot environment, you may wish to disable the ``crypt-ssh`` -module in those images. Just add + If you do not install the contents of ``helper``, you may wish to edit the ``module-setup.sh`` script provided by the + package to remove references to installing the helper. At the time of writing, these references consist of the last four + lines (five, if you count the harmless comment) of the ``install()`` functioned. Removing these lines should not be + critical, as Dracut should happily continue the initramfs creation process even if those installation commands fail. -.. code-block:: + If you use Dracut to produce the initramfs images in your boot environment, you may wish to disable the ``crypt-ssh`` + module in those images. Just add:: - omit_dracutmodules+=" crypt-ssh " + omit_dracutmodules+=" crypt-ssh " -to a configuration file in ``/etc/dracut.conf.d``. The configuration file must have a ``.conf`` extension to be -recognized; see `dracut.conf(5) `_ for more information. + to a configuration file in ``/etc/dracut.conf.d``. The configuration file must have a ``.conf`` extension to be + recognized; see :manpage:`dracut.conf(5)` for more information. -Configuring Dropbear in ZFSBootMenu -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + To inform ``dracut-network`` that it must bring up a network interface, pass the kernel command-line parameters + ``ip=dhcp`` and ``rd.neednet=1`` to your ZFSBootMenu image. If you use another boot loader to start ZFSBootMenu, *e.g.* + rEFInd or syslinux, this can be accomplished by configuring that loader. However, it may be more convenient to add these + parameters directly to the ZFSBootMenu image:: -By default, ``dracut-crypt-ssh`` will generate random host keys for your ZFSBootMenu initramfs. This is undesirable -because SSH will complain about unknown keys every time you reboot. If you wish, you can configure the module to copy -your regular host keys into the image. However, there are two problems with this: + mkdir -p /etc/cmdline.d + echo "ip=dhcp rd.neednet=1" > /etc/cmdline.d/dracut-network.conf -1. The ZFSBootMenu image will generally be installed on a filesystem with no access permissions, allowing anybody to - read your private host keys; and + It is possible to specify a static IP configuration by replacing ``dhcp`` with a properly formatted configuration + string. Consult the `dracut documentation `_ for details about + static IP configuration. -2. The ``dropbearconvert`` program may be incapable of converting modern OpenSSH host keys into the required dropbear - format. + There are methods besides writing to ``/etc/cmdline.d`` or configuring another boot loader to specify kernel + command-line arguments that will configure networking in Dracut. However, Dracut uses the ``/etc/cmdline.d`` directory + to store "fake" arguments, which it processes directly rather than handing to the kernel. Using other methods + (like adding these arguments to the ``kernel_cmdline`` Dracut option for a UEFI bundle) can cause the ``ip=dhcp`` + argument to appear more than once on the kernel command-line, which may cause ``dracut-network`` to fail + catastrophically and refuse to boot. Writing a configuration file in ``/etc/cmdline.d`` is a reliable way to ensure + that ``ip=dhcp`` appears exactly once to ``dracut-network``. -To create dedicated host keys in the proper format, decide on a location, for example ``/etc/dropbear``, and create the -new keys:: + .. group-tab:: mkinitcpio - mkdir -p /etc/dropbear - ssh-keygen -t rsa -m PEM -f /etc/dropbear/ssh_host_rsa_key - ssh-keygen -t ecdsa -m PEM -f /etc/dropbear/ssh_host_ecdsa_key + .. _remote-mkinitcpio-net: -The module expects to install RSA and ECDSA keys, so both types are created here. + If using :doc:`mkinitcpio ` to generate the ZFSBootMenu image, network access can be realized in several ways. -.. note:: + On some distributions, the `mkinitcpio-nfs-utils `_ package + provides a ``net`` module that allows the initramfs to parse ``ip=`` kernel command-line parameters. - When prompted for a passphrase when creating each host key, leave it blank. A non-empty password will prevent dropbear - from reading a key. - -To inform ``dracut-network`` that it must bring up a network interface, pass the kernel command-line parameters -``ip=dhcp`` and ``rd.neednet=1`` to your ZFSBootMenu image. If you use another boot loader to start ZFSBootMenu, *e.g.* -rEFInd or syslinux, this can be accomplished by configuring that loader. However, it may be more convenient to add these -parameters directly to the ZFSBootMenu image:: - - mkdir -p /etc/cmdline.d - echo "ip=dhcp rd.neednet=1" > /etc/cmdline.d/dracut-network.conf - -It is possible to specify a static IP configuration by replacing ``dhcp`` with a properly formatted configuration -string. Consult the `dracut documentation `_ for details about -static IP configuration. - -There are methods besides writing to ``/etc/cmdline.d`` or configuring another boot loader to specify kernel -command-line arguments that will configure networking in Dracut. However, Dracut uses the ``/etc/cmdline.d`` directory -to store "fake" arguments, which it processes directly rather than handing to the kernel. In my tests, using other -methods (like adding these arguments to the ``kernel_cmdline`` Dracut option for a UEFI bundle) can cause the -``ip=dhcp`` argument to appear more than once on the kernel command-line, which may cause ``dracut-network`` to fail -catastrophically and refuse to boot. Writing a configuration file in ``/etc/cmdline.d`` is a reliable way to ensure that -``ip=dhcp`` appears exactly once to ``dracut-network``. - -With critical pieces in place, ZFSBootMenu can be configured to bundle ``dracut-crypt-ssh`` in its images. Create the -Dracut configuration file ``/etc/zfsbootmenu/dracut.conf.d/dropbear.conf`` with the following contents:: - - # Enable dropbear ssh server and pull in network configuration args - add_dracutmodules+=" crypt-ssh " - install_optional_items+=" /etc/cmdline.d/dracut-network.conf " - # Copy system keys for consistent access - dropbear_rsa_key=/etc/dropbear/ssh_host_rsa_key - dropbear_ecdsa_key=/etc/dropbear/ssh_host_ecdsa_key - # User zbmuser is the authorized unlocker here - dropbear_acl=/home/zbmuser/.ssh/authorized_keys - -The last line is optional and assumes the user ``zbmuser`` should provide an ``authorized_keys`` file that will -determine remote access to the ZFSBootMenu image. The ``dracut-crypt-ssh`` module does not allow for password -authentication over SSH; instead, key-based authentication is forced. By default, the list of authorized keys is taken -from ``/root/.ssh/authorized_keys`` on the host. If you would prefer to use the ``authorized_keys`` file from another -user on your system, copy the above example and replace ``zbmuser`` with the name of the user whose ``authorized_keys`` -you wish to include. + If a static IP configuration is sufficient, the `mkinitcpio-rclocal `_ + module, which allows user scripts to be injected at several points in the initramfs boot process, provides a simple + mechanism for configuring a network interface. -.. note:: + .. tabs:: - The default configuration will start dropbear on TCP port 222. This can be overridden with the ``dropbear_port`` - configuration option. Generally, you do not want the server listening on the default port 22. Clients that expect to - find your normal host keys when connecting to an SSH server on port 22 will refuse to connect when they find different - keys provided by dropbear. + .. group-tab:: mkinitcpio-nfs-utils -Unless you've taken steps not described here, the network-enabled ZFSBootMenu image will not advertise itself via -dynamic DNS or mDNS. You will need to know the IP address of the ZFSBootMenu host to connect. Thus, you should either -configure a static IP address in ``/etc/cmdline.d/dracut-network.conf`` or configure your DHCP server to reserve a known -address for the MAC address of the network interface you configure for ``dracut-crypt-ssh``. + First, install ``mkinitcpio-nfs-utils``. -mkinitcpio ----------- + Then, to ensure that the ``net`` module is installed and run in the ZBM image, either append ``net`` to the array + defined on the ``HOOKS`` line in ``/etc/zfsbootmenu/mkinitcpio.conf`` or run:: -ZFSBootMenu also supports the `mkinitcpio `_ initramfs -generator used by Arch Linux. + sed -e '/HOOKS=/a HOOKS+=(net)' -i /etc/zfsbootmenu/mkinitcpio.conf -.. _remote-mkinitcpio-core: + Next, add an ``ip=`` parameter to ZFSBootMenu's kernel command-line. If you use another boot loader to start + ZFSBootMenu, *e.g.* rEFInd or syslinux, this can be accomplished by configuring that loader. If booting the EFI + bundle directly, this can be accomplished by configuring it in ``/etc/zfsbootmenu/config.yaml``, for example: -ZFSBootMenu Configuration Changes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. code-block:: yaml -Since `version 2.0.0 `_, ZFSBootMenu will install a standard -:zbm:`mkinitcpio.conf ` in the ``/etc/zfsbootmenu`` configuration directory. This file -is generally the same as a standard ``mkinitcpio.conf``, except some additional declarations may be added to control -aspects of the ``zfsbootmenu`` mkinitcpio module. The configuration file includes extensive inline documentation in the -form of comments; configuration options specific to ZFSBootMenu are also described in the -:ref:`zfsbootmenu(7) ` manual page. + Kernel: + CommandLine: "ro quiet loglevel=0 ip=:::::eth0:dhcp" -ZFSBootMenu still expects to use dracut by default. To override this behavior and instead use mkinitcpio, edit -``/etc/zfsbootmenu/config.yaml`` and add the following options: + .. note:: + For more details about the possible values for the ``ip=`` parameter, see the `net module documentation + `_. -.. code-block:: yaml + .. group-tab:: mkinitcpio-rclocal - Global: - InitCPIO: true - ## NOTE: The following three lines are OPTIONAL - InitCPIOHookDirs: - - /etc/zfsbootmenu/initcpio - - /usr/lib/initcpio + First, install ``mkinitcpio-rclocal``:: -.. note:: + curl -L https://github.com/ahesford/mkinitcpio-rclocal/archive/master.tar.gz | tar -zxvf - -C /tmp + mkdir -p /etc/zfsbootmenu/initcpio/{install,hooks} + cp /tmp/mkinitcpio-rclocal-master/rclocal_hook /etc/zfsbootmenu/initcpio/hooks/rclocal + cp /tmp/mkinitcpio-rclocal-master/rclocal_install /etc/zfsbootmenu/initcpio/install/rclocal + rm -r /tmp/mkinitcpio-rclocal-master - In the examples below, a couple of mkinitcpio modules will be installed to ``/etc/zfsbootmenu/initcpio`` to keep them - isolated from system-installed modules. To accommodate this non-standard installation, ``InitCPIOHookDirs`` must be - defined in ``/etc/zfsbootmenu/config.yaml``. Furthermore, because overriding the hook directory causes mkinitcpio to - ignore its default module path, the default ``/usr/lib/initcpio`` must be manually specified. If all hooks are - installed in ``/usr/lib/initcpio`` or ``/etc/initcpio``, the ZFSBootMenu configuration does **not** need to specify - ``InitCPIOHookDirs``. + Next, create an ``rc.local`` script that can be run within the mkinitcpio image to configure the ``eth0`` interface:: -Without further changes, running ``generate-zbm`` should now produce a ZBM image based on mkinitcpio rather than dracut, -although it will lack networking and remote-access capabilities. (By default, ``generate-zbm`` instructs mkinitcpio to -use the configuration at ``/etc/zfsbootmenu/config.yaml``, although this can be changed in the ``generate-zbm`` -configuration file.) For these features, some additional mkinitcpio modules and configuration changes are necessary. + cat > /etc/zfsbootmenu/initcpio/rc.local </dev/null 2>&1 || exit - HOOKS=(base udev autodetect modconf block filesystems keyboard) + # Bring up the interface + ip link set dev eth0 up -.. _remote-mkinitcpio-net: + # Configure a static address for this host + ip addr add 192.168.1.2/24 brd + dev eth0 + ip route add default via 192.168.1.1 -Basic Network Access -~~~~~~~~~~~~~~~~~~~~ + # Add some name servers + cat > /etc/resolv.conf <`_ package provides a -`net module `_ that allows the initramfs to parse ``ip=`` -directives from the kernel command line. When a static IP configuration is sufficient, the -`mkinitcpio-rclocal `_ module allows user scripts to be injected at -several points in the initramfs boot process and provides a simple mechanism for configuring a network interface. + .. note:: -When installing mkinitcpio modules that are not provided by a system package manager, it may be preferable to keep them -isolated from the ordinary module tree. Because this module will only be required in ZBM images, placing extra modules -in ``/etc/zfsbootmenu/initcpio`` is convenient:: + If your Ethernet interface is called something other than ``eth0`` or your static IP configuration is different, + adjust the script as needed. - curl -L https://github.com/ahesford/mkinitcpio-rclocal/archive/master.tar.gz | tar -zxvf - -C /tmp - mkdir -p /etc/zfsbootmenu/initcpio/{install,hooks} - cp /tmp/mkinitcpio-rclocal-master/rclocal_hook /etc/zfsbootmenu/initcpio/hooks/rclocal - cp /tmp/mkinitcpio-rclocal-master/rclocal_install /etc/zfsbootmenu/initcpio/install/rclocal - rm -r /tmp/mkinitcpio-rclocal-master + To ensure that the ``rclocal`` module is installed and run in the ZBM image, either append ``rclocal`` to the array + defined on the ``HOOKS`` line in ``/etc/zfsbootmenu/mkinitcpio.conf`` or run:: -Next, create an ``rc.local`` script that can be run within the mkinitcpio image to configure the ``eth0`` interface:: + sed -e '/HOOKS=/a HOOKS+=(rclocal)' -i /etc/zfsbootmenu/mkinitcpio.conf - cat > /etc/zfsbootmenu/initcpio/rc.local </dev/null 2>&1 || exit + echo 'rclocal_hook=/etc/zfsbootmenu/initcpio/rc.local' >> /etc/zfsbootmenu/mkinitcpio.conf - # Bring up the interface - ip link set dev eth0 up + Finally, make sure to include the ``ip`` executable in your initramfs image by manually adding ``ip`` to the + ``BINARIES`` array in ``/etc/zfsbootmenu/mkinitcpio.conf`` or by running:: - # Configure a static address for this host - ip addr add 192.168.1.2/24 brd + dev eth0 - ip route add default via 192.168.1.1 + sed -e '/BINARIES=/a BINARIES+=(ip)' -i /etc/zfsbootmenu/mkinitcpio.conf - # Add some name servers - cat > /etc/resolv.conf <<-EOF - nameserver 1.1.1.1 - nameserver 8.8.8.8 - EOF - RCEOF -.. note:: +Unless you've taken steps not described here, the network-enabled ZFSBootMenu image will not advertise itself via +dynamic DNS or mDNS. You will need to know the IP address of the ZFSBootMenu host to connect. Thus, you should either +configure a static IP address or configure your DHCP server to reserve a known address for the MAC address of the +network interface you configured. - If your Ethernet interface is called something other than ``eth0`` or your static IP configuration is different, - adjust the script as needed. +Configuring Dropbear +-------------------- -To ensure that the ``rclocal`` module is installed and run in the ZBM image, either append ``rclocal`` to the array -defined on the ``HOOKS`` line in ``/etc/zfsbootmenu/mkinitcpio.conf`` or run +First, install ``dropbear``, if not already installed. -.. code-block:: +By default, ``dropbear`` will generate random host keys for your ZFSBootMenu initramfs. This is undesirable because SSH +will complain about unknown keys every time you reboot. If you wish, you can configure it to copy your regular host keys +into the image. However, there are two problems with this: - sed -e '/HOOKS=/a HOOKS+=(rclocal)' -i /etc/zfsbootmenu/mkinitcpio.conf +1. The ZFSBootMenu image will generally be installed on a filesystem with no access permissions, allowing anybody to + read your private host keys; and -The ``rclocal`` module should be told where it can find the ``rc.local`` script to install and run by running:: +2. The ``dropbearconvert`` program may be incapable of converting modern OpenSSH host keys into the required dropbear + format. - echo 'rclocal_hook=/etc/zfsbootmenu/initcpio/rc.local' >> /etc/zfsbootmenu/mkinitcpio.conf +To create dedicated host keys in the proper format, decide on a location, for example ``/etc/dropbear``, and create the +new keys:: -Finally, make sure to include the ``ip`` executable in your initramfs image by manually adding ``ip`` to the -``BINARIES`` array in ``/etc/zfsbootmenu/mkinitcpio.conf`` or by running + mkdir -p /etc/dropbear + for keytype in rsa ecdsa ed25519; do + dropbearkey -t "${keytype}" -f "/etc/dropbear/dropbear_${keytype}_host_key" + done -.. code-block:: +.. note:: + The dracut module expects to install RSA and ECDSA keys, so at minimum those keys should be created. + The mkinitcpio module supports RSA, ECDSA, and ED25519 keys. - sed -e '/BINARIES=/a BINARIES+=(ip)' -i /etc/zfsbootmenu/mkinitcpio.conf + Not all versions of ``dropbear`` support ED25519 keys, so it is fine if the ED25519 key fails to generate. -.. _remote-mkinitcpio-dropbear: +The Dracut and mkinitcpio dropbear modules do not allow for password authentication over SSH; instead key-based +authentication is forced. The authorized keys for dropbear can be configured by putting an `authorized_keys file +`_ at ``/etc/dropbear/root_key``. On a single-user machine, this can be +realized by symlinking your user's ``authorized_keys`` file:: -Dropbear -~~~~~~~~ + ln -s "${HOME}/.ssh/authorized_keys" /etc/dropbear/root_key -Arch Linux provides a `mkinitcpio-dropbear `_ package -that provides a straightforward method for installing, configuring and running the dropbear SSH server inside a -mkinitcpio image. This package is based on a -`project of the same name `_ by an Arch Linux developer. A -`fork of the mkinitcpio-dropbear project `_ contains a few minor -improvements in runtime configuration and key management. If these improvements are not needed, using the upstream -project is perfectly acceptable. +.. tabs:: -Once again, the mkinitcpio module must first be downloaded and installed:: + .. group-tab:: Dracut - curl -L https://github.com/ahesford/mkinitcpio-dropbear/archive/master.tar.gz | tar -zxvf - -C /tmp - mkdir -p /etc/zfsbootmenu/initcpio/{install,hooks} - cp /tmp/mkinitcpio-dropbear-master/rclocal_hook /etc/zfsbootmenu/initcpio/hooks/dropbear - cp /tmp/mkinitcpio-dropbear-master/rclocal_install /etc/zfsbootmenu/initcpio/install/dropbear - rm -r /tmp/mkinitcpio-dropbear-master + With critical pieces in place, ZFSBootMenu can be configured to bundle ``dracut-crypt-ssh`` in its images. Create + the Dracut configuration file ``/etc/zfsbootmenu/dracut.conf.d/dropbear.conf`` with the following contents:: -The upstream ``dropbear`` module will attempt to copy host OpenSSH keys into ``/etc/dropbear`` if possible; otherwise, -it will generate random host keys. Both options are undesirable. Copying host keys will leave these protected files -directly accessible to anybody able to read a ZFSBootMenu image, which is probably every user on the system. Generating -unique keys with each run inhibits your ability to detect interlopers when you connect to your bootloader via SSH. My -fork will, by default, respect any existing dropbear keys available as ``/etc/dropbear/dropbear_*_host_key``. Therefore, -make some new host keys for use in your ZFSBootMenu image:: + # Enable dropbear ssh server and pull in network configuration args + add_dracutmodules+=" crypt-ssh " + install_optional_items+=" /etc/cmdline.d/dracut-network.conf " + # Copy system keys for consistent access + dropbear_rsa_key=/etc/dropbear/ssh_host_rsa_key + dropbear_ecdsa_key=/etc/dropbear/ssh_host_ecdsa_key + dropbear_acl=/etc/dropbear/root_key - mkdir -p /etc/dropbear - for keytype in rsa ecdsa ed25519; do - dropbearkey -t "${keytype}" -f "/etc/dropbear/dropbear_${keytype}_host_key" - done + .. note:: -The module also requires, at ``/etc/dropbear/root_key``, a set of authorized SSH keys that will be given access to the -``root`` account in the image. On a single-user system, it is sufficient to do:: + The default configuration will start dropbear on TCP port 222. This can be overridden with the ``dropbear_port`` + configuration option. Generally, you do not want the server listening on the default port 22. Clients that expect + to find your normal host keys when connecting to an SSH server on port 22 will refuse to connect when they find + different keys provided by dropbear. - ln -s ${HOME}/.ssh/authorized_keys /etc/dropbear/root_key + .. group-tab:: mkinitcpio -assuming that ``${HOME}`` points to the home directory of the user who should be given access to ZFSBootMenu. + .. _remote-mkinitcpio-dropbear: -Finally, enable the ``dropbear`` module in ``/etc/zfsbootmenu/mkinitcpio.conf`` by manually appending ``dropbear`` to -the ``HOOKS`` array, or by running:: + Arch Linux provides a `mkinitcpio-dropbear `_ + package that provides a straightforward method for installing, configuring and running the dropbear SSH server + inside a mkinitcpio image. This package is based on a `project of the same name + `_ by an Arch Linux developer. A `fork of the mkinitcpio-dropbear + project `_ contains a few minor improvements in runtime + configuration and key management. If these improvements are not needed, using the upstream project is perfectly + acceptable. - sed -e '/HOOKS.*rclocal/a HOOKS+=(dropbear)' -i /etc/zfsbootmenu/mkinitcpio.conf + First, download and install the mkinitcpio module:: + + curl -L https://github.com/ahesford/mkinitcpio-dropbear/archive/master.tar.gz | tar -zxvf - -C /tmp + mkdir -p /etc/zfsbootmenu/initcpio/{install,hooks} + cp /tmp/mkinitcpio-dropbear-master/dropbear_hook /etc/zfsbootmenu/initcpio/hooks/dropbear + cp /tmp/mkinitcpio-dropbear-master/dropbear_install /etc/zfsbootmenu/initcpio/install/dropbear + rm -r /tmp/mkinitcpio-dropbear-master + + Then, enable the ``dropbear`` module in ``/etc/zfsbootmenu/mkinitcpio.conf`` by manually appending ``dropbear`` to + the ``HOOKS`` array, or by running:: + + sed -e '/HOOKS.*rclocal/a HOOKS+=(dropbear)' -i /etc/zfsbootmenu/mkinitcpio.conf + + .. note:: + + The default configuration will start dropbear on TCP port 22. If using the ``ahesford/mkinitcpio-dropbear`` fork + recommended here, this can be overridden by defining ``dropbear_listen`` in ``/etc/dropbear/dropbear.conf``:: + + echo 'dropbear_listen=222' >> /etc/dropbear/dropbear.conf + + Generally, you do not want the server listening on the default port 22. Clients that expect to find your normal + host keys when connecting to an SSH server on port 22 will refuse to connect when they find different keys + provided by dropbear. Final Steps -~~~~~~~~~~~ +----------- With the above configuration complete, running ``generate-zbm`` should produce a ZFSBootMenu image that contains the necessary components to enable an SSH server in your bootloader. This can be verified with the ``lsinitrd`` tool provided by dracut or the ``lsinitcpio`` tool provided by mkinitcpio. (The ``lsinitcpio`` tool is not able to inspect UEFI bundles, but ``lsinitrd`` can.) In the file listing, you should see keys in ``/etc/dropbear``, the ``dropbear`` and -``ip`` executables, and the file ``root/.ssh/authorized_keys``. +``ip`` executables, and the file ``/root/.ssh/authorized_keys``. After rebooting, ZFSBootMenu should configure the network interface, launch an SSH server and accept connections on TCP -port 22 by default. If your SSH client complains because it finds ZFSBootMenu keys when it expects to find your normal -host keys, you may wish to reconfigure dropbear to listen on a non-standard port. My fork of ``mkinitcpio-dropbear`` -supports this by writing a ``dropbear_listen`` definition to ``/etc/dropbear/dropbear.conf``:: - - echo 'dropbear_listen=2222' > /etc/dropbear/dropbear.conf - -After writing this file (adjust ``2222`` to whatever port you prefer), re-run ``generate-zbm``, reboot and confirm that -dropbear listens where expected. +port 222 (for Dracut) or TCP port 22 (for mkinitcpio) by default, unless otherwise configured. If your SSH client +complains because it finds ZFSBootMenu keys when it expects to find your normal host keys, you may wish to reconfigure +dropbear to listen on a non-standard port and re-run ``generate-zbm``. Accessing ZFSBootMenu Remotely ------------------------------ @@ -321,7 +280,7 @@ You may then use the menu as if you were connected locally. .. note:: - recent versions of ZFSBootMenu automatically set the ``TERM`` environment variable to ``linux``. If you are running an + Recent versions of ZFSBootMenu automatically set the ``TERM`` environment variable to ``linux``. If you are running an older version, your SSH client may have provided a more specific terminal definition that will not be recognized by the restricted environment provided by ZFSBootMenu. Under these circumstances, you may need to run:: From e43b194ac2fcb3260f7f0c5ff19bd4e8e34a4d8d Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Tue, 1 Aug 2023 19:21:30 -0500 Subject: [PATCH 12/33] docs/guides/: limit pool features Since binary releases are out of sync with what users have installed on their system, start setting feature flag compatibility masks to match what the current ZFSBootMenu binary releases ships. --- docs/guides/_include/pool-creation.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/guides/_include/pool-creation.rst b/docs/guides/_include/pool-creation.rst index e584da047..df7d12926 100644 --- a/docs/guides/_include/pool-creation.rst +++ b/docs/guides/_include/pool-creation.rst @@ -16,6 +16,7 @@ Create the zpool -O xattr=sa \ -O relatime=on \ -o autotrim=on \ + -o compatibility=openzfs-2.1-linux \ -m none zroot "$POOL_DEVICE" .. group-tab:: Encrypted @@ -36,6 +37,7 @@ Create the zpool -O keylocation=file:///etc/zfs/zroot.key \ -O keyformat=passphrase \ -o autotrim=on \ + -o compatibility=openzfs-2.1-linux \ -m none zroot "$POOL_DEVICE" .. note:: @@ -51,3 +53,9 @@ Create the zpool * ``keyformat=passphrase`` - By setting the format to ``passphrase``, we can now force a prompt for this in ``zfsbootmenu``. It's critical that your passphrase be something you can type on your keyboard, since you will need to type it in to unlock the pool on boot. + +.. note:: + + The option ``-o compatibility=openzfs-2.1-linux`` ensures that the pool is created only with feature flags supported by the current ZFSBootMenu binary release. If you plan on building a custom ZFSBootMenu image that you will keep synchronized with your host, the compatibility option may be omitted. + + Binary releases of ZFSBootMenu are generally built with the latest stable version of ZFS. Future releases of ZFSBootMenu may therefore support newer feature sets. Check project release notes prior to updating or removing `compatibility` options and upgrading your system pool. From d00ffe6858000bfe544bcaaadd989adeeb809172 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Thu, 17 Aug 2023 12:08:05 -0500 Subject: [PATCH 13/33] docs: update list of known-good distributions --- docs/index.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 9b96f1bf8..cce7151b8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -130,15 +130,17 @@ will prompt the user to enter a passphrase as necessary. Distribution Agnostic --------------------- -ZFSBootMenu is capable of booting just about any Linux distribution. Major distributions that are known to boot without +ZFSBootMenu is capable of booting just about any Linux distribution. Distributions that are known to boot without requiring any special configuration include: * Void -* Arch +* Chimera * Alpine +* openSUSE (Leap, Tumbleweed) * Gentoo * Fedora * Debian and its descendants (Ubuntu, Linux Mint, Devuan, etc.) +* Arch Red Hat and its descendants (RHEL, CentOS, etc.) are expected to work as well but have never been tested. From 21456e7809a5277840eb0f2283ec9292c7ddbc5b Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Fri, 8 Sep 2023 16:28:19 -0500 Subject: [PATCH 14/33] docs/guides/: code golf an export --- docs/guides/_include/os-release.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/_include/os-release.rst b/docs/guides/_include/os-release.rst index bfdec04b5..233fb9747 100644 --- a/docs/guides/_include/os-release.rst +++ b/docs/guides/_include/os-release.rst @@ -7,7 +7,7 @@ defined within can be used as a short name for the filesystem that will hold thi .. code-block:: source /etc/os-release - export ID="$ID" + export ID .. vim: softtabstop=2 shiftwidth=2 textwidth=120 From aed2c87b344202470917784f6f3cc9a81ba251d4 Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Tue, 12 Sep 2023 04:31:23 -0400 Subject: [PATCH 15/33] docs/guides/general/tailscale: add tailscale integration guide --- docs/guides/general.rst | 1 + docs/guides/general/tailscale.rst | 78 +++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) create mode 100644 docs/guides/general/tailscale.rst diff --git a/docs/guides/general.rst b/docs/guides/general.rst index 70b998f44..9c8da50e9 100644 --- a/docs/guides/general.rst +++ b/docs/guides/general.rst @@ -10,6 +10,7 @@ General general/uefi-booting general/mkinitcpio general/remote-access + general/tailscale general/portable .. diff --git a/docs/guides/general/tailscale.rst b/docs/guides/general/tailscale.rst new file mode 100644 index 000000000..ddfa81976 --- /dev/null +++ b/docs/guides/general/tailscale.rst @@ -0,0 +1,78 @@ +Tailscale Integration +===================== + +Sometimes direct remote access to ZFSBootMenu is not possible, like when a computer using ZFSBootMenu is behind a +firewall or inside a private network. Adding `Tailscale `_ support to ZFSBootMenu can help +bridge this gap. + +Prerequisites +------------- + +Presently, the only known and recommended initramfs module for Tailscale integration is +`mkinitcpio-tailscale `_, so this guide requires using +:doc:`mkinitcpio ` to generate the ZFSBootMenu image. + +:doc:`Remote access ` should also be set up before following this guide. + +Because the Tailscale node key is stored in the initramfs, it should not use the same one as the host system. To ensure +this key is useless to anyone trying to access the connected Tailnet, +`Tailscale ACLs `_ should be used to restrict any ZFSBootMenu Tailscale nodes +from connecting to any other node in the Tailnet. For example: + +.. code-block:: json + + // Example ACLs for mkinitcpio-tailscale and ZFSBootMenu + { + "tagOwners": { + "tag:zfsbootmenu": ["autogroup:admin"], + "tag:local": ["autogroup:admin"], + }, + + "acls": [ + {"action": "accept", "src": ["tag:local"], "dst": ["*:*"]}, + ], + } + +In this example, nodes with ``tag:local`` can connect to any node in the Tailnet, but because there is no rule with +``tag:zfsbootmenu`` as the source, it cannot initiate any connections, rendering it fairly useless if compromised. + +Setup +----- + +First, generate an `auth key `_ and save it to ``/tmp/zbm-ts-authkey``. +The recommended settings for this key are: + +- **not** reusable +- **1 day** expiration +- **not** ephemeral +- tagged with the relevant ACL tag (``tag:zfsbootmenu`` if using ACLs like the example above) + +Once used to generate the necessary information, this key is no longer needed and can be revoked or expired safely. + +Next, install `mkinitcpio-tailscale `_. This is available as a +package on Void Linux. If not available as a package, it can be installed manually:: + + curl -L https://github.com/classabbyamp/mkinitcpio-tailscale/archive/master.tar.gz | tar -zxvf - -C /tmp + mkdir -p /etc/zfsbootmenu/initcpio/{install,hooks} + cp /tmp/mkinitcpio-tailscale-master/tailscale_hook /etc/zfsbootmenu/initcpio/hooks/tailscale + cp /tmp/mkinitcpio-tailscale-master/tailscale_install /etc/zfsbootmenu/initcpio/install/tailscale + rm -r /tmp/mkinitcpio-tailscale-master + +To generate the node key for ZFSBootMenu's Tailscale node:: + + mkinitcpio-tailscale-setup -k /tmp/zbm-ts-authkey + +Once it runs successfully, you should see a machine in the +`Tailscale admin console `_ with the name ``-mkinitcpio`` +and the ACL tag ``tag:zfsbootmenu``. + +Then, enable the ``tailscale`` module in ``/etc/zfsbootmenu/mkinitcpio.conf`` by manually appending ``tailscale`` to +the ``HOOKS`` array, or by running:: + + sed -e '/HOOKS.*dropbear/a HOOKS+=(tailscale)' -i /etc/zfsbootmenu/mkinitcpio.conf + +With the above configuration complete, running ``generate-zbm`` should produce a ZFSBootMenu image that contains the +necessary components to enable SSH access over Tailscale in your bootloader. + +After rebooting, ZFSBootMenu should configure the network interface, launch an SSH server, and connect to Tailscale. +Connection to ZFSBootMenu should be possible using either the local IP, Tailscale IP, or Tailscale hostname. From d03f9de7c27cdc2ec8b1f6d81fe9356d0e5cc15e Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Fri, 8 Sep 2023 09:42:12 -0400 Subject: [PATCH 16/33] Add dm-crypt to recovery images, so cryptsetup works Fixes: #468. --- etc/zfsbootmenu/recovery.conf.d/recovery.conf | 1 + 1 file changed, 1 insertion(+) diff --git a/etc/zfsbootmenu/recovery.conf.d/recovery.conf b/etc/zfsbootmenu/recovery.conf.d/recovery.conf index c372c8c65..5af6a77f7 100644 --- a/etc/zfsbootmenu/recovery.conf.d/recovery.conf +++ b/etc/zfsbootmenu/recovery.conf.d/recovery.conf @@ -9,6 +9,7 @@ install_optional_items+=" /bin/efibootmgr " # LUKS control install_optional_items+=" /bin/cryptsetup " +add_drivers+=" dm-crypt " # Networking install_optional_items+=" /bin/ip /bin/curl /bin/dhclient /sbin/dhclient-script /bin/ssh " From bf207286269335b416278b37baa88229c27d9cfb Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Thu, 7 Sep 2023 09:19:01 -0500 Subject: [PATCH 17/33] zfsbootmenu: make 'less' an optional binary 'less' is only used by debug logging viewer, so there's no need to refuse to build an image if the host system doesn't have that binary available. --- zfsbootmenu/install-helpers.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/zfsbootmenu/install-helpers.sh b/zfsbootmenu/install-helpers.sh index d10fd6874..71701ec92 100644 --- a/zfsbootmenu/install-helpers.sh +++ b/zfsbootmenu/install-helpers.sh @@ -34,7 +34,6 @@ zfsbootmenu_essential_binaries=( "lsmod" "depmod" "dmesg" - "less" "fzf" "setsid" ) @@ -43,6 +42,7 @@ zfsbootmenu_essential_binaries=( zfsbootmenu_optional_binaries=( "mbuffer" "column" + "less" ) # shellcheck disable=SC2034 From ee0043c2b2bc569fc00aeef22b117f8bcd822629 Mon Sep 17 00:00:00 2001 From: classabbyamp Date: Wed, 13 Sep 2023 23:40:19 -0400 Subject: [PATCH 18/33] docs/guides/general/tailscale: mention tailscale ssh not as good as dropbear, IMO, but worth mentioning I guess --- docs/guides/general/tailscale.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/guides/general/tailscale.rst b/docs/guides/general/tailscale.rst index ddfa81976..e9673c68f 100644 --- a/docs/guides/general/tailscale.rst +++ b/docs/guides/general/tailscale.rst @@ -12,7 +12,9 @@ Presently, the only known and recommended initramfs module for Tailscale integra `mkinitcpio-tailscale `_, so this guide requires using :doc:`mkinitcpio ` to generate the ZFSBootMenu image. -:doc:`Remote access ` should also be set up before following this guide. +:doc:`Remote access ` should also be set up before following this guide, though the SSH server can +be either Dropbear from that guide or `Tailscale's built-in SSH server `_. +Note that if using Tailscale's SSH server, remote access will only be possible via Tailscale, not the local network. Because the Tailscale node key is stored in the initramfs, it should not use the same one as the host system. To ensure this key is useless to anyone trying to access the connected Tailnet, @@ -71,8 +73,13 @@ the ``HOOKS`` array, or by running:: sed -e '/HOOKS.*dropbear/a HOOKS+=(tailscale)' -i /etc/zfsbootmenu/mkinitcpio.conf +If using Tailscale SSH instead of Dropbear, add the necessary flags to ``/etc/tailscale/tailscaled.conf``:: + + tailscale_args="--ssh" + With the above configuration complete, running ``generate-zbm`` should produce a ZFSBootMenu image that contains the necessary components to enable SSH access over Tailscale in your bootloader. After rebooting, ZFSBootMenu should configure the network interface, launch an SSH server, and connect to Tailscale. -Connection to ZFSBootMenu should be possible using either the local IP, Tailscale IP, or Tailscale hostname. +Connection to ZFSBootMenu should be possible using either the local IP (if using Dropbear), Tailscale IP, or Tailscale +hostname. From b6776bc4209d5dd42cbda6a292692f596050c4c0 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Tue, 19 Sep 2023 16:15:26 -0500 Subject: [PATCH 19/33] docs/guides/: remove Debian 11 guide Debian 12 has been out long enough. Debian 11's ZFS is old enough that it doesn't understand the `compatibility` pool property, which would require duplicating the entire pool creation document. Instead, lets kick Debian 11 to the curb. Closes #489 --- docs/guides/debian.rst | 1 - docs/guides/debian/bullseye-uefi.rst | 48 ---------------------------- 2 files changed, 49 deletions(-) delete mode 100644 docs/guides/debian/bullseye-uefi.rst diff --git a/docs/guides/debian.rst b/docs/guides/debian.rst index 2d6f41f75..466deb458 100644 --- a/docs/guides/debian.rst +++ b/docs/guides/debian.rst @@ -4,5 +4,4 @@ Debian .. toctree:: :titlesonly: - debian/bullseye-uefi debian/bookworm-uefi diff --git a/docs/guides/debian/bullseye-uefi.rst b/docs/guides/debian/bullseye-uefi.rst deleted file mode 100644 index 7ca541412..000000000 --- a/docs/guides/debian/bullseye-uefi.rst +++ /dev/null @@ -1,48 +0,0 @@ -Bullseye (11) UEFI -================== - -.. |distribution| replace:: debian - -.. contents:: Contents - :depth: 2 - :local: - :backlinks: none - -This guide can be used to install Debian onto a single disk with or without ZFS encryption. - -It assumes the following: - -* Your system uses UEFI to boot -* Your system is x86_64 -* You're mildly comfortable with ZFS, EFI and discovering system facts on your own (``lsblk``, ``dmesg``, ``gdisk``, ...) - -Download the latest `Debian Bullseye (11) Live image `_, write it to a USB drive and -boot your system in EFI mode. - -.. include:: ../_include/efi-boot-check.rst - -.. include:: _include/bullseye/live-environment.rst - -.. include:: ../_include/define-env.rst - -.. include:: ../_include/disk-preparation.rst - -.. include:: ../_include/pool-creation.rst - -.. include:: ../_include/create-filesystems.rst - -.. include:: ../_include/update-devices.rst - -.. include:: _include/bullseye/distro-install.rst - -.. include:: _include/zfs-config.rst - -.. include:: ../_include/zbm-setup.rst - -.. include:: ../_include/setup-esp.rst - -.. include:: _include/zbm-install.rst - -.. include:: _include/efi-boot-method.rst - -.. include:: ../_include/cleanup.rst From 908eb29547680cc128bd4f48afca774f5dbcaba5 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Wed, 4 Oct 2023 13:02:02 -0500 Subject: [PATCH 20/33] docs/guides/debian/: add curl as a source install dep --- docs/guides/debian/_include/zbm-install-deps.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/guides/debian/_include/zbm-install-deps.rst b/docs/guides/debian/_include/zbm-install-deps.rst index 5e9c040fd..17981fb7f 100644 --- a/docs/guides/debian/_include/zbm-install-deps.rst +++ b/docs/guides/debian/_include/zbm-install-deps.rst @@ -8,6 +8,7 @@ Install all packages required to build a ZFSBootMenu image on Debian: libyaml-pp-perl \ git \ fzf \ + curl \ mbuffer \ kexec-tools \ dracut-core \ From 88bc09f1ccc8128b07b0fb959765a27f6c022513 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Tue, 10 Oct 2023 16:24:42 -0400 Subject: [PATCH 21/33] docs/: fix requirements for Python 3.12 --- docs/requirements.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/requirements.txt b/docs/requirements.txt index 711f0da6f..bb39bdab7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -3,3 +3,4 @@ sphinx-tabs sphinx-rtd-theme>=1.1.1 sphinx-copybutton recommonmark +setuptools From 22af4587909822b8fb1ecf68015888c056a84315 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Fri, 13 Oct 2023 07:44:57 -0400 Subject: [PATCH 22/33] docs/guides/alpine: zfs-scripts is required for compatibility property --- docs/guides/alpine/_include/live-environment.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/alpine/_include/live-environment.rst b/docs/guides/alpine/_include/live-environment.rst index 6ba4e4e3f..6fbd9cbb2 100644 --- a/docs/guides/alpine/_include/live-environment.rst +++ b/docs/guides/alpine/_include/live-environment.rst @@ -19,7 +19,7 @@ Setup additional tools .. code-block:: - apk add zfs sgdisk wipefs + apk add zfs zfs-scripts sgdisk wipefs modprobe zfs .. include:: ../_include/zgenhostid.rst From 65286495ae1f9c17c2c3bfdd350e5ff93358d194 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Tue, 30 May 2023 13:18:51 -0500 Subject: [PATCH 23/33] zfsbootmenu-help: use cat in place of less less-633, when invoked under fzf as a preview helper, does not render any text. The previously known-good version of less was 608. Advanced functionality such as searching or paging is not needed or even functional in fzf. GNU cat and Busybox cat preserve embedded ansi color styling. --- zfsbootmenu/install-helpers.sh | 1 + zfsbootmenu/libexec/zfsbootmenu-help | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/zfsbootmenu/install-helpers.sh b/zfsbootmenu/install-helpers.sh index 71701ec92..c842816f4 100644 --- a/zfsbootmenu/install-helpers.sh +++ b/zfsbootmenu/install-helpers.sh @@ -36,6 +36,7 @@ zfsbootmenu_essential_binaries=( "dmesg" "fzf" "setsid" + "cat" ) # shellcheck disable=SC2034 diff --git a/zfsbootmenu/libexec/zfsbootmenu-help b/zfsbootmenu/libexec/zfsbootmenu-help index 6292a36a7..8e1bd53e1 100755 --- a/zfsbootmenu/libexec/zfsbootmenu-help +++ b/zfsbootmenu/libexec/zfsbootmenu-help @@ -80,7 +80,7 @@ while getopts "lL:s:" opt; do exit ;; s) - less -f -n -r "${OPTARG}" + cat "${OPTARG}" exit ;; ?) From 7532d1f08d781247d2763200187d651945ae4962 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Mon, 5 Jun 2023 13:20:54 -0500 Subject: [PATCH 24/33] zfsbootmenu: protect stdout of main interface fzf forces us to capture stdout to know which key combination was pressed and which item was selected. A bug has been lurking for ages: * Hit mod-l on the main screen to see the warning/error log * Hit enter to select whatever is shown * Hit mod-p to look at the pool status screen When the sub fzf instance used to draw logs exits with a selection (e.g. with the enter key), it writes that to stdout. Then when the lower level fzf instance exits (e.g. the main menu screen) with a selection, stdout from both instances is captured by the subshell. This solution protects against that by discarding stdout from all of the sub-instances of fzf. --- zfsbootmenu/lib/fzf-defaults.sh | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/zfsbootmenu/lib/fzf-defaults.sh b/zfsbootmenu/lib/fzf-defaults.sh index 79dc5a176..0165a7172 100755 --- a/zfsbootmenu/lib/fzf-defaults.sh +++ b/zfsbootmenu/lib/fzf-defaults.sh @@ -9,12 +9,12 @@ fuzzy_default_options=( "--ansi" "--no-clear" "--cycle" "--color=16" "--layout=reverse-list" "--inline-info" "--tac" - "--bind" '"alt-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} ]"' - "--bind" '"ctrl-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} ]"' - "--bind" '"ctrl-alt-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} ]"' - "--bind" "\"alt-l:execute[ /bin/zlogtail ]${HAS_REFRESH:++refresh-preview}\"" - "--bind" "\"ctrl-l:execute[ /bin/zlogtail ]${HAS_REFRESH:++refresh-preview}\"" - "--bind" "\"ctrl-alt-l:execute[ /bin/zlogtail ]${HAS_REFRESH:++refresh-preview}\"" + "--bind" '"alt-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} 1>/dev/null ]"' + "--bind" '"ctrl-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} 1>/dev/null ]"' + "--bind" '"ctrl-alt-h:execute[ /libexec/zfsbootmenu-help -L ${HELP_SECTION:-main-screen} 1>/dev/null ]"' + "--bind" "\"alt-l:execute[ /bin/zlogtail 1>/dev/null ]${HAS_REFRESH:++refresh-preview}\"" + "--bind" "\"ctrl-l:execute[ /bin/zlogtail 1>/dev/null ]${HAS_REFRESH:++refresh-preview}\"" + "--bind" "\"ctrl-alt-l:execute[ /bin/zlogtail 1>/dev/null ]${HAS_REFRESH:++refresh-preview}\"" ) if [ -n "${HAS_BORDER}" ]; then From d6f763b47116e594239b009a24cc7b2eba5a337d Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Mon, 31 Jul 2023 23:32:19 -0400 Subject: [PATCH 25/33] releng/tag-release.sh: relax branch requirement --- releng/tag-release.sh | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/releng/tag-release.sh b/releng/tag-release.sh index 77db6e551..b508659ee 100755 --- a/releng/tag-release.sh +++ b/releng/tag-release.sh @@ -23,10 +23,18 @@ if [ ! -e bin/generate-zbm ] || [ ! -e docs/CHANGELOG.md ]; then error "ERROR: run this script from the root of the zfsbootmenu tree" fi -# Only tag releases from master -if [ "$(git rev-parse --abbrev-ref HEAD)" != "master" ]; then - error "ERROR: will not tag releases on any branch but master" -fi +# Only tag releases from master or a compatible release-tracking branch +case "$(git rev-parse --abbrev-ref HEAD)" in + master) + echo "Tagging release from master branch" + ;; + "v${release%.*}.x"|"v${release%%.*}.x") + echo "Tagging release from version-tracking branch" + ;; + *) + error "ERROR: attempt to tag release on incompatible branch" + ;; +esac # Only allow changes to CHANGELOG.md when tagging releases # shellcheck disable=SC2143 From 5edc02f02ba8215f728806b50c328262190f8950 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Tue, 19 Sep 2023 20:14:28 -0400 Subject: [PATCH 26/33] docs/Makefile: man generation fails unless html docs are built first --- docs/Makefile | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/Makefile b/docs/Makefile index 4bf1f5ceb..1c627086f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -69,5 +69,8 @@ $(VENV)/req_done: requirements.txt $(VENV)/success $(VENV)/bin/pip install $(PIP_FLAGS) -U -r requirements.txt @touch $(VENV)/req_done +# Man-page generation fails unless HTML documentation is built first +man:: html + %:: Makefile @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) From 09e4d760ab2acd9c926b936376c4bf9de0378dd4 Mon Sep 17 00:00:00 2001 From: "Wesley H. Gimenes" Date: Thu, 5 Oct 2023 03:54:18 -0300 Subject: [PATCH 27/33] docs/man/zfsbootmenu: fix typo Signed-off-by: Wesley H. Gimenes Closes: #497 [via git-merge-pr] --- docs/man/zfsbootmenu.7.rst | 2 +- zfsbootmenu/help-files/132/zfsbootmenu.7.ansi | 2 +- zfsbootmenu/help-files/52/zfsbootmenu.7.ansi | 2 +- zfsbootmenu/help-files/92/zfsbootmenu.7.ansi | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/man/zfsbootmenu.7.rst b/docs/man/zfsbootmenu.7.rst index 0b89d83d3..f620ef52c 100644 --- a/docs/man/zfsbootmenu.7.rst +++ b/docs/man/zfsbootmenu.7.rst @@ -65,7 +65,7 @@ These options are set on the kernel command line when booting the initramfs or U .. code-block:: - echo 0 > /sys/module/spl/paramters/spl_hostid + echo 0 > /sys/module/spl/parameters/spl_hostid **zbm.sort_key** diff --git a/zfsbootmenu/help-files/132/zfsbootmenu.7.ansi b/zfsbootmenu/help-files/132/zfsbootmenu.7.ansi index 890caade6..224d43c52 100644 --- a/zfsbootmenu/help-files/132/zfsbootmenu.7.ansi +++ b/zfsbootmenu/help-files/132/zfsbootmenu.7.ansi @@ -81,7 +81,7 @@ Setting spl.spl_hostid to a non-zero value on the kernel commandline will make the ZFS kernel modules ignore any value set in /etc/hostid. To restore standard ZFS behavior on a running system, execute - echo 0 > /sys/module/spl/paramters/spl_hostid + echo 0 > /sys/module/spl/parameters/spl_hostid zbm.sort_key diff --git a/zfsbootmenu/help-files/52/zfsbootmenu.7.ansi b/zfsbootmenu/help-files/52/zfsbootmenu.7.ansi index 9b3806b54..5d87692cf 100644 --- a/zfsbootmenu/help-files/52/zfsbootmenu.7.ansi +++ b/zfsbootmenu/help-files/52/zfsbootmenu.7.ansi @@ -143,7 +143,7 @@ standard ZFS behavior on a running system, execute - echo 0 > /sys/module/spl/paramters/spl_hostid + echo 0 > /sys/module/spl/parameters/spl_hostid zbm.sort_key diff --git a/zfsbootmenu/help-files/92/zfsbootmenu.7.ansi b/zfsbootmenu/help-files/92/zfsbootmenu.7.ansi index 122f00478..f7af8b4db 100644 --- a/zfsbootmenu/help-files/92/zfsbootmenu.7.ansi +++ b/zfsbootmenu/help-files/92/zfsbootmenu.7.ansi @@ -95,7 +95,7 @@ ZFS kernel modules ignore any value set in /etc/hostid. To restore standard ZFS behavior on a running system, execute - echo 0 > /sys/module/spl/paramters/spl_hostid + echo 0 > /sys/module/spl/parameters/spl_hostid zbm.sort_key From 7b3dcc12a56e045a3f2a111c6c4839f09699e190 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Tue, 30 May 2023 21:36:24 -0500 Subject: [PATCH 28/33] zfs-chroot: add read-write prompt When entering a chroot for a regular dataset and the pool is read-only, provide a timed_prompt that lets the user choose between entering a read-only chroot (return key/enter key) or a read-write chroot (escape key). If the dataset is a snapshot or the pool is already read-write, do not show the prompt. Fixes #428 --- zfsbootmenu/bin/zfs-chroot | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/zfsbootmenu/bin/zfs-chroot b/zfsbootmenu/bin/zfs-chroot index b02b74e1a..8e4966f88 100755 --- a/zfsbootmenu/bin/zfs-chroot +++ b/zfsbootmenu/bin/zfs-chroot @@ -33,14 +33,24 @@ selected="${1}" zdebug "started with ${selected}" [ -n "${selected}" ] || exit 0 +pool="${selected%%/*}" + +if ! is_snapshot "${selected}" && ! is_writable "${pool}" ; then + if ! timed_prompt -d 10 \ + -e "Enter r/w chroot" \ + -r "Enter r/o chroot" \ + -p "Entering chroot in $( colorize yellow "%0.2d" ) seconds" ; then + set_rw_pool "${pool}" + fi +fi + +clear if ! mountpoint="$( allow_rw=yes mount_zfs "${selected}" )"; then zerror "failed to mount ${selected}" exit 1 fi -pool="${selected%%/*}" - # Snapshots and read-only pools always produce read-only mounts if is_snapshot "${selected}" || ! is_writable "${pool}"; then writemode="$( colorize green "read-only")" From e4102eea7a7baaaf55e00983693b761681e6aaa6 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Fri, 16 Jun 2023 10:18:10 -0500 Subject: [PATCH 29/33] zfs-chroot: load keys again after setting pool r/w --- zfsbootmenu/bin/zfs-chroot | 1 + 1 file changed, 1 insertion(+) diff --git a/zfsbootmenu/bin/zfs-chroot b/zfsbootmenu/bin/zfs-chroot index 8e4966f88..c0cd264b4 100755 --- a/zfsbootmenu/bin/zfs-chroot +++ b/zfsbootmenu/bin/zfs-chroot @@ -41,6 +41,7 @@ if ! is_snapshot "${selected}" && ! is_writable "${pool}" ; then -r "Enter r/o chroot" \ -p "Entering chroot in $( colorize yellow "%0.2d" ) seconds" ; then set_rw_pool "${pool}" + CLEAR_SCREEN=1 load_key "${selected}" fi fi From ecef4ac3fd48ae23462a43d00f499bd44673de47 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Fri, 13 Oct 2023 14:33:18 -0400 Subject: [PATCH 30/33] docs/CHANGELOG: describe v2.2.1 --- docs/CHANGELOG.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index f6e92234a..f696f1364 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,5 +1,21 @@ # Changelog +## ZFSBootMenu v2.2.1 (2023-10-13) + +ZFSBootMenu v2.2.1 offers a few minor bug fixes over the prior release. More significantly, the build-container images and release assets for this version include OpenZFS 2.2.0 to provide access to upgraded pools. + +All users of the binary releases or the ZFSBootMenu build container are encouraged to update to ZFSBootMenu v2.2.1 before upgrading any ZFS pools. + +### Significant commits in this release +* e4102ee - zfs-chroot: load keys again after setting pool r/w (Zach Dykstra) +* 7b3dcc1 - zfs-chroot: add read-write prompt (Zach Dykstra) +* 09e4d76 - docs/man/zfsbootmenu: fix typo (Wesley H. Gimenes) +* 7532d1f - zfsbootmenu: protect stdout of main interface (Zach Dykstra) +* 6528649 - zfsbootmenu-help: use cat in place of less (Zach Dykstra) +* bf20728 - zfsbootmenu: make 'less' an optional binary (Zach Dykstra) +* d03f9de - Add dm-crypt to recovery images, so cryptsetup works (Andrew J. Hesford) +* b212b23 - zbm-builder.sh: add mount-options argument, document use (Andrew Gunnerson) + ## ZFSBootMenu v2.2.0 (2023-05-21) Perhaps the most significant change in ZFSBootMenu v2.2.0 is an overhaul of the project documentation. We are thrilled to welcome new member @classabbyamp to the project, who oversaw this substantial effort. Disparate documentation previously stored in Markdown files, the GitHub Wiki, POD files, and another git repository have now been combined into a single tree that is published on Read The Docs. The documentation is now maintained as an integral part of this repository and is published at https://docs.zfsbootmenu.org/. This includes: From 0e8ffed944800536bee7fb73bf1380b84cf2b1aa Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Fri, 13 Oct 2023 14:51:12 -0400 Subject: [PATCH 31/33] zfsbootmenu/bin/zfs-chroot: use tput to reset/clear screen --- zfsbootmenu/bin/zfs-chroot | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/zfsbootmenu/bin/zfs-chroot b/zfsbootmenu/bin/zfs-chroot index c0cd264b4..5e8a7ea1b 100755 --- a/zfsbootmenu/bin/zfs-chroot +++ b/zfsbootmenu/bin/zfs-chroot @@ -45,7 +45,8 @@ if ! is_snapshot "${selected}" && ! is_writable "${pool}" ; then fi fi -clear +tput reset +tput clear if ! mountpoint="$( allow_rw=yes mount_zfs "${selected}" )"; then zerror "failed to mount ${selected}" From 7895ef5c1198c5f3e55c0f1ba6d483669ae9e2e7 Mon Sep 17 00:00:00 2001 From: Zach Dykstra Date: Fri, 13 Oct 2023 14:06:20 -0500 Subject: [PATCH 32/33] Bump to version 2.2.1 --- bin/generate-zbm | 2 +- docs/conf.py | 2 +- docs/man/dist/man5/generate-zbm.5 | 2 +- docs/man/dist/man7/zfsbootmenu.7 | 4 ++-- docs/man/dist/man8/generate-zbm.8 | 2 +- docs/man/dist/man8/zbm-kcl.8 | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/bin/generate-zbm b/bin/generate-zbm index bd1fe3015..cb2ce5fb3 100755 --- a/bin/generate-zbm +++ b/bin/generate-zbm @@ -4,7 +4,7 @@ use strict; use warnings; -our $VERSION = '2.2.0'; +our $VERSION = '2.2.1'; use Getopt::Long qw(:config no_ignore_case auto_version); use Pod::Usage qw(pod2usage); diff --git a/docs/conf.py b/docs/conf.py index f4b05fb48..7a1d6ea59 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,7 +10,7 @@ author = 'ZFSBootMenu Team' man_author = f'{author} ' copyright = f'2019 Zach Dykstra, 2020-2023 {author}' -release = '2.2.0' +release = '2.2.1' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/docs/man/dist/man5/generate-zbm.5 b/docs/man/dist/man5/generate-zbm.5 index 590ea1732..45bac3dce 100644 --- a/docs/man/dist/man5/generate-zbm.5 +++ b/docs/man/dist/man5/generate-zbm.5 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "GENERATE-ZBM" "5" "2023-05-21" "" "ZFSBootMenu" +.TH "GENERATE-ZBM" "5" "2023-10-13" "" "ZFSBootMenu" .SH NAME generate-zbm \- configuration file for generate-zbm .SH SYNOPSIS diff --git a/docs/man/dist/man7/zfsbootmenu.7 b/docs/man/dist/man7/zfsbootmenu.7 index ab3bbc164..022cd0c82 100644 --- a/docs/man/dist/man7/zfsbootmenu.7 +++ b/docs/man/dist/man7/zfsbootmenu.7 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ZFSBOOTMENU" "7" "2023-05-21" "" "ZFSBootMenu" +.TH "ZFSBOOTMENU" "7" "2023-10-13" "" "ZFSBootMenu" .SH NAME zfsbootmenu \- System Integration .SH SYNOPSIS @@ -121,7 +121,7 @@ Setting \fIspl.spl_hostid\fP to a non\-zero value on the kernel commandline will .sp .nf .ft C -echo 0 > /sys/module/spl/paramters/spl_hostid +echo 0 > /sys/module/spl/parameters/spl_hostid .ft P .fi .UNINDENT diff --git a/docs/man/dist/man8/generate-zbm.8 b/docs/man/dist/man8/generate-zbm.8 index d0684e188..e87d0cb92 100644 --- a/docs/man/dist/man8/generate-zbm.8 +++ b/docs/man/dist/man8/generate-zbm.8 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "GENERATE-ZBM" "8" "2023-05-21" "" "ZFSBootMenu" +.TH "GENERATE-ZBM" "8" "2023-10-13" "" "ZFSBootMenu" .SH NAME generate-zbm \- ZFSBootMenu initramfs generator .SH SYNOPSIS diff --git a/docs/man/dist/man8/zbm-kcl.8 b/docs/man/dist/man8/zbm-kcl.8 index de227b657..9463513fd 100644 --- a/docs/man/dist/man8/zbm-kcl.8 +++ b/docs/man/dist/man8/zbm-kcl.8 @@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.TH "ZBM-KCL" "8" "2023-05-21" "" "ZFSBootMenu" +.TH "ZBM-KCL" "8" "2023-10-13" "" "ZFSBootMenu" .SH NAME zbm-kcl \- manipulate kernel command lines for boot environments and EFI executables .SH SYNOPSIS From d11cf27435ef2c1b88dc9433afc66754586e5750 Mon Sep 17 00:00:00 2001 From: "Andrew J. Hesford" Date: Fri, 13 Oct 2023 15:33:59 -0400 Subject: [PATCH 33/33] releng/tag-release.sh: support tagging on stable release branches --- releng/tag-release.sh | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/releng/tag-release.sh b/releng/tag-release.sh index b508659ee..36072c039 100755 --- a/releng/tag-release.sh +++ b/releng/tag-release.sh @@ -24,7 +24,8 @@ if [ ! -e bin/generate-zbm ] || [ ! -e docs/CHANGELOG.md ]; then fi # Only tag releases from master or a compatible release-tracking branch -case "$(git rev-parse --abbrev-ref HEAD)" in +release_branch="$(git rev-parse --abbrev-ref HEAD)" || release_branch="" +case "${release_branch}" in master) echo "Tagging release from master branch" ;; @@ -190,7 +191,8 @@ if ! git push; then fi if ! gh release create "${tag}" "${prerelease[@]}" \ - -F "${relnotes}" -t "ZFSBootMenu ${tag}" "${asset_files[@]}"; then + --target "${release_branch}" -F "${relnotes}" \ + -t "ZFSBootMenu ${tag}" "${asset_files[@]}"; then error "ERROR: release creation failed" fi