nleymann

Installing Debian on Turris Omnia

There are a few websites describing the installation of Debian on Turris Omnia routers but in some cases the information is not 100% accurate and a bit outdated. Therefore I tried to assemble a new and updated tutorial.

Unfortunately I was not able to boot the router using uboot via bootp over the network (bootp failed and the Turris Omnia was not able to obtain a valid IP-Address). For the following description I used an USB/UART serial cable which is available from Amazon for about 15 Euro (this cable also works with other routers such as the Banana PI R3 aka BPI-R3). The description is based on information from the following sites:

It’s recommended to install Debian not on the build-in memory but on an additional mSATA SSD. 128GB are more than sufficient and cheap. In the following text we assume that the SSD is available as /dev/sda (partition /dev/sda1) and the USB stick as /dev/sdb (partition /dev/sdb1). If this is not the case you need to change commands as needed to reflect your specific setup.

First hurdle is the fact that – at least on my routers – the slots are used in the wrong order. The SSD needs to go into the rightmost slot which is already occupied by the WiFi module. So it is necessary to move the WiFi module to the leftmost slot. Next problem are the spacers which seem to be soldered to the board. New spacers are needed to install the WiFi module and SSD in the slots.

After moving the WiFi module and installing the it is necessary to plug-in the serial cable. cz.nic is providing a description of the wiring:

  • https://docs.turris.cz/hw/serial/

Warning: Colors and wiring are depending on your cable. Check the description at the cz.nic website and the description of your cable very carefully to make sure that you are using the right pins. With the cable above, wiring is as follows:

  • GND (black), first pin (left side)
  • RXD (white), second pin
  • TXD (blue), third pin

I used a Debian based system to connect to the Turris Omnia. Drivers for the cable were available by default and the device is /dev/ttyUSB0. Access is via a terminal program such as microcom:

microcom -s 115200 -p /dev/ttyUSB0

First of all it is necessary to mount the USB stick on your PC and to format it with ext3. Than mount the stick to /mnt/stick or something similar. I used an image from https://github.com/tmshlvck/turris-debian/releases:

https://github.com/tmshlvck/turris-debian/releases/download/bullseye-20211018/omnia-medkit-20211018.tar.gz

Download the image, copy it to the USB Stick, mount the USB stick and plug it into the Turris Omnia. Then install the image on the router. Details can be found under: https://github.com/tmshlvck/turris-debian/wiki. In short, you have to:

  • push the reset button on the router (and don’t release the button).
  • wait until 4th LED is lighting up and now release the button. This triggers the automatic installation from USB stick.
  • check on the console if everything goes as expected.

After installation the router will be rebooted and you will be greeted with an login prompt on the console (microcom window). Login using „root“/“turris“ as username/password. First of all check if the SSD is recognized by the system (we assume that the disk is available as /dev/sda):

fdisk -l

Create a partition and set it to bootable (if you are being as, chose „dos“ for partition table format):

cfdisk /dev/sda

Check, if partition is available (in our case it is /dev/sda1):

lsblk

Now we need to format the partition. Then we mount it and create the necessary structure for Debian:

mkfs.btrfs -f /dev/sda1
mkdir /mnt/ssd
mount /dev/sda1 /mnt/ssd
btrfs subvol create /mnt/ssd/@
cd /mnt/ssd/@

Next step is to mount the USB stick (assuming, it is known by the Omnia Turris as /dev/sdb1) and to extract the image on the SSD:

mkdir /mnt/usb
mount /dev/sdb1 /mnt/usb/
tar xvfz /mnt/usb/omnia-medkit-20211018.tar.gz

Now we have to change boot loader and path settings to be able to boot from the SSD (/dev/sda1)

ln -s \@/boot/boot.scr /mnt/ssd/boot.scr
chroot /mnt/ssd/\@/
/etc/kernel/postinst.d/z99-genbootscr /dev/sda1

Now we need to check if the correct device is used for booting (see following output from last command, boot-device should be /dev/sda1):

Root device: /dev/sda1
Kernel Image: /boot/vmlinuz-5.10.0-9-armmp
InitRD: /boot/initrd.img-5.10.0-9-armmp
Image Name:   boot
Created:      Sat Dec  9 07:41:22 2023
Image Type:   PowerPC Linux Script (uncompressed)
Data Size:    1367 Bytes = 1.33 KiB = 0.00 MiB
Load Address: 00000000
Entry Point:  00000000
Contents:
   Image 0: 1359 Bytes = 1.33 KiB = 0.00 MiB

Next step is to change the entry in /etc/fstab (entry for the newly installed Debian on the SSD) and to exit from the chroot environment.

sed -i 's%/dev/mmcblk0p1%/dev/sda1%' /etc/fstab
exit

Last (almost) step is to check again, if the correct device is used for the boot process (/dev/sda1 in our case).

cat /mnt/ssd/boot.scr

Should produce:

"W��?DbootOsetenv bootargs "earlyprintk console=$console pcie_aspm=off root=/dev/sda1 rootdelay=2 rootflags=subvol=@,commit=5 rw"
setenv omnia_boot_prep 'scsi scan;'
setenv omnia_boot_lk 'load scsi 0 ${kernel_addr_r} /@/boot/vmlinuz-5.10.0-9-armmp'
setenv omnia_boot_ldt_phy 'load scsi 0 ${fdt_addr_r} /@/boot/armada-385-turris-omnia-phy.dtb'
setenv omnia_boot_ldt_sfp 'load scsi 0 ${fdt_addr_r} /@/boot/armada-385-turris-omnia-sfp.dtb'
setenv omnia_fixup_mac0 'setexpr fmac0 gsub : " " $ethaddr; fdt resize; fdt set /soc/internal-regs/ethernet@70000 local-mac-address "[${fmac0}]"'
setenv omnia_fixup_mac1 'setexpr fmac1 gsub : " " $eth1addr; fdt resize; fdt set /soc/internal-regs/ethernet@30000 local-mac-address "[${fmac1}]"'
setenv omnia_fixup_mac2 'setexpr fmac2 gsub : " " $eth2addr; fdt resize; fdt set /soc/internal-regs/ethernet@34000 local-mac-address "[${fmac2}]"'
setenv omnia_boot_lrd 'load scsi 0 ${ramdisk_addr_r} /@/boot/initrd.img-5.10.0-9-armmp'
setenv omnia_boot_brd 'bootz ${kernel_addr_r} ${ramdisk_addr_r}:0x${filesize} ${fdt_addr_r};'
setenv omnia_boot 'run omnia_boot_prep; run omnia_boot_lk; if gpio input gpio@71_4; then echo SFP; run omnia_boot_ldt_sfp; else echo PHY; run omnia_boot_ldt_phy; fi; fdt addr ${fdt_addr_r}; run omnia_fixup_mac0; run omnia_fixup_mac1; run omnia_fixup_mac2; run omnia_boot_lrd; run omnia_boot_brd'
run omnia_boot

If everything looks ok we unmount the SSD and reboot the router

cd /
umount /mnt/ssd
reset

Last step is to add the correct settings to the boot loader (uboot). In order to do so we need to stop the boot process (again, in the console simply press a key as soon as the countdown starting with „3“ starts). After you have stopped the process you end up in the uboot console. Here we set the boot target to boot from our SSD:

setenv boot_targets "scsi0 mmc0 usb0 pxe dhcp"
saveenv
reset

That’s it. After reboot login to the router („root“/“turris“) and check if the correct device is mounted with „df“ our „mount“ (/dev/sda1 should show up as device for „/“). Now you can start configuring the network.

If you intend to compile your own kernel on the router, install necessary dependencies (but be warned, the compiler needs a couple of hours to create a custom kernel depending on your settings):

apt-get update
apt-get install git
apt-get install build-essential
apt-get install pkg-config libncurses-dev 
apt-get install flex bison libssl-dev bc
apt-get install rsync wget screen 
wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.10.136.tar.gz

make menuconfig
make -j2 bindeb-pkg