freebsd-update and the upgrade path

freebsd 15 / published / guide #51 / ≈ 5 min read

freebsd-update is the tool that fetches and applies patches to the FreeBSD base system. It does two jobs: routine security patches (boring, run every week) and major version upgrades (12 → 13, 13 → 14, …) which need more care. This guide covers both paths, the safe way.

Reminder of the FreeBSD split:

  • Base system — kernel + libc + core utilities. Updated by freebsd-update.
  • Packages — everything else. Updated by pkg.

The two are independent. A base-system upgrade does not touch your packages; you upgrade them yourself with pkg.

The routine: weekly security patches

sudo freebsd-update fetch
sudo freebsd-update install

Two commands. fetch downloads available patches; install applies them. If a kernel patch was applied, reboot:

sudo shutdown -r now

You can run freebsd-update fetch from cron to keep things ready — just install on your own schedule:

sudo crontab -e
0 3 * * * freebsd-update cron     # special "quiet" mode for cron use

The cron subcommand fetches with random delay and only emails if there's something new.

What it actually patches

Run without arguments:

sudo freebsd-update fetch
sudo freebsd-update install

This installs any pending security advisories (SA-XX:NN) and errata notices (EN-XX:NN) — only fixes, never feature changes. Safe to do regularly.

The major upgrade — what makes it different

Going from 14.x to 15.0 is a bigger event. The kernel changes ABI; some old programs may stop running; you'll re-link every package on top.

The high-level routine:

  1. Make a boot environment — your safety net.
  2. Update to the latest patch level of the current release.
  3. Run freebsd-update upgrade to fetch the new release.
  4. Install the new kernel.
  5. Reboot.
  6. Install the new userland.
  7. Upgrade all packages with pkg.
  8. Reboot once more, run one final freebsd-update install.

Sounds like a lot. It's not — but the order matters.

Step 0: take a boot environment

On a ZFS install, this is one command and one second:

sudo bectl create pre-15-upgrade

See ZFS boot environments for the full guide. If anything goes wrong, you can boot back to pre-15-upgrade from the loader menu.

On UFS, you don't have BEs — make sure you have backups before going on.

Step 1: patch the current release fully

sudo freebsd-update fetch
sudo freebsd-update install
sudo pkg update && sudo pkg upgrade
sudo shutdown -r now

Start the upgrade from a fully-patched current release. Anything else makes the diffs harder to merge.

Step 2: fetch the new release

sudo freebsd-update upgrade -r 15.0-RELEASE

It downloads the differences and walks you through three-way merges of any /etc files you've modified that also changed upstream. Each merge offers your version, the new version, or a merged result. Take your time — these are the questions that bite people.

If you're unsure on a merge, pick the upstream default and re-apply your changes manually afterwards. Easier than getting a half-merged config.

Step 3: install the new kernel

sudo freebsd-update install
sudo shutdown -r now

You now boot the new kernel with the old userland. This sounds weird; it's the FreeBSD documented order. On reboot the system comes up at 15.0 (kernel) running 14.x userland.

Step 4: install the new userland

sudo freebsd-update install

That replaces every base-system binary with the 15.0 versions.

Step 5: rebuild / reinstall every package

Packages built for 14.x will mostly still run on a 15.x system thanks to compatibility libs, but anything that links against the new ABI breaks until rebuilt. The safe thing is to upgrade them all at once:

sudo pkg update
sudo pkg upgrade -f

The -f forces a reinstall of every package, even ones with the same version number, so they link against the new libs.

Step 6: one last freebsd-update install

sudo freebsd-update install

Cleans up any final state that was waiting on packages being upgraded. Sometimes no-ops; sometimes does one last little step.

Step 7: reboot one more time

sudo shutdown -r now

You're on 15.0, top to bottom.

When something goes wrong

  • System won't boot after step 3. From the loader menu (Space at boot), pick "Boot environments" → pre-15-upgrade. You're back on the working old system. Investigate from there.
  • A package crashes after step 5. Try a forced reinstall of just that package: sudo pkg install -f <name>. If still bad, search the FreeBSD mailing lists / forums for known issues with that port + the new release.
  • A custom binary you built yourself stops working. Rebuild it. Anything compiled for the old ABI needs a fresh build.
  • You bailed out partway and want to undo. sudo freebsd-update rollback reverses the last install step. Or bectl activate pre-15-upgrade + reboot.

How long does it take?

Most of the elapsed time is the package rebuild (step 5), which depends on how much you have installed and how fast your hardware is. A typical "small server with a dozen packages" upgrade is well under an hour, including the boot reboot dance. A "kitchen-sink desktop" can take a few hours.

Stable point releases vs. -CURRENT

freebsd-update only works for RELEASE versions (12.4-RELEASE, 13.3-RELEASE, 14.3-RELEASE, …). If you run -STABLE or -CURRENT, you build from source with src tree updates and make buildworld/buildkernel — different workflow, not covered here.

A safer schedule

For a server you care about:

  1. Weekly: freebsd-update fetch && freebsd-update install && pkg upgrade. Reboot if a kernel patch landed.
  2. Wait for the .1 point release (e.g. 15.1) before upgrading to the new major version. Many edge-case bugs are fixed in the first point release.
  3. Always take a BE first. Always.

← back to index