Upgrading Nitrux is easy. We even support two methods to achieve this: using a utility created explicitly for this purpose or Calamares—yes, you read that right.
In today’s tutorial, we’ll check how to do this.
Difficulty: ★☆☆☆☆
📜 Table of Contents
About Upgrades in Nitrux
Below is the information we’ve deemed important for users to understand about this distribution and its upgrade process.
- We aim to release new upgrade archives for the Nitrux Update Tool System during the first week of the month, usually the same week as the latest release. Sometimes, this period may extend for a couple more days. Either way, we will announce the availability of the update archive on our social media, chat groups, and the PSA section on this website.
- The update archives for the Nitrux Update Tool System and the utility are designed to upgrade only from the previous release to the latest, i.e., 3.4.0 to 3.4.1 or 3.4.1 to 3.5.0, etcetera. To upgrade from older installations, i.e., 3.4.0 to 3.5.0, see Upgrade using Live media (Calamares).
- Regarding the updated archives, we delete the previous files whenever a new archive is uploaded. We do not keep a historical archive of these files or the ISOs online.
- Users must manually run the Nitrux Update Tool System to check for updates. The Nitrux Update Tool System will also not download any update archive in the background for “offline updates.” There’s no background process, and the utility isn’t designed for this purpose. This also means that updates are not forced on the user; users are responsible for updating their installations on time.
Upgrade using the Nitrux Update Tool System
The Nitrux Update Tool System (nuts) is a utility designed to update Nitrux OS and provide a backup option for rollbacks.
⚠️ Important: The Nitrux Update Tool System is intended to work exclusively in Nitrux OS, and using this utility in other distributions will break them or not work at all. Please do not open issues regarding this use case; they will be closed.
The Nitrux Update Tool System (nuts) is a simple, minimalistic update and rollback utility. It performs three steps:
- It creates a backup of the root directory using SquashFS and the XFS partition using the XFS tools and stores them locally.
- Then, it downloads an OTA-style update file and updates the system using a custom AppImage.
- Depending on the situation, the utility restores a backup using ‘rsync’ and the locally generated SquashFS file or the XFS tools.
The Nitrux Update Tool System will reboot the computer automatically five seconds after completing a task.
See the commands below to use the Nitrux Update Tool System.
sudo nuts update
- It uses the specified media in the nuts-query to update the currently installed root and back up the current root directory and partition.
- 🔰 Information: The OTA archives for the Nitrux Update Tool System do not include updates to the NVIDIA proprietary driver or MESA.
- 🔰 Information: Depending on various factors, such as system specifications and Internet connection speed, the update process may take between 25 and 30 minutes to complete (during our tests using a virtual machine). Please be aware that the update process involves creating the XFS backup, compressing the XFS backup, creating the root directory SquashFS backup, and downloading and applying the OTA-style update file. Other factors affecting the completion time include connectivity to GitHub (and raw.githubusercontent.com) and SourceForge and its mirrors.
- 🔰 Information: If your computer can’t reach the domain raw.githubusercontent.com, you cannot proceed with the update process. We recommend using a VPN or a proxy or contacting your ISP if they block access to these domains; see our tutorial Filesystem, Security, Privacy, and Anonymization Features in Nitrux for more information about using VPNs and proxies. This is not a bug or issue with Nitrux or is caused by Nitrux.
sudo nuts restore
- Restores the backup of the root directory generated during the update.
sudo nuts rescue
- Restores the backup of the XFS root partition in case of an interrupted update.
- 🔰 Information: This operation is a special handling of an unforeseen event. If the update process were interrupted, the root would be inconsistent. That means the root is unusable, i.e., the user can’t access the GUI or, worse, a TTY, so the user can’t restore the SquashFS. This operation will allow the user to restore the root partition from a Live session. This operation does not replace restore; it exists if using restore is impossible. The user can only use this operation during a live session.
sudo nuts self-update
- Updates the Nitrux Update Tool System and the configuration file using the Git branch set in the configuration file.
Upgrade using Live media (Calamares)
Using an installer like Calamares to “update” a distribution doesn’t occur to most people.
But we can do this by replacing only the old root partition with a new one. Think of it like having a directory with multiple text files [abc][abcd][abcxyz] and deleting only one of the files instead of the entire directory, and now you have [abc123][abcd][abcxyz]. Doing the procedure below wouldn’t be possible if the distribution was installed as a single partition, which is the case for most Linux distributions; that’s why Nitrux uses a custom partition layout and why we emphasize not using a single partition layout when installing the distribution initially.
Some might mistake this for “reinstalling.” However, reinstalling would mean reusing the initial installation media, like an ISO of version 2.9.0, resulting in the “new” root still being version 2.9.0. Nonetheless, we’re saying that if you used an ISO of version 2.9.0 for the initial installation and then used an ISO of version 2.9.1, deleted the old root, and created a new root, the new root, once installed, will be version 2.9.1.
To upgrade from previous versions of Nitrux using Calamares, do the following.
- Download and flash the latest ISO.
- Boot to the Live session and start Calamares.
- After completing the locale, keyboard, and user configuration, select the option to do a “Manual partitioning.”
- Select and delete the previous installation root; do not delete or format other partitions unless desired; only select “Keep.”
- 🔰 Information: For further details about manual partitioning, see Non-automated Partitioning Options.
The table below defines our partition layout for EFI or UEFI firmware-type computers that use storage devices using GPT (GUID Partition Table).
- ⚠️ Important: Please be aware that the root directory is immutable, and any directory within the root will be read-only. Do not use a single partition layout.
| Partition | Label | Mountpoint | Filesystem Type | Flags |
|---|---|---|---|---|
| EFI System Partition | ESP | /boot/efi | fat32 | boot |
| root | NX_ROOT | / | xfs | none |
| home | NX_HOME | /home | f2fs | none |
| /var/lib | NX_VAR_LIB | /var/lib | f2fs | none |
| swap | SWAP | none (automatically setup) | linuxswap | none (automatically setup) |
The table below defines our partition layout for Legacy BIOS firmware-type computers that use storage devices using GPT (GUID Partition Table).
- ⚠️ Important: Please be aware that the root directory is immutable, and any directory within the root will be read-only. Do not use a single partition layout.
| Partition | Label | Mountpoint | Filesystem Type | Flags |
|---|---|---|---|---|
| EFI System Partition | – | – | unformatted | bios-grub |
| root | NX_ROOT | / | xfs | none |
| home | NX_HOME | /home | f2fs | none |
| /var/lib | NX_VAR_LIB | /var/lib | f2fs | none |
| swap | SWAP | none (automatically setup) | linuxswap | none (automatically setup) |
- Finally, proceed with the installation of the new root.
Troubleshooting
Below is the information we deem necessary for users to troubleshoot problems.
Unable to Find an Overlay Filesystem Error
When using the Nitrux Update Tool System, the error message ERROR: Unable to find an overlayroot filesystem will be displayed after the following user actions:
- Turning off the overlay functionality by editing the boot parameter and booting the distribution afterward.
- Using the command
sudo overlayroot-chrootand attempting to execute the commandsudo nuts <option>within the shell session afterward.
The error message indicates that OverlayFS is not being used. As we thoroughly mention on our website, this distribution uses OverlayFS, and we designed it to work in this manner. Doing either of these actions will prevent the Nitrux Upgrade Tool System from functioning.
As such, we strongly emphasize and recommend following the straightforward instructions outlined in Installing Nitrux and in this tutorial. This is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Unable to Resolve Partition Label
When using the Nitrux Update Tool System, the error message findfs: unable to resolve LABEL will be displayed if the user does not install the distribution following our specific instructions as outlined in Installing Nitrux and this tutorial.
The error message indicates that the given partition does not have a label. This distribution specifies partition labels during installation precisely because we require them for our update process. This is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Unable to Create Redundant Backup of Root Partition
If the user did not use the XFS filesystem for the root partition, the Nitrux Update Tool System will not be able to create the redundant backup of the root partition, which means that using the command nuts rescue will not work.
As we thoroughly mentioned in Installing Nitrux and this tutorial, we’ve designed our distribution using XFS and F2FS in mind and no other filesystems for setting up our distribution. This is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Report Update Process Bugs
To report problems with the Nitrux Update Tool System during the update, please use our bug tracker on GitHub and include the file /var/log/nuts.log in a bug report.
- 🔰 Information: This file is only available during the active session.
That’s it; this concludes today’s tutorial.