Skip to content

tools/lab: fresh-environment lab — real install.sh on fresh Alpine VMs with simulated ISPs (DHCP, PPPoE, DHCPv6-PD) and a LAN client - #149

Merged
Cd1s merged 20 commits into
mainfrom
lab/fresh-env
Oct 17, 2026
Merged

Cd1s merged 20 commits into
mainfrom
lab/fresh-env

Conversation

@Cd1s

@Cd1s Cd1s commented Oct 17, 2026

Copy link
Copy Markdown
Owner

What

tools/lab/ — a fresh-environment lab for testing mini-router the way users install it. Each lab (IDs 1–8, in parallel) is a QEMU/KVM guest booted from the official Alpine 3.24 x86_64 cloud image (+ linux-lts), a simulated ISP and a LAN client, all in network namespaces:

  • lab.sh install gives the guest a new disk and runs the unmodified install.sh (MR_YES=1 MR_LOCAL=…) after the first boot finished, from a seeded offline Alpine mirror (official signed APKINDEX + exactly the packages install.sh asks for) — nothing in the guest is stubbed. --tree DIR / MR_LAB_TREE tests another checkout, --release vX.Y.Z a published release.
  • ISP simulator: DHCP (also a modem on the LAN's own 192.168.1.0/24, --gw), static, PPPoE (CHAP, bad password, no PADO, CGNAT), IPv6 RA and DHCPv6-PD (kea), cable pulled.
  • LAN client checks (lan dhcp|check|exec), panel API (api, change <patch> = apply + wait + confirm / leave pending), a root console over virtio-serial that works with the network down, reboot, powercut.
  • Scenarios (TAP): 01-fresh-dhcp, 02-pppoe-pd, 03-move-dhcp-samesubnet, 04-powercut-confirm, 05-isp-switch-live.
  • README: a one-page quick reference for test agents first.

Why

The CI renders configs and runs the daemons in namespaces, but never runs install.sh on a real Alpine machine. This lab found three install bugs that every fresh machine hit: #142 (fixed in #143), #145 (PR #147, a regression from #138) and #146 (PR #148).

Dependencies

Root on a Linux host with KVM; qemu-system-x86 qemu-utils slirp4netns iproute2 nftables dnsmasq-base ppp pppoe radvd kea-dhcp6-server genisoimage socat curl jq busybox and Go. Binaries only: their system services stay disabled — lab.sh starts every daemon inside a lab namespace with its own config (dnsmasq --conf-file=/dev/null; kea under its AppArmor profile in a private mount namespace with lab directories over /etc/kea, /run, /var/lib/kea), and up warns if a host dnsmasq / kea / radvd service runs. Images and caches: ~1.5 GiB in /root/build/mr-lab-images.

Host safety

  • No host bridge, route, nftables rule or sysctl: links, addresses and daemons live in mrlab<ID>-* namespaces; the ISP namespace reaches the internet through slirp4netns (user-mode NAT), its subscriber NAT is an nft table inside that namespace.
  • Every namespace has its own /etc/netns/<ns>/resolv.conf (and the ISP its own /etc/ppp); the LAN client's DHCP uses a private udhcpc script — the BusyBox default would overwrite the host's /etc/resolv.conf.
  • A guard hashes the host's /etc/resolv.conf, /etc/hosts and /etc/ppp/** before and after every lab.sh command and fails the command, with a diff, if anything changed.
  • down removes only mrlab<ID>* objects. After the runs: resolver hash unchanged, ip -br link | grep -c mrlab = 0. The only host-kernel side effect: pppd loads ppp_generic.

Why not in GitHub Actions

It needs root, /dev/kvm, network namespaces with slirp4netns, ~1.5 GiB of images downloaded from the Alpine CDN and a few minutes per scenario (one guest boot plus install each); GitHub's hosted runners have no KVM, so it would be slow and flaky there. The lab scripts are shellchecked by the existing tools/ci.sh; the lab itself is run on the build host (by people or test agents) before releases and for install / WAN changes.

Verification

On IN, five labs in parallel, main (ce5f0a6) + #147: 01 6/6, 02 8/8, 03 11/11, 04 8/8, 05 5/6. The one not ok is a product gap: when the line moves from PPPoE to DHCP, mr doctor only says "no IPv4 address on pppoe-wan". Plain main today: every scenario stops at the install (#145).

🤖 Generated with Claude Code

Cd1s and others added 20 commits October 17, 2026 21:21
…o agent console, deferred install, PPPoE/PD ISP rework
….sh change, scenarios on lib.sh, A1c report

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ubnet modems after #138

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…host's /run, cleanup on every exit

- the cloud image and the minirootfs are fixed versions with pinned SHA256s (checked against Alpine's
  .sha512 / .sha256); the package chroot is always re-extracted from the verified tarball
- one lock (mr-lab-images/.build.lock) for all shared image initialisation; temp dirs from mktemp;
  loop mounts on fresh mount points, unmounted by the exit trap
- veth pairs are created inside the lab namespaces (ip -n <sw> link add ... peer ... netns <ns>)
- pppoe-server and its pppd run with a private tmpfs /run: no /run/ppp0.pid or pppd2.tdb on the host
- processes are stopped TERM first, KILL after 3 s; isp_stop / ns_del signal everything inside the
  lab namespace, pid files only a process whose name still matches; powercut goes through kill_qemu
- host guard: INT/TERM/HUP run it in dash, symlinks under /etc/ppp, a baseline across commands
  (lab.sh guard-reset); up refuses to run next to host dnsmasq / kea / radvd services
- scenarios: the lab is taken down on any exit (MRLAB_KEEP=1 keeps it), failed setup steps bail out
- README: dependencies (mask services before installing; python3, openssh-client; no socat),
  download trust, host safety

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Cd1s
Cd1s merged commit 6103f0b into main Oct 17, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant