Updating to FreeBSD 6.0 - Revision history

Jimbo at 12:11, 3 January 2009

2009-01-03T12:11:58Z

Jimbo at 12:11, 3 January 2009

2009-01-03T12:11:26Z

Joe: Fixing busted link

2006-02-24T15:03:08Z

Fixing busted link

62.163.37.105: /* Customizing the kernal */

2006-02-05T21:11:11Z

Customizing the kernal

Joe: changed section title to be harder to ignore

2005-12-24T05:49:15Z

changed section title to be harder to ignore

Joe: Walkthrough of updating from 5.4 to 6.0, mostly from /usr/src/UPDATING + HBK

2005-12-23T14:14:43Z

Walkthrough of updating from 5.4 to 6.0, mostly from /usr/src/UPDATING + HBK

New page

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.
#Source Update (described in this document)
#Reinstall using a new install iso cd (keep good backups... nice to fall back on)
#Binary update using the freebsd-update port as described [http://www.daemonology.net/freebsd-upgrade-5.4-to-6.0/|here]

The complete FreeBSD Handbook section can be found here: [http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html] 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 [http://www.google.com/bsd], 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 [http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html 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''.

← Older revision		Revision as of 12:11, 3 January 2009
Line 101:		Line 101:
	boot kernel.old		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''.		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''.
		+
		+	[[Category: Common Tasks]]

@@ Line 18: / Line 18: @@
 ===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 [http://www.google.com/bsd], 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.
+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 '''google.com/bsd''', 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===

@@ Line 2: / Line 2: @@
 #Source Update (described in this document)
 #Reinstall using a new install iso cd (keep good backups... nice to fall back on)
-#Binary update using the freebsd-update port as described [http://www.daemonology.net/freebsd-upgrade-5.4-to-6.0/|here]
+#Binary update using the freebsd-update port as described [http://www.daemonology.net/freebsd-upgrade-5.4-to-6.0/ here]
 The complete FreeBSD Handbook section can be found here: [http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html] This article is an attempt to more clearly layout some of the steps involved for this particular upgrade.

@@ Line 47: / Line 47: @@
     override the CPUTYPE if it needs to.
-===Customizing the kernal===
+===Customizing the kernel===
 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.

@@ Line 9: / Line 9: @@
 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==
+==Getting Up To Date Source==
 *Use [[FreeBSD_Release_Branches]] to help you decide which release to follow.
 *Select a supfile tag.