Upgrading system image on encrypted NVME (keeping `/home` intact)

1

I have just recently upgraded to the A311D processor module. I had my Debian
installation around for a while so I thought the best “upgrade” would be to nuke the system – however, I did not want to remove my whole home directory in the process.

In case anyone else is in the same boat, below are the notes I took during the
installation that left me with a fresh new system and my old dusty home
directory with all the data intact!

The instructions assume that you have created the original system using the
reform-setup-encrypted-nvme script. If not, you will have to adjust some
commands in case e.g. your LVM volume group is called something else.

Preparation

  • Backup! Even when the intention is to keep the home directory in place, make a backup, just in case. In fact, make two!
  • Download the newest system image for the A311D and flash it to an SD card.
  • After the installation of the processor module, insert the SD card and boot from it.
  • Log in as root user (no password) and follow the on-screen instructions to create your own user. If you have several local users, make sure that you create them in the order you did originally, or you might have to adjust the permissions on the home directories later on.

Mount the nvme and decrypt it

Run the following commands as root:

NVMEDEV=nvme0n1
cryptsetup luksOpen "/dev/$NVMEDEV" reform_crypt

Enter your passphrase for the system volume when asked.

Now, the volume group and the logical volumes should already be visible in /dev/mapper:

$ ls /dev/mapper/
control  reform_crypt  reformvg-root  reformvg-swap

You can list the logical volumes and their size:

$ sudo lvs
  LV   VG       Attr       LSize   Pool Origin Data%  Meta%  Move Log Cpy%Sync Convert
  root reformvg -wi-a----- 945.85g                                                    
  swap reformvg -wi-a-----   8.00g

$ ls /dev/reformvg/
root  swap

If these commands do not produce similar output, your volume group might be
called something else or you might have to run vgchange -ay reformvg first.

Copy the data

As most things are already set up, that means we can skip a whole lot of what
the migration script would do! So it is time to prepare copying the data. Adjust the variable ROOTMNT below if you want to mount the old root volume somewhere else (only temporarily so it should not really matter):

ROOTMNT=/mnt
mount /dev/reformvg/root $ROOTMNT

For the actual copy command, I use the same as the migration script would do, except the parameters --delete and --exclude '/home/*'. The former instructs rsync to remove any file that is not overwritten already in the copying process. This means that we do not need to format the filesystem and still get a fresh image. In order to not remove or overwrite the home directory in the process, I added the latter paramter. You can add several --exclude statements if you want to omit other directories as well.

You can add --dry-run and -v options if you want to test the command first without actually changing anything.

rsync -axHAWXS --delete --exclude '/home/*' --numeric-ids --info=progress2 / $ROOTMNT

Adjust configuration

Before rebooting, we need to adjust the configuration for the encrypted volume:

SWAPUUID=$(blkid -s UUID -o value /dev/reformvg/swap)
CRYPTUUID=$(blkid -s UUID -o value "/dev/$NVMEDEV")
 echo "RESUME=UUID=$SWAPUUID" > "$ROOTMNT/etc/initramfs-tools/conf.d/resume"
 echo "reform_crypt UUID=$CRYPTUUID none luks,discard" > "$ROOTMNT/etc/crypttab"
 echo "UUID=$SWAPUUID none swap sw 0 0" >> "$ROOTMNT/etc/fstab"

Set the boot device

Now unmount the old root and set the root logical volume as boot device.

umount $ROOTMNT
umount /boot
reform-boot-config /dev/reformvg/root

If you have the BPI-CM4 (A311D), then you are done!

Otherwise, run
reform-boot-config --emmc /dev/reformvg/root=
if you want to run the /boot partition from EMMC.

Safely close volume group and LUKS volume

vgchange -an reformvg
cryptsetup luksClose reform_crypt

Reboot, cross fingers and you are done!

  • keep the SD card in the slot as that is where the boot files are located on (for A311D anyway)
  • when started up, run sudo reform-check, sudo apt update && sudo apt upgrade and install your favorite packages!
  • you might want to check out the sway, foot, dunst, waybar … configuration files which have been updated quite a bit recently. You can find the new versions in /etc/skel/.config/.
2 Likes
2

Thank for writing all of this down! I wonder though, what was your motivation for starting over with all of your rootfs (except /home) getting reset to vanilla reform-system-image instead of continuing with your existing installation on the new SoM?

3

No particular reason. I have been messing with the system for a while and preferred starting from a well-defined point rather than trying to clean up or bug-hunt in my setup later. And getting the basics back is almost as easy as “apt build-dep emacs” :wink:

4

Okay, fair! :smiley: Then your instructions look really good! I’ll receive my a311d on the 28th of december if everything goes to plan and will publish a small guide on how to upgrade from imx8mq to a311d without wiping the system as soon as I find time. (please anybody correct me if such a guide already exists and i just have missed it)

1 Like