release-notes/en/release-notes.en.sgml

<!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.110 2006-11-30 01:25:19 fjp 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), Andreas Barth (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>Introduction</heading>

        <p>The primairy goals of these Release Notes are to inform users
        of major changes in this release of the Debian distribution, to
        provide information on how to upgrade safely from the previous
        to the this release and finally to inform users of known potential
        issues users could encounter when upgrading to or using the
        release.</p>

        <p>Note that it is impossible to list every known issue and that
        therefore a selection has been made based on a combination of the
        expected prevalence and impact of issues.</p>

        <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>TODO: Update numbers</p>
           <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="inst-new"><heading>What's new in the installation system?</heading>

        <!-- TODO: Hhhm. Whats new in the installer ? -->
           <p>There has been a lot of development on the Debian Installer
           since its first official release with &oldreleasename; resulting
           in both improved hardware support and some exciting new features.</p>

           <p>In these Release Notes we'll only list the major changes in the
           installer. If you are interested in an overview of the detailed
           changes since &oldreleasename;, please check the release announcements
           for the &releasename; beta and RC releases avaiable from the project's
           <url id="&url-installer-news" name="news history">.</p>

         <sect1 id="inst-changes"><heading>Major changes</heading>

           <p><taglist>
             <tag>No reboot during the installation</tag>
             <item><p>The installation used to be split into two parts:
             setting up the base system and making it bootable, followed
             by a reboot and after that the execution of <prgn/base-config/
             which would take care of things like user setup, setup of the
             package management system and installation of additional
             packages (using tasksel).</p>
             <p>For &releasename; the second stage has been integrated into
             Debian Installer itself. This has a number of advantages,
             including increased security and the fact that after the reboot
             at the end of the installation the new system should already have
             the correct timezone and, if you installed the Desktop environment,
             will at once start the graphical user interface.</p></item>

             <tag>UTF-8 encoding default for new systems</tag>
             <item><p>The installer will set up systems to use UTF-8 encoding
             rather than the old language-specific encodings (like ISO-8859-1,
             EUC-JP or KIO-8).</p></item>

             <tag>More flexible partitioning</tag>
             <item><p>It is now possible to set up file systems on an LVM volume
             using guided partitioning.</p>
             <p>The installer is also able to set up encrypted filesystems.
             Using manual partitioning you have the choice between <tt/dm-crypt/
             and <tt/loop-aes/, using a passphrase or a random key, and you can
             tune various other options. Using guided partitioning, the installer
             will create an encrypted LVM partition that contains any other
             filesystems (except <file>/boot</file>)as logical volumes.</p></item>

<![ %i386-amd64 [
             <tag>Graphical user interface</tag>
             <item><p>If you prefer a graphical user interface, try booting the
             the installer with <tt/installgui/.</p>
             <p>The functionality of the graphical installer is almost identical
             to the regular installer, only the presentation differs. There is one
             exception: the graphical frontend does not support setting up
             encrypted partitions using random keys.</p>
             <p>Note: the graphical user interface is not available for all
             architectures.</p></item>
]]>

<![ %powerpc [
             <tag>Graphical user interface</tag>
             <item><p>For &arch-title; a separate installation image using a
             graphical user interface is available on an experimental basis.
             It is known to work on most CHRP systems that have an ATI graphics
             card, but has been insufficiently tested on &arch-title; to include
             it on the normal installation CDs.</p>
             <p>If you'd like to try the graphical installer, look for the
             "gtk-miniiso" image.</p></item>
]]>

             <tag>Rescue mode</tag>
             <item><p>You can use the installer to solve problems with your
             system, for example when it refuses to boot. The first steps will
             be just like a regular installation, but the installer will not
             start the partitioner. Instead it will offer you a menu of rescue
             options.</p>
             <p>Activate the rescue mode by booting the installer with
             <tt/rescue/, or by adding a boot parameter
             <tt>rescue/enable=true</tt>.</p></item>

             <tag>Using sudo instead of root account</tag>
             <item><p>During expert installations you can choose to not
             set up the root account (it will be locked), but instead set
             up <prgn/sudo/ so that the first user can use that for
             system administration.</p></item>

<!-- FIXME: Bug Manoj for a link to documentation on enabling SELinux -->
             <tag>SELinux</tag>
             <item><p>The packages needed for SELinux support have been
             promoted to priority "standard". This means that they will be
             installed by default if you select the Standard task during
             installation. However, SELinux support is not enabled by default.
             If you want to secure your system using SELinux, you will need
             to enable it manually after the installation.</p></item>

<![ %not-s390 [
             <tag>New languages</tag>
             <item><p>Thanks to the huge efforts of translators, Debian can
             now be installed in up to $FIXME$ languages.
<![ %g-i [
             If the graphical user interface is used, an additional $FIXME$
             languages are supported.
]]>
             </p></item>
]]> <!-- not-s390 -->

           </taglist></p>
         </sect1>

         <sect1 id="inst-auto"><heading>Automated installation</heading>

           <p>A lot of the changes mentioned in the previous section also
           imply changes in the support in the installer for automated
           installation using preconfiguration files. This means that if
           you have existing preconfiguration files that worked with the
           &oldreleasename; installer, you cannot expect these to work
           with the new installer without modification.</p>

           <p>The good news is that the <url id="url-install-manual"
           name="Installation Guide"> now has a separate appendix with
           extensive documentation on using preconfiguration.</p>

           <p>The &releasename; installer introduces some exciting new
           features that allow futher and easier automation of installs.
           It also adds support for advanced partitioning using RAID, LVM
           and encrypted LVM. See the documentation for details.</p>

         </sect1>
        </sect>

      </chapt>

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

        <p>The Debian Installer is the official installation system for Debian.
        It offers a variety of installation methods. Which methods
        are available to install your system depends on your architecture.</p>

        <p>Images of the installer for &releasename; and the Installation Guide
        can be found on the <url id="&url-installer;" name="Debian website">.</p>

        <p>The Installation Guide is also included on the first CD/DVD of the
        official Debian CD/DVD sets, at:

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

        <p>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 the parameter <tt>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>We suggest that before upgrading you also read the information in
          <ref id="information">. That chapter covers potential issues not
          directly related to the upgrade process but which could still be
          relevant.</p>

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

          <p>The upgrade has a few preconditions; you should check them
          before actually executing the upgrade.</p>

       <sect1><heading>Make sure you have sufficient space for the upgrade</heading>

       <p>You have to make sure before upgrading your system that you have
       sufficient hard disk space when you start the full system upgrade
       described in <ref id="upgrading_other">. You will first need
       enough hard disk on the filesystem partition that holds <file>/var/</file> 
       to temporarily download the packages that will be installed in your system.
       After the download, you will probably need more space in other 
       filesystem partitions in order to both install upgraded packages (which
       might contain bigger binaries or more data) and new packages that will be pulled
       in for the upgrade. If your system does not have sufficient space you
       might end up with an incomplete upgrade that might be difficult to 
       recover from.</p>

<!-- JFS: Apt will not always abort if you do not have enough disk space. 
       For reference see: #247331, #214119, #192146, #185201, #40438 and #32919 -->

       <p>Both <prgn/aptitude/ and <prgn/apt/ will show you detailed information
       of the disk space needed for the installation. You can see this estimate
       before executing the actual upgrade running:
       </p>

         <p><example>
# aptitude -y -s -f --with-recommends dist-upgrade
[ ... ]
XXX upgraded, XXX newly installed, XXX to remove and XXX not upgraded.
Need to get xx.xMB/yyyMB of archives. After unpacking AAAMB will be used.
Would download/install/remove packages.
</example></p>
       

       <p>If you do not have enough space for the upgrade, make sure you free up
       space beforehand. You can:
       </p>
       
<!-- JFS There are more tips at 
       http://lists.debian.org/debian-user/2005/11/msg02078.html
       or      
       http://www.debian-administration.org/articles/143
       but maybe that should be in the Debian Reference best and pointed from here -->
       <p>
       <list>
<!-- JFS: Does aptitude to 'apt-get autoclean' by itself? -->
       <item>Remove packages that have been previously downloaded for
       installation (at <file>/var/cache/apt/archive</file>), cleaning up the
       package cache by running <prgn>apt-get clean</prgn>.

<!-- JFS Point to http://www.enricozini.org/blog/eng/pkgsizestat.html ?
     Enrico's script shows files that occupy space in a given partition
     which might be good for systems that are heavily partitioned -->

       <item>Remove old packages you no longer use. If you have
       <prgn/popularity-contest/  installed you can use
       <prgn/popcon-largest-unused/ to list the packages you do not use in the
       system that occupy the most space. You can also use <prgn/deborphan/
       or <prgn/debfoster/ to find obsolete packages (see 
       <ref id="obsolete">)
       
       <item>Remove packages that take up too much space and you do not 
       have an immediate need for (you can always reinstall them after the
       upgrade). You can list packages that take up most of the disk space
       with <prgn/dpigs/ (available in the  <prgn/debian-goodies/ package)
       or with <prgn/wajig/ (running <prgn>wajig size</prgn>).
       
       <item>Temporarily move to another system, or permanently remove, system
       logs residing under <file>/var/log/</file>.

       </list></p>
        </sect1>

        <sect1 id="glibc-kernel"><heading>Support for 2.2-kernels has been dropped</heading>
          <p>In case you run a kernel prior to 2.4.1,
          you need to upgrade to (at least) the
          2.4-series before upgrading the <package/glibc/, which means:
          best before starting with the upgrade.
          It is recommended to upgrade to the 2.6-kernel series.          
        </sect1>

        <sect1 id="kernelorder"><heading>Upgrade your kernel or userland first?</heading>
<!-- TODO: remove this section, it is just that one can see "needs to be done" on the normal output -->
          <p>[FIXME: Needs decision/documentation whether to upgrade userland or kernel first.]</p>
        </sect1>

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

        <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="newkernel"><heading>Upgrading your kernel and related
        packages</heading>

          <p>You should upgrade the Linux kernel separately from the rest of
          your packages.
<!-- TODO: add something in "before you upgrade", and get the order right -->
          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.
          Please read the information in this section about potential issues
          with kernel upgrades.</p> 

          <p>All Linux kernel packages have been renamed from <tt/kernel-*/ to
          <tt/linux-*/ to clean up the namespace.</p>

<![ %defaulted-2.4 [
          <p>If you are currently using a kernel from the 2.4 series,
          the older stable Linux kernel series, you should upgrade to a 2.6
          series kernel, as 2.4 is no longer supported in %releasename;.
          If you are currently using a kernel from the 2.2 series, you 
          must upgrade to (at least) the 2.4 series, better to a 2.6 series
          kernel prior to upgrading your packages.
<!-- TODO: incoporate this part in this section -->
          Some general issues associated with an upgrade to 2.6 are documented
          in <ref id="upgrade-to-2.6">.</p>
]]>

        <sect1><heading>initrd-tools deprecated</heading>
          <p><package/initrd-tools/ is no longer supported and has been
          superseded by <package/initramfs-tools/ and <package/yaird/.
          Upgrading to an &releasename; kernel will cause
          <package/initramfs-tools/ to be installed by default.
<![ %defaulted-2.4 [
          If you are upgrading from a 2.4 kernel to a 2.6 kernel for the
          first time, you must use <package/initramfs-tools/. Using
          <package/yaird/ will cause linux-image-2.6 installations to
          fail if you are running a 2.2 or 2.4 kernel.
]]>
          </p>
        </sect1>

        <sect1><heading>devfs deprecated</heading>
          <p>&releasename; no longer provides support for <prgn>devfs</prgn>.
          It is recommended that users switch to udev for dynamic
          <file>/dev</file> management.
          Debian kernels no longer include support for <prgn>devfs</prgn>,
          so <prgn>devfs</prgn> users will need to manually convert their
          systems before upgrading to an &releasename; kernel.</p>

          <p>If you see the string 'devfs' in <file>/proc/mounts</file>,
          you are likely using devfs.
          Any config files that reference devfs style names will need to be
          adjusted to use udev style names. Files that are most likely to
          refer to devfs style device names include <file>/etc/fstab</file>,
          <file>/etc/lilo.conf</file>, <file>/boot/grub/menu.lst</file>, etc.</p>

          <p>More information about potential issues is available in bug report
          <url id="http://bugs.debian.org/341152" name="#351152">.</p>
        </sect1>

<![ %i386-amd64-ia64 [
        <sect1><heading>Standard kernels contain SMP abilities</heading>
          <p>Multiprocessor systems no longer require a *-smp flavour of the
          Linux kernel. For &arch-title; linux-image packages without the -smp
          suffix support both uniprocessor and multiprocessor systems.</p>
        </sect1>
]]>

<![ %i386 [
        <sect1><heading>386 kernel flavour deprecated</heading>
          <p>Support for the 80386 sub-archicture for &arch-title; has been dropped
          in &releasename;.  The 386 kernel flavor is no longer supported and has been
          replaced by the new 486 flavour.</p>
        </sect1>
]]>
          
        <sect1><heading>Device enumeration reordering</heading>
          <p>&releasename; features a more robust mechanism for hardware discovery
          than previous releases. However, this may cause changes in the
          order devices are discovered on your system affecting the order
          in which device names are assigned.
          For example, if you have two network adapters that are associated
          with two different drivers, the devices eth0 and eth1 refer to
          may be swapped.
          Please note that the new mechanism means that if you e.g. exchange
          ethernet adapters in a running &releasename; system, the new adapter
          will also get a new interface name.</p>

          <p>For network devices, you can avoid this reordering by using the
          <prgn>ifrename</prgn> utility to bind physical devices to
          specific names at boot time.
<!-- TODO: add ifupdown-scripts-zg2 as well here? -->
          See <manref name="ifrename" section="8"> and <manref name="iftab"
          section="5"> for more information.</p>

<!-- TODO:
          *** maks: please review the initramfs stuff for accuracy - I'm going
          ***       by what I remember, and haven't tested this recently
          -->
          <p>For storage devices, you can avoid this reordering by using
          <package/initramfs-tools/ and configuring it to load storage device
          driver modules in the same order they are currently loaded.
          To do this, identify the order the storage modules on your system
          were loaded by looking at the output of <prgn/lsmod/.
          <prgn/lsmod/ lists modules in the reverse order that they were loaded
          in, i.e., the first module in the list was the last one
          loaded.</p>

          <p>However, removing and reloading modules after initial boot
          will affect this order. Also, your kernel may have some drivers
          linked statically, and these names will not appear in the output
          of <prgn>lsmod</prgn>. You may be able to decipher these driver
          names and load order from looking at
          <file>/var/log/kern.log</file>, or the output of
          <prgn>dmesg</prgn>.</p>

          <p>Add these module names to <file>/etc/initramfs-tools/modules</file>
          in the order they should be loaded at boottime. Some module names may
          have changed between &oldreleasename; and &releasename;. For
          example, sym53c8xx_2 has become sym53c8xx.</p>

          <p>You will then need to regenerate your initramfs image(s) by
          executing <tt>update-initramfs -k all</tt>.</p>

          <p>Once you are running an &releasename; kernel and <prgn/udev/, you may
          reconfigure your system to access disks by an alias that is not
          dependent upon driver load order. These aliases reside in the
          <file>/dev/disk/</file> hierarchy.</p>
        </sect1>

<![ %ia64 [
        <sect1><heading>Serial device reordering</heading>
          <p>If you have an HP machine and you're using the MP serial
          console port (the connector labelled "console" on the 3-headed
          cable), this kernel upgrade will break your console!</p>

          <p>Please read the following information before upgrading.</p>

          <p><list>
          <item><p>The console device will change from <file>ttyS0</file> to
           <file>ttyS1</file>, <file>ttyS2</file>, or <file>ttyS3</file> so
            <list>
            <item><p>Edit <file>/etc/inittab</file> to add a getty entry for
             <file>/dev/ttyS1</file> (rx4640, rx5670, rx7620, rx8620, Superdome),
             <file>/dev/ttyS2</file> (rx1600), or
             <file>/dev/ttyS3</file> (rx2600).</p></item>
            <item><p>Edit <file>/etc/securetty</file> to add
             <file>ttyS1</file>, <file>ttyS2</file>, or
             <file>ttyS3</file>.</p></item>
            <item><p>Leave the existing <file>ttyS0</file> entries in
             <file>/etc/inittab</file> and <file>/etc/securetty</file> so
             you can still boot old kernels.</p></item>
            </list>
          </p></item>

          <item><p>Edit <file>/etc/elilo.conf</file> to remove any "console="
           arguments.</p></item>

          <item><p>Run <prgn/elilo/ to install the bootloader with new
           configuration.</p></item>

          <item><p>Reboot and use the EFI boot option maintenance menu to
           select exactly one device for console output, input, and standard
           error.  Then do a cold reset so the changes take
           effect.</p> 
          
           <p>For the MP console, be careful to select the device with
           "Acpi(HWP0002,700)/Pci(...)/Uart" in the path.</p></item>
          </list></p>

          <p>More details about these changes and troubleshooting hints are
          available at
          <url id="http://lists.debian.org/debian-ia64/2005/01/msg00008.html">.</p>

        </sect1>
]]>

        <sect1><heading>Upgrading the kernel</heading>
          <p>When you dist-upgrade from &oldreleasename; to &releasename;,
          it is strongly recommended that you install a new
          linux-image-2.6-* metapackage.
          This package may be installed automatically by the dist-upgrade
          process. You can verify this by running:
          <example>
# dpkg -l | grep '^ii  linux-image'
          </example></p>

          <p>If you do not see any output, then you will need to install a
          new linux-image package by hand. To see a list of available
          linux-image-2.6 metapackages, run:
          <example>
# apt-cache search linux-image-2.6- | grep -v transition
          </example></p>

          <p>If you are unsure about which package to select, run
          <tt>uname -r</tt> and look for a package with a similar name.
          For example, if you see '2.4.27-3-686', it is recommended that you
          install <package/linux-image-2.6-686/.
          You may also use apt-cache to see a long description of each
          package in order to help choose the best one available.
          For example:
          <example>
# apt-cache show linux-image-2.6-686
          </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>
        </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="mdadm"><heading>Upgrading mdadm</heading>

         <p>mdadm now needs a configuration file to assemble MD arrays (RAID)
         from the initial ramdisk and during the system initialisation
         sequence. Please make sure to read and act upon the instructions in
         <file>/usr/share/doc/mdadm/README.upgrading-2.5.3.gz</file> after
         the package has been upgraded <strong>and before you reboot</strong>.
         The latest version of this file is available at
         <url id="http://svn.debian.org/wsvn/pkg-mdadm/mdadm/trunk/debian/README.upgrading-2.5.3?op=file">;
         please consult it in case of problems.</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>
        
        <sect id="problems"><heading>Potential problems</heading>
          <p>Sometimes, changes have side-issues we cannot reasonably avoid,
          or we expose bugs somewhere else.
          We document here the issues we are aware of.
          Please also read the errata, the relevant packages' documentation,
          bug reports and other information mentioned in <ref id="morereading">.
          </p>

          <sect1 id="window-scaling"><heading>Certain networking site cannot be reached by TCP</heading>
          <p>
          Since 2.6.17, Linux uses TCP window scaling which is specified in RFC 1323 in
          an aggressive way. Some servers have a broken behaviour, and announce wrong
          window sizes for themselves. Please see the bugs
          <url id="http://bugs.debian.org/381262" name="#381262"> and
          <url id="http://bugs.debian.org/395066" name="#395066">
          for more information.
          </p>
          </sect1>

          <sect1 id="poweroff"><heading>Automatic poweroff stops working</heading>
          <p>
          On some older systems, <prgn>shutdown -h</prgn> may not power off the system
          anymore (but just stop it). This happens because apm needs to be used there.
          Adding <tt>acpi=off apm=power_off</tt> to the kernel's command line, e.g.
          in <package/grub/ or <package/lilo/ configuration files should fix this issue.
          Please see bug
          <url id="http://bugs.debian.org/390547" name="#390547">
          for additional information.
          </p>
          </sect1>

          <sect1 id="apt-pdiff"><heading>Apt downloads small files with update</heading>
          <p>
          There has been support added to <prgn>apt</prgn> to download only the difference
          between packages files. This is handy for people with bad network connections,
          but people having a very nearby mirror may want to disable this feature.
          One can disable it by adding <tt>Acquire::Pdiffs "false";</tt> to
          <file>/etc/apt/apt.conf</file>.
          </p>
          </sect1>
        </sect>


<!-- 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 -->


      <sect id="xorg"> <heading>XFree86 to X.Org transition</heading>
        <p>The transition to X.Org involves some structural changes. In case
        all installed packages are from Debian and also included in &releasename;,
        the upgrade should work without problems.
        Experience has however shown there are a few changes to be aware of as
        they can potentially cause issues during the upgrade.</p>

        <p>The most important change is that <file>/usr/X11R6/bin</file> has
        been dropped and only remains as a symlink to <file>/usr/bin</file>.
        This means this directory has to be empty at the time the new packages
        are installed. The new packages conflict with most packages that used
        <file>/usr/X11R6/bin</file>,
        but in some cases manual intervention may be needed.
        Please remember to not run upgrades within an X session.</p>
        
        <p>In case the upgrade aborts during X.Org installation, you should
        check if any files are still left in <file>/usr/X11R6/bin</file>.
        You can then use <tt>dpkg -S</tt> to find out which Debian package
        installed that file (if any), and remove such packages with
        <tt>dpkg --remove</tt>. Please make a note which packages you
        remove, so that you can install substitute packages later on.
        Before continuing with the upgrade, all files in
        <file>/usr/X11R6/bin</file> need to be removed.

        <p>Please read <url id="http://wiki.debian.org/Xorg69To7">
        for more details and other issues.</p>

      </sect>

      <sect id="exim"> <heading>Upgrading from exim to exim4</heading>
      <p>One of the packages that has been obsoleted by the &releasename;
      release is the Mail Transfer Agent (MTA) exim, which has been replaced
      by the completely new package exim4.</p>

      <p>exim (version 3.xx) has been unmaintained upstream for years, and
      Debian has dropped support for that version as well. If you are still using
      exim 3.xx, please upgrade your exim installation to exim4 manually.
      Since exim4 is already part of &oldreleasename, you can choose to do the
      upgrade on your &oldreleasename; system before the upgrade to &releasename;,
      or after the &releasename; upgrade at your convenience. Just remember that
      your old exim package is not going to be upgraded and that it won't get
      security support after support for &oldreleasename; will be discontinued.</p>

      <p>The exim4 packages in Debian are extensively documented. The package's
      home page is <url id="http://wiki.debian.org/PkgExim4"> on the Debian Wiki, and
      the README file can be found at
      <url id="http://pkg-exim4.alioth.debian.org/README/etch/README.Debian.html"> and
      inside the packages as well.</p>

      <p>The README file has a chapter about Packaging, which explains the
      different package variations we offer, and it has a chapter about
      Updating from Exim 3, which will help you in doing the actual
      transition.</p>
<!-- FIXME: update with decisions of (S)RMs might be needed -->
      </sect>
      
      <sect id="apache2"> <heading>Upgrading apache2</heading>
        <p>Apache has been upgraded to the new version 2.2.
        Although this shouldn't impact the average user,
        there are some potential issues to be aware of.</p>

        <p><url id="http://httpd.apache.org/docs/2.2/upgrading.html"> contains
        the upstream changes. Please read this page, and remember that especially:
        <list>
        <item><p>all modules need to be recompiled</p></item>
        <item><p>authorization modules have been resorted and renamed</p></item>
        <item><p>some configuration options have been renamed</p></item>
        </list></p>

        <p>Debian-specific changes include that the string SSL is no longer defined,
        as ssl is now supported by the default package.</p>

      </sect>

      <sect id="php-globals"> <heading>Deprecated insecure php configurations</heading>
        <p>For many years, turning on the <tt/register_globals/ settings in PHP
        has been known to be insecure and dangerous, and this option has defaulted to
        off for some time now. This configuration is
        now finally deprecated on Debian systems as too dangerous.
        The same applies to flaws in <tt/safe_mode/ and <tt/open_basedir/, which
        have also been unmaintained for some time.</p>
        
        <p>Starting with this release, the Debian security team does not provide
        security support for a number of PHP configurations which are known to
        be insecure. Most importantly, issues resulting from 
        <tt/register_globals/ being turned on will no longer be addressed.</p>
        
        <p>If you run legacy applications that require <tt/register_globals/,
        enable it for the respective paths only, e.g. through the Apache
        configuration file. More information is available in the
        <file>README.Debian.security</file> file in the PHP
        documentation directory (<file>/usr/share/doc/php4</file>,
        <file>/usr/share/doc/php5</file>).
      </sect>

      <sect id="mozilla-security"> <heading>Security status of mozilla products</heading>
        <p>The Mozilla programs are important tools for many users.
        Unfortunately the upstream security policy is to urge users to update to
        new upstream versions, which conflicts with Debian's policy not to ship
        large functional changes in security updates.
        We cannot predict it today, but during lifetime of &releasename; the
        Debian Security Team may come to a point where supporting
        Mozilla products is no longer feasible and announce
        the end of security support for Mozilla products.
        You should take this into account when deploying Mozilla and consider
        alternatives available in Debian if the absence of security support would
        pose a problem for you.</p>
      </sect>
      </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 Reference, 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:
-->