FreeBSD pkgbase: Managing the Operating System as Signed Packages

FreeBSD pkgbase distributes the operating system’s base components as packages managed by pkg. It applies package-manager mechanics to the kernel, userland, and related base sets; it is not merely another name for installing third-party packages from the Ports Collection. The distinction changes how a host is upgraded, how repositories are selected, and how operators recover from a partially completed transition.

The Handbook currently describes package-based installation and upgrading as a tech preview for FreeBSD 15, while traditional distribution sets remain the established path. FreeBSD 14 package-base use is described as experimental. Treat those status statements as release-specific and re-read the Handbook for the exact release before adopting pkgbase on a production machine.

Separate base packages from application packages

The base system has its own repository identity, release branches, signing configuration, and ABI expectations. Third-party packages may still be managed by pkg, but that does not make the base repository interchangeable with the ordinary package repository. A system can have both sources configured, and an upgrade plan must be reviewed with that separation in mind.

For a release-aligned repository, the Handbook’s example uses the FreeBSD-base repository, fingerprint-based signatures, and a release-specific URL. Do not copy a branch name from another machine: latest, weekly, and release branches have different update cadence and compatibility intent. Pin the repository to the intended release family and verify the package plan before accepting it.

Conversion is a migration, not a one-line update

Converting an existing host can relocate or replace files that previously belonged to distribution sets. The current Handbook recommends the Foundation-sponsored pkgbasify tool and warns that conversion can require several GiB of additional free space. Make a tested backup first. On a ZFS-root host, create and verify a boot environment; on other layouts, take a recoverable system backup and confirm console access.

Before any conversion or upgrade, record the release, architecture, repository configuration, boot environment, package inventory, free space, and service dependencies. Stage the migration on a disposable clone where possible. An SSH server restart during conversion can terminate the session that launched it, so arrange out-of-band access and do not treat an open terminal as a rollback plan.

For an already converted host, the high-level repository transaction resembles this release-specific workflow:

# Inspect the configured base repository and its signing policy first.
pkg -vv

# Refresh only the intended base-system repository.
pkg update -r FreeBSD-base

# Review every proposed base package change before accepting it.
pkg upgrade -r FreeBSD-base

The commands above are not a conversion recipe, a major-upgrade checklist, or a guarantee that a given repository URL is right for the host. Stop if the repository is unsigned, points at the wrong branch, proposes unexpected removals, or does not match the installed release. Preserve the package manager’s transaction output for the change record.

Keep rollback and third-party ABI work explicit

After upgrading the base system, third-party packages may need to be updated to match the new ABI. A successful base transaction is not proof that every service works: inspect package changes, reboot into the intended boot environment, check service health, and verify kernel and userland release identifiers. Retain the old boot environment until those checks pass.

Do not run freebsd-update and a pkgbase base upgrade as competing authorities over the same installed files. The Handbook describes the intended relationship between the tools as evolving; follow the procedure documented for the exact supported release rather than assuming that tools can be mixed in any order. Likewise, do not use a generic pkg upgrade across all repositories as a substitute for first reviewing the base-only plan.

Production acceptance checklist

Before adopting the model, verify release support, repository signatures, disk headroom, package origin, boot-environment recovery, console access, expected service restarts, and ABI follow-up. After the transaction, compare the resulting package inventory with the approved plan, reboot, test network and storage access, confirm critical daemons, and verify that rollback still works. Keep the repository configuration and transaction record with the system’s operating documentation.

pkgbase can make base-system updates fit more naturally into package workflows, but its safety depends on release-matched repositories and disciplined recovery planning. Treat it as a distinct operating-system lifecycle choice, not as an incidental pkg setting.

Related:

Sources:

Separate base packages from application packages

Conversion is a migration, not a one-line update

Keep rollback and third-party ABI work explicit

Production acceptance checklist

Comments