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.

Reinstall

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 disposal.

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 .

	Argentina	cvsup.ar.FreeBSD.ORG
	Australia	cvsup.au.FreeBSD.ORG
	Brazil		cvsup.br.FreeBSD.ORG
	Canada		cvsup.ca.FreeBSD.ORG
	Denmark		cvsup.dk.FreeBSD.ORG
	Estonia		cvsup.ee.FreeBSD.ORG
	Finland		cvsup.fi.FreeBSD.ORG
	Germany		cvsup.de.FreeBSD.ORG
			cvsup2.de.FreeBSD.ORG
			cvsup3.de.FreeBSD.ORG
	Iceland		cvsup.is.FreeBSD.ORG
	Japan		cvsup.jp.FreeBSD.ORG
			cvsup2.jp.FreeBSD.ORG
			cvsup3.jp.FreeBSD.ORG
			cvsup4.jp.FreeBSD.ORG
			cvsup5.jp.FreeBSD.ORG
	Netherlands	cvsup.nl.FreeBSD.ORG
	Norway		cvsup.no.FreeBSD.ORG
	Poland		cvsup.pl.FreeBSD.ORG
	Russia		cvsup.ru.FreeBSD.ORG
			cvsup2.ru.FreeBSD.ORG
	Slovakia	cvsup.sk.FreeBSD.ORG
			cvsup2.sk.FreeBSD.ORG
	South Africa	cvsup.za.FreeBSD.ORG
			cvsup2.za.FreeBSD.ORG
	Sweden		cvsup.se.FreeBSD.ORG
	Taiwan		cvsup.tw.FreeBSD.ORG
	Ukraine		cvsup2.ua.FreeBSD.ORG
	United Kingdom	cvsup.uk.FreeBSD.ORG
	USA		cvsup.FreeBSD.ORG	(Washington)
			cvsup2.FreeBSD.ORG	(California)
			cvsup3.FreeBSD.ORG	(Massachusetts)
			cvsup4.FreeBSD.ORG	(Virginia)
			cvsup5.FreeBSD.ORG	(Georgia)
  

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 grab.

	.		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.

	*default host=CHANGE_THIS.FreeBSD.org
	*default base=/usr
	*default prefix=/usr
	# 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
  

Then run:

	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 repository.

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 run:

	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 /usr/share/examples/cvsup directory.

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 lists.

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 required.

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.

Enjoy,

- Rob

Return to Issue #3