feat(extensions): add netboot extension for TFTP+NFS diskless boot#9656
Open
iav wants to merge 20 commits intoarmbian:mainfrom
Open
feat(extensions): add netboot extension for TFTP+NFS diskless boot#9656iav wants to merge 20 commits intoarmbian:mainfrom
iav wants to merge 20 commits intoarmbian:mainfrom
Conversation
iav
requested review from
a team,
EvilOlaf,
TRSx80,
igorpecovnik and
littlecxm
as code owners
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (15)
🚧 Files skipped from review as they are similar to previous changes (13)
📝 WalkthroughWalkthroughAdds a new netboot mode ( ChangesNetboot feature & deployment
Archive & metadata preservation + host ownership semantics
Sequence DiagramsequenceDiagram
participant Builder as Builder Host
participant Ext as Netboot Extension
participant Staging as TFTP/NFS Staging
participant Remote as Remote Server
participant Target as Target U‑Boot
Builder->>Ext: build with ROOTFS_TYPE=nfs-root
Ext->>Staging: validate NETBOOT_*, normalize paths, stage kernel/DTB/uInitrd, generate PXE configs
Ext->>Staging: create rootfs archive or rsync export (preserve owners/xattrs/ACLs)
Ext->>Builder: emit netboot_artifacts_ready (TFTP tree, PXE config, ROOTFS_ARCHIVE)
Builder->>Remote: rsync TFTP payload + pxelinux configs
Builder->>Remote: upload & extract ROOTFS_ARCHIVE (optional, preserve metadata)
Target->>Remote: DHCP/PXE -> download kernel/DTB/initrd via TFTP
Target->>Target: initramfs dhcpcd hook may set ROOTSERVER -> mount NFS root
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip 💬 Introducing Slack Agent: The best way for teams to turn conversations into code.Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.
Built for teams:
One agent for your entire SDLC. Right inside Slack. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
05
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@extensions/netboot/netboot.sh`:
- Around line 38-42: The function
extension_prepare_config__netboot_force_nfs_rootfs sets ROOTFS_TYPE too late (it
runs during do_extra_configuration) so NFS-specific branches in
do_main_configuration never see it; move the ROOTFS_TYPE assignment earlier by
ensuring extension_prepare_config__netboot_force_nfs_rootfs (or its logic) runs
before do_main_configuration—either call that function in the init/startup hook
that executes prior to main configuration (e.g., extension_init or top-level
script before do_main_configuration) or export/set declare -g ROOTFS_TYPE="nfs"
at script initialization so the global variable is in effect for
do_main_configuration and the NFS setup in
lib/functions/configuration/main-config.sh executes.
- Around line 147-149: The PXE staging copies ${MOUNT}/boot/uInitrd but never
references it in the generated extlinux.cfg, so U-Boot won't load the initramfs;
modify the netboot stanza generation to set an initrd_line variable when the
file exists (mirror how fdt_line is created — e.g. check for
"${MOUNT}/boot/uInitrd", set initrd_line="INITRD ${tftp_prefix_dir}/uInitrd")
and then include ${initrd_line} in the emitted PXE stanza alongside fdt_line so
the INITRD directive is present for U-Boot.
In `@extensions/netboot/README.md`:
- Around line 137-155: The README has multiple unlabeled fenced code blocks
(e.g., the directory tree block showing "/srv/netboot/" and other blocks around
lines 159-164, 171-175, 465-489, 544-547); update each triple-backtick fence to
include an appropriate info string (for example use sh, ini, or text as
appropriate) so markdownlint stops flagging them—locate the fences by searching
for the blocks that display the directory tree and configuration snippets and
add the matching language tag to each opening ``` line.
In `@lib/functions/image/rootfs-to-image.sh`:
- Around line 82-93: The rsync into ROOTFS_EXPORT_DIR can leave stale files
behind when the export tree is reused; update the rsync invocation in
rootfs-to-image.sh (the run_host_command_logged rsync call) to include --delete
(and optionally --delete-excluded) so files removed from the source are removed
from "${ROOTFS_EXPORT_DIR}" as well; add the flag either into $rsync_ea or
directly in the rsync command invocation to ensure exported NFS root mirrors the
built image.
- Around line 69-76: The archive creation pipeline (tar … | pv … |
${archive_filter} > "${ROOTFS_ARCHIVE_PATH}") must be guarded with pipefail so
failures in tar or pv aren't masked by a later stage; wrap that pipeline in a
shell context with set -o pipefail (or enable set -o pipefail locally before
running the pipeline) so a nonzero exit from tar or pv will cause the script to
fail and propagate the error from creating ROOTFS_ARCHIVE_PATH; update the block
around display_alert/ tar / pv / ${archive_filter} to ensure pipefail is active
for that pipeline.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: fca3bef5-36a8-4aaa-81dd-645853e7579e
📒 Files selected for processing (5)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/netboot.shlib/functions/configuration/main-config.shlib/functions/image/rootfs-to-image.sh
iav
added a commit
to iav/armbian
that referenced
this pull request
Apr 12, 2026
`nfs-root` is a new rootfs type distinct from the existing `nfs` hybrid mode. Selecting it wires the `netboot` extension from the core `ROOTFS_TYPE` dispatch in `do_main_configuration`, so callers no longer need a separate `ENABLE_EXTENSIONS=netboot`. The legacy `nfs` branch (kernel+DTB on local boot partition, `/` over NFS) is untouched — both paths coexist until the hybrid mode's future is decided. Core plumbing mirrors the `nfs` branch for all paths where local root storage would be meaningless: partition layout skip (`prepare_partitions`), archive/export gate and version suffix (`rootfs-to-image.sh`), and the host-side filesystem compatibility check in `main-config.sh`. Extension hooks now key on `ROOTFS_TYPE=nfs-root` instead of guessing from `nfs`, removing the `force ROOTFS_TYPE=nfs` shim that ran too late relative to `do_main_configuration`. Also folded in from CodeRabbit review on PR armbian#9656: - pipefail around tar|pv|compressor so truncated archives no longer slip through on an intermediate stage failure - `rsync --delete` on `ROOTFS_EXPORT_DIR` so stale files from a previous build don't linger in the NFS export tree - explicit `INITRD` directive in extlinux when `uInitrd` is staged; U-Boot only loads an initramfs when the stanza names it - README updated to document `ROOTFS_TYPE=nfs-root` as the single switch Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Member
|
Very nice. With recent u-boot (2026.04, thanks to Kwiboo), one can enable LWIP networking stack for better TFTP performance (loading kernel and initramfs) -- there's also some TFTP Window Size stuff that can be tuned. U-boot with LWIP + u-boot's |
Contributor
Author
|
Thanks for the pointer! Let's get this merged first — iterating on something that works is the easy part. |
iav
force-pushed
the
enh/netboot-extension
branch
from
a76e4b2 to
fec99ac
Compare
iav
force-pushed
the
enh/netboot-extension
branch
5 times, most recently
from
a10feb4 to
4ff6016
Compare
Contributor
Author
|
@coderabbitai review |
Contributor
Author
|
Pull my Helios64 to v2026.04 in #9675 |
iav
force-pushed
the
enh/netboot-extension
branch
4 times, most recently
from
a61ff64 to
dac19c8
Compare
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@extensions/netboot/README.md`:
- Around line 437-444: The README incorrectly states that rsync performs kernel
reflinks on btrfs/xfs; update the text near ROOTFS_EXPORT_DIR to remove or
reword the claim that "the kernel reflinks the rootfs tree" and instead explain
that while bind-mounting and rsync preserve ownership, rsync will copy data
unless explicit reflink tooling or filesystem-level copy-on-write (e.g., cp
--reflink or filesystem snapshot mechanisms) is used; reference
ROOTFS_EXPORT_DIR and the rsync-in-container behavior so readers understand the
export remains fast only when reflink/cow mechanisms are explicitly employed,
not automatically by rsync.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 1e89d51b-0cb5-41e2-936a-6b5ab8d6bd19
📒 Files selected for processing (13)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/configuration/main-config.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
✅ Files skipped from review due to trivial changes (3)
- extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel
- lib/functions/image/partitioning.sh
- config/templates/nfs-boot.cmd.template
🚧 Files skipped from review as they are similar to previous changes (4)
- lib/functions/rootfs/rootfs-create.sh
- extensions/netboot/netboot-deploy.sh
- extensions/netboot/netboot.sh
- lib/functions/image/rootfs-to-image.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@extensions/netboot/README.md`:
- Around line 659-660: The example uses a glob "output/images/*-netboot-tftp/"
which can accidentally merge multiple build outputs into "/srv/netboot/tftp/";
update the README example to point at a specific build directory instead of the
wildcard (e.g., replace "output/images/*-netboot-tftp/" with the specific build
directory name for the target board/release) and keep the destination
"/srv/netboot/tftp/"; update the example text so readers must substitute their
exact build directory (referencing the string "output/images/*-netboot-tftp/"
and the destination "/srv/netboot/tftp/").
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 7bdbb458-1561-4a19-9941-b926c8ce368d
📒 Files selected for processing (14)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
🚧 Files skipped from review as they are similar to previous changes (4)
- lib/functions/rootfs/rootfs-create.sh
- config/templates/nfs-boot.cmd.template
- lib/functions/image/rootfs-to-image.sh
- extensions/netboot/netboot-deploy.sh
2 tasks
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@extensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdog`:
- Around line 14-16: The watchdog currently writes "b" to /proc/sysrq-trigger
which is a no-op if kernel sysrq is disabled; modify the script around the sleep
600 block so it first attempts to enable sysrq by writing "1" to
/proc/sys/kernel/sysrq (check the write/result), then trigger the sysrq reboot
via echo b > /proc/sysrq-trigger only if enabling succeeded, and if enabling or
triggering fails fallback to a forced reboot command (e.g., busybox reboot -f or
echo c to /proc/sysrq-trigger / invoking kexec/reboot alternative) so the
watchdog cannot silently hang.
- Line 11: Update the inaccurate comment in zz-netboot-watchdog: replace "Force
kernel panic + PSCI reset after 10 min if NFS root mount hangs." with text that
correctly describes the action performed by the script (e.g. "Trigger immediate
reboot via SysRq 'b' (not a kernel panic) + PSCI reset after 10 min if NFS root
mount hangs.") so the comment accurately reflects that echo b >
/proc/sysrq-trigger issues an immediate reboot rather than causing a kernel
panic.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 6ff8f58e-7371-4aee-b74b-ab78af14a2f0
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
✅ Files skipped from review due to trivial changes (1)
- extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel
🚧 Files skipped from review as they are similar to previous changes (7)
- lib/functions/rootfs/create-cache.sh
- lib/functions/image/partitioning.sh
- lib/functions/rootfs/rootfs-create.sh
- extensions/netboot/files/initramfs-hooks/netboot-rootpath
- config/templates/nfs-boot.cmd.template
- extensions/netboot/netboot-deploy.sh
- extensions/netboot/netboot.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In
`@extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel`:
- Around line 9-11: In zz-netboot-watchdog-cancel, don't pass raw pidfile
contents to kill; read /run/netboot-watchdog.pid, trim whitespace, validate it
matches a numeric regex and is within a safe range (e.g. >1), verify the PID
refers to a live process (kill -0 or /proc/$pid exists) and only then call kill;
if validation fails, log/ignore and remove the stale pidfile rather than sending
a signal to an unintended process.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: e1c86711-3099-4f4e-a87d-3dca25f2de02
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
🚧 Files skipped from review as they are similar to previous changes (6)
- lib/functions/image/partitioning.sh
- lib/functions/configuration/main-config.sh
- extensions/netboot/files/initramfs-hooks/netboot-rootpath
- lib/functions/rootfs/rootfs-create.sh
- config/templates/nfs-boot.cmd.template
- lib/functions/image/rootfs-to-image.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@extensions/netboot/netboot.sh`:
- Around line 446-480: The TFTP staging subtree (${tftp_prefix_dir}) is never
cleared so stale files (old DTBs, uInitrd) can persist across incremental
builds; before copying artifacts (kernel via kernel_src, dtbs, uInitrd) remove
or clean the contents of ${tftp_prefix_dir} (but keep the directory itself) and
recreate any required subdirs (e.g. dtb and pxe_dir) so subsequent
run_host_command_logged cp -v / cp -a operations only copy current ${MOUNT}/boot
artifacts; ensure this cleaning happens just after declaring
tftp_prefix_dir/pxe_dir and before copying kernel, dtb, and initrd so
dtb_payload and INITRD checks reflect the fresh tree.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: cd4ac0fe-9415-4f52-b343-21e8d9d1347a
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
🚧 Files skipped from review as they are similar to previous changes (9)
- lib/functions/rootfs/create-cache.sh
- extensions/netboot/files/dhcpcd-hooks/71-netboot-rootpath
- lib/functions/image/partitioning.sh
- lib/functions/configuration/main-config.sh
- extensions/netboot/files/initramfs-hooks/netboot-rootpath
- lib/functions/rootfs/rootfs-create.sh
- config/templates/nfs-boot.cmd.template
- lib/functions/image/rootfs-to-image.sh
- extensions/netboot/netboot-deploy.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@extensions/netboot/netboot-deploy.sh`:
- Around line 44-48: The script must fail fast if the remote side is not
effectively root for NFS updates: update the logic around NETBOOT_DEPLOY_SUDO,
the archive untar routine (where tar --numeric-owner is used) and the
kernel-only sync to require either NETBOOT_DEPLOY_SUDO=yes or an effective
remote UID of 0; implement a remote check (ssh "$host" 'id -u' or similar)
before running tar/rsync/mkdir/tar that preserve numeric owners and if neither
condition is true exit with a clear error; tighten the NETBOOT_DEPLOY_SUDO
help/contract text to state it is required when the SSH account cannot act as
root for rsync/mkdir/tar on TFTP_ROOT and NETBOOT_NFS_PATH; apply the same
check/exit logic to the other similar blocks mentioned (archive untar and
/lib/modules sync locations).
- Around line 545-550: The rsync that syncs
"${scratch_dir}/usr/lib/linux-image-${kver}/" to
"${NETBOOT_DEPLOY_SSH}:${NETBOOT_DEPLOY_TFTP_ROOT}/${NETBOOT_TFTP_PREFIX}/dtb/"
copies new DTBs but does not remove DTBs removed or renamed in the package, so
add the delete option to the rsync invocation (i.e. include --delete among the
"${rsync_base[@]}" options passed to run_host_command_logged_raw) for the dtb
sync to mirror the full-image deploy behavior and ensure removed DTBs are pruned
from the target.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: adade000-f830-4a0c-832c-83fad6ccc028
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
🚧 Files skipped from review as they are similar to previous changes (6)
- lib/functions/rootfs/create-cache.sh
- lib/functions/image/partitioning.sh
- lib/functions/configuration/main-config.sh
- lib/functions/rootfs/rootfs-create.sh
- extensions/netboot/files/dhcpcd-hooks/71-netboot-rootpath
- lib/functions/image/rootfs-to-image.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@lib/functions/rootfs/rootfs-create.sh`:
- Around line 26-27: The tar extraction in the rootfs cache restore (the tar xp
invocation in create-cache.sh) is missing the --sparse flag so sparse-file
extents recorded during creation are lost; update the extraction command (the
tar xp --numeric-owner --xattrs
--xattrs-include="${ROOTFS_TAR_XATTR_INCLUDE:-security.*}" --acls --selinux ...
-C "${SDCARD}"/ invocation) to include --sparse so restored files preserve
sparse metadata and match the creation command used in rootfs-create.sh.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 6c34a51f-bbf3-489f-bca4-e0f135b4485d
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
✅ Files skipped from review due to trivial changes (1)
- extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel
🚧 Files skipped from review as they are similar to previous changes (8)
- lib/functions/image/partitioning.sh
- extensions/netboot/files/initramfs-hooks/netboot-rootpath
- extensions/netboot/files/dhcpcd-hooks/71-netboot-rootpath
- lib/functions/configuration/main-config.sh
- config/templates/nfs-boot.cmd.template
- lib/functions/rootfs/create-cache.sh
- lib/functions/image/rootfs-to-image.sh
- extensions/netboot/netboot-deploy.sh
Contributor
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel (1)
17-17:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winMake watchdog cancellation tolerant to stale/already-exited PIDs.
killcan legitimately fail (race, stale pidfile). Mask the exit status to avoid unintended script abort in errexit contexts.Based on learnings, Armbian shell execution generally assumes `set -e`, so unhandled non-zero statuses can terminate flow unexpectedly.Suggested patch
- [ "${watchdog_pid}" -gt 1 ] && kill "${watchdog_pid}" 2> /dev/null + [ "${watchdog_pid}" -gt 1 ] && kill "${watchdog_pid}" 2> /dev/null || true🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel` at line 17, In zz-netboot-watchdog-cancel make the watchdog PID kill tolerant to stale/exited PIDs by masking kill's exit status; locate the line using the watchdog_pid variable and the kill "${watchdog_pid}" 2> /dev/null invocation and change it so failures don't propagate (for example by appending a no-op OR to swallow non-zero exit codes like "|| true" or using ":"), ensuring the script won't abort under set -e when the PID is already gone.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@extensions/netboot/netboot-deploy.sh`:
- Around line 435-438: The remote command passed to run_host_command_logged_raw
can exit early under set -e and leave the large q_remote_archive in /tmp if tar
fails; change the remote shell sequence invoked over ssh (the string currently
building with mkdir -p ${q_nfs_path}; ${sudo_prefix}tar -xp ... -f
${q_remote_archive} -C ${q_nfs_path}; rm -f ${q_remote_archive}) so that the
mkdir→tar step short-circuits on error (use && between mkdir and tar) but the rm
-f ${q_remote_archive} is executed unconditionally and the original tar exit
status is preserved and re-exited (capture the tar/mkdir exit code into a temp
var and then run rm -f ${q_remote_archive}; exit ${ret}) to ensure cleanup
always runs while still propagating failures back to
run_host_command_logged_raw.
- Line 437: The tar invocation that uses --selinux, --acls, and --xattrs (the
line that runs "${sudo_prefix}tar -xp --numeric-owner --xattrs
--xattrs-include='*' --acls --selinux -f ${q_remote_archive} -C ${q_nfs_path}")
assumes GNU tar and will fail on BusyBox; modify the deployment script to probe
the remote tar capabilities (e.g. run "${sudo_prefix}tar --version" or check for
"GNU" in output) and conditionally set an extended-attribute flags variable
(like EXT_TAR_FLAGS="--numeric-owner --xattrs --xattrs-include='*' --acls
--selinux" for GNU tar, fallback to "-x --numeric-owner" or "-xp" for non-GNU),
then use "${sudo_prefix}tar ${EXT_TAR_FLAGS} -f ${q_remote_archive} -C
${q_nfs_path}" in place of the hardcoded flags; alternatively, if you prefer
docs-only, add a README note stating GNU tar is required on the NFS server.
---
Duplicate comments:
In
`@extensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancel`:
- Line 17: In zz-netboot-watchdog-cancel make the watchdog PID kill tolerant to
stale/exited PIDs by masking kill's exit status; locate the line using the
watchdog_pid variable and the kill "${watchdog_pid}" 2> /dev/null invocation and
change it so failures don't propagate (for example by appending a no-op OR to
swallow non-zero exit codes like "|| true" or using ":"), ensuring the script
won't abort under set -e when the PID is already gone.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 0a996b13-5b68-49c0-80c0-39489b849af8
📒 Files selected for processing (15)
config/templates/nfs-boot.cmd.templateextensions/netboot/README.mdextensions/netboot/files/dhcpcd-hooks/71-netboot-rootpathextensions/netboot/files/initramfs-hooks/netboot-rootpathextensions/netboot/files/initramfs-scripts/init-premount/zz-netboot-watchdogextensions/netboot/files/initramfs-scripts/nfs-bottom/zz-netboot-watchdog-cancelextensions/netboot/netboot-deploy.shextensions/netboot/netboot.shlib/functions/artifacts/artifacts-obtain.shlib/functions/configuration/main-config.shlib/functions/host/host-utils.shlib/functions/image/partitioning.shlib/functions/image/rootfs-to-image.shlib/functions/rootfs/create-cache.shlib/functions/rootfs/rootfs-create.sh
🚧 Files skipped from review as they are similar to previous changes (5)
- lib/functions/rootfs/create-cache.sh
- lib/functions/configuration/main-config.sh
- extensions/netboot/files/initramfs-hooks/netboot-rootpath
- lib/functions/image/rootfs-to-image.sh
- config/templates/nfs-boot.cmd.template
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@extensions/netboot/README.md`:
- Line 95: The README uses two spellings ("Normalize" and "normalises") for the
same concept; pick one dialect and make it consistent across the file by
updating all occurrences (e.g., the NETBOOT_CLIENT_MAC description and earlier
uses) to the chosen spelling; search for instances of "normalize", "normalise",
"normalizes", "normalises" and update them to one variant so the README is
consistent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f83b57d6-01c8-4e1a-95e5-eb619ce2d934
📒 Files selected for processing (2)
extensions/netboot/README.mdextensions/netboot/netboot-deploy.sh
🚧 Files skipped from review as they are similar to previous changes (1)
- extensions/netboot/netboot-deploy.sh
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Make the network-boot u-boot template work for both arm64 (Image/booti) and armv7 (zImage/bootz). Load kernel/initrd/dtb from the local boot partition; mount root over NFS. Take console settings from DTB `/chosen/stdout-path` instead of hardcoded baud — boards like helios64 (1500000) and others (115200) work without per-board overrides. Assisted-by: Claude:claude-opus-4-7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Allow the rootfs stage to produce a compressed archive, an exported directory tree, or both. Compression is configurable. When `ROOTFS_COMPRESSION=none` is set without `ROOTFS_EXPORT_DIR`, fail fast — there would be no rootfs artifact otherwise. Assisted-by: Claude:claude-opus-4-7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Add opt-in netboot extension for diskless U-Boot PXE/NFS boot. Generates a TFTP tree (kernel + DTB + uInitrd + per-board pxelinux.cfg with extlinux APPEND for NFS root) alongside or instead of a flashable image. Supports per-host MAC-tagged configs, builder-as-NFS-server via ROOTFS_EXPORT_DIR, ROOTSERVER discovery from DHCP siaddr in initramfs, and a `netboot_artifacts_ready` post-hook for deploy automation. Assisted-by: Claude:claude-opus-4-7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
New rootfs type for full network boot: the only thing on the device's local storage is U-Boot itself. Kernel, DTB, optional uInitrd and PXE config come from TFTP; rootfs is mounted over NFS. A new case branch in do_main_configuration auto-enables the netboot extension, symmetric with existing fs-f2fs-support / fs-btrfs wiring. The legacy ROOTFS_TYPE=nfs (hybrid: kernel on local storage, only / over NFS) is untouched — both paths coexist. - nfs-root case branch in ROOTFS_TYPE dispatch calls enable_extension "netboot" - prepare_partitions skips root partition creation and SD-size sanity check - check_filesystem_compatibility_on_host skipped for nfs-root - create_image_from_sdcard_rootfs early-returns for nfs-root after the pre_umount hook has grabbed TFTP artifacts from /boot: SDCARD.raw is dropped, the .img pipeline (mv to DESTIMG, write-to-SD, fingerprint, compress) is skipped. For nfs-root the only deliverables are the rootfs archive / ROOTFS_EXPORT_DIR tree and the TFTP staging dir — producing a boot-partition .img would be misleading (nothing on the device reads it). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Documents the netboot extension: artifact server setup (tftpd-hpa + nfs-kernel-server), TFTP tree layout, DHCP options 66/67 on the network DHCP server, userpatches.conf knobs, the netboot_artifacts_ready hook, a full end-to-end helios64 walkthrough, and a troubleshooting section. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
In the rootfs cache and image pipelines, switch tar/rsync calls to:
rsync -aHWh -XAXS --numeric-ids ...
tar cp --xattrs --xattrs-include='security.*' --acls --selinux --sparse ...
Without this, xattrs (notably `security.capability` for setcap'd binaries
like /usr/bin/ping) and POSIX ACLs were stripped during the rootfs →
tarball → image (or → NFS export) round-trip.
The tar xattr include pattern defaults to `security.*` (file capabilities
and SELinux contexts) — broader patterns also pick up source-fs internals
(`bcachefs_*`, `btrfs.*`, `zfs.*` from the build host) that have no
meaning on the target and produce extract-time errors. Tunable via:
- `ROOTFS_TAR_XATTR_INCLUDE` (env, replaces default include pattern)
- `ROOTFS_TAR_EXTRA_FLAGS` (bash array, appended to tar args)
- `ROOTFS_RSYNC_XATTR_FLAGS` (env, replaces rsync xattr/ACL flags)
- `pre_create_rootfs_archive` extension hook (set the above lazily,
e.g. depending on ARCH/RELEASE)
Drive-by: scope the `post_create_rootfs_archive` hook dispatch to
`ROOTFS_TYPE=nfs|nfs-root` (the only types that produce an archive)
and add `zst` to the `expected:` list in the unknown-compression
error message.
Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Reference implementation of the `netboot_artifacts_ready` post-hook:
rsyncs the TFTP tree and unpacks the rootfs archive into an NFS export
on a remote server over SSH.
- Setting `NETBOOT_DEPLOY_SSH=user@host` implies `ROOTFS_TYPE=nfs-root`
so the operator does not have to repeat it on the command line.
- An early probe hook (`extension_prepare_config__060_…`) tries
`touch && rm` on the target TFTP root before the long build, so a
misconfigured SSH key / sudo / known_hosts fails fast with a clear
diagnostic instead of after `./compile.sh` has run for 40 minutes.
- Host identity is explicit: `known_hosts` file by default
(`NETBOOT_DEPLOY_SSH_KNOWN_HOSTS`), optional TOFU
(`NETBOOT_DEPLOY_SSH_TOFU=yes`) for first-time deployments.
- SSH key passed via `NETBOOT_DEPLOY_SSH_KEY`; `sudo` on the
target is opt-in via `NETBOOT_DEPLOY_SUDO=yes`.
Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
Add troubleshooting entries for the most common netboot failure modes: 'NFS over TCP not available from <gateway>' (DHCP boot-server / siaddr unset or wrong) and the corresponding dnsmasq/OpenWRT 'dhcp-boot' fix. Show how to verify with /proc/net/pnp on a booted client. Assisted-by: Claude:claude-opus-4-7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
… watchdog
Replace the `nfsroot=auto` (DHCP option 17) discovery path with
`nfsroot=<path>,tcp,v3` baked into the extlinux APPEND, and let the
kernel resolve the NFS server from DHCP siaddr at boot. Per-host rootfs
paths live in per-board pxelinux.cfg files; the server is a single
network-wide value. DHCP option 17 is no longer consulted in this mode
— it doesn't scale to multi-board setups (one path for all clients).
Add a 10-minute mount-stall safety net via two initramfs hooks:
- `init-premount/zz-netboot-watchdog` forks a background shell that
sleeps 600 s and then triggers an immediate reboot via
`echo b > /proc/sysrq-trigger` if the NFS root mount has not
completed by then.
- `nfs-bottom/zz-netboot-watchdog-cancel` kills that background
shell after a successful mount.
Active only for `ROOTFS_TYPE=nfs-root`. Without the watchdog, a
misconfigured server or transient network failure would hang the target
in initramfs forever; with it, the board self-recovers and tries again.
Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
…uid_owner netboot extension exports an unpacked rootfs tree under output/netboot-export/<suffix>/ and reset_uid_owner runs over it. Debian/Ubuntu rootfs trees routinely contain dangling symlinks (e.g. /etc/systemd/system/multi-user.target.wants/ entries referring to services from packages that aren't installed). GNU chown without -h follows the symlink and fails on a missing target with 'cannot dereference', so post-docker cleanup returns exit 2 even though the build itself succeeded. chown -h sets the owner of the symlink inode itself rather than its target; it is a no-op for regular files and directories. This is the semantically correct choice when walking a filesystem tree, regardless of the netboot use case. Surfaced by armbian#9656 (netboot extension); applies to any extension that performs reset_uid_owner over a real rootfs tree on host. Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
The default NETBOOT_TFTP_PREFIX and (shared-mode) NETBOOT_NFS_PATH now
include a build-flavor suffix so CLI vs minimal vs desktop builds for
the same board/branch/release coexist side by side without colliding
on the staging tree, the deployed TFTP layout, or the NFS root.
• CLI: armbian/<family>/<board>/<branch>-<release>
• min: armbian/<family>/<board>/<branch>-<release>-min
• desktop: armbian/<family>/<board>/<branch>-<release>-desktop
Flavor is computed once in extension_prepare_config and stored as the
global ${_NETBOOT_FLAVOR}, so the post-build hook that composes pxe_tag
picks it up too — pxelinux.cfg/<board>-<branch>-<release><flavor>.example
becomes a unique tagged file per flavor, and the deploy/symlink workflow
keeps working without changes.
Per-host NFS path (NETBOOT_HOSTNAME set) is left untouched — host names
are already disambiguating.
User-supplied NETBOOT_TFTP_PREFIX / NETBOOT_NFS_PATH are honored verbatim,
flavor is only added to the defaults.
README updated to document the new <flavor> segment in both default
patterns.
Assisted-by: Claude:claude-opus-4.7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
NFS-side writes (rootfs archive untar with --numeric-owner/xattrs and /lib/modules/<ver>/ rsync) preserve ownership only when the remote shell runs as uid 0. With NETBOOT_DEPLOY_SUDO=no and a non-root SSH login the write succeeds but the export gets rewritten under the login uid; the next netboot then panics on broken permissions in /etc, /usr, modules. Add _netboot_deploy_require_remote_root helper that probes 'id -u' over the same SSH path the deploy will use and aborts with a precise error when uid != 0 and SUDO=no. NETBOOT_DEPLOY_SUDO=yes (sudo -n) is the documented elevation escape hatch and skips the probe. Call it before: - rootfs archive untar in netboot_artifacts_ready (full-image deploy) - /lib/modules/<ver>/ rsync in artifact_ready__netboot_kernel_deploy Doc on NETBOOT_DEPLOY_SUDO updated to spell out the constraint. Reported-by: coderabbitai (review on PR armbian#9656) Assisted-by: Claude:claude-opus-4.7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
The kernel-only deploy hook (artifact_ready__netboot_kernel_deploy) was copying new DTBs but never removing ones that disappeared from the linux-image package. A board pointing at a renamed or removed BOOT_FDT_FILE would keep loading the old DTB against the fresh kernel — exactly the kernel/DTB coherence gap this hook is meant to close. Mirror the full-image deploy by adding --delete to the dtb/ rsync. Safe scope: dtb/ lives entirely under the board+branch+release-scoped NETBOOT_TFTP_PREFIX, so the prune only touches DTBs from this kernel's package and never neighbours from other deployments under the shared TFTP root. Reported-by: coderabbitai (review on PR armbian#9656) Assisted-by: Claude:claude-opus-4.7 Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
The earlier 'preserve xattrs/ACLs/sparse' commit added --sparse to tar
creation in rootfs-create.sh but missed the symmetric flag on the tar
extraction in create-cache.sh. Without --sparse on extract, sparse-extent
information stored in the tarball is silently discarded — files restore
as fully-allocated, negating the storage optimization the creation flag
was meant to enable.
Add --sparse to the 'tar xp' invocation that restores the rootfs cache
into ${SDCARD}.
Reported-by: coderabbitai (review on PR armbian#9656)
Assisted-by: Claude:claude-opus-4.7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
…amfs is build-side only
Initramfs cannot be regenerated correctly outside a full image build:
its content depends on the configured rootfs (customize_image hooks,
/etc/initramfs-tools tweaks, board-specific extensions, userpatches
overlay), and that context survives only during the build itself.
After deploy the configured rootfs lives only on the NFS server, which
may be OpenWRT/embedded/etc. and cannot run chroot+update-initramfs;
regenerating from the generic post-debootstrap rootfs cache would
produce a *different* initramfs than the one the full build would have
made — fake, not just incomplete.
Therefore artifact_ready__netboot_kernel_deploy now:
- drops any pre-existing uInitrd from TFTP after the kernel rsync,
so U-Boot does not pair the new kernel with a stale initramfs whose
modules have a wrong vermagic
- replaces the previous 'run update-initramfs on the server' guidance
(which was wrong — server-side regen is impossible on most servers
and produces a wrong initramfs even where it is) with a clear
contract: 'for a fresh initramfs do a full image rebuild'
- documents the boot-time consequence in the function header: boards
with built-in boot networking (mvneta, etc.) come up cleanly
without initramfs; modular-NIC boards fail fast at networking and
the operator knows to do a full rebuild
README 'Kernel-only deploy' section reframed as a narrow optimization
for built-in-NIC boards rather than a general kernel refresh path,
with explicit guidance on when to use it vs the full image rebuild.
Closes the long-standing P2 (NETBOOT_DEPLOY_REGENERATE_INITRD) by
contract clarification, not deferred TODO: standalone initramfs
regeneration is an architecturally wrong frame, removed from scope.
Assisted-by: Claude:claude-opus-4.7
Signed-off-by: Igor Velkov <325961+iav@users.noreply.github.com>
… failure The remote shell ran with `set -e`, so a tar failure (disk full on the NFS export, archive corruption, etc.) exited the shell before the `rm -f` and left a 200-800 MB rootfs archive in /tmp. Repeated failed deploys accumulate. Restructure to: mkdir && tar; capture rc; rm -f unconditionally; exit with the captured rc so Armbian's set -e still aborts on the real failure. Reported by coderabbitai (armbian#9656 review, line 438). Assisted-by: Claude:claude-opus-4.7
…target The deploy hook untars the rootfs archive with --xattrs/--acls/--selinux, which are GNU-tar extensions. Busybox tar (Alpine, OpenWRT) silently drops xattrs on extract — file capabilities like security.capability on ping/mtr are lost and they fail at runtime, regardless of the host filesystem's xattr support. Capability-probe with fallback was considered and rejected: there is no Busybox-tar code path that preserves xattrs, so the only honest fallback would be silently broken caps. Document the requirement instead. Reported by coderabbitai (armbian#9656 review, line 437). Assisted-by: Claude:claude-opus-4.7
…ernel build
A full image build (`compile.sh build ...`) obtains a kernel artifact
internally and triggers `artifact_ready` with WHAT=kernel. The kernel-
only deploy handler treated that as a standalone kernel deploy and
rsynced `/lib/modules/<ver>/` into the NFS export. The subsequent full-
image rootfs archive deploy then fails on tar extract:
tar: ./lib: Cannot create symlink to 'usr/lib': File exists
— the rsync materialized `lib/` as a directory, but the rootfs tarball
contains `./lib -> usr/lib` (Ubuntu/Debian usrmerge), and tar refuses
to overwrite a directory with a symlink.
Add a `${ARMBIAN_COMMAND}` gate so the kernel-only path only fires for
standalone `compile.sh kernel ...` runs. Full image builds keep using
the full rootfs archive deploy in
`netboot_artifacts_ready__deploy_to_remote_server`.
Reproducer: clean NFS export at `${NETBOOT_NFS_PATH}`, then run
`compile.sh build BOARD=helios4 BRANCH=edge BUILD_MINIMAL=yes
RELEASE=resolute ROOTFS_TYPE=nfs-root ENABLE_EXTENSIONS=netboot,netboot-deploy
NETBOOT_DEPLOY_SSH=root@${nfs_server} NETBOOT_NFS_PATH=...`. Without
this fix the deploy hook fails on the lib-symlink collision; with it,
the rootfs archive lands cleanly.
Assisted-by: Claude:claude-opus-4.7
Line 77 uses British 'normalises'; line 95 used American 'Normalize'. Match the British form already established earlier in the file. Reported by coderabbitai (armbian#9656 review, README.md:95). Assisted-by: Claude:claude-opus-4.7
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an opt-in
netbootextension that produces a full network-boot payload — kernel, DTB, optionaluInitrd,pxelinux.cfgand an NFS-exportable rootfs — from a regular Armbian build. For netboot the only thing that has to live on the device's local storage is U-Boot itself: the kernel and DTB come from TFTP,/is mounted over NFS, nothing else on mmc/eMMC/USB is touched during early boot.Today
ROOTFS_TYPE=nfsalone only gives a hybrid image (kernel+DTB still on SD/eMMC, only/over NFS). This PR keeps that path working and layers a real netboot flow on top via a newROOTFS_TYPE=nfs-root.What changes
lib/functions/configuration/main-config.sh— newROOTFS_TYPE=nfs-rootcase branch, symmetric with the existingfs-f2fs-support/fs-btrfswiring: the branch auto-enables thenetbootextension soROOTFS_TYPE=nfs-rootis the single switch that selects the full netboot flow.check_filesystem_compatibility_on_hostis skipped for bothnfsandnfs-root— the host-side check is a sanity net for block-device targets and falsely rejects valid NFS configurations.extensions/netboot/netboot.sh— new, directory-based extension. Directory layout (rather than a singleextensions/netboot.shfile) exists so the long-form usage guide can live next to the code asREADME.md; inlining documentation of that size into the script body would be unwieldy. Hooks:extension_prepare_config— validate variables (NETBOOT_CLIENT_MACMAC normalization to the01-<mac>PXELINUX form,ROOTFS_COMPRESSION/ROOTFS_EXPORT_DIRrejection of bad combinations before debootstrap), set the build-flavor_NETBOOT_FLAVORsuffix (-min/-desktop/ empty) for default paths._netboot_compute_runtime_defaults— lazy helper that materializesNETBOOT_TFTP_PREFIX/NETBOOT_NFS_PATHdefaults (armbian/${LINUXFAMILY}/${BOARD}/${BRANCH}-${RELEASE}${_NETBOOT_FLAVOR}shared, or/srv/netboot/rootfs/hosts/<hostname>per-host) at hook time, when${LINUXFAMILY}is guaranteed populated. Computing inextension_prepare_configwould capture an empty${LINUXFAMILY}on flows where family-config sourcing happens later (e.g. kernel-onlycompile.sh kernel ...). Called from each consuming hook (pre_umount_final_image,post_create_rootfs_archive,artifact_readyinnetboot-deploy.sh).custom_kernel_config— enableROOT_NFS,NFS_FS,NFS_V3,IP_PNP,IP_PNP_DHCPsoroot=/dev/nfs ip=dhcpworks without an initrd.post_customize_image— droparmbian-resize-filesystem.service(meaningless on NFS root) and/root/.not_logged_in_yet(thearmbian-firstlogininteractive wizard blocks bring-up when there is no interactive console).armbian-firstrun.servicestays — it only regenerates SSH host keys.host_pre_docker_launch— bind-mountROOTFS_EXPORT_DIRinto the build container when it lives outside${SRC}, so the single-step builder-as-NFS-server workflow works the same inside and outside Docker.pre_umount_final_image— assemble the TFTP tree (Image/zImage,dtb/,uInitrd), writepxelinux.cfg/{default.example | 01-<mac>}with the rightFDT/FDTDIRline and an explicitINITRDdirective whenuInitrdis present (U-Boot's PXE parser only loads an initramfs when the stanza names it), expose anetboot_artifacts_readyhook for userpatches that deploy to a real server.lib/functions/artifacts/artifacts-obtain.sh— new genericartifact_readyextension hook, fired at the end ofobtain_complete_artifactafterartifact_reversion_for_deployment(on the local-build path; skipped whendeploy_to_remote=yessince that path tears downartifact_base_dirwithout leaving usable.debfiles on disk). Extension-side handlers see reversioned.debfilenames inartifact_map_debs_reversioned_*under${DEB_STORAGE}and the standardWHAT/artifact_name/artifact_version/artifact_final_filecontext. Generic — netboot-deploy below is the first consumer; any extension can use it for deploy / notification / cache-warming actions.lib/functions/image/rootfs-to-image.sh— two new controls for NFS-rootfs builds (bothROOTFS_TYPE=nfsandnfs-root):ROOTFS_COMPRESSION=zstd|gzip|none(defaultzstd).zstd→.tar.zst,gzip→.tar.gz,none→ no archive at all. Rejected early ifnoneis set withoutROOTFS_EXPORT_DIR. Thetar | pv | compressorpipeline now runs in aset -o pipefailsubshell so a broken archive step actually fails the build instead of producing a silently truncated file.ROOTFS_EXPORT_DIR=/abs/path— also (or only) rsync the rootfs tree into this directory. Can point anywhere on the build host's filesystem — inside or outside the Armbian tree (the extension bind-mounts external paths into the Docker container automatically). If the path is an NFS mount or any other network filesystem, the build writes directly to the remote server with no intermediate archive. The rsync uses--deleteso a re-used export dir stays in sync with the new build instead of accumulating stale files from previous runs. Combined withROOTFS_COMPRESSION=nonethis turns deploy-to-NFS-server into a single build step.ROOTFS_ARCHIVE_PATHis exported so downstream hooks (the newnetboot_artifacts_ready) can reference the produced archive.lib/functions/image/partitioning.sh—prepare_partitionsskips the root partition entry fornfs-rootthe same way it does fornfs, and the SD-size sanity check no longer applies to either (there is no image file to size).config/templates/nfs-boot.cmd.template— previously sunxi/arm32-only (zImage+bootz). Made arch-agnostic so the hybridROOTFS_TYPE=nfspath builds for arm64 boards too.extensions/netboot/netboot-deploy.sh— reference deploy hook with two trigger points:netboot_artifacts_ready__deploy_to_remote_server— full-image flow (existing). Rsyncs the staged TFTP tree and uploads + untars the rootfs archive via SSH.artifact_ready__netboot_kernel_deploy— new kernel-only flow. Triggered bycompile.sh kernel BOARD=... ENABLE_EXTENSIONS=netboot,netboot-deploy NETBOOT_DEPLOY_SSH=.... Unpacks the reversionedlinux-image-${BRANCH}-${LINUXFAMILY}_*_${ARCH}*.debinto${SRC}/.tmp/; rsyncsvmlinuz-${kver}→${TFTP_PREFIX}/Image|zImage|vmlinuz-${kver}(renamed by${ARCH}, mirrors whatpre_umount_final_image__900_collect_netboot_artifactsproduces in a full image build),usr/lib/linux-image-${kver}/→${TFTP_PREFIX}/dtb/, andlib/modules/${kver}/→${NFS_PATH}/lib/modules/${kver}/with--deletescoped to that single kernel version. Closes a coherence gap: a kernel-only refresh (changed driver, recompiled with a config tweak) used to leave the on-NFS.koset out-of-sync with the freshly-deployed vmlinuz, producingBPF: Invalid name_offset:Nandfailed to validate module BTF: -22spam at boot. Initramfs is intentionally skipped — regenerating it requires a chroot into the NFS rootfs (cross-arch needsqemu-user-static+binfmt_miscregistered on the server, not the build host); operator runs it manually or rebuilds the full image when ABI moves.extensions/netboot/README.md— long-form guide: variable reference, server setup (tftpd-hpa+nfs-kernel-server), DHCP 66/67 config (OpenWRT + others), per-host / per-MAC deployments, firstrun vs firstlogin, end-to-end helios64 example, troubleshooting. Includes a "Kernel-only deploy" subsection covering theartifact_readyhandler workflow with theupdate-initramfsfollow-up step.Variables (quick reference)
All optional.
ROOTFS_TYPE=nfs-rootalone gives you a shared-rootfs build with apxelinux.cfg/default.examplefile.NETBOOT_SERVERnfsroot=keeps${serverip}literal for U-Boot to fill from DHCP siaddr.NETBOOT_TFTP_PREFIXarmbian/${LINUXFAMILY}/${BOARD}/${BRANCH}-${RELEASE}NETBOOT_NFS_PATH/srv/netboot/rootfs/shared/...or/srv/netboot/rootfs/hosts/<hostname>nfsroot=.NETBOOT_HOSTNAMEhosts/<hostname>/— each machine owns its own writable copy.NETBOOT_CLIENT_MAC01-<mac>(per-MAC PXELINUX override). Accepts:or-, normalized to lowercase.ROOTFS_COMPRESSIONzstdzstd/gzip/none.ROOTFS_EXPORT_DIRTest plan
Validated end-to-end on helios64 (
rockchip64,edge/resolute,ttyS2 @ 1500000), Armbian 26.05:ROOTFS_TYPE=nfs-root NETBOOT_SERVER=192.168.1.125, shared NFS path, FDTDIR fallback for boards withoutBOOT_FDT_FILE, no hardcodedconsole=). 6:57 min, all artifacts correct.NETBOOT_HOSTNAME=helios64-a NETBOOT_CLIENT_MAC=aa:bb:cc:dd:ee:ff).pxelinux.cfg/01-aa-bb-cc-dd-ee-ffcontainsnfsroot=.../hosts/helios64-a. 7:44 min.ROOTFS_COMPRESSION=gzip— produces.tar.gz(defaultzstd→.tar.zst). On the helios64 rootfs: 503 MB gzip vs 460 MB zstd.ROOTFS_COMPRESSION=none ROOTFS_EXPORT_DIR=...— single-step tree workflow, 1.5 GB tree in export dir, no archive produced. 5:17 min.ROOTFS_COMPRESSION=nonewithoutROOTFS_EXPORT_DIR— fails fast inextension_prepare_configbefore debootstrap, not hours later.tftpd-hpa+ NFS rootfs via rsync tonfs-kernel-server. DHCP options 66/67 on OpenWRT. Helios64 cold boot → U-Bootbootflow scan -lb→ TFTP →booti→ kernel →ip_auto_config→ NFS mount → systemdgraphical.target→ login prompt onttyS2@1500000. Noarmbian-firstloginwizard, noresize2fserrors,armbian-firstrun.serviceregenerates SSH host keys normally. Verified twice: once with archive workflow + manual unpack, once with tree workflow + rsync deploy.mvebu,armhf, U-Boot v2025.10) — second SoC family. PXE netboot: DHCP → TFTP (zImage + DTB) →bootz→ kernel → NFS root → systemd → login prompt. No initrd needed (see notes below).compile.sh iav kernel BOARD=helios64 BRANCH=edge BUILD_MINIMAL=yes RELEASE=trixie ENABLE_EXTENSIONS=netboot,netboot-deploy NETBOOT_DEPLOY_SSH=root@m1). On a cache-hit kernel artifact the newartifact_ready__netboot_kernel_deployhandler fired, unpacked the reversionedlinux-image-*.debunder${SRC}/.tmp/, rsynced vmlinuz →${TFTP_PREFIX}/Image, dtbs →${TFTP_PREFIX}/dtb/, modules →${NFS_PATH}/lib/modules/${kver}/with--delete. Runtime 17 sec.compile.sh iav build BOARD=helios64 BRANCH=edge BUILD_MINIMAL=no RELEASE=bookworm ROOTFS_TYPE=nfs-root ENABLE_EXTENSIONS=netboot,netboot-deploy. 16:15 min. Cold boot helios64 → U-Boot SPL/BL31/proper → DHCP from m1 → TFTP fetch (Image45.8 MB,uInitrd26.4 MB,dtb/rockchip/rk3399-kobol-helios64.dtb) → kernel boot → NFS rootfs mount → systemd PID1 →Welcome to Armbian-unofficial 26.05.0-trunk bookworm→helios64 login: root.dmesg | grep -c BPF= 1 line (only-BPF_FRAMEWORKin systemd's version banner; noInvalid name_offset/failed to validate module BTF— empirical confirmation that vmlinuz and/lib/modules/${kver}/are coherent under the lazy default expansion).BOOT_FDT_FILEset (the FDTDIR vs FDT code path is exercised by helios64's missingBOOT_FDT_FILE, but a board with it set should also work).Known issues found during helios4 testing (not blockers for this PR):
ramdisk_addr_r(0x2880000) is only 8 MB abovekernel_addr_r(0x2080000), but zImage 6.12 is 8.1 MB → U-Boot refuses to boot with initrd. Workaround: omitINITRDfrom PXE config — kernel withCONFIG_ROOT_NFS=ymounts NFS root directly without initrd.ip=dhcpwrites DNS to/proc/net/pnpbutsystemd-resolveddoesn't read it → "No DNS servers known". Workaround:resolvectl dns <iface> <gateway>. Needs a networkd.networkfile or oneshot service inpost_customize_image(future improvement).Post-review update: architecture reworked after CodeRabbit #1 — the extension no longer forces
ROOTFS_TYPEfrom insideextension_prepare_config(too late in the config lifecycle); instead a newROOTFS_TYPE=nfs-rootcase branch inmain-config.shenables the extension, symmetric with existing filesystem-support extensions.pipefailon the archive pipeline (#4),rsync --deleteon the export dir (#5), and an explicitINITRDdirective whenuInitrdis present (#2) are all in.Post-review update (round 3): archive creation moved from the early
if/elseblock to afterpre_umount_final_imagehooks so the tarball/export tree captures the fully finalized rootfs (includesupdate_initramfsoutput and all hook edits). Split out as a separate pre-feature commit — also fixes the same bug in the originalROOTFS_TYPE=nfshybrid flow. Additionally: the netboot extension now setsBOOTSIZE=0fornfs-root, preventing the phantom/bootfstab entry at its source; the compensatingpre_umount_final_image__100_netboot_clean_fstabhook is gone.Post-review update (round 4):
config/templates/nfs-boot.cmd.templatenow wraps the DTB load in anif load ... ; then true; else echo FATAL; reset; fiblock so a missing/wrongdtb/${fdtfile}aborts the boot with a clear message instead of continuing with an invalid${fdt_addr_r}— consistent with the ramdisk and kernel handling on the following lines.Post-review update (round 5): also includes a small core-fix in
lib/functions/host/host-utils.sh—reset_uid_ownernow useschown -hto tolerate dangling symlinks in the unpacked rootfs tree this extension exports (see the commit for the full rationale).Post-review update (round 6): adds a generic
artifact_readyextension hook tolib/functions/artifacts/artifacts-obtain.shand a kernel-only deploy handler innetboot-deploy.sh(artifact_ready__netboot_kernel_deploy). Closes the kernel-only coherence gap —compile.sh kernel ... ENABLE_EXTENSIONS=netboot,netboot-deploynow refreshes vmlinuz + dtbs +/lib/modules/${kver}/in one shot instead of needing a full image rebuild. Default-path computation innetboot.shmoved fromextension_prepare_configinto a lazy_netboot_compute_runtime_defaultshelper called at hook time — fixes a latent bug where${LINUXFAMILY}could be empty when the default was first materialized on flows that source the family config later in the dispatch.Related work
A companion PR to armbian/documentation will add
Developer-Guide_Netboot.mdwith the short overview + variable reference; this extension'sREADME.mdis the long-form guide and is linked from that page.🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Initramfs
Bug Fixes / Reliability
Behavior