102 lines
3.1 KiB
Markdown
102 lines
3.1 KiB
Markdown
# NUC Fleet Netboot (Unifi + ProxyDHCP)
|
|
|
|
This runbook provisions x86_64 NUCs from runner netboot artifacts without USB image flashing.
|
|
|
|
It uses:
|
|
|
|
- Unifi DHCP for IP leases.
|
|
- Local `dnsmasq` ProxyDHCP for PXE/iPXE bootfile logic.
|
|
- Local HTTP + TFTP service for boot artifacts.
|
|
|
|
## Why ProxyDHCP
|
|
|
|
iPXE commonly needs two boot stages:
|
|
|
|
1. firmware PXE -> `ipxe.efi`
|
|
2. iPXE -> `netboot.ipxe`
|
|
|
|
If DHCP always returns `ipxe.efi`, clients can loop forever. ProxyDHCP handles stage-specific boot responses cleanly while leaving Unifi as the DHCP lease server.
|
|
|
|
## Prerequisites
|
|
|
|
- A Linux boot server on the same VLAN/L2 domain as the NUCs.
|
|
- Unifi network with normal DHCP enabled.
|
|
- Local DNS record on that VLAN: `boot.every.channel -> <boot-server-ip>`.
|
|
- `curl`, `tar`, `python3`, `dnsmasq` installed on the boot server.
|
|
- Runner netboot artifact already published to Forgejo Releases (or available as a local tarball).
|
|
|
|
## 1) Stage artifacts
|
|
|
|
From repository root on the boot server:
|
|
|
|
```sh
|
|
./scripts/netboot-stage.sh
|
|
```
|
|
|
|
Optional inputs:
|
|
|
|
- `EVERY_CHANNEL_NETBOOT_RELEASE_TAG=boot-v2026.02.28`
|
|
- `EVERY_CHANNEL_NETBOOT_TARBALL=/path/to/ec-runner-x86_64-netboot-....tar.gz`
|
|
- `EVERY_CHANNEL_FORGE_TOKEN=<token>` for private releases
|
|
- `EVERY_CHANNEL_NETBOOT_HOSTNAME=boot.every.channel`
|
|
|
|
This stages:
|
|
|
|
- `tmp/netboot/http/{kernel,initrd,netboot.ipxe}`
|
|
- `tmp/netboot/tftp/ipxe.efi`
|
|
|
|
## 2) Serve HTTP + TFTP + ProxyDHCP
|
|
|
|
Example (replace values for your VLAN):
|
|
|
|
```sh
|
|
sudo \
|
|
EVERY_CHANNEL_NETBOOT_LISTEN_IP=10.20.30.2 \
|
|
EVERY_CHANNEL_NETBOOT_INTERFACE=eth0 \
|
|
EVERY_CHANNEL_NETBOOT_PROXY_SUBNET=10.20.30.0/24 \
|
|
EVERY_CHANNEL_NETBOOT_HOSTNAME=boot.every.channel \
|
|
./scripts/netboot-serve.sh
|
|
```
|
|
|
|
Notes:
|
|
|
|
- Keep this process running during provisioning.
|
|
- Do not set Unifi DHCP bootfile options while this proxy mode is active.
|
|
- Ensure `boot.every.channel` resolves to the boot server IP from NUC clients.
|
|
|
|
## 3) Unifi / NUC settings
|
|
|
|
Unifi:
|
|
|
|
- Keep DHCP enabled for the provisioning VLAN.
|
|
- Leave DHCP boot/TFTP overrides unset when using `netboot-serve.sh`.
|
|
- Create/verify local DNS host override: `boot.every.channel -> <boot-server-ip>`.
|
|
|
|
NUC BIOS:
|
|
|
|
- Enable UEFI network boot (IPv4 PXE).
|
|
- Disable Legacy/CSM if possible.
|
|
- Put network boot before disk for first install cycle.
|
|
|
|
## 4) Provision the fleet
|
|
|
|
1. Boot each NUC on the provisioning VLAN.
|
|
2. PXE will chainload into iPXE and then runner `netboot.ipxe`.
|
|
3. Complete install/bootstrap flow on each node.
|
|
4. After successful install, switch boot order back to local disk.
|
|
|
|
## Troubleshooting
|
|
|
|
- Symptom: iPXE loop (`ipxe.efi` repeatedly)
|
|
- Cause: static DHCP bootfile without iPXE-aware logic.
|
|
- Fix: use ProxyDHCP flow (`netboot-serve.sh`) or set conditional DHCP rules.
|
|
- Symptom: NUC gets IP but never downloads boot artifacts
|
|
- Verify firewall allows UDP 67/68, UDP 69, and TCP 8080 between NUCs and boot server.
|
|
- Symptom: no `dnsmasq` offers seen
|
|
- Verify `EVERY_CHANNEL_NETBOOT_INTERFACE` and `EVERY_CHANNEL_NETBOOT_PROXY_SUBNET`.
|
|
|
|
## Security / networking
|
|
|
|
- Tailscale is not required for provisioning.
|
|
- Keep the provisioning VLAN isolated from regular clients.
|
|
- Stop `netboot-serve.sh` when rollout is complete.
|