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.48 2005-05-28 14:39:40 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)</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 previous editions of the release notes contained
        information about upgrading from releases older than than the previous
        release. However such content often complicated the documentation so we
        have decided to only discuss upgrades from &debian; 3.0 ('woody'). If
        you need to upgrade from older releases please read previous editions of
        the release notes.</p>

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

        <p>The list of supported architectures has not changed since the
        previous release, &debian; 3.0 ('woody'). Here is the full list of
        architectures for this release.</p>
        
        <p>
          <list>
            <item><p>Intel x86 ('i386')</p></item>
            <item><p>Motorola 680x0 ('m68k')</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>
          </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 other 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>

]]>

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

<![ %available-2.6 [
          <p>On the &arch-title; architecture a 2.6 kernel is also available;
          this has kernel version &kernelversion-2.6;. Note that Debian's 2.6.8
          kernel packages include the 2.6.8.1 kernel release and selected other
          patches.</p>
]]>
]]> <!-- %m68k -->
<![ %m68k [
          <p>&debian; &release; for the &arch-title; architecture ships with
          kernel versions 2.2.25 and 2.4.27. For some subarchitectures 2.6.8
          kernels are also available, but these should be considered
          experimental.</p>
]]>
        
        <sect id="newdistro"><heading>What's new in the distribution?</heading> 
           
           <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 (that is 73% of
           the number of packages in &oldreleasename;). Also, a significant number
           of packages has 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>This release of &debian; contains the much improved XFree86
           4.3 release, which includes support for a greater range of
           hardware, better autodetection support, and improved support for
           advanced technologies such as Xinerama and 3D acceleration.</p>
           
           <p>&debian; is more desktop orientated than ever in this new release,
           it now includes GNOME 2.8 and KDE 3.3. Also included for the
           first time is a complete office suite in the form of OpenOffice.org
           1.1, other productivity tools included in the release are the
           Evolution groupware software and GAIM instant messaging client.</p>
           
           <p>The &releasename; version of <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 also give <package/aptitude/
           a try as 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 now also available.</p>

        <sect1 id="volatile"><heading>New service debian-volatile</heading>

           <p>There is a new service <em/debian-volatile/ allowing 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. An administrator can use the "volatile.debian.net"
           archive with similar ease to the "security.debian.org" archive, and
           enjoy the use of packages with up-to-date information without the
           hassle and risks of maintaining an entire (or partial) system based
           on bleeding-edge packages. For more information and a list of mirrors,
           please see the archive's <url id="&url-debian-volatile"
           name="web page">.</p>
           
           <p>Note that debian-volatile is <em/not/ an official Debian service.
           Use it at your own discretion.</p>

        </sect1>

        <sect1 id="non-us"><heading>non-US obsoleted</heading> 

           <p>For the &releasename; release, packages that were formerly in the
           non-US part of the archive have been moved into the regular archive.
           If you have any lines referring to "non-us" in your
           <file>/etc/apt/sources.list</file>, you should remove them.</p>

        </sect1>

        </sect>

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

          <p>The old &debian; installation system has been replaced by a
          completely new installation system called
          <prgn>debian-installer</prgn>. The new installation system is
          modular in design and so has been developed with extensibility in
          mind. It has been fully translated into almost forty languages;
          additional translations are in progress and may be added in
          point releases for &releasename;.</p>
          
          <p>Some of the new features in the installation system include
          improved hardware detection, support for booting off USB flash devices,
          the use of <prgn>aptitude</prgn> to install packages during configuration
          of the base system, and support for the <prgn>XFS</prgn> file system,
          <prgn>RAID</prgn> and <prgn>LVM</prgn> (logical volume management).</p>
          
          <p>For full details on the new Debian installation system, users
          are advised to read the Debian Installation Guide included on the
          first CD or available from <url id="&url-install-manual;"
          name="the release pages">. The Installation Guide has been fully
          translated into eight languages and more are being worked on.
          Additional translations will be made available from the website
          when completed.</p>

<![ %i386 [ 

          <p>For the &arch-title; architecture, a special set of installation
          floppy disk images, "speakup", is available for the blind.
          These images have a special kernel that supports braille displays.
          A complete list of supported models may be found in the brltty
          documentation. See the <url id="&url-installer;index#speakup"
          name="debian-installer release page"> for further information
          on these images.</p>

]]>

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

        </sect>

      </chapt>

      <chapt id="installing"><heading>New installations</heading>

        <p>The old &debian; installation system called
        <prgn>boot-floppies</prgn> has been replaced by a new componentized and
        more powerful installation system called <prgn>debian-installer</prgn>.</p>

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

<![ %not-m68k [
<![ %d-i-avail-2.6 [
          <p>The installation system uses a 2.4 series kernel by default.
          Installation using a 2.6 based kernel is also possible for
          &arch-title;. For more details on how to use this please consult the
          Installation Guide.</p>
]]>          
<![ %d-i-default-2.6 [
          <p>The installation system uses a 2.6 series kernel by default for
          &arch-title;.</p>
]]>
]]> <!-- %not-m68k -->
<![ %m68k [
          <p>Depending on the subarchitecture, installation may be possible using
          either a 2.2.25 kernel or a 2.4.27 kernel or both. For mac the 2.2.25
          kernel is preferred, for other subarchitectures the 2.4.27 kernel.</p>

          <p>There currently is no support for atari partitions in <prgn/partman/,
          the component used in <package/debian-installer/ to partition and format
          disks. This means this step has to be performed manually. For further
          information please see the Installation Guide.</p>
]]>

<![ %alpha [
        <p>The new 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_kbd"><heading>Issues with keyboards on &arch-title;</heading>

        <p>There are several issues with keyboard selection during installation.</p>

        <p>The first issue is with USB keyboards by Sun as used on for example
        SunBlade systems. When installing using the default 2.4 kernel, these are
        incorrectly "recognized" by the installer as regular Sun keyboards.
        A workaround is documented in the Installation Guide (see link above,
        chapter "Using the Debian Installer").</p>

        <p>The second issue is kernel related. Kernels in the 2.6 series use
        a different input layer that makes all keyboards look like "normal"
        PC keyboards. This means that if you boot the installer with a 2.4
        kernel and configure it for a Sun or USB keyboard and later (in expert
        mode) select a 2.6 kernel for the new system, you will very likely end
        up with a non-working keyboard after reboot.</p>

      </sect>

      <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;. This can result in ugly display on
        systems that do properly support the framebuffer, like those with ATI
        graphical cards. If you see display problems in the installer, you can try
        booting the installer with parameter "debian-installer/framebuffer=true".</p>

      </sect>
]]>

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

        <p>For technical reasons the <package/popcon/ is no longer installed by
        default for new &releasename; installations. This will probably be
        corrected in future releases.</p>

        <p><package/popcon/ 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/popcon/ is processed anonymously. We would
        appreciate it if you install the package and allow it to participate
        in the 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
-->

        <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>It's wise to inform all users in advance of any upgrades you're
          planning, although users accessing your system via SSH (at least)
          shouldn't notice much during the upgrade, and may want to continue
          working. If you wish to take extra precautions, back up or unmount
          user's partitions (<file>/home</file>) before upgrading. A reboot
          will not normally be necessary, unless you plan to also upgrade
          your kernel.</p>

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

          <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. It assumes your system
        has been updated to the latest point release of &oldreleasename;.
        If you have not or are unsure, follow the instructions in
        <ref id="old-upgrade"></p>

<![ %has-woody-aptitude [
        <p>It also assumes you have the &oldreleasename; version of
        <prgn/aptitude/ installed. You can check if it is installed using
        
        <example>
$ dpkg -l aptitude
        </example>
        
        If the line of output does <em/not/ begin with "i", you should install
        it before you start the upgrade using the instructions in
        <ref id="old-aptitude">.</p>
]]>

<![ %mips [
        <sect1><heading>SGI IP22: set up arcboot</heading>

          <p>If you have an <em>SGI IP22</em> you should now prepare
          it to boot with <package>arcboot</package>, and not to boot
          the kernel directly. <package>arcboot</package> is available
          in &oldreleasename; so you can install it in the usual ways.</p>

          <p>Before you attempt to install <package>arcboot</package>, you
          should first check that entries in your <file>sources.list</file>
          still refer to &oldreleasename; as explained in
          <ref id="old-sources">.</p>

        </sect1>
]]>

        <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. You can identify packages on hold with
 
          <example>
# dpkg --audit
          </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.

<![ %has-woody-aptitude [
          The `hold' package state can be changed by using <prgn/aptitude/:

          <example>
# aptitude hold | unhold &lt;package name&gt;
          </example>
]]>
<![ %no-woody-aptitude [
          The `hold' package state can be changed either by using <prgn/dselect/
          (in the Select menu, use the `H' and `G' keys to hold and unhold,
          respectively), or by editing the file produced by

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

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

          <example>
# dpkg --set-selections &lt; ~/curr-sels.txt
          </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>

<![ %glibcneedsnewkernel [
<![ %not-mips-mipsel [

        <sect id="new-kernel">
        <heading>Checking kernel support</heading>

<![ %sparc [
           <p>All machines with a 64bit SPARC CPU (sun4u) should be upgradable
           without any special considerations about kernel support.</p>

           <p>sun4c CPUs are <em>no longer supported</em> in &releasename;.
           The support for sun4d CPUs is in a rather unknown state since they
           are very rare. It is possible that sun4d CPUs with an MMU work.</p>

           <p>sun4m CPUs are still supported but you need to install a newer kernel
           version first before upgrading the system. This is necessary because newer
           versions of glibc use assembler instructions not available on certain
           machines, so you need a updated kernel first that emulates the missing
           instructions.</p>

           <p>Technically only <em>some</em> sun4m chips are affected, but as
           glibc can't reliably detect whether a system is affected it
           will refuse to be upgraded on any 32bit SPARC system before a
           fixed kernel is installed.</p>

           <p>For those interested in the gory details: some of the sun4m chips,
           produced by Cypress/ROSS, don't implement the <tt>umul</tt>
           instruction (RT601/CY7C601, same chip, only different names).
           They were used in the early SPARCserver 6xxMP models. Later models
           used chips manufactured by TI. Currently we don't know if these are
           also affected.</p>
<!-- Add link to http://www.ultralinux.org/faq.html#q_2_1 ? -->
]]>

<![ %hppa [
          <p>On 64bit HPPA machines you will need to upgrade to a newer
          kernel version first before upgrading the system. This is necessary because
          newer versions of glibc use assembler instructions not available on certain
          machines, so you need an updated kernel first that emulates the missing
          instructions.</p>
]]>

<![ %i386 [
          <p>True "80386" CPUs are <em/no longer supported/ by &releasename;.
          This does not affect any CPUs that are compatible with "80486"
          CPUs or above.</p>
]]>

<![ %upgradekernel [
        <sect1 id="kernel-upgrade"><heading>Upgrading the kernel</heading>

          <p>If (and only if) the previous section indicates that you should
          upgrade your kernel <em/before/ the upgrade of the system, you
          should do so now.</p>

          <p>
          Backports are available of all tools needed to install the
          current kernel from &releasename;.
          Detailed instructions on how to install the new kernel can be
          found in <ref id="kernel-upgrade-howto">.</p>
          
        </sect1>
]]>
        </sect>
]]> <!-- not-mips-mipsel -->
]]> <!-- glibcneedsnewkernel -->

        <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 tool for upgrading between &debian; releases is
          to use the package management tool <prgn>aptitude</prgn>. This tool
          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 the typescript
          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>


<![ %mips-mipsel [
        <sect1 id="upgrading_kernel_mipsen"><heading>Upgrading the kernel</heading>         


          <p>On &arch-title; machines you will need to upgrade to a newer
          kernel version first before upgrading the system. This is necessary
          because of a inconsistent definition of the inter process communication
          of the new libc and the kernel, so you need an updated kernel
          that provides the correct definition first.</p>

          <p>Detailed instructions on how to install the new kernel can be
          found in <ref id="kernel-upgrade-howto">.</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/.

<![ %has-woody-aptitude [
          It should therefore be upgraded first using:
          <example>
# aptitude install aptitude
          </example></p>
]]>
<![ %no-woody-aptitude [
          It should therefore be installed first using:
          <example>
# apt-get install aptitude
          </example></p>
]]>

          <p><prgn/aptitude/ will show you a list of the changes that will be
          made and ask 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>

        </sect1>

        <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 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>packagename</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/packagename.deb</var>
          </example></p>

<!-- FJP Add instructions what to do in case of file conflicts
     dpkg -r \-\-force-depends <package name>
-->

          <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>
          
          <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/kernel-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.4-686) he _will_ upgrade the kernel if using
  aptitude (post-sarge) -->

<![ %available-2.6 [

         <p>&debian; comes with a &kernelversion; kernel which is in the 2.4
         series, the older stable Linux kernel series. You may wish to use a 2.6
         series kernel for better hardware support or improved performance.</p>

         <p>However, you a 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 ^kernel-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>Please note that the installation system of &oldreleasename; 
         (and previous releases) did <em/not/ install the kernel as a package 
         in your system. This has changed in &releasename; and you can
         install virtual packages to keep track of kernel changes.
         These packages are named kernel-image-<tt/VERSION/-<tt/ARCH/, with
         <tt/VERSION/ corresponding to the kernel version number (2.4 or 2.6)
         and <tt/ARCH/ corresponding to any of the supported architectures.
         If you want to have security support for the kernel integrated in
         package management please install the kernel package most suitable
         for your hardware after the upgrade.</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="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
         automaticaly installed through dependancies.</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&amp;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>
-->

<sect id="pythonchanges"><heading>Changes to Python packages</heading>

   <p>None of the python2.X packages that are included with &releasename; include
the standard modules 'profile' and 'pstats', because they are licensed under a
license that does not conform to the DFSG (see bug #293932 for details). These
two modules can be found in the python-profiler and python2.X-profiler packages
that are included in the non-free section of the Debian archive.</p>
</sect>

<![ %available-2.6 [
        <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/kernel-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 [
          <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 [
        <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>

        <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 preferred over
          the OSS sound drivers. If you install <package/alsa-base/, ALSA modules
          for your soundcard should be loaded automatically; this will also
          automatically blacklist OSS modules for <package/discover/ and
          <package/hotplug/ to prevent them from loading. If you have OSS modules
          listed in <file>/etc/modules</file>, you should remove them.</p>

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

        <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 dynamically populate that
        directory with devices as kernel modules are loaded. It works 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
        e.g. <package/gnome/, there is a chance that upgrading to a 2.6 kernel
        will 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>
]]> <!-- %available-2.6 -->

<![ %i386 [
        <sect id="x-mouse">
        <heading>X Window System fails to load</heading>

          <p>If after booting your machine, X fails to load and you
          see an error "missing core pointer" in
          <file>/var/log/XFree86.0.log</file>, the problem could be that the
          mouse driver is not loaded fast enough by <prgn/hotplug/ (bug
          <url id="http://bugs.debian.org/255744" name="#255744">). The
          solution is to add the driver module for your mouse (e.g. psmouse)
          in <file>/etc/modules</file>.</p>

        </sect>

        <sect id="x-transmeta">
        <heading>X Window System on Transmeta Crusoe systems</heading>

          <p>The X server shipping in &releasename; contains optimized code which 
          is not properly executed by many Transmeta(TM) Crusoe(TM) processors.
          The result of this is that at a certain time (when cached code "morphed"
          from x86 to Crusoe VLIW instructions in the CPU is in a buggy state),
          X client applications which connect with it fail with the following
          error message:

<example>
X Error of failed request:  BadLength
   (poly request too large or internal Xlib length error)
Major opcode of failed request:  18 (X_ChangeProperty)
Serial number of failed request:  15
Current serial number in output stream:  18
</example></p>

          <p>In practical terms, this means that after a few hours of operation,
          applications will suddenly quit in rapid succession; if a display manager
          is running, that too will repeatedly quit and attempt to restart itself.
          The state will persist until the buggy VLIW Transmeta code is flushed
          from the cache.</p>

          <p>Since the bug is in the proprietary Transmeta Code Morphing Software
          (CMS), and the laptop BIOS checks the CMS for a vendor signature at boot
          time, this can only be fixed in cooperation between Transmeta and the
          laptop vendor. Further information about this issue can be found at
          <url id="http://www.cs.auc.dk/~fleury/bug_cms/"> and Debian bug report
          <url id="http://bugs.debian.org/216933" name="#216933">.</p>

          <p>The workaround for this bug is to install an X server compiled without
          optimization, such as the <package/xserver-xfree86-dbg/ package.</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 Guide, Debian New Maintainers Guide, and Debian
        FAQ are available, and many more. For full details of the resources
        available 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>

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


<![ %upgradekernel [

    <appendix id="kernel-upgrade-howto"><heading>Upgrading the kernel</heading>

<![ %not-mips-mipsel [
<![ %sparc [
          <p><strong>The information in this appendix is relevant only
          if, for a successful upgrade of the system, you need to upgrade the
          kernel <em/before/ upgrading the system. Please read
          <ref id="new-kernel"> to find out if that is required for your
          system</strong>.</p>
]]>
          <p>The following instructions explain step by step how to use the
          available backported tools to install the newer kernel.</p>

          <p>Because packages may need to be installed from &oldreleasename;,
          you should first check that entries in your <file>sources.list</file>
          still refer to &oldreleasename; as explained in
          <ref id="old-sources">.</p>
]]> <!-- %not-mips-mipsel -->

<![ %mips-mipsel [
          <p>The following instructions explain step by step how to install
          the newer kernel.</p>
]]>

          <p><taglist>
               <tag>Download and install the needed packages</tag>

<![ %mips-mipsel [
                <item>
                <p><em>with apt</em>; if you not yet have done so,
                change your <file>sources.list</file> file to point
                to &releasename; as described in <ref id="upgrade-process">,
                update your packages lists and install the kernel-image for
                your machine. You can find a list of available kernel
                images below or with the command
         
         <example>
apt-cache search ^kernel-image
         </example></p>

                <p>During the install the package may complain about module mismatches
                and ask if the installation should continue. Answer <tt>YES</tt> to that
                question as these mismatches will be resolved as soon as you reboot with
                the new kernel.</p>

                <p><em>with dpkg</em>: fetch the current kernel package from
                the Debian mirror of your choice. The available packages are:

                <list>
<![ %mips [
                <item><p><url id="&mips-kernel-patch;/&mips-kernel-image-r4k;" name="&mips-kernel-image-r4k;">
                for R4XX0 processors and the SGI IP22 subarchitecture like the Indy and Indigo2.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mips-kernel-image-r5k;" name="&mips-kernel-image-r5k;">
                for R5000 processors and the SGI IP22 subarchitecture like the Indy and Indigo2.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mips-kernel-image-swarm;" name="&mips-kernel-image-swarm;">
                for the Broadcom BCM91250A (aka SWARM) pass 2.2.</p></item>
]]>
<![ %mipsel [
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-r3k;" name="&mipsel-kernel-image-r3k;">
                for R3000 based DECstations with KN02 (or compatible) mainboard, such as the DECstation 5000/1xx series with xx=20,25,33 and the DECstation 5000/240.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-r4k;" name="&mipsel-kernel-image-r4k;">
                for R4X00 based DECstations with KN04 (or compatible) mainboard, such as the DECstation 5000/150, the Personal DECstation 5000/50 and the DECstation 5000/260.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-r5k-cobalt;" name="&mipsel-kernel-image-r5k-cobalt;">
                for MIPS based Cobalt machines (such as the Qube, RaQ, Qube2 and RaQ2).</p></item> 
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-r5k-lasat;" name="&mipsel-kernel-image-r5k-lasat;">
                for R5000 processors on the Lasat Masquerade Pro.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-swarm;" name="&mipsel-kernel-image-swarm;">
                for the Broadcom BCM91250A (aka SWARM) pass 2.2.</p></item>
                <item><p><url id="&mips-kernel-patch;/&mipsel-kernel-image-xxs1500;" name="&mipsel-kernel-image-xxs1500;">
                for the Au1500 based XXS1500 board.</p></item>
]]>
                </list></p>

                <p>Then install the package using <tt>dpkg -i</tt>. It may
                complain about module mismatches (from <package>modutils</package>)
                and ask if the installation should continue. Answer <tt>YES</tt>
                to that question as these mismatches will be resolved as soon
                as you reboot with the new kernel.</p>

                </item>
]]> <!-- %mips-mipsel -->

<![ %not-mips-mipsel [
               <item>
               <p><em>with apt</em>: to install the packages with
               <prgn>apt</prgn> or one of its frontends, add the following line
               in your <file>/etc/apt/sources.list</file>:

<example>
deb &url-kernel-upgrade;
# sources are also available if you need them
# deb-src &url-kernel-upgrade;
</example></p>

<![ %sparc [
               <p>Then install the packages
               <package>modutils</package> and
               <package>initrd-tools</package>.
]]>
<![ %hppa [
               <p>Then install the packages
               <package>module-init-tools</package>,
               <package>palo</package>,
               and <package>initrd-tools</package>.
]]>
               (Afterwards you can safely drop the additional entry again.)</p>

               <p>After that change your <file>sources.list</file> file to point
               to &releasename; as described in <ref id="upgrade-process">,
               update your packages lists and install the package
               <package>&upgrade-kernel-image-name;</package>.
               </p>

               <p><em>with dpkg</em>: to install the packages directly with <prgn>dpkg</prgn> you need to
               download the necessary files first.</p>
               <p><list>
                 <item><url id="&upgrade-kernel-image;"></item>
                 <item><url id="&upgrade-kernel-modutils;"></item>
                 <item><url id="&all-initrd-tools;"></item>
                 <item><url id="&upgrade-kernel-cramfsprogs;"></item>
               </list></p>

               <p>The kernel package depends on <package>&upgrade-kernel-modutils-name</package>;
               <package>initrd-tools</package> depends on <package>cramfsprogs</package>.
               All other dependencies (which are <package>stat</package>,
               <package>cpio</package> and <package>ash</package>) can be
               satisfied with packages from &oldreleasename; in the usual way.</p>
<![ %hppa [
               <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>
]]>
               </item>
]]> <!-- %not-mips-mipsel -->

               <tag>Don't delete your old kernel yet</tag>
               <item><p>You should first verify that the new one boots and all hardware
               needed for the upgrade works (e.g. network adaptors).</p></item>

<![ %sparc [
               <tag>Make your system bootable</tag>
               <item>
               <p>You will probably have to adapt your boot loader configuration
               <file>/etc/silo.conf</file>. Note that the kernel now uses an
               initrd while the Debian kernels in &oldreleasename; did not.</p>
               </item>
]]>
<!-- ??hppa??
<![ %hppa [
               <tag>Make your system bootable</tag>
               <item>
               <p>???</p>
               </item>
]]>
-->

               <tag>Reboot to the new kernel</tag>
               <tag>Check your system</tag>
               <item><p>Check especially input devices, display devices, devices
               needed to access the &releasename; packages (i.e. network adaptors,
               CD drives, etc). Some driver modules may have been renamed, some
               drivers which have been compiled into the old kernel might now be
               compiled as modules, ...</p></item>

          </taglist></p>

    </appendix>
]]>

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

<![ %has-woody-aptitude [
       <sect id="old-aptitude">
       <heading>Installing &oldreleasename; version of aptitude</heading>

          <p>First you need to make sure you will install &oldreleasename;'s
          version of <package/aptitude/ and not &releasename;'s by following
          the instructions in <ref id="old-sources">.</p>

          <p>After that, just execute

          <example>
# apt-get install aptitude
          </example>

          to install <package/aptitude/.</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 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, safe 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:
-->
