installation instructions for Turris Omnia

feels like a milestone, or at least a big step towards one

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 install process has two stages, and is intended that you
-    the device and add a serial console (although it may be handy
+    should not need to open the device and add a serial console
-    for visibility  and in case anything goes wrong). In outline
+    (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.
 
-      1. build a "recovery" system with useful btrfs tools
+    Installation using a USB stick
-      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
+    First, build the image for the USB stick. Review
-      5. use min-copy-closure -d /mnt/@ to copy the real configuration
+    :file:`examples/recovery.nix` in order to change the default
-         to the device
+    root password (which is ``secret``) and/or the SSH keys, then
-      6. reboot into a fully operational system
+    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.
 
-    Detailed instructions to follow...
   '';
 
   system = {
@@ -64,8 +164,8 @@
             hash = "sha256-PkdzUKZ0IpBiWe/RS70J76JKnBFzRblWcKlaIFNxnHQ=";
           };
           extraPatchPhase = ''
-          ${pkgs.openwrt.applyPatches.mvebu}
+            ${pkgs.openwrt.applyPatches.mvebu}
-        '';
+          '';
           config = {
             PCI = "y";
             OF = "y";
@@ -132,9 +232,6 @@
             PHY_MVEBU_A38X_COMPHY = "y"; # for eth2
             MARVELL_PHY = "y";
 
-            USB_XHCI_MVEBU = "y";
-            USB_XHCI_HCD = "y";
-
             MVPP2 = "y";
             MV_XOR = "y";
 
@@ -150,6 +247,12 @@
             NET_DSA = "y";
             NET_DSA_MV88E6XXX = "y"; # depends on PTP_1588_CLOCK_OPTIONAL
           };
+          conditionalConfig = {
+            USB = {
+              USB_XHCI_MVEBU = "y";
+              USB_XHCI_HCD = "y";
+            };
+          };
         };
 
         boot = {
@@ -185,7 +288,7 @@
           };
 
         boot.tftp = {
-          loadAddress = lim.parseInt "0x1000000";
+          loadAddress = lim.parseInt "0x1700000";
           kernelFormat = "zimage";
           compressRoot = true;
         };

examples/recovery.nix

@@ -22,6 +22,7 @@ in rec {
     ../modules/outputs/ubimage.nix
     ../modules/outputs/jffs2.nix
     ../modules/outputs/ext4fs.nix
+    ../modules/outputs/extlinux.nix
   ];
 
   kernel.config = {
@@ -33,8 +34,9 @@ in rec {
     serverip = "10.0.0.1"; # build machine or other tftp server
     freeSpaceBytes = 1024 * 1024 * 4;
   };
+  boot.loader.extlinux.enable = true;
 
-  hostname = "recovery";
+  hostname = "liminix-recovery";
 
   services.dhcpc = svc.network.dhcp.client.build {
     interface = config.hardware.networkInterfaces.lan2;
@@ -83,13 +85,23 @@ in rec {
     mnt = dir {};
   };
   rootfsType = "ext4";
+
   # sda is most likely correct for the boot-from-USB case. For tftp
   # it's overridden by the boot.scr anyway, so maybe it all works out
-  hardware.rootDevice = "/dev/sda1";
+  hardware.rootDevice = lib.mkForce "/dev/sda1";
+
   users.root = {
     # the password is "secret". Use mkpasswd -m sha512crypt to
     # create this hashed password string
     passwd = "$6$y7WZ5hM6l5nriLmo$5AJlmzQZ6WA.7uBC7S8L4o19ESR28Dg25v64/vDvvCN01Ms9QoHeGByj8lGlJ4/b.dbwR9Hq2KXurSnLigt1W1";
+
+
+    openssh.authorizedKeys.keys =
+      let fromBuild =
+            (builtins.readFile
+              ((builtins.toPath (builtins.getEnv "HOME")) + "/.ssh/authorized_keys")
+            );
+      in lib.splitString "\n" fromBuild;
   };
 
   defaultProfile.packages = with pkgs; [

modules/hardware.nix

@@ -76,7 +76,11 @@ in {
         default = [];
         example = ["ath9k" "ath10k"];
       };
-      rootDevice = mkOption { };
+      rootDevice = mkOption {
+        description = "Full path to preferred root device";
+        type = types.str;
+        example = "/dev/mtdblock3";
+      };
       networkInterfaces = mkOption {
         type = types.attrsOf types.anything;
       };

modules/kernel.nix

@@ -13,6 +13,16 @@ let
 
   type_service = pkgs.liminix.lib.types.service;
 
+  mergeConditionals = conf : conditions :
+    # for each key in conditions, if it is present in conf
+    # then merge the associated value into conf
+    lib.foldlAttrs
+      (acc: name: value:
+        if (conf ? ${name}) && (conf.${name} != "n")
+        then acc // value
+        else acc)
+      conf
+      conditions;
 in {
   options = {
     kernel = {
@@ -42,6 +52,20 @@ in {
           };
         '';
       };
+      conditionalConfig = mkOption {
+        description = ''
+          Kernel config options that should only be applied when
+          some other option is present.
+        '';
+        type = types.attrsOf (types.attrsOf types.nonEmptyStr);
+        default = {};
+        example = {
+          USB = {
+            USB_XHCI_MVEBU = "y";
+            USB_XHCI_HCD = "y";
+          };
+        };
+      };
       makeTargets = mkOption {
         type = types.listOf types.str;
       };
@@ -49,10 +73,15 @@ in {
   };
   config = {
     system.outputs =
-      let k = liminix.builders.kernel.override {
+      let
-            inherit (config.kernel) config src extraPatchPhase;
+        mergedConfig = mergeConditionals
-            targets = config.kernel.makeTargets;
+          config.kernel.config
-          };
+          config.kernel.conditionalConfig;
+        k = liminix.builders.kernel.override {
+          config = mergedConfig;
+          inherit (config.kernel) src extraPatchPhase;
+          targets = config.kernel.makeTargets;
+        };
       in {
         kernel = k.vmlinux;
         zimage = k.zImage;

modules/outputs/extlinux.nix

@@ -24,7 +24,7 @@ in {
       cd $out
       ${if wantsDtb then "cp ${o.dtb} dtb" else "true"}
       cp ${o.initramfs} initramfs
-      cp ${o.zimage}  kernel
+      cp ${o.zimage} kernel
       mkdir extlinux
       cat > extlinux/extlinux.conf << _EOF
       menu title Liminix

pkgs/schnapps/default.nix

@@ -3,9 +3,10 @@
 , fetchFromGitLab
 , makeWrapper
 , btrfs-progs
+, util-linux-small
 , lib
 }:
-let search_path = lib.makeBinPath [btrfs-progs];
+let search_path = lib.makeBinPath [btrfs-progs util-linux-small];
 in stdenv.mkDerivation {
   pname = "schnapps";
   version = "2.13.0";

pkgs/systemconfig/default.nix

@@ -92,10 +92,13 @@ in attrset:
         # case otherwise we will install into a ramfs/rootfs
         ""
       }
-      if test -d $dest/persist; then dest=$dest/persist; fi
+      if test -d \$dest/persist; then dest=\$dest/persist; fi
       cp -v -fP \$src/bin/* \$src/etc/* \$dest
       ${if attrset ? boot then ''
-        (cd \$dest && rm ./boot && ln -sf ${lib.strings.removePrefix "/" attrset.boot.target} ./boot)
+        (cd \$dest
+         if test -e boot ; then rm boot ; fi
+         ln -sf ${lib.strings.removePrefix "/" attrset.boot.target} ./boot
+        )
       '' else ""}
       EOF
       chmod +x $out/bin/install