dnl	$OpenBSD: upgrade,v 1.24 2004/03/28 20:38:09 millert Exp $
dnl OpenBSDUpgrade({:-the CD-ROM or an installation floppy as you would do for
dnl a new installation-:})
Prior to version 3.4, OpenBSD used the a.out binary format.  Beginning
with version 3.4, OpenBSD uses the ELF binary format.  Because of
this, upgrades from a version of OpenBSD prior to 3.4 can be a
complex, delicate process.  The best solution, whenever possible,
is to back up 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.

If upgrading from a version of OpenBSD prior to 3.4, you cannot use
the bsd.rd kernel to upgrade the system.  The existing bootblocks
on your system cannot boot the OSREV bsd.rd--use the bsd.rd-a.out
kernel instead.

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 an /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, an installation
floppy, or the bsd.rd-a.out kernel 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 on, 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.

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 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