feat(extensions): add netboot extension for full TFTP+NFS boot

iav · claude · iav · commit aef1c59ba0bb · 2026-04-15T19:30:49.000+03:00
Hooks:
- extension_prepare_config: validate variables, compute defaults for
  NETBOOT_TFTP_PREFIX / NETBOOT_NFS_PATH (shared by
  LINUXFAMILY/BOARD/BRANCH/RELEASE, or per-host when NETBOOT_HOSTNAME
  is set), normalize NETBOOT_CLIENT_MAC to PXELINUX 01-&lt;mac&gt; form,
  fail fast on bad ROOTFS_COMPRESSION/ROOTFS_EXPORT_DIR combinations.
- custom_kernel_config: enable ROOT_NFS, NFS_FS, NFS_V3, IP_PNP,
  IP_PNP_DHCP so root=/dev/nfs ip=dhcp works without an initrd.
- post_customize_image: drop armbian-resize-filesystem.service
  (meaningless on NFS root) and /root/.not_logged_in_yet (the
  armbian-firstlogin interactive wizard blocks bring-up when there is
  no interactive console). armbian-firstrun.service stays — it only
  regenerates SSH host keys.
- host_pre_docker_launch: append a bind-mount for ROOTFS_EXPORT_DIR to
  DOCKER_EXTRA_ARGS when the directory lives outside ${SRC}, using the
  hook's documented mechanism.
- pre_umount_final_image: assemble the TFTP tree (Image/zImage, dtb/,
  uInitrd), write pxelinux.cfg/{default.example | 01-&lt;mac&gt;} with the
  right FDT/FDTDIR line and explicit INITRD directive when uInitrd is
  present, expose a netboot_artifacts_ready hook for userpatches.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/extensions/netboot/netboot.sh b/extensions/netboot/netboot.sh
@@ -0,0 +1,219 @@
+#
+# SPDX-License-Identifier: GPL-2.0
+# Copyright (c) 2026 Igor Velkov
+# This file is a part of the Armbian Build Framework https://github.com/armbian/build/
+#
+# Netboot: produce kernel + DTB + extlinux.conf + rootfs.tgz for TFTP/NFS root
+# boot without local storage. See Developer-Guide_Netboot.md for server setup
+# (tftpd-hpa + nfs-kernel-server + router DHCP options) and for the
+# `netboot_artifacts_ready` hook used to auto-deploy artifacts to a server.
+#
+# Variables:
+#   NETBOOT_SERVER            IP of TFTP/NFS server. If empty, nfsroot= uses
+#                             ${serverip} (filled by U-Boot from DHCP siaddr).
+#   NETBOOT_TFTP_PREFIX       Path prefix inside TFTP root. Default:
+#                             armbian/${LINUXFAMILY}/${BOARD}/${BRANCH}-${RELEASE}
+#   NETBOOT_NFS_PATH          Absolute NFS path of rootfs on the server.
+#                             Default depends on NETBOOT_HOSTNAME — see below.
+#   NETBOOT_HOSTNAME          Per-host deployment. When set, default NFS path
+#                             becomes /srv/netboot/rootfs/hosts/<hostname>
+#                             (each machine owns a full writable rootfs copy).
+#                             When empty, shared/${LINUXFAMILY}/${BOARD}/... is used.
+#   NETBOOT_CLIENT_MAC        Client MAC (aa:bb:cc:dd:ee:ff or aa-bb-cc-dd-ee-ff).
+#                             When set, PXE config is written as `01-<mac>`
+#                             (PXELINUX per-MAC override) instead of `default`;
+#                             multiple boards can then coexist on one TFTP root.
+#
+# Hook:
+#   netboot_artifacts_ready   Called after all artifacts are staged. Exposed
+#                             context: NETBOOT_TFTP_OUT, NETBOOT_TFTP_PREFIX,
+#                             NETBOOT_NFS_PATH, NETBOOT_PXE_FILE,
+#                             NETBOOT_ROOTFS_ARCHIVE (may be empty if
+#                             ROOTFS_COMPRESSION=none), plus BOARD/LINUXFAMILY/
+#                             BRANCH/RELEASE. Use it from userpatches to rsync
+#                             to a netboot server, unpack the rootfs archive,
+#                             etc. For builder-as-NFS-server workflows prefer
+#                             ROOTFS_EXPORT_DIR to skip the archive step.
+
+function extension_prepare_config__netboot_defaults_and_validate() {
+	declare -g NETBOOT_SERVER="${NETBOOT_SERVER:-}"
+	declare -g NETBOOT_HOSTNAME="${NETBOOT_HOSTNAME:-}"
+	declare -g NETBOOT_CLIENT_MAC="${NETBOOT_CLIENT_MAC:-}"
+	declare -g NETBOOT_TFTP_PREFIX="${NETBOOT_TFTP_PREFIX:-armbian/${LINUXFAMILY}/${BOARD}/${BRANCH}-${RELEASE}}"
+
+	if [[ -n "${NETBOOT_HOSTNAME}" ]]; then
+		declare -g NETBOOT_NFS_PATH="${NETBOOT_NFS_PATH:-/srv/netboot/rootfs/hosts/${NETBOOT_HOSTNAME}}"
+	else
+		declare -g NETBOOT_NFS_PATH="${NETBOOT_NFS_PATH:-/srv/netboot/rootfs/shared/${LINUXFAMILY}/${BOARD}/${BRANCH}-${RELEASE}}"
+	fi
+
+	if [[ -n "${NETBOOT_CLIENT_MAC}" ]]; then
+		declare -g NETBOOT_CLIENT_MAC_NORMALIZED="${NETBOOT_CLIENT_MAC//:/-}"
+		NETBOOT_CLIENT_MAC_NORMALIZED="${NETBOOT_CLIENT_MAC_NORMALIZED,,}"
+		if [[ ! "${NETBOOT_CLIENT_MAC_NORMALIZED}" =~ ^[0-9a-f]{2}-[0-9a-f]{2}-[0-9a-f]{2}-[0-9a-f]{2}-[0-9a-f]{2}-[0-9a-f]{2}$ ]]; then
+			exit_with_error "${EXTENSION}: NETBOOT_CLIENT_MAC must look like aa:bb:cc:dd:ee:ff (got '${NETBOOT_CLIENT_MAC}')"
+		fi
+	fi
+
+	# Fail-fast on bad ROOTFS_COMPRESSION/ROOTFS_EXPORT_DIR combos before debootstrap,
+	# not hours later in create_image_from_sdcard_rootfs.
+	case "${ROOTFS_COMPRESSION:-gzip}" in
+		gzip | zstd | none) ;;
+		*) exit_with_error "${EXTENSION}: unknown ROOTFS_COMPRESSION: '${ROOTFS_COMPRESSION}' (expected: gzip|zstd|none)" ;;
+	esac
+	if [[ "${ROOTFS_COMPRESSION:-gzip}" == "none" && -z "${ROOTFS_EXPORT_DIR}" ]]; then
+		exit_with_error "${EXTENSION}: ROOTFS_COMPRESSION=none requires ROOTFS_EXPORT_DIR (otherwise nothing is produced)"
+	fi
+}
+
+# Ensure NFS-root client support is built into the kernel.
+function custom_kernel_config__netboot_enable_nfs_root() {
+	opts_y+=("ROOT_NFS" "NFS_FS" "NFS_V3" "IP_PNP" "IP_PNP_DHCP")
+}
+
+# armbian-resize-filesystem tries to grow the root fs on first boot via resize2fs.
+# On an NFS-mounted root that's always meaningless (and would error) — strip the
+# systemd enablement symlink so the unit never runs.
+function post_customize_image__netboot_disable_resize_filesystem() {
+	[[ "${ROOTFS_TYPE}" == "nfs-root" ]] || return 0
+	display_alert "${EXTENSION}: disabling armbian-resize-filesystem.service" "meaningless on NFS root" "info"
+	run_host_command_logged find "${SDCARD}/etc/systemd/system/" \
+		-name "armbian-resize-filesystem.service" -type l -delete
+}
+
+# /etc/profile.d/armbian-check-first-login.sh launches the armbian-firstlogin
+# whiptail wizard (root password → user → locale …) when /root/.not_logged_in_yet
+# exists. On netboot there is often no interactive console on first boot, so the
+# wizard blocks the whole bring-up. Drop the trigger flag; default root/1234 login
+# keeps working, and armbian-firstrun.service still regenerates SSH host keys.
+function post_customize_image__netboot_skip_firstlogin_wizard() {
+	[[ "${ROOTFS_TYPE}" == "nfs-root" ]] || return 0
+	[[ -f "${SDCARD}/root/.not_logged_in_yet" ]] || return 0
+	display_alert "${EXTENSION}: skipping armbian-firstlogin wizard" "no interactive console assumed on netboot" "info"
+	run_host_command_logged rm -f "${SDCARD}/root/.not_logged_in_yet"
+}
+
+# ROOTFS_EXPORT_DIR must be visible inside the build container at the same path the
+# in-container rsync writes to — otherwise data lands in the container's private
+# filesystem and disappears on umount. Two cases:
+#   1) Path already under ${SRC}: core already bind-mounts ${SRC} at
+#      ${DOCKER_ARMBIAN_TARGET_PATH} (/armbian) inside the container, so the data
+#      path IS host-visible — but the env var still holds the host path, which
+#      does not exist in the container. Translate the env var to the container
+#      path so rsync writes into the bind-mounted volume.
+#   2) Path outside ${SRC}: add an explicit bind-mount at the same path.
+function host_pre_docker_launch__netboot_mount_export_dir() {
+	[[ -z "${ROOTFS_EXPORT_DIR}" ]] && return 0
+	if [[ "${ROOTFS_EXPORT_DIR}" == "${SRC}"* ]]; then
+		declare container_export_dir="${DOCKER_ARMBIAN_TARGET_PATH:-/armbian}${ROOTFS_EXPORT_DIR#"${SRC}"}"
+		display_alert "${EXTENSION}: translating ROOTFS_EXPORT_DIR for container" "${ROOTFS_EXPORT_DIR} -> ${container_export_dir}" "info"
+		mkdir -p "${ROOTFS_EXPORT_DIR}"
+		DOCKER_EXTRA_ARGS+=("--env" "ROOTFS_EXPORT_DIR=${container_export_dir}")
+		return 0
+	fi
+	mkdir -p "${ROOTFS_EXPORT_DIR}"
+	display_alert "${EXTENSION}: bind-mounting ROOTFS_EXPORT_DIR into container" "${ROOTFS_EXPORT_DIR}" "info"
+	DOCKER_EXTRA_ARGS+=("--mount" "type=bind,source=${ROOTFS_EXPORT_DIR},target=${ROOTFS_EXPORT_DIR}")
+}
+
+function pre_umount_final_image__900_collect_netboot_artifacts() {
+	[[ "${ROOTFS_TYPE}" == "nfs-root" ]] || return 0
+
+	# shellcheck disable=SC2154 # ${version} is a readonly global set in create_image_from_sdcard_rootfs
+	declare tftp_out="${DEST}/images/${version}-netboot-tftp"
+	declare tftp_prefix_dir="${tftp_out}/${NETBOOT_TFTP_PREFIX}"
+	declare pxe_dir="${tftp_out}/pxelinux.cfg"
+	run_host_command_logged mkdir -pv "${tftp_prefix_dir}/dtb" "${pxe_dir}"
+
+	# Kernel image: arm64 uses Image, armv7 uses zImage. Preserve source basename
+	# so U-Boot `booti`/`bootz` still picks the right path via image header.
+	declare kernel_src="" kernel_name=""
+	if [[ -f "${MOUNT}/boot/Image" ]]; then
+		kernel_src="${MOUNT}/boot/Image"
+		kernel_name="Image"
+	elif [[ -f "${MOUNT}/boot/zImage" ]]; then
+		kernel_src="${MOUNT}/boot/zImage"
+		kernel_name="zImage"
+	elif [[ -f "${MOUNT}/boot/vmlinuz-${IMAGE_INSTALLED_KERNEL_VERSION}" ]]; then
+		kernel_src="${MOUNT}/boot/vmlinuz-${IMAGE_INSTALLED_KERNEL_VERSION}"
+		# vmlinuz-* is a generic bzImage/Image; prefer Image for arm64, zImage otherwise
+		[[ "${ARCH}" == "arm64" ]] && kernel_name="Image" || kernel_name="zImage"
+	fi
+	[[ -n "${kernel_src}" ]] || exit_with_error "${EXTENSION}: kernel image not found under ${MOUNT}/boot"
+	run_host_command_logged cp -v "${kernel_src}" "${tftp_prefix_dir}/${kernel_name}"
+
+	if [[ -d "${MOUNT}/boot/dtb" ]]; then
+		run_host_command_logged cp -a "${MOUNT}/boot/dtb/." "${tftp_prefix_dir}/dtb/"
+	fi
+
+	declare initrd_line=""
+	if [[ -f "${MOUNT}/boot/uInitrd" ]]; then
+		run_host_command_logged cp -v "${MOUNT}/boot/uInitrd" "${tftp_prefix_dir}/uInitrd"
+		initrd_line="INITRD ${NETBOOT_TFTP_PREFIX}/uInitrd"
+	fi
+
+	# When NETBOOT_SERVER is empty, leave ${serverip} literal in nfsroot= so
+	# U-Boot expands it at `pxe boot` time from DHCP siaddr (path 2).
+	declare nfsroot_server="${NETBOOT_SERVER:-\${serverip\}}"
+
+	# Intentionally no `console=` in APPEND: hardcoding a baud (e.g. 115200)
+	# breaks boards like helios64 which run at 1500000. Kernel resolves console
+	# from DTB `/chosen/stdout-path`; `earlycon` keeps the early output.
+
+	# BOOT_FDT_FILE is not set for every board (e.g. helios64) — U-Boot then
+	# resolves DTB via its own ${fdtfile} env. FDTDIR handles both cases.
+	declare fdt_line
+	if [[ -n "${BOOT_FDT_FILE}" && "${BOOT_FDT_FILE}" != "none" ]]; then
+		fdt_line="FDT ${NETBOOT_TFTP_PREFIX}/dtb/${BOOT_FDT_FILE}"
+	else
+		fdt_line="FDTDIR ${NETBOOT_TFTP_PREFIX}/dtb"
+	fi
+
+	# Per-MAC override wins over `default` in U-Boot `pxe get`. Multiple boards
+	# can share one TFTP root with distinct `01-<mac>` files.
+	declare pxe_file
+	if [[ -n "${NETBOOT_CLIENT_MAC_NORMALIZED}" ]]; then
+		pxe_file="01-${NETBOOT_CLIENT_MAC_NORMALIZED}"
+	else
+		pxe_file="default.example"
+	fi
+
+	cat > "${pxe_dir}/${pxe_file}" <<- EXTLINUX_CONF
+		# Generated by ${EXTENSION} for ${BOARD} ${BRANCH} ${RELEASE}
+		# Target NFS path: ${NETBOOT_NFS_PATH}
+		DEFAULT armbian
+		TIMEOUT 30
+		PROMPT 0
+
+		LABEL armbian
+		    MENU LABEL Armbian ${BOARD} ${BRANCH} ${RELEASE} (netboot)
+		    KERNEL ${NETBOOT_TFTP_PREFIX}/${kernel_name}
+		    ${fdt_line}${initrd_line:+
+		    ${initrd_line}}
+		    APPEND root=/dev/nfs nfsroot=${nfsroot_server}:${NETBOOT_NFS_PATH},tcp,v3 ip=dhcp rw rootwait earlycon loglevel=7 panic=10
+	EXTLINUX_CONF
+
+	display_alert "${EXTENSION}: artifacts ready" "${tftp_out}" "info"
+	display_alert "${EXTENSION}: TFTP payload" "${NETBOOT_TFTP_PREFIX}/ (${kernel_name}, dtb/, uInitrd)" "info"
+	display_alert "${EXTENSION}: PXE config" "pxelinux.cfg/${pxe_file}" "info"
+	display_alert "${EXTENSION}: target NFS path" "${NETBOOT_NFS_PATH}" "info"
+
+	# Expose context to the deploy hook. rootfs.tgz is built by the NFS ROOTFS_TYPE
+	# path earlier in the pipeline; its path follows the same ${version} naming.
+	declare -g NETBOOT_TFTP_OUT="${tftp_out}"
+	declare -g NETBOOT_PXE_FILE="${pxe_file}"
+	# ROOTFS_ARCHIVE_PATH is set by create_image_from_sdcard_rootfs after the archive
+	# is produced (honours ROOTFS_COMPRESSION=gzip|zstd). Empty when ROOTFS_COMPRESSION=none.
+	declare -g NETBOOT_ROOTFS_ARCHIVE="${ROOTFS_ARCHIVE_PATH:-}"
+
+	call_extension_method "netboot_artifacts_ready" <<- 'NETBOOT_HOOK_DOC'
+		*called after netboot TFTP tree and rootfs are staged*
+		Implementations can rsync ${NETBOOT_TFTP_OUT} to a TFTP server, extract
+		${NETBOOT_ROOTFS_ARCHIVE} into ${NETBOOT_NFS_PATH} on an NFS server, etc.
+		When the build host IS the NFS server, prefer ROOTFS_EXPORT_DIR (skips
+		the archive step and writes straight into the export path).
+		Exposed context: NETBOOT_TFTP_OUT, NETBOOT_TFTP_PREFIX, NETBOOT_PXE_FILE,
+		NETBOOT_NFS_PATH, NETBOOT_ROOTFS_ARCHIVE (may be empty), NETBOOT_HOSTNAME,
+		NETBOOT_CLIENT_MAC, plus BOARD, LINUXFAMILY, BRANCH, RELEASE.
+	NETBOOT_HOOK_DOC
+}
