The clean path to Turris OS 6 (and any other major version)

Hi everyone,

Since Turris OS 6 was promoted stable there have been many users struggling with small or not so small issues after upgrading. For all of you long-time Turris OS users, you will remember that the situation was similar with the move from Turris OS 3 to 5 a couple of years back. That doesn’t come as a surprise, given the almost infinite amount of configurations out there, the big architectural changes between versions and the relatively small Turris team that’s in charge of keeping all these balls in the air.

I thought I’d share my approach to major upgrades (that is, the first digit of the version number increases). It’s a very simple approach that many people in IT will be able to relate to and applies many technologies:

Don’t upgrade. Reinstall.

Yes, you will have to reconfigure your router. But that’s not necessarily a bad thing, it keeps your admin skills fresh. The result is a fresh, clean system where you can be sure that there isn’t any old stuff (files, configuration, packages) lingering around that was dragged along for years that might bite you sometime in the future.

With that being said, here’s a simple way to install the latest version of Turris OS while keeping your old system available. We will be installing the new version as a factory image. The factory image is basically a new snapshot on your router’s disk – not to be confused with the rescue system which lives on flash (NOR) storage and which we are neither going to touch or use.

Please note:

  • This is my personal approach which I’m sharing for educational purposes. I’m not part of the Turris team and it’s not their official procedure. You’re doing this at your own risk.
  • Read through the whole instructions once before starting so you know what to expect. In particular, your router will be factory-reset and you will need to physically connect to it for reconfiguration. Don’t attempt this procedure five minutes prior to your spouse’s important video conference call. :wink:
  • This procedure should work fine for Mox and Omnia if your software version isn’t so old that it can’t download the update any more – in this case please refer to Fallback: Using a USB stick below. If you have a Turris 1.x, please follow the official guide to convert to BTRFS and to perform a factory reset.
  • Execute the instructions one by one. If you run into any errors, do no continue. Instead, leave a reply with the error message, your router model and the old Turris OS version you’re using.
  • Do not perform any other actions between the instructions such as changing directories, rebooting etc.

With that being out of the way let’s get started!

Factory-reset to the latest Turris OS version

# Determine which model you have
model=$(cat /proc/device-tree/model | grep -o -E "(Mox|Omnia)" | tr '[A-Z]' '[a-z]')
[ -n "$model" ] && echo "Found router model: $model" \
  || echo "ERROR: Couldn't determine router model."

# Download factory image (called "medkit") and its checksum
cd /tmp

# If you get an error such as:
#   wget: not an http or ftp url:…
#   wget: bad address ''
# then please proceed using a USB stick instead, as described below.

# Verify its integrity
sha256sum -c $model-medkit-latest.tar.gz.sha256 \
  || echo "ERROR: Checksum check failed. Please try downloading both files again and re-check."

# Import to disk as new factory image
schnapps import -f $model-medkit-latest.tar.gz

# Create a snapshot of the current systems to make it easily identifiable
schnapps create "Pre factory rollback"

# Rollback to new factory image. This will create a snapshot of your current
# system and then switch to the new factory image and reboot.
schnapps rollback factory

# We're done. Reboot into your new Turris OS!

Your router will now boot into a vanilla Turris OS with default config. Connect to one of its LAN ports and open in your browser. Continue with configuration from there.

Fallback: Using a USB stick

If your Turris OS version is really old (not updated in years) then it won’t be able to connect to (missing TLS support, DNS failures). In this case, you can download the new Turris OS image (medkit) to a USB stick (using your browser) and install it from there. The procedure is outlined in the official documentation for Omnia and MOX.

Optional follow-up tasks

Return to old Turris OS

If you need to return to the old version of Turris OS you can easily do so:

# Find the snapshot we created ("Pre factory rollback")
old_snap=$(schnapps list | grep "Pre factory rollback" | sed -n -e 's/^\s\+\(\d\+\).*/\1/p')
[ -n "$old_snap" ] && echo "Snapshot of old Turris OS: $old_snap" \
  || echo "ERROR: Couldn't find pre factory rollback snapshot."

# Rollback to the snapshot and reboot
schnapps rollback $old_snap

Examine old config files

You might want to look up some of your old configuration. That’s also possible using snapshots:

# Let's create a mountpoint which we'll use to access the snapshot
mkdir -p /mnt/old-tos

# Find the snapshot we created ("Pre factory rollback")
old_snap=$(schnapps list | grep "Pre factory rollback" | sed -n -e 's/^\s\+\(\d\+\).*/\1/p')
[ -n "$old_snap" ] && echo "Snapshot of old Turris OS: $old_snap" \
  || echo "ERROR: Couldn't find pre factory rollback snapshot."

# Mount the snapshot read-only. If you manually moved your system to SSD then
# you'll need to replace `mmcblk0p1` with `sda1`.
mount -o subvol=@${old_snap},ro /dev/mmcblk0p1 /mnt/old-tos

You can now access your old system under /mnt/old-tos/. It’s mounted read-only to prevent any accidental changes. After a reboot you’ll need to re-mount it again using the above instructions.

I hope this guide helps some of you to get to a clean, up-to-date system! Have fun! :v:


It would be nice if this guide could be supplemented officially as part of Rescue mode documentation… would it be possible, team? @Pepe ?

Nice guide :slight_smile:

Maybe you can add checking the signatures as well:

usign -V -p /etc/updater/keys/ -x /tmp/$model-medkit-latest.tar.gz.sig -m /tmp/$model-medkit-latest.tar.gz

For Omnia 2019 and newer there is an easier way:

  1. Press the reset button and wait for 6 LEDs (Power, 0, 1, 2, 3, 4) to light up.
  2. Release the reset button.

See Flash from the internet in the Docs.

How could I check which version of system is installed as current “factory-reset” one?

mount -o subvol=/ /dev/mmcblk0p1 /mnt/.snapshots
cat /mnt/.snapshots/@factory/etc/turris-version
umount /mnt/.snapshots

Assuming that you’re using the default eMMC storage this should do the trick.

1 Like

Thanks! It did the trick!

The easier way would be turris-diagnostics system-info.

1 Like

Maybe, but it is compressed file :wink: I wanted to use this info in some scripts… (to keep refreshing factory reset image).

Have you tried to run it? It provides output to stdout. The compression is only something added on top of it if you wish.

It is not ideal for the scripting as it pulls other info as well, but the advantage is that it works for all routers, no matter the factory version, as that is the process required for support requests.

1 Like

Is there a way of changing the default IP address in the image prior to flashing it (e.g. mounting and editing a file)? Using @dhopfm 's mount hints to verify the snapshot version, I grepped the filesystem for and found two hits:

lib/preinit/00_preinit.conf and bin/config_generate.

I’m not going to go blindly changing things…Has anyone done this before?

Many thanks, it solved my problem with non-updatable Turris with OS 3

note that current version of TOS supports Updating factory image

1 Like

Thank you, this solve my problem.

Thanks for this walkthrough. I confirm that it worked correctly for upgrading TOS 3 to 6.5 even when on a machine with root FS on an mSATA SSD. :+1: