README-upgrade for Debian Gnu/Linux v. 2.0

                Upgrading using the Official Debian CD

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

     Debian 2.0 is based on the Gnu libc6 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 - the cd_autoup.sh script and 'apt-get dist-upgrade'.

     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 must 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 will now attempt to force removal of the
necessary packages, even if they are on hold.  However, it is
preferable to remove the hold manually before upgrading.


               Upgrading using the cd_autoup.sh script

     This README, the script cd-autoup.sh, and two .debs for bo
packages should be in a top-level directory "upgrade-i386" on the CD.
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.

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

     If you are not familiar with using dselect read dselect.beginner.txt
or dselect.beginner.html in the debian/hamm/hamm/disks-i386/current
directory of this CD before beginning the upgrade.

     It is strongly recommended that you use /usr/bin/script to record
a transcript of the 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.)

     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.  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 running cd_autoup.sh.  If you wish to use the apt access method
from dselect later, install apt manually (dpkg -i apt_0.1.4.bo_i386.deb) 
at this time.  Then enter `cd_autoup.sh'.

     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, it displays an informative message,
which is repeated here for ready reference:

  libc6 is now installed.  Now run dselect to upgrade the rest of your
  system.  It is recommended that you run the access, update, install,
  and configure modules of dselect initially to just upgrade all
  installed packages.  After that you may use the select and install
  modules to install additional packages if desired.  
  
  Keep in mind that when dpkg/dselect upgrades many packages (and almost
  every package on your system will be upgraded in this step), it is
  usually necessary to repeat the install and configure steps several
  times (perhaps four or five times) before the whole system is
  configured.  The apt access method for dselect improves this
  considerably.
  
  If you have apt installed (see discussion under "Upgrading using
  apt"), the apt access method should be selected in dselect's Access
  module.  Apt is much faster than any of the older dselect access
  methods.  When that's done, reboot with "shutdown -r now" for the
  utmp/wtmp wrapper functions in the upgraded libc5 to take effect.
  
  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 is 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, otherwise last and
  who and sac, etc. won't work. Here's what Miquel van Smoorenburg
  <miquels@cistron.nl> had to say about this recently in debian-user
  mailing list:
  
      > 1. You need to update ALL your packages to hamm
      > 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
  
       You now have a Debian Gnu/Linux v2.0 system.  Have fun! 



                         Upgrading using apt

     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. 

     If you are not familiar with using dselect read dselect.beginner.txt
or dselect.beginner.html in the debian/hamm/hamm/disks-i386/current
directory of this CD before beginning the upgrade.

     It is strongly recommended that you use /usr/bin/script to record
a transcript of the 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. 

     This README, apt_0.1.4.bo_i386.deb, dpkg_1.4.0.8.deb, and the
script cd-autoup.sh should be in a top-level directory "upgrade-i386"
on the CD.  If you cd to this directory before starting the upgrade,
you may install the bo packages (if needed) 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.

     Any package installation operation requires superuser privileges,
so either login as root or use su or sudo to gain these privileges.
Then enter `script -<filename>', and cd to the directory containing
this README.  (If your working directory is on the CD when you start
script, include a path to a writable directory in <filename>.)  Then
install apt manually (dpkg -i apt_0.1.4.bo_i386.deb).  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 proceeding with the rest of the
upgrade.  

     It is recommended that you read the apt user's guide in
/usr/doc/apt at this time.  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.

     Then run: apt-get update
               apt-get -f dist-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> had to say about this recently in debian-user
mailing list:

    > 1. You need to update ALL your packages to hamm
    > 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

     You now have a Debian Gnu/Linux v2.0 system.  Have fun! 

$Id: README-upgrade,v 0.7 1998/08/27 13:37:45 bob Exp bob $