Updated Jan 3rd, 2022.
In our previous article, we talked about how does znx works. If you haven’t, go and check it out. Right, so with that out of the way, let’s get to the nitty-gritty of this article. Ever since the release of znx, we had many ask us how they install Nitrux using znx, and the official answer is by executing znx init and znx deploy, as we mention in the Compendium and the FAQ.
But what happens when there’s only a single device?. It would mean deleting all your files, and that is, of course, not desirable to do. However, you can use our ISO files and keep your existing system installation (and user data) intact!.
Today we’re going to check out how to integrate a znx compatible ISO image into an existing installation of a Linux distribution. For this example, I’m going to use Xubuntu 20.04.03, albeit none of what we’ll do is specific to XFCE (or Ubuntu, for that matter).
What does “Integration” mean?
That is a good question. What I mean by integration is deploying (which in the context of znx is the equivalent to installing) and managing (upgrade, downgrade, etc.) a znx-compatible ISO image to an existing Linux partition without removing it by reusing the existing root partition and the process is pretty straightforward.
So, with the premise in mind, what do you do?.
I will be using Virtualbox for clarity, but none of the steps below are specific to Virtualbox.
Obtaining the necessary files
Boot into your Linux installation (in this case, I installed Xubuntu) and go to the znx repository at GitHub to download the latest AppImage (master) from the Releases page to your Home directory. Let’s assume that you’ve downloaded the file to your Downloads directory.
Now, proceed to rename the file to znx; this is so that we don’t get confused with a long file name.
Then, give the file executable permissions.
Now, open a terminal window and navigate to the Downloads directory, and extract the AppImage file.
cd Downloads && ./znx --appimage-extract
A new directory will be created, which is squashfs-root, this directory has the contents of the Appimage. Now, in the terminal window, navigate to the squashfs-root directory.
cd squashfs-root
Ok. So, now we need to install a new package to Xubuntu, we need to install grub-efi-amd64 or the equivalent package in your distribution. This package will add the necessary GRUB modules that znx requires.
sudo apt install grub-efi-amd64
You will be asked to confirm this action, so press Y. After the installation is complete, open a new tab in the terminal window.
Please be mindful that the following steps will be performed using the root account.
Now we need to navigate to the /boot/efi directory. However, if we attempt to do this with our user account, we will be presented with a message that says Permission denied. To avoid this, switch to the root account.
sudo -i
Now that you’re root navigate to /boot/efi and type ll (that’s two lowercase L) and press enter, this will list the directories in this path. Then, create a directory tree called boot/grub.
cd /boot/efi && mkdir -p boot/grub
Then, create a new boot directory using mkdir -p boot/grub; this command will create empty boot and grub directories. We have to copy the grub.cfg and the themes directory from the znx AppImage that we extracted earlier to boot/grub; we will do this using the command cp.
cp -r /home/$USERNAME/Downloads/squashfs-root/grub/grub.cfg boot/grub cp -r /home/$USERNAME/Downloads/squashfs-root/grub/themes boot/grub
We can verify that the files are in the correct path by typing ll/boot/grub (that’s two lowercase L) and press enter.
Next, we navigate to the EFI directory and delete the contents of the BOOT directory inside of it. Then we create a new directory called boot (lowercase).
cd EFI && rm -r BOOT/ && mkdir boot
Then, we copy the file bootx64.efi from the squashfs-root folder to the EFI/boot directory.
cp -r /home/$USERNAME/Downloads/squashfs-root/bootx64.efi EFI/boot
Those are all the files that we need, you can remove the squashfs-root directory.
Adding an entry to the EFI boot menu
Now, we will add an EFI boot entry available from the EFI/UEFI firmware boot menu. This boot menu is the menu that is available when the computer is booting and (depending on the computer) can be displayed using F12 or F10 or other combinations of keys.
The EFI firmware boot menu is not confused with the GRUB boot menu.
To create an EFI boot entry, we pass the following arguments to efibootmgr:
- –create (-c) to create a new entry.
- –part (-p) followed by the partition number on which the EFI System Partition is hosted.
- –disk (-d) followed by the disk on which the EFI System Partition is hosted.
- –label (-L) followed by the label to use as the boot entry.
- –loader (-l) followed by the path of the EFI image to boot.
In the example, the storage device is a SATA device (sda/b/c etc.) for NVME devices it is /dev/nvmeXnY (i.e., nvme0n1).
efibootmgr -c -d /dev/sda -p 1 -L "znx" -l "\EFI\boot\bootx64.efi"
Then, verify that the EFI entry is pointing to the correct loader file.
efibootmgr -v
The output of the command efibootmgr shows us that the entry we just added is number 0004 (Boot0004); it tells is in which physical device is the bootloader file too.
The next time we reboot, we will see an EFI entry for znx and ubuntu, along with the EFI entries for the hardware devices.
Now you can exit the root account by typing exit.
Add partition labels for znx
For this part, we will need to change the label of the partitions to those required for znx. We will need to change the EFI System Partition label to ZNX_BOOT and the Root partition to ZNX_DATA since this is where we will be deploying our znx compatible ISO file, and znx will save the user data with OverlayFS.
If you don’t set the partition labels, then znx will not manage the ISO files.
By default, if you used the automatic installation mode in the Ubiquity installer, only the ESP has its label set to “EFI System Partition.” To change the partition labels, we will be using GParted, so if you don’t have it installed already, please install it.
Open GParted, right-click the partition, and select “Name Partition,” now, change the name to ZNX_BOOT. Do the same for the Root partition and enter ZNX_DATA, then press “OK.”
Please note that ZNX_DATA is a Btrfs partition; if the storage device uses another filesystem, such as Ext4, the data persistence will not work.
To apply the changes, click the green checkmark button at the top of the window, then select “Apply.”
GParted will do the changes to the partitions, and they will have new labels (or names as GParted refers to them).
And that’s it, now to the final steps.
Add znx to the PATH
We can now move the znx AppImage to our PATH. Use mv to move the file to /usr/bin and execute hash -d /usr/bin/znx to update the cached paths. Now we can access znx from everywhere without having to type ./ first.
sudo mv Downloads/znx /usr/bin hash -d /usr/bin/znx
Testing that everything works
Now that we have added the files and the labels, znx can make use of the existing Root partition to deploy images. This is the easiest step; to test this, let’s deploy a new znx compatible ISO file.
sudo znx deploy /dev/sda nx/minimal http://updates.nxos.org/nitrux-minimal-vfio-amd64.iso
znx can deploy images, hurrah!. Also, since we set the labels, the rest of the functionality is available. That means that we can deploy, upgrade, downgrade and remove images.
The image below is from the Virtualbox EFI boot menu (or Boot Manager). As we can observe, we added the EFI entry of znx, and if we select it, the computer will display the znx boot menu. To access this menu, press ESC when the virtual machine is booting up.
And now, we can deploy as many znx-compatible images as we want!.
And if we wanted to boot into Xubuntu, we’d select the ubuntu boot entry.
Then, if we press ESC again after selecting the ubuntu boot entry, we will access the Xubuntu GRUB boot menu; this means that we didn’t break anything, and we can access both systems.
Conclusion
The article proves something, and that is that znx is sufficiently flexible. There’s no denying that znx has to provide this functionality independently. But, this clarifies that you do not have to wipe your storage device to deploy Nitrux if you don’t want to do that.
In the end, you can easily integrate the znx ISO images into an existing installation.