Upgrading from bo or earlier releases

     One of Debian's key features is its upgrade mechanism, which
permits one to upgrade an older Debian system without reinstalling
everything. 

     If your system has already been upgraded to Debian 2.0 (hamm),
you do not need to read any further.  Refer to the Release-Notes in the
top-level directory of the CD.

     Beginning with version 2.0, Debian is based on the libc6 (Gnu
glibc2) library, while earlier Debian versions were based on the libc5
library.  Programs compiled to dynamically link with the libc5
libraries will not run with the the libc6 libraries, and vice versa.
Debian has developed a method to permit binaries compiled for both
libraries to coexist on a system, and to permit development under
either library to be done.

     Because certain libc6 packages are incompatible with some libc5
packages, it is necessary to remove some libc5 packages and to install
some libc6 packages before starting the upgrade.  These removals and
installations must be done in the correct order or the system may be
left in an unstable state.  Two means of accomplishing this have been
provided - 'apt-get dist-upgrade' and the cd_autoup.sh script .

     The apt-get method is recommended if you are able to use it.  Apt
s very particular about the status of the system.  It checks the
system status, and refuses to continue if any packages are "broken".

     This README, the script cd-autoup.sh, two .debs for bo packages,
and a directory "deb-files" containing 27 .debs needed by
cd_upgrade.sh, should be in a top-level directory
"upgrade-older-i386" on the CD.  (In the past some CD vendors have
modified the directory structure.  If this is the case with your CD,
you may have to modify some of the commands given below.)  If you cd
to this directory before starting the upgrade, you may install the bo
packages (if needed) and run the script using the commands given
below.  If you prefer not to change to the directory on the CD,
appropriate pathnames must be included in these commands.

     Regardless of the method used for upgrading, it is recommended
that you check the status of all packages first.  This can be done by
dpkg -l|less or dpkg --get-selections> filename, or it can be done
in dselect.  It is desirable to remove any holds before upgrading.  If
any package that is essential for the upgrade is on hold, the upgrade
will fail.  Holds can be removed in dselect, or by editing the file
produced by dpkg --get-selections> filename to change "hold" to
"install".  Then, with root permissions, do: 
          dpkg --set-selections<filename.

     Any package installation operation, including the autoup script,
must be run with superuser privileges, so either login as root or use
su or sudo to gain these privileges.  

     It is strongly recommended that you use /usr/bin/script to record
a transcript of the upgrade session - in fact, it is a good idea to
use script to record any dselect session (and anything else you do
that it is desirable to record).  Then if any problems develop, you
can see what happened.  script will write this transcript to the file
specified as an argument - `script -myfilename', or to the default
filename `typescript'.  (If your current directory is on the CD when
you start script, "myfilename" must include a path to a writable
directory.)

     If you are upgrading from a buzz (1.1.x) system, you must upgrade
dpkg manually (dpkg -i dpkg_1.4.0.8.deb) before starting the upgrade.
If you wish to use apt-get or the apt access method from dselect
later, install apt manually (dpkg -i apt_0.1.10_i386-libc5.deb) at
this time.


                       Upgrading using apt-get

     The Deity Project has developed a new and improved interface for
dpkg, known as apt.  The user interface for apt is not yet operational,
but it may be used from the command line and as an access method for
dselect. 

     Note the paragraph above about packages on hold.  Holds can
prevent APT from upgrading the entire system and if used improperly
can completely prevent upgrading at all. Holds on key packages such as
libraries and holds on essential packages are especially likely to
cause problems. If you find that APT is not upgrading a number of
packages a hold is the likely culprit.

     It is recommended that you read the Release-Notes in the top
level directory of the CD, and read the apt user's guide in
/usr/doc/apt proceeding further.  Before beginning the upgrade you
must set up apt's configuration file, /etc/apt/sources.list. Add as
the first line after the instructional comments:

             deb file:<cd_mount_point>/debian stable main

     If you do not yet have internet access (or do not want to
download any new security fixes) on the machine then comment out the
other two lines. Otherwise you may select a closer mirror, if you
wish. 

     Then run: apt-get update
               apt-get -f dist-upgrade

     The -f (Fix) option causes apt to attempt to correct a system
with broken dependencies in place. APT does not allow broken package
dependencies to exist on a system. It is possible that a system's
dependency structure can be so corrupt as to require manual
intervention (which usually means using dselect or dpkg --remove to
eliminate some of the offending packages). 
     
     If apt reports some broken packages after these two commands, try
to repair the system (perhaps removing the broken packages or
installing missing dependencies).  If you can not repair the system to
apt's satisfaction, you must use the cd_autoup.sh method to upgrade.

     You should carefully review the list of packages that APT wants
to remove and be sure that is okay.  Some essential packages are OK to
remove (e2fsprogs, for instance), but others are not.

WARNING  
     If APT lists lib* in the list of essential packages to remove then
it is very likely you will hose your system by continuing.

      Then run: apt-get install timezones locales

     At this point your system is stable, with most or all of the
packages upgraded to libc6.  You may now run dselect, using apt as the
access method, to upgrade any packages that are still libc5, and
install new ones if desired.

      Finally, remember to fix up wtmp and utmp, otherwise last and
who and sac, etc. won't work. Here's what Miquel van Smoorenburg
<miquels@cistron.nl>, the maintainer of sysvinit, recommended:

     1. You need to update ALL your packages to libc6 (hamm or later) versions 
     2. Reboot if you haven't done that already
     3. You need to move the wtmp file and truncate the utmp file:
        cd /var/log
        mv wtmp wtmp.libc5
        touch wtmp
        cd /var/run
        cp /dev/null utmp
     4. You might want to reboot again to make sure
    
     This is because the "struct utmp" and thus the utmp and wtmp
"databases" are different between libc5 and libc6


               Upgrading using the cd_autoup.sh script

     If any packages on your system were marked "hold" by dselect,
they can not be removed or upgraded.  This would cause the upgrade to
fail.  If any of the following packages are on hold, you should use
dselect to remove the hold before starting the upgrade:

    ldso, libc5, libc6, timezones, locales, ncurses3.0, ncurses3.4,
libreadline2, libreadlineg2, bash, libg++27, libg++272, libstdc++2.8,
dpkg, dpkg-dev, slang0.99.34, slang0.99.38, libgdbm1, libgdbmg1,
perl-base, perl, data-dumper, libnet-perl, dpkg-ftp, dpkg-mountable,
netbase, netstd, timezone, xmanpages, perl-suid, perl-debug, wg15-locale,
libpthread0, xslib, splay, boot-floppies, localebin.

     The cd_autoup.sh script attempts to force removal of the
necessary packages, even if they are on hold.  However, it is
preferable to remove the hold manually before upgrading.

     The script cd-autoup.sh is designed to remove the incompatible
libc5 packages and install the necessary libc6 packages.  It may be
used to upgrade buzz (1.1.x), rex (1.2.x), or bo (1.3.x) systems to
hamm (2.0) or later versions.

     After getting superuser privileges and changing to the
/upgrade-older-i386 directory of the cd, run "cd_autoup.sh".  (The
script may be run from another working directory by prepending the
appropriate path.)

     Before starting the actual upgrade, this script removes a number
of packages that, for one reason or another, interfere with the
upgrade.  Some of these will be replaced with hamm packages by the
script, others must be reinstalled with dselect after the script has
run.  The script will write a file "removed-<today's date>" to the
\root directory listing all files that were removed. This file may
be used as a guide in selecting packages to be installed with
dselect.  

     Then answer the questions when asked (certain of the newly
installed programs have interactive configuration scripts).  A number
of harmless, but alarming-sounding warnings are displayed during the
upgrade process, especially when perl is removed to permit installing
perl-base.  

     When the script finishes your system is stable, with the most
important packages upgraded to libc6.  You may now run dselect to
upgrade the packages that are still libc5, and install new ones if
desired.  Before running dselect you should read Release-Notes in the
top level directory of the CD.  If you are unfamiliar with dselect,
refer to "Using dselect" in the Release-Notes.

     All development packages (-dev, -dbg, and -pic) and a number of
other incompatible packages have been removed during this upgrade
procedure due to conflicts between libc5 and libc6 versions.  A list
of the removed packages are in the file "/root/removed-<today's
date>".  You will have to install the libc6 equivalents of any of
these packages that you need.  If you will be doing any libc5
development work, you will also want to re-install (from the old-libs
directory) any of these libc5 packages you need.

      Finally, remember to fix up wtmp and utmp, as described in the
last paragraph of the section "Upgrading using apt-get" above.
     
Bob Hilliard <hilliard@debian.org>
$Id: README-upgrade,v 1.6 1999/02/20 23:59:10 bob Exp bob $