NixOS, Alpine Linux: mount datasets in Root on ZFS guide; immutable

root; GRUB update

Acknowledgement: @bjornstromberg
Closes openzfs#398

NixOS: remove NetworkManager by default, add note for enable

Signed-off-by: Maurice Zhou <[email protected]>

Author: Maurice Zhou

docs/Getting Started/Alpine Linux/Root on ZFS/2-system-installation.rst

@@ -80,9 +80,6 @@ System Installation
    limited to only those that GRUB supports, allowing the root pool to use
    any/all features.
 
-   Features enabled with ``-o compatibility=grub2`` can be seen
-   `here <https://github.com/openzfs/zfs/blob/master/cmd/zpool/compatibility.d/grub2>`__.
-
 #. Create root pool::
 
        zpool create \
@@ -158,7 +155,7 @@ System Installation
     done
 
     mkdir -p /mnt/boot/efi
-    mount -t vfat $(echo $DISK | cut -f1 -d\ )-part1 /mnt/boot/efi
+    mount -t vfat $(echo $DISK | cut -f1 -d' ')-part1 /mnt/boot/efi
 
 #. By default ``setup-disk`` command does not support zfs and will refuse to run,
    add zfs support::
@@ -186,14 +183,6 @@ System Installation
 
     chroot /mnt /usr/bin/env DISK="$DISK" sh
 
-#. Rebuild initrd::
-
-    sed -i 's|zfs|nvme zfs|' /etc/mkinitfs/mkinitfs.conf
-    for directory in /lib/modules/*; do
-      kernel_version=$(basename $directory)
-      mkinitfs $kernel_version
-    done
-
 #. Apply GRUB workaround::
 
      echo 'export ZPOOL_VDEV_NAME_PATH=YES' >> /etc/profile.d/zpool_vdev_name_path.sh
@@ -206,10 +195,11 @@ System Installation
      sed -i 's|stat -f -c %T /|echo zfs|' /usr/sbin/grub-mkconfig
 
      # grub-probe fails to identify fs mounted at /boot
-     sed -i "s|GRUB_DEVICE_BOOT=.*|GRUB_DEVICE_BOOT=$(echo $DISK | cut -f1 -d\ )-part2|"  /usr/sbin/grub-mkconfig
+     BOOT_DEVICE=$(zpool status -P bpool | grep -- -part2 | head -n1 | sed  "s|.*/dev*|/dev|" | sed "s|part2.*|part2|")
+     sed -i "s|GRUB_DEVICE_BOOT=.*|GRUB_DEVICE_BOOT=${BOOT_DEVICE}|"  /usr/sbin/grub-mkconfig
 
-   This workaround needs to be applied for every GRUB update, as the
-   update will overwrite the changes.
+   The ``sed`` workaround for ``grub-mkconfig`` needs to be applied
+   for every GRUB update, as the update will overwrite the changes.
 
 #. Install GRUB::
 
@@ -227,6 +217,8 @@ System Installation
 
      grub-mkconfig -o /boot/efi/alpine/grub-bootdir/x86_64-efi/grub/grub.cfg
      grub-mkconfig -o /boot/efi/alpine/grub-bootdir/i386-pc/grub/grub.cfg
+     mkdir -p /boot/grub
+     grub-mkconfig -o /boot/grub/grub.cfg
 
 #. For both legacy and EFI booting: mirror ESP content::
 
@@ -243,7 +235,7 @@ System Installation
 
 #. Unmount filesystems::
 
-     cut -f2 -d\  /proc/mounts | grep ^/mnt | tac | while read i; do umount -l $i; done
+     umount -Rl /mnt
      zpool export -a
 
 #. Reboot::

docs/Getting Started/Arch Linux/Root on ZFS/2-system-installation.rst

@@ -148,4 +148,4 @@ System Installation
     done
 
     mkdir -p /mnt/boot/efi
-    mount -t vfat $(echo $DISK | cut -f1 -d\ )-part1 /mnt/boot/efi
+    mount -t vfat $(echo $DISK | cut -f1 -d' ')-part1 /mnt/boot/efi

docs/Getting Started/Arch Linux/Root on ZFS/5-bootloader.rst

@@ -30,6 +30,8 @@ Bootloader
 	  /boot/efi --bootloader-id arch --removable
       grub-mkconfig -o /boot/efi/arch/grub-bootdir/x86_64-efi/grub/grub.cfg
       grub-mkconfig -o /boot/efi/arch/grub-bootdir/i386-pc/grub/grub.cfg
+      mkdir -p /boot/grub
+      grub-mkconfig -o /boot/grub/grub.cfg
 
 #. For both legacy and EFI booting: mirror ESP content::
 

docs/Getting Started/Fedora/Root on ZFS/2-system-installation.rst

@@ -148,4 +148,4 @@ System Installation
     done
 
     mkdir -p /mnt/boot/efi
-    mount -t vfat $(echo $DISK | cut -f1 -d\ )-part1 /mnt/boot/efi
+    mount -t vfat $(echo $DISK | cut -f1 -d' ')-part1 /mnt/boot/efi

docs/Getting Started/Fedora/Root on ZFS/5-bootloader.rst

@@ -30,6 +30,8 @@ Bootloader
       cp -r /usr/lib/grub/x86_64-efi/ /boot/efi/EFI/fedora/
       grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
       grub2-mkconfig -o /boot/efi/fedora/grub-bootdir/i386-pc/grub2/grub.cfg
+      mkdir -p /boot/grub2
+      grub2-mkconfig -o /boot/grub2/grub.cfg
 
 #. For both legacy and EFI booting: mirror ESP content::
 
@@ -47,6 +49,7 @@ Bootloader
 
       grub2-mkconfig -o /boot/efi/EFI/fedora/grub.cfg
       grub2-mkconfig -o /boot/efi/fedora/grub-bootdir/i386-pc/grub2/grub.cfg
+      grub2-mkconfig -o /boot/grub2/grub.cfg
 
 Finish Installation
 ~~~~~~~~~~~~~~~~~~~~

docs/Getting Started/NixOS/Root on ZFS/1-preparation.rst

@@ -6,16 +6,15 @@ Preparation
 .. contents:: Table of Contents
    :local:
 
-This guide supports x86_64 and arm64-efi architectures.
+**Note for arm64**
 
-**Note for Tow-Boot**
+Currently there is a bug with the grub installation script.  See `here
+<https://github.com/NixOS/nixpkgs/issues/222491>`__ for details.
 
-`Tow-Boot firmware <https://tow-boot.org/>`__
-enables UEFI boot on many affordable arm64 based computers.  If
-using Tow-Boot, NixOS and Tow-Boot must be on separate disks.
-Example, Tow-Boot is installed to an SD card.  Then the SD card
-should not be also shared with NixOS.  Install NixOS to an external
-disk instead.
+**Note for Immutable Root**
+
+Immutable root can be enabled or disabled by setting
+``zfs-root.boot.immutable`` option inside per-host configuration.
 
 #. Disable Secure Boot. ZFS modules can not be loaded if Secure Boot is enabled.
 #. Download `NixOS Live Image

docs/Getting Started/NixOS/Root on ZFS/2-system-installation.rst

@@ -126,14 +126,18 @@ System Installation
       mount -t zfs rpool/nixos/root /mnt/
       zfs create -o mountpoint=legacy rpool/nixos/home
       mkdir /mnt/home
-      mount -t zfs  rpool/nixos/home /mnt/home
+      mount -t zfs rpool/nixos/home /mnt/home
       zfs create -o mountpoint=legacy  rpool/nixos/var
       zfs create -o mountpoint=legacy rpool/nixos/var/lib
       zfs create -o mountpoint=legacy rpool/nixos/var/log
       zfs create -o mountpoint=none bpool/nixos
       zfs create -o mountpoint=legacy bpool/nixos/root
       mkdir /mnt/boot
       mount -t zfs bpool/nixos/root /mnt/boot
+      mkdir -p /mnt/var/log
+      mkdir -p /mnt/var/lib
+      mount -t zfs rpool/nixos/var/lib /mnt/var/lib
+      mount -t zfs rpool/nixos/var/log /mnt/var/log
       zfs create -o mountpoint=legacy rpool/nixos/empty
       zfs snapshot rpool/nixos/empty@start
 

docs/Getting Started/NixOS/Root on ZFS/3-system-configuration.rst

@@ -36,10 +36,10 @@ System Configuration
      sed -i "s|\"bootDevices_placeholder\"|$diskNames|g" \
        /mnt/etc/nixos/hosts/exampleHost/default.nix
 
-     sed -i "s|\"hostId_placeholder\"|\"$(head -c4 /dev/urandom | od -A none -t x4| sed 's| ||g')\"|g" \
+     sed -i "s|\"abcd1234\"|\"$(head -c4 /dev/urandom | od -A none -t x4| sed 's| ||g')\"|g" \
        /mnt/etc/nixos/hosts/exampleHost/default.nix
 
-     sed -i "s|\"systemType_placeholder\"|\"$(uname -m)-linux\"|g" \
+     sed -i "s|\"x86_64-linux\"|\"$(uname -m)-linux\"|g" \
        /mnt/etc/nixos/flake.nix
 
 #. Set root password::
@@ -52,8 +52,8 @@ System Configuration
      "s|rootHash_placeholder|${rootPwd}|" \
      /mnt/etc/nixos/hosts/exampleHost/default.nix
 
-#. Optional: add SSH public key for root and change host name in
-   ``/mnt/etc/nixos/hosts/exampleHost/default.nix``.
+#. You can enable NetworkManager for wireless networks and GNOME
+   desktop environment in ``configuration.nix``.
 
 #. From now on, the complete configuration of the system will be
    tracked by git, set a user name and email address to continue::
@@ -76,8 +76,6 @@ System Configuration
 
      nixos-install --no-root-passwd --flake "git+file:///mnt/etc/nixos#exampleHost"
 
-   If the host name was changed, use the new host name in this command.
-
 #. Exit ephemeral nix shell with git::
 
      exit
@@ -91,22 +89,6 @@ System Configuration
 
      reboot
 
-#. NetworkManager is enabled by default.  To manage network
-   connections, execute::
-
-     nmtui
-
-#. Optional: immutable root filesystem can be enabled by setting
-   ``my.boot.immutable`` option to ``true``.
-   then execute::
-
-     nixos-rebuild boot
-
-   Then reboot.  You may need to make certain
-   adjustments to where configuration files are stored,
-   see `NixOS wiki <https://nixos.wiki/wiki/ZFS>`__ for
-   details.
-
 Replace a failed disk
 =====================
 

docs/Getting Started/RHEL-based distro/RHEL-based distro Root on ZFS/2-system-installation.rst

@@ -148,4 +148,4 @@ System Installation
     done
 
     mkdir -p /mnt/boot/efi
-    mount -t vfat $(echo $DISK | cut -f1 -d\ )-part1 /mnt/boot/efi
+    mount -t vfat $(echo $DISK | cut -f1 -d' ')-part1 /mnt/boot/efi

docs/Getting Started/RHEL-based distro/RHEL-based distro Root on ZFS/5-bootloader.rst

@@ -30,6 +30,8 @@ Bootloader
       cp -r /usr/lib/grub/x86_64-efi/ /boot/efi/EFI/almalinux/
       grub2-mkconfig -o /boot/efi/EFI/almalinux/grub.cfg
       grub2-mkconfig -o /boot/efi/almalinux/grub-bootdir/i386-pc/grub2/grub.cfg
+      mkdir -p /boot/grub2
+      grub2-mkconfig -o /boot/grub2/grub.cfg
 
 #. For both legacy and EFI booting: mirror ESP content::
 
@@ -47,6 +49,7 @@ Bootloader
 
       grub2-mkconfig -o /boot/efi/EFI/almalinux/grub.cfg
       grub2-mkconfig -o /boot/efi/almalinux/grub-bootdir/i386-pc/grub2/grub.cfg
+      grub2-mkconfig -o /boot/grub2/grub.cfg
 
 Finish Installation
 ~~~~~~~~~~~~~~~~~~~~