Booting Turris Omnia from an mSATA SSD⚓︎

This guide details creating a system that runs entirely from an mSATA SSD drive, bypassing the onboard NAND memory. The target system can either be a backup of your current system or a clean version of Turris OS.

Warning

This guide is only for Omnia 2019 or newer. For older series, please install the turris-nor-updatepackage and run the nor-update command from CLI or update your NOR via serial cable.

After setting up boot from SSD, you should avoid using the LuCI mount plugin as it tries to unmount all external drives including your SSD, and that would break your system until a reboot.

Notice

After setting up boot from SSD, parts of the rescue modes will not be usable, like reverting to the previous snapshot and factory reset. You can still manage your snapshots manually using schnapps.

Requirements⚓︎

a Turris Omnia router,
an mSATA SSD drive,
an Internet connection,
a PH2 and PH1 screwdriver,
a serial console cable

Hardware installation⚓︎

Make sure your Omnia is not connected to the power supply.
Unscrew the six PH2 screws securing the top cover.
Remove the top cover by sliding it out towards the front of the device, in order to avoid damaging the LED light pipes.
Move the already present PCIe cards by one position towards the SIM card slot.
Insert your mSATA SSD into the remaining slot (the one which is closest to the heatsink of the CPU), as it is the only one that supports the mSATA interface.

Tip

Because it’s a complex operation (which includes many steps) you can utilize our video guide:

Device detection⚓︎

Plug your Omnia into the power supply.
Connect to the router via SSH, or via a serial console.

Check whether the new SSD can be detected:

fdisk -l | grep "sd"

# It should display info about the disk:
Disk /dev/sda: 238.47 GiB, 256060514304 bytes, 500118192 sectors

Preparation of the SSD⚓︎

Notice

If you can no longer access your eMMC, or if you simply want to start with a clean system, you can use a medkit. Instead of backing up your system in step 1, skip to step 2.

Backup the current filesystem by creating and exporting a snapshot.
```
schnapps export -c /tmp/backup.tar.gz
```
Run fdisk to partition the SSD.
```
fdisk /dev/nvme0n1
```
Create a new dos or GPT partition table by typing o or g.
Create a new primary partition by typing n. Its size must be at least the same as the original one present on the eMMC (e.g., 8 GB).
Write the changes by typing w.
Create a filesystem on the new partition:
```
mkfs.btrfs /dev/sda1
```

Create a mount point and mount the partition on it:

mkdir -p /mnt/ssd && mount /dev/sda1 /mnt/ssd

Create a Btrfs subvolume for the root directory:
```
btrfs su cr /mnt/ssd/@
```
If you created a backup in step 1, unpack it into the new subvolume:
```
tar -C /mnt/ssd/@ -xvzf /tmp/backup.tar.gz
```
Or if you are starting with a clean system, unpack a current medkit into the new subvolume:
```
wget -O - https://repo.turris.cz/hbs/medkit/omnia-medkit-latest.tar.gz | tar -C /mnt/ssd/@ -xvzf -
```
Create a symlink to the boot.scr file:
```
cd /mnt/ssd && ln -s @/boot/boot.scr .
```
Leave the directory and unmount the SSD:
```
cd && umount /mnt/ssd
```

Updating U-Boot to boot from the SSD⚓︎

In order to boot from the SSD prepared in the previous steps, you need to modify the U-Boot environment.

Connect to your Omnia via a serial console.
Reboot the device and start pressing Enter repeatedly until the U-Boot prompt appears:
```
=>
```

Run printenv to check the original boot_targets environment variable:

printenv boot_targets

# The output:
boot_targets=mmc0 scsi0 usb0 pxe dhcp

Set the variable, so that NVMe is preferred over eMMC for the next boot:
```
setenv boot_targets scsi0 mmc0 usb0 pxe dhcp
```
You are setting this environment variable temporarily for this boot only, so you won’t get stuck with an unbootable device.
Boot to the system on the SSD:
```
run distro_bootcmd
```

After the system boots up, run the mount command to display what is actually mounted:

mount

# The output should look like this:
/dev/sda1 on / type btrfs (rw,noatime,ssd,discard=async,space_cache=v2,commit=5,subvolid=256,subvol=/@)

If everything went well, rerun the setenv command from step 4 and then write the environment variable permanently by running:
```
saveenv
```
Reboot your device by:
```
run distro_bootcmd
```

Notice

In case of an update of the U-Boot and its environment in one of our future releases, your setup could be overriden and hence you would need to repeat the above steps to configure the U-Boot again.

Info

The boot_prefixes variable specifies where to search for the boot directory (which is located on the @ subvolume now), whereas boot_targets defines the boot sequence,

Creating a factory image⚓︎

The last thing to do is to create a factory image, so you have something to return to if you run into trouble.

You just need to run:

schnapps update-factory

To rollback to the factory version, use the Factory reset button in reForis or the schnapps rollback factory command.

Credits⚓︎

This guide utilizes instructions originally written by drhm on our forum.