Upgrading from 6.2 to 7.0

These instructions are for upgrading from FreeBSD 6.2-RELEASE to 7.0-RELEASE. Note that if you are upgrading from 5.x or 6.x, there is an important step noted here that you must follow if you have any kernel modules loaded. You will also have to follow the step listed here if you are upgrading from 6.0 or from 5.x. You cannot upgrade to 7.0 directly from a FreeBSD version older than 5.3.

While it would always be a possibility to reformat and install FreeBSD 6.2, there's no reason not to take advantage of FreeBSD's upgrade capabilities. Before we even begin, BACK UP YOUR DATA. There's no way to stress this enough. Whatever time you lose in being cautious is more than saved for that one time when you do need the backup. I would at least backup your home directory, and all of /etc and /usr/local/etc before continuing. This is pretty easy to do if you have a CD-RW or DVD-RW drive. You'll probably want to use a graphical CD-burning program such as K3B, featured in our section on CD Burning, but you could also give command-line burning a whirl.

Now that you've backed up your relevant data, we can continue. As always, su to root. The first thing you want to do is edit /etc/make.conf and add the following lines if they're not there already:

SUP_UPDATE=yes
SUP=/usr/local/bin/cvsup
SUPFLAGS=-g -L 2
SUPHOST= cvsup4.FreeBSD.org
SUPFILE=/root/standard-supfile
KERNCONF=NEWKER

In the last line, NEWKER refers to the name I gave my custom kernel. See our section on building a custom kernel for more details. If you're running a GENERIC kernel (i.e. you didn't bother to build a custom kernel), delete this last line. Obviously, if you created a custom kernel and labeled it something other than NEWKER, you'll want to refer to the name you gave your kernel. (For example, KERNCONF=CUSTOM).

SUPHOST (4th line from the bottom) refers to the cvsup mirror you wish to target. It can be cvsup.FreeBSD.org through cvsup9.FreeBSD.org. Choose whichever one you like (probably whichever is the fastest for you).

NOTE: there are some fairly significant changes to the FreeBSD kernel between 6.x and 7.x, and unless you know what you're doing you would probably be best off leaving out the line specifying a custom kernel and just building a GENERIC kernel. If you choose to upgrade with a custom kernel, see some important notes below on that subject.

Now that you've done that, we'll setup our supfile.

cp /usr/share/examples/cvsup/standard-supfile /root/
vi /root/standard-supfile

You only need to edit two lines, *default host, which you'll want to make refer to one of the aforementioned cvsup mirrors, and *default release, which you'll want to change to RELENG_7_0. You could also specify RELENG_7 if you want to track the 7.x STABLE branch (more actively developed than the RELEASE branch). The relevant section of my standard-supfile looks like this:

# Defaults that apply to all the collections
#
# IMPORTANT: Change the next line to use one of the CVSup mirror sites
# listed at http://www.freebsd.org/doc/handbook/mirrors.html.
*default host=cvsup5.FreeBSD.org
*default base=/var/db
*default prefix=/usr
*default release=cvs tag=RELENG_7_0
*default delete use-rel-suffix

This is a read-only file, so to save your changes, type:

:w!

This will write your changes anyway. This is a very useful vi command. Now you can :q! to exit.

Now that we've updated the necessary config files, let's get this show on the road.

cd /usr/src
make update

One of two things will happen. 1) You'll see a lot of scrolling text as cvsup checks out the 7.0 sources and downloads them to /usr/src, replacing your old sources. 2) You'll receive an error message along the lines of "don't know how to make update". If you receive this error, it means that you don't have source installed on your system. To install source. . .

cvsup -h cvsup5.freebsd.org /root/standard-supfile

This will produce several minutes (on a high-speed Internet connection) of scrolling text as your system downloads the source to everything.

Either way, we're now ready to continue.

vi /usr/src/UPDATING

It is imperative that you read through this file before continuing (at least entries with recent dates). Otherwise you may miss essential notes and end up scratching your head as to why your build failed. For example, note that you will need to rebuild hal after updating to 7.0. As a matter of fact, due to a significant change in the version of gcc used by FreeBSD, you'll probably want to rebuild all of your installed packages after updating to 7.0.

NOTE: if you chose to upgrade with a custom kernel, at the very least you need to view /usr/src/sys/i386/conf/GENERIC (or the kernel conf for your computer's architecture, i.e. amd64). I would recommend copying this GENERIC kernel configuration to NEWKER and then compare it line by line with your 6.x custom kernel configuration, only adding/specifying options that you're really sure of.

make cleanworld

This will clean out all old build files. Unnecessary if you've never done an update before, but it won't hurt as an extra step.

make buildworld

Now we're building world. This will take awhile so you'll probably want to leave and come back.

make buildkernel

Now we're building the new kernel. This shouldn't take as long. If you have problems here, you will want to try taking out the line specifying the kernel config from /etc/make.conf, and building a generic kernel.

make installkernel

Now we're installing the new kernel. If the kernel install finishes successfully, we're ready to reboot. I tempted fate by rebooting normally rather than rebooting into safe mode. It worked fine for me, but to be safe you should probably boot into safe mode. If you're feeling lucky, you can skip ahead to the final install, i.e. "cd /usr/src && make installworld", after which you'll need to run "mergemaster". To boot into single user mode, hit "4" when you get to the loader with beastie. If all goes well you'll be asked for your shell, and you can hit enter to get the default shell which will work fine. If you had no problems here, skip ahead.

On the other hand, you may get an error trying to boot off of the new kernel. If you do, hit "6" at the loader promt to drop into a shell.

boot /boot/kernel.old

This will boot off of your old kernel. Once you are booted up, you should copy your old kernel over the new kernel that doesn't work.

cd /boot
cp -r kernel.old kernel

Now take the time to figure out what went wrong. (This may be another excellent opportunity to try upgrading with a GENERIC kernel rather than attempting to build a custom one. You can always upgrade with a GENERIC kernel and then build a custom kernel after you've successfully upgraded to 7.0). When you've got it figured out, reboot back into single user mode, and continue on.

Now that we're in single user mode, on a bootable 7.0 kernel, we can finish the install.

fsck -p

First we're checking for any filesystem inconsistencies, just to make sure all is okay.

mount -u /
mount -a

Now we're manually mounting our filesystems.

mergemaster -p

mergemaster will compare new configuration files with our old files. It gives us a chance to update to new 7.0 configuration files, while keeping our old configurations as necessary. This is the reason it was so important to backup /etc and /usr/local/etc. It is easy enough to make a mistake with mergemaster. In this case we are running it in prebuild mode.

As you can see from the instructions, i installs the new config file. Do this for files which you haven't modified. d will delete the new config file, so do this with files where you want to keep your custom configuration. m will merge the two files. It gives you options of which pieces to keep from each file. This is the most thorough way to keep old configurations, and you can do it if you are feeling ambitious. When comparing the old file and the new, note that a minus ( - ) sign in front of a line indicates that it is a line in the old file that is different from the new, and that a plus ( + ) sign in front of a line indicates that it is a line in the new file that is different from the old.

As far as the config files go, if you're lazy, you should get by with the first two options (i and d). Just to note, files like rc.conf, make.conf and passwd are ones you will most certainly want to keep your previous customizations.

Since we ran in prebuild mode, there were probably only one or two files you got prompted about. Now we can continue.

cd /usr/src
make installworld

After this we will have a complete 7.0 system. After installing the new world, you'll want to run mergemaster again, this time not in prebuild mode.

mergemaster

This time you'll be prompted for many more files. The commands are exactly the same (i installs the new config file, d keeps the old config file). To quickly scroll through files you know you haven't modified, just hit 'End'. After mergemaster is done, reboot as normal, and hopefully you'll enjoy 7.0.

If you want to be able to use 6.x packages you already have installed on your system, add the following line to /etc/rc.conf:

enable_compat6x="YES"

Then, install the compat6x package:

cd /usr/ports/misc/compat6x
make install clean

portupgrade -afkO

Back to our FreeBSD Guide Home