Upgrade FreeBSD 12.⋯ to FreeBSD 13

freebsd-12-to-13.md

Preamble

If you want future FreeBSD update and upgrade routines to be simpler: please support the PkgBase initiative. See, for example, https://alpha.pkgbase.live/.

---

Guidance below is for 12.⋯ systems that:

• fall below 12.2-RELEASE-p4 (12.2 patch level 4)
• boot from ZFS (not UFS).

All commands are to be run as root. Beyond step 7 below, aim to run each command in terminal that is away from (or without starting) the desktop environment. Hint:

• Control-Alt-F2 switches to terminal ttyv1
• from there, Alt-F9 returns to the desktop environment.

If you never previously followed a freebsd-update(8) routine, please be prepared:

• to respond appropriately when presented with a colon : or (END) at the command line – with q as the laziest effective response
• for a possible requirement to use vi(1) for command line edition of some files.

For EFI system partition (ESP) boot loader guidance please see, for example:

• https://old.reddit.com/r/freebsd/comments/mq8wnq/freebsdannounce_freebsd_130release_now_available/guky1nd/
• Upgrade FreeBSD with ZFS Boot Environments | 𝚟𝚎𝚛𝚖𝚊𝚍𝚎𝚗 – there's also a more streamlined system upgrade routine, which requires fewer restarts through use of chroot(8) (but does not cover the current peculiarities of helloSystem).

The routine

1. pkg -v
2. if the package management tool is not yet installed, allow it
3. pkg query '%R %o %v' | grep -v -e FreeBSD -e ports-mgmt\/pkg | sort > /var/log/exceptionalpackages.txt && cat /var/log/exceptionalpackages.txt
4. if the query reveals anything (any package that was not installed from a FreeBSD package repository), be aware that the pkg upgrade lines below might not cover what's required for an entirely successful upgrade – be prepared to act upon an on-screen hint to rebuild all installed 3rd party software (e.g., programs installed from the ports tree)
5. du -h /var/cache/pkg && pkg clean -qy && pkg autoremove -qy && du -h /var/cache/pkg
6. bectl create 12.2-RELEASE-p6 && bectl activate 12.2-RELEASE-p6
7. restart the computer
8. /usr/sbin/freebsd-update fetch install
9. freebsd-version -kru
10. observe the mismatch
11. restart the computer
12. /usr/sbin/freebsd-update install
13. – there might be nothing applicable
14. pkg upgrade
15. /usr/sbin/freebsd-update install
16. – there might be nothing applicable
17. restart the computer
18. freebsd-version -kru
19. du -h /var/cache/pkg && pkg clean -qy && pkg autoremove -qy && du -h /var/cache/pkg
20. bectl create 13.0-RELEASE && bectl activate 13.0-RELEASE
21. restart the computer
22. /usr/sbin/freebsd-update upgrade -r 13.0-RELEASE
23. /usr/sbin/freebsd-update install
24. freebsd-version -kru
25. restart the computer
26. freebsd-version -kru
27. /usr/sbin/freebsd-update install
28. freebsd-version -kru
29. pkg upgrade
30. /usr/sbin/freebsd-update install
31. sed -i '' '/opensolaris/d' /boot/loader.conf && cat /boot/loader.conf
32. restart the computer.

Background

Some of the logic above is drawn from cutting edge Chapter 24 of the FreeBSD Handbook.

freebsd-version(1) lines are optional:

• for a person who has never previously used freebsd-update, observing the output from freebsd-version might help to understand the state of things at various stages within routines such as this.

Package cleaning and autoremoval lines are optional:

• intended to help minimise the sizes of past boot environments that might be rarely or never required.

ttyv1 is recommended because (amongst other things) pkg upgrade whilst signed in to a packaged desktop environment might adversely affect the running environment. If you prefer to run the commands in a terminal in a desktop environment, proceed with caution – beware of any running program prematurely loading an upgraded component; refrain from running any additional program; and so on.

The interim boot environment with 12.2-RELEASE-p6 (or greater) is:

• primarily for a fix to freebsd-update

– if you skip the relevant steps, and if you subsequently find a problem with scripted or manual use of passwd(1) with 12.2-RELEASE-p3 (or less), you may:

• apply the two-line workaround in section IV of [FreeBSD-Announce] FreeBSD Errata Notice FreeBSD-EN-21:08.freebsd-update.

Hint: possible symptoms of a passwd-related problem include pkg install falkon failing at or around the mysql57-server stage.

Use of vi is avoidable:

• permanently set EDITOR and VISUAL variables to /usr/local/bin/nano

– I have a GitHub gist for this, but it's not public.

Exceptions for users of helloSystem

You must:

• pkg lock hello

If not already locked, this is to safeguard essential helloSystem files that are associated with the non-ported hello package, which has a nonconformist origin and a name that conflicts with a previously packaged port (misc/hello, unrelated to helloSystem).

Without the lock, pkg upgrade will replace helloSystem's ambiguous hello < 2.10_1 with properly-defined misc/hello 2.10_1. Replacement is proper – given the version numbers – however the consequences are unwanted. Related:

• https://github.com/helloSystem/ISO/commits/e5324c0e3fe430407fbe94083f4915f0a778c9fa/overlays/uzip/hello/manifest (origins of the problem)
• helloSystem/hello#67 (comment) ▶ https://lists.freebsd.org/pipermail/freebsd-ports/2021-March/120439.html sought advice from the freebsd-ports list.

In addition, if you find helloSystem preventing normal use of pkg(8), you should:

• mv /usr/sbin/pkg.real /usr/sbin/pkg

– for the non-standard pkg to be replaced by the real (FreeBSD-provided) package management tool.

Will you update this excellent guide for the release version? Or does the same apply?

Thank you – I wrote 13.0-RELEASE into the file a few days ago (see Revisions).