Instructions to ad-hoc upgrade the TrueNAS SCALE kernel

truenas-scale-kernel-upgrade.adoc

Ad-hoc upgrade of TrueNAS SCALE kernel

Warning

This is unsupported and has the potential to corrupt your data. Proceed at your own risk.

Installation

Choose an existing stable kernel branch, e.g. SCALE-v5.15-stable.

1. Update destination box to latest patch release

2. Take a backup of the configuration

3. Create a build environment according to the scale-build requirements

4. In the build environment, as root:

   base=22.02
   kernel=5.15

   Note	${base} should match the release version of the destination host.

   git clone https://github.com/truenas/scale-build
   cd scale-build
   export TRUENAS_BRANCH_OVERRIDE=release/${base}
   export TRY_BRANCH_OVERRIDE=SCALE-v${kernel}-stable
   make

   Tip	The make can fail as long as it makes it past the kernel build.

5. Copy the relevant kernel-related files to the destination host

   destination=root@test

   cd tmp/pkgdir
   rsync -hvi -a kmod-zfs-${kernel}*_*_amd64.deb linux-headers-truenas-amd64_${kernel}*-*_amd64.deb linux-image-truenas-amd64_${kernel}*-*_amd64.deb linux-truenas-libc-dev_${kernel}*-*_amd64.deb ${destination}:

6. As root, on the destination host:

   1. Set up some parameters

      base_dataset=$(awk '$2=="/" { print $1 }' < /etc/mtab)
      # This should match whatever the kernel branch built
      kernel=5.15.34
      # Follow the default TrueNAS snapshot timestamp format
      start_time=$(date '+%Y-%m-%d-%H:%M:%S')

   2. Review:

      echo base_dataset=${base_dataset}
      echo kernel=${kernel}
      echo start_time=${start_time}

      Tip	Make a note of these values if you want the ability to remove it later.

   3. Clone a new dataset on the boot pool for the root filesystem:

      zfs snapshot ${base_dataset}@${start_time}
      zfs clone ${base_dataset}@${start_time} ${base_dataset}-${kernel}
      zfs set mountpoint=legacy ${base_dataset}-${kernel}
      zfs set zectl:keep=False ${base_dataset}-${kernel}
      zfs set truenas:kernel_version=${kernel}+truenas ${base_dataset}-${kernel}

   4. Set up a chroot environment for the newly created root filesystem:

      mount -t zfs ${base_dataset}-${kernel} /mnt
      mount -v -t proc proc /mnt/proc
      mount -v --rbind /dev /mnt/dev
      mount -v --make-rslave /mnt/dev
      mount -v --rbind /sys /mnt/sys
      mount -v --make-rslave /mnt/sys
      mount -v -t tmpfs tmp-fs /mnt/run

   5. Upgrade the kernel in the chroot:

      chroot /mnt sh -c "cd \$HOME && dpkg -i kmod-zfs-${kernel}+truenas_*_amd64.deb linux-headers-truenas-amd64_${kernel}+truenas-*_amd64.deb linux-image-truenas-amd64_${kernel}+truenas-*_amd64.deb linux-truenas-libc-dev_${kernel}+truenas-*_amd64.deb"

   6. Unmount the chroot environment:

      umount -R /mnt

   7. Add the new filesystem choice to the grub boot menu:

      update-grub

7. Reboot and choose the new boot environment from the boot menu

Removal

1. Download the configuration from the new boot environment

2. Boot into the original boot environment from the grub menu

3. Destroy the root dataset noted in the installation step

4. Update the grub menu to remove the destroyed option

   update-grub

5. (Optional) Destroy the original snapshot

   zfs destroy ${base_dataset}@${start_time}

6. Restore the configuration