Last Updated: 21 Nov 2020


Author: (external edit)

FreeBSD Stable Upgrade Procedure

This outlines how to upgrade your FreeBSD installation to FreeBSD-STABLE. It isn't designed to replace the manual, but is a quick set of crib-notes on how to get the OS upgraded.

NOTE: If you just want to update to the latest FreeBSD release, the binary upgrade process is probably the way to go. The FreeBSD folks DO NOT recommend tracking the 'STABLE' branch.

Get the Source

  • First, get the latest stable source code using cvsup. To do this, get the stable-supfile out of the examples dir (/usr/share/examples/cvsup/stable-supfile), copy it to /usr/src/, change the server location & whatever else you need following the comments in the file, and do a cvsup: cd /usr/src; cvsup stable-supfile
  • Once you've got the code, read /usr/src/UPDATING. See if it has anything interesting or scary that you might need to pay attention to.
  • Look at the Makefile in /usr/src for anything funny. I've yet to ever see anything, but it never hurts to give the Makefile a quick glance.
  • [OPTIONAL] Setup a custom kernel. Note that I don't usually do this, because GENERIC is fast enough and stable enough for my needs. If you want to:
    • Go into /usr/src/sys/i386/conf
    • Copy GENERIC to SYSTEMNAME (where SYSTEMNAME is the name of your new kernel).
    • Edit this file to remove any drivers/etc that you don't want. Change the name (ident) near the top

Cleanup First

Cleanup any old files:

  • cd /usr/src
  • make clean

Compile Kernel

You have to compile the new -STABLE kernel (and reboot) before compiling the rest of the OS. This is because some userland applications might depend on features in the new kernel, so you might not be able to compile them until you're running on the new kernel.

  • cd /usr/src
  • make buildkernel -j4 KERNCONF=GENERIC (or SYSTEMNAME)
  • make installkernel KERNCONF=GENERIC (or SYSTEMNAME)
  • reboot

Note: building the kernel this way also builds any kernel modules (in /boot/kernel). Normally this is what you want, but if you've got custom modules (updated drivers for a 3Ware RAID card in my case) you'll need to copy those back in.

Compile Userland Apps

  • make buildworld -j4 (this will take a LONG time)
  • mergemaster -p (merge/update any configuration files that it asks you about)
  • make installworld
  • make delete-old
  • make delete-old-libs
  • mergemaster -U -i This is the most manually intensive process. Merge/update/delete any files it asks you about. In general:
    • If it's a file that you know you haven't touched, install the new one.
    • If it's a file you know you have touched, and it is something that is somewhat generic and/or unimportant (e.g. /etc/motd), delete the new one and keep your old copy.
    • If you've touched the file and it is important, then manually merge them.
  • reboot
  • Check /var/log/message for anything funky. Hopefully the system will come up cleanly, but it doesn't hurt to check.

That's it. Test everything, and you're done!


Enter your comment. Wiki syntax is allowed: