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.
- 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
wget https://repo.turris.cz/hbs/medkit/$model-medkit-latest.tar.gz
wget https://repo.turris.cz/hbs/medkit/$model-medkit-latest.tar.gz.sha256
# If you get an error such as:
# wget: not an http or ftp url: https://repo.turris.cz/…
# wget: bad address 'repo.turris.cz'
# 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!
reboot
Your router will now boot into a vanilla Turris OS with default config. Connect to one of its LAN ports and open 192.168.1.1 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 repo.turris.cz (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
reboot
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! 
