Upgrading FreeBSD 14 to 15 with pkgbase
I just went through what has been by far the most difficult upgrade of FreeBSD since the beginning of time (circa 1999, version 3.4). I used to do it via make buildworld before mergemaster existed, so I’m used to a lot of effort to upgrade.
My system runs 14.3 with pkgbase converted from a regular install when it was 14.2 on ZFS root and uses the MINIMAL kernel as set in the /boot/loader.conf file. I wanted to upgrade to 15.0-RELEASE. What I ended up with is 15.0-RELEASE user-land and a 15-STABLE kernel. Here’s what I had to do. Mostly this follows the instructions from the FreeBSD Handbook. I’ve since been told that the handbook is out of date.
I did it several times and distilled it down to these steps.
Learning that I needed to alter the fingerprints setting in the FreeBSD-base.conf file took forever to suss out but I found it in another forum post. The admonition in the release notes is to install the new signature keys only for prior test releases of 15, but it seems to apply to 14.3 pkgbase systems as well, basically any system which does not have /usr/share/keys/pkgbase-15 on it.
One additional thing I did was uninstall the source code packages. My system uses a separate ZFS dataset for /usr/src (which is what pkgbasify does when converting a traditional system), so upgrading within a boot environment will install the source code into /usr/src within the BE. When booted the ZFS data set will sit on top of /usr/src from the BE and now you have 1GB of orphaned space in the BE dataset and will still see the sources for the older 14.3!
pkg remove FreeBSD-src FreeBSD-src-sys
bectl create 15.0-RELEASE
bectl mount 15.0-RELEASE /mnt/upgrade
pkg -c /mnt/upgrade lock pkg
pkg -c /mnt/upgrade add -f https://pkg.freebsd.org/FreeBSD:15:amd64/base_release_0/FreeBSD-pkg-bootstrap-15.0.pkg
# edit the file FreeBSD-base.conf to set the url to base_release_0 and fingerprints to point to "/usr/share/keys/pkgbase-15"
emacs /mnt/upgrade/usr/local/etc/pkg/repos/FreeBSD-base.conf
env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base
pkg -c /mnt/upgrade unlock pkg
chroot /mnt/upgrade
freebsd-version -kru
exit
Now at this point, we have a problem… there doesn’t appear to be a minimal kernel package in the base_release_0 package set:
root@lorax:~ # pkg -c /mnt/upgrade info | grep FreeBSD-kernel
pkg: Warning: Major OS version upgrade detected. Running "pkg bootstrap -f" recommended
FreeBSD-kernel-generic-15.0 FreeBSD GENERIC Kernel
FreeBSD-kernel-generic-mmccam-14.3p6 FreeBSD GENERIC-MMCCAM kernel
FreeBSD-kernel-minimal-14.3p6 FreeBSD MINIMAL kernel
I deleted the 14.3 minimal kernel package and tried to install the 15 package:
# pkg -c /mnt/upgrade install FreeBSD-kernel-minimal
... other output...
pkg: No packages available to install matching 'FreeBSD-kernel-minimal' have been found in the repositories
Among the many tries at upgrading, one of them was to upgrade to base_latest which curiously had not one difficulty. So I figured I will just grab the minimal kernel from there. I also went ahead and upgraded all of the other packages. I think I could have gotten away with just installing the compat14x-amd64 package for the older shared libraries and upgrade all packages later.
pkg -c /mnt/upgrade add -f https://pkg.freebsd.org/FreeBSD:15:amd64/base_latest/FreeBSD-kernel-minimal-15.snap20251201164446.pkg
bectl activate -t 15.0-RELEASE
pkg -c /mnt/upgrade upgrade
shutdown -r now
Now I have a usable minimal kernel. The system does boot and runs fine so far.
After the reboot and final verification, I re-install the source packages into the now-mounted /usr/src dataset and also set the boot environment permanently.
pkg install FreeBSD-src FreeBSD-src-sys
bectl activate 15.0-RELEASE
I do have a fair number of orphaned 14.3 packages left, though:
FreeBSD-dpv-14.3p6 ? orphaned: base
FreeBSD-dpv-dev-14.3p6 ? orphaned: base
FreeBSD-dpv-dev-lib32-14.3p6 ? orphaned: base
FreeBSD-dpv-lib32-14.3p6 ? orphaned: base
FreeBSD-dpv-man-14.3p6 ? orphaned: base
FreeBSD-efi-tools-dev-lib32-14.3p6 ? orphaned: base
FreeBSD-efi-tools-lib32-14.3p6 ? orphaned: base
FreeBSD-ftpd-14.3p6 ? orphaned: base
FreeBSD-ftpd-man-14.3p6 ? orphaned: base
FreeBSD-kernel-generic-mmccam-14.3p6 ? orphaned: base
FreeBSD-liby-dev-14.3p6 ? orphaned: base
FreeBSD-liby-dev-lib32-14.3p6 ? orphaned: base
FreeBSD-openssl-lib-lib32-14.3p6 ? orphaned: base
FreeBSD-openssl-lib-man-14.3p6 ? orphaned: base
FreeBSD-pkg-bootstrap-man-14.3p6 ? orphaned: base
FreeBSD-sendmail-dev-14.3p6 ? orphaned: base
FreeBSD-sendmail-dev-lib32-14.3p6 ? orphaned: base
FreeBSD-sendmail-lib32-14.3p6 ? orphaned: base
FreeBSD-tests-man-14.3p6 ? orphaned: base
FreeBSD-unbound-14.3p6 ? orphaned: base
FreeBSD-unbound-dev-14.3p6 ? orphaned: base
FreeBSD-unbound-dev-lib32-14.3p6 ? orphaned: base
FreeBSD-unbound-lib32-14.3p6 ? orphaned: base
FreeBSD-unbound-man-14.3p6 ? orphaned: base
My open questions (I will update as I find answers) are:
Q: Is 15.0-RELEASE simply missing the MINIMAL kernel and these other orphaned packages?
Q: What am I supposed to do with these orphaned packages? I have no need for the lib32 versions so I think I’m ok getting rid of those, but things like unbound I’m not so sure what happens if they go away. Luckily they still run with the compatibility libraries installed.
Q: Is the right way now to just have a tiny FreeBSD-base.conf with just the enabled: yes setting as per the release notes? Mine looks like the one from the handbook upgrading page referenced above:
FreeBSD-base: {
url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_release_0",
mirror_type: "srv",
signature_type: "fingerprints",
fingerprints: "/usr/share/keys/pkgbase-15",
enabled: yes
}
Q: When I was testing this out, I upgraded to base_latest (15.0-STABLE) and it had zero issues like this. It includes the MINIMAL kernel, does not complain of the signing keys, etc. What makes it different?
A: It seems that with moving the packages for the release to a new pkgbase server, the infrastructure team decided to use a new signing key.