Details

Reviewers

fernape
carlavilla
grahamperrin

Group Reviewers

docs
Doc Committers

Commits

R9:a836774703fa: [Handbook]: Clarify kernel modules on upgrades

Summary

Affects:

https://docs.freebsd.org/en/books/handbook/cutting-edge/#freebsdupdate-upgrade.

https://github.com/freebsd/freebsd-doc/pull/164 condensed:

forewarn users that FreeBSD-provided packages of kernel modules might be unusable with a new version of the OS until some time after the version is announced.

An example of a module that will not load following a simple forced upgrade of its package:

text
root@fuji:~ # kldload vboxdrv
kldload: an error occurred while loading module vboxdrv. Please check dmesg(8) for more details.
root@fuji:~ # pkg upgrade --force --quiet --yes virtualbox-ose-kmod && kldload vboxdrv && uname -aKU
kldload: an error occurred while loading module vboxdrv. Please check dmesg(8) for more details.
root@fuji:~ # uname -aKU
FreeBSD fuji 13.2-RELEASE FreeBSD 13.2-RELEASE releng/13.2-n254617-525ecfdad597 GENERIC amd64 1302001 1302001
root@fuji:~ # dmesg | tail -n 2
KLD vboxdrv.ko: depends on kernel - not available or version mismatch
linker_load_file: /boot/modules/vboxdrv.ko - unsupported file type
root@fuji:~ #

Origin of this diff:

https://patch-diff.githubusercontent.com/raw/freebsd/freebsd-doc/pull/164.diff.

Test Plan

Preview in GitHub:

https://github.com/grahamperrin/freebsd-doc/blob/bug-270338/documentation/content/en/books/handbook/cutting-edge/_index.adoc#23-performing-minor-and-major-version-upgrades.

Diff Detail

Repository

R9 FreeBSD doc repository

Lint

Lint Not Applicable

Unit

Tests Not Applicable

Event Timeline

grahamperrin requested review of this revision.Apr 9 2023, 6:18 PM

grahamperrin created this revision.

jrm added a subscriber: jrm.Apr 10 2023, 4:13 AM

jrm added inline comments.

documentation/content/en/books/handbook/cutting-edge/_index.adoc
270	..might not be suitable for 13.2.

Accepting Glen's suggestion.

ceri added a subscriber: ceri.Apr 10 2023, 8:06 AM

ceri added inline comments.

documentation/content/en/books/handbook/cutting-edge/_index.adoc
262	not use the newest

https://github.com/grahamperrin/freebsd-doc/commit/1e617a5a58f9adcb50028266468b5b06266b9a9f pays attention to version numbers in examples.

grahamperrin marked an inline comment as done.Apr 10 2023, 8:20 AM

grahamperrin added inline comments.

documentation/content/en/books/handbook/cutting-edge/_index.adoc
262	Done with https://github.com/freebsd/freebsd-doc/pull/164/commits/3ee9f64e3b14d700ae391fffef1f08308b52675a. Nice catch.

https://github.com/freebsd/freebsd-doc/pull/164/commits/3ee9f64e3b14d700ae391fffef1f08308b52675a – @ceri's correction.

grahamperrin edited the summary of this revision. (Show Details)Apr 11 2023, 11:26 PM

…

An example of a module that will not load following a simple forced upgrade of its package:

…

Confirming that the same version of the module does load following build from source (in a jail that is upgraded to 13.2-RELEASE):

root@fuji:~ # poudriere bulk -j thirteen -J 4 -Ctv emulators/virtualbox-ose-kmod
…
root@fuji:~ # pkg upgrade --force -r poudriere virtualbox-ose-kmod
Updating poudriere repository catalogue...
poudriere repository is up to date.
All repositories are up to date.
Checking integrity... done (0 conflicting)
The following 1 package(s) will be affected (of 0 checked):

Installed packages to be REINSTALLED:
        virtualbox-ose-kmod-6.1.36 [poudriere]

Number of packages to be reinstalled: 1

Proceed with this action? [y/N]: y
[1/1] Reinstalling virtualbox-ose-kmod-6.1.36...
[1/1] Extracting virtualbox-ose-kmod-6.1.36: 100%
root@fuji:~ # kldload vboxdrv
root@fuji:~ # kldstat | grep vb
20    1 0xffffffff82dbf000    590f0 vboxdrv.ko
root@fuji:~ #

grahamperrin added inline comments.Apr 12 2023, 1:26 AM

documentation/content/en/books/handbook/cutting-edge/_index.adoc
262	newer … is probably better than newest

https://github.com/freebsd/freebsd-doc/pull/164/commits/78fc0f2082493013b42df10c18435c4f65446b47

newer, not newest

Related to this, I think the best advice would be to use PORTS_MODULES in /etc/make.conf. At least when the problem happens in CURRENT.
Unfortunately this piece of information has gone away in the last revamp of the X11 chapter of the handbook.
I think we should get it back.

In D39474#899925, @fernape wrote:

Related to this, I think the best advice would be to use PORTS_MODULES in /etc/make.conf.
Unfortunately this piece of information has gone away in the last revamp of the X11 chapter of the handbook.
I think we should get it back.

What part? No problem to get it back, let me know the part and I'll add it again

For now, can we get the warning in quickly? Then refine things.

Someone from FreeBSD Forums contacted me in IRC/Matrix drawing attention to a case today that involves the virtualbox-ose-kmod example above:

https://forums.freebsd.org/threads/88747/.

Thanks

In D39474#899927, @carlavilla wrote:

In D39474#899925, @fernape wrote:

Related to this, I think the best advice would be to use PORTS_MODULES in /etc/make.conf.
Unfortunately this piece of information has gone away in the last revamp of the X11 chapter of the handbook.
I think we should get it back.

What part? No problem to get it back, let me know the part and I'll add it again

It would be this.
However, although it talks about a graphic driver, it is more general and it is related to updating from sources. So maybe that piece should go near here.
I don't know if pkg(8) has a similar system that would trigger the rebuild of a module if the system is binary updated (as with freebsd-update).

In D39474#899951, @fernape wrote:

In D39474#899927, @carlavilla wrote:

In D39474#899925, @fernape wrote:

Related to this, I think the best advice would be to use PORTS_MODULES in /etc/make.conf.
Unfortunately this piece of information has gone away in the last revamp of the X11 chapter of the handbook.
I think we should get it back.

What part? No problem to get it back, let me know the part and I'll add it again

It would be this.
However, although it talks about a graphic driver, it is more general and it is related to updating from sources. So maybe that piece should go near here.
I don't know if pkg(8) has a similar system that would trigger the rebuild of a module if the system is binary updated (as with freebsd-update).

Sure, can you please add a NOTE or something like that? As Graham pointed, we need to fix this ASAP

Thanks for the warnong Fernando and Graham

LGTM.

Let's think about where to reintroduce the PORTS_MODULES information and point there from this warning in a future change.

This revision is now accepted and ready to land.Apr 12 2023, 4:54 PM

In D39474#899962, @fernape wrote:

LGTM.

Let's think about where to reintroduce the PORTS_MODULES information and point there from this warning in a future change.

Nod

Thanks, overlap with https://github.com/freebsd/freebsd-doc/commit/b8788e696d, ~~I'll manually edit my branch in GitHub to match Allan's changes, then … deal with likely trailing whitespace errors (my habitual mistake) and push.~~

Sorry, I'll be unable to resolve the conflict at the command line (and please, no offers of help), ~~can someone else do the honours with resolution and commit? Many thanks~~

Fixed in GitHub, I think …

This revision now requires review to proceed.Apr 13 2023, 5:14 PM

grahamperrin added inline comments.Apr 13 2023, 5:43 PM

documentation/content/en/books/handbook/cutting-edge/_index.adoc
323	Without a suitable test system, I couldn't tell for certain whether this should be 13.1 or 13.2. Looking at the "ns2-bachi-net" kernel example at https://blog.bachi.net/?p=4380, and other real-world examples, I'm fairly certain that it should be 13.1 (for an upgrade from 13.1 to 13.2). Fixed in GitHub, I'll update the diff in Phabricator.