NetBSD/distrib/notes/mac68k/upgrade

.\"	$NetBSD: upgrade,v 1.19 2002/06/29 23:54:05 lukem Exp $
.\"
.\" Copyright (c) 1999-2002 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.
.\"
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
No automated upgrade procedure exists for upgrading to release \*V for the
.Nx*M
architecture.
The current procedure is essentially to perform a new install from scratch.
It is hoped that there will be a good upgrade procedure for future releases.
Please feel free to volunteer to help replace these installation tools.
.Pp
The following steps outline the current upgrade procedure.
These steps should help ease the upgrade process.
Please read these instructions carefully and completely before proceeding.
.(enum
Since upgrading involves replacing 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.
Although the upgrade should not damage your file system(s) in any way,
you never know what may happen.
.It
Download the distribution sets you want from the
.Pa \*M/binary/sets
subdirectory of the
.Nx \*V
distribution.
You will need the base set and the kernel at a minimum.
Be sure to download the files in
.Em binary
mode.
If you will be upgrading from within
.Nx ,
make sure
that you place the distribution sets on a file system you will be able to
reach from single-user mode.
.It
Install the \*V kernel.
You may either use the Installer utility
(included in the
.Pa installation/misc
subdirectory) or install from within
.Nx
(the latter is recommended for speed reasons).
If you choose the former, proceed as you normally would.
If you choose to install from within
.Nx ,
then boot (or shutdown) into single-user
mode and do the following:
.Pp
.Dl # Ic "cd /"
.Dl # Ic "pax -zrvpe -f /path/to/kern.tgz"
.Pp
There is no need to backup your old kernel explicitly since it will be
incapable of running many of the newer binaries you are about to
install.
(Unless, of course, you have a backup copy of your older
binaries and want to revert to them for some reason.)
However, you might want to keep a backup if you are upgrading from within
.Nx
just in case the newer kernel has trouble booting your machine.
.It
If you are installing using the Installer, skip to step 5.
Otherwise, reboot into
.Nx
in single-user mode.
Run
.Ic fsck Fl f
and then mount all
local partitions read/write.
Usually
.Ic mount Fl a t Ic nonfs
should do the
trick, but if you have several partitions on the same disk, take note of
the fact that a change in partition numbering may have moved a few of
your partitions around.
You can do a
.Ic disklabel sd Ns Ar X
(where
.Ar X
is a
drive on which you have
.Nx
partitions) to see how the partitions are
currently laid out.
It is likely that a partition has shifted into the
.Li sd Ns Ar X Ns Li d
or
.Li sd Ns Ar X Ns Li e
slots, slots that often were not available under
previous releases of
.Nx .
If this is the case, you will need to
manually mount your root partition
.Pq Pa /
via
.Ic "mount -w /"
and edit your
.Pa /etc/fstab
file to reflect the new partition layout.
Unless you are familiar with
.Xr ex 1
or
.Xr ed 1 .
the easiest way to fix your
.Pa /etc/fstab
file
is probably to simply do a
.Ic "cat \*> /etc/fstab"
and type in the corrected file in its entirety.
.It
Install the distribution sets.
Keep in mind that the
.Nx \*V
distribution takes up a considerably larger amount of disk space than
did the 1.3 family of distributions.
If you are using the Installer, proceed normally
(remember that you will need to mount non-root partitions by hand using
the MiniShell before installing).
If you are installing from within
.Nx ,
do the following:
.Pp
.Dl # Ic "cd /"
.Dl # Ic "pax -zrvpe -f /path/to/base.tgz"
.Pp
Keep in mind that there is
no going back once you have installed the base set short of a complete
re-install of an earlier distribution.
Continue with the appropriate command line for each of the other sets
you wish to install except for the
.Sy etc
set.
If you are in the Installer, open up the Minishell and do the following:
.Pp
.Dl Ic "cd /tmp"
.Dl Ic "exit"
.Pp
Ignore the warning message this will cause.
Now, use the Installer to install the
.Sy etc
set (it will install into
.Pa /tmp
instead of the
.Pa /etc
directory).
.Pp
If you are in
.Nx ,
do the following instead:
.Pp
.Dl # Ic "cd /tmp"
.Dl # Ic "pax -zrvpe -f /path/to/etc.tgz"
.It
If you are in the Installer, quit it and boot into
.Nx
in single-user mode.
From there,
.Ic cd
to the
.Pa /tmp/etc
directory and compare each file there with your old files in
.Pa /etc .
You will probably want to replace
some of your system configuration files, or incorporate some of the
changes in the new versions into yours.
You should take note of the following when upgrading to the
.Nx \*V
etc.tgz set:
.(bullet
Several of the options given to many of the file systems have changed,
and some of the file systems have changed names.
.(Note
It is imperative that you change any instances of
.Sy ufs
.Pa /etc/fstab
to
.Sy ffs .
.Note)
To find out
more about different file system options, read the man page for the
associated
.Ic mount
command (e.g.
.Xr mount_mfs 8
for MFS file systems; note:
FFS type file systems are documented in the
.Xr mount 8
man page).
If you have not already done so, you may also need to correct
.Pa /etc/fstab
for a shift in the partition numbering scheme.
See step 4 above for more details.
.It
You will also probably want to upgrade your device nodes at this time as well.
Make sure you have installed the latest MAKEDEV script
(it should be included in the etc set) and perform the following commands:
.Pp
.Dl # Ic "cd /dev"
.Dl # Ic "sh MAKEDEV all"
.bullet)
.It
Run
.Ic fsck Fl f
to make sure that your file system is still consistent.
If fsck reports any errors, fix them by answering
.Sq Ic y
to its suggested
solutions
.(Note
If there are a large number of errors, you may wish
to stop and run
.Ic fsck Fl fy
to automatically answer
.Ic yes
instead.
.Note)
.It
Exit from single-user mode and it should continue to boot into
multi-user mode.
.enum)
.Pp
At this point you have successfully upgraded to
.Nx \*V .