ThinLinX Support > ThinLinX Help Desk > Knowledgebase

Search help:

Upgrading from TLXOS 4.x to 5.x fails - what's wrong?


You cannot upgrade directly from unmodified TLXOS 4.x to TLXOS 5.x - this will fail with an "Error programming the boot partition" error, because the boot partition is too small for the TLXOS 5.x /boot filesystem image.

To avoid this, you must first apply a 4.99.99 "bridging upgrade".  This isn't a full TLXOS upgrade, nor does it truly have a 4.99.99 version number.  It actually upgrades Maintenance Mode only, and the first time the new Maintenance Mode image is booted, e.g. when you next attempt a 4.x to 5.x upgrade, it will perform a one-time irreversible conversion of your TLXOS 4.x install to the new layout that TLXOS 5.x uses.

This conversion involves combining the separate boot and TFM (Maintenance Mode) partitions to form a single, larger, boot partition, whilst converting the userspace part of your former Maintenance Mode partition to an alternative early userspace (/boot/tfm.img).  Removal of the dedicated /tfm filesystem also requires minor modifications to the TLXOS 4.x root filesystem.

When this conversion is complete, you will still be running the same version of TLXOS 4.x, but you will no longer be able to upgrade or downgrade to any 4.x version of TLXOS, and can only upgrade to TLXOS 5.x.  The Kernel Version displayed in TMS and TLxconfig will have "-uprep" appended to indicate that this modification has taken place, and the TFM Version will change to Unknown because there is no longer a TFM partition and Maintenance Mode has ceased to be a separately-versioned entity.

At this point you will be able to update to TLXOS 5.x (initially 5.0.0 LTS or 5.2.0, but also any later version we provide in future).  If the switch to Maintenance Mode was performed by TMS as part of a queued TLXOS 5.x upgrade, this will occur immediately.  If you switched to Maintenance Mode voluntarily, you can exit Maintenance Mode and keep working at the same 4.x version you were using previously until such time as you are ready to upgrade.

Upgrading from TLXOS 4.x to 5.0.0 LTS is lower risk than upgrading to 5.2.0 or later, because TLXOS 5.0.0 LTS is designed to fit in the space already allocated by TLXOS 4.x, and 5.2.0 isn't.  TLXOS 5.2.0 has a larger disk footprint than TLXOS 5.0.0 LTS because it is based on a later version of Debian (which is larger), and also because it lacks the filesystem compression used in 5.0.0 LTS and earlier.  This means that, despite our best efforts, upgrades to 5.2.0 and later may fail due to lack of disk space in certain cases (e.g. when using low capacity storage such as a <= 4 GB SD card, or when a lot of additional data has been stored in the /config midlayer).

Upgrading to TLXOS RPi 5.2.0 and later from TLXOS RPi 4.x will result in the loss of the /config midlayer (except for the /config/etc/environment file, which is preserved).  This is unavoidable, because the boot partition is too small even for the enlarged partition prepared by the 4.99.99 bridging upgrade, requiring relocation of the LVM partition.  Consequently, you will lose uploaded files such as SSH public keys and CA certificates, and will have to reinstall them after the upgrade using TMS or Tlxconfig.  This may also occur during future TLXOS 5.x upgrades, whenever we are forced to enlarge the /boot filesystem.


Related articles Can I upgrade TLXOS without using TMS or reinstalling from scratch?
Can I customize the installation image prior to install?
tms_client / Tlxconfig 8.4.1
What is the difference between TLXOS 4.8.x/5.0.x LTS and later versions (e.g. 4.11.x/5.2.x)? Which do I need?
Can TMS be used to manage remote devices connecting via the Internet?
Article details
Article ID: 101
Category: Frequently Asked Questions
Date added: 2024-02-22 00:57:14
Views: 32

« Go back