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.

9 files changed, 103 insertions, 24 deletions

diff --git a/distrib/notes/alpha/hardware b/distrib/notes/alpha/hardware
index 05f493fff31..fad285ed8db 100644
--- a/distrib/notes/alpha/hardware
+++ b/distrib/notes/alpha/hardware
@@ -1,8 +1,8 @@
-dnl	$OpenBSD: hardware,v 1.33 2003/04/19 11:57:20 henning Exp $
+dnl	$OpenBSD: hardware,v 1.34 2003/09/06 22:22:41 miod Exp $
 OpenBSD/MACHINE OSREV is expected to run on the following hardware.
 If you have hardware that is listed here and are unable to run
 OpenBSD, or if you are able to run OpenBSD on hardware not listed
-here, please send mail to <alpha@openbsd.org> with as much information
+here, please send mail to <alpha@OpenBSD.org> with as much information
 as possible.
 
 Supported hardware:
diff --git a/distrib/notes/alpha/prep b/distrib/notes/alpha/prep
index 94c0ef9604a..4f26b61ebb7 100644
--- a/distrib/notes/alpha/prep
+++ b/distrib/notes/alpha/prep
@@ -1,4 +1,4 @@
-dnl	$OpenBSD: prep,v 1.19 2003/03/24 11:33:56 miod Exp $
+dnl	$OpenBSD: prep,v 1.20 2003/09/06 22:22:42 miod Exp $
 OpenBSD/MACHINE requires the SRM console.  Some alphas come with
 the AlphaBIOS (also known as the ARC firmware on older machines) instead;
 this is what Windows NT uses. It is fairly simple to replace the AlphaBIOS
@@ -128,4 +128,4 @@ OpenBSD/MACHINE console device restrictions:
     use display && keyboard console'', then you need to use a serial
     console.
     If your machine was not listed in the list above, please report this
-    on <alpha@openbsd.org>.
+    on <alpha@OpenBSD.org>.
diff --git a/distrib/notes/hp300/prep b/distrib/notes/hp300/prep
index d75386f1846..aa85056de16 100644
--- a/distrib/notes/hp300/prep
+++ b/distrib/notes/hp300/prep
@@ -1,3 +1,4 @@
+dnl	$OpenBSD: prep,v 1.17 2003/09/06 22:22:43 miod Exp $
 Most MACHINE machines don't generally need any specific preparation.
 
 On series 400, you will wish to configure the prom as ``HP-UX compatible''
@@ -9,5 +10,5 @@ to make this setting Permanent with ``P'', then validate your changes with
 If you plan to use a serial console, you might have to flip a switch
 on series 300, or configure the RS-232 interface as ``remote'' from the
 Configuration menu, on series 400.  Please refer to the OpenBSD/MACHINE
-FAQ at http://www.openbsd.org/hp300/hp300faq.html for more information
+FAQ at http://www.OpenBSD.org/hp300/hp300faq.html for more information
 about this process.
diff --git a/distrib/notes/hppa/upgrade b/distrib/notes/hppa/upgrade
index e3c99374675..ed24da54599 100644
--- a/distrib/notes/hppa/upgrade
+++ b/distrib/notes/hppa/upgrade
@@ -1,5 +1,3 @@
-dnl	$OpenBSD: upgrade,v 1.3 2003/03/06 04:19:45 david Exp $
-Since OpenBSD/OSREV is the first MACHINE release, there is no upgrade
-functionality.
-dnl
+dnl	$OpenBSD: upgrade,v 1.4 2003/09/06 22:22:43 miod Exp $
 dnl OpenBSDUpgrade({:-the CD-ROM, the miniroot-:})
+OpenBSDUpgrade({:-the miniroot-:})
diff --git a/distrib/notes/hppa/xfer b/distrib/notes/hppa/xfer
index 9e63d652f01..39a60d432d4 100644
--- a/distrib/notes/hppa/xfer
+++ b/distrib/notes/hppa/xfer
@@ -1,9 +1,8 @@
-dnl	$OpenBSD: xfer,v 1.3 2003/02/15 21:38:22 miod Exp $
+dnl	$OpenBSD: xfer,v 1.4 2003/09/06 22:22:43 miod Exp $
 Installation is supported from several media types, including:
 
 	CD-ROM
-dnl Not until upgrades are available
-dnl	FFS partitions
+	FFS partitions
 	Tape
 	FTP
 	HTTP
@@ -13,6 +12,5 @@ OpenBSDXferShortPrelude
 
 
 OpenBSDXferBareTape
-dnl Not until upgrades are available
-dnl
-dnl OpenBSDXferFFS
+
+OpenBSDXferFFS
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.