feat(os-update): add generic 'os_update' pre-reboot event for plugins (OS-486)

[elibosley]

Why

When Unraid updates the OS, the new release ships a new kernel but the box keeps running the old one until reboot. Out-of-tree driver plugins (WiFi, GPU, NIC, …) build per-kernel modules, so a reboot can land on a kernel with no matching driver — fatal for, e.g., a headless server whose only link is a USB WiFi adapter.

Today the only mitigation is hardwired in unRAIDServer.plg: it greps for a running inotifywait -q /boot/changes.txt … process and, if found, force-downloads + runs ich777's plugin_update_helper, which carries a hardcoded list of ~22 supported plugins and is not extensible.

What

Add a generic, self-registering os_update event, dispatched through the existing emhttp_event mechanism:

• unRAIDServer.plg fires os_update after the new release files (incl. changes.txt) are on the flash but before the reboot prompt, passing the incoming Unraid version ($2) and kernel release ($3, uname -r form parsed from changes.txt).
• sbin/emhttp_event documents the new event.

Any plugin can then drop an executable at …/event/os_update to stage a kernel-matched build. Hooks run synchronously, so "PLEASE REBOOT" only appears once they finish — no separate "wait for a notification" gate.

Notes

• Additive + backward compatible: the existing ich777 inotifywait detection and messaging are untouched.
• Not auto-update: the event fires only during a user-initiated OS update. The webgui change downloads nothing itself — it runs only already-installed plugin hooks (which already run as root at boot). Strictly more conservative than the current wget … | at now of ich777's helper.
• Reference consumer: the unraid-rtl8821au driver plugin migrates to event/os_update (separate repo).

Test

• xmllint clean on unRAIDServer.plg; bash -n clean on the resolved install block and emhttp_event.
• End-to-end sim: kernel parsed from a realistic changes.txt → emhttp_event os_update → sample event/os_update hook receives (os_update, <version>, 6.19.2-Unraid); plugins without the hook are skipped.

Resolves OS-486.

Summary by CodeRabbit

• New Features

  • OS updates now trigger an additional pre-reboot os_update event so supporting components can prepare before the system restarts.
  • The event includes the detected incoming Linux kernel identifier when available, built into an Unraid-specific version string.

• Bug Fixes

  • Update hooks now safely handle situations where the kernel identifier can’t be determined and won’t run if the event helper isn’t present.
  • The hook runs synchronously but is protected by a timeout to prevent hangs from blocking the update flow.

• Documentation

  • Added clear in-file documentation for the os_update event timing and arguments.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e60037d2-312d-4d9c-ae57-e167f4772ee1

📥 Commits

Reviewing files that changed from the base of the PR and between fb537cb and 41b445b.

📒 Files selected for processing (2)

• emhttp/plugins/unRAIDServer/unRAIDServer.plg
• sbin/emhttp_event

✅ Files skipped from review due to trivial changes (1)

• sbin/emhttp_event

🚧 Files skipped from review as they are similar to previous changes (1)

• emhttp/plugins/unRAIDServer/unRAIDServer.plg

---

Walkthrough

The upgrade script now derives a kernel version from /boot/changes.txt and emits an os_update event before reboot messaging when emhttp_event is available. The event script header also documents the new event’s timing and arguments.

Changes

OS update event emission

Layer / File(s)	Summary
Event emission and contract emhttp/plugins/unRAIDServer/unRAIDServer.plg, sbin/emhttp_event	The plugin now fires emhttp_event os_update with the current unRAID version and derived kernel identifier during OS updates, and the event header documents the new event’s timing, arguments, and synchronous hook behavior.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

A bunny tapped the update trail,
With kernel crumbs tucked in its tail.
“Hop, os_update!” said the moon,
“Then reboot time will come soon.”
🐇✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding a generic pre-reboot os_update event for plugins.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch os-486-os-update-driver-event

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔧 PR Test Plugin Available

A test plugin has been generated for this PR that includes the modified files.

Version: 2026.06.27.1241
Build: View Workflow Run

📥 Installation Instructions:

Install via Unraid Web UI:

1. Go to Plugins → Install Plugin
2. Copy and paste this URL:

https://preview.dl.unraid.net/pr-plugins/pr-2683/webgui-pr-2683.plg

3. Click Install

Alternative: Direct Download

• 📦 Download PLG
• 📦 Download TXZ

⚠️ Important Notes:

• Testing only: This plugin is for testing PR changes
• Backup included: Original files are automatically backed up
• Easy removal: Files are restored when plugin is removed
• Conflicts: Remove this plugin before installing production updates
• Post-merge behavior: This preview stays available after merge until preview storage expires or it is manually cleaned up

📝 Modified Files:

Click to expand file list

emhttp/plugins/unRAIDServer/unRAIDServer.plg
sbin/emhttp_event

🔄 To Remove:

Navigate to Plugins → Installed Plugins and remove webgui-pr-2683, or run:

plugin remove webgui-pr-2683

---

_{🤖 This comment is automatically generated and will be updated with each new push to this PR.}