NetBSD/distrib/notes/common/upgrade

.\"	$NetBSD: upgrade,v 1.13 2002/04/14 13:12:38 bjh21 Exp $
.\"
.\" Copyright (c) 1999-2001 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"        This product includes software developed by the NetBSD
.\"        Foundation, Inc. and its contributors.
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
.\"    contributors may be used to endorse or promote products derived
.\"    from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.
.
.Pp
The upgrade to
.Nx \*V
is a binary upgrade; it can be quite difficult
to advance to a later version by recompiling from source due primarily
to interdependencies in the various components.
.Pp
.ie \n[macppc]:\n[sparc] \{\
To do the upgrade, you must boot from the installer kernel using one of
the methods described above.
.\}
.el .ie r_pmax \{\
To do the upgrade, you must install new bootblocks and boot off
the
.Ic install
kernel as described in the
.Sx Installing from an existing system
section.
.\}
.el .ie r_x68k \{\
As noted above, you must have the
.Pa loadbsd.x
utility and the installation kernel you chose, or, the
boot floppies available to do the upgrade.
.\}
.el \{\
To do the upgrade, you must have the boot floppy
.if r_alpha set
available.
.\}
You must also have at least the
.Sy base
and
.Sy kern
binary distribution sets available, so that you can upgrade with them,
using one of the upgrade methods described above. Finally, you must
have sufficient disk space available to install the new binaries.
Since the old binaries are being overwritten in place, you only need
space for the new binaries, which weren't previously on the system.
If you have a few megabytes free on each of your root
.Pq Pa /
and
.Pa /usr
partitions, you should have enough space.
.Pp
Since upgrading involves replacing the boot blocks on your
.Nx
partition, the kernel, and most of the system binaries, it has the
potential to cause data loss. You are strongly advised to
.Em back up any important data on your disk ,
whether on the
.Nx
partition or on
another operating system's partition, before beginning the upgrade
process.
.if r_macppc \{\
Since installation of the bootloader will prevent
.Tn MacOS
from using the disk and will prevent Open Firmware 3 machines from
booting, there is an option to bypass this step.  Make sure you know
whether or not to install the bootloader.
.\}
.Pp
The upgrade procedure using the
.Ic sysinst
tool is similar to an installation, but without the hard disk partitioning.
The original
.Pa /etc
directory is renamed to
.Pa /etc.old ,
and no attempt is made to merge any of the previous configuration into
the new system except that the previous
.Pa /etc/fstab
file is copied into the new configuration.
Getting the binary
sets is done in the same manner as the installation procedure;
refer to the installation part of the document
for how to do this. Also, some sanity checks are done, i.e.
file systems are checked before unpacking the sets.
.Pp
After a new kernel has been copied to your hard disk, your
machine is a complete
.Nx \*V
system. However, that
doesn't mean that you're finished with the upgrade process.
You will probably want to update the set of device
nodes you have in
.Pa /dev .
If you've changed the contents of
.Pa /dev
by hand, you will need to be careful about this, but if
not, you can just cd into
.Pa /dev ,
and run the command:
.Pp
.Dl # Ic "sh MAKEDEV all"
.Pp
You must also deal with certain changes in the formats of
some of the configuration files. The most notable change is
that the options given to many of the file systems in
.Pa /etc/fstab
have changed, and some of the file
systems have changed names. To find out what the new options
are, it's suggested that you read the manual page
for the file system's mount commands, for example
.Xr mount_nfs 8
for NFS.
.Pp
Finally, you will want to delete old binaries that were part
of the version of
.Nx
that you upgraded from and have since been removed from the
.Nx
distribution.