[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ next ]

Release Notes for Debian GNU/Linux 3.0 (`woody'), Intel x86
Chapter 3 - Upgrades from Previous Releases

3.1 Detailed Changes to the System

3.1.1 Important program syntax changes

Debian attempts to avoid changing upstream packages, therefore changes in the original packages will be present in Debian GNU/Linux

In Debian GNU/Linux 2.2 'Potato' release tar used the


switch for bzip compression, however now the


switch is in use. You may need to change any scripts accordingly.

3.1.2 Note for users of virus scanners

Users of virus scanners such as amavis, scannerdaemon and clamav should keep their packages up-to-date otherwise there is the possibility that a buggy package could allow viruses to pass into or out of the system, with horrific consequences. It should also be mentioned that the virus database in woody is now static and obsolete. Pinning the antivirus packages from testing or unstable may be a possible solution.

3.1.3 Estonian Timezone

Regulation nr. 84 (21.02.2002, Estonian Government), valid from 01.03.2002, says, that starting from this year (spring, 2002), there is a daylight savings time in Estonia. The beginning of daylight savings time ("summer time" in estonian) is on last Sunday of March 01:00 GMT (03:00 local time) and end on last Sunday of October 01:00 GMT (04:00 local time). You should be able to use exactly the same rules as for Helsinki in /usr/share/zoneinfo/Europe/Helsinki file.

3.1.4 Upgrading PostgreSQL

The new version of PostgreSQL is more strict and restrictive in its input handling. This means that tests line foo = NULL which is not valid anyway won't be accepted anymore. This also means that when using UNICODE encoding, ISO 8859-1 and ISO 8859-15 are no longer valid encodings to use when inserting data into the relation in question. In such a case you are advised to convert the corresponding relation dump, which you can alway make using pg_dump -t table database, using recode latin1..utf-16.

This particular change can also affect the upgrade process, since dumping and importing data from the old and into the new database may stomp over illegal input.

3.1.5 Notes for users of sendmail/m4

The version of m4 in woody does not run on Linux kernels from the 2.0 series. It is therefore strongly recommended that users of sendmail upgrade to a 2.2 series or better Linux kernel before proceeding with the upgrade.

3.2 Preparing for the Upgrade

Before upgrading your system, it is strongly recommended that you make a full backup, or at least backup any data or configuration information you can't afford to lose. The upgrade tools and process are quite reliable, but a hardware failure in the middle of an upgrade could result in a severely damaged system.

The main things you'll want to back up are the contents of /etc, /var/lib/dpkg and the output of dpkg --get-selections \*.

It's wise to inform all users in advance of any upgrades you're planning, although users accessing your system via ssh (at least) shouldn't notice much during the upgrade, and may want to continue working. If you wish to take extra precautions, back up or unmount user's partitions (/home) before upgrading. A reboot will not normally be necessary.

Distribution upgrade should be done either locally from a textmode virtual console (or a directly connected serial terminal), or remotely via an ssh link.

Important: You should not upgrade using telnet, rlogin, rsh, or from an X session managed by xdm on the machine you are upgrading. That is because each of those services may well be terminated during the upgrade, which can result in an inaccessible system that is only half-upgraded.

3.2.1 Checking Packages Status

Regardless of the method used for upgrading, it is recommended that you check the status of all packages first, and verify that all packages are in an upgradable state. The following command will show any packages which have a status of Half-Installed or Failed-Config, and those with any error status.

                 # dpkg --audit

You could also inspect the state of all packages on your system using dselect, or with commands such as

                 # dpkg -l | pager


                 # dpkg --get-selections > ~/curr-pkgs.txt

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. You can identify packages on hold with

                 # dpkg --audit

If you changed and recompiled a package locally, and didn't rename it or put an epoch in the version, you must put it on hold to prevent it from being upgraded. The `hold' package state can be changed either by using dselect (in the Select menu, use the `H' and `G' keys to hold and unhold, respectively), or by editing the file produced by

                 dpkg --get-selections > ~/curr-sels.txt

to change "hold" to "install" (or vice versa), and then, with root permissions, doing

                dpkg --set-selections < ~/curr-sels.txt

3.2.2 Special Considerations for SSH Users

The commercial SSH located in the ssh package before release 2.2 or in the ssh-nonfree in release 2.2 has been replaced by the DFSG free ssh package (OpenSSH) in this release. The commercial SSH collection is no longer present. The ssh package includes a Debconf question which will regenerate a configuration which is OpenSSH compatible.

3.2.3 Directories Possibly Needing Attention

It is important that the /etc/rcS.d directory exists prior to the upgrade; the installation of the libc6 package will fail otherwise.

The /usr/share/doc directory (if it exists already) should not be a symlink (e.g. to /usr/doc), since that will cause some packages to break. However, symlinking /usr/doc to /usr/share/doc is allowed. Please note that if you use such a symlink there will be numerous messages about /usr/doc directories that can't be removed. Those are normal, and you can safely ignore them.

3.3 Preparing Sources for APT

The recommended method of upgrading is to use the apt method with dselect, as described here. The built-in dependency analysis enables smooth upgrades and easy installations.

You should not be doing any major package upgrades with access methods other than apt in dselect, because those, unlike the apt method, do not do any logical package ordering during the installation, and therefore aren't as reliable. Additionally, such upgrades are not well tested and are unsupported by Debian.

Any package installation operation must be run with superuser privileges, so either login as root or use su or sudo to gain the necessary access rights.

Before starting the upgrade you must set up apt's configuration file for package lists, /etc/apt/sources.list.

apt will consider all packages that can be found via any "deb" line, and install the package with the highest version number, giving priority to the first mentioned lines (that way, in case of multiple mirror locations, you'd typically first name a local harddisk, then CD-ROMs, and then HTTP/FTP mirrors).

3.3.1 Adding APT Internet Sources

The default configuration is set up for installation from main Debian Internet servers, but you may wish to modify /etc/apt/sources.list to use other mirrors, preferably a mirror that is network-wise closest to you.

Otherwise, Debian HTTP or FTP mirror addresses can be found at http://www.debian.org/distrib/ftplist (look at the "Full list of mirrors" section). HTTP mirrors are generally speedier than ftp mirrors.

For example, suppose your closest Debian mirror is http://mirrors.kernel.org/debian/. When inspecting that mirror with a web browser or FTP program, you will notice that the main directories are organized like this:


To use this mirror with apt, you add this line to your sources.list file:

                  deb http://mirrors.kernel.org/debian woody main contrib

Note that the `dists' is added implicitly, and the arguments after the release name are used to expand the path into multiple directories.

After adding your new sources, disable the previously existing "deb" lines in sources.list, by placing a hash sign (#) in front of them.

Any package needed for installation that is fetched from the network is stored in the /var/cache/apt/archives (and the partial/ subdirectory, during download), so you must make sure you have enough space before attempting to start the installation. With a reasonably extended Debian installation, you can expect at least 300 MB of downloaded data.

Note: if you are using the static versions of apt and dpkg, the hostname-lookup is broken (which is one reason to use the normal apt when upgrading over the network). The solution is to simply put the mirrors' IP address in the "deb" line. (Hint: nslookup some-server)

3.3.2 Adding APT Local Mirror Sources

Instead of using HTTP or FTP packages mirrors, you may wish to modify /etc/apt/sources.list to use a mirror on a local disk (possibly NFS-mounted).

For example, your packages mirror may be under /var/ftp/debian/, and have main directories like this:


To use this with apt, add this line to your sources.list file:

                  deb file:/var/ftp/debian woody main contrib

Note that the `dists' is added implicitly, and the arguments after the release name are used to expand the path into multiple directories.

After adding your new sources, disable the previously existing "deb" lines in sources.list, by placing a hash sign (#) in front of them.

3.3.3 Adding APT CD-ROM Sources

See above if you need to first install the latest version of apt and dpkg packages, as described above.

If you want to use CDs only, comment out the existing "deb" lines in /etc/apt/sources.list by placing a hash sign (#) in front of them.

Make sure there is a line in /etc/fstab that enables mounting your CD-ROM drive at the /cdrom mount point (the exact /cdrom mount point is required for apt-cdrom).For example, if /dev/hdc is your CD-ROM drive, /etc/fstab should contain a line like:

                  /dev/hdc /cdrom auto defaults,noauto,ro 0 0

Note that there must be no spaces between the words defaults,noauto,ro in the fourth field.

To verify it works, insert a CD and try running

                 mount /cdrom (this will mount the CD to the mount point)
                 ls -alF /cdrom (this should show the CD's root directory)
                 umount /cdrom (this will unmount the CD)

Next, run:

                 apt-cdrom add

for each Debian Binary CD-ROM you have, to add the data about each CD to APT's database.

3.4 Upgrading using dselect

The recommended method for upgrading to Debian GNU/Linux 3.0 is using the package management tool dselect. This tool makes safer decisions about packages than apt-get.

If dselect is not installed please install the version supplied with your release of Debian GNU/Linux.

The access method for the archive (using APT) has already been configured, you can change this configuration however using the "[A]ccess" method on the menu. If you are happy with your access configuration proceed to the next stage by selecting "[U]pdate" from the menu. This will update the package database.

If no problems occured with the update stage, choose "[S]elect" from the menu, dselect will examine the available packages and intelligently decide which packages need upgrading and which new packages need to be installed to compliment the upgrades. It will also suggest packages that should be removed. Hitting return at the package selection screen will either give you a conflict/dependency resolution screen (at which you may have to change selections and press return again) or return you to the main menu. Help on the package selection stage is available by pressing "?".

Now that the package selections have been decided it is necessary to install any new packages, to do this choose "[I]nstall" from the main menu. This will download and install the packages using APT from your prefered medium. Go and have a nice cup of Earl Grey, this is going to take some time.

The final two stages are "[C]onfig" and "[R]emove" which will finish the upgrade process by configuring the new packages and removing any redudant packages

3.5 Upgrading using apt-get directly (not recommended)

Don't forget to mount all needed partitions (notably the root and /usr partitions) read-write, with a command like:

                 mount -o remount,rw /mountpoint

Assuming you have already configured apt's sources.list as explained above, run (as root):

                 apt-get update

This will resynchronize the package overview files from their sources, updating information about new and updated packages.

It is strongly recommended that you use the /usr/bin/script program to record a transcript of the upgrade session. Then if any problems develop, you will have a log of what happened, and if needed, can provide exact information in a bug report. To start the recording, type:

                 script -a ~/upgrade-to-woody.typescript

or similar. Do not put the typescript file in a temporary directory such as /tmp or /var/tmp (files in those directories may be deleted during the upgrade or during any restart).

It is important to upgrade apt, dpkg and debconf before you do the majority of the upgrade. Apt has been considerably improved since the previous releases. Debconf is an essential tool which is in extensive use in recent packages.

                 apt-get install dpkg apt debconf

This will install the newest versions of dpkg, apt and debconf, which are needed for the rest of the upgrade. It will also upgrade some necessary system libraries to the latest version.

When debconf asks about the kind of questions to ask, do not choose 'critical', or else you will miss important questions.

Some people prefer to first rehearse the upgrade using

                 apt-get --fix-broken --show-upgraded --simulate dist-upgrade | pager

While this may be somewhat time consuming, it may avoid some surprises. This will tell you either what's wrong with your system (and how to solve it), or, most likely, what exactly will be done during the upgrade. Pay special attention to the packages that will be "REMOVED"; no essential packages should be listed there.

After you have verified that apt-get should work fine, run:

                 apt-get --fix-broken --show-upgraded dist-upgrade

This will perform a complete upgrade of the system, i.e. install the newest available versions of all packages, and resolve all possible dependency changes between packages in different releases. If necessary, it will install some new packages (usually new library versions, or renamed packages), and remove any conflicting obsoleted packages.

When upgrading from a set of CD-ROMs, you will be asked to insert specific CDs at several points during the upgrade. You might have to insert the same CD multiple times; this is due to inter-related packages that have been spread out over the CDs.

New versions of currently installed packages that cannot be upgraded without changing the install status of another package will be left at their current version (displayed as "held back"). Therefore, it may be necessary to use dpkg or dselect to remove and reinstall some broken packages or dependencies. Alternatively, apt-get dselect-upgrade may be used after apt-get -f dist-upgrade.(See the apt-get(8) man page.)

The --fix-broken (or just -f) 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.

3.5.1 Possible Issues During or After Upgrade

Sometimes it's necessary to enable APT::Force-LoopBreak option in APT to be able to temporarily remove an essential package due to a Conflicts/Pre-Depends loop. apt-get will alert you of this and abort the upgrade. You can work around that by specifying -o APT::Force-LoopBreak=1 option on apt-get command line.

It is possible that a system's dependency structure can be so corrupt as to require manual intervention. Usually this means using dselect or

                 dpkg --remove packagename

to eliminate some of the offending packages, or

                 apt-get --fix-broken --show-upgraded install
                 dpkg --configure --pending

In extreme cases you might have to force re-installation with a command like

                 dpkg --install /path/to/packagename.deb

After fixing things up, you should be able to resume the upgrade by repeating the previously described dist-upgrade commands.

During the upgrade, you will be asked questions to configure or re-configure several packages. When you are asked if any file in the /etc/init.d or /etc/terminfo directories, or the /etc/manpath.config file should be replaced by the package maintainer's version, it's usually necessary to answer `yes' to ensure system consistency. You can always revert to the old versions, since they will be saved with a .dpkg-old extension.

If you're not sure what to do, write down the name of the package or file, and sort things out at a later time. You can search in the typescript file to review the information that was on the screen during the upgrade.

3.5.2 ToDo Before the Next Reboot

When apt-get dist-upgrade has finished, the "formal" upgrade is complete, but there are some other things that should be taken care of before the next reboot.

Most importantly, packages locales and util-linux may need to be installed. This can be done with:

                 apt-get install locales util-linux

If you were upgrading from Debian version 2.0 or earlier, this will remove the getty package, because getty is now in the util-linux package.

There probably are several more packages that need to be installed, that are not noticed by apt-get, because apt-get doesn't automatically select the packages that aren't depended on by other packages (e.g. all packages in Recommends: and Suggests: fields). These can quite easily be found when using dselect or another visual frontend. In dselect, pick the `apt' method in the [A]ccess screen (if you haven't already) and update the database with new packages information, using the [U]pdate option. After that, in the [S]elect screen, press `o', `o', `v' and Shift-d, and then search for the

                 --- Obsolete and local packages present on system ---

header. In that section, all such packages will be shown. For example, the old gimp package has been replaced by gimp1.2. You can either install the new package via dselect (which will then show a ``dependency conflict resolution'' screen indicating that the old packages should be removed), or by using:

                 apt-get install gimp1.2

which will remove the older versions at once (you might just need to confirm).

Another example, that is often not shown even in dselect, are the telnet and talk clients and servers, and the NFS server, which were split off from the old netstd package. You can install them with a command like:

                 apt-get install telnet telnetd talk talkd nfs-server

The same applies to manpages-dev, which was split off from manpages.

Please refer to the Release Notes document for previous releases of Debian GNU/Linux for more information about packages that were split in that release; go back and read Renamed Packages, Section 5.1 and Split Packages, Section 5.2 to see the list of packages split in this release.

If you were upgrading from Debian version 2.0 or earlier, and have the X Window System installed, give the following commands:

                apt-get remove xbase
                apt-get install xfonts-base xfonts-75dpi xfonts-100dpi xfonts-scalable

And if you don't want xdm to start at boot time ("X autostart"), also run:

                apt-get remove xdm

Read /usr/share/doc/xfree86-common/README.Debian-upgrade for more info on the upgrade of the X window system packages. This is relevant for users of all previous Debian releases. In short, you need to read it.

The configuration system for the kernel modules has changed since Debian GNU/Linux release 2.0. If you upgraded from Debian 2.0 or earlier, you must convert your system before the next reboot. Usually running update-modules force will be enough; nevertheless reading the update-modules(8) manual page is recommended.

If you were upgrading from a Debian GNU/Linux version 1.x (i.e. lower than 2.0), the old system was using the `libc5' library, while the upgraded system uses the `libc6' version. The new library has changed the format for the utmp and wtmp files; you can check this by trying the last command. To solve this, a reboot is necessary, but first copy the old file and empty the existing ones, with these commands:

                cd /var/log
                mv wtmp wtmp.libc5
                touch wtmp
                cd /var/run
                cp /dev/null utmp

Then reboot the system (note: this is not necessary for upgrades from Debian release 2.0 and higher!). Once rebooted, the last command will show correct data again.

Note that the Linux kernel was not upgraded by these procedures.You may wish to do so yourself, either by installing one of the kernel-image-* packages or by compiling a customized kernel from sources.

Debian GNU/Linux comes with a 2.2.20 which is in the 2.2 series, the older stable Linux kernel series. You may wish to use a 2.4 series kernel for better hardware support or improved performace. Booting the third cdrom will do this automagically or you can use install a prebuilt one.

                apt-get install kernel-image-2.4.18-{386,586tsc,686}

For the more adventurous, there is an easy way to compile your own custom kernel on Debian GNU/Linux. Install the kernel-package tool and read the documentation in /usr/share/doc/kernel-package.

Enjoy your new Debian GNU/Linux 3.0 system! :-)

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ next ]

Release Notes for Debian GNU/Linux 3.0 (`woody'), Intel x86

$Id: release-notes.en.sgml,v 1.1 2003/01/04 00:37:57 joy Exp $

Josip Rodin, Bob Hilliard, Adam Di Carlo, Anne Bezemer, Rob Bradford (current)