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

A question:

uclcmd usage after creating /usr/local/etc/pkg/repos/FreeBSD.conf

• https://lists.freebsd.org/archives/freebsd-current/2025-September/008892.html | https://mail-archive.freebsd.org/cgi/mid.cgi?b231cd1b-1fb7-48a9-a471-1fc78e4ff5d6

… (I do want to use uclcmd with a file that is initially empty.)

Usage (copy): https://pastebin.com/raw/r8gNNDQ5

sysctl vm.pageout_oom_seq=120

The use case for an increased value such as 120 should be documented.

With the default – 12 – memory-related killings may occur. In Reddit:

• pkg: killed: failed to reclaim memory : r/freebsd

The pinned comment refers to a documentation bug report (closed) and subsequent discussion.

Dry runs of a major upgrade from RELEASE to CURRENT, preceded by a fetch of packages:

env ABI=FreeBSD:16:amd64 pkg upgrade -Fqy

root@freebsd-conf:~ # env ABI=FreeBSD:16:amd64 pkg upgrade -Fqy
pkg: Setting ABI requires setting OSVERSION, guessing the OSVERSION as: 1600000
pkg: Warning: Major OS version upgrade detected.  Running "pkg bootstrap -f" recommended
pkg: Cannot solve problem using SAT solver
root@freebsd-conf:~ # env ABI=FreeBSD:16:amd64 pkg-static upgrade -fnU --repository FreeBSD | grep 'to be removed'
pkg-static: Setting ABI requires setting OSVERSION, guessing the OSVERSION as: 1600000
pkg-static: Warning: Major OS version upgrade detected.  Running "pkg bootstrap -f" recommended
root@freebsd-conf:~ # env ABI=FreeBSD:16:amd64 pkg-static upgrade -fnU --repository FreeBSD-base | grep 'to be removed'
pkg-static: Setting ABI requires setting OSVERSION, guessing the OSVERSION as: 1600000
pkg-static: Warning: Major OS version upgrade detected.  Running "pkg bootstrap -f" recommended
Number of packages to be removed: 904
root@freebsd-conf:~ # env ABI=FreeBSD:16:amd64 pkg-static upgrade -fnU | grep 'to be removed'pkg-static: Setting ABI requires setting OSVERSION, guessing the OSVERSION as: 1600000
pkg-static: Warning: Major OS version upgrade detected.  Running "pkg bootstrap -f" recommended
Number of packages to be removed: 6
root@freebsd-conf:~ # pkg lock -l
Currently locked packages:
pkg-2.3.1
root@freebsd-conf:~ # file /usr/sbin/pkg /usr/local/bin/konsole
/usr/sbin/pkg:          ELF 64-bit LSB pie executable, x86-64, version 1 (FreeBSD), dynamically linked, interpreter /libexec/ld-elf.so.1, for FreeBSD 14.3, FreeBSD-style, stripped
/usr/local/bin/konsole: ELF 64-bit LSB executable, x86-64, version 1 (FreeBSD), dynamically linked, interpreter /libexec/ld-elf.so.1, for FreeBSD 14.2, FreeBSD-style, stripped
root@freebsd-conf:~ # freebsd-version -kru ; uname -mvKU
16.0-CURRENT
16.0-CURRENT
14.3-RELEASE-p3
FreeBSD 16.0-CURRENT main-n280598-57d5a8feda3f GENERIC amd64 1600000 1403000
root@freebsd-conf:~ # pkg repos -el | sort -f
FreeBSD
FreeBSD-base
FreeBSD-kmods
root@freebsd-conf:~ # pkg repos -e | grep -B 1 url
FreeBSD: { 
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/latest",
--
FreeBSD-kmods: { 
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/kmods_latest",
--
FreeBSD-base: { 
    url             : "pkg+https://pkg.FreeBSD.org/FreeBSD:14:amd64/base_latest",
root@freebsd-conf:~ # 

• 0 (zero) removals with --repository FreeBSD (FreeBSD-ports)
• 906 removals with --repository FreeBSD-base
• 6 removals without specifying a repository.

A non-dry run of the third option does fetch additional packages.

The fetch-after-fetch effect was noted a few days ago:

• freebsd/pkg#2414 (comment)
• freebsd/pkg#2414 (comment)

Now, it's nice that I can avoid hundreds of unwanted removals by not specifying a repository.

Previously, with a major upgrade to 15.0-ALPHA3, it was necessary to specify the FreeBSD (ports) repository for a disorderly upgrade (port packages before userland).

Now, it's nice that I can avoid hundreds of unwanted removals by not specifying a repository.

False!

See https://gist.github.com/grahamperrin/cd67326a3339ca5278cf48d183188e25?permalink_comment_id=5773482#gistcomment-5773482

I completed a major upgrade from 14.3-RELEASE-p3 to (unannounced) 15.0-ALPHA4:

• with pkg 2.2.2 locked prior to the upgrade
• without an sqlite error 👍
• in a single step, without specifying a repo (not recommended, but I'm pleased that it worked).

Around a week later, sqlite-related issue 2522 recurred – not involving pkgbase, as far as I can tell.

The issue has been reproduced and diagnosed.

Mentions and captures:

• FreeBSD: pkgbase: major upgrades : r/freebsd (2025-09-20)
• https://mastodon.bsd.cafe/@grahamperrin/115234812588477415 (2025-09-20)
• https://mail-archive.freebsd.org/cgi/mid.cgi?edf544d1-a7d7-4720-b060-4c0375941ee1 | https://lists.freebsd.org/archives/freebsd-pkgbase/2025-October/000991.html
• http://archive.today/2025.10.09-234041/https://gist.github.com/grahamperrin/a58edbb8587af513a154ac01d922f611
• https://web.archive.org/web/20251010225031/https://gist.github.com/grahamperrin/a58edbb8587af513a154ac01d922f611
• https://mastodon.bsd.cafe/@grahamperrin/115436754469610675 (followers only)

/etc/pkg/FreeBSD.conf in 15.0-RELEASE:

#
# To disable a repository, instead of modifying or removing this file,
# create a /usr/local/etc/pkg/repos/FreeBSD.conf file, e.g.:
#
#   mkdir -p /usr/local/etc/pkg/repos
#   echo "FreeBSD-ports: { enabled: no }" > /usr/local/etc/pkg/repos/FreeBSD.conf
#   echo "FreeBSD-ports-kmods: { enabled: no }" >> /usr/local/etc/pkg/repos/FreeBSD.conf
#
# Note that the FreeBSD-base repository is disabled by default.
#

FreeBSD-ports: {
  url: "pkg+https://pkg.FreeBSD.org/${ABI}/quarterly",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}
FreeBSD-ports-kmods: {
  url: "pkg+https://pkg.FreeBSD.org/${ABI}/kmods_quarterly_${VERSION_MINOR}",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkg",
  enabled: yes
}
FreeBSD-base: {
  url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_release_${VERSION_MINOR}",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkgbase-${VERSION_MAJOR}",
  enabled: no
}

The FreeBSD-base section:

FreeBSD-base: {
  url: "pkg+https://pkg.FreeBSD.org/${ABI}/base_release_${VERSION_MINOR}",
  mirror_type: "srv",
  signature_type: "fingerprints",
  fingerprints: "/usr/share/keys/pkgbase-${VERSION_MAJOR}",
  enabled: no
}

UCL, and lowercase for the domain, although this may result in a merge conflict:

FreeBSD-base {
    url = "pkg+https://pkg.freebsd.org/${ABI}/base_release_${VERSION_MINOR}";
    mirror_type = "srv";
    signature_type = "fingerprints";
    fingerprints = "/usr/share/keys/pkgbase-${VERSION_MAJOR}";
    enabled = no;
}

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.