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.

Warning: pay extra attention if updating sshd_config remotely, as if it's done incorrectly, SSH may fail to start on the next reboot, and lock you out half-way through the upgrade.

  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.

      If you're satisfied with the changes that will be made, press Y to continue. Patches will then be downloaded and applied, which will take some time.

      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

      Hint: use vi's search function to find every conflict (eg. use the vi syntax "/=====" and then simply "/" to find next)

      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 (these are NOT inserted in the output file). Lines beginning with " " (space) will be left unchanged.

      Note that the output of this diff can scroll off the top of the screen, ensure you've seen ALL the proposed changes before accepting them. If the proposed changes seem reasonable, press Y when prompted.

      Once all changes have been merged, several lists of files that will be changed are shown. Press Q to exit these listings.

    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 (docs: manpage):

      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