Booting Turris Omnia NG from an NVMe SSD⚓︎

This guide details creating a system that runs entirely from an NVMe 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

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 NG router,
an NVMe 2230 or 2242 SSD drive,
an Internet connection,
a PH2 screwdriver (and a PH1 screwdriver for the 2230 drive),
a serial console cable

Hardware installation⚓︎

Make sure your Turris Omnia NG is not connected to the power supply.
Unscrew the six PH2 screws securing the top cover.
Remove the D-pad button.
Lift the top cover first at the rear part of the device and slide it out towards the front to avoid the D-pad stick at the front.
The M.2 M key NVMe slot is located at the front right part of the device next to the display.

Notice

2230 SSD drives require you to remove the mainboard from the bottom case, in order to reposition the M.2 holder for the card.

Device detection⚓︎

Plug your Omnia NG 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 "nvme"

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

Preparation of the SSD⚓︎

Notice

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

Back up 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 partition table by typing o (currently there are issues with the GPT partition table).
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/nvme0n1p1
```

Create a mount point and mount the partition on it:

mkdir -p /mnt/ssd && mount /dev/nvme0n1p1 /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-ng-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 NG 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 nvme0 usb0 pxe dhcp

Set the variable, so that NVMe is preferred over eMMC for the next boot:
```
setenv boot_targets nvme0 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/nvme0n1p1 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.