lenny/en/release-notes.dbk

<!DOCTYPE debiandoc PUBLIC "-//DebianDoc//DTD DebianDoc//EN" [
  <!entity % dynamicdata  SYSTEM "../dynamic.ent"       > %dynamicdata;
  <!entity % shareddata   SYSTEM "../release-notes.ent" > %shareddata;
  <!entity docid "$Id: release-notes.en.sgml,v 1.78 2006-11-08 19:53:55 jseidel Exp $">
]>

<!-- Be careful with automatic reformatting. Please note that the indentation
     in examples is used in the output (plus additional space) as well. -->

<debiandoc>
  <book>
  <titlepag>
    <title>Release Notes for &debian; &release; (`&releasename'), &arch-title;</title>
      <author>
        <name>Josip Rodin, Bob Hilliard, Adam Di Carlo, Anne Bezemer, Rob
        Bradford (current), Frans Pop (current)</name><email></email>
      </author>
      <author>
        <name></name><email>debian-doc@lists.debian.org</email>
      </author>
      <version>&docid;</version>
    </titlepag>
    <toc detail="sect1">
      <chapt id="about"><heading>What's new in the Release Notes</heading>

        <p>[The most recent version of this document is always available at
        <url id="&url-release-notes;">. If your version is more than a month
        old, you might wish to download the latest version.]</p>

        <p>Please note that we only support
        and document upgrading from the previous release of Debian (in this case,
        the upgrade from &oldreleasename;). If you need to upgrade from older
        releases, we suggest you read previous editions of the release notes.</p>

<!--
        <sect id="changes"><heading>Changes in the Release Notes</heading> 

          <p>This section lists changes in the Release Notes since the original
          version that was published with &debian; &release;r0. Minor textual
          corrections are omitted.</p>

          <p><list>

            <item><p>Description of change.</p></item>

          </list></p>

        </sect>
-->

      </chapt>

      <chapt id="whats-new"><heading>What's new in &debian; &release;</heading>

        <p>This release adds official support for the AMD64 architecture which
        supports 64-bit processors from both Intel (EM64T) and AMD (AMD64).
        During the previous release, &debian; 3.1 ('sarge'), an unofficial
        version of this port was available. Upgrading from this unofficial
        version should be possible using these Release Notes, but is not
        supported.</p>

        <p>Official support for the Motorola 680x0 ('m68k') architecture has been
        dropped because it did not meet the criteria set by the Debian Release
        Managers. The most important underlying reasons are performance and limited
        upstream support for essential toolchain components. However, the m68k port
        is expected to remain active and available for installation even if not a
        part of this official stable release.</p>

        <p>The following are the officially supported architectures for
        &debian; &releasename;:</p>

        <p>
          <list>
            <item><p>Intel x86 ('i386')</p></item>
            <item><p>Alpha ('alpha')</p></item>
            <item><p>SPARC ('sparc')</p></item>
            <item><p>PowerPC ('powerpc')</p></item>
            <item><p>ARM ('arm')</p></item>
            <item><p>MIPS ('mips' (Big endian) and 'mipsel' (Little endian))</p></item>
            <item><p>Intel Itanium ('ia64')</p></item>
            <item><p>HP PA-RISC ('hppa')</p></item>
            <item><p>S/390 ('s390')</p></item>
            <item><p>AMD64 ('amd64')</p></item>
          </list>
        </p>

          <p>You can read more about port status, and port-specific
          information for your architecture at the <url id="&url-ports;"
          name="Debian port web pages">.</p>

<![ %secondrelease [
          <p>This is only the second official release of &debian; for the
          &arch-title; architecture. We feel that it has proven itself
          sufficiently to be released. However, because it has not had the
          exposure (and hence testing by users) that our releases on
          other architectures have had, you may encounter a few bugs. Please
          use our <url id="&url-bts;" name="bug tracking system"> to report
          any problems; make sure to mention the fact that the bug is on the
          &architecture; platform.</p>
]]>

          <p>&debian; &release; for the &arch-title; architecture ships with
          kernel version &kernelversion;.</p>


        <sect id="newdistro"><heading>What's new in the distribution?</heading> 

<!-- TODO: Numbers need to be updated -->           
           <p>This new release of Debian again comes with a lot more software
           than its predecessor &oldreleasename;; the distribution includes
           over 9000 new packages. Most of the software in the distribution
           has been updated: almost 6500 software packages (this is 73% of
           all packages in &oldreleasename;). Also, a significant number
           of packages have for various reasons been removed from the distribution.
           You will not see any updates for these packages and they will be
           marked as 'obsolete' in package management front-ends.</p>

           <p>With this release &debian; switches from XFree86 to the 7.1
           release of XOrg, which includes support for a greater range of
           hardware and better autodetection. This allows the use of Compiz,
           which is one of the first compositing window managers for the X
           Window System, taking full advantage of hardware
           OpenGL-acceleration for supported devices.</p>

           <p>&debian; again ships with current desktop applications. Amongst
           others it now includes GNOME 2.14, KDE 3.5 and OpenOffice.org 2.0.</p>

           <p><prgn/aptitude/ is the preferred program for package management
           from console.
           It has proven to be better at dependency resolution than <prgn/apt-get/
           <prgn/aptitude/ supports most command line operations of <prgn/apt-get/.
           If you are still using <prgn/dselect/, you should switch to
           <package/aptitude/ as the official frontend for package management.</p>

           <p>The official &debian; distribution now ships on thirteen to fifteen
           binary CDs (depending on the architecture) and a similar number of
           source CDs. A DVD version of the distribution is also available.</p>

        <sect1 id="volatile"><heading>debian-volatile now an official service</heading>

           <p>The <em/debian-volatile/ service that was introduced as an
           unofficial service with the release of &oldreleasename;, has now
           become an official &debian; service.</p>

           <p>This means that it no longer has a <tt/.debian.net/ address,
           but now uses a <tt/.debian.org/ address. Please make sure to update
           your <file>/etc/apt/sources.list</file> accordingly if you were
           already using this service.</p>

           <p><em/debian-volatile/ allows users to easily
           update stable packages that contain information that quickly goes out
           of date. Examples are a virus scanner's signatures list or a spam
           filter's pattern set. For more information and a list of mirrors,
           please see the archive's <url id="&url-debian-volatile"
           name="web page">.</p>

        </sect1>
        </sect>

        <sect id="newinst"><heading>What's new in the installation system?</heading>

<!-- FJP: Maybe a short description of available installation methods could be
          added here: floppy, CD (netinst/business-card/full set), netboot,
          hd-media, USB-stick. -->

        <!-- TODO: Hhhm. Whats new in the installer ? -->
        </sect>

      </chapt>

<!-- TODO: Mention default usage of UTF-8 for new installs -->
      <chapt id="installing"><heading>New installations</heading>

        <p>The installer offers a variety of installation methods. Which methods
        are available to install your system depends on your architecture.</p>

        <p>If you are making a new installation of Debian, you should read
        the Installation Guide, which is available on the Official CD at:

        <example>
/doc/install/manual/<var>language</var>/index.html
        </example>

        or on the Internet from the <url id="&url-install-manual;"
        name="&releasename; release pages">. You may also want to check the
        <url id="&url-installer;index#errata" name="errata"> for
        debian-installer.</p>

<![ %alpha [
        <!-- TODO: Still true? -->
        <p>The installer can only be used to install on alpha systems which
        support the SRM console. Be sure to switch your system to SRM before
        starting the installation. If your machine supports only the AlphaBIOS/ARC
        console, you can still install &releasename; using a (minimal) &oldreleasename;
        installation and a subsequent upgrade. For more information about the
        different consoles please read the references on the
        <url id="http://www.debian.org/ports/alpha" name="Debian alpha port web pages">.
        </p>
]]>

<![ %sparc [ 
      <sect id="sparc_fb"><heading>Issues with framebuffer on &arch-title;</heading>

        <p>Because of display problems on some systems, framebuffer support is
        disabled by default for &arch-title; for most graphics cards. This can
        result in ugly display on systems that do properly support the framebuffer.
        If you see display problems in the installer, you can try booting the installer
        with parameter <tt>debian-installer/framebuffer=true</tt>.
        Please let us know if the framebuffer is not used by default, but works for
        your hardware.</p>

      </sect>
]]>

      <sect id="popcon"><heading>Popularity contest</heading>

        <p>Unlike for the previous release, the installation system will again offer
        to install the <package/popularity-contest/ package.</p>

        <p><package/popularity-contest/ provides the Debian project with valuable information
        on which packages in the distribution are actually used. This information
        is used mainly to decide the order in which packages are included on
        installation CD-ROMs, but is also often consulted by Debian developers
        in deciding whether or not to adopt a package that no longer has a
        maintainer.</p>

        <p>Information from <package/popularity-contest/ is processed anonymously.
        We would appreciate it if you would participate in this official survey;
        you will thereby help improve Debian.</p>

      </sect>
      </chapt>


      <chapt id="upgrading"><heading>Upgrades from previous releases</heading>

<!-- For doc-writers' convenience:
Debian Supported
release: architectures:

1.3.1 or less i386
2.0           i386,m68k
2.1           i386,m68k,alpha,sparc
2.2           i386,m68k,alpha,sparc,powerpc,arm
3.0             + hppa,s390,mips,mipsel,ia64
3.1           i386,m68k,alpha,sparc,powerpc,arm,hppa,s390,mips,mipsel,ia64 (no changes)
4.0           i386,alpha,sparc,powerpc,arm,hppa,s390,mips,mipsel,ia64,amd64
               (+ amd64; - m68k)
-->

        <sect id="backup"><heading>Preparing for the upgrade</heading>

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

          <p>The main things you'll want to back up are the contents of
          <file>/etc</file>, <file>/var/lib/dpkg</file> and the output of
          <tt>dpkg --get-selections "*"</tt> (the quotes are important).</p>

          <p>The upgrade process in itself does not modify anything in the
          <file>/home</file> directory. However, some applications (e.g.
          parts of the Mozilla suite, and the GNOME and KDE desktop
          environments) 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.</p>

          <p>It's wise to inform all users in advance of any upgrades you're
          planning, although users accessing your system via an <prgn/ssh/
          connection should notice little during the upgrade, and should be
          able to continue working. If you wish to take extra precautions, back up or
          unmount users' partitions (<file>/home</file>) before upgrading. A
          reboot will not normally be necessary, unless you also plan to
          upgrade your kernel.</p>

          <!-- TODO: Is not necessary to change the kernel? e.g. udev ? -->

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

          <p><strong/Important!/ You should <em/not/ upgrade using <prgn/telnet/,
          <prgn/rlogin/, <prgn/rsh/, or from an X session managed by <prgn/xdm/,
          <prgn/gdm/ or <prgn/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 <em/inaccessible/ system that is only
          half-upgraded.</p>

          <!-- TODO: surely gdm/kdm are sane? -->

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

        </sect>

        <sect id="system-status">
        <heading>Checking system status</heading>

        <p>The upgrade process described in this chapter has been designed for
        upgrades from "pure" &oldreleasename; systems without 3rd party
        packages. It may be wise to remove these packages first.</p>

        <p>This procedure also assumes your system has been updated to the
        latest point release of &oldreleasename;.  If you have not done this
        or are unsure, follow the instructions in <ref id="old-upgrade">.</p>

        <sect1><heading>Disabling APT pinning</heading>

          <p>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
          <file>/etc/apt/preferences</file>) to allow the upgrade of packages to
          the versions in the new stable release. Further information on APT
          pinning can be found in <manref name="apt_preferences" section="5">.</p>

        </sect1>
        
        <sect1><heading>Checking packages status</heading>

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

          <example>
# dpkg --audit
          </example></p>
 
          <p>You could also inspect the state of all packages on your system
          using <prgn/dselect/, <prgn/aptitude/, or with commands such as

          <example>
# dpkg -l | pager 
          </example>

          or

          <example>
# dpkg --get-selections &gt; ~/curr-pkgs.txt
          </example></p>

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

          <p>Note that <prgn/aptitude/ uses a different method for registering
          packages that are on hold than <prgn/apt-get/ and <prgn/dselect/.
          You can identify packages on hold for <prgn/aptitude/ with

          <example>
# aptitude search "~ahold" | grep "^.h"
          </example></p>

          <p>If you want to check which packages you had on hold for
          <prgn/apt-get/, you should use
          <example>
# dpkg --get-selections | grep hold
          </example></p>

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

          <p>The "hold" package state for <prgn/aptitude/ can be changed using
          (replace <tt/hold/ with <tt/unhold/ to unset the "hold" state):
          <example>
# aptitude hold <var>package_name</var>
          </example>
          </p>

          <p>If there is anything you need to fix, it is best to make sure your
          <file/sources.list/ still refers to &oldreleasename; as explained in
          <ref id="old-sources">.</p>
        </sect1>

        <sect1 id="backports"><heading>Unofficial sources and backports</heading>

          <p>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 <file>/etc/apt/sources.list</file>,
          you should check if that archive also offers packages compiled for
          &releasename; and change the source line accordingly at the same time
          as your source lines for Debian packages.</p>

          <p>Some users may have unofficial backported "newer" versions of
          packages that <em/are/ in Debian installed on their &oldreleasename;
          system. Such packages are most likely to cause problems during an
          upgrade as they may result in file conflicts<footnote>Debian's
          package management system normally does not allow a package to remove
          or replace a file owned by another package; not unless it has been
          defined to replace that package.</footnote>. Section <ref id="trouble">
          has some information on how to deal with file conflicts if they should
          occur.</p>

        </sect1>
        </sect>


        <sect id="upgrade-process"><heading>Preparing sources for APT</heading>

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

          <p><package/apt/ will consider all packages that can be found via
          any "<tt>deb</tt>" 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).</p>

          <p>A release can often be referred to by both its codename (e.g.
          &oldreleasename;, &releasename;) 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.</p>

         <sect1 id="network"><heading>Adding APT Internet sources</heading>

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

<!-- FJP: Why is 'default configuration' relevant here? We are talking about
          upgrading existing installations; we really have no idea what
          apt-sources users will have set up here (maybe just a Woody CD-set).
          Note: D-I sets the default configuration to a mirror based on
          the selected country and not the 'main' servers. -->

           <p>Debian HTTP or FTP mirror addresses can be found at
           <url id="&url-debian-mirrors;"> (look at the "Full list of
           mirrors" section). HTTP mirrors are generally speedier than FTP
           mirrors.</p>

           <p>For example, suppose your closest Debian mirror is
           <tt>&url-debian-mirror-eg;/</tt>. When inspecting that mirror
           with a web browser or FTP program, you will notice that the main
           directories are organized like this:

           <example>
&url-debian-mirror-eg;/dists/&releasename;/main/binary-&architecture;/...
&url-debian-mirror-eg;/dists/&releasename;/contrib/binary-&architecture;/...
           </example></p>

           <p>To use this mirror with <prgn/apt/, you add this line to your
           <file/sources.list/ file:

           <example>
deb &url-debian-mirror-eg; &releasename; main contrib
           </example></p>

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

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

           <p>Any package needed for installation that is fetched from the
           network is stored in <file>/var/cache/apt/archives</file>
           (and the <file>partial/</file> 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.</p>

         </sect1>

         <sect1 id="localmirror"><heading>Adding APT sources for a local mirror</heading>

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

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

           <example>
/var/ftp/debian/dists/&releasename;/main/binary-&architecture;/...
/var/ftp/debian/dists/&releasename;/contrib/binary-&architecture;/...
           </example></p>

           <p>To use this with <prgn/apt/, add this line to your
           <file/sources.list/ file:

           <example>
deb file:/var/ftp/debian &releasename; main contrib
           </example></p>

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

          <p>After adding your new sources, disable the previously
          existing "<tt/deb/" lines in <file/sources.list/, by placing a
          hash sign (<tt/#/) in front of them.</p></sect1>

        <sect1 id="cdroms"><heading>Adding APT source from CD-ROM or DVD</heading>

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

<!-- Default cdrom mount point is /cdrom, not /media/cdrom and fixed!, see #282344
     (but the -d option of apt-cdrom allows scanning from somewhere else) -->
          <p>Make sure there is a line in <file>/etc/fstab</file> that
          enables mounting your CD-ROM drive at the <file>/cdrom</file>
          mount point (the exact <file>/cdrom</file> mount point is required
          for <prgn/apt-cdrom/). For example, if <file>/dev/hdc</file> is
          your CD-ROM drive, <file>/etc/fstab</file> should contain a line
          like:

          <example>
/dev/hdc /cdrom auto defaults,noauto,ro 0 0
          </example></p>

          <p>Note that there must be <em/no spaces/ between the words
          <tt>defaults,noauto,ro</tt> in the fourth field.</p>

          <p>To verify it works, insert a CD and try running

          <example>
# 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
          </example></p>

          <p>Next, run:

          <example>
# apt-cdrom add
          </example>

          for each Debian Binary CD-ROM you have, to add the data about
          each CD to APT's database.</p>
        </sect1>
        </sect>

        <sect id="upgradingpackages"><heading>Upgrading packages</heading>

          <p>The recommended way to upgrade from previous &debian; releases is
          to use the package management tool <prgn>aptitude</prgn>. This program
          makes safer decisions about package installations than running
          <prgn>apt-get</prgn> directly.</p>

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

          <example>
# mount -o remount,rw /<var>mountpoint</var>
          </example></p>

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

          <p>It is strongly recommended that you use the
          <prgn>/usr/bin/script</prgn> 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:

          <example>
# script -a ~/upgrade-to-&releasename;.typescript
          </example>

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

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

          <p>After you have completed the upgrade, you can stop <prgn/script/
          by typing <tt/exit/ at the prompt.</p>

        <sect1 id="updating_lists"><heading>Updating the package list</heading>

          <p>First the list of available packages for the new release needs to
          be fetched. This is done by executing<footnote>We use <prgn/apt-get/
          for this because the &oldreleasename; version <prgn/aptitude/ may fail
          when new sources have been added to <file/sources.list/.</footnote>:</p>

          <p><example>
# apt-get update
          </example></p>

        </sect1>


<!-- FJP: This next section can probably be dropped for etch -->
        <sect1 id="upgrading_aptitude"><heading>Upgrading aptitude</heading>

          <p>Upgrade tests have shown that &releasename;'s version of
          <prgn/aptitude/ is better at solving the complex dependencies during
          an upgrade than either <prgn/apt-get/ or &oldreleasename;'s
          <prgn/aptitude/.

          It should therefore be upgraded first using:
          <example>
# aptitude install aptitude
          </example></p>

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

          <p>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 <package/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 <tt>install aptitude perl</tt>
          instead of <tt>install aptitude</tt>.</p>

        </sect1>

<!-- FJP: This next section can probably be dropped for etch -->
        <sect1 id="upgrading_doc-base"><heading>Upgrading doc-base</heading>

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

          <p><example>
# dpkg -l doc-base
          </example></p>

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

          <p><example>
# aptitude install doc-base
          </example></p>

        </sect1>

        <sect1 id="upgrading_other"><heading>Upgrading the rest of the system</heading>

          <p>You are now ready to continue with the main part of the
          upgrade. Execute:</p>
          <p><example>
# aptitude -f --with-recommends dist-upgrade
          </example></p>

          <p>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 <package>console-tools-libs</package>).</p>

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

          <p>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 <prgn>aptitude</prgn> to choose these
          packages for installation or by trying <tt>aptitude -f install
          <var>package</var></tt>.</p>

          <p>The <tt/--fix-broken/ (or just <tt/-f/) option causes
          <package/apt/ to attempt to correct a system with broken
          dependencies in place. <package/apt/ does not allow broken package
          dependencies to exist on a system.</p>

        </sect1>

        <sect1 id="trouble"><heading>Possible issues during upgrade</heading>

          <p>If an operation using <prgn/aptitude/, <prgn/apt-get/ or
          <prgn/dpkg/ fails with the error
<example>
E: Dynamic MMap ran out of room
</example>
          the default cache space is insufficient. You can solve this by either
          removing or commenting lines you don't need in
          <file>/etc/apt/sources.list</file> or by increasing the cache size.
          The cache size can be increased by setting <tt/APT::Cache-Limit/ in
          <file>/etc/apt/apt.conf</file>. The following command will set it
          to a value that should be sufficient for the upgrade:
<example>
# echo 'APT::Cache-Limit "12500000";' >> /etc/apt/apt.conf
</example>
          This assumes that you do not yet have this variable set in that file.</p>

          <p>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. <prgn/aptitude/ will alert you of
          this and abort the upgrade. You can work around that by specifying
          <tt>-o APT::Force-LoopBreak=1</tt> option on <prgn/aptitude/
          command line.</p>
<!-- JFS: Shouldn't this mention also Apt's configuration file? -->

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

          <example>
# dpkg --remove <var>package_name</var>
          </example>

          to eliminate some of the offending packages, or

          <example>
# aptitude --fix-broken install
# dpkg --configure --pending
          </example></p>

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

          <example>
# dpkg --install <var>/path/to/package_name.deb</var>
          </example></p>

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

          <example>
Unpacking replacement <var>&lt;package-foo&gt;</var> ...
dpkg: error processing <var>&lt;package-name-for-foo&gt;</var> (--unpack):
 trying to overwrite `<var>&lt;some-file-name&gt;</var>',
 which is also in package <var>&lt;package-bar&gt;</var>
          </example></p>

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

          <example>
# dpkg -r --force-depends <var>package_name</var>
          </example></p>

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

          <p>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 <file>/etc/init.d</file> or
          <file>/etc/terminfo</file> directories, or the
          <file>/etc/manpath.config</file> 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 <tt/.dpkg-old/
          extension.</p>

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

        </sect1>
        </sect>

        <sect id="nownownow"><heading>Things to do before rebooting</heading>

          <p>When <tt>aptitude dist-upgrade</tt> has finished, the
          "formal" upgrade is complete, but there are some other things
          that should be taken care of <em/before/ the next reboot.</p>

<!-- TODO: Needs update; we probably need a section about upgrading to XOrg -->
          <p>Read
          <file>/usr/share/doc/xfree86-common/README.Debian-upgrade.gz</file> 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.</p>

        <sect1 id="newkernel"><heading>Upgrading your kernel</heading>

          <p>Note that the Linux kernel was <em/not/ upgraded by these
          procedures. You may wish to do so yourself, either by installing one
          of the <package/linux-image-*/ packages or by compiling a customized
          kernel from sources.</p> 
<!-- JFS: This is not strictly true, if the user was using a non-versioned
  kernel (kernel-image-2.6-686) he _will_ upgrade the kernel if using
  aptitude (post-sarge) -->

<!-- TODO: Needs to be updated
           Mention 2.4 no longer supported; mention rename to linux-*
           Upgrade from 2.6.8 may cause problems -->
<![ %defaulted-2.4 [

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

         <p>However, you are strongly advised <strong/not/ to upgrade to a 2.6
         kernel as part of the upgrade from &oldreleasename; to &releasename;.
         Some issues associated with an upgrade to 2.6 are documented in
         <ref id="upgrade-to-2.6">.</p>
]]>

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

         <example>
# apt-cache search ^linux-image
         </example></p>

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

         <p>For the more adventurous there is an easy way to compile your
         own custom kernel on &debian;. Install the
         <package>kernel-package</package> tool and read the documentation
         in <file>/usr/share/doc/kernel-package</file>.</p>

        </sect1>

<!-- TODO: Replace with #389099 -->
        <sect1 id="mdadm"><heading>Upgrading from raidtools2 to mdadm</heading>

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

         <p>The remainder of this section gives some upgrade hints for users of
         <package/raidtools2/.</p>

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

         <example>
# fdisk -l <var>disk_device</var>
         </example></p>

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

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

         <example>
# echo 'DEVICE /dev/hd*[0-9] /dev/sd*[0-9]' &gt; /etc/mdadm/mdadm.conf
# mdadm --examine --scan &gt;&gt; /etc/mdadm/mdadm.conf
         </example></p>

         <p>These commands will generate a configuration file with the existing
         arrays on the system.</p>

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

        </sect1>
        </sect>

        <sect id="obsolete"><heading>Obsolete packages</heading>

<!-- JFS: Providing a full listing might be useful, especially if we can
point to the Bug that was opened when the bug was removed. This list should
be moved to an appendix, instead of adding it inline as we did in the
potato to woody RN -->

         <p>Introducing several thousand new packages, &releasename; also
         retires and omits more than two thousand old packages that were in
         &oldreleasename;. 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 &releasename;'s
         release<footnote>Or for as long as there is not another release in
         that time frame. Typically only two stable releases are supported
         at any given time.</footnote>, and will not normally provide other
         support in the meantime. Replacing them with available
         alternatives, if any, is recommended.</p>

         <p>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 &releasename; due to bugs in them. In the later case,
         packages might still be present in the "unstable" distribution.</p>

         <p>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 <prgn>aptitude</prgn>, you will see a
         listing of these packages in the "Obsolete and Locally Created
         Packages" entry. <prgn>dselect</prgn> provides a similar section
         but the listing it presents might differ. Also, if you have used
         <prgn>aptitude</prgn> to manually install packages in
         &oldreleasename; 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, <prgn>aptitude</prgn>,
         unlike <prgn>deborphan</prgn> will not mark as obsolete packages
         that you manually installed, as opposed to those that were
         automatically installed through dependencies.</p>

         <p>There are additional tools you can use to find obsolete packages
         such as <prgn>deborphan</prgn>, <prgn>debfoster</prgn> or
         <prgn>cruft</prgn>. <prgn>deborphan</prgn> 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.</p>

<!-- JFS: Should we recommend purging old packages? This might be
dangerous since the maintainer scripts might try to remove stuff that
didn't belong to them... -->

         <p>The <url id="&url-bts;" name="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 <url
         id="&url-bts;cgi-bin/pkgreport.cgi?pkg=ftp.debian.org&#38;archive=yes"
         name="ftp.debian.org pseudo-package">.</p>

        <sect1 id="dummy"><heading>Dummy packages</heading>

<!-- JFS: If the appendix is kept this section should point there and the packages described here should be moved to that section -->

         <p>Some packages from &oldreleasename; have been split into several
         packages in &releasename;, often to improve system maintainability. To
         ease the upgrade path in such cases, &releasename; often provides
         "dummy" packages: empty packages that have the same name as the old
         package in &oldreleasename; 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.

         <p>Most (but not all) dummy packages' descriptions indicate their
         purpose. Package descriptions for dummy packages are not uniform,
         however, so you might also find <prgn>deborphan</prgn> with the
         <tt>--guess</tt> 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.</p>

        </sect1>
        </sect>
      </chapt>

<!-- FJP: Add more info here on dealing with obsolete packages?
          Also how to purge packages that were deleted but still have conffiles
          (use "limit" command in aptitude and search for ~c) -->

        <chapt id="information">
        <heading>Issues to be aware of for &releasename;</heading>

<!-- Controversial, disabled for now, please translate though
        <sect id="german-quotes"><heading>Problems with German Quotes</heading>

          <p>The locales for German style languages (e.g. de_DE@euro)
          unfortunately use an aesthetically unpleasing way of representing
          open quotation marks.  We have retained it this way in order to
          preserve compatibility with other Linux distributions, and we hope
          that in the future it will be fixed. We suggest that you switch to a
          UTF-8 locale (e.g. de_DE@euro.UTF-8), which fully supports German with
          the correct quotation marks, and, using Unicode encoding, has better
          support for other languages as well.</p>

          <p>To change the system wide locale choice, use:
          <example>dpkg-reconfigure locales</example></p>
        </sect>
-->  
<!--   Will be added if relevant information is written here
        <sect id="syntax"><heading>Important program syntax changes</heading>

          <p>Debian attempts to avoid changing upstream packages, therefore
          any changes in the upstream package will be present in the version in
          &debian;. This can mean that program behaviour may change between
          releases of &debian;. </p>

          <p><em>No changes yet reported.</em></p>

        </sect>
-->

<![ %defaulted-2.4 [
        <sect id="upgrade-to-2.6">
        <heading>Upgrading to a 2.6 kernel</heading>

          <p>The 2.6 kernel series contains major changes from the 2.4 series.
          Modules have been renamed and a lot of drivers have been partially
          or sometimes almost completely rewritten. Upgrading to a 2.6 kernel
          from an earlier version is therefore not a process to be undertaken
          lightly. This section aims to make you aware of some of the issues
          you may face.</p>

          <p>You are therefore strongly advised not to upgrade to a 2.6 kernel
          as part of the upgrade from &oldreleasename; to &releasename;.
          Instead, you should first make sure your system works correctly
          with either the old kernel or with a 2.4 kernel from &releasename;
          and do the upgrade to a 2.6 kernel later as a separate project.</p>

          <p>If you compile your own kernel from source, make sure you install
          <package/module-init-tools/ before you reboot with the 2.6 kernel.
          This package replaces <package/modutils/ for 2.6 kernels. If you
          install one of the Debian <package/linux-image/ packages, this
          package will be installed automatically because of dependencies.</p>

          <p>If you use <em/LVM/, you should also install <package/lvm2/
          before you reboot as the 2.6 kernel does not directly support LVM1.
          To access LVM1 volumes, the compatibility layer of <package/lvm2/
          (the dm-mod module) is used. You can leave <package/lvm10/ installed;
          the init scripts will detect which kernel is used and execute the
          appropriate version.</p>

          <p>If you have entries in the <file>/etc/modules</file> file (the
          list of modules to be loaded during system boot), be aware that some
          module names may have changed. If this happens you will have to update
          this file with the new module names.</p>

<![ %i386-amd64 [
          <p>For some SATA disk controllers, the device assigned to a drive and
          its partitions may change from <file>/dev/hdX</file> to
          <file>/dev/sdX</file>. If this happens, you will have to modify your
          <file>/etc/fstab</file> and bootloader configuration accordingly.
          Unless these changes are made correctly, your system may not boot
          correctly.</p>
]]>

          <p>Once you have installed your 2.6 kernel, but before you reboot,
          make sure you have a recovery method. First, make sure that the
          bootloader configuration has entries for both the new kernel and
          the old, working 2.4 kernel. You should also ensure you have a "rescue"
          floppy or cdrom to hand, in case misconfiguration of the bootloader
          prevents you booting the old kernel.</p>

<![ %not-s390 [
<![ %not-amd64 [
        <sect1 id="2.6-keyboard">
        <heading>Keyboard configuration</heading>

          <p>The most invasive change in the 2.6 kernels is a fundamental
          change of the input layer. This change makes all keyboards look
          like "normal" PC keyboards. This means that if you currently have
          a different type of keyboard selected (e.g. a USB-MAC or Sun
          keyboard), you will very likely end up with a non-working keyboard
          after rebooting with the new 2.6 kernel.</p>

          <p>If you can SSH into the box from another system, you can resolve
          this issue by running <tt>dpkg-reconfigure console-data</tt>, choosing
          the option "Select keymap from full list" and selecting a "pc"
          keyboard.</p>

          <p>If your console keyboard is affected, you will probably also need to
          reconfigure your keyboard for the X Window System. You can do this
          either by running <tt>dpkg-reconfigure xserver-xfree86</tt> or by
          editing <file>/etc/X11/XF86Config-4</file> directly. Don't forget
          to read the documentation referred to in <ref id="nownownow">.</p>

<![ %i386 [
          <p>This issue is unlikely to affect the &arch-title; architecture
          as all PS/2 and most USB keyboards will already be configured as
          a "normal" PC keyboard.</p>
]]>
<![ %not-i386 [
          <p>Note that if you are using a USB keyboard, this may be configured
          as either a "normal" PC keyboard or as a USB-MAC keyboard. In the
          first case you will not be affected by this issue.</p>
]]>
        </sect1>
]]> <!-- %not-amd64 -->

        <sect1 id="2.6-mouse">
        <heading>Mouse configuration</heading>

          <p>Again because of the changes in the input layer, you may have to
          reconfigure the X Window System and <package/gpm/ if your mouse is
          not working after upgrading to a 2.6 kernel. The most likely cause is
          that the device which gets the data from the mouse has changed.
          You may also need to load different modules.</p>

<![ %sparc [
          <p>If you currently have X configured for <file>/dev/sunmouse</file>,
          you probably need to change this to <file>/dev/psaux</file>.</p>
]]>

        </sect1>

        <sect1 id="2.6-sound">
        <heading>Sound configuration</heading>

          <p>For the 2.6 kernel series the ALSA sound drivers are recommended
          over the older OSS sound drivers. ALSA sound drivers are provided
          as modules by default. In order for sound to work, the ALSA modules
          appropriate for your sound hardware need to be loaded. In general
          this will happen automatically if you have, in addition to the
          <package>alsa-base</package> package, either the
          <package>hotplug</package> package or the <package>discover</package>
          package installed. The <package>alsa-base</package> package also
          "blacklists" OSS modules to prevent <prgn>hotplug</prgn> and
          <prgn>discover</prgn> from loading them. If you have OSS modules
          listed in <file>/etc/modules</file>, you should remove them.</p>

        </sect1>
]]> <!-- %not-s390 -->

<!-- FJP: May already be covered by kernel team text
          Etch Debian kernels depend on udev via initramfs-tools -->
        <sect1 id="2.6-udev">
        <heading>Switching to 2.6 may activate udev</heading>

        <p><package/udev/ is a userspace implementation of devfs. It is mounted
        over the <file>/dev</file> directory and will populate that directory
        with devices supported by the kernel. It will also dynamically add and
        remove devices as kernel modules are loaded or unloaded respectively,
        working together with <package/hotplug/ to detect new devices.
        <package/udev/ works only with 2.6 kernels.</p>

        <p>As <package/udev/ is automatically installed as a dependency of the new
        default initrd generator used with the 2.6 kernels
        (<package/initramfs-tools/), upgrading to a 2.6 kernel will normally result
        in <package/udev/ being activated.</p>

        <p>Although <package/udev/ has been tested extensively, you may experience
        minor problems with some devices that will need to be fixed. The most
        common problems are changed permission and/or ownership of a device.
        In some cases a device may not be created by default (e.g.
        <file>/dev/video</file> and <file>/dev/radio</file>).</p>

        <p><package/udev/ provides configuration mechanisms to deal with these
        issues. See <manref name="udev" section="8"> and <file>/etc/udev</file>
        for further information.</p>

        </sect1>
        </sect>
]]> <!-- %defaulted-2.4 -->
      </chapt>

      <chapt id="moreinfo">

        <heading>More information on &debian;</heading>

        <sect id="morereading"> <heading>Further reading</heading>
        <p>Beyond these release notes and the installation guide, further
        documentation on &debian; is available from the Debian
        Documentation Project (DDP), whose goal is to create high quality
        documentation for Debian users and developers. Documentation
        including the Debian Guide, Debian New Maintainers Guide, and Debian
        FAQ are available, and many more. For full details of the existing resources
        see the <url id="&url-ddp;" name="DDP website">.</p>

        <p>Documentation for individual packages is installed into
        <file>/usr/share/doc/<var>package</var></file>, this may include
        copyright information, Debian specific details and any upstream
        documentation.</p>

      </sect> 

      <sect id="gethelp"> 
        <heading>Getting help</heading> 

        <p>There are many sources of help, advice and support for Debian
        users, but these should only be considered if research into
        documentation of the issue has exhausted all sources. This section
        provides a short introduction into these which may be helpful for
        new Debian users.</p>

      <sect1 id="lists">
        <heading>Mailing lists</heading>
        <p>The mailing lists of most interest to Debian users are the
        debian-user list (English) and other debian-user-<var/language/ lists
        (for other languages). For information on these lists and details of
        how to subscribe see <url id="&url-debian-list-archives;">. Please
        check the archives for answers to your question prior to posting and
        also adhere to standard list etiquette.</p>
      </sect1>
<!-- TODO: Changed to OFTC -->
      <sect1 id="irc">
        <heading>Internet Relay Chat</heading> 

        <p>Debian has an IRC channel dedicated to the support and aid of
        Debian users located on the OFTC IRC network which exists to
        provide interactive services to peer-directed project communities.
        To access the channel, point your favourite IRC client at
        &debian-irc-server; and join #debian.</p>

        <p>Please follow the channel guidelines, respecting other users
        fully. For more information on OFTC please visit the <url
        id="&url-irc-host;" name="website">.</p>

      </sect1>
      </sect> 

      <sect id="bugs">
        <heading>Reporting bugs</heading>

        <p>We strive to make Debian GNU/Linux a high quality operating
        system, however that does not mean that the packages we provide are
        totally free of bugs.
        Consistent with Debian's "open development" philosophy and as a 
        service to our users, we provide all the information on reported bugs
        at our own Bug Tracking System (BTS). The BTS is browseable at
        <url id="&url-bts;" name="bugs.debian.org">.</p>

        <p>If you find a bug in the distribution or in packaged software
        that is part of it, please report it so that it can be properly
        fixed for next releases. Reporting bugs requires a valid email
        address, we ask for this so that we can trace bugs and developers
        can get in contact with submitters should they need more
        information.</p>

        <p>You can submit a bug report using the program
        <package>reportbug</package> or manually using email. 
        You can read more about the Bug Tracking System and how to use it by
        reading the reference cards (available at
        <file>/usr/share/doc/debian</file> if you have
        <package>doc-debian</package> installed) or online at the
        <url id="&url-bts;" name="Bug Tracking System">.</p>

      </sect>

      <sect id="contributing">
        <heading>Contributing to Debian</heading>

        <p>You do not need to be an expert to contribute to Debian. By
        assisting users with problems on the various user support <url
        id="&url-debian-list-archives;" name="lists"> you are contributing to
        the community. Identifying (and importantly solving) problems
        related to the development of the distribution by participating on
        the development <url id="&url-debian-list-archives;" name="lists"> is
        also extremely helpful. To maintain Debian's high quality
        distribution <url id="&url-bts;" name="submit bugs">
        and help developers track them down and fix them. If you have a way
        with words then you may want to contribute more actively by helping
        to write <url id="&url-ddp;"
        name="documentation"> or <url
        id="&url-debian-i18n;" name="translate"> existing
        documentation into your own language.</p>

        <p>If you can dedicate more time, you could manage a piece of the
        Free Software collection within Debian. Especially helpful is if
        people adopt or maintain items that people have requested for
        inclusion within Debian, the <url id="&url-wnpp;" name="Work Needing
        and Prospective Packages database"> details this information. If you
        have an interest in specific groups then you may find enjoyment in
        contributing to some of Debian's subprojects which include ports to
        particular architectures, <url id="&url-debian-jr;" name="Debian
        Jr."> and <url id="&url-debian-med;" name="Debian Med">.</p>

        <p>In any case, if you are working in the free software community in
        any way, as a user, programmer, writer or translator you are already
        helping the free software effort. Contributing is rewarding and fun,
        and as well as allowing you to meet new people it gives you that
        warm fuzzy feeling inside.</p></sect>

    </chapt>

<!-- This may or may not still be useful -->
    <appendix id="old-stuff">
    <heading>Managing your &oldreleasename; system</heading>

       <p>This appendix contains information on how to make sure you can install
       or upgrade &oldreleasename; packages before you upgrade to &releasename;.
       This should only be necessary in specific situations.</p>

       <sect id="old-upgrade">
       <heading>Upgrading your &oldreleasename; system</heading>

          <p>Basically this is no different than any other upgrade of
          &oldreleasename; you've been doing. The only difference is that you
          first need to make sure your package list still contains
          &oldreleasename; packages as explained in <ref id="old-sources">.</p>

       </sect>

       <sect id="old-sources">
       <heading>Checking your sources list</heading>

          <p>If any of the lines in your <file>/etc/apt/sources.list</file>
          refer to 'stable', you are effectively already "using" &releasename;.
          If you have already run <tt>apt-get update</tt>, you can still get
          back without problems following the procedure below.</p>

          <p>If you have also already installed packages from &releasename;,
          there probably is not much point in installing packages from
          &oldreleasename; anymore. In that case you will have to decide for
          yourself whether you want to continue or not. It is possible to
          downgrade packages, but that is not covered here.</p>

          <p>Open the file <file>/etc/apt/sources.list</file> with your favorite
          editor (as root) and check all lines beginning with <tt>deb http:</tt>
          or <tt>deb ftp:</tt> for a reference to "<tt/stable/". If you find any,
          change <tt/stable/ to <tt/&oldreleasename;/.</p>

          <p>If you have any lines starting with <tt>deb file:</tt>, you will
          have to check for yourself if the location they refer to contains
          a &oldreleasename; or a &releasename; archive.</p>

          <p><strong/Important!/ Do not change any lines that begin with
          <tt>deb cdrom:</tt>. Doing so would invalidate the line and you would
          have to run <prgn/apt-cdrom/ again. Do not be alarmed if a 'cdrom' source
          line refers to "<tt/unstable/". Although confusing, this is normal.</p>

          <p>If you've made any changes, save the file and execute

          <example>
# apt-get update
          </example>

          to refresh the package list.</p>

       </sect>

    </appendix>

  </book>
</debiandoc>

<!-- Keep this comment at the end of the file
Local Variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:nil
sgml-declaration:nil
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
fill-column: 75
End:
-->