dnl	$OpenBSD: upgrade,v 1.22 2003/11/10 22:11:35 espie 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