Node Provisioner

node-provisioning/provision-rf-node.sh converts a stock Ubuntu 24.04 host into a node that can carry a real-radio DU, and node-provisioning/validate-rf-node.sh is the one evaluator of the result. Both ship in the release's installer package (racora-installer-<tag>.tar.gz) and are persisted on a provisioned host under /opt/racora/node-provisioning/. How they are used is Install the Control Node and Add a Radio Node; this page is what they do.

provision-rf-node.sh

Run as root. Idempotent and phased: by hand it completes one phase per run and asks for a reboot; with --install-service it drives itself through every phase and reboot.

Flag	Default	Meaning
--isolcpus <list>	auto	CPU cores to isolate for the DU PHY. Auto picks the last 4 cores on a host with 8 or more, the last 2 with 4 to 7, and none below 4 (a warning)
--pro-token <token>	none	Ubuntu Pro token, attached in phase 1 when the host is not attached already
--gpu auto|on|off	auto	GPU enablement; auto detects an NVIDIA GPU and skips cleanly when there is none
--skip-uhd	off	do not install UHD (a node without a B210)
--fronthaul auto|on|off	auto	the fronthaul stage; auto configures PTP only when a fronthaul-capable NIC exists
--ptp-mode gm|oc	gm	gm: this node's NIC clock is the grandmaster of the fronthaul segment; oc: an ordinary clock locking to an upstream grandmaster (also disables systemd-timesyncd)
--ptp-iface <if>	auto	the fronthaul NIC; auto takes the best detected candidate
--install-service	off	install and start the self-driving service, then exit
--on-complete <cmd>	none	a command run once when the node is provisioned; the installer's node mode passes its join finalizer. A failing hook only warns
--unattended	internal	used by the service: reboots between phases by itself
--nvidia-guard	internal	used by racora-nvidia-rt-guard.service at boot: re-applies the real-time bypass and rebuilds the NVIDIA module if a driver update dropped it, then exits

Invalid values for --gpu, --fronthaul and --ptp-mode exit 1; so does running as a non-root user.

Phases

1. Real-time kernel (reboot). Attaches Ubuntu Pro with the token when needed and enables the realtime-kernel service. Without a token on an unattached host it stops with the status STUCK.
2. GPU, UHD, fronthaul, isolation, tuning (one reboot for all of them).
   • GPU, first: installs DKMS, the kernel headers and the recommended NVIDIA driver, and the NVIDIA container toolkit. The driver's dkms.conf gets IGNORE_PREEMPT_RT_PRESENCE=1 baked in so every build, including a package postinst, passes the real-time check. The containerd nvidia runtime handler is not configured here; k3s configures it when the toolkit is present.
   • The NVIDIA guard, with the GPU: an unattended-upgrades blacklist in /etc/apt/apt.conf.d/51racora-nvidia-guard for the nvidia-, libnvidia- and xserver-xorg-video-nvidia packages, and racora-nvidia-rt-guard.service, a boot unit ordered before k3s.service, k3s-agent.service and kubelet.service that rebuilds the module if a driver update dropped it.
   • UHD: the ppa:ettusresearch/uhd repository, libuhd-dev and uhd-host, and uhd_images_downloader.
   • Fronthaul: ethtool and linuxptp, then the three fronthaul scripts (below) when a capable NIC exists.
   • Isolation: irqbalance disabled; isolcpus=, nohz_full= and rcu_nocbs= for the isolated set appended to the GRUB command line, after a timestamped backup of /etc/default/grub.
   • Tuning: tuned installed if missing, the racora TuneD profile installed and activated (tuned-adm profile racora).
3. Verification: runs validate-rf-node.sh with the same --gpu, --fronthaul and --skip-uhd settings plus --latency, and records the result. A failed check does not fail the provisioner.

The Self-Driving Service

--install-service writes the options to /etc/racora/provision.env (mode 600, since it may hold the Pro token), copies the scripts to /opt/racora/node-provisioning/, installs racora-provision.service (a oneshot that runs the provisioner with --unattended on every boot while the env file exists), writes a login banner script to /etc/update-motd.d/99-racora-provision, resets the reboot counter and starts the service. The provisioner reboots the host between phases, at most 6 times (/etc/racora/provision.reboots); past that it disables the service and reports STUCK. On completion it disables the service, removes the counter, runs the --on-complete command, and writes DONE to the status file.

Progress is readable in /etc/racora/provision.status (one line, the current step), in the login banner, and in journalctl -u racora-provision. Stopping it is systemctl disable --now racora-provision or removing the env file.

The Fronthaul Stage

Script	What it does
fronthaul/detect-fronthaul.sh	scans every physical NIC for hardware TX and RX timestamping and a PTP hardware clock; --record writes /etc/racora/fronthaul-inventory; --exclude a,b removes NICs from consideration. Prefers ports not carrying the default route, then ports with link up, then the highest speed, then the lowest PCI address. Exits 0 when a capable NIC exists, 1 otherwise
fronthaul/setup-ptp.sh	--iface <if> [--mode gm|oc] [--domain N] [--dst-mac MAC] [--phc2sys on|off]: renders and installs racora-ptp4l.service and racora-phc2sys.service with the ITU-T G.8275.1 defaults (domain 24, L2 transport, the non-forwardable multicast address 01:80:C2:00:00:0E, 8 announce, 16 sync and 16 delay-request messages per second). Idempotent: files are installed only on change
fronthaul/setup-rt-latency.sh	[--cpus auto|list] [--iface <if>] [--max-exit-latency <us>] (default 10): disables the idle states whose exit latency exceeds the limit on the isolated cores, steers the fronthaul NIC's IRQs to the housekeeping cores, turns hardware VLAN receive filtering off on that NIC, and installs the racora-rt-latency boot unit so all of it survives reboots

The TuneD Profile

racora-tuned/tuned.conf, installed as the racora profile, sets the kernel command line nosoftlockup nmi_watchdog=0 crashkernel=auto softlockup_panic=0 audit=0 mce=off tsc=nowatchdog skew_tick=1, the performance governor at maximum frequency, an idle state cap that TuneD drops silently on platforms without a cpufreq interface (which is why the fronthaul stage applies the cap itself), and scheduler, network and memory sysctls for a DU PHY and a GPU on the same node.

Standalone References

rt-kernel/install-rt-kernel.sh (only the real-time kernel step; warns on a release other than 24.04) and cpu-tuning/setup-cpu-isolation.sh (governor, isolation, irqbalance) are single-step references; the provisioner is the supported path.

validate-rf-node.sh

Run as root; changes no configuration. Flags: --gpu auto|on|off (default auto, which checks the GPU only when one is present), --fronthaul auto|on|off (default auto), --skip-uhd, --latency (a 30 s cyclictest, target under 50 µs). An unknown option exits 2.

Checks, as [PASS], [FAIL], [WARN] or [INFO]: the PREEMPT_RT kernel, CPU isolation, the racora TuneD profile, UHD (and whether a B210 is plugged in, informative only), the performance governor, irqbalance off; with a GPU, nvidia-smi and the container toolkit; with a fronthaul NIC, the NIC, the two PTP units, the PTP port state, the idle-state cap and the IRQ placement on the isolated cores. It exits 0 when no check failed and 1 otherwise, including a GPU or fronthaul failure that does not gate rf_ready; the capabilities file says which gates passed.

It writes /etc/racora/node-capabilities:

rf_ready=<true|false>           # RT kernel and isolation and the TuneD profile and UHD
gpu_ready=<true|false>          # nvidia-smi works and the container toolkit is installed
fronthaul_ready=<true|false>    # a capable NIC and PTP running and the RT-latency stage holding
fronthaul_nic=, fronthaul_phc=, kernel=, isolated_cpus=, evaluated_at=

The k3s platform turns the three *_ready values into the node labels at registration; on a cluster you run, platforms/kubernetes/label-node.sh does (The Node Contract).

Installer Pass-Throughs

Installer variable	Provisioner flag
INSTALL_RACORA_PRO_TOKEN	--pro-token
INSTALL_RACORA_ISOLCPUS	--isolcpus
INSTALL_RACORA_GPU	--gpu (node mode defaults it to off)
INSTALL_RACORA_FRONTHAUL	--fronthaul
INSTALL_RACORA_PTP_MODE	--ptp-mode

The installer always adds --install-service; node mode adds --on-complete with its join finalizer. INSTALL_RACORA_PROVISION decides whether the installer provisions at all: off (the default for a server install), check (warn when the host is not RF-ready), ensure (provision when it is not; the default in node mode). The pre-flight that decides is validate-rf-node.sh. Where the scripts come from: a release install runs them from the release's installer package; on a host Racora installed, a provision-rf run uses the persisted copy of that release's installer (/opt/racora/installer); on any other host it follows INSTALL_RACORA_VERSION when set and the repository's main branch otherwise; a checkout or an offline bundle uses them in place.