Making the Transition to ELF

Here are some steps that might help with the transition from FreeBSD 2.2.8 to 3.x. It is a list of general steps, not a list of everything you need to do within those steps; but it does tell you where to get the information you need. If it seems confusing when you get around to reading the actual documents, you might want to do a fresh install of FreeBSD 3.1-RELEASE instead of trying to convert a 2.2.x system.

1. Cvsup using tag=RELENG_3_1_0_RELEASE. Although the claim is sometimes made that you should do 3.0 first, it's probably not necessary.
2. Go to /usr/src and read all the text files (especially README and UPDATING) including the Makefiles. Get the other files referred to there, especially the document by Robert Nordier on boot blocks. Install mergemaster from the ports collection if you plan to use it (see below).
3. As root in /usr/src do
make aout-to-elf-build
and then
make aout-to-elf-install
Alternatively, you can do make upgrade, which is probably even better. It may do some of the following steps for you, but you should make sure they're done.
This will take quite a while--longer than the usual make world, as it's building support for both elf and aout binaries, which you need. You do not have to go to single-user mode to do this.
4. Merge /usr/src/etc with /etc. Remember that you have important configuration files in /etc, including password files, the group file, rc.conf, and others. You can use mergemaster to do this, but it will ask you for decisions and needs to be done carefully. Read the man page for mergemaster and for sdiff first.
The merge into /etc (back it up first) is often ignored or not done carefully enough. Be sure to add the new group; if you need to ask what it is, you haven't read the docs in /usr/src. You may want to read Nik Clayton's discussion of this topic in his tutorial on upgrading on the FreeBSD web page (or on his own page). As Nik points out, part of this "merge" is putting the new MAKEDEV in /dev. Note that other "files" in /usr/src/etc are directories with subdirectories. It's especially important to install the new make.conf.
5. Install the new boot blocks. You need them to boot an elf kernel, and aout kernels are no longer supported. They should have been installed by the aout-to-elf procedure, but if not, you can use the "mount" command to find your boot device (say it's wd0s1) and then do
disklabel -B /dev/wd0s1
substituting the appropriate device for wd0s1.
6. Build an elf kernel. If your system is 2.2.x, it will offer to build a GENERIC kernel for you so the system can boot. But you will probably want to do your own in addition. You should use the new GENERIC as the base for making changes rather than your old config file, because there are quite a few changes you will otherwise miss, and you'll get error messages when you try to build it. Install the new kernel; if you don't build and install a new kernel (whether GENERIC or not), programs like ps and w and top won't work.
7. Note that for scsi drives, you will have to build some new devices nodes in /dev (with ./MAKEDEV), such as da instead of sd, although the system will boot even if you don't do this and leave /etc/fstab as it was. Because there are so many changes, you will want to have a boot floppy available and know the location of your boot sector and the names of old kernels so you can get the system to boot in case you've done something wrong. Reboot. Good luck.

My thanks to Dag-Erling Smørgrav (des@freebsd.org) for helpful suggestions that improved this document greatly; remaining errors are my own.
Annelise Anderson andrsn@andrsn.stanford.edu