Recover an interrupted freebsd-update run

Synopsis #

freebsd-update separates fetching, merging, and installation into saved phases. During a release upgrade, repeated freebsd-update install invocations intentionally perform different work around a reboot and third-party package upgrade. An interruption does not therefore imply that the process must start again.

Do not remove /var/db/freebsd-update, change the target release, or start another update job while diagnosing the saved transaction. Those actions can destroy the state needed to continue safely.

This procedure applies to a distribution-set base system. A pkgbase host is maintained with pkg; identify the method with the update and upgrade decision guide .

Record the current state #

Capture the exact error and the three installed version values:

$ freebsd-version -kru
$ uname -a
$ df -h / /var
$ mount

Check for another active process before starting a replacement invocation:

$ pgrep -laf freebsd-update

If an active process is still fetching, merging, or installing, investigate that process rather than running a concurrent copy. An abandoned terminal does not necessarily mean the process stopped.

Interpret the phase #

Once retrieval and configuration merging have completed, the saved upgrade state makes the next install invocation advance to the appropriate phase. Do not repeat upgrade -r merely because the shell session ended after that preparation succeeded.

Continue a saved transaction #

Confirm that no other update process is running and that storage is writable with adequate free space. If the preceding fetch or upgrade preparation completed, continue with:

# freebsd-update install

If retrieval was interrupted before preparing an installation, repeat that retrieval command first. Keep the work directory so verified downloads can be reused. An install message saying no updates are available after an incomplete fetch means that no installation is ready; it does not prove that the host is up to date.

Read the output of each completed phase. If a kernel was installed but has not been booted, compare the running and installed kernel:

$ freebsd-version -kr

When they differ at the kernel phase, reboot before installing userland:

# shutdown -r now

After booting, record the versions again and continue with freebsd-update install. During a major release upgrade, complete the package ABI step at the point requested by the official release instructions, then make the final install call to remove obsolete base-system files.

Diagnose a repeated failure #

If the same phase fails again, preserve its full output and check:

• free space in /var and the update work directory;
• whether /, /boot, or /var became read-only;
• DNS and HTTPS reachability when the failure occurs during fetch;
• local modifications named in a failed configuration merge;
• a custom kernel or nondefault Components setting;
• the target release’s errata for a known upgrade issue.

Do not respond to a checksum, signature, or metadata error by disabling verification. Do not delete a configuration file simply to force a merge. Correct the underlying storage, network, or merge failure and rerun the same saved phase.

A fetch can also be refused because an automated session has no terminal. For a deliberate scripted fetch, the documented --not-running-from-cron option permits freebsd-update --not-running-from-cron fetch without a TTY. Use the separate cron subcommand for scheduled checks.

Roll back only the most recent installed update #

For a patch update that installed successfully but caused a regression, freebsd-update rollback uninstalls the most recently installed update:

# freebsd-update rollback

Review the proposed changes and reboot when the kernel or modules changed. This rollback is not a general undo mechanism for every phase of a release upgrade, and the configured backup kernel is managed separately. A ZFS-root system with a known pre-change boot environment can instead use the narrower boot-environment recovery procedure .

Primary references #

• FreeBSD Handbook: binary updates and release upgrades
• FreeBSD 15.1-RELEASE upgrading instructions
• freebsd-update(8)
• freebsd-update.conf(5)
• freebsd-version(1)