Kernel Follower
os-kernelfollow · System
Rebuilds an out-of-tree FreeBSD kernel module for the kernel an OPNsense update installs, before the reboot, so a driver from outside OPNsense's own repository is there on the next boot.
In the menu
- With os-xgs-npu installed: XGS: Kernel Follower
- Without os-xgs-npu: System: Kernel Follower
It reads the kernel the next boot will use - a kernel set an update has staged, or /boot/kernel - from the binary, without booting it, and compares it with the stamp beside each module registered with it. A module that does not match is rebuilt for that kernel from its sources: an archive carried on the machine, or github.com/opnsense/src at the commit the kernel names.
It runs from the upgrade hook, from the stop hook of every orderly reboot - which holds the reboot until the build is done, for at most ten minutes - and from cron every five minutes. When a module the network needs cannot be rebuilt, the next boot is sent once to /boot/kernel.old, which the installed module matches; that is cancelled once the module is rebuilt.
A plugin registers its module with one file in /usr/local/etc/kernelfollow.d/. On a Sophos XGS with os-xgs-npu, os-xgs-npu follows its own two modules, octep.ko and npuep.ko, with its own follower: this plugin leaves them to it and only shows them, touches nextboot only to cancel a fall-back it set itself, and leaves the old kernel sources for os-xgs-npu to remove.
Features
-
Next boot's kernel read
From the binary of a staged kernel set or of /boot/kernel, without booting it, and compared with each module's stamp.
-
Clean rebuild
Built from nothing in an emptied directory, checked to have compiled every source with that kernel's machine headers, installed under a temporary name and moved into place; the previous build is kept as .prev with its own stamp.
-
Runs when it matters
The upgrade hook, the stop hook of every orderly reboot (at most ten minutes) and cron every five minutes. With nothing registered, each run is a directory listing.
-
Fall-back for the network
A module marked CRITICAL=yes that cannot be rebuilt sends the next boot, once, to /boot/kernel.old with nextboot -k; the run that rebuilds it cancels this.
-
Old sources removed
The sources of kernels no longer run are removed once the new kernel has run a day (a setting), with every module matching it and attached.
-
Check and Follow now
The page shows the kernel running and the one the next boot takes, each module against it, the sources on disk and the last run; Check says what a run would do, Follow now runs it.
Install and update
From os-xgs-npu's release after 0.1.0-alpha.7.1, XGS: Updates lists it on its Plugins tab - an installed copy is updated there by hand, and a missing one installed there - and the ready-made images built from that release carry it; until then it is installed and updated as below. The plugin's cron entry runs the follower every five minutes, never the update. To install it on an XGS appliance or on any other OPNsense, as root: from a checkout of the repository with sh install/install.sh, which puts the page under XGS with os-xgs-npu and under System without it, and keeps the settings when run again - archives of kernel sources in kernel-sources/ beside the checkout let a machine without internet build; or from the release's package, os-kernelfollow-1.0.0.pkg, checked against SHA256SUMS and added with pkg. A copy installed this way is updated by its own self-update.py. It is not in the OPNsense plugin repository.
Limits, and what is not tested yet
- A real kernel update: a staged kernel set, the fetch of sources over the network, the upgrade and stop hooks.
- nextboot itself, and the removal of old sources.
- The package, built by tools/make-package.sh and added with pkg.
- An install on OPNsense without os-xgs-npu.
- An update through the Plugins tab or self-update.py: 1.0.0 is the first release, so none has been ahead of an installed copy.
Repository
First release: 2026-10-25
The discussion of this page is held in the project's GitHub Discussions. Showing it here loads giscus from giscus.app and GitHub, and writing in it needs a GitHub account - what that means.