June 21st, 2004, 17:30
This is highly abbreviated to keep it simple, and is pasted as plain text.

Updating Your FreeBSD Desktop
Part 1: Core System
Ed Hurst, 21 June 2004

Now that we have everything installed and setup the way we like it,
it's important to keep an eye on updating the system. The emphasis is
not so much slavishly chasing the cutting edge of BSD technology.
Instead, our focus will be on security updates and optimization.

One of the major selling points with FreeBSD is security. How silly it
would be if we didn't do the minimum necessary to insure it stays
secure. FreeBSD coders are some of the best on earth, but if perfect
software could be written, no one could afford it. From time to time,
flaws are discovered after the product is released. Fixes are often
released within 24 hours of discovering a flaw. However, these fixes
are seldom offered as a new package built and ready to download. You
will have to download a patch, apply it and rebuild the flawed binaries
from source. Occasionally, a flaw will affect the whole system base and
will require rebuilding the whole thing.

Which brings us to the issue of optimization: Rebuilding the system
base is a good idea in the first place, simply because it offers the
best opportunity to make your system run as well as it can. When you
install FreeBSD from a CD-ROM, you are getting generic binaries with
the lowest level of optimization. Virtually everyone who tries a
rebuild will swear it made things better.

While this sounds like a major task fraught with risk, it really is
quite simple. The good folks of FreeBSD have made it so easy, it's
painless. Even when one considers doing an upgrade using a slow dialup
connection such as mine, you can be sure the time factor is reasonable,
and the results well worth it. To demonstrate the possibilities, here's
the stats:

- Task: update from FreeBSD 4.9 to 4.10

- Fastest transfer rate: 2600 Bps

- System source update: 20 minutes (using CVSup)

- Buildworld: 1.5 hours to compile

- Buildkernel: 12 minutes to compile

- Mergemaster config files: 15 minutes

- Total time investment: roughly 2 hours

This was done on my old home-built machine:

Gigabyte GA-7 series mobo, AMD 750 chipset
AMD Duron 800, 384MB RAM
Maxtor 40GB/7200RPM harddrive

At each step of the way, I took the defaults whenever possible. Please
note that the only tweaking I chose to do was in /etc/make.conf,
selecting "i686" as the CPUTYPE. I could have chosen "k7" because my
CPU is a Duron, but at the time I was focussed on safety. As I later
learned, most of the time it works out that compiling with CPUTYPE=k7
in actual practice shows up as k6. You can find some guidelines on this
file and decide what best suits your purposes. Most of the entries are
of no interest to the desktop user.

Here is the process, step by step.

1. Insure that you have CVSup installed. Installing packages is covered
in earlier lessons, so we'll assume you have it. Log in as root and
navigate to /usr/src/share/examples/cvsup. There you will see several
files which you can copy and modify for use. Our interest here is the
file 'stable-supfile'. Copy it to /usr/src and open in your favorite
text editor. Two main items here. Go down to where you see:

*default host=CHANGE_THIS.FreeBSD.org

You need to change this to a mirror that is presumably near you so that
you can get a fast and strong connection. The list of mirrors can be
found at /usr/share/doc/en/books/handbook/cvsup.html near the bottom of
the page. The list shows about 17 mirrors. If you know how to use the
'ping' command, you can time the response to find the one CVSup server
which will serve you quickest. With my slow connection, it was safer to
look for the one geographically closest, by using the 'host' command to
identify where each mirror was hosted. Mine ended up with:

*default host=cvsup5.us.FreeBSD.org

A few lines down, I made sure there was a one like this:

*default release=cvs tag=RELENG_4

This keeps me up to date with the latest packages for the 4.x branch of
FreeBSD; as of this writing the latest stable version is 4.10. Save the
file and close. From the same source of example files, copy the 'refuse'
file over to /usr/src. This file keeps you from downloading a horde of
listings for language-oriented packages you probably won't use. Check to
make sure you approve of what's refused in the file, then save and

2. Connect as user to the Internet, but run CVSup as root. Simply type
on the commandline:

cvsup stable-supfile

What should pop up will be an ugly pink window with two frames. On the
left is a bunch of statistics; on the right will be a live listing of
what the program is doing. Look it over, but what really matters are
the tiny buttons on the lower left-hand corner. Click the one that says
"Start" and watch, if you have time. As stated above, my system was
finished in 20 minutes downloading the difference between the source
files for 4.9 and for 4.10. Because of compression ("zipping") the
replacement rate was quite a bit faster than the packet flow rate, as
shown in the status in the left frame.

3. When finished, the little buttons will change to show it. Close the
application and drop your connection to the Internet. Now is a good
time to close down applications, shut down the X server, and work in
the console. This will allow your system to devote maximum resources to
the work of rebuilding. Log out of your user account and login as root.

Navigate back to /usr/src. Issue the command:

make buildworld

This took my system an hour and a half. Naturally, your mileage may
vary. If there are going to be any problems, this is where you are most
likely to see them. However, they are extremely rare. If it fails,
you'll get an error notice that you can copy and paste in a message
asking for help. The Handbook page makeworld.html will provide the
necessary details. As long as you have not installed anything from a
failed buildworld, you can simply resume using your system as before.
For the truly paranoid, do this: Just before you command buildworld,
you can use the 'script' command.

script /var/tmp/mw.out

This will create a file that has a record of every keystroke and every
commandline message you get, starting with what follows the command
'script', and ending only when you type 'exit'. This file will be saved
in /var/tmp as 'mw.out' (makeworld output). If all goes well, you can
delete the file later. Be sure to type the command 'exit' when
buildworld is finished. Assuming all went well, you'll know when the
command prompt returns empty.

What happens is that a script will tell your computer to rebuild the
newest version of the basic C libraries, install themselves, then build
again for optimization, and install themselves again. Then the rest of
the system is built.

4. Of course, you'll need to update the kernel, too. But since nothing
new has been installed, you can't use the Handbook instructions for
building a kernel the normal way. You have to use the script:

make buildkernel

This took 12 minutes for me, but was faster when I went back and built a
custom kernel from the update. For now, we won't do that. Let's just
stick with the trusted generic kernel, because you'll need to keep an
updated generic kernel on hand for emergencies.

5. When building is finished, and there's no problems, run the command:

make installkernel

If you are nervous, now is the time to reboot and see if everything
works with the new kernel. I simply forged ahead with the next step.

6. First, drop down out of regular run mode into single mode. On
FreeBSD, this is very easy; simply type:

shutdown now

By leaving out the switches for shutdown, such as -h (halt) or -r
(reboot), you are telling shutdown to go into single mode. This means
you are pulled back out of the system, as it were, running only the
absolute minimum, rather like DOS in many ways. It's not wise to have
programs running while replacing them. Now it's safe to install your
new base system:

cd /usr/src
make installworld

This will take a few minutes. When it's finished, we have one more step
before running our new system.

7. Invoke 'mergemaster' from the commandline so that we can compare all
our old config files with the new defaults. Often a system update will
include changes to the layout of the config files, and the old ones may
not work properly in the new system. Mergemaster will show you the
differences line-by-line using minus (-) for what the old looks like,
and plus (+) to indicate how the new one is different. Read the prompts
on the screen and decide what you want to change. For the most part, I
accepted the defaults. I keep a written record of changes I make to the
various config files on my system. While it's annoying to have to stop
and record every change, and note why I did it, things like mergemaster
become much easier. In fact, the simplest way is to accept all the new
files, then go back and edit them individually according the changes
you made before the update.

Now we're done and ready for the first test run:

shutdown -r now

In a couple of minutes, I was back up. The X server started a little
faster, things seemed brighter and sharper, but it may have just been
my own internal glow at knowing the update worked.

Next time you install a system, especially with a recent release,
consider just getting the base system installed, then running the
buildworld process (minus update) to optimize everything before going
any further. The primary difference this makes is that anything you
compile afterwards will compile quite a bit faster, because the system
libraries have already been optimized.

July 12th, 2004, 23:28
Thanks for sharing your articles with the board, I found your printing article really useful (even under GNU/Linux).

Thanks again.