Posted by: jasonk2600 | December 10, 2009

Upgrading FreeBSD Major Releases from Source


The following will explain the required steps in order to upgrade a functioning FreeBSD system to a newer major release.  For example, upgrading a system running FreeBSD 7.x to FreeBSD 8.x.  There are two different methods of upgrading to a newer major release; binary-based upgrading and source-based upgrading.  Upgrading will be covered in this document.  Although upgrading via source can consume quite a bit more time, it produces a more stable system with better performance.  Be sure to backup your entire system BEFORE proceeding!

Synchronizing The Source

If you have not already done so, install the CVSup utility from the ports collection.

# cd /usr/ports/net/cvsup-without-gui
# make install clean
# rehash
# mkdir /root/cvsup
# cp /usr/share/examples/cvsup/stable-supfile /root/cvsup/stable-supfile


Modify the stable-supfile to utilize a CVSup server near you and set which source tree to synchronize to.  In the example below, CVSup will use a CVSup server in the United States and synchronize to the FreeBSD 8-STABLE source code branch.

*default release=cvs tag=RELENG_8


Run CVSup with the newly configured supfile to synchronize your local source tree (/usr/src).

# cvsup –g –L 2 /root/cvsup/stable-supfile
   [ ..Lots of Output..]

Compiling The Source

This phase of the upgrade process can take a considerable amount of time, depending upon the speed of your system.  The first step is to compile the new compiler, related tools, and the rest of the userland files.

# cd /usr/src
# make buildworld
   [ ..Lots of Output.. ]


Next, build and install the new system kernel from the new source code.  In this example, we’ll be using the included GENERIC kernel configuration file.  You may need to customize the GENERIC kernel configuration (e.g. to enable the PF firewall), the GENERIC kernel configuration is stored in /usr/src/sys/i386/conf/GENERIC.

# cd /usr/src
# make buildkernel KERNCONF=GENERIC
   [ ..Lots of Output.. ]
# make installkernel KERNCONF=GENERIC
   [ ..Lots of Output.. ]

Upgrading The System

After the new kernel has been installed, reboot the system into single user mode by selecting option ‘4’ from the FreeBSD boot menu.

# shutdown –r now


Once the system has finished booting up into single user mode, mount the file system volumes.

# adjkerntz –i
# swapon –a
# mount –t ufs –a


Run the mergemaster utility to update some initial configuration files to prepare for the new userland files to be installed.

# cd /usr/src
# mergemaster –p


Install the new userland files and run mergemaster again to merge the new configuration files with your existing configuration files.  Take special care during this phase and review each of the changes the will be made to your existing configuration files.  Take notes of configuration files that may need to be changed after the installing the new ones.

# cd /usr/src
# make installworld
   [ ..Lots of Output.. ]
# mergemaster


Be sure to review /usr/src/UPDATING for any specialized steps that may be required to finalize the upgrade process!

That’s all there is to it.  Fully reboot the system to load the new kernel and userland files.

# cd /
# shutdown –r now


Once the system has successfully booted with the new kernel and userland files in place it is advisable to recompile any applications that were installed from the ports collection.  Skipping this step may introduce instability and errors on the system due to the fact that some of the applications from the ports collection rely on userland libraries and other files that have just been upgraded.  The following example uses the portupgrade utility from the ports collection (/usr/ports/ports-mgmt/portupgrade) to accomplish this.  NOTE: Depending upon the various speed of the hardware components used in your system the following process may take an extended amount of time.

# portupgrade -afv
   [ ....LOTS of Output.... ]


Once the port upgrade process has finished, reboot the system once more. Finally, enjoy your freshly optimized and upgraded FreeBSD system.






  1. no need to install/use cvsup
    The base system has a utility called ‘csup’
    just replace your cvsup command with csup and enjoy 🙂

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


%d bloggers like this: