"kernel-devel" and kernel module builds for TemplateVMs documentation missing

[mtalexan]

Qubes OS version:

R3.2 and R4.0

Affected component(s):

Documentation

---

Steps to reproduce the behavior:

Search documentation for details on building kernel modules for TemplateVMs

Expected behavior:

Documentation exists with at least basic directional instructions

Actual behavior:

No documentation exists. The closest only discusses how to use different kernels in VMs (https://www.qubes-os.org/doc/managing-vm-kernel/)

General notes:

The topic is clearly not self-explanatory as there are a number of open issues regarding the kernel-devel package for Fedora-* TemplateVMs, and there are many hits on Google Groups discussions about the topic, most without a clear resolution.
The consensus seems to be that the Qubes-provided kernel is unlikely to work for most use cases. If the drivers weren't provided as part of the Fedora kernel the Qubes-provided variant is based on, the module is frequently tightly coupled with specific kernel versions. This means the usual rpmfusion and the like, which are frequently the primary/sole sources of these modules for most users, won't contain a version that works with, or can be built against, the Qubes kernel. Instead they'll only support the most recent handful of kernel versions the stock Fedora provided, the oldest of which is usually newer than the newest Qubes dom0 kernel version.
Even for akmods and dkms drivers that try to build against the "current" kernel, this holds true. These types of modules are designed to be built from source automatically for the specific user's system under the assumption the kernel-devel package has been installed. They fail consistently though, even when the kernel-devel package for the Qubes-provided kernel is installed in the Fedora-XX TemplateVM that is set to use the Qubes-provided kernel. This is usually a result of the build-from-source configurations in the packages akmods/dkms are building. The source packages will frequently need/assume specific tools and/or settings are available for the "current" kernel. Then the equivalent tools and settings are needed within the dom0 Qubes-provided kernel, but are not available or accessible. Usually these tools would be provided thru the dnf repositories, but Qubes fails to provide many of these that match the kernel versions released for dom0. They aren't available thru the usual Fedora dnf repositories either, becuase the Fedora repository provided versions are built against the Fedora-provided kernels.
The recommendation, as pieced together from the various threads, is to instead create an "unsafe" TemplateVM clone that uses the Fedora/Debian-provided kernel instead of the tested and validated dom0 kernel as an HVM, and build/run the kernel modules against that. For things like a netVM, this is frequently the only option available to get WiFi chips working that require non-free binary drivers.

A documentation page discussing this issue, specifically this pieced together "resolution" should be created to consolidate what's known on this topic rather than having parts of it scattered all over the internet. A link to the page on how to change the kernel version in a VM, including some clarification about which parts of it are relevant, and the basic run-down given above would be sufficient.

---

Related issues:

#3835
#3742
#3158
#2908
#2844
#2692

[andrewdavidwong]

@mtalexan, would you be willing to submit a PR for this? Please see the Documentation Guidelines for details.

[andrewdavidwong]

@mtalexan, would you be willing to submit a PR for this? Please see the Documentation Guidelines for details.

[mtalexan]

Sure. I'll create and submit the PR with a recommendation on how it could/should be hooked into the existing top few documentation pages that aren't part of qubes-doc

[mtalexan]

Sure. I'll create and submit the PR with a recommendation on how it could/should be hooked into the existing top few documentation pages that aren't part of qubes-doc