FreeBSD: pkgbase: major upgrades

pkgbase-major-upgrade.md

FreeBSD: pkgbase: major upgrades

A rough guide, for alpha testing on AMD64:

• tested with FreeBSD 15.0-ALPHA2 and ALPHA3
• things might be less rough with ALPHA4, with or without the next release of ports-mgmt/pkg.

Not intended to be comprehensive.

Preamble

It's conventional to upgrade the userland part of base before upgrading non-base packages.

The numbered steps below break from convention. The disorderly approach is a workaround to pkg issue #2414. Proceed with caution.

Also, please note:

• FreeBSD bug 289097 affecting /root/.cshrc and /root/.profile – fixed (cherry-pick, 2025-10-01)
• pkg solver is looking at too many packages · Issue #2520 · freebsd/pkg – this might be an underlying cause of issue 2414 above
• BACKUP_LIBRARIES improvements · Issue #2501 · freebsd/pkg
• pkg: sqlite error while executing BEGIN IMMEDIATE TRANSACTION in file pkgdb.c:1206: cannot start a transaction within a transaction · Issue #2522 · freebsd/pkg – reportedly fixed in pkg 2.4.0
• libpkg: Support system triggers · freebsd/pkg@7831a19 (2025-09-18) – version 2.3.1 of pkg does not include this base-related enhancement
• if you had a minimal installation of the OS prior to upgrade, you might want to install FreeBSD-bsdconfig, FreeBSD-csh, and FreeBSD-ee – or the meta package for their set(s) – after the upgrade
• Desktop environments: FreeBSD Project-provided packages in the ports collection
• last but not least, freebsd-update and pkgbase – discussion, an outcome of which should be a tool that frees us from the complexity below.

14.3-RELEASE-p3 to 15.0-ALPHA3

1. su -
2. pkg install devel/uclcmd
3. /bin/tcsh
4. pkg prime-origins | sort -u > /var/tmp/pkg-prime-origins.txt
5. /usr/local/etc/periodic/daily/411.pkg-backup
6. pkg upgrade
7. uclcmd set --file /usr/local/etc/pkg/repos/FreeBSD-base.conf FreeBSD-base.url 'pkg+https://pkg.freebsd.org/${ABI}/base_latest'
8. pkg -v
9. note the version
10. pkg lock -y pkg
11. touch /usr/local/etc/pkg/repos/FreeBSD.conf
12. cat /usr/local/etc/pkg/repos/FreeBSD.conf
13. if the file is empty, run an echo command
14. echo "FreeBSD {url = example} FreeBSD-kmods {url = example}" > /usr/local/etc/pkg/repos/FreeBSD.conf
15. uclcmd set --file /usr/local/etc/pkg/repos/FreeBSD.conf FreeBSD.url 'pkg+https://pkg.freebsd.org/${ABI}/latest'
16. uclcmd set --file /usr/local/etc/pkg/repos/FreeBSD.conf FreeBSD-kmods.url 'pkg+https://pkg.freebsd.org/${ABI}/kmods_latest'
17. env ABI=FreeBSD:15:amd64 pkg update -f
18. ignore all on-screen suggestions to run pkg bootstrap -f
19. sysctl vm.pageout_oom_seq=120
20. env ABI=FreeBSD:15:amd64 pkg upgrade --fetch-only --yes
21. conflicts may be observed as a result of the fetch, another iteration (run of the command) may be required
22. bectl create fourteen-fifteen-ready
23. env ABI=FreeBSD:15:amd64 pkg upgrade -U FreeBSD-kernel-generic
24. history -S
25. exit
26. shutdown -r now
27. login as root at ttyv1
28. /bin/tcsh
29. service cron stop
30. /usr/local/etc/periodic/daily/411.pkg-backup
31. sysctl vm.pageout_oom_seq=120
32. env ABI=FreeBSD:15:amd64 pkg-static upgrade -fU --repository FreeBSD
33. env ABI=FreeBSD:15:amd64 pkg-static upgrade
34. if the upgrades were successful, history -S then exit and shutdown -r now
35. ee /usr/local/etc/pkg/repos/FreeBSD.conf
36. modernise the repository names – FreeBSD-ports and FreeBSD-ports-kmods
37. pkg install -nU -r FreeBSD-base --glob 'FreeBSD-set-*'
38. decide whether you want any base meta package (for a FreeBSD Project-defined set of packages)
39. pkg install -nU -r FreeBSD-base --glob 'FreeBSD-*'
40. decide whether you want any additional base package
41. when you're certain that bootstrap will not result in a downgrade, pkg-static unlock -y pkg && pkg bootstrap -fy

Experimenting with https://www.freebsd.org/releases/15.0R/relnotes/#upgrade-rc (intended for release candidates, not major), do not run this command before a major upgrade:

pkg add -f https://pkg.freebsd.org/FreeBSD:15:$(uname -p)/base_release_0/FreeBSD-pkg-bootstrap-15.0.pkg

The forced installation breaks pkg:

root@pkg-issue-2414:/etc/pkg # pkg add -f https://pkg.freebsd.org/FreeBSD:15:$(uname -p)/base_release_0/FreeBSD-pkg-bootstrap-15.0.pkg
Illegal variable name.
root@pkg-issue-2414:/etc/pkg # sh
# pkg add -f https://pkg.freebsd.org/FreeBSD:15:$(uname -p)/base_release_0/FreeBSD-pkg-bootstrap-15.0.pkg
Fetching FreeBSD-pkg-bootstrap-15.0.pkg: 100%  153 KiB 156.7kB/s    00:01    
Installing FreeBSD-pkg-bootstrap-15.0...
pkg: wrong architecture: FreeBSD:15:amd64 instead of FreeBSD:14:amd64
Newer FreeBSD version for package FreeBSD-pkg-bootstrap:
To ignore this error set IGNORE_OSVERSION=yes
- package: 1500068
- running userland: 1403000
Ignore the mismatch and continue? [y/N]: y
package FreeBSD-pkg-bootstrap is already installed, forced install
pkg: FreeBSD-pkg-bootstrap-15.0 conflicts with FreeBSD-pkg-bootstrap-man-14.3p3 (installs files into the same place).  Problematic file: /usr/share/man/man7/pkg.7.gz ignored by forced mode
Extracting FreeBSD-pkg-bootstrap-15.0: 100%
# pkg iinfo bootstrap
ld-elf.so.1: Shared object "libcrypto.so.35" not found, required by "pkg"
# 

The second of the warnings under https://docs.freebsd.org/en/books/handbook/cutting-edge/#_preparations is misplaced:

• /mnt/upgrade does not yet exist.