admin.rst (6686B)
1 System Administration 2 ##################### 3 4 Services on a running system 5 **************************** 6 7 * add an s6-rc cheatsheet here 8 9 10 Flashing and updating 11 ********************* 12 13 14 15 Flashing from Liminix 16 ===================== 17 18 The flash procedure from an existing Liminix-system has two steps. 19 First we reboot the device (using "kexec") into an "ephemeral" 20 RAM-based version of the new configuration, then when we're happy it 21 works we can flash the image - and if it doesn't work we can reboot 22 the device again and it will boot from the old image. 23 24 25 Building the RAM-based image 26 ---------------------------- 27 28 To create the ephemeral image, build ``outputs.kexecboot`` instead of 29 ``outputs.default``. This generates a directory containing the root 30 filesystem image and kernel, along with an executable called `kexec` 31 and a `boot.sh` script that runs it with appropriate arguments. 32 33 For example 34 35 .. code-block:: console 36 37 nix-build -I liminix-config=./examples/arhcive.nix \ 38 --arg device "import ./devices/gl-ar750" 39 -A outputs.kexecboot && \ 40 (tar chf - result | ssh root@the-device tar -C /run -xvf -) 41 42 and then login to the device and run 43 44 .. code-block:: console 45 46 cd /run/result 47 sh ./boot.sh . 48 49 50 This will load the new kernel and map the root filesystem into a RAM 51 disk, then start executing the new kernel. *This is effectively a 52 reboot - be sure to close all open files and finish anything else 53 you were doing first.* 54 55 If the new system crashes or is rebooted, then the device will revert 56 to the old configuration it finds in flash. 57 58 59 Building the second (permanent) image 60 ------------------------------------- 61 62 While running in the kexecboot system, you can build the permanent 63 image and copy it to the device with :command:`ssh` 64 65 .. code-block:: console 66 67 build-machine$ nix-build -I liminix-config=./examples/arhcive.nix \ 68 --arg device "import ./devices/gl-ar750" 69 -A outputs.default && \ 70 (tar chf - result | ssh root@the-device tar -C /run -xvf -) 71 72 build-machine$ tar chf - result/firmware.bin | \ 73 ssh root@the-device tar -C /run -xvf - 74 75 Next you need to connect to the device and locate the "firmware" 76 partition, which you can do with a combination of :command:`dmesg` 77 output and the contents of :file:`/proc/mtd` 78 79 .. code-block:: console 80 81 <5>[ 0.469841] Creating 4 MTD partitions on "spi0.0": 82 <5>[ 0.474837] 0x000000000000-0x000000040000 : "u-boot" 83 <5>[ 0.480796] 0x000000040000-0x000000050000 : "u-boot-env" 84 <5>[ 0.487056] 0x000000050000-0x000000060000 : "art" 85 <5>[ 0.492753] 0x000000060000-0x000001000000 : "firmware" 86 87 # cat /proc/mtd 88 dev: size erasesize name 89 mtd0: 00040000 00001000 "u-boot" 90 mtd1: 00010000 00001000 "u-boot-env" 91 mtd2: 00010000 00001000 "art" 92 mtd3: 00fa0000 00001000 "firmware" 93 mtd4: 002a0000 00001000 "kernel" 94 mtd5: 00d00000 00001000 "rootfs" 95 96 Now run (in this example) 97 98 .. code-block:: console 99 100 flashcp -v firmware.bin /dev/mtd3 101 102 103 "I know my new image is good, can I skip the intermediate step?" 104 ---------------------------------------------------------------- 105 106 In addition to giving you a chance to see if the new image works, this 107 two-step process ensures that you're not copying the new image over 108 the top of the active root filesystem. Sometimes it works, but you 109 will at least need physical access to the device to power-cycle it 110 because it will be effectively frozen afterwards. 111 112 113 Flashing from the boot monitor 114 ============================== 115 116 If you are prepared to open the device and have a TTL serial adaptor 117 of some kind to connect it to, you can probably use U-Boot and a TFTP 118 server to download and flash the image. This is quite 119 hardware-specific, and sometimes involves soldering: please refer 120 to :ref:`serial`. 121 122 123 Flashing from OpenWrt 124 ===================== 125 126 .. CAUTION:: Untested! A previous version of these instructions 127 (without the -e flag) led to bricking the device 128 when flashing a jffs2 image. If you are reading 129 this message, nobody has yet reported on whether the 130 new instructions are any better. 131 132 If your device is running OpenWrt then it probably has the 133 :command:`mtd` command installed. After transferring the image onto the 134 device using e.g. :command:`ssh`, you can run it as follows: 135 136 .. code-block:: console 137 138 mtd -e -r write /tmp/firmware.bin firmware 139 140 The options to this command are for "erase before writing" and "reboot 141 after writing". 142 143 For more information, please see the `OpenWrt manual <https://openwrt.org/docs/guide-user/installation/sysupgrade.cli>`_ which may also contain (hardware-dependent) instructions on how to flash an image using the vendor firmware - perhaps even from a web interface. 144 145 Updating an installed system (JFFS2) 146 ************************************ 147 148 149 Adding packages 150 =============== 151 152 If your device is running a JFFS2 root filesystem, you can build 153 extra packages for it on your build system and copy them to the 154 device: any package in Nixpkgs or in the Liminix overlay is available 155 with the ``pkgs`` prefix: 156 157 .. code-block:: console 158 159 nix-build -I liminix-config=./my-configuration.nix \ 160 --arg device "import ./devices/mydevice" -A pkgs.tcpdump 161 162 nix-shell -p min-copy-closure root@the-device result/ 163 164 Note that this only copies the package to the device: it doesn't update 165 any profile to add it to ``$PATH`` 166 167 168 Rebuilding the system 169 ===================== 170 171 :command:`liminix-rebuild` is the Liminix analogue of :command:`nixos-rebuild`, although its operation is a bit different because it expects to run on a build machine and then copy to the host device. Run it with the same ``liminix-config`` and ``device`` parameters as you would run :command:`nix-build`, and it will build any new/changed packages and then copy them to the device using SSH. For example: 172 173 .. code-block:: console 174 175 liminix-rebuild root@the-device -I liminix-config=./examples/rotuer.nix --arg device "import ./devices/gl-ar750" 176 177 This will 178 179 * build anything that needs building 180 * copy new or changed packages to the device 181 * reboot the device 182 183 It doesn't delete old packages automatically: to do that run 184 :command:`min-collect-garbage`, which will delete any packages not in 185 the current system closure. Note that Liminix does not have the NixOS 186 concept of environments or generations, and there is no way back from 187 this except for building the previous configuration again. 188 189 190 Caveats 191 ------- 192 193 * it needs there to be enough free space on the device for all the new 194 packages in addition to all the packages already on it - which may be 195 a problem if a lot of things have changed (e.g. a new version of 196 nixpkgs). 197 198 * it cannot upgrade the kernel, only userland