xref: /src/distrib/notes/i386/upgrade

The upgrade to NetBSD _VER is a binary upgrade; it would be prohibitive
to make users upgrade by compiling and installing the _VER sources, and
it would be very difficult to even compile a set of instructions that
allowed them to do so.  Because of the many changes to the system, it
is difficult and impractical to upgrade by recompiling from the sources
and installing.

To do the upgrade, you must have the boot floppy image (boot-13.fs)
available.  You must also have at least the "base13" and "kern13"
binary distribution sets available, so that you can upgrade with it,
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 and /usr
partitions, you should have enough space.

Since upgrading involves replacing the boot blocks on your NetBSD
partition, the kernel, and most of the system binaries, it has the
potential to cause data loss.  You are strongly advised to BACK UP ANY
IMPORTANT DATA ON YOUR DISK, whether on the NetBSD partition or on
another operating system's partition, before beginning the upgrade
process.

To upgrade your system, follow the following instructions:

	Boot your machine using of the appropriate upgrade floppy.
        The boot loader will start, and will print a countdown and
        begin booting. You will likely see one "file not found"
        warning from the boot loader -- ignore this as it is normal,
        and indicates the boot loader failed to find a normal kernel
        to boot before trying to boot a compressed kernel.

        If the boot loader messages do not appear in a reasonable
        amount of time, you either have a bad boot floppy or a
        hardware problem.  Try writing the install floppy image to
        a different disk, and using that.

	While booting, you will probably see several warnings.  You
	should be warned that no swap space is present, and that
	init(8) cannot find /etc/rc.  Do not be alarmed, these are
	completely normal.  When you reach the prompt asking you for a
	shell name, just hit return.

	You will be asked if you wish to install or upgrade your
	system or go to a shell prompt. Enter "upgrade".

	You will be presented with some information about the upgrade
	process and a warning message, and will be asked if you wish
	to proceed with the upgrade process.  If you answer
	negatively, the upgrade process will stop, and your disk will
	not be modified.  If you answer affirmatively, the upgrade
	process will begin, and your disk will be modified.  You may
	hit Control-C to stop the upgrade process at any time.
	However, if you hit it at an inopportune moment, your system
	may be left in an inconsistent (and possibly unusable) state.

	You will be asked if you wish to upgrade your file systems to
	the new file system format.  If you do, reply affirmatively.
	If you don't have your file systems upgraded now, you should
	probably do it manually after the install process is complete,
	by using "fsck -c 2". Read the fsck(8) manual page for more
	details. NOTE: ONLY UPGRADE YOUR FILE SYSTEMS IF YOU ARE
        UPGRADING FROM A PRE-NetBSD 1.0 RELEASE.

        If you choose to upgrade your file systems, the upgrade
        program will then check your root file system, and, if you
        approved, will upgrade it to the new file system format.  It
        will then mount your root file system on /mnt.

	If your file systems are being upgraded, the upgrade script
	will copy the new fsck(8) program to your hard disk and
	upgrade your remaining file systems.

	The upgrade program will then automatically replace the boot
	blocks on your disk with newer versions, and mount all of your
	file systems under /mnt.  (In other words, your root partition
	will be mounted on /mnt, your /usr partition on /mnt/usr, etc.)

	If you don't already have the NetBSD distribution sets on your
	disk, look in the installation section for information on how
	to transfer them to your disk.

	Once the distribution sets are transferred to your disk,
	continue here.  (Obviously, if the NetBSD distribution sets
	are already on your disk, because you've transferred them
	before starting the upgrade process, you don't need to
	transfer them again now!)

	After the software has been transferred to the machine (or
	mounted, in the case of upgrading via NFS), change into the
	directory containing the "base13" distribution set.  Once you
	are there, run the "Set_tmp_dir" command, and hit return at
	the prompt to select the default answer for the temporary
	directory's path name.  (It should be the path name of the
	directory that you're in.)

	Run the command "Extract base13" to upgrade the base
	distribution.

	Repeat the above two steps for all of the sets you wish to
	upgrade.  (For each, change into the directory containing the
	set, run "Set_tmp_dir" and accept the default path name, then
	run the "Extract <setname>" command.)

        NOTE: YOU MUST INSTALL THE "kern13" DISTRIBUTION, AS IT
        CONTAINS THE NEW NetBSD _VER KERNEL! This step is different
        from previous netbsd upgrade procedures, which installed the
        kernel from a boot floppy using a special procedure.

	If you were previously using the security distribution set,
	you MUST upgrade to the new version, or you will not be able
	to log in when the upgrade process is complete.  Similarly, if
	you were not previously using the security set, you must NOT
	upgrade to the new version.

	When you are done upgrading all of the distribution sets you
	wish to upgrade, issue the command "Cleanup".  It will clean
	up the installation, by remaking some system databases.  When
	it is complete, you should use "halt" to halt the system, or
	"reboot" to reboot it.

Your system has now been upgraded to NetBSD _VER.

        After a new kernel has been copied to your hard disk, your
	machine is a complete NetBSD _VER system.  However, that
	doesn't mean that you're finished with the upgrade process.
	There are several things that you should do, or might have to
	do, to insure that the system works properly.

	First, if you did not upgrade your file systems to the new
	file system format during the upgrade process, and you are
        upgrading from a pre-1.0 NetBSD, you may want to do so now,
        with "fsck -c 2".  If you are unsure about the process, it's
        suggested that you read the fsck(8) manual page.

	Second, you will probably want to get the etc13 distribution,
	extract it, and compare its contents with those in your /etc/
	directory.  You will probably want to replace some of your
	system configuration files, or incorporate some of the changes
	in the new versions into yours.

	Third, you will probably want to update the set of device
	nodes you have in /dev.  If you've changed the contents of
	/dev by hand, you will need to be careful about this, but if
	not, you can just cd into /dev, and run the command "sh
	MAKEDEV all".

	Fourth, you must 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
	/etc/fstab or by hand have changed, and some of the file
	systems have changed names. *IMPORTANT*: ANY INSTANCES OF "ufs"
        IN /etc/fstab MUST BE CHANGED TO "ffs".  To find out what the
        new options are, it's suggested that you read the manual page
        for the file systems' mount commands, for example mount_nfs(8)
        for NFS.  (Note that the information for mounts of type "ffs",
	i.e. Fast File Systems, are contained in the mount(8) man
	page.)

	Finally, you will want to delete old binaries that were part
	of the version of NetBSD that you upgraded from and have since
	been removed from the NetBSD distribution.  If you are
        upgrading from a pre-1.0 NetBSD, you might also
	want to recompile any locally-built binaries, to take
	advantage of the shared libraries.  (Note that any new
	binaries that you build will be dynamically linked, and
	therefore take advantage of the shared libraries, by default.
	For information on how to make statically linked binaries,
	see the cc(1) and ld(1) manual pages.)