MD Installation notes updates for 3.4, 1/3

This mainly includes an hopefully helpful section about i386 upgrades, which
I urge knowledgeable people and native english speakers to check out, in
order to polish it soon enough.

1 files changed, 82 insertions, 2 deletions

diff --git a/distrib/notes/i386/upgrade b/distrib/notes/i386/upgrade
index 597ee8788d7..bf4c8dbdbce 100644
--- a/distrib/notes/i386/upgrade
+++ b/distrib/notes/i386/upgrade
@@ -1,2 +1,82 @@
-OpenBSDUpgrade({:-the CD-ROM or an installation floppy as you would do for
-a new installation-:})
+dnl	$OpenBSD: upgrade,v 1.17 2003/09/06 22:22:43 miod Exp $
+dnl OpenBSDUpgrade({:-the CD-ROM or an installation floppy as you would do for
+dnl a new installation-:})
+Due to the change in binary format from a.out to ELF in OpenBSD OSREV,
+upgrades, albeit possible, are very tricky.  The best solution, whenever
+possible, is to backup your data and reinstall from scratch.
+
+The two main hurdles in the upgrade from an a.out system to an ELF OpenBSD
+OSREV system are:
+- the a.out binary emulation, required for compatibility with a.out
+  binaries using shared libraries, is not enabled by default, and requires
+  an explicit configuration change.
+- a.out shared libraries (lib*.so) need to be moved to a specific location
+  for proper operation of older binaries.
+
+Before you start the upgrade process, the a.out emulation area needs to be
+setup. It needs to be put inside a /emul/a.out hierarchy. This directory can,
+however, be a symbolic link, should the available space in the root partition
+not be enough.
+
+The /emul/a.out should be populated by the a.out shared libraries.
+An easy way to do it is to run the following commands as root:
+
+   mkdir -p /emul/a.out/sbin /emul/a.out/var/run
+   tar cf - `/sbin/ldconfig -r | awk '/=>/ { print $3 }'` |
+       tar -C /emul/a.out -xpf -
+   cp -p /sbin/ldconfig /emul/a.out/sbin
+
+Then, a cache of these shared libraries must be generated with:
+
+   cp /var/run/ld.so.hints /var/run/ld.so.hints.backup
+   for lib in `/sbin/ldconfig -r |
+       awk '/=>/ { printf("/emul/a.out%s\n", $3"); }'`;
+   do
+       dirname $lib;
+   done | sort | uniq > /root/a.out-newlibdirs
+   /sbin/ldconfig -s `cat /root/a.out-newlibdirs`
+   /bin/mv /var/run/ld.so.hints /emul/a.out/var/run
+   /bin/mv /var/run/ld.so.hints.backups /var/run/ld.so.hints
+   rm -f /root/a.out-newlibdirs
+
+Finally, it is a good idea to keep a list of the various shared libraries
+which have been copied to the /emul/a.out hierarchy, as they will need to
+be removed after the upgrade is completed:
+
+  /sbin/ldconfig -r | awk '/=>/ { print $3 }' > /root/a.out-sharedlibs
+
+The last step before the upgrade is to enable the a.out emulation, in
+order to be sure that /etc/rc.local or any other customization you have
+made to the system will still run:
+
+  echo "kern.emul.aout=1" >> /etc/sysctl.conf
+
+The upgrade is now possible. Boot from the CD-ROM or an installation
+floppy, as you would do for a new installation. 
+
+When prompted, select the (U)pgrade option rather than the (I)nstall
+option at the prompt in the install process.
+
+The upgrade script will ask you for the existing root partition, and
+will use the existing filesystems defined in /etc/fstab to install the
+new system in.  It will also use your existing network parameters.
+
+From then, the upgrade procedure is very close to the installation
+procedure described earlier in this document.  Note that the upgrade
+procedure will not let you pick the ``etc{:--:}OSrev.tgz'' set, so as to
+preserve your files in `/etc' which you are likely to have customized
+since a previous installation.
+
+When the upgrade procedure tells you that the upgrade is complete, do not
+reboot the system yet.
+
+However, it is strongly advised that you unpack the etc{:--:}OSrev.tgz set in
+a temporary directory and merge changes by hand, since all components of
+your system may not function correctly until your files in `/etc' are
+updated.
+
+After the upgrade is completed, it is now possible to remove the old a.out
+shared libraries from their initial locations:
+
+  rm -f `cat /root/a.out-sharedlibs`
+  rm -f /root/a.out-sharedlibs