nearxos/reterminal-dm4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
66ad3b0a39a37d2fbb6c7f96501a6fbadff15102
reterminal-dm4/emmc-provisioning/docs/NETWORK-BOOT-DEPLOYMENT-FLOW.md

5.8 KiB
Raw Blame History

How network boot deployment works

This describes the full flow from power-on to eMMC deploy/backup when using network boot with the provisioning LXC.

Overview

  1. reTerminal is set to try network boot first (EEPROM BOOT_ORDER=0x21).
  2. It is connected to the same LAN as the LXC’s eth1 (e.g. 10.20.50.0/24).
  3. On power-on it gets an IP via DHCP and loads boot files via TFTP from the LXC.
  4. The netboot environment (kernel + rootfs) runs provisioning-client.sh, which registers with the dashboard and polls for an action.
  5. In the dashboard you see the device under “Device detected (Network)” and choose Deploy or Backup.
  6. The device performs the action (download image → write eMMC, or read eMMC → upload), then you can reboot to run from eMMC.

Step-by-step

1. LXC (provisioning server)

  • eth0 = WAN (e.g. 10.130.60.141), internet for the LXC.
  • eth1 = LAN (e.g. 10.20.50.1/24):
    • dnsmasq: DHCP on eth1 (e.g. 10.20.50.100–200) and TFTP with next-server = 10.20.50.1, boot file = start4cd.elf.
    • TFTP root /srv/tftpboot: Raspberry Pi 4/CM4 boot files (from GitHub: start4cd.elf, fixup4cd.dat, kernel8.img, etc.).
    • NAT: traffic from 10.20.50.0/24 is masqueraded out eth0 so netbooted devices have internet if needed.

The dashboard (Flask) runs in the LXC and is reachable at e.g. http://10.20.50.1:5000 from the LAN. The golden image for Deploy lives at /var/lib/cm4-provisioning/golden.img (same LXC or bind-mounted from host).

2. reTerminal (device)

  • EEPROM: BOOT_ORDER=0x21 (network first, then SD/eMMC). Can be set by cloud-init first-boot on an already-flashed device.
  • Network: Ethernet connected to the same segment as the LXC’s eth1 (e.g. same switch/VLAN as 10.20.50.0/24).
  • On power-on:
    1. Pi 4/CM4 firmware does DHCP on the wired interface.
    2. DHCP reply gives: IP (e.g. 10.20.50.100), next-server (TFTP) = 10.20.50.1, boot filename = start4cd.elf.
    3. Device TFTPs boot files from the LXC (start4cd.elf, fixup4cd.dat, kernel, DTB, etc.).
    4. It boots the kernel (and optionally an initramfs or NFS root). That environment must have network, curl, and provisioning-client.sh.

3. Netboot root / environment

The TFTP-loaded kernel (and optional initramfs/NFS root) must end up in an environment where:

  • The device has an IP on the same LAN as the LXC (already from DHCP).
  • provisioning-client.sh is present and run (e.g. from init, a login script, or a systemd service).
  • PROVISIONING_SERVER is set to the dashboard URL on the LXC’s LAN IP, e.g.
    PROVISIONING_SERVER=http://10.20.50.1:5000

So the “netboot environment” is either:

  • A custom initramfs (recommended): build with network-boot-initramfs/build.sh, copy initrd.img to the TFTP root, and add initramfs initrd.img followkernel to config.txt. The initramfs brings up the network and runs the provisioning client. See network-boot-initramfs/README.md.
  • A minimal rootfs (e.g. NFS) that runs the client script at boot, or
  • Any other setup that gets the client running with network and the right PROVISIONING_SERVER.

4. Provisioning client (on the device)

  • provisioning-client.sh:
    1. Registers: POST /api/register-device with MAC and IP.
    2. Polls: GET /api/device-action-poll?mac=... every few seconds.
    3. When the dashboard returns action = deploy (with url):
      downloads the image from url and runs dd of=/dev/mmcblk0.
    4. When the dashboard returns action = backup (with upload_url):
      runs dd if=/dev/mmcblk0 and POSTs the stream to upload_url.
    5. Then exits (and you can reboot to eMMC after deploy).

5. Dashboard (your actions)

  • You open the dashboard at http://10.20.50.1:5000 (or the LXC’s WAN IP if you’re not on the provisioning LAN).
  • Under “Device detected (Network)” you see the device (identified by MAC).
  • You click Deploy or Backup.
  • The dashboard sets the action (and URL/upload_url) for that MAC; the next device-action-poll returns it, and the client runs the corresponding dd + curl.

Data flow summary

Stage Where What happens
Boot reTerminal DHCP (get IP + next-server + boot file), then TFTP (load start4cd.elf, kernel, etc.).
Boot reTerminal Kernel (and netboot root) start; run provisioning-client.sh with PROVISIONING_SERVER=http://10.20.50.1:5000.
Register Device → LXC POST /api/register-device (MAC, IP).
Poll Device → LXC GET /api/device-action-poll?mac=... every 5 s.
Your choice You → LXC In dashboard: click Deploy or Backup for that device.
Deploy LXC → device Client GETs image URL, streams to dd of=/dev/mmcblk0.
Backup Device → LXC Client dd if=/dev/mmcblk0 and POSTs to upload_url.
After reTerminal Reboot; if you deployed, it can now boot from eMMC.

What you need in place

  • LXC: eth1 = 10.20.50.1/24, dnsmasq (DHCP + TFTP on eth1), /srv/tftpboot with RPi 4 boot files, NAT for 10.20.50.0/24 via eth0. Dashboard running, golden.img present for Deploy.
    See NETWORK-BOOT-LXC.md and setup-network-boot-on-lxc.sh.
  • reTerminal: EEPROM boot order = network first; Ethernet on 10.20.50.0/24; netboot environment that runs provisioning-client.sh with PROVISIONING_SERVER=http://10.20.50.1:5000.
  • Netboot root: Must provide network, curl, and the client script (NFS, initramfs, or custom root).

The TFTP setup only gets the Pi to boot a kernel (and optional root). The provisioning (Deploy/Backup) is done by that kernel’s environment running the network-client against the dashboard on the LXC.