initial version. 3 minute edit away from i386..

1 files changed, 103 insertions, 0 deletions

diff --git a/distrib/notes/amd64/upgrade b/distrib/notes/amd64/upgrade
new file mode 100644
index 00000000000..48e2b2689c4
--- /dev/null
+++ b/distrib/notes/amd64/upgrade
@@ -0,0 +1,103 @@
+dnl	$OpenBSD: upgrade,v 1.1 2004/02/07 21:29:10 deraadt Exp $
+dnl OpenBSDUpgrade({:-the CD-ROM or an installation floppy as you would do for
+dnl a new installation-:})
+Due to the change from a.out to ELF binary format in OpenBSD OSREV,
+upgrades can be a complex, delicate process. The best solution, whenever
+possible, is to backup your data and reinstall from scratch.
+
+The second best solution is to remove all ports, third party programs and
+libraries installed on your system; upgrade; and then add ELF versions of
+the removed files.
+
+In all cases, once you start the upgrade you MUST complete it. If the
+upgrade process fails or is abandoned before it completes you will almost
+certainly be left with a non-functional system.
+
+Finally, you cannot use the bsd.rd kernel to upgrade the system. The
+existing bootblocks on your system cannot boot the OSREV bsd.rd.
+
+If you must do an upgrade while preserving the functionality of any
+existing a.out binary files, then the rest of this section will guide you
+through that process.
+
+The two main hurdles in upgrading from an a.out system to an ELF OpenBSD
+OSREV system while preserving the functioning of a.out binaries 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
+set up. 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.
+
+It is recommended that the following instructions and commands are issued in
+single-user mode.
+
+The /emul/a.out hierarchy 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/var/run
+   tar cf - /sbin/ldconfig /usr/bin/ldd /usr/libexec/ld.so |
+       tar -C /emul/a.out -xpf -
+   for lib in $(/sbin/ldconfig -r |
+     awk '/=>/ { print $3 }');
+   do
+     dirname $lib;
+   done | sort -u > /root/a.out-libdirs
+   tar cf - $(find $(< /root/a.out-libdirs) -name "lib*.so.*") |
+       tar -C /emul/a.out -xpf -
+
+Then, a cache of these shared libraries must be generated with:
+
+   cp /var/run/ld.so.hints /var/run/ld.so.hints.backup
+   /sbin/ldconfig -s $(/usr/bin/sed 's,^/,/emul/a.out/,' /root/a.out-libdirs) 
+   /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
+
+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
+
+
+ATTENTION! Several configuration files under /etc, such as /etc/login.conf,
+will refer to existing a.out binaries. DO NOT UPGRADE YOUR SYSTEM UNLESS
+YOU HAVE ENABLED A.OUT EMULATION FIRST! After you merge configuration files
+changes and replace or remove your existing a.out binaries, it will be
+possible to disable a.out emulation.
+
+
+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 $(file $(find $(< /root/a.out-libdirs) -name "lib*.so.*") |
+    awk -F: '/demand paged/ { print $1 }')
+  rm -f /root/a.out-libdirs