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.

4 files changed, 91 insertions, 9 deletions

diff --git a/distrib/notes/i386/contents b/distrib/notes/i386/contents
index e0007001965..2a599642511 100644
--- a/distrib/notes/i386/contents
+++ b/distrib/notes/i386/contents
@@ -1,4 +1,4 @@
-dnl	$OpenBSD: contents,v 1.43 2003/03/25 19:57:31 miod Exp $
+dnl	$OpenBSD: contents,v 1.44 2003/09/06 22:22:43 miod Exp $
 TopPart
 
 OpenBSDfloppy
@@ -13,7 +13,7 @@ OpenBSDfloppy
 				pcmcia drivers; see below.
 
 		cdrom{:--:}OSrev.fs	The MACHINE boot and installation
-				2.88mb floppy image that contains almost all
+				2.88MB floppy image that contains almost all
 				OpenBSD drivers; see below.
 
 OpenBSDdistsets
diff --git a/distrib/notes/i386/hardware b/distrib/notes/i386/hardware
index 7e8786c55b1..bbc75ed34e0 100644
--- a/distrib/notes/i386/hardware
+++ b/distrib/notes/i386/hardware
@@ -1,4 +1,4 @@
-dnl	$OpenBSD: hardware,v 1.128 2003/09/05 19:11:38 henning Exp $
+dnl	$OpenBSD: hardware,v 1.129 2003/09/06 22:22:43 miod Exp $
 OpenBSD/MACHINE OSREV works across a broad range of standard PC's and
 clones, with a wide variety of processors and I/O bus architectures.  It
 can be expected to install and run with minimal difficulties on most
@@ -952,5 +952,5 @@ Special care for PCI BIOS:
 
 	Try to gather dmesg output from the failing configuration, for
 	example by using serial console (see boot(8)) and send it to
-	<mickey@openbsd.org> along with descriptions of your hardware setup.
+	<mickey@OpenBSD.org> along with descriptions of your hardware setup.
 	Alternatively, dig in the code and fix problems.
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
diff --git a/distrib/notes/i386/whatis b/distrib/notes/i386/whatis
index 7149543a3ce..d0a9ef94440 100644
--- a/distrib/notes/i386/whatis
+++ b/distrib/notes/i386/whatis
@@ -1,3 +1,5 @@
-For the MACHINE, OpenBSD OSREV brings greater stability and security.  As a
-side effect of the full security audit, many userland programs have
-been significantly cleaned up and debugged.
+dnl	$OpenBSD: whatis,v 1.9 2003/09/06 22:22:43 miod Exp $
+For the MACHINE, OpenBSD OSREV brings greater stability and security,
+including a stricter memory permission scheme. As a side effect of the
+full security audit, many userland programs have been significantly
+cleaned up and debugged.