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

Release Notes for Debian GNU/Linux 3.1 (`sarge'), Alpha
Chapter 4 - Upgrades from previous releases

4.1 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 "*" (the quotes are important).

The upgrade process in itself does not modify anything in the /home directory. However, some applications (e.g. Mozilla, some KDE applications) are known to overwrite existing user settings with new defaults when a new version of the application is first started by a user. As a precaution, you may want to make a backup of the hidden files and directories ("dotfiles") in users' home directories. This backup may help to restore or recreate the old settings. You may also want to inform users about this issue.

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, unless you plan to also upgrade your kernel.

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, gdm or kdm etc 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.

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.

4.2 Checking system status

The upgrade process described in this chapter has been designed for upgrades from "pure" woody systems. It assumes your system has been updated to the latest point release of woody. If you have not or are unsure, follow the instructions in Upgrading your woody system, Section A.1.

It also assumes you have the woody version of aptitude installed. You can check if it is installed using

     $ dpkg -l aptitude

If the line of output does not begin with "i", you should install it before you start the upgrade using the instructions in Installing woody version of aptitude, Section A.2.

4.2.1 Disabling APT pinning

If you have configured APT to install certain packages from a distribution other than stable (e.g. from testing), you may have to change your APT pinning configuration (stored in /etc/apt/preferences) to allow the upgrade of packages to the versions in the new stable release. Further information on APT pinning can be found in apt_preferences(5).

4.2.2 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, aptitude, 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. Note that aptitude uses a different method for registering packages that are on hold than apt-get and dselect. You can identify packages on hold for aptitude with

     # aptitude search "~ahold" | grep "^.h"

If you want to check which packages you had on hold for apt-get, you should use

     # dpkg --get-selections | grep hold

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 for aptitude can be changed using (replace hold with unhold to unset the "hold" state):

     # aptitude hold package_name

If there is anything you need to fix, it is best to make sure your sources.list still refers to woody as explained in Checking your sources list, Section A.3.

4.2.3 Unofficial sources and backports

If you have any non-Debian packages on your system, you should be aware that these may be removed during the upgrade because of conflicting dependencies. If these packages were installed by adding an extra package archive in your /etc/apt/sources.list, you should check if that archive also offers packages compiled for sarge and change the source line accordingly at the same time as your source lines for Debian packages.

Some users may have unofficial backported "newer" versions of packages that are in Debian installed on their woody system. Such packages are most likely to cause problems during an upgrade as they may result in file conflicts[1]. Section Possible issues during upgrade, Section 4.4.5 has some information on how to deal with file conflicts if they should occur.

4.3 Preparing sources for APT

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

A release can often be referred to by both its codename (e.g. woody, sarge) and by its status name (i.e. oldstable, stable, testing, unstable). Referring to a release by its codename has the advantage that you will never be surprised by a new release and for this reason is the approach taken here. It does of course mean that you will have to watch out for release announcements yourself. If you use the status name instead, you will just see loads of updates for packages available as soon as a release has happened.

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

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 sarge 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 /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.

4.3.2 Adding APT sources for a local mirror

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 mounted over NFS).

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

4.3.3 Adding APT source from CD-ROM or DVD

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.

4.4 Upgrading packages

The recommended tool for upgrading between Debian GNU/Linux releases is to use the package management tool aptitude. This tool makes safer decisions about package installations than running apt-get directly.

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

Next you should double check that the APT source entries (in /etc/apt/sources.list) refer either to "sarge" or to "stable". Note: source lines for a CD-ROM will often refer to "unstable"; although this may be confusing, you should not change it.

It is strongly recommended that you use the /usr/bin/script program to record a transcript of the upgrade session. Then if a problem occurs, 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-sarge.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).

The typescript will also allow you to review information that has scrolled off-screen. Just switch to VT2 (using Alt-F2) and, after logging in, use less ~root/upgrade-to-sarge.typescript to view the file.

After you have completed the upgrade, you can stop script by typing exit at the prompt.

4.4.1 Updating the package list

First the list of available packages for the new release needs to be fetched. This is done by executing[2]:

     # apt-get update

4.4.2 Upgrading aptitude

Upgrade tests have shown that sarge's version of aptitude is better at solving the complex dependencies during an upgrade than either apt-get or woody's aptitude. It should therefore be upgraded first using:

     # aptitude install aptitude

You will be shown a list of the changes that will be made and asked you to confirm them. You should take a careful look at the proposed changes, especially packages that will be removed by the upgrade, before you confirm.

In some cases if a large number of packages is listed for removal, you may be able to reduce this list by "pre-upgrading" selected other packages alongside aptitude. An example may clarify this. During upgrade tests for systems having KDE installed, we have seen that this step would cause removal of a large number of KDE packages and/or perl. The solution proved to be to install aptitude perl instead of install aptitude.

4.4.3 Upgrading doc-base

If you have doc-base installed, it must be upgraded before the rest of the system too. Reason is that it may fail if perl is upgraded at the same time. You can find out if it is installed using:

     # dpkg -l doc-base

If the line of output begins with "i" then it is installed and must be upgraded before continuing.

     # aptitude install doc-base

4.4.4 Upgrading the rest of the system

You are now ready to continue with the main part of the upgrade. Execute:

     # aptitude -f --with-recommends 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 (such as console-tools-libs).

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"). This can be resolved by either using aptitude to choose these packages for installation or by trying aptitude -f install package.

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.

4.4.5 Possible issues during upgrade

If an operation using aptitude, apt-get or dpkg fails with the error

     E: Dynamic MMap ran out of room

the default cache space is insufficient. You can solve this by either removing or commenting lines you don't need in /etc/apt/sources.list or by increasing the cache size. The cache size can be increased by setting APT::Cache-Limit in /etc/apt/apt.conf. The following command will set it to a value that should be sufficient for the upgrade:

     # echo 'APT::Cache-Limit "12500000";' >> /etc/apt/apt.conf

This assumes that you do not yet have this variable set in that file.

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. aptitude will alert you of this and abort the upgrade. You can work around that by specifying -o APT::Force-LoopBreak=1 option on aptitude command line.

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

     # dpkg --remove package_name

to eliminate some of the offending packages, or

     # aptitude --fix-broken install
     # dpkg --configure --pending

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

     # dpkg --install /path/to/package_name.deb

File conflicts should not occur if you upgrade from a "pure" woody system, but can occur if you have unofficial backports installed. A file conflict will result in an error like:

     Unpacking replacement <package-foo> ...
     dpkg: error processing <package-name-for-foo> (--unpack):
      trying to overwrite `<some-file-name>',
      which is also in package <package-bar>

You can try to solve a file conflict by forcibly removing the package mentioned on the last line of the error message:

     # dpkg -r --force-depends package_name

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

During the upgrade, you will be asked questions regarding the configuration or re-configuration of 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.

4.5 Things to do before rebooting

When aptitude 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.

Read /usr/share/doc/xfree86-common/README.Debian-upgrade.gz 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.

4.5.1 Upgrading your kernel

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.

If you are currently using a kernel from the 2.4 series, the older stable Linux kernel series, you may wish to upgrade to a 2.6 series kernel for better hardware support or improved performance.

However, you are strongly advised not to upgrade to a 2.6 kernel as part of the upgrade from woody to sarge. Some issues associated with an upgrade to 2.6 are documented in Upgrading to a 2.6 kernel, Section 5.2.

To upgrade your kernel you must first choose the kernel most appropriate for your subarchitecture. A list of kernels available for you to install can be found with:

     # apt-cache search ^kernel-image

You should then use aptitude install to install it. Once this new kernel is installed you should reboot at the next available opportunity to get the benefit.

Please note that the installation system of woody (and previous releases) did not install the kernel as a package in your system. This has changed in sarge and you can install virtual packages to keep track of kernel changes. These packages are named kernel-image-VERSION-ARCH, with VERSION corresponding to the kernel version number (2.4 or 2.6) and ARCH corresponding to any of the supported architectures. If you want to have security support for the kernel integrated in package management please install the kernel package most suitable for your hardware after the upgrade.

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.

4.5.2 Upgrading from raidtools2 to mdadm

raidtools2 is no longer maintained by its upstream developers and has been replaced by the mdadm package. mdadm is a single program that can perform almost any RAID management task without a configuration file; by default it does not use one.

The remainder of this section gives some upgrade hints for users of raidtools2.

As mentioned above, in many cases mdadm can work without configuration file. If you use a kernel that automatically configures the RAID array for you, can skip this paragraph — you merely have to install the package mdadm and the RAID will be detected during the boot process. The standard kernels in Debian have support for the configuration of RAID arrays on boot. You also need to make sure that the partitions are set to type "Linux raid autodetect" (id fd). The following command will list the current type of partitions:

     # fdisk -l disk_device

If you have a mixed setup with some RAID arrays that are auto-configured and some that are not, you have to create a configuration file.

To migrate from the configuration file /etc/raidtab (raidtools2) to /etc/mdadm/mdadm.conf (mdadm), please execute:

     # echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' > /etc/mdadm/mdadm.conf
     # mdadm --examine --scan >> /etc/mdadm/mdadm.conf

These commands will generate a configuration file with the existing arrays on the system.

You should also make sure that the RAID arrays are started automatically on boot. Check the file /etc/default/mdadm to see if the variable AUTOSTART is set to true.

4.6 Obsolete packages

Introducing several thousand new packages, sarge also retires and omits more than two thousand old packages that were in woody. It provides no upgrade path for these obsolete packages. While nothing prevents you from continuing to use an obsolete package where desired, the Debian project will usually discontinue security support for it a year after sarge's release[3], and will not normally provide other support in the meantime. Replacing them with available alternatives, if any, is recommended.

There are many reasons why packages might have been removed from the distribution: they are no longer maintained upstream; there is no longer a Debian Developer interested in maintaining the packages; the functionality they provide has been superseded by different software (or a new version); or they are no longer considered suitable for sarge due to bugs in them. In the later case, packages might still be present in the "unstable" distribution.

Detecting which packages in an updated system are "obsolete" is easy since the package management front-ends will mark them as such. If you are using aptitude, you will see a listing of these packages in the "Obsolete and Locally Created Packages" entry. dselect provides a similar section but the listing it presents might differ. Also, if you have used aptitude to manually install packages in woody it will have kept track of those packages you manually installed and will be able to mark as obsolete those packages pulled in by dependencies alone which are no longer needed if a package has been removed. Also, aptitude, unlike deborphan will not mark as obsolete packages that you manually installed, as opposed to those that were automatically installed through dependencies.

There are additional tools you can use to find obsolete packages such as deborphan, debfoster or cruft. deborphan is highly recommended, although it will (in default mode) only report obsolete libraries: packages in the "libs" or "oldlibs" sections that are not used by any other packages. Do not blindly remove the packages these tools present, especially if you are using aggressive non-default options that are prone to produce false positives. It is highly recommended that you manually review the packages suggested for removal (i.e. their contents, size and description) before you remove them.

The Debian Bug Tracking System often provides additional information on why the package was removed. You should review both the archived bug reports for the package itself and the archived bug reports for the ftp.debian.org pseudo-package.

4.6.1 Dummy packages

Some packages from woody have been split into several packages in sarge, often to improve system maintainability. To ease the upgrade path in such cases, sarge often provides "dummy" packages: empty packages that have the same name as the old package in woody with dependencies that cause the new packages to be installed. These "dummy" packages are considered obsolete packages after the upgrade and can be safely removed.

Most (but not all) dummy packages' descriptions indicate their purpose. Package descriptions for dummy packages are not uniform, however, so you might also find deborphan with the --guess options useful to detect them in your system. Note that some dummy packages are not intended to be removed after an upgrade but are, instead, used to keep track of the current available version of a program over time.

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

Release Notes for Debian GNU/Linux 3.1 (`sarge'), Alpha

$Id: release-notes.en.sgml,v 1.71 2006/09/18 13:21:10 fjp Exp $

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