Modernised use of freebsd-update for minor and major upgrades to FreeBSD

@kpax thanks.

Most readers will, understandably, think of thirty-three steps as ridiculous – partly because it felt good, historically, to portray FreeBSD upgrades as requiring no more than a handful of steps.

The "works for me" mindset, cutting corners without realising it, is true for some people, not for others. Some people:

• have no non-base kernel modules
• do not use hardware that's affected by boot loader bug 294630, for which there's no release note

– and so on.

Oversimplification of upgrade routines is popular, but not good practice.

Blog posts that regurgitate official documentation are good for bloggers who want clicks, but it's a problem when the basis for those posts is wrong.

Credit to Michael Larabel (Phoronix) for special attention to the essence of the third release candidate:

> Critical bug fixes to the x86 boot loader / kernel handoff which can cause the boot to hang; this seems to happen most often but not exclusively when Intel microcode updates are being loaded.

I added another step (currently 33) for misc/compat14x.

Thank you for the ace instructions. I'm glad I waited to upgrade, as I didn't trust myself to be able to work out the kmod hiccup, but these were perfect. Just finished upgrading 15.0R-p10 to 15.1R and everything just works. Boot up is perceptibly faster, which is a nice cherry on top of the smooth upgrade. Edit: Now that the upgrade is complete, I'm going to bectl my way to trying a pkgbasify conversion. I was going to wait until 16.0R, but have half a mind of pulling the trigger early seeing as how these problems seemed non-existent on pkgbase and it's in our future anyway.

Oracle VirtualBox

The FreeBSD-ports-kmods repo includes kernel modules for FreeBSD as a host but not as a guest:

grahamperrin@clean:~ % pkg search -r FreeBSD-ports-kmods virtualbox-ose-additions-72
grahamperrin@clean:~ % pkg search -r FreeBSD-ports-kmods virtualbox-ose-additions
grahamperrin@clean:~ % pkg search -r FreeBSD-ports-kmods virtualbox
virtualbox-ose-kmod-6.1.50.1501000_1 VirtualBox kernel module for FreeBSD
virtualbox-ose-kmod-70-7.0.26.1501000 VirtualBox kernel module for FreeBSD
virtualbox-ose-kmod-71-7.1.18.1501000 VirtualBox kernel module for FreeBSD
virtualbox-ose-kmod-72-7.2.8.1501000 VirtualBox kernel module for FreeBSD
virtualbox-ose-kmod-legacy-5.2.44.1501000_7 VirtualBox kernel module for FreeBSD
grahamperrin@clean:~ %

Guest Additions

The FreeBSD-ports repo currently includes modules for 15.0 that do load with 15.1-RELEASE.

An example with latest:

grahamperrin@clean:~ % kldstat | grep vb
13    1 0xffffffff837a2000    38d00 vboxguest.ko
grahamperrin@clean:~ % uname -KU
1501000 1501000
grahamperrin@clean:~ % pkg query '%At %Av' virtualbox-ose-additions-72
FreeBSD_version 1500068
build_timestamp 2026-06-18T02:27:44+0000
built_by poudriere-git-3.4.8
cpe cpe:2.3:a:oracle:vm_virtualbox:7.2.10:::::freebsd15:x64
flavor xorg
port_checkout_unclean no
port_git_hash bbd7ab52a8a20722c901b3e4950cbb7e2b52581c
ports_top_checkout_unclean no
ports_top_git_hash 8fe72327c24ccd35a826c402c09af4831ccb6725
repo_type binary
repository FreeBSD-ports
grahamperrin@clean:~ % pkg info --list virtualbox-ose-additions-72 | grep .ko
        /boot/modules/vboxguest.ko
        /boot/modules/vboxvfs.ko
grahamperrin@clean:~ % service vboxguest status
/usr/local/etc/rc.d/vboxguest: unknown directive 'status'.
Usage: /usr/local/etc/rc.d/vboxguest [fast|force|one|quiet](https://billboard.bsd.cafe/start|stop|restart|rcvar|enable|disable|delete|enabled|describe|extracommands)
grahamperrin@clean:~ % service vboxservice status
vboxservice is running as pid 1960.
grahamperrin@clean:~ % su -
Password:
root@clean:~ # kldload vboxvfs
root@clean:~ # exit
logout
grahamperrin@clean:~ % kldstat | grep vb
13    2 0xffffffff837a2000    38d00 vboxguest.ko
18    1 0xffffffff837f9000    26be1 vboxvfs.ko
grahamperrin@clean:~ % 

The guide above should help to avoid kernel panics and other issues with kernel modules.

Relevant documentation includes:

• freebsd-update(8)
• FreeBSD 15.1-RELEASE Upgrading Instructions | The FreeBSD Project (2026-06-15) – bugged.

TomAoki notes the importance of upgrading the boot loader before – not after – the first boot of 15.1-RELEASE.

Thanks to Emrion in The FreeBSD Forums for inspiring the sh(1)-specific export lines.

---

Cross-post: Modernised use of freebsd-update … : r/freebsd

Users of freebsd-update(8) with 14.4-RELEASE, please note:

• Upgrading with Distribution Sets has no real hint that non-base packages should be forcibly upgraded following a major upgrade of base.

Noted:

> freebsd-update(8) may prompt to rebuild or reinstall all third-party software due to changes in system libraries. Follow those instructions as needed.

If I recall correctly, the instructions do not demonstrate use of --force.

Steps 28-35 above do include pkg commands that will ultimately force a combined upgrade from two repositories, excluding FreeBSD-base:

• FreeBSD-ports and FreeBSD-ports-kmods

– there should be comparable advice in official documentation.

> upgrade the boot loader

sysutils/loaders-update

> Update bootcodes and loaders > > This utility is a tool designed to keep the FreeBSD bootcodes and loaders up-to-date. It's useful because the FreeBSD upgrade process doesn't update them. It verifies if they are up to date and updates them if desired.

FreeBSD-ports-kmods and NVIDIA

Noted in Reddit:

> … kmods are built on freebsd 15 until its end of life, and then they are built on freebsd 15.1. > > which is why you get the problem when you upgrade to 15.1 of them not working and the kdl error, so you either need to build them from ports or use poudrire …

Essentially: users of NVIDIA GPUs should be prepared to build their own packages, for the non-base kernel modules, at times of minor and major OS upgrades.

grahamperrin@clean:~ % pkg search -r FreeBSD-ports-kmods nvidia
nvidia-kmod-595.71.05.1501000  NVIDIA graphics driver kernel module
grahamperrin@clean:~ % pkg repos -e FreeBSD-ports-kmods | grep url
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/kmods_latest_1",
grahamperrin@clean:~ %

/boot/modules/nvidia.ko
/boot/modules/nvidia-modeset.ko
/boot/modules/nvidia_gsp_ga10x_fw.ko
/boot/modules/nvidia_gsp_tu10x_fw.ko

14.4-RELEASE to 15.0-RELEASE

Tested successfully with:

• 1500500 as the osversion
• latest for FreeBSD and FreeBSD-kmods.

I hope that 1500500 is appropriate. I took it from the FreeBSD 15 Versions section of Chapter 8 of the FreeBSD Porter's Handbook.

The RELEASE announcement at refers to a page that was originally a necessary duplicate of the upgrade instructions: . The installation page no longer exists:

In the Wayback Machine: Upgrading with Base System Packages

> … Systems running 14.4-RELEASE or 15.0-RELEASE can be upgraded as follows: …

• the instructions were incorrect for a pkgbase major upgrade.

Now in the introduction:

> … 14.4-RELEASE or 15.0-RELEASE installations to 15.1-RELEASE. …

– and 14.4 is not mentioned for pkgbase:

> … 15.0-RELEASE can be upgraded …