SmoothKernel provides the headers and templates that out-of-tree modules use to build against the shared kernel. Module source code lives in consuming repos, not here.
Current or expected consumers:
- OpenZFS through
openzfs-zfs-dkms. - SmoothNAS
smoothfs. - Optional NVIDIA modules from Debian's
nvidia-driver-*packages.
A Smooth* out-of-tree module should package as DKMS unless there is a strong reason to ship a prebuilt module. DKMS keeps the module coupled to the target kernel headers and avoids one binary package per kernel version.
The minimum package contents are:
/usr/src/<module>-<version>/
dkms.conf
Makefile
source files
debian/postinst
debian/prerm
Use the templates in this repository:
- ../templates/dkms.conf.in
- ../templates/debian-postinst.in
- ../templates/debian-prerm.in
- ../templates/compat.h.in
BUILD_EXCLUSIVE_KERNEL is required. It prevents a module from trying to build
against a kernel below its supported API floor.
Example floor for 6.18+:
^(6\.(1[8-9]|[2-9][0-9])|[7-9]\.).*
Keep this regex in lockstep with the module's compat.h floor.
The postinst template:
- Checks that
dkmsexists. - Adds the module/version.
- Builds it.
- Installs it.
- Attempts
modprobeif the module is not already loaded.
The prerm template:
- Refuses to unload a filesystem module while matching mounts are active.
- Attempts module unload for removable modules.
- Removes the DKMS module/version.
Do not hide DKMS build failures in production packages. A module package that installs but cannot build leaves the appliance in a partially functional state.
Every module should centralize kernel API drift in one header derived from ../templates/compat.h.in.
Rules:
- Other
.cfiles should not contain scattered#if LINUX_VERSION_CODEblocks. - Call sites should use unconditional
<prefix>_compat_*()helpers. - Bumping the kernel floor means updating the floor macros, deleting dead
pre-floor branches, and updating
BUILD_EXCLUSIVE_KERNEL.
This keeps kernel bumps reviewable. The maintainer should be able to audit API drift by reading one compatibility header, not searching every source file.
Consumers build against the installed SmoothKernel headers package. With the current localversion convention, the versioned header package has a name like:
linux-headers-<kernel-version>-smoothkernel
Flavor meta packages may expose stable dependencies, but DKMS ultimately uses:
/lib/modules/$(uname -r)/build
apt may configure linux-image-* before linux-headers-*. The image's
postinst runs /etc/kernel/postinst.d/dkms, which skips a kernel whose headers
aren't there yet, so the headers package's postinst reruns
/etc/kernel/header_postinst.d (DKMS's hook) as Debian's headers packages do.
bindeb-pkg ships no headers postinst; recipes/build-kernel.sh adds it, and
make check-headers-dkms-order installs the packages in that order and
requires ZFS to get built.
The headers package also ships prebuilt host tools that every module build
runs: objtool (x86) links libelf and sign-file links libcrypto.
bindeb-pkg declares no Depends for them, so build-kernel.sh adds the
libraries they link, and fails the build if one links a library it has no
package mapping for. The check-headers-dkms-order container is deliberately
minimal, so it fails if the headers package doesn't bring what it needs.
DKMS-built modules are signed on the target machine by the
smooth-secureboot flow described in signing.md.
Package scripts should not generate their own unrelated signing keys. They
should rely on the shared DKMS signing hooks so ZFS, smoothfs, and optional
NVIDIA modules all follow the same trust model.
For every DKMS consumer:
dkms status
modinfo <module>
sudo modprobe <module>
lsmod | grep '^<module>'For filesystem modules, also mount and unmount a real test filesystem. For Secure Boot validation:
modinfo -F signer <module>The signer should be the enrolled host MOK for DKMS-built modules.
When SmoothKernel moves to a new kernel line:
- Build and install the new headers.
- Rebuild every DKMS consumer.
- Update
compat.hfloors only after deciding the old floor is no longer supported. - Delete dead compatibility branches.
- Update
BUILD_EXCLUSIVE_KERNEL. - Run the module's real workload smoke test.
For SmoothNAS, this means ZFS pool import/export and smoothfs mount behavior,
not just a successful compile.