commit 49ec4a296101af199e6e85886d7082e1db0ed365
parent c8154a2db99f0d0c6b5e47c279d6b83d8e69cb8f
Author: Daniel Barlow <dan@telent.net>
Date: Sun, 4 Feb 2024 18:20:04 +0000
installation instructions for Turris Omnia
feels like a milestone, or at least a big step towards one
Diffstat:
2 files changed, 114 insertions(+), 14 deletions(-)
diff --git a/devices/turris-omnia/default.nix b/devices/turris-omnia/default.nix
@@ -10,19 +10,119 @@
to work (and provides you an easy rollback if you decide you don't
like Liminix after all).
- The install process is designed so that you should not need to open
- the device and add a serial console (although it may be handy
- for visibility and in case anything goes wrong). In outline
-
- 1. build a "recovery" system with useful btrfs tools
- 2. boot that system using TFTP or a USB stick
- 3. once booted, mount the real root filesystem on /mnt
- 4. take a snapshot using schnapps, and then delete everything
- 5. use min-copy-closure -d /mnt/@ to copy the real configuration
- to the device
- 6. reboot into a fully operational system
-
- Detailed instructions to follow...
+ The install process has two stages, and is intended that you
+ should not need to open the device and add a serial console
+ (although it may be handy for visibility, and in case anything
+ goes wrong). First we build a minimal installation/recovery
+ system, then we reboot into that recovery image to prepare the
+ device for the full target install.
+
+ Installation using a USB stick
+ ==============================
+
+ First, build the image for the USB stick. Review
+ :file:`examples/recovery.nix` in order to change the default
+ root password (which is ``secret``) and/or the SSH keys, then
+ build it with
+
+ $ nix-build -I liminix-config=./examples/recovery.nix \
+ --arg device "import ./devices/turris-omnia" \
+ -A outputs.mbrimage -o mbrimage
+ $ file -L mbrimage
+ mbrimage: DOS/MBR boot sector; partition 1 : ID=0x83, active, start-CHS (0x0,0,5), end-CHS (0x6,130,26), startsector 4, 104602 sectors
+
+ Next, copy the image from your build machine to a USB storage
+ medium using :command:`dd` or your other most favoured file copying
+ tool, which might be a comand something like this:
+
+ $ dd if=mbrimage of=/dev/path/to/the/usb/stick \
+ bs=1M conv=fdatasync status=progress
+
+ The Omnia's default boot order only checks USB after it has failed
+ to boot from eMMC, which is not ideal for our purpose. Unless you
+ have a serial cable, the easiest way to change this is by booting
+ to TurrisOS and logging in with ssh:
+
+ root@turris:/# fw_printenv boot_targets
+ boot_targets=mmc0 nvme0 scsi0 usb0 pxe dhcp
+ root@turris:/# fw_setenv boot_targets usb0 mmc0
+ root@turris:/# fw_printenv boot_targets
+ boot_targets=usb0 mmc0
+ root@turris:/# reboot -f
+
+ It should now boot into the recovery image. It expects a network
+ cable to be plugged into LAN2 with something on the other end of
+ it that serves DHCP requests. Check your DHCP server logs for a
+ request from a ``liminix-recovery`` host and figure out what IP
+ address was assigned.
+
+ $ ssh liminix-recovery.lan
+
+ You should get a "Busybox" banner and a root prompt. Now you can
+ start preparing the device to install Liminix on it. First we'll
+ mount the root filesystem and take a snapshot:
+
+ # mkdir /dest && mount /dev/mmcblk0p1 /dest
+ # schnapps -d /dest create "pre liminix"
+ # schnapps -d /dest list
+ ERROR: not a valid btrfs filesystem: /
+ # | Type | Size | Date | Description
+ ------+-----------+-------------+---------------------------+------------------------------------
+ 1 | single | 16.00KiB | 1970-01-01 00:11:49 +0000 | pre liminix
+
+ (``not a valid btrfs filesystem: /`` is not a real error)
+
+ then we can remove all the files
+
+ # rm -r /dest/@/*
+
+ and then it's ready to install the real Liminix system onto. On
+ your build system, create the Liminix configuration you wish to
+ install: here we'll use the ``rotuer`` example.
+
+ build$ nix-build -I liminix-config=./examples/rotuer.nix \
+ --arg device "import ./devices/turris-omnia" \
+ -A outputs.systemConfiguration
+
+ and then use :command:`min-copy-closure` to copy it to the device.
+
+ build$ nix-shell --run \
+ "min-copy-closure -r /dest/@ root@liminix-recovery.lan result"
+
+ and activate it
+
+ build$ ssh root@liminix-recovery.lan \
+ "/dest/@/$(readlink result)/bin/install /dest/@"
+
+ The final steps are performed directly on the device again: add
+ a symlink so U-Boot can find :file:`/boot`, then restore the
+ default boot order and reboot into the new configuration.
+
+ # cd /dest && ln -s @/boot .
+ # fw_setenv boot_targets "mmc0 nvme0 scsi0 usb0 pxe dhcp"
+ # cd / ; umount /dest
+ # reboot
+
+
+ Installation using a TFTP server and serial console
+ ===================================================
+
+ If you have a :ref:`serial` console connection and a TFTP server,
+ and would rather use them than fiddling with USB sticks, the
+ :file:`examples/recovery.nix` configuration also works
+ using the ``tftpboot`` output. So you can do
+
+ build$ nix-build -I liminix-config=./examples/recovery.nix \
+ --arg device "import ./devices/turris-omnia" \
+ -A outputs.tftpboot
+
+ and then paste the generated :file:`result/boot.scr` into
+ U-Boot, and you will end up with the same system as you would
+ have had after booting from USB. If you don't have a serial
+ console connection you could probably even get clever with
+ elaborate use of :command:`fw_setenv`, but that is left as
+ an exercise for the reader.
+
'';
system = {
diff --git a/examples/recovery.nix b/examples/recovery.nix
@@ -36,7 +36,7 @@ in rec {
};
boot.loader.extlinux.enable = true;
- hostname = "recovery";
+ hostname = "liminix-recovery";
services.dhcpc = svc.network.dhcp.client.build {
interface = config.hardware.networkInterfaces.lan2;
