Updating to FreeBSD 6.0

This article describes the source upgrade process from 5.X to 6.0 . It is essentially the same as the handbook chapter, modified to highlight a few potential pitfalls in the upgrade process. There are three basic updating options, although the source update can be considered the 'standard' method.

1. Source Update (described in this document)
2. Reinstall using a new install iso cd (keep good backups... nice to fall back on)
3. Binary update using the freebsd-update port as described [1]

The complete FreeBSD Handbook section can be found here: [2] This article is an attempt to more clearly layout some of the steps involved for this particular upgrade.

Upgrading from older versions of 5.X

There are potential problems updating a system from 5.1-5.3 to 6.0 directly. Although they do not affect everyone, it is highly recomended to upgrade at least to RELENG_5_4 or RELENG_5 (Read FreeBSD_Release_Branches for definitions of these tags) before upgrading to 6.0 . You can use the somewhat more general instructions in Upgrading_the_base_system to do the upgrade from 5.X to RELENG_5.

Getting the Source

• Use FreeBSD_Release_Branches to help you decide which release to follow.
• Select a supfile tag.
• Use Updating the source tree to update your source tree.

System Preperation

There are a few things you need to do before you launch into compiling your new kernel, particularly if you are jumping across major versions.

Do your homework

Google for "FreeBSD version your-particular-hardware" to see if anyone has had problems... and to check if there were any solutions. You may want to use [3], and double check with an archive of FreeBSD-Questions or FreeBSD-Stable as well. You also MUST read through /usr/src/UPDATING. For future reference, much of this information was taken from the COMMON ITEMS section of UPDATING, but some of it may change in the future, so it's only smart to double check.

Backups

Everyone says to make backups, what is less obvious is what exactly should be backed up. For example... usually large data directories and home directories that are on their own partitions or drives do not need to be backed up (more than usual). These are simply unmounted and not touched again until the system is up and running. Most of your system can just be dumped to a larger file system and left. But you will want to keep a few files handy (possibly inside of /root/old_system/ or something similer)

• /etc/rc.conf
• /boot/loader.conf
• /etc/sysctl.conf

You may want to check the loader.conf file for particular hardware modules that will need special attention. (nvidia is a common one)

Double check your /etc/make.conf settings

From the handbook:

  Examine the files /usr/share/examples/etc/make.conf
(called /etc/defaults/make.conf in FreeBSD 4.X) and /etc/make.conf.
The first contains some default defines - most of which are commented out.
To make use of them when you rebuild your system from source, add them
to /etc/make.conf. Keep in mind that anything you add to /etc/make.conf
is also used every time you run make, so it is a good idea to set them
to something sensible for your system.
  A typical user will probably want to copy the CFLAGS and NO_PROFILE (or
NOPROFILE on FreeBSD 5.X and older) lines found in
/usr/share/examples/etc/make.conf (or in /etc/defaults/make.conf on
FreeBSD 4.X) to /etc/make.conf and uncomment them. Examine the other
definitions (COPTFLAGS, NOPORTDOCS and so on) and decide if they are
relevant to you.

From a recent /usr/src/UPDATING

If CPUTYPE is defined in your /etc/make.conf, make sure to use the
  "?=" instead of the "=" assignment operator, so that buildworld can
  override the CPUTYPE if it needs to.

Customizing the kernal

For a major update like this, you may want to simply install the GENERIC kernel, and then customize it and rebuild when you know the major version change hasn't disrupted something on your system. See Kernels,_Custom for information on customizing a kernel. Note that your old kernel config file from 5.X CANNOT simply be copied and used for 6.X. If you are going to use a custom kernel, just make sure to use make kernel KERNFILE=your kernel config file (full path) below.

Upgrade your ports...

by whatever means you use. This is not strictly needed, but may head off problems with the last step in this process. You can refer to ports for more information about this.

Compilation

Follow these steps in order, as long as they do not produce error messages.

su -          #Become root
Password:
cd /usr/src   #or to whichever directory you put src in
make buildworld

This will build the system libraries and surrounding programs for the operating system to function

make buildkernel
make installkernel

Build and install the Kernel itself. Note that you will often see documentation that tells you to

• make kernel

This is just an alias that executes both of the above commands in sequence.

shutdown -r now #Reboot the system

From the boot prompt boot -s will launch in single user mode. Then do the following:

fsck -p
mount -u /
mount -a
cd src            #or /usr/src
adjkerntz -i      #if the CMOS clock is set to local time

This should get you ready to install world.

• Local Terminal Access

Note that this assumes you are at a local terminal on the machine. Single user mode makes sure that system binaries are not being replaced while they are being used. If you really cannot have physical access to the machine, you might risk cutting off all other services other than ssh, and killing any unnecessary daemons (to minimize library usage) and attempting the remote upgrade, but this is neither supported nor recomended. If you continue in multiuser mode you should realize there is a significant probability that you will break your system.

mergemaster -p

This script will bring you through each of your configuration files and ask you if you want to update to the new settings that it has found. This will really depend on the settings files that are being updated. A common tactic here is to record any changes that look like they disappeared from any files that you edited, and accept all changes. Then examining the changes in more detail after the system is up and running.

make installworld

Install the world libraries and programs.

mergemaster -i

Run this script again to check for changes from the installed world.

shutdown -r now

This will reboot the system. Bring it up again in as normal with your new kernel running. Type uname -a on a prompt to verify the version.

portupgrade -af

This is not optional or minor. Your ports have linked against system libraries that have been changed, sometimes drastically. If you do not run this command, you will likely have streams of funny-looking error messages from a wide variety of your ports. This will probably take longer than any other part of the install (up to several days for slower systems with GUI's installed, an hour or two for a server without any massive ports installed).

Restore configuration files

Restore from your notes taken during the mergemaster -p phase, and the saved configuration files in the #Backups step. You may need to also reinstall any binary modules (non-ports) that you may have had previously installed. nvidia video drivers and RAID card drivers are commonly in this category.

If there are problems

First... did you do everything properly and in order?

If things break in compiling world or kernel

This is probably the best place for things to break, as they haven't actually changed anything yet. Firstly, check a few of the listed errors in /usr/src/UPDATING, and try a few of the debugging ideas in the handbook. If neither that nor Google works. Keep in mind, if your kernel compile breaks here you haven't actually broken anything, so you've only inconvenienced yourself. You may want to try make clean before doing subsequent build attempts.

If your system won't boot to the new kernel

By default, FreeBSD saves a copy of the old kernel as kernel.old . If you can't get it to boot... at the countdown loader, interrupt it and type the following

unload
boot kernel.old

This should boot your old kernel, and you can examine logs to try to determine what happened. One thing to watch out for though, don't just build another kernel without saving your current one, because then the current buggy kernel will overwrite your current failsafe kernel.old.