ublue-os akmods

OCI images providing a set of cached kernel RPMs and extra kernel modules to Universal Blue images. Used for better hardware support and consistent build process.

How it's organized

The akmods images are built and published daily. However, there's not a single image but several, given various kernels we now support.

The akmods packages are divided up for building in a few different "groups":

• common - any kmod installed by default in Aurora/Bazzite/Bluefin (or were originally in main images pre-Fedora 39)
• extra - less common kmods used by only one Universal Blue project.
• nvidia - only the nvidia proprietary kmod and addons
• nvidia-open - only the nvidia-open kmod and addons
• zfs - only the zfs kmod and utilities built for select kernels

Each of these images contains a cached copy of the respective kernel RPMs compatible with the respective kmods for the image.

Builds also run for different kernels:

• main - Mainline Fedora Kernel
• coreos-stable - Current Fedora CoreOS stable kernel version
• coreos-testing - Current Fedora CoreOS testing kernel version
• Centos - Mainline Centos Kernel
• Longterm-6.18 - Fedora Kernel on Kernel 6.18 LTS

See images.yaml for which akmods packages are built for each Kernel

Features

Overview

The common images contain related kmod packages, plus:

• ublue-os-akmods-addons - installs extra repos and our kmods signing key; install and import to allow SecureBoot systems to use these kmods

The nvidia and nvidia-open images contains

• ublue-os-nvidia-addons - installs extra repos enabling our nvidia support
  • nvidia container selinux policy - uses RHEL9 policy as the closest match
  • nvidia-container-toolkit repo - version 1.14 (and newer) provide CDI for podman use of nvidia gpus
• ublue-os-ucore-nvidia - a slightly lighter ublue-os-nvidia-addons for CoreOS/uCore systems

Kmod Packages

Group	Package	Description	Source
common	framework-laptop	A kernel module that exposes the Framework Laptop (13, 16)'s battery charge limit and LEDs to userspace
common	openrazer	kernel module adding additional features to Razer hardware
common	v4l2loopback	allows creating "virtual video devices"	RPMFusion - free
common	wl	support for some legacy broadcom wifi devices	RPMFusion - nonfree
common	xone	xbox one controller USB wired/RF driver modified to work along-side xpad (built from xonedo fork)
common	xpadneo	xbox one controller bluetooth driver	negativo17 - fedora-multimedia
extra	evdi	DisplayLink USB graphics adapter support	negativo17 - fedora-multimedia
extra	gcadapter_oc	Gamecube controller adapter overclocking
extra	hid-fanatecff	Fanatec wheel base force feedback	Terra
extra	hid-tmff2	Thrustmaster T300RS, T248, TX, T128, T598, T-GT II, TS-XW force feedback	Terra
extra	kvmfr	KVM framebuffer relay kernel module for use with Looking Glass
extra	nct6687d	Linux kernel module for Nuvoton NCT6687D/NCT6687-R motherboard fan control	Terra
extra	new-lg4ff	Logitech force feedback wheels	Terra
extra	ryzen-smu	AMD Ryzen SMU (System Management Unit) driver
extra	sc0710	Elgato 4K60 Pro MK.2 / 4K Pro capture card driver	Terra
extra	system76	System76 laptop hardware support
extra	system76-io	System76 Thelio I/O board driver
extra	t150-driver	Thrustmaster T150 steering wheel	Terra
extra	zenergy	AMD Zen energy monitoring driver	Terra
nvidia-open	nvidia	nvidia-open GPU drivers	negativo17 - fedora-nvidia
zfs	zfs	OpenZFS advanced file system and volume manager	zfs

Notes

NVIDIA Hardware Support

We build both the open and closed drivers from NVIDIA. The open driver is the only option for supporting the latest hardware. The closed driver is required for older hardware, but even it doesn't support "legacy" hardware.

nvidia-open - newest current and most open driver supports the following hardware:

• GeForce RTX: 50 Series, 40 Series, 30 Series, 20 Series
• GeForce: 16 Series
• and more: NVIDIA Compatible GPUs list

nvidia - closed proprietary driver supports the following hardware:

• GeForce RTX: 40 Series, 30 Series, 20 Series
• GeForce: 16 Series, 10 Series, 900 Series, 700 Series
• NVIDIA Turing: T4, T4G
• NVIDIA Volta: V100
• NVIDIA Pascal: Quadro: P2000, P4000, P5000, P6000, GP100; Tesla: P100, P40, P4
• NVIDIA Maxwell: Quadro: K2200, M2000, M4000, M5000, M6000, M6000 24GB; - - Tesla: M60, M40, M6, M4

Pinning the coreos-stable kernel

coreos_stable_kernel_pin in the Justfile is a temporary ceiling on the kernel used for every coreos-stable target (common, nvidia-lts, nvidia-open, zfs). It exists so publication can continue when Fedora CoreOS stable ships a kernel that OpenZFS cannot yet build.

Empty '' means follow upstream fedora-coreos:stable. A value like '6.17.12' is a major.minor.patch cap applied in get-kernel-version for coreos-stable only. Newer detected kernels are rewritten to that pin plus the detected release suffix, then verified in Koji. Kernels at or below the pin pass through.

Use the pin when all of these are true:

1. coreos-stable ZFS builds are reliably failing, not flaking.
2. The failure is kernel-version incompatibility: OpenZFS META Linux-Maximum is below the current CoreOS stable kernel, or configure rejects the kernel as unsupported.
3. Waiting for an OpenZFS release would keep the entire coreos-stable check job red, blocking publication of the other targets (and kernel CVE / nvidia updates) to downstream stable images such as ucore:stable.

Do not use the pin for transient CI or network flakes, failures that are not “kernel newer than OpenZFS supports,” coreos-testing (set zfs.linux_experimental in images.yaml if you intentionally want to track newer kernels), or as a long-term fork of the CoreOS stable kernel. Prefer the pin over inventing local OpenZFS kernel-compat backports when the only goal is to restore publication. Carry an already-upstreamed ZFS fix only when the team has explicitly decided to do that.

To apply the pin:

1. Read the last successful major.minor.patch from a published image (ostree.linux on ghcr.io/ublue-os/akmods-zfs:coreos-stable-<ver>) or from a prior build/*/KCWD/rpms/cache.json.
2. Set coreos_stable_kernel_pin := 'X.Y.Z' in the Justfile, then commit and merge.
3. Clear it back to '' as soon as ZFS builds on the current CoreOS stable kernel.

Downstream stable images keep the older kernel until the pin is cleared. That is intentional: operations continue, but new kernel CVEs in the unpinned CoreOS kernel wait.

A coreos-stable ZFS job that fails for this unsupported-kernel reason prints a pointer to this section.

Usage

To install one of these kmods, you'll need to install any of their specific dependencies (checkout the build-prep.sh and the specific build-FOO.sh script for details), and ensure you are on a compatible kernel.

Using common images as an example, add something like this to your Containerfile, replacing TAG with the appropriate tag for the image:

COPY --from=ghcr.io/ublue-os/akmods:TAG / /tmp/akmods-common
RUN find /tmp/akmods-common
## optionally install remove old and install new kernel
# dnf -y remove --no-autoremove kernel kernel-core kernel-modules kernel-modules-core kernel-modules-extra
## install ublue support package and desired kmod(s)
RUN dnf install /tmp/rpms/ublue-os/ublue-os-akmods*.rpm
RUN dnf install /tmp/rpms/kmods/kmod-v4l2loopback*.rpm

For NVIDIA images, add something like this to your Containerfile, replacing TAG with the appropriate tag for the image:

COPY --from=ghcr.io/ublue-os/akmods-nvidia:TAG / /tmp/akmods-nvidia
RUN find /tmp/akmods-nvidia
## optionally install remove old and install new kernel
# dnf -y remove --no-autoremove kernel kernel-core kernel-modules kernel-modules-core kernel-modules-extra
## install ublue support package and desired kmod(s)
RUN dnf install /tmp/rpms/ublue-os/ublue-os-nvidia*.rpm
RUN dnf install /tmp/rpms/kmods/kmod-nvidia*.rpm

Note There is an nvidia-install script that most universal-blue images use located with the main repo that works for desktop Fedora installs.

Verification

Image Signatures

All architecture images and manifest indexes are signed by Podman with the shared Universal Blue static key. Prefer verifying immutable, digest-pinned subjects with Cosign v3.1.2:

cosign verify \
  --key https://raw.githubusercontent.com/ublue-os/main/main/cosign.pub \
  ghcr.io/ublue-os/akmods@sha256:DIGEST

For historical manifest digests with registry-attached GitHub provenance, use legacy bundle discovery:

cosign verify \
  --new-bundle-format=false \
  --key https://raw.githubusercontent.com/ublue-os/main/main/cosign.pub \
  ghcr.io/ublue-os/akmods@sha256:DIGEST

The ublue-os/main/cosign.pub key is the Universal Blue image trust root. Mutable tags such as main-44 or coreos-stable-43 are convenient for discovery, but a digest is the preferred verification target.

Build Provenance

GitHub build provenance is a separate trust decision from image signatures: it uses a short-lived GitHub OIDC certificate rather than the Universal Blue static key. Provenance currently covers the release and kernel-version manifest indexes, not architecture-only image digests.

gh attestation verify \
  oci://ghcr.io/ublue-os/akmods@sha256:DIGEST \
  --repo ublue-os/akmods

Provenance is stored in GitHub's attestations API. It is no longer published as a registry referrer, so registry provenance and GitHub linked-artifact storage records are not available for newly published digests.

Local Building/Testing

You can build these akmods locally with our test keys using the included Justfile. We strongly recommend using the provided devcontainer which contains all dependencies for building this project.

How to Use the Justfile

To build an akmods package, run the following:

just build

Since nothing additional was set. The following will occur. The build scripts will determine the current fedora kernel version, download the RPMs, and sign the kernel with the test key. It will then build the common set of akmods. To modify what gets built, modify the following environment variables:

• AKMODS_KERNEL - The kernel flavor you are building
• AKMODS_VERSION - The release version
• AKMODS_TARGET - The akmods package to build

AKMODS_KERNEL=centos AKMODS_VERSION=10 AKMODS_TARGET=zfs just build

Will determine the current centos kernel version, download the rpms and sign them, and will then build the zfs package.

You can also populate a .env file to store your current settings.

You can see your current settings with just --evaluate

Additionally you can pass values as key/value pairs.

just kernel_flavor=main version=42 akmods_target=extra build

Which will build the extra package for main.

Note, the Justfile will compare your inputs to the images.yaml file to ensure you have a valid combination.

How to Use images.yaml

All build targets are defined in the images.yaml file. This is where the top level targets are defined. You can view the targets using:

yq 'explode(.).images' images.yaml

Adding Kernels and KMODs

Generally speaking, Kernels are only added if they will be used internally to Universal Blue.

KMODs as well will likely only be included if there is a need/desire to include them within the Universal Blue Project. Generally, KMODs for hardware enablement will be considered for inclusion or ones that fix/resolve a known feature gap.

Don't hesitate to file an issue asking about inclusion.

Metrics