path: root/docs/install-omnia.adoc

= NixOS on Turris Omnia

CAUTION: PCIe devices are not functional right now on the Turris Omnia!

The Turris Omnia is little bit more complex regarding the initial setup compared
to Turris Mox. One issue is that armv7 builds are not provided by official
Hydra. The second issue is that there is not a single reasonable installation
(such as SD card on Turris Mox).

Turris Omnia can be booted either from USB or internal disk or from internal
MMC. The USB drive is the easies to setup from PCs and thus it is suggested for
testing NixOS on your Turris Omnia. You can always return to the Turris OS just
by unplugging the USB drive.

== 1.) Updating U-Boot

The updated U-Boot is required to make Turris Omnia work with NixOS in most
cases. The reason is that the original U-Boot 2015.10 does not support booting
from USB or internal drive. The newer Turris Omnia routers have newer U-Boot
versions but always verify the U-Boot version before you continue by running the
following command as root on the router:

include::shards/install-uboot.adoc[]

----
strings /dev/mtd0 | grep 'U-Boot [0-9.]\+'
----

The minimal suggested version is U-Boot 2022.07.

=== Updating U-Boot on Turris OS

These instructions apply if you have SD card with Turris OS and want to use the
official way of updating firmware on Turris Mox. The minimal version of Turris
OS to get new stable version of U-Boot is Turris OS 6.0. Please update the
Turris OS installation to this version or newer before you continue.

The next step is to install `turris-nor-update` and run it:

----
opkg update
opkg install turris-nor-update
turris-nor-update
----

This should give you at least U-Boot 2022.07.

=== Updating U-Boot on NixOS

TODO

== 2.) Get tarball with NixOS

The initial system can either be downloaded from Gitlab or build locally. Note
that version available for download can be pretty old. It is just some version
that was build with latest commit to the NixTurris repository.

* TODO (we do not have CI builds yet)
* ./build-tarball.adoc[Documentation on how to build your own tarball]

== 3a.) Boot from USB drive

This is the easies option to get NixOS on Turris Omnia. You can prepare the
drive in any Linux system and then just plug it into the Omnia.

You should use some reliable and preferably USB 3.0 flash drive or just regular
SSD drive. The suggested minimal size is 8GB but that is pretty much every USB
drive on the market right now. You might want to use swap and thus make sure
that you use some higher quality one as swap can kill cheap flash drives pretty
fast.

You need to format the USB drive first. The required partition table is GPT. You
can use only one partition that would be preferably formatted with BTRFS. The
important thing is to set label `NixTurris` so boot can locate the correct
partition by it. 

It is up to you which tool are you going to use. The instructions here are going
to be for GNU Parted. The following shell log should give you an idea of what
you should do to get the correct layout:

----
~# parted /dev/sdx
(parted) mktable gpt
(parted) mkpart NixTurris 0% 100%
(parted) set 1 boot on
(parted) quit
~# mkfs.btrfs /dev/sdx1
----

The next step is to unpack the tarball to the USB drive.

----
~# mkdir -p mnt
~# mount /dev/sdx1 mnt
~# tar -xf nixos-system-armv7-linux.tar.xz -C mnt
~# umount mnt
~# eject /dev/sdx
----

Now you can take this drive and plug it in the Turris Omnia. The last step is to
instruct firmware to boot from USB.

TIP: If you have USB to serial converter (see
https://docs.turris.cz/hw/serial/#turris-omnia[official documentation]) then you
can trigger USB boot only once using it. You have to reboot Omnia and halt boot
process by pressing kbd:[Enter] few times once you see `U-Boot` booting. You
should get U-Boot prompt shortly after (the line starting with `> `). USB boot
is initialized by entering `run usb_boot` to it and confirming by kbd:[Enter].

You need to have `uboot-envtools` package installed on Turris OS or `ubootTools`
on NixOS.

First you have to verify your environment access configuration by printing the
current environment using `fw_printenv` (as root). You should get output with no
message informing you about invalid CRC. Do not proceed if you get it.

To set USB boot as a preferred method run:

----
fw_setenv boot_targets usb0 mmc0 nvme0 scsi0 pxe dhcp
----

Feel free to validate settings by running `fw_printenv` again.

Now you can reboot your Omnia to NixOS. The next step is to do first
configuration and for that you have to be able to ./initial-access.adoc[access
the router].

== 3b.) Install on internal storage

It is highly suggested not to use internal MMC for the whole system. The
suggested deployment is rather the `/boot` partition on MMC or the whole system
on internal drive (note that U-Boot might not be able to boot from all internal
drives).

TODO

WARNING: this is not fully supported at the moment as tarball contains in
`/boot` only Syslinux configuration and thus boot simply from `/boot` is not
possible. You have to copy kernel, initrd and dtb to the `/boot` partition and
modify Syslinux's configuration file.


== Reverting to Turris OS

The steps required to revert to Turris OS differ from how deep have you went
with installation. If you are lucky it is just about restarting U-Boot
environment, if not then you have to use Medkit to install Turris OS back.

=== Resetting U-Boot environment to the default

The modification suggested by this document are only to the single variable
(`boot_targets`). The revert to the previous value should be in most cases
enough. This can be done by (see previous usage in this document for required
packages):

----
fw_setenv boot_targets mmc0 nvme0 scsi0 usb0 pxe dhcp
----

You can also reset environment to the default if you want to be sure. For that
you need USB to serial converter connected (see
https://docs.turris.cz/hw/serial/#turris-omnia[official documentation]). Reboot
the board and halt boot process by pressing kbd:[Enter] few times once you see
`U-Boot` booting. You should get U-Boot prompt shortly after (the line starting
with `> `). To reset environment enter:

----
env default -a
saveenv
----

To continue boot you can enter command `boot`.

=== Using Medkit to install Turris OS back to the MMC

You have to do this only if you attempted installation on internal storage.
First you have to reset U-Boot environment and thus follow steps in the previous
section. Next follow the
https://docs.turris.cz/hw/omnia/rescue-modes/#re-flash-router[official medkit
steps].