Immutable, flashable miner image (ISO): boot a USB and mine, fully tuned

[VijitSingh97]

Goal

Ship an immutable, flashable image (ISO / raw disk image) that turns a bare machine into a fully-tuned RigForge miner: flash a USB → boot → mining, with no OS install, no package setup, and no manual tuning. Long-term this — not a scripted install onto a general-purpose distro — is the target deployment for RigForge.

Companion to the stack-host installer epic: p2pool-starter-stack/pithead#77. That issue covers the stateful Docker stack host; this issue is the miner half, and the miner is where an immutable image fits best.

Why immutable is the right model for the miner

The miner is a stateless compute appliance — one tuned XMRig process pointed at a stratum endpoint, no wallet, no chain, nothing to persist. That makes immutability a near-perfect fit:

• Reflash-to-update is ideal. Nothing to migrate, so "pull new image, reflash" beats in-place upgrades. No drift; every rig is byte-identical.
• Tuning baked in at boot. HugePages (1 GB + 2 MB) need kernel cmdline params + a reboot; an image bakes them into the bootloader so they're active on first boot — this removes rigforge.sh's "reboot for HugePages to take effect" step entirely. Same for the MSR module, NUMA layout, hugetlbfs mounts, memlock, and the cpupower performance governor.
• Smaller surface, headless-friendly. A read-only single-purpose image is simpler and safer than a full distro, and is meant to run blind on a box with no monitor.
• "Borrow a machine to mine" UX. A diskless/USB-resident image can run without touching the host's disk — boot from USB, mine, pull the stick, the machine is untouched.

Deployment options — the DIY path stays first-class

This image is additive. RigForge keeps both ways to deploy:

1. Do-it-yourself (existing): on a machine you already run (Ubuntu/Debian/macOS), git clone + sudo ./rigforge.sh — full control, no reflashing.
2. Flash-and-go (new, this issue): a prebuilt immutable image you flash to a USB and boot.

Non-goal: deprecating rigforge.sh. It stays the install-onto-existing-OS path and the source of the tuning logic the image bakes in — one codebase, two delivery methods, not a fork.

Approaches (immutable-first)

• Alpine diskless mode (apkovl) — ⭐ likely the fastest path to a real immutable image. Boots from USB into RAM (read-only base); the XMRig service + config ride in a small apkovl overlay on the USB. Minimal build effort, tiny footprint.
• Buildroot — smallest and most locked-down: read-only squashfs rootfs + a writable overlay/partition for config. The build pipeline compiles upstream XMRig and bakes in all tuning. Most control, most effort (cross-compile toolchain, packaging XMRig + tuning, reflash-only updates). Proven for real appliances.
• mkosi — build a bespoke immutable image (read-only /usr) on an Alpine/Debian base, output as .raw/.iso. Flexible middle ground.
• bootc / image mode — build the appliance from a Containerfile, ship as a disk image, update from a container registry. Heavier base for a single-process appliance, but the registry-update path is attractive (and mirrors a possible stack direction).
• (Interim only) Ubuntu autoinstall ISO running rigforge.sh — fastest to stand up but not immutable; useful only as a stepping stone while the real image is built.

Recommendation: target an immutable image. Prototype quickly with Alpine diskless to validate the boot-and-mine flow + tuning, then evaluate Buildroot for the final locked-down appliance. Keep rigforge.sh as the "install onto an existing Ubuntu/Debian/macOS box" path — the image is the new flash-and-go path, not a replacement for the script.

Config / zero-config UX

The miner needs essentially one input: the stack/pool endpoint (plus an optional rig label, which can default to the hostname). Options, ideally support more than one:

• Writable config partition — a one-line file on a FAT partition the user edits before booting (P2POOL_NODE_HOSTNAME).
• Kernel cmdline param — pass the endpoint at boot.
• mDNS zero-config — RigForge already resolves <host>.local; the image could auto-discover the stack with no config at all on a typical LAN.

What to bake into the image

• Upstream XMRig, compiled at build time (with the DONATION patch applied), plus a CPU-profile-aware config.
• HugePages 1 GB + 2 MB via kernel cmdline; hugetlbfs mount; raised memlock.
• MSR kernel module + hardware-prefetcher control; NUMA binding; cpupower performance governor.
• XMRig as a managed service (systemd or Buildroot init) with log rotation and auto-restart.
• AVX2 detection at boot — warn/halt clearly on unsupported CPUs.

Build & release

• CI builds the image and publishes checksummed (ideally signed) .iso/.raw artifacts per release.
• Document the reflash-to-update path.
• Version the image independently of the stack (RigForge is its own repo); include a "known-good stack version" compatibility note rather than coupling versions.

Cross-cutting concerns

• UEFI + legacy BIOS, and Secure Boot.
• Diskless USB-run vs install-to-disk — decide whether to support one or both (diskless is the standout UX for the miner).
• Multi-rig: one image, per-rig identity via hostname/label so workers are distinguishable on the dashboard.
• Headless: must fully provision and recover with no console attached.

Acceptance criteria

• Flashing the image to a USB and booting bare metal yields XMRig mining against the configured (or auto-discovered) endpoint, fully tuned, with no interactive install.
• HugePages / MSR / governor are active on first boot (verify via XMRig's "huge pages 100%" / dataset init output) — no manual reboot dance.
• Documented build → flash → (minimal) config → boot steps.
• Checksummed release artifact; reflash-to-update documented.
• AVX2 / unsupported hardware is surfaced rather than silently failing.

Open questions

• Buildroot vs Alpine diskless for the final image.
• Diskless USB-run vs install-to-disk (or both)?
• Config: file-on-partition vs kernel cmdline vs mDNS zero-config (or a combination)?
• Independent image versioning vs a stack-compatibility note.

Relationship

• feat(tune): trustworthy measurement & decisions — variance gate, sustained/thermal, live A/B (#62, #63, #64) #77 — umbrella installer epic (stack host); this is the miner counterpart.
• Connection contract is unchanged: XMRig → STACK_HOST:3333 stratum, no wallet in the worker config.

Research sources

• Alpine diskless mode (apkovl): https://wiki.alpinelinux.org/wiki/Diskless_Mode
• Read-only rootfs + overlay (Bootlin): https://bootlin.com/blog/systemd-read-only-rootfs-and-overlay-file-system-over-etc/
• Buildroot manual (rootfs overlay, post-build/post-image): https://buildroot.org/downloads/manual/manual.html
• Buildroot real-world appliance (Home Assistant OS): https://developers.home-assistant.io/docs/operating-system/getting-started/
• mkosi (bespoke immutable images): https://mkosi.systemd.io/
• bootc install to bare metal: https://bootc.dev/bootc/bootc-install.html
• bootc-image-builder (ISO/disk outputs): https://github.com/osbuild/bootc-image-builder
• XMRig RandomX optimization guide: https://xmrig.com/docs/miner/randomx-optimization-guide

[VijitSingh97]

Feasibility check: pure "run-off-the-USB, no installer" model

Did a feasibility pass specifically on the diskless / live-run end of this issue (boot the USB, load everything into RAM, mine — never install to disk, pull the stick and the host is untouched). Short version: feasible, with shipping precedent, and it fits the miner better than the current compile-on-host script. Recommend treating diskless live-run as the primary target rather than just one option.

Precedent (this already exists for CPU/RandomX)

• MoneroS — ~12 MB Linux-from-scratch distro purely for mining Monero: burn ISO → USB → boot bare metal → mining, web monitor on :8080. Exactly this model. https://github.com/OodavidsinoO/MoneroS
• LinuxKit immutable live-USB XMRig build — boots and auto-starts XMRig. https://strm.sh/posts/mining-monero-using-a-live-linuxkit-build/
• GPU-side (Hive OS, PiMP, RaveOS, msOS) shows the boot-from-USB mining-appliance pattern is mature; the CPU/RandomX variant is the same shape.

Why it fits RigForge better than compile-on-host

• Tuning is config, not a special binary. rigforge.sh sets threads/asm/MSR/prefetch in config.json at runtime off the detected CPU; upstream XMRig does its own runtime CPU detection + JIT, so one prebuilt binary runs on any AVX2 x86-64. Bake one binary, generate config at boot from detected hardware — no per-host compile, no toolchain, no source clone on each boot. (The compile-time DONATION patch moves to image-build time.)
• The "reboot for HugePages" step disappears. That's the script's one hard reboot (GRUB cmdline). In a live image we own the bootloader, so default_hugepagesz=1G hugepagesz=1G hugepages=N (+ 2 MB) is active on first boot — and reserving 1 GB pages early at boot is the recommended approach to dodge fragmentation per the kernel docs. The reboot dance is gone, as already noted in the issue body.
• Stateless = ideal fit. No wallet/chain/state — one XMRig → stratum. Read-only root in RAM, power-cycle = clean state.

Caveats a spike must resolve (all surmountable)

1. Secure Boot ⇒ MSR writes blocked. Confirmed: EFI Secure Boot auto-enables kernel lockdown, and LOCKDOWN_MSR blocks writes to /dev/cpu/*/msr (man kernel_lockdown.7). MSR prefetcher tuning therefore needs Secure Boot off — which an unsigned custom live image needs anyway. Without MSR it still mines; you just lose a few % of the X3D/EPYC tuning. (Matches the existing README "disable Secure Boot" note.)
2. RAM budget. Live overlay in RAM + RandomX fast-mode dataset (~2.3 GB) is tight on low-RAM boxes. Mitigate with a USB persistence/overlay partition (keep overlay off RAM) and recommend 4 GB+.
3. USB write endurance. Run from RAM, send logs to tmpfs (or the persistence partition), don't hammer cheap flash.
4. Headless config + identity. Covered in the issue already (file-on-FAT / kernel cmdline / mDNS auto-discovery); per-rig identity from MAC/random so identical sticks don't collide on the dashboard.

Recommendation

Prototype the boot → detect → bake-tuning → mine loop with Alpine diskless (apkovl) to validate the flow fast, carrying a prebuilt XMRig + the existing config-generation logic from rigforge.sh. The Secure Boot/MSR and RAM-budget items are the two things worth nailing down early since they bound real-world hardware coverage.