Skip to content

kernel-modules: update the docs to use sysext #432

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

kernel-modules: update the docs to use sysext #432

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 41 additions & 25 deletions content/docs/latest/reference/developer-guides/kernel-modules.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,30 +34,28 @@ cd /mnt/work

```shell
modules=/opt/modules # Adjust this writable storage location as needed.
sudo mkdir -p "${modules}" "${modules}.wd"
```

Create a mount unit to use `/opt/modules` at boot - `/etc/systemd/system/usr-lib-modules.mount`:
```ini
[Unit]
Description=Custom Kernel Modules
Before=local-fs.target
ConditionPathExists=/opt/modules

[Mount]
Type=overlay
What=overlay
Where=/usr/lib/modules
Options=lowerdir=/usr/lib/modules,upperdir=/opt/modules,workdir=/opt/modules.wd

[Install]
WantedBy=local-fs.target
```

Enable the unit so this overlay becomes available:

```shell
sudo systemctl enable --now usr-lib-modules.mount
sudo mkdir -p "${modules}.wd"

# prepare the structure for kernel-modules sysext
sudo mkdir -p /var/lib/extensions/kernel-modules/usr/lib/{extension-release.d,modules}

# the kmod depends on current kernel and architecture, so include it in the metadata
# this causes systemd-sysext to skip loading the sysext after upgrade
source /etc/os-release && \
printf "ID=flatcar\nVERSION_ID=%s\nARCHITECTURE=%s\n" \
"$VERSION_ID" \
"$(hostnamectl | grep 'Architecture:' | awk '{print $2}')" \
| sudo tee /var/lib/extensions/kernel-modules/usr/lib/extension-release.d/extension-release.kernel-modules
Comment on lines +44 to +48
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nicer?

Suggested change
source /etc/os-release && \
printf "ID=flatcar\nVERSION_ID=%s\nARCHITECTURE=%s\n" \
"$VERSION_ID" \
"$(hostnamectl | grep 'Architecture:' | awk '{print $2}')" \
| sudo tee /var/lib/extensions/kernel-modules/usr/lib/extension-release.d/extension-release.kernel-modules
sudo tee /var/lib/extensions/kernel-modules/usr/lib/extension-release.d/extension-release.kernel-modules <<EOF
ID=flatcar
VERSION_ID=$(. /etc/os-release && echo \$VERSION_ID)
ARCHITECTURE=$(hostnamectl | grep 'Architecture:' | awk '{print $2}')
EOF

I had hoped to find a nicer way to get the architecture but no luck.


sudo tee /var/lib/extensions/kernel-modules/usr/lib/extension-release.d/extension-release.kernel-modules <<EOF
ID=flatcar
VERSION_ID=$(. /etc/os-release && echo $VERSION_ID)
ARCHITECTURE=$(hostnamectl | grep 'Architecture:' | awk '{print $2}')
EOF

sudo mount -t overlay overlay \
-o lowerdir=/usr/lib/modules,upperdir=/var/lib/extensions/kernel-modules/usr/lib/modules/,workdir=/opt/modules.wd \
/var/lib/extensions/kernel-modules/usr/lib/modules/
```

## Prepare a Flatcar Container Linux development container
Expand All @@ -84,7 +82,7 @@ Start the development container with the host's writable modules directory mount
Since the container requires access to loopback devices, `--capability=CAP_NET_ADMIN` is required.
```shell
sudo systemd-nspawn \
--bind=/usr/lib/modules \
--bind=/var/lib/extensions/kernel-modules/usr/lib/modules:/usr/lib/modules \
--capability=CAP_NET_ADMIN \
--image=flatcar_developer_container.bin
```
Expand All @@ -107,3 +105,21 @@ In case the installation step didn't update the module dependency files automati
```shell
sudo depmod
```

## Clean up and activate the sysext

Exit the developer container and unmount the path on host and actvate the built sysext.

```shell
# unmount the overlay
sudo umount /var/lib/extensions/kernel-modules/usr/lib/modules/

# verify the final contents
find /var/lib/extensions/kernel-modules/

# merge the freshly created sysext
sudo systemd-sysext refresh

# load the module
sudo modprobe <module name>
```
Loading