Synopsis #
Pkgbase manages the kernel and base userland through pkg. It is a technology preview in FreeBSD 15. Use a disposable installation or a restorable copy for a first conversion; conversion can leave an unbootable system if it fails.
This procedure uses the FreeBSD Foundation’s pkgbasify helper. It converts a traditional installation; it is not needed if base files are already registered as packages.
Check the starting point #
Have a working console, installation media, and a backup stored outside this system. A ZFS boot environment helps with rollback but does not replace that backup.
$ freebsd-version -kru
# pkg bootstrap
$ pkg which /usr/bin/uname
$ df -h / /usr /var
# pkg repositories
If pkg which reports a FreeBSD-runtime package, the system already uses pkgbase. Follow base-system maintenance
instead.
Keep at least 5 GiB free for conversion, including space on the filesystems that hold base files. Read the helper’s current instructions and known problems
before proceeding. Check separate datasets mounted over base directories, especially a read-only /var/empty or a separate /root, against those known problems.
Run the conversion #
As root, download and inspect the helper before running it:
# fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.lua
# less pkgbasify.lua
# chmod +x pkgbasify.lua
# ./pkgbasify.lua
Accept the backup boot-environment prompt on a ZFS system. The helper selects the release repository and package sets for the installed components, registers base packages, and reinstalls their files. It can merge configuration files and restart SSH, so retain console access until verification is complete.
If conversion stops with an error, read that error before doing anything else. Do not reboot or repeatedly force installation while the system is only partly converted. Follow the helper’s recovery instructions for the actual failure.
Check configuration and reboot #
Confirm the expected users and groups are present and that administrative access still works. Review /etc/ssh/sshd_config and unresolved configuration merges:
# find /etc -name '*.pkgnew' -print
# sshd -t
# pkg which /usr/bin/uname
# pkg info -x '^FreeBSD-'
Resolve any .pkgnew files before rebooting. Test a new administrative login while the original console remains open, then reboot:
# shutdown -r now
After boot, check the running kernel, installed userland, network, and required services. Use pkgbase maintenance
for later base updates; do not continue using freebsd-update on the converted installation.