akms − Alpine Kernel Module Support
akms (install | build) [options] <srcdir | all>
akms (uninstall | unbuild) [options] <modname>[/<modver>]
akms status [options] [<modname>[/<modver>]]
akms [−h] [−−help] [−V]
akms(8) (AKMS) is a tool that enables building out−of−tree (external) Linux kernel modules from source for each installed kernel on the user’s system in an automated and organized fashion. The concept is to have kernel modules automatically rebuilt when a new kernel version is installed.
AKMS is principally inspired by DKMS (Dynamic Kernel Module Support) used on many Linux distributions. AKMS has been designed specifically for Alpine Linux and apk(8); implemented with simplicity, reliability, and security in mind.
Builds are always executed under an unprivileged user inside a sandbox (using bwrap(1)) with isolated Mount, IPC, PID, Network, UTS, Cgroup, and User (if possible) namespaces.
The built kernel objects are automatically compressed with the same compression format as other modules installed with the given kernel. The supported formats are: “gz”, “xz” (requires xz tool), and “zst” (requires zstd tool).
Another advantage of AKMS over DKMS is that you don’t need to have all the dependencies for building modules permanently installed on the system. If some dependencies are missing, they are automatically installed in a disposable overlay over your real root filesystem (using OverlayFS and bubblewrap). The original reason for using overlay was to avoid the limitation of the APK triggers — they are executed inside a “transaction” that holds an exclusive repository lock. This means that no packages could be installed if akms(8) was executed by a trigger. Mounting a disposable overlay on top of “/” for building the modules overcomes this limitation and also provides other benefits.
install
Build and install kernel module from the srcdir for the kernel version(s) specified by −−kernel. srcdir can be either the absolute path of the module’s source directory containing an AKMBUILD(5) file or a glob(7) pattern matching one or more module source directories in /usr/src (can be changed by parameter modules_srcdir in akms.conf(5)). A special value “all” can be used to build and install all modules found under /usr/src.
If the given module version is already built for the specified kernel, it will not be rebuilt, unless −−rebuild is used.
If the module is already installed, it will verify that the installed kernel objects in /lib/modules/<kernelver>/kernel/extra/akms/ match the ones stored in the state directory (refer to section FILES for more information).
If another version of the module is installed for the given kernel, it will be automatically uninstalled right before installing the new one.
build
The same as install, but it will only build the module without installing into /lib/modules.
uninstall
Uninstall the specified module(s) from /lib/modules/<kernelver>/kernel/extra/akms/. A special value “all” can be used to uninstall all modules installed for the kernel version(s) specified by −−kernel.
If keep_uninstalled is not enabled in akms.conf(5) or −−no−keep is specified, it will also remove the uninstalled module version from the state directory (refer to section FILES).
unbuild
Remove the specified module version(s) built for the kernel version specified by −−kernel from the state directory (refer to section FILES). A special value “all” can be used to unbuild all modules built for the specified kernel. If modver is not specified, all not installed versions will be removed.
If the specified module version is installed, it will not be removed unless −−force is used.
status
Print state of modules found in the state directory (refer to section MODULE STATE). The list can be filtered by the module name (modname), version (modver), kernel (−−kernel), and status (−−status).
The following options are available for all actions.
−q, −−quiet
Be quiet, print only warn and error messages. This option overrides parameter log_level specified in akms.conf(5).
−v, −−verbose
Be verbose, print even debug messages. This option overrides parameter log_level specified in akms.conf(5).
−V, −−version
Print the program version and exit.
−h, −−help
Print the help message and exit.
The following options are available for the install and build actions.
−K, −−keep
Keep uninstalled modules in the state directory (/var/lib/akms). This option overrides parameter keep_uninstalled specified in akms.conf(5). See akms.conf(5) for more information.
−−no−keep
The opposite of −−keep.
−k <kernelver>, −−kernel <kernelver>
Specify for which kernelver to build and install the module (e.g. 5.10.53−0−lts). A special value “all” can be used to build and install the module for all the installed kernels (based on /usr/share/kernel/*/kernel.release).
If not specified, the module will be built and installed for the installed kernel that has the same flavour as the currently running kernel.
−r, −−rebuild
Rebuild (and install) the module even if it has been already built.
−−[no−]overlay
Whether to install the build dependencies into the root overlay created on top of /, or on the host system. This option overrides parameter use_overlayfs specified in akms.conf(5) (enabled by default).
−−skip−cleanup
Do not unmount and delete the root overlay used for building and do not uninstall the build dependencies.
The following options are available for the uninstall action.
−K, −−keep
Keep uninstalled modules in the state directory (/var/lib/akms). This option overrides parameter keep_uninstalled specified in akms.conf(5). See akms.conf(5) for more information.
−−no−keep
The opposite of −−keep.
−f, −−force
Uninstall the module’s kernel objects from /lib/modules/<kernelver>/kernel/extra/akms/ even if they are different from the ones stored in the state directory (/var/lib/akms).
−k <kernelver>, −−kernel <kernelver>
Specify from which kernel version to uninstall the module (e.g. 5.10.53−0−lts). A special value “all” can be used to uninstall the module from all kernels where the module is installed.
If not specified, the module will be uninstalled from the installed kernel with the same flavour as the currently running kernel.
The following options are available for the unbuild action.
−f, −−force
Unbuild the module (remove from the state directory) even if it’s installed (without uninstalling).
−k <kernelver>, −−kernel <kernelver>
Specify for which kernel version to unbuild the module (e.g. 5.10.53−0−lts). A special value “all” can be used to unbuild the module for all kernels.
If not specified, module built for the installed kernel with the same flavour as the currently running kernel will be unbuilt.
The following options are available for the status action.
−k <kernelver>, −−kernel <kernelver>
Filter modules by the specified kernel version (e.g. 5.10.53−0−lts).
−s <state>, −−state <state>
Filter modules by their state. Refer to section MODULE STATE for more information.
A specific module version for a specific kernel can be in one of the following states:
1. (no state) — The given module version for the given kernel has not been built yet, there is no entry in the state directory.
2. building — The module is currently being built.
3. built — The module has been successfully built, but it is not installed in /lib/modules.
4. installed — The module is built and installed in /lib/modules.
5. failed — The module failed to be built.
6. corrupted — The module has been installed into /lib/modules, but the kernel objects found in /lib/modules differ from the built objects or some are missing.
.
The following diagram illustrates all possible transitions between the states supported by akms(8).
build (OK)
install
(no state)
−−−−−−−−−>
[building] −−−−−−>
[built]
−−−−−−−−−>
[installed]
−−−−−−−−+
ˆ ˆ \ | ˆ : ˆ |
| | | | | : | |
| build | | (NOK) | | : | install |
| | v | | v | |
| ‘−−− [failed] | | [corrupted] |
| | | | | |
| | | | ˆ (keep) | |
+−−−−−−−−−−−−−−−−−−−−−−−−−−−−+−−−−−−−+
−
+−−−−−−−−−−−−−−−−−−+−−−−−−−−−−−−−−+
unbuild < (no−keep) uninstall
Alpine’s akms package installs a trigger script that monitors /usr/src/. Each time you install or remove a package that creates or updates a directory in /usr/src and that directory contains an AKMBUILD(5) file, the trigger runs "akms install /usr/src/<directory>". In other words, when you install a kernel module source package, it will be automatically built and installed for the currently installed kernel.
This can be disabled by setting disable_trigger in akms.conf(5) to “yes” or changing modules_srcdir ibid. to another directory.
To automatically rebuild available modules after a new kernel version is installed, AKMS uses the trigger−based mechanism provided by the kernel−hooks package. It provides the akms.hook script that is automatically symlinked into /etc/kernel−hooks.d. When a new kernel version is installed, this hook runs "akms install −k <new−kernel−ver> all" to build all modules found in modules_srcdir (/usr/src) for the new kernel. Analogically, when an old kernel version is uninstalled (i.e. with an upgrade), it runs "akms uninstall −k <old−kernel−ver> all" to uninstall all modules installed for the old kernel.
If you want to disable this hook, just remove the symlink in /etc/kernel−hooks.d.
/etc/akms.conf
The configuration file for akms(8).
/usr/src/<modname>−<modver>/AKMBUILD
Metadata and instructions to build a dynamic kernel module. See AKMBUILD(5).
The following tree illustrates all files and directories used or expected by akms(8).
/
ââ etc
â ââ akms.conf ...............
akms.conf(5)
â ââ kernel−hooks.d
â ââ <n>−akms.hook
−−−+ .. symlink to akms.hook
â |
ââ usr/share/kernel−hooks.d |
â ââ akms.hook
<−−−−−−−−−−+
.. the kernel hook
â
ââ lib/modules
â ââ <kernelver>
............. dynamic modules for the kernelver
â â ââ kernel/extra/akms/... files
installed by akms (modules_dest_path)
â : ...
â ââ <kernelver>
â
ââ tmp/akms .................... temp_dir
in akms.conf(5)
â ââ <timestamp> ............. a
temp dir created when building, removed afterwards
â ââ overlay/............. mount point for
a disposable root overlay
â
ââ usr/src ..................... directory with
sources (modules_srcdir in akms.conf(5))
â ââ
<modname>−<modver> ......
module's source directory
â â ââ AKMBUILD ............
AKMBUILD(5)
â â ââ *.c, *.h, ...
â : ...
â ââ
<modname>−<modver>
â
ââ var/lib/akms ................ the state
directory tree
ââ <kernelver> .............
directory with modules for particular kernel version
â ââ <modname> ...........
directory with versions of the module
â â ââ <modver>
........ module's state directory
â â â ââ build/ ......
module's build directory (in states building, failed)
â â â ââ modules/ .... built
kernel objects
â â â ââ state ....... file
with the state string
â â ââ <modver>
<−−−+
â â : ... |
â â ââ <modver> |
â â ââ installed
−−−+ .. symlink to the installed version
â : ...
â ââ <modname>
: ...
ââ <kernelver>
Jakub Jirutka
Report bugs to the project’s issue tracker at <https://github.com/jirutka/akms/issues>.
akms.conf(5) AKMBUILD(5)
Jakub Jirutka