| ## Updating from Souce
## Rob Garrett <>
So, you've installed freebsd, and now you want to upgrade to a newer
version or perhaps you've decided to take your chances with -CURRENT.
There are a few different paths you can take to upgrade your system.
If you don't mind losing all of the software you have accumulated over
time, and you don't mind reconfiguring all of that additional software
this could be the path for you. However, if you've installed and
configured Apache, and just now got it where you like it, or your DNS
server is working great, or you just got the hang of sendmail.cf,
you're most likely not really looking forward to doing that all over
again and this option starts to look less and less attractive.
However, if you have a slow system, this could still be your best bet.
Upgrade from Source
For -CURRENT this is really the only option, but there are some things
you should know before jumping into it. You also need to be aware of
the time factor involved in doing a make world, and later in this
article, I'll look at some ways to speed this up. On a 400 MHz PII
with 128 MB of RAM, you can complete the whole process in less than
2 hours, however, on that old 486 with 8 MB of RAM, make world has
been known to take as long as 36 hours.
1) Follow the -CURRENT mailing list for a week or two before
you decide to jump in. This will help you get a feel for
the state of the system in -CURRENT, and could very easily
be the difference between a pleasant upgrade, and disaster.
2) Subscribe to the cvs-all mailing list. This will help you
understand what changes have been made since the last time
you upgraded and may very well be the deciding factor on
whether or not to build a new kernel, though I would
recommend doing so whether you need to or not.
3) Always cvsup before you build, if something does go wrong
it's a lot easier to get help if the source you are dealing
with is up to date.
If you're planning on upgrading a "production server" please do a
clean install. This is the best method for going about that.
The following is an excerpt of an email from Jordan Hubbard on this
subject. This was posted to the FreeBSD-stable mailing list on Thu, 18
Feb 1999 and is included here for completeness.
Those of you doing production server upgrades should install
3.1 fresh on a box and then *rotate* it into place, preferably
after carefully running it and the old machine in parallel for
awhile to see how the new one holds up. Once you're
comfortable with the upgrade, you can pull the old box and
free it for use in the next service rotation. For those who
just like to live life on the edge or are too cheap to buy a
"staging box" for this purpose, however, I have to say that
the source upgrade is probably the worst way to go about doing
it. If you absolutely must upgrade a box in-place (or don't
care because it's not a critical resource), do the binary
upgrade by booting the installation disks for 3.1-RELEASE (or
a later 3.1-STABLE snapshot from releng3.freebsd.org) and
choosing an upgrade installation. This is a faster, less
error prone and extremely direct way of upgrading from any
previous release, be it a.out OR ELF, in comparison to a
source upgrade. It still won't result in an installation
which is quite as "clean" as a completely fresh install, but
it does work (yes, I've tested it :).
I have a friend named Buster, and Buster's a dog. He sits on the couch
looking out the window most of the day, however, when another dog or
cat or just about anything else comes by, he attacks the window
barking and scratching the glass anxious to get to whatever it was he
saw. The point is, to often we skip what we think are little things
in order to speed things up. This isn't a process for the impatient;
taking care of the little things is the key to success with a source
upgrade. In order for you to have the proper tools to do this with
the least amount of effort you need to have a few tools at your
Here's my recommended "Shopping List"
cvsup: located in /usr/ports/net/cvsup
mergemaster: located in /usr/ports/misc/mergemaster
After cvsup is installed, you need to decide how you want to handle
your source tree. You have two options here.
1) Update the source tree in place. This is the easiest way
to keep your source tree up to date.
2) Download and maintain a copy of the full source
repository. This is useful if you want (or need) to look
back to see how a file has changed over the different
versions. It's also necessary if you want to do any real
development within FreeBSD. It does have it's drawbacks in
that you're going to need a 500 MB or so partition to hold
all the data besides the working source tree. This method
also takes a bit longer to work with.
I am going to try to cover both methods in this article, but I will
probably miss something here or there. You can refer to the man pages
and also the
if I don't succeed in explaining something fully.
For reference here is a list of cvsup servers for FreeBSD. This list
was compiled from the information in the
South Africa cvsup.za.FreeBSD.ORG
United Kingdom cvsup.uk.FreeBSD.ORG
USA cvsup.FreeBSD.ORG (Washington)
The export-restricted code for FreeBSD (eBones and secure) is
available via CVSup at the following international repository. Please
use this site to get the export-restricted code, if you are outside
the USA or Canada.
South Africa cvsup.internat.FreeBSD.ORG
Now that we know where the cvsup servers are located we can talk
about TAGS the tag you use tells cvsup what version of the source to
. CURRENT tree
RELENG_3 3.0-STABLE tree
RELENG_2_2 2.2-STABLE tree
The quick and easy way to update your source tree to is to change the
*default host = line to the cvsup server closest to you and then
change the tag in the file /usr/share/examples/stable-supfile to
whichever version of -STABLE you're after.
# The following line is for 3-stable. If you want
# 2.2-stable, change "RELENG_3" to "RELENG_2_2".
*default release=cvs tag=RELENG_3
*default delete use-rel-suffix
cvsup -g -L2 /usr/share/examples/cvsup/stable-supfile
For -CURRENT, you could also do this:
cvsup -g -L2 -h cvsup.ca.FreeBSD.org /usr/share/examples/cvsup/standard-supfile
Here's a description of the switches above:
-g Disables the graphical shell for x
-L2 Sets the level of verbosity that cvsup uses
-h Specifies the server to contact
Now we'll look at the slightly more complicated version.. The full
The first question we need to ask ourselves is where do we have 500 MB
or so of disk space we can use. We also need to take in to account
that we can't put the repository directly on /usr, so what we'll do is
put this where it wants to go in the default setup. You can put it
elsewhere and then create links to it or change the supfile to point
to the directory where you want it.
First, create a user called ncvs with a nologin shell. You can save
some time here if you have the cd set by copying the repository off of
the 2nd cd to /usr/home/ncvs.
Now all that's left to do to check the repository out is to change
the default host in /usr/share/examples/cvsup/cvs-supfile, and then
cvsup -g -L2 /usr/share/examples/cvsup/cvs-supfile
You might also want to copy whichever version of that file you decide
to use to root's home directory (/root), or somewhere else out of the
way because make world will replace the files in the
Now for the kicker:
# rm -rf /usr/src
# rm -rf /usr/ports
# setenv CVSROOT /usr/home/ncvs
# cd /usr
# cvs co /src
# cvs co /ports
You only need to do this the first time you use the repository. After
that, you can just cd to /usr/src and then do cvs update -Pd.
# cd /usr/src
# make world (if you're upgrading from 2.2.* to 3.* or
-CURRENT, use 'make upgrade' instead)
You can also use something like make -j4 world or similar. This
causes make to start the given number of cc's at one time. The
official statement on -j is not to use it, as it can cause problems
with diagnosing why a given build didn't work. If you do use it the
recommended formula is the number of processors +1. I have
successfully completed make world with -j values in the 40 to 50
range. You need to be aware of the fact that if this doesn't work try
it again with just make world before taking the problem to the mailing
Now that we've built and updated userland our next step is to update
/etc, which is not done automatically because it would override any
existing configuration you have.
The first thing we need to do, is make a backup copy of the files in
/etc. I put these in /var, so it would be:
# mkdir /var/etc.back
# cp -rf /etc /var/etc.back
Now we're ready to invoke mergemaster. You did install it didn't you?
# /usr/local/sbin/mergemaster -c -v
Mergemaster will scan /usr/src/etc and create copies of any files that
have changed. It will then show you diffs. The new info will be on
the right side of the screen and the old on the left.
You can merge the changed files now or go back and deal with them
later. I usually do it at this point.
You need to be careful because mergemaster will replace the files in
/etc with the new versions. It's quite possible and very easy to
mess up your password database or get it out of sync. Be careful..
it's not hard to get it right, you just need to pay attention to what
you're doing. If you have any questions about the options available
to you with mergemaster typing ? will provide some help.
The next thing we need to do is create a new kernel config I do this
from GENERIC after reading LINT to check for new options or other
things that might of changed. This topic is well covered in other
places but there are a few things I would like to mention.
config -r <KERNEL_NAME>
This is a new option in 3.0+. It removes the old compile directory as
this is not the default anymore.
Also, you MUST do 'make depend'. This is no longer an option, it's
After make depend, run make, and then make install as normal.
NOTE: If you used the upgrade target all, the above will be dealt
with for you..
You can now reboot into your newly upgraded system.
Return to Issue #3