how to do a minor version upgrade of FreeBSD (6.3 and higher)
November 28th, 2013 (as amended)

The instructions below perform a "minor version upgrade" on FreeBSD, and are derived from the handbook page on this topic. A minor version upgrade is from, say, version 8.1 to 8.3. Upgrading from, say, 6.1 to 8.1 would be a "major version upgrade" - this isn't covered here.

Note: these instructions are for FreeBSD 6.3 and higher. To upgrade 6.2 or below, please see upgrading 6.2 and below.

Warning: freebsd-update creates creates a work directory in /var/db/freebsd-update. This can get large (approx 800Mb as of December 2014). Ensure to have at least 1Gb of free space on /var before using freebsd-update. If this is not feasible, it's possible to change the location of the work directory.

  1. install updates to the kernel (this may take some time, and requires a live internet connection):

    1. decide on the release to upgrade to - note the name of the release (eg. "8.3-RELEASE"), as this is needed below
    2. login as root
    3. freebsd-update -r 8.3-RELEASE upgrade

      Note: substitute "8.3-RELEASE" with the name of the release you selected in the first step.

      Note: freebsd-update uses mergemaster. If mergemaster needs manual assistance, you'll end up in vi. This will happen for each file requiring a manual merge. For each conflict in each file (there may be more than one conflict, and/or more than one file), the old and new versions are shown. The lines between the "<<<<<<< current version" line and the line consisting of "=======" are the existing lines in the file which are in conflict; the proposed replacement for these lines is below the ======= line. Delete everything except those lines you wish to keep. Delete the "current version" line, the ======= line, and the ending ">>>>>>> 6.4-RELEASE" line. Ensure to locate and resolve every conflict. Failing to remove the "current version" line and other bits will leave them in the file, which may or may not affect things, depending on the file.

      In the example below, the line "#VersionAddendum FreeBSD-20050903" is in conflict with the line "#VersionAddendum FreeBSD-20061110":

      <<<<<<<  current version
      #VersionAddendum FreeBSD-20050903
      #VersionAddendum FreeBSD-20061110
      >>>>>>> 6.4-RELEASE

      To resolve this conflict, delete everything except the correct line:

      #VersionAddendum FreeBSD-20061110

      Note: freebsd-update also displays another kind of diff, the output looks like this:

      The following changes, which occurred between FreeBSD 8.1-RELEASE and
      FreeBSD 8.3-RELEASE have been merged into /etc/group:
      --- current version
      +++ new version
      @@ -1,6 +1,6 @@
      -# $FreeBSD: src/etc/group,v 2010/06/14 02:09:06 kensmith Exp $
      +# $FreeBSD: src/etc/group,v 2012/03/03 06:15:13 kensmith Exp $

      Lines beginning with "-" are already in the file. Their proposed replacement are the lines beginning with "+". Lines beginning with "@" are some kind of diff data. Lines beginning with " " (space) will be left unchanged.

    4. freebsd-update install

  2. install userland updates:

    1. reboot
    2. login as root
    3. /usr/sbin/freebsd-update install

      Note: if doing a minor version upgrade, recompiling all the ports is usually not necessary, however, if this message appears:

      "Completing this upgrade requires removing old shared object files. Please rebuild all installed 3rd party software (e.g., programs installed from the ports tree) and then run "/usr/sbin/freebsd-update install" again to finish installing updates."

      ...then recompiling the ports is necessary after all. Also, according to the handbook, "After a major version upgrade, all third party software needs to be rebuilt and re-installed". To rebuild all 3rd-party software:

      portmaster -af

  3. update the ports collection (optional):

    1. login as root
    2. portsnap fetch extract
    3. portsnap fetch update

    When done, the upgrade to FreeBSD 8.3 is complete.

    Note: updating the ports collection does NOT recompile existing installations of the ports. Apache, for example, will NOT get automagically upgraded to the latest version by portsnap. The latest version will be downloaded, and placed into /usr/ports - but it will NOT be compiled. To upgrade an existing installation of a port, use portmaster or portupgrade (details here). To upgrade a particular package, use: portupgrade -R packagename