AKMS(8)

📦

version 0.3.0 · 2 versions

0.3.0 · alpine 3.22, alpine 3.23 (latest)
0.3.0 · alpine 3.24

✨ AKMS(8) ✨ — Alpine Kernel Module Support 💅

okay so like, this is the manual page for akms (section 8 of the manual, bestie), the Alpine Kernel Module Support tool. grab a snack, we're getting into it 🫶

🌸 NAME 🌸

akms — Alpine Kernel Module Support ✨

🎀 SYNOPSIS 🎀

akms (install | build) [options] <srcdir | all>

akms (uninstall | unbuild) [options] <modname>[/<modver>]

akms status [options] [<modname>[/<modver>]]

akms [-h] [--help] [-V]

🦋 DESCRIPTION 🦋

so akms(8) (aka AKMS) is this iconic tool that builds out-of-tree (external) Linux kernel modules from source for each installed kernel on your system, in an automated and organized fashion. like, no cap, fully automated. the whole concept is that your kernel modules get automatically rebuilt whenever a new kernel version lands on your machine. main character energy fr 💅

AKMS is principally inspired by DKMS (Dynamic Kernel Module Support), which a lot of Linux distros use. but AKMS was designed specifically for Alpine Linux and apk(8), implemented with simplicity, reliability, and security in mind. periodt. 👑

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. so yeah, it's sealed up nicely 🫧

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). slay 🗜️

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're automatically installed in a disposable overlay over your real root filesystem (using OverlayFS and bubblewrap). the original reason for using overlay was to dodge the limitation of the APK triggers — they run inside a "transaction" that holds an exclusive repository lock. which means 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 gives you other benefits too. lowkey genius 💡

✨ ACTIONS ✨

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. out with the old, in with the new 💖

build — The same as install, but it will only build the module without installing into /lib/modules. it's giving "look but don't touch" 🙈
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). vibe check on your modules 🔍

🔥 OPTIONS 🔥

💜 Common Options

The following options are available for all actions, bestie.

-q, --quiet — Be quiet, print only warn and error messages. This option overrides parameter log_level specified in akms.conf(5). shhh 🤫
-v, --verbose — Be verbose, print even debug messages. This option overrides parameter log_level specified in akms.conf(5). tell me EVERYTHING 🗣️
-V, --version — Print the program version and exit.
-h, --help — Print the help message and exit.

🧚 Install and Build Options

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. do it again, do it bigger 💅
--[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. leaving the mess behind, iconic 🫧

🍓 Uninstall Options

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). ⚠️ careful, bestie
-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. 🍦

🌈 Unbuild Options

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). bold move 😭
-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. 🍦

⭐ Status Options

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.

👑 MODULE STATE 👑

A specific module version for a specific kernel can be in one of the following states, bestie:

(no state) — The given module version for the given kernel has not been built yet, there is no entry in the state directory. it's giving nonexistent 🙈
building — The module is currently being built. ⏳
built — The module has been successfully built, but it is not installed in /lib/modules. so close 🥺
installed — The module is built and installed in /lib/modules. slay! 💅
failed — The module failed to be built. 😭 rip
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. 💀 uh oh

The following diagram illustrates all possible transitions between the states supported by akms(8). keep your eyes on it:

                    build                (OK)            install
       (no state) ---------> [building] ------> [built] ---------> [installed] --------+
            ^                    ^      \        |   ^                :   ^            |
            |                    |       |       |   |                :   |            |
            |              build |       | (NOK) |   |                :   | install    |
            |                    |       v       |   |                v   |            |
            |                    `--- [failed]   |   |             [corrupted]         |
            |                            |       |   |                  |              |
            |                            |       |   | ^ (keep)         |              |
            +----------------------------+-------+ - +------------------+--------------+
                           unbuild                 < (no-keep)      uninstall

🎀 APK TRIGGERS 🎀

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. auto-pilot fr 🛫

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. easy 🫶

🗂️ FILES 🗂️

Okay bestie, here’s the filesystem map — this is where akms(8) keeps its stuff and where it expects to find yours 💖

/etc/akms.conf — the configuration file for akms(8), no cap.
/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). Literally the whole vibe, laid out 👑

/
├─ 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>

💖 AUTHORS 💖

The author credit goes to Jakub Jirutka — periodt 🫶

🐛 REPORTING BUGS 🐛

Found a bug? Don’t suffer in silence, bestie 😭 Report bugs to the project’s issue tracker at https://github.com/jirutka/akms/issues.

👀 SEE ALSO 👀

akms.conf(5)
AKMBUILD(5)

👑 AUTHOR 👑

Again, iconic behavior: Jakub Jirutka 💅✨

And that’s the whole map, bestie — you absolutely ate this read-through 🗺️💖 The footer situation is AKMS(8), dated 2025-01-05, and yes, it’s giving reference-page royalty 👑🌸

📦 where this page comes from

alpine 3.22: akms-doc 0.3.0-r0 · MIT
alpine 3.23: akms-doc 0.3.0-r0 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms